@libar-dev/architect 1.0.0-pre.3 → 1.0.0-pre.5

package/docs-live/product-areas/GENERATION.md

@@ -5,16 +5,16 @@
 
 ---
 
-**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries.
+**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries.
 
 ### Pipeline Stages
 
-| Stage       | Module                     | Responsibility                                                  |
-| ----------- | -------------------------- | --------------------------------------------------------------- |
-| Scanner     | `src/scanner/`             | File discovery, AST parsing, opt-in via `@architect`            |
-| Extractor   | `src/extractor/`           | Pattern extraction from TypeScript JSDoc and Gherkin tags       |
-| Transformer | `src/generators/pipeline/` | MasterDataset with pre-computed views for O(1) access (ADR-006) |
-| Codec       | `src/renderable/`          | Pure functions: MasterDataset → RenderableDocument → Markdown   |
+| Stage       | Module                     | Responsibility                                                 |
+| ----------- | -------------------------- | -------------------------------------------------------------- |
+| Scanner     | `src/scanner/`             | File discovery, AST parsing, opt-in via `@architect`           |
+| Extractor   | `src/extractor/`           | Pattern extraction from TypeScript JSDoc and Gherkin tags      |
+| Transformer | `src/generators/pipeline/` | PatternGraph with pre-computed views for O(1) access (ADR-006) |
+| Codec       | `src/renderable/`          | Pure functions: PatternGraph → RenderableDocument → Markdown   |
 
 ### Codec Inventory
 
@@ -33,7 +33,7 @@
 ## Key Invariants
 
 - Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output
-- Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship
+- Single read model (ADR-006): All codecs consume PatternGraph. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship
 - Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/`
 - Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors
 - RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer
@@ -59,20 +59,20 @@ Scoped architecture diagram showing component relationships:
 ```mermaid
 graph TB
     subgraph generator["Generator"]
-        SourceMapper[/"SourceMapper"/]
-        Documentation_Generation_Orchestrator("Documentation Generation Orchestrator")
         GitModule["GitModule"]
         GitHelpers["GitHelpers"]
         GitBranchDiff["GitBranchDiff"]
+        SourceMapper[/"SourceMapper"/]
+        Documentation_Generation_Orchestrator("Documentation Generation Orchestrator")
+        DesignReviewGenerator("DesignReviewGenerator")
+        DecisionDocGenerator("DecisionDocGenerator")
+        CliReferenceGenerator["CliReferenceGenerator"]
+        CliRecipeGenerator["CliRecipeGenerator"]
         TransformTypes["TransformTypes"]
         TransformDataset("TransformDataset")
         SequenceTransformUtils("SequenceTransformUtils")
         RelationshipResolver("RelationshipResolver")
         ContextInferenceImpl["ContextInferenceImpl"]
-        ProcessApiReferenceGenerator["ProcessApiReferenceGenerator"]
-        DesignReviewGenerator("DesignReviewGenerator")
-        DecisionDocGenerator("DecisionDocGenerator")
-        CliRecipeGenerator["CliRecipeGenerator"]
     end
     subgraph renderer["Renderer"]
         loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser["loadPreambleFromMarkdown — Shared Markdown-to-SectionBlock Parser"]
@@ -84,48 +84,48 @@ graph TB
         ArchitectureCodec[("ArchitectureCodec")]
     end
     subgraph related["Related"]
-        MasterDataset["MasterDataset"]:::neighbor
+        PatternGraph["PatternGraph"]:::neighbor
         Pattern_Scanner["Pattern Scanner"]:::neighbor
         GherkinASTParser["GherkinASTParser"]:::neighbor
         ShapeExtractor["ShapeExtractor"]:::neighbor
         PatternHelpers["PatternHelpers"]:::neighbor
         ReferenceDocShowcase["ReferenceDocShowcase"]:::neighbor
-        ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor
         ProceduralGuideCodec["ProceduralGuideCodec"]:::neighbor
         PatternRelationshipModel["PatternRelationshipModel"]:::neighbor
         DesignReviewGeneration["DesignReviewGeneration"]:::neighbor
+        CliReferenceGeneration["CliReferenceGeneration"]:::neighbor
         CliRecipeCodec["CliRecipeCodec"]:::neighbor
         ContextInference["ContextInference"]:::neighbor
     end
     loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec
+    GitModule -->|uses| GitBranchDiff
+    GitModule -->|uses| GitHelpers
     SourceMapper -.->|depends on| DecisionDocCodec
     SourceMapper -.->|depends on| ShapeExtractor
     SourceMapper -.->|depends on| GherkinASTParser
     Documentation_Generation_Orchestrator -->|uses| Pattern_Scanner
-    GitModule -->|uses| GitBranchDiff
-    GitModule -->|uses| GitHelpers
     PatternsCodec ..->|implements| PatternRelationshipModel
-    DesignReviewCodec -->|uses| MasterDataset
+    DesignReviewCodec -->|uses| PatternGraph
     DesignReviewCodec -->|uses| MermaidDiagramUtils
     DesignReviewCodec ..->|implements| DesignReviewGeneration
     CompositeCodec ..->|implements| ReferenceDocShowcase
-    ArchitectureCodec -->|uses| MasterDataset
-    TransformTypes -->|uses| MasterDataset
-    TransformDataset -->|uses| MasterDataset
-    TransformDataset ..->|implements| PatternRelationshipModel
-    SequenceTransformUtils -->|uses| MasterDataset
-    SequenceTransformUtils ..->|implements| DesignReviewGeneration
-    RelationshipResolver -->|uses| PatternHelpers
-    ContextInferenceImpl ..->|implements| ContextInference
-    ProcessApiReferenceGenerator ..->|implements| ProcessApiHybridGeneration
+    ArchitectureCodec -->|uses| PatternGraph
     DesignReviewGenerator -->|uses| DesignReviewCodec
-    DesignReviewGenerator -->|uses| MasterDataset
+    DesignReviewGenerator -->|uses| PatternGraph
     DesignReviewGenerator ..->|implements| DesignReviewGeneration
     DecisionDocGenerator -.->|depends on| DecisionDocCodec
     DecisionDocGenerator -.->|depends on| SourceMapper
+    CliReferenceGenerator ..->|implements| CliReferenceGeneration
     CliRecipeGenerator ..->|implements| CliRecipeCodec
+    TransformTypes -->|uses| PatternGraph
+    TransformDataset -->|uses| PatternGraph
+    TransformDataset ..->|implements| PatternRelationshipModel
+    SequenceTransformUtils -->|uses| PatternGraph
+    SequenceTransformUtils ..->|implements| DesignReviewGeneration
+    RelationshipResolver -->|uses| PatternHelpers
+    ContextInferenceImpl ..->|implements| ContextInference
     DesignReviewGeneration -.->|depends on| MermaidDiagramUtils
-    CliRecipeCodec -.->|depends on| ProcessApiHybridGeneration
+    CliRecipeCodec -.->|depends on| CliReferenceGeneration
     classDef neighbor stroke-dasharray: 5 5
 ```
 
@@ -133,13 +133,13 @@ graph TB
 
 ## API Types
 
-### RuntimeMasterDataset (interface)
+### RuntimePatternGraph (interface)
 
 ```typescript
 /**
- * Runtime MasterDataset with optional workflow
+ * Runtime PatternGraph with optional workflow
  *
- * Extends the Zod-compatible MasterDataset with workflow reference.
+ * Extends the Zod-compatible PatternGraph with workflow reference.
  * LoadedWorkflow contains Maps which aren't JSON-serializable,
  * so it's kept separate from the Zod schema.
  *
@@ -147,7 +147,7 @@ graph TB
 ```
 
 ```typescript
-interface RuntimeMasterDataset extends MasterDataset {
+interface RuntimePatternGraph extends PatternGraph {
   /** Optional workflow configuration (not serializable) */
   readonly workflow?: LoadedWorkflow;
 }
@@ -256,11 +256,11 @@ type CollapsibleBlock = {
 };
 ```
 
-### transformToMasterDataset (function)
+### transformToPatternGraph (function)
 
 ```typescript
 /**
- * Transform raw extracted data into a MasterDataset with all pre-computed views.
+ * Transform raw extracted data into a PatternGraph with all pre-computed views.
  *
  * This is a ONE-PASS transformation that computes:
  * - Status-based groupings (completed/active/planned)
@@ -272,46 +272,46 @@ type CollapsibleBlock = {
  * - Optional relationship index
  *
  * Convenience wrapper that returns just the dataset.
- * Use `transformToMasterDatasetWithValidation` to get validation summary.
+ * Use `transformToPatternGraphWithValidation` to get validation summary.
  *
  * @param raw - Raw dataset with patterns, registry, and optional workflow
- * @returns MasterDataset with all pre-computed views
+ * @returns PatternGraph with all pre-computed views
  */
 ```
 
 ```typescript
