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

package/docs-live/product-areas/DATA-API.md

@@ -29,7 +29,7 @@
 
 ## Shared Pipeline Factory Responsibilities
 
-**Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result<PipelineResult, PipelineError>` without process-level side effects.
+**Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result<PipelineResult, PipelineError>` without process-level side effects.
 
 **Rationale:** Centralizing scan/extract/merge/transform flow prevents divergence between CLI consumers and preserves a single ADR-006 read-model path.
 
@@ -39,20 +39,20 @@
 
 The factory owns: configuration load, TypeScript scan + extraction, Gherkin scan +
 extraction, merge conflict handling, hierarchy child derivation, workflow load,
-and `transformToMasterDataset` with validation summary.
+and `transformToPatternGraph` with validation summary.
 
 ---
 
 ## Consumer Architecture and PipelineOptions Differentiation
 
-Three consumers share this factory: `process-api`, `validate-patterns`, and the
+Three consumers share this factory: `pattern-graph-cli`, `validate-patterns`, and the
 generation orchestrator. `PipelineOptions` differentiates behavior by
 `mergeConflictStrategy` (`fatal` vs `concatenate`), `includeValidation` toggles,
 and `failOnScanErrors` policy without forking pipeline logic.
 
 ### When to Use
 
-- Any consumer needs a MasterDataset without rewriting scan/extract/merge flow
+- Any consumer needs a PatternGraph without rewriting scan/extract/merge flow
 - CLI consumers require differentiated conflict strategy and validation behavior
 - Orchestrator needs a shared steps 1-8 implementation before codec/file execution
 
@@ -65,7 +65,7 @@ Scoped architecture diagram showing component relationships:
 ```mermaid
 graph TB
     subgraph api["Api"]
-        MasterDataset[/"MasterDataset"/]
+        PatternGraph[/"PatternGraph"/]
         MCPToolRegistry("MCPToolRegistry")
         MCPServerImpl("MCPServerImpl")
         MCPPipelineSession("MCPPipelineSession")
@@ -73,8 +73,8 @@ graph TB
         MCPFileWatcher[/"MCPFileWatcher"/]
         PatternSummarizerImpl("PatternSummarizerImpl")
         ScopeValidatorImpl("ScopeValidatorImpl")
-        ProcessStateAPI("ProcessStateAPI")
         PatternHelpers["PatternHelpers"]
+        PatternGraphAPI("PatternGraphAPI")
         HandoffGeneratorImpl("HandoffGeneratorImpl")
         FuzzyMatcherImpl("FuzzyMatcherImpl")
         CoverageAnalyzerImpl("CoverageAnalyzerImpl")
@@ -84,7 +84,7 @@ graph TB
     end
     subgraph cli["Cli"]
         ReplMode("ReplMode")
-        ProcessAPICLIImpl("ProcessAPICLIImpl")
+        PatternGraphCLIImpl("PatternGraphCLIImpl")
         OutputPipelineImpl("OutputPipelineImpl")
         MCPServerBin[/"MCPServerBin"/]
         DatasetCache[/"DatasetCache"/]
@@ -98,17 +98,17 @@ graph TB
         RulesQueryModule["RulesQueryModule"]:::neighbor
         FSMValidator["FSMValidator"]:::neighbor
         PipelineFactory["PipelineFactory"]:::neighbor
-        ProcessStateAPICLI["ProcessStateAPICLI"]:::neighbor
-        ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor
         PhaseStateMachineValidation["PhaseStateMachineValidation"]:::neighbor
+        PatternGraphAPICLI["PatternGraphAPICLI"]:::neighbor
         MCPServerIntegration["MCPServerIntegration"]:::neighbor
         DataAPIDesignSessionSupport["DataAPIDesignSessionSupport"]:::neighbor
         DataAPIOutputShaping["DataAPIOutputShaping"]:::neighbor
         DataAPIContextAssembly["DataAPIContextAssembly"]:::neighbor
         DataAPICLIErgonomics["DataAPICLIErgonomics"]:::neighbor
         DataAPIArchitectureQueries["DataAPIArchitectureQueries"]:::neighbor
+        CliReferenceGeneration["CliReferenceGeneration"]:::neighbor
     end
-    MCPToolRegistry -->|uses| ProcessStateAPI
+    MCPToolRegistry -->|uses| PatternGraphAPI
     MCPToolRegistry -->|uses| MCPPipelineSession
     MCPToolRegistry ..->|implements| MCPServerIntegration
     MCPServerImpl -->|uses| MCPPipelineSession
@@ -116,7 +116,7 @@ graph TB
     MCPServerImpl -->|uses| MCPFileWatcher
     MCPServerImpl ..->|implements| MCPServerIntegration
     MCPPipelineSession -->|uses| PipelineFactory
-    MCPPipelineSession -->|uses| ProcessStateAPI
+    MCPPipelineSession -->|uses| PatternGraphAPI
     MCPPipelineSession -->|uses| ConfigLoader
     MCPPipelineSession ..->|implements| MCPServerIntegration
     MCPModule -->|uses| MCPServerImpl
@@ -125,16 +125,16 @@ graph TB
     MCPModule -->|uses| MCPToolRegistry
     MCPFileWatcher ..->|implements| MCPServerIntegration
     ReplMode -->|uses| PipelineFactory
-    ReplMode -->|uses| ProcessStateAPI
+    ReplMode -->|uses| PatternGraphAPI
     ReplMode ..->|implements| DataAPICLIErgonomics
-    ProcessAPICLIImpl -->|uses| ProcessStateAPI
-    ProcessAPICLIImpl -->|uses| MasterDataset
-    ProcessAPICLIImpl -->|uses| PipelineFactory
-    ProcessAPICLIImpl -->|uses| RulesQueryModule
-    ProcessAPICLIImpl -->|uses| PatternSummarizerImpl
-    ProcessAPICLIImpl -->|uses| FuzzyMatcherImpl
-    ProcessAPICLIImpl -->|uses| OutputPipelineImpl
-    ProcessAPICLIImpl ..->|implements| ProcessStateAPICLI
+    PatternGraphCLIImpl -->|uses| PatternGraphAPI
+    PatternGraphCLIImpl -->|uses| PatternGraph
+    PatternGraphCLIImpl -->|uses| PipelineFactory
+    PatternGraphCLIImpl -->|uses| RulesQueryModule
+    PatternGraphCLIImpl -->|uses| PatternSummarizerImpl
+    PatternGraphCLIImpl -->|uses| FuzzyMatcherImpl
+    PatternGraphCLIImpl -->|uses| OutputPipelineImpl
+    PatternGraphCLIImpl ..->|implements| PatternGraphAPICLI
     OutputPipelineImpl -->|uses| PatternSummarizerImpl
     OutputPipelineImpl ..->|implements| DataAPIOutputShaping
     MCPServerBin -->|uses| MCPServerImpl
@@ -142,39 +142,39 @@ graph TB
     DatasetCache -->|uses| PipelineFactory
     DatasetCache -->|uses| WorkflowConfigSchema
     DatasetCache ..->|implements| DataAPICLIErgonomics
-    CLISchema ..->|implements| ProcessApiHybridGeneration
-    PatternSummarizerImpl -->|uses| ProcessStateAPI
+    CLISchema ..->|implements| CliReferenceGeneration
+    PatternSummarizerImpl -->|uses| PatternGraphAPI
     PatternSummarizerImpl ..->|implements| DataAPIOutputShaping
-    ScopeValidatorImpl -->|uses| ProcessStateAPI
-    ScopeValidatorImpl -->|uses| MasterDataset
+    ScopeValidatorImpl -->|uses| PatternGraphAPI
+    ScopeValidatorImpl -->|uses| PatternGraph
     ScopeValidatorImpl -->|uses| StubResolverImpl
     ScopeValidatorImpl ..->|implements| DataAPIDesignSessionSupport
-    ProcessStateAPI -->|uses| MasterDataset
-    ProcessStateAPI -->|uses| FSMValidator
-    ProcessStateAPI ..->|implements| PhaseStateMachineValidation
     PatternHelpers ..->|implements| DataAPIOutputShaping
-    HandoffGeneratorImpl -->|uses| ProcessStateAPI
-    HandoffGeneratorImpl -->|uses| MasterDataset
+    PatternGraphAPI -->|uses| PatternGraph
+    PatternGraphAPI -->|uses| FSMValidator
+    PatternGraphAPI ..->|implements| PhaseStateMachineValidation
+    HandoffGeneratorImpl -->|uses| PatternGraphAPI
+    HandoffGeneratorImpl -->|uses| PatternGraph
     HandoffGeneratorImpl -->|uses| ContextFormatterImpl
     HandoffGeneratorImpl ..->|implements| DataAPIDesignSessionSupport
     FuzzyMatcherImpl ..->|implements| DataAPIOutputShaping
     CoverageAnalyzerImpl -->|uses| Pattern_Scanner
-    CoverageAnalyzerImpl -->|uses| MasterDataset
+    CoverageAnalyzerImpl -->|uses| PatternGraph
     CoverageAnalyzerImpl ..->|implements| DataAPIArchitectureQueries
     ContextFormatterImpl -->|uses| ContextAssemblerImpl
     ContextFormatterImpl ..->|implements| DataAPIContextAssembly
-    ContextAssemblerImpl -->|uses| ProcessStateAPI
-    ContextAssemblerImpl -->|uses| MasterDataset
+    ContextAssemblerImpl -->|uses| PatternGraphAPI
+    ContextAssemblerImpl -->|uses| PatternGraph
     ContextAssemblerImpl -->|uses| PatternSummarizerImpl
     ContextAssemblerImpl -->|uses| FuzzyMatcherImpl
     ContextAssemblerImpl -->|uses| StubResolverImpl
     ContextAssemblerImpl ..->|implements| DataAPIContextAssembly
-    ArchQueriesImpl -->|uses| ProcessStateAPI
-    ArchQueriesImpl -->|uses| MasterDataset
+    ArchQueriesImpl -->|uses| PatternGraphAPI
+    ArchQueriesImpl -->|uses| PatternGraph
     ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries
-    StubResolverImpl -->|uses| ProcessStateAPI
+    StubResolverImpl -->|uses| PatternGraphAPI
     FSMValidator ..->|implements| PhaseStateMachineValidation
-    PipelineFactory -->|uses| MasterDataset
+    PipelineFactory -->|uses| PatternGraph
     MCPServerIntegration -.->|depends on| DataAPICLIErgonomics
     DataAPIDesignSessionSupport -.->|depends on| DataAPIContextAssembly
     DataAPIContextAssembly -.->|depends on| DataAPIOutputShaping
@@ -190,7 +190,7 @@ graph TB
 
 ```typescript
 /**
- * Options for building a MasterDataset via the shared pipeline.
+ * Options for building a PatternGraph via the shared pipeline.
  *
  * DD-1: Factory lives at src/generators/pipeline/build-pipeline.ts.
  * DD-2: mergeConflictStrategy controls per-consumer conflict handling.
@@ -213,13 +213,16 @@ interface PipelineOptions {
   readonly includeValidation?: boolean;
   /** DD-5: When true, return error on individual scan failures (default false). */
   readonly failOnScanErrors?: boolean;
