Handbook Workflows
Overview
Handbook workflows fall into four groups:
- Source preparation workflows parse, classify, and extract answers from source artifacts.
- Source-context workflows turn cited uploaded-handbook evidence into durable, provenance-backed context memory.
- Generation workflows create, review, revise, render, and promote handbook candidates.
- Evaluation workflows run adherence, comparison, corpus-diff, and policy-review checks.
- Lab/smoke workflows exercise a broader product path for validation and demos.
Runtime-registered workflows are loaded in packages/domain-handbook/src/loader.ts. Additional exported workflows exist for scripts/tests/direct callers.
Runtime-Registered Workflows
These workflows are currently registered by loadHandbookArtifacts() and therefore participate in generated runtime workflow routes when Handbook is enabled.
| Runtime workflow key | Product workflow ID | Role |
|---|---|---|
msba-generate-verified-answer | n/a | Runs evidence-backed verified answer generation. |
handbook-classify-document | handbook.classify-document.v1 | Classifies document coverage, audience, level, scope, and tags. |
handbook-compare-handbooks | handbook.compare-handbooks.v1 | Compares same-scope/type handbook records. |
handbook-diff-corpus-versions | handbook.diff-corpus-versions.v1 | Diffs corpus snapshots and tags affected handbooks. |
handbook-extract-source-answers | handbook.extract-source-answers.v1 | Extracts source answer rows and classification output. |
handbook-extract-source-context | handbook.extract-source-context.v1 | Synthesizes and persists source-context answers with evidence provenance. |
handbook-generate-complete-handbook | handbook.generate-complete-handbook.v1 | Generates a candidate handbook from catalog, answers, policy evidence, and source refs. |
handbook-promote-candidate-handbook | handbook.promote-candidate-handbook.v1 | Promotes a reviewed candidate to active. |
handbook-product-flow-lab | handbook.product-flow-lab.v1 | Runs the broad source-to-generation lab path. |
handbook-prototype-candidate-chain | handbook.prototype-candidate-chain.v1 | Runs prototype candidate query/answer/assessment/release checks. |
handbook-rag-validation | n/a | Validates RAG ingestion, processing evidence, and corpus query behavior. |
handbook-render-document | handbook.render-document.v1 | Renders document exports from section model artifacts. |
handbook-review-candidate | handbook.review-candidate.v1 | Records warning acknowledgements and manual override approvals. |
handbook-revise-candidate-section | handbook.revise-candidate-section.v1 | Creates copy-on-write section revisions. |
handbook-run-policy-adherence | handbook.run-policy-adherence.v1 | Evaluates candidate/active handbook adherence against policy evidence. |
handbook-run-policy-review | handbook.run-policy-review.v1 | Runs the deeper whole-handbook policy-review pipeline. |
handbook-understand-source-document | handbook.understand-source-document.v1 | Stores and parses source documents into normalized artifacts. |
Use /handbook/routes.json in the active environment to see generated slugs and route availability.
Exported But Not Runtime-Registered
| Exported workflow | Role | Current exposure |
|---|---|---|
handbook-ingestion-profile | Profile-driven ingestion pipeline for MSBA policy and district handbook sources. | Exported from package; used by scripts/tests/direct callers, not registered in loadHandbookArtifacts(). |
msba-pdf-to-verified-answer | Legacy one-shot PDF-to-answer vertical path. | Exported from package; not registered in loadHandbookArtifacts(). |
Functional Product Sequence
Source Preparation
| Workflow | What it consumes | What it produces |
|---|---|---|
handbook.understand-source-document.v1 | source artifact refs, document kind, parsing options | parsed document artifacts, pages, spans, quality, diagnostics |
handbook.classify-document.v1 | parsed source artifacts and catalog context | coverage, audience, level, school/building scope, tags |
handbook.extract-source-answers.v1 | parsed source artifacts and question/answer extraction plan | principal/district answer-set artifacts and answer rows |
handbook.extract-source-context.v1 | owner scope, uploaded handbook evidence, and requested source-context data points | derived source-context artifact, answer ledger, and optional SQL projections |
These workflows use the Source Artifact Store contract so later operations can reload source and derived artifacts by ref rather than by local path.
Source context is supplemental district/handbook evidence. It may fill product context or help a checklist reviewer understand uploaded wording, but it does not replace authoritative MSBA policy evidence.
Generation And Review
| Workflow | What it does |
|---|---|
handbook.generate-complete-handbook.v1 | Creates a candidate handbook instance, locks corpus snapshot refs, generates section artifacts, records lineage, warnings, and progress. |
handbook.review-candidate.v1 | Records warning acknowledgements and manual override approvals. |
handbook.revise-candidate-section.v1 | Writes a new section artifact and manifest entry while reusing unchanged section artifacts. |
handbook.render-document.v1 | Produces DOCX/PDF-ready artifacts from section model and manifest data. |
handbook.promote-candidate-handbook.v1 | Promotes a candidate to active, retires the prior active version, and supersedes sibling candidates. |
Generated handbooks should be represented canonically as JSON section-model artifacts plus a section manifest. DOCX/PDF outputs are derived render artifacts.
Evaluation And Review
| Workflow or runner | What it verifies |
|---|---|
handbook.run-policy-adherence.v1 | Candidate or active handbook adherence against policy evidence. |
handbook.compare-handbooks.v1 | Differences between same-scope/type handbook records. |
handbook.diff-corpus-versions.v1 | Whether corpus changes affect existing handbook outputs. |
handbook.run-policy-review.v1 | Whole-handbook review against selected MSBA policy evidence and checklist items. |
Policy review is normally started through the Admin BFF job path so it can use durable job progress, retries, saved run projection, checklist results, reviewer actions, and exports.
Policy Review Sequence
The checklist pass evaluates every checklist item against the full indexed handbook. It is not limited to the current handbook segment being compared to policy.
Lab And Smoke Workflows
| Workflow | Purpose |
|---|---|
handbook.product-flow-lab.v1 | Operator-facing module simulator for the broad product path: source understanding, answer extraction, generation, review, promotion, export, adherence, comparison, and corpus review. |
handbook.prototype-candidate-chain.v1 | Prototype-style candidate chain: ingest source, query candidate index, generate verified answers, assess quality, release weak candidates. |
handbook-rag-validation | RAG validation over PDF ingestion, processing evidence, and corpus query behavior. |
These are useful for local product labs, deployed smoke tests, and demonstrations. Production-facing behavior should prefer leaf workflows and explicit job runners.
Operator Sequences
Prepare A Handbook For Review
- Upload or select the handbook PDF in the Admin Handbook Review Flow.
- Start a PDF preparation job with
preparationMode: "reviewable-unit-v2". - Wait for extraction, chunking, embedding, indexing, and verification to complete.
- Confirm the indexed handbook row appears in
[HANDBOOK].[IndexedArtifactRegistry]. - Select the handbook and the authoritative MSBA policy set.
- Start policy review.
Generate A Handbook Candidate
- Understand the source document.
- Extract source answers and classification output.
- Generate a complete candidate handbook.
- Review warnings and manual override requirements.
- Revise individual sections when needed.
- Render DOCX/PDF artifacts.
- Promote the candidate only after review gates allow it.
- Run adherence, comparison, and corpus-diff checks as applicable.
Verification Ladder
| Lane | Command |
|---|---|
| Domain contract and workflow tests | npm run test:handbook |
| Policy-review contracts and stores | npx vitest run packages/domain-handbook/tests/policy-review-run/policy-review-contracts.test.ts packages/domain-handbook/tests/policy-review-run/policy-review-run-store.test.ts |
| Policy-review pipeline and checklist | npx vitest run packages/domain-handbook/tests/policy-review-run/policy-review-pipeline-runner.test.ts packages/domain-handbook/tests/policy-review-run/policy-review-local-runner.test.ts |
| Runtime route mapping | npx vitest run tests/shared/unit/routes/domain-mapping.test.ts tests/shared/unit/routes/handbook-product-workflow-adapter-smoke.test.ts |
| Admin builds | npm --prefix apps/admin-ui run build:server && npm --prefix apps/admin-ui run build:client |
See docs/internal/handbook/product-workflow-testing.md for deployed smoke commands and current evidence.