-function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
+function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph;
 ```
 
 | Parameter | Type | Description                                                |
 | --------- | ---- | ---------------------------------------------------------- |
 | raw       |      | Raw dataset with patterns, registry, and optional workflow |
 
-**Returns:** MasterDataset with all pre-computed views
+**Returns:** PatternGraph with all pre-computed views
 
 ---
 
 ## Business Rules
 
-92 patterns, 441 rules with invariants (442 total)
+93 patterns, 451 rules with invariants (452 total)
 
 ### ADR 005 Codec Based Markdown Rendering
 
-| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                                       | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Codecs implement a decode-only contract                           | Every codec is a pure function that accepts a MasterDataset and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. | Pure functions are deterministic and trivially testable. For the same MasterDataset, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| RenderableDocument is a typed intermediate representation         | RenderableDocument contains a title, an ordered array of SectionBlock elements, and an optional record of additional files. Each SectionBlock is a discriminated union: heading, paragraph, table, code, list, separator, or metaRow. The renderer consumes this IR without needing to know which codec produced it.            | A typed IR decouples codecs from rendering. Codecs express intent ("this is a table with these rows") and the renderer handles syntax ("pipe-delimited markdown with separator row"). This means switching output format (e.g., HTML instead of markdown) requires only a new renderer, not changes to every codec.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| CompositeCodec assembles documents from child codecs              | CompositeCodec accepts an array of child codecs and produces a single RenderableDocument by concatenating their sections. Child codec order determines section order in the output. Separators are inserted between children by default.                                                                                        | Reference documents combine content from multiple domains (patterns, conventions, shapes, diagrams). Rather than building a monolithic codec that knows about all content types, CompositeCodec lets each domain own its codec and composes them declaratively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ADR content comes from both Feature description and Rule prefixes | ADR structured content (Context, Decision, Consequences) can appear in two locations within a feature file. Both sources must be rendered. Silently dropping either source causes content loss.                                                                                                                                 | Early ADRs used name prefixes like "Context - ..." and "Decision - ..." on Rule blocks to structure content. Later ADRs placed Context, Decision, and Consequences as bold-annotated prose in the Feature description, reserving Rule: blocks for invariants and design rules. Both conventions are valid. The ADR codec must handle both because the codebase contains ADRs authored in each style. The Feature description lives in pattern.directive.description. If the codec only renders Rules (via partitionRulesByPrefix), then Feature description content is silently dropped -- no error, no warning. This caused confusion across two repos where ADR content appeared in the feature file but was missing from generated docs. The fix renders pattern.directive.description in buildSingleAdrDocument between the Overview metadata table and the partitioned Rules section, using renderFeatureDescription() which walks content linearly and handles prose, tables, and DocStrings with correct interleaving. |
-| The markdown renderer is codec-agnostic                           | The renderer accepts any RenderableDocument regardless of which codec produced it. Rendering depends only on block types, not on document origin. This enables testing codecs and renderers independently.                                                                                                                      | If the renderer knew about specific codecs, adding a new codec would require renderer changes. By operating purely on the SectionBlock discriminated union, the renderer is closed for modification but open for extension via new block types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                                      | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codecs implement a decode-only contract                           | Every codec is a pure function that accepts a PatternGraph and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. | Pure functions are deterministic and trivially testable. For the same PatternGraph, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| RenderableDocument is a typed intermediate representation         | RenderableDocument contains a title, an ordered array of SectionBlock elements, and an optional record of additional files. Each SectionBlock is a discriminated union: heading, paragraph, table, code, list, separator, or metaRow. The renderer consumes this IR without needing to know which codec produced it.           | A typed IR decouples codecs from rendering. Codecs express intent ("this is a table with these rows") and the renderer handles syntax ("pipe-delimited markdown with separator row"). This means switching output format (e.g., HTML instead of markdown) requires only a new renderer, not changes to every codec.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| CompositeCodec assembles documents from child codecs              | CompositeCodec accepts an array of child codecs and produces a single RenderableDocument by concatenating their sections. Child codec order determines section order in the output. Separators are inserted between children by default.                                                                                       | Reference documents combine content from multiple domains (patterns, conventions, shapes, diagrams). Rather than building a monolithic codec that knows about all content types, CompositeCodec lets each domain own its codec and composes them declaratively.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ADR content comes from both Feature description and Rule prefixes | ADR structured content (Context, Decision, Consequences) can appear in two locations within a feature file. Both sources must be rendered. Silently dropping either source causes content loss.                                                                                                                                | Early ADRs used name prefixes like "Context - ..." and "Decision - ..." on Rule blocks to structure content. Later ADRs placed Context, Decision, and Consequences as bold-annotated prose in the Feature description, reserving Rule: blocks for invariants and design rules. Both conventions are valid. The ADR codec must handle both because the codebase contains ADRs authored in each style. The Feature description lives in pattern.directive.description. If the codec only renders Rules (via partitionRulesByPrefix), then Feature description content is silently dropped -- no error, no warning. This caused confusion across two repos where ADR content appeared in the feature file but was missing from generated docs. The fix renders pattern.directive.description in buildSingleAdrDocument between the Overview metadata table and the partitioned Rules section, using renderFeatureDescription() which walks content linearly and handles prose, tables, and DocStrings with correct interleaving. |
+| The markdown renderer is codec-agnostic                           | The renderer accepts any RenderableDocument regardless of which codec produced it. Rendering depends only on block types, not on document origin. This enables testing codecs and renderers independently.                                                                                                                     | If the renderer knew about specific codecs, adding a new codec would require renderer changes. By operating purely on the SectionBlock discriminated union, the renderer is closed for modification but open for extension via new block types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### ADR 006 Single Read Model Architecture
 
 | Rule                                                      | Invariant                                                                                                                                                                                                                                                                  | Rationale                                                                                                                                                                        |
 | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| All feature consumers query the read model, not raw state | Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the MasterDataset. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the MasterDataset.                  | Bypassing the read model forces consumers to re-derive data that the MasterDataset already computes, creating duplicate logic and divergent behavior when the pipeline evolves.  |
-| No lossy local types                                      | Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. | Lossy local types silently drop fields that later become needed, causing bugs that only surface when new MasterDataset capabilities are added and the local type lacks them.     |
-| Relationship resolution is computed once                  | Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToMasterDataset()`. No consumer re-derives these from raw pattern arrays or scanned file tags.                               | Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. |
+| All feature consumers query the read model, not raw state | Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the PatternGraph. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the PatternGraph.                    | Bypassing the read model forces consumers to re-derive data that the PatternGraph already computes, creating duplicate logic and divergent behavior when the pipeline evolves.   |
+| No lossy local types                                      | Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. | Lossy local types silently drop fields that later become needed, causing bugs that only surface when new PatternGraph capabilities are added and the local type lacks them.      |
+| Relationship resolution is computed once                  | Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToPatternGraph()`. No consumer re-derives these from raw pattern arrays or scanned file tags.                                | Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. |
 | Three named anti-patterns                                 | These are recognized violations, serving as review criteria for new code and refactoring targets for existing code.                                                                                                                                                        | Without named anti-patterns, violations appear as one-off style issues rather than systematic architectural drift, making them harder to detect and communicate in code review.  |
 
 ### Arch Generator Registration
@@ -343,37 +343,37 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Architecture Diagram Core
 
-| Rule                                                  | Invariant                                                                                                                                            | Rationale                                                                                                                                                                                  |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Architecture tags exist in the tag registry           | Three architecture-specific tags (`arch-role`, `arch-context`, `arch-layer`) must exist in the tag registry with correct format and enum values.     | Architecture diagram generation requires metadata to classify source files into diagram components. Standard tag infrastructure enables consistent extraction via the existing AST parser. |
-| AST parser extracts architecture tags from TypeScript | The AST parser must extract `arch-role`, `arch-context`, and `arch-layer` tags from TypeScript JSDoc comments into DocDirective objects.             | Source code annotations are the single source of truth for architectural metadata. Parser must extract them alongside existing pattern metadata.                                           |
-| MasterDataset builds archIndex during transformation  | The `transformToMasterDataset` function must build an `archIndex` that groups patterns by role, context, and layer for efficient diagram generation. | Single-pass extraction during dataset transformation avoids expensive re-traversal. Index structure enables O(1) lookup by each dimension.                                                 |
-| Component diagrams group patterns by bounded context  | Component diagrams must render patterns as nodes grouped into bounded context subgraphs, with relationship arrows using UML-inspired styles.         | Component diagrams visualize system architecture showing how bounded contexts isolate components. Subgraphs enforce visual separation.                                                     |
+| Rule                                                  | Invariant                                                                                                                                           | Rationale                                                                                                                                                                                  |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Architecture tags exist in the tag registry           | Three architecture-specific tags (`arch-role`, `arch-context`, `arch-layer`) must exist in the tag registry with correct format and enum values.    | Architecture diagram generation requires metadata to classify source files into diagram components. Standard tag infrastructure enables consistent extraction via the existing AST parser. |
+| AST parser extracts architecture tags from TypeScript | The AST parser must extract `arch-role`, `arch-context`, and `arch-layer` tags from TypeScript JSDoc comments into DocDirective objects.            | Source code annotations are the single source of truth for architectural metadata. Parser must extract them alongside existing pattern metadata.                                           |
+| PatternGraph builds archIndex during transformation   | The `transformToPatternGraph` function must build an `archIndex` that groups patterns by role, context, and layer for efficient diagram generation. | Single-pass extraction during dataset transformation avoids expensive re-traversal. Index structure enables O(1) lookup by each dimension.                                                 |
+| Component diagrams group patterns by bounded context  | Component diagrams must render patterns as nodes grouped into bounded context subgraphs, with relationship arrows using UML-inspired styles.        | Component diagrams visualize system architecture showing how bounded contexts isolate components. Subgraphs enforce visual separation.                                                     |
 
 ### Architecture Doc Refactoring
 
-| Rule                                                                            | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Convention-tagged JSDoc produces machine-extractable codec documentation        | Every codec source file annotated with `@architect-convention<br>    codec-registry` must have structured JSDoc following the machine-extractable format. The convention extractor splits multi-codec files by `## Heading` into separate convention rules, each rendered as its own section in the generated reference document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | DD-1: Convention tag approach over dedicated codec. Rather than creating a new "codec inventory" codec that enumerates codecs from source, the existing convention-tag mechanism is reused. Each codec file's JSDoc is treated as convention rules tagged with `codec-registry`. This avoids new codec infrastructure and leverages the proven convention extractor path. The reference codec already handles 4-layer composition, so convention tags slot into the existing Layer 1 (conventions) position. |
-| Machine-extractable JSDoc format follows structured heading convention          | DD-2: Multi-codec JSDoc splitting uses one `## Heading` per codec per file. Each heading block contains structured fields in a fixed order: `**Purpose:**` one-liner, `**Output Files:**` file paths, options table with Type/Default/Description columns, `**When to Use:**` bullet list, and `**Factory Pattern:**` code example. Fields are optional -- codecs without options omit the table, codecs without factory patterns omit the code block.                                                                                                                                                                                                                                                                                                                                                              | The convention extractor uses `## ` heading regex to split descriptions into rules. Without this structure, a file like `session.ts` (3 codecs) would produce a single undifferentiated blob. The heading text becomes the convention rule title in the generated reference. The fixed field order ensures consistent rendering across all 20+ codec entries.                                                                                                                                                |
-| Heading match in convention extractor handles whitespace correctly              | The convention extractor's heading parser uses `matchEnd` (the character position after the full regex match) rather than `indexOf('\n',<br>    heading.index)` to calculate where content starts after a heading. This prevents the `\s*` prefix in the heading regex from consuming leading newlines, which would cause `heading.index` to point to those newlines instead of the heading text.                                                                                                                                                                                                                                                                                                                                                                                                                   | Discovered during Phase 2 implementation. The heading regex `/^\s*##\s+(.+)$/gm` matches headings with optional leading whitespace. When a heading has leading newlines, `heading.index` points to the first newline (part of the `\s*` match), not the `##` character. Using `indexOf('\n', heading.index)` then finds the newline BEFORE the heading, producing content that includes the heading text itself. The fix uses the regex match's end position directly.                                       |
-| Section disposition follows content-type routing                                | DD-3: Each ARCHITECTURE.md section is routed based on content type. Three routing strategies apply: (1) product area absorption -- sections describing a specific pipeline stage move to the corresponding product area document where they get live diagrams and relationship graphs; (2) generated shapes -- sections documenting TypeScript interfaces move to generated shape reference docs; (3) generated diagrams -- ASCII/text data flow diagrams are replaced by live Mermaid diagrams generated from architecture annotations.                                                                                                                                                                                                                                                                            | The routing heuristic is: if a generated equivalent already exists, replace with pointer; if content is convention-taggable in source files, tag and generate; if editorial content that cannot be expressed as annotations, retain. This ensures each section lands in the location with the best maintenance model for its content type.                                                                                                                                                                   |
-| Product area absorption validates content coverage before pointer replacement   | DD-4: Product area absorption replaces ARCHITECTURE.md sections with pointers only when the target product area document already covers the equivalent content. Three sections route to product areas: Configuration Architecture (L70-139) to CONFIGURATION.md, Source Systems (L585-692) to ANNOTATION.md, and Workflow Integration (L959-1068) to PROCESS.md. Annotation format examples from Source Systems merge into the Four-Stage Pipeline retained section rather than being lost. Workflow API code examples are dropped -- Claude reads source files directly.                                                                                                                                                                                                                                           | Product area documents are generated from annotated source code and already contain live diagrams, relationship graphs, and API types. Absorbing manual Architecture sections into these generated docs eliminates drift while preserving the content in a maintained location. The key test is: does the product area doc cover the same technical facts? If yes, the manual section becomes a 4-line pointer.                                                                                              |
-| MasterDataset shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group master-dataset to extract MasterDataset schema types, RuntimeMasterDataset, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape master-dataset and @architect-include master-dataset contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md.                                                                                                                                                                                                                                                                                                            | The MasterDataset is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md.                                                                                                                                                                             |
-| Pipeline architecture convention content replaces ASCII data flow diagrams      | DD-7: The Data Flow Diagrams section (L774-957) contains 4 ASCII diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer architecture. A new master-dataset-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document.                                                                                                                                                         | ASCII diagrams cannot be generated from code annotations. The hybrid approach maximizes generated coverage: convention-tagged JSDoc captures the narrative (pipeline steps, ADR-006 consumer pattern) while the hardcoded diagram source produces visual Mermaid output. Using the already-registered pipeline-architecture convention tag avoids new taxonomy entries.                                                                                                                                      |
-| Usefulness-driven editorial trimming targets Claude as primary consumer         | DD-9: ARCHITECTURE.md serves Claude (primary audience) and human developers (secondary). Content retained must answer architectural "why" and "how things connect" questions. Content available via source file reads or generated reference documents is removed. Post-decomposition target: ~320 lines (~75% reduction from 1,287 lines). Sections dropped entirely: Programmatic Usage (L1070-1125) and Extending the System (L1127-1194) -- Claude reads source files directly and infers extension patterns from existing codec implementations. DD-5: Key Design Patterns section (L693-772) trimmed from ~80 to ~15 lines: Result Monad becomes a pointer to CORE-TYPES.md, Schema-First Validation becomes a 3-line summary with source pointer, Tag Registry becomes a 4-line summary with source pointer. | Claude has direct access to source files and generated reference docs. Duplicating this content in ARCHITECTURE.md wastes context window tokens. The remaining editorial sections (Executive Summary, Four-Stage Pipeline, Codec Architecture, Progressive Disclosure) provide the mental model and architectural "why" that cannot be inferred from code alone.                                                                                                                                             |
+| Rule                                                                           | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Convention-tagged JSDoc produces machine-extractable codec documentation       | Every codec source file annotated with `@architect-convention<br>    codec-registry` must have structured JSDoc following the machine-extractable format. The convention extractor splits multi-codec files by `## Heading` into separate convention rules, each rendered as its own section in the generated reference document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | DD-1: Convention tag approach over dedicated codec. Rather than creating a new "codec inventory" codec that enumerates codecs from source, the existing convention-tag mechanism is reused. Each codec file's JSDoc is treated as convention rules tagged with `codec-registry`. This avoids new codec infrastructure and leverages the proven convention extractor path. The reference codec already handles 4-layer composition, so convention tags slot into the existing Layer 1 (conventions) position. |
+| Machine-extractable JSDoc format follows structured heading convention         | DD-2: Multi-codec JSDoc splitting uses one `## Heading` per codec per file. Each heading block contains structured fields in a fixed order: `**Purpose:**` one-liner, `**Output Files:**` file paths, options table with Type/Default/Description columns, `**When to Use:**` bullet list, and `**Factory Pattern:**` code example. Fields are optional -- codecs without options omit the table, codecs without factory patterns omit the code block.                                                                                                                                                                                                                                                                                                                                                              | The convention extractor uses `## ` heading regex to split descriptions into rules. Without this structure, a file like `session.ts` (3 codecs) would produce a single undifferentiated blob. The heading text becomes the convention rule title in the generated reference. The fixed field order ensures consistent rendering across all 20+ codec entries.                                                                                                                                                |
+| Heading match in convention extractor handles whitespace correctly             | The convention extractor's heading parser uses `matchEnd` (the character position after the full regex match) rather than `indexOf('\n',<br>    heading.index)` to calculate where content starts after a heading. This prevents the `\s*` prefix in the heading regex from consuming leading newlines, which would cause `heading.index` to point to those newlines instead of the heading text.                                                                                                                                                                                                                                                                                                                                                                                                                   | Discovered during Phase 2 implementation. The heading regex `/^\s*##\s+(.+)$/gm` matches headings with optional leading whitespace. When a heading has leading newlines, `heading.index` points to the first newline (part of the `\s*` match), not the `##` character. Using `indexOf('\n', heading.index)` then finds the newline BEFORE the heading, producing content that includes the heading text itself. The fix uses the regex match's end position directly.                                       |
+| Section disposition follows content-type routing                               | DD-3: Each ARCHITECTURE.md section is routed based on content type. Three routing strategies apply: (1) product area absorption -- sections describing a specific pipeline stage move to the corresponding product area document where they get live diagrams and relationship graphs; (2) generated shapes -- sections documenting TypeScript interfaces move to generated shape reference docs; (3) generated diagrams -- ASCII/text data flow diagrams are replaced by live Mermaid diagrams generated from architecture annotations.                                                                                                                                                                                                                                                                            | The routing heuristic is: if a generated equivalent already exists, replace with pointer; if content is convention-taggable in source files, tag and generate; if editorial content that cannot be expressed as annotations, retain. This ensures each section lands in the location with the best maintenance model for its content type.                                                                                                                                                                   |
+| Product area absorption validates content coverage before pointer replacement  | DD-4: Product area absorption replaces ARCHITECTURE.md sections with pointers only when the target product area document already covers the equivalent content. Three sections route to product areas: Configuration Architecture (L70-139) to CONFIGURATION.md, Source Systems (L585-692) to ANNOTATION.md, and Workflow Integration (L959-1068) to PROCESS.md. Annotation format examples from Source Systems merge into the Four-Stage Pipeline retained section rather than being lost. Workflow API code examples are dropped -- Claude reads source files directly.                                                                                                                                                                                                                                           | Product area documents are generated from annotated source code and already contain live diagrams, relationship graphs, and API types. Absorbing manual Architecture sections into these generated docs eliminates drift while preserving the content in a maintained location. The key test is: does the product area doc cover the same technical facts? If yes, the manual section becomes a 4-line pointer.                                                                                              |
+| PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group pattern-graph to extract PatternGraph schema types, RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape pattern-graph contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md.                                                                                                                                                                                                                                                                                                                                                      | The PatternGraph is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md.                                                                                                                                                                              |
+| Pipeline architecture convention content replaces ASCII data flow diagrams     | DD-7: The Data Flow Diagrams section (L774-957) contains 4 ASCII diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer architecture. A new pattern-graph-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document.                                                                                                                                                          | ASCII diagrams cannot be generated from code annotations. The hybrid approach maximizes generated coverage: convention-tagged JSDoc captures the narrative (pipeline steps, ADR-006 consumer pattern) while the hardcoded diagram source produces visual Mermaid output. Using the already-registered pipeline-architecture convention tag avoids new taxonomy entries.                                                                                                                                      |
+| Usefulness-driven editorial trimming targets Claude as primary consumer        | DD-9: ARCHITECTURE.md serves Claude (primary audience) and human developers (secondary). Content retained must answer architectural "why" and "how things connect" questions. Content available via source file reads or generated reference documents is removed. Post-decomposition target: ~320 lines (~75% reduction from 1,287 lines). Sections dropped entirely: Programmatic Usage (L1070-1125) and Extending the System (L1127-1194) -- Claude reads source files directly and infers extension patterns from existing codec implementations. DD-5: Key Design Patterns section (L693-772) trimmed from ~80 to ~15 lines: Result Monad becomes a pointer to CORE-TYPES.md, Schema-First Validation becomes a 3-line summary with source pointer, Tag Registry becomes a 4-line summary with source pointer. | Claude has direct access to source files and generated reference docs. Duplicating this content in ARCHITECTURE.md wastes context window tokens. The remaining editorial sections (Executive Summary, Four-Stage Pipeline, Codec Architecture, Progressive Disclosure) provide the mental model and architectural "why" that cannot be inferred from code alone.                                                                                                                                             |
 
 ### Architecture Doc Refactoring Testing
 