+  /** Pre-loaded tag registry. When provided, skips internal config load (Step 1). */
+  readonly tagRegistry?: TagRegistry;
 }
 ```
 
-| Property          | Description                                                                |
-| ----------------- | -------------------------------------------------------------------------- |
-| includeValidation | DD-3: When false, skip validation pass (default true).                     |
-| failOnScanErrors  | DD-5: When true, return error on individual scan failures (default false). |
+| Property          | Description                                                                  |
+| ----------------- | ---------------------------------------------------------------------------- |
+| includeValidation | DD-3: When false, skip validation pass (default true).                       |
+| failOnScanErrors  | DD-5: When true, return error on individual scan failures (default false).   |
+| tagRegistry       | Pre-loaded tag registry. When provided, skips internal config load (Step 1). |
 
 ### PipelineResult (interface)
 
@@ -232,18 +235,18 @@ interface PipelineOptions {
 
 ```typescript
 interface PipelineResult {
-  readonly dataset: RuntimeMasterDataset;
+  readonly dataset: RuntimePatternGraph;
   readonly validation: ValidationSummary;
   readonly warnings: readonly PipelineWarning[];
   readonly scanMetadata: ScanMetadata;
 }
 ```
 
-### MasterDatasetSchema (const)
+### PatternGraphSchema (const)
 
 ```typescript
 /**
- * Master Dataset - Unified view of all extracted patterns
+ * PatternGraph - Unified view of all extracted patterns
  *
  * Contains raw patterns plus pre-computed views and statistics.
  * This is the primary data structure passed to generators and sections.
@@ -252,7 +255,7 @@ interface PipelineResult {
 ```
 
 ```typescript
-MasterDatasetSchema = z.object({
+PatternGraphSchema = z.object({
   // ─────────────────────────────────────────────────────────────────────────
   // Raw Data
   // ─────────────────────────────────────────────────────────────────────────
@@ -284,7 +287,7 @@ MasterDatasetSchema = z.object({
   byCategory: z.record(z.string(), z.array(ExtractedPatternSchema)),
 
   /** Patterns grouped by source type */
-  bySource: SourceViewsSchema,
+  bySourceType: SourceViewsSchema,
 
   /** Patterns grouped by product area (for O(1) product area lookups) */
   byProductArea: z.record(z.string(), z.array(ExtractedPatternSchema)),