-| Rule                                                                  | Invariant                                                                                                                                                                                                               | Rationale                                                                                                                                                                                                                                      |
-| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Product area sections coexist with generated documents                | Each architecture section in docs/ARCHITECTURE.md has a corresponding generated document in docs-live/product-areas/ covering equivalent content from annotated sources.                                                | Manual and generated docs must coexist during the transition period. Generated docs prove that annotated sources produce equivalent coverage before manual sections are deprecated.                                                            |
-| Four-Stage Pipeline section retains annotation format examples        | The Four-Stage Pipeline section contains annotation format examples (e.g., @architect-shape, extract-shapes) and appears before the Source Systems section in document order.                                           | Annotation format examples in the pipeline section demonstrate the source-first architecture. Their ordering establishes the conceptual flow: pipeline stages first, then the source systems that feed them.                                   |
-| Convention extraction produces ARCHITECTURE-CODECS reference document | The ARCHITECTURE-CODECS.md reference document is generated from convention-tagged JSDoc in codec source files and contains structured sections for each codec with output file references.                              | Codec documentation must stay synchronized with source code. Convention extraction from JSDoc ensures the reference document reflects actual codec implementations rather than manually maintained descriptions that drift.                    |
-| Full sections coexist with generated equivalents in docs-live         | Major sections of ARCHITECTURE.md (Unified Transformation, Data Flow Diagrams, Quick Reference) are retained alongside their generated equivalents in docs-live/reference/.                                             | Generated reference documents (ARCHITECTURE-TYPES.md, ARCHITECTURE-CODECS.md) provide exhaustive type and codec listings, but the manual sections offer architectural narrative and design rationale that generated docs cannot yet replicate. |
-| MasterDataset shapes appear in ARCHITECTURE-TYPES reference           | The ARCHITECTURE-TYPES.md reference document contains core MasterDataset types (MasterDataset, RuntimeMasterDataset, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. | Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift.                                      |
-| Pipeline architecture convention appears in generated reference       | Source files in the pipeline layer (orchestrator.ts, build-pipeline.ts) carry the pipeline-architecture convention tag, enabling convention extraction into the ARCHITECTURE-TYPES reference document.                  | Convention tags on pipeline source files are the mechanism that feeds content into generated reference docs. Without these tags, the architecture reference would have no source material to extract.                                          |
-| Full ARCHITECTURE.md retains all sections with substantial content    | ARCHITECTURE.md retains all major sections (Programmatic Usage, Extending the System, Key Design Patterns) with substantial content and remains under 1700 lines as a comprehensive reference.                          | These sections contain editorial content (usage examples, extension guides, design pattern explanations) that cannot be generated from annotations. They remain manual until procedural guide codecs can replicate their depth.                |
+| Rule                                                                  | Invariant                                                                                                                                                                                                            | Rationale                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Product area sections coexist with generated documents                | Each architecture section in docs/ARCHITECTURE.md has a corresponding generated document in docs-live/product-areas/ covering equivalent content from annotated sources.                                             | Manual and generated docs must coexist during the transition period. Generated docs prove that annotated sources produce equivalent coverage before manual sections are deprecated.                                                            |
+| Four-Stage Pipeline section retains annotation format examples        | The Four-Stage Pipeline section contains annotation format examples (e.g., @architect-shape, extract-shapes) and appears before the Source Systems section in document order.                                        | Annotation format examples in the pipeline section demonstrate the source-first architecture. Their ordering establishes the conceptual flow: pipeline stages first, then the source systems that feed them.                                   |
+| Convention extraction produces ARCHITECTURE-CODECS reference document | The ARCHITECTURE-CODECS.md reference document is generated from convention-tagged JSDoc in codec source files and contains structured sections for each codec with output file references.                           | Codec documentation must stay synchronized with source code. Convention extraction from JSDoc ensures the reference document reflects actual codec implementations rather than manually maintained descriptions that drift.                    |
+| Full sections coexist with generated equivalents in docs-live         | Major sections of ARCHITECTURE.md (Unified Transformation, Data Flow Diagrams, Quick Reference) are retained alongside their generated equivalents in docs-live/reference/.                                          | Generated reference documents (ARCHITECTURE-TYPES.md, ARCHITECTURE-CODECS.md) provide exhaustive type and codec listings, but the manual sections offer architectural narrative and design rationale that generated docs cannot yet replicate. |
+| PatternGraph shapes appear in ARCHITECTURE-TYPES reference            | The ARCHITECTURE-TYPES.md reference document contains core PatternGraph types (PatternGraph, RuntimePatternGraph, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. | Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift.                                      |
+| Pipeline architecture convention appears in generated reference       | Source files in the pipeline layer (orchestrator.ts, build-pipeline.ts) carry the pipeline-architecture convention tag, enabling convention extraction into the ARCHITECTURE-TYPES reference document.               | Convention tags on pipeline source files are the mechanism that feeds content into generated reference docs. Without these tags, the architecture reference would have no source material to extract.                                          |
+| Full ARCHITECTURE.md retains all sections with substantial content    | ARCHITECTURE.md retains all major sections (Programmatic Usage, Extending the System, Key Design Patterns) with substantial content and remains under 1700 lines as a comprehensive reference.                       | These sections contain editorial content (usage examples, extension guides, design pattern explanations) that cannot be generated from annotations. They remain manual until procedural guide codecs can replicate their depth.                |
 
 ### Arch Tag Extraction
 
@@ -427,19 +427,27 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Cli Recipe Codec
 
-| Rule                                                            | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CLI recipes are a separate generator from reference tables      | The `CliRecipeGenerator` is a standalone sibling to `ProcessApiReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the reference generator produces `docs-live/reference/PROCESS-API-REFERENCE.md`.                                                                                                                                                                   | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. ProcessApiReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one.                                                          |
-| Recipe content uses a structured schema extension               | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged.                                                                                                                                                               | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed.                                                                                                                                                                                                                                     |
-| Narrative prose uses preamble mechanism                         | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file.                                                                                                                                                                                            | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). |
-| Generated recipe file complements manual PROCESS-API.md         | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/PROCESS-API-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source.                                              |
-| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata.                                                                                     | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43.                                                                                                                   |
+| Rule                                                            | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI recipes are a separate generator from reference tables      | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/CLI-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`.                                                                                                                                                                  | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one.                                                                 |
+| Recipe content uses a structured schema extension               | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged.                                                                                                                                       | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed.                                                                                                                                                                                                                                     |
+| Narrative prose uses preamble mechanism                         | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file.                                                                                                                                                                    | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). |
+| Generated recipe file complements manual CLI.md                 | After this pattern completes, `docs/CLI.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/CLI-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source.                                              |
+| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata.                                                             | The manual CLI.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43.                                                                                                                           |
+
+### Cli Reference Generation
+
+| Rule                                                      | Invariant                                                                                                                                                                                                                                                                                                                                                                      | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/CLI-REFERENCE.md` are generated from this schema by a standalone `CliReferenceGenerator`. The schema also drives `showHelp()`.                | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/pattern-graph-cli.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). |
+| Narrative prose sections remain manual                    | CLI.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work.                                                                                                                                                                                                                                                         |
+| Standalone generator respects ADR-006 single read model   | The `CliReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path.                                                                                  | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct.                                                                                                                                                 |
 
 ### Codec Based Generator Testing
 
-| Rule                                                     | Invariant                                                                                                                            | Rationale                                                                                                                    |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| CodecBasedGenerator adapts codecs to generator interface | CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. | The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. |
+| Rule                                                     | Invariant                                                                                                                            | Rationale                                                                                                                                                                                                                  |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CodecBasedGenerator adapts codecs to generator interface | CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. | The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. PatternGraph is required in context — enforced by the TypeScript type system, not at runtime. |
 
 ### Codec Behavior Testing
 
@@ -564,18 +572,18 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Design Review Generation
 
-| Rule                                                                | Invariant                                                                                                                                                                                                                                                                                        | Rationale                                                                                                                                                                                                          |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| SequenceIndex pre-computes ordered steps from rule-level tags       | The MasterDataset sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first.               | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model. Downstream consumers (codec, process API) read structured data, not raw tags. |
-| DesignReviewCodec generates sequence diagrams from ordered steps    | The sequence diagram contains participants derived from `@architect-sequence-module` tags, Note blocks from Rule names, call arrows from Input/Output markers, and alt blocks from `@architect-sequence-error` scenarios. Participant order follows step order with User and orchestrator first. | Sequence diagrams verify interaction ordering and error handling completeness. Auto-generation ensures diagrams stay synchronized with spec annotations. Manual diagrams drift within days of a spec edit.         |
-| DesignReviewCodec generates component diagrams from data flow types | The component diagram groups modules into subgraphs by shared Input type, renders distinct Output types as hexagon nodes with field lists, and draws directed edges showing data flow through the orchestrator. No circular edges exist in the generated diagram.                                | Component diagrams verify unidirectional data flow and interface completeness. Type hexagon nodes make the central contracts visible, informing stub creation with exact field lists.                              |
-| Process API exposes sequence data via subcommand                    | The sequence subcommand with no args lists all patterns with sequence annotations. With a pattern name, it returns the full SequenceIndexEntry including steps, participants, and data flow types.                                                                                               | The Process API is the primary query interface for AI sessions. Exposing sequence data enables design review analysis without regenerating the full document or reading generated markdown.                        |
+| Rule                                                                | Invariant                                                                                                                                                                                                                                                                                        | Rationale                                                                                                                                                                                                         |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SequenceIndex pre-computes ordered steps from rule-level tags       | The PatternGraph sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first.                | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model. Downstream consumers (codec, process API) read structured data, not raw tags. |
+| DesignReviewCodec generates sequence diagrams from ordered steps    | The sequence diagram contains participants derived from `@architect-sequence-module` tags, Note blocks from Rule names, call arrows from Input/Output markers, and alt blocks from `@architect-sequence-error` scenarios. Participant order follows step order with User and orchestrator first. | Sequence diagrams verify interaction ordering and error handling completeness. Auto-generation ensures diagrams stay synchronized with spec annotations. Manual diagrams drift within days of a spec edit.        |
+| DesignReviewCodec generates component diagrams from data flow types | The component diagram groups modules into subgraphs by shared Input type, renders distinct Output types as hexagon nodes with field lists, and draws directed edges showing data flow through the orchestrator. No circular edges exist in the generated diagram.                                | Component diagrams verify unidirectional data flow and interface completeness. Type hexagon nodes make the central contracts visible, informing stub creation with exact field lists.                             |
+| Process API exposes sequence data via subcommand                    | The sequence subcommand with no args lists all patterns with sequence annotations. With a pattern name, it returns the full SequenceIndexEntry including steps, participants, and data flow types.                                                                                               | The Process API is the primary query interface for AI sessions. Exposing sequence data enables design review analysis without regenerating the full document or reading generated markdown.                       |
 
 ### Design Review Generation Tests
 
 | Rule                                                                       | Invariant                                                                                                                                                                                              | Rationale                                                                                                                                                                 |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SequenceIndex pre-computes ordered steps from annotated rules              | buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model.                                      |
+| SequenceIndex pre-computes ordered steps from annotated rules              | buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model.                                       |
 | Participants are deduplicated with orchestrator first                      | The participants array starts with the orchestrator, followed by module names in first-appearance step order, with no duplicates.                                                                      | Sequence diagram participant declarations must be ordered and unique. The orchestrator is always the first participant as the entry point.                                |
 | Data flow types are extracted from Input and Output annotations            | The dataFlowTypes array contains distinct type names parsed from Input and Output annotation strings using the "TypeName -- fields" format.                                                            | Data flow types are used by the component diagram to render hexagon nodes and by the type definitions table to show producers and consumers.                              |
 | DesignReviewCodec produces sequence diagram with correct participant count | The rendered sequence diagram participant list includes User plus all participants from the SequenceIndexEntry. The count equals 1 (User) plus the number of unique participants.                      | Correct participant count proves the codec reads SequenceIndex data correctly and maps it to Mermaid syntax.                                                              |
@@ -586,7 +594,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | Mermaid-sensitive text is escaped across rendered labels                   | Participant aliases, subgraph labels, type hexagon text, and edge labels escape Mermaid-sensitive characters such as quotes, pipes, and comment markers before rendering.                              | Design review diagrams are generated directly from annotations. Valid annotation text must not break Mermaid parsing when rendered into different label positions.        |
 | Design questions table includes auto-computed metrics                      | The Design Questions section contains a table with auto-computed step count, type count, and error path count drawn from the SequenceIndexEntry data.                                                  | Auto-computed metrics reduce manual counting during design reviews and highlight coverage gaps (e.g., 0 error paths).                                                     |
 | Invalid sequence annotations are skipped with validation warnings          | Patterns with ambiguous sequence-step numbering or empty sequence-module tags are excluded from sequenceIndex and reported through malformedPatterns.                                                  | Design reviews should never render misleading diagrams from malformed annotations. The transform pass is the correct place to validate and suppress bad sequence entries. |
-| Process API sequence lookup resolves pattern names case-insensitively      | The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented process-api queries.                                                         | Design review consumers should not need exact display-name casing when querying sequence data from the CLI.                                                               |
+| Process API sequence lookup resolves pattern names case-insensitively      | The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented pattern-graph queries.                                                       | Design review consumers should not need exact display-name casing when querying sequence data from the CLI.                                                               |
 
 ### Design Review Generator Lifecycle Tests
 
@@ -613,7 +621,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | Convention tags are the primary consolidation mechanism | Each consolidation phase follows the same pattern: register a convention tag value in `src/taxonomy/conventions.ts`, annotate source files with `@architect-convention` tags using structured JSDoc, add a `ReferenceDocConfig` entry in `architect.config.ts`, and replace the manual doc section with a pointer to the generated reference document.                                                                                                                                      | Convention-tagged annotations are the only sustainable way to keep docs in sync with implementation. The reference codec (`createReferenceCodec`) already handles the 4-layer composition so each phase only needs annotation work and config — no new codec infrastructure required.                                                                                                                                                                            |
 | Preamble preserves editorial context in generated docs  | `ReferenceDocConfig.preamble` accepts `readonly SectionBlock[]` that are prepended before all generated content. Preamble sections appear in both detailed and summary (claude-md) outputs, followed by a separator. A config without preamble produces no extra separator or empty sections.                                                                                                                                                                                               | Not all documentation content can be extracted from code annotations. Introductory prose, cross-cutting context, and reading guides require human authorship. The preamble provides a designated place for this content within the generated document structure, avoiding a separate hand-maintained file.                                                                                                                                                       |
 | Each consolidation phase is independently deliverable   | Each phase can be implemented and validated independently. A phase is complete when: the manual doc section has been replaced with a pointer to the generated equivalent, `pnpm docs:all` produces the generated output without errors, and the generated content covers the replaced manual content. No phase requires another uncompleted phase to function.                                                                                                                              | Independent phases allow incremental consolidation without blocking on the full initiative. Each merged PR reduces manual maintenance immediately. Phase ordering in the plan is a suggested sequence (simplest first), not a dependency chain.                                                                                                                                                                                                                  |
-| Manual docs retain editorial and tutorial content       | Documents containing philosophy (METHODOLOGY.md) remain fully manual with no generated equivalent (~238 lines). Documents that were originally manual but now have generated equivalents or have been restructured (SESSION-GUIDES.md, GHERKIN-PATTERNS.md, PROCESS-API.md) retain their editorial content as preamble within generated outputs. PUBLISHING.md was relocated to MAINTAINERS.md at the repository root.                                                                      | The consolidation targets sections most likely to drift when code changes: reference tables, codec listings, validation rules, API types. Editorial content changes at a different cadence and requires human judgment to update. Forcing this into annotations would produce worse documentation. Documents that transitioned to hybrid generation preserve their editorial voice via preamble while keeping reference content in sync with source annotations. |
+| Manual docs retain editorial and tutorial content       | Documents containing philosophy (METHODOLOGY.md) remain fully manual with no generated equivalent (~238 lines). Documents that were originally manual but now have generated equivalents or have been restructured (SESSION-GUIDES.md, GHERKIN-PATTERNS.md, CLI.md) retain their editorial content as preamble within generated outputs. PUBLISHING.md was relocated to MAINTAINERS.md at the repository root.                                                                              | The consolidation targets sections most likely to drift when code changes: reference tables, codec listings, validation rules, API types. Editorial content changes at a different cadence and requires human judgment to update. Forcing this into annotations would produce worse documentation. Documents that transitioned to hybrid generation preserve their editorial voice via preamble while keeping reference content in sync with source annotations. |
 | Audience alignment determines document location         | Each document lives in the location matching its primary audience: `docs/` (deployed to libar.dev) for content that serves package users and developers; repo root for GitHub-visible metadata (CONTRIBUTING.md, SECURITY.md, MAINTAINERS.md); CLAUDE.md for AI session context. A document appearing in docs/ must be useful to a developer or user visiting the website — maintainer-only operational procedures (npm publishing workflow, GitHub Actions setup) belong at the repo root. | The audit found PUBLISHING.md (maintainer-only) in docs/ alongside user-facing guides. SESSION-GUIDES.md (AI session procedures) duplicates CLAUDE.md with 95% overlap. Audience mismatches increase website noise for users and create drift risk when the same content lives in two locations.                                                                                                                                                                 |
 
 ### Docs Live Consolidation
@@ -631,12 +639,12 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Enhanced Index Generation
 
-| Rule                                                               | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| IndexCodec composes generated statistics with editorial navigation | The IndexCodec generates document listings and pattern statistics from MasterDataset pre-computed views (`byCategory`, `byPhase`, `byProductArea`, `byStatus`), while audience reading paths, the document roles matrix, and the quick finder table use the `ReferenceDocConfig.preamble` mechanism as manually authored `SectionBlock[]`. The codec does not hardcode document metadata -- all statistics are derived from the dataset at generation time. Editorial content changes at authorial cadence via config edits, not code changes.       | Approximately 40% of INDEX.md content (product area lists, file inventories, pattern statistics, phase progress) is directly derivable from MasterDataset views and drifts when patterns change status or new patterns are added. The remaining 60% (audience paths, document roles, quick finder) requires human editorial judgment about which documents serve which readers. The preamble mechanism cleanly separates these two content types within a single generated output, as proven by CodecDrivenReferenceGeneration and DocsConsolidationStrategy Phase 2. |
-| Audience reading paths are first-class sections                    | Three audience profiles exist in the generated index: New User, Developer/AI, and Team Lead/CI. Each profile has a curated reading order that lists documents in recommended sequence with a one-line description of what each document provides for that audience. Reading paths appear prominently after the quick navigation table and before the auto-generated statistics sections. The reading paths are sourced from preamble, not derived from pattern metadata.                                                                             | The manual INDEX.md reading orders are consistently cited as the most useful navigation aid by developers onboarding to the project. A flat alphabetical file listing (as in the current docs-live/INDEX.md) forces readers to guess which documents are relevant to their role. Audience-specific paths reduce time-to-relevance from minutes of scanning to seconds of following a curated sequence. This content is inherently editorial -- no annotation can express "read this third because it builds on concepts from document two."                           |
-| Index unifies manual and generated doc listings                    | The generated index covers both `docs/` (manual reference documents) and `docs-live/` (generated reference documents) in a single unified navigation structure. Documents are organized by topic or audience, not by source directory. The reader does not need to know whether a document is manually authored or auto-generated. Each document entry includes its title, a brief description, and its primary audience. The directory source (docs/ or docs-live/) appears only in the link path, not as a section heading or organizational axis. | The current documentation set splits across two directories for implementation reasons (manual vs generated), but this split is meaningless to readers. A developer looking for architecture documentation should find one entry, not separate entries under "Manual Docs" and "Generated Docs" sections. The unified listing follows the same principle as a library catalog -- books are organized by subject, not by whether they were hand-typeset or digitally printed.                                                                                          |
-| Document metadata drives auto-generated sections                   | Pattern counts per product area, phase progress summaries, and product area coverage percentages are derived from MasterDataset pre-computed views at generation time. The IndexCodec accesses `dataset.byProductArea` for area statistics, `dataset.byStatus` for status distribution, and `dataset.byPhase` for phase ordering. No statistics are hardcoded in the codec or config. When a pattern changes status or a new pattern is added, regenerating the index reflects the change without any manual update.                                 | The manual INDEX.md has no statistics section because maintaining accurate counts manually is unsustainable across 196+ patterns. The MasterDataset pre-computed views provide O(1) access to grouped pattern data. Surfacing these statistics in the index gives readers an at-a-glance project health overview (how many patterns per area, what percentage are completed, which phases are active) that was previously only available via the Process Data API CLI.                                                                                                |
+| Rule                                                               | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| IndexCodec composes generated statistics with editorial navigation | The IndexCodec generates document listings and pattern statistics from PatternGraph pre-computed views (`byCategory`, `byPhase`, `byProductArea`, `byStatus`), while audience reading paths, the document roles matrix, and the quick finder table use the `ReferenceDocConfig.preamble` mechanism as manually authored `SectionBlock[]`. The codec does not hardcode document metadata -- all statistics are derived from the dataset at generation time. Editorial content changes at authorial cadence via config edits, not code changes.        | Approximately 40% of INDEX.md content (product area lists, file inventories, pattern statistics, phase progress) is directly derivable from PatternGraph views and drifts when patterns change status or new patterns are added. The remaining 60% (audience paths, document roles, quick finder) requires human editorial judgment about which documents serve which readers. The preamble mechanism cleanly separates these two content types within a single generated output, as proven by CodecDrivenReferenceGeneration and DocsConsolidationStrategy Phase 2. |
+| Audience reading paths are first-class sections                    | Three audience profiles exist in the generated index: New User, Developer/AI, and Team Lead/CI. Each profile has a curated reading order that lists documents in recommended sequence with a one-line description of what each document provides for that audience. Reading paths appear prominently after the quick navigation table and before the auto-generated statistics sections. The reading paths are sourced from preamble, not derived from pattern metadata.                                                                             | The manual INDEX.md reading orders are consistently cited as the most useful navigation aid by developers onboarding to the project. A flat alphabetical file listing (as in the current docs-live/INDEX.md) forces readers to guess which documents are relevant to their role. Audience-specific paths reduce time-to-relevance from minutes of scanning to seconds of following a curated sequence. This content is inherently editorial -- no annotation can express "read this third because it builds on concepts from document two."                          |
+| Index unifies manual and generated doc listings                    | The generated index covers both `docs/` (manual reference documents) and `docs-live/` (generated reference documents) in a single unified navigation structure. Documents are organized by topic or audience, not by source directory. The reader does not need to know whether a document is manually authored or auto-generated. Each document entry includes its title, a brief description, and its primary audience. The directory source (docs/ or docs-live/) appears only in the link path, not as a section heading or organizational axis. | The current documentation set splits across two directories for implementation reasons (manual vs generated), but this split is meaningless to readers. A developer looking for architecture documentation should find one entry, not separate entries under "Manual Docs" and "Generated Docs" sections. The unified listing follows the same principle as a library catalog -- books are organized by subject, not by whether they were hand-typeset or digitally printed.                                                                                         |
+| Document metadata drives auto-generated sections                   | Pattern counts per product area, phase progress summaries, and product area coverage percentages are derived from PatternGraph pre-computed views at generation time. The IndexCodec accesses `dataset.byProductArea` for area statistics, `dataset.byStatus` for status distribution, and `dataset.byPhase` for phase ordering. No statistics are hardcoded in the codec or config. When a pattern changes status or a new pattern is added, regenerating the index reflects the change without any manual update.                                  | The manual INDEX.md has no statistics section because maintaining accurate counts manually is unsustainable across 196+ patterns. The PatternGraph pre-computed views provide O(1) access to grouped pattern data. Surfacing these statistics in the index gives readers an at-a-glance project health overview (how many patterns per area, what percentage are completed, which phases are active) that was previously only available via the Process Data API CLI.                                                                                                |
 
 ### Error Guide Codec
 
@@ -663,7 +671,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Behavior-specs renderer does not duplicate convention table content       | When the reference codec renders a convention rule that contains a table, the table appears exactly once in the output: in the main convention section. The behavior-specs (expanded rule detail) section shows only the Invariant, Rationale, and Verified-by metadata — not the table body. A convention section with N tables produces exactly N table instances in the generated document, regardless of detail level. | DD-4: The current renderer re-includes the full convention table when rendering the expanded rule detail section. For REFERENCE-SAMPLE.md with 5 canonical value tables, this produces 500+ lines of exact duplication. Agents consuming this file waste context on content they already parsed. Human readers see the same table twice in the same scroll view.        |
 | Compact \_claude-md/ files are self-sufficient for their product area     | Each product area compact (`_claude-md/<area>/<area>-overview.md`) is self-sufficient as a standalone context file — an agent reading only the compact can answer: what does this area do, what are its key patterns, what are its invariants, and what files to read for details. Minimum target: 4 KB. The Generation compact is a specific gap: 1.4 KB for an area with 20+ codecs and the entire rendering pipeline.   | DD-2: `_claude-md/` compacts are the Claude consumption contract. A 1.4 KB compact for the largest product area (233 KB) means agents have no usable summary context for Generation. They fall back to reading the full file or hallucinating based on names alone. The contract requires each compact to be a genuine summary, not a stub.                             |
-| ARCHITECTURE-TYPES.md leads with type definitions, not convention content | ARCHITECTURE-TYPES.md opens with the MasterDataset type definitions section before any pipeline-architecture convention content. An agent querying "what is MasterDataset" finds the type definition within the first 30 lines. The pipeline-architecture convention prose (orchestrator responsibilities, pipeline steps) follows the type definitions section.                                                           | The file is named ARCHITECTURE-TYPES — type definitions are the primary content. The pipeline-architecture convention content was added as a secondary layer. Current output opens with orchestrator prose, burying the type definitions that both Claude and human developers are most likely seeking. Section ordering in ReferenceDocConfig determines render order. |
+| ARCHITECTURE-TYPES.md leads with type definitions, not convention content | ARCHITECTURE-TYPES.md opens with the PatternGraph type definitions section before any pipeline-architecture convention content. An agent querying "what is PatternGraph" finds the type definition within the first 30 lines. The pipeline-architecture convention prose (orchestrator responsibilities, pipeline steps) follows the type definitions section.                                                             | The file is named ARCHITECTURE-TYPES — type definitions are the primary content. The pipeline-architecture convention content was added as a secondary layer. Current output opens with orchestrator prose, burying the type definitions that both Claude and human developers are most likely seeking. Section ordering in ReferenceDocConfig determines render order. |
 
 ### Generated Doc Quality Tests
 
@@ -680,7 +688,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | Orchestrator coordinates full documentation generation pipeline | Orchestrator merges TypeScript and Gherkin patterns, handles conflicts, and produces requested document types.              | Without centralized orchestration, consumers would wire pipelines independently, leading to inconsistent merging and silent data loss.     |
 | Registry manages generator registration and retrieval           | Registry prevents duplicate names, returns undefined for unknown generators, and lists available generators alphabetically. | Duplicate registrations would silently overwrite generators, causing unpredictable output depending on registration order.                 |
-| CodecBasedGenerator adapts codecs to generator interface        | Generator delegates to underlying codec for transformation. Missing MasterDataset produces descriptive error.               | If the adapter silently proceeds without a MasterDataset, codecs receive undefined input and produce corrupt or empty documents.           |
+| CodecBasedGenerator adapts codecs to generator interface        | Generator delegates to underlying codec for transformation. Missing PatternGraph produces descriptive error.                | If the adapter silently proceeds without a PatternGraph, codecs receive undefined input and produce corrupt or empty documents.            |
 | Orchestrator supports PR changes generation options             | PR changes can filter by git diff, changed files, or release version.                                                       | Without filtering, PR documentation would include all patterns in the dataset, making change review noisy and hiding actual modifications. |
 
 ### Generator Registry Testing
@@ -713,6 +721,21 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | All implementation links in a pattern are normalized       | Every implementation link in a pattern document must have its path normalized, regardless of how many implementations exist.         | A single un-normalized link in a multi-implementation pattern produces a broken reference that undermines trust in the entire generated document. |
 | normalizeImplPath strips known prefixes                    | normalizeImplPath removes only recognized repository prefixes from the start of a path and leaves all other path segments unchanged. | Over-stripping would corrupt legitimate path segments that happen to match a prefix name, producing silent broken links.                          |
 
+### Index Codec Testing
+
+| Rule                                              | Invariant                                                                                                                                                                                                                                                                           | Rationale                                                                                                                                                             |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Document metadata is correctly set                | The index document must have the title "Documentation Index", a purpose string referencing @libar-dev/architect, and all sections enabled when using default options.                                                                                                               | Document metadata drives navigation and table of contents generation — incorrect titles or missing purpose strings produce broken index pages in generated doc sites. |
+| Package metadata section renders correctly        | The Package Metadata section must always render a table with hardcoded fields: Package (@libar-dev/architect), Purpose, Patterns count derived from dataset, Product Areas count derived from dataset, and License (MIT).                                                           | Package metadata provides readers with an instant snapshot of the project — hardcoded fields ensure consistent branding while dataset-derived counts stay accurate.   |
+| Document inventory groups entries by topic        | When documentEntries is non-empty and includeDocumentInventory is true, entries must be grouped by topic with one H3 sub-heading and one table per topic group. When entries are empty, no inventory section is rendered.                                                           | A flat list of all documents becomes unnavigable beyond a small count — topic grouping gives readers a structured entry point into the documentation set.             |
+| Product area statistics are computed from dataset | The Product Area Statistics table must list each product area alphabetically with Patterns, Completed, Active, Planned, and Progress columns, plus a bolded Total row aggregating all areas. The progress column must contain a visual progress bar and percentage.                 | Product area statistics give team leads a cross-cutting view of work distribution — alphabetical order and a total row enable fast scanning and aggregate assessment. |
+| Phase progress summarizes pattern status          | The Phase Progress section must render a summary paragraph with total, completed, active, and planned counts, a status distribution table with Status/Count/Percentage columns, and — when patterns have phase numbers — a "By Phase" sub-section with a per-phase breakdown table. | Phase progress is the primary indicator of delivery health — the summary paragraph provides instant context while the distribution table enables deeper analysis.     |
+| Regeneration footer contains commands             | The Regeneration section must always be present (it is not optional), must contain the heading "Regeneration", and must include at least one code block with pnpm commands.                                                                                                         | The regeneration footer ensures consumers always know how to rebuild the docs — it is unconditional so it cannot be accidentally omitted.                             |
+| Section ordering follows layout contract          | Sections must appear in this fixed order: Package Metadata, preamble (if any), Document Inventory (if any), Product Area Statistics, Phase Progress, Regeneration. Separators must appear after each non-final section group. This order is the layout contract for INDEX.md.       | Consumers depend on a predictable INDEX.md structure for navigation links — reordering sections would break existing bookmarks and tool-generated cross-references.   |
+| Custom purpose text overrides default             | When purposeText is set to a non-empty string, the document purpose must use that string instead of the auto-generated default. When purposeText is empty or omitted, the auto-generated purpose is used.                                                                           | Consumers with different documentation sets need to customize the navigation purpose without post-processing the generated output.                                    |
+| Epilogue replaces regeneration footer             | When epilogue sections are provided, they completely replace the built-in regeneration footer. When epilogue is empty, the regeneration footer is rendered as before.                                                                                                               | Consumers may need a custom footer (e.g., links to CI, contribution guides) that has nothing to do with regeneration commands.                                        |
+| Package metadata overrides work                   | When packageMetadataOverrides provides a value for name, purpose, or license, that value replaces the corresponding default or projectMetadata value in the Package Metadata table. Unset override keys fall through to the default chain.                                          | Consumers reusing the IndexCodec for different packages need to override individual metadata fields without providing a full projectMetadata object.                  |
+
 ### Layered Diagram Generation
 
 | Rule                                                    | Invariant                                                                                                                             | Rationale                                                                                                                                  |
@@ -748,13 +771,13 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Orchestrator Pipeline Factory Migration
 
-| Rule                                                    | Invariant                                                                                                                                                                                                                                                                                                        | Rationale                                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Orchestrator delegates pipeline to factory              | `generateDocumentation()` calls `buildMasterDataset()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`).                              | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit.                                                                      |
-| mergePatterns lives in pipeline module                  | The `mergePatterns()` function lives in `src/generators/pipeline/merge-patterns.ts` as a pipeline step. It is not defined in consumer code (orchestrator or CLI files).                                                                                                                                          | `mergePatterns` is step 5 of the 8-step pipeline. It was defined in orchestrator.ts for historical reasons (the orchestrator was the first pipeline host). Now that the pipeline factory exists, the function belongs alongside other pipeline steps (scan, extract, transform). The public API re-export in `generators/index.ts` preserves backward compatibility.         |
-| Factory provides structured warnings for all consumers  | `PipelineResult.warnings` contains typed warning objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers that need simple messages (process-api) read `.message` only. | The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured `GenerationWarning` objects. The factory must provide equivalent structure to eliminate the orchestrator's need to run the pipeline directly. The `PipelineWarning` type is structurally similar to `GenerationWarning` to minimize mapping complexity. |
-| Pipeline factory supports partial success mode          | When `failOnScanErrors` is false, the factory captures scan errors and extraction errors as warnings and continues with successfully processed files. When true (default), the factory returns `Result.err` on the first scan failure.                                                                           | The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable files even if some files have syntax errors. The process-api treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration.                                              |
-| End-to-end verification confirms behavioral equivalence | After migration, all CLI commands and doc generation produce identical output to pre-refactor behavior.                                                                                                                                                                                                          | The migration must not change observable behavior for any consumer. Full verification confirms the factory migration is a pure refactor.                                                                                                                                                                                                                                     |
+| Rule                                                    | Invariant                                                                                                                                                                                                                                                                                                              | Rationale                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Orchestrator delegates pipeline to factory              | `generateDocumentation()` calls `buildPatternGraph()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`).                                     | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit.                                                                      |
+| mergePatterns lives in pipeline module                  | The `mergePatterns()` function lives in `src/generators/pipeline/merge-patterns.ts` as a pipeline step. It is not defined in consumer code (orchestrator or CLI files).                                                                                                                                                | `mergePatterns` is step 5 of the 8-step pipeline. It was defined in orchestrator.ts for historical reasons (the orchestrator was the first pipeline host). Now that the pipeline factory exists, the function belongs alongside other pipeline steps (scan, extract, transform). The public API re-export in `generators/index.ts` preserves backward compatibility.         |
+| Factory provides structured warnings for all consumers  | `PipelineResult.warnings` contains typed warning objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers that need simple messages (pattern-graph-cli) read `.message` only. | The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured `GenerationWarning` objects. The factory must provide equivalent structure to eliminate the orchestrator's need to run the pipeline directly. The `PipelineWarning` type is structurally similar to `GenerationWarning` to minimize mapping complexity. |
+| Pipeline factory supports partial success mode          | When `failOnScanErrors` is false, the factory captures scan errors and extraction errors as warnings and continues with successfully processed files. When true (default), the factory returns `Result.err` on the first scan failure.                                                                                 | The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable files even if some files have syntax errors. The pattern-graph-cli treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration.                                        |
+| End-to-end verification confirms behavioral equivalence | After migration, all CLI commands and doc generation produce identical output to pre-refactor behavior.                                                                                                                                                                                                                | The migration must not change observable behavior for any consumer. Full verification confirms the factory migration is a pure refactor.                                                                                                                                                                                                                                     |
 
 ### Patterns Codec Testing
 
@@ -855,21 +878,13 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 | Rule                                                                           | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Procedural guides use a dual-source codec                                      | The ProceduralGuideCodec composes auto-generated reference sections (from MasterDataset and taxonomy) with manually-authored procedural content (from preamble `SectionBlock[]`). Auto-generated content covers ~5% of the output (tag reference tables, pattern statistics, session type contract tables extracted from                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Procedural guides use a dual-source codec                                      | The ProceduralGuideCodec composes auto-generated reference sections (from PatternGraph and taxonomy) with manually-authored procedural content (from preamble `SectionBlock[]`). Auto-generated content covers ~5% of the output (tag reference tables, pattern statistics, session type contract tables extracted from                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | blocks). The remaining ~95% is editorial preamble: checklists, decision trees, |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Gap analysis found that SESSION-GUIDES.md and ANNOTATION-GUIDE.md content is overwhelmingly procedural and editorial. Attempting to annotate checklists and walkthroughs as source code would produce worse documentation than hand-authoring. The dual-source pattern (proven by CodecDrivenReferenceGeneration, ErrorGuideCodec, and CliRecipeCodec) composes preamble editorial content with auto-generated reference sections. The codec's value is not in generating the procedural content but in providing a single output pipeline that keeps reference tables current while carrying editorial content in a consistent structure.     |
-| Session workflow checklists derive from annotated Rule: blocks                 | The SessionGuidesModuleSource spec's Rule: blocks (Rules 3-8) are the canonical source for session workflow invariants. The ProceduralGuideCodec extracts structured tables from these Rule: blocks and renders them as developer-facing checklists at the detailed level. The same Rule: blocks produce compact invariant statements for `_claude-md/workflow/` modules at the summary level. Two audiences (public developers and AI sessions) are served from a single annotated source with different rendering detail levels. The codec does not duplicate or re-derive Rule: block content -- it reads from MasterDataset's behavior extraction views.                                                                         | SessionGuidesModuleSource already captures session type contracts (Rule 3), planning constraints (Rule 4), design constraints (Rule 5), implementation execution order (Rule 6), FSM error reference (Rule 7), and handoff patterns (Rule 8) as structured tables within Rule: block descriptions. These tables contain the same information as the manual SESSION-GUIDES.md checklists, but in a machine-extractable format. Rendering these as developer-facing checklists eliminates the maintenance burden of keeping the manual file in sync with the spec, while the compact rendering for AI context was already delivered by Phase 39. |
+| Session workflow checklists derive from annotated Rule: blocks                 | The SessionGuidesModuleSource spec's Rule: blocks (Rules 3-8) are the canonical source for session workflow invariants. The ProceduralGuideCodec extracts structured tables from these Rule: blocks and renders them as developer-facing checklists at the detailed level. The same Rule: blocks produce compact invariant statements for `_claude-md/workflow/` modules at the summary level. Two audiences (public developers and AI sessions) are served from a single annotated source with different rendering detail levels. The codec does not duplicate or re-derive Rule: block content -- it reads from PatternGraph's behavior extraction views.                                                                          | SessionGuidesModuleSource already captures session type contracts (Rule 3), planning constraints (Rule 4), design constraints (Rule 5), implementation execution order (Rule 6), FSM error reference (Rule 7), and handoff patterns (Rule 8) as structured tables within Rule: block descriptions. These tables contain the same information as the manual SESSION-GUIDES.md checklists, but in a machine-extractable format. Rendering these as developer-facing checklists eliminates the maintenance burden of keeping the manual file in sync with the spec, while the compact rendering for AI context was already delivered by Phase 39. |
 | Annotation guide content remains separate from session guides                  | The ProceduralGuideCodec produces two separate generated files via two `ReferenceDocConfig` entries: one for session workflow guides (replacing SESSION-GUIDES.md) and one for annotation guides (replacing ANNOTATION-GUIDE.md). The session workflow guide targets workflow practitioners who need to know session type selection, execution order, and FSM error recovery. The annotation guide targets annotation authors who need to know opt-in markers, tag syntax, shape extraction modes, and verification steps. These audiences overlap but have distinct primary needs. The codec class is shared; the config entries and preamble content differ.                                                                       | SESSION-GUIDES.md and ANNOTATION-GUIDE.md serve different audiences at different points in the development lifecycle. Merging them into a single guide would force annotation authors to navigate session workflow content and vice versa. The existing DocsConsolidationStrategy Phase 5 (Guide trimming) already treats them as separate documents. Using one codec class with two config entries follows the same pattern as `createReferenceCodec` producing multiple documents from different configs.                                                                                                                                    |
 | Decision trees render as Mermaid flowcharts                                    | Session type decision trees and annotation workflow decision trees render as Mermaid flowchart diagrams in the detailed output level. The session type decision tree replaces the ASCII art tree in SESSION-GUIDES.md with a Mermaid `graph TD` diagram that renders as an interactive flowchart on the Starlight website. Decision tree content is authored as fenced mermaid code blocks in the markdown source file, parsed into `MermaidBlock` entries by `loadPreambleFromMarkdown()` at config load time. At summary level, decision trees render as compact text tables instead of diagrams.                                                                                                                                  | The manual SESSION-GUIDES.md uses an ASCII art tree for the session decision flow, which renders poorly on the website and cannot be interacted with. Mermaid flowcharts are already supported by the Starlight website (proven by product area docs with C4Context and graph LR diagrams). Converting decision trees to Mermaid provides visual clarity, click-through navigation, and consistent rendering across platforms. The content block type `mermaid` is already one of the 9 supported SectionBlock types (proven by ReferenceDocShowcase).                                                                                         |
 | Generated guide supersedes manual only at quality parity                       | The manual `docs/SESSION-GUIDES.md` is retained in the repository until the generated equivalent matches or exceeds its quality across all content dimensions: completeness (all checklists present), accuracy (all FSM states current), visual clarity (decision trees render correctly), and usability (verified by comparison audit). The SessionGuidesModuleSource invariant ("not deleted, shortened, or replaced with a redirect") is respected during the transition period. The quality comparison deliverable produces an explicit audit document recording which sections have parity and which gaps remain. Only after the audit confirms full parity is the manual file replaced with a pointer to the generated output. | SESSION-GUIDES.md is cited in the SessionGuidesModuleSource spec as "the authoritative public human reference" serving developers on libar.dev. Replacing it prematurely with a generated equivalent that lacks checklists, has formatting issues, or omits edge cases would degrade the developer experience. The quality-gated approach ensures the generated version earns its place as the replacement by demonstrating equivalent or better quality, not merely by existing. This is the same principle applied by DocsConsolidationStrategy: "Manual docs retain editorial and tutorial content" until generation quality is sufficient. |
 
-### Process Api Hybrid Generation
-
-| Rule                                                      | Invariant                                                                                                                                                                                                                                                                                                                                                                              | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/PROCESS-API-REFERENCE.md` are generated from this schema by a standalone `ProcessApiReferenceGenerator`. The schema also drives `showHelp()`.         | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/process-api.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from MasterDataset (annotation-derived data), not static constants (ADR-006). |
-| Narrative prose sections remain manual                    | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work.                                                                                                                                                                                                                                                    |
-| Standalone generator respects ADR-006 single read model   | The `ProcessApiReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into MasterDataset or consume MasterDataset for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path.                                                                                 | ADR-006 establishes MasterDataset as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through MasterDataset would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct.                                                                                                                                          |
-
 ### Publishing Relocation
 
 | Rule                                                  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -916,7 +931,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | Rule                                                    | Invariant                                                                                                                                                                                                 | Rationale                                                                                                                                                              |
 | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Scoped diagrams are generated from diagramScopes config | Diagram content is determined exclusively by diagramScopes filters (archContext, include, archLayer, patterns), and filters compose via OR — a pattern matching any single filter appears in the diagram. | Without filter-driven scoping, diagrams would include all patterns regardless of relevance, producing unreadable visualizations that obscure architectural boundaries. |
-| Hardcoded diagram sources render deterministic output   | Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content.                                                                                     | Domain diagrams such as pipeline and MasterDataset fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape.                    |
+| Hardcoded diagram sources render deterministic output   | Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content.                                                                                     | Domain diagrams such as pipeline and PatternGraph fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape.                     |
 | Multiple diagram scopes produce multiple mermaid blocks | Each entry in the diagramScopes array produces an independent Mermaid block with its own title and direction.                                                                                             | Product areas require multiple architectural views (e.g., system overview and data flow) from a single configuration.                                                  |
 
 ### Reference Codec Diagram Type Testing
@@ -933,7 +948,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 | Deep behavior rendering replaces shallow truncation                          | At standard and detailed levels, behavior sections render full rule descriptions with parsed invariant, rationale, and verified-by content. At summary level, the 120-character truncation is preserved for compact output. Behavior rendering reuses parseBusinessRuleAnnotations from the convention extractor rather than reimplementing structured content parsing.                                                                                                                                                                                | The current 120-character truncation discards invariants, rationale, and verified-by content that is already extracted and available in BusinessRule.description. Reference documents need the full rule content to serve as authoritative documentation. The convention extractor already parses this structured content via parseBusinessRuleAnnotations -- the behavior builder should delegate to the same function.                                                                           |
 | Shape sections include JSDoc prose and property documentation                | At standard level, shape code blocks are preceded by JSDoc prose when available. At detailed level, interface shapes additionally render a property documentation table. At summary level, only the type-kind table appears. Shapes without JSDoc render code blocks without preceding paragraph.                                                                                                                                                                                                                                                      | JSDoc on shapes contains design rationale and usage guidance that is already extracted by the shape extractor. Gating it behind detailed level wastes the data at the most common detail level (standard). The fix is a single condition change: reference.ts line 342 from detailLevel === 'detailed' to detailLevel !== 'summary'.                                                                                                                                                               |
 | Diagram scope supports archLayer filtering and multiple diagram types        | DiagramScope gains optional archLayer and diagramType fields. The archLayer filter selects patterns by their architectural layer (domain, application, infrastructure) and composes with archContext and archView via OR logic, consistent with existing filter dimensions. The diagramType field controls Mermaid output format: graph (default), sequenceDiagram, stateDiagram-v2, C4Context, classDiagram. Each diagram type has its own node and edge syntax appropriate to the Mermaid specification.                                             | Layer-based views are fundamental to layered architecture documentation -- a developer reviewing the domain layer wants only deciders and value objects, not infrastructure adapters. Multiple diagram types unlock event flow documentation (sequence), FSM visualization (state), architecture overview (C4), and type hierarchy views (class) that flowcharts cannot express naturally.                                                                                                         |
-| Every renderable block type appears in the showcase document                 | The generated REFERENCE-SAMPLE.md at detailed level must contain at least one instance of each of the 9 block types: heading, paragraph, separator, table, list, code, mermaid, collapsible, link-out. At summary level, progressive disclosure blocks (collapsible, link-out) are omitted for compact output.                                                                                                                                                                                                                                         | The sample document is the integration test for the reference codec. If any block type is missing, there is no automated verification that the codec can produce it. Coverage of all 9 types validates the full rendering pipeline from MasterDataset through codec through renderer.                                                                                                                                                                                                              |
+| Every renderable block type appears in the showcase document                 | The generated REFERENCE-SAMPLE.md at detailed level must contain at least one instance of each of the 9 block types: heading, paragraph, separator, table, list, code, mermaid, collapsible, link-out. At summary level, progressive disclosure blocks (collapsible, link-out) are omitted for compact output.                                                                                                                                                                                                                                         | The sample document is the integration test for the reference codec. If any block type is missing, there is no automated verification that the codec can produce it. Coverage of all 9 types validates the full rendering pipeline from PatternGraph through codec through renderer.                                                                                                                                                                                                               |
 | Edge labels and custom node shapes enrich diagram readability                | Relationship edges in scoped diagrams display labels describing the relationship semantics (uses, dependsOn, implements, extends). Edge labels are enabled by default and can be disabled via a showEdgeLabels option for compact diagrams. Node shapes vary by archRole value -- services use rounded rectangles, bounded contexts use subgraphs, projections use cylinders, and sagas use hexagons.                                                                                                                                                  | Unlabeled edges are ambiguous -- a reader seeing a solid arrow cannot distinguish "uses" from "implements" without consulting an edge style legend. Custom node shapes leverage Mermaid's shape vocabulary to make archRole visually distinguishable without color reliance, improving accessibility.                                                                                                                                                                                              |
 | Extraction pipeline surfaces complete API documentation                      | ExportInfo.signature shows full function parameter types and return type instead of the placeholder value. JSDoc param, returns, and throws tags are extracted and stored on ExtractedShape. Property-level JSDoc preserves full multi-line content without first-line truncation. Auto-shape discovery mode extracts all exported types from files matching source-selector globs globs without requiring explicit extract-shapes annotations.                                                                                                        | Function signatures are the most valuable API surface -- they show what a pattern exports without source navigation. The ExportInfo.signature field already exists in the schema but holds a lossy placeholder. The fix is approximately 15 lines in ast-parser.ts: threading sourceCode into extractFromDeclaration and slicing parameter ranges. Auto-shape discovery eliminates manual annotation burden for files that match source-selector globs.                                            |
 | Infrastructure enables flexible document composition and AI-optimized output | CompositeCodec assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. The modular claude-md renderer produces token-efficient output using section markers optimized for LLM consumption. The Gherkin tag extractor uses TagRegistry metadata instead of hardcoded if/else branches, making new tag addition a zero-code-change operation. Convention content can be extracted from TypeScript JSDoc blocks containing structured Invariant/Rationale annotations, not only from Gherkin Rule blocks. | CompositeCodec enables referenceDocConfigs to include content from any codec, not just the current 4 sources. The modular claude-md renderer unifies two formatting paths (codec-based markdown vs hand-written markers in context-formatter.ts). Data-driven tag extraction cuts the maintenance burden of the 40-branch if/else in gherkin-ast-parser.ts roughly in half. TypeScript convention extraction enables self-documenting business rules in implementation files alongside their code. |
@@ -999,10 +1014,10 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Requirements Adr Codec Testing
 
-| Rule                                                                      | Invariant                                                                                                                                                                                                                 | Rationale                                                                                                                                                                                    |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| RequirementsDocumentCodec generates PRD-style documentation from patterns | RequirementsDocumentCodec transforms MasterDataset patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering.          | Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. |
-| AdrDocumentCodec documents architecture decisions                         | AdrDocumentCodec transforms MasterDataset ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. | Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned.     |
+| Rule                                                                      | Invariant                                                                                                                                                                                                                | Rationale                                                                                                                                                                                    |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RequirementsDocumentCodec generates PRD-style documentation from patterns | RequirementsDocumentCodec transforms PatternGraph patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering.          | Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. |
+| AdrDocumentCodec documents architecture decisions                         | AdrDocumentCodec transforms PatternGraph ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. | Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned.     |
 
 ### Rich Content Helpers Testing
 
@@ -1048,17 +1063,17 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Session Guides Module Source
 
-| Rule                                                             | Invariant                                                                                                                                                                                                                                                                                                                             | Rationale                                                                                                                                                                                                                                                                                                                          |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SESSION-GUIDES.md is the authoritative public human reference    | `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or replaced with a redirect. Its comprehensive checklists, CLI command examples, and session decision trees serve developers on libar.dev.                                                                                                                             | Session workflow guidance requires two formats for two audiences. Public developers need comprehensive checklists with full examples. AI sessions need compact invariants they can apply without reading 389 lines.                                                                                                                |
-| CLAUDE.md session workflow content is derived, not hand-authored | After Phase 39 generation deliverables complete, the "Session Workflows" section in CLAUDE.md contains no manually-authored content. It is composed from generated `_claude-md/workflow/` modules.                                                                                                                                    | A hand-maintained CLAUDE.md session section creates two copies of session workflow guidance with no synchronization mechanism. Regeneration from annotated source eliminates drift.                                                                                                                                                |
-| Session type determines artifacts and FSM changes                | Four session types exist, each with defined input, output, and FSM impact. Mixing outputs across session types (e.g., writing code in a planning session) violates session discipline.                                                                                                                                                | Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types.                                                                                                                                                |
-| Planning sessions produce roadmap specs only                     | A planning session creates a roadmap spec with metadata, deliverables table, Rule: blocks with invariants, and scenarios. It must not produce implementation code, transition to active, or prompt for implementation readiness.                                                                                                      | Planning is the cheapest session type — it produces .feature file edits, no compilation needed. Mixing implementation into planning defeats the cost advantage and introduces untested code without a locked scope.                                                                                                                |
-| Design sessions produce decisions and stubs only                 | A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage.                                                                                                                      | Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts.                                                                                                                               |
-| Implementation sessions follow FSM-enforced execution order      | Implementation sessions must follow a strict 5-step execution order. Transition to active must happen before any code changes. Transition to completed must happen only when ALL deliverables are done. Skipping steps causes Process Guard rejection at commit time.                                                                 | The execution order ensures FSM state accurately reflects work state at every point. Writing code before transitioning to active means Process Guard sees changes to a roadmap spec (no scope protection). Marking completed with incomplete work creates a hard-locked state that requires unlock-reason to fix.                  |
-| FSM errors have documented fixes                                 | Every Process Guard error code has a defined cause and fix. The error codes, causes, and fixes form a closed set — no undocumented error states exist.                                                                                                                                                                                | Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity.                                                                                                                                                       |
-| Handoff captures session-end state for continuity                | Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes.                                                                                                                                                                      | Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes.                                                                                                                                          |
-| ClaudeModuleGeneration is the generation mechanism               | Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. | The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. |
+| Rule                                                             | Invariant                                                                                                                                                                                                                                                                                                                             | Rationale                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SESSION-GUIDES.md is the authoritative public human reference    | `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or replaced with a redirect. Its comprehensive checklists, CLI command examples, and session decision trees serve developers on libar.dev.                                                                                                                             | Session workflow guidance requires two formats for two audiences. Public developers need comprehensive checklists with full examples. AI sessions need compact invariants they can apply without reading 389 lines.                                                                                                                  |
+| CLAUDE.md session workflow content is derived, not hand-authored | After Phase 39 generation deliverables complete, the "Session Workflows" section in CLAUDE.md contains no manually-authored content. It is composed from generated `_claude-md/workflow/` modules.                                                                                                                                    | A hand-maintained CLAUDE.md session section creates two copies of session workflow guidance with no synchronization mechanism. Regeneration from annotated source eliminates drift.                                                                                                                                                  |
+| Session type determines artifacts and FSM changes                | Four session types exist, each with defined input, output, and FSM impact. Mixing outputs across session types (e.g., writing code in a planning session) violates session discipline.                                                                                                                                                | Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types.                                                                                                                                                  |
+| Planning sessions produce roadmap specs only                     | A planning session creates a roadmap spec with metadata, deliverables table, Rule: blocks with invariants, and scenarios. It must not produce implementation code, transition to active, or prompt for implementation readiness.                                                                                                      | Planning is the cheapest session type — it produces .feature file edits, no compilation needed. Mixing implementation into planning defeats the cost advantage and introduces untested code without a locked scope.                                                                                                                  |
+| Design sessions produce decisions and stubs only                 | A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage.                                                                                                                      | Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts.                                                                                                                                 |
+| Implementation sessions follow FSM-enforced execution order      | Implementation sessions must follow a strict 5-step execution order. Transition to active must happen before any code changes. Transition to completed must happen only when ALL deliverables are done. Skipping steps causes Process Guard rejection at commit time.                                                                 | The execution order ensures FSM state accurately reflects work state at every point. Writing code before transitioning to active means Process Guard sees changes to a roadmap spec (no scope protection). Marking completed with incomplete work creates a hard-locked state that requires unlock-reason to fix.                    |
+| FSM errors have documented fixes                                 | Every Process Guard error code has a defined cause and fix. The error codes, causes, and fixes form a closed set — no undocumented error states exist.                                                                                                                                                                                | Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity.                                                                                                                                                         |
+| Handoff captures session-end state for continuity                | Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes.                                                                                                                                                                      | Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes.                                                                                                                                            |
+| ClaudeModuleGeneration is the generation mechanism               | Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. | The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. |
 
 ### Shape Matcher Testing
 
@@ -1133,23 +1148,23 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset;
 
 ### Traceability Generator
 
-| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                      | Rationale                                                                                                                                                                                                                                                                                                                                                             |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Cross-references Verified by annotations against actual scenarios | Every `verifiedBy` string extracted from a Rule description is matched against scenario names in the MasterDataset. The traceability matrix shows each Rule with its verification status: verified (all references resolve), partially verified (some resolve), or unverified (none resolve or no annotation). | `parseBusinessRuleAnnotations()` already extracts `verifiedBy` arrays from Rule descriptions. Without cross-referencing against actual scenario names, the traceability report cannot distinguish between claimed and actual test coverage. A dangling reference (scenario name that does not exist) is worse than no annotation because it creates false confidence. |
-| Detects orphan scenarios and unverified rules                     | Orphan scenarios (acceptance-criteria scenarios not referenced by any Rule's Verified by annotation) and unverified rules (Rules without a Verified by annotation or with zero matched scenarios) are listed in dedicated sections of the traceability output.                                                 | Coverage gaps indicate either missing traceability annotations or actual missing test coverage. Orphan scenarios may be valuable tests that lack traceability links, or dead tests that should be removed. Unverified rules are business constraints with no demonstrated test coverage.                                                                              |
-| Traceability output is wired into the docs pipeline               | The TraceabilityCodec output is generated as part of `pnpm docs:all` via a `docs:traceability` npm script backed by a ReferenceDocConfig entry in `architect.config.ts`. The output file lands in `docs-live/TRACEABILITY.md`.                                                                                 | The TraceabilityCodec is registered in the CodecRegistry but not wired into `architect.config.ts` or `package.json`. Without config wiring, the codec is only usable programmatically or via tests. Adding it to the docs pipeline makes traceability output a first-class generated artifact alongside CHANGELOG.md, OVERVIEW.md, and other reporting codecs.        |
+| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                     | Rationale                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cross-references Verified by annotations against actual scenarios | Every `verifiedBy` string extracted from a Rule description is matched against scenario names in the PatternGraph. The traceability matrix shows each Rule with its verification status: verified (all references resolve), partially verified (some resolve), or unverified (none resolve or no annotation). | `parseBusinessRuleAnnotations()` already extracts `verifiedBy` arrays from Rule descriptions. Without cross-referencing against actual scenario names, the traceability report cannot distinguish between claimed and actual test coverage. A dangling reference (scenario name that does not exist) is worse than no annotation because it creates false confidence. |
+| Detects orphan scenarios and unverified rules                     | Orphan scenarios (acceptance-criteria scenarios not referenced by any Rule's Verified by annotation) and unverified rules (Rules without a Verified by annotation or with zero matched scenarios) are listed in dedicated sections of the traceability output.                                                | Coverage gaps indicate either missing traceability annotations or actual missing test coverage. Orphan scenarios may be valuable tests that lack traceability links, or dead tests that should be removed. Unverified rules are business constraints with no demonstrated test coverage.                                                                              |
+| Traceability output is wired into the docs pipeline               | The TraceabilityCodec output is generated as part of `pnpm docs:all` via a `docs:traceability` npm script backed by a ReferenceDocConfig entry in `architect.config.ts`. The output file lands in `docs-live/TRACEABILITY.md`.                                                                                | The TraceabilityCodec is registered in the CodecRegistry but not wired into `architect.config.ts` or `package.json`. Without config wiring, the codec is only usable programmatically or via tests. Adding it to the docs pipeline makes traceability output a first-class generated artifact alongside CHANGELOG.md, OVERVIEW.md, and other reporting codecs.        |
 
 ### Transform Dataset Testing
 
 | Rule                                                              | Invariant                                                                                                                                     | Rationale                                                                                                                                                                                     |
 | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Empty dataset produces valid zero-state views                     | An empty input produces a MasterDataset with all counts at zero and no groupings.                                                             | Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs.                                         |
+| Empty dataset produces valid zero-state views                     | An empty input produces a PatternGraph with all counts at zero and no groupings.                                                              | Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs.                                         |
 | Status and phase grouping creates navigable views                 | Patterns are grouped by canonical status and sorted by phase number, with per-phase status counts computed.                                   | Generators need O(1) access to status-filtered and phase-ordered views without recomputing on each render pass.                                                                               |
 | Quarter and category grouping organizes by timeline and domain    | Patterns are grouped by quarter and category, with only patterns bearing the relevant metadata included in each view.                         | Timeline and domain views must exclude patterns without the relevant metadata to prevent misleading counts and empty groupings in generated documentation.                                    |
 | Source grouping separates TypeScript and Gherkin origins          | Patterns are partitioned by source file type, and patterns with phase metadata appear in the roadmap view.                                    | Codecs that render TypeScript-specific or Gherkin-specific views depend on pre-partitioned sources; mixing sources would produce incorrect per-origin statistics and broken cross-references. |
 | Relationship index builds bidirectional dependency graph          | The relationship index contains forward and reverse lookups, with reverse lookups merged and deduplicated against explicit annotations.       | Bidirectional navigation is required for dependency tree queries without O(n) scans per lookup.                                                                                               |
 | Completion tracking computes project progress                     | Completion percentage is rounded to the nearest integer, and fully-completed requires all patterns in completed status with a non-zero total. | Inconsistent rounding or a false-positive fully-completed signal on an empty dataset would misrepresent project health in dashboards and generated progress reports.                          |
-| Workflow integration conditionally includes delivery process data | The workflow is included in the MasterDataset only when provided, and phase names are resolved from the workflow configuration.               | Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation.                              |
+| Workflow integration conditionally includes delivery process data | The workflow is included in the PatternGraph only when provided, and phase names are resolved from the workflow configuration.                | Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation.                              |
 
 ### Universal Doc Generator Robustness