@@ -509,7 +512,7 @@ ArchIndexSchema = z.object({
 
 ## Business Rules
 
-38 patterns, 146 rules with invariants (146 total)
+38 patterns, 147 rules with invariants (147 total)
 
 ### Arch Queries Test
 
@@ -547,17 +550,17 @@ ArchIndexSchema = z.object({
 
 ### Data API CLI Ergonomics
 
-| Rule                                                                      | Invariant                                                                                                                                | Rationale                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| MasterDataset is cached between invocations with file-change invalidation | Cache is automatically invalidated when any source file (TypeScript or Gherkin) has a modification time newer than the cache.            | The pipeline (scan -> extract -> transform) runs fresh on every invocation (~2-5 seconds). Most queries during a session don't need fresh data -- the source files haven't changed between queries. Caching the MasterDataset to a temp file with file-modification-time invalidation makes subsequent queries instant while ensuring staleness is impossible. |
-| REPL mode keeps pipeline loaded for interactive multi-query sessions      | REPL mode loads the pipeline once and accepts multiple queries on stdin, with optional tab completion for pattern names and subcommands. | Design sessions often involve 10-20 exploratory queries in sequence (check status, look up pattern, check deps, look up another pattern). REPL mode eliminates per-query pipeline overhead entirely.                                                                                                                                                           |
-| Per-subcommand help and diagnostic modes aid discoverability              | Every subcommand supports `--help` with usage, flags, and examples. Dry-run shows pipeline scope without executing.                      | AI agents read `--help` output to discover available commands and flags. Without per-subcommand help, agents must read external documentation. Dry-run mode helps diagnose "why no patterns found?" issues by showing what would be scanned.                                                                                                                   |
+| Rule                                                                     | Invariant                                                                                                                                | Rationale                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PatternGraph is cached between invocations with file-change invalidation | Cache is automatically invalidated when any source file (TypeScript or Gherkin) has a modification time newer than the cache.            | The pipeline (scan -> extract -> transform) runs fresh on every invocation (~2-5 seconds). Most queries during a session don't need fresh data -- the source files haven't changed between queries. Caching the PatternGraph to a temp file with file-modification-time invalidation makes subsequent queries instant while ensuring staleness is impossible. |
+| REPL mode keeps pipeline loaded for interactive multi-query sessions     | REPL mode loads the pipeline once and accepts multiple queries on stdin, with optional tab completion for pattern names and subcommands. | Design sessions often involve 10-20 exploratory queries in sequence (check status, look up pattern, check deps, look up another pattern). REPL mode eliminates per-query pipeline overhead entirely.                                                                                                                                                          |
+| Per-subcommand help and diagnostic modes aid discoverability             | Every subcommand supports `--help` with usage, flags, and examples. Dry-run shows pipeline scope without executing.                      | AI agents read `--help` output to discover available commands and flags. Without per-subcommand help, agents must read external documentation. Dry-run mode helps diagnose "why no patterns found?" issues by showing what would be scanned.                                                                                                                  |
 
 ### Data API Context Assembly
 
 | Rule                                                           | Invariant                                                                                                                                                                                           | Rationale                                                                                                                                                                                                                                                                                                  |
 | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Context command assembles curated context for a single pattern | Given a pattern name, `context` returns everything needed to start working on that pattern: metadata, file locations, dependency status, and architecture position -- in ~1.5KB of structured text. | This is the core value proposition. The command crosses five gaps simultaneously: it assembles data from multiple MasterDataset indexes, shapes it compactly, resolves file paths from pattern names, discovers stubs by convention, and tailors output by session type.                                   |
+| Context command assembles curated context for a single pattern | Given a pattern name, `context` returns everything needed to start working on that pattern: metadata, file locations, dependency status, and architecture position -- in ~1.5KB of structured text. | This is the core value proposition. The command crosses five gaps simultaneously: it assembles data from multiple PatternGraph indexes, shapes it compactly, resolves file paths from pattern names, discovers stubs by convention, and tailors output by session type.                                    |
 | Files command returns only file paths organized by relevance   | `files` returns the most token-efficient output possible -- just file paths that Claude Code can read directly.                                                                                     | Most context tokens are spent reading actual files, not metadata. The `files` command tells Claude Code _which_ files to read, organized by importance. Claude Code then reads what it needs. This is more efficient than `context` when the agent already knows the pattern and just needs the file list. |
 | Dep-tree command shows recursive dependency chain with status  | The dependency tree walks both `dependsOn`/`enables` (planning) and `uses`/`usedBy` (implementation) relationships with configurable depth.                                                         | Before starting work on a pattern, agents need to know the full dependency chain: what must be complete first, what this unblocks, and where the current pattern sits in the sequence. A tree visualization with status markers makes blocking relationships immediately visible.                          |
 | Context command supports multiple patterns with merged output  | Multi-pattern context deduplicates shared dependencies and highlights overlap between patterns.                                                                                                     | Design sessions often span multiple related patterns (e.g., reviewing DS-2 through DS-5 together). Separate `context` calls would duplicate shared dependencies. Merged context shows the union of all dependencies with overlap analysis.                                                                 |
@@ -584,19 +587,19 @@ ArchIndexSchema = z.object({
 
 | Rule                                                              | Invariant                                                                                                                                                                          | Rationale                                                                                                                                                                                                                                                                                                      |
 | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ProcessStateAPI is accessible as an MCP server for Claude Code    | The MCP server exposes all ProcessStateAPI methods as MCP tools with typed input/output schemas. The pipeline is loaded once on server start and refreshed on source file changes. | MCP is Claude Code's native tool integration protocol. An MCP server eliminates the CLI subprocess overhead (2-5s per query) and enables Claude Code to call process queries as naturally as it calls other tools. Stateful operation means the pipeline loads once and serves many queries.                   |
+| PatternGraphAPI is accessible as an MCP server for Claude Code    | The MCP server exposes all PatternGraphAPI methods as MCP tools with typed input/output schemas. The pipeline is loaded once on server start and refreshed on source file changes. | MCP is Claude Code's native tool integration protocol. An MCP server eliminates the CLI subprocess overhead (2-5s per query) and enables Claude Code to call process queries as naturally as it calls other tools. Stateful operation means the pipeline loads once and serves many queries.                   |
 | Process state can be auto-generated as CLAUDE.md context sections | Generated CLAUDE.md sections are additive layers that provide pattern metadata, relationships, and reading lists for specific scopes.                                              | CLAUDE.md is the primary mechanism for providing persistent context to Claude Code sessions. Auto-generating CLAUDE.md sections from process state ensures the context is always fresh and consistent with the source annotations. This applies the "code-first documentation" principle to AI context itself. |
 | Cross-package views show dependencies spanning multiple packages  | Cross-package queries aggregate patterns from multiple input sources and resolve cross-package relationships.                                                                      | In the monorepo, patterns in `platform-core` are used by patterns in `platform-bc`, which are used by the example app. Understanding these cross-package dependencies is essential for release planning and impact analysis. Currently each package must be queried independently with separate input globs.   |
 | Process validation integrates with git hooks and file watching    | Pre-commit hooks validate annotation consistency. Watch mode re-generates docs on source changes.                                                                                  | Git hooks catch annotation errors at commit time (e.g., new `uses` reference to non-existent pattern, invalid `arch-role` value, stub `@target` to non-existent directory). Watch mode enables live documentation regeneration during implementation sessions.                                                 |
 
 ### Data API Relationship Graph
 
-| Rule                                                                      | Invariant                                                                                                                                                                                     | Rationale                                                                                                                                                                                                                                                           |
-| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Graph command traverses relationships recursively with configurable depth | Graph traversal walks both planning relationships (`dependsOn`, `enables`) and implementation relationships (`uses`, `usedBy`) with cycle detection to prevent infinite loops.                | Flat lookups show direct connections. Recursive traversal shows the full picture: transitive dependencies, indirect consumers, and the complete chain from root to leaf. Depth limiting prevents overwhelming output on deeply connected graphs.                    |
-| Impact analysis shows transitive dependents of a pattern                  | Impact analysis answers "if I change X, what else is affected?" by walking `usedBy` + `enables` recursively.                                                                                  | Before modifying a completed pattern (which requires unlock), understanding the blast radius prevents unintended breakage. Impact analysis is the reverse of dependency traversal -- it looks forward, not backward.                                                |
-| Path finding discovers relationship chains between two patterns           | Path finding returns the shortest chain of relationships connecting two patterns, or indicates no path exists. Traversal considers all relationship types (uses, usedBy, dependsOn, enables). | Understanding how two seemingly unrelated patterns connect helps agents assess indirect dependencies before making changes. When pattern A and pattern D are connected through B and C, modifying A requires understanding that chain.                              |
-| Graph health commands detect broken references and isolated patterns      | Dangling references (pattern names in `uses`/`dependsOn` that don't match any pattern definition) are detectable. Orphan patterns (no relationships at all) are identifiable.                 | The MasterDataset transformer already computes dangling references during Pass 3 (relationship resolution) but does not expose them via the API. Orphan patterns indicate missing annotations. Both are data quality signals that improve over time with attention. |
+| Rule                                                                      | Invariant                                                                                                                                                                                     | Rationale                                                                                                                                                                                                                                                          |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Graph command traverses relationships recursively with configurable depth | Graph traversal walks both planning relationships (`dependsOn`, `enables`) and implementation relationships (`uses`, `usedBy`) with cycle detection to prevent infinite loops.                | Flat lookups show direct connections. Recursive traversal shows the full picture: transitive dependencies, indirect consumers, and the complete chain from root to leaf. Depth limiting prevents overwhelming output on deeply connected graphs.                   |
+| Impact analysis shows transitive dependents of a pattern                  | Impact analysis answers "if I change X, what else is affected?" by walking `usedBy` + `enables` recursively.                                                                                  | Before modifying a completed pattern (which requires unlock), understanding the blast radius prevents unintended breakage. Impact analysis is the reverse of dependency traversal -- it looks forward, not backward.                                               |
+| Path finding discovers relationship chains between two patterns           | Path finding returns the shortest chain of relationships connecting two patterns, or indicates no path exists. Traversal considers all relationship types (uses, usedBy, dependsOn, enables). | Understanding how two seemingly unrelated patterns connect helps agents assess indirect dependencies before making changes. When pattern A and pattern D are connected through B and C, modifying A requires understanding that chain.                             |
+| Graph health commands detect broken references and isolated patterns      | Dangling references (pattern names in `uses`/`dependsOn` that don't match any pattern definition) are detectable. Orphan patterns (no relationships at all) are identifiable.                 | The PatternGraph transformer already computes dangling references during Pass 3 (relationship resolution) but does not expose them via the API. Orphan patterns indicate missing annotations. Both are data quality signals that improve over time with attention. |
 
 ### Data API Stub Integration
 
@@ -644,25 +647,26 @@ ArchIndexSchema = z.object({
 
 ### Lint Process Cli
 
-| Rule                                       | Invariant                                                                                                                                            | Rationale                                                                                                                                                                 |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CLI displays help and version information  | The --help/-h and --version/-v flags must produce usage/version output and exit successfully without requiring other arguments.                      | Help and version are universal CLI conventions — both short and long flag forms must work for discoverability and scripting compatibility.                                |
-| CLI requires git repository for validation | The lint-process CLI must fail with a clear error when run outside a git repository in both staged and all modes.                                    | Process guard validation depends on git diff for change detection — running without git produces undefined behavior rather than useful validation results.                |
-| CLI validates file mode input              | In file mode, the CLI must require at least one file path via positional argument or --file flag, and fail with a clear error when none is provided. | File mode is for targeted validation of specific files — accepting zero files would silently produce a "no violations" result that falsely implies the files are valid.   |
-| CLI handles no changes gracefully          | When no relevant changes are detected (empty diff), the CLI must exit successfully with a zero exit code.                                            | No changes means no violations are possible — failing on empty diffs would break CI pipelines on commits that only modify non-spec files.                                 |
-| CLI supports multiple output formats       | The CLI must support JSON and pretty (human-readable) output formats, with pretty as the default.                                                    | Pretty format serves interactive pre-commit use while JSON format enables CI/CD pipeline integration and automated violation processing.                                  |
-| CLI supports debug options                 | The --show-state flag must display the derived process state (FSM states, protection levels, deliverables) without affecting validation behavior.    | Process guard decisions are derived from complex state — exposing the intermediate state helps developers understand why a specific validation passed or failed.          |
-| CLI warns about unknown flags              | Unrecognized CLI flags must produce a warning message but allow execution to continue.                                                               | Process validation is critical-path at commit time — hard-failing on a typo in an optional flag would block commits unnecessarily when the core validation would succeed. |
+| Rule                                       | Invariant                                                                                                                                                                                                 | Rationale                                                                                                                                                                                       |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI displays help and version information  | The --help/-h and --version/-v flags must produce usage/version output and exit successfully without requiring other arguments.                                                                           | Help and version are universal CLI conventions — both short and long flag forms must work for discoverability and scripting compatibility.                                                      |
+| CLI requires git repository for validation | The lint-process CLI must fail with a clear error when run outside a git repository in both staged and all modes.                                                                                         | Process guard validation depends on git diff for change detection — running without git produces undefined behavior rather than useful validation results.                                      |
+| CLI validates file mode input              | In file mode, the CLI must require at least one file path via positional argument or --file flag, and fail with a clear error when none is provided.                                                      | File mode is for targeted validation of specific files — accepting zero files would silently produce a "no violations" result that falsely implies the files are valid.                         |
+| CLI handles no changes gracefully          | When no relevant changes are detected (empty diff), the CLI must exit successfully with a zero exit code.                                                                                                 | No changes means no violations are possible — failing on empty diffs would break CI pipelines on commits that only modify non-spec files.                                                       |
+| CLI supports multiple output formats       | The CLI must support JSON and pretty (human-readable) output formats, with pretty as the default.                                                                                                         | Pretty format serves interactive pre-commit use while JSON format enables CI/CD pipeline integration and automated violation processing.                                                        |
+| CLI supports debug options                 | The --show-state flag must display the derived process state (FSM states, protection levels, deliverables) without affecting validation behavior.                                                         | Process guard decisions are derived from complex state — exposing the intermediate state helps developers understand why a specific validation passed or failed.                                |
+| CLI warns about unknown flags              | Unrecognized CLI flags must produce a warning message but allow execution to continue.                                                                                                                    | Process validation is critical-path at commit time — hard-failing on a typo in an optional flag would block commits unnecessarily when the core validation would succeed.                       |
+| CLI honors config-defined feature scope    | Process guard must derive state and diff transitions from the configured feature globs, including `tests/features/**/*.feature`, while ignoring non-feature files that only contain annotation-like text. | Rebrand cleanup imports completed artifacts under multiple feature roots — using hardcoded feature locations misses valid unlock reasons and creates false positives from docs or helper files. |
 
 ### MCP Server Integration
 
-| Rule                                                                    | Invariant                                                                                                                                                                                                                                                                                                 | Rationale                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| MCP server starts via stdio transport and manages its own lifecycle     | The MCP server communicates over stdio using JSON-RPC. It builds the pipeline once during initialization, then enters a request-response loop. No non-MCP output is written to stdout (no console.log, no pnpm banners).                                                                                  | MCP defines stdio as the standard transport for local tool servers. Claude Code spawns the process and communicates over stdin/stdout pipes. Any extraneous stdout output corrupts the JSON-RPC stream. Loading the pipeline during initialization ensures the first tool call is fast. |
-| ProcessStateAPI methods and CLI subcommands are registered as MCP tools | Every CLI subcommand is registered as an MCP tool with a JSON Schema describing its input parameters. Tool names use snake*case with a "architect*" prefix to avoid collisions with other MCP servers.                                                                                                    | MCP tools are the unit of interaction. Each tool needs a name, description (for LLM tool selection), and JSON Schema for input validation. The "architect\_" prefix prevents collisions in multi-server setups.                                                                         |
-| MasterDataset is loaded once and reused across all tool invocations     | The pipeline runs exactly once during server initialization. All subsequent tool calls read from in-memory MasterDataset. A manual rebuild can be triggered via a "architect_rebuild" tool, and overlapping rebuild requests coalesce so the final in-memory session reflects the newest completed build. | The pipeline costs 2-5 seconds. Running it per tool call negates MCP benefits. Pre-computed views provide O(1) access ideal for a query server.                                                                                                                                         |
-| Source file changes trigger automatic dataset rebuild with debouncing   | When --watch is enabled, changes to source files trigger an automatic pipeline rebuild. Multiple rapid changes are debounced into a single rebuild (default 500ms window).                                                                                                                                | During implementation sessions, source files change frequently. Without auto-rebuild, agents must manually call architect_rebuild. Debouncing prevents redundant rebuilds during rapid-fire saves.                                                                                      |
-| MCP server is configurable via standard client configuration            | The server works with .mcp.json (Claude Code), claude_desktop_config.json (Claude Desktop), and any MCP client. It accepts --input, --features, --base-dir args, auto-detects architect.config.ts, and reports the package version accurately through the CLI.                                            | MCP clients discover servers through configuration files. The server must work with sensible defaults (config auto-detection) while supporting explicit overrides for monorepo setups.                                                                                                  |
+| Rule                                                                    | Invariant                                                                                                                                                                                                                                                                                                | Rationale                                                                                                                                                                                                                                                                               |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| MCP server starts via stdio transport and manages its own lifecycle     | The MCP server communicates over stdio using JSON-RPC. It builds the pipeline once during initialization, then enters a request-response loop. No non-MCP output is written to stdout (no console.log, no pnpm banners).                                                                                 | MCP defines stdio as the standard transport for local tool servers. Claude Code spawns the process and communicates over stdin/stdout pipes. Any extraneous stdout output corrupts the JSON-RPC stream. Loading the pipeline during initialization ensures the first tool call is fast. |
+| PatternGraphAPI methods and CLI subcommands are registered as MCP tools | Every CLI subcommand is registered as an MCP tool with a JSON Schema describing its input parameters. Tool names use snake*case with a "architect*" prefix to avoid collisions with other MCP servers.                                                                                                   | MCP tools are the unit of interaction. Each tool needs a name, description (for LLM tool selection), and JSON Schema for input validation. The "architect\_" prefix prevents collisions in multi-server setups.                                                                         |
+| PatternGraph is loaded once and reused across all tool invocations      | The pipeline runs exactly once during server initialization. All subsequent tool calls read from in-memory PatternGraph. A manual rebuild can be triggered via a "architect_rebuild" tool, and overlapping rebuild requests coalesce so the final in-memory session reflects the newest completed build. | The pipeline costs 2-5 seconds. Running it per tool call negates MCP benefits. Pre-computed views provide O(1) access ideal for a query server.                                                                                                                                         |
+| Source file changes trigger automatic dataset rebuild with debouncing   | When --watch is enabled, changes to source files trigger an automatic pipeline rebuild. Multiple rapid changes are debounced into a single rebuild (default 500ms window).                                                                                                                               | During implementation sessions, source files change frequently. Without auto-rebuild, agents must manually call architect_rebuild. Debouncing prevents redundant rebuilds during rapid-fire saves.                                                                                      |
+| MCP server is configurable via standard client configuration            | The server works with .mcp.json (Claude Code), claude_desktop_config.json (Claude Desktop), and any MCP client. It accepts --input, --features, --base-dir args, auto-detects architect.config.ts, and reports the package version accurately through the CLI.                                           | MCP clients discover servers through configuration files. The server must work with sensible defaults (config auto-detection) while supporting explicit overrides for monorepo setups.                                                                                                  |
 
 ### Output Pipeline Tests
 
@@ -673,72 +677,74 @@ ArchIndexSchema = z.object({
 | List filters compose via AND logic             | Multiple list filters (status, category) must compose via AND logic, with pagination (limit/offset) applied after filtering and empty results for out-of-range offsets.               | AND composition is the intuitive default for filters — "status=active AND category=core" should narrow results, not widen them via OR logic.               |
 | Empty stripping removes noise                  | Null and empty values must be stripped from output objects to reduce noise in API responses.                                                                                          | Empty fields in pattern summaries create visual clutter and waste tokens in AI context windows — stripping them keeps output focused on meaningful data.   |
 
-### Pattern Helpers Tests
+### Pattern Graph API CLI
 
-| Rule                                                     | Invariant                                                                                                                                                          | Rationale                                                                                                                                                                 |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| getPatternName uses patternName tag when available       | getPatternName must return the patternName tag value when set, falling back to the pattern's name field when the tag is absent.                                    | The patternName tag allows human-friendly display names — without the fallback, patterns missing the tag would display as undefined.                                      |
-| findPatternByName performs case-insensitive matching     | findPatternByName must match pattern names case-insensitively, returning undefined when no match exists.                                                           | Case-insensitive matching prevents frustrating "not found" errors when developers type "processguard" instead of "ProcessGuard" — both clearly refer to the same pattern. |
-| getRelationships looks up with case-insensitive fallback | getRelationships must first try exact key lookup in the relationship index, then fall back to case-insensitive matching, returning undefined when no match exists. | Exact-first with case-insensitive fallback balances performance (O(1) exact lookup) with usability (tolerates case mismatches in cross-references).                       |
-| suggestPattern provides fuzzy suggestions                | suggestPattern must return fuzzy match suggestions for close pattern names, returning empty results when no close match exists.                                    | Fuzzy suggestions power "did you mean?" UX in the CLI — without them, typos produce unhelpful "pattern not found" messages.                                               |
+| Rule                                      | Invariant                                                        | Rationale                                                                                                                                                                                                                                     |
+| ----------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI supports status-based pattern queries | Every PatternGraphAPI status query method is accessible via CLI. | The most common planning question is "what's the current state?" Status queries (active, roadmap, completed) answer this directly without reading docs. Without CLI access, Claude Code must regenerate markdown and parse unstructured text. |
+| CLI supports phase-based queries          | Patterns can be filtered by phase number.                        | Phase 18 (Event Durability) is the current focus per roadmap priorities. Quick phase queries help assess progress and remaining work within a phase. Phase-based planning is the primary organization method for roadmap work.                |
+| CLI provides progress summary queries     | Overall and per-phase progress is queryable in a single command. | Planning sessions need quick answers to "where are we?" without reading the full PATTERNS.md generated file. Progress metrics drive prioritization and help identify where to focus effort.                                                   |
+| CLI supports multiple output formats      | JSON output is parseable by AI agents without transformation.    | Claude Code can parse JSON directly. Text format is for human reading. JSON format enables scripting and integration with other tools. The primary use case is AI agent parsing where structured output reduces context and errors.           |
+| CLI supports individual pattern lookup    | Any pattern can be queried by name with full details.            | During implementation, Claude Code needs to check specific pattern status, deliverables, and dependencies without reading the full spec file. Pattern lookup is essential for focused implementation work.                                    |
+| CLI provides discoverable help            | All flags are documented via --help with examples.               | Claude Code can read --help output to understand available queries without needing external documentation. Self-documenting CLIs reduce the need for Claude Code to read additional context files.                                            |
 
-### Pattern Summarize Tests
+### Pattern Graph API Relationship Queries
 
-| Rule                                         | Invariant                                                                                                                                                                                                  | Rationale                                                                                                                                                      |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| summarizePattern projects to compact summary | summarizePattern must project a full pattern object to a compact summary containing exactly 6 fields, using the patternName tag over the name field when available and omitting undefined optional fields. | Compact summaries reduce token usage by 80-90% compared to full patterns — they provide enough context for navigation without overwhelming AI context windows. |
-| summarizePatterns batch processes arrays     | summarizePatterns must batch-process an array of patterns, returning a correctly-sized array of compact summaries.                                                                                         | Batch processing avoids N individual function calls — the API frequently needs to summarize all patterns matching a query in a single operation.               |
+| Rule                                             | Invariant                                                               | Rationale                                                                                                                                                                                                        |
+| ------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| API provides implementation relationship queries | Every pattern with `implementedBy` entries is discoverable via the API. | Claude Code needs to navigate from abstract patterns to concrete code. Without this, exploration requires manual grep + file reading, wasting context tokens.                                                    |
+| API provides inheritance hierarchy queries       | Pattern inheritance chains are fully navigable in both directions.      | Patterns form specialization hierarchies (e.g., ReactiveProjections extends ProjectionCategories). Claude Code needs to understand what specializes a base pattern and what a specialized pattern inherits from. |
+| API provides combined relationship views         | All relationship types are accessible through a unified interface.      | Claude Code often needs the complete picture: dependencies AND implementations AND inheritance. A single call reduces round-trips and context switching.                                                         |
+| API supports bidirectional traceability queries  | Navigation from spec to code and code to spec is symmetric.             | Traceability is bidirectional by definition. If a spec links to code, the code should link back to the spec. The API should surface broken links.                                                                |
 
-### PDR 001 Session Workflow Commands
+### Pattern Graph API Testing
 
-| Rule                                                 | Invariant                                                                                                    | Rationale                                                                                                                                   |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| DD-1 - Text output with section markers              | scope-validate and handoff must return plain text with === SECTION === markers, never JSON.                  | Inconsistent output formats force consumers to detect and branch on format type, breaking the dual output path contract.                    |
-| DD-2 - Git integration is opt-in via --git flag      | Domain logic must never invoke shell commands or depend on git directly.                                     | Shell dependencies in domain logic make functions untestable without git fixtures and break deterministic behavior.                         |
-| DD-3 - Session type inferred from FSM status         | Every FSM status must map to exactly one default session type, overridable by an explicit --session flag.    | Ambiguous or missing inference forces users to always specify --session manually, defeating the ergonomic benefit of status-based defaults. |
-| DD-4 - Severity levels match Process Guard model     | Scope validation must use exactly three severity levels (PASS, BLOCKED, WARN) consistent with Process Guard. | Divergent severity models cause confusion when the same violation appears in both systems with different severity classifications.          |
-| DD-5 - Current date only for handoff                 | Handoff must always use the current system date with no override mechanism.                                  | A --date flag enables backdating handoff timestamps, which breaks audit trail integrity for multi-session work.                             |
-| DD-6 - Both positional and flag forms for scope type | scope-validate must accept scope type as both a positional argument and a --type flag.                       | Supporting only one form creates inconsistency with CLI conventions and forces users to remember which form each subcommand uses.           |
-| DD-7 - Co-located formatter functions                | Each module must export both its data builder and text formatter as co-located functions.                    | Splitting builder and formatter across files increases coupling surface and makes it harder to trace data flow through the module.          |
+| Rule                                           | Invariant                                                                                                                     | Rationale                                                                                                                    |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Status queries return correct patterns         | Status queries must correctly filter by both normalized status (planned = roadmap + deferred) and FSM status (exact match).   | The two-domain status convention requires separate query methods — mixing them produces incorrect filtered results.          |
+| Phase queries return correct phase data        | Phase queries must return only patterns in the requested phase, with accurate progress counts and completion percentage.      | Phase-level queries power the roadmap and session planning views — incorrect counts cascade into wrong progress percentages. |
+| FSM queries expose transition validation       | FSM queries must validate transitions against the PDR-005 state machine and expose protection levels per status.              | Programmatic FSM access enables tooling to enforce delivery process rules without reimplementing the state machine.          |
+| Pattern queries find and retrieve pattern data | Pattern lookup must be case-insensitive by name, and category queries must return only patterns with the requested category.  | Case-insensitive search reduces friction in CLI and AI agent usage where exact casing is often unknown.                      |
+| Timeline queries group patterns by time        | Quarter queries must correctly filter by quarter string, and recently completed must be sorted by date descending with limit. | Timeline grouping enables quarterly reporting and session context — recent completions show delivery momentum.               |
 
-### Process Api Cli Cache
+### Pattern Graph Cli Cache
 
-| Rule                                        | Invariant                                                                                                                                                                 | Rationale                                                                                                                                                                                    |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| MasterDataset is cached between invocations | When source files have not changed between CLI invocations, the second invocation must use the cached MasterDataset and report cache.hit as true with reduced pipelineMs. | The pipeline rebuild costs 2-5 seconds per invocation. Caching eliminates this cost for repeated queries against unchanged sources, which is the common case during interactive AI sessions. |
+| Rule                                       | Invariant                                                                                                                                                                           | Rationale                                                                                                                                                                                    |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PatternGraph is cached between invocations | When source files have not changed between CLI invocations, the second invocation must use the cached PatternGraph and report cache.hit as true alongside pipeline timing metadata. | The pipeline rebuild costs 2-5 seconds per invocation. Caching eliminates this cost for repeated queries against unchanged sources, which is the common case during interactive AI sessions. |
 
-### Process Api Cli Core
+### Pattern Graph Cli Core
 
 | Rule                                              | Invariant                                                                                                                     | Rationale                                                                                                                                                                                                                        |
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | CLI displays help and version information         | The CLI must always provide discoverable usage and version information via standard flags.                                    | Without accessible help and version output, users cannot self-serve CLI usage or report issues with a specific version.                                                                                                          |
 | CLI requires input flag for subcommands           | Every data-querying subcommand must receive either an explicit `--input` glob or a project config that provides source globs. | Without an input source, the pipeline has no files to scan and would produce empty or misleading results instead of a clear error, but project config auto-detection should remove that boilerplate when the repo is configured. |
-| CLI status subcommand shows delivery state        | The status subcommand must return structured JSON containing delivery progress derived from the MasterDataset.                | Consumers depend on machine-readable status output for scripting and CI integration; unstructured output breaks downstream automation.                                                                                           |
+| CLI status subcommand shows delivery state        | The status subcommand must return structured JSON containing delivery progress derived from the PatternGraph.                 | Consumers depend on machine-readable status output for scripting and CI integration; unstructured output breaks downstream automation.                                                                                           |
 | CLI query subcommand executes API methods         | The query subcommand must dispatch to any public Data API method by name and pass positional arguments through.               | The CLI is the primary interface for ad-hoc queries; failing to resolve a valid method name or its arguments silently drops the user's request.                                                                                  |
 | CLI pattern subcommand shows pattern detail       | The pattern subcommand must return the full JSON detail for an exact pattern name match, or a clear error if not found.       | Pattern lookup is the primary debugging tool for annotation issues; ambiguous or silent failures waste investigation time.                                                                                                       |
-| CLI arch subcommand queries architecture          | The arch subcommand must expose role, bounded context, and layer queries over the MasterDataset's architecture metadata.      | Architecture queries replace manual exploration of annotated sources; missing or incorrect results lead to wrong structural assumptions during design sessions.                                                                  |
+| CLI arch subcommand queries architecture          | The arch subcommand must expose role, bounded context, and layer queries over the PatternGraph's architecture metadata.       | Architecture queries replace manual exploration of annotated sources; missing or incorrect results lead to wrong structural assumptions during design sessions.                                                                  |
 | CLI shows errors for missing subcommand arguments | Subcommands that require arguments must reject invocations with missing arguments and display usage guidance.                 | Silent acceptance of incomplete input would produce confusing pipeline errors instead of actionable feedback at the CLI boundary.                                                                                                |
 | CLI handles argument edge cases                   | The CLI must gracefully handle non-standard argument forms including numeric coercion and the `--` pnpm separator.            | Real-world invocations via pnpm pass `--` separators and numeric strings; mishandling these causes silent data loss or crashes in automated workflows.                                                                           |
 
-### Process Api Cli Dry Run
+### Pattern Graph Cli Dry Run
 
 | Rule                                            | Invariant                                                                                                                                                                                         | Rationale                                                                                                                                                                                                       |
 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Dry-run shows pipeline scope without processing | The --dry-run flag must display file counts, config status, and cache status without executing the pipeline. Output must contain the DRY RUN marker and must not contain a JSON success envelope. | Dry-run enables users to verify their input patterns resolve to expected files before committing to the 2-5s pipeline cost, which is especially valuable when debugging glob patterns or config auto-detection. |
 
-### Process Api Cli Help
+### Pattern Graph Cli Help
 
 | Rule                                      | Invariant                                                                                                                                                                                            | Rationale                                                                                                                                                 |
 | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Per-subcommand help shows usage and flags | Running any subcommand with --help must display usage information specific to that subcommand, including applicable flags and examples. Unknown subcommands must fall back to a descriptive message. | Per-subcommand help replaces the need to scroll through full --help output and provides contextual guidance for subcommand-specific flags like --session. |
 
-### Process Api Cli Metadata
+### Pattern Graph Cli Metadata
 
 | Rule                                          | Invariant                                                                                                                                                                                                 | Rationale                                                                                                                                                                            |
 | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Response metadata includes validation summary | Every JSON response envelope must include a metadata.validation object with danglingReferenceCount, malformedPatternCount, unknownStatusCount, and warningCount fields, plus a numeric pipelineMs timing. | Consumers use validation counts to detect annotation quality degradation without running a separate validation pass. Pipeline timing enables performance regression detection in CI. |
 
-### Process Api Cli Modifiers And Rules
+### Pattern Graph Cli Modifiers And Rules
 
 | Rule                                                       | Invariant                                                                                                                                                                       | Rationale                                                                                                                                                                             |
 | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -746,14 +752,22 @@ ArchIndexSchema = z.object({
 | CLI arch health subcommands detect graph quality issues    | Health subcommands (dangling, orphans, blocking) operate on the relationship index, not the architecture index, and return results without requiring arch annotations.          | Graph quality issues (broken references, isolated patterns, blocked dependencies) are relationship-level concerns that should be queryable even when no architecture metadata exists. |
 | CLI rules subcommand queries business rules and invariants | The rules subcommand returns structured business rules extracted from Gherkin Rule: blocks, grouped by product area and phase, with parsed invariant and rationale annotations. | Live business rule queries replace static generated markdown, enabling on-demand filtering by product area, pattern, and invariant presence.                                          |
 
-### Process Api Cli Repl
+### Pattern Graph Cli Reference Tests
+
+| Rule                                                       | Invariant                                                                                                                           | Rationale |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| Generated reference file contains all three table sections | CLI-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema.                  |           |
+| CLI schema stays in sync with parser                       | Every flag recognized by parseArgs() has a corresponding entry in the CLI schema. A missing schema entry means the sync test fails. |           |
+| showHelp output reflects CLI schema                        | The help text rendered by showHelp() includes all options from the CLI schema, formatted for terminal display.                      |           |
+
+### Pattern Graph Cli Repl
 
 | Rule                                                         | Invariant                                                                                                         | Rationale                                                                                                                 |
 | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | REPL mode accepts multiple queries on a single pipeline load | REPL mode loads the pipeline once and accepts multiple queries on stdin, eliminating per-query pipeline overhead. | Design sessions involve 10-20 exploratory queries in sequence. REPL mode eliminates per-query pipeline overhead entirely. |
 | REPL reload rebuilds the pipeline from fresh sources         | The reload command rebuilds the pipeline from fresh sources and subsequent queries use the new dataset.           | During implementation sessions, source files change frequently. Reload allows refreshing without restarting the REPL.     |
 
-### Process Api Cli Subcommands
+### Pattern Graph Cli Subcommands
 
 | Rule                                                           | Invariant                                                                                                                                                                                           | Rationale                                                                                                                                                                      |
 | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -764,53 +778,43 @@ ArchIndexSchema = z.object({
 | CLI extended arch subcommands query architecture relationships | Extended arch subcommands (neighborhood, compare, coverage) must return valid JSON reflecting the actual architecture relationships present in the scanned sources.                                 | Architecture queries drive design-session decisions; stale or structurally invalid output leads to incorrect dependency analysis and missed coupling between bounded contexts. |
 | CLI unannotated subcommand finds files without annotations     | The unannotated subcommand must return valid JSON listing every TypeScript file that lacks the `@architect` opt-in marker.                                                                          | Files missing the opt-in marker are invisible to the scanner; without this subcommand, unannotated files silently drop out of generated documentation and validation.          |
 
-### Process API Layered Extraction
+### Pattern Graph Layered Extraction
 
-| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                                                  | Rationale                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CLI file contains only routing, no domain logic                   | `process-api.ts` parses arguments, calls the pipeline factory for the MasterDataset, routes subcommands to API modules, and formats output. It does not build Maps, filter patterns, group data, or resolve relationships. Thin view projections (3-5 line `.map()` calls over pre-computed archIndex views) are acceptable as formatting. | Domain logic in the CLI file is only accessible via the command line. Extracting it to `src/api/` makes it programmatically testable, reusable by future consumers (MCP server, watch mode), and aligned with the feature-consumption layer defined in ADR-006.                                                                                                                                               |
-| Pipeline factory is shared across CLI consumers                   | The scan-extract-transform sequence is defined once in `src/generators/pipeline/build-pipeline.ts`. CLI consumers that need a MasterDataset call the factory rather than wiring the pipeline independently. The factory accepts `mergeConflictStrategy` to handle behavioral differences between consumers.                                | Three consumers (process-api, validate-patterns, orchestrator) independently wire the same 8-step sequence: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, transformToMasterDataset. The only semantic difference is merge-conflict handling (fatal vs concatenate). This is a Parallel Pipeline anti-pattern per ADR-006. |
-| Domain logic lives in API modules                                 | Query logic that operates on MasterDataset lives in `src/api/` modules. The `rules-query.ts` module provides business rules querying with the same grouping logic that was inline in handleRules: filter by product area and pattern, group by area -> phase -> feature -> rules, parse annotations, compute totals.                       | `handleRules` is 184 lines with 5 Map/Set constructions, codec-layer imports (`parseBusinessRuleAnnotations`, `deduplicateScenarioNames`), and a complex 3-level grouping algorithm. This is the last significant inline domain logic in process-api.ts. Moving it to `src/api/` follows the same pattern as the 12 existing API modules (context-assembler, arch-queries, scope-validator, etc.).            |
-| Pipeline factory returns Result for consumer-owned error handling | The factory returns `Result<PipelineResult, PipelineError>` rather than throwing or calling `process.exit()`. Each consumer maps the error to its own strategy: process-api.ts calls `process.exit(1)`, validate-patterns.ts throws, and orchestrator.ts (future) returns `Result.err()`.                                                  | The current `buildPipeline()` in process-api.ts calls `process.exit(1)` on errors, making it non-reusable. The factory must work across consumers with different error handling models. The Result monad is the project's established pattern for this (see `src/types/result.ts`).                                                                                                                           |
-| End-to-end verification confirms behavioral equivalence           | After extraction, all CLI commands produce identical output to pre-refactor behavior with zero build, test, lint, and validation errors.                                                                                                                                                                                                   | The refactor must not change observable behavior. Full CLI verification confirms the extraction is a pure refactor.                                                                                                                                                                                                                                                                                           |
+| Rule                                                              | Invariant                                                                                                                                                                                                                                                                                                                                       | Rationale                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| CLI file contains only routing, no domain logic                   | `pattern-graph-cli.ts` parses arguments, calls the pipeline factory for the PatternGraph, routes subcommands to API modules, and formats output. It does not build Maps, filter patterns, group data, or resolve relationships. Thin view projections (3-5 line `.map()` calls over pre-computed archIndex views) are acceptable as formatting. | Domain logic in the CLI file is only accessible via the command line. Extracting it to `src/api/` makes it programmatically testable, reusable by future consumers (MCP server, watch mode), and aligned with the feature-consumption layer defined in ADR-006.                                                                                                                                                    |
+| Pipeline factory is shared across CLI consumers                   | The scan-extract-transform sequence is defined once in `src/generators/pipeline/build-pipeline.ts`. CLI consumers that need a PatternGraph call the factory rather than wiring the pipeline independently. The factory accepts `mergeConflictStrategy` to handle behavioral differences between consumers.                                      | Three consumers (pattern-graph-cli, validate-patterns, orchestrator) independently wire the same 8-step sequence: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, transformToPatternGraph. The only semantic difference is merge-conflict handling (fatal vs concatenate). This is a Parallel Pipeline anti-pattern per ADR-006. |
+| Domain logic lives in API modules                                 | Query logic that operates on PatternGraph lives in `src/api/` modules. The `rules-query.ts` module provides business rules querying with the same grouping logic that was inline in handleRules: filter by product area and pattern, group by area -> phase -> feature -> rules, parse annotations, compute totals.                             | `handleRules` is 184 lines with 5 Map/Set constructions, codec-layer imports (`parseBusinessRuleAnnotations`, `deduplicateScenarioNames`), and a complex 3-level grouping algorithm. This is the last significant inline domain logic in pattern-graph-cli.ts. Moving it to `src/api/` follows the same pattern as the 12 existing API modules (context-assembler, arch-queries, scope-validator, etc.).           |
+| Pipeline factory returns Result for consumer-owned error handling | The factory returns `Result<PipelineResult, PipelineError>` rather than throwing or calling `process.exit()`. Each consumer maps the error to its own strategy: pattern-graph-cli.ts calls `process.exit(1)`, validate-patterns.ts throws, and orchestrator.ts (future) returns `Result.err()`.                                                 | The current `buildPipeline()` in pattern-graph-cli.ts calls `process.exit(1)` on errors, making it non-reusable. The factory must work across consumers with different error handling models. The Result monad is the project's established pattern for this (see `src/types/result.ts`).                                                                                                                          |
+| End-to-end verification confirms behavioral equivalence           | After extraction, all CLI commands produce identical output to pre-refactor behavior with zero build, test, lint, and validation errors.                                                                                                                                                                                                        | The refactor must not change observable behavior. Full CLI verification confirms the extraction is a pure refactor.                                                                                                                                                                                                                                                                                                |
 
-### Process Api Reference Tests
-
-| Rule                                                       | Invariant                                                                                                                           | Rationale |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------- |
-| Generated reference file contains all three table sections | PROCESS-API-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema.          |           |
-| CLI schema stays in sync with parser                       | Every flag recognized by parseArgs() has a corresponding entry in the CLI schema. A missing schema entry means the sync test fails. |           |
-| showHelp output reflects CLI schema                        | The help text rendered by showHelp() includes all options from the CLI schema, formatted for terminal display.                      |           |
-
-### Process State API CLI
+### Pattern Helpers Tests
 
-| Rule                                      | Invariant                                                        | Rationale                                                                                                                                                                                                                                     |
-| ----------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CLI supports status-based pattern queries | Every ProcessStateAPI status query method is accessible via CLI. | The most common planning question is "what's the current state?" Status queries (active, roadmap, completed) answer this directly without reading docs. Without CLI access, Claude Code must regenerate markdown and parse unstructured text. |
-| CLI supports phase-based queries          | Patterns can be filtered by phase number.                        | Phase 18 (Event Durability) is the current focus per roadmap priorities. Quick phase queries help assess progress and remaining work within a phase. Phase-based planning is the primary organization method for roadmap work.                |
-| CLI provides progress summary queries     | Overall and per-phase progress is queryable in a single command. | Planning sessions need quick answers to "where are we?" without reading the full PATTERNS.md generated file. Progress metrics drive prioritization and help identify where to focus effort.                                                   |
-| CLI supports multiple output formats      | JSON output is parseable by AI agents without transformation.    | Claude Code can parse JSON directly. Text format is for human reading. JSON format enables scripting and integration with other tools. The primary use case is AI agent parsing where structured output reduces context and errors.           |
-| CLI supports individual pattern lookup    | Any pattern can be queried by name with full details.            | During implementation, Claude Code needs to check specific pattern status, deliverables, and dependencies without reading the full spec file. Pattern lookup is essential for focused implementation work.                                    |
-| CLI provides discoverable help            | All flags are documented via --help with examples.               | Claude Code can read --help output to understand available queries without needing external documentation. Self-documenting CLIs reduce the need for Claude Code to read additional context files.                                            |
+| Rule                                                     | Invariant                                                                                                                                                          | Rationale                                                                                                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| getPatternName uses patternName tag when available       | getPatternName must return the patternName tag value when set, falling back to the pattern's name field when the tag is absent.                                    | The patternName tag allows human-friendly display names — without the fallback, patterns missing the tag would display as undefined.                                      |
+| findPatternByName performs case-insensitive matching     | findPatternByName must match pattern names case-insensitively, returning undefined when no match exists.                                                           | Case-insensitive matching prevents frustrating "not found" errors when developers type "processguard" instead of "ProcessGuard" — both clearly refer to the same pattern. |
+| getRelationships looks up with case-insensitive fallback | getRelationships must first try exact key lookup in the relationship index, then fall back to case-insensitive matching, returning undefined when no match exists. | Exact-first with case-insensitive fallback balances performance (O(1) exact lookup) with usability (tolerates case mismatches in cross-references).                       |
+| suggestPattern provides fuzzy suggestions                | suggestPattern must return fuzzy match suggestions for close pattern names, returning empty results when no close match exists.                                    | Fuzzy suggestions power "did you mean?" UX in the CLI — without them, typos produce unhelpful "pattern not found" messages.                                               |
 
-### Process State API Relationship Queries
+### Pattern Summarize Tests
 
-| Rule                                             | Invariant                                                               | Rationale                                                                                                                                                                                                        |
-| ------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| API provides implementation relationship queries | Every pattern with `implementedBy` entries is discoverable via the API. | Claude Code needs to navigate from abstract patterns to concrete code. Without this, exploration requires manual grep + file reading, wasting context tokens.                                                    |
-| API provides inheritance hierarchy queries       | Pattern inheritance chains are fully navigable in both directions.      | Patterns form specialization hierarchies (e.g., ReactiveProjections extends ProjectionCategories). Claude Code needs to understand what specializes a base pattern and what a specialized pattern inherits from. |
-| API provides combined relationship views         | All relationship types are accessible through a unified interface.      | Claude Code often needs the complete picture: dependencies AND implementations AND inheritance. A single call reduces round-trips and context switching.                                                         |
-| API supports bidirectional traceability queries  | Navigation from spec to code and code to spec is symmetric.             | Traceability is bidirectional by definition. If a spec links to code, the code should link back to the spec. The API should surface broken links.                                                                |
+| Rule                                         | Invariant                                                                                                                                                                                                  | Rationale                                                                                                                                                      |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| summarizePattern projects to compact summary | summarizePattern must project a full pattern object to a compact summary containing exactly 6 fields, using the patternName tag over the name field when available and omitting undefined optional fields. | Compact summaries reduce token usage by 80-90% compared to full patterns — they provide enough context for navigation without overwhelming AI context windows. |
+| summarizePatterns batch processes arrays     | summarizePatterns must batch-process an array of patterns, returning a correctly-sized array of compact summaries.                                                                                         | Batch processing avoids N individual function calls — the API frequently needs to summarize all patterns matching a query in a single operation.               |
 
-### Process State API Testing
+### PDR 001 Session Workflow Commands
 
-| Rule                                           | Invariant                                                                                                                     | Rationale                                                                                                                    |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| Status queries return correct patterns         | Status queries must correctly filter by both normalized status (planned = roadmap + deferred) and FSM status (exact match).   | The two-domain status convention requires separate query methods — mixing them produces incorrect filtered results.          |
-| Phase queries return correct phase data        | Phase queries must return only patterns in the requested phase, with accurate progress counts and completion percentage.      | Phase-level queries power the roadmap and session planning views — incorrect counts cascade into wrong progress percentages. |
-| FSM queries expose transition validation       | FSM queries must validate transitions against the PDR-005 state machine and expose protection levels per status.              | Programmatic FSM access enables tooling to enforce delivery process rules without reimplementing the state machine.          |
-| Pattern queries find and retrieve pattern data | Pattern lookup must be case-insensitive by name, and category queries must return only patterns with the requested category.  | Case-insensitive search reduces friction in CLI and AI agent usage where exact casing is often unknown.                      |
-| Timeline queries group patterns by time        | Quarter queries must correctly filter by quarter string, and recently completed must be sorted by date descending with limit. | Timeline grouping enables quarterly reporting and session context — recent completions show delivery momentum.               |
+| Rule                                                 | Invariant                                                                                                    | Rationale                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| DD-1 - Text output with section markers              | scope-validate and handoff must return plain text with === SECTION === markers, never JSON.                  | Inconsistent output formats force consumers to detect and branch on format type, breaking the dual output path contract.                    |
+| DD-2 - Git integration is opt-in via --git flag      | Domain logic must never invoke shell commands or depend on git directly.                                     | Shell dependencies in domain logic make functions untestable without git fixtures and break deterministic behavior.                         |
+| DD-3 - Session type inferred from FSM status         | Every FSM status must map to exactly one default session type, overridable by an explicit --session flag.    | Ambiguous or missing inference forces users to always specify --session manually, defeating the ergonomic benefit of status-based defaults. |
+| DD-4 - Severity levels match Process Guard model     | Scope validation must use exactly three severity levels (PASS, BLOCKED, WARN) consistent with Process Guard. | Divergent severity models cause confusion when the same violation appears in both systems with different severity classifications.          |
+| DD-5 - Current date only for handoff                 | Handoff must always use the current system date with no override mechanism.                                  | A --date flag enables backdating handoff timestamps, which breaks audit trail integrity for multi-session work.                             |
+| DD-6 - Both positional and flag forms for scope type | scope-validate must accept scope type as both a positional argument and a --type flag.                       | Supporting only one form creates inconsistency with CLI conventions and forces users to remember which form each subcommand uses.           |
+| DD-7 - Co-located formatter functions                | Each module must export both its data builder and text formatter as co-located functions.                    | Splitting builder and formatter across files increases coupling surface and makes it harder to trace data flow through the module.          |
 
 ### Scope Validator Tests