From 7a3e4f2329ae2b98041f49ffbedb69b1c2489c09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Wed, 1 Apr 2026 17:18:20 +0200 Subject: [PATCH 1/6] =?UTF-8?q?refactor:=20rename=20MasterDataset=20?= =?UTF-8?q?=E2=86=92=20PatternGraph=20=E2=80=94=20ubiquitous=20language=20?= =?UTF-8?q?alignment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align internal code vocabulary with product terminology per the naming review (ideation docs 04-05). "PatternGraph" communicates structure and content; "MasterDataset" was generic and required translation in every AI session. Tier 1 (core types): - MasterDataset → PatternGraph (type, schema, all references) - RuntimeMasterDataset → RuntimePatternGraph - buildMasterDataset() → buildPatternGraph() - transformToMasterDataset() → transformToPatternGraph() - GeneratorContext.masterDataset → GeneratorContext.patternGraph - @architect-shape master-dataset → @architect-shape pattern-graph Tier 2 (API layer): - ProcessStateAPI → PatternGraphAPI - createProcessStateAPI() → createPatternGraphAPI() File renames: - master-dataset.ts → pattern-graph.ts - process-state.ts → pattern-graph-api.ts - process-state-api test/spec files → pattern-graph-api No logic changes. No backward compatibility. All 8,808 tests pass. 304 files changed across source, tests, specs, and documentation. --- AGENTS.md | 2 +- CHANGELOG.md | 2 +- CLAUDE.md | 34 +-- README.md | 8 +- _claude-md/api/mcp-server.md | 2 +- _claude-md/core/architecture.md | 26 +- _claude-md/core/project-overview.md | 2 +- _claude-md/metadata.json | 2 +- _claude-md/testing/test-implementation.md | 4 +- architect.config.ts | 8 +- ...-source-first-pattern-architecture.feature | 2 +- ...005-codec-based-markdown-rendering.feature | 14 +- ...006-single-read-model-architecture.feature | 48 ++-- .../design-reviews/mcp-server-integration.md | 2 +- ...ss-api-layered-extraction-findings.feature | 16 +- .../specs/architecture-diagram-core.feature | 16 +- .../architecture-doc-refactoring.feature | 50 ++-- architect/specs/cli-recipe-codec.feature | 4 +- .../specs/codec-behavior-testing.feature | 26 +- .../codec-driven-reference-generation.feature | 6 +- .../specs/data-api-cli-ergonomics.feature | 12 +- .../specs/data-api-context-assembly.feature | 6 +- .../specs/data-api-output-shaping.feature | 2 +- .../data-api-platform-integration.feature | 10 +- .../specs/data-api-relationship-graph.feature | 6 +- .../specs/data-api-stub-integration.feature | 6 +- .../declaration-level-shape-tagging.feature | 8 +- .../specs/design-review-generation.feature | 12 +- .../specs/enhanced-index-generation.feature | 42 ++-- architect/specs/generated-doc-quality.feature | 10 +- .../generator-infrastructure-testing.feature | 12 +- .../specs/mcp-server-integration.feature | 18 +- architect/specs/monorepo-support.feature | 4 +- ...strator-pipeline-factory-migration.feature | 16 +- ....feature => pattern-graph-api-cli.feature} | 10 +- ...rn-graph-api-relationship-queries.feature} | 16 +- .../specs/pattern-relationship-model.feature | 2 +- architect/specs/phase-state-machine.feature | 2 +- .../specs/procedural-guide-codec.feature | 10 +- .../process-api-hybrid-generation.feature | 14 +- .../process-api-layered-extraction.feature | 34 +-- .../specs/reference-doc-showcase.feature | 2 +- .../specs/step-definition-completion.feature | 2 +- .../specs/traceability-generator.feature | 8 +- ...validator-read-model-consolidation.feature | 30 +-- .../handoff-generator.ts | 10 +- .../scope-validator.ts | 8 +- .../cli-recipe-codec/cli-recipe-generator.ts | 4 +- .../stubs/cli-recipe-codec/recipe-data.ts | 2 +- .../arch-queries.ts | 16 +- .../coverage-analyzer.ts | 8 +- .../context-assembler.ts | 16 +- .../output-pipeline.ts | 8 +- .../data-api-output-shaping/summarize.ts | 2 +- .../stub-resolver.ts | 10 +- .../index-codec-options.ts | 14 +- .../enhanced-index-generation/index-codec.ts | 28 +-- .../index-preamble-config.ts | 12 +- .../mcp-server-integration/file-watcher.ts | 2 +- .../pipeline-session.ts | 14 +- .../mcp-server-integration/tool-registry.ts | 4 +- .../annotation-guide-preamble.ts | 2 +- .../procedural-codec.ts | 2 +- ...eview-progressive-disclosure-and-codecs.md | 86 +++---- docs-inbox/codebase-exploration-findings.md | 44 ++-- docs-inbox/refactoring-execution-guide.md | 20 +- docs-inbox/reimplementation-drift-analysis.md | 2 +- ...on-prompt-generator-architecture-review.md | 14 +- docs-inbox/session-prompt-generator-brief.md | 16 +- docs-live/ARCHITECTURE.md | 62 ++--- docs-live/CHANGELOG-GENERATED.md | 190 +++++++-------- docs-live/INDEX.md | 12 +- docs-live/PRODUCT-AREAS.md | 8 +- .../annotation/annotation-overview.md | 2 +- .../annotation/annotation-reference.md | 10 +- .../architecture/architecture-types.md | 8 +- .../architecture/reference-sample.md | 2 +- .../core-types/core-types-overview.md | 2 +- .../_claude-md/data-api/data-api-overview.md | 4 +- .../generation/generation-overview.md | 30 +-- docs-live/business-rules/data-api.md | 174 +++++++------- docs-live/business-rules/generation.md | 36 +-- ...r-003-source-first-pattern-architecture.md | 2 +- .../adr-005-codec-based-markdown-rendering.md | 10 +- .../adr-006-single-read-model-architecture.md | 48 ++-- docs-live/product-areas/ANNOTATION.md | 22 +- docs-live/product-areas/CORE-TYPES.md | 4 +- docs-live/product-areas/DATA-API.md | 224 +++++++++--------- docs-live/product-areas/GENERATION.md | 216 ++++++++--------- docs-live/product-areas/PROCESS.md | 2 +- docs-live/product-areas/VALIDATION.md | 10 +- docs-live/reference/ANNOTATION-REFERENCE.md | 10 +- docs-live/reference/ARCHITECTURE-CODECS.md | 22 +- docs-live/reference/ARCHITECTURE-TYPES.md | 34 +-- docs-live/reference/PROCESS-API-RECIPES.md | 14 +- docs-live/reference/REFERENCE-SAMPLE.md | 68 +++--- docs-sources/annotation-guide.md | 10 +- docs-sources/index-navigation.md | 10 +- docs-sources/process-api-recipes.md | 2 +- docs/ANNOTATION-GUIDE.md | 10 +- docs/ARCHITECTURE.md | 142 +++++------ docs/CONFIGURATION.md | 4 +- docs/DOCS-GAP-ANALYSIS.md | 6 +- docs/INDEX.md | 34 +-- docs/MCP-SETUP.md | 6 +- docs/METHODOLOGY.md | 2 +- docs/VALIDATION.md | 4 +- package.json | 2 +- src/api/arch-queries.ts | 18 +- src/api/context-assembler.ts | 36 +-- src/api/coverage-analyzer.ts | 10 +- src/api/handoff-generator.ts | 14 +- src/api/index.ts | 10 +- ...{process-state.ts => pattern-graph-api.ts} | 28 +-- src/api/pattern-helpers.ts | 10 +- src/api/rules-query.ts | 8 +- src/api/scope-validator.ts | 24 +- src/api/stub-resolver.ts | 10 +- src/api/summarize.ts | 2 +- src/api/types.ts | 12 +- src/cli/cli-schema.ts | 12 +- src/cli/dataset-cache.ts | 10 +- src/cli/output-pipeline.ts | 6 +- src/cli/process-api.ts | 73 +++--- src/cli/repl.ts | 20 +- src/cli/validate-patterns.ts | 24 +- .../built-in/cli-recipe-generator.ts | 2 +- src/generators/built-in/codec-generators.ts | 8 +- .../built-in/design-review-generator.ts | 6 +- src/generators/built-in/index.ts | 2 +- .../process-api-reference-generator.ts | 2 +- .../built-in/reference-generators.ts | 14 +- src/generators/codec-based.ts | 6 +- src/generators/index.ts | 10 +- src/generators/orchestrator.ts | 24 +- src/generators/pipeline/build-pipeline.ts | 34 +-- src/generators/pipeline/index.ts | 10 +- .../pipeline/relationship-resolver.ts | 4 +- src/generators/pipeline/sequence-utils.ts | 6 +- src/generators/pipeline/transform-dataset.ts | 30 +-- src/generators/pipeline/transform-types.ts | 22 +- src/generators/types.ts | 4 +- src/index.ts | 6 +- src/mcp/file-watcher.ts | 2 +- src/mcp/pipeline-session.ts | 22 +- src/mcp/tool-registry.ts | 6 +- src/renderable/codecs/adr.ts | 8 +- src/renderable/codecs/architecture.ts | 32 +-- src/renderable/codecs/business-rules.ts | 12 +- src/renderable/codecs/claude-module.ts | 8 +- src/renderable/codecs/composite.ts | 2 +- src/renderable/codecs/convention-extractor.ts | 10 +- src/renderable/codecs/design-review.ts | 12 +- src/renderable/codecs/index-codec.ts | 10 +- src/renderable/codecs/index.ts | 4 +- src/renderable/codecs/patterns.ts | 28 +-- src/renderable/codecs/planning.ts | 8 +- src/renderable/codecs/pr-changes.ts | 8 +- .../codecs/product-area-metadata.ts | 10 +- src/renderable/codecs/reference-builders.ts | 4 +- src/renderable/codecs/reference-diagrams.ts | 28 +-- src/renderable/codecs/reference-types.ts | 6 +- src/renderable/codecs/reference.ts | 4 +- src/renderable/codecs/reporting.ts | 8 +- src/renderable/codecs/requirements.ts | 12 +- src/renderable/codecs/session.ts | 38 +-- src/renderable/codecs/shape-matcher.ts | 10 +- src/renderable/codecs/taxonomy.ts | 6 +- src/renderable/codecs/timeline.ts | 42 ++-- src/renderable/codecs/types/base.ts | 20 +- src/renderable/codecs/validation-rules.ts | 6 +- src/renderable/generate.ts | 34 +-- src/renderable/index.ts | 2 +- src/renderable/schema.ts | 2 +- src/validation-schemas/index.ts | 6 +- .../{master-dataset.ts => pattern-graph.ts} | 22 +- .../context-assembler.feature | 2 +- ...-api.feature => pattern-graph-api.feature} | 12 +- .../session-support/handoff-generator.feature | 4 +- .../stub-integration/stub-resolver.feature | 2 +- .../architecture-diagrams/arch-index.feature | 12 +- .../codecs/convention-extractor.feature | 6 +- .../codecs/generated-doc-quality.feature | 2 +- .../behavior/codecs/planning-codecs.feature | 58 ++--- .../codecs/pr-changes-codec-options.feature | 36 +-- .../codecs/pr-changes-codec-rendering.feature | 44 ++-- .../codecs/reference-codec-core.feature | 26 +- .../reference-codec-detail-rendering.feature | 42 ++-- .../reference-codec-diagram-types.feature | 26 +- .../codecs/reference-codec-diagrams.feature | 36 +-- .../codecs/reference-generators.feature | 8 +- .../behavior/codecs/reporting-codecs.feature | 50 ++-- .../codecs/requirements-adr-codecs.feature | 52 ++-- .../behavior/codecs/session-codecs.feature | 42 ++-- .../behavior/codecs/shape-matcher.feature | 6 +- .../behavior/codecs/shape-selector.feature | 8 +- .../behavior/codecs/timeline-codecs.feature | 42 ++-- .../features/behavior/patterns-codec.feature | 30 +-- .../behavior/transform-dataset.feature | 46 ++-- tests/features/cli/data-api-cache.feature | 6 +- tests/features/cli/process-api-core.feature | 4 +- .../architecture-doc-refactoring.feature | 20 +- .../doc-generation/index-codec.feature | 2 +- .../doc-generation/taxonomy-codec.feature | 2 +- .../validation-rules-codec.feature | 2 +- .../features/generation/design-review.feature | 4 +- .../generators/business-rules-codec.feature | 2 +- tests/features/generators/codec-based.feature | 6 +- tests/features/mcp/mcp-server.feature | 8 +- tests/fixtures/dataset-factories.ts | 96 ++++---- .../arch-queries.steps.ts | 10 +- .../context-assembler.steps.ts | 24 +- .../output-shaping/output-pipeline.steps.ts | 14 +- .../output-shaping/pattern-helpers.steps.ts | 14 +- ...pi.steps.ts => pattern-graph-api.steps.ts} | 16 +- .../handoff-generator.steps.ts | 20 +- .../session-support/scope-validator.steps.ts | 20 +- .../stub-integration/stub-resolver.steps.ts | 10 +- tests/steps/architecture/arch-index.steps.ts | 28 +-- .../architecture/component-diagram.steps.ts | 4 +- .../generator-registration.steps.ts | 6 +- .../architecture/layered-diagram.steps.ts | 4 +- .../cli/process-api-reference.steps.ts | 2 +- .../behavior/codecs/composite-codec.steps.ts | 14 +- .../codecs/convention-extractor.steps.ts | 48 ++-- .../codecs/generated-doc-quality.steps.ts | 12 +- .../behavior/codecs/planning-codecs.steps.ts | 126 +++++----- .../codecs/pr-changes-codec-options.steps.ts | 70 +++--- .../pr-changes-codec-rendering.steps.ts | 86 +++---- .../codecs/reference-codec-core.steps.ts | 54 ++--- .../reference-codec-detail-rendering.steps.ts | 86 +++---- .../reference-codec-diagram-types.steps.ts | 54 ++--- .../codecs/reference-codec-diagrams.steps.ts | 58 ++--- .../codecs/reference-generators.steps.ts | 32 +-- .../behavior/codecs/reporting-codecs.steps.ts | 104 ++++---- .../codecs/requirements-adr-codecs.steps.ts | 98 ++++---- .../behavior/codecs/session-codecs.steps.ts | 96 ++++---- .../behavior/codecs/shape-matcher.steps.ts | 18 +- .../behavior/codecs/shape-selector.steps.ts | 18 +- .../behavior/codecs/timeline-codecs.steps.ts | 98 ++++---- .../steps/behavior/context-inference.steps.ts | 28 +-- .../behavior/description-headers.steps.ts | 18 +- .../description-quality-foundation.steps.ts | 16 +- .../behavior/implementation-links.steps.ts | 10 +- .../depends-on-tag.steps.ts | 8 +- .../extends-tag.steps.ts | 6 +- .../implements-tag.steps.ts | 8 +- .../mermaid-rendering.steps.ts | 14 +- .../pattern-relationships/uses-tag.steps.ts | 8 +- tests/steps/behavior/patterns-codec.steps.ts | 64 ++--- .../behavior/pr-changes-generation.steps.ts | 12 +- .../remaining-work-enhancement.steps.ts | 32 +-- .../behavior/remaining-work-totals.steps.ts | 22 +- .../steps/behavior/session-handoffs.steps.ts | 22 +- .../steps/behavior/transform-dataset.steps.ts | 84 +++---- tests/steps/cli/data-api-cache.steps.ts | 8 +- tests/steps/cli/data-api-dryrun.steps.ts | 2 +- tests/steps/cli/data-api-help.steps.ts | 2 +- tests/steps/cli/data-api-metadata.steps.ts | 2 +- tests/steps/cli/data-api-repl.steps.ts | 2 +- tests/steps/cli/process-api-core.steps.ts | 4 +- .../cli/process-api-modifiers-rules.steps.ts | 4 +- .../cli/process-api-subcommands.steps.ts | 4 +- .../architecture-doc-refactoring.steps.ts | 6 +- .../steps/doc-generation/index-codec.steps.ts | 72 +++--- .../doc-generation/taxonomy-codec.steps.ts | 48 ++-- .../validation-rules-codec.steps.ts | 40 ++-- .../design-review-generator.steps.ts | 10 +- .../business-rules-generator.steps.ts | 8 +- tests/steps/generators/codec-based.steps.ts | 16 +- .../generators/pr-changes-options.steps.ts | 12 +- .../prd-implementation-section.steps.ts | 8 +- .../generators/table-extraction.steps.ts | 8 +- tests/steps/mcp/mcp-server.steps.ts | 4 +- tests/support/helpers/design-review-state.ts | 24 +- tests/support/helpers/mcp-state.ts | 20 +- ...pi-state.ts => pattern-graph-api-state.ts} | 0 .../support/helpers/pr-changes-codec-state.ts | 10 +- .../support/helpers/reference-codec-state.ts | 10 +- 279 files changed, 2989 insertions(+), 2994 deletions(-) rename architect/specs/{process-state-api-cli.feature => pattern-graph-api-cli.feature} (97%) rename architect/specs/{process-state-api-relationship-queries.feature => pattern-graph-api-relationship-queries.feature} (95%) rename src/api/{process-state.ts => pattern-graph-api.ts} (96%) rename src/validation-schemas/{master-dataset.ts => pattern-graph.ts} (96%) rename tests/features/api/{process-state-api.feature => pattern-graph-api.feature} (96%) rename tests/steps/api/{process-state-api.steps.ts => pattern-graph-api.steps.ts} (97%) rename tests/support/helpers/{process-api-state.ts => pattern-graph-api-state.ts} (100%) diff --git a/AGENTS.md b/AGENTS.md index 24cde0ee..570efb66 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,7 +56,7 @@ Use `architect.config.ts` or `.js` as the main integration contract and keep scr ## Architecture Snapshot - Pipeline: `Config -> Scanner -> Extractor -> Transformer -> Codec`. -- Central read model: `MasterDataset` (consumed by docs generation, Data API, and validators). +- Central read model: `PatternGraph` (consumed by docs generation, Data API, and validators). - Preset in this repo config: `libar-generic` (`@architect-*` tags). - Source ownership invariant: - TypeScript owns runtime relationships (`uses`, `used-by`, category-like tags). diff --git a/CHANGELOG.md b/CHANGELOG.md index 22e5e0b4..2bfe21c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,7 +36,7 @@ First npm-published pre-release for monorepo validation. - FSM-enforced workflow validation via pre-commit hooks - Codec-based document generation (patterns, roadmap, decisions, product areas, etc.) - Cross-source validation (TypeScript + Gherkin dual-source merging) -- MasterDataset single read model (ADR-006) +- PatternGraph single read model (ADR-006) ### Changed diff --git a/CLAUDE.md b/CLAUDE.md index 72aa3729..297c8563 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ Context engineering platform with extraction pipeline and typed codecs. Extracts **Key Capabilities:** - Pattern extraction from TypeScript JSDoc and Gherkin tags -- MasterDataset transformation with pre-computed views (O(1) access) +- PatternGraph transformation with pre-computed views (O(1) access) - Codec-based markdown generation with progressive disclosure - FSM-enforced delivery workflow validation via pre-commit hooks @@ -139,7 +139,7 @@ See the **Context Gathering Protocol** section above for mandatory session start ### MCP Server — Native AI Context Tools -When the MCP server is running, **use `architect_*` tools instead of CLI commands** (`pnpm architect:query --`). The MCP server keeps the MasterDataset in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same ProcessStateAPI methods available via CLI. +When the MCP server is running, **use `architect_*` tools instead of CLI commands** (`pnpm architect:query --`). The MCP server keeps the PatternGraph in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same PatternGraphAPI methods available via CLI. #### Session Start (MCP Protocol) @@ -269,13 +269,13 @@ The `--watch` flag enables auto-rebuild when `.ts` or `.feature` files change (5 ``` CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - (files) (patterns) (MasterDataset) (Markdown) + (files) (patterns) (PatternGraph) (Markdown) ``` 1. **Scanner** (`src/scanner/`): File discovery, AST parsing, opt-in detection via `@architect` marker 2. **Extractor** (`src/extractor/`): Pattern extraction from TypeScript JSDoc and Gherkin tags -3. **Transformer** (`src/generators/pipeline/`): Builds MasterDataset with pre-computed views -4. **Codec** (`src/renderable/`): Zod 4 codecs transform MasterDataset → RenderableDocument → Markdown +3. **Transformer** (`src/generators/pipeline/`): Builds PatternGraph with pre-computed views +4. **Codec** (`src/renderable/`): Zod 4 codecs transform PatternGraph → RenderableDocument → Markdown ### Key Design Patterns @@ -283,8 +283,8 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - **Schema-First**: Zod schemas in `src/validation-schemas/` define types with runtime validation - **Registry Pattern**: Tag registry (`src/taxonomy/`) defines categories, status values, and tag formats - **Codec-Based Rendering**: Generators in `src/generators/` use codecs to transform data to markdown -- **Pipeline Factory**: Shared `buildMasterDataset()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. -- **Single Read Model** (ADR-006): MasterDataset is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. +- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. +- **Single Read Model** (ADR-006): PatternGraph is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. **Live module inventory:** `pnpm architect:query -- arch context` and `pnpm architect:query -- arch layer` @@ -292,14 +292,14 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC Architecture and process decisions are recorded as annotated Gherkin specs in `architect/decisions/`: -| Spec | Key Decision | -| ------- | -------------------------------------------------------------------------- | -| ADR-001 | Taxonomy canonical values — tag registry is the single source of truth | -| ADR-002 | Gherkin-only testing — no `.test.ts` files, all tests are `.feature` | -| ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | -| ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | -| ADR-006 | Single read model — MasterDataset is the sole read model for all consumers | -| PDR-001 | Session workflow commands — Process Data API CLI design decisions | +| Spec | Key Decision | +| ------- | ------------------------------------------------------------------------- | +| ADR-001 | Taxonomy canonical values — tag registry is the single source of truth | +| ADR-002 | Gherkin-only testing — no `.test.ts` files, all tests are `.feature` | +| ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | +| ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | +| ADR-006 | Single read model — PatternGraph is the sole read model for all consumers | +| PDR-001 | Session workflow commands — Process Data API CLI design decisions | Query decisions: `pnpm architect:query -- decisions ` @@ -522,9 +522,9 @@ The project has strict linting rules. Save time by coding defensively. ```typescript // debug-codec.ts import { RemainingWorkCodec } from './src/renderable/codecs/session.js'; -import { createTestMasterDataset } from './tests/fixtures/dataset-factories.js'; +import { createTestPatternGraph } from './tests/fixtures/dataset-factories.js'; -const dataset = createTestMasterDataset({ ... }); +const dataset = createTestPatternGraph({ ... }); const doc = RemainingWorkCodec.decode(dataset); console.log(JSON.stringify(doc.sections, null, 2)); ``` diff --git a/README.md b/README.md index 12370de4..b25634c1 100644 --- a/README.md +++ b/README.md @@ -77,16 +77,16 @@ This validates FSM transitions and blocks invalid status changes. * @architect * @architect-pattern TransformDataset * @architect-status completed - * @architect-uses MasterDataset, ExtractedPattern, TagRegistry + * @architect-uses PatternGraph, ExtractedPattern, TagRegistry */ -export function transformToMasterDataset(input: TransformInput): MasterDataset { +export function transformToPatternGraph(input: TransformInput): PatternGraph { // ... } ``` -**Gherkin feature files** own planning metadata (status, phase, deliverables). The generator merges both sources into a unified MasterDataset. +**Gherkin feature files** own planning metadata (status, phase, deliverables). The generator merges both sources into a unified PatternGraph. -**Pipeline:** `Config → Scanner → Extractor → Transformer → Codec` — files become patterns, patterns become a MasterDataset, the MasterDataset renders to Markdown and JSON. +**Pipeline:** `Config → Scanner → Extractor → Transformer → Codec` — files become patterns, patterns become a PatternGraph, the PatternGraph renders to Markdown and JSON. --- diff --git a/_claude-md/api/mcp-server.md b/_claude-md/api/mcp-server.md index 906d293e..9f6b0f99 100644 --- a/_claude-md/api/mcp-server.md +++ b/_claude-md/api/mcp-server.md @@ -1,6 +1,6 @@ ### MCP Server — Native AI Context Tools -When the MCP server is running, **use `architect_*` tools instead of CLI commands** (`pnpm architect:query --`). The MCP server keeps the MasterDataset in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same ProcessStateAPI methods available via CLI. +When the MCP server is running, **use `architect_*` tools instead of CLI commands** (`pnpm architect:query --`). The MCP server keeps the PatternGraph in memory — tool calls dispatch in sub-milliseconds vs 2-5 seconds for CLI subprocess invocations. All 25 tools wrap the same PatternGraphAPI methods available via CLI. #### Session Start (MCP Protocol) diff --git a/_claude-md/core/architecture.md b/_claude-md/core/architecture.md index 36d3bbd0..371465a2 100644 --- a/_claude-md/core/architecture.md +++ b/_claude-md/core/architecture.md @@ -2,13 +2,13 @@ ``` CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - (files) (patterns) (MasterDataset) (Markdown) + (files) (patterns) (PatternGraph) (Markdown) ``` 1. **Scanner** (`src/scanner/`): File discovery, AST parsing, opt-in detection via `@architect` marker 2. **Extractor** (`src/extractor/`): Pattern extraction from TypeScript JSDoc and Gherkin tags -3. **Transformer** (`src/generators/pipeline/`): Builds MasterDataset with pre-computed views -4. **Codec** (`src/renderable/`): Zod 4 codecs transform MasterDataset → RenderableDocument → Markdown +3. **Transformer** (`src/generators/pipeline/`): Builds PatternGraph with pre-computed views +4. **Codec** (`src/renderable/`): Zod 4 codecs transform PatternGraph → RenderableDocument → Markdown ### Key Design Patterns @@ -16,8 +16,8 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - **Schema-First**: Zod schemas in `src/validation-schemas/` define types with runtime validation - **Registry Pattern**: Tag registry (`src/taxonomy/`) defines categories, status values, and tag formats - **Codec-Based Rendering**: Generators in `src/generators/` use codecs to transform data to markdown -- **Pipeline Factory**: Shared `buildMasterDataset()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. -- **Single Read Model** (ADR-006): MasterDataset is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. +- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. +- **Single Read Model** (ADR-006): PatternGraph is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. **Live module inventory:** `pnpm architect:query -- arch context` and `pnpm architect:query -- arch layer` @@ -25,13 +25,13 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC Architecture and process decisions are recorded as annotated Gherkin specs in `architect/decisions/`: -| Spec | Key Decision | -| ------- | -------------------------------------------------------------------------- | -| ADR-001 | Taxonomy canonical values — tag registry is the single source of truth | -| ADR-002 | Gherkin-only testing — no `.test.ts` files, all tests are `.feature` | -| ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | -| ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | -| ADR-006 | Single read model — MasterDataset is the sole read model for all consumers | -| PDR-001 | Session workflow commands — Process Data API CLI design decisions | +| Spec | Key Decision | +| ------- | ------------------------------------------------------------------------- | +| ADR-001 | Taxonomy canonical values — tag registry is the single source of truth | +| ADR-002 | Gherkin-only testing — no `.test.ts` files, all tests are `.feature` | +| ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | +| ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | +| ADR-006 | Single read model — PatternGraph is the sole read model for all consumers | +| PDR-001 | Session workflow commands — Process Data API CLI design decisions | Query decisions: `pnpm architect:query -- decisions ` diff --git a/_claude-md/core/project-overview.md b/_claude-md/core/project-overview.md index 9d3f34a0..e6ec0d49 100644 --- a/_claude-md/core/project-overview.md +++ b/_claude-md/core/project-overview.md @@ -7,7 +7,7 @@ Context engineering platform with extraction pipeline and typed codecs. Extracts **Key Capabilities:** - Pattern extraction from TypeScript JSDoc and Gherkin tags -- MasterDataset transformation with pre-computed views (O(1) access) +- PatternGraph transformation with pre-computed views (O(1) access) - Codec-based markdown generation with progressive disclosure - FSM-enforced delivery workflow validation via pre-commit hooks diff --git a/_claude-md/metadata.json b/_claude-md/metadata.json index 67d88bce..25b88322 100644 --- a/_claude-md/metadata.json +++ b/_claude-md/metadata.json @@ -50,7 +50,7 @@ { "path": "api/mcp-server.md", "tags": ["core"], - "description": "MCP server tools for native AI agent access to ProcessStateAPI" + "description": "MCP server tools for native AI agent access to PatternGraphAPI" } ] }, diff --git a/_claude-md/testing/test-implementation.md b/_claude-md/testing/test-implementation.md index 1bece84f..e63857c0 100644 --- a/_claude-md/testing/test-implementation.md +++ b/_claude-md/testing/test-implementation.md @@ -29,9 +29,9 @@ The project has strict linting rules. Save time by coding defensively. ```typescript // debug-codec.ts import { RemainingWorkCodec } from './src/renderable/codecs/session.js'; -import { createTestMasterDataset } from './tests/fixtures/dataset-factories.js'; +import { createTestPatternGraph } from './tests/fixtures/dataset-factories.js'; -const dataset = createTestMasterDataset({ ... }); +const dataset = createTestPatternGraph({ ... }); const doc = RemainingWorkCodec.decode(dataset); console.log(JSON.stringify(doc.sections, null, 2)); ``` diff --git a/architect.config.ts b/architect.config.ts index ec32f617..e21d150d 100644 --- a/architect.config.ts +++ b/architect.config.ts @@ -61,7 +61,7 @@ const INDEX_DOCUMENT_ENTRIES: readonly DocumentEntry[] = [ { title: 'Process API Recipes', path: 'reference/PROCESS-API-RECIPES.md', description: 'CLI workflow recipes and session guides', audience: 'AI/Devs', topic: 'Reference Guides' }, { title: 'Process Guard Reference', path: 'reference/PROCESS-GUARD-REFERENCE.md', description: 'Pre-commit hooks, error codes, programmatic API', audience: 'Team Leads', topic: 'Reference Guides' }, { title: 'Architecture Codecs', path: 'reference/ARCHITECTURE-CODECS.md', description: 'All codecs with factory patterns and options', audience: 'Developers', topic: 'Reference Guides' }, - { title: 'Architecture Types', path: 'reference/ARCHITECTURE-TYPES.md', description: 'MasterDataset interface and type shapes', audience: 'Developers', topic: 'Reference Guides' }, + { title: 'Architecture Types', path: 'reference/ARCHITECTURE-TYPES.md', description: 'PatternGraph interface and type shapes', audience: 'Developers', topic: 'Reference Guides' }, { title: 'Configuration Guide', path: 'reference/CONFIGURATION-GUIDE.md', description: 'Presets, config files, sources, output, and monorepo setup', audience: 'Users', topic: 'Reference Guides' }, { title: 'Validation Tools Guide', path: 'reference/VALIDATION-TOOLS-GUIDE.md', description: 'lint-patterns, lint-steps, lint-process, validate-patterns reference', audience: 'CI/CD', topic: 'Reference Guides' }, { title: 'Gherkin Authoring Guide', path: 'reference/GHERKIN-AUTHORING-GUIDE.md', description: 'Roadmap specs, Rule blocks, DataTables, tag conventions', audience: 'Developers', topic: 'Reference Guides' }, @@ -115,7 +115,7 @@ export default defineConfig({ { title: 'Architecture Types Reference', conventionTags: ['pipeline-architecture'], - shapeSelectors: [{ group: 'master-dataset' }], + shapeSelectors: [{ group: 'pattern-graph' }], behaviorCategories: [], shapesFirst: true, claudeMdSection: 'architecture', @@ -123,8 +123,8 @@ export default defineConfig({ claudeMdFilename: 'architecture-types.md', diagramScopes: [ { - title: 'MasterDataset View Fan-out', - source: 'master-dataset-views', + title: 'PatternGraph View Fan-out', + source: 'pattern-graph-views', }, ], }, diff --git a/architect/decisions/adr-003-source-first-pattern-architecture.feature b/architect/decisions/adr-003-source-first-pattern-architecture.feature index 6b42a0bd..47c2381c 100644 --- a/architect/decisions/adr-003-source-first-pattern-architecture.feature +++ b/architect/decisions/adr-003-source-first-pattern-architecture.feature @@ -125,7 +125,7 @@ Feature: ADR-003 - Source-First Pattern Architecture **Invariant:** `@architect-pattern:X` may appear in exactly one file across the entire codebase. The `mergePatterns()` conflict check in `orchestrator.ts` correctly enforces this. - **Rationale:** Duplicate pattern definitions cause merge conflicts in the MasterDataset and produce ambiguous ownership in generated documentation. + **Rationale:** Duplicate pattern definitions cause merge conflicts in the PatternGraph and produce ambiguous ownership in generated documentation. **Verified by:** TypeScript source is canonical pattern definition **Migration path for existing conflicts:** diff --git a/architect/decisions/adr-005-codec-based-markdown-rendering.feature b/architect/decisions/adr-005-codec-based-markdown-rendering.feature index 1012f439..2d899e30 100644 --- a/architect/decisions/adr-005-codec-based-markdown-rendering.feature +++ b/architect/decisions/adr-005-codec-based-markdown-rendering.feature @@ -12,7 +12,7 @@ Feature: ADR-005 - Codec-Based Markdown Rendering **Context:** The documentation generator needs to transform structured pattern data - (MasterDataset) into markdown files. The initial approach used direct + (PatternGraph) into markdown files. The initial approach used direct string concatenation in generator functions, mixing data selection, formatting logic, and output assembly in a single pass. This made generators hard to test, difficult to compose, and impossible to @@ -21,7 +21,7 @@ Feature: ADR-005 - Codec-Based Markdown Rendering **Decision:** Adopt a codec architecture inspired by serialization codecs (encode/decode). - Each document type has a codec that decodes a MasterDataset into a + Each document type has a codec that decodes a PatternGraph into a RenderableDocument — an intermediate representation of sections, headings, tables, paragraphs, and code blocks. A separate renderer transforms the RenderableDocument into markdown. This separates data selection (what to @@ -65,14 +65,14 @@ Feature: ADR-005 - Codec-Based Markdown Rendering Rule: Codecs implement a decode-only contract - **Invariant:** Every codec is a pure function that accepts a MasterDataset + **Invariant:** Every codec is a pure function that accepts a PatternGraph and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. **Rationale:** Pure functions are deterministic and trivially testable. - For the same MasterDataset, a codec always produces the same + For the same PatternGraph, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. @@ -80,7 +80,7 @@ Feature: ADR-005 - Codec-Based Markdown Rendering """typescript interface DocumentCodec { - decode(dataset: MasterDataset): RenderableDocument; + decode(dataset: PatternGraph): RenderableDocument; } """ @@ -89,13 +89,13 @@ Feature: ADR-005 - Codec-Based Markdown Rendering @acceptance-criteria @happy-path Scenario: Codec produces deterministic output - Given a MasterDataset with 3 patterns + Given a PatternGraph with 3 patterns When the same codec decodes the dataset twice Then both RenderableDocuments are structurally identical @acceptance-criteria @validation Scenario: Codec has no side effects - Given a MasterDataset passed to a codec + Given a PatternGraph passed to a codec When the codec completes decoding Then the original dataset is unmodified And no files were written to disk diff --git a/architect/decisions/adr-006-single-read-model-architecture.feature b/architect/decisions/adr-006-single-read-model-architecture.feature index f878bed4..ed81518a 100644 --- a/architect/decisions/adr-006-single-read-model-architecture.feature +++ b/architect/decisions/adr-006-single-read-model-architecture.feature @@ -13,49 +13,49 @@ Feature: ADR-006 - Single Read Model Architecture **Context:** The Architect package applies event sourcing to itself: git is the event store, annotated source files are authoritative state, generated - documentation is a projection. The MasterDataset is the read model — + documentation is a projection. The PatternGraph is the read model — produced by a single-pass O(n) transformer with pre-computed views and a relationship index. - ADR-005 established that codecs consume MasterDataset as their sole input. - The ProcessStateAPI consumes it. But the validation layer bypasses it, + ADR-005 established that codecs consume PatternGraph as their sole input. + The PatternGraphAPI consumes it. But the validation layer bypasses it, wiring its own mini-pipeline from raw scanner/extractor output. It creates a lossy local type that discards relationship data, then discovers it lacks the information needed — requiring ad-hoc re-derivation of what - the MasterDataset already computes. + the PatternGraph already computes. - This is the same class of problem the MasterDataset was created to solve. + This is the same class of problem the PatternGraph was created to solve. Before the single-pass transformer, each generator called `.filter()` - independently. The MasterDataset eliminated that duplication for codecs. + independently. The PatternGraph eliminated that duplication for codecs. This ADR extends the same principle to all consumers. **Decision:** - The MasterDataset is the single read model for all consumers. No consumer + The PatternGraph is the single read model for all consumers. No consumer re-derives pattern data from raw scanner/extractor output when that data - is available in the MasterDataset. Validators, codecs, and query APIs + is available in the PatternGraph. Validators, codecs, and query APIs consume the same pre-computed read model. **Consequences:** | Type | Impact | | Positive | Relationship resolution happens once — no consumer re-derives implements, uses, or dependsOn | | Positive | Eliminates lossy local types that discard fields from canonical ExtractedPattern | - | Positive | Validation rules automatically benefit from new MasterDataset views and indices | + | Positive | Validation rules automatically benefit from new PatternGraph views and indices | | Positive | Aligns with the monorepo's own ADR-006: projections for all reads, never query aggregate state | | Negative | Validators that today only need stage 1-2 data will import the transformer | - | Negative | MasterDataset schema changes affect more consumers | + | Negative | PatternGraph schema changes affect more consumers | Rule: All feature consumers query the read model, not raw state **Invariant:** Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the - MasterDataset. Direct scanner/extractor imports are permitted only in - pipeline orchestration code that builds the MasterDataset. - **Rationale:** Bypassing the read model forces consumers to re-derive data that the MasterDataset already computes, creating duplicate logic and divergent behavior when the pipeline evolves. - **Verified by:** Feature consumers import from MasterDataset not from raw pipeline stages + PatternGraph. Direct scanner/extractor imports are permitted only in + pipeline orchestration code that builds the PatternGraph. + **Rationale:** Bypassing the read model forces consumers to re-derive data that the PatternGraph already computes, creating duplicate logic and divergent behavior when the pipeline evolves. + **Verified by:** Feature consumers import from PatternGraph not from raw pipeline stages | Layer | May Import | Examples | | Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, process-api.ts pipeline setup | - | Feature Consumption | MasterDataset, relationshipIndex | codecs, ProcessStateAPI, validators, query handlers | + | Feature Consumption | PatternGraph, relationshipIndex | codecs, PatternGraphAPI, validators, query handlers | Exception: `lint-patterns.ts` is a pure stage-1 consumer. It validates annotation syntax on scanned files. No relationships, no cross-source @@ -67,24 +67,24 @@ Feature: ADR-006 - Single Read Model Architecture discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. - **Rationale:** Lossy local types silently drop fields that later become needed, causing bugs that only surface when new MasterDataset capabilities are added and the local type lacks them. - **Verified by:** Feature consumers import from MasterDataset not from raw pipeline stages + **Rationale:** Lossy local types silently drop fields that later become needed, causing bugs that only surface when new PatternGraph capabilities are added and the local type lacks them. + **Verified by:** Feature consumers import from PatternGraph not from raw pipeline stages Rule: Relationship resolution is computed once **Invariant:** Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in - `transformToMasterDataset()`. No consumer re-derives these from raw + `transformToPatternGraph()`. No consumer re-derives these from raw pattern arrays or scanned file tags. **Rationale:** Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. - **Verified by:** Feature consumers import from MasterDataset not from raw pipeline stages + **Verified by:** Feature consumers import from PatternGraph not from raw pipeline stages Rule: Three named anti-patterns **Invariant:** These are recognized violations, serving as review criteria for new code and refactoring targets for existing code. **Rationale:** Without named anti-patterns, violations appear as one-off style issues rather than systematic architectural drift, making them harder to detect and communicate in code review. - **Verified by:** Feature consumers import from MasterDataset not from raw pipeline stages + **Verified by:** Feature consumers import from PatternGraph not from raw pipeline stages | Anti-Pattern | Detection Signal | | Parallel Pipeline | Feature consumer imports from scanner/ or extractor/ | @@ -98,7 +98,7 @@ Feature: ADR-006 - Single Read Model Architecture """typescript // Good: consume the read model - function validateCrossSource(dataset: RuntimeMasterDataset): ValidationSummary { + function validateCrossSource(dataset: RuntimePatternGraph): ValidationSummary { const rel = dataset.relationshipIndex[patternName]; const isImplemented = rel.implementedBy.length > 0; } @@ -113,12 +113,12 @@ Feature: ADR-006 - Single Read Model Architecture **References** - Monorepo ADR-006: Projections for All Reads (same principle, application domain) - - ADR-005: Codec-Based Markdown Rendering (established MasterDataset as codec input) + - ADR-005: Codec-Based Markdown Rendering (established PatternGraph as codec input) - Order-management ARCHITECTURE.md: CommandOrchestrator + Read Model separation @acceptance-criteria - Scenario: Feature consumers import from MasterDataset not from raw pipeline stages + Scenario: Feature consumers import from PatternGraph not from raw pipeline stages Given a feature consumer that needs pattern relationships or status groupings When reviewing its import statements - Then it imports from MasterDataset or relationshipIndex + Then it imports from PatternGraph or relationshipIndex And it does not import directly from scanner/ or extractor/ modules diff --git a/architect/design-reviews/mcp-server-integration.md b/architect/design-reviews/mcp-server-integration.md index d8fbe129..b0e5ea2e 100644 --- a/architect/design-reviews/mcp-server-integration.md +++ b/architect/design-reviews/mcp-server-integration.md @@ -55,7 +55,7 @@ sequenceDiagram mcp_server->>mcp_server: exit(1) end - Note over mcp_server: Rule 3 — 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. + Note over mcp_server: Rule 3 — 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. mcp_server->>+pipeline_session: ToolCallRequest pipeline_session-->>-mcp_server: ToolCallResult diff --git a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature index 2d39df18..83a10607 100644 --- a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature +++ b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature @@ -24,7 +24,7 @@ Feature: Process API Layered Extraction — Investigation Findings **Domain Logic** (~500+ lines): handleRules (183 lines), handleStubs (42 lines), handleDecisions (39 lines), handlePdr (65 lines), plus supporting types and helpers. These are feature consumers of the - MasterDataset that belong in src/api/ modules. + PatternGraph that belong in src/api/ modules. | Handler | Lines | Complexity | API Counterpart Exists? | | handleRules | 1096-1279 | High: nested Map hierarchies, parseBusinessRuleAnnotations | No — needs src/api/rules-query.ts | @@ -52,7 +52,7 @@ Feature: Process API Layered Extraction — Investigation Findings The Process Guard (derive-state.ts) is a partial consumer. It only scans Gherkin files and extracts deliverables for FSM state derivation. - It does NOT need a full MasterDataset — its use case is lightweight + It does NOT need a full PatternGraph — its use case is lightweight state derivation from annotations, not feature consumption. **Design question for the pipeline factory:** Should derive-state.ts @@ -82,7 +82,7 @@ Feature: Process API Layered Extraction — Investigation Findings should be: | Input | Type | Source | - | dataset | RuntimeMasterDataset | Pipeline output | + | dataset | RuntimePatternGraph | Pipeline output | | filters | RulesFilters | Parsed from subArgs | | modifiers | OutputModifiers | --count, --names-only | @@ -100,11 +100,11 @@ Feature: Process API Layered Extraction — Investigation Findings | Pattern merging | mergePatterns() | mergePatterns() | | Hierarchy | computeHierarchyChildren() | computeHierarchyChildren() | | Workflow | loadDefaultWorkflow() | loadDefaultWorkflow() or loadWorkflowFromPath() | - | Transform | transformToMasterDataset() | transformToMasterDatasetWithValidation() | + | Transform | transformToPatternGraph() | transformToPatternGraphWithValidation() | The pipeline factory must accommodate both: orchestrator needs the - basic MasterDataset, process-api needs the validation summary too. - transformToMasterDatasetWithValidation returns both — the factory + basic PatternGraph, process-api needs the validation summary too. + transformToPatternGraphWithValidation returns both — the factory should return TransformResult and let callers destructure what they need. Rule: Suggestions for deeper analysis in a dedicated design session @@ -142,7 +142,7 @@ Feature: Process API Layered Extraction — Investigation Findings **5. Test strategy** The extracted API modules (rules-query.ts, etc.) become independently - testable with mock MasterDataset inputs. This is a major testability + testable with mock PatternGraph inputs. This is a major testability improvement. The design session should define the test approach: Gherkin feature files (consistent with project policy) using factory - helpers to build test MasterDataset instances. + helpers to build test PatternGraph instances. diff --git a/architect/specs/architecture-diagram-core.feature b/architect/specs/architecture-diagram-core.feature index 7f95180d..af9392dc 100644 --- a/architect/specs/architecture-diagram-core.feature +++ b/architect/specs/architecture-diagram-core.feature @@ -35,7 +35,7 @@ Feature: Architecture Diagram Generation - Core | DocDirective schema fields | complete | validation-schemas/doc-directive.ts | Yes | unit | | ExtractedPattern schema fields | complete | validation-schemas/extracted-pattern.ts | Yes | unit | | AST parser tag extraction | complete | scanner/ast-parser.ts | Yes | unit | - | MasterDataset archIndex | complete | generators/pipeline/transform-dataset.ts | Yes | unit | + | PatternGraph archIndex | complete | generators/pipeline/transform-dataset.ts | Yes | unit | | ArchitectureCodec (component) | complete | renderable/codecs/architecture.ts | Yes | unit | # ============================================================================ @@ -172,12 +172,12 @@ Feature: Architecture Diagram Generation - Core And the directive should have archLayer undefined # ============================================================================ - # RULE 3: MasterDataset ArchIndex + # RULE 3: PatternGraph ArchIndex # ============================================================================ - Rule: MasterDataset builds archIndex during transformation + Rule: PatternGraph builds archIndex during transformation - **Invariant:** The `transformToMasterDataset` function must build an `archIndex` + **Invariant:** The `transformToPatternGraph` function must build an `archIndex` that groups patterns by role, context, and layer for efficient diagram generation. **Rationale:** Single-pass extraction during dataset transformation avoids @@ -193,7 +193,7 @@ Feature: Architecture Diagram Generation - Core | Handler1 | command-handler | | Handler2 | command-handler | | Projection1 | projection | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex.byRole["command-handler"] contains 2 patterns And archIndex.byRole["projection"] contains 1 pattern @@ -204,7 +204,7 @@ Feature: Architecture Diagram Generation - Core | OrderHandler | orders | | OrderProjection | orders | | InventoryHandler | inventory | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex.byContext["orders"] contains 2 patterns And archIndex.byContext["inventory"] contains 1 pattern @@ -215,7 +215,7 @@ Feature: Architecture Diagram Generation - Core | Decider1 | domain | | Handler1 | application | | Infra1 | infrastructure | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex.byLayer["domain"] contains 1 pattern And archIndex.byLayer["application"] contains 1 pattern And archIndex.byLayer["infrastructure"] contains 1 pattern @@ -228,7 +228,7 @@ Feature: Architecture Diagram Generation - Core | WithRole | saga | - | - | | WithContext | - | inventory | - | | NoArchTags | - | - | - | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex.all contains 3 patterns And archIndex.all does not contain "NoArchTags" diff --git a/architect/specs/architecture-doc-refactoring.feature b/architect/specs/architecture-doc-refactoring.feature index 4f32a138..32220c9d 100644 --- a/architect/specs/architecture-doc-refactoring.feature +++ b/architect/specs/architecture-doc-refactoring.feature @@ -13,7 +13,7 @@ Feature: Architecture Document Refactoring **Problem:** ARCHITECTURE.md is 1,287 lines of manually-maintained documentation covering 14 sections. The codec system already generates much of this content (codec references - via convention tags, MasterDataset types via shape extraction, pipeline diagrams + via convention tags, PatternGraph types via shape extraction, pipeline diagrams via architecture annotations). Maintaining parallel manual and generated versions creates drift and duplication. @@ -37,7 +37,7 @@ Feature: Architecture Document Refactoring | Executive Summary | 28-69 | Keep | Editorial narrative | | Configuration Architecture | 70-139 | Phase 4: absorb | Configuration product area | | Four-Stage Pipeline | 140-343 | Keep, trim | Editorial narrative (core concepts) | - | Unified Transformation | 345-478 | Phase 4: generate | Shapes reference doc (MasterDataset types) | + | Unified Transformation | 345-478 | Phase 4: generate | Shapes reference doc (PatternGraph types) | | Codec Architecture | 481-527 | Keep | Editorial narrative (concepts only) | | Available Codecs | 529-534 | Phase 2: done | Pointer to ARCHITECTURE-CODECS.md | | Progressive Disclosure | 535-584 | Keep | Editorial narrative | @@ -58,7 +58,7 @@ Feature: Architecture Document Refactoring | Convention-extractor heading match bugfix | complete | src/renderable/codecs/convention-extractor.ts | Yes | unit | | Available Codecs section replaced with pointer | complete | docs/ARCHITECTURE.md | No | n/a | | Configuration Architecture to product area | complete | docs/ARCHITECTURE.md | Yes | integration | - | MasterDataset Schema to shapes reference | complete | docs/ARCHITECTURE.md | Yes | integration | + | PatternGraph Schema to shapes reference | complete | docs/ARCHITECTURE.md | Yes | integration | | Source Systems to Annotation product area | complete | docs/ARCHITECTURE.md | Yes | integration | | Data Flow Diagrams to architecture diagrams | complete | docs/ARCHITECTURE.md | Yes | integration | | Workflow Integration to Process product area | complete | docs/ARCHITECTURE.md | Yes | integration | @@ -207,7 +207,7 @@ Feature: Architecture Document Refactoring for its content type. **Verified by:** Product area absorption captures equivalent content, - Shape reference covers MasterDataset documentation, + Shape reference covers PatternGraph documentation, No content is lost in routing @acceptance-criteria @happy-path @@ -219,10 +219,10 @@ Feature: Architecture Document Refactoring And the ARCHITECTURE.md section can be replaced with a pointer @acceptance-criteria @happy-path - Scenario: Shape reference covers MasterDataset documentation - Given the Unified Transformation section with MasterDataset schema + Scenario: Shape reference covers PatternGraph documentation + Given the Unified Transformation section with PatternGraph schema And TypeScript types tagged with @architect-shape in the source - When a shapes reference doc config targets MasterDataset types + When a shapes reference doc config targets PatternGraph types Then the generated shapes section contains the same type definitions And the manual schema documentation can be replaced @@ -287,35 +287,35 @@ Feature: Architecture Document Refactoring Then the annotation format examples appear in the Four-Stage Pipeline section And the examples explain how to read and write architect tags - Rule: MasterDataset shapes generate a dedicated ARCHITECTURE-TYPES reference document + Rule: PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document **Invariant:** DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using - shapeSelectors with group master-dataset to extract MasterDataset schema types, - RuntimeMasterDataset, RawDataset, PipelineOptions, and PipelineResult. Source files - tagged with @architect-shape master-dataset and @architect-include master-dataset + shapeSelectors with group master-dataset to extract PatternGraph schema types, + RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files + tagged with @architect-shape pattern-graph and @architect-include master-dataset contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. - **Rationale:** The MasterDataset is the central data structure -- the sole read model + **Rationale:** The PatternGraph is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md. - **Verified by:** MasterDataset shapes extracted into reference doc, + **Verified by:** PatternGraph shapes extracted into reference doc, Pipeline types included alongside schema types, Unified Transformation section replaced with pointer @acceptance-criteria @happy-path - Scenario: MasterDataset shapes extracted via shape selectors - Given source files tagged with @architect-shape master-dataset + Scenario: PatternGraph shapes extracted via shape selectors + Given source files tagged with @architect-shape pattern-graph And a ReferenceDocConfig with shapeSelectors targeting master-dataset group When the reference codec generates ARCHITECTURE-TYPES.md - Then MasterDatasetSchema, RuntimeMasterDataset, and RawDataset types appear + Then PatternGraphSchema, RuntimePatternGraph, and RawDataset types appear And each shape includes its TypeScript declaration and JSDoc description @acceptance-criteria @happy-path Scenario: Pipeline types included in ARCHITECTURE-TYPES reference doc - Given PipelineOptions and PipelineResult tagged with @architect-shape master-dataset + Given PipelineOptions and PipelineResult tagged with @architect-shape pattern-graph And @architect-include master-dataset on their source files When the reference codec generates ARCHITECTURE-TYPES.md Then PipelineOptions and PipelineResult shapes appear in the API Types section @@ -324,10 +324,10 @@ Feature: Architecture Document Refactoring @acceptance-criteria @happy-path Scenario: Unified Transformation section replaced with pointer and narrative Given the Unified Transformation section in ARCHITECTURE.md (L345-478) - And ARCHITECTURE-TYPES.md generated with MasterDataset shapes + And ARCHITECTURE-TYPES.md generated with PatternGraph shapes When the section is consolidated Then the section is replaced with a condensed narrative and pointer - And the narrative explains MasterDataset role as the sole read model + And the narrative explains PatternGraph role as the sole read model And no type definitions remain in ARCHITECTURE.md Rule: Pipeline architecture convention content replaces ASCII data flow diagrams @@ -336,7 +336,7 @@ Feature: Architecture Document Refactoring diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer - architecture. A new master-dataset-views hardcoded diagram source generates a + architecture. A new pattern-graph-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document. @@ -360,12 +360,12 @@ Feature: Architecture Document Refactoring And consumer architecture patterns from build-pipeline.ts appear @acceptance-criteria @happy-path - Scenario: master-dataset-views diagram source generates Mermaid fan-out diagram - Given master-dataset-views added to DIAGRAM_SOURCE_VALUES in reference.ts - And buildMasterDatasetViewsDiagram builder function implemented - And ARCHITECTURE-TYPES.md config includes master-dataset-views in diagramScopes + Scenario: pattern-graph-views diagram source generates Mermaid fan-out diagram + Given pattern-graph-views added to DIAGRAM_SOURCE_VALUES in reference.ts + And buildPatternGraphViewsDiagram builder function implemented + And ARCHITECTURE-TYPES.md config includes pattern-graph-views in diagramScopes When the reference codec generates the document - Then a Mermaid diagram showing MasterDataset view fan-out is rendered + Then a Mermaid diagram showing PatternGraph view fan-out is rendered And the diagram appears in both detailed and compact outputs @acceptance-criteria @happy-path diff --git a/architect/specs/cli-recipe-codec.feature b/architect/specs/cli-recipe-codec.feature index c762977a..cd82202c 100644 --- a/architect/specs/cli-recipe-codec.feature +++ b/architect/specs/cli-recipe-codec.feature @@ -105,10 +105,10 @@ Feature: CLI Recipe Codec And neither generator imports nor depends on the other @acceptance-criteria @validation - Scenario: Recipe generator has no MasterDataset dependency + Scenario: Recipe generator has no PatternGraph dependency Given the CliRecipeGenerator source file When inspecting its import statements - Then it does not import MasterDataset or any pipeline module + Then it does not import PatternGraph or any pipeline module And it imports only from src/cli/cli-schema.ts and generator infrastructure Rule: Recipe content uses a structured schema extension diff --git a/architect/specs/codec-behavior-testing.feature b/architect/specs/codec-behavior-testing.feature index 030fed6f..e4f9d437 100644 --- a/architect/specs/codec-behavior-testing.feature +++ b/architect/specs/codec-behavior-testing.feature @@ -20,7 +20,7 @@ Feature: Codec Behavior Testing **Solution:** Create behavior specs for each untested codec covering: - - Input transformation (MasterDataset to RenderableDocument) + - Input transformation (PatternGraph to RenderableDocument) - Output structure (correct sections, headings, content) - Edge cases (empty data, missing fields) @@ -65,28 +65,28 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: RoadmapDocumentCodec groups by phase - Given MasterDataset with patterns in phases 15, 16, 17 + Given PatternGraph with patterns in phases 15, 16, 17 When RoadmapDocumentCodec transforms dataset Then document has sections for each phase And patterns are grouped under their phase headings @acceptance-criteria @happy-path Scenario: CompletedMilestonesCodec shows only completed - Given MasterDataset with completed and roadmap patterns + Given PatternGraph with completed and roadmap patterns When CompletedMilestonesCodec transforms dataset Then document only includes completed patterns And completion dates are shown @acceptance-criteria @happy-path Scenario: CurrentWorkCodec shows only active - Given MasterDataset with active, roadmap, and completed patterns + Given PatternGraph with active, roadmap, and completed patterns When CurrentWorkCodec transforms dataset Then document only includes active patterns And current progress is highlighted @acceptance-criteria @validation Scenario: Empty dataset produces minimal output - Given MasterDataset with no patterns + Given PatternGraph with no patterns When RoadmapDocumentCodec transforms dataset Then document has title and purpose And content section indicates no planned work @@ -108,7 +108,7 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: SessionContextCodec includes active pattern details - Given MasterDataset with active pattern "FeatureX" + Given PatternGraph with active pattern "FeatureX" And pattern has 3 deliverables (2 complete, 1 pending) When SessionContextCodec transforms dataset Then document includes FeatureX with deliverable status @@ -116,7 +116,7 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: RemainingWorkCodec aggregates by phase - Given MasterDataset with incomplete patterns in phases 15, 16 + Given PatternGraph with incomplete patterns in phases 15, 16 When RemainingWorkCodec transforms dataset Then document groups remaining work by phase And total effort remaining is calculated @@ -138,14 +138,14 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: RequirementsDocumentCodec includes full feature descriptions - Given MasterDataset with pattern having Problem/Solution description + Given PatternGraph with pattern having Problem/Solution description When RequirementsDocumentCodec transforms dataset Then document includes Problem and Solution sections And business value table is rendered @acceptance-criteria @happy-path Scenario: Acceptance criteria have bold keywords - Given MasterDataset with pattern having acceptance scenarios + Given PatternGraph with pattern having acceptance scenarios When RequirementsDocumentCodec transforms dataset Then scenario steps have bold Given/When/Then keywords @@ -166,14 +166,14 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: ChangelogCodec follows Keep a Changelog format - Given MasterDataset with patterns tagged to releases v0.1.0, v0.2.0 + Given PatternGraph with patterns tagged to releases v0.1.0, v0.2.0 When ChangelogCodec transforms dataset Then document has sections for each release version And Unreleased section shows untagged changes @acceptance-criteria @happy-path Scenario: TraceabilityCodec maps rules to scenarios - Given MasterDataset with patterns having Rules and Verified by annotations + Given PatternGraph with patterns having Rules and Verified by annotations When TraceabilityCodec transforms dataset Then document includes Rule-to-Scenario matrix And unverified rules are listed separately @@ -195,14 +195,14 @@ Feature: Codec Behavior Testing @acceptance-criteria @happy-path Scenario: PlanningChecklistCodec includes deliverables - Given MasterDataset with active pattern having 5 deliverables + Given PatternGraph with active pattern having 5 deliverables When PlanningChecklistCodec transforms dataset Then document includes checklist with all deliverables And status checkboxes reflect completion state @acceptance-criteria @happy-path Scenario: SessionFindingsCodec captures discoveries - Given MasterDataset with pattern having @discovered-gap annotations + Given PatternGraph with pattern having @discovered-gap annotations When SessionFindingsCodec transforms dataset Then document includes Discoveries section And gaps, improvements, and risks are categorized diff --git a/architect/specs/codec-driven-reference-generation.feature b/architect/specs/codec-driven-reference-generation.feature index 1cc76689..1abf901e 100644 --- a/architect/specs/codec-driven-reference-generation.feature +++ b/architect/specs/codec-driven-reference-generation.feature @@ -62,14 +62,14 @@ Feature: Codec-Driven Reference Generation @acceptance-criteria @happy-path Scenario: Config with matching data produces a complete document Given a ReferenceDocConfig with convention tags and shape sources - And a MasterDataset with patterns matching those tags and sources + And a PatternGraph with patterns matching those tags and sources When the reference codec renders the document Then the output contains convention sections, shape sections, and metadata @acceptance-criteria @edge-case Scenario: Config with no matching data produces fallback content Given a ReferenceDocConfig with tags that match no patterns - And an empty MasterDataset + And an empty PatternGraph When the reference codec renders the document Then the output contains "No content found" fallback message @@ -98,7 +98,7 @@ Feature: Codec-Driven Reference Generation @acceptance-criteria @happy-path Scenario: Empty sources are omitted gracefully Given a config with only convention tags (no shapes, no behaviors, no diagrams) - And a MasterDataset with matching conventions + And a PatternGraph with matching conventions When the reference codec renders the document Then only convention sections appear And no empty placeholder sections exist diff --git a/architect/specs/data-api-cli-ergonomics.feature b/architect/specs/data-api-cli-ergonomics.feature index 90c52530..4588a4cf 100644 --- a/architect/specs/data-api-cli-ergonomics.feature +++ b/architect/specs/data-api-cli-ergonomics.feature @@ -19,7 +19,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode **Solution:** Add performance and ergonomic improvements: - 1. **Pipeline caching** -- Cache MasterDataset to temp file with mtime invalidation + 1. **Pipeline caching** -- Cache PatternGraph to temp file with mtime invalidation 2. **REPL mode** -- `process-api repl` keeps pipeline loaded for interactive queries 3. **FSM short-circuit** -- FSM queries skip the scan pipeline entirely 4. **Per-subcommand help** -- `process-api --help` with examples @@ -36,7 +36,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | MasterDataset cache with mtime invalidation | complete | src/cli/dataset-cache.ts | Yes | unit | + | PatternGraph cache with mtime invalidation | complete | src/cli/dataset-cache.ts | Yes | unit | | REPL mode handler | complete | src/cli/repl.ts | Yes | integration | | FSM short-circuit for static queries | complete | src/cli/process-api.ts | Yes | unit | | Per-subcommand help system | complete | src/cli/process-api.ts | Yes | integration | @@ -47,14 +47,14 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode # RULE 1: Pipeline Caching # ============================================================================ - Rule: MasterDataset is cached between invocations with file-change invalidation + Rule: PatternGraph is cached between invocations with file-change invalidation **Invariant:** Cache is automatically invalidated when any source file (TypeScript or Gherkin) has a modification time newer than the cache. **Rationale:** 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 + -- 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. @@ -62,7 +62,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode @acceptance-criteria @happy-path Scenario: Second query uses cached dataset - Given a previous query has cached the MasterDataset + Given a previous query has cached the PatternGraph And no source files have been modified since When running "process-api status" Then the query completes in under 200ms @@ -70,7 +70,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode @acceptance-criteria @happy-path Scenario: Cache invalidated on source file change - Given a cached MasterDataset exists + Given a cached PatternGraph exists And a source TypeScript file has been modified When running "process-api status" Then the pipeline runs fresh (cache miss) diff --git a/architect/specs/data-api-context-assembly.feature b/architect/specs/data-api-context-assembly.feature index 60ed8bbf..df7b650b 100644 --- a/architect/specs/data-api-context-assembly.feature +++ b/architect/specs/data-api-context-assembly.feature @@ -15,7 +15,7 @@ Feature: Data API Context Assembly - One-Command Session Context 30-100KB of curated, multi-source context from hundreds of annotated files. Today this requires either manual context compilation by the user or 5-10 explore agents burning context and time. The Architect pipeline already - has rich data (MasterDataset with archIndex, relationshipIndex, byPhase, + has rich data (PatternGraph with archIndex, relationshipIndex, byPhase, byStatus views) but no command combines data from multiple indexes around a focal pattern into a compact, session-oriented context bundle. @@ -60,12 +60,12 @@ Feature: Data API Context Assembly - One-Command Session Context and architecture position -- in ~1.5KB of structured text. **Rationale:** This is the core value proposition. The command crosses five - gaps simultaneously: it assembles data from multiple MasterDataset indexes, + 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. **Assembly steps:** - 1. Find pattern in MasterDataset via `getPattern()` + 1. Find pattern in PatternGraph via `getPattern()` 2. Resolve spec file from `pattern.filePath` 3. Find stubs via `implementedBy` in relationshipIndex 4. Walk `dependsOn` chain with status for each dependency diff --git a/architect/specs/data-api-output-shaping.feature b/architect/specs/data-api-output-shaping.feature index 2aa75324..355e9c52 100644 --- a/architect/specs/data-api-output-shaping.feature +++ b/architect/specs/data-api-output-shaping.feature @@ -10,7 +10,7 @@ Feature: Data API Output Shaping - Compact Output for AI Agents **Problem:** - The ProcessStateAPI CLI returns raw `ExtractedPattern` objects via `JSON.stringify`. + The PatternGraphAPI CLI returns raw `ExtractedPattern` objects via `JSON.stringify`. List queries (e.g., `getCurrentWork`) produce ~594KB of JSON because each pattern includes full `directive` (raw JSDoc AST), `code` (source text), and dozens of empty/null fields. AI agents waste context tokens parsing verbose output that is diff --git a/architect/specs/data-api-platform-integration.feature b/architect/specs/data-api-platform-integration.feature index 7a58165c..eb12ac4b 100644 --- a/architect/specs/data-api-platform-integration.feature +++ b/architect/specs/data-api-platform-integration.feature @@ -19,7 +19,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support **Solution:** Two integration capabilities: - 1. **MCP Server Mode** -- Expose ProcessStateAPI as an MCP server that Claude + 1. **MCP Server Mode** -- Expose PatternGraphAPI as an MCP server that Claude Code connects to directly. Eliminates CLI overhead and enables stateful queries (pipeline loaded once, multiple queries without re-scanning). 2. **Monorepo Support** -- Cross-package dependency views, package-scoped @@ -54,9 +54,9 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support # RULE 1: MCP Server Mode # ============================================================================ - Rule: ProcessStateAPI is accessible as an MCP server for Claude Code + Rule: PatternGraphAPI is accessible as an MCP server for Claude Code - **Invariant:** The MCP server exposes all ProcessStateAPI methods as MCP tools + **Invariant:** 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. @@ -81,10 +81,10 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support **Verified by:** MCP server starts, MCP tool invocation, Auto-refresh on change @acceptance-criteria @happy-path - Scenario: MCP server exposes ProcessStateAPI tools + Scenario: MCP server exposes PatternGraphAPI tools Given the MCP server is started with input globs When Claude Code requests tool listing - Then all ProcessStateAPI methods appear as MCP tools + Then all PatternGraphAPI methods appear as MCP tools And each tool has typed input and output schemas @acceptance-criteria @happy-path diff --git a/architect/specs/data-api-relationship-graph.feature b/architect/specs/data-api-relationship-graph.feature index 3ee8348a..4590f8fd 100644 --- a/architect/specs/data-api-relationship-graph.feature +++ b/architect/specs/data-api-relationship-graph.feature @@ -31,8 +31,8 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis | Blocking chains | Understand what prevents progress | | Path finding | Discover non-obvious relationships | - **Relationship to ProcessStateAPIRelationshipQueries:** - This spec supersedes the earlier ProcessStateAPIRelationshipQueries spec, + **Relationship to PatternGraphAPIRelationshipQueries:** + This spec supersedes the earlier PatternGraphAPIRelationshipQueries spec, which focused on implementation/inheritance convenience methods. The underlying data is available via getPatternRelationships(). This spec adds graph-level operations that traverse relationships recursively. @@ -146,7 +146,7 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis don't match any pattern definition) are detectable. Orphan patterns (no relationships at all) are identifiable. - **Rationale:** The MasterDataset transformer already computes dangling + **Rationale:** 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. diff --git a/architect/specs/data-api-stub-integration.feature b/architect/specs/data-api-stub-integration.feature index 12982ffd..1b4e4c68 100644 --- a/architect/specs/data-api-stub-integration.feature +++ b/architect/specs/data-api-stub-integration.feature @@ -78,7 +78,7 @@ Feature: Data API Stub Integration - Unlocking Design Session Data Scenario: Annotated stubs are discoverable by the scanner Given stub files with @architect and @architect-implements tags When running the scanner pipeline with stubs input glob - Then all annotated stubs appear in the MasterDataset + Then all annotated stubs appear in the PatternGraph And each stub has an implementsPatterns relationship @acceptance-criteria @happy-path @@ -86,13 +86,13 @@ Feature: Data API Stub Integration - Unlocking Design Session Data Given a stub with "@architect-target:platform-core/src/agent/router.ts" When the stub is scanned and extracted Then the pattern's targetPath field contains "platform-core/src/agent/router.ts" - And the targetPath is available via ProcessStateAPI queries + And the targetPath is available via PatternGraphAPI queries @acceptance-criteria @validation Scenario: Stub without @architect opt-in is invisible to scanner Given a stub file without the @architect marker When running the scanner pipeline with stubs input glob - Then the stub does NOT appear in the MasterDataset + Then the stub does NOT appear in the PatternGraph And no error is raised for the missing marker # ============================================================================ diff --git a/architect/specs/declaration-level-shape-tagging.feature b/architect/specs/declaration-level-shape-tagging.feature index 6217449f..a5386f17 100644 --- a/architect/specs/declaration-level-shape-tagging.feature +++ b/architect/specs/declaration-level-shape-tagging.feature @@ -256,7 +256,7 @@ Feature: Declaration-Level Shape Tagging @acceptance-criteria @happy-path Scenario: Select specific shapes by source and names - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/risk-levels.ts | RISK_LEVELS | api-types | const | @@ -271,7 +271,7 @@ Feature: Declaration-Level Shape Tagging @acceptance-criteria @happy-path Scenario: Select all shapes in a group - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/status-values.ts | ProcessStatus | api-types | type | @@ -286,7 +286,7 @@ Feature: Declaration-Level Shape Tagging @acceptance-criteria @happy-path Scenario: Select all tagged shapes from a source file - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/risk-levels.ts | RISK_LEVELS | api-types | const | @@ -302,7 +302,7 @@ Feature: Declaration-Level Shape Tagging @acceptance-criteria @happy-path Scenario: Source-only selector returns all matching shapes - Given a MasterDataset with patterns containing extracted shapes + Given a PatternGraph with patterns containing extracted shapes And a reference doc config with shapeSelectors [{"source":"src/taxonomy/*.ts"}] When the reference codec renders Then all extracted shapes from matching files appear diff --git a/architect/specs/design-review-generation.feature b/architect/specs/design-review-generation.feature index 793e14bd..ff27087f 100644 --- a/architect/specs/design-review-generation.feature +++ b/architect/specs/design-review-generation.feature @@ -19,14 +19,14 @@ Feature: Design Review Diagram Generation A generation pipeline that reads sequence annotations (`architect-sequence-*`) from feature files and produces design review documents with Mermaid sequence and component diagrams. The pipeline fits into the existing codec/generator architecture: sequence - data is pre-computed in a SequenceIndex view on MasterDataset, then a standalone + data is pre-computed in a SequenceIndex view on PatternGraph, then a standalone DesignReviewCodec renders the diagrams and supporting tables. Output goes to architect/design-reviews/. Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | - | SequenceIndex schema | complete | src/validation-schemas/master-dataset.ts | + | SequenceIndex schema | complete | src/validation-schemas/pattern-graph.ts | | Sequence transform utilities | complete | src/generators/pipeline/sequence-utils.ts | | Transform dataset integration | complete | src/generators/pipeline/transform-dataset.ts | | BusinessRule errorScenarioNames | complete | src/validation-schemas/extracted-pattern.ts | @@ -37,10 +37,10 @@ Feature: Design Review Diagram Generation Rule: SequenceIndex pre-computes ordered steps from rule-level tags - **Invariant:** The MasterDataset sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first. + **Invariant:** The PatternGraph sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first. **Rationale:** Pre-computing in the transform pass avoids repeated parsing - in the codec. ADR-006 mandates the MasterDataset as the sole read model. + in the codec. ADR-006 mandates the PatternGraph as the sole read model. Downstream consumers (codec, process API) read structured data, not raw tags. **Verified by:** SequenceIndex populated for annotated pattern, @@ -49,14 +49,14 @@ Feature: Design Review Diagram Generation @acceptance-criteria @happy-path Scenario: SequenceIndex populated for annotated pattern Given a pattern with @architect-sequence-orchestrator and 6 @architect-sequence-step rules - When the pattern is transformed to MasterDataset + When the pattern is transformed to PatternGraph Then sequenceIndex contains an entry for the pattern And the entry has 6 ordered steps with modules and data flow types @acceptance-criteria @validation Scenario: Patterns without sequence annotations excluded Given a pattern with no @architect-sequence-orchestrator tag - When the pattern is transformed to MasterDataset + When the pattern is transformed to PatternGraph Then sequenceIndex does not contain an entry for the pattern Rule: DesignReviewCodec generates sequence diagrams from ordered steps diff --git a/architect/specs/enhanced-index-generation.feature b/architect/specs/enhanced-index-generation.feature index d28bc85b..df9df176 100644 --- a/architect/specs/enhanced-index-generation.feature +++ b/architect/specs/enhanced-index-generation.feature @@ -20,7 +20,7 @@ Feature: Enhanced Index Generation **Solution:** Create an `IndexCodec` that generates a comprehensive navigation hub by composing - auto-generated statistics from MasterDataset pre-computed views with editorial + auto-generated statistics from PatternGraph pre-computed views with editorial navigation content via the preamble mechanism. The codec produces document listings, pattern counts per product area, and phase progress from `byCategory`, `byPhase`, `byProductArea`, and `byStatus` views. Audience reading paths, the document roles @@ -31,14 +31,14 @@ Feature: Enhanced Index Generation **Why It Matters:** | Benefit | How | | Single navigation hub | Unifies manual docs/ and generated docs-live/ listings in one document | - | Zero-drift statistics | Pattern counts, phase progress, product area coverage regenerated from MasterDataset | + | Zero-drift statistics | Pattern counts, phase progress, product area coverage regenerated from PatternGraph | | Audience paths preserved | Editorial reading orders carried via preamble, not duplicated manually | | Document roles matrix | Audience-to-document mapping maintained in config, rendered in output | | Closes Phase 6 | Completes DocsConsolidationStrategy Phase 6 (Index navigation update, pending) | **Scope:** | Content Type | Auto-generatable? | Source | - | Product area and generated doc listing | Yes | Static documentEntries config plus MasterDataset views | + | Product area and generated doc listing | Yes | Static documentEntries config plus PatternGraph views | | Pattern statistics per area | Yes | dataset.byProductArea view | | Phase progress summary | Yes | dataset.byStatus plus dataset.byPhase | | Audience reading paths (New User, Developer, Team Lead) | No | Preamble SectionBlock[] | @@ -49,7 +49,7 @@ Feature: Enhanced Index Generation **Design Questions (for design session):** | Question | Options | Recommendation | - | Create new IndexCodec or extend existing index generator? | (A) New IndexCodec, (B) Extend docs-live/INDEX.md generator | (A) New codec -- current generator is a simple file lister with no MasterDataset access | + | Create new IndexCodec or extend existing index generator? | (A) New IndexCodec, (B) Extend docs-live/INDEX.md generator | (A) New codec -- current generator is a simple file lister with no PatternGraph access | | How to merge manual and generated doc listings? | (A) Unified table, (B) Separate sections | (A) Unified -- users should not need to know which docs are manual vs generated | | Should audience paths be preamble or a new annotation type? | (A) Preamble, (B) New annotation | (A) Preamble -- reading orders are editorial judgment, not code-derivable | | Can key concepts be derived from pattern metadata? | (A) Yes from descriptions, (B) No, use preamble | (B) Preamble -- pattern descriptions are too granular for a glossary | @@ -57,7 +57,7 @@ Feature: Enhanced Index Generation **Design Session Findings (2026-03-06):** | Finding | Impact | Resolution | - | DD-1: New IndexCodec registered in CodecRegistry as document type index | Enables MasterDataset access via standard codec.decode(dataset) pipeline and free integration with generateDocument, generateAllDocuments, CodecOptions | Create createIndexCodec() factory following OverviewCodec pattern, register in CodecRegistry and DOCUMENT_TYPES | + | DD-1: New IndexCodec registered in CodecRegistry as document type index | Enables PatternGraph access via standard codec.decode(dataset) pipeline and free integration with generateDocument, generateAllDocuments, CodecOptions | Create createIndexCodec() factory following OverviewCodec pattern, register in CodecRegistry and DOCUMENT_TYPES | | DD-2: Document entries configured statically, not via filesystem discovery | Codec remains pure (no I/O), deterministic, testable. Config updated alongside document changes | IndexCodecOptions.documentEntries: readonly DocumentEntry[] with title, path, description, audience, topic | | DD-3: Audience reading paths are full preamble SectionBlock arrays | Reading order is editorial judgment -- no annotation can express pedagogical sequencing. Most-cited navigation aid preserved | IndexCodecOptions.preamble contains READING_ORDER_SECTIONS with 3 audience profiles | | DD-4: Key concepts glossary uses preamble, not annotation extraction | Pattern descriptions too granular for reader-friendly glossary. Future @architect-glossary annotation could replace this | KEY_CONCEPTS_SECTIONS in preamble with 6 core concept definitions | @@ -75,7 +75,7 @@ Feature: Enhanced Index Generation Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | Create IndexCodec with MasterDataset-driven statistics | complete | src/renderable/codecs/index-codec.ts | Yes | unit | + | Create IndexCodec with PatternGraph-driven statistics | complete | src/renderable/codecs/index-codec.ts | Yes | unit | | Register IndexCodec in codec registry and generator config | complete | src/renderable/generate.ts | Yes | integration | | Preamble content for audience paths, document roles, quick finder | complete | docs-sources/index-navigation.md | No | n/a | | CodecOptions entry for enhanced INDEX.md | complete | architect.config.ts | Yes | integration | @@ -85,7 +85,7 @@ Feature: Enhanced Index Generation Rule: IndexCodec composes generated statistics with editorial navigation **Invariant:** The IndexCodec generates document listings and pattern statistics - from MasterDataset pre-computed views (`byCategory`, `byPhase`, `byProductArea`, + from PatternGraph pre-computed views (`byCategory`, `byPhase`, `byProductArea`, `byStatus`), while audience reading paths, the document roles matrix, and the quick finder table use the `ReferenceDocConfig.preamble` mechanism as manually authored `SectionBlock[]`. The codec does not hardcode document metadata -- all @@ -94,28 +94,28 @@ Feature: Enhanced Index Generation **Rationale:** Approximately 40% of INDEX.md content (product area lists, file inventories, pattern statistics, phase progress) is directly derivable from - MasterDataset views and drifts when patterns change status or new patterns are + PatternGraph views and drifts when patterns change status or new patterns are added. The remaining 60% (audience paths, document roles, quick finder) requires human editorial judgment about which documents serve which readers. The preamble mechanism cleanly separates these two content types within a single generated output, as proven by CodecDrivenReferenceGeneration and DocsConsolidationStrategy Phase 2. - **Verified by:** Codec produces statistics from MasterDataset, + **Verified by:** Codec produces statistics from PatternGraph, Preamble editorial content appears before generated sections @acceptance-criteria @happy-path - Scenario: IndexCodec generates pattern statistics from MasterDataset - Given a MasterDataset with patterns across 7 product areas + Scenario: IndexCodec generates pattern statistics from PatternGraph + Given a PatternGraph with patterns across 7 product areas And patterns have statuses including roadmap, active, and completed When the IndexCodec generates the index document Then a product area statistics table shows pattern counts per area And a phase progress summary shows counts by status - And all statistics match the MasterDataset view contents + And all statistics match the PatternGraph view contents @acceptance-criteria @validation Scenario: Statistics update when patterns change status - Given a MasterDataset where 3 patterns moved from roadmap to completed + Given a PatternGraph where 3 patterns moved from roadmap to completed When the IndexCodec regenerates the index document Then the phase progress summary reflects the updated status counts And product area statistics reflect the new completed count @@ -153,7 +153,7 @@ Feature: Enhanced Index Generation Scenario: Reading paths are not derived from pattern metadata Given an IndexCodec with audience paths defined in preamble When inspecting the codec source code - Then no audience path content is computed from MasterDataset + Then no audience path content is computed from PatternGraph And all reading order content originates from the preamble SectionBlock array Rule: Index unifies manual and generated doc listings @@ -195,7 +195,7 @@ Feature: Enhanced Index Generation Rule: Document metadata drives auto-generated sections **Invariant:** Pattern counts per product area, phase progress summaries, and - product area coverage percentages are derived from MasterDataset pre-computed views + product area coverage percentages are derived from PatternGraph pre-computed views at generation time. The IndexCodec accesses `dataset.byProductArea` for area statistics, `dataset.byStatus` for status distribution, and `dataset.byPhase` for phase ordering. No statistics are hardcoded in the codec or config. When a pattern @@ -203,18 +203,18 @@ Feature: Enhanced Index Generation change without any manual update. **Rationale:** The manual INDEX.md has no statistics section because maintaining - accurate counts manually is unsustainable across 196+ patterns. The MasterDataset + accurate counts manually is unsustainable across 196+ patterns. The PatternGraph pre-computed views provide O(1) access to grouped pattern data. Surfacing these statistics in the index gives readers an at-a-glance project health overview (how many patterns per area, what percentage are completed, which phases are active) that was previously only available via the Process Data API CLI. - **Verified by:** Statistics section renders from MasterDataset views, + **Verified by:** Statistics section renders from PatternGraph views, No hardcoded counts exist in codec or config @acceptance-criteria @happy-path - Scenario: Product area statistics render from MasterDataset - Given a MasterDataset with byProductArea containing 7 product areas + Scenario: Product area statistics render from PatternGraph + Given a PatternGraph with byProductArea containing 7 product areas And each area has between 5 and 40 patterns When the IndexCodec generates the auto-generated statistics section Then a table shows each product area with its pattern count @@ -222,14 +222,14 @@ Feature: Enhanced Index Generation @acceptance-criteria @happy-path Scenario: Phase progress summary shows status distribution - Given a MasterDataset with byStatus containing roadmap, active, and completed patterns + Given a PatternGraph with byStatus containing roadmap, active, and completed patterns When the IndexCodec generates the phase progress section Then a summary shows the count of patterns in each status And a completion percentage is calculated from completed vs total @acceptance-criteria @validation Scenario: Empty product area still appears in statistics - Given a MasterDataset where the CoreTypes product area has zero patterns + Given a PatternGraph where the CoreTypes product area has zero patterns When the IndexCodec generates the statistics section Then CoreTypes appears in the table with a count of zero And no error occurs due to the empty area diff --git a/architect/specs/generated-doc-quality.feature b/architect/specs/generated-doc-quality.feature index 63db323a..33df689f 100644 --- a/architect/specs/generated-doc-quality.feature +++ b/architect/specs/generated-doc-quality.feature @@ -29,7 +29,7 @@ Feature: Generated Documentation Quality Improvements | Benefit | Audience | | Removes ~200 wasted token-lines per REFERENCE-SAMPLE.md read | Claude | | Generation compact usable as standalone context (1.4 KB → 4+ KB) | Claude | - | ARCHITECTURE-TYPES.md answers "what is MasterDataset?" immediately | Claude | + | ARCHITECTURE-TYPES.md answers "what is PatternGraph?" immediately | Claude | | 233 KB product area docs become navigable in a browser | Human devs | Background: Deliverables @@ -101,9 +101,9 @@ Feature: Generated Documentation Quality Improvements Rule: ARCHITECTURE-TYPES.md leads with type definitions, not convention content - **Invariant:** ARCHITECTURE-TYPES.md opens with the MasterDataset type definitions + **Invariant:** ARCHITECTURE-TYPES.md opens with the PatternGraph type definitions section before any pipeline-architecture convention content. An agent querying - "what is MasterDataset" finds the type definition within the first 30 lines. + "what is PatternGraph" finds the type definition within the first 30 lines. The pipeline-architecture convention prose (orchestrator responsibilities, pipeline steps) follows the type definitions section. @@ -117,8 +117,8 @@ Feature: Generated Documentation Quality Improvements Pipeline convention content follows types section @acceptance-criteria @happy-path - Scenario: MasterDataset type definition appears before orchestrator prose + Scenario: PatternGraph type definition appears before orchestrator prose Given ARCHITECTURE-TYPES.md generated with shapes section ordered before conventions When the first 30 lines are read - Then MasterDataset or a related type definition appears + Then PatternGraph or a related type definition appears And no orchestrator responsibility prose appears before the first type definition diff --git a/architect/specs/generator-infrastructure-testing.feature b/architect/specs/generator-infrastructure-testing.feature index 43df86ba..2655efc6 100644 --- a/architect/specs/generator-infrastructure-testing.feature +++ b/architect/specs/generator-infrastructure-testing.feature @@ -146,8 +146,8 @@ Feature: Generator Infrastructure Testing Rule: CodecBasedGenerator adapts codecs to generator interface **Invariant:** Generator delegates to underlying codec for transformation. - Missing MasterDataset produces descriptive error. - **Rationale:** If the adapter silently proceeds without a MasterDataset, codecs + Missing PatternGraph produces descriptive error. + **Rationale:** If the adapter silently proceeds without a PatternGraph, codecs receive undefined input and produce corrupt or empty documents. **API:** See `src/generators/codec-based.ts` @@ -157,15 +157,15 @@ Feature: Generator Infrastructure Testing @acceptance-criteria @happy-path Scenario: Generator delegates to codec Given CodecBasedGenerator wrapping PatternsDocumentCodec - And context with MasterDataset + And context with PatternGraph When generator.generate() is called Then codec.decode() is invoked with dataset And RenderableDocument is returned @acceptance-criteria @validation - Scenario: Missing MasterDataset returns error + Scenario: Missing PatternGraph returns error Given CodecBasedGenerator for patterns - And context WITHOUT MasterDataset + And context WITHOUT PatternGraph When generator.generate() is called Then error file is returned And error message indicates missing dataset @@ -173,7 +173,7 @@ Feature: Generator Infrastructure Testing @acceptance-criteria @happy-path Scenario: Codec options are passed through Given CodecBasedGenerator with codecOptions - And context with MasterDataset + And context with PatternGraph When generator.generate() is called Then codec receives codecOptions diff --git a/architect/specs/mcp-server-integration.feature b/architect/specs/mcp-server-integration.feature index 297e5ee8..03e600d8 100644 --- a/architect/specs/mcp-server-integration.feature +++ b/architect/specs/mcp-server-integration.feature @@ -12,17 +12,17 @@ Feature: MCP Server Integration **Problem:** - Claude Code accesses ProcessStateAPI through subprocess calls to the process-api + Claude Code accesses PatternGraphAPI through subprocess calls to the process-api CLI. Each invocation runs the full 8-step pipeline (config, scan, extract, merge, hierarchy, workflow, transform, validate), taking 2-5 seconds. During a typical session with 10-20 queries, this adds 30-90 seconds of pure pipeline overhead. The subprocess model prevents stateful interaction -- there is no way to keep the - MasterDataset in memory between queries. + PatternGraph in memory between queries. **Solution:** - Implement an MCP (Model Context Protocol) server that wraps ProcessStateAPI: - 1. Load the pipeline ONCE and keep MasterDataset in memory - 2. Expose ProcessStateAPI methods and CLI subcommands as MCP tools + Implement an MCP (Model Context Protocol) server that wraps PatternGraphAPI: + 1. Load the pipeline ONCE and keep PatternGraph in memory + 2. Expose PatternGraphAPI methods and CLI subcommands as MCP tools 3. Allow Claude Code to call them as native tools with sub-millisecond dispatch 4. Optionally watch source files and rebuild the dataset on changes @@ -61,7 +61,7 @@ Feature: MCP Server Integration Given the MCP server is started with config auto-detection When the client sends an MCP initialize request Then the server responds with capabilities including tools - And the pipeline has been built with MasterDataset in memory + And the pipeline has been built with PatternGraph in memory @acceptance-criteria @happy-path Scenario: Server handles shutdown cleanly @@ -78,7 +78,7 @@ Feature: MCP Server Integration @architect-sequence-step:2 @architect-sequence-module:tool-registry - Rule: ProcessStateAPI methods and CLI subcommands are registered as MCP tools + Rule: PatternGraphAPI methods and CLI subcommands are registered as MCP tools **Invariant:** 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_" @@ -125,10 +125,10 @@ Feature: MCP Server Integration @architect-sequence-step:3 @architect-sequence-module:pipeline-session - Rule: MasterDataset is loaded once and reused across all tool invocations + Rule: PatternGraph is loaded once and reused across all tool invocations **Invariant:** The pipeline runs exactly once during server initialization. All - subsequent tool calls read from in-memory MasterDataset. A manual rebuild can + 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. diff --git a/architect/specs/monorepo-support.feature b/architect/specs/monorepo-support.feature index b26373bd..b448e51f 100644 --- a/architect/specs/monorepo-support.feature +++ b/architect/specs/monorepo-support.feature @@ -12,7 +12,7 @@ Feature: Monorepo Cross-Package Support The Architect package is consumed by a large monorepo (~600 files across multiple packages), but the config system has no concept of "packages." The consumer passes all source paths as repeated --input and --features CLI flags, - creating massive duplication across 15+ scripts. MasterDataset has no concept of + creating massive duplication across 15+ scripts. PatternGraph has no concept of which package a pattern belongs to. There is no --package filter for scoping queries, no cross-package dependency visibility, and no per-package coverage. @@ -31,7 +31,7 @@ Feature: Monorepo Cross-Package Support | Package-aware source resolver | pending | src/config/resolve-config.ts | | Package provenance on ExtractedPattern | pending | src/validation-schemas/extracted-pattern.ts | | Scanner package assignment | pending | src/scanner/pattern-scanner.ts | - | MasterDataset byPackage view | pending | src/generators/pipeline/transform-dataset.ts | + | PatternGraph byPackage view | pending | src/generators/pipeline/transform-dataset.ts | | CLI --package filter flag | pending | src/cli/output-pipeline.ts | | Cross-package dependency subcommand | pending | src/api/cross-package.ts | | Per-package coverage report | pending | src/api/coverage-analyzer.ts | diff --git a/architect/specs/orchestrator-pipeline-factory-migration.feature b/architect/specs/orchestrator-pipeline-factory-migration.feature index 11f02a17..983ac5a5 100644 --- a/architect/specs/orchestrator-pipeline-factory-migration.feature +++ b/architect/specs/orchestrator-pipeline-factory-migration.feature @@ -25,7 +25,7 @@ Feature: Orchestrator Pipeline Factory Migration **Current violations in orchestrator.ts:** | Anti-Pattern | Location | Evidence | - | Parallel Pipeline | Lines 282-427 | 8-step pipeline: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, transformToMasterDataset | + | Parallel Pipeline | Lines 282-427 | 8-step pipeline: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, transformToPatternGraph | Additionally, `mergePatterns()` is defined in orchestrator.ts (line 701) but imported by `build-pipeline.ts` from `../orchestrator.js`. This @@ -48,7 +48,7 @@ Feature: Orchestrator Pipeline Factory Migration **Solution:** Enrich the pipeline factory's `PipelineResult` with structured warnings that capture the granularity the orchestrator needs, then migrate - `generateDocumentation()` to call `buildMasterDataset()`. Move + `generateDocumentation()` to call `buildPatternGraph()`. Move `mergePatterns()` to `src/generators/pipeline/merge-patterns.ts` as a standalone pipeline step. @@ -85,8 +85,8 @@ Feature: Orchestrator Pipeline Factory Migration - The public API (`mergePatterns`) stays available, just moves home DD-3: Pipeline factory gains an includeValidation option. - The orchestrator calls `transformToMasterDataset` (no validation), - while process-api calls `transformToMasterDatasetWithValidation`. + The orchestrator calls `transformToPatternGraph` (no validation), + while process-api calls `transformToPatternGraphWithValidation`. The factory already calls the validation variant. Adding `includeValidation?: boolean` (default true) lets the orchestrator opt out, since doc generation doesn't need validation summaries. @@ -128,7 +128,7 @@ Feature: Orchestrator Pipeline Factory Migration loading (`loadConfig`) is replaced by the factory's internal config step — `tagRegistry` is accessed via `dataset.tagRegistry`. The merged patterns array for `GenerateResult.patterns` and generator context is - `dataset.patterns` from the MasterDataset. + `dataset.patterns` from the PatternGraph. DD-7: validate-patterns.ts and process-api.ts are unaffected. They already consume the factory. The only change they see is @@ -180,7 +180,7 @@ Feature: Orchestrator Pipeline Factory Migration Rule: Orchestrator delegates pipeline to factory - **Invariant:** `generateDocumentation()` calls `buildMasterDataset()` + **Invariant:** `generateDocumentation()` calls `buildPatternGraph()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., @@ -206,8 +206,8 @@ Feature: Orchestrator Pipeline Factory Migration @acceptance-criteria Scenario: Factory is sole pipeline definition Given the three CLI consumers: process-api, validate-patterns, orchestrator - When each needs a MasterDataset - Then each calls buildMasterDataset from build-pipeline.ts + When each needs a PatternGraph + Then each calls buildPatternGraph from build-pipeline.ts And no consumer wires the 8-step pipeline inline Rule: mergePatterns lives in pipeline module diff --git a/architect/specs/process-state-api-cli.feature b/architect/specs/pattern-graph-api-cli.feature similarity index 97% rename from architect/specs/process-state-api-cli.feature rename to architect/specs/pattern-graph-api-cli.feature index 729f9e95..020b7b51 100644 --- a/architect/specs/process-state-api-cli.feature +++ b/architect/specs/pattern-graph-api-cli.feature @@ -1,5 +1,5 @@ @architect -@architect-pattern:ProcessStateAPICLI +@architect-pattern:PatternGraphAPICLI @architect-status:completed @architect-completed:2026-02-09 @architect-unlock-reason:Normalize-deliverable-status-taxonomy @@ -9,10 +9,10 @@ @architect-priority:high @architect-business-value:direct-api-queries-for-planning @architect-executable-specs:tests/features/api -Feature: ProcessStateAPI CLI - Direct Queries for Planning Sessions +Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions **Problem:** - The ProcessStateAPI provides 27 typed query methods for efficient state queries, but + The PatternGraphAPI provides 27 typed query methods for efficient state queries, but Claude Code sessions cannot use it directly: - Import paths require built packages with correct ESM resolution - No CLI command exposes the API for shell invocation @@ -20,7 +20,7 @@ Feature: ProcessStateAPI CLI - Direct Queries for Planning Sessions - Documentation claims API is "directly usable" but practical usage is blocked **Solution:** - Add a CLI command `pnpm process:query` that exposes key ProcessStateAPI methods: + Add a CLI command `pnpm process:query` that exposes key PatternGraphAPI methods: - `--status active|roadmap|completed` - Filter patterns by status - `--phase N` - Get patterns in specific phase - `--progress` - Show completion percentage and counts @@ -52,7 +52,7 @@ Feature: ProcessStateAPI CLI - Direct Queries for Planning Sessions Rule: CLI supports status-based pattern queries - **Invariant:** Every ProcessStateAPI status query method is accessible via CLI. + **Invariant:** Every PatternGraphAPI status query method is accessible via CLI. **Rationale:** The most common planning question is "what's the current state?" Status queries (active, roadmap, completed) answer this directly without reading docs. diff --git a/architect/specs/process-state-api-relationship-queries.feature b/architect/specs/pattern-graph-api-relationship-queries.feature similarity index 95% rename from architect/specs/process-state-api-relationship-queries.feature rename to architect/specs/pattern-graph-api-relationship-queries.feature index b9ab9122..b03d13e5 100644 --- a/architect/specs/process-state-api-relationship-queries.feature +++ b/architect/specs/pattern-graph-api-relationship-queries.feature @@ -1,17 +1,17 @@ @architect -@architect-pattern:ProcessStateAPIRelationshipQueries +@architect-pattern:PatternGraphAPIRelationshipQueries @architect-status:completed @architect-unlock-reason:Relationships-available-via-getPatternRelationships-superseded-by-DataAPIRelationshipGraph @architect-phase:24 @architect-product-area:DataAPI @architect-effort:3d -Feature: ProcessStateAPI Relationship Queries +Feature: PatternGraphAPI Relationship Queries - **Problem:** ProcessStateAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, + **Problem:** PatternGraphAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, `enables`) but lacks implementation relationship queries. Claude Code cannot ask "what code implements this pattern?" or "what pattern does this file implement?" - **Solution:** Extend ProcessStateAPI with relationship query methods that leverage the new + **Solution:** Extend PatternGraphAPI with relationship query methods that leverage the new `implements`/`extends` tags from PatternRelationshipModel: - Bidirectional traceability: spec → code and code → spec - Inheritance hierarchy navigation: base → specializations @@ -26,9 +26,9 @@ Feature: ProcessStateAPI Relationship Queries Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | Implementation relationship queries | superseded | src/api/process-state.ts | No | N/A | - | Inheritance hierarchy queries | superseded | src/api/process-state.ts | No | N/A | - | ProcessStateAPI type extensions | complete | src/api/types.ts | Yes | unit | + | Implementation relationship queries | superseded | src/api/pattern-graph-api.ts | No | N/A | + | Inheritance hierarchy queries | superseded | src/api/pattern-graph-api.ts | No | N/A | + | PatternGraphAPI type extensions | complete | src/api/types.ts | Yes | unit | | Relationship query step definitions | superseded | N/A | No | N/A | # ═══════════════════════════════════════════════════════════════════════════════ @@ -128,7 +128,7 @@ Feature: ProcessStateAPI Relationship Queries **Rationale:** Claude Code often needs the complete picture: dependencies AND implementations AND inheritance. A single call reduces round-trips and context switching. - **API:** See `@libar-dev/architect/src/api/process-state.ts` + **API:** See `@libar-dev/architect/src/api/pattern-graph-api.ts` **Verified by:** Get all relationships, Filter by relationship type diff --git a/architect/specs/pattern-relationship-model.feature b/architect/specs/pattern-relationship-model.feature index d9cbd32d..3fd699b2 100644 --- a/architect/specs/pattern-relationship-model.feature +++ b/architect/specs/pattern-relationship-model.feature @@ -41,7 +41,7 @@ Feature: Pattern Relationship Model | Extends tag in taxonomy registry | complete | src/taxonomy/registry-builder.ts | Yes | unit | | DocDirective schema update | complete | src/validation-schemas/doc-directive.ts | Yes | unit | | ExtractedPattern schema update | complete | src/validation-schemas/extracted-pattern.ts | Yes | unit | - | RelationshipEntry schema update | complete | src/validation-schemas/master-dataset.ts | Yes | unit | + | RelationshipEntry schema update | complete | src/validation-schemas/pattern-graph.ts | Yes | unit | | Relationship index enhancement | complete | src/generators/pipeline/transform-dataset.ts | Yes | unit | | Mermaid graph enhancement | complete | src/renderable/codecs/patterns.ts | Yes | unit | | Pattern detail implementations section | complete | src/renderable/codecs/patterns.ts | Yes | unit | diff --git a/architect/specs/phase-state-machine.feature b/architect/specs/phase-state-machine.feature index 9427eb86..45aea39c 100644 --- a/architect/specs/phase-state-machine.feature +++ b/architect/specs/phase-state-machine.feature @@ -28,7 +28,7 @@ Feature: Phase State Machine Validation | FSM transition matrix and validator | complete | 123 | @libar-dev/architect/src/validation/fsm/transitions.ts | | Pure validation functions | complete | 123 | @libar-dev/architect/src/validation/fsm/validator.ts | | Status validation lint rule | complete | 2190 | @libar-dev/architect/src/lint/rules.ts | - | ProcessStateAPI for programmatic queries | complete | 95 | @libar-dev/architect/src/api/process-state.ts | + | PatternGraphAPI for programmatic queries | complete | 95 | @libar-dev/architect/src/api/pattern-graph-api.ts | Rule: Valid status values are enforced diff --git a/architect/specs/procedural-guide-codec.feature b/architect/specs/procedural-guide-codec.feature index d3feb1ac..3ba9fd34 100644 --- a/architect/specs/procedural-guide-codec.feature +++ b/architect/specs/procedural-guide-codec.feature @@ -28,7 +28,7 @@ Feature: Procedural Guide Codec **Solution:** Create a `ProceduralGuideCodec` that uses a dual-source composition pattern: auto-generated reference sections (tag reference tables, pattern statistics, session type contracts) are - derived from MasterDataset and taxonomy sources, while procedural content (checklists, + derived from PatternGraph and taxonomy sources, while procedural content (checklists, decision trees, getting-started walkthrough, troubleshooting tables) is authored as markdown files in `docs-sources/` and parsed into `SectionBlock[]` at config load time by `loadPreambleFromMarkdown()`. The codec produces two separate generated files -- one for @@ -62,7 +62,7 @@ Feature: Procedural Guide Codec | Getting-started annotation walkthrough | Cannot derive from annotations | Markdown source -> loadPreambleFromMarkdown() | | Shape extraction mode explanations | Cannot derive from annotations | Markdown source -> loadPreambleFromMarkdown() | | Zod schema gotcha and troubleshooting | Cannot derive from annotations | Markdown source -> loadPreambleFromMarkdown() | - | Tag reference summary table | Taxonomy registry data | Auto-generated from MasterDataset | + | Tag reference summary table | Taxonomy registry data | Auto-generated from PatternGraph | | Verification CLI recipes | Cannot derive from annotations | Markdown source -> loadPreambleFromMarkdown() | **Design Questions (for design session):** @@ -110,7 +110,7 @@ Feature: Procedural Guide Codec Rule: Procedural guides use a dual-source codec **Invariant:** The ProceduralGuideCodec composes auto-generated reference sections - (from MasterDataset and taxonomy) with manually-authored procedural content (from + (from PatternGraph and taxonomy) with manually-authored procedural content (from preamble `SectionBlock[]`). Auto-generated content covers ~5% of the output (tag reference tables, pattern statistics, session type contract tables extracted from Rule: blocks). The remaining ~95% is editorial preamble: checklists, decision trees, @@ -136,7 +136,7 @@ Feature: Procedural Guide Codec @acceptance-criteria @happy-path Scenario: ProceduralGuideCodec composes preamble with generated reference Given a ProceduralGuideCodec configured with preamble checklist content - And the MasterDataset contains session type metadata from SessionGuidesModuleSource + And the PatternGraph contains session type metadata from SessionGuidesModuleSource When the codec generates the session workflow guide Then preamble checklist sections appear first in the output And auto-generated session type contract tables follow the preamble @@ -158,7 +158,7 @@ Feature: Procedural Guide Codec statements for `_claude-md/workflow/` modules at the summary level. Two audiences (public developers and AI sessions) are served from a single annotated source with different rendering detail levels. The codec does not duplicate or re-derive Rule: - block content -- it reads from MasterDataset's behavior extraction views. + block content -- it reads from PatternGraph's behavior extraction views. **Rationale:** SessionGuidesModuleSource already captures session type contracts (Rule 3), planning constraints (Rule 4), design constraints (Rule 5), implementation diff --git a/architect/specs/process-api-hybrid-generation.feature b/architect/specs/process-api-hybrid-generation.feature index ce94741e..5a4ee0d7 100644 --- a/architect/specs/process-api-hybrid-generation.feature +++ b/architect/specs/process-api-hybrid-generation.feature @@ -40,7 +40,7 @@ Feature: PROCESS-API.md Hybrid Generation | Finding | Impact | Resolution | | Original spec references src/cli/parser.ts | File does not exist | Fix to src/cli/process-api.ts + src/cli/output-pipeline.ts | | Orchestrator only does full-file writes | Marker-based partial replacement not supported | Split Output Reference into separate generated file | - | ReferenceDocConfig is MasterDataset-sourced | CLI schema data is not annotation-derived | Standalone generator, not ReferenceDocConfig (ADR-006) | + | ReferenceDocConfig is PatternGraph-sourced | CLI schema data is not annotation-derived | Standalone generator, not ReferenceDocConfig (ADR-006) | | --format in Output Modifiers table but not in OutputModifiers interface | Would produce incomplete table | Schema includes --format alongside modifiers | | --session parsed as global option but absent from Global Options table | Intentional, documented in Session Types | Schema captures in separate sessionOptions group | | showHelp() lines 271-370 is third copy of same data | Three-way sync risk | Schema drives both help text and doc generation | @@ -88,7 +88,7 @@ Feature: PROCESS-API.md Hybrid Generation (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from - MasterDataset (annotation-derived data), not static constants (ADR-006). + PatternGraph (annotation-derived data), not static constants (ADR-006). **Verified by:** Tables match parser definitions, showHelp output matches schema, sync test catches drift @@ -136,17 +136,17 @@ Feature: PROCESS-API.md Hybrid Generation Rule: Standalone generator respects ADR-006 single read model **Invariant:** The `ProcessApiReferenceGenerator` imports CLI schema data directly - from `src/cli/cli-schema.ts`. It does NOT inject CLI data into MasterDataset or - consume MasterDataset for table generation. It implements `DocumentGenerator` and + from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or + consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. - **Rationale:** ADR-006 establishes MasterDataset as the sole read model for + **Rationale:** ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted - from annotations. Forcing it through MasterDataset would violate the "no parallel + from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. - **Verified by:** Generator has no MasterDataset import, output file written by orchestrator + **Verified by:** Generator has no PatternGraph import, output file written by orchestrator @acceptance-criteria @integration Scenario: Generator produces complete reference file diff --git a/architect/specs/process-api-layered-extraction.feature b/architect/specs/process-api-layered-extraction.feature index 03c6d21a..a2c14bcd 100644 --- a/architect/specs/process-api-layered-extraction.feature +++ b/architect/specs/process-api-layered-extraction.feature @@ -31,9 +31,9 @@ Feature: Process API Layered Extraction in process-api.ts, 13 are thin wrappers over `src/api/` modules: | Handler | Delegates To | - | handleStatus | ProcessStateAPI methods | + | handleStatus | PatternGraphAPI methods | | handleQuery | Dynamic API method dispatch | - | handlePattern | ProcessStateAPI methods | + | handlePattern | PatternGraphAPI methods | | handleList | output-pipeline.ts | | handleSearch | fuzzy-match.ts, pattern-helpers.ts | | handleStubs | stub-resolver.ts | @@ -70,7 +70,7 @@ Feature: Process API Layered Extraction `Result` so each consumer can map errors to its own strategy (process-api calls `process.exit(1)`, validate-patterns throws, orchestrator returns `Result.err()`). - `PipelineResult` contains `{ dataset: RuntimeMasterDataset, validation: + `PipelineResult` contains `{ dataset: RuntimePatternGraph, validation: ValidationSummary }`. The `TagRegistry` is accessible via `dataset.tagRegistry` and does not need a separate field. @@ -92,7 +92,7 @@ Feature: Process API Layered Extraction validate-patterns.ts only. DD-4: handleRules domain logic extracts to `src/api/rules-query.ts`. - The new module exports `queryBusinessRules(dataset: RuntimeMasterDataset, + The new module exports `queryBusinessRules(dataset: RuntimePatternGraph, filters: RulesFilters): RulesQueryResult`. The `RulesFilters` interface, `RuleOutput` interface, and all nested Map construction move to this module. The `parseBusinessRuleAnnotations` and `deduplicateScenarioNames` imports @@ -116,7 +116,7 @@ Feature: Process API Layered Extraction calls would add indirection with no architectural benefit. DD-7: validate-patterns.ts partially adopts the pipeline factory. - The factory replaces the MasterDataset construction pipeline (steps 1-8). + The factory replaces the PatternGraph construction pipeline (steps 1-8). DoD validation and anti-pattern detection remain as direct stage-1 consumers using raw scanned files (`scanResult.value.files`, `gherkinScanResult.value.files`). This is correct per ADR-006: the @@ -144,7 +144,7 @@ Feature: Process API Layered Extraction | 2 | Export from src/generators/pipeline/index.ts barrel | pnpm typecheck | | 3 | Migrate process-api.ts buildPipeline to factory call | pnpm typecheck, pnpm process:query -- overview | | 4 | Remove unused scanner/extractor imports from process-api.ts | pnpm lint | - | 5 | Migrate validate-patterns.ts MasterDataset pipeline to factory call | pnpm validate:patterns (0 errors, 0 warnings) | + | 5 | Migrate validate-patterns.ts PatternGraph pipeline to factory call | pnpm validate:patterns (0 errors, 0 warnings) | | 6 | Create src/api/rules-query.ts with queryBusinessRules | pnpm typecheck | | 7 | Slim handleRules in process-api.ts to thin delegation | pnpm process:query -- rules | | 8 | Export from src/api/index.ts barrel | pnpm typecheck | @@ -158,7 +158,7 @@ Feature: Process API Layered Extraction | src/api/rules-query.ts | NEW: business rules query from handleRules | +~200 | | src/api/index.ts | Add re-exports for rules-query | +5 | | src/cli/process-api.ts | Replace buildPipeline + handleRules with delegations | -~280 net | - | src/cli/validate-patterns.ts | Replace MasterDataset pipeline with factory call | -~30 net | + | src/cli/validate-patterns.ts | Replace PatternGraph pipeline with factory call | -~30 net | **What does NOT change:** @@ -176,7 +176,7 @@ Feature: Process API Layered Extraction | Deliverable | Status | Location | | Create shared pipeline factory | complete | src/generators/pipeline/build-pipeline.ts | | process-api.ts consumes pipeline factory | complete | src/cli/process-api.ts | - | validate-patterns.ts consumes pipeline factory (MasterDataset only) | complete | src/cli/validate-patterns.ts | + | validate-patterns.ts consumes pipeline factory (PatternGraph only) | complete | src/cli/validate-patterns.ts | | Extract handleRules to rules-query.ts | complete | src/api/rules-query.ts | | Update barrel exports | complete | src/api/index.ts, src/generators/pipeline/index.ts | | End-to-end verification | complete | CLI output | @@ -184,7 +184,7 @@ Feature: Process API Layered Extraction Rule: CLI file contains only routing, no domain logic **Invariant:** `process-api.ts` parses arguments, calls the pipeline - factory for the MasterDataset, routes subcommands to API modules, and + 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. @@ -209,14 +209,14 @@ Feature: Process API Layered Extraction Given handleRules business rules grouping When extracted to src/api/rules-query.ts Then the CLI handler parses filters, calls queryBusinessRules, and formats output - And the queryBusinessRules function is a pure function taking RuntimeMasterDataset + And the queryBusinessRules function is a pure function taking RuntimePatternGraph And the nested Map construction lives in rules-query.ts, not process-api.ts Rule: Pipeline factory is shared across CLI consumers **Invariant:** 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 + PatternGraph call the factory rather than wiring the pipeline independently. The factory accepts `mergeConflictStrategy` to handle behavioral differences between consumers. @@ -224,7 +224,7 @@ Feature: Process API Layered Extraction orchestrator) independently wire the same 8-step sequence: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, - transformToMasterDataset. The only semantic difference is merge-conflict + transformToPatternGraph. The only semantic difference is merge-conflict handling (fatal vs concatenate). This is a Parallel Pipeline anti-pattern per ADR-006. @@ -233,10 +233,10 @@ Feature: Process API Layered Extraction @acceptance-criteria Scenario: CLI consumers use factory Given process-api.ts and validate-patterns.ts - When each needs a MasterDataset + When each needs a PatternGraph Then each calls the shared pipeline factory from build-pipeline.ts And process-api.ts does not import from scanner/ or extractor/ - And validate-patterns.ts uses the factory for MasterDataset but retains direct scans for DoD and anti-patterns + And validate-patterns.ts uses the factory for PatternGraph but retains direct scans for DoD and anti-patterns @acceptance-criteria Scenario: Orchestrator migration deferred @@ -248,7 +248,7 @@ Feature: Process API Layered Extraction Rule: Domain logic lives in API modules - **Invariant:** Query logic that operates on MasterDataset lives in + **Invariant:** 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 -> @@ -267,7 +267,7 @@ Feature: Process API Layered Extraction Scenario: rules-query module exports Given the new src/api/rules-query.ts When inspecting the module - Then it exports queryBusinessRules taking RuntimeMasterDataset and RulesFilters + Then it exports queryBusinessRules taking RuntimePatternGraph and RulesFilters And it exports RulesQueryResult, RulesFilters, and RuleOutput types And it is re-exported from src/api/index.ts @@ -298,7 +298,7 @@ Feature: Process API Layered Extraction @acceptance-criteria Scenario: Factory uses Result monad - Given the pipeline factory buildMasterDataset + Given the pipeline factory buildPatternGraph When a config error, scan error, or merge conflict occurs Then the factory returns Result.err with a structured PipelineError And it does not call process.exit or throw diff --git a/architect/specs/reference-doc-showcase.feature b/architect/specs/reference-doc-showcase.feature index 782642b7..3d6664aa 100644 --- a/architect/specs/reference-doc-showcase.feature +++ b/architect/specs/reference-doc-showcase.feature @@ -225,7 +225,7 @@ Feature: Reference Document Showcase **Rationale:** The sample document is the integration test for the reference codec. If any block type is missing, there is no automated verification that the codec can produce it. Coverage of all 9 types validates the full - rendering pipeline from MasterDataset through codec through renderer. + rendering pipeline from PatternGraph through codec through renderer. **Verified by:** All 9 block types present in detailed output, Summary output uses compact block subset diff --git a/architect/specs/step-definition-completion.feature b/architect/specs/step-definition-completion.feature index 324c0db7..4a014b64 100644 --- a/architect/specs/step-definition-completion.feature +++ b/architect/specs/step-definition-completion.feature @@ -68,7 +68,7 @@ Feature: Step Definition Completion **Implementation Notes:** - Use createExtractedPattern() from tests/fixtures/pattern-factories.ts - - Use createMasterDataset() from tests/fixtures/dataset-factories.ts + - Use createPatternGraph() from tests/fixtures/dataset-factories.ts - Import codecs from src/renderable/codecs/ - Assert on RenderableDocument structure, not markdown output diff --git a/architect/specs/traceability-generator.feature b/architect/specs/traceability-generator.feature index 8357f0a5..a09280a5 100644 --- a/architect/specs/traceability-generator.feature +++ b/architect/specs/traceability-generator.feature @@ -18,7 +18,7 @@ Feature: Traceability Generator - Rule-to-Scenario Coverage via Codec Rule-to-Scenario traceability. The `parseBusinessRuleAnnotations()` helper in `src/renderable/codecs/helpers.ts` already extracts `verifiedBy` strings from Rule descriptions. The remaining work is: - 1. Cross-reference those strings against actual scenario names in MasterDataset + 1. Cross-reference those strings against actual scenario names in PatternGraph 2. Build a traceability matrix section showing Rule-to-Scenario mappings 3. Detect coverage gaps (unverified rules, orphan scenarios, dangling references) 4. Wire the codec output into `docs:all` via config and npm script @@ -48,7 +48,7 @@ Feature: Traceability Generator - Rule-to-Scenario Coverage via Codec Rule: Cross-references Verified by annotations against actual scenarios **Invariant:** Every `verifiedBy` string extracted from a Rule description is - matched against scenario names in the MasterDataset. The traceability matrix + matched against scenario names in the PatternGraph. The traceability matrix shows each Rule with its verification status: verified (all references resolve), partially verified (some resolve), or unverified (none resolve or no annotation). @@ -67,7 +67,7 @@ Feature: Traceability Generator - Rule-to-Scenario Coverage via Codec Rule: Reservations prevent race conditions **Verified by:** Concurrent reservations, Expired reservation cleanup """ - And the MasterDataset contains scenarios: + And the PatternGraph contains scenarios: | Scenario Name | | Concurrent reservations | | Expired reservation cleanup | @@ -77,7 +77,7 @@ Feature: Traceability Generator - Rule-to-Scenario Coverage via Codec @acceptance-criteria @validation Scenario: Reports dangling references Given a Rule references scenario "Non-existent test" in Verified by - And no scenario with that name exists in the MasterDataset + And no scenario with that name exists in the PatternGraph When the TraceabilityCodec decodes the dataset Then a "Dangling References" section should list "Non-existent test" And the Rule should show status "partially verified" or "unverified" diff --git a/architect/specs/validator-read-model-consolidation.feature b/architect/specs/validator-read-model-consolidation.feature index 22921ea5..8c1e5b37 100644 --- a/architect/specs/validator-read-model-consolidation.feature +++ b/architect/specs/validator-read-model-consolidation.feature @@ -13,7 +13,7 @@ Feature: Validator Read Model Consolidation **Problem:** `validate-patterns.ts` is the only feature consumer that bypasses the - MasterDataset. It wires its own mini-pipeline (scan + extract + ad-hoc + PatternGraph. It wires its own mini-pipeline (scan + extract + ad-hoc matching), creates a lossy local type (`GherkinPatternInfo`) that discards relationship data, and then fails to resolve `@architect-implements` links — producing 7 false-positive warnings. @@ -21,7 +21,7 @@ Feature: Validator Read Model Consolidation This is the Parallel Pipeline anti-pattern identified in ADR-006. The validator re-derives pattern identity and cross-source matching from raw scanner/extractor output, ignoring the relationship index that the - MasterDataset already computes with full forward and reverse edges. + PatternGraph already computes with full forward and reverse edges. **Current violations in validate-patterns.ts (lines refer to pre-refactor):** @@ -42,9 +42,9 @@ Feature: Validator Read Model Consolidation | SourceMapper | Utility with @architect-phase 27 but no Gherkin spec | Spurious phase tag | **Solution:** - Refactor `validate-patterns.ts` to consume the MasterDataset as its + Refactor `validate-patterns.ts` to consume the PatternGraph as its data source for cross-source validation. The validator becomes a feature - consumer like codecs and the ProcessStateAPI — querying pre-computed + consumer like codecs and the PatternGraphAPI — querying pre-computed views and the relationship index instead of building its own maps from raw data. @@ -67,7 +67,7 @@ Feature: Validator Read Model Consolidation This keeps the refactoring focused on data-access only. DD-2: The validatePatterns() function signature changes from - (tsPatterns, gherkinPatterns) to (dataset: RuntimeMasterDataset). + (tsPatterns, gherkinPatterns) to (dataset: RuntimePatternGraph). All cross-source matching uses dataset.patterns + dataset.relationshipIndex. The function remains exported for testability. @@ -77,7 +77,7 @@ Feature: Validator Read Model Consolidation in any relationshipIndex entry's implementedBy array. This resolves the ShapeExtractor and DecisionDocGenerator false positives. - DD-4: The validator will import transformToMasterDatasetWithValidation + DD-4: The validator will import transformToPatternGraphWithValidation from generators/pipeline/index.js, plus the merge and hierarchy helpers already used by process-api.ts. This is a temporary parallel pipeline (acknowledged) that will be replaced when the pipeline factory exists. @@ -90,8 +90,8 @@ Feature: Validator Read Model Consolidation | Step | What | Verification | | 1 | Remove @architect-phase from 5 utility files | pnpm build, warnings drop from 7 to 2 | - | 2 | Wire MasterDataset pipeline in main() | pnpm typecheck | - | 3 | Rewrite validatePatterns() to consume RuntimeMasterDataset | pnpm typecheck | + | 2 | Wire PatternGraph pipeline in main() | pnpm typecheck | + | 3 | Rewrite validatePatterns() to consume RuntimePatternGraph | pnpm typecheck | | 4 | Delete GherkinPatternInfo, extractGherkinPatternInfo | pnpm typecheck, pnpm test | | 5 | Remove unused scanner/extractor imports | pnpm lint | | 6 | Run pnpm validate:patterns — verify 0 errors, 0 warnings | Full verification | @@ -118,8 +118,8 @@ Feature: Validator Read Model Consolidation Given the following deliverables: | Deliverable | Status | Location | | Remove phase tags from 5 utility patterns | complete | 5 TS files (see Files Modified) | - | Wire MasterDataset pipeline in main() | complete | src/cli/validate-patterns.ts | - | Rewrite validatePatterns() to consume RuntimeMasterDataset | complete | src/cli/validate-patterns.ts | + | Wire PatternGraph pipeline in main() | complete | src/cli/validate-patterns.ts | + | Rewrite validatePatterns() to consume RuntimePatternGraph | complete | src/cli/validate-patterns.ts | | Delete GherkinPatternInfo and extractGherkinPatternInfo | complete | src/cli/validate-patterns.ts | | Remove unused scanner/extractor imports | complete | src/cli/validate-patterns.ts | | Zero warnings on pnpm validate:patterns | complete | CLI output | @@ -127,10 +127,10 @@ Feature: Validator Read Model Consolidation Rule: Validator queries the read model for cross-source matching **Invariant:** Pattern identity resolution — including implements - relationships in both directions — uses `MasterDataset.relationshipIndex` + relationships in both directions — uses `PatternGraph.relationshipIndex` rather than ad-hoc name-equality maps built from raw scanner output. - **Rationale:** The MasterDataset computes implementedBy reverse lookups + **Rationale:** The PatternGraph computes implementedBy reverse lookups in transform-dataset.ts (second pass, lines 488-546). The validator's current name-equality Map cannot resolve ShapeExtractor -> ShapeExtraction or DecisionDocGeneratorTesting -> DecisionDocGenerator because these are @@ -144,7 +144,7 @@ Feature: Validator Read Model Consolidation And a Gherkin feature "DecisionDocGeneratorTesting" with @architect-implements:DecisionDocGenerator When running cross-source validation Then no warning is produced for "DecisionDocGenerator" - And the relationship is resolved via MasterDataset.relationshipIndex + And the relationship is resolved via PatternGraph.relationshipIndex @acceptance-criteria Scenario: TS pattern implementing a Gherkin spec resolves @@ -156,7 +156,7 @@ Feature: Validator Read Model Consolidation Rule: No lossy local types in the validator **Invariant:** The validator operates on `ExtractedPattern` from the - MasterDataset, not a consumer-local DTO that discards fields. + PatternGraph, not a consumer-local DTO that discards fields. **Rationale:** GherkinPatternInfo keeps only name, phase, status, file, and deliverables — discarding uses, dependsOn, implementsPatterns, @@ -171,7 +171,7 @@ Feature: Validator Read Model Consolidation When inspecting the module Then no GherkinPatternInfo interface exists And no extractGherkinPatternInfo function exists - And pattern data comes from MasterDataset.patterns + And pattern data comes from PatternGraph.patterns Rule: Utility patterns without specs are not false positives diff --git a/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts b/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts index f669ddb7..7b00ee43 100644 --- a/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts +++ b/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts @@ -2,15 +2,15 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIDesignSessionSupport - * @architect-uses ProcessStateAPI, MasterDataset, ContextFormatterImpl + * @architect-uses PatternGraphAPI, PatternGraph, ContextFormatterImpl * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/handoff-generator.ts * @architect-since DS-E * * ## HandoffGenerator — Session-End State Summary * - * Pure function that assembles a handoff document from ProcessStateAPI - * and MasterDataset. Captures everything the next session needs to + * Pure function that assembles a handoff document from PatternGraphAPI + * and PatternGraph. Captures everything the next session needs to * continue work without context loss. * * ### Algorithm @@ -115,8 +115,8 @@ export interface HandoffDocument { * Assembles completed/in-progress deliverables, discovered items, * blockers, and next priorities into a structured document. * - * @param api - ProcessStateAPI for pattern/deliverable/dependency queries - * @param dataset - MasterDataset (unused currently, reserved for future) + * @param api - PatternGraphAPI for pattern/deliverable/dependency queries + * @param dataset - PatternGraph (unused currently, reserved for future) * @param options - Pattern name, optional session type override, optional git files * @returns Assembled handoff document */ diff --git a/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts b/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts index 5ae0fe58..cf0b32b8 100644 --- a/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts +++ b/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts @@ -2,14 +2,14 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIDesignSessionSupport - * @architect-uses ProcessStateAPI, MasterDataset, StubResolver + * @architect-uses PatternGraphAPI, PatternGraph, StubResolver * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/scope-validator.ts * @architect-since DS-E * * ## ScopeValidator — Pre-flight Session Readiness Checker * - * Pure function composition over ProcessStateAPI and MasterDataset. + * Pure function composition over PatternGraphAPI and PatternGraph. * Runs a checklist of prerequisite validations before starting a * design or implementation session. * @@ -138,8 +138,8 @@ export interface ScopeValidationResult { * Selects and runs checks based on scopeType, then aggregates results * into a verdict. * - * @param api - ProcessStateAPI for pattern/FSM queries - * @param dataset - MasterDataset for stub resolution + * @param api - PatternGraphAPI for pattern/FSM queries + * @param dataset - PatternGraph for stub resolution * @param options - Pattern name, scope type, base directory * @returns Aggregated validation result with verdict */ diff --git a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts index c97ee204..cebc4983 100644 --- a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts +++ b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts @@ -9,7 +9,7 @@ * Produces `docs-live/reference/PROCESS-API-RECIPES.md` from the declarative * CLI schema. Sibling to `ProcessApiReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends - * on MasterDataset (ADR-006 compliant). + * on PatternGraph (ADR-006 compliant). * * **Design Decision DD-1 (Separate generator, not extension):** * Reference tables and recipe guides serve different audiences and change at @@ -241,7 +241,7 @@ export interface CliRecipeGeneratorConfig { * * Follows the same pattern as ProcessApiReferenceGenerator: * - Implements DocumentGenerator interface - * - Consumes CLI_SCHEMA directly (no MasterDataset dependency) + * - Consumes CLI_SCHEMA directly (no PatternGraph dependency) * - Returns OutputFile[] via standard orchestrator write path * - Registered in architect.config.ts generatorOverrides * diff --git a/architect/stubs/cli-recipe-codec/recipe-data.ts b/architect/stubs/cli-recipe-codec/recipe-data.ts index 32155e96..e21fe1c9 100644 --- a/architect/stubs/cli-recipe-codec/recipe-data.ts +++ b/architect/stubs/cli-recipe-codec/recipe-data.ts @@ -131,7 +131,7 @@ const overviewNarrative: CommandNarrative = { '318 patterns (224 completed, 47 active, 47 planned) = 70%', '', '=== ACTIVE PHASES ===', - 'Phase 24: ProcessStateAPIRelationshipQueries (1 active)', + 'Phase 24: PatternGraphAPIRelationshipQueries (1 active)', 'Phase 25: DataAPIStubIntegration (1 active)', '', '=== BLOCKING ===', diff --git a/architect/stubs/data-api-architecture-queries/arch-queries.ts b/architect/stubs/data-api-architecture-queries/arch-queries.ts index 50dc1d6d..8486974f 100644 --- a/architect/stubs/data-api-architecture-queries/arch-queries.ts +++ b/architect/stubs/data-api-architecture-queries/arch-queries.ts @@ -2,7 +2,7 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIArchitectureQueries - * @architect-uses ProcessStateAPI, MasterDataset, Pattern Scanner + * @architect-uses PatternGraphAPI, PatternGraph, Pattern Scanner * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/arch-queries.ts * @architect-since DS-D @@ -47,7 +47,7 @@ * See ADR-008 for rationale. */ export interface SubcommandContext { - /** ProcessStateAPI instance for pattern queries. */ + /** PatternGraphAPI instance for pattern queries. */ readonly api: unknown; /** CLI config with input globs, features, baseDir. */ readonly cliConfig: { @@ -82,7 +82,7 @@ export interface NeighborEntry { * 1-hop neighborhood result for a focal pattern. * * Resolves: uses, usedBy, same-context siblings, implements/implementedBy. - * All from pre-computed MasterDataset views (no additional scanning). + * All from pre-computed PatternGraph views (no additional scanning). */ export interface NeighborhoodResult { /** Focal pattern name. */ @@ -245,7 +245,7 @@ export interface SourceInventory { * 5. Resolve NeighborEntry metadata for each neighbor * * @param name - Pattern name to get neighborhood for - * @param dataset - MasterDataset with archIndex and relationshipIndex + * @param dataset - PatternGraph with archIndex and relationshipIndex * @returns Neighborhood result, or undefined if pattern not found */ export function computeNeighborhood( @@ -266,7 +266,7 @@ export function computeNeighborhood( * * @param ctx1 - First context name * @param ctx2 - Second context name - * @param dataset - MasterDataset with archIndex and relationshipIndex + * @param dataset - PatternGraph with archIndex and relationshipIndex * @returns Comparison result, or undefined if either context not found */ export function compareContexts( @@ -288,7 +288,7 @@ export function compareContexts( * 5. Cross-reference with tagRegistry.metadataTags for tag names * 6. Sort by count descending * - * @param dataset - MasterDataset with patterns and tagRegistry + * @param dataset - PatternGraph with patterns and tagRegistry * @returns Tag usage report sorted by count */ export function aggregateTagUsage( @@ -306,9 +306,9 @@ export function aggregateTagUsage( * - .feature extension → Gherkin * - .ts extension → TypeScript * - * No re-scan needed — all data from MasterDataset.patterns[].source.file. + * No re-scan needed — all data from PatternGraph.patterns[].source.file. * - * @param dataset - MasterDataset with patterns + * @param dataset - PatternGraph with patterns * @returns Source inventory grouped by type */ export function buildSourceInventory( diff --git a/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts b/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts index 91730ec5..45c52ad1 100644 --- a/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts +++ b/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts @@ -2,7 +2,7 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIArchitectureQueries - * @architect-uses Pattern Scanner, MasterDataset + * @architect-uses Pattern Scanner, PatternGraph * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/coverage-analyzer.ts * @architect-since DS-D @@ -10,7 +10,7 @@ * ## CoverageAnalyzer — Annotation Coverage and Taxonomy Gap Detection * * Reports annotation completeness by comparing scannable files (from glob) - * against annotated patterns in MasterDataset. Also detects unused taxonomy + * against annotated patterns in PatternGraph. Also detects unused taxonomy * values defined in TagRegistry but never applied. * * ### Coverage Data Access Strategy (DS-D-1) @@ -92,7 +92,7 @@ export interface CoverageReport { * * Async because findFilesToScan() uses glob (filesystem I/O). * - * @param dataset - MasterDataset with extracted patterns + * @param dataset - PatternGraph with extracted patterns * @param inputGlobs - CLI --input glob patterns * @param baseDir - Base directory for file discovery * @param registry - TagRegistry for unused taxonomy detection @@ -139,7 +139,7 @@ export async function findUnannotatedFiles( * 4. Collect all statuses used: similarly * 5. Diff against registry definitions * - * @param dataset - MasterDataset with patterns + * @param dataset - PatternGraph with patterns * @param registry - TagRegistry with definitions * @returns Report of unused taxonomy values */ diff --git a/architect/stubs/data-api-context-assembly/context-assembler.ts b/architect/stubs/data-api-context-assembly/context-assembler.ts index c5d09ef5..af4e8481 100644 --- a/architect/stubs/data-api-context-assembly/context-assembler.ts +++ b/architect/stubs/data-api-context-assembly/context-assembler.ts @@ -2,14 +2,14 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIContextAssembly - * @architect-uses ProcessStateAPI, MasterDataset, PatternSummarizer + * @architect-uses PatternGraphAPI, PatternGraph, PatternSummarizer * @architect-used-by ProcessAPICLIImpl, ContextFormatter * @architect-target src/api/context-assembler.ts * @architect-since DS-C * * ## ContextAssembler — Session-Oriented Context Bundle Builder * - * Pure function composition over MasterDataset. Reads from 5 pre-computed + * Pure function composition over PatternGraph. Reads from 5 pre-computed * views (patterns, relationshipIndex, archIndex, deliverables, FSM) and * assembles them into a ContextBundle tailored to the session type. * @@ -39,7 +39,7 @@ * * See: DataAPIContextAssembly spec, Rules 1-5 * - * **When to Use:** When building a session context bundle for a pattern — use this instead of manually querying MasterDataset views. + * **When to Use:** When building a session context bundle for a pattern — use this instead of manually querying PatternGraph views. */ // --------------------------------------------------------------------------- @@ -312,7 +312,7 @@ export interface OverviewSummary { /** * Assemble a curated context bundle for one or more focal patterns. * - * Pure function: takes MasterDataset + options, returns ContextBundle. + * Pure function: takes PatternGraph + options, returns ContextBundle. * * Algorithm: * 1. Resolve each focal pattern via dataset.patterns lookup @@ -320,7 +320,7 @@ export interface OverviewSummary { * 3. For multi-pattern: union deps, tag shared (appearing in 2+ sets) * 4. Populate/omit sections based on sessionType * - * @param dataset - MasterDataset with patterns, relationshipIndex, archIndex + * @param dataset - PatternGraph with patterns, relationshipIndex, archIndex * @param options - Context assembly options * @returns Assembled context bundle */ @@ -337,7 +337,7 @@ export function assembleContext( * Uses iterative BFS with visited-set cycle detection (DS-C-2). * Walks dependsOn/enables (planning) and optionally uses/usedBy (implementation). * - * @param dataset - MasterDataset with patterns and relationshipIndex + * @param dataset - PatternGraph with patterns and relationshipIndex * @param options - Dep-tree options (pattern, maxDepth, includeImplementationDeps) * @returns Root node of the dependency tree */ @@ -354,7 +354,7 @@ export function buildDepTree( * Returns file paths grouped by: primary (spec + stubs), completed deps, * roadmap deps, architecture neighbors. * - * @param dataset - MasterDataset with patterns and relationshipIndex + * @param dataset - PatternGraph with patterns and relationshipIndex * @param pattern - Focal pattern name * @param includeRelated - Whether to include deps and neighbors (default: false) * @returns File reading list with paths organized by relevance @@ -373,7 +373,7 @@ export function buildFileReadingList( * Aggregates: progress counts, active phases, blocking relationships. * A pattern is "blocked" if any of its dependsOn targets has status !== completed. * - * @param dataset - MasterDataset with patterns, byStatus, byPhase, relationshipIndex + * @param dataset - PatternGraph with patterns, byStatus, byPhase, relationshipIndex * @returns Project overview summary */ export function buildOverview( diff --git a/architect/stubs/data-api-output-shaping/output-pipeline.ts b/architect/stubs/data-api-output-shaping/output-pipeline.ts index 6f079d6b..bcac61b3 100644 --- a/architect/stubs/data-api-output-shaping/output-pipeline.ts +++ b/architect/stubs/data-api-output-shaping/output-pipeline.ts @@ -58,7 +58,7 @@ export const DEFAULT_OUTPUT_MODIFIERS: OutputModifiers = { * Composable list filters for the `list` subcommand. * * Filters combine via AND logic. Each filter narrows the result set. - * The pipeline uses Set-based intersection on pre-computed MasterDataset views. + * The pipeline uses Set-based intersection on pre-computed PatternGraph views. */ export interface ListFilters { /** Filter by FSM status (roadmap, active, completed, deferred) */ @@ -95,7 +95,7 @@ export type PipelineInput = | { readonly kind: 'scalar'; readonly data: unknown }; /** - * Set of ProcessStateAPI method names that return ExtractedPattern[]. + * Set of PatternGraphAPI method names that return ExtractedPattern[]. * * Used by the router to tag results with `kind: 'patterns'` for the pipeline. */ @@ -138,12 +138,12 @@ export function applyOutputPipeline( } /** - * Apply composable filters to the pattern list using MasterDataset views. + * Apply composable filters to the pattern list using PatternGraph views. * * Uses Set-based intersection for O(n) composition across pre-computed views. * Pagination (offset/limit) applies after all filters. * - * @param dataset - MasterDataset with pre-computed views + * @param dataset - PatternGraph with pre-computed views * @param filters - Composable list filters * @returns Filtered array of ExtractedPatterns */ diff --git a/architect/stubs/data-api-output-shaping/summarize.ts b/architect/stubs/data-api-output-shaping/summarize.ts index df9b5610..323097d3 100644 --- a/architect/stubs/data-api-output-shaping/summarize.ts +++ b/architect/stubs/data-api-output-shaping/summarize.ts @@ -2,7 +2,7 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIOutputShaping - * @architect-uses ProcessStateAPI + * @architect-uses PatternGraphAPI * @architect-used-by OutputPipeline, ProcessAPICLIImpl * @architect-target src/api/summarize.ts * @architect-since DS-A diff --git a/architect/stubs/data-api-stub-integration/stub-resolver.ts b/architect/stubs/data-api-stub-integration/stub-resolver.ts index 576e27b7..e636fee0 100644 --- a/architect/stubs/data-api-stub-integration/stub-resolver.ts +++ b/architect/stubs/data-api-stub-integration/stub-resolver.ts @@ -2,14 +2,14 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIStubIntegration - * @architect-uses ProcessStateAPI + * @architect-uses PatternGraphAPI * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/stub-resolver.ts * @architect-since DS-B * * ## StubResolver — Design Stub Discovery and Resolution * - * Identifies design session stubs in the MasterDataset and resolves them + * Identifies design session stubs in the PatternGraph and resolves them * against the filesystem to determine implementation status. * * Stub identification heuristic: @@ -66,13 +66,13 @@ export interface StubSummary { // --------------------------------------------------------------------------- /** - * Identify stub patterns from the MasterDataset. + * Identify stub patterns from the PatternGraph. * * A pattern is a stub if: * 1. Its source file path contains '/stubs/' (lives in stubs directory), OR * 2. It has a `targetPath` field (from @architect-target tag) * - * @param dataset - MasterDataset with all patterns + * @param dataset - PatternGraph with all patterns * @returns Array of patterns identified as stubs */ export function findStubPatterns(_dataset: unknown): readonly unknown[] { @@ -138,7 +138,7 @@ export function extractDecisionItems( * Scans pattern descriptions, ADR fields, and seeAlso references * for `PDR-{number}` occurrences. * - * @param patterns - All patterns from MasterDataset + * @param patterns - All patterns from PatternGraph * @param pdrNumber - PDR number to search for (e.g., "012") * @returns Patterns referencing this PDR */ diff --git a/architect/stubs/enhanced-index-generation/index-codec-options.ts b/architect/stubs/enhanced-index-generation/index-codec-options.ts index e745978f..c6be6c59 100644 --- a/architect/stubs/enhanced-index-generation/index-codec-options.ts +++ b/architect/stubs/enhanced-index-generation/index-codec-options.ts @@ -10,11 +10,11 @@ * registered in CodecRegistry, NOT a standalone generator or extension of the * current docs-live/INDEX.md (which is a static file, not generated by any code). * - * **Rationale (DD-1):** The index needs MasterDataset pre-computed views + * **Rationale (DD-1):** The index needs PatternGraph pre-computed views * (`byProductArea`, `byPhase`, `byStatus`, `byCategory`) to generate statistics. - * Only codecs registered in CodecRegistry receive MasterDataset via the + * Only codecs registered in CodecRegistry receive PatternGraph via the * `codec.decode(dataset)` pipeline. A standalone generator (like - * ProcessApiReferenceGenerator) would need to wire its own MasterDataset access, + * ProcessApiReferenceGenerator) would need to wire its own PatternGraph access, * duplicating what CodecBasedGenerator already provides. The codec approach also * gets free integration with `generateDocument('index', dataset)`, * `generateAllDocuments()`, and the `CodecOptions` type-safe options pipeline. @@ -28,7 +28,7 @@ * diagrams, shapes, behaviors) is designed for scoped reference documents that * assemble content from annotated sources. The index document is fundamentally * different — it is a NAVIGATION document that lists OTHER documents, computes - * cross-cutting statistics from MasterDataset views, and composes them with + * cross-cutting statistics from PatternGraph views, and composes them with * editorial preamble sections. None of the 4 layers apply: * - No convention tags to extract (the index doesn't document conventions) * - No scoped diagrams (the index doesn't visualize architecture) @@ -66,7 +66,7 @@ import type { BaseCodecOptions } from '../../src/renderable/codecs/types/base.js * roles matrix, quick finder table). * * The codec composes two content types: - * 1. **Auto-generated** — Statistics and document listings from MasterDataset + * 1. **Auto-generated** — Statistics and document listings from PatternGraph * 2. **Editorial** — Preamble sections authored in config * * This separation follows the same principle as ReferenceDocConfig.preamble @@ -85,7 +85,7 @@ export interface IndexCodecOptions extends BaseCodecOptions { * - Key concepts glossary * * These sections require editorial judgment and cannot be derived - * from MasterDataset metadata. + * from PatternGraph metadata. */ readonly preamble?: readonly SectionBlock[]; @@ -110,7 +110,7 @@ export interface IndexCodecOptions extends BaseCodecOptions { * * Each entry describes a document from either docs/ or docs-live/. * The codec renders this static inventory and combines it with - * statistics derived from MasterDataset views. + * statistics derived from PatternGraph views. * * Documents are organized by topic, NOT by source directory. * The reader should not need to know whether a document is manual diff --git a/architect/stubs/enhanced-index-generation/index-codec.ts b/architect/stubs/enhanced-index-generation/index-codec.ts index 74572545..46cf5cef 100644 --- a/architect/stubs/enhanced-index-generation/index-codec.ts +++ b/architect/stubs/enhanced-index-generation/index-codec.ts @@ -6,14 +6,14 @@ * * ## IndexCodec Factory — DD-1 Implementation Stub * - * Creates the IndexCodec as a Zod codec (MasterDataset -> RenderableDocument). + * Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). * Follows the same factory pattern as all other codecs in the system: * `createIndexCodec(options?) -> DocumentCodec`. * * ### Codec Decode Pipeline * * ``` - * MasterDataset + * PatternGraph * | * +--> [Package Metadata Header] (optional, from options) * | @@ -60,7 +60,7 @@ * `generateDetailFiles` defaults to false. */ -import type { MasterDataset } from '../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../src/validation-schemas/pattern-graph.js'; import type { RenderableDocument, SectionBlock } from '../../src/renderable/schema.js'; import type { IndexCodecOptions, DocumentEntry } from './index-codec-options.js'; import type { StatusCounts } from '../../src/api/types.js'; @@ -72,7 +72,7 @@ import type { StatusCounts } from '../../src/api/types.js'; /** * Create an IndexCodec with custom options. * - * The returned codec transforms MasterDataset into a RenderableDocument + * The returned codec transforms PatternGraph into a RenderableDocument * containing the enhanced index. Register in CodecRegistry as: * * ```typescript @@ -81,13 +81,13 @@ import type { StatusCounts } from '../../src/api/types.js'; * ``` * * @param options - IndexCodecOptions with preamble and visibility toggles - * @returns A Zod codec (MasterDataset -> RenderableDocument) + * @returns A Zod codec (PatternGraph -> RenderableDocument) */ export function createIndexCodec( _options?: IndexCodecOptions ): unknown { // DD-1: Registered in CodecRegistry as document type 'index' - // Uses z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { decode, encode }) + // Uses z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { decode, encode }) // pattern identical to OverviewCodec, BusinessRulesCodec, etc. throw new Error('EnhancedIndexGeneration not yet implemented - roadmap pattern'); } @@ -101,7 +101,7 @@ export function createIndexCodec( // --------------------------------------------------------------------------- /** - * Builds the enhanced index RenderableDocument from MasterDataset. + * Builds the enhanced index RenderableDocument from PatternGraph. * * Section ordering: * 1. Package metadata header (if enabled) @@ -111,12 +111,12 @@ export function createIndexCodec( * 5. Phase progress summary (from byStatus view) * 6. Regeneration commands footer * - * @param dataset - MasterDataset with pre-computed views + * @param dataset - PatternGraph with pre-computed views * @param options - Resolved IndexCodecOptions * @returns RenderableDocument for the enhanced index */ function buildIndexDocument( - _dataset: MasterDataset, + _dataset: PatternGraph, _options: IndexCodecOptions ): RenderableDocument { throw new Error('EnhancedIndexGeneration not yet implemented - roadmap pattern'); @@ -153,11 +153,11 @@ function buildDocumentInventory( * a table identical in structure to buildProductAreaIndex() in * reference-generators.ts, but scoped to the index context. * - * @param dataset - MasterDataset with byProductArea view + * @param dataset - PatternGraph with byProductArea view * @returns SectionBlock[] for the product area statistics */ function buildProductAreaStats( - _dataset: MasterDataset + _dataset: PatternGraph ): SectionBlock[] { // Reuses computeStatusCounts() from src/renderable/utils.ts // Produces table: | Area | Patterns | Completed | Active | Planned | @@ -171,11 +171,11 @@ function buildProductAreaStats( * Uses dataset.byStatus view to show status distribution and * completion percentage via completionPercentage() utility. * - * @param dataset - MasterDataset with byStatus view + * @param dataset - PatternGraph with byStatus view * @returns SectionBlock[] for the phase progress summary */ function buildPhaseProgress( - _dataset: MasterDataset + _dataset: PatternGraph ): SectionBlock[] { // Uses dataset.byStatus (StatusGroupsSchema: { roadmap, active, completed, deferred }) // Renders: "X patterns total: Y completed (Z%), A active, B planned" @@ -204,7 +204,7 @@ void buildPhaseProgress; void buildRegenerationFooter; // Suppress unused import warnings -void (undefined as unknown as MasterDataset); +void (undefined as unknown as PatternGraph); void (undefined as unknown as SectionBlock); void (undefined as unknown as DocumentEntry); void (undefined as unknown as StatusCounts); diff --git a/architect/stubs/enhanced-index-generation/index-preamble-config.ts b/architect/stubs/enhanced-index-generation/index-preamble-config.ts index e0c4a052..300afe60 100644 --- a/architect/stubs/enhanced-index-generation/index-preamble-config.ts +++ b/architect/stubs/enhanced-index-generation/index-preamble-config.ts @@ -26,7 +26,7 @@ * * **Rationale (DD-4):** A glossary entry for "Delivery Workflow FSM" needs a * reader-friendly 2-sentence explanation plus an ASCII state diagram. Pattern - * descriptions are structured for MasterDataset consumers (codecs, API queries), + * descriptions are structured for PatternGraph consumers (codecs, API queries), * not for human onboarding. Attempting to derive glossary content from pattern * metadata would produce entries like "FSM enforcement, pre-commit hooks" — * accurate but unhelpful for someone encountering the concept for the first @@ -158,7 +158,7 @@ export const READING_ORDER_SECTIONS: readonly SectionBlock[] = [ { type: 'paragraph' as const, text: [ - '4. **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** -- Four-stage pipeline, codecs, MasterDataset', + '4. **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** -- Four-stage pipeline, codecs, PatternGraph', '5. **[PROCESS-API.md](docs/PROCESS-API.md)** -- Data API CLI query interface', '6. **[SESSION-GUIDES.md](docs/SESSION-GUIDES.md)** -- Planning/Design/Implementation workflows', '7. **[GHERKIN-PATTERNS.md](docs/GHERKIN-PATTERNS.md)** -- Writing effective Gherkin specs', @@ -233,11 +233,11 @@ export const KEY_CONCEPTS_SECTIONS: readonly SectionBlock[] = [ text: [ '**Delivery Process** -- A code-first documentation and workflow toolkit. Extracts patterns from annotated TypeScript and Gherkin sources, generates markdown documentation, and validates delivery workflow via pre-commit hooks.', '', - '**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the MasterDataset.', + '**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the PatternGraph.', '', - '**MasterDataset** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. No consumer re-derives data from raw scanner output.', + '**PatternGraph** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. No consumer re-derives data from raw scanner output.', '', - '**Codec** -- A Zod-based transformer that decodes MasterDataset into a RenderableDocument. Each codec produces a specific document type (e.g., PatternsDocumentCodec produces PATTERNS.md). Codecs are pure functions with no I/O.', + '**Codec** -- A Zod-based transformer that decodes PatternGraph into a RenderableDocument. Each codec produces a specific document type (e.g., PatternsDocumentCodec produces PATTERNS.md). Codecs are pure functions with no I/O.', '', '**Dual-Source Architecture** -- Feature files own planning metadata (status, phase, dependencies). TypeScript files own implementation metadata (uses, used-by, category). This split prevents ownership conflicts and enables independent annotation cadences.', '', @@ -307,7 +307,7 @@ export const INDEX_DOCUMENT_ENTRIES: readonly DocumentEntry[] = [ { title: 'Architecture', path: 'docs/ARCHITECTURE.md', - description: 'Four-stage pipeline, codecs, MasterDataset, schemas', + description: 'Four-stage pipeline, codecs, PatternGraph, schemas', audience: 'Developers', topic: 'Architecture', }, diff --git a/architect/stubs/mcp-server-integration/file-watcher.ts b/architect/stubs/mcp-server-integration/file-watcher.ts index 59d32e0e..cf5f03ee 100644 --- a/architect/stubs/mcp-server-integration/file-watcher.ts +++ b/architect/stubs/mcp-server-integration/file-watcher.ts @@ -24,7 +24,7 @@ * * DD-3: File type filtering - only .ts and .feature file changes trigger * rebuilds. Changes to .md, .json, or other files are silently ignored - * since they don't affect the MasterDataset. + * since they don't affect the PatternGraph. * * DD-4: Rebuild failure isolation - if a rebuild fails (e.g., parse error * in modified file), the watcher logs the error and keeps the previous diff --git a/architect/stubs/mcp-server-integration/pipeline-session.ts b/architect/stubs/mcp-server-integration/pipeline-session.ts index ba67422c..7292133b 100644 --- a/architect/stubs/mcp-server-integration/pipeline-session.ts +++ b/architect/stubs/mcp-server-integration/pipeline-session.ts @@ -2,14 +2,14 @@ * @architect * @architect-status completed * @architect-implements MCPServerIntegration - * @architect-uses PipelineFactory, ProcessStateAPI, ConfigLoader + * @architect-uses PipelineFactory, PatternGraphAPI, ConfigLoader * @architect-used-by MCPServerImpl, MCPToolRegistry, MCPFileWatcher * @architect-target src/mcp/pipeline-session.ts * @architect-since DS-MCP * - * ## PipelineSessionManager — In-Memory MasterDataset Lifecycle + * ## PipelineSessionManager — In-Memory PatternGraph Lifecycle * - * Manages the persistent MasterDataset that all MCP tool calls read from. + * Manages the persistent PatternGraph that all MCP tool calls read from. * Loads config via auto-detection or explicit globs, builds the pipeline once, * and provides atomic rebuild with concurrent-read safety. * @@ -21,8 +21,8 @@ * v * PipelineSessionManager.initialize() * |-- loadConfig() / applyProjectSourceDefaults() - * |-- buildMasterDataset() - * |-- createProcessStateAPI() + * |-- buildPatternGraph() + * |-- createPatternGraphAPI() * v * PipelineSession { dataset, api, registry, baseDir, sourceGlobs, buildTimeMs } * ``` @@ -56,8 +56,8 @@ export interface SessionOptions { } export interface PipelineSession { - readonly dataset: import('../../src/generators/pipeline/index.js').RuntimeMasterDataset; - readonly api: import('../../src/api/process-state.js').ProcessStateAPI; + readonly dataset: import('../../src/generators/pipeline/index.js').RuntimePatternGraph; + readonly api: import('../../src/api/pattern-graph-api.js').PatternGraphAPI; readonly registry: import('../../src/validation-schemas/tag-registry.js').TagRegistry; readonly baseDir: string; readonly sourceGlobs: { diff --git a/architect/stubs/mcp-server-integration/tool-registry.ts b/architect/stubs/mcp-server-integration/tool-registry.ts index 8acbc2f2..60f35c49 100644 --- a/architect/stubs/mcp-server-integration/tool-registry.ts +++ b/architect/stubs/mcp-server-integration/tool-registry.ts @@ -2,14 +2,14 @@ * @architect * @architect-status completed * @architect-implements MCPServerIntegration - * @architect-uses ProcessStateAPI, MCPPipelineSession + * @architect-uses PatternGraphAPI, MCPPipelineSession * @architect-used-by MCPServerImpl * @architect-target src/mcp/tool-registry.ts * @architect-since DS-MCP * * ## MCPToolRegistry — Tool Definitions with Zod Schemas * - * Defines 25 MCP tools mapping to ProcessStateAPI methods and CLI subcommands. + * Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. * Each tool has a architect_ prefix, a Zod input schema for parameter validation, * and a handler that delegates to existing API functions. * diff --git a/architect/stubs/procedural-guide-codec/annotation-guide-preamble.ts b/architect/stubs/procedural-guide-codec/annotation-guide-preamble.ts index ede5d33d..21de2c0a 100644 --- a/architect/stubs/procedural-guide-codec/annotation-guide-preamble.ts +++ b/architect/stubs/procedural-guide-codec/annotation-guide-preamble.ts @@ -108,7 +108,7 @@ * * | Wrong (type alias) | Correct (schema constant) | * |--------------------|---------------------------| - * | `@extract-shapes MasterDataset` | `@extract-shapes MasterDatasetSchema` | + * | `@extract-shapes PatternGraph` | `@extract-shapes PatternGraphSchema` | * * --- * diff --git a/architect/stubs/procedural-guide-codec/procedural-codec.ts b/architect/stubs/procedural-guide-codec/procedural-codec.ts index 866c05bb..9cdb848a 100644 --- a/architect/stubs/procedural-guide-codec/procedural-codec.ts +++ b/architect/stubs/procedural-guide-codec/procedural-codec.ts @@ -63,7 +63,7 @@ * - ~5% auto-generated: Tag reference summary table derived from taxonomy * registry data via `createReferenceCodec()`'s existing convention or * shape extraction. Tag groups, format types, and example values are - * already in MasterDataset. + * already in PatternGraph. * * **Rationale (DD-5):** The annotation guide content is highly stable -- * the getting-started walkthrough, shape extraction modes, and Zod gotcha diff --git a/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md b/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md index 84737c0f..0738be66 100644 --- a/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md +++ b/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md @@ -35,14 +35,14 @@ Four parallel deep-dives covered the entire pipeline: | -------------------------- | ---------- | -------------- | --------------------------------------------------------------------- | | Codec pipeline | 28 files | ~16,900 | `src/renderable/` (codecs, render, schema, generate) | | Taxonomy & tag registry | 13+ files | ~4,000 | `src/taxonomy/`, scanner parsers, validation schemas | -| MasterDataset & config | 12 files | ~3,500 | `src/validation-schemas/`, `src/config/`, `src/generators/pipeline/` | +| PatternGraph & config | 12 files | ~3,500 | `src/validation-schemas/`, `src/config/`, `src/generators/pipeline/` | | Scanner/extractor/API/lint | 52 files | ~16,900 | `src/scanner/`, `src/extractor/`, `src/api/`, `src/mcp/`, `src/lint/` | --- ## Part 1: Spec Direction Assessment -**The direction is sound.** The four specs address real problems with well-reasoned solutions. The three-layer progressive disclosure model, ProjectMetadata flow through MasterDataset, codec consolidation via view discriminants, and config simplification are all architecturally correct choices. +**The direction is sound.** The four specs address real problems with well-reasoned solutions. The three-layer progressive disclosure model, ProjectMetadata flow through PatternGraph, codec consolidation via view discriminants, and config simplification are all architecturally correct choices. However, the specs optimize locally in several places where a structural intervention would yield more. The window for breaking changes is closing — this review focuses on what to break _now_ for compounding returns. @@ -54,41 +54,41 @@ However, the specs optimize locally in several places where a structural interve The most significant architectural issue is not in the codec layer (where the specs focus) but in the **pipeline data flow**. There are two parallel type systems that don't unify. -#### RuntimeMasterDataset vs MasterDataset +#### RuntimePatternGraph vs PatternGraph `src/generators/pipeline/transform-types.ts:88` defines: ```typescript -export interface RuntimeMasterDataset extends MasterDataset { +export interface RuntimePatternGraph extends PatternGraph { readonly workflow?: LoadedWorkflow; } ``` This creates a type split that propagates everywhere: -| Consumer | Receives | Can Access Workflow? | -| -------------------------------- | ---------------------------- | -------------------- | -| `GeneratorContext.masterDataset` | `RuntimeMasterDataset` | Yes | -| `z.codec.decode(dataset)` | `MasterDataset` (Zod schema) | **No** | -| `ProcessStateAPI` | `RuntimeMasterDataset` | Yes (via factory) | -| `PipelineResult.dataset` | `RuntimeMasterDataset` | Yes | +| Consumer | Receives | Can Access Workflow? | +| ------------------------------- | --------------------------- | -------------------- | +| `GeneratorContext.patternGraph` | `RuntimePatternGraph` | Yes | +| `z.codec.decode(dataset)` | `PatternGraph` (Zod schema) | **No** | +| `PatternGraphAPI` | `RuntimePatternGraph` | Yes (via factory) | +| `PipelineResult.dataset` | `RuntimePatternGraph` | Yes | -**Codecs — the primary consumers of MasterDataset — cannot access workflow data.** The Zod codec type signature enforces `MasterDataset` (the serializable subset), but `LoadedWorkflow` contains `Map` instances that can't be represented in Zod. +**Codecs — the primary consumers of PatternGraph — cannot access workflow data.** The Zod codec type signature enforces `PatternGraph` (the serializable subset), but `LoadedWorkflow` contains `Map` instances that can't be represented in Zod. -**Why this matters for the specs:** The proposed `ProjectMetadata` flows through `MasterDataset` (Spec 1 Rule 5). This is correct. But it means `MasterDataset` is accumulating fields that are really "runtime context for codecs" — not data extracted from source files. `ProjectMetadata`, `tagExampleOverrides`, and `workflow` are all config/runtime context, not extraction products. +**Why this matters for the specs:** The proposed `ProjectMetadata` flows through `PatternGraph` (Spec 1 Rule 5). This is correct. But it means `PatternGraph` is accumulating fields that are really "runtime context for codecs" — not data extracted from source files. `ProjectMetadata`, `tagExampleOverrides`, and `workflow` are all config/runtime context, not extraction products. **Structural intervention — `CodecContext`:** ```typescript interface CodecContext { - readonly dataset: MasterDataset; // extraction products only + readonly dataset: PatternGraph; // extraction products only readonly projectMetadata?: ProjectMetadata; // config identity readonly workflow?: LoadedWorkflow; // FSM definitions readonly tagExampleOverrides?: Partial>; } ``` -This separates concerns cleanly: `MasterDataset` stays as a pure extraction read model (ADR-006), while `CodecContext` carries everything a codec needs. The `DocumentCodec` type would become `z.ZodCodec`. +This separates concerns cleanly: `PatternGraph` stays as a pure extraction read model (ADR-006), while `CodecContext` carries everything a codec needs. The `DocumentCodec` type would become `z.ZodCodec`. **Breaking change:** Yes — every codec's `decode` signature changes. But since `createDecodeOnlyCodec()` is planned anyway (Spec 4 Rule 3), this is the right time. The helper absorbs the change: @@ -233,7 +233,7 @@ Spec 2 includes regression scenarios (Rule 1), but they're mixed with new-featur Every codec repeats the identical ceremony: ```typescript -return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { +return z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { decode: (dataset) => buildDocument(dataset, opts), encode: () => { throw new Error('Codec is decode-only. See zod-codecs.md'); @@ -329,15 +329,15 @@ The `z.any()` on `sections` means **codec output is never schema-validated at ru When `generateFromConfig()` is used (the high-level orchestrator path), config is loaded twice: 1. **Externally** by `loadProjectConfig()` → `ResolvedConfig` -2. **Inside** `buildMasterDataset()` at `build-pipeline.ts:172` which calls `loadConfig(baseDir)` again +2. **Inside** `buildPatternGraph()` at `build-pipeline.ts:172` which calls `loadConfig(baseDir)` again -The second load exists because `buildMasterDataset()` is designed as a standalone entry point (used by 5 consumers: orchestrator, process-api CLI, validate-patterns CLI, REPL, MCP server). +The second load exists because `buildPatternGraph()` is designed as a standalone entry point (used by 5 consumers: orchestrator, process-api CLI, validate-patterns CLI, REPL, MCP server). **Fix:** `PipelineOptions` should accept an optional pre-loaded `TagRegistry`. When provided, skip the internal `loadConfig()`. The 4 non-orchestrator consumers continue to omit it. The orchestrator passes its already-loaded config. Zero behavioral change, one fewer disk read + config resolution. ### SI-2: `bySource` Naming Mismatch -`MasterDataset.bySource` contains four arrays: +`PatternGraph.bySource` contains four arrays: | Key | What it actually is | Problem | | ------------ | ------------------------------------ | -------------------------------------------- | @@ -352,11 +352,11 @@ The second load exists because `buildMasterDataset()` is designed as a standalon ### SI-3: Vestigial Grouping Functions in `utils.ts` -`src/renderable/utils.ts` ~lines 326-354 define `groupByCategory()`, `groupByPhase()`, `groupByQuarter()`. These duplicate the pre-computed views already in `MasterDataset.byCategory`, `byPhase`, `byQuarter`. +`src/renderable/utils.ts` ~lines 326-354 define `groupByCategory()`, `groupByPhase()`, `groupByQuarter()`. These duplicate the pre-computed views already in `PatternGraph.byCategory`, `byPhase`, `byQuarter`. -Post-ADR-006, all consumers should have a `MasterDataset`. These functions exist for a pre-ADR-006 world. +Post-ADR-006, all consumers should have a `PatternGraph`. These functions exist for a pre-ADR-006 world. -**Fix:** Remove and update callers to use MasterDataset views directly. +**Fix:** Remove and update callers to use PatternGraph views directly. ### SI-4: `completionPercentage()` Duplication @@ -377,9 +377,9 @@ The shape extractor also does **double file reads**: the scanner reads file cont `gherkin-extractor.ts` imports `extractPatternTags` from `scanner/gherkin-ast-parser.ts`. This is a scanner function consumed by the extractor. The function is purely transformational and belongs in a shared utility or in the extractor itself. -### SI-7: `GeneratorContext.masterDataset` Is Optional When Always Populated +### SI-7: `GeneratorContext.patternGraph` Is Optional When Always Populated -`src/generators/types.ts:77` types `masterDataset` as `RuntimeMasterDataset | undefined`, but every real invocation populates it. Generators must defensively null-check for a condition that can't happen. +`src/generators/types.ts:77` types `patternGraph` as `RuntimePatternGraph | undefined`, but every real invocation populates it. Generators must defensively null-check for a condition that can't happen. **Fix:** Make it required. @@ -414,7 +414,7 @@ The orchestrator merges codec options with simple spread: `{ ...config.project.c 2. **Rule 4 (output directory):** Also change the preset default to `docs-live` (CI-5). Eliminates the need for most consumers to set `output.directory` at all. -3. **Rule 5 (`MasterDataset.projectMetadata`):** Consider using `CodecContext` (CI-1) instead of adding `projectMetadata` directly to `MasterDataset`. This keeps MasterDataset as a pure extraction read model. +3. **Rule 5 (`PatternGraph.projectMetadata`):** Consider using `CodecContext` (CI-1) instead of adding `projectMetadata` directly to `PatternGraph`. This keeps PatternGraph as a pure extraction read model. 4. **`tagExampleOverrides` validation scenario (line 259-266):** Ensure the Zod schema uses `z.enum(FORMAT_TYPES)` for keys, not a generic `z.record(z.string(), ...)`. @@ -454,7 +454,7 @@ The orchestrator merges codec options with simple spread: `{ ...config.project.c 2. **`reference.ts` decomposition should be 5 files, not 3** (CI-6). Independent PR, not coupled with the consolidation. -3. **`createDecodeOnlyCodec()` should accept `CodecContext`** (CI-1), not raw `MasterDataset`. +3. **`createDecodeOnlyCodec()` should accept `CodecContext`** (CI-1), not raw `PatternGraph`. --- @@ -462,7 +462,7 @@ The orchestrator merges codec options with simple spread: `{ ...config.project.c ### BC-1: Introduce `CodecContext` Wrapper (CI-1) -Replace `MasterDataset` as the codec input with `CodecContext` that separates extraction products from runtime context. All codecs change signature via `createDecodeOnlyCodec()`. +Replace `PatternGraph` as the codec input with `CodecContext` that separates extraction products from runtime context. All codecs change signature via `createDecodeOnlyCodec()`. ### BC-2: Make `docs-live` the Preset Default (CI-5) @@ -480,7 +480,7 @@ Clean up all instances. In Gherkin files where category intent is real, replace Update to `@architect-sequence-error`. -### BC-6: Make `GeneratorContext.masterDataset` Required +### BC-6: Make `GeneratorContext.patternGraph` Required Remove the `undefined` from the type. Eliminate ~21 unnecessary null checks. @@ -497,7 +497,7 @@ The initial review session produced findings CI-1 through CI-6 and BC-1 through | Previous Finding | Disposition | Notes | | ---------------------------------------------------- | -------------------------------------------------------------------------- | ----- | | CI-1: Self-describing codecs | **Validated and extended** — also derive `CodecOptions` type automatically | -| CI-2: `createDecodeOnlyCodec()` design | **Validated** — should accept `CodecContext`, not `MasterDataset` | +| CI-2: `createDecodeOnlyCodec()` design | **Validated** — should accept `CodecContext`, not `PatternGraph` | | CI-3: Progressive disclosure as renderer concern | **Validated** — `detailLevel` enforcement also belongs in renderer | | CI-4: `output.directory` preset default | **Validated** — change at preset level for `docs-live` | | CI-5: `reference.ts` decomposition timing | **Extended** — 5 files, not 3; diagrams alone are 690 lines | @@ -505,7 +505,7 @@ The initial review session produced findings CI-1 through CI-6 and BC-1 through | BC-1: Remove `DOCUMENT_TYPE_RENDERERS` | **Validated** — inline on `codecMeta` | | BC-2: `docs-live` preset default | **Validated** | | BC-3: Optional `behaviorCategories`/`conventionTags` | **Validated** — schema-level `.default([])` | -| BC-4: Remove `isCore` from MasterDataset views | **Superseded** — the `@architect-core` ghost tag is the real issue | +| BC-4: Remove `isCore` from PatternGraph views | **Superseded** — the `@architect-core` ghost tag is the real issue | | BC-5: Fix flag example in TaxonomyCodec | **Validated** — `@architect-core` → `@architect-sequence-error` | | BC-6: Remove flag format entirely | **Overturned** — flag format costs nearly nothing, semantic value is real | @@ -540,17 +540,17 @@ The previous review suggested removing the `flag` format type since only `sequen ## Part 9: One-Line Verdicts -| Area | Verdict | -| ---------------------------------------------------------------- | ------------------------------------------------------------------------ | -| Overall spec direction | **Sound** — addresses real problems, minor structural adjustments needed | -| Pipeline split-brain (`RuntimeMasterDataset` vs `MasterDataset`) | **Address now** — introduce `CodecContext` | -| Type safety gaps (25 `as` casts, index signatures) | **Acceptable as-is** — Zod validation downstream catches errors | -| `@architect-core` ghost tag | **Clean up immediately** — dual behavior in TS vs Gherkin is a live bug | -| Flag format removal | **Don't remove** — architectural cost is trivial, semantic value is real | -| Self-describing codecs | **Missing from specs, needed before consolidation** | -| `reference.ts` decomposition | **5 files, not 3** — diagrams alone are 690 lines | -| Progressive disclosure ownership | **Render layer** — not codec options | -| `detailLevel` enforcement | **Renderer default + codec override** — covers all 21 codecs, not just 3 | -| `bySource` naming | **Rename to `bySourceType`** — `roadmap`/`prd` are not source types | -| Double config load | **Fix via optional `TagRegistry` on `PipelineOptions`** | -| `autoDiscoverDocuments` | **Defer** — adds coupling for unclear benefit | +| Area | Verdict | +| -------------------------------------------------------------- | ------------------------------------------------------------------------ | +| Overall spec direction | **Sound** — addresses real problems, minor structural adjustments needed | +| Pipeline split-brain (`RuntimePatternGraph` vs `PatternGraph`) | **Address now** — introduce `CodecContext` | +| Type safety gaps (25 `as` casts, index signatures) | **Acceptable as-is** — Zod validation downstream catches errors | +| `@architect-core` ghost tag | **Clean up immediately** — dual behavior in TS vs Gherkin is a live bug | +| Flag format removal | **Don't remove** — architectural cost is trivial, semantic value is real | +| Self-describing codecs | **Missing from specs, needed before consolidation** | +| `reference.ts` decomposition | **5 files, not 3** — diagrams alone are 690 lines | +| Progressive disclosure ownership | **Render layer** — not codec options | +| `detailLevel` enforcement | **Renderer default + codec override** — covers all 21 codecs, not just 3 | +| `bySource` naming | **Rename to `bySourceType`** — `roadmap`/`prd` are not source types | +| Double config load | **Fix via optional `TagRegistry` on `PipelineOptions`** | +| `autoDiscoverDocuments` | **Defer** — adds coupling for unclear benefit | diff --git a/docs-inbox/codebase-exploration-findings.md b/docs-inbox/codebase-exploration-findings.md index d41f54e4..db74d6f0 100644 --- a/docs-inbox/codebase-exploration-findings.md +++ b/docs-inbox/codebase-exploration-findings.md @@ -51,7 +51,7 @@ - `NormalizedStatusFilter` (line 38): alias for `NormalizedStatus` from taxonomy - `CodecLimits` (lines 43-50): `recentItems`, `maxDetailFiles`, `collapseThreshold` - `BaseCodecOptions` (lines 55-64): `generateDetailFiles`, `detailLevel`, `limits` -- `DocumentCodec` (lines 127-130): `z.ZodCodec` +- `DocumentCodec` (lines 127-130): `z.ZodCodec` **Key functions:** @@ -181,7 +181,7 @@ export const DEFAULT_XXX_OPTIONS: Required = { ... }; // 3. Factory function export function createXxxCodec(options?: XxxCodecOptions): DocumentCodec { const opts = mergeOptions(DEFAULT_XXX_OPTIONS, options); - return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { + return z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { decode: (dataset) => buildXxxDocument(dataset, opts), encode: () => { throw new Error('Codec is decode-only.'); }, }); @@ -200,7 +200,7 @@ generate.ts ──depends-on──> codecs/index.ts (barrel) ──depends-on──> schema.ts (RenderableDocument) ──depends-on──> codecs/types/base.ts (DocumentCodec, BaseCodecOptions) -Each codec ──depends-on──> validation-schemas/master-dataset.ts (MasterDataset) +Each codec ──depends-on──> validation-schemas/master-dataset.ts (PatternGraph) ──depends-on──> schema.ts (block builders) ──depends-on──> codecs/types/base.ts (BaseCodecOptions, mergeOptions) ──depends-on──> codecs/shared-schema.ts (RenderableDocumentOutputSchema) @@ -301,9 +301,9 @@ Preserves type safety: `FormatType` constrains keys, `Partial` allows omissions. --- -## 3. MasterDataset & Configuration (~3,500 lines) +## 3. PatternGraph & Configuration (~3,500 lines) -### 3.1 MasterDataset Schema (352 lines) +### 3.1 PatternGraph Schema (352 lines) Four layers: @@ -318,19 +318,19 @@ Four layers: **`bySource` (lines 113-125):** Contains `typescript`, `gherkin`, `roadmap`, `prd`. The latter two are NOT source types — naming mismatch. -**No workflow in Zod schema:** `LoadedWorkflow` contains Maps (not JSON-serializable), excluded from schema. Handled by `RuntimeMasterDataset`. +**No workflow in Zod schema:** `LoadedWorkflow` contains Maps (not JSON-serializable), excluded from schema. Handled by `RuntimePatternGraph`. -### 3.2 RuntimeMasterDataset vs MasterDataset +### 3.2 RuntimePatternGraph vs PatternGraph `transform-types.ts:88`: ```typescript -export interface RuntimeMasterDataset extends MasterDataset { +export interface RuntimePatternGraph extends PatternGraph { readonly workflow?: LoadedWorkflow; } ``` -Creates a type split: codecs receive `MasterDataset` (no workflow), `GeneratorContext` carries `RuntimeMasterDataset` (with workflow), `ProcessStateAPI` wraps `RuntimeMasterDataset`. +Creates a type split: codecs receive `PatternGraph` (no workflow), `GeneratorContext` carries `RuntimePatternGraph` (with workflow), `PatternGraphAPI` wraps `RuntimePatternGraph`. ### 3.3 Configuration System @@ -362,7 +362,7 @@ Two presets: 5. Merge patterns 6. Compute hierarchy children 7. Load workflow -8. Transform to MasterDataset +8. Transform to PatternGraph **5 consumers:** Orchestrator, Process API CLI, validate-patterns CLI, REPL, MCP server. @@ -379,19 +379,19 @@ Two presets: **Codec options merge (lines 328-366):** Simple spread: `{ ...config.project.codecOptions, ...options?.codecOptions }`. **Shallow merge** — nested options clobbered, not deep-merged. -**`GeneratorContext.masterDataset` typed as optional** (types.ts:77): `RuntimeMasterDataset | undefined`. Always populated in practice. +**`GeneratorContext.patternGraph` typed as optional** (types.ts:77): `RuntimePatternGraph | undefined`. Always populated in practice. ### 3.7 Result Monad (`result.ts` — 107 lines) Discriminated union with: `ok()`, `err()`, `isOk()`, `isErr()`, `unwrap()`, `unwrapOr()`, `map()`, `mapErr()`. -Used consistently in: pipeline factory, scanner, config loader, orchestrator, document generation. **Not used in:** `transformToMasterDataset()` (returns plain values with `ValidationSummary`). +Used consistently in: pipeline factory, scanner, config loader, orchestrator, document generation. **Not used in:** `transformToPatternGraph()` (returns plain values with `ValidationSummary`). Missing: `flatMap`/`andThen`, `tap`. Manual unwrapping needed for chaining. ### 3.8 Renderable Utils (`utils.ts` — 419 lines) -**Vestigial functions:** `groupByCategory()`, `groupByPhase()`, `groupByQuarter()` (lines 326-354) duplicate MasterDataset pre-computed views. +**Vestigial functions:** `groupByCategory()`, `groupByPhase()`, `groupByQuarter()` (lines 326-354) duplicate PatternGraph pre-computed views. **Duplication:** `completionPercentage()` and `isFullyCompleted()` exist in both `utils.ts` (lines 289-299) and `transform-dataset.ts` (lines 410-419). @@ -446,7 +446,7 @@ Both produce `ExtractedPattern` and validate via `ExtractedPatternSchema.safePar ### 4.3 Process Data API (14 files, 4,110 lines) -**`ProcessStateAPI` (process-state.ts line 87):** 25-method interface in 5 groups: +**`PatternGraphAPI` (process-state.ts line 87):** 25-method interface in 5 groups: - Status queries (5 methods) - Phase queries (4 methods) @@ -454,11 +454,11 @@ Both produce `ExtractedPattern` and validate via `ExtractedPatternSchema.safePar - Pattern queries (7 methods) - Timeline queries (5 methods) -Plus `getMasterDataset()`. +Plus `getPatternGraph()`. **Implementation:** Thin facade — most methods are 1-5 line delegations to pre-computed dataset views. -**Linear scan issue:** `getPatternsByStatus()` (line 311) filters `dataset.patterns` linearly. MasterDataset pre-computes normalized groups but not exact FSM status. A `byExactStatus` index would be O(1). +**Linear scan issue:** `getPatternsByStatus()` (line 311) filters `dataset.patterns` linearly. PatternGraph pre-computes normalized groups but not exact FSM status. A `byExactStatus` index would be O(1). **Context assembler** (726 lines): The largest API file. Handles 3 session types with different inclusion rules. Candidate for strategy pattern refactoring. @@ -473,7 +473,7 @@ Plus `getMasterDataset()`. - 6 architecture (JSON output) - 3 management -**Tool-to-API mapping:** Every tool wraps either a `ProcessStateAPI` method, a standalone query function, or a composed operation. +**Tool-to-API mapping:** Every tool wraps either a `PatternGraphAPI` method, a standalone query function, or a composed operation. **`--watch` implementation:** `chokidar`-based file watching with 500ms debounce. Failed rebuilds log error and keep previous dataset. @@ -523,7 +523,7 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC/API/LINT | ----------------------- | ------------- | ----------------------------------------- | | Scanner → Extractor | Good | Clean type contract | | Extractor → Transformer | Good | Unified `ExtractedPattern` type | -| Transformer → API | Excellent | MasterDataset is the single read model | +| Transformer → API | Excellent | PatternGraph is the single read model | | API → MCP | Good | Thin wrapper, 1:1 mapping | | Scanner → Lint | Clean | Lint reuses scanner infrastructure | | Extractor → Renderable | **Violation** | `renderShapesAsMarkdown` wrong layer | @@ -541,7 +541,7 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC/API/LINT 2. **Pure codecs:** All codecs are pure functions (dataset in, document out). No I/O, no side effects. 3. **Type-safe taxonomy:** Multi-layer enforcement (const arrays → union types → Zod schemas → runtime Sets). 4. **Result monad:** Consistent error handling in pipeline, scanner, config loader. -5. **Pre-computed views:** O(1) access in MasterDataset for status, phase, quarter, category. +5. **Pre-computed views:** O(1) access in PatternGraph for status, phase, quarter, category. 6. **Decider pattern:** Process Guard is pure — no I/O, no side effects, easy to test. ### 5.2 Systematic Issues @@ -551,15 +551,15 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC/API/LINT 3. **Double file reads:** Scanner reads, extractor re-reads for shapes. 4. **Double config load:** Orchestrator loads config, pipeline loads again. 5. **Layer violations:** Shape rendering in extractor, tag extraction across scanner/extractor boundary. -6. **Vestigial code:** Grouping functions that duplicate MasterDataset views. +6. **Vestigial code:** Grouping functions that duplicate PatternGraph views. 7. **Inconsistent patterns:** Two different pattern-building styles between TS and Gherkin extractors. 8. **Ghost annotations:** `@architect-core` with dual behavior by source type. ### 5.3 `ValidationRulesCodec` Note -This codec ignores `MasterDataset` entirely (confirmed: `_dataset` parameter unused). It builds from hardcoded `RULE_DEFINITIONS`. Two options: +This codec ignores `PatternGraph` entirely (confirmed: `_dataset` parameter unused). It builds from hardcoded `RULE_DEFINITIONS`. Two options: -1. Make it read rules from MasterDataset (which HAS business rules from Gherkin extraction) — architecturally cleaner +1. Make it read rules from PatternGraph (which HAS business rules from Gherkin extraction) — architecturally cleaner 2. Document it as a "static content codec" — honest about what it is Option 1 is more useful but requires decider rules to be extractable as data. diff --git a/docs-inbox/refactoring-execution-guide.md b/docs-inbox/refactoring-execution-guide.md index 0fce83d0..812a1cb7 100644 --- a/docs-inbox/refactoring-execution-guide.md +++ b/docs-inbox/refactoring-execution-guide.md @@ -115,7 +115,7 @@ Phases are ordered by: (1) safety prerequisites, (2) structural foundations that **Scope:** - Add `createDecodeOnlyCodec(decode)` function to `src/renderable/codecs/types/base.ts` -- Initially accepts `(dataset: MasterDataset) => RenderableDocument` (Phase 1B changes the signature) +- Initially accepts `(dataset: PatternGraph) => RenderableDocument` (Phase 1B changes the signature) - Returns `DocumentCodec` with standard encode-throws behavior - Migrate all 21 registered codecs + unregistered reference codecs to use it - Remove all inline `z.codec()` + `encode: () => throw` patterns @@ -138,7 +138,7 @@ Phases are ordered by: (1) safety prerequisites, (2) structural foundations that ### 1B: `CodecContext` Wrapper (Decision Point) -**Why:** Separates extraction products from runtime context. Makes `MasterDataset` a pure read model (ADR-006 alignment). +**Why:** Separates extraction products from runtime context. Makes `PatternGraph` a pure read model (ADR-006 alignment). **Decision required:** This is the highest-leverage structural change but also the highest-risk. Two options: @@ -146,7 +146,7 @@ Phases are ordered by: (1) safety prerequisites, (2) structural foundations that ```typescript interface CodecContext { - readonly dataset: MasterDataset; + readonly dataset: PatternGraph; readonly projectMetadata?: ProjectMetadata; readonly workflow?: LoadedWorkflow; readonly tagExampleOverrides?: Partial>; @@ -155,8 +155,8 @@ interface CodecContext { All codecs change from `decode(dataset)` to `decode(context)`. The `createDecodeOnlyCodec()` helper absorbs the change — codec authors update one function signature per codec. -**Option B — `projectMetadata` on MasterDataset (non-breaking, incremental):** -Add `projectMetadata?: ProjectMetadata` to `MasterDatasetSchema` as the specs propose. Simpler, but MasterDataset accumulates non-extraction fields. +**Option B — `projectMetadata` on PatternGraph (non-breaking, incremental):** +Add `projectMetadata?: ProjectMetadata` to `PatternGraphSchema` as the specs propose. Simpler, but PatternGraph accumulates non-extraction fields. **Recommendation:** Option A if this is the refactoring window. Option B if shipping speed matters more. @@ -169,8 +169,8 @@ Add `projectMetadata?: ProjectMetadata` to `MasterDatasetSchema` as the specs pr **Acceptance criteria:** -- [ ] No codec directly receives `MasterDataset` — all go through `CodecContext` -- [ ] `MasterDataset` has no `projectMetadata` field (it's on `CodecContext`) +- [ ] No codec directly receives `PatternGraph` — all go through `CodecContext` +- [ ] `PatternGraph` has no `projectMetadata` field (it's on `CodecContext`) - [ ] All codecs access dataset via `context.dataset` - [ ] `pnpm build && pnpm test` passes @@ -294,13 +294,13 @@ readonly tagExampleOverrides?: Record; - `src/config/presets.ts` — add `output.directory: 'docs-live'` to libar-generic preset - `src/renderable/codecs/reference.ts` — `ReferenceDocConfig` optional fields, `preambleFile` -### 2C: MasterDataset / CodecContext Integration +### 2C: PatternGraph / CodecContext Integration **Scope:** (Spec 1 Rule 5) **If CodecContext (1B Option A):** Add `projectMetadata` to `CodecContext`, populated in orchestrator from resolved config. -**If MasterDataset (1B Option B):** Add `projectMetadata?: ProjectMetadata` to `MasterDatasetSchema`, populated in `buildMasterDataset()`. +**If PatternGraph (1B Option B):** Add `projectMetadata?: ProjectMetadata` to `PatternGraphSchema`, populated in `buildPatternGraph()`. ### 2D: Codec Consumption @@ -533,7 +533,7 @@ These are real improvements but not blocking any spec work: ### 7A: Pipeline Efficiency - `PipelineOptions` accepts optional pre-loaded `TagRegistry` (eliminates double config load) -- Make `GeneratorContext.masterDataset` required (eliminate unnecessary optionality) +- Make `GeneratorContext.patternGraph` required (eliminate unnecessary optionality) ### 7B: Layer Boundary Fixes diff --git a/docs-inbox/reimplementation-drift-analysis.md b/docs-inbox/reimplementation-drift-analysis.md index eb198310..1f92bfd2 100644 --- a/docs-inbox/reimplementation-drift-analysis.md +++ b/docs-inbox/reimplementation-drift-analysis.md @@ -32,7 +32,7 @@ And these specs are scope for the features introduced: ``` ┌── DataAPIOutputShaping (25a) ─────── [DONE] 8/8 - ProcessStateAPI ─────┤ + PatternGraphAPI ─────┤ (V1, exists) └── DataAPIContextAssembly (25b) ───── [DONE] 7/7 │ └── DataAPIDesignSessionSupport (25c) ── [PARTIALLY-DESIGNED] diff --git a/docs-inbox/session-prompt-generator-architecture-review.md b/docs-inbox/session-prompt-generator-architecture-review.md index 3cf40919..d76ee761 100644 --- a/docs-inbox/session-prompt-generator-architecture-review.md +++ b/docs-inbox/session-prompt-generator-architecture-review.md @@ -26,10 +26,10 @@ The insight that **CLAUDE.md sections should be generated from decision records* The codebase has **two deliberate rendering paths** established by ADR-008: -| Path | Pipeline | Audience | Format | -| -------------- | ------------------------------------------------------------------------- | ------------------------- | ------------------------------------ | -| **Codec path** | MasterDataset → Codec → RenderableDocument → UniversalRenderer → Markdown | Human docs / AI reference | Markdown with headers, tables, lists | -| **Text path** | MasterDataset → Assembler → Formatter → Plain text | AI session context | `=== SECTION ===` markers, compact | +| Path | Pipeline | Audience | Format | +| -------------- | ------------------------------------------------------------------------ | ------------------------- | ------------------------------------ | +| **Codec path** | PatternGraph → Codec → RenderableDocument → UniversalRenderer → Markdown | Human docs / AI reference | Markdown with headers, tables, lists | +| **Text path** | PatternGraph → Assembler → Formatter → Plain text | AI session context | `=== SECTION ===` markers, compact | Session prompts are **AI session context** — they tell an agent what to do. Per the codebase's own architectural decisions, they belong on the text path. @@ -122,7 +122,7 @@ More importantly, prompt sections should be assembled **programmatically** from Instead of recipe→template→markdown, I recommend **extending the existing context assembly pipeline**: ``` -MasterDataset ──→ assembleContext() ──→ ContextBundle ──→ formatContextBundle() ──→ text +PatternGraph ──→ assembleContext() ──→ ContextBundle ──→ formatContextBundle() ──→ text (existing, + conventions) (extended with conventions) (extended sections) ``` @@ -131,7 +131,7 @@ MasterDataset ──→ assembleContext() ──→ ContextBundle ``` Decision Records (tagged @convention) ─┐ ├──→ assembleSessionPrompt() ──→ SessionPromptBundle ──→ formatSessionPrompt() -ProcessStateAPI queries ───────────────┘ ↓ +PatternGraphAPI queries ───────────────┘ ↓ Structured text ``` @@ -140,7 +140,7 @@ ProcessStateAPI queries ───────────────┘ 1. **ADR-008 aligned** — text output for AI, not markdown 2. **No new engine** — extends existing assembler + formatter pattern (same as scope-validator, handoff-generator) 3. **Parameterized by design** — pattern name is already a parameter -4. **Convention injection is pure data** — filter decision records from MasterDataset by `@convention` tag, extract Rule block content +4. **Convention injection is pure data** — filter decision records from PatternGraph by `@convention` tag, extract Rule block content 5. **Co-located formatter** — per PDR-002 DD-7, formatters live with their data assemblers (see `scope-validator.ts:134`, `handoff-generator.ts:180`) ### What the prompt assembler does diff --git a/docs-inbox/session-prompt-generator-brief.md b/docs-inbox/session-prompt-generator-brief.md index 2e5def11..4df74c59 100644 --- a/docs-inbox/session-prompt-generator-brief.md +++ b/docs-inbox/session-prompt-generator-brief.md @@ -3,7 +3,7 @@ > **Status:** Ready for Planning Session > **Scope:** New capability for `@libar-dev/architect` > **Phase:** TBD (after DataAPIDesignSessionSupport) -> **Depends on:** DataAPIDesignSessionSupport (completed), ProcessStateAPI (completed) +> **Depends on:** DataAPIDesignSessionSupport (completed), PatternGraphAPI (completed) --- @@ -22,7 +22,7 @@ The Process API already solves the _dynamic data_ half of this problem (`context Generate complete session prompts by composing: -- **Dynamic pattern data** from ProcessStateAPI (already exists) +- **Dynamic pattern data** from PatternGraphAPI (already exists) - **Static conventions** from tagged decision records (new capability) - **Session-type rules** that filter conventions by applicability (new capability) @@ -41,10 +41,10 @@ pnpm architect:query -- session-prompt --type design The codebase has two deliberate rendering architectures: -| Path | Pipeline | Audience | Format | -| -------------- | -------------------------------------------------------- | ------------------------- | ------------------------- | -| **Codec path** | MasterDataset -> Codec -> RenderableDocument -> Markdown | Human docs / AI reference | Markdown | -| **Text path** | MasterDataset -> Assembler -> Formatter -> Plain text | AI session context | `=== SECTION ===` markers | +| Path | Pipeline | Audience | Format | +| -------------- | ------------------------------------------------------- | ------------------------- | ------------------------- | +| **Codec path** | PatternGraph -> Codec -> RenderableDocument -> Markdown | Human docs / AI reference | Markdown | +| **Text path** | PatternGraph -> Assembler -> Formatter -> Plain text | AI session context | `=== SECTION ===` markers | Session prompts are AI session context. They belong on the **text path**. @@ -75,7 +75,7 @@ Follow the established pattern from `scope-validator.ts` and `handoff-generator. ``` Decision Records (tagged @convention) ---+ +--> assembleSessionPrompt() --> SessionPromptBundle --> formatSessionPrompt() -ProcessStateAPI queries -----------------+ | +PatternGraphAPI queries -----------------+ | Structured text ``` @@ -95,7 +95,7 @@ ProcessStateAPI queries -----------------+ | `validateScope()` | Yes | Pre-flight readiness checks | | `generateHandoff()` | Yes | Session-end state summary | | `formatContextBundle()` | Yes | Text rendering with `=== SECTION ===` markers | -| MasterDataset patterns | Yes | Decision records are already extracted as patterns | +| PatternGraph patterns | Yes | Decision records are already extracted as patterns | **Only truly new piece:** Convention extraction — filter `dataset.patterns` for decision records with `@architect-convention` tags, extract their Rule block content, group by topic. diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index 652f859b..78bd9777 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -25,7 +25,7 @@ Component architecture with bounded context isolation: ```mermaid graph TB subgraph api["Api BC"] - MasterDataset["MasterDataset[read-model]"] + PatternGraph["PatternGraph[read-model]"] MCPToolRegistry["MCPToolRegistry[service]"] MCPServerImpl["MCPServerImpl[service]"] MCPPipelineSession["MCPPipelineSession[service]"] @@ -33,7 +33,7 @@ graph TB MCPFileWatcher["MCPFileWatcher[infrastructure]"] PatternSummarizerImpl["PatternSummarizerImpl[service]"] ScopeValidatorImpl["ScopeValidatorImpl[service]"] - ProcessStateAPI["ProcessStateAPI[service]"] + PatternGraphAPI["PatternGraphAPI[service]"] HandoffGeneratorImpl["HandoffGeneratorImpl[service]"] FuzzyMatcherImpl["FuzzyMatcherImpl[service]"] CoverageAnalyzerImpl["CoverageAnalyzerImpl[service]"] @@ -69,11 +69,11 @@ graph TB ContentDeduplicator["ContentDeduplicator[infrastructure]"] CodecBasedGenerator["CodecBasedGenerator[service]"] FileCache["FileCache[infrastructure]"] + DesignReviewGenerator["DesignReviewGenerator[service]"] + DecisionDocGenerator["DecisionDocGenerator[service]"] TransformDataset["TransformDataset[service]"] SequenceTransformUtils["SequenceTransformUtils[service]"] RelationshipResolver["RelationshipResolver[service]"] - DesignReviewGenerator["DesignReviewGenerator[service]"] - DecisionDocGenerator["DecisionDocGenerator[service]"] end subgraph lint["Lint BC"] LintRules["LintRules[service]"] @@ -114,12 +114,12 @@ graph TB end DoDValidator --> DualSourceExtractor GherkinScanner --> GherkinASTParser - MCPToolRegistry --> ProcessStateAPI + MCPToolRegistry --> PatternGraphAPI MCPToolRegistry --> MCPPipelineSession MCPServerImpl --> MCPPipelineSession MCPServerImpl --> MCPToolRegistry MCPServerImpl --> MCPFileWatcher - MCPPipelineSession --> ProcessStateAPI + MCPPipelineSession --> PatternGraphAPI MCPPipelineSession --> ConfigLoader MCPModule --> MCPServerImpl MCPModule --> MCPPipelineSession @@ -133,45 +133,45 @@ graph TB SourceMapper -.-> DecisionDocCodec SourceMapper -.-> GherkinASTParser Documentation_Generation_Orchestrator --> Pattern_Scanner - ReplMode --> ProcessStateAPI - ProcessAPICLIImpl --> ProcessStateAPI - ProcessAPICLIImpl --> MasterDataset + ReplMode --> PatternGraphAPI + ProcessAPICLIImpl --> PatternGraphAPI + ProcessAPICLIImpl --> PatternGraph ProcessAPICLIImpl --> PatternSummarizerImpl ProcessAPICLIImpl --> FuzzyMatcherImpl ProcessAPICLIImpl --> OutputPipelineImpl OutputPipelineImpl --> PatternSummarizerImpl MCPServerBin --> MCPServerImpl - ConfigResolver --> ArchitectFactory - ArchitectFactory --> RegexBuilders - ConfigLoader --> ArchitectFactory - PatternSummarizerImpl --> ProcessStateAPI - ScopeValidatorImpl --> ProcessStateAPI - ScopeValidatorImpl --> MasterDataset - ProcessStateAPI --> MasterDataset - ProcessStateAPI --> FSMValidator - HandoffGeneratorImpl --> ProcessStateAPI - HandoffGeneratorImpl --> MasterDataset + PatternSummarizerImpl --> PatternGraphAPI + ScopeValidatorImpl --> PatternGraphAPI + ScopeValidatorImpl --> PatternGraph + PatternGraphAPI --> PatternGraph + PatternGraphAPI --> FSMValidator + HandoffGeneratorImpl --> PatternGraphAPI + HandoffGeneratorImpl --> PatternGraph HandoffGeneratorImpl --> ContextFormatterImpl CoverageAnalyzerImpl --> Pattern_Scanner - CoverageAnalyzerImpl --> MasterDataset + CoverageAnalyzerImpl --> PatternGraph ContextFormatterImpl --> ContextAssemblerImpl - ContextAssemblerImpl --> ProcessStateAPI - ContextAssemblerImpl --> MasterDataset + ContextAssemblerImpl --> PatternGraphAPI + ContextAssemblerImpl --> PatternGraph ContextAssemblerImpl --> PatternSummarizerImpl ContextAssemblerImpl --> FuzzyMatcherImpl - ArchQueriesImpl --> ProcessStateAPI - ArchQueriesImpl --> MasterDataset + ArchQueriesImpl --> PatternGraphAPI + ArchQueriesImpl --> PatternGraph + ConfigResolver --> ArchitectFactory + ArchitectFactory --> RegexBuilders + ConfigLoader --> ArchitectFactory FSMValidator --> FSMTransitions FSMValidator --> FSMStates - DesignReviewCodec --> MasterDataset - ArchitectureCodec --> MasterDataset + DesignReviewCodec --> PatternGraph + ArchitectureCodec --> PatternGraph ProcessGuardDecider --> FSMValidator - TransformDataset --> MasterDataset - SequenceTransformUtils --> MasterDataset DesignReviewGenerator --> DesignReviewCodec - DesignReviewGenerator --> MasterDataset + DesignReviewGenerator --> PatternGraph DecisionDocGenerator -.-> DecisionDocCodec DecisionDocGenerator -.-> SourceMapper + TransformDataset --> PatternGraph + SequenceTransformUtils --> PatternGraph ``` --- @@ -196,7 +196,7 @@ All components with architecture annotations: | 🚧 Pattern Helpers | api | - | domain | src/api/pattern-helpers.ts | | 🚧 MCP File Watcher | api | infrastructure | infrastructure | src/mcp/file-watcher.ts | | 🚧 MCP Module | api | infrastructure | application | src/mcp/index.ts | -| ✅ Master Dataset | api | read-model | domain | src/validation-schemas/master-dataset.ts | +| ✅ Pattern Graph | api | read-model | domain | src/validation-schemas/pattern-graph.ts | | 🚧 Arch Queries Impl | api | service | domain | src/api/arch-queries.ts | | 🚧 Context Assembler Impl | api | service | application | src/api/context-assembler.ts | | 🚧 Context Formatter Impl | api | service | application | src/api/context-formatter.ts | @@ -206,8 +206,8 @@ All components with architecture annotations: | 🚧 MCP Pipeline Session | api | service | application | src/mcp/pipeline-session.ts | | 🚧 MCP Server Impl | api | service | application | src/mcp/server.ts | | 🚧 MCP Tool Registry | api | service | application | src/mcp/tool-registry.ts | +| 🚧 Pattern Graph API | api | service | application | src/api/pattern-graph-api.ts | | 🚧 Pattern Summarizer Impl | api | service | application | src/api/summarize.ts | -| 🚧 Process State API | api | service | application | src/api/process-state.ts | | ✅ Scope Validator Impl | api | service | application | src/api/scope-validator.ts | | ✅ CLI Schema | cli | - | domain | src/cli/cli-schema.ts | | 🚧 Dataset Cache | cli | infrastructure | infrastructure | src/cli/dataset-cache.ts | diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 568b3faf..3ff495b1 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -17,45 +17,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. - **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. - **MCP Server Impl**: Main entry point for the Architect MCP server. -- **MCP Pipeline Session**: Manages the in-memory MasterDataset lifecycle for the MCP server. +- **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. - **MCP Module**: Public API for the MCP server module. - **MCP File Watcher**: Watches source file globs and triggers debounced pipeline rebuilds. - **Git Name Status Parser**: Parses NUL-delimited git name-status output into categorized file lists. - **Git Module**: Shared git utilities used by both generators and lint layers. - **Git Helpers**: Low-level helpers for safe git command execution and input sanitization. - **Git Branch Diff**: Provides lightweight git diff operations for determining which files changed relative to a base branch. -- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. -- **Process API CLI Impl**: Exposes ProcessStateAPI methods as CLI subcommands with JSON output. -- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. -- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. -- **Lint Process CLI**: Validates git changes against workflow rules. -- **Dataset Cache**: Caches the full PipelineResult (MasterDataset + ValidationSummary + warnings) to a JSON file. - **Config Resolver**: Resolves a raw `ArchitectProjectConfig` into a fully-resolved `ResolvedConfig` with all defaults applied, stubs... - **Project Config Types**: Unified project configuration for the Architect package. - **Project Config Schema**: Zod validation schema for `ArchitectProjectConfig`. - **Source Merger**: Computes effective sources for a specific generator by applying per-generator overrides to the base resolved sources. - **Define Config**: Identity function for type-safe project configuration. - **File Cache**: Simple Map-based cache for file contents during a single generation run. -- **Process State Types**: :MasterDataset Type definitions for the ProcessStateAPI query interface. +- **Process State Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. - **Pattern Summarizer Impl**: Projects the full ExtractedPattern (~3.5KB per pattern) down to a PatternSummary (~100 bytes) for list queries. -- **Stub Resolver Impl**: Identifies design session stubs in the MasterDataset and resolves them against the filesystem to determine... -- **Process State API**: TypeScript interface for querying project state. +- **Stub Resolver Impl**: Identifies design session stubs in the PatternGraph and resolves them against the filesystem to determine... - **Pattern Helpers**: Common helper functions used by context-assembler, arch-queries, and other API modules that need pattern name... +- **Pattern Graph API**: TypeScript interface for querying project state. - **API Module**: Central export for the Process State API, providing a TypeScript interface for querying project state. - **Fuzzy Matcher Impl**: Provides fuzzy matching for pattern names with tiered scoring: exact (1.0) > prefix (0.9) > substring (0.7) >... -- **Coverage Analyzer Impl**: Reports annotation completeness by comparing scannable files (from glob) against annotated patterns in MasterDataset. +- **Coverage Analyzer Impl**: Reports annotation completeness by comparing scannable files (from glob) against annotated patterns in PatternGraph. - **Context Formatter Impl**: First plain-text formatter in the codebase. -- **Context Assembler Impl**: Pure function composition over MasterDataset. -- **Arch Queries Impl**: Pure functions over MasterDataset for deep architecture exploration. +- **Context Assembler Impl**: Pure function composition over PatternGraph. +- **Arch Queries Impl**: Pure functions over PatternGraph for deep architecture exploration. +- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. +- **Process API CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. +- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. +- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. +- **Lint Process CLI**: Validates git changes against workflow rules. +- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **FSM Validator**: :PDR005MvpWorkflow Pure validation functions following the Decider pattern: - No I/O, no side effects - Return... - **FSM Transitions**: :PDR005MvpWorkflow Defines valid transitions between FSM states per PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **FSM States**: :PDR005MvpWorkflow Defines the 4-state FSM from PDR-005 MVP Workflow: - roadmap: Planned work (fully editable) -... - **FSM Module**: :PDR005MvpWorkflow Central export for the 4-state FSM defined in PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **Reference Document Codec**: :Generation A single codec factory that creates reference document codecs from configuration objects. -- **Design Review Codec**: :Generation Transforms MasterDataset into a RenderableDocument containing design review artifacts: sequence diagrams,... +- **Design Review Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing design review artifacts: sequence diagrams,... - **Composite Codec**: :Generation Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. - **Codec Registry Barrel**: Collects all codecMeta exports into a single array. -- **Claude Module Codec**: :Generation Transforms MasterDataset into RenderableDocuments for CLAUDE.md module generation. +- **Claude Module Codec**: :Generation Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. - **Process Guard Types**: :FSMValidator Defines types for the process guard linter including: - Process state derived from file annotations -... - **Process Guard Module**: :FSMValidator,DeriveProcessState,DetectChanges,ProcessGuardDecider Enforces workflow rules by validating changes... - **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... @@ -66,34 +66,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Relationship Resolver**: Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) and detects dangling references in... - **Reference Generator Registration**: Registers all reference document generators. - **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. -- **MCP Server Integration**: Claude Code accesses ProcessStateAPI through subprocess calls to the process-api CLI. +- **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the process-api CLI. - **Design Review Generation**: Design reviews require manual creation of sequence and component diagrams that duplicate information already captured... - **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. - **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. -- **Tag Registry Builder Testing**: The tag registry builder constructs a complete TagRegistry from TypeScript constants. -- **Normalized Status Testing**: The normalized status module maps any status input — raw FSM states (roadmap, active, completed, deferred),... -- **Deliverable Status Taxonomy Testing**: The deliverable status module defines the 6 canonical status values for deliverables in Gherkin Background tables:... - **Workflow Config Schemas Validation**: The workflow configuration module defines Zod schemas for validating delivery workflow definitions with statuses,... - **Tag Registry Schemas Validation**: The tag registry configuration module provides schema-validated taxonomy definitions for organizing patterns by... - **Codec Utils Validation**: The codec utilities provide factory functions for creating type-safe JSON parsing and serialization pipelines using... +- **Tag Registry Builder Testing**: The tag registry builder constructs a complete TagRegistry from TypeScript constants. +- **Normalized Status Testing**: The normalized status module maps any status input — raw FSM states (roadmap, active, completed, deferred),... +- **Deliverable Status Taxonomy Testing**: The deliverable status module defines the 6 canonical status values for deliverables in Gherkin Background tables:... - **Load Preamble Parser**: The parseMarkdownToBlocks function converts raw markdown content into a readonly SectionBlock[] array using a 5-state... - **Design Review Generation Tests**: Tests the full design review generation pipeline: sequence annotations are extracted from patterns with business... - **Design Review Generator Lifecycle Tests**: The design review generator cleans up stale markdown files when annotated patterns are renamed or removed from the... -- **Claude Metadata Parity Testing**: The extractor must preserve Claude routing metadata from TypeScript directives and keep the sync and async Gherkin... - **Architecture Doc Refactoring Testing**: Validates that ARCHITECTURE.md retains its full reference content and that generated documents in docs-live/ coexist... +- **Claude Metadata Parity Testing**: The extractor must preserve Claude routing metadata from TypeScript directives and keep the sync and async Gherkin... - **Process Api Cli Repl**: Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. - **Process Api Cli Metadata**: Response metadata includes validation summary and pipeline timing for diagnostics. - **Process Api Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. - **Process Api Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. -- **Process Api Cli Cache**: MasterDataset caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. +- **Process Api Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. - **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... - **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... -- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... -- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... - **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... - **Pattern Helpers Tests** - **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. - **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. +- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... +- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... - **Arch Queries Test** - **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. - **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. @@ -118,34 +118,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Public API**: Main entry point for the @libar-dev/architect package. -- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to ProcessStateAPI methods and CLI subcommands. +- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. - **MCPServer — Entry Point and Lifecycle Manager**: Main entry point for the Architect MCP server. -- **PipelineSessionManager — In-Memory MasterDataset Lifecycle**: Manages the persistent MasterDataset that all MCP tool calls read from. +- **PipelineSessionManager — In-Memory PatternGraph Lifecycle**: Manages the persistent PatternGraph that all MCP tool calls read from. - **McpFileWatcher — Debounced Source File Watcher**: Watches TypeScript and Gherkin source files for changes, triggering debounced pipeline rebuilds. - **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. -- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (MasterDataset -> RenderableDocument). +- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). - **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... - **Workflow Config Schema**: Zod schemas for validating workflow configuration files that define status models, phase definitions, and artifact... - **Tag Registry Configuration**: Defines the structure and validation for tag taxonomy configuration. +- **Pattern Graph**: Defines the schema for a pre-computed dataset that holds all extracted patterns along with derived views (by status,... - **Output Schemas**: Zod schemas for JSON output formats used by CLI tools. -- **Master Dataset**: Defines the schema for a pre-computed dataset that holds all extracted patterns along with derived views (by status,... - **Extracted Shape Schema**: Zod schema for TypeScript type definitions extracted from source files via the @architect-extract-shapes tag. - **Extracted Pattern Schema**: Zod schema for validating complete extracted patterns with code, metadata, relationships, and source information. - **Dual Source Schemas**: Zod schemas for dual-source extraction types. - **Doc Directive Schema**: Zod schemas for validating parsed @architect-\* directives from JSDoc comments. - **Codec Utils**: Provides factory functions for creating type-safe JSON parsing and serialization pipelines using Zod schemas. -- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... -- **Utils Module**: Common helper functions used across the Architect package. -- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. -- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. -- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. -- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. -- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... -- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. - **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... - **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. - **Anti Pattern Detector**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... +- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... +- **Utils Module**: Common helper functions used across the Architect package. +- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. +- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. - **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). - **Risk Levels**: Three-tier risk classification for roadmap planning. - **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. @@ -154,8 +150,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... - **Format Types**: Defines how tag values are parsed and validated. - **Category Definitions**: Categories are used to classify patterns and organize documentation. -- **Result Monad Types**: Explicit error handling via discriminated union. -- **Error Factory Types**: Structured, discriminated error types with factory functions. +- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. +- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. +- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... +- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. @@ -177,12 +175,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... - **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. - **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. -- **CLI Version Helper**: Reads package version from package.json for CLI --version flag. -- **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. -- **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. -- **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. -- **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. -- **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. - **Workflow Loader**: Provides the default 6-phase workflow as an inline constant and loads custom workflow overrides from JSON files via... - **Configuration Types**: Type definitions for the Architect configuration system. - **Regex Builders**: Type-safe regex factory functions for tag detection and normalization. @@ -190,45 +182,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architect Factory**: Main factory function for creating configured Architect instances. - **Configuration Defaults**: Centralized default constants for the Architect package. - **Config Loader**: Discovers and loads `architect.config.ts` or `architect.config.js` files for hierarchical configuration. -- **Scope Validator Impl**: Pure function composition over ProcessStateAPI and MasterDataset. +- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. - **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. -- **Handoff Generator Impl**: Pure function that assembles a handoff document from ProcessStateAPI and MasterDataset. -- **Validation Rules Codec**: :Generation Transforms MasterDataset into a RenderableDocument for Process Guard validation rules reference. +- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. +- **Result Monad Types**: Explicit error handling via discriminated union. +- **Error Factory Types**: Structured, discriminated error types with factory functions. +- **CLI Version Helper**: Reads package version from package.json for CLI --version flag. +- **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. +- **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. +- **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. +- **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. +- **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. +- **Validation Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. - **Timeline Codec**: :Generation Purpose: Development roadmap organized by phase with progress tracking. -- **Taxonomy Codec**: :Generation Transforms MasterDataset into a RenderableDocument for taxonomy reference output. +- **Taxonomy Codec**: :Generation Transforms PatternGraph into a RenderableDocument for taxonomy reference output. - **Shared Codec Schema**: Provides a simplified RenderableDocument output schema for use with Zod 4 codecs. - **Session Codec**: :Generation Purpose: Current session context for AI agents and developers. -- **Requirements Codec**: :Generation Transforms MasterDataset into RenderableDocument for PRD/requirements output. +- **Requirements Codec**: :Generation Transforms PatternGraph into RenderableDocument for PRD/requirements output. - **Reporting Codecs**: :Generation Purpose: Keep a Changelog format changelog grouped by release version. - **Reference Codec**: All type/interface definitions and shared constants used across the ReferenceDocumentCodec module family. - **Reference Codec**: All diagram builder functions: collectScopePatterns, collectNeighborPatterns, prepareDiagramContext, and the five... - **Reference Codec**: Section builder functions that transform extracted data into SectionBlock arrays. - **Reference Codec**: Static data: PRODUCT_AREA_ARCH_CONTEXT_MAP and PRODUCT_AREA_META. -- **Pr Changes Codec**: :Generation Transforms MasterDataset into RenderableDocument for PR-scoped output. +- **Pr Changes Codec**: :Generation Transforms PatternGraph into RenderableDocument for PR-scoped output. - **Planning Codecs**: :Generation Purpose: Pre-planning questions and Definition of Done validation. -- **Patterns Codec**: :Generation Transforms MasterDataset into a RenderableDocument for pattern registry output. +- **Patterns Codec**: :Generation Transforms PatternGraph into a RenderableDocument for pattern registry output. - **Document Codecs**: Barrel export for all document codecs. -- **Index Codec**: :Generation Purpose: Navigation hub composing editorial preamble with MasterDataset statistics. +- **Index Codec**: :Generation Purpose: Navigation hub composing editorial preamble with PatternGraph statistics. - **Rich Content Helpers**: Shared helper functions for rendering Gherkin rich content in document codecs. - **Mermaid Diagram Utils**: Sanitization and formatting helpers shared across architecture.ts and reference.ts diagram builders. - **Decision Doc Codec**: Parses decision documents (ADR/PDR in .feature format) and extracts content for documentation generation. -- **Business Rules Codec**: :Generation Transforms MasterDataset into a RenderableDocument for business rules output. -- **Architecture Codec**: :Generation Transforms MasterDataset into a RenderableDocument containing architecture diagrams (Mermaid) generated... -- **Adr Document Codec**: :Generation Transforms MasterDataset into RenderableDocument for Architecture Decision Records. -- **Transform Dataset**: Transforms raw extracted patterns into a MasterDataset with all pre-computed views. +- **Business Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for business rules output. +- **Architecture Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing architecture diagrams (Mermaid) generated... +- **Adr Document Codec**: :Generation Transforms PatternGraph into RenderableDocument for Architecture Decision Records. +- **Transform Dataset**: Transforms raw extracted patterns into a PatternGraph with all pre-computed views. - **Merge Patterns**: Merges patterns from TypeScript and Gherkin sources with conflict detection. - **Pipeline Module**: Barrel export for the unified transformation pipeline components. - **Context Inference Impl**: Auto-infers bounded context from file paths using configurable rules. -- **Pipeline Factory**: Invariant: `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... +- **Pipeline Factory**: Invariant: `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... - **Process Api Reference Generator**: :Generation Generates `PROCESS-API-REFERENCE.md` from the declarative CLI schema. - **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. - **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. - **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. - **Codec Base Options**: :Add-createDecodeOnlyCodec-helper Shared types, interfaces, and utilities for all document codecs. - **ADR 006 Single Read Model Architecture**: The Architect package applies event sourcing to itself: git is the event store, annotated source files are... -- **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (MasterDataset) into markdown files. +- **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (PatternGraph) into markdown files. - **ADR 002 Gherkin Only Testing**: A package that generates documentation from `.feature` files had dual test approaches: 97 legacy `.test.ts` files... -- **Validator Read Model Consolidation**: `validate-patterns.ts` is the only feature consumer that bypasses the MasterDataset. +- **Validator Read Model Consolidation**: `validate-patterns.ts` is the only feature consumer that bypasses the PatternGraph. - **Universal Doc Generator Robustness**: This feature transforms the PoC document generator into a production-ready universal generator capable of operating... - **Step Lint Vitest Cucumber**: Hours are lost debugging vitest-cucumber-specific issues that only surface at test runtime. - **Step Lint Extended Rules**: The initial lint-steps CLI catches 8 vitest-cucumber traps, but 4 documented traps from... @@ -238,11 +238,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Reference Doc Showcase**: The Reference Generation Sample document exercises a small fraction of the reference codec's capabilities: 2... - **Readme Rationalization**: `README.md` is 504 lines and serves three different audiences in one document: (a) npm package consumers who need... - **Publishing Relocation**: `docs/PUBLISHING.md` (144 lines) is deployed to libar.dev as part of the `docs/` directory, but its content is... -- **Process State API Relationship Queries**: Problem: ProcessStateAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, `enables`) but lacks... -- **Process State API CLI**: The ProcessStateAPI provides 27 typed query methods for efficient state queries, but Claude Code sessions cannot use... - **Process API Layered Extraction**: `process-api.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. - **Process Api Hybrid Generation**: `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source... - **Procedural Guide Codec**: Two manual docs contain procedural content with no annotation source for generation: `docs/SESSION-GUIDES.md` (389... +- **Pattern Graph API Relationship Queries**: Problem: PatternGraphAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, `enables`) but lacks... +- **Pattern Graph API CLI**: The PatternGraphAPI provides 27 typed query methods for efficient state queries, but Claude Code sessions cannot use... - **Orchestrator Pipeline Factory Migration**: `orchestrator.ts` is the last feature consumer that wires the 8-step scan-extract-merge-transform pipeline inline... - **Gherkin Patterns Restructure**: `docs/GHERKIN-PATTERNS.md` is 515 lines and mixes two distinct concerns: (a) a writing guide for Gherkin authoring... - **Generated Doc Quality**: Four quality issues reduce the usefulness of generated docs for both Claude agents and human developers: (1)... @@ -255,7 +255,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Data API Stub Integration**: Design sessions produce code stubs in `architect/stubs/` with rich metadata: `@architect-target` (destination file... - **Data API Design Session Support**: Starting a design or implementation session requires manually compiling elaborate context prompts. - **Data API Platform Integration**: The process-api CLI requires subprocess invocation for every query, adding shell overhead and preventing stateful... -- **Data API Output Shaping**: The ProcessStateAPI CLI returns raw `ExtractedPattern` objects via `JSON.stringify`. +- **Data API Output Shaping**: The PatternGraphAPI CLI returns raw `ExtractedPattern` objects via `JSON.stringify`. - **Data API Context Assembly**: Starting a Claude Code design or implementation session requires assembling 30-100KB of curated, multi-source context... - **Data API CLI Ergonomics**: The process-api CLI runs the full pipeline (scan, extract, transform) on every invocation, taking 2-5 seconds. - **Data API Architecture Queries**: The current `arch` subcommand provides basic queries (roles, context, layer, graph) but lacks deeper analysis needed... @@ -268,6 +268,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architecture Diagram Core**: Problem: Architecture documentation requires manually maintaining mermaid diagrams that duplicate information already... - **Architecture Diagram Advanced**: Problem: Core diagram generation (see ArchitectureDiagramCore) produces component-level diagrams from `arch-*` tags. - **String Utils**: String utilities provide consistent text transformations across the codebase. +- **Status Transition Detection Testing**: Tests for the detectStatusTransitions function that parses git diff output. +- **Process Guard Testing**: Pure validation functions for enforcing delivery process rules per PDR-005. +- **FSM Validator Testing**: Pure validation functions for the 4-state FSM defined in PDR-005. +- **DoD Validator Testing**: Validates that completed phases meet Definition of Done criteria: 1. +- **Detect Changes Testing**: Tests for the detectDeliverableChanges function that parses git diff output. +- **Config Schema Validation**: Configuration schemas validate scanner and generator inputs with security constraints to prevent path traversal... +- **Anti Pattern Detector Testing**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... - **Result Monad**: The Result type provides explicit error handling via a discriminated union. - **Error Factories**: Error factories create structured, discriminated error types with consistent message formatting. - **Gherkin Ast Parser**: The Gherkin AST parser extracts feature metadata, scenarios, and steps from .feature files for timeline generation... @@ -276,40 +283,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Ast Parser Relationships Edges**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Metadata**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Exports**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. -- **Status Transition Detection Testing**: Tests for the detectStatusTransitions function that parses git diff output. -- **Process Guard Testing**: Pure validation functions for enforcing delivery process rules per PDR-005. -- **FSM Validator Testing**: Pure validation functions for the 4-state FSM defined in PDR-005. -- **DoD Validator Testing**: Validates that completed phases meet Definition of Done criteria: 1. -- **Detect Changes Testing**: Tests for the detectDeliverableChanges function that parses git diff output. -- **Config Schema Validation**: Configuration schemas validate scanner and generator inputs with security constraints to prevent path traversal... -- **Anti Pattern Detector Testing**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... - **Rule Keyword Po C**: This feature tests whether vitest-cucumber supports the Rule keyword for organizing scenarios under business rules. -- **Table Extraction**: Tables in business rule descriptions should appear exactly once in output. -- **Generator Registry Testing**: Tests the GeneratorRegistry registration, lookup, and listing capabilities. -- **Prd Implementation Section Testing**: Tests the Implementations section rendering in pattern documents. -- **Pr Changes Options**: Tests the PrChangesCodec filtering capabilities for generating PR-scoped documentation. -- **Documentation Orchestrator**: Tests the orchestrator's pattern merging, conflict detection, and generator coordination capabilities. -- **Codec Based Generator Testing**: Tests the CodecBasedGenerator which adapts the RenderableDocument Model (RDM) codec system to the DocumentGenerator... -- **Business Rules Document Codec**: Tests the BusinessRulesCodec transformation from MasterDataset to RenderableDocument. -- **Shape Extraction Types Testing**: Validates the shape extraction system that extracts TypeScript type definitions (interfaces, type aliases, enums,... -- **Shape Extraction Rendering Testing**: Validates the shape extraction system that extracts TypeScript type definitions (interfaces, type aliases, enums,... -- **Extraction Pipeline Enhancements Testing**: Validates extraction pipeline capabilities for ReferenceDocShowcase: function signature surfacing, full... -- **Dual Source Extractor Testing**: Extracts and combines pattern metadata from both TypeScript code stubs (@architect-) and Gherkin feature files... -- **Declaration Level Shape Tagging Testing**: Tests the discoverTaggedShapes function that scans TypeScript source code for declarations annotated with the... - **Lint Rule Individual Testing**: Individual lint rules that check parsed directives for completeness. - **Lint Rule Advanced Testing**: Complex lint rule logic and collection-level behavior. - **Lint Engine Testing**: The lint engine orchestrates rule execution, aggregates violations, and formats output for human and machine... - **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... -- **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms MasterDataset into a RenderableDocument for Process Guard... -- **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms MasterDataset into a RenderableDocument for tag taxonomy reference... +- **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... +- **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... - **Source Mapping Validator Testing**: Context: Source mappings reference files that may not exist, use invalid extraction methods, or have incompatible... - **Source Mapper Testing**: The Source Mapper aggregates content from multiple source files based on source mapping tables parsed from decision... - **Robustness Integration**: Context: Document generation pipeline needs validation, deduplication, and warning collection to work together... - **Poc Integration**: End-to-end integration tests that exercise the full documentation generation pipeline using the actual POC decision... -- **Index Codec Testing**: Validates the Index Codec that transforms MasterDataset into a RenderableDocument for the main documentation... +- **Index Codec Testing**: Validates the Index Codec that transforms PatternGraph into a RenderableDocument for the main documentation... - **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . - **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... - **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. +- **Table Extraction**: Tables in business rule descriptions should appear exactly once in output. +- **Generator Registry Testing**: Tests the GeneratorRegistry registration, lookup, and listing capabilities. +- **Prd Implementation Section Testing**: Tests the Implementations section rendering in pattern documents. +- **Pr Changes Options**: Tests the PrChangesCodec filtering capabilities for generating PR-scoped documentation. +- **Documentation Orchestrator**: Tests the orchestrator's pattern merging, conflict detection, and generator coordination capabilities. +- **Codec Based Generator Testing**: Tests the CodecBasedGenerator which adapts the RenderableDocument Model (RDM) codec system to the DocumentGenerator... +- **Business Rules Document Codec**: Tests the BusinessRulesCodec transformation from PatternGraph to RenderableDocument. +- **Shape Extraction Types Testing**: Validates the shape extraction system that extracts TypeScript type definitions (interfaces, type aliases, enums,... +- **Shape Extraction Rendering Testing**: Validates the shape extraction system that extracts TypeScript type definitions (interfaces, type aliases, enums,... +- **Extraction Pipeline Enhancements Testing**: Validates extraction pipeline capabilities for ReferenceDocShowcase: function signature surfacing, full... +- **Dual Source Extractor Testing**: Extracts and combines pattern metadata from both TypeScript code stubs (@architect-) and Gherkin feature files... +- **Declaration Level Shape Tagging Testing**: Tests the discoverTaggedShapes function that scans TypeScript source code for declarations annotated with the... - **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... - **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... - **Preset System**: Presets provide pre-configured taxonomies for different project types. @@ -324,8 +324,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Process Cli**: Command-line interface for validating changes against delivery process rules. - **Lint Patterns Cli**: Command-line interface for validating pattern annotation quality. - **Generate Docs Cli**: Command-line interface for generating documentation from annotated TypeScript. -- **Process State API Testing**: Programmatic interface for querying delivery process state. -- **Transform Dataset Testing**: The transformToMasterDataset function transforms raw extracted patterns into a MasterDataset with all pre-computed... +- **Pattern Graph API Testing**: Programmatic interface for querying delivery process state. +- **Transform Dataset Testing**: The transformToPatternGraph function transforms raw extracted patterns into a PatternGraph with all pre-computed... - **Session Handoffs**: The delivery process supports mid-phase handoffs between sessions and coordination across multiple developers through... - **Session File Lifecycle**: Orphaned session files are automatically cleaned up during generation, maintaining a clean docs-living/sessions/... - **Scanner Core**: The scanPatterns function orchestrates file discovery, directive detection, and AST parsing to extract documentation... @@ -335,7 +335,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Remaining Work Summary Accuracy**: Summary totals in REMAINING-WORK.md must match the sum of phase table rows. - **Remaining Work Enhancement**: Enhanced REMAINING-WORK.md generation with priority-based sorting, quarter grouping, and progressive disclosure for... - **Pr Changes Generation**: The delivery process generates PR-CHANGES.md from active or completed phases, formatted for PR descriptions, code... -- **Patterns Codec Testing**: The PatternsDocumentCodec transforms MasterDataset into a RenderableDocument for generating PATTERNS.md and category... +- **Patterns Codec Testing**: The PatternsDocumentCodec transforms PatternGraph into a RenderableDocument for generating PATTERNS.md and category... - **Pattern Tag Extraction**: The extractPatternTags function parses Gherkin feature tags into structured metadata objects for pattern processing. - **Layer Inference Testing**: The layer inference module classifies feature files into testing layers (timeline, domain, integration, e2e,... - **Kebab Case Slugs**: As a documentation generator I need to generate readable, URL-safe slugs from pattern names So that generated file... @@ -353,25 +353,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Linter Validation Testing**: Tests for lint rules that validate relationship integrity, detect conflicts, and ensure bidirectional traceability... - **Implements Tag Processing**: Tests for the @architect-implements tag which links implementation files to their corresponding roadmap pattern... - **Extends Tag Testing**: Tests for the @architect-extends tag which establishes generalization relationships between patterns (pattern... -- **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform MasterDataset into... +- **Process Api Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... +- **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform PatternGraph into... - **Shape Selector Testing**: Tests the filterShapesBySelectors function that provides fine-grained shape selection via structural discriminated... - **Shape Matcher Testing**: Matches file paths against glob patterns for TypeScript shape extraction. -- **Session Codec Testing**: The session codecs (SessionContextCodec, RemainingWorkCodec) transform MasterDataset into RenderableDocuments for AI... -- **Requirements Adr Codec Testing**: The RequirementsDocumentCodec and AdrDocumentCodec transform MasterDataset into RenderableDocuments for PRD-style and... -- **Reporting Codec Testing**: The reporting codecs (ChangelogCodec, TraceabilityCodec, OverviewCodec) transform MasterDataset into... +- **Session Codec Testing**: The session codecs (SessionContextCodec, RemainingWorkCodec) transform PatternGraph into RenderableDocuments for AI... +- **Requirements Adr Codec Testing**: The RequirementsDocumentCodec and AdrDocumentCodec transform PatternGraph into RenderableDocuments for PRD-style and... +- **Reporting Codec Testing**: The reporting codecs (ChangelogCodec, TraceabilityCodec, OverviewCodec) transform PatternGraph into... - **Reference Generator Testing**: Registers reference document generators from project config. - **Reference Codec Diagram Testing**: Scoped diagram generation from diagramScopes config, including archContext, include, archLayer, patterns filters, and... - **Reference Codec Diagram Type Testing**: Diagram type controls Mermaid output format including flowchart, sequenceDiagram, stateDiagram-v2, C4Context, and... - **Reference Codec Detail Rendering**: Standard detail level behavior, deep behavior rendering with structured annotations, shape JSDoc prose,... - **Reference Codec Core Testing**: Parameterized codec factory that creates reference document codecs from configuration objects. -- **Pr Changes Codec Rendering Testing**: The PrChangesCodec transforms MasterDataset into RenderableDocument for PR-scoped documentation. -- **Pr Changes Codec Options Testing**: The PrChangesCodec transforms MasterDataset into RenderableDocument for PR-scoped documentation. -- **Planning Codec Testing**: The planning codecs (PlanningChecklistCodec, SessionPlanCodec, SessionFindingsCodec) transform MasterDataset into... +- **Pr Changes Codec Rendering Testing**: The PrChangesCodec transforms PatternGraph into RenderableDocument for PR-scoped documentation. +- **Pr Changes Codec Options Testing**: The PrChangesCodec transforms PatternGraph into RenderableDocument for PR-scoped documentation. +- **Planning Codec Testing**: The planning codecs (PlanningChecklistCodec, SessionPlanCodec, SessionFindingsCodec) transform PatternGraph into... - **Generated Doc Quality Tests**: Tests for the four quality fixes in GeneratedDocQuality (Phase 38): duplicate table removal, Generation compact... - **Dedent Helper**: The dedent helper function normalizes indentation in code blocks extracted from DocStrings. -- **Convention Extractor Testing**: Extracts convention content from MasterDataset decision records tagged with @architect-convention. +- **Convention Extractor Testing**: Extracts convention content from PatternGraph decision records tagged with @architect-convention. - **Composite Codec Testing**: Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. -- **Process Api Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Layered Diagram Generation**: As a documentation generator I want to generate layered architecture diagrams from metadata So that system... - **Arch Generator Registration**: As a CLI user I want an architecture generator registered in the generator registry So that I can run pnpm... - **Component Diagram Generation**: As a documentation generator I want to generate component diagrams from architecture metadata So that system... diff --git a/docs-live/INDEX.md b/docs-live/INDEX.md index 2b5db575..5024a073 100644 --- a/docs-live/INDEX.md +++ b/docs-live/INDEX.md @@ -33,7 +33,7 @@ | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | | Learn annotation mechanics | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | | See codec patterns and options | [Architecture Codecs](reference/ARCHITECTURE-CODECS.md) | -| Understand MasterDataset types | [Architecture Types](reference/ARCHITECTURE-TYPES.md) | +| Understand PatternGraph types | [Architecture Types](reference/ARCHITECTURE-TYPES.md) | --- @@ -77,7 +77,7 @@ | Process API Recipes | AI/Devs | CLI workflow recipes and session guides | | Process Guard Reference | Team Leads | Pre-commit hooks, error codes, programmatic API | | Architecture Codecs | Developers | All codecs with factory patterns and options | -| Architecture Types | Developers | MasterDataset interface and type shapes | +| Architecture Types | Developers | PatternGraph interface and type shapes | --- @@ -85,11 +85,11 @@ **Delivery Process** -- A code-first documentation and workflow toolkit. Extracts patterns from annotated TypeScript and Gherkin sources, generates markdown documentation, and validates delivery workflow via pre-commit hooks. -**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the MasterDataset. +**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the PatternGraph. -**MasterDataset** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. +**PatternGraph** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. -**Codec** -- A Zod-based transformer that decodes MasterDataset into a RenderableDocument. Each codec produces a specific document type. Codecs are pure functions with no I/O. +**Codec** -- A Zod-based transformer that decodes PatternGraph into a RenderableDocument. Each codec produces a specific document type. Codecs are pure functions with no I/O. **Dual-Source Architecture** -- Feature files own planning metadata (status, phase, dependencies). TypeScript files own implementation metadata (uses, used-by, category). This split prevents ownership conflicts. @@ -126,7 +126,7 @@ | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | CLI workflow recipes and session guides | AI/Devs | | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | Pre-commit hooks, error codes, programmatic API | Team Leads | | [Architecture Codecs](reference/ARCHITECTURE-CODECS.md) | All codecs with factory patterns and options | Developers | -| [Architecture Types](reference/ARCHITECTURE-TYPES.md) | MasterDataset interface and type shapes | Developers | +| [Architecture Types](reference/ARCHITECTURE-TYPES.md) | PatternGraph interface and type shapes | Developers | | [Configuration Guide](reference/CONFIGURATION-GUIDE.md) | Presets, config files, sources, output, and monorepo setup | Users | | [Validation Tools Guide](reference/VALIDATION-TOOLS-GUIDE.md) | lint-patterns, lint-steps, lint-process, validate-patterns reference | CI/CD | | [Gherkin Authoring Guide](reference/GHERKIN-AUTHORING-GUIDE.md) | Roadmap specs, Rule blocks, DataTables, tag conventions | Developers | diff --git a/docs-live/PRODUCT-AREAS.md b/docs-live/PRODUCT-AREAS.md index 4011221f..38184a89 100644 --- a/docs-live/PRODUCT-AREAS.md +++ b/docs-live/PRODUCT-AREAS.md @@ -29,7 +29,7 @@ Configuration is the entry boundary — it transforms a user-authored `architect > **How does code become docs?** -The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. +The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. **96 patterns** — 82 completed, 6 active, 8 planned @@ -53,7 +53,7 @@ The Data API provides direct terminal access to project state. It replaces readi **40 patterns** — 23 completed, 15 active, 2 planned -**Key patterns:** DataAPIContextAssembly, ProcessStateAPICLI, DataAPIDesignSessionSupport, DataAPIRelationshipGraph, DataAPIOutputShaping +**Key patterns:** DataAPIContextAssembly, PatternGraphAPICLI, DataAPIDesignSessionSupport, DataAPIRelationshipGraph, DataAPIOutputShaping ## [CoreTypes](product-areas/CORE-TYPES.md) @@ -120,9 +120,9 @@ C4Context System(DataAPIContextAssembly, "DataAPIContextAssembly") System(CrossCuttingDocumentInclusion, "CrossCuttingDocumentInclusion") System(CodecDrivenReferenceGeneration, "CodecDrivenReferenceGeneration") + System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") - System(StringUtils, "StringUtils") System(ExtractionPipelineEnhancementsTesting, "ExtractionPipelineEnhancementsTesting") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") @@ -199,9 +199,9 @@ graph LR DataAPIContextAssembly["DataAPIContextAssembly"] CrossCuttingDocumentInclusion["CrossCuttingDocumentInclusion"] CodecDrivenReferenceGeneration["CodecDrivenReferenceGeneration"] + StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] - StringUtils["StringUtils"] ExtractionPipelineEnhancementsTesting["ExtractionPipelineEnhancementsTesting"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] diff --git a/docs-live/_claude-md/annotation/annotation-overview.md b/docs-live/_claude-md/annotation/annotation-overview.md index 737875e3..667930e6 100644 --- a/docs-live/_claude-md/annotation/annotation-overview.md +++ b/docs-live/_claude-md/annotation/annotation-overview.md @@ -19,8 +19,8 @@ | MetadataTagDefinitionForRegistry | interface | | CategoryDefinition | interface | | CategoryTag | type | -| buildRegistry | function | | isShapeOnlyDirective | function | +| buildRegistry | function | | METADATA_TAGS_BY_GROUP | const | | CATEGORIES | const | | CATEGORY_TAGS | const | diff --git a/docs-live/_claude-md/annotation/annotation-reference.md b/docs-live/_claude-md/annotation/annotation-reference.md index 3a26810b..42a8de9a 100644 --- a/docs-live/_claude-md/annotation/annotation-reference.md +++ b/docs-live/_claude-md/annotation/annotation-reference.md @@ -57,7 +57,7 @@ List specific declaration names in the file-level JSDoc: ```typescript /** * @architect - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema */ ``` @@ -94,7 +94,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i | Wrong (type alias) | Correct (schema constant) | | ---------------------------------------- | ----------------------------------------- | -| `@extract-shapes MasterDataset` | `@extract-shapes MasterDatasetSchema` | +| `@extract-shapes PatternGraph` | `@extract-shapes PatternGraphSchema` | | Shows: `z.infer` (unhelpful) | Shows: `z.object({...})` (full structure) | #### Annotation Patterns by File Type @@ -104,9 +104,9 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i ```typescript /** * @architect - * @architect-pattern MasterDataset + * @architect-pattern PatternGraph * @architect-status completed - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, PhaseGroupSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, PhaseGroupSchema */ ``` @@ -130,7 +130,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i * @architect-status completed * @architect-arch-context generator * @architect-arch-layer application - * @architect-extract-shapes transformToMasterDataset, RuntimeMasterDataset + * @architect-extract-shapes transformToPatternGraph, RuntimePatternGraph */ ``` diff --git a/docs-live/_claude-md/architecture/architecture-types.md b/docs-live/_claude-md/architecture/architecture-types.md index a360563b..65a69394 100644 --- a/docs-live/_claude-md/architecture/architecture-types.md +++ b/docs-live/_claude-md/architecture/architecture-types.md @@ -4,13 +4,13 @@ | Type | Kind | | ----------------------- | --------- | -| MasterDatasetSchema | const | +| PatternGraphSchema | const | | StatusGroupsSchema | const | | StatusCountsSchema | const | | PhaseGroupSchema | const | | SourceViewsSchema | const | | RelationshipEntrySchema | const | -| RuntimeMasterDataset | interface | +| RuntimePatternGraph | interface | | RawDataset | interface | | PipelineOptions | interface | | PipelineResult | interface | @@ -19,13 +19,13 @@ **Invariant:** The orchestrator is the integration boundary for full docs generation: it delegates dataset construction to the shared pipeline, then executes codecs and writes files. -#### Steps 1-8 via buildMasterDataset() +#### Steps 1-8 via buildPatternGraph() #### Steps 9-10: Codec Execution and File Writing #### Shared Pipeline Factory Responsibilities -**Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` without process-level side effects. +**Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` without process-level side effects. #### 8-Step Dataset Build Flow diff --git a/docs-live/_claude-md/architecture/reference-sample.md b/docs-live/_claude-md/architecture/reference-sample.md index 15d28726..79f898de 100644 --- a/docs-live/_claude-md/architecture/reference-sample.md +++ b/docs-live/_claude-md/architecture/reference-sample.md @@ -121,7 +121,7 @@ | Rule | Description | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| Codecs implement a decode-only contract | **Invariant:** Every codec is a pure function that accepts a MasterDataset
and returns a RenderableDocument.... | +| Codecs implement a decode-only contract | **Invariant:** Every codec is a pure function that accepts a PatternGraph
and returns a RenderableDocument.... | | RenderableDocument is a typed intermediate representation | **Invariant:** RenderableDocument contains a title, an ordered array of
SectionBlock elements, and an optional... | | CompositeCodec assembles documents from child codecs | **Invariant:** CompositeCodec accepts an array of child codecs and
produces a single RenderableDocument by... | | ADR content comes from both Feature description and Rule prefixes | **Invariant:** ADR structured content (Context, Decision, Consequences)
can appear in two locations within a... | diff --git a/docs-live/_claude-md/core-types/core-types-overview.md b/docs-live/_claude-md/core-types/core-types-overview.md index 8c7bbafe..9eeab236 100644 --- a/docs-live/_claude-md/core-types/core-types-overview.md +++ b/docs-live/_claude-md/core-types/core-types-overview.md @@ -9,7 +9,7 @@ - Branded nominal types: `Branded` creates compile-time distinct types from structural TypeScript. Prevents mixing `PatternId` with `CategoryName` even though both are `string` at runtime - String transformation consistency: `slugify` produces URL-safe identifiers, `camelCaseToTitleCase` preserves acronyms (e.g., "APIEndpoint" becomes "API Endpoint"), `toKebabCase` handles consecutive uppercase correctly -**Components:** Other (TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, StringUtils, FileCacheTesting, KebabCaseSlugs, ErrorHandlingUnification) +**Components:** Other (StringUtils, FileCacheTesting, TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, KebabCaseSlugs, ErrorHandlingUnification) #### API Types diff --git a/docs-live/_claude-md/data-api/data-api-overview.md b/docs-live/_claude-md/data-api/data-api-overview.md index f62eb826..1de1683d 100644 --- a/docs-live/_claude-md/data-api/data-api-overview.md +++ b/docs-live/_claude-md/data-api/data-api-overview.md @@ -18,7 +18,7 @@ #### Shared Pipeline Factory Responsibilities -**Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` without process-level side effects. +**Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` without process-level side effects. #### 8-Step Dataset Build Flow @@ -30,7 +30,7 @@ | ----------------------- | --------- | | PipelineOptions | interface | | PipelineResult | interface | -| MasterDatasetSchema | const | +| PatternGraphSchema | const | | StatusGroupsSchema | const | | StatusCountsSchema | const | | PhaseGroupSchema | const | diff --git a/docs-live/_claude-md/generation/generation-overview.md b/docs-live/_claude-md/generation/generation-overview.md index f5c28fe3..63937687 100644 --- a/docs-live/_claude-md/generation/generation-overview.md +++ b/docs-live/_claude-md/generation/generation-overview.md @@ -1,11 +1,11 @@ ### Generation Overview -**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. +**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. #### Key Invariants - Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output -- Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship +- Single read model (ADR-006): All codecs consume PatternGraph. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship - Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/` - Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors - RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer @@ -15,16 +15,16 @@ #### API Types -| Type | Kind | -| ------------------------ | --------- | -| RuntimeMasterDataset | interface | -| RawDataset | interface | -| RenderableDocument | type | -| SectionBlock | type | -| HeadingBlock | type | -| TableBlock | type | -| ListBlock | type | -| CodeBlock | type | -| MermaidBlock | type | -| CollapsibleBlock | type | -| transformToMasterDataset | function | +| Type | Kind | +| ----------------------- | --------- | +| RuntimePatternGraph | interface | +| RawDataset | interface | +| RenderableDocument | type | +| SectionBlock | type | +| HeadingBlock | type | +| TableBlock | type | +| ListBlock | type | +| CodeBlock | type | +| MermaidBlock | type | +| CollapsibleBlock | type | +| transformToPatternGraph | function | diff --git a/docs-live/business-rules/data-api.md b/docs-live/business-rules/data-api.md index 352add63..9ebb5e45 100644 --- a/docs-live/business-rules/data-api.md +++ b/docs-live/business-rules/data-api.md @@ -664,6 +664,88 @@ _Validates the output pipeline transforms: summarization, modifiers,_ _output-pipeline.feature_ +### Pattern Graph API + +_- Markdown generation is not ideal for programmatic access_ + +--- + +#### Status queries return correct patterns + +> **Invariant:** Status queries must correctly filter by both normalized status (planned = roadmap + deferred) and FSM status (exact match). +> +> **Rationale:** The two-domain status convention requires separate query methods — mixing them produces incorrect filtered results. + +**Verified by:** + +- Get patterns by normalized status +- Get patterns by FSM status +- Get current work returns active patterns +- Get roadmap items returns roadmap and deferred +- Get status counts +- Get completion percentage + +--- + +#### Phase queries return correct phase data + +> **Invariant:** Phase queries must return only patterns in the requested phase, with accurate progress counts and completion percentage. +> +> **Rationale:** Phase-level queries power the roadmap and session planning views — incorrect counts cascade into wrong progress percentages. + +**Verified by:** + +- Get patterns by phase +- Get phase progress +- Get nonexistent phase returns undefined +- Get active phases + +--- + +#### FSM queries expose transition validation + +> **Invariant:** FSM queries must validate transitions against the PDR-005 state machine and expose protection levels per status. +> +> **Rationale:** Programmatic FSM access enables tooling to enforce delivery process rules without reimplementing the state machine. + +**Verified by:** + +- Check valid transition +- Check invalid transition +- Get valid transitions from status +- Get protection info + +--- + +#### Pattern queries find and retrieve pattern data + +> **Invariant:** Pattern lookup must be case-insensitive by name, and category queries must return only patterns with the requested category. +> +> **Rationale:** Case-insensitive search reduces friction in CLI and AI agent usage where exact casing is often unknown. + +**Verified by:** + +- Find pattern by name (case insensitive) +- Find nonexistent pattern returns undefined +- Get patterns by category +- Get all categories with counts + +--- + +#### Timeline queries group patterns by time + +> **Invariant:** Quarter queries must correctly filter by quarter string, and recently completed must be sorted by date descending with limit. +> +> **Rationale:** Timeline grouping enables quarterly reporting and session context — recent completions show delivery momentum. + +**Verified by:** + +- Get patterns by quarter +- Get all quarters +- Get recently completed sorted by date + +_pattern-graph-api.feature_ + ### Pattern Summarize Tests _Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to_ @@ -699,13 +781,13 @@ _summarize.feature_ ### Process Api Cli Cache -_MasterDataset caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass._ +_PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass._ --- -#### MasterDataset is cached between invocations +#### PatternGraph is cached between invocations -> **Invariant:** When source files have not changed between CLI invocations, the second invocation must use the cached MasterDataset and report cache.hit as true alongside pipeline timing metadata. +> **Invariant:** 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. > > **Rationale:** 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. @@ -753,7 +835,7 @@ _Core CLI infrastructure: help, version, input validation, status, query, patter #### CLI status subcommand shows delivery state -> **Invariant:** The status subcommand must return structured JSON containing delivery progress derived from the MasterDataset. +> **Invariant:** The status subcommand must return structured JSON containing delivery progress derived from the PatternGraph. > > **Rationale:** Consumers depend on machine-readable status output for scripting and CI integration; unstructured output breaks downstream automation. @@ -792,7 +874,7 @@ _Core CLI infrastructure: help, version, input validation, status, query, patter #### CLI arch subcommand queries architecture -> **Invariant:** The arch subcommand must expose role, bounded context, and layer queries over the MasterDataset's architecture metadata. +> **Invariant:** The arch subcommand must expose role, bounded context, and layer queries over the PatternGraph's architecture metadata. > > **Rationale:** Architecture queries replace manual exploration of annotated sources; missing or incorrect results lead to wrong structural assumptions during design sessions. @@ -1102,88 +1184,6 @@ _Verifies that the declarative CLI schema drives reference table generation_ _process-api-reference.feature_ -### Process State API - -_- Markdown generation is not ideal for programmatic access_ - ---- - -#### Status queries return correct patterns - -> **Invariant:** Status queries must correctly filter by both normalized status (planned = roadmap + deferred) and FSM status (exact match). -> -> **Rationale:** The two-domain status convention requires separate query methods — mixing them produces incorrect filtered results. - -**Verified by:** - -- Get patterns by normalized status -- Get patterns by FSM status -- Get current work returns active patterns -- Get roadmap items returns roadmap and deferred -- Get status counts -- Get completion percentage - ---- - -#### Phase queries return correct phase data - -> **Invariant:** Phase queries must return only patterns in the requested phase, with accurate progress counts and completion percentage. -> -> **Rationale:** Phase-level queries power the roadmap and session planning views — incorrect counts cascade into wrong progress percentages. - -**Verified by:** - -- Get patterns by phase -- Get phase progress -- Get nonexistent phase returns undefined -- Get active phases - ---- - -#### FSM queries expose transition validation - -> **Invariant:** FSM queries must validate transitions against the PDR-005 state machine and expose protection levels per status. -> -> **Rationale:** Programmatic FSM access enables tooling to enforce delivery process rules without reimplementing the state machine. - -**Verified by:** - -- Check valid transition -- Check invalid transition -- Get valid transitions from status -- Get protection info - ---- - -#### Pattern queries find and retrieve pattern data - -> **Invariant:** Pattern lookup must be case-insensitive by name, and category queries must return only patterns with the requested category. -> -> **Rationale:** Case-insensitive search reduces friction in CLI and AI agent usage where exact casing is often unknown. - -**Verified by:** - -- Find pattern by name (case insensitive) -- Find nonexistent pattern returns undefined -- Get patterns by category -- Get all categories with counts - ---- - -#### Timeline queries group patterns by time - -> **Invariant:** Quarter queries must correctly filter by quarter string, and recently completed must be sorted by date descending with limit. -> -> **Rationale:** Timeline grouping enables quarterly reporting and session context — recent completions show delivery momentum. - -**Verified by:** - -- Get patterns by quarter -- Get all quarters -- Get recently completed sorted by date - -_process-state-api.feature_ - ### Scope Validator Tests _Starting an implementation or design session without checking prerequisites_ diff --git a/docs-live/business-rules/generation.md b/docs-live/business-rules/generation.md index ac817cd6..07d3bf15 100644 --- a/docs-live/business-rules/generation.md +++ b/docs-live/business-rules/generation.md @@ -362,17 +362,17 @@ _Validates that ARCHITECTURE.md retains its full reference content and that_ --- -#### MasterDataset shapes appear in ARCHITECTURE-TYPES reference +#### PatternGraph shapes appear in ARCHITECTURE-TYPES reference -> **Invariant:** The ARCHITECTURE-TYPES.md reference document contains core MasterDataset types (MasterDataset, RuntimeMasterDataset, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. +> **Invariant:** The ARCHITECTURE-TYPES.md reference document contains core PatternGraph types (PatternGraph, RuntimePatternGraph, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. > > **Rationale:** Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift. **Verified by:** -- Core MasterDataset types appear in ARCHITECTURE-TYPES +- Core PatternGraph types appear in ARCHITECTURE-TYPES - Pipeline types appear in ARCHITECTURE-TYPES reference -- Unified Transformation section has full MasterDataset content +- Unified Transformation section has full PatternGraph content --- @@ -554,7 +554,7 @@ _arch-tag-extraction.feature_ ### Business Rules Document Codec -_Tests the BusinessRulesCodec transformation from MasterDataset to RenderableDocument._ +_Tests the BusinessRulesCodec transformation from PatternGraph to RenderableDocument._ --- @@ -709,7 +709,7 @@ _Tests the CodecBasedGenerator which adapts the RenderableDocument Model (RDM)_ > **Invariant:** CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. > -> **Rationale:** The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. MasterDataset is required in context — enforced by the TypeScript type system, not at runtime. +> **Rationale:** The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. PatternGraph is required in context — enforced by the TypeScript type system, not at runtime. **Verified by:** @@ -1003,7 +1003,7 @@ _content-deduplication.feature_ ### Convention Extractor -_Extracts convention content from MasterDataset decision records_ +_Extracts convention content from PatternGraph decision records_ --- @@ -1476,7 +1476,7 @@ _Tests the full design review generation pipeline: sequence annotations are_ > **Invariant:** buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. > -> **Rationale:** Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model. +> **Rationale:** Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model. **Verified by:** @@ -1906,7 +1906,7 @@ _implementation-links.feature_ ### Index Codec -_Validates the Index Codec that transforms MasterDataset into a_ +_Validates the Index Codec that transforms PatternGraph into a_ --- @@ -3263,12 +3263,12 @@ _Scoped diagram generation from diagramScopes config, including archContext,_ > **Invariant:** Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content. > -> **Rationale:** Domain diagrams such as pipeline and MasterDataset fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. +> **Rationale:** Domain diagrams such as pipeline and PatternGraph fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. **Verified by:** -- master-dataset-views source produces MasterDataset fan-out diagram -- master-dataset-views source renders expected fan-out nodes +- pattern-graph-views source produces PatternGraph fan-out diagram +- pattern-graph-views source renders expected fan-out nodes --- @@ -3788,7 +3788,7 @@ _- Need to generate product requirements documents with flexible groupings_ #### RequirementsDocumentCodec generates PRD-style documentation from patterns -> **Invariant:** RequirementsDocumentCodec transforms MasterDataset patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. +> **Invariant:** RequirementsDocumentCodec transforms PatternGraph patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. > > **Rationale:** Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. @@ -3811,7 +3811,7 @@ _- Need to generate product requirements documents with flexible groupings_ #### AdrDocumentCodec documents architecture decisions -> **Invariant:** AdrDocumentCodec transforms MasterDataset ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. +> **Invariant:** AdrDocumentCodec transforms PatternGraph ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. > > **Rationale:** Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned. @@ -4317,7 +4317,7 @@ _table-extraction.feature_ ### Taxonomy Codec -_Validates the Taxonomy Codec that transforms MasterDataset into a_ +_Validates the Taxonomy Codec that transforms PatternGraph into a_ --- @@ -4485,7 +4485,7 @@ _- Generators need multiple views of the same pattern data_ #### Empty dataset produces valid zero-state views -> **Invariant:** An empty input produces a MasterDataset with all counts at zero and no groupings. +> **Invariant:** An empty input produces a PatternGraph with all counts at zero and no groupings. > > **Rationale:** Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs. @@ -4570,7 +4570,7 @@ _- Generators need multiple views of the same pattern data_ #### Workflow integration conditionally includes delivery process data -> **Invariant:** The workflow is included in the MasterDataset only when provided, and phase names are resolved from the workflow configuration. +> **Invariant:** The workflow is included in the PatternGraph only when provided, and phase names are resolved from the workflow configuration. > > **Rationale:** Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation. @@ -4583,7 +4583,7 @@ _transform-dataset.feature_ ### Validation Rules Codec -_Validates the Validation Rules Codec that transforms MasterDataset into a_ +_Validates the Validation Rules Codec that transforms PatternGraph into a_ --- diff --git a/docs-live/decisions/adr-003-source-first-pattern-architecture.md b/docs-live/decisions/adr-003-source-first-pattern-architecture.md index 3c068610..9a48c285 100644 --- a/docs-live/decisions/adr-003-source-first-pattern-architecture.md +++ b/docs-live/decisions/adr-003-source-first-pattern-architecture.md @@ -112,7 +112,7 @@ artifacts are annotated source code, executable specs, and decision specs. **Invariant:** `@architect-pattern:X` may appear in exactly one file across the entire codebase. The `mergePatterns()` conflict check in `orchestrator.ts` correctly enforces this. -**Rationale:** Duplicate pattern definitions cause merge conflicts in the MasterDataset and produce ambiguous ownership in generated documentation. +**Rationale:** Duplicate pattern definitions cause merge conflicts in the PatternGraph and produce ambiguous ownership in generated documentation. | Current State | Resolution | | ------------------------------- | ----------------------------------------------- | diff --git a/docs-live/decisions/adr-005-codec-based-markdown-rendering.md b/docs-live/decisions/adr-005-codec-based-markdown-rendering.md index cbe9827e..3d4d574f 100644 --- a/docs-live/decisions/adr-005-codec-based-markdown-rendering.md +++ b/docs-live/decisions/adr-005-codec-based-markdown-rendering.md @@ -13,7 +13,7 @@ **Context:** The documentation generator needs to transform structured pattern data -(MasterDataset) into markdown files. The initial approach used direct +(PatternGraph) into markdown files. The initial approach used direct string concatenation in generator functions, mixing data selection, formatting logic, and output assembly in a single pass. This made generators hard to test, difficult to compose, and impossible to @@ -22,7 +22,7 @@ AI context). **Decision:** Adopt a codec architecture inspired by serialization codecs (encode/decode). -Each document type has a codec that decodes a MasterDataset into a +Each document type has a codec that decodes a PatternGraph into a RenderableDocument — an intermediate representation of sections, headings, tables, paragraphs, and code blocks. A separate renderer transforms the RenderableDocument into markdown. This separates data selection (what to @@ -52,15 +52,15 @@ include) from formatting (how it looks) from serialization (markdown syntax). ### Codecs implement a decode-only contract -**Invariant:** Every codec is a pure function that accepts a MasterDataset and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. +**Invariant:** Every codec is a pure function that accepts a PatternGraph and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. -**Rationale:** Pure functions are deterministic and trivially testable. For the same MasterDataset, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. +**Rationale:** Pure functions are deterministic and trivially testable. For the same PatternGraph, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. **Codec call signature:** ```typescript interface DocumentCodec { - decode(dataset: MasterDataset): RenderableDocument; + decode(dataset: PatternGraph): RenderableDocument; } ``` diff --git a/docs-live/decisions/adr-006-single-read-model-architecture.md b/docs-live/decisions/adr-006-single-read-model-architecture.md index f8a4be84..52c2a688 100644 --- a/docs-live/decisions/adr-006-single-read-model-architecture.md +++ b/docs-live/decisions/adr-006-single-read-model-architecture.md @@ -14,26 +14,26 @@ **Context:** The Architect package applies event sourcing to itself: git is the event store, annotated source files are authoritative state, generated -documentation is a projection. The MasterDataset is the read model — +documentation is a projection. The PatternGraph is the read model — produced by a single-pass O(n) transformer with pre-computed views and a relationship index. -ADR-005 established that codecs consume MasterDataset as their sole input. -The ProcessStateAPI consumes it. But the validation layer bypasses it, +ADR-005 established that codecs consume PatternGraph as their sole input. +The PatternGraphAPI consumes it. But the validation layer bypasses it, wiring its own mini-pipeline from raw scanner/extractor output. It creates a lossy local type that discards relationship data, then discovers it lacks the information needed — requiring ad-hoc re-derivation of what -the MasterDataset already computes. +the PatternGraph already computes. -This is the same class of problem the MasterDataset was created to solve. +This is the same class of problem the PatternGraph was created to solve. Before the single-pass transformer, each generator called `.filter()` -independently. The MasterDataset eliminated that duplication for codecs. +independently. The PatternGraph eliminated that duplication for codecs. This ADR extends the same principle to all consumers. **Decision:** -The MasterDataset is the single read model for all consumers. No consumer +The PatternGraph is the single read model for all consumers. No consumer re-derives pattern data from raw scanner/extractor output when that data -is available in the MasterDataset. Validators, codecs, and query APIs +is available in the PatternGraph. Validators, codecs, and query APIs consume the same pre-computed read model. **Consequences:** @@ -42,27 +42,27 @@ consume the same pre-computed read model. | -------- | ---------------------------------------------------------------------------------------------- | | Positive | Relationship resolution happens once — no consumer re-derives implements, uses, or dependsOn | | Positive | Eliminates lossy local types that discard fields from canonical ExtractedPattern | -| Positive | Validation rules automatically benefit from new MasterDataset views and indices | +| Positive | Validation rules automatically benefit from new PatternGraph views and indices | | Positive | Aligns with the monorepo's own ADR-006: projections for all reads, never query aggregate state | | Negative | Validators that today only need stage 1-2 data will import the transformer | -| Negative | MasterDataset schema changes affect more consumers | +| Negative | PatternGraph schema changes affect more consumers | ## Rules ### All feature consumers query the read model, not raw state -**Invariant:** Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the MasterDataset. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the MasterDataset. +**Invariant:** Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the PatternGraph. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the PatternGraph. -**Rationale:** Bypassing the read model forces consumers to re-derive data that the MasterDataset already computes, creating duplicate logic and divergent behavior when the pipeline evolves. +**Rationale:** Bypassing the read model forces consumers to re-derive data that the PatternGraph already computes, creating duplicate logic and divergent behavior when the pipeline evolves. -| Layer | May Import | Examples | -| ---------------------- | -------------------------------- | --------------------------------------------------- | -| Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, process-api.ts pipeline setup | -| Feature Consumption | MasterDataset, relationshipIndex | codecs, ProcessStateAPI, validators, query handlers | +| Layer | May Import | Examples | +| ---------------------- | ------------------------------- | --------------------------------------------------- | +| Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, process-api.ts pipeline setup | +| Feature Consumption | PatternGraph, relationshipIndex | codecs, PatternGraphAPI, validators, query handlers | **Verified by:** -- Feature consumers import from MasterDataset not from raw pipeline stages +- Feature consumers import from PatternGraph not from raw pipeline stages Exception: `lint-patterns.ts` is a pure stage-1 consumer. It validates annotation syntax on scanned files. No relationships @@ -74,21 +74,21 @@ consume the same pre-computed read model. **Invariant:** Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. -**Rationale:** Lossy local types silently drop fields that later become needed, causing bugs that only surface when new MasterDataset capabilities are added and the local type lacks them. +**Rationale:** Lossy local types silently drop fields that later become needed, causing bugs that only surface when new PatternGraph capabilities are added and the local type lacks them. **Verified by:** -- Feature consumers import from MasterDataset not from raw pipeline stages +- Feature consumers import from PatternGraph not from raw pipeline stages ### Relationship resolution is computed once -**Invariant:** Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToMasterDataset()`. No consumer re-derives these from raw pattern arrays or scanned file tags. +**Invariant:** Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToPatternGraph()`. No consumer re-derives these from raw pattern arrays or scanned file tags. **Rationale:** Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. **Verified by:** -- Feature consumers import from MasterDataset not from raw pipeline stages +- Feature consumers import from PatternGraph not from raw pipeline stages ### Three named anti-patterns @@ -106,7 +106,7 @@ consume the same pre-computed read model. ```typescript // Good: consume the read model - function validateCrossSource(dataset: RuntimeMasterDataset): ValidationSummary { + function validateCrossSource(dataset: RuntimePatternGraph): ValidationSummary { const rel = dataset.relationshipIndex[patternName]; const isImplemented = rel.implementedBy.length > 0; } @@ -121,12 +121,12 @@ consume the same pre-computed read model. **References** - Monorepo ADR-006: Projections for All Reads (same principle, application domain) - - ADR-005: Codec-Based Markdown Rendering (established MasterDataset as codec input) + - ADR-005: Codec-Based Markdown Rendering (established PatternGraph as codec input) - Order-management ARCHITECTURE.md: CommandOrchestrator + Read Model separation **Verified by:** -- Feature consumers import from MasterDataset not from raw pipeline stages +- Feature consumers import from PatternGraph not from raw pipeline stages Naming them makes them visible in code review — including AI-assisted sessions where the default proposal is often "add a helper function." diff --git a/docs-live/product-areas/ANNOTATION.md b/docs-live/product-areas/ANNOTATION.md index 773cad42..f9d6eaa1 100644 --- a/docs-live/product-areas/ANNOTATION.md +++ b/docs-live/product-areas/ANNOTATION.md @@ -210,35 +210,35 @@ interface CategoryDefinition { type CategoryTag = (typeof CATEGORIES)[number]['tag']; ``` -### buildRegistry (function) +### isShapeOnlyDirective (function) ```typescript /** - * Build the complete tag registry from TypeScript constants + * Check if a directive is a shape-only annotation (declaration-level @architect-shape). * - * This is THE single source of truth for the taxonomy. - * All consumers should use this function instead of loading JSON. + * Shape directives annotate individual interfaces/types for documentation extraction. + * They inherit context from a parent pattern and should not enter the directive pipeline + * as standalone patterns. */ ``` ```typescript -function buildRegistry(): TagRegistry; +function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; ``` -### isShapeOnlyDirective (function) +### buildRegistry (function) ```typescript /** - * Check if a directive is a shape-only annotation (declaration-level @architect-shape). + * Build the complete tag registry from TypeScript constants * - * Shape directives annotate individual interfaces/types for documentation extraction. - * They inherit context from a parent pattern and should not enter the directive pipeline - * as standalone patterns. + * This is THE single source of truth for the taxonomy. + * All consumers should use this function instead of loading JSON. */ ``` ```typescript -function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; +function buildRegistry(): TagRegistry; ``` ### METADATA_TAGS_BY_GROUP (const) diff --git a/docs-live/product-areas/CORE-TYPES.md b/docs-live/product-areas/CORE-TYPES.md index 0bd9e85e..999f7864 100644 --- a/docs-live/product-areas/CORE-TYPES.md +++ b/docs-live/product-areas/CORE-TYPES.md @@ -33,9 +33,9 @@ Scoped architecture diagram showing component relationships: ```mermaid C4Context title Core Type System + System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") - System(StringUtils, "StringUtils") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") Rel(KebabCaseSlugs, StringUtils, "depends on") @@ -51,9 +51,9 @@ Scoped architecture diagram showing component relationships: ```mermaid graph LR + StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] - StringUtils["StringUtils"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] KebabCaseSlugs -.->|depends on| StringUtils diff --git a/docs-live/product-areas/DATA-API.md b/docs-live/product-areas/DATA-API.md index df545a68..842c4e95 100644 --- a/docs-live/product-areas/DATA-API.md +++ b/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` without process-level side effects. +**Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` 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,7 +39,7 @@ 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. --- @@ -52,7 +52,7 @@ 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,22 +65,22 @@ Scoped architecture diagram showing component relationships: ```mermaid graph TB subgraph api["Api"] - MasterDataset[/"MasterDataset"/] - MCPToolRegistry("MCPToolRegistry") - MCPServerImpl("MCPServerImpl") - MCPPipelineSession("MCPPipelineSession") - MCPModule[/"MCPModule"/] - MCPFileWatcher[/"MCPFileWatcher"/] + PatternGraph[/"PatternGraph"/] PatternSummarizerImpl("PatternSummarizerImpl") ScopeValidatorImpl("ScopeValidatorImpl") - ProcessStateAPI("ProcessStateAPI") PatternHelpers["PatternHelpers"] + PatternGraphAPI("PatternGraphAPI") HandoffGeneratorImpl("HandoffGeneratorImpl") FuzzyMatcherImpl("FuzzyMatcherImpl") CoverageAnalyzerImpl("CoverageAnalyzerImpl") ContextFormatterImpl("ContextFormatterImpl") ContextAssemblerImpl("ContextAssemblerImpl") ArchQueriesImpl("ArchQueriesImpl") + MCPToolRegistry("MCPToolRegistry") + MCPServerImpl("MCPServerImpl") + MCPPipelineSession("MCPPipelineSession") + MCPModule[/"MCPModule"/] + MCPFileWatcher[/"MCPFileWatcher"/] end subgraph cli["Cli"] ReplMode("ReplMode") @@ -98,9 +98,9 @@ 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 @@ -108,33 +108,17 @@ graph TB DataAPICLIErgonomics["DataAPICLIErgonomics"]:::neighbor DataAPIArchitectureQueries["DataAPIArchitectureQueries"]:::neighbor end - MCPToolRegistry -->|uses| ProcessStateAPI - MCPToolRegistry -->|uses| MCPPipelineSession - MCPToolRegistry ..->|implements| MCPServerIntegration - MCPServerImpl -->|uses| MCPPipelineSession - MCPServerImpl -->|uses| MCPToolRegistry - MCPServerImpl -->|uses| MCPFileWatcher - MCPServerImpl ..->|implements| MCPServerIntegration - MCPPipelineSession -->|uses| PipelineFactory - MCPPipelineSession -->|uses| ProcessStateAPI - MCPPipelineSession -->|uses| ConfigLoader - MCPPipelineSession ..->|implements| MCPServerIntegration - MCPModule -->|uses| MCPServerImpl - MCPModule -->|uses| MCPPipelineSession - MCPModule -->|uses| MCPFileWatcher - 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| PatternGraphAPI + ProcessAPICLIImpl -->|uses| PatternGraph ProcessAPICLIImpl -->|uses| PipelineFactory ProcessAPICLIImpl -->|uses| RulesQueryModule ProcessAPICLIImpl -->|uses| PatternSummarizerImpl ProcessAPICLIImpl -->|uses| FuzzyMatcherImpl ProcessAPICLIImpl -->|uses| OutputPipelineImpl - ProcessAPICLIImpl ..->|implements| ProcessStateAPICLI + ProcessAPICLIImpl ..->|implements| PatternGraphAPICLI OutputPipelineImpl -->|uses| PatternSummarizerImpl OutputPipelineImpl ..->|implements| DataAPIOutputShaping MCPServerBin -->|uses| MCPServerImpl @@ -143,38 +127,54 @@ graph TB DatasetCache -->|uses| WorkflowConfigSchema DatasetCache ..->|implements| DataAPICLIErgonomics CLISchema ..->|implements| ProcessApiHybridGeneration - PatternSummarizerImpl -->|uses| ProcessStateAPI + 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 + MCPToolRegistry -->|uses| PatternGraphAPI + MCPToolRegistry -->|uses| MCPPipelineSession + MCPToolRegistry ..->|implements| MCPServerIntegration + MCPServerImpl -->|uses| MCPPipelineSession + MCPServerImpl -->|uses| MCPToolRegistry + MCPServerImpl -->|uses| MCPFileWatcher + MCPServerImpl ..->|implements| MCPServerIntegration + MCPPipelineSession -->|uses| PipelineFactory + MCPPipelineSession -->|uses| PatternGraphAPI + MCPPipelineSession -->|uses| ConfigLoader + MCPPipelineSession ..->|implements| MCPServerIntegration + MCPModule -->|uses| MCPServerImpl + MCPModule -->|uses| MCPPipelineSession + MCPModule -->|uses| MCPFileWatcher + MCPModule -->|uses| MCPToolRegistry + MCPFileWatcher ..->|implements| MCPServerIntegration + 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. @@ -235,14 +235,14 @@ 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 /** @@ -255,7 +255,7 @@ interface PipelineResult { ``` ```typescript -MasterDatasetSchema = z.object({ +PatternGraphSchema = z.object({ // ───────────────────────────────────────────────────────────────────────── // Raw Data // ───────────────────────────────────────────────────────────────────────── @@ -550,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. | @@ -587,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 @@ -660,13 +660,13 @@ ArchIndexSchema = z.object({ ### 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 @@ -677,6 +677,36 @@ 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 Graph API CLI + +| 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 Graph API Relationship Queries + +| 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. | + +### Pattern Graph API Testing + +| 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. | + ### Pattern Helpers Tests | Rule | Invariant | Rationale | @@ -707,9 +737,9 @@ ArchIndexSchema = z.object({ ### Process Api 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 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. | +| 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 @@ -717,10 +747,10 @@ ArchIndexSchema = z.object({ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | @@ -770,13 +800,13 @@ ArchIndexSchema = z.object({ ### Process API 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` 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 | `process-api.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 (process-api, 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 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` 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. | ### Process Api Reference Tests @@ -786,36 +816,6 @@ ArchIndexSchema = z.object({ | 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 - -| 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. | - -### Process State API Relationship Queries - -| 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. | - -### Process State API Testing - -| 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. | - ### Scope Validator Tests | Rule | Invariant | Rationale | diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index addcffcb..f6f40e96 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -5,16 +5,16 @@ --- -**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. +**How does code become docs?** The generation pipeline transforms annotated source code into markdown documents through a four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels (detailed, standard, summary). The Orchestrator runs generators in registration order, producing both detailed `docs-live/` references and compact `_claude-md/` summaries. ### Pipeline Stages -| Stage | Module | Responsibility | -| ----------- | -------------------------- | --------------------------------------------------------------- | -| Scanner | `src/scanner/` | File discovery, AST parsing, opt-in via `@architect` | -| Extractor | `src/extractor/` | Pattern extraction from TypeScript JSDoc and Gherkin tags | -| Transformer | `src/generators/pipeline/` | MasterDataset with pre-computed views for O(1) access (ADR-006) | -| Codec | `src/renderable/` | Pure functions: MasterDataset → RenderableDocument → Markdown | +| Stage | Module | Responsibility | +| ----------- | -------------------------- | -------------------------------------------------------------- | +| Scanner | `src/scanner/` | File discovery, AST parsing, opt-in via `@architect` | +| Extractor | `src/extractor/` | Pattern extraction from TypeScript JSDoc and Gherkin tags | +| Transformer | `src/generators/pipeline/` | PatternGraph with pre-computed views for O(1) access (ADR-006) | +| Codec | `src/renderable/` | Pure functions: PatternGraph → RenderableDocument → Markdown | ### Codec Inventory @@ -33,7 +33,7 @@ ## Key Invariants - Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output -- Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship +- Single read model (ADR-006): All codecs consume PatternGraph. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship - Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/` - Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors - RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer @@ -64,15 +64,15 @@ graph TB GitBranchDiff["GitBranchDiff"] SourceMapper[/"SourceMapper"/] Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") + ProcessApiReferenceGenerator["ProcessApiReferenceGenerator"] + DesignReviewGenerator("DesignReviewGenerator") + DecisionDocGenerator("DecisionDocGenerator") + CliRecipeGenerator["CliRecipeGenerator"] TransformTypes["TransformTypes"] TransformDataset("TransformDataset") SequenceTransformUtils("SequenceTransformUtils") RelationshipResolver("RelationshipResolver") ContextInferenceImpl["ContextInferenceImpl"] - ProcessApiReferenceGenerator["ProcessApiReferenceGenerator"] - DesignReviewGenerator("DesignReviewGenerator") - DecisionDocGenerator("DecisionDocGenerator") - CliRecipeGenerator["CliRecipeGenerator"] end subgraph renderer["Renderer"] loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser["loadPreambleFromMarkdown — Shared Markdown-to-SectionBlock Parser"] @@ -84,7 +84,7 @@ graph TB ArchitectureCodec[("ArchitectureCodec")] end subgraph related["Related"] - MasterDataset["MasterDataset"]:::neighbor + PatternGraph["PatternGraph"]:::neighbor Pattern_Scanner["Pattern Scanner"]:::neighbor GherkinASTParser["GherkinASTParser"]:::neighbor ShapeExtractor["ShapeExtractor"]:::neighbor @@ -97,33 +97,33 @@ graph TB CliRecipeCodec["CliRecipeCodec"]:::neighbor ContextInference["ContextInference"]:::neighbor end + loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec GitModule -->|uses| GitBranchDiff GitModule -->|uses| GitHelpers - loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec SourceMapper -.->|depends on| DecisionDocCodec SourceMapper -.->|depends on| ShapeExtractor SourceMapper -.->|depends on| GherkinASTParser Documentation_Generation_Orchestrator -->|uses| Pattern_Scanner PatternsCodec ..->|implements| PatternRelationshipModel - DesignReviewCodec -->|uses| MasterDataset + DesignReviewCodec -->|uses| PatternGraph DesignReviewCodec -->|uses| MermaidDiagramUtils DesignReviewCodec ..->|implements| DesignReviewGeneration CompositeCodec ..->|implements| ReferenceDocShowcase - ArchitectureCodec -->|uses| MasterDataset - TransformTypes -->|uses| MasterDataset - TransformDataset -->|uses| MasterDataset - TransformDataset ..->|implements| PatternRelationshipModel - SequenceTransformUtils -->|uses| MasterDataset - SequenceTransformUtils ..->|implements| DesignReviewGeneration - RelationshipResolver -->|uses| PatternHelpers - ContextInferenceImpl ..->|implements| ContextInference + ArchitectureCodec -->|uses| PatternGraph ProcessApiReferenceGenerator ..->|implements| ProcessApiHybridGeneration DesignReviewGenerator -->|uses| DesignReviewCodec - DesignReviewGenerator -->|uses| MasterDataset + DesignReviewGenerator -->|uses| PatternGraph DesignReviewGenerator ..->|implements| DesignReviewGeneration DecisionDocGenerator -.->|depends on| DecisionDocCodec DecisionDocGenerator -.->|depends on| SourceMapper CliRecipeGenerator ..->|implements| CliRecipeCodec + TransformTypes -->|uses| PatternGraph + TransformDataset -->|uses| PatternGraph + TransformDataset ..->|implements| PatternRelationshipModel + SequenceTransformUtils -->|uses| PatternGraph + SequenceTransformUtils ..->|implements| DesignReviewGeneration + RelationshipResolver -->|uses| PatternHelpers + ContextInferenceImpl ..->|implements| ContextInference DesignReviewGeneration -.->|depends on| MermaidDiagramUtils CliRecipeCodec -.->|depends on| ProcessApiHybridGeneration classDef neighbor stroke-dasharray: 5 5 @@ -133,13 +133,13 @@ graph TB ## API Types -### RuntimeMasterDataset (interface) +### RuntimePatternGraph (interface) ```typescript /** - * Runtime MasterDataset with optional workflow + * Runtime PatternGraph with optional workflow * - * Extends the Zod-compatible MasterDataset with workflow reference. + * Extends the Zod-compatible PatternGraph with workflow reference. * LoadedWorkflow contains Maps which aren't JSON-serializable, * so it's kept separate from the Zod schema. * @@ -147,7 +147,7 @@ graph TB ``` ```typescript -interface RuntimeMasterDataset extends MasterDataset { +interface RuntimePatternGraph extends PatternGraph { /** Optional workflow configuration (not serializable) */ readonly workflow?: LoadedWorkflow; } @@ -256,11 +256,11 @@ type CollapsibleBlock = { }; ``` -### transformToMasterDataset (function) +### transformToPatternGraph (function) ```typescript /** - * Transform raw extracted data into a MasterDataset with all pre-computed views. + * Transform raw extracted data into a PatternGraph with all pre-computed views. * * This is a ONE-PASS transformation that computes: * - Status-based groupings (completed/active/planned) @@ -272,22 +272,22 @@ type CollapsibleBlock = { * - Optional relationship index * * Convenience wrapper that returns just the dataset. - * Use `transformToMasterDatasetWithValidation` to get validation summary. + * Use `transformToPatternGraphWithValidation` to get validation summary. * * @param raw - Raw dataset with patterns, registry, and optional workflow - * @returns MasterDataset with all pre-computed views + * @returns PatternGraph with all pre-computed views */ ``` ```typescript -function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; +function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ``` | Parameter | Type | Description | | --------- | ---- | ---------------------------------------------------------- | | raw | | Raw dataset with patterns, registry, and optional workflow | -**Returns:** MasterDataset with all pre-computed views +**Returns:** PatternGraph with all pre-computed views --- @@ -297,21 +297,21 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### ADR 005 Codec Based Markdown Rendering -| Rule | Invariant | Rationale | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Codecs implement a decode-only contract | Every codec is a pure function that accepts a MasterDataset and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. | Pure functions are deterministic and trivially testable. For the same MasterDataset, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. | -| RenderableDocument is a typed intermediate representation | RenderableDocument contains a title, an ordered array of SectionBlock elements, and an optional record of additional files. Each SectionBlock is a discriminated union: heading, paragraph, table, code, list, separator, or metaRow. The renderer consumes this IR without needing to know which codec produced it. | A typed IR decouples codecs from rendering. Codecs express intent ("this is a table with these rows") and the renderer handles syntax ("pipe-delimited markdown with separator row"). This means switching output format (e.g., HTML instead of markdown) requires only a new renderer, not changes to every codec. | -| CompositeCodec assembles documents from child codecs | CompositeCodec accepts an array of child codecs and produces a single RenderableDocument by concatenating their sections. Child codec order determines section order in the output. Separators are inserted between children by default. | Reference documents combine content from multiple domains (patterns, conventions, shapes, diagrams). Rather than building a monolithic codec that knows about all content types, CompositeCodec lets each domain own its codec and composes them declaratively. | -| ADR content comes from both Feature description and Rule prefixes | ADR structured content (Context, Decision, Consequences) can appear in two locations within a feature file. Both sources must be rendered. Silently dropping either source causes content loss. | Early ADRs used name prefixes like "Context - ..." and "Decision - ..." on Rule blocks to structure content. Later ADRs placed Context, Decision, and Consequences as bold-annotated prose in the Feature description, reserving Rule: blocks for invariants and design rules. Both conventions are valid. The ADR codec must handle both because the codebase contains ADRs authored in each style. The Feature description lives in pattern.directive.description. If the codec only renders Rules (via partitionRulesByPrefix), then Feature description content is silently dropped -- no error, no warning. This caused confusion across two repos where ADR content appeared in the feature file but was missing from generated docs. The fix renders pattern.directive.description in buildSingleAdrDocument between the Overview metadata table and the partitioned Rules section, using renderFeatureDescription() which walks content linearly and handles prose, tables, and DocStrings with correct interleaving. | -| The markdown renderer is codec-agnostic | The renderer accepts any RenderableDocument regardless of which codec produced it. Rendering depends only on block types, not on document origin. This enables testing codecs and renderers independently. | If the renderer knew about specific codecs, adding a new codec would require renderer changes. By operating purely on the SectionBlock discriminated union, the renderer is closed for modification but open for extension via new block types. | +| Rule | Invariant | Rationale | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Codecs implement a decode-only contract | Every codec is a pure function that accepts a PatternGraph and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. | Pure functions are deterministic and trivially testable. For the same PatternGraph, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. | +| RenderableDocument is a typed intermediate representation | RenderableDocument contains a title, an ordered array of SectionBlock elements, and an optional record of additional files. Each SectionBlock is a discriminated union: heading, paragraph, table, code, list, separator, or metaRow. The renderer consumes this IR without needing to know which codec produced it. | A typed IR decouples codecs from rendering. Codecs express intent ("this is a table with these rows") and the renderer handles syntax ("pipe-delimited markdown with separator row"). This means switching output format (e.g., HTML instead of markdown) requires only a new renderer, not changes to every codec. | +| CompositeCodec assembles documents from child codecs | CompositeCodec accepts an array of child codecs and produces a single RenderableDocument by concatenating their sections. Child codec order determines section order in the output. Separators are inserted between children by default. | Reference documents combine content from multiple domains (patterns, conventions, shapes, diagrams). Rather than building a monolithic codec that knows about all content types, CompositeCodec lets each domain own its codec and composes them declaratively. | +| ADR content comes from both Feature description and Rule prefixes | ADR structured content (Context, Decision, Consequences) can appear in two locations within a feature file. Both sources must be rendered. Silently dropping either source causes content loss. | Early ADRs used name prefixes like "Context - ..." and "Decision - ..." on Rule blocks to structure content. Later ADRs placed Context, Decision, and Consequences as bold-annotated prose in the Feature description, reserving Rule: blocks for invariants and design rules. Both conventions are valid. The ADR codec must handle both because the codebase contains ADRs authored in each style. The Feature description lives in pattern.directive.description. If the codec only renders Rules (via partitionRulesByPrefix), then Feature description content is silently dropped -- no error, no warning. This caused confusion across two repos where ADR content appeared in the feature file but was missing from generated docs. The fix renders pattern.directive.description in buildSingleAdrDocument between the Overview metadata table and the partitioned Rules section, using renderFeatureDescription() which walks content linearly and handles prose, tables, and DocStrings with correct interleaving. | +| The markdown renderer is codec-agnostic | The renderer accepts any RenderableDocument regardless of which codec produced it. Rendering depends only on block types, not on document origin. This enables testing codecs and renderers independently. | If the renderer knew about specific codecs, adding a new codec would require renderer changes. By operating purely on the SectionBlock discriminated union, the renderer is closed for modification but open for extension via new block types. | ### ADR 006 Single Read Model Architecture | Rule | Invariant | Rationale | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| All feature consumers query the read model, not raw state | Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the MasterDataset. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the MasterDataset. | Bypassing the read model forces consumers to re-derive data that the MasterDataset already computes, creating duplicate logic and divergent behavior when the pipeline evolves. | -| No lossy local types | Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. | Lossy local types silently drop fields that later become needed, causing bugs that only surface when new MasterDataset capabilities are added and the local type lacks them. | -| Relationship resolution is computed once | Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToMasterDataset()`. No consumer re-derives these from raw pattern arrays or scanned file tags. | Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. | +| All feature consumers query the read model, not raw state | Code that needs pattern relationships, status groupings, cross-source resolution, or dependency information consumes the PatternGraph. Direct scanner/extractor imports are permitted only in pipeline orchestration code that builds the PatternGraph. | Bypassing the read model forces consumers to re-derive data that the PatternGraph already computes, creating duplicate logic and divergent behavior when the pipeline evolves. | +| No lossy local types | Consumers do not define local DTOs that duplicate and discard fields from ExtractedPattern. If a consumer needs a subset, the type system provides the projection — not a hand-written extraction function that becomes a barrier between the consumer and canonical data. | Lossy local types silently drop fields that later become needed, causing bugs that only surface when new PatternGraph capabilities are added and the local type lacks them. | +| Relationship resolution is computed once | Forward relationships (uses, dependsOn, implementsPatterns) and reverse lookups (usedBy, implementedBy, extendedBy) are computed in `transformToPatternGraph()`. No consumer re-derives these from raw pattern arrays or scanned file tags. | Re-deriving relationships in consumers duplicates the resolution logic and risks inconsistency when different consumers implement subtly different traversal or filtering rules. | | Three named anti-patterns | These are recognized violations, serving as review criteria for new code and refactoring targets for existing code. | Without named anti-patterns, violations appear as one-off style issues rather than systematic architectural drift, making them harder to detect and communicate in code review. | ### Arch Generator Registration @@ -343,37 +343,37 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Architecture Diagram Core -| Rule | Invariant | Rationale | -| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Architecture tags exist in the tag registry | Three architecture-specific tags (`arch-role`, `arch-context`, `arch-layer`) must exist in the tag registry with correct format and enum values. | Architecture diagram generation requires metadata to classify source files into diagram components. Standard tag infrastructure enables consistent extraction via the existing AST parser. | -| AST parser extracts architecture tags from TypeScript | The AST parser must extract `arch-role`, `arch-context`, and `arch-layer` tags from TypeScript JSDoc comments into DocDirective objects. | Source code annotations are the single source of truth for architectural metadata. Parser must extract them alongside existing pattern metadata. | -| MasterDataset builds archIndex during transformation | The `transformToMasterDataset` function must build an `archIndex` that groups patterns by role, context, and layer for efficient diagram generation. | Single-pass extraction during dataset transformation avoids expensive re-traversal. Index structure enables O(1) lookup by each dimension. | -| Component diagrams group patterns by bounded context | Component diagrams must render patterns as nodes grouped into bounded context subgraphs, with relationship arrows using UML-inspired styles. | Component diagrams visualize system architecture showing how bounded contexts isolate components. Subgraphs enforce visual separation. | +| Rule | Invariant | Rationale | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Architecture tags exist in the tag registry | Three architecture-specific tags (`arch-role`, `arch-context`, `arch-layer`) must exist in the tag registry with correct format and enum values. | Architecture diagram generation requires metadata to classify source files into diagram components. Standard tag infrastructure enables consistent extraction via the existing AST parser. | +| AST parser extracts architecture tags from TypeScript | The AST parser must extract `arch-role`, `arch-context`, and `arch-layer` tags from TypeScript JSDoc comments into DocDirective objects. | Source code annotations are the single source of truth for architectural metadata. Parser must extract them alongside existing pattern metadata. | +| PatternGraph builds archIndex during transformation | The `transformToPatternGraph` function must build an `archIndex` that groups patterns by role, context, and layer for efficient diagram generation. | Single-pass extraction during dataset transformation avoids expensive re-traversal. Index structure enables O(1) lookup by each dimension. | +| Component diagrams group patterns by bounded context | Component diagrams must render patterns as nodes grouped into bounded context subgraphs, with relationship arrows using UML-inspired styles. | Component diagrams visualize system architecture showing how bounded contexts isolate components. Subgraphs enforce visual separation. | ### Architecture Doc Refactoring -| Rule | Invariant | Rationale | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Convention-tagged JSDoc produces machine-extractable codec documentation | Every codec source file annotated with `@architect-convention
codec-registry` must have structured JSDoc following the machine-extractable format. The convention extractor splits multi-codec files by `## Heading` into separate convention rules, each rendered as its own section in the generated reference document. | DD-1: Convention tag approach over dedicated codec. Rather than creating a new "codec inventory" codec that enumerates codecs from source, the existing convention-tag mechanism is reused. Each codec file's JSDoc is treated as convention rules tagged with `codec-registry`. This avoids new codec infrastructure and leverages the proven convention extractor path. The reference codec already handles 4-layer composition, so convention tags slot into the existing Layer 1 (conventions) position. | -| Machine-extractable JSDoc format follows structured heading convention | DD-2: Multi-codec JSDoc splitting uses one `## Heading` per codec per file. Each heading block contains structured fields in a fixed order: `**Purpose:**` one-liner, `**Output Files:**` file paths, options table with Type/Default/Description columns, `**When to Use:**` bullet list, and `**Factory Pattern:**` code example. Fields are optional -- codecs without options omit the table, codecs without factory patterns omit the code block. | The convention extractor uses `## ` heading regex to split descriptions into rules. Without this structure, a file like `session.ts` (3 codecs) would produce a single undifferentiated blob. The heading text becomes the convention rule title in the generated reference. The fixed field order ensures consistent rendering across all 20+ codec entries. | -| Heading match in convention extractor handles whitespace correctly | The convention extractor's heading parser uses `matchEnd` (the character position after the full regex match) rather than `indexOf('\n',
heading.index)` to calculate where content starts after a heading. This prevents the `\s*` prefix in the heading regex from consuming leading newlines, which would cause `heading.index` to point to those newlines instead of the heading text. | Discovered during Phase 2 implementation. The heading regex `/^\s*##\s+(.+)$/gm` matches headings with optional leading whitespace. When a heading has leading newlines, `heading.index` points to the first newline (part of the `\s*` match), not the `##` character. Using `indexOf('\n', heading.index)` then finds the newline BEFORE the heading, producing content that includes the heading text itself. The fix uses the regex match's end position directly. | -| Section disposition follows content-type routing | DD-3: Each ARCHITECTURE.md section is routed based on content type. Three routing strategies apply: (1) product area absorption -- sections describing a specific pipeline stage move to the corresponding product area document where they get live diagrams and relationship graphs; (2) generated shapes -- sections documenting TypeScript interfaces move to generated shape reference docs; (3) generated diagrams -- ASCII/text data flow diagrams are replaced by live Mermaid diagrams generated from architecture annotations. | The routing heuristic is: if a generated equivalent already exists, replace with pointer; if content is convention-taggable in source files, tag and generate; if editorial content that cannot be expressed as annotations, retain. This ensures each section lands in the location with the best maintenance model for its content type. | -| Product area absorption validates content coverage before pointer replacement | DD-4: Product area absorption replaces ARCHITECTURE.md sections with pointers only when the target product area document already covers the equivalent content. Three sections route to product areas: Configuration Architecture (L70-139) to CONFIGURATION.md, Source Systems (L585-692) to ANNOTATION.md, and Workflow Integration (L959-1068) to PROCESS.md. Annotation format examples from Source Systems merge into the Four-Stage Pipeline retained section rather than being lost. Workflow API code examples are dropped -- Claude reads source files directly. | Product area documents are generated from annotated source code and already contain live diagrams, relationship graphs, and API types. Absorbing manual Architecture sections into these generated docs eliminates drift while preserving the content in a maintained location. The key test is: does the product area doc cover the same technical facts? If yes, the manual section becomes a 4-line pointer. | -| MasterDataset shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group master-dataset to extract MasterDataset schema types, RuntimeMasterDataset, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape master-dataset and @architect-include master-dataset contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. | The MasterDataset is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md. | -| Pipeline architecture convention content replaces ASCII data flow diagrams | DD-7: The Data Flow Diagrams section (L774-957) contains 4 ASCII diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer architecture. A new master-dataset-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document. | ASCII diagrams cannot be generated from code annotations. The hybrid approach maximizes generated coverage: convention-tagged JSDoc captures the narrative (pipeline steps, ADR-006 consumer pattern) while the hardcoded diagram source produces visual Mermaid output. Using the already-registered pipeline-architecture convention tag avoids new taxonomy entries. | -| Usefulness-driven editorial trimming targets Claude as primary consumer | DD-9: ARCHITECTURE.md serves Claude (primary audience) and human developers (secondary). Content retained must answer architectural "why" and "how things connect" questions. Content available via source file reads or generated reference documents is removed. Post-decomposition target: ~320 lines (~75% reduction from 1,287 lines). Sections dropped entirely: Programmatic Usage (L1070-1125) and Extending the System (L1127-1194) -- Claude reads source files directly and infers extension patterns from existing codec implementations. DD-5: Key Design Patterns section (L693-772) trimmed from ~80 to ~15 lines: Result Monad becomes a pointer to CORE-TYPES.md, Schema-First Validation becomes a 3-line summary with source pointer, Tag Registry becomes a 4-line summary with source pointer. | Claude has direct access to source files and generated reference docs. Duplicating this content in ARCHITECTURE.md wastes context window tokens. The remaining editorial sections (Executive Summary, Four-Stage Pipeline, Codec Architecture, Progressive Disclosure) provide the mental model and architectural "why" that cannot be inferred from code alone. | +| Rule | Invariant | Rationale | +| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Convention-tagged JSDoc produces machine-extractable codec documentation | Every codec source file annotated with `@architect-convention
codec-registry` must have structured JSDoc following the machine-extractable format. The convention extractor splits multi-codec files by `## Heading` into separate convention rules, each rendered as its own section in the generated reference document. | DD-1: Convention tag approach over dedicated codec. Rather than creating a new "codec inventory" codec that enumerates codecs from source, the existing convention-tag mechanism is reused. Each codec file's JSDoc is treated as convention rules tagged with `codec-registry`. This avoids new codec infrastructure and leverages the proven convention extractor path. The reference codec already handles 4-layer composition, so convention tags slot into the existing Layer 1 (conventions) position. | +| Machine-extractable JSDoc format follows structured heading convention | DD-2: Multi-codec JSDoc splitting uses one `## Heading` per codec per file. Each heading block contains structured fields in a fixed order: `**Purpose:**` one-liner, `**Output Files:**` file paths, options table with Type/Default/Description columns, `**When to Use:**` bullet list, and `**Factory Pattern:**` code example. Fields are optional -- codecs without options omit the table, codecs without factory patterns omit the code block. | The convention extractor uses `## ` heading regex to split descriptions into rules. Without this structure, a file like `session.ts` (3 codecs) would produce a single undifferentiated blob. The heading text becomes the convention rule title in the generated reference. The fixed field order ensures consistent rendering across all 20+ codec entries. | +| Heading match in convention extractor handles whitespace correctly | The convention extractor's heading parser uses `matchEnd` (the character position after the full regex match) rather than `indexOf('\n',
heading.index)` to calculate where content starts after a heading. This prevents the `\s*` prefix in the heading regex from consuming leading newlines, which would cause `heading.index` to point to those newlines instead of the heading text. | Discovered during Phase 2 implementation. The heading regex `/^\s*##\s+(.+)$/gm` matches headings with optional leading whitespace. When a heading has leading newlines, `heading.index` points to the first newline (part of the `\s*` match), not the `##` character. Using `indexOf('\n', heading.index)` then finds the newline BEFORE the heading, producing content that includes the heading text itself. The fix uses the regex match's end position directly. | +| Section disposition follows content-type routing | DD-3: Each ARCHITECTURE.md section is routed based on content type. Three routing strategies apply: (1) product area absorption -- sections describing a specific pipeline stage move to the corresponding product area document where they get live diagrams and relationship graphs; (2) generated shapes -- sections documenting TypeScript interfaces move to generated shape reference docs; (3) generated diagrams -- ASCII/text data flow diagrams are replaced by live Mermaid diagrams generated from architecture annotations. | The routing heuristic is: if a generated equivalent already exists, replace with pointer; if content is convention-taggable in source files, tag and generate; if editorial content that cannot be expressed as annotations, retain. This ensures each section lands in the location with the best maintenance model for its content type. | +| Product area absorption validates content coverage before pointer replacement | DD-4: Product area absorption replaces ARCHITECTURE.md sections with pointers only when the target product area document already covers the equivalent content. Three sections route to product areas: Configuration Architecture (L70-139) to CONFIGURATION.md, Source Systems (L585-692) to ANNOTATION.md, and Workflow Integration (L959-1068) to PROCESS.md. Annotation format examples from Source Systems merge into the Four-Stage Pipeline retained section rather than being lost. Workflow API code examples are dropped -- Claude reads source files directly. | Product area documents are generated from annotated source code and already contain live diagrams, relationship graphs, and API types. Absorbing manual Architecture sections into these generated docs eliminates drift while preserving the content in a maintained location. The key test is: does the product area doc cover the same technical facts? If yes, the manual section becomes a 4-line pointer. | +| PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group master-dataset to extract PatternGraph schema types, RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape pattern-graph and @architect-include master-dataset contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. | The PatternGraph is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md. | +| Pipeline architecture convention content replaces ASCII data flow diagrams | DD-7: The Data Flow Diagrams section (L774-957) contains 4 ASCII diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer architecture. A new pattern-graph-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document. | ASCII diagrams cannot be generated from code annotations. The hybrid approach maximizes generated coverage: convention-tagged JSDoc captures the narrative (pipeline steps, ADR-006 consumer pattern) while the hardcoded diagram source produces visual Mermaid output. Using the already-registered pipeline-architecture convention tag avoids new taxonomy entries. | +| Usefulness-driven editorial trimming targets Claude as primary consumer | DD-9: ARCHITECTURE.md serves Claude (primary audience) and human developers (secondary). Content retained must answer architectural "why" and "how things connect" questions. Content available via source file reads or generated reference documents is removed. Post-decomposition target: ~320 lines (~75% reduction from 1,287 lines). Sections dropped entirely: Programmatic Usage (L1070-1125) and Extending the System (L1127-1194) -- Claude reads source files directly and infers extension patterns from existing codec implementations. DD-5: Key Design Patterns section (L693-772) trimmed from ~80 to ~15 lines: Result Monad becomes a pointer to CORE-TYPES.md, Schema-First Validation becomes a 3-line summary with source pointer, Tag Registry becomes a 4-line summary with source pointer. | Claude has direct access to source files and generated reference docs. Duplicating this content in ARCHITECTURE.md wastes context window tokens. The remaining editorial sections (Executive Summary, Four-Stage Pipeline, Codec Architecture, Progressive Disclosure) provide the mental model and architectural "why" that cannot be inferred from code alone. | ### Architecture Doc Refactoring Testing -| Rule | Invariant | Rationale | -| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Product area sections coexist with generated documents | Each architecture section in docs/ARCHITECTURE.md has a corresponding generated document in docs-live/product-areas/ covering equivalent content from annotated sources. | Manual and generated docs must coexist during the transition period. Generated docs prove that annotated sources produce equivalent coverage before manual sections are deprecated. | -| Four-Stage Pipeline section retains annotation format examples | The Four-Stage Pipeline section contains annotation format examples (e.g., @architect-shape, extract-shapes) and appears before the Source Systems section in document order. | Annotation format examples in the pipeline section demonstrate the source-first architecture. Their ordering establishes the conceptual flow: pipeline stages first, then the source systems that feed them. | -| Convention extraction produces ARCHITECTURE-CODECS reference document | The ARCHITECTURE-CODECS.md reference document is generated from convention-tagged JSDoc in codec source files and contains structured sections for each codec with output file references. | Codec documentation must stay synchronized with source code. Convention extraction from JSDoc ensures the reference document reflects actual codec implementations rather than manually maintained descriptions that drift. | -| Full sections coexist with generated equivalents in docs-live | Major sections of ARCHITECTURE.md (Unified Transformation, Data Flow Diagrams, Quick Reference) are retained alongside their generated equivalents in docs-live/reference/. | Generated reference documents (ARCHITECTURE-TYPES.md, ARCHITECTURE-CODECS.md) provide exhaustive type and codec listings, but the manual sections offer architectural narrative and design rationale that generated docs cannot yet replicate. | -| MasterDataset shapes appear in ARCHITECTURE-TYPES reference | The ARCHITECTURE-TYPES.md reference document contains core MasterDataset types (MasterDataset, RuntimeMasterDataset, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. | Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift. | -| Pipeline architecture convention appears in generated reference | Source files in the pipeline layer (orchestrator.ts, build-pipeline.ts) carry the pipeline-architecture convention tag, enabling convention extraction into the ARCHITECTURE-TYPES reference document. | Convention tags on pipeline source files are the mechanism that feeds content into generated reference docs. Without these tags, the architecture reference would have no source material to extract. | -| Full ARCHITECTURE.md retains all sections with substantial content | ARCHITECTURE.md retains all major sections (Programmatic Usage, Extending the System, Key Design Patterns) with substantial content and remains under 1700 lines as a comprehensive reference. | These sections contain editorial content (usage examples, extension guides, design pattern explanations) that cannot be generated from annotations. They remain manual until procedural guide codecs can replicate their depth. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Product area sections coexist with generated documents | Each architecture section in docs/ARCHITECTURE.md has a corresponding generated document in docs-live/product-areas/ covering equivalent content from annotated sources. | Manual and generated docs must coexist during the transition period. Generated docs prove that annotated sources produce equivalent coverage before manual sections are deprecated. | +| Four-Stage Pipeline section retains annotation format examples | The Four-Stage Pipeline section contains annotation format examples (e.g., @architect-shape, extract-shapes) and appears before the Source Systems section in document order. | Annotation format examples in the pipeline section demonstrate the source-first architecture. Their ordering establishes the conceptual flow: pipeline stages first, then the source systems that feed them. | +| Convention extraction produces ARCHITECTURE-CODECS reference document | The ARCHITECTURE-CODECS.md reference document is generated from convention-tagged JSDoc in codec source files and contains structured sections for each codec with output file references. | Codec documentation must stay synchronized with source code. Convention extraction from JSDoc ensures the reference document reflects actual codec implementations rather than manually maintained descriptions that drift. | +| Full sections coexist with generated equivalents in docs-live | Major sections of ARCHITECTURE.md (Unified Transformation, Data Flow Diagrams, Quick Reference) are retained alongside their generated equivalents in docs-live/reference/. | Generated reference documents (ARCHITECTURE-TYPES.md, ARCHITECTURE-CODECS.md) provide exhaustive type and codec listings, but the manual sections offer architectural narrative and design rationale that generated docs cannot yet replicate. | +| PatternGraph shapes appear in ARCHITECTURE-TYPES reference | The ARCHITECTURE-TYPES.md reference document contains core PatternGraph types (PatternGraph, RuntimePatternGraph, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. | Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift. | +| Pipeline architecture convention appears in generated reference | Source files in the pipeline layer (orchestrator.ts, build-pipeline.ts) carry the pipeline-architecture convention tag, enabling convention extraction into the ARCHITECTURE-TYPES reference document. | Convention tags on pipeline source files are the mechanism that feeds content into generated reference docs. Without these tags, the architecture reference would have no source material to extract. | +| Full ARCHITECTURE.md retains all sections with substantial content | ARCHITECTURE.md retains all major sections (Programmatic Usage, Extending the System, Key Design Patterns) with substantial content and remains under 1700 lines as a comprehensive reference. | These sections contain editorial content (usage examples, extension guides, design pattern explanations) that cannot be generated from annotations. They remain manual until procedural guide codecs can replicate their depth. | ### Arch Tag Extraction @@ -437,9 +437,9 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Codec Based Generator Testing -| Rule | Invariant | Rationale | -| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CodecBasedGenerator adapts codecs to generator interface | CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. | The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. MasterDataset is required in context — enforced by the TypeScript type system, not at runtime. | +| Rule | Invariant | Rationale | +| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CodecBasedGenerator adapts codecs to generator interface | CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. | The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. PatternGraph is required in context — enforced by the TypeScript type system, not at runtime. | ### Codec Behavior Testing @@ -564,18 +564,18 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Design Review Generation -| Rule | Invariant | Rationale | -| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| SequenceIndex pre-computes ordered steps from rule-level tags | The MasterDataset sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model. Downstream consumers (codec, process API) read structured data, not raw tags. | -| DesignReviewCodec generates sequence diagrams from ordered steps | The sequence diagram contains participants derived from `@architect-sequence-module` tags, Note blocks from Rule names, call arrows from Input/Output markers, and alt blocks from `@architect-sequence-error` scenarios. Participant order follows step order with User and orchestrator first. | Sequence diagrams verify interaction ordering and error handling completeness. Auto-generation ensures diagrams stay synchronized with spec annotations. Manual diagrams drift within days of a spec edit. | -| DesignReviewCodec generates component diagrams from data flow types | The component diagram groups modules into subgraphs by shared Input type, renders distinct Output types as hexagon nodes with field lists, and draws directed edges showing data flow through the orchestrator. No circular edges exist in the generated diagram. | Component diagrams verify unidirectional data flow and interface completeness. Type hexagon nodes make the central contracts visible, informing stub creation with exact field lists. | -| Process API exposes sequence data via subcommand | The sequence subcommand with no args lists all patterns with sequence annotations. With a pattern name, it returns the full SequenceIndexEntry including steps, participants, and data flow types. | The Process API is the primary query interface for AI sessions. Exposing sequence data enables design review analysis without regenerating the full document or reading generated markdown. | +| Rule | Invariant | Rationale | +| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SequenceIndex pre-computes ordered steps from rule-level tags | The PatternGraph sequenceIndex contains one entry per pattern that has the `architect-sequence-orchestrator` tag and at least one rule with the `architect-sequence-step` tag. Steps are sorted by stepNumber. Participants are deduplicated and ordered with orchestrator first. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model. Downstream consumers (codec, process API) read structured data, not raw tags. | +| DesignReviewCodec generates sequence diagrams from ordered steps | The sequence diagram contains participants derived from `@architect-sequence-module` tags, Note blocks from Rule names, call arrows from Input/Output markers, and alt blocks from `@architect-sequence-error` scenarios. Participant order follows step order with User and orchestrator first. | Sequence diagrams verify interaction ordering and error handling completeness. Auto-generation ensures diagrams stay synchronized with spec annotations. Manual diagrams drift within days of a spec edit. | +| DesignReviewCodec generates component diagrams from data flow types | The component diagram groups modules into subgraphs by shared Input type, renders distinct Output types as hexagon nodes with field lists, and draws directed edges showing data flow through the orchestrator. No circular edges exist in the generated diagram. | Component diagrams verify unidirectional data flow and interface completeness. Type hexagon nodes make the central contracts visible, informing stub creation with exact field lists. | +| Process API exposes sequence data via subcommand | The sequence subcommand with no args lists all patterns with sequence annotations. With a pattern name, it returns the full SequenceIndexEntry including steps, participants, and data flow types. | The Process API is the primary query interface for AI sessions. Exposing sequence data enables design review analysis without regenerating the full document or reading generated markdown. | ### Design Review Generation Tests | Rule | Invariant | Rationale | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SequenceIndex pre-computes ordered steps from annotated rules | buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model. | +| SequenceIndex pre-computes ordered steps from annotated rules | buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. | Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model. | | Participants are deduplicated with orchestrator first | The participants array starts with the orchestrator, followed by module names in first-appearance step order, with no duplicates. | Sequence diagram participant declarations must be ordered and unique. The orchestrator is always the first participant as the entry point. | | Data flow types are extracted from Input and Output annotations | The dataFlowTypes array contains distinct type names parsed from Input and Output annotation strings using the "TypeName -- fields" format. | Data flow types are used by the component diagram to render hexagon nodes and by the type definitions table to show producers and consumers. | | DesignReviewCodec produces sequence diagram with correct participant count | The rendered sequence diagram participant list includes User plus all participants from the SequenceIndexEntry. The count equals 1 (User) plus the number of unique participants. | Correct participant count proves the codec reads SequenceIndex data correctly and maps it to Mermaid syntax. | @@ -631,12 +631,12 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Enhanced Index Generation -| Rule | Invariant | Rationale | -| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| IndexCodec composes generated statistics with editorial navigation | The IndexCodec generates document listings and pattern statistics from MasterDataset pre-computed views (`byCategory`, `byPhase`, `byProductArea`, `byStatus`), while audience reading paths, the document roles matrix, and the quick finder table use the `ReferenceDocConfig.preamble` mechanism as manually authored `SectionBlock[]`. The codec does not hardcode document metadata -- all statistics are derived from the dataset at generation time. Editorial content changes at authorial cadence via config edits, not code changes. | Approximately 40% of INDEX.md content (product area lists, file inventories, pattern statistics, phase progress) is directly derivable from MasterDataset views and drifts when patterns change status or new patterns are added. The remaining 60% (audience paths, document roles, quick finder) requires human editorial judgment about which documents serve which readers. The preamble mechanism cleanly separates these two content types within a single generated output, as proven by CodecDrivenReferenceGeneration and DocsConsolidationStrategy Phase 2. | -| Audience reading paths are first-class sections | Three audience profiles exist in the generated index: New User, Developer/AI, and Team Lead/CI. Each profile has a curated reading order that lists documents in recommended sequence with a one-line description of what each document provides for that audience. Reading paths appear prominently after the quick navigation table and before the auto-generated statistics sections. The reading paths are sourced from preamble, not derived from pattern metadata. | The manual INDEX.md reading orders are consistently cited as the most useful navigation aid by developers onboarding to the project. A flat alphabetical file listing (as in the current docs-live/INDEX.md) forces readers to guess which documents are relevant to their role. Audience-specific paths reduce time-to-relevance from minutes of scanning to seconds of following a curated sequence. This content is inherently editorial -- no annotation can express "read this third because it builds on concepts from document two." | -| Index unifies manual and generated doc listings | The generated index covers both `docs/` (manual reference documents) and `docs-live/` (generated reference documents) in a single unified navigation structure. Documents are organized by topic or audience, not by source directory. The reader does not need to know whether a document is manually authored or auto-generated. Each document entry includes its title, a brief description, and its primary audience. The directory source (docs/ or docs-live/) appears only in the link path, not as a section heading or organizational axis. | The current documentation set splits across two directories for implementation reasons (manual vs generated), but this split is meaningless to readers. A developer looking for architecture documentation should find one entry, not separate entries under "Manual Docs" and "Generated Docs" sections. The unified listing follows the same principle as a library catalog -- books are organized by subject, not by whether they were hand-typeset or digitally printed. | -| Document metadata drives auto-generated sections | Pattern counts per product area, phase progress summaries, and product area coverage percentages are derived from MasterDataset pre-computed views at generation time. The IndexCodec accesses `dataset.byProductArea` for area statistics, `dataset.byStatus` for status distribution, and `dataset.byPhase` for phase ordering. No statistics are hardcoded in the codec or config. When a pattern changes status or a new pattern is added, regenerating the index reflects the change without any manual update. | The manual INDEX.md has no statistics section because maintaining accurate counts manually is unsustainable across 196+ patterns. The MasterDataset pre-computed views provide O(1) access to grouped pattern data. Surfacing these statistics in the index gives readers an at-a-glance project health overview (how many patterns per area, what percentage are completed, which phases are active) that was previously only available via the Process Data API CLI. | +| Rule | Invariant | Rationale | +| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| IndexCodec composes generated statistics with editorial navigation | The IndexCodec generates document listings and pattern statistics from PatternGraph pre-computed views (`byCategory`, `byPhase`, `byProductArea`, `byStatus`), while audience reading paths, the document roles matrix, and the quick finder table use the `ReferenceDocConfig.preamble` mechanism as manually authored `SectionBlock[]`. The codec does not hardcode document metadata -- all statistics are derived from the dataset at generation time. Editorial content changes at authorial cadence via config edits, not code changes. | Approximately 40% of INDEX.md content (product area lists, file inventories, pattern statistics, phase progress) is directly derivable from PatternGraph views and drifts when patterns change status or new patterns are added. The remaining 60% (audience paths, document roles, quick finder) requires human editorial judgment about which documents serve which readers. The preamble mechanism cleanly separates these two content types within a single generated output, as proven by CodecDrivenReferenceGeneration and DocsConsolidationStrategy Phase 2. | +| Audience reading paths are first-class sections | Three audience profiles exist in the generated index: New User, Developer/AI, and Team Lead/CI. Each profile has a curated reading order that lists documents in recommended sequence with a one-line description of what each document provides for that audience. Reading paths appear prominently after the quick navigation table and before the auto-generated statistics sections. The reading paths are sourced from preamble, not derived from pattern metadata. | The manual INDEX.md reading orders are consistently cited as the most useful navigation aid by developers onboarding to the project. A flat alphabetical file listing (as in the current docs-live/INDEX.md) forces readers to guess which documents are relevant to their role. Audience-specific paths reduce time-to-relevance from minutes of scanning to seconds of following a curated sequence. This content is inherently editorial -- no annotation can express "read this third because it builds on concepts from document two." | +| Index unifies manual and generated doc listings | The generated index covers both `docs/` (manual reference documents) and `docs-live/` (generated reference documents) in a single unified navigation structure. Documents are organized by topic or audience, not by source directory. The reader does not need to know whether a document is manually authored or auto-generated. Each document entry includes its title, a brief description, and its primary audience. The directory source (docs/ or docs-live/) appears only in the link path, not as a section heading or organizational axis. | The current documentation set splits across two directories for implementation reasons (manual vs generated), but this split is meaningless to readers. A developer looking for architecture documentation should find one entry, not separate entries under "Manual Docs" and "Generated Docs" sections. The unified listing follows the same principle as a library catalog -- books are organized by subject, not by whether they were hand-typeset or digitally printed. | +| Document metadata drives auto-generated sections | Pattern counts per product area, phase progress summaries, and product area coverage percentages are derived from PatternGraph pre-computed views at generation time. The IndexCodec accesses `dataset.byProductArea` for area statistics, `dataset.byStatus` for status distribution, and `dataset.byPhase` for phase ordering. No statistics are hardcoded in the codec or config. When a pattern changes status or a new pattern is added, regenerating the index reflects the change without any manual update. | The manual INDEX.md has no statistics section because maintaining accurate counts manually is unsustainable across 196+ patterns. The PatternGraph pre-computed views provide O(1) access to grouped pattern data. Surfacing these statistics in the index gives readers an at-a-glance project health overview (how many patterns per area, what percentage are completed, which phases are active) that was previously only available via the Process Data API CLI. | ### Error Guide Codec @@ -663,7 +663,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Behavior-specs renderer does not duplicate convention table content | When the reference codec renders a convention rule that contains a table, the table appears exactly once in the output: in the main convention section. The behavior-specs (expanded rule detail) section shows only the Invariant, Rationale, and Verified-by metadata — not the table body. A convention section with N tables produces exactly N table instances in the generated document, regardless of detail level. | DD-4: The current renderer re-includes the full convention table when rendering the expanded rule detail section. For REFERENCE-SAMPLE.md with 5 canonical value tables, this produces 500+ lines of exact duplication. Agents consuming this file waste context on content they already parsed. Human readers see the same table twice in the same scroll view. | | Compact \_claude-md/ files are self-sufficient for their product area | Each product area compact (`_claude-md//-overview.md`) is self-sufficient as a standalone context file — an agent reading only the compact can answer: what does this area do, what are its key patterns, what are its invariants, and what files to read for details. Minimum target: 4 KB. The Generation compact is a specific gap: 1.4 KB for an area with 20+ codecs and the entire rendering pipeline. | DD-2: `_claude-md/` compacts are the Claude consumption contract. A 1.4 KB compact for the largest product area (233 KB) means agents have no usable summary context for Generation. They fall back to reading the full file or hallucinating based on names alone. The contract requires each compact to be a genuine summary, not a stub. | -| ARCHITECTURE-TYPES.md leads with type definitions, not convention content | ARCHITECTURE-TYPES.md opens with the MasterDataset type definitions section before any pipeline-architecture convention content. An agent querying "what is MasterDataset" finds the type definition within the first 30 lines. The pipeline-architecture convention prose (orchestrator responsibilities, pipeline steps) follows the type definitions section. | The file is named ARCHITECTURE-TYPES — type definitions are the primary content. The pipeline-architecture convention content was added as a secondary layer. Current output opens with orchestrator prose, burying the type definitions that both Claude and human developers are most likely seeking. Section ordering in ReferenceDocConfig determines render order. | +| ARCHITECTURE-TYPES.md leads with type definitions, not convention content | ARCHITECTURE-TYPES.md opens with the PatternGraph type definitions section before any pipeline-architecture convention content. An agent querying "what is PatternGraph" finds the type definition within the first 30 lines. The pipeline-architecture convention prose (orchestrator responsibilities, pipeline steps) follows the type definitions section. | The file is named ARCHITECTURE-TYPES — type definitions are the primary content. The pipeline-architecture convention content was added as a secondary layer. Current output opens with orchestrator prose, burying the type definitions that both Claude and human developers are most likely seeking. Section ordering in ReferenceDocConfig determines render order. | ### Generated Doc Quality Tests @@ -680,7 +680,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Orchestrator coordinates full documentation generation pipeline | Orchestrator merges TypeScript and Gherkin patterns, handles conflicts, and produces requested document types. | Without centralized orchestration, consumers would wire pipelines independently, leading to inconsistent merging and silent data loss. | | Registry manages generator registration and retrieval | Registry prevents duplicate names, returns undefined for unknown generators, and lists available generators alphabetically. | Duplicate registrations would silently overwrite generators, causing unpredictable output depending on registration order. | -| CodecBasedGenerator adapts codecs to generator interface | Generator delegates to underlying codec for transformation. Missing MasterDataset produces descriptive error. | If the adapter silently proceeds without a MasterDataset, codecs receive undefined input and produce corrupt or empty documents. | +| CodecBasedGenerator adapts codecs to generator interface | Generator delegates to underlying codec for transformation. Missing PatternGraph produces descriptive error. | If the adapter silently proceeds without a PatternGraph, codecs receive undefined input and produce corrupt or empty documents. | | Orchestrator supports PR changes generation options | PR changes can filter by git diff, changed files, or release version. | Without filtering, PR documentation would include all patterns in the dataset, making change review noisy and hiding actual modifications. | ### Generator Registry Testing @@ -765,7 +765,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | Rule | Invariant | Rationale | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Orchestrator delegates pipeline to factory | `generateDocumentation()` calls `buildMasterDataset()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`). | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit. | +| Orchestrator delegates pipeline to factory | `generateDocumentation()` calls `buildPatternGraph()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`). | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit. | | mergePatterns lives in pipeline module | The `mergePatterns()` function lives in `src/generators/pipeline/merge-patterns.ts` as a pipeline step. It is not defined in consumer code (orchestrator or CLI files). | `mergePatterns` is step 5 of the 8-step pipeline. It was defined in orchestrator.ts for historical reasons (the orchestrator was the first pipeline host). Now that the pipeline factory exists, the function belongs alongside other pipeline steps (scan, extract, transform). The public API re-export in `generators/index.ts` preserves backward compatibility. | | Factory provides structured warnings for all consumers | `PipelineResult.warnings` contains typed warning objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers that need simple messages (process-api) read `.message` only. | The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured `GenerationWarning` objects. The factory must provide equivalent structure to eliminate the orchestrator's need to run the pipeline directly. The `PipelineWarning` type is structurally similar to `GenerationWarning` to minimize mapping complexity. | | Pipeline factory supports partial success mode | When `failOnScanErrors` is false, the factory captures scan errors and extraction errors as warnings and continues with successfully processed files. When true (default), the factory returns `Result.err` on the first scan failure. | The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable files even if some files have syntax errors. The process-api treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration. | @@ -870,20 +870,20 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | Rule | Invariant | Rationale | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Procedural guides use a dual-source codec | The ProceduralGuideCodec composes auto-generated reference sections (from MasterDataset and taxonomy) with manually-authored procedural content (from preamble `SectionBlock[]`). Auto-generated content covers ~5% of the output (tag reference tables, pattern statistics, session type contract tables extracted from | | +| Procedural guides use a dual-source codec | The ProceduralGuideCodec composes auto-generated reference sections (from PatternGraph and taxonomy) with manually-authored procedural content (from preamble `SectionBlock[]`). Auto-generated content covers ~5% of the output (tag reference tables, pattern statistics, session type contract tables extracted from | | | blocks). The remaining ~95% is editorial preamble: checklists, decision trees, | | Gap analysis found that SESSION-GUIDES.md and ANNOTATION-GUIDE.md content is overwhelmingly procedural and editorial. Attempting to annotate checklists and walkthroughs as source code would produce worse documentation than hand-authoring. The dual-source pattern (proven by CodecDrivenReferenceGeneration, ErrorGuideCodec, and CliRecipeCodec) composes preamble editorial content with auto-generated reference sections. The codec's value is not in generating the procedural content but in providing a single output pipeline that keeps reference tables current while carrying editorial content in a consistent structure. | -| Session workflow checklists derive from annotated Rule: blocks | The SessionGuidesModuleSource spec's Rule: blocks (Rules 3-8) are the canonical source for session workflow invariants. The ProceduralGuideCodec extracts structured tables from these Rule: blocks and renders them as developer-facing checklists at the detailed level. The same Rule: blocks produce compact invariant statements for `_claude-md/workflow/` modules at the summary level. Two audiences (public developers and AI sessions) are served from a single annotated source with different rendering detail levels. The codec does not duplicate or re-derive Rule: block content -- it reads from MasterDataset's behavior extraction views. | SessionGuidesModuleSource already captures session type contracts (Rule 3), planning constraints (Rule 4), design constraints (Rule 5), implementation execution order (Rule 6), FSM error reference (Rule 7), and handoff patterns (Rule 8) as structured tables within Rule: block descriptions. These tables contain the same information as the manual SESSION-GUIDES.md checklists, but in a machine-extractable format. Rendering these as developer-facing checklists eliminates the maintenance burden of keeping the manual file in sync with the spec, while the compact rendering for AI context was already delivered by Phase 39. | +| Session workflow checklists derive from annotated Rule: blocks | The SessionGuidesModuleSource spec's Rule: blocks (Rules 3-8) are the canonical source for session workflow invariants. The ProceduralGuideCodec extracts structured tables from these Rule: blocks and renders them as developer-facing checklists at the detailed level. The same Rule: blocks produce compact invariant statements for `_claude-md/workflow/` modules at the summary level. Two audiences (public developers and AI sessions) are served from a single annotated source with different rendering detail levels. The codec does not duplicate or re-derive Rule: block content -- it reads from PatternGraph's behavior extraction views. | SessionGuidesModuleSource already captures session type contracts (Rule 3), planning constraints (Rule 4), design constraints (Rule 5), implementation execution order (Rule 6), FSM error reference (Rule 7), and handoff patterns (Rule 8) as structured tables within Rule: block descriptions. These tables contain the same information as the manual SESSION-GUIDES.md checklists, but in a machine-extractable format. Rendering these as developer-facing checklists eliminates the maintenance burden of keeping the manual file in sync with the spec, while the compact rendering for AI context was already delivered by Phase 39. | | Annotation guide content remains separate from session guides | The ProceduralGuideCodec produces two separate generated files via two `ReferenceDocConfig` entries: one for session workflow guides (replacing SESSION-GUIDES.md) and one for annotation guides (replacing ANNOTATION-GUIDE.md). The session workflow guide targets workflow practitioners who need to know session type selection, execution order, and FSM error recovery. The annotation guide targets annotation authors who need to know opt-in markers, tag syntax, shape extraction modes, and verification steps. These audiences overlap but have distinct primary needs. The codec class is shared; the config entries and preamble content differ. | SESSION-GUIDES.md and ANNOTATION-GUIDE.md serve different audiences at different points in the development lifecycle. Merging them into a single guide would force annotation authors to navigate session workflow content and vice versa. The existing DocsConsolidationStrategy Phase 5 (Guide trimming) already treats them as separate documents. Using one codec class with two config entries follows the same pattern as `createReferenceCodec` producing multiple documents from different configs. | | Decision trees render as Mermaid flowcharts | Session type decision trees and annotation workflow decision trees render as Mermaid flowchart diagrams in the detailed output level. The session type decision tree replaces the ASCII art tree in SESSION-GUIDES.md with a Mermaid `graph TD` diagram that renders as an interactive flowchart on the Starlight website. Decision tree content is authored as fenced mermaid code blocks in the markdown source file, parsed into `MermaidBlock` entries by `loadPreambleFromMarkdown()` at config load time. At summary level, decision trees render as compact text tables instead of diagrams. | The manual SESSION-GUIDES.md uses an ASCII art tree for the session decision flow, which renders poorly on the website and cannot be interacted with. Mermaid flowcharts are already supported by the Starlight website (proven by product area docs with C4Context and graph LR diagrams). Converting decision trees to Mermaid provides visual clarity, click-through navigation, and consistent rendering across platforms. The content block type `mermaid` is already one of the 9 supported SectionBlock types (proven by ReferenceDocShowcase). | | Generated guide supersedes manual only at quality parity | The manual `docs/SESSION-GUIDES.md` is retained in the repository until the generated equivalent matches or exceeds its quality across all content dimensions: completeness (all checklists present), accuracy (all FSM states current), visual clarity (decision trees render correctly), and usability (verified by comparison audit). The SessionGuidesModuleSource invariant ("not deleted, shortened, or replaced with a redirect") is respected during the transition period. The quality comparison deliverable produces an explicit audit document recording which sections have parity and which gaps remain. Only after the audit confirms full parity is the manual file replaced with a pointer to the generated output. | SESSION-GUIDES.md is cited in the SessionGuidesModuleSource spec as "the authoritative public human reference" serving developers on libar.dev. Replacing it prematurely with a generated equivalent that lacks checklists, has formatting issues, or omits edge cases would degrade the developer experience. The quality-gated approach ensures the generated version earns its place as the replacement by demonstrating equivalent or better quality, not merely by existing. This is the same principle applied by DocsConsolidationStrategy: "Manual docs retain editorial and tutorial content" until generation quality is sufficient. | ### Process Api Hybrid Generation -| Rule | Invariant | Rationale | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/PROCESS-API-REFERENCE.md` are generated from this schema by a standalone `ProcessApiReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/process-api.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from MasterDataset (annotation-derived data), not static constants (ADR-006). | -| Narrative prose sections remain manual | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | -| Standalone generator respects ADR-006 single read model | The `ProcessApiReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into MasterDataset or consume MasterDataset for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes MasterDataset as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through MasterDataset would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/PROCESS-API-REFERENCE.md` are generated from this schema by a standalone `ProcessApiReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/process-api.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). | +| Narrative prose sections remain manual | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | +| Standalone generator respects ADR-006 single read model | The `ProcessApiReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | ### Publishing Relocation @@ -931,7 +931,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | Rule | Invariant | Rationale | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scoped diagrams are generated from diagramScopes config | Diagram content is determined exclusively by diagramScopes filters (archContext, include, archLayer, patterns), and filters compose via OR — a pattern matching any single filter appears in the diagram. | Without filter-driven scoping, diagrams would include all patterns regardless of relevance, producing unreadable visualizations that obscure architectural boundaries. | -| Hardcoded diagram sources render deterministic output | Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content. | Domain diagrams such as pipeline and MasterDataset fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. | +| Hardcoded diagram sources render deterministic output | Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content. | Domain diagrams such as pipeline and PatternGraph fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. | | Multiple diagram scopes produce multiple mermaid blocks | Each entry in the diagramScopes array produces an independent Mermaid block with its own title and direction. | Product areas require multiple architectural views (e.g., system overview and data flow) from a single configuration. | ### Reference Codec Diagram Type Testing @@ -948,7 +948,7 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; | Deep behavior rendering replaces shallow truncation | At standard and detailed levels, behavior sections render full rule descriptions with parsed invariant, rationale, and verified-by content. At summary level, the 120-character truncation is preserved for compact output. Behavior rendering reuses parseBusinessRuleAnnotations from the convention extractor rather than reimplementing structured content parsing. | The current 120-character truncation discards invariants, rationale, and verified-by content that is already extracted and available in BusinessRule.description. Reference documents need the full rule content to serve as authoritative documentation. The convention extractor already parses this structured content via parseBusinessRuleAnnotations -- the behavior builder should delegate to the same function. | | Shape sections include JSDoc prose and property documentation | At standard level, shape code blocks are preceded by JSDoc prose when available. At detailed level, interface shapes additionally render a property documentation table. At summary level, only the type-kind table appears. Shapes without JSDoc render code blocks without preceding paragraph. | JSDoc on shapes contains design rationale and usage guidance that is already extracted by the shape extractor. Gating it behind detailed level wastes the data at the most common detail level (standard). The fix is a single condition change: reference.ts line 342 from detailLevel === 'detailed' to detailLevel !== 'summary'. | | Diagram scope supports archLayer filtering and multiple diagram types | DiagramScope gains optional archLayer and diagramType fields. The archLayer filter selects patterns by their architectural layer (domain, application, infrastructure) and composes with archContext and archView via OR logic, consistent with existing filter dimensions. The diagramType field controls Mermaid output format: graph (default), sequenceDiagram, stateDiagram-v2, C4Context, classDiagram. Each diagram type has its own node and edge syntax appropriate to the Mermaid specification. | Layer-based views are fundamental to layered architecture documentation -- a developer reviewing the domain layer wants only deciders and value objects, not infrastructure adapters. Multiple diagram types unlock event flow documentation (sequence), FSM visualization (state), architecture overview (C4), and type hierarchy views (class) that flowcharts cannot express naturally. | -| Every renderable block type appears in the showcase document | The generated REFERENCE-SAMPLE.md at detailed level must contain at least one instance of each of the 9 block types: heading, paragraph, separator, table, list, code, mermaid, collapsible, link-out. At summary level, progressive disclosure blocks (collapsible, link-out) are omitted for compact output. | The sample document is the integration test for the reference codec. If any block type is missing, there is no automated verification that the codec can produce it. Coverage of all 9 types validates the full rendering pipeline from MasterDataset through codec through renderer. | +| Every renderable block type appears in the showcase document | The generated REFERENCE-SAMPLE.md at detailed level must contain at least one instance of each of the 9 block types: heading, paragraph, separator, table, list, code, mermaid, collapsible, link-out. At summary level, progressive disclosure blocks (collapsible, link-out) are omitted for compact output. | The sample document is the integration test for the reference codec. If any block type is missing, there is no automated verification that the codec can produce it. Coverage of all 9 types validates the full rendering pipeline from PatternGraph through codec through renderer. | | Edge labels and custom node shapes enrich diagram readability | Relationship edges in scoped diagrams display labels describing the relationship semantics (uses, dependsOn, implements, extends). Edge labels are enabled by default and can be disabled via a showEdgeLabels option for compact diagrams. Node shapes vary by archRole value -- services use rounded rectangles, bounded contexts use subgraphs, projections use cylinders, and sagas use hexagons. | Unlabeled edges are ambiguous -- a reader seeing a solid arrow cannot distinguish "uses" from "implements" without consulting an edge style legend. Custom node shapes leverage Mermaid's shape vocabulary to make archRole visually distinguishable without color reliance, improving accessibility. | | Extraction pipeline surfaces complete API documentation | ExportInfo.signature shows full function parameter types and return type instead of the placeholder value. JSDoc param, returns, and throws tags are extracted and stored on ExtractedShape. Property-level JSDoc preserves full multi-line content without first-line truncation. Auto-shape discovery mode extracts all exported types from files matching source-selector globs globs without requiring explicit extract-shapes annotations. | Function signatures are the most valuable API surface -- they show what a pattern exports without source navigation. The ExportInfo.signature field already exists in the schema but holds a lossy placeholder. The fix is approximately 15 lines in ast-parser.ts: threading sourceCode into extractFromDeclaration and slicing parameter ranges. Auto-shape discovery eliminates manual annotation burden for files that match source-selector globs. | | Infrastructure enables flexible document composition and AI-optimized output | CompositeCodec assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. The modular claude-md renderer produces token-efficient output using section markers optimized for LLM consumption. The Gherkin tag extractor uses TagRegistry metadata instead of hardcoded if/else branches, making new tag addition a zero-code-change operation. Convention content can be extracted from TypeScript JSDoc blocks containing structured Invariant/Rationale annotations, not only from Gherkin Rule blocks. | CompositeCodec enables referenceDocConfigs to include content from any codec, not just the current 4 sources. The modular claude-md renderer unifies two formatting paths (codec-based markdown vs hand-written markers in context-formatter.ts). Data-driven tag extraction cuts the maintenance burden of the 40-branch if/else in gherkin-ast-parser.ts roughly in half. TypeScript convention extraction enables self-documenting business rules in implementation files alongside their code. | @@ -1014,10 +1014,10 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Requirements Adr Codec Testing -| Rule | Invariant | Rationale | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| RequirementsDocumentCodec generates PRD-style documentation from patterns | RequirementsDocumentCodec transforms MasterDataset patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. | Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. | -| AdrDocumentCodec documents architecture decisions | AdrDocumentCodec transforms MasterDataset ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. | Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned. | +| Rule | Invariant | Rationale | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| RequirementsDocumentCodec generates PRD-style documentation from patterns | RequirementsDocumentCodec transforms PatternGraph patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. | Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. | +| AdrDocumentCodec documents architecture decisions | AdrDocumentCodec transforms PatternGraph ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. | Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned. | ### Rich Content Helpers Testing @@ -1148,23 +1148,23 @@ function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset; ### Traceability Generator -| Rule | Invariant | Rationale | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Cross-references Verified by annotations against actual scenarios | Every `verifiedBy` string extracted from a Rule description is matched against scenario names in the MasterDataset. The traceability matrix shows each Rule with its verification status: verified (all references resolve), partially verified (some resolve), or unverified (none resolve or no annotation). | `parseBusinessRuleAnnotations()` already extracts `verifiedBy` arrays from Rule descriptions. Without cross-referencing against actual scenario names, the traceability report cannot distinguish between claimed and actual test coverage. A dangling reference (scenario name that does not exist) is worse than no annotation because it creates false confidence. | -| Detects orphan scenarios and unverified rules | Orphan scenarios (acceptance-criteria scenarios not referenced by any Rule's Verified by annotation) and unverified rules (Rules without a Verified by annotation or with zero matched scenarios) are listed in dedicated sections of the traceability output. | Coverage gaps indicate either missing traceability annotations or actual missing test coverage. Orphan scenarios may be valuable tests that lack traceability links, or dead tests that should be removed. Unverified rules are business constraints with no demonstrated test coverage. | -| Traceability output is wired into the docs pipeline | The TraceabilityCodec output is generated as part of `pnpm docs:all` via a `docs:traceability` npm script backed by a ReferenceDocConfig entry in `architect.config.ts`. The output file lands in `docs-live/TRACEABILITY.md`. | The TraceabilityCodec is registered in the CodecRegistry but not wired into `architect.config.ts` or `package.json`. Without config wiring, the codec is only usable programmatically or via tests. Adding it to the docs pipeline makes traceability output a first-class generated artifact alongside CHANGELOG.md, OVERVIEW.md, and other reporting codecs. | +| Rule | Invariant | Rationale | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Cross-references Verified by annotations against actual scenarios | Every `verifiedBy` string extracted from a Rule description is matched against scenario names in the PatternGraph. The traceability matrix shows each Rule with its verification status: verified (all references resolve), partially verified (some resolve), or unverified (none resolve or no annotation). | `parseBusinessRuleAnnotations()` already extracts `verifiedBy` arrays from Rule descriptions. Without cross-referencing against actual scenario names, the traceability report cannot distinguish between claimed and actual test coverage. A dangling reference (scenario name that does not exist) is worse than no annotation because it creates false confidence. | +| Detects orphan scenarios and unverified rules | Orphan scenarios (acceptance-criteria scenarios not referenced by any Rule's Verified by annotation) and unverified rules (Rules without a Verified by annotation or with zero matched scenarios) are listed in dedicated sections of the traceability output. | Coverage gaps indicate either missing traceability annotations or actual missing test coverage. Orphan scenarios may be valuable tests that lack traceability links, or dead tests that should be removed. Unverified rules are business constraints with no demonstrated test coverage. | +| Traceability output is wired into the docs pipeline | The TraceabilityCodec output is generated as part of `pnpm docs:all` via a `docs:traceability` npm script backed by a ReferenceDocConfig entry in `architect.config.ts`. The output file lands in `docs-live/TRACEABILITY.md`. | The TraceabilityCodec is registered in the CodecRegistry but not wired into `architect.config.ts` or `package.json`. Without config wiring, the codec is only usable programmatically or via tests. Adding it to the docs pipeline makes traceability output a first-class generated artifact alongside CHANGELOG.md, OVERVIEW.md, and other reporting codecs. | ### Transform Dataset Testing | Rule | Invariant | Rationale | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Empty dataset produces valid zero-state views | An empty input produces a MasterDataset with all counts at zero and no groupings. | Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs. | +| Empty dataset produces valid zero-state views | An empty input produces a PatternGraph with all counts at zero and no groupings. | Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs. | | Status and phase grouping creates navigable views | Patterns are grouped by canonical status and sorted by phase number, with per-phase status counts computed. | Generators need O(1) access to status-filtered and phase-ordered views without recomputing on each render pass. | | Quarter and category grouping organizes by timeline and domain | Patterns are grouped by quarter and category, with only patterns bearing the relevant metadata included in each view. | Timeline and domain views must exclude patterns without the relevant metadata to prevent misleading counts and empty groupings in generated documentation. | | Source grouping separates TypeScript and Gherkin origins | Patterns are partitioned by source file type, and patterns with phase metadata appear in the roadmap view. | Codecs that render TypeScript-specific or Gherkin-specific views depend on pre-partitioned sources; mixing sources would produce incorrect per-origin statistics and broken cross-references. | | Relationship index builds bidirectional dependency graph | The relationship index contains forward and reverse lookups, with reverse lookups merged and deduplicated against explicit annotations. | Bidirectional navigation is required for dependency tree queries without O(n) scans per lookup. | | Completion tracking computes project progress | Completion percentage is rounded to the nearest integer, and fully-completed requires all patterns in completed status with a non-zero total. | Inconsistent rounding or a false-positive fully-completed signal on an empty dataset would misrepresent project health in dashboards and generated progress reports. | -| Workflow integration conditionally includes delivery process data | The workflow is included in the MasterDataset only when provided, and phase names are resolved from the workflow configuration. | Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation. | +| Workflow integration conditionally includes delivery process data | The workflow is included in the PatternGraph only when provided, and phase names are resolved from the workflow configuration. | Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation. | ### Universal Doc Generator Robustness diff --git a/docs-live/product-areas/PROCESS.md b/docs-live/product-areas/PROCESS.md index b7f0a9f2..99080207 100644 --- a/docs-live/product-areas/PROCESS.md +++ b/docs-live/product-areas/PROCESS.md @@ -295,7 +295,7 @@ graph LR | Tier 1 specs are ephemeral working documents | Tier 1 roadmap specs serve planning and delivery tracking. They are not the source of truth for pattern identity, invariants, or acceptance criteria. After completion, they may be archived. | Treating tier 1 specs as durable creates a maintenance burden — at scale only 39% maintain traceability, and duplicated Rules/Scenarios average 200-400 stale lines. | | Three durable artifact types | The delivery process produces three artifact types with long-term value. All other artifacts are projections or ephemeral. | Without a clear boundary between durable and ephemeral artifacts, teams maintain redundant documents that inevitably drift from the source of truth. | | Implements is UML Realization (many-to-one) | `@architect-implements` declares a realization relationship. Multiple files can implement the same pattern. One file can implement multiple patterns (CSV format). | Without many-to-one realization, cross-cutting patterns that span multiple files cannot be traced back to a single canonical definition. | -| Single-definition constraint | `@architect-pattern:X` may appear in exactly one file across the entire codebase. The `mergePatterns()` conflict check in `orchestrator.ts` correctly enforces this. | Duplicate pattern definitions cause merge conflicts in the MasterDataset and produce ambiguous ownership in generated documentation. | +| Single-definition constraint | `@architect-pattern:X` may appear in exactly one file across the entire codebase. The `mergePatterns()` conflict check in `orchestrator.ts` correctly enforces this. | Duplicate pattern definitions cause merge conflicts in the PatternGraph and produce ambiguous ownership in generated documentation. | | Reverse links preferred over forward links | `@architect-implements` (reverse: "I verify this pattern") is the primary traceability mechanism. `@architect-executable-specs` (forward: "my tests live here") is retained but not required. | Forward links in tier 1 specs go stale when specs are archived, while reverse links in test files are self-maintaining because the test cannot run without the implementation. | ### Cli Behavior Testing diff --git a/docs-live/product-areas/VALIDATION.md b/docs-live/product-areas/VALIDATION.md index e5909dde..51e7f4a6 100644 --- a/docs-live/product-areas/VALIDATION.md +++ b/docs-live/product-areas/VALIDATION.md @@ -1133,11 +1133,11 @@ const missingPatternName: LintRule; ### Validator Read Model Consolidation -| Rule | Invariant | Rationale | -| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Validator queries the read model for cross-source matching | Pattern identity resolution — including implements relationships in both directions — uses `MasterDataset.relationshipIndex` rather than ad-hoc name-equality maps built from raw scanner output. | The MasterDataset computes implementedBy reverse lookups in transform-dataset.ts (second pass, lines 488-546). The validator's current name-equality Map cannot resolve ShapeExtractor -> ShapeExtraction or DecisionDocGeneratorTesting -> DecisionDocGenerator because these are implements relationships, not name matches. | -| No lossy local types in the validator | The validator operates on `ExtractedPattern` from the MasterDataset, not a consumer-local DTO that discards fields. | GherkinPatternInfo keeps only name, phase, status, file, and deliverables — discarding uses, dependsOn, implementsPatterns, include, productArea, rules, and 20+ other fields. When the validator needs relationship data, it cannot access it through the lossy type. | -| Utility patterns without specs are not false positives | Internal utility patterns that have a `@architect-phase` but will never have a Gherkin spec should not carry phase metadata. Phase tags signal roadmap participation. | Five utility patterns (ContentDeduplicator, FileCache, WarningCollector, SourceMappingValidator, SourceMapper) have phase tags from the phase when they were built. They are infrastructure, not roadmap features. The validator correctly reports missing Gherkin for patterns with phases — the fix is removing the phase tag, not suppressing the warning. | +| Rule | Invariant | Rationale | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Validator queries the read model for cross-source matching | Pattern identity resolution — including implements relationships in both directions — uses `PatternGraph.relationshipIndex` rather than ad-hoc name-equality maps built from raw scanner output. | The PatternGraph computes implementedBy reverse lookups in transform-dataset.ts (second pass, lines 488-546). The validator's current name-equality Map cannot resolve ShapeExtractor -> ShapeExtraction or DecisionDocGeneratorTesting -> DecisionDocGenerator because these are implements relationships, not name matches. | +| No lossy local types in the validator | The validator operates on `ExtractedPattern` from the PatternGraph, not a consumer-local DTO that discards fields. | GherkinPatternInfo keeps only name, phase, status, file, and deliverables — discarding uses, dependsOn, implementsPatterns, include, productArea, rules, and 20+ other fields. When the validator needs relationship data, it cannot access it through the lossy type. | +| Utility patterns without specs are not false positives | Internal utility patterns that have a `@architect-phase` but will never have a Gherkin spec should not carry phase metadata. Phase tags signal roadmap participation. | Five utility patterns (ContentDeduplicator, FileCache, WarningCollector, SourceMappingValidator, SourceMapper) have phase tags from the phase when they were built. They are infrastructure, not roadmap features. The validator correctly reports missing Gherkin for patterns with phases — the fix is removing the phase tag, not suppressing the warning. | ### Workflow Config Schemas Validation diff --git a/docs-live/reference/ANNOTATION-REFERENCE.md b/docs-live/reference/ANNOTATION-REFERENCE.md index 8f308432..62a3996b 100644 --- a/docs-live/reference/ANNOTATION-REFERENCE.md +++ b/docs-live/reference/ANNOTATION-REFERENCE.md @@ -64,7 +64,7 @@ List specific declaration names in the file-level JSDoc: ```typescript /** * @architect - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema */ ``` @@ -103,7 +103,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i | Wrong (type alias) | Correct (schema constant) | | ---------------------------------------- | ----------------------------------------- | -| `@extract-shapes MasterDataset` | `@extract-shapes MasterDatasetSchema` | +| `@extract-shapes PatternGraph` | `@extract-shapes PatternGraphSchema` | | Shows: `z.infer` (unhelpful) | Shows: `z.object({...})` (full structure) | --- @@ -115,9 +115,9 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i ```typescript /** * @architect - * @architect-pattern MasterDataset + * @architect-pattern PatternGraph * @architect-status completed - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, PhaseGroupSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, PhaseGroupSchema */ ``` @@ -141,7 +141,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i * @architect-status completed * @architect-arch-context generator * @architect-arch-layer application - * @architect-extract-shapes transformToMasterDataset, RuntimeMasterDataset + * @architect-extract-shapes transformToPatternGraph, RuntimePatternGraph */ ``` diff --git a/docs-live/reference/ARCHITECTURE-CODECS.md b/docs-live/reference/ARCHITECTURE-CODECS.md index e12f379b..f229e17d 100644 --- a/docs-live/reference/ARCHITECTURE-CODECS.md +++ b/docs-live/reference/ARCHITECTURE-CODECS.md @@ -7,7 +7,7 @@ ## ValidationRulesCodec -Transforms MasterDataset into a RenderableDocument for Process Guard validation +Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. Generates VALIDATION-RULES.md and detail files (validation/\*.md). **Purpose:** Process Guard validation rules reference with FSM diagrams and protection level matrix. @@ -91,7 +91,7 @@ const doc = ValidationRulesCodec.decode(dataset); ## TaxonomyDocumentCodec -Transforms MasterDataset into a RenderableDocument for taxonomy reference output. +Transforms PatternGraph into a RenderableDocument for taxonomy reference output. Generates TAXONOMY.md and detail files (taxonomy/\*.md). **Purpose:** Taxonomy reference documentation with tag definitions, preset comparison, and format type reference. @@ -161,7 +161,7 @@ const doc = TaxonomyDocumentCodec.decode(dataset); ## RequirementsDocumentCodec -Transforms MasterDataset into RenderableDocument for PRD/requirements output. +Transforms PatternGraph into RenderableDocument for PRD/requirements output. Generates PRODUCT-REQUIREMENTS.md and detail files (requirements/\*.md). **Purpose:** Product requirements documentation grouped by product area or user role. @@ -302,7 +302,7 @@ const doc = codec.decode(dataset); ## PrChangesCodec -Transforms MasterDataset into RenderableDocument for PR-scoped output. +Transforms PatternGraph into RenderableDocument for PR-scoped output. Filters patterns by changed files and/or release version tags. **Purpose:** PR-scoped view filtered by changed files or release version. @@ -389,7 +389,7 @@ const doc = codec.decode(dataset); ## PatternsDocumentCodec -Transforms MasterDataset into a RenderableDocument for pattern registry output. +Transforms PatternGraph into a RenderableDocument for pattern registry output. Generates PATTERNS.md and category detail files (patterns/\*.md). **Purpose:** Pattern registry with category-based organization. @@ -429,7 +429,7 @@ const doc = PatternsDocumentCodec.decode(dataset); ## IndexCodec -**Purpose:** Navigation hub composing editorial preamble with MasterDataset statistics. +**Purpose:** Navigation hub composing editorial preamble with PatternGraph statistics. **Output Files:** `INDEX.md` (single page, no detail files) @@ -454,7 +454,7 @@ const doc = PatternsDocumentCodec.decode(dataset); ## DesignReviewCodec -Transforms MasterDataset into a RenderableDocument containing design review +Transforms PatternGraph into a RenderableDocument containing design review artifacts: sequence diagrams, component diagrams, type definition tables, and design question templates. @@ -509,7 +509,7 @@ const doc = composeDocuments([docA, docB], { title: 'Combined' }); ## ClaudeModuleCodec -Transforms MasterDataset into RenderableDocuments for CLAUDE.md module generation. +Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. Filters patterns with `claudeModule` tags and generates compact markdown modules suitable for the `_claude-md/` directory structure. @@ -537,7 +537,7 @@ const doc = codec.decode(dataset); ## BusinessRulesCodec -Transforms MasterDataset into a RenderableDocument for business rules output. +Transforms PatternGraph into a RenderableDocument for business rules output. Generates BUSINESS-RULES.md organized by product area, phase, and feature. **Purpose:** Business rules documentation organized by product area, phase, and feature. Extracts domain constraints from Gherkin Rule: blocks. @@ -592,7 +592,7 @@ const doc = codec.decode(dataset); ## ArchitectureDocumentCodec -Transforms MasterDataset into a RenderableDocument containing +Transforms PatternGraph into a RenderableDocument containing architecture diagrams (Mermaid) generated from source annotations. **Purpose:** Architecture diagrams (Mermaid) generated from source annotations. Supports component and layered views. @@ -637,7 +637,7 @@ const doc = ArchitectureDocumentCodec.decode(dataset); ## AdrDocumentCodec -Transforms MasterDataset into RenderableDocument for Architecture Decision Records. +Transforms PatternGraph into RenderableDocument for Architecture Decision Records. Extracts ADRs from patterns with `@architect-adr` tags. **Purpose:** Architecture Decision Records extracted from patterns with @architect-adr tags. diff --git a/docs-live/reference/ARCHITECTURE-TYPES.md b/docs-live/reference/ARCHITECTURE-TYPES.md index dda1be85..c31dfc6d 100644 --- a/docs-live/reference/ARCHITECTURE-TYPES.md +++ b/docs-live/reference/ARCHITECTURE-TYPES.md @@ -7,7 +7,7 @@ ## API Types -### MasterDatasetSchema (const) +### PatternGraphSchema (const) ```typescript /** @@ -20,7 +20,7 @@ ``` ```typescript -MasterDatasetSchema = z.object({ +PatternGraphSchema = z.object({ // ───────────────────────────────────────────────────────────────────────── // Raw Data // ───────────────────────────────────────────────────────────────────────── @@ -244,13 +244,13 @@ RelationshipEntrySchema = z.object({ }); ``` -### RuntimeMasterDataset (interface) +### RuntimePatternGraph (interface) ```typescript /** - * Runtime MasterDataset with optional workflow + * Runtime PatternGraph with optional workflow * - * Extends the Zod-compatible MasterDataset with workflow reference. + * Extends the Zod-compatible PatternGraph with workflow reference. * LoadedWorkflow contains Maps which aren't JSON-serializable, * so it's kept separate from the Zod schema. * @@ -258,7 +258,7 @@ RelationshipEntrySchema = z.object({ ``` ```typescript -interface RuntimeMasterDataset extends MasterDataset { +interface RuntimePatternGraph extends PatternGraph { /** Optional workflow configuration (not serializable) */ readonly workflow?: LoadedWorkflow; } @@ -304,7 +304,7 @@ interface RawDataset { ```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. @@ -349,7 +349,7 @@ interface PipelineOptions { ```typescript interface PipelineResult { - readonly dataset: RuntimeMasterDataset; + readonly dataset: RuntimePatternGraph; readonly validation: ValidationSummary; readonly warnings: readonly PipelineWarning[]; readonly scanMetadata: ScanMetadata; @@ -366,11 +366,11 @@ interface PipelineResult { --- -## Steps 1-8 via buildMasterDataset() +## Steps 1-8 via buildPatternGraph() Steps 1-8 (config load, TypeScript/Gherkin scan + extraction, merge, hierarchy -derivation, workflow load, and `transformToMasterDataset`) are delegated to -`buildMasterDataset()`. +derivation, workflow load, and `transformToPatternGraph`) are delegated to +`buildPatternGraph()`. --- @@ -390,7 +390,7 @@ policy, and persisted file writes). ## Shared Pipeline Factory Responsibilities -**Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` without process-level side effects. +**Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns `Result` 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. @@ -400,7 +400,7 @@ policy, and persisted file writes). 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. --- @@ -413,19 +413,19 @@ 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 --- -## MasterDataset View Fan-out +## PatternGraph View Fan-out -Pre-computed view fan-out from MasterDataset (single-pass transform): +Pre-computed view fan-out from PatternGraph (single-pass transform): ```mermaid graph TB - MD[MasterDataset] + MD[PatternGraph] MD --> byStatus["byStatus
(completed / active / planned)"] MD --> byPhase["byPhase
(sorted, with counts)"] MD --> byQuarter["byQuarter
(keyed by Q-YYYY)"] diff --git a/docs-live/reference/PROCESS-API-RECIPES.md b/docs-live/reference/PROCESS-API-RECIPES.md index f1e49869..9252b116 100644 --- a/docs-live/reference/PROCESS-API-RECIPES.md +++ b/docs-live/reference/PROCESS-API-RECIPES.md @@ -35,7 +35,7 @@ Example `overview` output: 318 patterns (224 completed, 47 active, 47 planned) = 70% === ACTIVE PHASES === -Phase 24: ProcessStateAPIRelationshipQueries (1 active) +Phase 24: PatternGraphAPIRelationshipQueries (1 active) Phase 25: DataAPIStubIntegration (1 active) === BLOCKING === @@ -79,7 +79,7 @@ Example output: 318 patterns (224 completed, 47 active, 47 planned) = 70% === ACTIVE PHASES === -Phase 24: ProcessStateAPIRelationshipQueries (1 active) +Phase 24: PatternGraphAPIRelationshipQueries (1 active) Phase 25: DataAPIStubIntegration (1 active) === BLOCKING === @@ -130,20 +130,20 @@ Example output: Status: active | Category: pattern ## ContextAssembler — Session-Oriented Context Bundle Builder -Pure function composition over MasterDataset. +Pure function composition over PatternGraph. File: src/api/context-assembler.ts === DEPENDENCIES === -[active] ProcessStateAPI (implementation) src/api/process-state.ts -[completed] MasterDataset (implementation) src/validation-schemas/master-dataset.ts +[active] PatternGraphAPI (implementation) src/api/pattern-graph-api.ts +[completed] PatternGraph (implementation) src/validation-schemas/pattern-graph.ts === CONSUMERS === ContextFormatterImpl (active) ProcessAPICLIImpl (active) === ARCHITECTURE (context: api) === -MasterDataset (completed, read-model) -ProcessStateAPI (active, service) +PatternGraph (completed, read-model) +PatternGraphAPI (active, service) ... ``` diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index c5f3e021..4860aea7 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -226,8 +226,8 @@ sequenceDiagram Orchestrator ->> Extractor: extractFromGherkin(docs) Extractor -->> Orchestrator: ExtractedPattern[] Orchestrator ->> Orchestrator: mergePatterns(ts, gherkin) - Orchestrator ->> Transformer: transformToMasterDataset(patterns) - Transformer -->> Orchestrator: MasterDataset + Orchestrator ->> Transformer: transformToPatternGraph(patterns) + Transformer -->> Orchestrator: PatternGraph Orchestrator ->> Codec: codec.decode(dataset) Codec -->> Orchestrator: RenderableDocument Orchestrator ->> Renderer: render(document) @@ -255,16 +255,6 @@ classDiagram class Documentation_Generation_Orchestrator { <> } - class ProcessApiReferenceGenerator { - } - class DesignReviewGenerator { - <> - } - class DecisionDocGenerator { - <> - } - class CliRecipeGenerator { - } class TransformTypes { } class TransformDataset { @@ -279,7 +269,17 @@ classDiagram class ContextInferenceImpl { +ContextInferenceRule interface } - class MasterDataset + class ProcessApiReferenceGenerator { + } + class DesignReviewGenerator { + <> + } + class DecisionDocGenerator { + <> + } + class CliRecipeGenerator { + } + class PatternGraph class Pattern_Scanner class GherkinASTParser class ShapeExtractor @@ -297,21 +297,21 @@ classDiagram SourceMapper ..> ShapeExtractor : depends on SourceMapper ..> GherkinASTParser : depends on Documentation_Generation_Orchestrator ..> Pattern_Scanner : uses + TransformTypes ..> PatternGraph : uses + TransformDataset ..> PatternGraph : uses + TransformDataset ..|> PatternRelationshipModel : implements + SequenceTransformUtils ..> PatternGraph : uses + SequenceTransformUtils ..|> DesignReviewGeneration : implements + RelationshipResolver ..> PatternHelpers : uses + ContextInferenceImpl ..|> ContextInference : implements ProcessApiReferenceGenerator ..|> ProcessApiHybridGeneration : implements DesignReviewGenerator ..> DesignReviewCodec : uses - DesignReviewGenerator ..> MasterDataset : uses + DesignReviewGenerator ..> PatternGraph : uses DesignReviewGenerator ..|> DesignReviewGeneration : implements DecisionDocGenerator ..> DecisionDocCodec : depends on DecisionDocGenerator ..> SourceMapper : depends on CliRecipeGenerator ..|> CliRecipeCodec : implements - TransformTypes ..> MasterDataset : uses - TransformDataset ..> MasterDataset : uses - TransformDataset ..|> PatternRelationshipModel : implements - SequenceTransformUtils ..> MasterDataset : uses - SequenceTransformUtils ..|> DesignReviewGeneration : implements - RelationshipResolver ..> PatternHelpers : uses - ContextInferenceImpl ..|> ContextInference : implements - DesignReviewCodec ..> MasterDataset : uses + DesignReviewCodec ..> PatternGraph : uses DesignReviewCodec ..|> DesignReviewGeneration : implements CliRecipeCodec ..> ProcessApiHybridGeneration : depends on ``` @@ -388,7 +388,7 @@ Scoped architecture diagram showing component relationships: ```mermaid graph LR subgraph api["Api"] - MasterDataset[/"MasterDataset"/] + PatternGraph[/"PatternGraph"/] PatternHelpers["PatternHelpers"] ArchQueriesImpl("ArchQueriesImpl") end @@ -411,7 +411,7 @@ graph LR FSMStates[/"FSMStates"/] end subgraph related["Related"] - ProcessStateAPI["ProcessStateAPI"]:::neighbor + PatternGraphAPI["PatternGraphAPI"]:::neighbor TypeScriptTaxonomyImplementation["TypeScriptTaxonomyImplementation"]:::neighbor ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor ProceduralGuideCodec["ProceduralGuideCodec"]:::neighbor @@ -421,18 +421,18 @@ graph LR end TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec + CLISchema ..->|implements| ProcessApiHybridGeneration ProjectConfigTypes -->|uses| ConfigurationTypes ProjectConfigTypes -->|uses| ConfigurationPresets ConfigurationPresets -->|uses| ConfigurationTypes PatternHelpers ..->|implements| DataAPIOutputShaping - ArchQueriesImpl -->|uses| ProcessStateAPI - ArchQueriesImpl -->|uses| MasterDataset + ArchQueriesImpl -->|uses| PatternGraphAPI + ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries - CLISchema ..->|implements| ProcessApiHybridGeneration FSMTransitions ..->|implements| PhaseStateMachineValidation FSMStates ..->|implements| PhaseStateMachineValidation - ProcessStateAPI -->|uses| MasterDataset - ProcessStateAPI ..->|implements| PhaseStateMachineValidation + PatternGraphAPI -->|uses| PatternGraph + PatternGraphAPI ..->|implements| PhaseStateMachineValidation DataAPIArchitectureQueries -.->|depends on| DataAPIOutputShaping classDef neighbor stroke-dasharray: 5 5 ``` @@ -591,7 +591,7 @@ Validation happens later at load time via Zod schema in `loadProjectConfig()`. **Context:** The documentation generator needs to transform structured pattern data -(MasterDataset) into markdown files. The initial approach used direct +(PatternGraph) into markdown files. The initial approach used direct string concatenation in generator functions, mixing data selection, formatting logic, and output assembly in a single pass. This made generators hard to test, difficult to compose, and impossible to @@ -600,7 +600,7 @@ AI context). **Decision:** Adopt a codec architecture inspired by serialization codecs (encode/decode). -Each document type has a codec that decodes a MasterDataset into a +Each document type has a codec that decodes a PatternGraph into a RenderableDocument — an intermediate representation of sections, headings, tables, paragraphs, and code blocks. A separate renderer transforms the RenderableDocument into markdown. This separates data selection (what to @@ -627,15 +627,15 @@ include) from formatting (how it looks) from serialization (markdown syntax). #### Codecs implement a decode-only contract -**Invariant:** Every codec is a pure function that accepts a MasterDataset and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. +**Invariant:** Every codec is a pure function that accepts a PatternGraph and returns a RenderableDocument. Codecs do not perform side effects, do not write files, and do not access the filesystem. The codec contract is decode-only because the transformation is one-directional: structured data becomes a document, never the reverse. -**Rationale:** Pure functions are deterministic and trivially testable. For the same MasterDataset, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. +**Rationale:** Pure functions are deterministic and trivially testable. For the same PatternGraph, a codec always produces the same RenderableDocument. This makes snapshot testing reliable and enables codec output comparison across versions. **Codec call signature:** ```typescript interface DocumentCodec { - decode(dataset: MasterDataset): RenderableDocument; + decode(dataset: PatternGraph): RenderableDocument; } ``` diff --git a/docs-sources/annotation-guide.md b/docs-sources/annotation-guide.md index ee56da2e..325b11fb 100644 --- a/docs-sources/annotation-guide.md +++ b/docs-sources/annotation-guide.md @@ -57,7 +57,7 @@ List specific declaration names in the file-level JSDoc: ```typescript /** * @architect - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema */ ``` @@ -96,7 +96,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i | Wrong (type alias) | Correct (schema constant) | | ---------------------------------------- | ----------------------------------------- | -| `@extract-shapes MasterDataset` | `@extract-shapes MasterDatasetSchema` | +| `@extract-shapes PatternGraph` | `@extract-shapes PatternGraphSchema` | | Shows: `z.infer` (unhelpful) | Shows: `z.object({...})` (full structure) | --- @@ -108,9 +108,9 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i ```typescript /** * @architect - * @architect-pattern MasterDataset + * @architect-pattern PatternGraph * @architect-status completed - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, PhaseGroupSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, PhaseGroupSchema */ ``` @@ -134,7 +134,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i * @architect-status completed * @architect-arch-context generator * @architect-arch-layer application - * @architect-extract-shapes transformToMasterDataset, RuntimeMasterDataset + * @architect-extract-shapes transformToPatternGraph, RuntimePatternGraph */ ``` diff --git a/docs-sources/index-navigation.md b/docs-sources/index-navigation.md index bf49f554..3394a261 100644 --- a/docs-sources/index-navigation.md +++ b/docs-sources/index-navigation.md @@ -15,7 +15,7 @@ | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | | Learn annotation mechanics | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | | See codec patterns and options | [Architecture Codecs](reference/ARCHITECTURE-CODECS.md) | -| Understand MasterDataset types | [Architecture Types](reference/ARCHITECTURE-TYPES.md) | +| Understand PatternGraph types | [Architecture Types](reference/ARCHITECTURE-TYPES.md) | --- @@ -59,7 +59,7 @@ | Process API Recipes | AI/Devs | CLI workflow recipes and session guides | | Process Guard Reference | Team Leads | Pre-commit hooks, error codes, programmatic API | | Architecture Codecs | Developers | All codecs with factory patterns and options | -| Architecture Types | Developers | MasterDataset interface and type shapes | +| Architecture Types | Developers | PatternGraph interface and type shapes | --- @@ -67,11 +67,11 @@ **Delivery Process** -- A code-first documentation and workflow toolkit. Extracts patterns from annotated TypeScript and Gherkin sources, generates markdown documentation, and validates delivery workflow via pre-commit hooks. -**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the MasterDataset. +**Pattern** -- An annotated unit of work tracked by the delivery process. Each pattern has a status (roadmap, active, completed, deferred), belongs to a product area, and has deliverables. Patterns are the atomic unit of the PatternGraph. -**MasterDataset** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. +**PatternGraph** -- The single read model (ADR-006) containing all extracted patterns with pre-computed views (byProductArea, byPhase, byStatus, byCategory). All codecs and the Data API consume this dataset. -**Codec** -- A Zod-based transformer that decodes MasterDataset into a RenderableDocument. Each codec produces a specific document type. Codecs are pure functions with no I/O. +**Codec** -- A Zod-based transformer that decodes PatternGraph into a RenderableDocument. Each codec produces a specific document type. Codecs are pure functions with no I/O. **Dual-Source Architecture** -- Feature files own planning metadata (status, phase, dependencies). TypeScript files own implementation metadata (uses, used-by, category). This split prevents ownership conflicts. diff --git a/docs-sources/process-api-recipes.md b/docs-sources/process-api-recipes.md index b36d6753..75f1a74f 100644 --- a/docs-sources/process-api-recipes.md +++ b/docs-sources/process-api-recipes.md @@ -31,7 +31,7 @@ Example `overview` output: 318 patterns (224 completed, 47 active, 47 planned) = 70% === ACTIVE PHASES === -Phase 24: ProcessStateAPIRelationshipQueries (1 active) +Phase 24: PatternGraphAPIRelationshipQueries (1 active) Phase 25: DataAPIStubIntegration (1 active) === BLOCKING === diff --git a/docs/ANNOTATION-GUIDE.md b/docs/ANNOTATION-GUIDE.md index 809b3600..4045424e 100644 --- a/docs/ANNOTATION-GUIDE.md +++ b/docs/ANNOTATION-GUIDE.md @@ -78,7 +78,7 @@ List specific declaration names in the file-level JSDoc: ```typescript /** * @architect - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, RelationshipEntry + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, RelationshipEntry */ ``` @@ -120,7 +120,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i | Wrong (type alias) | Correct (schema constant) | | ---------------------------------------- | ----------------------------------------- | -| `@extract-shapes MasterDataset` | `@extract-shapes MasterDatasetSchema` | +| `@extract-shapes PatternGraph` | `@extract-shapes PatternGraphSchema` | | Shows: `z.infer` (unhelpful) | Shows: `z.object({...})` (full structure) | --- @@ -132,9 +132,9 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i ```typescript /** * @architect - * @architect-pattern MasterDataset + * @architect-pattern PatternGraph * @architect-status completed - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, PhaseGroupSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, PhaseGroupSchema */ ``` @@ -158,7 +158,7 @@ For Zod files, extract the **schema constant** (with `Schema` suffix), not the i * @architect-status completed * @architect-arch-context generator * @architect-arch-layer application - * @architect-extract-shapes transformToMasterDataset, RuntimeMasterDataset + * @architect-extract-shapes transformToPatternGraph, RuntimePatternGraph */ ``` diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 581ec310..e9caa55a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,14 +40,14 @@ The tag prefix is configurable via presets or custom configuration (see [Configu ### Key Design Principles -| Principle | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------ | -| **Single Source of Truth** | Code + .feature files are authoritative; docs are generated projections | -| **Single-Pass Transformation** | All derived views computed in O(n) time, not redundant O(n) per section | -| **Codec-Based Rendering** | Zod 4 codecs transform MasterDataset → RenderableDocument → Markdown | -| **Schema-First Validation** | Zod schemas define types; runtime validation at all boundaries | -| **Single Read Model** | MasterDataset is the sole read model for all consumers — codecs, validators, query API (ADR-006) | -| **Result Monad** | Explicit error handling via `Result` instead of exceptions | +| Principle | Description | +| ------------------------------ | ----------------------------------------------------------------------------------------------- | +| **Single Source of Truth** | Code + .feature files are authoritative; docs are generated projections | +| **Single-Pass Transformation** | All derived views computed in O(n) time, not redundant O(n) per section | +| **Codec-Based Rendering** | Zod 4 codecs transform PatternGraph → RenderableDocument → Markdown | +| **Schema-First Validation** | Zod schemas define types; runtime validation at all boundaries | +| **Single Read Model** | PatternGraph is the sole read model for all consumers — codecs, validators, query API (ADR-006) | +| **Result Monad** | Explicit error handling via `Result` instead of exceptions | ### Architecture Overview @@ -57,7 +57,7 @@ The tag prefix is configurable via presets or custom configuration (see [Configu ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ ┌─────────────┐ │ SCANNER │ → │ EXTRACTOR │ → │ TRANSFORMER │ → │ CODEC │ │ │ │ │ │ │ │ │ - │ TypeScript │ │ ExtractedP- │ │ MasterDataset │ │ Renderable │ + │ TypeScript │ │ ExtractedP- │ │ PatternGraph │ │ Renderable │ │ Gherkin │ │ attern[] │ │ (pre-computed │ │ Document │ │ Files │ │ │ │ views) │ │ → Markdown │ └─────────────┘ └─────────────┘ └─────────────────┘ └─────────────┘ @@ -94,7 +94,7 @@ export default defineConfig({ | **Scanner** | `regexBuilders.hasFileOptIn()` | Detects files with configured opt-in marker | | **Scanner** | `regexBuilders.directivePattern` | Matches tags with configured prefix | | **Extractor** | `registry.categories` | Maps tags to category names | -| **Transformer** | `registry` | Builds MasterDataset with category indexes | +| **Transformer** | `registry` | Builds PatternGraph with category indexes | ### Configuration Resolution @@ -141,7 +141,7 @@ defineConfig(userConfig) ## Four-Stage Pipeline -The pipeline has two entry points. The orchestrator (`src/generators/orchestrator.ts`) runs all 10 steps end-to-end for documentation generation. The shared pipeline factory `buildMasterDataset()` (`src/generators/pipeline/build-pipeline.ts`) runs steps 1-8 and returns a `Result` for CLI consumers like process-api and validate-patterns (see [Pipeline Factory](#pipeline-factory-adr-006)). +The pipeline has two entry points. The orchestrator (`src/generators/orchestrator.ts`) runs all 10 steps end-to-end for documentation generation. The shared pipeline factory `buildPatternGraph()` (`src/generators/pipeline/build-pipeline.ts`) runs steps 1-8 and returns a `Result` for CLI consumers like process-api and validate-patterns (see [Pipeline Factory](#pipeline-factory-adr-006)). ### Stage 1: Scanner @@ -216,14 +216,14 @@ After extraction, patterns from both sources are merged with conflict detection. ### Pipeline Factory (ADR-006) -ADR-006 established the **Single Read Model Architecture**: the MasterDataset is the sole read model for all consumers. The shared pipeline factory extracts the 8-step scan-extract-merge-transform pipeline into a reusable function. +ADR-006 established the **Single Read Model Architecture**: the PatternGraph is the sole read model for all consumers. The shared pipeline factory extracts the 8-step scan-extract-merge-transform pipeline into a reusable function. **Key File:** `src/generators/pipeline/build-pipeline.ts` **Signature:** ```typescript -function buildMasterDataset( +function buildPatternGraph( options: PipelineOptions ): Promise>; ``` @@ -246,7 +246,7 @@ function buildMasterDataset( | Field | Type | Description | | -------------- | ---------------------------- | ------------------------------------------ | -| `dataset` | `RuntimeMasterDataset` | The fully-computed read model | +| `dataset` | `RuntimePatternGraph` | The fully-computed read model | | `validation` | `ValidationSummary` | Schema validation results for all patterns | | `warnings` | `readonly PipelineWarning[]` | Structured non-fatal warnings | | `scanMetadata` | `ScanMetadata` | Aggregate scan counts for reporting | @@ -289,7 +289,7 @@ function buildMasterDataset( | Layer | May Import | Examples | | ---------------------- | ------------------------------------- | ----------------------------------------------------- | | Pipeline Orchestration | `scanner/`, `extractor/`, `pipeline/` | `orchestrator.ts`, pipeline setup in CLI entry points | -| Feature Consumption | `MasterDataset`, `relationshipIndex` | codecs, ProcessStateAPI, validators, query handlers | +| Feature Consumption | `PatternGraph`, `relationshipIndex` | codecs, PatternGraphAPI, validators, query handlers | **Named Anti-Patterns (ADR-006):** @@ -303,7 +303,7 @@ function buildMasterDataset( **Purpose:** Compute all derived views in a single O(n) pass. -**Key File:** `src/generators/pipeline/transform-dataset.ts:transformToMasterDataset()` +**Key File:** `src/generators/pipeline/transform-dataset.ts:transformToPatternGraph()` This is the **key innovation** of the unified pipeline. Instead of each section calling `.filter()` repeatedly: @@ -318,16 +318,16 @@ The transformer computes ALL views upfront: ```typescript // NEW: Single-pass transformation - O(n) total -const masterDataset = transformToMasterDataset({ patterns, tagRegistry, workflow }); +const patternGraph = transformToPatternGraph({ patterns, tagRegistry, workflow }); // Sections access pre-computed views - O(1) -const completed = masterDataset.byStatus.completed; -const phase3 = masterDataset.byPhase.find((p) => p.phaseNumber === 3); +const completed = patternGraph.byStatus.completed; +const phase3 = patternGraph.byPhase.find((p) => p.phaseNumber === 3); ``` ### Stage 4: Codec -**Purpose:** Transform MasterDataset into RenderableDocument, then render to markdown. +**Purpose:** Transform PatternGraph into RenderableDocument, then render to markdown. **Key Files:** @@ -336,7 +336,7 @@ const phase3 = masterDataset.byPhase.find((p) => p.phaseNumber === 3); ```typescript // Codec transforms to universal intermediate format -const doc = PatternsDocumentCodec.decode(masterDataset); +const doc = PatternsDocumentCodec.decode(patternGraph); // Renderer produces markdown files const files = renderDocumentWithFiles(doc, 'PATTERNS.md'); @@ -346,14 +346,14 @@ const files = renderDocumentWithFiles(doc, 'PATTERNS.md'); ## Unified Transformation Architecture -### MasterDataset Schema +### PatternGraph Schema -**Key File:** `src/validation-schemas/master-dataset.ts` +**Key File:** `src/validation-schemas/pattern-graph.ts` -The `MasterDataset` is the central data structure containing all pre-computed views: +The `PatternGraph` is the central data structure containing all pre-computed views: ```typescript -interface MasterDataset { +interface PatternGraph { // ─── Raw Data ─────────────────────────────────────────────────────────── patterns: ExtractedPattern[]; tagRegistry: TagRegistry; @@ -418,24 +418,24 @@ interface MasterDataset { } ``` -### RuntimeMasterDataset +### RuntimePatternGraph -The runtime type extends `MasterDataset` with non-serializable workflow: +The runtime type extends `PatternGraph` with non-serializable workflow: ```typescript // transform-dataset.ts:50-53 -interface RuntimeMasterDataset extends MasterDataset { +interface RuntimePatternGraph extends PatternGraph { readonly workflow?: LoadedWorkflow; // Contains Maps - not JSON-serializable } ``` ### Single-Pass Transformation -The `transformToMasterDataset()` function iterates over patterns exactly once, accumulating all views: +The `transformToPatternGraph()` function iterates over patterns exactly once, accumulating all views: ```typescript // transform-dataset.ts:98-235 (simplified) -export function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset { +export function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph { // Initialize accumulators const byStatus: StatusGroups = { completed: [], active: [], planned: [] }; const byPhaseMap = new Map(); @@ -487,14 +487,14 @@ export function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset The Architect package uses a codec-based architecture for document generation: ``` -MasterDataset → Codec.decode() → RenderableDocument ─┬→ renderToMarkdown → Markdown Files +PatternGraph → Codec.decode() → RenderableDocument ─┬→ renderToMarkdown → Markdown Files └→ renderToClaudeMdModule → Modular Claude.md ``` | Component | Description | | -------------------------- | --------------------------------------------------------------------------------- | -| **MasterDataset** | Aggregated view of all extracted patterns with indexes by category, phase, status | -| **Codec** | Zod 4 codec that transforms MasterDataset into RenderableDocument | +| **PatternGraph** | Aggregated view of all extracted patterns with indexes by category, phase, status | +| **Codec** | Zod 4 codec that transforms PatternGraph into RenderableDocument | | **RenderableDocument** | Universal intermediate format with typed section blocks | | **renderToMarkdown** | Domain-agnostic markdown renderer for human documentation | | **renderToClaudeMdModule** | Modular-claude-md renderer (H3-rooted headings, omits Mermaid/link-outs) | @@ -853,7 +853,7 @@ const doc = codec.decode(dataset); **Key Exports:** -- `createCompositeCodec(codecs, options)` — Factory that decodes each child codec against the same MasterDataset and composes their outputs +- `createCompositeCodec(codecs, options)` — Factory that decodes each child codec against the same PatternGraph and composes their outputs - `composeDocuments(documents, options)` — Pure document-level composition (concatenates sections, merges `additionalFiles` with last-wins semantics) **Options (CompositeCodecOptions):** @@ -1141,8 +1141,8 @@ Data-driven configuration for pattern categorization: │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────────────────┐│ -│ │ Step 8: Transform to MasterDataset (SINGLE PASS) ││ -│ │ transformToMasterDataset({ patterns, tagRegistry, workflow }) ││ +│ │ Step 8: Transform to PatternGraph (SINGLE PASS) ││ +│ │ transformToPatternGraph({ patterns, tagRegistry, workflow }) ││ │ │ ││ │ │ Computes: byStatus, byPhase, byQuarter, byCategory, bySourceType, ││ │ │ counts, phaseCount, categoryCount, relationshipIndex ││ @@ -1152,7 +1152,7 @@ Data-driven configuration for pattern categorization: │ ┌─────────────────────────────────────────────────────────────────────────────┐│ │ │ Step 9: Run Codecs ││ │ │ for each generator: ││ -│ │ doc = Codec.decode(masterDataset) ││ +│ │ doc = Codec.decode(patternGraph) ││ │ │ files = renderDocumentWithFiles(doc, outputPath) ││ │ └─────────────────────────────────────────────────────────────────────────────┘│ │ │ │ @@ -1167,10 +1167,10 @@ Data-driven configuration for pattern categorization: ### Pipeline Factory Entry Point (ADR-006) -Steps 1-8 are also available via `buildMasterDataset()` from `src/generators/pipeline/build-pipeline.ts`. The orchestrator adds Steps 9-10 (codec execution and file writing). +Steps 1-8 are also available via `buildPatternGraph()` from `src/generators/pipeline/build-pipeline.ts`. The orchestrator adds Steps 9-10 (codec execution and file writing). ``` -buildMasterDataset(options) +buildPatternGraph(options) │ ▼ Steps 1-8 (scan → extract → merge → transform) @@ -1189,11 +1189,11 @@ buildMasterDataset(options) └── Step 10: File writing → OutputFile[] ``` -### MasterDataset Views +### PatternGraph Views ``` ┌─────────────────────────────────────┐ - │ MasterDataset │ + │ PatternGraph │ │ │ │ patterns: ExtractedPattern[] │ │ tagRegistry: TagRegistry │ @@ -1242,7 +1242,7 @@ buildMasterDataset(options) ```` ┌─────────────────────────────┐ - │ MasterDataset │ + │ PatternGraph │ └──────────────┬──────────────┘ │ ┌──────────────────────────┼──────────────────────────┐ @@ -1403,7 +1403,7 @@ const currentCodec = createCurrentWorkCodec({ ### Direct Codec Usage ```typescript -import { createPatternsCodec, type MasterDataset } from '@libar-dev/architect'; +import { createPatternsCodec, type PatternGraph } from '@libar-dev/architect'; import { renderToMarkdown } from '@libar-dev/architect/renderable'; // Create custom codec @@ -1413,7 +1413,7 @@ const codec = createPatternsCodec({ }); // Transform dataset -const document = codec.decode(masterDataset); +const document = codec.decode(patternGraph); // Render to markdown const markdown = renderToMarkdown(document); @@ -1425,7 +1425,7 @@ const markdown = renderToMarkdown(document); import { generateDocument, type DocumentType } from '@libar-dev/architect/renderable'; // Generate with default options -const files = generateDocument('patterns', masterDataset); +const files = generateDocument('patterns', patternGraph); // files is OutputFile[] for (const file of files) { @@ -1461,7 +1461,7 @@ if (document.additionalFiles) { ```typescript import { z } from 'zod'; -import { MasterDatasetSchema, type MasterDataset } from '../validation-schemas/master-dataset'; +import { PatternGraphSchema, type PatternGraph } from '../validation-schemas/master-dataset'; import { type RenderableDocument, document, heading, paragraph } from '../renderable/schema'; import { RenderableDocumentOutputSchema } from '../renderable/codecs/shared-schema'; @@ -1474,8 +1474,8 @@ interface MyCodecOptions { export function createMyCodec(options?: MyCodecOptions) { const opts = { includeCustomSection: true, ...options }; - return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { - decode: (dataset: MasterDataset): RenderableDocument => { + return z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { + decode: (dataset: PatternGraph): RenderableDocument => { const sections = [ heading(2, 'Summary'), paragraph(`Total patterns: ${dataset.counts.total}`), @@ -1513,7 +1513,7 @@ class MyCustomGenerator implements DocumentGenerator { generate(patterns, context) { const codec = createMyCodec(); - const doc = codec.decode(context.masterDataset); + const doc = codec.decode(context.patternGraph); const files = renderDocumentWithFiles(doc, 'MY-CUSTOM.md'); return Promise.resolve({ files }); } @@ -1612,25 +1612,25 @@ filterQuarters: []; // All (default) ## Code References -| Component | File | Purpose | -| ------------------------ | --------------------------------------------------- | ---------------------------------------------- | -| MasterDataset Schema | `src/validation-schemas/master-dataset.ts` | Central data structure | -| transformToMasterDataset | `src/generators/pipeline/transform-dataset.ts` | Single-pass transformation | -| Document Codecs | `src/renderable/codecs/*.ts` | Zod 4 codec implementations | -| Reference Codec | `src/renderable/codecs/reference.ts` | Scoped reference documents | -| Composite Codec | `src/renderable/codecs/composite.ts` | Multi-codec assembly | -| Convention Extractor | `src/renderable/codecs/convention-extractor.ts` | Convention content extraction | -| Shape Matcher | `src/renderable/codecs/shape-matcher.ts` | Declaration-level filtering | -| Markdown Renderer | `src/renderable/render.ts` | Block → Markdown | -| Claude Context Renderer | `src/renderable/render.ts` | LLM-optimized rendering | -| Orchestrator | `src/generators/orchestrator.ts` | Pipeline coordination | -| TypeScript Scanner | `src/scanner/pattern-scanner.ts` | TS AST parsing | -| Gherkin Scanner | `src/scanner/gherkin-scanner.ts` | Feature file parsing | -| Pipeline Factory | `src/generators/pipeline/build-pipeline.ts` | Shared 8-step pipeline for CLI consumers | -| Business Rules Query | `src/api/rules-query.ts` | Rules domain query (from Gherkin Rule: blocks) | -| Business Rules Codec | `src/renderable/codecs/business-rules.ts` | Business rules from Gherkin Rule: blocks | -| Architecture Codec | `src/renderable/codecs/architecture.ts` | Architecture diagrams from annotations | -| Taxonomy Codec | `src/renderable/codecs/taxonomy.ts` | Taxonomy reference documentation | -| Validation Rules Codec | `src/renderable/codecs/validation-rules.ts` | Process Guard validation rules reference | -| Decision Doc Generator | `src/generators/built-in/decision-doc-generator.ts` | ADR/PDR decision documents | -| Shape Extractor | `src/extractor/shape-extractor.ts` | Shape extraction from TS | +| Component | File | Purpose | +| ----------------------- | --------------------------------------------------- | ---------------------------------------------- | +| PatternGraph Schema | `src/validation-schemas/pattern-graph.ts` | Central data structure | +| transformToPatternGraph | `src/generators/pipeline/transform-dataset.ts` | Single-pass transformation | +| Document Codecs | `src/renderable/codecs/*.ts` | Zod 4 codec implementations | +| Reference Codec | `src/renderable/codecs/reference.ts` | Scoped reference documents | +| Composite Codec | `src/renderable/codecs/composite.ts` | Multi-codec assembly | +| Convention Extractor | `src/renderable/codecs/convention-extractor.ts` | Convention content extraction | +| Shape Matcher | `src/renderable/codecs/shape-matcher.ts` | Declaration-level filtering | +| Markdown Renderer | `src/renderable/render.ts` | Block → Markdown | +| Claude Context Renderer | `src/renderable/render.ts` | LLM-optimized rendering | +| Orchestrator | `src/generators/orchestrator.ts` | Pipeline coordination | +| TypeScript Scanner | `src/scanner/pattern-scanner.ts` | TS AST parsing | +| Gherkin Scanner | `src/scanner/gherkin-scanner.ts` | Feature file parsing | +| Pipeline Factory | `src/generators/pipeline/build-pipeline.ts` | Shared 8-step pipeline for CLI consumers | +| Business Rules Query | `src/api/rules-query.ts` | Rules domain query (from Gherkin Rule: blocks) | +| Business Rules Codec | `src/renderable/codecs/business-rules.ts` | Business rules from Gherkin Rule: blocks | +| Architecture Codec | `src/renderable/codecs/architecture.ts` | Architecture diagrams from annotations | +| Taxonomy Codec | `src/renderable/codecs/taxonomy.ts` | Taxonomy reference documentation | +| Validation Rules Codec | `src/renderable/codecs/validation-rules.ts` | Process Guard validation rules reference | +| Decision Doc Generator | `src/generators/built-in/decision-doc-generator.ts` | ADR/PDR decision documents | +| Shape Extractor | `src/extractor/shape-extractor.ts` | Shape extraction from TS | diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 69e8aa44..b1816b6e 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -135,10 +135,10 @@ Full taxonomy for domain-driven architectures with 21 categories. * @architect-pattern TransformDataset * @architect-status completed * @architect-core - * @architect-uses MasterDataset, ExtractedPattern + * @architect-uses PatternGraph, ExtractedPattern * @architect-used-by Orchestrator */ -export function transformToMasterDataset(input: TransformInput): MasterDataset { ... } +export function transformToPatternGraph(input: TransformInput): PatternGraph { ... } ``` > **Category Reference:** Run `pnpm docs:taxonomy` for the complete list. See [TAXONOMY.md](./TAXONOMY.md) for concepts. diff --git a/docs/DOCS-GAP-ANALYSIS.md b/docs/DOCS-GAP-ANALYSIS.md index 0ba1dbb2..7d14342c 100644 --- a/docs/DOCS-GAP-ANALYSIS.md +++ b/docs/DOCS-GAP-ANALYSIS.md @@ -116,7 +116,7 @@ generated equivalents. Work packages in this gap analysis should map to its phas | `process-api-hybrid-generation.feature` | ProcessApiHybridGeneration | completed | 43 | CLI schema as single source for reference tables | | `claude-module-generation.feature` | ClaudeModuleGeneration | completed | 25 | Claude module tags + behavior spec sourcing | | `reference-doc-showcase.feature` | ReferenceDocShowcase | completed | 30 | All 9 content block types across 3 detail levels | -| `validator-read-model-consolidation.feature` | ValidatorReadModelConsolidation | completed | 100 | MasterDataset as single read model (ADR-006) | +| `validator-read-model-consolidation.feature` | ValidatorReadModelConsolidation | completed | 100 | PatternGraph as single read model (ADR-006) | **Query these specs:** `pnpm architect:query -- decisions DocsConsolidationStrategy` @@ -183,7 +183,7 @@ Step 5: Replace manual doc section with pointer to generated output | Tag Value | Used By | Produces | | ----------------------- | ---------------------- | ------------------------------------ | | `codec-registry` | ARCHITECTURE-CODECS.md | All 20 codecs with factory patterns | -| `pipeline-architecture` | ARCHITECTURE-TYPES.md | MasterDataset interface, shapes | +| `pipeline-architecture` | ARCHITECTURE-TYPES.md | PatternGraph interface, shapes | | `taxonomy-rules` | REFERENCE-SAMPLE.md | Tag rules + 6 diagram types showcase | ### What This Means for New Work @@ -739,7 +739,7 @@ ProceduralGuideCodec) have completed design sessions with findings and code stub - **CliRecipeCodec** creates a sibling `CliRecipeGenerator` to `ProcessApiReferenceGenerator`, both standalone `DocumentGenerator` implementations consuming `CLI_SCHEMA` directly. - **EnhancedIndexGeneration** creates a new `IndexCodec` registered in `CodecRegistry`, - composing MasterDataset-driven statistics with editorial preamble navigation content. + composing PatternGraph-driven statistics with editorial preamble navigation content. **Master spec status:** 11/15 deliverables complete. WP-2 (IndexCodec) implementation is complete but manual docs/ files are preserved as reference — Phase 1 (taxonomy diff --git a/docs/INDEX.md b/docs/INDEX.md index 6061da4e..a5fa9dfe 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -48,7 +48,7 @@ ### For Developers / AI -4. **[ARCHITECTURE.md](./ARCHITECTURE.md)** — Four-stage pipeline, codecs, MasterDataset +4. **[ARCHITECTURE.md](./ARCHITECTURE.md)** — Four-stage pipeline, codecs, PatternGraph 5. **[PROCESS-API.md](./PROCESS-API.md)** — Data API CLI query interface 6. **[SESSION-GUIDES.md](./SESSION-GUIDES.md)** — Planning/Design/Implementation workflows 7. **[GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md)** — Writing effective Gherkin specs @@ -117,22 +117,22 @@ ### ARCHITECTURE.md (Lines 1-1638) -| Section | Lines | Key Topics | -| -------------------------- | --------- | ----------------------------------------------------------------- | -| Executive Summary | 28-69 | What it does, key principles (incl. Single Read Model), overview | -| Configuration Architecture | 70-139 | Entry point, pipeline effects, resolution | -| Four-Stage Pipeline | 140-343 | Scanner → Extractor → Pipeline Factory → Transformer → Codec | -| Unified Transformation | 345-478 | MasterDataset schema (relationshipIndex + archIndex), single-pass | -| Codec Architecture | 481-527 | Concepts, block vocabulary, factory, 3 renderers | -| Available Codecs | 529-870 | All 20 codecs with options tables | -| Progressive Disclosure | 871-917 | Split logic, detail levels | -| Source Systems | 919-1024 | TypeScript scanner, Gherkin scanner | -| Key Design Patterns | 1026-1105 | Result monad, schema-first, tag registry | -| Data Flow Diagrams | 1107-1290 | Pipeline flow, factory entry point, MasterDataset views, codecs | -| Workflow Integration | 1292-1401 | Planning, implementing, release workflows | -| Programmatic Usage | 1403-1458 | Direct codec usage, generateDocument | -| Extending the System | 1460-1527 | Custom codec, custom generator | -| Quick Reference | 1529-1604 | Codec-to-generator mapping, CLI, filters | +| Section | Lines | Key Topics | +| -------------------------- | --------- | ---------------------------------------------------------------- | +| Executive Summary | 28-69 | What it does, key principles (incl. Single Read Model), overview | +| Configuration Architecture | 70-139 | Entry point, pipeline effects, resolution | +| Four-Stage Pipeline | 140-343 | Scanner → Extractor → Pipeline Factory → Transformer → Codec | +| Unified Transformation | 345-478 | PatternGraph schema (relationshipIndex + archIndex), single-pass | +| Codec Architecture | 481-527 | Concepts, block vocabulary, factory, 3 renderers | +| Available Codecs | 529-870 | All 20 codecs with options tables | +| Progressive Disclosure | 871-917 | Split logic, detail levels | +| Source Systems | 919-1024 | TypeScript scanner, Gherkin scanner | +| Key Design Patterns | 1026-1105 | Result monad, schema-first, tag registry | +| Data Flow Diagrams | 1107-1290 | Pipeline flow, factory entry point, PatternGraph views, codecs | +| Workflow Integration | 1292-1401 | Planning, implementing, release workflows | +| Programmatic Usage | 1403-1458 | Direct codec usage, generateDocument | +| Extending the System | 1460-1527 | Custom codec, custom generator | +| Quick Reference | 1529-1604 | Codec-to-generator mapping, CLI, filters | #### Available Codecs Reference diff --git a/docs/MCP-SETUP.md b/docs/MCP-SETUP.md index 64e498b3..3a0e29c1 100644 --- a/docs/MCP-SETUP.md +++ b/docs/MCP-SETUP.md @@ -1,6 +1,6 @@ # MCP Server Setup -> Architect MCP server exposes ProcessStateAPI as native Claude Code tools with sub-millisecond dispatch. +> Architect MCP server exposes PatternGraphAPI as native Claude Code tools with sub-millisecond dispatch. ## Quick Start @@ -78,8 +78,8 @@ Override config auto-detection for monorepo setups: The MCP server: 1. **Loads the pipeline once** — config detection, scanning, extraction, transformation (~1-2s) -2. **Keeps MasterDataset in memory** — all subsequent queries are O(1) lookups -3. **Exposes 25 tools** — each wrapping a ProcessStateAPI method or CLI subcommand +2. **Keeps PatternGraph in memory** — all subsequent queries are O(1) lookups +3. **Exposes 25 tools** — each wrapping a PatternGraphAPI method or CLI subcommand 4. **Optionally watches files** — auto-rebuilds on source changes (500ms debounce) ## Available Tools diff --git a/docs/METHODOLOGY.md b/docs/METHODOLOGY.md index 0dc19a09..2a3191a2 100644 --- a/docs/METHODOLOGY.md +++ b/docs/METHODOLOGY.md @@ -27,7 +27,7 @@ Event sourcing teaches us: **derive state, don't store it**. Apply this to docum - **Events** = Git commits (changes to annotated code) - **Projections** = Generated docs (PATTERNS.md, ROADMAP.md) -- **Read Model** = MasterDataset (consumed by codecs, validators, and Data API CLI) +- **Read Model** = PatternGraph (consumed by codecs, validators, and Data API CLI) When you run `architect-generate`, you're rebuilding read models from the event stream. The source annotations are always authoritative. diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index edba06e7..1a2166ad 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -298,7 +298,7 @@ npx validate-patterns \ ### Architecture Note (ADR-006) -Cross-source validation now consumes the `MasterDataset` via the shared pipeline factory (`buildMasterDataset()`) with `mergeConflictStrategy: 'concatenate'`. This enables implements-aware matching through `relationshipIndex.implementedBy` — the validator no longer re-derives cross-source relationships from raw scanner output. +Cross-source validation now consumes the `PatternGraph` via the shared pipeline factory (`buildPatternGraph()`) with `mergeConflictStrategy: 'concatenate'`. This enables implements-aware matching through `relationshipIndex.implementedBy` — the validator no longer re-derives cross-source relationships from raw scanner output. Raw scans are retained only for DoD and anti-pattern detection, which are stage-1 consumers that validate annotation syntax directly on scanned files (no relationship resolution needed). @@ -402,7 +402,7 @@ import { deriveProcessState, validateChanges } from '@libar-dev/architect/lint'; import { detectAntiPatterns, validateDoD } from '@libar-dev/architect/validation'; ``` -`validatePatterns()` now accepts a `RuntimeMasterDataset`. Build one via `buildMasterDataset()` from `@libar-dev/architect/generators`. +`validatePatterns()` now accepts a `RuntimePatternGraph`. Build one via `buildPatternGraph()` from `@libar-dev/architect/generators`. See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed API documentation. diff --git a/package.json b/package.json index d22e2d54..b9782750 100644 --- a/package.json +++ b/package.json @@ -162,7 +162,7 @@ "mermaid", "traceability", "dual-source", - "master-dataset", + "pattern-graph", "gherkin", "bdd", "typescript-annotations", diff --git a/src/api/arch-queries.ts b/src/api/arch-queries.ts index c85ff056..1c7d7dd0 100644 --- a/src/api/arch-queries.ts +++ b/src/api/arch-queries.ts @@ -3,7 +3,7 @@ * @architect-pattern ArchQueriesImpl * @architect-status active * @architect-implements DataAPIArchitectureQueries - * @architect-uses ProcessStateAPI, MasterDataset + * @architect-uses PatternGraphAPI, PatternGraph * @architect-used-by ProcessAPICLIImpl * @architect-arch-role service * @architect-arch-context api @@ -11,17 +11,17 @@ * * ## ArchQueries — Neighborhood, Comparison, Tags, Sources * - * Pure functions over MasterDataset for deep architecture exploration. + * Pure functions over PatternGraph for deep architecture exploration. * No I/O — all data comes from pre-computed views. * * **When to Use:** When exploring architecture structure (neighborhoods, comparisons, tags, sources) via the Data API CLI. */ import type { - MasterDataset, + PatternGraph, RelationshipEntry, ArchIndex, -} from '../validation-schemas/master-dataset.js'; +} from '../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; import type { NeighborEntry } from './types.js'; import { getPatternName, findPatternByName, getRelationships } from './pattern-helpers.js'; @@ -125,7 +125,7 @@ export interface SourceInventory { export function computeNeighborhood( name: string, - dataset: MasterDataset + dataset: PatternGraph ): NeighborhoodResult | undefined { const pattern = findPatternByName(dataset.patterns, name); if (pattern === undefined) return undefined; @@ -230,7 +230,7 @@ function findIntegrationPoints( export function compareContexts( ctx1: string, ctx2: string, - dataset: MasterDataset + dataset: PatternGraph ): ContextComparison | undefined { const archIndex: ArchIndex | undefined = dataset.archIndex; if (archIndex === undefined) return undefined; @@ -293,7 +293,7 @@ export function compareContexts( // aggregateTagUsage // --------------------------------------------------------------------------- -export function aggregateTagUsage(dataset: MasterDataset): TagUsageReport { +export function aggregateTagUsage(dataset: PatternGraph): TagUsageReport { const tagMap = new Map>(); function increment(tag: string, value: string): void { @@ -363,7 +363,7 @@ function deriveLocationPattern(files: readonly string[]): string { return prefix !== '' ? `${prefix}/**/*.${ext}` : `**/*.${ext}`; } -export function buildSourceInventory(dataset: MasterDataset): SourceInventory { +export function buildSourceInventory(dataset: PatternGraph): SourceInventory { const groupSets = new Map>(); for (const p of dataset.patterns) { @@ -410,7 +410,7 @@ export interface OrphanEntry { * A pattern is an orphan if it has no uses, usedBy, dependsOn, enables, * implementsPatterns, implementedBy, extendedBy, seeAlso, or extendsPattern. */ -export function findOrphanPatterns(dataset: MasterDataset): readonly OrphanEntry[] { +export function findOrphanPatterns(dataset: PatternGraph): readonly OrphanEntry[] { const index = dataset.relationshipIndex; if (index === undefined) return []; diff --git a/src/api/context-assembler.ts b/src/api/context-assembler.ts index 2b3d8153..7d4c8512 100644 --- a/src/api/context-assembler.ts +++ b/src/api/context-assembler.ts @@ -3,7 +3,7 @@ * @architect-pattern ContextAssemblerImpl * @architect-status active * @architect-implements DataAPIContextAssembly - * @architect-uses ProcessStateAPI, MasterDataset, PatternSummarizerImpl, FuzzyMatcherImpl, StubResolverImpl + * @architect-uses PatternGraphAPI, PatternGraph, PatternSummarizerImpl, FuzzyMatcherImpl, StubResolverImpl * @architect-used-by ProcessAPICLIImpl, ContextFormatterImpl * @architect-arch-role service * @architect-arch-context api @@ -11,18 +11,18 @@ * * ## ContextAssembler — Session-Oriented Context Bundle Builder * - * Pure function composition over MasterDataset. Reads from 5 pre-computed + * Pure function composition over PatternGraph. Reads from 5 pre-computed * views (patterns, relationshipIndex, archIndex, deliverables, FSM) and * assembles them into a ContextBundle tailored to the session type. * * The assembler does NOT format output. It produces structured data that * the ContextFormatter renders as plain text (see ADR-008). * - * **When to Use:** When building a session context bundle for a pattern — use this instead of manually querying MasterDataset views. + * **When to Use:** When building a session context bundle for a pattern — use this instead of manually querying PatternGraph views. */ -import type { ProcessStateAPI } from './process-state.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraphAPI } from './pattern-graph-api.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; import { VALID_PROCESS_STATUS_SET, @@ -187,7 +187,7 @@ export interface OverviewSummary { /** * Find a pattern by name or throw QueryApiError with a fuzzy suggestion. */ -function requirePattern(dataset: MasterDataset, name: string): ExtractedPattern { +function requirePattern(dataset: PatternGraph, name: string): ExtractedPattern { const pattern = findPatternByNameFromList(dataset.patterns, name); if (pattern !== undefined) return pattern; const allNames = allPatternNames(dataset); @@ -197,7 +197,7 @@ function requirePattern(dataset: MasterDataset, name: string): ExtractedPattern } function resolveDepEntry( - dataset: MasterDataset, + dataset: PatternGraph, depName: string, kind: 'planning' | 'implementation' ): DepEntry { @@ -221,7 +221,7 @@ function buildMetadata(pattern: ExtractedPattern): PatternContextMeta { }; } -function resolveStubRefs(dataset: MasterDataset, patternName: string): readonly StubRef[] { +function resolveStubRefs(dataset: PatternGraph, patternName: string): readonly StubRef[] { const rels = getRelationships(dataset, patternName); if (rels === undefined) return []; @@ -235,7 +235,7 @@ function resolveStubRefs(dataset: MasterDataset, patternName: string): readonly } function resolveArchNeighbors( - dataset: MasterDataset, + dataset: PatternGraph, pattern: ExtractedPattern, focalNames: ReadonlySet ): readonly NeighborEntry[] { @@ -257,7 +257,7 @@ function resolveArchNeighbors( } function resolveDeliverables( - api: ProcessStateAPI, + api: PatternGraphAPI, patternName: string ): readonly DeliverableEntry[] { const deliverables = api.getPatternDeliverables(patternName); @@ -268,7 +268,7 @@ function resolveDeliverables( })); } -function resolveFsm(api: ProcessStateAPI, status: string | undefined): FsmContext | undefined { +function resolveFsm(api: PatternGraphAPI, status: string | undefined): FsmContext | undefined { if (status === undefined) return undefined; if (!VALID_STATUSES.has(status)) return undefined; const validStatus = status as ProcessStatusValue; @@ -290,8 +290,8 @@ function resolveTestFiles(pattern: ExtractedPattern): readonly string[] { // --------------------------------------------------------------------------- export function assembleContext( - dataset: MasterDataset, - api: ProcessStateAPI, + dataset: PatternGraph, + api: PatternGraphAPI, options: ContextOptions ): ContextBundle { const { patterns: patternNames, sessionType } = options; @@ -438,7 +438,7 @@ export function assembleContext( // buildDepTree // --------------------------------------------------------------------------- -export function buildDepTree(dataset: MasterDataset, options: DepTreeOptions): DepTreeNode { +export function buildDepTree(dataset: PatternGraph, options: DepTreeOptions): DepTreeNode { const { pattern: focalName, maxDepth, includeImplementationDeps } = options; requirePattern(dataset, focalName); @@ -459,7 +459,7 @@ export function buildDepTree(dataset: MasterDataset, options: DepTreeOptions): D } function findDepTreeRoot( - dataset: MasterDataset, + dataset: PatternGraph, focalName: string, includeImplementationDeps: boolean ): string { @@ -488,7 +488,7 @@ function findDepTreeRoot( } function buildTreeNode( - dataset: MasterDataset, + dataset: PatternGraph, name: string, focalName: string, depth: number, @@ -572,7 +572,7 @@ function buildTreeNode( // --------------------------------------------------------------------------- export function buildFileReadingList( - dataset: MasterDataset, + dataset: PatternGraph, patternName: string, includeRelated: boolean ): FileReadingList { @@ -649,7 +649,7 @@ export function buildFileReadingList( // buildOverview // --------------------------------------------------------------------------- -export function buildOverview(dataset: MasterDataset): OverviewSummary { +export function buildOverview(dataset: PatternGraph): OverviewSummary { const { counts } = dataset; const total = counts.total; const percentage = total > 0 ? Math.round((counts.completed / total) * 100) : 0; diff --git a/src/api/coverage-analyzer.ts b/src/api/coverage-analyzer.ts index 1a18620a..ded77944 100644 --- a/src/api/coverage-analyzer.ts +++ b/src/api/coverage-analyzer.ts @@ -3,7 +3,7 @@ * @architect-pattern CoverageAnalyzerImpl * @architect-status active * @architect-implements DataAPIArchitectureQueries - * @architect-uses Pattern Scanner, MasterDataset + * @architect-uses Pattern Scanner, PatternGraph * @architect-used-by ProcessAPICLIImpl * @architect-arch-role service * @architect-arch-context api @@ -12,7 +12,7 @@ * ## CoverageAnalyzer — Annotation Coverage and Taxonomy Gap Detection * * Reports annotation completeness by comparing scannable files (from glob) - * against annotated patterns in MasterDataset. Uses independent glob via + * against annotated patterns in PatternGraph. Uses independent glob via * findFilesToScan() — cheap (~1ms) and avoids changing buildPipeline(). * * **When to Use:** When checking annotation completeness or finding unannotated files via `arch coverage` or `unannotated` CLI subcommands. @@ -21,7 +21,7 @@ import * as fs from 'node:fs/promises'; import * as path from 'node:path'; import { findFilesToScan, hasFileOptIn } from '../scanner/pattern-scanner.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import type { TagRegistry } from '../validation-schemas/tag-registry.js'; // --------------------------------------------------------------------------- @@ -48,7 +48,7 @@ export interface CoverageReport { // --------------------------------------------------------------------------- export function findUnusedTaxonomy( - dataset: MasterDataset, + dataset: PatternGraph, registry: TagRegistry ): UnusedTaxonomyReport { // Collect used values from patterns @@ -122,7 +122,7 @@ export async function findUnannotatedFiles( // --------------------------------------------------------------------------- export async function analyzeCoverage( - dataset: MasterDataset, + dataset: PatternGraph, inputGlobs: readonly string[], baseDir: string, registry: TagRegistry diff --git a/src/api/handoff-generator.ts b/src/api/handoff-generator.ts index 272b504d..17f68986 100644 --- a/src/api/handoff-generator.ts +++ b/src/api/handoff-generator.ts @@ -3,7 +3,7 @@ * @architect-pattern HandoffGeneratorImpl * @architect-status completed * @architect-implements DataAPIDesignSessionSupport - * @architect-uses ProcessStateAPI, MasterDataset, ContextFormatterImpl + * @architect-uses PatternGraphAPI, PatternGraph, ContextFormatterImpl * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/handoff-generator.ts * @architect-arch-role service @@ -12,16 +12,16 @@ * * ## HandoffGenerator — Session-End State Summary * - * Pure function that assembles a handoff document from ProcessStateAPI - * and MasterDataset. Captures everything the next session needs to + * Pure function that assembles a handoff document from PatternGraphAPI + * and PatternGraph. Captures everything the next session needs to * continue work without context loss. * * **When to Use:** When ending a work session and capturing state for the next session via the `handoff` CLI subcommand. */ import type { SessionType } from './context-assembler.js'; -import type { ProcessStateAPI } from './process-state.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraphAPI } from './pattern-graph-api.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import { QueryApiError } from './types.js'; import { getPatternName } from './pattern-helpers.js'; import { @@ -78,8 +78,8 @@ function inferSessionType(status: string | undefined): HandoffSessionType { // --------------------------------------------------------------------------- export function generateHandoff( - api: ProcessStateAPI, - _dataset: MasterDataset, // _dataset reserved for future use per design stub + api: PatternGraphAPI, + _dataset: PatternGraph, // _dataset reserved for future use per design stub options: HandoffOptions ): HandoffDocument { const { patternName, modifiedFiles } = options; diff --git a/src/api/index.ts b/src/api/index.ts index a646b7c0..8588dffa 100644 --- a/src/api/index.ts +++ b/src/api/index.ts @@ -19,12 +19,12 @@ * * ```typescript * import { - * createProcessStateAPI, - * type ProcessStateAPI, + * createPatternGraphAPI, + * type PatternGraphAPI, * type QueryResult, * } from "@libar-dev/architect/api"; * - * const api = createProcessStateAPI(masterDataset); + * const api = createPatternGraphAPI(patternGraph); * * // Query current work * const activeWork = api.getCurrentWork(); @@ -59,8 +59,8 @@ export { createSuccess, createError, QueryApiError } from './types.js'; export type { NeighborEntry } from './types.js'; // Process State API -export type { ProcessStateAPI } from './process-state.js'; -export { createProcessStateAPI } from './process-state.js'; +export type { PatternGraphAPI } from './pattern-graph-api.js'; +export { createPatternGraphAPI } from './pattern-graph-api.js'; // Pattern Summarization export type { PatternSummary } from './summarize.js'; diff --git a/src/api/process-state.ts b/src/api/pattern-graph-api.ts similarity index 96% rename from src/api/process-state.ts rename to src/api/pattern-graph-api.ts index 10726bdc..29e02760 100644 --- a/src/api/process-state.ts +++ b/src/api/pattern-graph-api.ts @@ -1,13 +1,13 @@ /** * @architect * @architect-core - * @architect-pattern ProcessStateAPI + * @architect-pattern PatternGraphAPI * @architect-status active * @architect-implements PhaseStateMachineValidation * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application - * @architect-uses MasterDataset, FSMValidator + * @architect-uses PatternGraph, FSMValidator * * ## Process State API - Programmatic Query Interface * @@ -32,9 +32,9 @@ * ### Usage * * ```typescript - * import { createProcessStateAPI } from "@libar-dev/architect"; + * import { createPatternGraphAPI } from "@libar-dev/architect"; * - * const api = createProcessStateAPI(masterDataset); + * const api = createPatternGraphAPI(patternGraph); * * // Get current work * const active = api.getCurrentWork(); @@ -47,7 +47,7 @@ */ import type { - MasterDataset, + PatternGraph, ExtractedPattern, PhaseGroup as MasterPhaseGroup, } from '../validation-schemas/index.js'; @@ -84,7 +84,7 @@ import type { /** * Programmatic API for querying project state */ -export interface ProcessStateAPI { +export interface PatternGraphAPI { // ───────────────────────────────────────────────────────────────────────── // Status Queries // ───────────────────────────────────────────────────────────────────────── @@ -205,7 +205,7 @@ export interface ProcessStateAPI { /** * Get complete pattern relationships (all relationship types) * - * Returns the full relationship data from the MasterDataset's relationshipIndex, + * Returns the full relationship data from the PatternGraph's relationshipIndex, * including UML-inspired relationships (implements, extends) and cross-references * (see-also, api-ref). * @@ -290,9 +290,9 @@ export interface ProcessStateAPI { // ───────────────────────────────────────────────────────────────────────── /** - * Get the underlying MasterDataset + * Get the underlying PatternGraph */ - getMasterDataset(): MasterDataset; + getPatternGraph(): PatternGraph; } // ============================================================================= @@ -300,12 +300,12 @@ export interface ProcessStateAPI { // ============================================================================= /** - * Create a ProcessStateAPI instance from a MasterDataset + * Create a PatternGraphAPI instance from a PatternGraph * - * @param dataset - The MasterDataset to wrap - * @returns ProcessStateAPI instance + * @param dataset - The PatternGraph to wrap + * @returns PatternGraphAPI instance */ -export function createProcessStateAPI(dataset: MasterDataset): ProcessStateAPI { +export function createPatternGraphAPI(dataset: PatternGraph): PatternGraphAPI { // Helper to find patterns by exact FSM status function filterByExactStatus(status: ProcessStatusValue): ExtractedPattern[] { return dataset.patterns.filter((p) => p.status === status); @@ -585,7 +585,7 @@ export function createProcessStateAPI(dataset: MasterDataset): ProcessStateAPI { // Raw Access // ───────────────────────────────────────────────────────────────────── - getMasterDataset() { + getPatternGraph() { return dataset; }, }; diff --git a/src/api/pattern-helpers.ts b/src/api/pattern-helpers.ts index e5ed91b7..a2ee4c68 100644 --- a/src/api/pattern-helpers.ts +++ b/src/api/pattern-helpers.ts @@ -16,10 +16,10 @@ import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; import type { - MasterDataset, + PatternGraph, RelationshipEntry, SequenceIndexEntry, -} from '../validation-schemas/master-dataset.js'; +} from '../validation-schemas/pattern-graph.js'; import { findBestMatch } from './fuzzy-match.js'; /** @@ -48,7 +48,7 @@ export function findPatternByName( * case-insensitive scan if the exact key is not found. */ export function getRelationships( - dataset: MasterDataset, + dataset: PatternGraph, name: string ): RelationshipEntry | undefined { if (dataset.relationshipIndex === undefined) return undefined; @@ -65,7 +65,7 @@ export function getRelationships( * Look up a sequenceIndex entry by pattern name with case-insensitive fallback. */ export function getSequenceEntry( - dataset: MasterDataset, + dataset: PatternGraph, name: string ): SequenceIndexEntry | undefined { if (dataset.sequenceIndex === undefined) return undefined; @@ -81,7 +81,7 @@ export function getSequenceEntry( /** * Get all pattern display names from the dataset. */ -export function allPatternNames(dataset: MasterDataset): readonly string[] { +export function allPatternNames(dataset: PatternGraph): readonly string[] { return dataset.patterns.map((p) => getPatternName(p)); } diff --git a/src/api/rules-query.ts b/src/api/rules-query.ts index 62fd327e..a0f39943 100644 --- a/src/api/rules-query.ts +++ b/src/api/rules-query.ts @@ -22,7 +22,7 @@ import { parseBusinessRuleAnnotations } from '../renderable/codecs/helpers.js'; import type { BusinessRuleAnnotations } from '../renderable/codecs/helpers.js'; import { deduplicateScenarioNames } from '../renderable/codecs/business-rules.js'; import { QueryApiError } from './types.js'; -import type { RuntimeMasterDataset } from '../generators/pipeline/index.js'; +import type { RuntimePatternGraph } from '../generators/pipeline/index.js'; // ═══════════════════════════════════════════════════════════════════════════ // Types @@ -67,14 +67,14 @@ export interface RulesQueryResult { // ═══════════════════════════════════════════════════════════════════════════ /** - * Query business rules from the MasterDataset, grouped by product area, + * Query business rules from the PatternGraph, grouped by product area, * phase, and feature pattern. * - * DD-4: Pure function taking RuntimeMasterDataset and RulesFilters. + * DD-4: Pure function taking RuntimePatternGraph and RulesFilters. * All Map/Set construction lives here, not in the CLI handler. */ export function queryBusinessRules( - dataset: RuntimeMasterDataset, + dataset: RuntimePatternGraph, filters: RulesFilters ): RulesQueryResult { // Collect patterns with rules, applying filters diff --git a/src/api/scope-validator.ts b/src/api/scope-validator.ts index 0a395972..6126f17a 100644 --- a/src/api/scope-validator.ts +++ b/src/api/scope-validator.ts @@ -3,7 +3,7 @@ * @architect-pattern ScopeValidatorImpl * @architect-status completed * @architect-implements DataAPIDesignSessionSupport - * @architect-uses ProcessStateAPI, MasterDataset, StubResolverImpl + * @architect-uses PatternGraphAPI, PatternGraph, StubResolverImpl * @architect-used-by ProcessAPICLIImpl * @architect-target src/api/scope-validator.ts * @architect-arch-role service @@ -12,15 +12,15 @@ * * ## ScopeValidator — Pre-flight Session Readiness Checker * - * Pure function composition over ProcessStateAPI and MasterDataset. + * Pure function composition over PatternGraphAPI and PatternGraph. * Runs a checklist of prerequisite validations before starting a * design or implementation session. * * **When to Use:** When running pre-flight checks before a session via the `scope-validate` CLI subcommand. */ -import type { ProcessStateAPI } from './process-state.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraphAPI } from './pattern-graph-api.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import { QueryApiError } from './types.js'; import { getPatternName, findPatternByName, firstImplements } from './pattern-helpers.js'; import { findStubPatterns, resolveStubs, extractDecisionItems } from './stub-resolver.js'; @@ -79,8 +79,8 @@ const VALID_STATUSES = VALID_PROCESS_STATUS_SET; // --------------------------------------------------------------------------- export function validateScope( - api: ProcessStateAPI, - dataset: MasterDataset, + api: PatternGraphAPI, + dataset: PatternGraph, options: ScopeValidationOptions ): ScopeValidationResult { const { patternName, scopeType, baseDir, strict } = options; @@ -172,7 +172,7 @@ export function formatScopeValidation(result: ScopeValidationResult): string { // --------------------------------------------------------------------------- export function checkDependenciesCompleted( - api: ProcessStateAPI, + api: PatternGraphAPI, patternName: string ): ValidationCheck { const deps = api.getPatternDependencies(patternName); @@ -215,7 +215,7 @@ export function checkDependenciesCompleted( } export function checkDeliverablesDefined( - api: ProcessStateAPI, + api: PatternGraphAPI, patternName: string ): ValidationCheck { const deliverables = api.getPatternDeliverables(patternName); @@ -238,7 +238,7 @@ export function checkDeliverablesDefined( } export function checkFsmAllowsTransition( - api: ProcessStateAPI, + api: PatternGraphAPI, patternName: string ): ValidationCheck { const pattern = api.getPattern(patternName); @@ -287,7 +287,7 @@ export function checkFsmAllowsTransition( } export function checkDesignDecisionsRecorded( - dataset: MasterDataset, + dataset: PatternGraph, patternName: string ): ValidationCheck { const stubs = findStubPatterns(dataset); @@ -322,7 +322,7 @@ export function checkDesignDecisionsRecorded( } export function checkExecutableSpecsSet( - api: ProcessStateAPI, + api: PatternGraphAPI, patternName: string ): ValidationCheck { const pattern = api.getPattern(patternName); @@ -349,7 +349,7 @@ export function checkExecutableSpecsSet( // --------------------------------------------------------------------------- export function checkStubsFromDepsExist( - dataset: MasterDataset, + dataset: PatternGraph, patternName: string, baseDir: string ): ValidationCheck { diff --git a/src/api/stub-resolver.ts b/src/api/stub-resolver.ts index f7551fd5..1fac459b 100644 --- a/src/api/stub-resolver.ts +++ b/src/api/stub-resolver.ts @@ -3,12 +3,12 @@ * @architect-pattern StubResolverImpl * @architect-status active * @architect-implements DataAPIStubIntegration - * @architect-uses ProcessStateAPI + * @architect-uses PatternGraphAPI * @architect-used-by ProcessAPICLIImpl * * ## StubResolver — Design Stub Discovery and Resolution * - * Identifies design session stubs in the MasterDataset and resolves them + * Identifies design session stubs in the PatternGraph and resolves them * against the filesystem to determine implementation status. * * Stub identification heuristic: @@ -25,7 +25,7 @@ import { existsSync } from 'node:fs'; import { resolve } from 'node:path'; import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import { getPatternName, firstImplements } from './pattern-helpers.js'; // --------------------------------------------------------------------------- @@ -93,13 +93,13 @@ export interface PdrReference { // --------------------------------------------------------------------------- /** - * Identify stub patterns from the MasterDataset. + * Identify stub patterns from the PatternGraph. * * A pattern is a stub if: * 1. Its source file path contains '/stubs/' (lives in stubs directory), OR * 2. It has a `targetPath` field (from @architect-target tag) */ -export function findStubPatterns(dataset: MasterDataset): readonly ExtractedPattern[] { +export function findStubPatterns(dataset: PatternGraph): readonly ExtractedPattern[] { return dataset.patterns.filter( (p) => p.source.file.includes('/stubs/') || p.targetPath !== undefined ); diff --git a/src/api/summarize.ts b/src/api/summarize.ts index dae2a09a..e4e4c765 100644 --- a/src/api/summarize.ts +++ b/src/api/summarize.ts @@ -4,7 +4,7 @@ * @architect-pattern PatternSummarizerImpl * @architect-status active * @architect-implements DataAPIOutputShaping - * @architect-uses ProcessStateAPI + * @architect-uses PatternGraphAPI * @architect-used-by OutputPipeline, ProcessAPICLIImpl * @architect-arch-role service * @architect-arch-context api diff --git a/src/api/types.ts b/src/api/types.ts index d36c9f2f..897e652e 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -3,22 +3,22 @@ * @architect-core * @architect-pattern ProcessStateTypes * @architect-status active - * @architect-depends-on:MasterDataset + * @architect-depends-on:PatternGraph * * ## Process State API Types * - * Type definitions for the ProcessStateAPI query interface. + * Type definitions for the PatternGraphAPI query interface. * Designed for programmatic access by Claude Code and other tools. * * ### When to Use * - * - Import types when working with ProcessStateAPI responses + * - Import types when working with PatternGraphAPI responses * - Use QueryResult for typed response handling */ import type { DeliverableStatus, ProcessStatusValue } from '../taxonomy/index.js'; import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; -import type { ImplementationRef } from '../validation-schemas/master-dataset.js'; +import type { ImplementationRef } from '../validation-schemas/pattern-graph.js'; // ============================================================================= // Query Response Types @@ -159,8 +159,8 @@ export interface PatternDependencies { /** * Complete pattern relationships (includes all relationship types) * - * Used by ProcessStateAPI.getPatternRelationships() to expose the full - * relationship graph from the MasterDataset's relationshipIndex. + * Used by PatternGraphAPI.getPatternRelationships() to expose the full + * relationship graph from the PatternGraph's relationshipIndex. */ export interface PatternRelationships { /** Patterns this pattern depends on (from @architect-depends-on) */ diff --git a/src/cli/cli-schema.ts b/src/cli/cli-schema.ts index b4653f8a..06d990b5 100644 --- a/src/cli/cli-schema.ts +++ b/src/cli/cli-schema.ts @@ -246,7 +246,7 @@ export const CLI_SCHEMA: CLISchema = { '318 patterns (224 completed, 47 active, 47 planned) = 70%', '', '=== ACTIVE PHASES ===', - 'Phase 24: ProcessStateAPIRelationshipQueries (1 active)', + 'Phase 24: PatternGraphAPIRelationshipQueries (1 active)', 'Phase 25: DataAPIStubIntegration (1 active)', '', '=== BLOCKING ===', @@ -286,20 +286,20 @@ export const CLI_SCHEMA: CLISchema = { 'Status: active | Category: pattern', '## ContextAssembler \u2014 Session-Oriented Context Bundle Builder', '', - 'Pure function composition over MasterDataset.', + 'Pure function composition over PatternGraph.', 'File: src/api/context-assembler.ts', '', '=== DEPENDENCIES ===', - '[active] ProcessStateAPI (implementation) src/api/process-state.ts', - '[completed] MasterDataset (implementation) src/validation-schemas/master-dataset.ts', + '[active] PatternGraphAPI (implementation) src/api/pattern-graph-api.ts', + '[completed] PatternGraph (implementation) src/validation-schemas/pattern-graph.ts', '', '=== CONSUMERS ===', 'ContextFormatterImpl (active)', 'ProcessAPICLIImpl (active)', '', '=== ARCHITECTURE (context: api) ===', - 'MasterDataset (completed, read-model)', - 'ProcessStateAPI (active, service)', + 'PatternGraph (completed, read-model)', + 'PatternGraphAPI (active, service)', '...', ].join('\n'), }, diff --git a/src/cli/dataset-cache.ts b/src/cli/dataset-cache.ts index 77c9480c..317c8c01 100644 --- a/src/cli/dataset-cache.ts +++ b/src/cli/dataset-cache.ts @@ -9,9 +9,9 @@ * @architect-arch-layer infrastructure * @architect-uses PipelineFactory, WorkflowConfigSchema * - * ## Dataset Cache - MasterDataset Persistence with mtime Invalidation + * ## Dataset Cache - PatternGraph Persistence with mtime Invalidation * - * Caches the full PipelineResult (MasterDataset + ValidationSummary + warnings) + * Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) * to a JSON file. Subsequent CLI invocations skip the 2-5s pipeline rebuild * when no source files have changed. * @@ -29,7 +29,7 @@ import * as path from 'path'; import * as crypto from 'crypto'; import { glob } from 'glob'; import type { PipelineResult, PipelineOptions } from '../generators/pipeline/index.js'; -import type { RuntimeMasterDataset } from '../generators/pipeline/index.js'; +import type { RuntimePatternGraph } from '../generators/pipeline/index.js'; import type { WorkflowConfig } from '../validation-schemas/workflow-config.js'; import { createLoadedWorkflow } from '../validation-schemas/workflow-config.js'; @@ -141,8 +141,8 @@ export async function tryLoadCache( if (cached.metadata.version !== CACHE_VERSION) return undefined; if (cached.metadata.key !== cacheKey) return undefined; - // Reconstruct RuntimeMasterDataset from plain MasterDataset + WorkflowConfig - const dataset = cached.dataset as RuntimeMasterDataset; + // Reconstruct RuntimePatternGraph from plain PatternGraph + WorkflowConfig + const dataset = cached.dataset as RuntimePatternGraph; if (cached.workflowConfig !== null) { const workflow = createLoadedWorkflow(cached.workflowConfig); // Assign workflow back onto the deserialized dataset (Maps are not JSON-serializable) diff --git a/src/cli/output-pipeline.ts b/src/cli/output-pipeline.ts index e71b249f..d6f2027a 100644 --- a/src/cli/output-pipeline.ts +++ b/src/cli/output-pipeline.ts @@ -24,7 +24,7 @@ */ import type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js'; -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import { QueryApiError } from '../api/types.js'; import type { QueryResult } from '../api/types.js'; import { summarizePatterns, SUMMARY_FIELDS, deriveSource } from '../api/summarize.js'; @@ -104,7 +104,7 @@ export type PipelineInput = | { readonly kind: 'scalar'; readonly data: unknown }; /** - * Set of ProcessStateAPI method names that return ExtractedPattern[]. + * Set of PatternGraphAPI method names that return ExtractedPattern[]. * * Used by the router to tag results with `kind: 'patterns'` for the pipeline. */ @@ -223,7 +223,7 @@ export function applyOutputPipeline(input: PipelineInput, modifiers: OutputModif * Pagination (offset/limit) applies after all filters. */ export function applyListFilters( - dataset: MasterDataset, + dataset: PatternGraph, filters: ListFilters ): readonly ExtractedPattern[] { let candidates: readonly ExtractedPattern[] = dataset.patterns; diff --git a/src/cli/process-api.ts b/src/cli/process-api.ts index c6ea08c1..f9306cf4 100644 --- a/src/cli/process-api.ts +++ b/src/cli/process-api.ts @@ -4,18 +4,18 @@ * @architect-core @architect-cli * @architect-pattern ProcessAPICLIImpl * @architect-status active - * @architect-implements ProcessStateAPICLI + * @architect-implements PatternGraphAPICLI * @architect-arch-role service * @architect-arch-context cli * @architect-arch-layer application - * @architect-uses ProcessStateAPI, MasterDataset, PipelineFactory, RulesQueryModule, PatternSummarizerImpl, FuzzyMatcherImpl, OutputPipelineImpl + * @architect-uses PatternGraphAPI, PatternGraph, PipelineFactory, RulesQueryModule, PatternSummarizerImpl, FuzzyMatcherImpl, OutputPipelineImpl * @architect-used-by npm scripts, Claude Code sessions * @architect-usecase "When querying project state from CLI" * @architect-usecase "When Claude Code needs real-time delivery state queries" * - * ## architect - CLI Query Interface to ProcessStateAPI + * ## architect - CLI Query Interface to PatternGraphAPI * - * Exposes ProcessStateAPI methods as CLI subcommands with JSON output. + * Exposes PatternGraphAPI methods as CLI subcommands with JSON output. * Runs pipeline steps 1-8 (config -> scan -> extract -> transform), * then routes subcommands to API methods. * @@ -27,7 +27,7 @@ * * ### Key Concepts * - * - **Subcommand Routing**: CLI subcommands map to ProcessStateAPI methods + * - **Subcommand Routing**: CLI subcommands map to PatternGraphAPI methods * - **JSON Output**: All output is JSON to stdout, errors to stderr * - **Pipeline Reuse**: Steps 1-8 match architect-generate exactly * - **QueryResult Envelope**: All output wrapped in success/error discriminated union @@ -43,13 +43,13 @@ import * as path from 'path'; import * as fs from 'fs'; import { applyProjectSourceDefaults, findConfigFile } from '../config/config-loader.js'; import { - buildMasterDataset, + buildPatternGraph, type PipelineResult, type ValidationSummary, - type RuntimeMasterDataset, + type RuntimePatternGraph, } from '../generators/pipeline/index.js'; -import { createProcessStateAPI } from '../api/process-state.js'; -import type { ProcessStateAPI } from '../api/process-state.js'; +import { createPatternGraphAPI } from '../api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../api/pattern-graph-api.js'; import type { ExtractedPattern } from '../validation-schemas/index.js'; import type { TagRegistry } from '../validation-schemas/tag-registry.js'; import { @@ -521,7 +521,7 @@ Available API Methods (for 'query'): getPatternsByCategory, getCategories Timeline: getPatternsByQuarter, getQuarters, getCurrentWork, getRoadmapItems, getRecentlyCompleted - Raw: getMasterDataset + Raw: getPatternGraph `); } @@ -693,7 +693,7 @@ function formatConfigStatus(configPath: string | null): string { // ============================================================================= async function buildPipeline(config: ProcessAPICLIConfig): Promise { - const result = await buildMasterDataset({ + const result = await buildPatternGraph({ input: config.input, features: config.features, baseDir: config.baseDir, @@ -825,7 +825,7 @@ function tryFsmShortCircuit(subcommand: string, subArgs: readonly string[]): unk // Subcommand Handlers // ============================================================================= -function handleStatus(api: ProcessStateAPI): unknown { +function handleStatus(api: PatternGraphAPI): unknown { return { counts: api.getStatusCounts(), completionPercentage: api.getCompletionPercentage(), @@ -909,8 +909,8 @@ const API_METHODS = [ 'getCurrentWork', 'getRoadmapItems', 'getRecentlyCompleted', - 'getMasterDataset', -] as const satisfies ReadonlyArray; + 'getPatternGraph', +] as const satisfies ReadonlyArray; type ApiMethodName = (typeof API_METHODS)[number]; @@ -921,7 +921,7 @@ type ApiMethodName = (typeof API_METHODS)[number]; */ const API_DISPATCH: Record< ApiMethodName, - (api: ProcessStateAPI, args: ReadonlyArray) => unknown + (api: PatternGraphAPI, args: ReadonlyArray) => unknown > = { // Status queries getPatternsByNormalizedStatus: (api, args) => @@ -991,11 +991,11 @@ const API_DISPATCH: Record< }, // Raw access - getMasterDataset: (api) => api.getMasterDataset(), + getPatternGraph: (api) => api.getPatternGraph(), }; function handleQuery( - api: ProcessStateAPI, + api: PatternGraphAPI, args: string[] ): { methodName: string; result: unknown } { const methodName = args[0]; @@ -1018,7 +1018,7 @@ function handleQuery( return { methodName, result: dispatch(api, coercedArgs) }; } -function handlePattern(api: ProcessStateAPI, args: string[]): unknown { +function handlePattern(api: PatternGraphAPI, args: string[]): unknown { const name = args[0]; if (!name) { throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect pattern '); @@ -1026,7 +1026,7 @@ function handlePattern(api: ProcessStateAPI, args: string[]): unknown { const pattern = api.getPattern(name); if (!pattern) { - const hint = suggestPattern(name, allPatternNames(api.getMasterDataset())); + const hint = suggestPattern(name, allPatternNames(api.getPatternGraph())); throw new QueryApiError('PATTERN_NOT_FOUND', `Pattern not found: "${name}".${hint}`); } @@ -1130,10 +1130,7 @@ function parseListFilters(subArgs: string[]): ListFilters { /** * Generate contextual hint for empty list results. */ -function generateEmptyHint( - dataset: RuntimeMasterDataset, - filters: ListFilters -): string | undefined { +function generateEmptyHint(dataset: RuntimePatternGraph, filters: ListFilters): string | undefined { if (filters.status !== null) { const counts = dataset.counts; const alternatives: string[] = []; @@ -1162,7 +1159,7 @@ function generateEmptyHint( } function handleList( - dataset: RuntimeMasterDataset, + dataset: RuntimePatternGraph, subArgs: string[], modifiers: OutputModifiers ): unknown { @@ -1178,13 +1175,13 @@ function handleList( return applyOutputPipeline(input, modifiers); } -function handleSearch(api: ProcessStateAPI, subArgs: string[]): unknown { +function handleSearch(api: PatternGraphAPI, subArgs: string[]): unknown { const query = subArgs[0]; if (!query) { throw new QueryApiError('INVALID_ARGUMENT', 'Usage: architect search '); } - const names = allPatternNames(api.getMasterDataset()); + const names = allPatternNames(api.getPatternGraph()); const matches = fuzzyMatchPatterns(query, names); if (matches.length === 0) { @@ -1316,7 +1313,7 @@ async function handleArch(ctx: RouteContext): Promise { // ============================================================================= function handleSequence( - dataset: RuntimeMasterDataset, + dataset: RuntimePatternGraph, subArgs: string[], modifiers: OutputModifiers ): unknown { @@ -1349,7 +1346,7 @@ function handleSequence( // ============================================================================= -function handleStubs(dataset: RuntimeMasterDataset, subArgs: string[], baseDir: string): unknown { +function handleStubs(dataset: RuntimePatternGraph, subArgs: string[], baseDir: string): unknown { const stubs = findStubPatterns(dataset); const resolutions = resolveStubs(stubs, baseDir); @@ -1393,7 +1390,7 @@ function handleStubs(dataset: RuntimeMasterDataset, subArgs: string[], baseDir: return groupStubsByPattern(filtered); } -function handleDecisions(dataset: RuntimeMasterDataset, subArgs: string[]): unknown { +function handleDecisions(dataset: RuntimePatternGraph, subArgs: string[]): unknown { const patternName = subArgs[0]; if (patternName === undefined) { throw new QueryApiError('INVALID_ARGUMENT', 'Usage: decisions '); @@ -1433,7 +1430,7 @@ function handleDecisions(dataset: RuntimeMasterDataset, subArgs: string[]): unkn }; } -function handlePdr(dataset: RuntimeMasterDataset, subArgs: string[]): unknown { +function handlePdr(dataset: RuntimePatternGraph, subArgs: string[]): unknown { const pdrNumber = subArgs[0]; if (pdrNumber === undefined) { throw new QueryApiError('INVALID_ARGUMENT', 'Usage: pdr (e.g., pdr 012)'); @@ -1521,8 +1518,8 @@ function handleRules(ctx: RouteContext): unknown { // ============================================================================= interface RouteContext { - api: ProcessStateAPI; - dataset: RuntimeMasterDataset; + api: PatternGraphAPI; + dataset: RuntimePatternGraph; validation: ValidationSummary; subcommand: string; subArgs: string[]; @@ -1986,18 +1983,18 @@ async function main(): Promise { } const pipelineMs = Math.round(performance.now() - startMs); - const { dataset: masterDataset, validation } = pipelineResult; + const { dataset: patternGraph, validation } = pipelineResult; // Build extended metadata for JSON responses const extra = buildQueryMetadataExtra(validation, cacheHit, cacheAgeMs, pipelineMs); - // Create ProcessStateAPI - const api = createProcessStateAPI(masterDataset); + // Create PatternGraphAPI + const api = createPatternGraphAPI(patternGraph); // Route and execute subcommand const result = await routeSubcommand({ api, - dataset: masterDataset, + dataset: patternGraph, validation, subcommand: opts.subcommand, subArgs: opts.subArgs, @@ -2005,7 +2002,7 @@ async function main(): Promise { sessionType: opts.sessionType, baseDir: path.resolve(opts.baseDir), cliConfig: { input: opts.input, features: opts.features, baseDir: opts.baseDir }, - registry: masterDataset.tagRegistry, + registry: patternGraph.tagRegistry, }); // Dual output path (ADR-008): @@ -2014,7 +2011,7 @@ async function main(): Promise { if (typeof result === 'string') { console.log(result); } else { - const envelope = createSuccess(result, masterDataset.counts.total, extra); + const envelope = createSuccess(result, patternGraph.counts.total, extra); const output = formatOutput(envelope, opts.format); console.log(output); } diff --git a/src/cli/repl.ts b/src/cli/repl.ts index c0af90b3..6d177327 100644 --- a/src/cli/repl.ts +++ b/src/cli/repl.ts @@ -7,7 +7,7 @@ * @architect-arch-role service * @architect-arch-context cli * @architect-arch-layer application - * @architect-uses PipelineFactory, ProcessStateAPI + * @architect-uses PipelineFactory, PatternGraphAPI * * ## REPL Mode - Interactive Multi-Query Pipeline Session * @@ -30,13 +30,13 @@ import * as readline from 'node:readline/promises'; import * as path from 'path'; import { - buildMasterDataset, + buildPatternGraph, type PipelineResult, - type RuntimeMasterDataset, + type RuntimePatternGraph, type ValidationSummary, } from '../generators/pipeline/index.js'; -import { createProcessStateAPI } from '../api/process-state.js'; -import type { ProcessStateAPI } from '../api/process-state.js'; +import { createPatternGraphAPI } from '../api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../api/pattern-graph-api.js'; import { QueryApiError, createSuccess, createError } from '../api/types.js'; import { formatOutput } from './output-pipeline.js'; import { @@ -60,8 +60,8 @@ export interface ReplOptions { } interface ReplState { - api: ProcessStateAPI; - dataset: RuntimeMasterDataset; + api: PatternGraphAPI; + dataset: RuntimePatternGraph; validation: ValidationSummary; } @@ -70,7 +70,7 @@ interface ReplState { // ============================================================================= async function loadPipeline(opts: ReplOptions): Promise { - const result = await buildMasterDataset({ + const result = await buildPatternGraph({ input: opts.input, features: opts.features, baseDir: opts.baseDir, @@ -192,7 +192,7 @@ export async function startRepl(opts: ReplOptions): Promise { console.error('Loading pipeline...'); const pipeline = await loadPipeline(opts); const state: ReplState = { - api: createProcessStateAPI(pipeline.dataset), + api: createPatternGraphAPI(pipeline.dataset), dataset: pipeline.dataset, validation: pipeline.validation, }; @@ -263,7 +263,7 @@ async function processLine(trimmed: string, state: ReplState, opts: ReplOptions) console.error('Reloading pipeline...'); try { const fresh = await loadPipeline(opts); - state.api = createProcessStateAPI(fresh.dataset); + state.api = createPatternGraphAPI(fresh.dataset); state.dataset = fresh.dataset; state.validation = fresh.validation; console.error(`Reloaded: ${state.dataset.counts.total} patterns`); diff --git a/src/cli/validate-patterns.ts b/src/cli/validate-patterns.ts index c3d2a219..631e6a80 100644 --- a/src/cli/validate-patterns.ts +++ b/src/cli/validate-patterns.ts @@ -5,7 +5,7 @@ * @architect-cli * @architect-pattern ValidatePatternsCLI * @architect-status completed - * @architect-uses PatternScanner, GherkinScanner, DocExtractor, GherkinExtractor, MasterDataset, CodecUtils + * @architect-uses PatternScanner, GherkinScanner, DocExtractor, GherkinExtractor, PatternGraph, CodecUtils * @architect-extract-shapes ValidateCLIConfig, ValidationIssue, ValidationSummary * * ## ValidatePatternsCLI - Cross-Source Pattern Validator @@ -41,7 +41,7 @@ import { applyProjectSourceDefaults, formatConfigError, } from '../config/config-loader.js'; -import { buildMasterDataset } from '../generators/pipeline/index.js'; +import { buildPatternGraph } from '../generators/pipeline/index.js'; import { ScannerConfigSchema, createJsonOutputCodec, @@ -49,7 +49,7 @@ import { } from '../validation-schemas/index.js'; import type { ExtractedPattern } from '../validation-schemas/index.js'; import { normalizeStatus, isPatternComplete } from '../taxonomy/index.js'; -import type { RuntimeMasterDataset } from '../generators/pipeline/index.js'; +import type { RuntimePatternGraph } from '../generators/pipeline/index.js'; import { validateDoD, formatDoDSummary, @@ -336,7 +336,7 @@ function hasImplementsMatch( tsPattern: ExtractedPattern, tsName: string, gherkinByName: ReadonlyMap, - dataset: RuntimeMasterDataset + dataset: RuntimePatternGraph ): boolean { // Check if a Gherkin pattern implements this TS pattern if ((dataset.relationshipIndex?.[tsName]?.implementedBy.length ?? 0) > 0) { @@ -364,7 +364,7 @@ function hasImplementsMatch( function hasGherkinImplementsMatch( gherkinPattern: ExtractedPattern, tsByName: ReadonlyMap, - dataset: RuntimeMasterDataset + dataset: RuntimePatternGraph ): boolean { const name = getPatternName(gherkinPattern); @@ -389,7 +389,7 @@ function hasGherkinImplementsMatch( } /** - * Validate cross-source consistency using the MasterDataset read model. + * Validate cross-source consistency using the PatternGraph read model. * * Compares TypeScript patterns against Gherkin patterns to find: * - Missing patterns in either source (with implements-aware resolution) @@ -398,13 +398,13 @@ function hasGherkinImplementsMatch( * - Missing deliverables for completed phases * - Invalid dependencies * - * DD-2: Consumes RuntimeMasterDataset instead of raw scanner/extractor output. + * DD-2: Consumes RuntimePatternGraph instead of raw scanner/extractor output. * DD-3: Two-phase matching — name-based first, then relationshipIndex fallback. * - * @param dataset - The pre-computed MasterDataset read model + * @param dataset - The pre-computed PatternGraph read model * @returns Validation summary with issues and statistics */ -export function validatePatterns(dataset: RuntimeMasterDataset): ValidationSummary { +export function validatePatterns(dataset: RuntimePatternGraph): ValidationSummary { const issues: ValidationIssue[] = []; const tsPatterns = dataset.bySourceType.typescript; const gherkinPatterns = dataset.bySourceType.gherkin; @@ -726,8 +726,8 @@ async function main(): Promise { console.log(''); } - // Build MasterDataset via shared pipeline factory (DD-7) - const pipelineResult = await buildMasterDataset({ + // Build PatternGraph via shared pipeline factory (DD-7) + const pipelineResult = await buildPatternGraph({ input: config.input, features: config.features, baseDir: config.baseDir, @@ -747,7 +747,7 @@ async function main(): Promise { } // Raw scans for stage-1 consumers (DoD validation, anti-pattern detection) - // These correctly use scanned file data, not the MasterDataset — see DD-7 + // These correctly use scanned file data, not the PatternGraph — see DD-7 const scannerConfig = ScannerConfigSchema.parse({ patterns: config.input, exclude: config.exclude.length > 0 ? config.exclude : undefined, diff --git a/src/generators/built-in/cli-recipe-generator.ts b/src/generators/built-in/cli-recipe-generator.ts index f1c4d9cf..077cf95a 100644 --- a/src/generators/built-in/cli-recipe-generator.ts +++ b/src/generators/built-in/cli-recipe-generator.ts @@ -11,7 +11,7 @@ * Generates `PROCESS-API-RECIPES.md` from the declarative CLI schema. * Sibling to `ProcessApiReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends - * on MasterDataset (ADR-006 compliant). + * on PatternGraph (ADR-006 compliant). * * ### When to Use * diff --git a/src/generators/built-in/codec-generators.ts b/src/generators/built-in/codec-generators.ts index 0d99daad..37ae8b98 100644 --- a/src/generators/built-in/codec-generators.ts +++ b/src/generators/built-in/codec-generators.ts @@ -8,7 +8,7 @@ * ## Codec-Based Generator Registration * * Registers codec-based generators for the RenderableDocument Model (RDM) system. - * These generators use Zod 4 codecs to transform MasterDataset into RenderableDocuments, + * These generators use Zod 4 codecs to transform PatternGraph into RenderableDocuments, * which are then rendered to markdown via the universal renderer. * * ### When to Use @@ -162,7 +162,7 @@ generatorRegistry.register(createCodecGenerator('claude-modules', 'claude-module /** * Index Generator - * Generates INDEX.md navigation hub with editorial preamble + MasterDataset statistics + * Generates INDEX.md navigation hub with editorial preamble + PatternGraph statistics */ generatorRegistry.register(createCodecGenerator('index', 'index')); @@ -195,7 +195,7 @@ generatorRegistry.register(createDesignReviewGenerator()); /** * Process API CLI Reference Generator * Generates PROCESS-API-REFERENCE.md from declarative CLI schema. - * Standalone: does not consume MasterDataset (ADR-006). + * Standalone: does not consume PatternGraph (ADR-006). */ generatorRegistry.register(createProcessApiReferenceGenerator()); @@ -206,7 +206,7 @@ generatorRegistry.register(createProcessApiReferenceGenerator()); /** * CLI Recipe & Workflow Guide Generator * Generates PROCESS-API-RECIPES.md from declarative CLI schema. - * Standalone: does not consume MasterDataset (ADR-006). + * Standalone: does not consume PatternGraph (ADR-006). */ let cliRecipePreamble: readonly SectionBlock[] = []; try { diff --git a/src/generators/built-in/design-review-generator.ts b/src/generators/built-in/design-review-generator.ts index 485cbe17..f9e5a857 100644 --- a/src/generators/built-in/design-review-generator.ts +++ b/src/generators/built-in/design-review-generator.ts @@ -7,13 +7,13 @@ * @architect-arch-role service * @architect-arch-context generator * @architect-arch-layer application - * @architect-uses DesignReviewCodec, MasterDataset, SequenceIndex + * @architect-uses DesignReviewCodec, PatternGraph, SequenceIndex * @architect-product-area:Generation * * ## DesignReviewGenerator * * Generates design review documents for patterns with sequence annotations. - * Auto-discovers annotated patterns from MasterDataset.sequenceIndex and + * Auto-discovers annotated patterns from PatternGraph.sequenceIndex and * produces one design review per entry. * * Output: `architect/design-reviews/{pattern-name}.md` @@ -65,7 +65,7 @@ class DesignReviewGeneratorImpl implements DocumentGenerator { context: GeneratorContext ): Promise { const files: OutputFile[] = []; - const dataset = context.masterDataset; + const dataset = context.patternGraph; const sequenceIndex = dataset.sequenceIndex; if (!sequenceIndex || Object.keys(sequenceIndex).length === 0) { diff --git a/src/generators/built-in/index.ts b/src/generators/built-in/index.ts index d2d02653..6fbc4744 100644 --- a/src/generators/built-in/index.ts +++ b/src/generators/built-in/index.ts @@ -10,7 +10,7 @@ * Registers all codec-based generators on import using the RDM * (RenderableDocument Model) architecture. * - * All generators use Zod 4 codecs to transform MasterDataset + * All generators use Zod 4 codecs to transform PatternGraph * into RenderableDocuments, which are then rendered to markdown. * * ### When to Use diff --git a/src/generators/built-in/process-api-reference-generator.ts b/src/generators/built-in/process-api-reference-generator.ts index d68b854f..8ddfebe2 100644 --- a/src/generators/built-in/process-api-reference-generator.ts +++ b/src/generators/built-in/process-api-reference-generator.ts @@ -10,7 +10,7 @@ * ## Standalone Generator for Process API CLI Reference * * Generates `PROCESS-API-REFERENCE.md` from the declarative CLI schema. - * Does NOT consume MasterDataset (ADR-006 compliant — CLI schema is static + * Does NOT consume PatternGraph (ADR-006 compliant — CLI schema is static * TypeScript, not annotation-derived data). */ diff --git a/src/generators/built-in/reference-generators.ts b/src/generators/built-in/reference-generators.ts index eb9fc6d6..a8ed9d97 100644 --- a/src/generators/built-in/reference-generators.ts +++ b/src/generators/built-in/reference-generators.ts @@ -14,7 +14,7 @@ import type { DocumentGenerator, GeneratorContext, GeneratorOutput } from '../types.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { DetailLevel } from '../../renderable/codecs/types/base.js'; import type { RenderableDocument, SectionBlock } from '../../renderable/schema.js'; import { heading, paragraph, separator, table, document } from '../../renderable/schema.js'; @@ -110,7 +110,7 @@ class ReferenceDocGenerator implements DocumentGenerator { _patterns: readonly ExtractedPattern[], context: GeneratorContext ): Promise { - const dataset = context.masterDataset; + const dataset = context.patternGraph; const codec = createReferenceCodec(this.config, { detailLevel: this.detailLevel, @@ -141,7 +141,7 @@ function toGeneratorName(title: string): string { */ function generateDualOutputFiles( configs: readonly ReferenceDocConfig[], - dataset: MasterDataset, + dataset: PatternGraph, pathPrefix: string ): Array<{ path: string; content: string }> { const files: Array<{ path: string; content: string }> = []; @@ -192,7 +192,7 @@ class ReferenceDocsGenerator implements DocumentGenerator { _patterns: readonly ExtractedPattern[], context: GeneratorContext ): Promise { - const dataset = context.masterDataset; + const dataset = context.patternGraph; const files = generateDualOutputFiles(this.configs, dataset, 'reference'); return Promise.resolve({ files }); @@ -218,7 +218,7 @@ class ProductAreaDocsGenerator implements DocumentGenerator { _patterns: readonly ExtractedPattern[], context: GeneratorContext ): Promise { - const dataset = context.masterDataset; + const dataset = context.patternGraph; const files = generateDualOutputFiles(this.configs, dataset, 'product-areas'); @@ -235,13 +235,13 @@ class ProductAreaDocsGenerator implements DocumentGenerator { /** * Builds a progressive disclosure index for product area documents. * - * Data-driven: computes per-area statistics from MasterDataset patterns, + * Data-driven: computes per-area statistics from PatternGraph patterns, * renders cross-area progress table, and generates live Mermaid diagrams * from annotation relationship data via buildScopedDiagram. */ function buildProductAreaIndex( configs: readonly ReferenceDocConfig[], - dataset: MasterDataset + dataset: PatternGraph ): string { const sections: SectionBlock[] = []; diff --git a/src/generators/codec-based.ts b/src/generators/codec-based.ts index f0c569a3..d20e4396 100644 --- a/src/generators/codec-based.ts +++ b/src/generators/codec-based.ts @@ -21,7 +21,7 @@ * * Architecture: * ``` - * GeneratorContext.masterDataset → Codec.decode() → RenderableDocument → renderDocumentWithFiles() → OutputFile[] + * GeneratorContext.patternGraph → Codec.decode() → RenderableDocument → renderDocumentWithFiles() → OutputFile[] * ``` */ @@ -34,7 +34,7 @@ import type { CodecContextEnrichment } from '../renderable/codecs/types/base.js' * Codec-based generator that wraps the new RDM system. * * Each instance handles a single document type and uses the corresponding - * codec to transform MasterDataset into RenderableDocument, then renders + * codec to transform PatternGraph into RenderableDocument, then renders * to markdown. */ export class CodecBasedGenerator implements DocumentGenerator { @@ -51,7 +51,7 @@ export class CodecBasedGenerator implements DocumentGenerator { _patterns: readonly ExtractedPattern[], context: GeneratorContext ): Promise { - const { masterDataset: dataset } = context; + const { patternGraph: dataset } = context; // Build context enrichment from generator context fields const contextEnrichment: CodecContextEnrichment = { diff --git a/src/generators/index.ts b/src/generators/index.ts index 79d27815..f95ec73c 100644 --- a/src/generators/index.ts +++ b/src/generators/index.ts @@ -6,7 +6,7 @@ * @architect-pattern Generators Module * * RDM (RenderableDocument Model) based document generation system. - * Uses Zod 4 codecs to transform MasterDataset into RenderableDocuments. + * Uses Zod 4 codecs to transform PatternGraph into RenderableDocuments. * * ### When to Use * @@ -55,14 +55,14 @@ export { type GenerationWarning, } from './orchestrator.js'; -// Pipeline - MasterDataset transformation for ProcessStateAPI usage +// Pipeline - PatternGraph transformation for PatternGraphAPI usage export { - buildMasterDataset, + buildPatternGraph, type PipelineOptions, mergePatterns, - transformToMasterDataset, + transformToPatternGraph, type RawDataset, - type RuntimeMasterDataset, + type RuntimePatternGraph, } from './pipeline/index.js'; // Product area and reference document config helpers (for downstream repo configs) diff --git a/src/generators/orchestrator.ts b/src/generators/orchestrator.ts index e9c10f41..029c3e1a 100644 --- a/src/generators/orchestrator.ts +++ b/src/generators/orchestrator.ts @@ -22,11 +22,11 @@ * execution (orchestrator-owned) keeps Data API and validation consumers aligned on one * read-model path while preserving generator-specific output handling. * - * ## Steps 1-8 via buildMasterDataset() + * ## Steps 1-8 via buildPatternGraph() * * Steps 1-8 (config load, TypeScript/Gherkin scan + extraction, merge, hierarchy - * derivation, workflow load, and `transformToMasterDataset`) are delegated to - * `buildMasterDataset()`. + * derivation, workflow load, and `transformToPatternGraph`) are delegated to + * `buildPatternGraph()`. * * ## Steps 9-10: Codec Execution and File Writing * @@ -62,7 +62,7 @@ import { generatorRegistry } from './registry.js'; import type { GeneratorContext } from './types.js'; import type { Result } from '../types/index.js'; import { Result as R } from '../types/index.js'; -import { buildMasterDataset } from './pipeline/index.js'; +import { buildPatternGraph } from './pipeline/index.js'; import { getChangedFilesList } from '../git/index.js'; import type { CodecOptions } from '../renderable/generate.js'; import { registerReferenceGenerators } from './built-in/reference-generators.js'; @@ -170,7 +170,7 @@ export interface GenerateOptions { /** * Pre-loaded tag registry. When provided, skips internal config load inside - * buildMasterDataset (avoids loading config twice when caller already has it). + * buildPatternGraph (avoids loading config twice when caller already has it). */ tagRegistry?: TagRegistry; @@ -313,7 +313,7 @@ export async function generateDocumentation( : undefined; // let factory use defaults // DD-6: Delegate 8-step pipeline to shared factory - const pipelineResult = await buildMasterDataset({ + const pipelineResult = await buildPatternGraph({ input: options.input, features, baseDir, @@ -333,10 +333,10 @@ export async function generateDocumentation( } // DD-6: Extract values from pipeline result - const { dataset: masterDataset } = pipelineResult.value; - const allPatterns = masterDataset.patterns; - const registry = masterDataset.tagRegistry; - const workflow = masterDataset.workflow; + const { dataset: patternGraph } = pipelineResult.value; + const allPatterns = patternGraph.patterns; + const registry = patternGraph.tagRegistry; + const workflow = patternGraph.workflow; // DD-1: Map PipelineWarning[] → GenerationWarning[] for (const pw of pipelineResult.value.warnings) { @@ -405,12 +405,12 @@ export async function generateDocumentation( continue; // Skip this generator, try others } - // Build generator context with pre-computed masterDataset and codec options + // Build generator context with pre-computed patternGraph and codec options const context: GeneratorContext = { baseDir, outputDir: options.outputDir, registry, - masterDataset, + patternGraph, ...(workflow !== undefined ? { workflow } : {}), ...(codecOptions !== undefined ? { codecOptions } : {}), ...(options.projectMetadata !== undefined diff --git a/src/generators/pipeline/build-pipeline.ts b/src/generators/pipeline/build-pipeline.ts index 710365ac..cc9878d9 100644 --- a/src/generators/pipeline/build-pipeline.ts +++ b/src/generators/pipeline/build-pipeline.ts @@ -5,12 +5,12 @@ * @architect-status completed * @architect-implements ProcessAPILayeredExtraction * @architect-product-area DataAPI - * @architect-uses PatternScanner, GherkinScanner, DocExtractor, GherkinExtractor, MasterDataset + * @architect-uses PatternScanner, GherkinScanner, DocExtractor, GherkinExtractor, PatternGraph * @architect-convention pipeline-architecture * * ## Shared Pipeline Factory Responsibilities * - * **Invariant:** `buildMasterDataset()` is the shared factory for Steps 1-8 of the + * **Invariant:** `buildPatternGraph()` is the shared factory for Steps 1-8 of the * architecture pipeline and returns `Result` without * process-level side effects. * @@ -21,7 +21,7 @@ * * 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 * @@ -32,7 +32,7 @@ * * ### 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 */ @@ -52,13 +52,13 @@ import { DEFAULT_CONTEXT_INFERENCE_RULES } from '../../config/defaults.js'; import { loadDefaultWorkflow, loadWorkflowFromPath } from '../../config/workflow-loader.js'; import type { LoadedWorkflow } from '../../config/workflow-loader.js'; import { - transformToMasterDataset, - transformToMasterDatasetWithValidation, + transformToPatternGraph, + transformToPatternGraphWithValidation, } from './transform-dataset.js'; import { Result } from '../../types/result.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import type { TagRegistry } from '../../validation-schemas/tag-registry.js'; -import type { RuntimeMasterDataset, ValidationSummary } from './transform-types.js'; +import type { RuntimePatternGraph, ValidationSummary } from './transform-types.js'; import type { ContextInferenceRule } from './context-inference.js'; // ═══════════════════════════════════════════════════════════════════════════ @@ -66,14 +66,14 @@ import type { ContextInferenceRule } from './context-inference.js'; // ═══════════════════════════════════════════════════════════════════════════ /** - * 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. * DD-3: exclude, contextInferenceRules support future orchestrator * migration without breaking changes. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export interface PipelineOptions { readonly input: readonly string[]; @@ -135,10 +135,10 @@ export interface ScanMetadata { /** * Successful pipeline result containing the dataset and validation summary. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export interface PipelineResult { - readonly dataset: RuntimeMasterDataset; + readonly dataset: RuntimePatternGraph; readonly validation: ValidationSummary; readonly warnings: readonly PipelineWarning[]; readonly scanMetadata: ScanMetadata; @@ -149,7 +149,7 @@ export interface PipelineResult { // ═══════════════════════════════════════════════════════════════════════════ /** - * Build a MasterDataset by executing the 8-step extraction pipeline. + * Build a PatternGraph by executing the 8-step extraction pipeline. * * Returns Result so each consumer maps errors * to its own strategy (process.exit, throw, etc.). Does not call process.exit @@ -163,9 +163,9 @@ export interface PipelineResult { * 5. Merge patterns (conflict handling per mergeConflictStrategy) * 6. Compute hierarchy children * 7. Load workflow configuration - * 8. Transform to MasterDataset with validation + * 8. Transform to PatternGraph with validation */ -export async function buildMasterDataset( +export async function buildPatternGraph( options: PipelineOptions ): Promise> { const baseDir = path.resolve(options.baseDir); @@ -340,7 +340,7 @@ export async function buildMasterDataset( gherkinErrorCount, }; - // Step 8: Transform to MasterDataset + // Step 8: Transform to PatternGraph // DD-3: includeValidation controls which transform path to use const contextInferenceRules = options.contextInferenceRules ?? DEFAULT_CONTEXT_INFERENCE_RULES; const rawDataset = { @@ -351,7 +351,7 @@ export async function buildMasterDataset( }; if (options.includeValidation === false) { - const dataset = transformToMasterDataset(rawDataset); + const dataset = transformToPatternGraph(rawDataset); return Result.ok({ dataset, validation: { @@ -366,6 +366,6 @@ export async function buildMasterDataset( }); } - const { dataset, validation } = transformToMasterDatasetWithValidation(rawDataset); + const { dataset, validation } = transformToPatternGraphWithValidation(rawDataset); return Result.ok({ dataset, validation, warnings, scanMetadata }); } diff --git a/src/generators/pipeline/index.ts b/src/generators/pipeline/index.ts index 87fdc59f..3f538fa3 100644 --- a/src/generators/pipeline/index.ts +++ b/src/generators/pipeline/index.ts @@ -13,7 +13,7 @@ * * ### When to Use * - * - When transforming extracted patterns into a MasterDataset + * - When transforming extracted patterns into a PatternGraph * - When building custom generation pipelines * - When accessing pre-computed indexes and views from the dataset * @@ -25,8 +25,8 @@ // ═══════════════════════════════════════════════════════════════════════════ export { - transformToMasterDataset, - transformToMasterDatasetWithValidation, + transformToPatternGraph, + transformToPatternGraphWithValidation, completionPercentage, isFullyCompleted, } from './transform-dataset.js'; @@ -35,7 +35,7 @@ export type { ContextInferenceRule } from './context-inference.js'; export type { RawDataset, - RuntimeMasterDataset, + RuntimePatternGraph, ValidationSummary, MalformedPattern, DanglingReference, @@ -53,7 +53,7 @@ export { mergePatterns } from './merge-patterns.js'; // ═══════════════════════════════════════════════════════════════════════════ export { - buildMasterDataset, + buildPatternGraph, type PipelineOptions, type PipelineResult, type PipelineError, diff --git a/src/generators/pipeline/relationship-resolver.ts b/src/generators/pipeline/relationship-resolver.ts index 47cf42e3..c01f8efe 100644 --- a/src/generators/pipeline/relationship-resolver.ts +++ b/src/generators/pipeline/relationship-resolver.ts @@ -12,14 +12,14 @@ * * Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) * and detects dangling references in the pattern graph. These are the 2nd and 3rd - * passes of the MasterDataset transformation pipeline. + * passes of the PatternGraph transformation pipeline. */ import type { ExtractedPattern } from '../../validation-schemas/index.js'; import type { RelationshipEntry, ImplementationRef, -} from '../../validation-schemas/master-dataset.js'; +} from '../../validation-schemas/pattern-graph.js'; import { getPatternName } from '../../api/pattern-helpers.js'; import type { DanglingReference } from './transform-types.js'; diff --git a/src/generators/pipeline/sequence-utils.ts b/src/generators/pipeline/sequence-utils.ts index f5a858b7..a9d4469d 100644 --- a/src/generators/pipeline/sequence-utils.ts +++ b/src/generators/pipeline/sequence-utils.ts @@ -8,14 +8,14 @@ * @architect-arch-context generator * @architect-arch-layer application * @architect-include pipeline-stages - * @architect-uses MasterDataset, ExtractedPattern + * @architect-uses PatternGraph, ExtractedPattern * @architect-product-area:Generation * * ## SequenceTransformUtils - Sequence Index Builder * * Builds pre-computed SequenceIndexEntry objects from patterns that have * sequence diagram annotations. Used during the single-pass transform to - * populate MasterDataset.sequenceIndex. + * populate PatternGraph.sequenceIndex. * * ### Layer Boundary * @@ -26,7 +26,7 @@ */ import type { BusinessRule } from '../../validation-schemas/extracted-pattern.js'; -import type { SequenceStep, SequenceIndexEntry } from '../../validation-schemas/master-dataset.js'; +import type { SequenceStep, SequenceIndexEntry } from '../../validation-schemas/pattern-graph.js'; // ============================================================================= // Tag Parsing (simple string split — no dependency on extractPatternTags) diff --git a/src/generators/pipeline/transform-dataset.ts b/src/generators/pipeline/transform-dataset.ts index 8291d666..4115a52b 100644 --- a/src/generators/pipeline/transform-dataset.ts +++ b/src/generators/pipeline/transform-dataset.ts @@ -8,15 +8,15 @@ * @architect-arch-context generator * @architect-arch-layer application * @architect-include pipeline-stages - * @architect-uses MasterDataset, ExtractedPattern, TagRegistry, NormalizeStatus + * @architect-uses PatternGraph, ExtractedPattern, TagRegistry, NormalizeStatus * @architect-used-by Orchestrator * @architect-usecase "When computing all pattern views in a single pass" * @architect-usecase "When transforming raw extracted data for generators" - * @architect-extract-shapes RuntimeMasterDataset, RawDataset, transformToMasterDataset + * @architect-extract-shapes RuntimePatternGraph, RawDataset, transformToPatternGraph * * ## TransformDataset - Single-Pass Pattern Transformation * - * Transforms raw extracted patterns into a MasterDataset with all pre-computed + * Transforms raw extracted patterns into a PatternGraph with all pre-computed * views. This is the core of the unified transformation pipeline, computing * status groups, phase groups, quarter groups, category groups, and source * groups in a single iteration over the pattern array. @@ -29,7 +29,7 @@ * ### Key Concepts * * - **Single-pass**: O(n) complexity regardless of view count - * - **Immutable output**: Returns a new MasterDataset object + * - **Immutable output**: Returns a new PatternGraph object * - **Workflow integration**: Uses workflow config for phase names */ @@ -44,7 +44,7 @@ import type { RelationshipEntry, ArchIndex, SequenceIndexEntry, -} from '../../validation-schemas/master-dataset.js'; +} from '../../validation-schemas/pattern-graph.js'; import { normalizeStatus, ACCEPTED_STATUS_VALUES } from '../../taxonomy/index.js'; import { buildSequenceIndexEntryWithValidation } from './sequence-utils.js'; @@ -54,7 +54,7 @@ import type { MalformedPattern, ValidationSummary, TransformResult, - RuntimeMasterDataset, + RuntimePatternGraph, RawDataset, } from './transform-types.js'; @@ -67,7 +67,7 @@ function isKnownStatus(status: string | undefined): boolean { } /** - * Transform raw extracted data into a MasterDataset with all pre-computed views. + * Transform raw extracted data into a PatternGraph with all pre-computed views. * * This is a ONE-PASS transformation that computes: * - Status-based groupings (completed/active/planned) @@ -79,17 +79,17 @@ function isKnownStatus(status: string | undefined): boolean { * - Optional relationship index * * Convenience wrapper that returns just the dataset. - * Use `transformToMasterDatasetWithValidation` to get validation summary. + * Use `transformToPatternGraphWithValidation` to get validation summary. * * @param raw - Raw dataset with patterns, registry, and optional workflow - * @returns MasterDataset with all pre-computed views + * @returns PatternGraph with all pre-computed views */ -export function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset { - return transformToMasterDatasetWithValidation(raw).dataset; +export function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph { + return transformToPatternGraphWithValidation(raw).dataset; } /** - * Transform raw extracted data into a MasterDataset with validation summary. + * Transform raw extracted data into a PatternGraph with validation summary. * * This is the full transformation that includes: * - Pre-loop validation against ExtractedPatternSchema @@ -105,7 +105,7 @@ export function transformToMasterDataset(raw: RawDataset): RuntimeMasterDataset * @param raw - Raw dataset with patterns, registry, and optional workflow * @returns TransformResult with dataset and validation summary */ -export function transformToMasterDatasetWithValidation(raw: RawDataset): TransformResult { +export function transformToPatternGraphWithValidation(raw: RawDataset): TransformResult { const { patterns, tagRegistry, workflow, contextInferenceRules } = raw; // ───────────────────────────────────────────────────────────────────────── @@ -336,7 +336,7 @@ export function transformToMasterDatasetWithValidation(raw: RawDataset): Transfo }); // ───────────────────────────────────────────────────────────────────────── - // Assemble final MasterDataset + // Assemble final PatternGraph // ───────────────────────────────────────────────────────────────────────── const byCategory = Object.fromEntries(byCategoryMap); @@ -357,7 +357,7 @@ export function transformToMasterDatasetWithValidation(raw: RawDataset): Transfo warningCount: malformedPatterns.length + danglingReferences.length + unknownStatuses.length, }; - const dataset: RuntimeMasterDataset = { + const dataset: RuntimePatternGraph = { patterns: patterns as ExtractedPattern[], tagRegistry, byStatus, diff --git a/src/generators/pipeline/transform-types.ts b/src/generators/pipeline/transform-types.ts index d360b389..756fe78f 100644 --- a/src/generators/pipeline/transform-types.ts +++ b/src/generators/pipeline/transform-types.ts @@ -6,16 +6,16 @@ * @architect-arch-context generator * @architect-arch-layer application * @architect-used-by TransformDataset, Orchestrator - * @architect-uses MasterDataset, LoadedWorkflow, ExtractedPattern, TagRegistry, ContextInferenceRule + * @architect-uses PatternGraph, LoadedWorkflow, ExtractedPattern, TagRegistry, ContextInferenceRule * - * ## TransformTypes - MasterDataset Transformation Types + * ## TransformTypes - PatternGraph Transformation Types * * Type definitions for the dataset transformation pipeline. * Separated from transform-dataset.ts to allow importing types * without pulling in the transformation logic. */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { LoadedWorkflow } from '../../config/workflow-loader.js'; import type { ExtractedPattern, TagRegistry } from '../../validation-schemas/index.js'; import type { ContextInferenceRule } from './context-inference.js'; @@ -66,26 +66,26 @@ export interface ValidationSummary { } /** - * Result of transformToMasterDataset including both dataset and validation info. + * Result of transformToPatternGraph including both dataset and validation info. */ export interface TransformResult { - /** The transformed MasterDataset */ - dataset: RuntimeMasterDataset; + /** The transformed PatternGraph */ + dataset: RuntimePatternGraph; /** Validation summary with any issues found during transformation */ validation: ValidationSummary; } /** - * Runtime MasterDataset with optional workflow + * Runtime PatternGraph with optional workflow * - * Extends the Zod-compatible MasterDataset with workflow reference. + * Extends the Zod-compatible PatternGraph with workflow reference. * LoadedWorkflow contains Maps which aren't JSON-serializable, * so it's kept separate from the Zod schema. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ -export interface RuntimeMasterDataset extends MasterDataset { +export interface RuntimePatternGraph extends PatternGraph { /** Optional workflow configuration (not serializable) */ readonly workflow?: LoadedWorkflow; } @@ -93,7 +93,7 @@ export interface RuntimeMasterDataset extends MasterDataset { /** * Raw input data for transformation * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export interface RawDataset { /** Extracted patterns from TypeScript and/or Gherkin sources */ diff --git a/src/generators/types.ts b/src/generators/types.ts index c889f903..022bac9c 100644 --- a/src/generators/types.ts +++ b/src/generators/types.ts @@ -4,7 +4,7 @@ import type { ExtractedPattern, TagRegistry } from '../validation-schemas'; import type { LoadedWorkflow } from '../validation-schemas/workflow-config.js'; -import type { RuntimeMasterDataset } from './pipeline/index.js'; +import type { RuntimePatternGraph } from './pipeline/index.js'; import type { CodecOptions } from '../renderable/generate.js'; import type { ProjectMetadata } from '../config/project-config.js'; import type { FormatType } from '../taxonomy/index.js'; @@ -76,7 +76,7 @@ export interface GeneratorContext { * computed in a single pass. Sections should use these pre-computed views * instead of filtering the raw patterns array. */ - readonly masterDataset: RuntimeMasterDataset; + readonly patternGraph: RuntimePatternGraph; /** * Optional codec-specific options for document generation. diff --git a/src/index.ts b/src/index.ts index 474c77a3..d39eb957 100644 --- a/src/index.ts +++ b/src/index.ts @@ -99,7 +99,7 @@ export * as generators from './generators/index.js'; /** * RenderableDocument Model for codec-based document generation. * - * New architecture that uses Zod 4 codecs to transform MasterDataset into + * New architecture that uses Zod 4 codecs to transform PatternGraph into * RenderableDocuments, which are rendered to markdown via a universal renderer. * * @example @@ -107,10 +107,10 @@ export * as generators from './generators/index.js'; * import { generateDocument, generateAllDocuments } from '@libar-dev/architect/renderable'; * * // Generate a single document type - * const files = generateDocument("patterns", masterDataset); + * const files = generateDocument("patterns", patternGraph); * * // Generate all document types - * const allFiles = generateAllDocuments(masterDataset); + * const allFiles = generateAllDocuments(patternGraph); * ``` */ export * as renderable from './renderable/index.js'; diff --git a/src/mcp/file-watcher.ts b/src/mcp/file-watcher.ts index 41ac026d..d4b57a9c 100644 --- a/src/mcp/file-watcher.ts +++ b/src/mcp/file-watcher.ts @@ -14,7 +14,7 @@ * ## MCP File Watcher * * Watches source file globs and triggers debounced pipeline rebuilds. - * When a TypeScript or Gherkin file changes, the MasterDataset is rebuilt + * When a TypeScript or Gherkin file changes, the PatternGraph is rebuilt * so subsequent tool calls reflect the updated annotations. * * ### When to Use diff --git a/src/mcp/pipeline-session.ts b/src/mcp/pipeline-session.ts index d22061bf..bc1ba70a 100644 --- a/src/mcp/pipeline-session.ts +++ b/src/mcp/pipeline-session.ts @@ -9,29 +9,29 @@ * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application - * @architect-uses PipelineFactory, ProcessStateAPI, ConfigLoader + * @architect-uses PipelineFactory, PatternGraphAPI, ConfigLoader * @architect-implements MCPServerIntegration * * ## MCP Pipeline Session Manager * - * Manages the in-memory MasterDataset lifecycle for the MCP server. + * Manages the in-memory PatternGraph lifecycle for the MCP server. * Loads config, builds the pipeline once, and provides atomic rebuild. * * ### When to Use * - * - When the MCP server needs a persistent ProcessStateAPI instance + * - When the MCP server needs a persistent PatternGraphAPI instance * - When rebuilding the dataset after source file changes */ import * as fs from 'node:fs'; import * as path from 'path'; import { - buildMasterDataset, + buildPatternGraph, type PipelineResult, - type RuntimeMasterDataset, + type RuntimePatternGraph, } from '../generators/pipeline/index.js'; -import { createProcessStateAPI } from '../api/process-state.js'; -import type { ProcessStateAPI } from '../api/process-state.js'; +import { createPatternGraphAPI } from '../api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../api/pattern-graph-api.js'; import type { TagRegistry } from '../validation-schemas/tag-registry.js'; import { applyProjectSourceDefaults } from '../config/config-loader.js'; @@ -47,8 +47,8 @@ export interface SessionOptions { } export interface PipelineSession { - readonly dataset: RuntimeMasterDataset; - readonly api: ProcessStateAPI; + readonly dataset: RuntimePatternGraph; + readonly api: PatternGraphAPI; readonly registry: TagRegistry; readonly baseDir: string; readonly sourceGlobs: { readonly input: readonly string[]; readonly features: readonly string[] }; @@ -157,7 +157,7 @@ export class PipelineSessionManager { ): Promise { const startMs = Date.now(); - const result = await buildMasterDataset({ + const result = await buildPatternGraph({ input, features, baseDir, @@ -170,7 +170,7 @@ export class PipelineSessionManager { const pipelineResult: PipelineResult = result.value; const dataset = pipelineResult.dataset; - const api = createProcessStateAPI(dataset); + const api = createPatternGraphAPI(dataset); const buildTimeMs = Date.now() - startMs; return { diff --git a/src/mcp/tool-registry.ts b/src/mcp/tool-registry.ts index ec1ee65c..fe2f79d9 100644 --- a/src/mcp/tool-registry.ts +++ b/src/mcp/tool-registry.ts @@ -9,13 +9,13 @@ * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application - * @architect-uses ProcessStateAPI, MCPPipelineSession + * @architect-uses PatternGraphAPI, MCPPipelineSession * @architect-implements MCPServerIntegration * * ## MCP Tool Registry * * Defines all MCP tools with Zod input schemas and handler functions. - * Each tool wraps a ProcessStateAPI method or CLI subcommand. + * Each tool wraps a PatternGraphAPI method or CLI subcommand. * Tool names use "architect_" prefix to avoid collisions with other MCP servers. * * ### When to Use @@ -654,7 +654,7 @@ export function registerAllTools(server: McpServer, sessionManager: PipelineSess { title: 'Rebuild Dataset', description: - 'Force rebuild of the in-memory MasterDataset from current source files. Use after making changes to annotated sources.', + 'Force rebuild of the in-memory PatternGraph from current source files. Use after making changes to annotated sources.', inputSchema: z.object({}), }, safeHandler(async () => { diff --git a/src/renderable/codecs/adr.ts b/src/renderable/codecs/adr.ts index 69640ecf..2634692e 100644 --- a/src/renderable/codecs/adr.ts +++ b/src/renderable/codecs/adr.ts @@ -9,7 +9,7 @@ * * ## AdrDocumentCodec * - * Transforms MasterDataset into RenderableDocument for Architecture Decision Records. + * Transforms PatternGraph into RenderableDocument for Architecture Decision Records. * Extracts ADRs from patterns with `@architect-adr` tags. * * **Purpose:** Architecture Decision Records extracted from patterns with @architect-adr tags. @@ -43,7 +43,7 @@ * - **Consequences**: Positive and negative outcomes */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { partitionRulesByPrefix, @@ -137,7 +137,7 @@ export function createAdrCodec(options?: AdrCodecOptions): DocumentCodec { /** * Default ADR Document Codec * - * Transforms MasterDataset → RenderableDocument for architecture decisions. + * Transforms PatternGraph → RenderableDocument for architecture decisions. * Groups ADRs by category with progressive disclosure. */ export const AdrDocumentCodec = createAdrCodec(); @@ -158,7 +158,7 @@ export const codecMeta = { * Build ADR document */ function buildAdrDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/architecture.ts b/src/renderable/codecs/architecture.ts index dcc90766..3d10e151 100644 --- a/src/renderable/codecs/architecture.ts +++ b/src/renderable/codecs/architecture.ts @@ -8,13 +8,13 @@ * @architect-arch-context renderer * @architect-arch-layer application * @architect-include codec-transformation - * @architect-uses MasterDataset, ArchIndex + * @architect-uses PatternGraph, ArchIndex * @architect-convention codec-registry * @architect-product-area:Generation * * ## ArchitectureDocumentCodec * - * Transforms MasterDataset into a RenderableDocument containing + * Transforms PatternGraph into a RenderableDocument containing * architecture diagrams (Mermaid) generated from source annotations. * * **Purpose:** Architecture diagrams (Mermaid) generated from source annotations. Supports component and layered views. @@ -54,7 +54,7 @@ * - **layered**: Components organized by architectural layer */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -156,12 +156,12 @@ export function createArchitectureCodec(options?: ArchitectureCodecOptions): Doc /** * Default Architecture Document Codec * - * Transforms MasterDataset → RenderableDocument for architecture diagrams. + * Transforms PatternGraph → RenderableDocument for architecture diagrams. * Uses default options with component diagram type. * * @example * ```typescript - * const doc = ArchitectureDocumentCodec.decode(masterDataset); + * const doc = ArchitectureDocumentCodec.decode(patternGraph); * const markdown = renderToMarkdown(doc); * ``` */ @@ -183,7 +183,7 @@ export const codecMeta = { * Build the architecture document from dataset */ function buildArchitectureDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -244,9 +244,9 @@ function buildArchitectureDocument( * Apply context filter to architecture index */ function applyContextFilter( - archIndex: NonNullable, + archIndex: NonNullable, filterContexts: string[] -): NonNullable { +): NonNullable { if (filterContexts.length === 0) { return archIndex; } @@ -312,8 +312,8 @@ function applyContextFilter( * are excluded from diagrams but remain in the component inventory. */ function filterToKeyComponents( - archIndex: NonNullable -): NonNullable { + archIndex: NonNullable +): NonNullable { const hasRole = (p: ExtractedPattern): boolean => p.archRole !== undefined; const filteredAll = archIndex.all.filter(hasRole); @@ -367,7 +367,7 @@ function filterToKeyComponents( * Build summary section with component counts */ function buildSummarySection( - diagramIndex: NonNullable, + diagramIndex: NonNullable, totalAnnotated: number, keyComponentsOnly: boolean ): SectionBlock[] { @@ -409,8 +409,8 @@ function buildSummarySection( * - extends → solid open arrow (-->>) */ function buildComponentDiagram( - archIndex: NonNullable, - dataset: MasterDataset + archIndex: NonNullable, + dataset: PatternGraph ): SectionBlock[] { const lines: string[] = ['graph TB']; const nodeIds = new Map(); // pattern name → node ID @@ -514,8 +514,8 @@ function buildComponentDiagram( * Build layered architecture diagram organized by layer */ function buildLayeredDiagram( - archIndex: NonNullable, - dataset: MasterDataset + archIndex: NonNullable, + dataset: PatternGraph ): SectionBlock[] { const lines: string[] = ['graph TB']; const nodeIds = new Map(); @@ -616,7 +616,7 @@ function buildLegendSection(): SectionBlock[] { /** * Build component inventory table */ -function buildInventorySection(archIndex: NonNullable): SectionBlock[] { +function buildInventorySection(archIndex: NonNullable): SectionBlock[] { const rows: string[][] = []; // Sort patterns by context, then by role, then by name diff --git a/src/renderable/codecs/business-rules.ts b/src/renderable/codecs/business-rules.ts index de1576f2..ec1b6b2d 100644 --- a/src/renderable/codecs/business-rules.ts +++ b/src/renderable/codecs/business-rules.ts @@ -9,7 +9,7 @@ * * ## BusinessRulesCodec * - * Transforms MasterDataset into a RenderableDocument for business rules output. + * Transforms PatternGraph into a RenderableDocument for business rules output. * Generates BUSINESS-RULES.md organized by product area, phase, and feature. * * **Purpose:** Business rules documentation organized by product area, phase, and feature. Extracts domain constraints from Gherkin Rule: blocks. @@ -60,7 +60,7 @@ * ``` */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import type { BusinessRule } from '../../validation-schemas/extracted-pattern.js'; import { @@ -219,12 +219,12 @@ export function createBusinessRulesCodec(options?: BusinessRulesCodecOptions): D /** * Default Business Rules Document Codec * - * Transforms MasterDataset → RenderableDocument for business rules. + * Transforms PatternGraph → RenderableDocument for business rules. * Uses default options with standard detail level. * * @example * ```typescript - * const doc = BusinessRulesCodec.decode(masterDataset); + * const doc = BusinessRulesCodec.decode(patternGraph); * const markdown = renderToMarkdown(doc); * ``` */ @@ -246,7 +246,7 @@ export const codecMeta = { * Build the business rules document from dataset */ function buildBusinessRulesDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -314,7 +314,7 @@ function buildBusinessRulesDocument( * Collect rules organized by Product Area → Phase → Feature */ function collectRulesByProductArea( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): Map { const groups = new Map(); diff --git a/src/renderable/codecs/claude-module.ts b/src/renderable/codecs/claude-module.ts index 43de55e4..015dee1b 100644 --- a/src/renderable/codecs/claude-module.ts +++ b/src/renderable/codecs/claude-module.ts @@ -7,7 +7,7 @@ * * ## ClaudeModuleCodec * - * Transforms MasterDataset into RenderableDocuments for CLAUDE.md module generation. + * Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. * Filters patterns with `claudeModule` tags and generates compact markdown modules * suitable for the `_claude-md/` directory structure. * @@ -31,7 +31,7 @@ * ``` */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import type { BusinessRule } from '../../validation-schemas/extracted-pattern.js'; import { @@ -110,7 +110,7 @@ export function createClaudeModuleCodec(options?: ClaudeModuleCodecOptions): Doc /** * Default Claude Module Codec * - * Transforms MasterDataset → RenderableDocument for CLAUDE.md modules. + * Transforms PatternGraph → RenderableDocument for CLAUDE.md modules. * Uses default options with standard detail level. */ export const ClaudeModuleCodec = createClaudeModuleCodec(); @@ -133,7 +133,7 @@ export const codecMeta = { * with each module as an additionalFile. */ function buildClaudeModuleDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { // Filter to patterns with claudeModule set diff --git a/src/renderable/codecs/composite.ts b/src/renderable/codecs/composite.ts index 3aaa957c..58a1224c 100644 --- a/src/renderable/codecs/composite.ts +++ b/src/renderable/codecs/composite.ts @@ -159,7 +159,7 @@ export function composeDocuments( /** * Create a CompositeCodec that decodes each child codec against the same - * MasterDataset and composes their outputs into a single RenderableDocument. + * PatternGraph and composes their outputs into a single RenderableDocument. */ export function createCompositeCodec( codecs: readonly DocumentCodec[], diff --git a/src/renderable/codecs/convention-extractor.ts b/src/renderable/codecs/convention-extractor.ts index 4b61e93b..9c49b920 100644 --- a/src/renderable/codecs/convention-extractor.ts +++ b/src/renderable/codecs/convention-extractor.ts @@ -1,7 +1,7 @@ /** * Convention Extractor * - * Filters MasterDataset for patterns tagged with `@architect-convention` + * Filters PatternGraph for patterns tagged with `@architect-convention` * and extracts convention content as structured data for reference codec * composition. Supports two sources: * @@ -16,7 +16,7 @@ * @see ReferenceDocShowcase spec */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { BusinessRule, ExtractedPattern } from '../../validation-schemas/extracted-pattern.js'; import type { SectionBlock } from '../schema.js'; import { table } from '../schema.js'; @@ -311,14 +311,14 @@ function extractConventionRulesFromDescription( // ============================================================================ /** - * Extracts convention content from MasterDataset. + * Extracts convention content from PatternGraph. * * Filters patterns tagged with `@architect-convention` matching the * requested tag values. For Gherkin-sourced patterns, extracts from * Rule: blocks. For TypeScript-sourced patterns (no rules array), * decomposes the JSDoc description by ## headings. * - * @param dataset - The MasterDataset containing all extracted patterns + * @param dataset - The PatternGraph containing all extracted patterns * @param conventionTags - Convention tag values to filter by * @returns Array of ConventionBundles, one per requested tag value * @@ -331,7 +331,7 @@ function extractConventionRulesFromDescription( * ``` */ export function extractConventions( - dataset: MasterDataset, + dataset: PatternGraph, conventionTags: readonly string[] ): ConventionBundle[] { if (conventionTags.length === 0) return []; diff --git a/src/renderable/codecs/design-review.ts b/src/renderable/codecs/design-review.ts index 68b90c75..e77a06e5 100644 --- a/src/renderable/codecs/design-review.ts +++ b/src/renderable/codecs/design-review.ts @@ -8,13 +8,13 @@ * @architect-arch-context renderer * @architect-arch-layer application * @architect-include codec-transformation - * @architect-uses MasterDataset, SequenceIndex, MermaidDiagramUtils + * @architect-uses PatternGraph, SequenceIndex, MermaidDiagramUtils * @architect-convention codec-registry * @architect-product-area:Generation * * ## DesignReviewCodec * - * Transforms MasterDataset into a RenderableDocument containing design review + * Transforms PatternGraph into a RenderableDocument containing design review * artifacts: sequence diagrams, component diagrams, type definition tables, * and design question templates. * @@ -32,10 +32,10 @@ */ import type { - MasterDataset, + PatternGraph, SequenceIndexEntry, SequenceStep, -} from '../../validation-schemas/master-dataset.js'; +} from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -93,7 +93,7 @@ const DEFAULT_DESIGN_REVIEW_OPTIONS: Required = { * Create a DesignReviewCodec with the given options. * * @param options - Codec configuration (patternName is required) - * @returns Configured Zod codec that transforms MasterDataset → RenderableDocument + * @returns Configured Zod codec that transforms PatternGraph → RenderableDocument */ export function createDesignReviewCodec(options: DesignReviewCodecOptions): DocumentCodec { const opts = mergeOptions(DEFAULT_DESIGN_REVIEW_OPTIONS, options); @@ -109,7 +109,7 @@ export function createDesignReviewCodec(options: DesignReviewCodecOptions): Docu * Build the design review document from dataset */ function buildDesignReviewDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const { patternName } = options; diff --git a/src/renderable/codecs/index-codec.ts b/src/renderable/codecs/index-codec.ts index 173bb2d7..a3975479 100644 --- a/src/renderable/codecs/index-codec.ts +++ b/src/renderable/codecs/index-codec.ts @@ -10,7 +10,7 @@ * * ## IndexCodec * - * **Purpose:** Navigation hub composing editorial preamble with MasterDataset statistics. + * **Purpose:** Navigation hub composing editorial preamble with PatternGraph statistics. * * **Output Files:** `INDEX.md` (single page, no detail files) * @@ -32,7 +32,7 @@ * - DD-5: Standalone codec, not routed through reference codec pipeline */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import { type RenderableDocument, type SectionBlock, @@ -132,7 +132,7 @@ export const IndexCodec = createIndexCodec(); export const codecMeta = { type: 'index', outputPath: 'INDEX.md', - description: 'Navigation hub with editorial preamble and MasterDataset statistics', + description: 'Navigation hub with editorial preamble and PatternGraph statistics', factory: createIndexCodec, defaultInstance: IndexCodec, } as const; @@ -259,7 +259,7 @@ function buildDocumentInventory(entries: readonly DocumentEntry[]): SectionBlock return sections; } -function buildProductAreaStats(dataset: MasterDataset): SectionBlock[] { +function buildProductAreaStats(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = [heading(2, 'Product Area Statistics')]; const rows: string[][] = []; @@ -303,7 +303,7 @@ function buildProductAreaStats(dataset: MasterDataset): SectionBlock[] { return sections; } -function buildPhaseProgress(dataset: MasterDataset): SectionBlock[] { +function buildPhaseProgress(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = [heading(2, 'Phase Progress')]; const counts = computeStatusCounts(dataset.patterns); diff --git a/src/renderable/codecs/index.ts b/src/renderable/codecs/index.ts index 5dc50782..6cb83b2e 100644 --- a/src/renderable/codecs/index.ts +++ b/src/renderable/codecs/index.ts @@ -7,7 +7,7 @@ * ## Document Codecs * * Barrel export for all document codecs. - * Each codec transforms MasterDataset → RenderableDocument. + * Each codec transforms PatternGraph → RenderableDocument. * * ### When to Use * @@ -218,7 +218,7 @@ export { DEFAULT_CLAUDE_MODULE_OPTIONS, } from './claude-module.js'; -// Index (navigation hub with MasterDataset statistics + editorial preamble) +// Index (navigation hub with PatternGraph statistics + editorial preamble) export { IndexCodec, createIndexCodec, diff --git a/src/renderable/codecs/patterns.ts b/src/renderable/codecs/patterns.ts index 7d1c02be..80372f67 100644 --- a/src/renderable/codecs/patterns.ts +++ b/src/renderable/codecs/patterns.ts @@ -14,7 +14,7 @@ * * ## PatternsDocumentCodec * - * Transforms MasterDataset into a RenderableDocument for pattern registry output. + * Transforms PatternGraph into a RenderableDocument for pattern registry output. * Generates PATTERNS.md and category detail files (patterns/*.md). * * **Purpose:** Pattern registry with category-based organization. @@ -49,7 +49,7 @@ * ``` */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -181,12 +181,12 @@ export function createPatternsCodec(options?: PatternsCodecOptions): DocumentCod /** * Default Patterns Document Codec * - * Transforms MasterDataset → RenderableDocument for pattern registry. + * Transforms PatternGraph → RenderableDocument for pattern registry. * Uses default options with all features enabled. * * @example * ```typescript - * const doc = PatternsDocumentCodec.decode(masterDataset); + * const doc = PatternsDocumentCodec.decode(patternGraph); * const markdown = renderToMarkdown(doc); * ``` */ @@ -208,7 +208,7 @@ export const codecMeta = { * Build the patterns document from dataset */ function buildPatternsDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -263,9 +263,9 @@ function buildPatternsDocument( * Always excludes ADR patterns (they belong to the ADR codec). */ function applyPatternFilters( - dataset: MasterDataset, + dataset: PatternGraph, options: Required -): MasterDataset { +): PatternGraph { // Always exclude ADR patterns — they belong to the ADR codec, not patterns const nonAdrPatterns = dataset.patterns.filter((p) => p.adr === undefined); @@ -298,7 +298,7 @@ function applyPatternFilters( /** * Build progress summary section */ -function buildProgressSummary(dataset: MasterDataset): SectionBlock[] { +function buildProgressSummary(dataset: PatternGraph): SectionBlock[] { const { counts } = dataset; const progress = completionPercentage(counts); const progressBar = renderProgressBar(counts.completed, counts.total, 20); @@ -323,7 +323,7 @@ function buildProgressSummary(dataset: MasterDataset): SectionBlock[] { * Build quick navigation section * Links to category anchors within the main document (categories are H3 sections) */ -function buildQuickNavigation(dataset: MasterDataset): SectionBlock[] { +function buildQuickNavigation(dataset: PatternGraph): SectionBlock[] { const categories = Object.keys(dataset.byCategory).sort(); if (categories.length === 0) { @@ -344,7 +344,7 @@ function buildQuickNavigation(dataset: MasterDataset): SectionBlock[] { /** * Build pattern table section */ -function buildPatternTable(dataset: MasterDataset): SectionBlock[] { +function buildPatternTable(dataset: PatternGraph): SectionBlock[] { const patterns = sortByStatusAndName([...dataset.patterns]); const rows = patterns.map((p) => { @@ -369,7 +369,7 @@ function buildPatternTable(dataset: MasterDataset): SectionBlock[] { * Each pattern links to its individual detail file when generateDetailFiles is enabled */ function buildCategorySections( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -412,7 +412,7 @@ function buildCategorySections( * - implements → dotted arrow (..->) * - extends → solid open arrow (-->>) */ -function buildDependencyGraph(dataset: MasterDataset): SectionBlock[] { +function buildDependencyGraph(dataset: PatternGraph): SectionBlock[] { const relationships = dataset.relationshipIndex ?? {}; const patternNames = Object.keys(relationships); @@ -494,7 +494,7 @@ function patternToSlug(patternName: string): string { * Build individual pattern files (progressive disclosure) * Creates one file per pattern instead of grouping by category */ -function buildIndividualPatternFiles(dataset: MasterDataset): Record { +function buildIndividualPatternFiles(dataset: PatternGraph): Record { const files: Record = {}; for (const pattern of dataset.patterns) { @@ -513,7 +513,7 @@ function buildIndividualPatternFiles(dataset: MasterDataset): Record ): RenderableDocument { const sections: SectionBlock[] = []; @@ -418,7 +418,7 @@ function buildPhaseChecklist( // ═══════════════════════════════════════════════════════════════════════════ function buildSessionPlanDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -521,7 +521,7 @@ function buildPhasePlan( // ═══════════════════════════════════════════════════════════════════════════ function buildSessionFindingsDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/pr-changes.ts b/src/renderable/codecs/pr-changes.ts index fe1c4610..6f144a74 100644 --- a/src/renderable/codecs/pr-changes.ts +++ b/src/renderable/codecs/pr-changes.ts @@ -9,7 +9,7 @@ * * ## PrChangesCodec * - * Transforms MasterDataset into RenderableDocument for PR-scoped output. + * Transforms PatternGraph into RenderableDocument for PR-scoped output. * Filters patterns by changed files and/or release version tags. * * **Purpose:** PR-scoped view filtered by changed files or release version. @@ -42,7 +42,7 @@ * If both are specified, patterns must match at least one criterion. */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -154,7 +154,7 @@ export function createPrChangesCodec(options?: PrChangesCodecOptions): DocumentC /** * Default PR Changes Document Codec * - * Transforms MasterDataset → RenderableDocument for PR changes. + * Transforms PatternGraph → RenderableDocument for PR changes. * Without options, shows all patterns (no filtering). */ export const PrChangesCodec = createPrChangesCodec(); @@ -175,7 +175,7 @@ export const codecMeta = { * Build PR changes document */ function buildPrChangesDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/product-area-metadata.ts b/src/renderable/codecs/product-area-metadata.ts index a527fb20..b7ef3d73 100644 --- a/src/renderable/codecs/product-area-metadata.ts +++ b/src/renderable/codecs/product-area-metadata.ts @@ -138,7 +138,7 @@ export const PRODUCT_AREA_META: Readonly intro: 'The generation pipeline transforms annotated source code into markdown documents through a ' + 'four-stage architecture: Scanner discovers files, Extractor produces `ExtractedPattern` objects, ' + - 'Transformer builds MasterDataset with pre-computed views, and Codecs render to markdown via ' + + 'Transformer builds PatternGraph with pre-computed views, and Codecs render to markdown via ' + 'RenderableDocument IR. Nine specialized codecs handle reference docs, planning, session, reporting, ' + 'timeline, ADRs, business rules, taxonomy, and composite output — each supporting three detail levels ' + '(detailed, standard, summary). The Orchestrator runs generators in registration order, producing both ' + @@ -157,12 +157,12 @@ export const PRODUCT_AREA_META: Readonly [ 'Transformer', '`src/generators/pipeline/`', - 'MasterDataset with pre-computed views for O(1) access (ADR-006)', + 'PatternGraph with pre-computed views for O(1) access (ADR-006)', ], [ 'Codec', '`src/renderable/`', - 'Pure functions: MasterDataset → RenderableDocument → Markdown', + 'Pure functions: PatternGraph → RenderableDocument → Markdown', ], ] ), @@ -187,7 +187,7 @@ export const PRODUCT_AREA_META: Readonly ], keyInvariants: [ 'Codec purity: Every codec is a pure function (dataset in, document out). No side effects, no filesystem access. Same input always produces same output', - 'Single read model (ADR-006): All codecs consume MasterDataset. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship', + 'Single read model (ADR-006): All codecs consume PatternGraph. No codec reads raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship', 'Progressive disclosure: Every document renders at three detail levels (detailed, standard, summary) from the same codec. Summary feeds `_claude-md/` modules; detailed feeds `docs-live/reference/`', 'Config-driven generation: A single `ReferenceDocConfig` produces a complete document. Content sources compose in fixed order: conventions, diagrams, shapes, behaviors', 'RenderableDocument IR: Codecs express intent ("this is a table"), the renderer handles syntax ("pipe-delimited markdown"). Switching output format requires only a new renderer', @@ -260,7 +260,7 @@ export const PRODUCT_AREA_META: Readonly ], keyPatterns: [ 'DataAPIContextAssembly', - 'ProcessStateAPICLI', + 'PatternGraphAPICLI', 'DataAPIDesignSessionSupport', 'DataAPIRelationshipGraph', 'DataAPIOutputShaping', diff --git a/src/renderable/codecs/reference-builders.ts b/src/renderable/codecs/reference-builders.ts index 9c5485bd..f5b99c86 100644 --- a/src/renderable/codecs/reference-builders.ts +++ b/src/renderable/codecs/reference-builders.ts @@ -31,7 +31,7 @@ import type { ExtractedPattern } from '../../validation-schemas/extracted-patter import type { ExtractedShape } from '../../validation-schemas/extracted-shape.js'; import { camelCaseToTitleCase, slugify } from '../../utils/string-utils.js'; import { getPatternName } from '../../api/pattern-helpers.js'; -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import { collectScopePatterns } from './reference-diagrams.js'; // ============================================================================ @@ -380,7 +380,7 @@ export function buildShapeSections( * Returns undefined if no patterns found. */ export function buildBoundarySummary( - dataset: MasterDataset, + dataset: PatternGraph, scopes: readonly DiagramScope[] ): SectionBlock | undefined { const allPatterns: ExtractedPattern[] = []; diff --git a/src/renderable/codecs/reference-diagrams.ts b/src/renderable/codecs/reference-diagrams.ts index 24f77f47..031c5330 100644 --- a/src/renderable/codecs/reference-diagrams.ts +++ b/src/renderable/codecs/reference-diagrams.ts @@ -8,14 +8,14 @@ * All diagram builder functions: collectScopePatterns, collectNeighborPatterns, * prepareDiagramContext, and the five diagram type builders (flowchart, sequence, * state, C4, class). Also contains the three hardcoded domain diagrams - * (fsm-lifecycle, generation-pipeline, master-dataset-views) and the + * (fsm-lifecycle, generation-pipeline, pattern-graph-views) and the * public buildScopedDiagram dispatcher. */ import { type SectionBlock, heading, paragraph, separator, mermaid } from '../schema.js'; import type { DiagramScope } from './reference-types.js'; import type { ExtractedPattern } from '../../validation-schemas/extracted-pattern.js'; -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import { sanitizeNodeId, EDGE_STYLES, @@ -36,7 +36,7 @@ import type { ProcessStatusValue } from '../../taxonomy/index.js'; * Collect patterns matching a DiagramScope filter. */ export function collectScopePatterns( - dataset: MasterDataset, + dataset: PatternGraph, scope: DiagramScope ): ExtractedPattern[] { const nameSet = new Set(scope.patterns ?? []); @@ -62,7 +62,7 @@ export function collectScopePatterns( * the scope depends on, not what depends on it. */ export function collectNeighborPatterns( - dataset: MasterDataset, + dataset: PatternGraph, scopeNames: ReadonlySet ): ExtractedPattern[] { const neighborNames = new Set(); @@ -118,7 +118,7 @@ interface DiagramContext { /** Extract shared setup from scope + dataset into a reusable context */ function prepareDiagramContext( - dataset: MasterDataset, + dataset: PatternGraph, scope: DiagramScope ): DiagramContext | undefined { const scopePatterns = collectScopePatterns(dataset, scope); @@ -478,8 +478,8 @@ function buildGenerationPipelineSequenceDiagram(): string[] { ' Orchestrator ->> Extractor: extractFromGherkin(docs)', ' Extractor -->> Orchestrator: ExtractedPattern[]', ' Orchestrator ->> Orchestrator: mergePatterns(ts, gherkin)', - ' Orchestrator ->> Transformer: transformToMasterDataset(patterns)', - ' Transformer -->> Orchestrator: MasterDataset', + ' Orchestrator ->> Transformer: transformToPatternGraph(patterns)', + ' Transformer -->> Orchestrator: PatternGraph', ' Orchestrator ->> Codec: codec.decode(dataset)', ' Codec -->> Orchestrator: RenderableDocument', ' Orchestrator ->> Renderer: render(document)', @@ -487,11 +487,11 @@ function buildGenerationPipelineSequenceDiagram(): string[] { ]; } -/** Build MasterDataset fan-out diagram from hardcoded domain knowledge */ -function buildMasterDatasetViewsDiagram(): string[] { +/** Build PatternGraph fan-out diagram from hardcoded domain knowledge */ +function buildPatternGraphViewsDiagram(): string[] { return [ 'graph TB', - ' MD[MasterDataset]', + ' MD[PatternGraph]', ' MD --> byStatus["byStatus
(completed / active / planned)"]', ' MD --> byPhase["byPhase
(sorted, with counts)"]', ' MD --> byQuarter["byQuarter
(keyed by Q-YYYY)"]', @@ -664,7 +664,7 @@ function buildClassDiagram(ctx: DiagramContext): string[] { * Scope patterns are grouped by archContext in subgraphs (flowchart) or * rendered as participants/states (sequence/state diagrams). */ -export function buildScopedDiagram(dataset: MasterDataset, scope: DiagramScope): SectionBlock[] { +export function buildScopedDiagram(dataset: PatternGraph, scope: DiagramScope): SectionBlock[] { const title = scope.title ?? 'Component Overview'; // Content source override: render hardcoded domain diagrams @@ -684,11 +684,11 @@ export function buildScopedDiagram(dataset: MasterDataset, scope: DiagramScope): separator(), ]; } - if (scope.source === 'master-dataset-views') { + if (scope.source === 'pattern-graph-views') { return [ heading(2, title), - paragraph('Pre-computed view fan-out from MasterDataset (single-pass transform):'), - mermaid(buildMasterDatasetViewsDiagram().join('\n')), + paragraph('Pre-computed view fan-out from PatternGraph (single-pass transform):'), + mermaid(buildPatternGraphViewsDiagram().join('\n')), separator(), ]; } diff --git a/src/renderable/codecs/reference-types.ts b/src/renderable/codecs/reference-types.ts index f949f7bb..94943a50 100644 --- a/src/renderable/codecs/reference-types.ts +++ b/src/renderable/codecs/reference-types.ts @@ -21,7 +21,7 @@ import type { ShapeSelector } from './shape-matcher.js'; export const DIAGRAM_SOURCE_VALUES = [ 'fsm-lifecycle', 'generation-pipeline', - 'master-dataset-views', + 'pattern-graph-views', ] as const; /** Discriminated source type for DiagramScope.source */ @@ -71,7 +71,7 @@ export interface DiagramScope { * instead of computing from pattern relationships. * - 'fsm-lifecycle': FSM state transitions with protection levels * - 'generation-pipeline': 4-stage generation pipeline temporal flow - * - 'master-dataset-views': MasterDataset pre-computed view fan-out + * - 'pattern-graph-views': PatternGraph pre-computed view fan-out */ readonly source?: DiagramSource; } @@ -89,7 +89,7 @@ export interface ReferenceDocConfig { /** Convention tag values to extract from decision records */ readonly conventionTags?: readonly string[]; - /** Categories to filter behavior patterns from MasterDataset */ + /** Categories to filter behavior patterns from PatternGraph */ readonly behaviorCategories?: readonly string[]; /** Multiple scoped diagrams. */ diff --git a/src/renderable/codecs/reference.ts b/src/renderable/codecs/reference.ts index 299f3e2b..6fd91084 100644 --- a/src/renderable/codecs/reference.ts +++ b/src/renderable/codecs/reference.ts @@ -69,7 +69,7 @@ * ``` */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import { type RenderableDocument, type SectionBlock, @@ -328,7 +328,7 @@ export function createReferenceCodec( * 5. Behavior specifications (all patterns with rules/descriptions) */ function decodeProductArea( - dataset: MasterDataset, + dataset: PatternGraph, config: ReferenceDocConfig, opts: Required ): RenderableDocument { diff --git a/src/renderable/codecs/reporting.ts b/src/renderable/codecs/reporting.ts index 86dafd3d..60764a9c 100644 --- a/src/renderable/codecs/reporting.ts +++ b/src/renderable/codecs/reporting.ts @@ -44,7 +44,7 @@ * - When combining completion stats with architecture context */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -222,7 +222,7 @@ export const codecMetas = [ // ═══════════════════════════════════════════════════════════════════════════ function buildChangelogDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -375,7 +375,7 @@ function buildChangelogSection( // ═══════════════════════════════════════════════════════════════════════════ function buildTraceabilityDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -471,7 +471,7 @@ function buildTraceabilityDocument( // ═══════════════════════════════════════════════════════════════════════════ function buildOverviewDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/requirements.ts b/src/renderable/codecs/requirements.ts index 7653953a..99ee7894 100644 --- a/src/renderable/codecs/requirements.ts +++ b/src/renderable/codecs/requirements.ts @@ -9,7 +9,7 @@ * * ## RequirementsDocumentCodec * - * Transforms MasterDataset into RenderableDocument for PRD/requirements output. + * Transforms PatternGraph into RenderableDocument for PRD/requirements output. * Generates PRODUCT-REQUIREMENTS.md and detail files (requirements/*.md). * * **Purpose:** Product requirements documentation grouped by product area or user role. @@ -40,7 +40,7 @@ * ``` */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -168,7 +168,7 @@ export function createRequirementsCodec(options?: RequirementsCodecOptions): Doc /** * Default Requirements Document Codec * - * Transforms MasterDataset → RenderableDocument for product requirements. + * Transforms PatternGraph → RenderableDocument for product requirements. * Features grouped by product area and user role. */ export const RequirementsDocumentCodec = createRequirementsCodec(); @@ -189,7 +189,7 @@ export const codecMeta = { * Build requirements document */ function buildRequirementsDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -508,7 +508,7 @@ export function requirementToSlug(patternName: string, phase: number | undefined function buildRequirementsDetailFiles( patterns: ExtractedPattern[], options: Required, - dataset: MasterDataset + dataset: PatternGraph ): Record { const files: Record = {}; @@ -526,7 +526,7 @@ function buildRequirementsDetailFiles( function buildSingleRequirementDocument( pattern: ExtractedPattern, options: Required, - dataset: MasterDataset + dataset: PatternGraph ): RenderableDocument { const sections: SectionBlock[] = []; const emoji = getStatusEmoji(pattern.status); diff --git a/src/renderable/codecs/session.ts b/src/renderable/codecs/session.ts index f5a07cbd..a6704c01 100644 --- a/src/renderable/codecs/session.ts +++ b/src/renderable/codecs/session.ts @@ -39,7 +39,7 @@ * | groupPlannedBy | "quarter" \| "priority" \| "level" \| "none" | "none" | Group planned items | */ -import type { MasterDataset, PhaseGroup } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph, PhaseGroup } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -270,7 +270,7 @@ export function createSessionContextCodec(options?: SessionCodecOptions): Docume /** * Default Session Context Document Codec * - * Transforms MasterDataset → RenderableDocument for session context. + * Transforms PatternGraph → RenderableDocument for session context. * Shows current phase focus, active work, and planning context. */ export const SessionContextCodec = createSessionContextCodec(); @@ -297,7 +297,7 @@ export function createRemainingWorkCodec(options?: RemainingWorkCodecOptions): D /** * Default Remaining Work Document Codec * - * Transforms MasterDataset → RenderableDocument for remaining work. + * Transforms PatternGraph → RenderableDocument for remaining work. * Aggregates all incomplete work across phases. */ export const RemainingWorkCodec = createRemainingWorkCodec(); @@ -327,7 +327,7 @@ export const codecMetas = [ * Build session context document */ function buildSessionContextDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -378,7 +378,7 @@ function buildSessionContextDocument( /** * Build session status section */ -function buildSessionStatus(dataset: MasterDataset): SectionBlock[] { +function buildSessionStatus(dataset: PatternGraph): SectionBlock[] { const { counts } = dataset; const progress = completionPercentage(counts); const progressBar = renderProgressBar(counts.completed, counts.total, 20); @@ -412,7 +412,7 @@ function buildSessionStatus(dataset: MasterDataset): SectionBlock[] { * Build active work section */ function buildActiveWork( - dataset: MasterDataset, + dataset: PatternGraph, _options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -467,7 +467,7 @@ function buildActiveWork( * Build current phase context summary (links to detail file) */ function buildCurrentPhaseContextSummary( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -506,7 +506,7 @@ function buildCurrentPhaseContextSummary( * Build recent completions section */ function buildSessionRecentCompletions( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -541,7 +541,7 @@ function buildSessionRecentCompletions( /** * Build blocked items section */ -function buildBlockedItems(dataset: MasterDataset): SectionBlock[] { +function buildBlockedItems(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = []; // Find patterns that are blocked (have unmet dependencies) @@ -598,7 +598,7 @@ function getSessionPhaseSlug(phaseNumber: number, phaseName: string | undefined) * Build session phase navigation table */ function buildSessionPhaseNavigation( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -641,7 +641,7 @@ function buildSessionPhaseNavigation( * Build session phase detail files (progressive disclosure) */ function buildSessionPhaseFiles( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): Record { const files: Record = {}; @@ -664,7 +664,7 @@ function buildSessionPhaseFiles( */ function buildSessionPhaseDetailDocument( phase: PhaseGroup, - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -831,7 +831,7 @@ function buildBlockedPatternList(patterns: ExtractedPattern[]): SectionBlock[] { * Build remaining work document */ function buildRemainingWorkDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -900,7 +900,7 @@ function buildRemainingWorkDocument( * Build next actionable items section */ function buildNextActionableItems( - dataset: MasterDataset, + dataset: PatternGraph, incomplete: ExtractedPattern[], options: Required ): SectionBlock[] { @@ -957,7 +957,7 @@ function buildNextActionableItems( * Build remaining work summary */ function buildRemainingWorkSummary( - dataset: MasterDataset, + dataset: PatternGraph, incomplete: ExtractedPattern[] ): SectionBlock[] { const active = incomplete.filter((p) => isPatternActive(p.status)); @@ -998,7 +998,7 @@ function getRemainingPhaseSlug(phaseNumber: number, phaseName: string | undefine * Build remaining work phase navigation table */ function buildRemainingPhaseNavigation( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -1061,7 +1061,7 @@ function buildRemainingPhaseNavigation( * Build remaining work by priority (summary only for index) */ function buildRemainingByPrioritySummary( - dataset: MasterDataset, + dataset: PatternGraph, incomplete: ExtractedPattern[], options: Required ): SectionBlock[] { @@ -1134,7 +1134,7 @@ function buildRemainingByPrioritySummary( * Build remaining work phase detail files (progressive disclosure) */ function buildRemainingPhaseFiles( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): Record { const files: Record = {}; @@ -1157,7 +1157,7 @@ function buildRemainingPhaseFiles( */ function buildRemainingPhaseDetailDocument( phase: PhaseGroup, - dataset: MasterDataset, + dataset: PatternGraph, _options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/shape-matcher.ts b/src/renderable/codecs/shape-matcher.ts index f13973e2..8aed3475 100644 --- a/src/renderable/codecs/shape-matcher.ts +++ b/src/renderable/codecs/shape-matcher.ts @@ -2,12 +2,12 @@ * Shape Selector Matcher * * Resolves selector-based shape filters against pattern `source.file` paths - * in MasterDataset. Uses in-memory string matching (no filesystem access). + * in PatternGraph. Uses in-memory string matching (no filesystem access). * * @see CodecDrivenReferenceGeneration AD-6: In-memory glob matching */ -import type { MasterDataset } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedShape } from '../../validation-schemas/extracted-shape.js'; // ============================================================================ @@ -78,7 +78,7 @@ export function matchesShapePattern(filePath: string, pattern: string): boolean // ============================================================================ /** - * Filter shapes from MasterDataset using fine-grained ShapeSelectors. + * Filter shapes from PatternGraph using fine-grained ShapeSelectors. * * Three selector modes (DD-6): * - `{ group }` — all shapes where `shape.group` matches @@ -87,12 +87,12 @@ export function matchesShapePattern(filePath: string, pattern: string): boolean * * Returns a deduplicated list in selector iteration order. * - * @param dataset - MasterDataset with all extracted patterns + * @param dataset - PatternGraph with all extracted patterns * @param selectors - Fine-grained shape selectors * @returns Aggregated ExtractedShape array from matching selectors */ export function filterShapesBySelectors( - dataset: MasterDataset, + dataset: PatternGraph, selectors: readonly ShapeSelector[] ): readonly ExtractedShape[] { if (selectors.length === 0) return []; diff --git a/src/renderable/codecs/taxonomy.ts b/src/renderable/codecs/taxonomy.ts index 6e8d1e39..8b5ce404 100644 --- a/src/renderable/codecs/taxonomy.ts +++ b/src/renderable/codecs/taxonomy.ts @@ -9,7 +9,7 @@ * * ## TaxonomyDocumentCodec * - * Transforms MasterDataset into a RenderableDocument for taxonomy reference output. + * Transforms PatternGraph into a RenderableDocument for taxonomy reference output. * Generates TAXONOMY.md and detail files (taxonomy/*.md). * * **Purpose:** Taxonomy reference documentation with tag definitions, preset comparison, and format type reference. @@ -127,12 +127,12 @@ export function createTaxonomyCodec(options?: TaxonomyCodecOptions): DocumentCod /** * Default Taxonomy Document Codec * - * Transforms MasterDataset → RenderableDocument for taxonomy reference. + * Transforms PatternGraph → RenderableDocument for taxonomy reference. * Uses default options with all features enabled. * * @example * ```typescript - * const doc = TaxonomyDocumentCodec.decode(masterDataset); + * const doc = TaxonomyDocumentCodec.decode(patternGraph); * const markdown = renderToMarkdown(doc); * ``` */ diff --git a/src/renderable/codecs/timeline.ts b/src/renderable/codecs/timeline.ts index ae72adaa..f0c1166a 100644 --- a/src/renderable/codecs/timeline.ts +++ b/src/renderable/codecs/timeline.ts @@ -46,7 +46,7 @@ * - When checking which patterns are currently being worked on */ -import type { MasterDataset, PhaseGroup } from '../../validation-schemas/master-dataset.js'; +import type { PatternGraph, PhaseGroup } from '../../validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../validation-schemas/index.js'; import { type RenderableDocument, @@ -281,7 +281,7 @@ export function createRoadmapCodec(options?: RoadmapCodecOptions): DocumentCodec /** * Default Roadmap Document Codec * - * Transforms MasterDataset → RenderableDocument for roadmap view. + * Transforms PatternGraph → RenderableDocument for roadmap view. * Shows phases with progress, patterns grouped by phase. */ export const RoadmapDocumentCodec = createRoadmapCodec(); @@ -305,7 +305,7 @@ export function createMilestonesCodec(options?: CompletedMilestonesCodecOptions) /** * Default Completed Milestones Document Codec * - * Transforms MasterDataset → RenderableDocument for completed milestones. + * Transforms PatternGraph → RenderableDocument for completed milestones. * Shows historical completed phases and patterns. */ export const CompletedMilestonesCodec = createMilestonesCodec(); @@ -332,7 +332,7 @@ export function createCurrentWorkCodec(options?: CurrentWorkCodecOptions): Docum /** * Default Current Work Document Codec * - * Transforms MasterDataset → RenderableDocument for current work. + * Transforms PatternGraph → RenderableDocument for current work. * Shows active phases with deliverables and progress tracking. */ export const CurrentWorkCodec = createCurrentWorkCodec(); @@ -369,7 +369,7 @@ export const codecMetas = [ * Build roadmap document */ function buildRoadmapDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -414,7 +414,7 @@ function buildRoadmapDocument( /** * Build overall progress section */ -function buildOverallProgress(dataset: MasterDataset): SectionBlock[] { +function buildOverallProgress(dataset: PatternGraph): SectionBlock[] { const { counts, phaseCount } = dataset; const progress = completionPercentage(counts); const progressBar = renderProgressBar(counts.completed, counts.total, 20); @@ -444,7 +444,7 @@ function buildOverallProgress(dataset: MasterDataset): SectionBlock[] { /** * Build phase breakdown section */ -function buildPhaseBreakdown(dataset: MasterDataset): SectionBlock[] { +function buildPhaseBreakdown(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = []; sections.push(heading(2, 'Phases')); @@ -494,7 +494,7 @@ function buildPhaseSection(phase: PhaseGroup): SectionBlock[] { /** * Build quarterly timeline section */ -function buildQuarterlyTimeline(dataset: MasterDataset): SectionBlock[] { +function buildQuarterlyTimeline(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = []; const quarters = Object.keys(dataset.byQuarter).sort(); @@ -530,7 +530,7 @@ function buildQuarterlyTimeline(dataset: MasterDataset): SectionBlock[] { * Build phase navigation table with links to detail files */ function buildPhaseNavigationTable( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -587,7 +587,7 @@ export function getPhaseSlug(phaseNumber: number, phaseName: string | undefined) * Build phase detail files (progressive disclosure) */ function buildPhaseDetailFiles( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): Record { const files: Record = {}; @@ -739,7 +739,7 @@ function buildPatternDetailList(patterns: ExtractedPattern[]): SectionBlock[] { * Build completed milestones document */ function buildCompletedMilestonesDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -805,7 +805,7 @@ function buildCompletedMilestonesDocument( * Build completed summary section */ function buildCompletedSummary( - dataset: MasterDataset, + dataset: PatternGraph, completedPatterns: ExtractedPattern[] ): SectionBlock[] { const completedPhases = dataset.byPhase.filter( @@ -829,7 +829,7 @@ function buildCompletedSummary( /** * Build completed phases section */ -function buildCompletedPhases(dataset: MasterDataset): SectionBlock[] { +function buildCompletedPhases(dataset: PatternGraph): SectionBlock[] { const sections: SectionBlock[] = []; // Filter to fully completed phases @@ -873,7 +873,7 @@ function buildCompletedPhases(dataset: MasterDataset): SectionBlock[] { * Build quarterly navigation table with links to detail files */ function buildQuarterlyNavigationTable( - _dataset: MasterDataset, + _dataset: PatternGraph, completedPatterns: ExtractedPattern[], options: Required ): SectionBlock[] { @@ -948,7 +948,7 @@ function buildRecentCompletions(patterns: ExtractedPattern[], limit = 10): Secti * Build quarterly milestone detail files (progressive disclosure) */ function buildQuarterlyMilestoneFiles( - dataset: MasterDataset, + dataset: PatternGraph, completedPatterns: ExtractedPattern[], _options: Required ): Record { @@ -975,7 +975,7 @@ function buildQuarterlyMilestoneFiles( function buildQuarterDetailDocument( quarter: string, patterns: ExtractedPattern[], - dataset: MasterDataset + dataset: PatternGraph ): RenderableDocument { const sections: SectionBlock[] = []; @@ -1054,7 +1054,7 @@ function buildQuarterDetailDocument( * - Deliverables (if configured) */ function buildCurrentWorkDocument( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; @@ -1109,7 +1109,7 @@ function buildCurrentWorkDocument( * Build current work summary section */ function buildCurrentWorkSummary( - dataset: MasterDataset, + dataset: PatternGraph, _activePatterns: ExtractedPattern[] ): SectionBlock[] { // Count phases with active work @@ -1141,7 +1141,7 @@ function buildCurrentWorkSummary( * Build active phases section */ function buildActivePhases( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): SectionBlock[] { const sections: SectionBlock[] = []; @@ -1234,7 +1234,7 @@ function buildActivePatternsList( * Build current work detail files (progressive disclosure) */ function buildCurrentWorkDetailFiles( - dataset: MasterDataset, + dataset: PatternGraph, options: Required ): Record { const files: Record = {}; @@ -1257,7 +1257,7 @@ function buildCurrentWorkDetailFiles( */ function buildCurrentPhaseDetailDocument( phase: PhaseGroup, - _dataset: MasterDataset, + _dataset: PatternGraph, options: Required ): RenderableDocument { const sections: SectionBlock[] = []; diff --git a/src/renderable/codecs/types/base.ts b/src/renderable/codecs/types/base.ts index 5f7f456d..1d13d155 100644 --- a/src/renderable/codecs/types/base.ts +++ b/src/renderable/codecs/types/base.ts @@ -20,8 +20,8 @@ import { z } from 'zod'; import type { NormalizedStatus, FormatType } from '../../../taxonomy/index.js'; import type { ProjectMetadata } from '../../../config/project-config.js'; -import { MasterDatasetSchema } from '../../../validation-schemas/master-dataset.js'; -import type { MasterDataset } from '../../../validation-schemas/master-dataset.js'; +import { PatternGraphSchema } from '../../../validation-schemas/pattern-graph.js'; +import type { PatternGraph } from '../../../validation-schemas/pattern-graph.js'; import { RenderableDocumentOutputSchema } from '../shared-schema.js'; import type { RenderableDocument } from '../../schema.js'; @@ -121,7 +121,7 @@ export function mergeOptions( /** * Type alias for decode-only document codecs. * - * These codecs transform MasterDataset → RenderableDocument. + * These codecs transform PatternGraph → RenderableDocument. * The reverse direction (encode) is not supported and throws at runtime, * matching Zod's behavior for unidirectional transforms. * @@ -129,7 +129,7 @@ export function mergeOptions( * @see https://zod.dev/codecs */ export type DocumentCodec = z.ZodCodec< - typeof MasterDatasetSchema, + typeof PatternGraphSchema, typeof RenderableDocumentOutputSchema >; @@ -168,7 +168,7 @@ export interface CodecMeta { * Context provided to all codec decode functions. * * Separates extraction products (dataset) from runtime context - * (project metadata, workflow, tag overrides). This keeps MasterDataset + * (project metadata, workflow, tag overrides). This keeps PatternGraph * as a pure read model (ADR-006) while giving codecs access to * config-derived runtime data. * @@ -177,7 +177,7 @@ export interface CodecMeta { */ export interface CodecContext { /** The extraction read model — patterns, views, indexes */ - readonly dataset: MasterDataset; + readonly dataset: PatternGraph; /** Project identity metadata (package name, purpose, license, regeneration commands) */ readonly projectMetadata?: ProjectMetadata; /** Format type example overrides for TaxonomyCodec */ @@ -242,8 +242,8 @@ export function getCodecContextEnrichment(): CodecContextEnrichment { * across ~24 codec factories. * * The public-facing `decode` parameter receives a `CodecContext` wrapper, - * while the internal Zod boundary still operates on `MasterDataset` directly. - * This keeps MasterDataset as a pure read model (ADR-006) and allows the + * while the internal Zod boundary still operates on `PatternGraph` directly. + * This keeps PatternGraph as a pure read model (ADR-006) and allows the * context to be extended with runtime fields (e.g. projectMetadata) without * touching every Zod schema. * @@ -253,8 +253,8 @@ export function getCodecContextEnrichment(): CodecContextEnrichment { export function createDecodeOnlyCodec( decode: (context: CodecContext) => RenderableDocument ): DocumentCodec { - return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { - decode: (dataset: MasterDataset) => decode({ dataset, ..._contextEnrichment }), + return z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { + decode: (dataset: PatternGraph) => decode({ dataset, ..._contextEnrichment }), encode: (): never => { throw new Error('Codec is decode-only. See zod-codecs.md'); }, diff --git a/src/renderable/codecs/validation-rules.ts b/src/renderable/codecs/validation-rules.ts index bcde159e..0b4434be 100644 --- a/src/renderable/codecs/validation-rules.ts +++ b/src/renderable/codecs/validation-rules.ts @@ -8,7 +8,7 @@ * * ## ValidationRulesCodec * - * Transforms MasterDataset into a RenderableDocument for Process Guard validation + * Transforms PatternGraph into a RenderableDocument for Process Guard validation * rules reference. Generates VALIDATION-RULES.md and detail files (validation/*.md). * * **Purpose:** Process Guard validation rules reference with FSM diagrams and protection level matrix. @@ -238,12 +238,12 @@ export function createValidationRulesCodec(options?: ValidationRulesCodecOptions /** * Default ValidationRules Document Codec * - * Transforms MasterDataset -> RenderableDocument for validation rules reference. + * Transforms PatternGraph -> RenderableDocument for validation rules reference. * Uses default options with all features enabled. * * @example * ```typescript - * const doc = ValidationRulesCodec.decode(masterDataset); + * const doc = ValidationRulesCodec.decode(patternGraph); * const markdown = renderToMarkdown(doc); * ``` */ diff --git a/src/renderable/generate.ts b/src/renderable/generate.ts index eb008d9f..7b9e3f0d 100644 --- a/src/renderable/generate.ts +++ b/src/renderable/generate.ts @@ -14,14 +14,14 @@ * * ### When to Use * - * - When generating specific document types from MasterDataset + * - When generating specific document types from PatternGraph * - When needing high-level generation API without direct codec usage * - When building custom documentation workflows * - * Flow: MasterDataset → Codec → RenderableDocument → Renderer → Markdown + * Flow: PatternGraph → Codec → RenderableDocument → Renderer → Markdown */ -import type { MasterDataset } from '../validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../validation-schemas/pattern-graph.js'; import type { RenderableDocument } from './schema.js'; import { renderDocumentWithFiles, type OutputFile } from './render.js'; import { Result } from '../types/result.js'; @@ -152,7 +152,7 @@ export const DOCUMENT_TYPES = { }, index: { outputPath: 'INDEX.md', - description: 'Navigation hub with editorial preamble and MasterDataset statistics', + description: 'Navigation hub with editorial preamble and PatternGraph statistics', }, } as const; @@ -388,13 +388,13 @@ function resolveCodec(type: DocumentType, options?: CodecOptions): DocumentCodec * explicit error handling without try/catch at the call site. * * @param type - Document type to generate - * @param dataset - MasterDataset with pattern data + * @param dataset - PatternGraph with pattern data * @param options - Optional codec-specific options * @returns Result containing OutputFile[] on success, or GenerationError on failure * * @example * ```typescript - * const result = generateDocumentSafe("patterns", masterDataset); + * const result = generateDocumentSafe("patterns", patternGraph); * if (Result.isOk(result)) { * for (const file of result.value) { * fs.writeFileSync(file.path, file.content); @@ -406,7 +406,7 @@ function resolveCodec(type: DocumentType, options?: CodecOptions): DocumentCodec */ export function generateDocumentSafe( type: DocumentType, - dataset: MasterDataset, + dataset: PatternGraph, options?: CodecOptions, contextEnrichment?: CodecContextEnrichment ): Result { @@ -427,7 +427,7 @@ export function generateDocumentSafe( } try { - // Decode: MasterDataset → RenderableDocument (with error handling) + // Decode: PatternGraph → RenderableDocument (with error handling) let doc: RenderableDocument; try { doc = codec.decode(dataset) as RenderableDocument; @@ -464,7 +464,7 @@ export function generateDocumentSafe( * Generate a single document type * * @param type - Document type to generate - * @param dataset - MasterDataset with pattern data + * @param dataset - PatternGraph with pattern data * @param options - Optional codec-specific options (e.g., changedFiles for PR changes) * @returns Array of output files (main + additional for progressive disclosure) * @@ -479,17 +479,17 @@ export function generateDocumentSafe( * @example * ```typescript * // Without options (uses default codec) - * const files = generateDocument("patterns", masterDataset); + * const files = generateDocument("patterns", patternGraph); * * // With options (uses factory function) - * const files = generateDocument("pr-changes", masterDataset, { + * const files = generateDocument("pr-changes", patternGraph, { * "pr-changes": { changedFiles: ["src/foo.ts"], releaseFilter: "v0.2.0" } * }); * ``` */ export function generateDocument( type: DocumentType, - dataset: MasterDataset, + dataset: PatternGraph, options?: CodecOptions, contextEnrichment?: CodecContextEnrichment ): OutputFile[] { @@ -506,7 +506,7 @@ export function generateDocument( } try { - // Decode: MasterDataset → RenderableDocument + // Decode: PatternGraph → RenderableDocument const doc = codec.decode(dataset) as RenderableDocument; // Render: RenderableDocument → OutputFile[] @@ -523,14 +523,14 @@ export function generateDocument( * Generate multiple document types * * @param types - Document types to generate - * @param dataset - MasterDataset with pattern data + * @param dataset - PatternGraph with pattern data * @param options - Optional codec-specific options * @param contextEnrichment - Optional runtime context (projectMetadata, tagExampleOverrides) * @returns Array of all output files */ export function generateDocuments( types: DocumentType[], - dataset: MasterDataset, + dataset: PatternGraph, options?: CodecOptions, contextEnrichment?: CodecContextEnrichment ): OutputFile[] { @@ -547,13 +547,13 @@ export function generateDocuments( /** * Generate all document types * - * @param dataset - MasterDataset with pattern data + * @param dataset - PatternGraph with pattern data * @param options - Optional codec-specific options * @param contextEnrichment - Optional runtime context (projectMetadata, tagExampleOverrides) * @returns Array of all output files */ export function generateAllDocuments( - dataset: MasterDataset, + dataset: PatternGraph, options?: CodecOptions, contextEnrichment?: CodecContextEnrichment ): OutputFile[] { diff --git a/src/renderable/index.ts b/src/renderable/index.ts index 887c3f3d..6976c097 100644 --- a/src/renderable/index.ts +++ b/src/renderable/index.ts @@ -16,7 +16,7 @@ * * Architecture: * ``` - * MasterDataset → Document Codecs → RenderableDocument → Universal Renderer → Markdown + * PatternGraph → Document Codecs → RenderableDocument → Universal Renderer → Markdown * ``` * * Key Exports: diff --git a/src/renderable/schema.ts b/src/renderable/schema.ts index a59832c9..4b71a0c0 100644 --- a/src/renderable/schema.ts +++ b/src/renderable/schema.ts @@ -11,7 +11,7 @@ * ## RenderableDocument Schema * * Universal intermediate format for all generated documentation. - * Document codecs transform MasterDataset into this format, + * Document codecs transform PatternGraph into this format, * then the universal renderer converts it to markdown. * * ### When to Use diff --git a/src/validation-schemas/index.ts b/src/validation-schemas/index.ts index 3a24fbae..ab98bd33 100644 --- a/src/validation-schemas/index.ts +++ b/src/validation-schemas/index.ts @@ -179,11 +179,11 @@ export { PhaseGroupSchema, SourceViewsSchema, RelationshipEntrySchema, - MasterDatasetSchema, - type MasterDataset, + PatternGraphSchema, + type PatternGraph, type StatusGroups, type StatusCounts, type PhaseGroup, type SourceViews, type RelationshipEntry, -} from './master-dataset.js'; +} from './pattern-graph.js'; diff --git a/src/validation-schemas/master-dataset.ts b/src/validation-schemas/pattern-graph.ts similarity index 96% rename from src/validation-schemas/master-dataset.ts rename to src/validation-schemas/pattern-graph.ts index 00eacb2b..50cc9d62 100644 --- a/src/validation-schemas/master-dataset.ts +++ b/src/validation-schemas/pattern-graph.ts @@ -1,19 +1,19 @@ /** * @architect * @architect-validation @architect-core - * @architect-pattern MasterDataset + * @architect-pattern PatternGraph * @architect-status completed * @architect-uses Zod, ExtractedPattern, TagRegistry * @architect-used-by Orchestrator, SectionRenderer, ReportCodecs * @architect-usecase "When providing pre-computed views to section renderers" * @architect-usecase "When eliminating redundant filtering across generators" - * @architect-extract-shapes MasterDatasetSchema, StatusGroupsSchema, StatusCountsSchema, PhaseGroupSchema, SourceViewsSchema, RelationshipEntrySchema, ArchIndexSchema + * @architect-extract-shapes PatternGraphSchema, StatusGroupsSchema, StatusCountsSchema, PhaseGroupSchema, SourceViewsSchema, RelationshipEntrySchema, ArchIndexSchema * @architect-arch-role read-model * @architect-arch-context api * @architect-arch-layer domain * @architect-include codec-transformation * - * ## MasterDataset - Unified Pattern Views Schema + * ## PatternGraph - Unified Pattern Views Schema * * Defines the schema for a pre-computed dataset that holds all extracted patterns * along with derived views (by status, phase, quarter, category, source). This enables @@ -51,7 +51,7 @@ import { TagRegistrySchema } from './tag-registry.js'; * - active: active * - planned: roadmap, deferred, or undefined/unknown * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export const StatusGroupsSchema = z.object({ /** Patterns with status 'completed' */ @@ -67,7 +67,7 @@ export const StatusGroupsSchema = z.object({ /** * Status counts for aggregate statistics * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export const StatusCountsSchema = z.object({ /** Number of completed patterns */ @@ -89,7 +89,7 @@ export const StatusCountsSchema = z.object({ * Groups patterns by their phase number, with pre-computed * status counts for each phase. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export const PhaseGroupSchema = z.object({ /** Phase number (e.g., 1, 2, 3, 14, 39) */ @@ -108,7 +108,7 @@ export const PhaseGroupSchema = z.object({ /** * Source-based views for different data origins * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export const SourceViewsSchema = z.object({ /** Patterns from TypeScript files (.ts) */ @@ -146,7 +146,7 @@ export const ImplementationRefSchema = z.object({ * * Maps pattern names to their relationship metadata. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ export const RelationshipEntrySchema = z.object({ /** Patterns this pattern uses (from @architect-uses) */ @@ -260,9 +260,9 @@ export const SequenceIndexSchema = z.record(z.string().trim().min(1), SequenceIn * Contains raw patterns plus pre-computed views and statistics. * This is the primary data structure passed to generators and sections. * - * @architect-shape master-dataset + * @architect-shape pattern-graph */ -export const MasterDatasetSchema = z.object({ +export const PatternGraphSchema = z.object({ // ───────────────────────────────────────────────────────────────────────── // Raw Data // ───────────────────────────────────────────────────────────────────────── @@ -338,7 +338,7 @@ export const MasterDatasetSchema = z.object({ // Type Exports // ═══════════════════════════════════════════════════════════════════════════ -export type MasterDataset = z.infer; +export type PatternGraph = z.infer; export type StatusGroups = z.infer; export type StatusCounts = z.infer; export type PhaseGroup = z.infer; diff --git a/tests/features/api/context-assembly/context-assembler.feature b/tests/features/api/context-assembly/context-assembler.feature index df1569b2..eed9ae20 100644 --- a/tests/features/api/context-assembly/context-assembler.feature +++ b/tests/features/api/context-assembly/context-assembler.feature @@ -5,7 +5,7 @@ Feature: Context Assembler - Session-Oriented Context Bundle Builder Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and - buildOverview() pure functions that operate on MasterDataset. + buildOverview() pure functions that operate on PatternGraph. Rule: assembleContext produces session-tailored context bundles diff --git a/tests/features/api/process-state-api.feature b/tests/features/api/pattern-graph-api.feature similarity index 96% rename from tests/features/api/process-state-api.feature rename to tests/features/api/pattern-graph-api.feature index 0eefa59c..e99aec33 100644 --- a/tests/features/api/process-state-api.feature +++ b/tests/features/api/pattern-graph-api.feature @@ -1,9 +1,9 @@ @architect -@architect-implements:ProcessStateAPICLI +@architect-implements:PatternGraphAPICLI @architect-status:completed @architect-unlock-reason:Retroactive-completion-during-rebrand -@behavior @process-state-api -@architect-pattern:ProcessStateAPITesting +@behavior @pattern-graph-api +@architect-pattern:PatternGraphAPITesting @architect-product-area:DataAPI Feature: Process State API Programmatic interface for querying delivery process state. @@ -12,15 +12,15 @@ Feature: Process State API **Problem:** - Markdown generation is not ideal for programmatic access - Claude Code needs structured data to answer process questions - - Multiple queries require redundant parsing of MasterDataset + - Multiple queries require redundant parsing of PatternGraph **Solution:** - - ProcessStateAPI wraps MasterDataset with typed query methods + - PatternGraphAPI wraps PatternGraph with typed query methods - Returns structured data suitable for programmatic consumption - Integrates FSM validation for transition checks Background: - Given a test MasterDataset is initialized + Given a test PatternGraph is initialized # ========================================================================== # Status Queries diff --git a/tests/features/api/session-support/handoff-generator.feature b/tests/features/api/session-support/handoff-generator.feature index 0905a75d..5ffb8248 100644 --- a/tests/features/api/session-support/handoff-generator.feature +++ b/tests/features/api/session-support/handoff-generator.feature @@ -10,8 +10,8 @@ Feature: Handoff Generator - Session-End State Summary documentation is manual or forgotten. **Solution:** - HandoffGenerator assembles a structured handoff document from ProcessStateAPI - and MasterDataset, capturing completed work, remaining items, discovered + HandoffGenerator assembles a structured handoff document from PatternGraphAPI + and PatternGraph, capturing completed work, remaining items, discovered issues, and next-session priorities. Rule: Handoff generates compact session state summary diff --git a/tests/features/api/stub-integration/stub-resolver.feature b/tests/features/api/stub-integration/stub-resolver.feature index 52bd0b05..18814332 100644 --- a/tests/features/api/stub-integration/stub-resolver.feature +++ b/tests/features/api/stub-integration/stub-resolver.feature @@ -10,7 +10,7 @@ Feature: Stub Resolver - Design Stub Discovery and Resolution **Solution:** StubResolver functions identify, resolve, and group stubs from - the MasterDataset with filesystem existence checks. + the PatternGraph with filesystem existence checks. Rule: Stubs are identified by path or target metadata diff --git a/tests/features/behavior/architecture-diagrams/arch-index.feature b/tests/features/behavior/architecture-diagrams/arch-index.feature index a0e593cd..adc8abe9 100644 --- a/tests/features/behavior/architecture-diagrams/arch-index.feature +++ b/tests/features/behavior/architecture-diagrams/arch-index.feature @@ -5,7 +5,7 @@ @architect-implements:ArchitectureDiagramGeneration @architect-product-area:Generation @architecture -Feature: Architecture Index in MasterDataset +Feature: Architecture Index in PatternGraph As a documentation generator I want an archIndex built during dataset transformation @@ -34,7 +34,7 @@ Feature: Architecture Index in MasterDataset | Handler1 | command-handler | orders | application | | Handler2 | command-handler | inventory | application | | Proj1 | projection | orders | application | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex byRole for "command-handler" should contain 2 patterns And archIndex byRole for "projection" should contain 1 pattern @@ -54,7 +54,7 @@ Feature: Architecture Index in MasterDataset | OrderHandler | command-handler | orders | application | | OrderProj | projection | orders | application | | InvHandler | command-handler | inventory | application | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex byContext for "orders" should contain 2 patterns And archIndex byContext for "inventory" should contain 1 pattern @@ -74,7 +74,7 @@ Feature: Architecture Index in MasterDataset | Decider1 | decider | orders | domain | | Handler1 | command-handler | orders | application | | Infra1 | infrastructure | - | infrastructure | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex byLayer should have counts: | layer | count | | domain | 1 | @@ -101,7 +101,7 @@ Feature: Architecture Index in MasterDataset And a pattern without arch annotations: | name | | NoArchTags | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex all should contain 3 patterns And archIndex all should not contain pattern "NoArchTags" @@ -123,7 +123,7 @@ Feature: Architecture Index in MasterDataset | name | | NotAnnotated1 | | NotAnnotated2 | - When transformToMasterDataset runs + When transformToPatternGraph runs Then archIndex all should contain 1 pattern And archIndex all should contain pattern "Annotated" diff --git a/tests/features/behavior/codecs/convention-extractor.feature b/tests/features/behavior/codecs/convention-extractor.feature index 5d5987fe..b4759008 100644 --- a/tests/features/behavior/codecs/convention-extractor.feature +++ b/tests/features/behavior/codecs/convention-extractor.feature @@ -7,7 +7,7 @@ @architect-product-area:Generation Feature: Convention Extractor - Extracts convention content from MasterDataset decision records + Extracts convention content from PatternGraph decision records tagged with @architect-convention. Produces structured ConventionBundles with rule content, tables, and invariant/rationale metadata. @@ -21,13 +21,13 @@ Feature: Convention Extractor @happy-path @edge-case Scenario: Empty convention tags returns empty array - Given an empty MasterDataset + Given an empty PatternGraph When extracting conventions for no tags Then the convention result is empty @edge-case Scenario: No matching patterns returns empty array - Given a MasterDataset with patterns but no convention tags + Given a PatternGraph with patterns but no convention tags When extracting conventions for tag "fsm-rules" Then the convention result is empty diff --git a/tests/features/behavior/codecs/generated-doc-quality.feature b/tests/features/behavior/codecs/generated-doc-quality.feature index bdc78b60..27b3b2bc 100644 --- a/tests/features/behavior/codecs/generated-doc-quality.feature +++ b/tests/features/behavior/codecs/generated-doc-quality.feature @@ -77,5 +77,5 @@ Feature: Generated Documentation Quality Improvements | Term | | Scanner | | Codec | - | MasterDataset | + | PatternGraph | | RenderableDocument | diff --git a/tests/features/behavior/codecs/planning-codecs.feature b/tests/features/behavior/codecs/planning-codecs.feature index 159e8b7f..36bf05c7 100644 --- a/tests/features/behavior/codecs/planning-codecs.feature +++ b/tests/features/behavior/codecs/planning-codecs.feature @@ -7,7 +7,7 @@ @behavior @planning-codecs Feature: Planning Document Codecs The planning codecs (PlanningChecklistCodec, SessionPlanCodec, SessionFindingsCodec) - transform MasterDataset into RenderableDocuments for planning and retrospective views. + transform PatternGraph into RenderableDocuments for planning and retrospective views. **Problem:** - Need to generate planning checklists, session plans, and findings documents from patterns @@ -34,14 +34,14 @@ Feature: Planning Document Codecs @happy-path @edge-case Scenario: No actionable phases produces empty message - Given a MasterDataset with no actionable phases + Given a PatternGraph with no actionable phases When decoding with PlanningChecklistCodec Then the document title is "Planning Checklist" And the document contains "No active or actionable phases" @happy-path Scenario: Summary shows phases to plan count - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with PlanningChecklistCodec Then the document title is "Planning Checklist" And the summary table shows: @@ -52,7 +52,7 @@ Feature: Planning Document Codecs @happy-path Scenario: Pre-planning questions section - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with PlanningChecklistCodec Then the document contains a "Pre-Planning" section And the pre-planning section contains checklist items: @@ -64,21 +64,21 @@ Feature: Planning Document Codecs @happy-path Scenario: Definition of Done with deliverables - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with PlanningChecklistCodec Then the document contains a "Definition of Done" section And the DoD section shows deliverable items @happy-path Scenario: Acceptance criteria from scenarios - Given a MasterDataset with patterns with scenarios + Given a PatternGraph with patterns with scenarios When decoding with PlanningChecklistCodec Then the document contains a "Definition of Done" section And the DoD section shows acceptance criteria from scenarios @happy-path Scenario: Risk assessment section - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with includeRiskAssessment enabled Then the document contains a "Risk Assessment" section And the risk assessment contains checklist items: @@ -89,19 +89,19 @@ Feature: Planning Document Codecs @happy-path Scenario: Dependency status shows met vs unmet - Given a MasterDataset with patterns with dependencies + Given a PatternGraph with patterns with dependencies When decoding with PlanningChecklistCodec Then the document shows dependency status And met dependencies show completed marker And unmet dependencies show pending marker Scenario: forActivePhases option - Given a MasterDataset with active and planned patterns + Given a PatternGraph with active and planned patterns When decoding with forActivePhases enabled and forNextActionable disabled Then only active phases are shown in checklist Scenario: forNextActionable option - Given a MasterDataset with active and planned patterns + Given a PatternGraph with active and planned patterns When decoding with forActivePhases disabled and forNextActionable enabled Then only next actionable phases are shown in checklist @@ -117,14 +117,14 @@ Feature: Planning Document Codecs @happy-path @edge-case Scenario: No phases to plan produces empty message - Given a MasterDataset with only completed patterns + Given a PatternGraph with only completed patterns When decoding with SessionPlanCodec Then the document title is "Session Implementation Plan" And the document contains "No phases match the status filter" @happy-path Scenario: Summary shows status counts - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with SessionPlanCodec Then the document title is "Session Implementation Plan" And the summary table shows: @@ -135,39 +135,39 @@ Feature: Planning Document Codecs @happy-path Scenario: Implementation approach from useCases - Given a MasterDataset with patterns with useCases + Given a PatternGraph with patterns with useCases When decoding with SessionPlanCodec Then the document contains an "Implementation Approach" section And the implementation approach shows use cases @happy-path Scenario: Deliverables rendering - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with SessionPlanCodec Then the document contains a "Deliverables" section And the deliverables section shows items with status @happy-path Scenario: Acceptance criteria with steps - Given a MasterDataset with patterns with scenarios + Given a PatternGraph with patterns with scenarios When decoding with SessionPlanCodec Then the document contains an "Acceptance Criteria" section And the acceptance criteria shows scenario names @happy-path Scenario: Business rules section - Given a MasterDataset with patterns with rules + Given a PatternGraph with patterns with rules When decoding with SessionPlanCodec Then the document contains a "Business Rules" section And the business rules section shows rule names Scenario: statusFilter option for active only - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with statusFilter set to active only Then only active patterns are shown in plan Scenario: statusFilter option for planned only - Given a MasterDataset with planning patterns + Given a PatternGraph with planning patterns When decoding with statusFilter set to planned only Then only planned patterns are shown in plan @@ -183,14 +183,14 @@ Feature: Planning Document Codecs @happy-path @edge-case Scenario: No findings produces empty message - Given a MasterDataset with patterns without findings + Given a PatternGraph with patterns without findings When decoding with SessionFindingsCodec Then the document title is "Session Findings" And the document contains "No gaps, improvements, risks, or learnings" @happy-path Scenario: Summary shows finding type counts - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with SessionFindingsCodec Then the document title is "Session Findings" And the summary table shows: @@ -202,53 +202,53 @@ Feature: Planning Document Codecs @happy-path Scenario: Gaps section - Given a MasterDataset with patterns with discovered gaps + Given a PatternGraph with patterns with discovered gaps When decoding with SessionFindingsCodec Then the document contains a "Gaps" section And the gaps section shows discovered gaps @happy-path Scenario: Improvements section - Given a MasterDataset with patterns with discovered improvements + Given a PatternGraph with patterns with discovered improvements When decoding with SessionFindingsCodec Then the document contains a "Improvements" section And the improvements section shows discovered improvements @happy-path Scenario: Risks section includes risk field - Given a MasterDataset with patterns with discovered risks + Given a PatternGraph with patterns with discovered risks When decoding with SessionFindingsCodec Then the document contains a "Risks" section And the risks section shows discovered risks @happy-path Scenario: Learnings section - Given a MasterDataset with patterns with discovered learnings + Given a PatternGraph with patterns with discovered learnings When decoding with SessionFindingsCodec Then the document contains a "Learnings" section And the learnings section shows discovered learnings Scenario: groupBy category option - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with groupBy set to category Then findings are grouped by finding type Scenario: groupBy phase option - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with groupBy set to phase Then findings are grouped by source phase Scenario: groupBy type option - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with groupBy set to type Then findings are grouped by finding type Scenario: showSourcePhase option enabled - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with showSourcePhase enabled Then findings show phase attribution Scenario: showSourcePhase option disabled - Given a MasterDataset with patterns with findings + Given a PatternGraph with patterns with findings When decoding with showSourcePhase disabled Then findings do not show phase attribution diff --git a/tests/features/behavior/codecs/pr-changes-codec-options.feature b/tests/features/behavior/codecs/pr-changes-codec-options.feature index f678ca82..bd7606ba 100644 --- a/tests/features/behavior/codecs/pr-changes-codec-options.feature +++ b/tests/features/behavior/codecs/pr-changes-codec-options.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation @behavior @pr-changes-codec Feature: PR Changes Codec - Options and Filters - The PrChangesCodec transforms MasterDataset into RenderableDocument for + The PrChangesCodec transforms PatternGraph into RenderableDocument for PR-scoped documentation. It filters patterns by changed files and/or release version tags, groups by phase or priority, and generates review-focused output. @@ -36,7 +36,7 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Review checklist generated with standard items - Given a MasterDataset with PR-relevant patterns + Given a PatternGraph with PR-relevant patterns When decoding with includeReviewChecklist enabled Then the document contains a "Review Checklist" section And the review checklist contains standard items: @@ -46,27 +46,27 @@ Feature: PR Changes Codec - Options and Filters | Documentation updated if needed | Scenario: Review checklist includes completed patterns item when applicable - Given a MasterDataset with completed patterns + Given a PatternGraph with completed patterns When decoding with includeReviewChecklist enabled Then the review checklist contains "Completed patterns verified working" Scenario: Review checklist includes active work item when applicable - Given a MasterDataset with active patterns + Given a PatternGraph with active patterns When decoding with includeReviewChecklist enabled Then the review checklist contains "Active work is in a consistent state" Scenario: Review checklist includes dependencies item when patterns have dependencies - Given a MasterDataset with patterns with dependencies + Given a PatternGraph with patterns with dependencies When decoding with includeReviewChecklist enabled Then the review checklist contains "Dependencies are satisfied" Scenario: Review checklist includes deliverables item when patterns have deliverables - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with includeReviewChecklist enabled Then the review checklist contains "Deliverables tracked in feature files" Scenario: No review checklist when includeReviewChecklist is disabled - Given a MasterDataset with PR-relevant patterns + Given a PatternGraph with PR-relevant patterns When decoding with includeReviewChecklist disabled Then the document does not contain a "Review Checklist" section @@ -82,23 +82,23 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Dependencies section shows depends on relationships - Given a MasterDataset with patterns with dependsOn relationships + Given a PatternGraph with patterns with dependsOn relationships When decoding with includeDependencies enabled Then the document contains a "Dependencies" section And the dependencies section contains "Depends On" subsection Scenario: Dependencies section shows enables relationships - Given a MasterDataset with patterns with enables relationships + Given a PatternGraph with patterns with enables relationships When decoding with includeDependencies enabled Then the dependencies section contains "Enables" subsection Scenario: No dependencies section when patterns have no dependencies - Given a MasterDataset with patterns without dependencies + Given a PatternGraph with patterns without dependencies When decoding with includeDependencies enabled Then the document does not contain a "Dependencies" section Scenario: No dependencies section when includeDependencies is disabled - Given a MasterDataset with patterns with dependencies + Given a PatternGraph with patterns with dependencies When decoding with includeDependencies disabled Then the document does not contain a "Dependencies" section @@ -114,12 +114,12 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Patterns filtered by changedFiles match - Given a MasterDataset with patterns from various files + Given a PatternGraph with patterns from various files When decoding with changedFiles filter matching specific patterns Then only patterns from those files are included Scenario: changedFiles filter matches partial paths - Given a MasterDataset with patterns from various files + Given a PatternGraph with patterns from various files When decoding with changedFiles filter for a directory path Then patterns under that directory are included @@ -131,7 +131,7 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Patterns filtered by release version - Given a MasterDataset with patterns with different release deliverables + Given a PatternGraph with patterns with different release deliverables When decoding with releaseFilter "v0.2.0" Then only patterns with v0.2.0 deliverables are included @@ -143,12 +143,12 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Combined filters match patterns meeting either criterion - Given a MasterDataset with patterns matching file or release + Given a PatternGraph with patterns matching file or release When decoding with both changedFiles and releaseFilter Then patterns matching either filter are included Scenario: Patterns matching both criteria are not duplicated - Given a MasterDataset with a pattern matching both file and release + Given a PatternGraph with a pattern matching both file and release When decoding with both changedFiles and releaseFilter Then the pattern appears only once @@ -164,11 +164,11 @@ Feature: PR Changes Codec - Options and Filters @happy-path Scenario: Roadmap patterns are excluded - Given a MasterDataset with patterns of all statuses + Given a PatternGraph with patterns of all statuses When decoding with PrChangesCodec Then roadmap patterns are not included Scenario: Deferred patterns are excluded - Given a MasterDataset with deferred patterns + Given a PatternGraph with deferred patterns When decoding with PrChangesCodec Then deferred patterns are not included diff --git a/tests/features/behavior/codecs/pr-changes-codec-rendering.feature b/tests/features/behavior/codecs/pr-changes-codec-rendering.feature index 95dd2642..e4b53715 100644 --- a/tests/features/behavior/codecs/pr-changes-codec-rendering.feature +++ b/tests/features/behavior/codecs/pr-changes-codec-rendering.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation @behavior @pr-changes-codec Feature: PR Changes Codec - Core Rendering - The PrChangesCodec transforms MasterDataset into RenderableDocument for + The PrChangesCodec transforms PatternGraph into RenderableDocument for PR-scoped documentation. It filters patterns by changed files and/or release version tags, groups by phase or priority, and generates review-focused output. @@ -36,7 +36,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path @edge-case Scenario: No changes when no patterns match changedFiles filter - Given a MasterDataset with active patterns + Given a PatternGraph with active patterns When decoding with changedFiles filter for non-matching paths Then the document title is "Pull Request Changes" And the document contains "No Changes" section @@ -44,14 +44,14 @@ Feature: PR Changes Codec - Core Rendering @happy-path @edge-case Scenario: No changes when no patterns match releaseFilter - Given a MasterDataset with active patterns + Given a PatternGraph with active patterns When decoding with releaseFilter "v9.9.9" Then the document contains "No Changes" section And the no changes message mentions the release filter @happy-path @edge-case Scenario: No changes with combined filters when nothing matches - Given a MasterDataset with active patterns + Given a PatternGraph with active patterns When decoding with changedFiles and releaseFilter that match nothing Then the document contains "No Changes" section And the no changes message mentions both filters @@ -68,7 +68,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Summary section shows pattern counts - Given a MasterDataset with PR-relevant patterns + Given a PatternGraph with PR-relevant patterns When decoding with PrChangesCodec Then the document title is "Pull Request Changes" And the document contains a "Summary" section @@ -80,13 +80,13 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Summary shows release tag when releaseFilter is set - Given a MasterDataset with PR-relevant patterns with deliverables + Given a PatternGraph with PR-relevant patterns with deliverables When decoding with releaseFilter "v0.2.0" Then the summary table includes release tag row @happy-path Scenario: Summary shows files filter count when changedFiles is set - Given a MasterDataset with PR-relevant patterns + Given a PatternGraph with PR-relevant patterns When decoding with changedFiles filter for matching paths Then the summary table includes files filter row @@ -102,7 +102,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Changes grouped by phase with default sortBy - Given a MasterDataset with patterns in multiple phases + Given a PatternGraph with patterns in multiple phases When decoding with PrChangesCodec Then the document contains a "Changes by Phase" section And the document contains phase headings: @@ -111,7 +111,7 @@ Feature: PR Changes Codec - Core Rendering | Phase 2 | Scenario: Pattern details shown within phase groups - Given a MasterDataset with patterns in multiple phases + Given a PatternGraph with patterns in multiple phases When decoding with PrChangesCodec Then phase groups contain pattern headings with status emoji @@ -127,7 +127,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Changes grouped by priority - Given a MasterDataset with patterns with different priorities + Given a PatternGraph with patterns with different priorities When decoding with sortBy "priority" Then the document contains a "Changes by Priority" section And the document contains priority headings: @@ -137,7 +137,7 @@ Feature: PR Changes Codec - Core Rendering | Low Priority | Scenario: Priority groups show correct patterns - Given a MasterDataset with patterns with different priorities + Given a PatternGraph with patterns with different priorities When decoding with sortBy "priority" Then high priority section contains high priority patterns And low priority section contains low priority patterns @@ -154,7 +154,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Flat changes list with workflow sort - Given a MasterDataset with PR-relevant patterns + Given a PatternGraph with PR-relevant patterns When decoding with sortBy "workflow" Then the document contains a "Changes" section And the changes section contains pattern entries @@ -171,7 +171,7 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Pattern detail shows metadata table - Given a MasterDataset with a detailed pattern + Given a PatternGraph with a detailed pattern When decoding with PrChangesCodec Then pattern details include metadata table with: | property | @@ -179,14 +179,14 @@ Feature: PR Changes Codec - Core Rendering | Phase | Scenario: Pattern detail shows business value when available - Given a MasterDataset with a pattern with business value + Given a PatternGraph with a pattern with business value When decoding with PrChangesCodec Then pattern details include metadata table with: | property | | Business Value | Scenario: Pattern detail shows description - Given a MasterDataset with a detailed pattern + Given a PatternGraph with a detailed pattern When decoding with PrChangesCodec Then pattern details include description text @@ -202,17 +202,17 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Deliverables shown when patterns have deliverables - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with includeDeliverables enabled Then the document contains deliverables lists Scenario: Deliverables filtered by release when releaseFilter is set - Given a MasterDataset with patterns with mixed release deliverables + Given a PatternGraph with patterns with mixed release deliverables When decoding with releaseFilter "v0.2.0" and includeDeliverables Then only deliverables for "v0.2.0" are shown Scenario: No deliverables section when includeDeliverables is disabled - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with includeDeliverables disabled Then the document does not contain deliverables lists @@ -228,12 +228,12 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Acceptance criteria rendered when patterns have scenarios - Given a MasterDataset with patterns with scenarios + Given a PatternGraph with patterns with scenarios When decoding with PrChangesCodec Then the document contains "Acceptance Criteria" sections Scenario: Acceptance criteria shows scenario steps - Given a MasterDataset with patterns with scenarios and steps + Given a PatternGraph with patterns with scenarios and steps When decoding with PrChangesCodec Then acceptance criteria sections contain step lists @@ -245,12 +245,12 @@ Feature: PR Changes Codec - Core Rendering @happy-path Scenario: Business rules rendered when patterns have rules - Given a MasterDataset with patterns with business rules + Given a PatternGraph with patterns with business rules When decoding with PrChangesCodec Then the document contains "Business Rules" sections Scenario: Business rules show rule names and verification info - Given a MasterDataset with patterns with business rules + Given a PatternGraph with patterns with business rules When decoding with PrChangesCodec Then business rules sections contain rule names And business rules sections contain verification info diff --git a/tests/features/behavior/codecs/reference-codec-core.feature b/tests/features/behavior/codecs/reference-codec-core.feature index bf5a4d5d..cffb9ac3 100644 --- a/tests/features/behavior/codecs/reference-codec-core.feature +++ b/tests/features/behavior/codecs/reference-codec-core.feature @@ -22,7 +22,7 @@ Feature: Reference Codec - Core Behavior @happy-path @edge-case Scenario: Codec with no matching content produces fallback message Given a reference config with convention tags "nonexistent" and behavior tags "nonexistent" - And an empty MasterDataset + And an empty PatternGraph When decoding at detail level "standard" Then the document title matches the config title And the document contains a no-content fallback paragraph @@ -35,7 +35,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Convention rules appear as H2 headings with content Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention-tagged pattern: + And a PatternGraph with a convention-tagged pattern: | convention | ruleName | invariant | | fsm-rules | FSM Transitions | Only valid transitions apply | When decoding at detail level "detailed" @@ -45,7 +45,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Convention tables are rendered in the document Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with a table + And a PatternGraph with a convention pattern with a table When decoding at detail level "detailed" Then the document has at least 1 table @@ -57,7 +57,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Summary level omits narrative and rationale Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with narrative and rationale + And a PatternGraph with a convention pattern with narrative and rationale When decoding at detail level "summary" Then the document does not contain text "Rationale" And the document does not contain narrative text @@ -65,7 +65,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Detailed level includes rationale and verified-by Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with narrative and rationale + And a PatternGraph with a convention pattern with narrative and rationale When decoding at detail level "detailed" Then the document contains text "Rationale" @@ -77,7 +77,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Behavior-tagged patterns appear in a Behavior Specifications section Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern in category "process-guard" + And a PatternGraph with a behavior pattern in category "process-guard" When decoding at detail level "standard" Then the document has a heading "Behavior Specifications" @@ -89,7 +89,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Shapes appear when source file matches source selector glob Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a pattern at "src/lint/rules.ts" with extracted shapes + And a PatternGraph with a pattern at "src/lint/rules.ts" with extracted shapes When decoding at detail level "detailed" Then the document has a heading "API Types" And the document contains a code block with "typescript" @@ -97,7 +97,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Summary level shows shapes as a compact table Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a pattern at "src/lint/rules.ts" with extracted shapes + And a PatternGraph with a pattern at "src/lint/rules.ts" with extracted shapes When decoding at detail level "summary" Then the document has a heading "API Types" And the document has at least 1 table @@ -105,7 +105,7 @@ Feature: Reference Codec - Core Behavior @edge-case Scenario: No shapes when source file does not match glob Given a reference config with source selector "src/config/*.ts" - And a MasterDataset with a pattern at "src/lint/rules.ts" with extracted shapes + And a PatternGraph with a pattern at "src/lint/rules.ts" with extracted shapes When decoding at detail level "detailed" Then the document does not have a heading "API Types" @@ -117,7 +117,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Both convention and behavior sections appear when data exists Given a reference config with convention tags "fsm-rules" and behavior tags "process-guard" - And a MasterDataset with both convention and behavior data + And a PatternGraph with both convention and behavior data When decoding at detail level "detailed" Then the document has a heading "FSM Transitions" And the document has a heading "Behavior Specifications" @@ -130,7 +130,7 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Convention headings appear before shapes before behaviors Given a reference config with all three content sources - And a MasterDataset with convention, shape, and behavior data + And a PatternGraph with convention, shape, and behavior data When decoding at detail level "detailed" Then the heading "FSM Transitions" appears before "API Types" And the heading "API Types" appears before "Behavior Specifications" @@ -143,13 +143,13 @@ Feature: Reference Codec - Core Behavior @happy-path Scenario: Convention with mermaid content produces mermaid block in output Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with a mermaid diagram + And a PatternGraph with a convention pattern with a mermaid diagram When decoding at detail level "detailed" Then the document contains a mermaid block @happy-path Scenario: Summary level omits convention code examples Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with a mermaid diagram + And a PatternGraph with a convention pattern with a mermaid diagram When decoding at detail level "summary" Then the document does not contain a mermaid block diff --git a/tests/features/behavior/codecs/reference-codec-detail-rendering.feature b/tests/features/behavior/codecs/reference-codec-detail-rendering.feature index 63d74423..7685d959 100644 --- a/tests/features/behavior/codecs/reference-codec-detail-rendering.feature +++ b/tests/features/behavior/codecs/reference-codec-detail-rendering.feature @@ -22,7 +22,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Standard level includes narrative but omits rationale Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with a convention pattern with narrative and rationale + And a PatternGraph with a convention pattern with narrative and rationale When decoding at detail level "standard" Then the document contains narrative text And the document does not contain text "Rationale" @@ -35,7 +35,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Detailed level renders structured behavior rules Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with structured rules + And a PatternGraph with a behavior pattern with structured rules When decoding at detail level "detailed" Then the document has a heading "Invariant Rule" And the document contains text "Must follow FSM transitions" @@ -45,7 +45,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Standard level renders behavior rules without rationale Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with structured rules + And a PatternGraph with a behavior pattern with structured rules When decoding at detail level "standard" Then the document has a heading "Invariant Rule" And the document contains text "Must follow FSM transitions" @@ -54,7 +54,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Summary level shows behavior rules as truncated table Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with structured rules + And a PatternGraph with a behavior pattern with structured rules When decoding at detail level "summary" Then the document has at least 1 table And the document does not have a heading "Invariant Rule" @@ -62,7 +62,7 @@ Feature: Reference Codec - Detail Level Rendering @edge-case Scenario: Scenario names and verifiedBy merge as deduplicated list Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with overlapping scenarioNames and verifiedBy + And a PatternGraph with a behavior pattern with overlapping scenarioNames and verifiedBy When decoding at detail level "detailed" Then the document contains a verified-by list with 3 unique entries @@ -74,14 +74,14 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Standard level includes JSDoc in code blocks Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a shape pattern with JSDoc + And a PatternGraph with a shape pattern with JSDoc When decoding at detail level "standard" Then the document contains text "Input to the process guard decider function" @happy-path Scenario: Detailed level includes JSDoc in code block and property table Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a shape pattern with JSDoc and property docs + And a PatternGraph with a shape pattern with JSDoc and property docs When decoding at detail level "detailed" Then the document contains text "Input to the process guard decider function" And the document has at least 1 table @@ -89,7 +89,7 @@ Feature: Reference Codec - Detail Level Rendering @edge-case Scenario: Shapes without JSDoc render code blocks only Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a shape pattern without JSDoc + And a PatternGraph with a shape pattern without JSDoc When decoding at detail level "standard" Then the document does not contain text "Input to the process guard" And the document contains a code block with "typescript" @@ -102,7 +102,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Detailed level renders param table for function shapes Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a function shape with param docs + And a PatternGraph with a function shape with param docs When decoding at detail level "detailed" Then the document has a table with columns "Parameter" and "Type" and "Description" And the table contains param "orderId" with description "The unique order identifier" @@ -110,7 +110,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Detailed level renders returns and throws documentation Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a function shape with returns and throws docs + And a PatternGraph with a function shape with returns and throws docs When decoding at detail level "detailed" Then the rendered output contains returns paragraph with type and description And the document has a table with columns "Exception" and "Description" @@ -118,7 +118,7 @@ Feature: Reference Codec - Detail Level Rendering @happy-path Scenario: Standard level renders param table without throws Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a function shape with param and throws docs + And a PatternGraph with a function shape with param and throws docs When decoding at detail level "standard" Then the document has a table with columns "Parameter" and "Type" and "Description" And the document does not have a table with column "Exception" @@ -126,7 +126,7 @@ Feature: Reference Codec - Detail Level Rendering @edge-case Scenario: Shapes without param docs skip param table Given a reference config with source selector "src/lint/*.ts" - And a MasterDataset with a shape pattern with JSDoc + And a PatternGraph with a shape pattern with JSDoc When decoding at detail level "detailed" Then the document does not have a table with column "Parameter" @@ -148,7 +148,7 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Behavior pattern with many rules uses collapsible blocks at detailed level Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with 3 structured rules + And a PatternGraph with a behavior pattern with 3 structured rules When decoding at detail level "detailed" Then the document contains at least 1 collapsible block And each collapsible block summary includes a rule name @@ -156,14 +156,14 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Behavior pattern with few rules does not use collapsible blocks Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with 2 structured rules + And a PatternGraph with a behavior pattern with 2 structured rules When decoding at detail level "detailed" Then the document does not contain collapsible blocks @acceptance-criteria @happy-path Scenario: Summary level never produces collapsible blocks Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern with 3 structured rules + And a PatternGraph with a behavior pattern with 3 structured rules When decoding at detail level "summary" Then the document does not contain collapsible blocks @@ -184,7 +184,7 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Behavior pattern includes source file link-out at detailed level Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern in category "process-guard" + And a PatternGraph with a behavior pattern in category "process-guard" When decoding at detail level "detailed" Then the document contains at least 1 link-out block And the link-out path references a source file @@ -192,14 +192,14 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Standard level includes source file link-out Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern in category "process-guard" + And a PatternGraph with a behavior pattern in category "process-guard" When decoding at detail level "standard" Then the document contains at least 1 link-out block @acceptance-criteria @happy-path Scenario: Summary level omits link-out blocks Given a reference config with convention tags "" and behavior tags "process-guard" - And a MasterDataset with a behavior pattern in category "process-guard" + And a PatternGraph with a behavior pattern in category "process-guard" When decoding at detail level "summary" Then the document does not contain link-out blocks @@ -217,7 +217,7 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Include-tagged pattern appears in behavior section Given a reference config with includeTags "reference-sample" - And a MasterDataset with a pattern that has include "reference-sample" + And a PatternGraph with a pattern that has include "reference-sample" When decoding at detail level "standard" Then the document has a heading "Behavior Specifications" And the document contains text "IncludedPattern" @@ -225,7 +225,7 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @happy-path Scenario: Include-tagged pattern is additive with category-selected patterns Given a reference config with behavior tags "lint" and includeTags "reference-sample" - And a MasterDataset with a category pattern and an include-tagged pattern + And a PatternGraph with a category pattern and an include-tagged pattern When decoding at detail level "standard" Then the document contains text "LintPattern" And the document contains text "IncludedPattern" @@ -233,6 +233,6 @@ Feature: Reference Codec - Detail Level Rendering @acceptance-criteria @edge-case Scenario: Pattern without matching include tag is excluded Given a reference config with includeTags "reference-sample" - And a MasterDataset with a pattern that has include "other-doc" + And a PatternGraph with a pattern that has include "other-doc" When decoding at detail level "standard" Then the document does not have a heading "Behavior Specifications" diff --git a/tests/features/behavior/codecs/reference-codec-diagram-types.feature b/tests/features/behavior/codecs/reference-codec-diagram-types.feature index b3f237bc..3fd44f2e 100644 --- a/tests/features/behavior/codecs/reference-codec-diagram-types.feature +++ b/tests/features/behavior/codecs/reference-codec-diagram-types.feature @@ -34,7 +34,7 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: Default diagramType produces flowchart Given a reference config with diagramScopes archContext "orders" - And a MasterDataset with arch-annotated patterns in context "orders" + And a PatternGraph with arch-annotated patterns in context "orders" When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content starts with "graph" @@ -42,7 +42,7 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: Sequence diagram renders participant-message format Given a reference config with diagramScopes archContext "orders" and diagramType "sequenceDiagram" - And a MasterDataset with patterns in context "orders" with uses relationships + And a PatternGraph with patterns in context "orders" with uses relationships When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content starts with "sequenceDiagram" @@ -52,7 +52,7 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: State diagram renders state transitions Given a reference config with diagramScopes archContext "workflow" and diagramType "stateDiagram-v2" - And a MasterDataset with patterns in context "workflow" with dependsOn relationships + And a PatternGraph with patterns in context "workflow" with dependsOn relationships When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content starts with "stateDiagram-v2" @@ -61,14 +61,14 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @edge-case Scenario: Sequence diagram includes neighbor patterns as participants Given a reference config with diagramScopes archContext "orders" and diagramType "sequenceDiagram" - And a MasterDataset with an orders pattern that uses an external pattern + And a PatternGraph with an orders pattern that uses an external pattern When decoding at detail level "detailed" Then the mermaid content contains participant declarations for both scope and neighbor patterns @acceptance-criteria @edge-case Scenario: State diagram adds start and end pseudo-states Given a reference config with diagramScopes archContext "workflow" and diagramType "stateDiagram-v2" - And a MasterDataset with a linear dependsOn chain of workflow patterns + And a PatternGraph with a linear dependsOn chain of workflow patterns When decoding at detail level "detailed" Then the mermaid content contains a start pseudo-state transition And the mermaid content contains an end pseudo-state transition @@ -76,7 +76,7 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: C4 diagram renders system boundary format Given a reference config with diagramScopes archContext "orders" and diagramType "C4Context" - And a MasterDataset with patterns in context "orders" with uses relationships + And a PatternGraph with patterns in context "orders" with uses relationships When decoding at detail level "detailed" Then the mermaid content starts with "C4Context" And the mermaid content contains a Boundary block for "orders" @@ -86,14 +86,14 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: C4 diagram renders neighbor patterns as external systems Given a reference config with diagramScopes archContext "orders" and diagramType "C4Context" - And a MasterDataset with an orders pattern that uses an external pattern + And a PatternGraph with an orders pattern that uses an external pattern When decoding at detail level "detailed" Then the mermaid content contains a System_Ext declaration @acceptance-criteria @happy-path Scenario: Class diagram renders class members and relationships Given a reference config with diagramScopes archContext "orders" and diagramType "classDiagram" - And a MasterDataset with patterns in context "orders" with uses relationships + And a PatternGraph with patterns in context "orders" with uses relationships When decoding at detail level "detailed" Then the mermaid content starts with "classDiagram" And the mermaid content contains class declarations with members @@ -102,7 +102,7 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: Class diagram renders archRole as stereotype Given a reference config with diagramScopes archContext "orders" and diagramType "classDiagram" - And a MasterDataset with a service pattern and a projection pattern in context "orders" + And a PatternGraph with a service pattern and a projection pattern in context "orders" When decoding at detail level "detailed" Then the mermaid content contains a service stereotype And the mermaid content contains a projection stereotype @@ -126,21 +126,21 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @happy-path Scenario: Relationship edges display type labels by default Given a reference config with diagramScopes archContext "orders" - And a MasterDataset with patterns in context "orders" with uses relationships + And a PatternGraph with patterns in context "orders" with uses relationships When decoding at detail level "detailed" Then the mermaid content contains labeled edges with relationship type text @acceptance-criteria @happy-path Scenario: Edge labels can be disabled for compact diagrams Given a reference config with diagramScopes archContext "orders" and showEdgeLabels false - And a MasterDataset with patterns in context "orders" with uses relationships + And a PatternGraph with patterns in context "orders" with uses relationships When decoding at detail level "detailed" Then the mermaid content contains unlabeled edges @acceptance-criteria @happy-path Scenario: archRole controls Mermaid node shape Given a reference config with diagramScopes archContext "orders" - And a MasterDataset with a service pattern and a projection pattern in context "orders" + And a PatternGraph with a service pattern and a projection pattern in context "orders" When decoding at detail level "detailed" Then the service node uses rounded rectangle syntax And the projection node uses cylinder syntax @@ -148,6 +148,6 @@ Feature: Reference Codec - Diagram Type Rendering @acceptance-criteria @edge-case Scenario: Pattern without archRole uses default rectangle shape Given a reference config with diagramScopes archContext "orders" - And a MasterDataset with a pattern without archRole in context "orders" + And a PatternGraph with a pattern without archRole in context "orders" When decoding at detail level "detailed" Then the node uses default rectangle syntax diff --git a/tests/features/behavior/codecs/reference-codec-diagrams.feature b/tests/features/behavior/codecs/reference-codec-diagrams.feature index d6821738..717034e4 100644 --- a/tests/features/behavior/codecs/reference-codec-diagrams.feature +++ b/tests/features/behavior/codecs/reference-codec-diagrams.feature @@ -21,7 +21,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Config with diagramScopes produces mermaid block at detailed level Given a reference config with diagramScopes archContext "lint" - And a MasterDataset with arch-annotated patterns in context "lint" + And a PatternGraph with arch-annotated patterns in context "lint" When decoding at detail level "detailed" Then the document contains a mermaid block And the document has a heading "Component Overview" @@ -29,7 +29,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Neighbor patterns appear in diagram with distinct style Given a reference config with diagramScopes archContext "lint" - And a MasterDataset with arch patterns where lint uses validation + And a PatternGraph with arch patterns where lint uses validation When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "neighbor" @@ -39,7 +39,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: include filter selects patterns by include tag membership Given a reference config with diagramScopes include "pipeline-stages" - And a MasterDataset with patterns in include "pipeline-stages" + And a PatternGraph with patterns in include "pipeline-stages" When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "PatternScanner" @@ -47,7 +47,7 @@ Feature: Reference Codec - Diagram Scoping @edge-case Scenario: Self-contained scope produces no Related subgraph Given a reference config with diagramScopes archContext "lint" - And a MasterDataset with self-contained lint patterns + And a PatternGraph with self-contained lint patterns When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content does not contain "Related" @@ -55,7 +55,7 @@ Feature: Reference Codec - Diagram Scoping @edge-case Scenario: Multiple filter dimensions OR together Given a reference config with diagramScopes combining archContext and include - And a MasterDataset where one pattern matches archContext and another matches include + And a PatternGraph where one pattern matches archContext and another matches include When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains both "LintRules" and "DocExtractor" @@ -63,7 +63,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Explicit pattern names filter selects named patterns Given a reference config with diagramScopes patterns "LintRules" - And a MasterDataset with multiple arch-annotated patterns + And a PatternGraph with multiple arch-annotated patterns When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "LintRules" @@ -72,14 +72,14 @@ Feature: Reference Codec - Diagram Scoping @edge-case Scenario: Config without diagramScopes produces no diagram section Given a reference config with convention tags "fsm-rules" and behavior tags "" - And a MasterDataset with arch-annotated patterns in context "lint" + And a PatternGraph with arch-annotated patterns in context "lint" When decoding at detail level "detailed" Then the document does not have a heading "Component Overview" @happy-path Scenario: archLayer filter selects patterns by architectural layer Given a reference config with diagramScopes archLayer "domain" - And a MasterDataset with patterns in domain and infrastructure layers + And a PatternGraph with patterns in domain and infrastructure layers When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "DomainPattern" @@ -88,7 +88,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: archLayer and archContext compose via OR Given a reference config with diagramScopes archLayer "domain" and archContext "shared" - And a MasterDataset with a domain-layer pattern and a shared-context pattern + And a PatternGraph with a domain-layer pattern and a shared-context pattern When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains both "DomainPattern" and "SharedPattern" @@ -96,24 +96,24 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Summary level omits scoped diagram Given a reference config with diagramScopes archContext "lint" - And a MasterDataset with arch-annotated patterns in context "lint" + And a PatternGraph with arch-annotated patterns in context "lint" When decoding at detail level "summary" Then the document does not contain a mermaid block Rule: Hardcoded diagram sources render deterministic output **Invariant:** Hardcoded diagram sources render without relationship-scoping input and emit stable, source-specific Mermaid content. - **Rationale:** Domain diagrams such as pipeline and MasterDataset fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. - **Verified by:** master-dataset-views source renders expected fan-out nodes + **Rationale:** Domain diagrams such as pipeline and PatternGraph fan-out encode canonical architecture views that should not depend on ad-hoc test dataset shape. + **Verified by:** pattern-graph-views source renders expected fan-out nodes @happy-path - Scenario: master-dataset-views source produces MasterDataset fan-out diagram - Given a reference config with diagramScopes source "master-dataset-views" - And a MasterDataset with arch-annotated patterns in context "lint" + Scenario: pattern-graph-views source produces PatternGraph fan-out diagram + Given a reference config with diagramScopes source "pattern-graph-views" + And a PatternGraph with arch-annotated patterns in context "lint" When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "graph TB" - And the mermaid content contains all of "MasterDataset", "byStatus", "byPhase", and "relationshipIndex" + And the mermaid content contains all of "PatternGraph", "byStatus", "byPhase", and "relationshipIndex" Rule: Multiple diagram scopes produce multiple mermaid blocks @@ -123,7 +123,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Config with diagramScopes array produces multiple diagrams Given a reference config with two diagramScopes - And a MasterDataset with patterns in two different include groups + And a PatternGraph with patterns in two different include groups When decoding at detail level "detailed" Then the document contains 2 mermaid blocks And the document has headings "Codec Transformation" and "Pipeline Data Flow" @@ -131,7 +131,7 @@ Feature: Reference Codec - Diagram Scoping @happy-path Scenario: Diagram direction is reflected in mermaid output Given a reference config with LR direction diagramScopes - And a MasterDataset with patterns in include "pipeline-stages" + And a PatternGraph with patterns in include "pipeline-stages" When decoding at detail level "detailed" Then the document contains a mermaid block And the mermaid content contains "graph LR" diff --git a/tests/features/behavior/codecs/reference-generators.feature b/tests/features/behavior/codecs/reference-generators.feature index 6ae56609..30a9a939 100644 --- a/tests/features/behavior/codecs/reference-generators.feature +++ b/tests/features/behavior/codecs/reference-generators.feature @@ -70,7 +70,7 @@ Feature: Reference Document Generator Registration @happy-path Scenario: Product area generator with matching data produces non-empty output - Given a MasterDataset with a pattern in product area "Annotation" + Given a PatternGraph with a pattern in product area "Annotation" When running the "annotation-overview-reference" generator Then the output has 1 file And the output file path starts with "product-areas/" @@ -78,15 +78,15 @@ Feature: Reference Document Generator Registration @happy-path Scenario: Product area generator with no patterns still produces intro - Given an empty MasterDataset + Given an empty PatternGraph When running the "annotation-overview-reference" generator Then the output has 1 file And the output file content contains "How do I annotate code?" @integration Scenario: ARCHITECTURE-TYPES generator produces shapes and convention content - Given a MasterDataset with pipeline architecture conventions and master dataset shapes + Given a PatternGraph with pipeline architecture conventions and master dataset shapes When running the "architecture-types-reference" generator Then the output has 1 file And the output file path starts with "reference/" - And the output file content contains all of "MasterDatasetSchema", "PipelineOptions", "Orchestrator Pipeline Responsibilities", and "graph TB" + And the output file content contains all of "PatternGraphSchema", "PipelineOptions", "Orchestrator Pipeline Responsibilities", and "graph TB" diff --git a/tests/features/behavior/codecs/reporting-codecs.feature b/tests/features/behavior/codecs/reporting-codecs.feature index f0c1cf06..213253d6 100644 --- a/tests/features/behavior/codecs/reporting-codecs.feature +++ b/tests/features/behavior/codecs/reporting-codecs.feature @@ -7,7 +7,7 @@ @behavior @reporting-codecs Feature: Reporting Document Codecs The reporting codecs (ChangelogCodec, TraceabilityCodec, OverviewCodec) - transform MasterDataset into RenderableDocuments for reporting outputs. + transform PatternGraph into RenderableDocuments for reporting outputs. **Problem:** - Need to generate changelog, traceability, and overview documents @@ -34,14 +34,14 @@ Feature: Reporting Document Codecs @happy-path @edge-case Scenario: Decode empty dataset produces changelog header only - Given an empty MasterDataset for changelog + Given an empty PatternGraph for changelog When decoding with ChangelogCodec Then the document title is "Changelog" And the document contains Keep a Changelog header @happy-path Scenario: Unreleased section shows active and vNEXT patterns - Given a MasterDataset with unreleased patterns + Given a PatternGraph with unreleased patterns When decoding with ChangelogCodec Then the document contains "[Unreleased]" heading And the unreleased section contains active patterns @@ -49,7 +49,7 @@ Feature: Reporting Document Codecs @happy-path Scenario: Release sections sorted by semver descending - Given a MasterDataset with multiple releases: + Given a PatternGraph with multiple releases: | release | count | | v0.1.0 | 2 | | v0.2.0 | 3 | @@ -63,19 +63,19 @@ Feature: Reporting Document Codecs @happy-path Scenario: Quarter fallback for patterns without release - Given a MasterDataset with completed patterns without release tag + Given a PatternGraph with completed patterns without release tag When decoding with ChangelogCodec Then the document contains quarterly sections And the quarterly sections contain patterns Scenario: Earlier section for undated patterns - Given a MasterDataset with undated completed patterns + Given a PatternGraph with undated completed patterns When decoding with ChangelogCodec Then the document contains "[Earlier]" heading And the earlier section contains undated patterns Scenario: Category mapping to change types - Given a MasterDataset with category-mapped patterns: + Given a PatternGraph with category-mapped patterns: | category | expectedType | | fix | Fixed | | bugfix | Fixed | @@ -86,12 +86,12 @@ Feature: Reporting Document Codecs Then each category maps to correct change type Scenario: Exclude unreleased when option disabled - Given a MasterDataset with unreleased patterns + Given a PatternGraph with unreleased patterns When decoding with includeUnreleased disabled Then the document does not contain "[Unreleased]" heading Scenario: Change type sections follow standard order - Given a MasterDataset with mixed change types + Given a PatternGraph with mixed change types When decoding with ChangelogCodec Then change type sections follow order: | type | @@ -114,14 +114,14 @@ Feature: Reporting Document Codecs @happy-path @edge-case Scenario: No timeline patterns produces empty message - Given a MasterDataset with no timeline patterns + Given a PatternGraph with no timeline patterns When decoding with TraceabilityCodec Then the document title is "Timeline → Behavior Traceability" And the document contains "No Timeline Patterns" heading @happy-path Scenario: Coverage statistics show totals and percentage - Given a MasterDataset with traceability patterns: + Given a PatternGraph with traceability patterns: | name | phase | hasBehaviorFile | | Pattern A | 1 | true | | Pattern B | 1 | true | @@ -136,37 +136,37 @@ Feature: Reporting Document Codecs @happy-path Scenario: Coverage gaps table shows missing coverage - Given a MasterDataset with coverage gaps + Given a PatternGraph with coverage gaps When decoding with TraceabilityCodec Then the document contains "Coverage Gaps" heading And the gaps table shows patterns without behavior files @happy-path Scenario: Covered phases in collapsible section - Given a MasterDataset with covered patterns + Given a PatternGraph with covered patterns When decoding with TraceabilityCodec Then the document contains covered phases collapsible And the covered phases table shows behavior file paths Scenario: Exclude gaps when option disabled - Given a MasterDataset with coverage gaps + Given a PatternGraph with coverage gaps When decoding with includeGaps disabled Then the document does not contain "Coverage Gaps" heading Scenario: Exclude stats when option disabled - Given a MasterDataset with traceability patterns: + Given a PatternGraph with traceability patterns: | name | phase | hasBehaviorFile | | Pattern A | 1 | true | When decoding with includeStats disabled Then the document does not contain "Coverage Statistics" heading Scenario: Exclude covered when option disabled - Given a MasterDataset with covered patterns + Given a PatternGraph with covered patterns When decoding with includeCovered disabled Then the document does not contain covered phases collapsible Scenario: Verified behavior files indicated in output - Given a MasterDataset with verified behavior files + Given a PatternGraph with verified behavior files When decoding with TraceabilityCodec Then the covered patterns show verification status @@ -182,21 +182,21 @@ Feature: Reporting Document Codecs @happy-path @edge-case Scenario: Decode empty dataset produces minimal overview - Given an empty MasterDataset for overview + Given an empty PatternGraph for overview When decoding with OverviewCodec Then the document title is "Architecture Overview" And the document has a purpose @happy-path Scenario: Architecture section from overview-tagged patterns - Given a MasterDataset with overview patterns + Given a PatternGraph with overview patterns When decoding with OverviewCodec Then the document contains "Architecture" heading And the architecture section contains overview pattern descriptions @happy-path Scenario: Patterns summary with progress bar - Given a MasterDataset with status distribution for overview: + Given a PatternGraph with status distribution for overview: | status | count | | completed | 6 | | active | 2 | @@ -208,7 +208,7 @@ Feature: Reporting Document Codecs @happy-path Scenario: Timeline summary with phase counts - Given a MasterDataset with phased patterns + Given a PatternGraph with phased patterns When decoding with OverviewCodec Then the document contains "Timeline Summary" heading And the timeline summary table shows: @@ -219,24 +219,24 @@ Feature: Reporting Document Codecs | Patterns | Scenario: Exclude architecture when option disabled - Given a MasterDataset with overview patterns + Given a PatternGraph with overview patterns When decoding with includeArchitecture disabled Then the document does not contain "Architecture" heading Scenario: Exclude patterns summary when option disabled - Given a MasterDataset with status distribution for overview: + Given a PatternGraph with status distribution for overview: | status | count | | completed | 5 | When decoding with includePatternsSummary disabled Then the document does not contain "Patterns Summary" heading Scenario: Exclude timeline summary when option disabled - Given a MasterDataset with phased patterns + Given a PatternGraph with phased patterns When decoding with includeTimelineSummary disabled Then the document does not contain "Timeline Summary" heading Scenario: Multiple overview patterns create multiple architecture subsections - Given a MasterDataset with multiple overview patterns: + Given a PatternGraph with multiple overview patterns: | name | description | | Event Store | Core event persistence | | Projection Engine | Read model generation | diff --git a/tests/features/behavior/codecs/requirements-adr-codecs.feature b/tests/features/behavior/codecs/requirements-adr-codecs.feature index 42695f65..f3728fb4 100644 --- a/tests/features/behavior/codecs/requirements-adr-codecs.feature +++ b/tests/features/behavior/codecs/requirements-adr-codecs.feature @@ -6,7 +6,7 @@ @architect-implements:CodecBehaviorTesting @behavior @requirements-adr-codecs Feature: Requirements and ADR Document Codecs - The RequirementsDocumentCodec and AdrDocumentCodec transform MasterDataset + The RequirementsDocumentCodec and AdrDocumentCodec transform PatternGraph into RenderableDocuments for PRD-style and architecture decision documentation. **Problem:** @@ -26,20 +26,20 @@ Feature: Requirements and ADR Document Codecs Rule: RequirementsDocumentCodec generates PRD-style documentation from patterns - **Invariant:** RequirementsDocumentCodec transforms MasterDataset patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. + **Invariant:** RequirementsDocumentCodec transforms PatternGraph patterns into a PRD-style document with flexible grouping (product area, user role, or phase), optional detail file generation, and business value rendering. **Rationale:** Flexible grouping lets stakeholders view requirements through their preferred lens (area, role, or phase), and detail files provide deep-dive context without bloating the summary document. **Verified by:** No patterns with PRD metadata produces empty message, Summary shows counts and groupings, By product area section groups patterns correctly, By user role section uses collapsible groups, Group by phase option changes primary grouping, Filter by status option limits patterns, All features table shows complete list, Business value rendering when enabled, Generate individual requirement detail files when enabled, Requirement detail file contains acceptance criteria from scenarios, Requirement detail file contains business rules section, Implementation links from relationshipIndex @happy-path @edge-case Scenario: No patterns with PRD metadata produces empty message - Given an empty MasterDataset + Given an empty PatternGraph When decoding with RequirementsDocumentCodec Then the document title is "Product Requirements" And the document contains "No Product Requirements" @happy-path Scenario: Summary shows counts and groupings - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec Then the document title is "Product Requirements" And the document contains a "Summary" section @@ -51,30 +51,30 @@ Feature: Requirements and ADR Document Codecs @happy-path Scenario: By product area section groups patterns correctly - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec Then the document contains a "By Product Area" section And the product areas show their features Scenario: By user role section uses collapsible groups - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec Then the document contains a "By User Role" section And user role sections are collapsible Scenario: Group by phase option changes primary grouping - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec using groupBy phase Then the document contains a "By Phase" section And phase 1 shows its features Scenario: Filter by status option limits patterns - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec filtering to completed status Then the document shows only completed patterns Scenario: All features table shows complete list - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with RequirementsDocumentCodec Then the document contains an "All Features" section And the all features table has columns: @@ -85,12 +85,12 @@ Feature: Requirements and ADR Document Codecs | Status | Scenario: Business value rendering when enabled - Given a MasterDataset with PRD patterns with business value + Given a PatternGraph with PRD patterns with business value When decoding with RequirementsDocumentCodec Then the feature list shows business value descriptions Scenario: Generate individual requirement detail files when enabled - Given a MasterDataset with PRD patterns + Given a PatternGraph with PRD patterns When decoding with generateDetailFiles enabled for requirements Then the document has requirement detail files: | path | @@ -100,18 +100,18 @@ Feature: Requirements and ADR Document Codecs | requirements/phase-02-admin-dashboard.md | Scenario: Requirement detail file contains acceptance criteria from scenarios - Given a MasterDataset with PRD patterns with scenarios + Given a PatternGraph with PRD patterns with scenarios When decoding with generateDetailFiles enabled for requirements Then the requirement detail files contain acceptance criteria sections And the acceptance criteria shows scenario steps Scenario: Requirement detail file contains business rules section - Given a MasterDataset with PRD patterns with rules + Given a PatternGraph with PRD patterns with rules When decoding with generateDetailFiles enabled for requirements Then the requirement detail files contain business rules sections Scenario: Implementation links from relationshipIndex - Given a MasterDataset with PRD patterns with implementations + Given a PatternGraph with PRD patterns with implementations When decoding with generateDetailFiles enabled for requirements Then the requirement detail files contain implementations sections @@ -121,20 +121,20 @@ Feature: Requirements and ADR Document Codecs Rule: AdrDocumentCodec documents architecture decisions - **Invariant:** AdrDocumentCodec transforms MasterDataset ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. + **Invariant:** AdrDocumentCodec transforms PatternGraph ADR patterns into an architecture decision record document with status tracking, category/phase/date grouping, supersession relationships, and optional detail file generation. **Rationale:** Architecture decisions lose value without status tracking and supersession chains; without them, teams act on outdated decisions and cannot trace why a previous approach was abandoned. **Verified by:** No ADR patterns produces empty message, Summary shows status counts and categories, ADRs grouped by category, ADRs grouped by phase option, ADRs grouped by date (quarter) option, ADR index table with all decisions, ADR entries use clean text without emojis, Context, Decision, Consequences sections from Rule keywords, ADR supersedes rendering, Generate individual ADR detail files when enabled, ADR detail file contains full content @happy-path @edge-case Scenario: No ADR patterns produces empty message - Given a MasterDataset with no ADR patterns + Given a PatternGraph with no ADR patterns When decoding with AdrDocumentCodec Then the document title is "Architecture Decision Records" And the document contains "No Architecture Decisions" @happy-path Scenario: Summary shows status counts and categories - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with AdrDocumentCodec Then the document title is "Architecture Decision Records" And the document contains a "Summary" section @@ -148,25 +148,25 @@ Feature: Requirements and ADR Document Codecs @happy-path Scenario: ADRs grouped by category - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with AdrDocumentCodec Then the document contains a "By Category" section And the ADR categories show their decisions Scenario: ADRs grouped by phase option - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with AdrDocumentCodec using groupBy phase Then the document contains a "By Phase" section And ADR phase sections are collapsible Scenario: ADRs grouped by date (quarter) option - Given a MasterDataset with ADR patterns with quarters + Given a PatternGraph with ADR patterns with quarters When decoding with AdrDocumentCodec using groupBy date Then the document contains a "By Date" section And ADR date sections show quarters Scenario: ADR index table with all decisions - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with AdrDocumentCodec Then the document contains an "ADR Index" section And the ADR index table has columns: @@ -177,23 +177,23 @@ Feature: Requirements and ADR Document Codecs | Category | Scenario: ADR entries use clean text without emojis - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with AdrDocumentCodec Then ADR index entries contain no emojis Scenario: Context, Decision, Consequences sections from Rule keywords - Given a MasterDataset with ADR patterns with semantic rules + Given a PatternGraph with ADR patterns with semantic rules When decoding with AdrDocumentCodec Then ADR entries contain semantic sections Scenario: ADR supersedes rendering - Given a MasterDataset with ADR patterns with supersession + Given a PatternGraph with ADR patterns with supersession When decoding with AdrDocumentCodec Then ADR entries show supersedes relationships And ADR entries show supersededBy relationships Scenario: Generate individual ADR detail files when enabled - Given a MasterDataset with ADR patterns + Given a PatternGraph with ADR patterns When decoding with generateDetailFiles enabled for ADR Then the document has ADR detail files: | path | @@ -203,7 +203,7 @@ Feature: Requirements and ADR Document Codecs | decisions/adr-004-use-temporal.md | Scenario: ADR detail file contains full content - Given a MasterDataset with ADR patterns with semantic rules + Given a PatternGraph with ADR patterns with semantic rules When decoding with generateDetailFiles enabled for ADR Then the ADR detail files contain overview sections And the ADR detail files contain back links diff --git a/tests/features/behavior/codecs/session-codecs.feature b/tests/features/behavior/codecs/session-codecs.feature index ec87d402..e65462c2 100644 --- a/tests/features/behavior/codecs/session-codecs.feature +++ b/tests/features/behavior/codecs/session-codecs.feature @@ -7,7 +7,7 @@ @behavior @session-codecs Feature: Session Document Codecs The session codecs (SessionContextCodec, RemainingWorkCodec) - transform MasterDataset into RenderableDocuments for AI session context + transform PatternGraph into RenderableDocuments for AI session context and incomplete work aggregation views. **Problem:** @@ -34,7 +34,7 @@ Feature: Session Document Codecs @happy-path @edge-case Scenario: Decode empty dataset produces minimal session context - Given an empty MasterDataset + Given an empty PatternGraph When decoding with SessionContextCodec Then the document title is "Session Context" And the document has a purpose @@ -42,7 +42,7 @@ Feature: Session Document Codecs @happy-path Scenario: Decode dataset with timeline patterns - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with SessionContextCodec Then the document title is "Session Context" And the document contains sections: @@ -52,7 +52,7 @@ Feature: Session Document Codecs @happy-path Scenario: Session status shows current focus - Given a MasterDataset with status distribution: + Given a PatternGraph with status distribution: | status | count | | completed | 3 | | active | 2 | @@ -67,7 +67,7 @@ Feature: Session Document Codecs @happy-path Scenario: Phase navigation for incomplete phases - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with SessionContextCodec Then the document contains a "Phase Navigation" section And the phase navigation table has columns: @@ -79,30 +79,30 @@ Feature: Session Document Codecs @happy-path Scenario: Active work grouped by phase - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with SessionContextCodec Then the document contains an "Active Work" section And the active work shows patterns grouped by phase Scenario: Blocked items section with dependencies - Given a MasterDataset with blocked patterns + Given a PatternGraph with blocked patterns When decoding with includeDependencies enabled for session Then the document contains a "Blocked Items" section And the blocked items table shows pattern and blocker Scenario: No blocked items section when disabled - Given a MasterDataset with blocked patterns + Given a PatternGraph with blocked patterns When decoding with includeDependencies disabled for session Then the document does not contain "Blocked Items" Scenario: Recent completions collapsible - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with SessionContextCodec Then the document contains a collapsible "Recent Completions" And the recent completions shows completed patterns Scenario: Generate session phase detail files when enabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles enabled for session Then the document has session detail files: | path | @@ -110,7 +110,7 @@ Feature: Session Document Codecs | sessions/phase-04-advanced-projections.md | Scenario: No detail files when disabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles disabled for session Then the document has no additional files @@ -126,14 +126,14 @@ Feature: Session Document Codecs @happy-path @edge-case Scenario: All work complete produces celebration message - Given a MasterDataset with only completed patterns + Given a PatternGraph with only completed patterns When decoding with RemainingWorkCodec Then the document title is "Remaining Work" And the document contains "All Work Complete" @happy-path Scenario: Summary shows remaining counts - Given a MasterDataset with status distribution: + Given a PatternGraph with status distribution: | status | count | | completed | 3 | | active | 2 | @@ -148,7 +148,7 @@ Feature: Session Document Codecs @happy-path Scenario: Phase navigation with remaining count - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with RemainingWorkCodec Then the document contains a "By Phase" section And the by phase table has columns: @@ -160,7 +160,7 @@ Feature: Session Document Codecs @happy-path Scenario: By priority shows ready vs blocked - Given a MasterDataset with blocked patterns + Given a PatternGraph with blocked patterns When decoding with RemainingWorkCodec Then the document contains a "By Priority" section And the by priority table shows: @@ -171,28 +171,28 @@ Feature: Session Document Codecs @happy-path Scenario: Next actionable items section - Given a MasterDataset with actionable patterns + Given a PatternGraph with actionable patterns When decoding with RemainingWorkCodec Then the document contains a "Next Actionable Items" section And the next actionable items are not blocked Scenario: Next actionable respects maxNextActionable limit - Given a MasterDataset with many planned patterns + Given a PatternGraph with many planned patterns When decoding with maxNextActionable set to 3 Then the next actionable items shows at most 3 items Scenario: Sort by phase option - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with sortBy set to "phase" Then the remaining work is ordered by phase number Scenario: Sort by priority option - Given a MasterDataset with prioritized patterns + Given a PatternGraph with prioritized patterns When decoding with sortBy set to "priority" Then the remaining work shows priority groupings Scenario: Generate remaining work detail files when enabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles enabled for remaining Then the document has remaining detail files: | path | @@ -200,6 +200,6 @@ Feature: Session Document Codecs | remaining/phase-04-advanced-projections.md | Scenario: No detail files when disabled for remaining - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles disabled for remaining Then the document has no additional files diff --git a/tests/features/behavior/codecs/shape-matcher.feature b/tests/features/behavior/codecs/shape-matcher.feature index d7249a25..7a93778b 100644 --- a/tests/features/behavior/codecs/shape-matcher.feature +++ b/tests/features/behavior/codecs/shape-matcher.feature @@ -84,7 +84,7 @@ Feature: Shape Source Pattern Matching @happy-path Scenario: Shapes are selected from matching source glob patterns - Given a MasterDataset with patterns: + Given a PatternGraph with patterns: | filePath | shapeName | shapeKind | | src/lint/rules.ts | LintRule | interface | | src/lint/config.ts | LintConfig | type | @@ -94,7 +94,7 @@ Feature: Shape Source Pattern Matching @happy-path Scenario: Duplicate shape names are deduplicated - Given a MasterDataset with patterns: + Given a PatternGraph with patterns: | filePath | shapeName | shapeKind | | src/lint/rules.ts | LintRule | interface | | src/lint/config.ts | LintRule | type | @@ -103,7 +103,7 @@ Feature: Shape Source Pattern Matching @edge-case Scenario: No shapes returned when glob does not match - Given a MasterDataset with patterns: + Given a PatternGraph with patterns: | filePath | shapeName | shapeKind | | src/other/unrelated.ts | Unrelated | interface | When selecting shapes with source selector "src/lint/*.ts" diff --git a/tests/features/behavior/codecs/shape-selector.feature b/tests/features/behavior/codecs/shape-selector.feature index 3d819b83..b8dc2346 100644 --- a/tests/features/behavior/codecs/shape-selector.feature +++ b/tests/features/behavior/codecs/shape-selector.feature @@ -24,7 +24,7 @@ Feature: Shape Selector Filtering @acceptance-criteria @happy-path Scenario: Select specific shapes by source and names - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/risk-levels.ts | RISK_LEVELS | api-types | const | @@ -35,7 +35,7 @@ Feature: Shape Selector Filtering @acceptance-criteria @happy-path Scenario: Select all shapes in a group - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/status-values.ts | ProcessStatus | api-types | type | @@ -46,7 +46,7 @@ Feature: Shape Selector Filtering @acceptance-criteria @happy-path Scenario: Select all tagged shapes from a source file - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/risk-levels.ts | RISK_LEVELS | api-types | const | @@ -58,7 +58,7 @@ Feature: Shape Selector Filtering @acceptance-criteria @happy-path Scenario: Source-only selector returns all matching shapes - Given a MasterDataset with patterns containing these extracted shapes: + Given a PatternGraph with patterns containing these extracted shapes: | Pattern Source | Shape Name | Group | Kind | | src/taxonomy/risk-levels.ts | RiskLevel | api-types | type | | src/taxonomy/risk-levels.ts | RISK_LEVELS | | const | diff --git a/tests/features/behavior/codecs/timeline-codecs.feature b/tests/features/behavior/codecs/timeline-codecs.feature index 00fd37ac..7b1ed98d 100644 --- a/tests/features/behavior/codecs/timeline-codecs.feature +++ b/tests/features/behavior/codecs/timeline-codecs.feature @@ -7,7 +7,7 @@ @behavior @timeline-codecs Feature: Timeline Document Codecs The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) - transform MasterDataset into RenderableDocuments for different timeline views. + transform PatternGraph into RenderableDocuments for different timeline views. **Problem:** - Need to generate roadmap, milestones, and current work documents from patterns @@ -32,7 +32,7 @@ Feature: Timeline Document Codecs @happy-path @edge-case Scenario: Decode empty dataset produces minimal roadmap - Given an empty MasterDataset + Given an empty PatternGraph When decoding with RoadmapDocumentCodec Then the document title is "Development Roadmap" And the document has a purpose @@ -40,7 +40,7 @@ Feature: Timeline Document Codecs @happy-path Scenario: Decode dataset with multiple phases - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with RoadmapDocumentCodec Then the document title is "Development Roadmap" And the document contains sections: @@ -51,7 +51,7 @@ Feature: Timeline Document Codecs @happy-path Scenario: Progress section shows correct status counts - Given a MasterDataset with status distribution: + Given a PatternGraph with status distribution: | status | count | | completed | 5 | | active | 3 | @@ -67,7 +67,7 @@ Feature: Timeline Document Codecs @happy-path Scenario: Phase navigation table with progress - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with RoadmapDocumentCodec Then the phase navigation table has columns: | column | @@ -77,13 +77,13 @@ Feature: Timeline Document Codecs And the phase navigation has 4 rows Scenario: Phase sections show pattern tables - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with RoadmapDocumentCodec Then phase 1 section shows "100% complete" And phase 3 section shows active patterns Scenario: Generate phase detail files when enabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles enabled for roadmap Then the document has phase detail files: | path | @@ -93,12 +93,12 @@ Feature: Timeline Document Codecs | phases/phase-04-advanced-projections.md | Scenario: No detail files when disabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles disabled for roadmap Then the document has no additional files Scenario: Quarterly timeline shown when quarters exist - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with RoadmapDocumentCodec Then the document contains a "Quarterly Timeline" section And the quarterly timeline table has quarters: @@ -119,14 +119,14 @@ Feature: Timeline Document Codecs @happy-path @edge-case Scenario: No completed patterns produces empty message - Given a MasterDataset with only planned patterns + Given a PatternGraph with only planned patterns When decoding with CompletedMilestonesCodec Then the document title is "Completed Milestones" And the document contains "No Completed Milestones" @happy-path Scenario: Summary shows completed counts - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CompletedMilestonesCodec Then the document title is "Completed Milestones" And the summary table shows: @@ -135,25 +135,25 @@ Feature: Timeline Document Codecs @happy-path Scenario: Quarterly navigation with completed patterns - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CompletedMilestonesCodec Then the document contains a "Quarterly Navigation" section And the quarterly navigation shows quarters with completed counts Scenario: Completed phases shown in collapsible sections - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CompletedMilestonesCodec Then the document contains a "Completed Phases" section And the completed phases are collapsible Scenario: Recent completions section with limit - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CompletedMilestonesCodec Then the document contains a "Recent Completions" section And recent completions shows at most 10 patterns Scenario: Generate quarterly detail files when enabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles enabled for milestones Then the document has quarterly milestone files: | path | @@ -172,14 +172,14 @@ Feature: Timeline Document Codecs @happy-path @edge-case Scenario: No active work produces empty message - Given a MasterDataset with only completed patterns + Given a PatternGraph with only completed patterns When decoding with CurrentWorkCodec Then the document title is "Current Work" And the document contains "No Active Work" @happy-path Scenario: Summary shows overall progress - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CurrentWorkCodec Then the document title is "Current Work" And the summary shows overall progress percentage @@ -187,18 +187,18 @@ Feature: Timeline Document Codecs @happy-path Scenario: Active phases with progress bars - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CurrentWorkCodec Then the document contains an "Active Phases" section And active phase 3 shows progress and status breakdown Scenario: Deliverables rendered when configured - Given a MasterDataset with patterns with deliverables + Given a PatternGraph with patterns with deliverables When decoding with includeDeliverables enabled for current work Then the active patterns show their deliverables Scenario: All active patterns table - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with CurrentWorkCodec Then the document contains an "All Active Patterns" section And the active patterns table has columns: @@ -209,7 +209,7 @@ Feature: Timeline Document Codecs | Description | Scenario: Generate current work detail files when enabled - Given a MasterDataset with timeline patterns + Given a PatternGraph with timeline patterns When decoding with generateDetailFiles enabled for current work Then the document has current work detail files: | path | diff --git a/tests/features/behavior/patterns-codec.feature b/tests/features/behavior/patterns-codec.feature index 404f4081..99677441 100644 --- a/tests/features/behavior/patterns-codec.feature +++ b/tests/features/behavior/patterns-codec.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation @behavior @patterns-codec Feature: Patterns Document Codec - The PatternsDocumentCodec transforms MasterDataset into a RenderableDocument + The PatternsDocumentCodec transforms PatternGraph into a RenderableDocument for generating PATTERNS.md and category detail files. **Problem:** @@ -14,7 +14,7 @@ Feature: Patterns Document Codec - Output should include progress tracking, navigation, and categorization **Solution:** - - Codec transforms MasterDataset → RenderableDocument in a single decode call + - Codec transforms PatternGraph → RenderableDocument in a single decode call - Generates main document with optional category detail files Background: @@ -28,7 +28,7 @@ Feature: Patterns Document Codec @happy-path @edge-case Scenario: Decode empty dataset - Given an empty MasterDataset + Given an empty PatternGraph When decoding with PatternsDocumentCodec Then the document title is "Pattern Registry" And the document has a purpose @@ -36,7 +36,7 @@ Feature: Patterns Document Codec @happy-path Scenario: Decode dataset with patterns - document structure - Given a MasterDataset with 5 patterns across 2 categories + Given a PatternGraph with 5 patterns across 2 categories When decoding with PatternsDocumentCodec Then the document title is "Pattern Registry" And the document contains sections: @@ -47,7 +47,7 @@ Feature: Patterns Document Codec @happy-path Scenario: Progress summary shows correct counts - Given a MasterDataset with status distribution: + Given a PatternGraph with status distribution: | status | count | | completed | 3 | | active | 2 | @@ -69,7 +69,7 @@ Feature: Patterns Document Codec @happy-path Scenario: Pattern table includes all patterns - Given a MasterDataset with 4 patterns + Given a PatternGraph with 4 patterns When decoding with PatternsDocumentCodec Then the pattern table has 4 rows And the pattern table has columns: @@ -80,7 +80,7 @@ Feature: Patterns Document Codec | Description | Scenario: Pattern table is sorted by status then name - Given a MasterDataset with patterns: + Given a PatternGraph with patterns: | name | status | | Zebra | completed | | Alpha | roadmap | @@ -102,7 +102,7 @@ Feature: Patterns Document Codec @happy-path Scenario: Category sections with pattern lists - Given a MasterDataset with patterns in categories: + Given a PatternGraph with patterns in categories: | category | count | | core | 3 | | ddd | 2 | @@ -113,7 +113,7 @@ Feature: Patterns Document Codec | ddd | 2 | Scenario: Filter to specific categories - Given a MasterDataset with patterns in categories: + Given a PatternGraph with patterns in categories: | category | count | | core | 3 | | ddd | 2 | @@ -132,17 +132,17 @@ Feature: Patterns Document Codec **Verified by:** Dependency graph included when relationships exist, No dependency graph when no relationships, Dependency graph disabled by option Scenario: Dependency graph included when relationships exist - Given a MasterDataset with pattern relationships + Given a PatternGraph with pattern relationships When decoding with default options Then the document contains a mermaid dependency graph Scenario: No dependency graph when no relationships - Given a MasterDataset without relationships + Given a PatternGraph without relationships When decoding with default options Then the document does not contain a mermaid block Scenario: Dependency graph disabled by option - Given a MasterDataset with pattern relationships + Given a PatternGraph with pattern relationships When decoding with includeDependencyGraph disabled Then the document does not contain a mermaid block @@ -154,7 +154,7 @@ Feature: Patterns Document Codec @happy-path Scenario: Generate individual pattern files when enabled - Given a MasterDataset with named patterns: + Given a PatternGraph with named patterns: | name | category | | Core Pattern | core | | Another Core | core | @@ -169,13 +169,13 @@ Feature: Patterns Document Codec And pattern links point to individual files Scenario: No detail files when disabled - Given a MasterDataset with patterns in 2 categories + Given a PatternGraph with patterns in 2 categories When decoding with generateDetailFiles disabled Then the document has no additional files And category links are anchor links Scenario: Individual pattern file contains full details - Given a MasterDataset with a pattern named "Test Pattern" in category "core" + Given a PatternGraph with a pattern named "Test Pattern" in category "core" When decoding with generateDetailFiles enabled Then the "patterns/test-pattern.md" additional file exists And the pattern file has title containing "Test Pattern" diff --git a/tests/features/behavior/transform-dataset.feature b/tests/features/behavior/transform-dataset.feature index fa471733..a6af5b6c 100644 --- a/tests/features/behavior/transform-dataset.feature +++ b/tests/features/behavior/transform-dataset.feature @@ -6,8 +6,8 @@ @architect-product-area:Generation @behavior @transform-dataset Feature: Transform Dataset Pipeline - The transformToMasterDataset function transforms raw extracted patterns - into a MasterDataset with all pre-computed views in a single pass. + The transformToPatternGraph function transforms raw extracted patterns + into a PatternGraph with all pre-computed views in a single pass. This is the core of the unified transformation pipeline. **Problem:** @@ -18,14 +18,14 @@ Feature: Transform Dataset Pipeline **Solution:** - Single-pass transformation computes all views in O(n) - All views are immutable and pre-computed - - MasterDataset is the source of truth for all generators + - PatternGraph is the source of truth for all generators Background: Given a transform dataset test context Rule: Empty dataset produces valid zero-state views - **Invariant:** An empty input produces a MasterDataset with all counts at zero and no groupings. + **Invariant:** An empty input produces a PatternGraph with all counts at zero and no groupings. **Rationale:** Generators must handle the zero-state gracefully; a missing or malformed empty dataset would cause null-reference errors across all rendering codecs. **Verified by:** Transform empty dataset @@ -33,7 +33,7 @@ Feature: Transform Dataset Pipeline @happy-path @edge-case Scenario: Transform empty dataset Given an empty raw dataset - When transforming to MasterDataset + When transforming to PatternGraph Then the dataset has 0 patterns And all status counts are 0 And the phase count is 0 @@ -54,7 +54,7 @@ Feature: Transform Dataset Pipeline | completed | 5 | | active | 3 | | planned | 2 | - When transforming to MasterDataset + When transforming to PatternGraph Then byStatus.completed has 5 patterns And byStatus.active has 3 patterns And byStatus.planned has 2 patterns @@ -67,7 +67,7 @@ Feature: Transform Dataset Pipeline | active | active | | roadmap | planned | | deferred | planned | - When transforming to MasterDataset + When transforming to PatternGraph Then each pattern is grouped in the expected status bucket @happy-path @phase-grouping @@ -77,7 +77,7 @@ Feature: Transform Dataset Pipeline | 1 | 2 | | 2 | 3 | | 3 | 1 | - When transforming to MasterDataset + When transforming to PatternGraph Then byPhase has 3 phase groups with counts: | phase | count | | 1 | 2 | @@ -86,12 +86,12 @@ Feature: Transform Dataset Pipeline Scenario: Sort phases by phase number Given patterns in phases 3, 1, 2 (out of order) - When transforming to MasterDataset + When transforming to PatternGraph Then byPhase is sorted as [1, 2, 3] Scenario: Compute per-phase status counts Given phase 1 with 2 completed and 1 active patterns - When transforming to MasterDataset + When transforming to PatternGraph Then phase 1 counts are: | field | value | | completed | 2 | @@ -102,7 +102,7 @@ Feature: Transform Dataset Pipeline Scenario: Patterns without phase are not in byPhase Given 3 patterns without phase metadata And 2 patterns in phase 1 - When transforming to MasterDataset + When transforming to PatternGraph Then byPhase has 1 phase group And phaseCount is 1 @@ -120,7 +120,7 @@ Feature: Transform Dataset Pipeline | Q1-2024 | 2 | | Q2-2024 | 3 | | Q4-2024 | 1 | - When transforming to MasterDataset + When transforming to PatternGraph Then byQuarter has 3 quarters with counts: | quarter | count | | Q1-2024 | 2 | @@ -130,7 +130,7 @@ Feature: Transform Dataset Pipeline Scenario: Patterns without quarter are not in byQuarter Given 3 patterns without quarter And 2 patterns in quarter "Q1-2024" - When transforming to MasterDataset + When transforming to PatternGraph Then byQuarter has 1 quarter @happy-path @category-grouping @@ -140,7 +140,7 @@ Feature: Transform Dataset Pipeline | core | 3 | | ddd | 2 | | saga | 1 | - When transforming to MasterDataset + When transforming to PatternGraph Then byCategory has 3 categories with counts: | category | count | | core | 3 | @@ -162,14 +162,14 @@ Feature: Transform Dataset Pipeline | src/patterns/core.ts | typescript | | src/patterns/ddd.ts | typescript | | tests/features/saga.feature | gherkin | - When transforming to MasterDataset + When transforming to PatternGraph Then bySourceType.typescript has 2 patterns And bySourceType.gherkin has 1 pattern Scenario: Patterns with phase are also in roadmap view Given 3 patterns with phase metadata And 2 patterns without phase - When transforming to MasterDataset + When transforming to PatternGraph Then bySourceType.roadmap has 3 patterns Rule: Relationship index builds bidirectional dependency graph @@ -184,7 +184,7 @@ Feature: Transform Dataset Pipeline Scenario: Build relationship index from patterns Given a pattern "Core" that uses "Base" And a pattern "Base" that is used by "Core" - When transforming to MasterDataset + When transforming to PatternGraph Then the relationship index for "Core" uses contains "Base" And the relationship index for "Base" usedBy contains "Core" @@ -195,7 +195,7 @@ Feature: Transform Dataset Pipeline | usedBy | Application | | dependsOn | Infrastructure | | enables | Extension | - When transforming to MasterDataset + When transforming to PatternGraph Then the relationship index for "Feature" contains: | field | value | | uses | Utility | @@ -207,21 +207,21 @@ Feature: Transform Dataset Pipeline Scenario: Reverse lookup computes enables from dependsOn Given a pattern "Infra" with no relationships And a pattern "App" that depends on "Infra" - When transforming to MasterDataset + When transforming to PatternGraph Then the relationship index for "Infra" enables contains "App" @happy-path @relationships Scenario: Reverse lookup computes usedBy from uses Given a pattern "Lib" with no relationships And a pattern "Consumer" that uses "Lib" - When transforming to MasterDataset + When transforming to PatternGraph Then the relationship index for "Lib" usedBy contains "Consumer" @happy-path @relationships Scenario: Reverse lookup merges with explicit annotations without duplicates Given a pattern "Base" that enables "Feature" explicitly And a pattern "Feature" that depends on "Base" - When transforming to MasterDataset + When transforming to PatternGraph Then the relationship index for "Base" enables contains "Feature" And the relationship index for "Base" enables has exactly 1 entry @@ -264,7 +264,7 @@ Feature: Transform Dataset Pipeline Rule: Workflow integration conditionally includes delivery process data - **Invariant:** The workflow is included in the MasterDataset only when provided, and phase names are resolved from the workflow configuration. + **Invariant:** The workflow is included in the PatternGraph only when provided, and phase names are resolved from the workflow configuration. **Rationale:** Projects without a delivery workflow must still produce valid datasets; unconditionally requiring workflow data would break standalone documentation generation. **Verified by:** Include workflow in result when provided, Result omits workflow when not provided @@ -284,5 +284,5 @@ Feature: Transform Dataset Pipeline Scenario: Result omits workflow when not provided Given patterns without a workflow - When transforming to MasterDataset + When transforming to PatternGraph Then the result does not include workflow diff --git a/tests/features/cli/data-api-cache.feature b/tests/features/cli/data-api-cache.feature index dd5da965..25aaf8cc 100644 --- a/tests/features/cli/data-api-cache.feature +++ b/tests/features/cli/data-api-cache.feature @@ -5,7 +5,7 @@ @architect-product-area:DataAPI @cli @process-api @cache Feature: Process API CLI - Dataset Cache - MasterDataset caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. + PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. Background: Given a temporary working directory @@ -14,9 +14,9 @@ Feature: Process API CLI - Dataset Cache # RULE 1: Cache Hit on Unchanged Sources # ============================================================================ - Rule: MasterDataset is cached between invocations + Rule: PatternGraph is cached between invocations - **Invariant:** When source files have not changed between CLI invocations, the second invocation must use the cached MasterDataset and report cache.hit as true alongside pipeline timing metadata. + **Invariant:** 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. **Rationale:** 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. @happy-path diff --git a/tests/features/cli/process-api-core.feature b/tests/features/cli/process-api-core.feature index ed694d75..6e15cd38 100644 --- a/tests/features/cli/process-api-core.feature +++ b/tests/features/cli/process-api-core.feature @@ -72,7 +72,7 @@ Feature: Process API CLI - Core Infrastructure Rule: CLI status subcommand shows delivery state - **Invariant:** The status subcommand must return structured JSON containing delivery progress derived from the MasterDataset. + **Invariant:** The status subcommand must return structured JSON containing delivery progress derived from the PatternGraph. **Rationale:** Consumers depend on machine-readable status output for scripting and CI integration; unstructured output breaks downstream automation. @happy-path @@ -142,7 +142,7 @@ Feature: Process API CLI - Core Infrastructure Rule: CLI arch subcommand queries architecture - **Invariant:** The arch subcommand must expose role, bounded context, and layer queries over the MasterDataset's architecture metadata. + **Invariant:** The arch subcommand must expose role, bounded context, and layer queries over the PatternGraph's architecture metadata. **Rationale:** Architecture queries replace manual exploration of annotated sources; missing or incorrect results lead to wrong structural assumptions during design sessions. @happy-path diff --git a/tests/features/doc-generation/architecture-doc-refactoring.feature b/tests/features/doc-generation/architecture-doc-refactoring.feature index 55526adf..c0b98b70 100644 --- a/tests/features/doc-generation/architecture-doc-refactoring.feature +++ b/tests/features/doc-generation/architecture-doc-refactoring.feature @@ -112,7 +112,7 @@ Feature: Architecture Doc Refactoring Coverage @acceptance-criteria @happy-path Scenario: Unified Transformation Architecture section retained and ARCHITECTURE-TYPES exists When reading the "Unified Transformation Architecture" section - Then the section contains "MasterDataset" + Then the section contains "PatternGraph" And file "docs-live/reference/ARCHITECTURE-TYPES.md" exists @happy-path @@ -127,21 +127,21 @@ Feature: Architecture Doc Refactoring Coverage Then the section has content And file "docs-live/reference/ARCHITECTURE-CODECS.md" exists - Rule: MasterDataset shapes appear in ARCHITECTURE-TYPES reference + Rule: PatternGraph shapes appear in ARCHITECTURE-TYPES reference - **Invariant:** The ARCHITECTURE-TYPES.md reference document contains core MasterDataset types (MasterDataset, RuntimeMasterDataset, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. + **Invariant:** The ARCHITECTURE-TYPES.md reference document contains core PatternGraph types (PatternGraph, RuntimePatternGraph, RawDataset) and pipeline types (PipelineOptions, PipelineResult) extracted from shape annotations. **Rationale:** Type shapes are the structural backbone of the pipeline. Generating their documentation from annotations ensures the reference always matches the actual TypeScript interfaces, eliminating manual drift. - **Verified by:** Core MasterDataset types appear in ARCHITECTURE-TYPES, Pipeline types appear in ARCHITECTURE-TYPES reference, Unified Transformation section has full MasterDataset content + **Verified by:** Core PatternGraph types appear in ARCHITECTURE-TYPES, Pipeline types appear in ARCHITECTURE-TYPES reference, Unified Transformation section has full PatternGraph content @acceptance-criteria @happy-path - Scenario: Core MasterDataset types appear in ARCHITECTURE-TYPES + Scenario: Core PatternGraph types appear in ARCHITECTURE-TYPES When reading file "docs-live/reference/ARCHITECTURE-TYPES.md" Then the file contains each of the following: """ - MasterDataset - RuntimeMasterDataset + PatternGraph + RuntimePatternGraph RawDataset """ @@ -152,10 +152,10 @@ Feature: Architecture Doc Refactoring Coverage And the file also contains "PipelineResult" @happy-path - Scenario: Unified Transformation section has full MasterDataset content + Scenario: Unified Transformation section has full PatternGraph content When reading the "Unified Transformation Architecture" section - Then the section contains "MasterDataset" - And the section also contains "RuntimeMasterDataset" + Then the section contains "PatternGraph" + And the section also contains "RuntimePatternGraph" Rule: Pipeline architecture convention appears in generated reference diff --git a/tests/features/doc-generation/index-codec.feature b/tests/features/doc-generation/index-codec.feature index 99f14d7f..9f45e6ee 100644 --- a/tests/features/doc-generation/index-codec.feature +++ b/tests/features/doc-generation/index-codec.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation Feature: Index Document Codec - Validates the Index Codec that transforms MasterDataset into a + Validates the Index Codec that transforms PatternGraph into a RenderableDocument for the main documentation navigation index (INDEX.md). Background: Codec setup diff --git a/tests/features/doc-generation/taxonomy-codec.feature b/tests/features/doc-generation/taxonomy-codec.feature index f29cd7c6..d2f417e8 100644 --- a/tests/features/doc-generation/taxonomy-codec.feature +++ b/tests/features/doc-generation/taxonomy-codec.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation Feature: Taxonomy Document Codec - Validates the Taxonomy Codec that transforms MasterDataset into a + Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference documentation (TAXONOMY.md). Background: Codec setup diff --git a/tests/features/doc-generation/validation-rules-codec.feature b/tests/features/doc-generation/validation-rules-codec.feature index ca5ae9bf..ee3c4ad6 100644 --- a/tests/features/doc-generation/validation-rules-codec.feature +++ b/tests/features/doc-generation/validation-rules-codec.feature @@ -6,7 +6,7 @@ @architect-product-area:Generation Feature: Validation Rules Document Codec - Validates the Validation Rules Codec that transforms MasterDataset into a + Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference (VALIDATION-RULES.md). Background: Codec setup diff --git a/tests/features/generation/design-review.feature b/tests/features/generation/design-review.feature index 288306e0..ad43f5c9 100644 --- a/tests/features/generation/design-review.feature +++ b/tests/features/generation/design-review.feature @@ -7,7 +7,7 @@ Feature: Design Review Generation Pipeline Tests the full design review generation pipeline: sequence annotations are extracted from patterns with business rules, pre-computed into a SequenceIndex - on MasterDataset, then rendered through DesignReviewCodec into markdown with + on PatternGraph, then rendered through DesignReviewCodec into markdown with Mermaid sequence diagrams, component diagrams, type definition tables, and design question templates. @@ -17,7 +17,7 @@ Feature: Design Review Generation Pipeline Rule: SequenceIndex pre-computes ordered steps from annotated rules **Invariant:** buildSequenceIndexEntry produces a SequenceIndexEntry with steps sorted by stepNumber, participants deduplicated with orchestrator first, and data flow types collected from Input/Output annotations. - **Rationale:** Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the MasterDataset as the sole read model. + **Rationale:** Pre-computing in the transform pass avoids repeated parsing in the codec. ADR-006 mandates the PatternGraph as the sole read model. **Verified by:** SequenceIndex populated for annotated pattern, Steps sorted by step number, Patterns without sequence annotations have no entry @acceptance-criteria @happy-path diff --git a/tests/features/generators/business-rules-codec.feature b/tests/features/generators/business-rules-codec.feature index 817fbf0f..c4a141eb 100644 --- a/tests/features/generators/business-rules-codec.feature +++ b/tests/features/generators/business-rules-codec.feature @@ -6,7 +6,7 @@ @architect-implements:BusinessRulesGenerator Feature: Business Rules Document Codec - Tests the BusinessRulesCodec transformation from MasterDataset to RenderableDocument. + Tests the BusinessRulesCodec transformation from PatternGraph to RenderableDocument. Verifies rule extraction, organization by domain/phase, and progressive disclosure. Background: Business rules codec test context diff --git a/tests/features/generators/codec-based.feature b/tests/features/generators/codec-based.feature index 0e27654e..7bd10900 100644 --- a/tests/features/generators/codec-based.feature +++ b/tests/features/generators/codec-based.feature @@ -20,13 +20,13 @@ Feature: Codec-Based Generator Rule: CodecBasedGenerator adapts codecs to generator interface **Invariant:** CodecBasedGenerator delegates document generation to the underlying codec and surfaces codec errors through the generator interface. - **Rationale:** The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. MasterDataset is required in context — enforced by the TypeScript type system, not at runtime. + **Rationale:** The adapter pattern enables codec-based rendering to integrate with the existing orchestrator without modifying either side. PatternGraph is required in context — enforced by the TypeScript type system, not at runtime. **Verified by:** Generator delegates to codec, Codec options are passed through @acceptance-criteria @happy-path Scenario: Generator delegates to codec Given a CodecBasedGenerator wrapping "patterns" document type - And a context with MasterDataset containing patterns + And a context with PatternGraph containing patterns When the generator generate method is called Then the output should contain a file with path "PATTERNS.md" And the output should have no errors @@ -34,7 +34,7 @@ Feature: Codec-Based Generator @acceptance-criteria @happy-path Scenario: Codec options are passed through Given a CodecBasedGenerator for "pr-changes" document type - And a context with MasterDataset + And a context with PatternGraph And codecOptions with changedFiles filter: | file | | src/core/types.ts | diff --git a/tests/features/mcp/mcp-server.feature b/tests/features/mcp/mcp-server.feature index 2b9b2b3a..bd351565 100644 --- a/tests/features/mcp/mcp-server.feature +++ b/tests/features/mcp/mcp-server.feature @@ -3,15 +3,15 @@ Feature: MCP Server Integration Tests Verifies the MCP-specific layer: tool registration, pipeline session lifecycle, file watcher behavior, CLI argument parsing, and output - formatting. ProcessStateAPI correctness is tested separately. + formatting. PatternGraphAPI correctness is tested separately. Background: Test infrastructure - Given a test MasterDataset is initialized for MCP + Given a test PatternGraph is initialized for MCP Rule: Pipeline session manager loads once and supports atomic rebuild **Invariant:** The pipeline runs exactly once during initialization. - All subsequent calls read from in-memory MasterDataset. Rebuild + All subsequent calls read from in-memory PatternGraph. Rebuild atomically replaces the session. **Rationale:** Verifies the core lifecycle contract of PipelineSessionManager @@ -28,7 +28,7 @@ Feature: MCP Server Integration Tests Scenario: Session initializes and contains dataset Given a PipelineSessionManager initialized with test data When getSession is called - Then the session contains a MasterDataset with patterns + Then the session contains a PatternGraph with patterns And the session records build time in milliseconds Scenario: getSession throws before initialization diff --git a/tests/fixtures/dataset-factories.ts b/tests/fixtures/dataset-factories.ts index 87d85b9a..ccb2d831 100644 --- a/tests/fixtures/dataset-factories.ts +++ b/tests/fixtures/dataset-factories.ts @@ -1,19 +1,19 @@ /** - * MasterDataset Factory Utilities for Testing + * PatternGraph Factory Utilities for Testing * - * Provides convenient factories for creating MasterDataset objects + * Provides convenient factories for creating PatternGraph objects * for use in Gherkin step definitions and unit tests. These factories - * wrap the pattern factories and transformToMasterDataset to produce + * wrap the pattern factories and transformToPatternGraph to produce * fully-formed datasets with all pre-computed views. * * @architect */ import type { ExtractedPattern } from '../../src/validation-schemas/index.js'; -import type { StatusCounts } from '../../src/validation-schemas/master-dataset.js'; -import type { RuntimeMasterDataset } from '../../src/generators/pipeline/transform-types.js'; +import type { StatusCounts } from '../../src/validation-schemas/pattern-graph.js'; +import type { RuntimePatternGraph } from '../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDataset } from '../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../src/validation-schemas/tag-registry.js'; import { createTestPattern, @@ -31,9 +31,9 @@ import { // ============================================================================ /** - * Options for creating a test MasterDataset + * Options for creating a test PatternGraph */ -export interface TestMasterDatasetOptions { +export interface TestPatternGraphOptions { /** * Pre-built patterns to use (bypasses pattern generation) * If provided, all other pattern-generation options are ignored. @@ -82,39 +82,37 @@ export interface TestMasterDatasetOptions { // ============================================================================ /** - * Create a test MasterDataset with all pre-computed views + * Create a test PatternGraph with all pre-computed views * * This is the primary factory for creating test datasets. It wraps pattern * generation and transformation into a single convenient call. * * @param options - Configuration for the dataset - * @returns Fully-formed MasterDataset with all views computed + * @returns Fully-formed PatternGraph with all views computed * * @example * ```typescript * // Empty dataset - * const empty = createTestMasterDataset(); + * const empty = createTestPatternGraph(); * * // Dataset with 10 patterns across 3 categories - * const dataset = createTestMasterDataset({ + * const dataset = createTestPatternGraph({ * patternCount: 10, * categories: ["core", "ddd", "saga"], * }); * * // Dataset with specific status distribution - * const mixed = createTestMasterDataset({ + * const mixed = createTestPatternGraph({ * statusDistribution: { completed: 5, active: 3, planned: 2 }, * }); * * // Dataset with relationships for dependency graph testing - * const withDeps = createTestMasterDataset({ + * const withDeps = createTestPatternGraph({ * withRelationships: true, * }); * ``` */ -export function createTestMasterDataset( - options: TestMasterDatasetOptions = {} -): RuntimeMasterDataset { +export function createTestPatternGraph(options: TestPatternGraphOptions = {}): RuntimePatternGraph { const { patterns: providedPatterns, patternCount = 0, @@ -155,7 +153,7 @@ export function createTestMasterDataset( patterns = []; } - return transformToMasterDataset({ + return transformToPatternGraph({ patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -167,27 +165,27 @@ export function createTestMasterDataset( // ============================================================================ /** - * Create an empty MasterDataset + * Create an empty PatternGraph * * Useful for testing edge cases where no patterns exist. * - * @returns MasterDataset with all counts at 0 and empty views + * @returns PatternGraph with all counts at 0 and empty views */ -export function createEmptyMasterDataset(): RuntimeMasterDataset { - return createTestMasterDataset(); +export function createEmptyPatternGraph(): RuntimePatternGraph { + return createTestPatternGraph(); } /** - * Create a MasterDataset with specific status counts + * Create a PatternGraph with specific status counts * * Generates patterns to match the specified status distribution. * * @param counts - Status counts to achieve - * @returns MasterDataset with specified status distribution + * @returns PatternGraph with specified status distribution * * @example * ```typescript - * const dataset = createMasterDatasetWithStatus({ + * const dataset = createPatternGraphWithStatus({ * completed: 5, * active: 3, * planned: 2, @@ -199,55 +197,55 @@ export function createEmptyMasterDataset(): RuntimeMasterDataset { * expect(dataset.counts.total).toBe(10); * ``` */ -export function createMasterDatasetWithStatus(counts: Partial): RuntimeMasterDataset { - return createTestMasterDataset({ +export function createPatternGraphWithStatus(counts: Partial): RuntimePatternGraph { + return createTestPatternGraph({ statusDistribution: counts, }); } /** - * Create a MasterDataset with relationship data + * Create a PatternGraph with relationship data * * Uses the diamond dependency graph for testing dependency-related features. * - * @returns MasterDataset with 4 patterns in a diamond dependency structure + * @returns PatternGraph with 4 patterns in a diamond dependency structure */ -export function createMasterDatasetWithRelationships(): RuntimeMasterDataset { - return createTestMasterDataset({ withRelationships: true }); +export function createPatternGraphWithRelationships(): RuntimePatternGraph { + return createTestPatternGraph({ withRelationships: true }); } /** - * Create a MasterDataset with timeline metadata + * Create a PatternGraph with timeline metadata * * Includes patterns with phases, quarters, completion dates, and deliverables. * - * @returns MasterDataset with timeline-enriched patterns + * @returns PatternGraph with timeline-enriched patterns */ -export function createMasterDatasetWithTimeline(): RuntimeMasterDataset { - return createTestMasterDataset({ withTimeline: true }); +export function createPatternGraphWithTimeline(): RuntimePatternGraph { + return createTestPatternGraph({ withTimeline: true }); } /** - * Create a MasterDataset with roadmap phases + * Create a PatternGraph with roadmap phases * * Includes patterns across multiple phases with dependencies. * - * @returns MasterDataset with phase-structured patterns + * @returns PatternGraph with phase-structured patterns */ -export function createMasterDatasetWithRoadmap(): RuntimeMasterDataset { - return createTestMasterDataset({ withRoadmap: true }); +export function createPatternGraphWithRoadmap(): RuntimePatternGraph { + return createTestPatternGraph({ withRoadmap: true }); } /** - * Create a MasterDataset with patterns in specific categories + * Create a PatternGraph with patterns in specific categories * * @param categories - Categories to include (e.g., ["core", "ddd", "saga"]) * @param patternsPerCategory - Number of patterns per category - * @returns MasterDataset with patterns distributed across categories + * @returns PatternGraph with patterns distributed across categories * * @example * ```typescript - * const dataset = createMasterDatasetWithCategories( + * const dataset = createPatternGraphWithCategories( * ["core", "ddd", "saga"], * 2 * ); @@ -256,26 +254,26 @@ export function createMasterDatasetWithRoadmap(): RuntimeMasterDataset { * expect(Object.keys(dataset.byCategory)).toEqual(["core", "ddd", "saga"]); * ``` */ -export function createMasterDatasetWithCategories( +export function createPatternGraphWithCategories( categories: string[], patternsPerCategory = 2 -): RuntimeMasterDataset { +): RuntimePatternGraph { const patterns = createTestPatternSet({ categories, patternsPerCategory, stable: true, }); - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } /** - * Create a MasterDataset with ADR patterns + * Create a PatternGraph with ADR patterns * * @param count - Number of ADR patterns to create - * @returns MasterDataset with ADR-tagged patterns + * @returns PatternGraph with ADR-tagged patterns */ -export function createMasterDatasetWithADRs(count = 3): RuntimeMasterDataset { +export function createPatternGraphWithADRs(count = 3): RuntimePatternGraph { const patterns: ExtractedPattern[] = []; for (let i = 1; i <= count; i++) { @@ -290,7 +288,7 @@ export function createMasterDatasetWithADRs(count = 3): RuntimeMasterDataset { ); } - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } // ============================================================================ diff --git a/tests/steps/api/architecture-queries/arch-queries.steps.ts b/tests/steps/api/architecture-queries/arch-queries.steps.ts index 4228f1a3..360df5ba 100644 --- a/tests/steps/api/architecture-queries/arch-queries.steps.ts +++ b/tests/steps/api/architecture-queries/arch-queries.steps.ts @@ -21,11 +21,11 @@ import { findUnusedTaxonomy, type UnusedTaxonomyReport, } from '../../../../src/api/coverage-analyzer.js'; -import type { RuntimeMasterDataset } from '../../../../src/generators/pipeline/transform-types.js'; +import type { RuntimePatternGraph } from '../../../../src/generators/pipeline/transform-types.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; import { createTestPattern, - createTestMasterDataset, + createTestPatternGraph, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -36,7 +36,7 @@ const feature = await loadFeature('tests/features/api/architecture-queries/arch- // ============================================================================= interface TestState { - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; patterns: ExtractedPattern[]; neighborhood: NeighborhoodResult | undefined; comparison: ContextComparison | undefined; @@ -62,7 +62,7 @@ function initState(): TestState { function buildDataset(): void { if (state === null) return; - state.dataset = createTestMasterDataset({ patterns: state.patterns }); + state.dataset = createTestPatternGraph({ patterns: state.patterns }); } // ============================================================================= @@ -514,7 +514,7 @@ describeFeature(feature, ({ Background, Rule }) => { ); And('{string} enables {string} via reverse computation', () => { - // Reverse computation happens in createTestMasterDataset -> transformToMasterDataset + // Reverse computation happens in createTestPatternGraph -> transformToPatternGraph buildDataset(); }); diff --git a/tests/steps/api/context-assembly/context-assembler.steps.ts b/tests/steps/api/context-assembly/context-assembler.steps.ts index c82b187e..e11f3667 100644 --- a/tests/steps/api/context-assembly/context-assembler.steps.ts +++ b/tests/steps/api/context-assembly/context-assembler.steps.ts @@ -19,13 +19,13 @@ import { type SessionType, } from '../../../../src/api/context-assembler.js'; import { QueryApiError } from '../../../../src/api/types.js'; -import { createProcessStateAPI } from '../../../../src/api/process-state.js'; -import type { ProcessStateAPI } from '../../../../src/api/process-state.js'; -import type { RuntimeMasterDataset } from '../../../../src/generators/pipeline/transform-types.js'; +import { createPatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; +import type { RuntimePatternGraph } from '../../../../src/generators/pipeline/transform-types.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; import { createTestPattern, - createTestMasterDataset, + createTestPatternGraph, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -36,8 +36,8 @@ const feature = await loadFeature('tests/features/api/context-assembly/context-a // ============================================================================= interface TestState { - dataset: RuntimeMasterDataset | null; - api: ProcessStateAPI | null; + dataset: RuntimePatternGraph | null; + api: PatternGraphAPI | null; bundle: ContextBundle | null; tree: DepTreeNode | null; fileList: FileReadingList | null; @@ -64,8 +64,8 @@ function initState(): TestState { function buildDatasetAndApi(patterns: ExtractedPattern[]): void { if (state === null) return; - state.dataset = createTestMasterDataset({ patterns }); - state.api = createProcessStateAPI(state.dataset); + state.dataset = createTestPatternGraph({ patterns }); + state.api = createPatternGraphAPI(state.dataset); } // ============================================================================= @@ -751,10 +751,10 @@ describeFeature(feature, ({ Rule }) => { status: 'roadmap', phase: 12, }); - state.dataset = createTestMasterDataset({ + state.dataset = createTestPatternGraph({ patterns: [completedDep, activePattern, incompleteDep, planned], }); - state.api = createProcessStateAPI(state.dataset); + state.api = createPatternGraphAPI(state.dataset); }); When('I build the overview', () => { @@ -788,8 +788,8 @@ describeFeature(feature, ({ Rule }) => { RuleScenario('Empty dataset returns zero-state overview', ({ Given, When, Then, And }) => { Given('an empty dataset with {int} patterns', (_ctx: unknown, _count: number) => { state = initState(); - state.dataset = createTestMasterDataset(); - state.api = createProcessStateAPI(state.dataset); + state.dataset = createTestPatternGraph(); + state.api = createPatternGraphAPI(state.dataset); }); When('I build the overview', () => { diff --git a/tests/steps/api/output-shaping/output-pipeline.steps.ts b/tests/steps/api/output-shaping/output-pipeline.steps.ts index 39d7435f..fb5e8669 100644 --- a/tests/steps/api/output-shaping/output-pipeline.steps.ts +++ b/tests/steps/api/output-shaping/output-pipeline.steps.ts @@ -16,9 +16,9 @@ import { type PipelineInput, } from '../../../../src/cli/output-pipeline.js'; import { createTestPattern } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/api/output-shaping/output-pipeline.feature'); @@ -28,7 +28,7 @@ const feature = await loadFeature('tests/features/api/output-shaping/output-pipe interface PipelineTestState { patterns: ExtractedPattern[]; - dataset: MasterDataset | null; + dataset: PatternGraph | null; output: unknown; error: Error | null; scalarInput: unknown; @@ -328,7 +328,7 @@ describeFeature(feature, ({ Rule }) => { }) ), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -369,7 +369,7 @@ describeFeature(feature, ({ Rule }) => { filePath: 'src/api1.ts', }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -403,7 +403,7 @@ describeFeature(feature, ({ Rule }) => { filePath: `src/r${i}.ts`, }) ); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When( @@ -440,7 +440,7 @@ describeFeature(feature, ({ Rule }) => { filePath: `src/r${i}.ts`, }) ); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When( diff --git a/tests/steps/api/output-shaping/pattern-helpers.steps.ts b/tests/steps/api/output-shaping/pattern-helpers.steps.ts index 96f74306..733cdfde 100644 --- a/tests/steps/api/output-shaping/pattern-helpers.steps.ts +++ b/tests/steps/api/output-shaping/pattern-helpers.steps.ts @@ -14,12 +14,12 @@ import { suggestPattern, } from '../../../../src/api/pattern-helpers.js'; import { createTestPattern } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/extracted-pattern.js'; import type { - MasterDataset, + PatternGraph, RelationshipEntry, -} from '../../../../src/validation-schemas/master-dataset.js'; +} from '../../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/api/output-shaping/pattern-helpers.feature'); @@ -34,7 +34,7 @@ interface TestState { foundPattern: ExtractedPattern | undefined; relationships: RelationshipEntry | undefined; suggestion: string; - dataset: MasterDataset | null; + dataset: PatternGraph | null; candidates: readonly string[]; } @@ -170,7 +170,7 @@ describeFeature(feature, ({ Rule }) => { createTestPattern({ name, filePath: 'src/order.ts', uses: ['EventStore'] }), createTestPattern({ name: 'EventStore', filePath: 'src/event.ts' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('I get relationships for {string}', (_ctx: unknown, name: string) => { @@ -189,7 +189,7 @@ describeFeature(feature, ({ Rule }) => { createTestPattern({ name, filePath: 'src/order.ts', uses: ['EventStore'] }), createTestPattern({ name: 'EventStore', filePath: 'src/event.ts' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('I get relationships for {string}', (_ctx: unknown, name: string) => { @@ -205,7 +205,7 @@ describeFeature(feature, ({ Rule }) => { Given('a dataset without relationship index', () => { state = initState(); // Empty dataset has no relationship index - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); }); When('I get relationships for {string}', (_ctx: unknown, name: string) => { diff --git a/tests/steps/api/process-state-api.steps.ts b/tests/steps/api/pattern-graph-api.steps.ts similarity index 97% rename from tests/steps/api/process-state-api.steps.ts rename to tests/steps/api/pattern-graph-api.steps.ts index 9d7a94a6..a46a4375 100644 --- a/tests/steps/api/process-state-api.steps.ts +++ b/tests/steps/api/pattern-graph-api.steps.ts @@ -1,15 +1,15 @@ /** * Process State API Step Definitions * - * BDD step definitions for testing the ProcessStateAPI query interface. + * BDD step definitions for testing the PatternGraphAPI query interface. * * @architect */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; -import { createProcessStateAPI, type ProcessStateAPI } from '../../../src/api/index.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { createPatternGraphAPI, type PatternGraphAPI } from '../../../src/api/index.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; import type { ProcessStatusValue } from '../../../src/taxonomy/index.js'; @@ -20,7 +20,7 @@ import { createTestPattern } from '../../fixtures/pattern-factories.js'; // ============================================================================= interface APITestState { - api: ProcessStateAPI | null; + api: PatternGraphAPI | null; patterns: ExtractedPattern[]; queryResult: ExtractedPattern[] | undefined; phaseProgress: @@ -59,18 +59,18 @@ function initState(): APITestState { function buildAPI(): void { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); - state!.api = createProcessStateAPI(dataset); + state!.api = createPatternGraphAPI(dataset); } // ============================================================================= // Feature Definition // ============================================================================= -const feature = await loadFeature('tests/features/api/process-state-api.feature'); +const feature = await loadFeature('tests/features/api/pattern-graph-api.feature'); describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { AfterEachScenario(() => { @@ -78,7 +78,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); Background(({ Given }) => { - Given('a test MasterDataset is initialized', () => { + Given('a test PatternGraph is initialized', () => { state = initState(); }); }); diff --git a/tests/steps/api/session-support/handoff-generator.steps.ts b/tests/steps/api/session-support/handoff-generator.steps.ts index cc1a5833..219b45e0 100644 --- a/tests/steps/api/session-support/handoff-generator.steps.ts +++ b/tests/steps/api/session-support/handoff-generator.steps.ts @@ -13,11 +13,11 @@ import { } from '../../../../src/api/handoff-generator.js'; import { QueryApiError } from '../../../../src/api/types.js'; import { createTestPattern } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; -import { createProcessStateAPI } from '../../../../src/api/process-state.js'; -import type { ProcessStateAPI } from '../../../../src/api/process-state.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; +import { createPatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/api/session-support/handoff-generator.feature'); @@ -26,8 +26,8 @@ const feature = await loadFeature('tests/features/api/session-support/handoff-ge // ============================================================================= interface HandoffTestState { - api: ProcessStateAPI | null; - dataset: MasterDataset | null; + api: PatternGraphAPI | null; + dataset: PatternGraph | null; doc: HandoffDocument | null; formattedOutput: string; thrownError: unknown; @@ -46,11 +46,11 @@ function initState(): HandoffTestState { } function buildApiAndDataset(patterns: ExtractedPattern[]): { - api: ProcessStateAPI; - dataset: MasterDataset; + api: PatternGraphAPI; + dataset: PatternGraph; } { - const dataset = createTestMasterDataset({ patterns }); - const api = createProcessStateAPI(dataset); + const dataset = createTestPatternGraph({ patterns }); + const api = createPatternGraphAPI(dataset); return { api, dataset }; } diff --git a/tests/steps/api/session-support/scope-validator.steps.ts b/tests/steps/api/session-support/scope-validator.steps.ts index 02ae0fae..84037a70 100644 --- a/tests/steps/api/session-support/scope-validator.steps.ts +++ b/tests/steps/api/session-support/scope-validator.steps.ts @@ -13,11 +13,11 @@ import { } from '../../../../src/api/scope-validator.js'; import { QueryApiError } from '../../../../src/api/types.js'; import { createTestPattern } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; -import { createProcessStateAPI } from '../../../../src/api/process-state.js'; -import type { ProcessStateAPI } from '../../../../src/api/process-state.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; +import { createPatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; +import type { PatternGraphAPI } from '../../../../src/api/pattern-graph-api.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/api/session-support/scope-validator.feature'); @@ -26,8 +26,8 @@ const feature = await loadFeature('tests/features/api/session-support/scope-vali // ============================================================================= interface ScopeValidatorTestState { - api: ProcessStateAPI | null; - dataset: MasterDataset | null; + api: PatternGraphAPI | null; + dataset: PatternGraph | null; result: ScopeValidationResult | null; formattedOutput: string; thrownError: unknown; @@ -46,11 +46,11 @@ function initState(): ScopeValidatorTestState { } function buildApiAndDataset(patterns: ExtractedPattern[]): { - api: ProcessStateAPI; - dataset: MasterDataset; + api: PatternGraphAPI; + dataset: PatternGraph; } { - const dataset = createTestMasterDataset({ patterns }); - const api = createProcessStateAPI(dataset); + const dataset = createTestPatternGraph({ patterns }); + const api = createPatternGraphAPI(dataset); return { api, dataset }; } diff --git a/tests/steps/api/stub-integration/stub-resolver.steps.ts b/tests/steps/api/stub-integration/stub-resolver.steps.ts index b8d45e6f..af3f22e0 100644 --- a/tests/steps/api/stub-integration/stub-resolver.steps.ts +++ b/tests/steps/api/stub-integration/stub-resolver.steps.ts @@ -19,9 +19,9 @@ import { type PdrReference, } from '../../../../src/api/stub-resolver.js'; import { createTestPattern } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/api/stub-integration/stub-resolver.feature'); @@ -30,7 +30,7 @@ const feature = await loadFeature('tests/features/api/stub-integration/stub-reso // ============================================================================= interface StubResolverTestState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; patterns: ExtractedPattern[]; stubPatterns: readonly ExtractedPattern[]; resolutions: readonly StubResolution[]; @@ -75,7 +75,7 @@ describeFeature(feature, ({ Rule }) => { status: 'active', }); state.patterns = [stubPattern, normalPattern]; - state.dataset = createTestMasterDataset({ patterns: state.patterns }); + state.dataset = createTestPatternGraph({ patterns: state.patterns }); }); When('finding stub patterns from the dataset', () => { @@ -103,7 +103,7 @@ describeFeature(feature, ({ Rule }) => { status: 'active', }); state.patterns = [withTarget, withoutTarget]; - state.dataset = createTestMasterDataset({ patterns: state.patterns }); + state.dataset = createTestPatternGraph({ patterns: state.patterns }); }); When('finding stub patterns from the dataset', () => { diff --git a/tests/steps/architecture/arch-index.steps.ts b/tests/steps/architecture/arch-index.steps.ts index 872a6384..21062172 100644 --- a/tests/steps/architecture/arch-index.steps.ts +++ b/tests/steps/architecture/arch-index.steps.ts @@ -2,7 +2,7 @@ * Architecture Index Step Definitions * * BDD step definitions for testing the archIndex built during - * transformToMasterDataset. The archIndex groups patterns by role, + * transformToPatternGraph. The archIndex groups patterns by role, * context, and layer for efficient architecture diagram generation. * * @architect @@ -11,8 +11,8 @@ import { expect } from 'vitest'; import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createDefaultTagRegistry, createTestPattern } from '../../fixtures/dataset-factories.js'; import type { DataTableRow } from '../../support/world.js'; @@ -23,7 +23,7 @@ import type { DataTableRow } from '../../support/world.js'; interface ArchIndexState { patterns: ExtractedPattern[]; - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; } // ============================================================================= @@ -126,9 +126,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } }); - When('transformToMasterDataset runs', () => { + When('transformToPatternGraph runs', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -173,9 +173,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } }); - When('transformToMasterDataset runs', () => { + When('transformToPatternGraph runs', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -220,9 +220,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } }); - When('transformToMasterDataset runs', () => { + When('transformToPatternGraph runs', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -275,9 +275,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } }); - When('transformToMasterDataset runs', () => { + When('transformToPatternGraph runs', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -327,9 +327,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } }); - When('transformToMasterDataset runs', () => { + When('transformToPatternGraph runs', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/architecture/component-diagram.steps.ts b/tests/steps/architecture/component-diagram.steps.ts index 84c52098..88e1b1b7 100644 --- a/tests/steps/architecture/component-diagram.steps.ts +++ b/tests/steps/architecture/component-diagram.steps.ts @@ -15,7 +15,7 @@ import { createArchitectureCodec, type ArchitectureCodecOptions, } from '../../../src/renderable/codecs/architecture.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createDefaultTagRegistry, createTestPattern } from '../../fixtures/dataset-factories.js'; @@ -99,7 +99,7 @@ function generateDiagram(): void { if (!state) throw new Error('State not initialized'); // Build dataset with patterns - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/architecture/generator-registration.steps.ts b/tests/steps/architecture/generator-registration.steps.ts index 1c000050..aa2ae327 100644 --- a/tests/steps/architecture/generator-registration.steps.ts +++ b/tests/steps/architecture/generator-registration.steps.ts @@ -11,7 +11,7 @@ import { expect } from 'vitest'; import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { generatorRegistry } from '../../../src/generators/registry.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import type { GeneratorContext, GeneratorOutput } from '../../../src/generators/types.js'; import { createDefaultTagRegistry, createTestPattern } from '../../fixtures/dataset-factories.js'; @@ -92,7 +92,7 @@ async function runArchitectureGenerator(): Promise { // Build dataset with patterns const tagRegistry = createDefaultTagRegistry(); - const masterDataset = transformToMasterDataset({ + const patternGraph = transformToPatternGraph({ patterns: state.patterns, tagRegistry, workflow: undefined, @@ -103,7 +103,7 @@ async function runArchitectureGenerator(): Promise { baseDir: '/test', outputDir: '/test/output', registry: tagRegistry, - masterDataset, + patternGraph, codecOptions: state.codecOptions, }; diff --git a/tests/steps/architecture/layered-diagram.steps.ts b/tests/steps/architecture/layered-diagram.steps.ts index b9b23678..74496ac0 100644 --- a/tests/steps/architecture/layered-diagram.steps.ts +++ b/tests/steps/architecture/layered-diagram.steps.ts @@ -15,7 +15,7 @@ import { createArchitectureCodec, type ArchitectureCodecOptions, } from '../../../src/renderable/codecs/architecture.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createDefaultTagRegistry, createTestPattern } from '../../fixtures/dataset-factories.js'; @@ -89,7 +89,7 @@ function generateDiagram(): void { if (!state) throw new Error('State not initialized'); // Build dataset with patterns - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/behavior/cli/process-api-reference.steps.ts b/tests/steps/behavior/cli/process-api-reference.steps.ts index fe6bcb70..b8693e4c 100644 --- a/tests/steps/behavior/cli/process-api-reference.steps.ts +++ b/tests/steps/behavior/cli/process-api-reference.steps.ts @@ -34,7 +34,7 @@ function createMockGeneratorContext(): GeneratorContext { baseDir: process.cwd(), outputDir: 'docs-live', registry: {} as GeneratorContext['registry'], - masterDataset: {} as GeneratorContext['masterDataset'], + patternGraph: {} as GeneratorContext['patternGraph'], } as GeneratorContext; } diff --git a/tests/steps/behavior/codecs/composite-codec.steps.ts b/tests/steps/behavior/codecs/composite-codec.steps.ts index 2bad5a2b..d6117a6e 100644 --- a/tests/steps/behavior/codecs/composite-codec.steps.ts +++ b/tests/steps/behavior/codecs/composite-codec.steps.ts @@ -5,7 +5,7 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { z } from 'zod'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { RenderableDocument, SectionBlock } from '../../../../src/renderable/schema.js'; import { paragraph, document } from '../../../../src/renderable/schema.js'; import type { DocumentCodec } from '../../../../src/renderable/codecs/types/base.js'; @@ -13,9 +13,9 @@ import { createCompositeCodec, composeDocuments, } from '../../../../src/renderable/codecs/composite.js'; -import { MasterDatasetSchema } from '../../../../src/validation-schemas/master-dataset.js'; +import { PatternGraphSchema } from '../../../../src/validation-schemas/pattern-graph.js'; import { RenderableDocumentOutputSchema } from '../../../../src/renderable/codecs/shared-schema.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; import { resetPatternCounter } from '../../../fixtures/pattern-factories.js'; import { findParagraphs, findBlocksByType } from '../../../support/helpers/document-assertions.js'; @@ -26,7 +26,7 @@ import { findParagraphs, findBlocksByType } from '../../../support/helpers/docum interface CompositeCodecState { codecs: DocumentCodec[]; documents: RenderableDocument[]; - dataset: MasterDataset; + dataset: PatternGraph; result: RenderableDocument | null; } @@ -35,7 +35,7 @@ function initState(): CompositeCodecState { return { codecs: [], documents: [], - dataset: createTestMasterDataset({ patterns: [] }), + dataset: createTestPatternGraph({ patterns: [] }), result: null, }; } @@ -47,8 +47,8 @@ let state: CompositeCodecState | null = null; // ============================================================================ function stubCodec(doc: RenderableDocument): DocumentCodec { - return z.codec(MasterDatasetSchema, RenderableDocumentOutputSchema, { - decode: (_dataset: MasterDataset): RenderableDocument => doc, + return z.codec(PatternGraphSchema, RenderableDocumentOutputSchema, { + decode: (_dataset: PatternGraph): RenderableDocument => doc, encode: (): never => { throw new Error('stub codec is decode-only'); }, diff --git a/tests/steps/behavior/codecs/convention-extractor.steps.ts b/tests/steps/behavior/codecs/convention-extractor.steps.ts index 84c5402e..cc2a5cc4 100644 --- a/tests/steps/behavior/codecs/convention-extractor.steps.ts +++ b/tests/steps/behavior/codecs/convention-extractor.steps.ts @@ -4,20 +4,20 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import { extractConventions, type ConventionBundle, } from '../../../../src/renderable/codecs/convention-extractor.js'; import { createTestPattern, resetPatternCounter } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; // ============================================================================ // State // ============================================================================ interface ConventionExtractorState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; result: ConventionBundle[]; } @@ -51,8 +51,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('Empty and missing inputs produce empty results', ({ RuleScenario }) => { RuleScenario('Empty convention tags returns empty array', ({ Given, When, Then }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset({ patterns: [] }); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph({ patterns: [] }); }); When('extracting conventions for no tags', () => { @@ -65,8 +65,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('No matching patterns returns empty array', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns but no convention tags', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns but no convention tags', () => { + state!.dataset = createTestPatternGraph({ patterns: [createTestPattern({ name: 'PlainPattern' })], }); }); @@ -90,7 +90,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'Single pattern with one convention tag produces one bundle', ({ Given, When, Then, And }) => { Given('a pattern tagged with convention {string}', (_ctx: unknown, tag: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ADR004', @@ -132,7 +132,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a pattern tagged with conventions {string} and {string}', (_ctx: unknown, tag1: string, tag2: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'MultiConvention', @@ -184,9 +184,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); // Build dataset incrementally — store patterns if (!state!.dataset) { - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); } else { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [...state!.dataset.patterns, pattern], }); } @@ -208,7 +208,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }, ], }); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [...state!.dataset!.patterns, pattern], }); } @@ -244,7 +244,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a pattern with convention {string} and rule description:', (_ctx: unknown, tag: string, docString: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'StructuredADR', @@ -283,7 +283,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a pattern with convention {string} and rule description:', (_ctx: unknown, tag: string, docString: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TableADR', @@ -340,7 +340,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ' active --> completed', '"""', ].join('\n'); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'MermaidADR', @@ -385,7 +385,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a pattern with convention {string} and rule description:', (_ctx: unknown, tag: string, docString: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'PlainADR', @@ -437,7 +437,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { '## Terminal States Are Immutable', '**Invariant:** Completed patterns cannot be modified without unlock.', ].join('\n'); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TsConventionPattern', @@ -482,7 +482,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a TypeScript pattern {string} with convention {string} and description:', (_ctx: unknown, name: string, tag: string, docString: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name, @@ -535,7 +535,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }, ], }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); } ); @@ -548,7 +548,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { description: docString, filePath: 'src/conventions/ts-conventions.ts', }); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [...state!.dataset!.patterns, pattern], }); } @@ -578,7 +578,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Given( 'a TypeScript pattern with convention {string} and empty description', (_ctx: unknown, tag: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'EmptyTsPattern', @@ -618,7 +618,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { '| roadmap | None |', '| active | Scope-locked |', ].join('\n'); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TsTablePattern', @@ -658,7 +658,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { '| --- | --- | --- | --- |', '| sortBy | "phase" \\| "priority" \\| "effort" \\| "quarter" | "phase" | Sort order |', ].join('\n'); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TsEscapedUnionPattern', @@ -719,7 +719,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ' active --> completed', '"""', ].join('\n'); - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TsMermaidPattern', diff --git a/tests/steps/behavior/codecs/generated-doc-quality.steps.ts b/tests/steps/behavior/codecs/generated-doc-quality.steps.ts index 5fb4763f..09ce7c5d 100644 --- a/tests/steps/behavior/codecs/generated-doc-quality.steps.ts +++ b/tests/steps/behavior/codecs/generated-doc-quality.steps.ts @@ -9,7 +9,7 @@ import { initState, createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findHeadings, findTables, findLists, @@ -74,7 +74,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { '**Rationale:** Prevents drift.\n\n' + '| Value | Meaning |\n| --- | --- |\n| alpha | First |\n| beta | Second |\n\n' + '**Verified by:** Table validation'; - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionWithTable', @@ -153,7 +153,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { '**Rationale:** Prevents drift.\n\n' + '| Value | Meaning |\n| --- | --- |\n| alpha | First |\n| beta | Second |\n\n' + '**Verified by:** Table validation'; - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionWithTable', @@ -220,7 +220,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And('a dataset with both convention content and shape content', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionPattern', @@ -299,7 +299,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And('a dataset with multiple patterns in the Generation area', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'GenPattern1', @@ -401,7 +401,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And('a dataset with Generation area patterns', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'GenerationCodec', diff --git a/tests/steps/behavior/codecs/planning-codecs.steps.ts b/tests/steps/behavior/codecs/planning-codecs.steps.ts index 4ccebdfe..cd60aee1 100644 --- a/tests/steps/behavior/codecs/planning-codecs.steps.ts +++ b/tests/steps/behavior/codecs/planning-codecs.steps.ts @@ -21,9 +21,9 @@ import { SessionFindingsCodec, } from '../../../../src/renderable/codecs/planning.js'; import type { RenderableDocument, TableBlock } from '../../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -42,7 +42,7 @@ import type { DataTableRow } from '../../../support/world.js'; // ============================================================================= interface PlanningCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -136,7 +136,7 @@ function findSectionList(doc: RenderableDocument, sectionName: string): string[] // Dataset Factories // ============================================================================= -function createDatasetWithNoActionablePhases(): MasterDataset { +function createDatasetWithNoActionablePhases(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Pattern', @@ -144,10 +144,10 @@ function createDatasetWithNoActionablePhases(): MasterDataset { phase: 1, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithPlanningPatterns(): MasterDataset { +function createDatasetWithPlanningPatterns(): PatternGraph { const patterns = [ createTestPattern({ name: 'Foundation Pattern', @@ -165,10 +165,10 @@ function createDatasetWithPlanningPatterns(): MasterDataset { phase: 3, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithDeliverables(): MasterDataset { +function createDatasetWithDeliverables(): PatternGraph { const patterns = [ createTestPattern({ name: 'Pattern With Deliverables', @@ -180,10 +180,10 @@ function createDatasetWithDeliverables(): MasterDataset { ], }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithScenarios(): MasterDataset { +function createDatasetWithScenarios(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Scenarios', status: 'active', @@ -219,10 +219,10 @@ function createDatasetWithScenarios(): MasterDataset { steps: [{ keyword: 'Given', text: 'a logged in user' }], }, ]; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithDependencies(): MasterDataset { +function createDatasetWithDependencies(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Dependency', @@ -241,10 +241,10 @@ function createDatasetWithDependencies(): MasterDataset { phase: 2, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithActiveAndPlanned(): MasterDataset { +function createDatasetWithActiveAndPlanned(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Base', @@ -267,10 +267,10 @@ function createDatasetWithActiveAndPlanned(): MasterDataset { phase: 3, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithOnlyCompleted(): MasterDataset { +function createDatasetWithOnlyCompleted(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Pattern 1', @@ -283,10 +283,10 @@ function createDatasetWithOnlyCompleted(): MasterDataset { phase: 1, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithUseCases(): MasterDataset { +function createDatasetWithUseCases(): PatternGraph { const patterns = [ createTestPattern({ name: 'Pattern With Use Cases', @@ -299,10 +299,10 @@ function createDatasetWithUseCases(): MasterDataset { ], }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithRules(): MasterDataset { +function createDatasetWithRules(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Rules', status: 'active', @@ -329,10 +329,10 @@ function createDatasetWithRules(): MasterDataset { scenarioNames: ['Valid order', 'Empty order', 'Invalid quantity'], }, ]; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithoutFindings(): MasterDataset { +function createDatasetWithoutFindings(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Pattern', @@ -340,10 +340,10 @@ function createDatasetWithoutFindings(): MasterDataset { phase: 1, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithFindings(): MasterDataset { +function createDatasetWithFindings(): PatternGraph { const pattern1 = createTestPattern({ name: 'Pattern With Findings', status: 'completed', @@ -366,10 +366,10 @@ function createDatasetWithFindings(): MasterDataset { ]; patternWithFindings.risk = 'Scaling concerns'; - return createTestMasterDataset({ patterns: [pattern1] }); + return createTestPatternGraph({ patterns: [pattern1] }); } -function createDatasetWithDiscoveredGaps(): MasterDataset { +function createDatasetWithDiscoveredGaps(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Gaps', status: 'completed', @@ -379,10 +379,10 @@ function createDatasetWithDiscoveredGaps(): MasterDataset { 'Gap 1: Missing validation', 'Gap 2: No error messages', ]; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithDiscoveredImprovements(): MasterDataset { +function createDatasetWithDiscoveredImprovements(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Improvements', status: 'completed', @@ -392,10 +392,10 @@ function createDatasetWithDiscoveredImprovements(): MasterDataset { 'Improvement 1: Add caching', 'Improvement 2: Optimize queries', ]; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithDiscoveredRisks(): MasterDataset { +function createDatasetWithDiscoveredRisks(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Risks', status: 'completed', @@ -407,10 +407,10 @@ function createDatasetWithDiscoveredRisks(): MasterDataset { }; patternWithRisks.discoveredRisks = ['Risk 1: Security vulnerability']; patternWithRisks.risk = 'Risk 2: Performance issue'; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithDiscoveredLearnings(): MasterDataset { +function createDatasetWithDiscoveredLearnings(): PatternGraph { const pattern = createTestPattern({ name: 'Pattern With Learnings', status: 'completed', @@ -420,10 +420,10 @@ function createDatasetWithDiscoveredLearnings(): MasterDataset { 'Learning 1: Use composition', 'Learning 2: Prefer immutability', ]; - return createTestMasterDataset({ patterns: [pattern] }); + return createTestPatternGraph({ patterns: [pattern] }); } -function createDatasetWithFindingsAcrossPhases(): MasterDataset { +function createDatasetWithFindingsAcrossPhases(): PatternGraph { const pattern1 = createTestPattern({ name: 'Phase 1 Pattern', status: 'completed', @@ -438,7 +438,7 @@ function createDatasetWithFindingsAcrossPhases(): MasterDataset { }); (pattern2 as unknown as { discoveredGaps: string[] }).discoveredGaps = ['Phase 2 gap']; - return createTestMasterDataset({ patterns: [pattern1, pattern2] }); + return createTestPatternGraph({ patterns: [pattern1, pattern2] }); } // ============================================================================= @@ -464,7 +464,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PlanningChecklistCodec prepares for implementation sessions', ({ RuleScenario }) => { RuleScenario('No actionable phases produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with no actionable phases', () => { + Given('a PatternGraph with no actionable phases', () => { state!.dataset = createDatasetWithNoActionablePhases(); }); @@ -483,7 +483,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows phases to plan count', ({ Given, When, Then, And }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -510,7 +510,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Pre-planning questions section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -538,7 +538,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Definition of Done with deliverables', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with deliverables', () => { + Given('a PatternGraph with patterns with deliverables', () => { state!.dataset = createDatasetWithDeliverables(); }); @@ -560,7 +560,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Acceptance criteria from scenarios', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with scenarios', () => { + Given('a PatternGraph with patterns with scenarios', () => { state!.dataset = createDatasetWithScenarios(); }); @@ -582,7 +582,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Risk assessment section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -611,7 +611,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Dependency status shows met vs unmet', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with dependencies', () => { + Given('a PatternGraph with patterns with dependencies', () => { state!.dataset = createDatasetWithDependencies(); }); @@ -638,7 +638,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('forActivePhases option', ({ Given, When, Then }) => { - Given('a MasterDataset with active and planned patterns', () => { + Given('a PatternGraph with active and planned patterns', () => { state!.dataset = createDatasetWithActiveAndPlanned(); }); @@ -658,7 +658,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('forNextActionable option', ({ Given, When, Then }) => { - Given('a MasterDataset with active and planned patterns', () => { + Given('a PatternGraph with active and planned patterns', () => { state!.dataset = createDatasetWithActiveAndPlanned(); }); @@ -684,7 +684,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('SessionPlanCodec generates implementation plans', ({ RuleScenario }) => { RuleScenario('No phases to plan produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with only completed patterns', () => { + Given('a PatternGraph with only completed patterns', () => { state!.dataset = createDatasetWithOnlyCompleted(); }); @@ -703,7 +703,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows status counts', ({ Given, When, Then, And }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -730,7 +730,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Implementation approach from useCases', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with useCases', () => { + Given('a PatternGraph with patterns with useCases', () => { state!.dataset = createDatasetWithUseCases(); }); @@ -752,7 +752,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Deliverables rendering', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with deliverables', () => { + Given('a PatternGraph with patterns with deliverables', () => { state!.dataset = createDatasetWithDeliverables(); }); @@ -782,7 +782,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Acceptance criteria with steps', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with scenarios', () => { + Given('a PatternGraph with patterns with scenarios', () => { state!.dataset = createDatasetWithScenarios(); }); @@ -804,7 +804,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Business rules section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with rules', () => { + Given('a PatternGraph with patterns with rules', () => { state!.dataset = createDatasetWithRules(); }); @@ -826,7 +826,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('statusFilter option for active only', ({ Given, When, Then }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -843,7 +843,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('statusFilter option for planned only', ({ Given, When, Then }) => { - Given('a MasterDataset with planning patterns', () => { + Given('a PatternGraph with planning patterns', () => { state!.dataset = createDatasetWithPlanningPatterns(); }); @@ -866,7 +866,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('SessionFindingsCodec captures retrospective discoveries', ({ RuleScenario }) => { RuleScenario('No findings produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns without findings', () => { + Given('a PatternGraph with patterns without findings', () => { state!.dataset = createDatasetWithoutFindings(); }); @@ -885,7 +885,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows finding type counts', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindings(); }); @@ -912,7 +912,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Gaps section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with discovered gaps', () => { + Given('a PatternGraph with patterns with discovered gaps', () => { state!.dataset = createDatasetWithDiscoveredGaps(); }); @@ -934,7 +934,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Improvements section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with discovered improvements', () => { + Given('a PatternGraph with patterns with discovered improvements', () => { state!.dataset = createDatasetWithDiscoveredImprovements(); }); @@ -956,7 +956,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Risks section includes risk field', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with discovered risks', () => { + Given('a PatternGraph with patterns with discovered risks', () => { state!.dataset = createDatasetWithDiscoveredRisks(); }); @@ -980,7 +980,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Learnings section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with discovered learnings', () => { + Given('a PatternGraph with patterns with discovered learnings', () => { state!.dataset = createDatasetWithDiscoveredLearnings(); }); @@ -1002,7 +1002,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('groupBy category option', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindings(); }); @@ -1021,7 +1021,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('groupBy phase option', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindingsAcrossPhases(); }); @@ -1039,7 +1039,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('groupBy type option', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindings(); }); @@ -1059,7 +1059,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('showSourcePhase option enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindingsAcrossPhases(); }); @@ -1076,7 +1076,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('showSourcePhase option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with findings', () => { + Given('a PatternGraph with patterns with findings', () => { state!.dataset = createDatasetWithFindingsAcrossPhases(); }); diff --git a/tests/steps/behavior/codecs/pr-changes-codec-options.steps.ts b/tests/steps/behavior/codecs/pr-changes-codec-options.steps.ts index 23cca986..38b16ff5 100644 --- a/tests/steps/behavior/codecs/pr-changes-codec-options.steps.ts +++ b/tests/steps/behavior/codecs/pr-changes-codec-options.steps.ts @@ -39,7 +39,7 @@ import { createPatternsOfAllStatuses, createDeferredPatterns, createCompletedPatterns, - createTestMasterDataset, + createTestPatternGraph, } from '../../../support/helpers/pr-changes-codec-state.js'; import type { DataTableRow } from '../../../support/world.js'; @@ -78,8 +78,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Review checklist generated with standard items', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PR-relevant patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrRelevantPatterns() }); + Given('a PatternGraph with PR-relevant patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrRelevantPatterns() }); }); When('decoding with includeReviewChecklist enabled', () => { @@ -109,8 +109,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Review checklist includes completed patterns item when applicable', ({ Given, When, Then }) => { - Given('a MasterDataset with completed patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createCompletedPatterns() }); + Given('a PatternGraph with completed patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createCompletedPatterns() }); }); When('decoding with includeReviewChecklist enabled', () => { @@ -129,8 +129,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Review checklist includes active work item when applicable', ({ Given, When, Then }) => { - Given('a MasterDataset with active patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createActivePatterns() }); + Given('a PatternGraph with active patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createActivePatterns() }); }); When('decoding with includeReviewChecklist enabled', () => { @@ -149,8 +149,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Review checklist includes dependencies item when patterns have dependencies', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with dependencies', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with dependencies', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDependencies(), }); }); @@ -171,8 +171,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Review checklist includes deliverables item when patterns have deliverables', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with deliverables', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDeliverables(), }); }); @@ -193,8 +193,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No review checklist when includeReviewChecklist is disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with PR-relevant patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrRelevantPatterns() }); + Given('a PatternGraph with PR-relevant patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrRelevantPatterns() }); }); When('decoding with includeReviewChecklist disabled', () => { @@ -223,8 +223,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Dependencies section shows depends on relationships', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with dependsOn relationships', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithDependsOn() }); + Given('a PatternGraph with patterns with dependsOn relationships', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDependsOn() }); }); When('decoding with includeDependencies enabled', () => { @@ -248,8 +248,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Dependencies section shows enables relationships', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with enables relationships', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithEnables() }); + Given('a PatternGraph with patterns with enables relationships', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithEnables() }); }); When('decoding with includeDependencies enabled', () => { @@ -270,8 +270,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No dependencies section when patterns have no dependencies', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns without dependencies', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns without dependencies', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithoutDependencies(), }); }); @@ -293,8 +293,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No dependencies section when includeDependencies is disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with dependencies', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with dependencies', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDependencies(), }); }); @@ -321,8 +321,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec filters patterns by changedFiles', ({ RuleScenario }) => { RuleScenario('Patterns filtered by changedFiles match', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns from various files', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsFromVariousFiles() }); + Given('a PatternGraph with patterns from various files', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsFromVariousFiles() }); }); When('decoding with changedFiles filter matching specific patterns', () => { @@ -341,8 +341,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('changedFiles filter matches partial paths', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns from various files', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsFromVariousFiles() }); + Given('a PatternGraph with patterns from various files', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsFromVariousFiles() }); }); When('decoding with changedFiles filter for a directory path', () => { @@ -365,8 +365,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec filters patterns by releaseFilter', ({ RuleScenario }) => { RuleScenario('Patterns filtered by release version', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with different release deliverables', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with different release deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDifferentReleases(), }); }); @@ -392,8 +392,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Combined filters match patterns meeting either criterion', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns matching file or release', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns matching file or release', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsMatchingFileOrRelease(), }); }); @@ -415,8 +415,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Patterns matching both criteria are not duplicated', ({ Given, When, Then }) => { - Given('a MasterDataset with a pattern matching both file and release', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with a pattern matching both file and release', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternMatchingBothFileAndRelease(), }); }); @@ -445,8 +445,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec only includes active and completed patterns', ({ RuleScenario }) => { RuleScenario('Roadmap patterns are excluded', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns of all statuses', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsOfAllStatuses() }); + Given('a PatternGraph with patterns of all statuses', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsOfAllStatuses() }); }); When('decoding with PrChangesCodec', () => { @@ -462,8 +462,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Deferred patterns are excluded', ({ Given, When, Then }) => { - Given('a MasterDataset with deferred patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createDeferredPatterns() }); + Given('a PatternGraph with deferred patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createDeferredPatterns() }); }); When('decoding with PrChangesCodec', () => { diff --git a/tests/steps/behavior/codecs/pr-changes-codec-rendering.steps.ts b/tests/steps/behavior/codecs/pr-changes-codec-rendering.steps.ts index a62cb25c..324f10d5 100644 --- a/tests/steps/behavior/codecs/pr-changes-codec-rendering.steps.ts +++ b/tests/steps/behavior/codecs/pr-changes-codec-rendering.steps.ts @@ -38,7 +38,7 @@ import { createPatternWithBusinessValue, createPatternsWithScenarios, createPatternsWithBusinessRules, - createTestMasterDataset, + createTestPatternGraph, } from '../../../support/helpers/pr-changes-codec-state.js'; import type { DataTableRow } from '../../../support/world.js'; @@ -75,8 +75,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No changes when no patterns match changedFiles filter', ({ Given, When, Then, And }) => { - Given('a MasterDataset with active patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createActivePatterns() }); + Given('a PatternGraph with active patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createActivePatterns() }); }); When('decoding with changedFiles filter for non-matching paths', () => { @@ -105,8 +105,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No changes when no patterns match releaseFilter', ({ Given, When, Then, And }) => { - Given('a MasterDataset with active patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createActivePatterns() }); + Given('a PatternGraph with active patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createActivePatterns() }); }); When('decoding with releaseFilter {string}', (_ctx: unknown, release: string) => { @@ -129,8 +129,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No changes with combined filters when nothing matches', ({ Given, When, Then, And }) => { - Given('a MasterDataset with active patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createActivePatterns() }); + Given('a PatternGraph with active patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createActivePatterns() }); }); When('decoding with changedFiles and releaseFilter that match nothing', () => { @@ -161,8 +161,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec generates summary with filter information', ({ RuleScenario }) => { RuleScenario('Summary section shows pattern counts', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PR-relevant patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrRelevantPatterns() }); + Given('a PatternGraph with PR-relevant patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrRelevantPatterns() }); }); When('decoding with PrChangesCodec', () => { @@ -192,8 +192,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows release tag when releaseFilter is set', ({ Given, When, Then }) => { - Given('a MasterDataset with PR-relevant patterns with deliverables', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithDeliverables() }); + Given('a PatternGraph with PR-relevant patterns with deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDeliverables() }); }); When('decoding with releaseFilter {string}', (_ctx: unknown, release: string) => { @@ -212,8 +212,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Summary shows files filter count when changedFiles is set', ({ Given, When, Then }) => { - Given('a MasterDataset with PR-relevant patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrRelevantPatterns() }); + Given('a PatternGraph with PR-relevant patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrRelevantPatterns() }); }); When('decoding with changedFiles filter for matching paths', () => { @@ -239,8 +239,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec groups changes by phase when sortBy is "phase"', ({ RuleScenario }) => { RuleScenario('Changes grouped by phase with default sortBy', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns in multiple phases', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsInMultiplePhases() }); + Given('a PatternGraph with patterns in multiple phases', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsInMultiplePhases() }); }); When('decoding with PrChangesCodec', () => { @@ -266,8 +266,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Pattern details shown within phase groups', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns in multiple phases', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsInMultiplePhases() }); + Given('a PatternGraph with patterns in multiple phases', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsInMultiplePhases() }); }); When('decoding with PrChangesCodec', () => { @@ -293,8 +293,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'PrChangesCodec groups changes by priority when sortBy is "priority"', ({ RuleScenario }) => { RuleScenario('Changes grouped by priority', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with different priorities', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithPriorities() }); + Given('a PatternGraph with patterns with different priorities', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithPriorities() }); }); When('decoding with sortBy {string}', (_ctx: unknown, sortBy: string) => { @@ -324,8 +324,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Priority groups show correct patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with different priorities', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithPriorities() }); + Given('a PatternGraph with patterns with different priorities', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithPriorities() }); }); When('decoding with sortBy {string}', (_ctx: unknown, sortBy: string) => { @@ -352,8 +352,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec shows flat list when sortBy is "workflow"', ({ RuleScenario }) => { RuleScenario('Flat changes list with workflow sort', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PR-relevant patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrRelevantPatterns() }); + Given('a PatternGraph with PR-relevant patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrRelevantPatterns() }); }); When('decoding with sortBy {string}', (_ctx: unknown, sortBy: string) => { @@ -381,8 +381,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'PrChangesCodec renders pattern details with metadata and description', ({ RuleScenario }) => { RuleScenario('Pattern detail shows metadata table', ({ Given, When, Then }) => { - Given('a MasterDataset with a detailed pattern', () => { - state!.dataset = createTestMasterDataset({ patterns: createDetailedPattern() }); + Given('a PatternGraph with a detailed pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: createDetailedPattern() }); }); When('decoding with PrChangesCodec', () => { @@ -407,8 +407,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Pattern detail shows business value when available', ({ Given, When, Then }) => { - Given('a MasterDataset with a pattern with business value', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with a pattern with business value', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternWithBusinessValue(), }); }); @@ -434,8 +434,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Pattern detail shows description', ({ Given, When, Then }) => { - Given('a MasterDataset with a detailed pattern', () => { - state!.dataset = createTestMasterDataset({ patterns: createDetailedPattern() }); + Given('a PatternGraph with a detailed pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: createDetailedPattern() }); }); When('decoding with PrChangesCodec', () => { @@ -460,8 +460,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Deliverables shown when patterns have deliverables', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with deliverables', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDeliverables(), }); }); @@ -482,8 +482,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Deliverables filtered by release when releaseFilter is set', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with mixed release deliverables', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with mixed release deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithMixedReleaseDeliverables(), }); }); @@ -510,8 +510,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No deliverables section when includeDeliverables is disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with deliverables', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with patterns with deliverables', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithDeliverables(), }); }); @@ -538,8 +538,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Acceptance criteria rendered when patterns have scenarios', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with scenarios', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithScenarios() }); + Given('a PatternGraph with patterns with scenarios', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithScenarios() }); }); When('decoding with PrChangesCodec', () => { @@ -553,8 +553,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Acceptance criteria shows scenario steps', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with scenarios and steps', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithScenarios() }); + Given('a PatternGraph with patterns with scenarios and steps', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithScenarios() }); }); When('decoding with PrChangesCodec', () => { @@ -580,8 +580,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('PrChangesCodec renders business rules from Gherkin Rule keyword', ({ RuleScenario }) => { RuleScenario('Business rules rendered when patterns have rules', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with business rules', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithBusinessRules() }); + Given('a PatternGraph with patterns with business rules', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithBusinessRules() }); }); When('decoding with PrChangesCodec', () => { @@ -596,8 +596,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Business rules show rule names and verification info', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns with business rules', () => { - state!.dataset = createTestMasterDataset({ patterns: createPatternsWithBusinessRules() }); + Given('a PatternGraph with patterns with business rules', () => { + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithBusinessRules() }); }); When('decoding with PrChangesCodec', () => { diff --git a/tests/steps/behavior/codecs/reference-codec-core.steps.ts b/tests/steps/behavior/codecs/reference-codec-core.steps.ts index 5dee4a82..f369043e 100644 --- a/tests/steps/behavior/codecs/reference-codec-core.steps.ts +++ b/tests/steps/behavior/codecs/reference-codec-core.steps.ts @@ -11,7 +11,7 @@ import { getRenderedMarkdown, createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findHeadings, findTables, findBlocksByType, @@ -57,8 +57,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset({ patterns: [] }); + And('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph({ patterns: [] }); }); When('decoding at detail level {string}', (_ctx: unknown, level: string) => { @@ -96,10 +96,10 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a convention-tagged pattern:', + 'a PatternGraph with a convention-tagged pattern:', (_ctx: unknown, dataTable: Array>) => { const row = dataTable[0]!; - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionPattern', @@ -146,8 +146,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with a table', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with a table', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TablePattern', @@ -197,8 +197,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with narrative and rationale', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with narrative and rationale', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'DetailPattern', @@ -250,8 +250,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with narrative and rationale', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with narrative and rationale', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'DetailPatternFull', @@ -306,9 +306,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern in category {string}', + 'a PatternGraph with a behavior pattern in category {string}', (_ctx: unknown, category: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ProcessGuardSpec', @@ -360,9 +360,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a pattern at {string} with extracted shapes', + 'a PatternGraph with a pattern at {string} with extracted shapes', (_ctx: unknown, filePath: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapePattern', @@ -432,9 +432,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a pattern at {string} with extracted shapes', + 'a PatternGraph with a pattern at {string} with extracted shapes', (_ctx: unknown, filePath: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapePattern', @@ -490,9 +490,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a pattern at {string} with extracted shapes', + 'a PatternGraph with a pattern at {string} with extracted shapes', (_ctx: unknown, filePath: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapePattern', @@ -545,8 +545,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with both convention and behavior data', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with both convention and behavior data', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionADR', @@ -613,8 +613,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }; }); - And('a MasterDataset with convention, shape, and behavior data', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with convention, shape, and behavior data', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionADR', @@ -700,8 +700,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with a mermaid diagram', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with a mermaid diagram', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'MermaidConvention', @@ -750,8 +750,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with a mermaid diagram', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with a mermaid diagram', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'MermaidConventionSummary', diff --git a/tests/steps/behavior/codecs/reference-codec-detail-rendering.steps.ts b/tests/steps/behavior/codecs/reference-codec-detail-rendering.steps.ts index 37dae260..fee10feb 100644 --- a/tests/steps/behavior/codecs/reference-codec-detail-rendering.steps.ts +++ b/tests/steps/behavior/codecs/reference-codec-detail-rendering.steps.ts @@ -11,7 +11,7 @@ import { getRenderedMarkdown, createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findHeadings, findLists, findParagraphs, @@ -63,8 +63,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a convention pattern with narrative and rationale', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a convention pattern with narrative and rationale', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'DetailPatternStandard', @@ -123,8 +123,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a behavior pattern with structured rules', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a behavior pattern with structured rules', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'BehaviorSpec', @@ -197,8 +197,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a behavior pattern with structured rules', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a behavior pattern with structured rules', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'BehaviorSpecStd', @@ -258,8 +258,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a behavior pattern with structured rules', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a behavior pattern with structured rules', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'BehaviorSpecSum', @@ -316,9 +316,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern with overlapping scenarioNames and verifiedBy', + 'a PatternGraph with a behavior pattern with overlapping scenarioNames and verifiedBy', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'BehaviorSpecDedup', @@ -386,8 +386,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a shape pattern with JSDoc', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a shape pattern with JSDoc', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapeWithDoc', @@ -438,8 +438,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a shape pattern with JSDoc and property docs', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a shape pattern with JSDoc and property docs', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapeWithDocAndProps', @@ -499,8 +499,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a shape pattern without JSDoc', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a shape pattern without JSDoc', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapeNoDoc', @@ -562,8 +562,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a function shape with param docs', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a function shape with param docs', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'FuncWithParams', @@ -647,8 +647,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a function shape with returns and throws docs', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a function shape with returns and throws docs', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'FuncWithReturnsThrows', @@ -715,8 +715,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a function shape with param and throws docs', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a function shape with param and throws docs', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'FuncWithParamThrows', @@ -784,8 +784,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a shape pattern with JSDoc', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a shape pattern with JSDoc', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ShapeNoParams', @@ -839,7 +839,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern with {int} structured rules', + 'a PatternGraph with a behavior pattern with {int} structured rules', (_ctx: unknown, ruleCount: number) => { const rules = []; for (let i = 1; i <= ruleCount; i++) { @@ -850,7 +850,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { scenarioNames: [`Scenario ${i}A`, `Scenario ${i}B`], }); } - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'MultiRuleBehavior', @@ -898,7 +898,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern with {int} structured rules', + 'a PatternGraph with a behavior pattern with {int} structured rules', (_ctx: unknown, ruleCount: number) => { const rules = []; for (let i = 1; i <= ruleCount; i++) { @@ -909,7 +909,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { scenarioNames: [`Scenario ${i}A`, `Scenario ${i}B`], }); } - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'FewRuleBehavior', @@ -947,7 +947,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern with {int} structured rules', + 'a PatternGraph with a behavior pattern with {int} structured rules', (_ctx: unknown, ruleCount: number) => { const rules = []; for (let i = 1; i <= ruleCount; i++) { @@ -958,7 +958,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { scenarioNames: [], }); } - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'SummaryBehavior', @@ -1002,9 +1002,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern in category {string}', + 'a PatternGraph with a behavior pattern in category {string}', (_ctx: unknown, category: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LinkOutBehavior', @@ -1051,9 +1051,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern in category {string}', + 'a PatternGraph with a behavior pattern in category {string}', (_ctx: unknown, category: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LinkOutStandard', @@ -1090,9 +1090,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a behavior pattern in category {string}', + 'a PatternGraph with a behavior pattern in category {string}', (_ctx: unknown, category: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LinkOutSummary', @@ -1141,9 +1141,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And( - 'a MasterDataset with a pattern that has include {string}', + 'a PatternGraph with a pattern that has include {string}', (_ctx: unknown, includeTag: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'IncludedPattern', @@ -1199,8 +1199,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a category pattern and an include-tagged pattern', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a category pattern and an include-tagged pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintPattern', @@ -1260,9 +1260,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And( - 'a MasterDataset with a pattern that has include {string}', + 'a PatternGraph with a pattern that has include {string}', (_ctx: unknown, includeTag: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'NonMatchingPattern', diff --git a/tests/steps/behavior/codecs/reference-codec-diagram-types.steps.ts b/tests/steps/behavior/codecs/reference-codec-diagram-types.steps.ts index d0e37cf0..68c7e8b4 100644 --- a/tests/steps/behavior/codecs/reference-codec-diagram-types.steps.ts +++ b/tests/steps/behavior/codecs/reference-codec-diagram-types.steps.ts @@ -9,7 +9,7 @@ import { initState, createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findBlocksByType, type DetailLevel, type RenderableDocument, @@ -63,9 +63,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with arch-annotated patterns in context {string}', + 'a PatternGraph with arch-annotated patterns in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderHandler', @@ -126,9 +126,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with uses relationships', + 'a PatternGraph with patterns in context {string} with uses relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -203,9 +203,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with dependsOn relationships', + 'a PatternGraph with patterns in context {string} with dependsOn relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ValidationStep', @@ -272,8 +272,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with an orders pattern that uses an external pattern', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with an orders pattern that uses an external pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -332,8 +332,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a linear dependsOn chain of workflow patterns', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a linear dependsOn chain of workflow patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'StepC', @@ -398,9 +398,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with uses relationships', + 'a PatternGraph with patterns in context {string} with uses relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -476,8 +476,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with an orders pattern that uses an external pattern', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with an orders pattern that uses an external pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -534,9 +534,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with uses relationships', + 'a PatternGraph with patterns in context {string} with uses relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -605,9 +605,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a service pattern and a projection pattern in context {string}', + 'a PatternGraph with a service pattern and a projection pattern in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderHandler', @@ -668,9 +668,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with uses relationships', + 'a PatternGraph with patterns in context {string} with uses relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ServiceA', @@ -726,9 +726,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in context {string} with uses relationships', + 'a PatternGraph with patterns in context {string} with uses relationships', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'CompactA', @@ -782,9 +782,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a service pattern and a projection pattern in context {string}', + 'a PatternGraph with a service pattern and a projection pattern in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'OrderService', @@ -844,9 +844,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with a pattern without archRole in context {string}', + 'a PatternGraph with a pattern without archRole in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'PlainPattern', diff --git a/tests/steps/behavior/codecs/reference-codec-diagrams.steps.ts b/tests/steps/behavior/codecs/reference-codec-diagrams.steps.ts index 38e0c10b..3dd56cb5 100644 --- a/tests/steps/behavior/codecs/reference-codec-diagrams.steps.ts +++ b/tests/steps/behavior/codecs/reference-codec-diagrams.steps.ts @@ -10,7 +10,7 @@ import { makeConfig, createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findHeadings, findBlocksByType, type DetailLevel, @@ -67,9 +67,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with arch-annotated patterns in context {string}', + 'a PatternGraph with arch-annotated patterns in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -125,8 +125,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with arch patterns where lint uses validation', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with arch patterns where lint uses validation', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -198,9 +198,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with patterns in include {string}', + 'a PatternGraph with patterns in include {string}', (_ctx: unknown, viewName: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'PatternScanner', @@ -259,8 +259,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with self-contained lint patterns', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with self-contained lint patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -314,9 +314,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And( - 'a MasterDataset where one pattern matches archContext and another matches include', + 'a PatternGraph where one pattern matches archContext and another matches include', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -377,8 +377,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with multiple arch-annotated patterns', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with multiple arch-annotated patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -433,9 +433,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with arch-annotated patterns in context {string}', + 'a PatternGraph with arch-annotated patterns in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'ConventionADR', @@ -492,8 +492,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with patterns in domain and infrastructure layers', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with patterns in domain and infrastructure layers', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'DomainPattern', @@ -556,8 +556,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { } ); - And('a MasterDataset with a domain-layer pattern and a shared-context pattern', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with a domain-layer pattern and a shared-context pattern', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'DomainPattern', @@ -617,9 +617,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with arch-annotated patterns in context {string}', + 'a PatternGraph with arch-annotated patterns in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -651,7 +651,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('Hardcoded diagram sources render deterministic output', ({ RuleScenario }) => { RuleScenario( - 'master-dataset-views source produces MasterDataset fan-out diagram', + 'pattern-graph-views source produces PatternGraph fan-out diagram', ({ Given, And, When, Then }) => { Given( 'a reference config with diagramScopes source {string}', @@ -661,7 +661,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { conventionTags: [], shapeSelectors: [], behaviorCategories: [], - diagramScopes: [{ source: source as 'master-dataset-views' }], + diagramScopes: [{ source: source as 'pattern-graph-views' }], claudeMdSection: 'test', docsFilename: 'TEST-REFERENCE.md', claudeMdFilename: 'test.md', @@ -670,9 +670,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); And( - 'a MasterDataset with arch-annotated patterns in context {string}', + 'a PatternGraph with arch-annotated patterns in context {string}', (_ctx: unknown, context: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'LintRules', @@ -747,8 +747,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }; }); - And('a MasterDataset with patterns in two different include groups', () => { - state!.dataset = createTestMasterDataset({ + And('a PatternGraph with patterns in two different include groups', () => { + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'SessionCodec', @@ -810,9 +810,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); And( - 'a MasterDataset with patterns in include {string}', + 'a PatternGraph with patterns in include {string}', (_ctx: unknown, viewName: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'PatternScanner', diff --git a/tests/steps/behavior/codecs/reference-generators.steps.ts b/tests/steps/behavior/codecs/reference-generators.steps.ts index 6e202b08..9730c896 100644 --- a/tests/steps/behavior/codecs/reference-generators.steps.ts +++ b/tests/steps/behavior/codecs/reference-generators.steps.ts @@ -4,7 +4,7 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedShape } from '../../../../src/validation-schemas/extracted-shape.js'; import type { GeneratorOutput, GeneratorContext } from '../../../../src/generators/types.js'; import { GeneratorRegistry } from '../../../../src/generators/registry.js'; @@ -14,7 +14,7 @@ import { } from '../../../../src/generators/built-in/reference-generators.js'; import type { ReferenceDocConfig } from '../../../../src/renderable/codecs/reference.js'; import { createTestPattern, resetPatternCounter } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; import { buildRegistry } from '../../../../src/taxonomy/registry-builder.js'; // ============================================================================ @@ -30,12 +30,12 @@ const TEST_CONFIGS: readonly ReferenceDocConfig[] = [ { title: 'Architecture Types Reference', conventionTags: ['pipeline-architecture'], - shapeSelectors: [{ group: 'master-dataset' }], + shapeSelectors: [{ group: 'pattern-graph' }], behaviorCategories: [], claudeMdSection: 'architecture', docsFilename: 'ARCHITECTURE-TYPES.md', claudeMdFilename: 'architecture-types.md', - diagramScopes: [{ title: 'MasterDataset View Fan-out', source: 'master-dataset-views' }], + diagramScopes: [{ title: 'PatternGraph View Fan-out', source: 'pattern-graph-views' }], }, { title: 'Reference Generation Sample', @@ -55,7 +55,7 @@ const TEST_CONFIGS: readonly ReferenceDocConfig[] = [ interface ReferenceGeneratorState { registry: GeneratorRegistry; - dataset: MasterDataset | null; + dataset: PatternGraph | null; output: GeneratorOutput | null; } @@ -70,12 +70,12 @@ let state: ReferenceGeneratorState | null = null; // Helpers // ============================================================================ -function makeMinimalContext(dataset: MasterDataset): GeneratorContext { +function makeMinimalContext(dataset: PatternGraph): GeneratorContext { return { baseDir: '/tmp/test', outputDir: '/tmp/test/output', registry: buildRegistry(), - masterDataset: dataset as GeneratorContext['masterDataset'], + patternGraph: dataset as GeneratorContext['patternGraph'], }; } @@ -206,9 +206,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'Product area generator with matching data produces non-empty output', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with a pattern in product area {string}', + 'a PatternGraph with a pattern in product area {string}', (_ctx: unknown, area: string) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'TestAnnotationPattern', @@ -252,8 +252,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Product area generator with no patterns still produces intro', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset({ patterns: [] }); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph({ patterns: [] }); }); When('running the {string} generator', async (_ctx: unknown, generatorName: string) => { @@ -278,9 +278,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'ARCHITECTURE-TYPES generator produces shapes and convention content', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with pipeline architecture conventions and master dataset shapes', + 'a PatternGraph with pipeline architecture conventions and master dataset shapes', () => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ name: 'Documentation Generation Orchestrator', @@ -295,11 +295,11 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Codec decode and file write happen after shared dataset build.`, }), createTestPattern({ - name: 'MasterDataset', + name: 'PatternGraph', category: 'core', extractedShapes: [ - createShape('MasterDatasetSchema', 'master-dataset'), - createShape('PipelineOptions', 'master-dataset'), + createShape('PatternGraphSchema', 'pattern-graph'), + createShape('PipelineOptions', 'pattern-graph'), ], }), ], diff --git a/tests/steps/behavior/codecs/reporting-codecs.steps.ts b/tests/steps/behavior/codecs/reporting-codecs.steps.ts index 281c28e2..ded33b99 100644 --- a/tests/steps/behavior/codecs/reporting-codecs.steps.ts +++ b/tests/steps/behavior/codecs/reporting-codecs.steps.ts @@ -21,11 +21,11 @@ import { OverviewCodec, } from '../../../../src/renderable/codecs/reporting.js'; import type { RenderableDocument, TableBlock } from '../../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../../src/validation-schemas/index.js'; import { - createTestMasterDataset, - createMasterDatasetWithStatus, + createTestPatternGraph, + createPatternGraphWithStatus, createTestPattern, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -43,7 +43,7 @@ import type { DataTableRow } from '../../../support/world.js'; // ============================================================================= interface ReportingCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -461,8 +461,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Decode empty dataset produces changelog header only', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset for changelog', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph for changelog', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with ChangelogCodec', () => { @@ -484,8 +484,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Unreleased section shows active and vNEXT patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with unreleased patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with unreleased patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createUnreleasedPatterns(), }); }); @@ -518,9 +518,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Release sections sorted by semver descending', ({ Given, When, Then }) => { Given( - 'a MasterDataset with multiple releases:', + 'a PatternGraph with multiple releases:', (_ctx: unknown, dataTable: DataTableRow[]) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: createPatternsWithReleases(dataTable), }); } @@ -550,8 +550,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Quarter fallback for patterns without release', ({ Given, When, Then, And }) => { - Given('a MasterDataset with completed patterns without release tag', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with completed patterns without release tag', () => { + state!.dataset = createTestPatternGraph({ patterns: createCompletedPatternsWithoutRelease(), }); }); @@ -577,8 +577,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Earlier section for undated patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with undated completed patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with undated completed patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createUndatedCompletedPatterns(), }); }); @@ -602,9 +602,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Category mapping to change types', ({ Given, When, Then }) => { Given( - 'a MasterDataset with category-mapped patterns:', + 'a PatternGraph with category-mapped patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: createCategoryMappedPatterns(dataTable), }); } @@ -624,8 +624,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Exclude unreleased when option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with unreleased patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with unreleased patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createUnreleasedPatterns(), }); }); @@ -646,8 +646,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Change type sections follow standard order', ({ Given, When, Then }) => { - Given('a MasterDataset with mixed change types', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with mixed change types', () => { + state!.dataset = createTestPatternGraph({ patterns: createMixedChangeTypePatterns(), }); }); @@ -683,9 +683,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('TraceabilityCodec maps timeline patterns to behavior tests', ({ RuleScenario }) => { RuleScenario('No timeline patterns produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with no timeline patterns', () => { + Given('a PatternGraph with no timeline patterns', () => { // Create patterns without phase (not timeline patterns) - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: [ createTestPattern({ id: generatePatternId(1), @@ -714,9 +714,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Coverage statistics show totals and percentage', ({ Given, When, Then }) => { Given( - 'a MasterDataset with traceability patterns:', + 'a PatternGraph with traceability patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: createTraceabilityPatterns(dataTable), }); } @@ -741,8 +741,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Coverage gaps table shows missing coverage', ({ Given, When, Then, And }) => { - Given('a MasterDataset with coverage gaps', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with coverage gaps', () => { + state!.dataset = createTestPatternGraph({ patterns: createCoverageGapPatterns(), }); }); @@ -768,8 +768,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Covered phases in collapsible section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with covered patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with covered patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createCoveredPatterns(), }); }); @@ -798,8 +798,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Exclude gaps when option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with coverage gaps', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with coverage gaps', () => { + state!.dataset = createTestPatternGraph({ patterns: createCoverageGapPatterns(), }); }); @@ -821,9 +821,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Exclude stats when option disabled', ({ Given, When, Then }) => { Given( - 'a MasterDataset with traceability patterns:', + 'a PatternGraph with traceability patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: createTraceabilityPatterns(dataTable), }); } @@ -845,8 +845,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Exclude covered when option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with covered patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with covered patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createCoveredPatterns(), }); }); @@ -864,8 +864,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Verified behavior files indicated in output', ({ Given, When, Then }) => { - Given('a MasterDataset with verified behavior files', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with verified behavior files', () => { + state!.dataset = createTestPatternGraph({ patterns: createVerifiedBehaviorPatterns(), }); }); @@ -888,8 +888,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('OverviewCodec provides project architecture summary', ({ RuleScenario }) => { RuleScenario('Decode empty dataset produces minimal overview', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset for overview', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph for overview', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with OverviewCodec', () => { @@ -909,8 +909,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Architecture section from overview-tagged patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with overview patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with overview patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createOverviewPatterns(), }); }); @@ -935,13 +935,13 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Patterns summary with progress bar', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with status distribution for overview:', + 'a PatternGraph with status distribution for overview:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status ?? 'completed'] = parseInt(row.count ?? '0', 10); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -970,8 +970,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Timeline summary with phase counts', ({ Given, When, Then, And }) => { - Given('a MasterDataset with phased patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with phased patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPhasedPatterns(), }); }); @@ -999,8 +999,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Exclude architecture when option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with overview patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with overview patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createOverviewPatterns(), }); }); @@ -1022,13 +1022,13 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Exclude patterns summary when option disabled', ({ Given, When, Then }) => { Given( - 'a MasterDataset with status distribution for overview:', + 'a PatternGraph with status distribution for overview:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status ?? 'completed'] = parseInt(row.count ?? '0', 10); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -1048,8 +1048,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Exclude timeline summary when option disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with phased patterns', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with phased patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPhasedPatterns(), }); }); @@ -1073,9 +1073,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'Multiple overview patterns create multiple architecture subsections', ({ Given, When, Then }) => { Given( - 'a MasterDataset with multiple overview patterns:', + 'a PatternGraph with multiple overview patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { - state!.dataset = createTestMasterDataset({ + state!.dataset = createTestPatternGraph({ patterns: createMultipleOverviewPatterns(dataTable), }); } diff --git a/tests/steps/behavior/codecs/requirements-adr-codecs.steps.ts b/tests/steps/behavior/codecs/requirements-adr-codecs.steps.ts index 7ec31cde..637497b2 100644 --- a/tests/steps/behavior/codecs/requirements-adr-codecs.steps.ts +++ b/tests/steps/behavior/codecs/requirements-adr-codecs.steps.ts @@ -17,14 +17,14 @@ import { } from '../../../../src/renderable/codecs/requirements.js'; import { createAdrCodec, AdrDocumentCodec } from '../../../../src/renderable/codecs/adr.js'; import type { RenderableDocument, TableBlock } from '../../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern, BusinessRule, ScenarioRef, } from '../../../../src/validation-schemas/index.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -62,7 +62,7 @@ type AdrPattern = ExtractedPattern & { // ============================================================================= interface RequirementsAdrCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -468,8 +468,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'No patterns with PRD metadata produces empty message', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with RequirementsDocumentCodec', () => { @@ -489,8 +489,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Summary shows counts and groupings', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec', () => { @@ -524,8 +524,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'By product area section groups patterns correctly', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec', () => { @@ -546,8 +546,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('By user role section uses collapsible groups', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec', () => { @@ -569,8 +569,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Group by phase option changes primary grouping', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec using groupBy phase', () => { @@ -593,8 +593,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Filter by status option limits patterns', ({ Given, When, Then }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec filtering to completed status', () => { @@ -613,8 +613,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('All features table shows complete list', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec', () => { @@ -638,8 +638,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Business value rendering when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with PRD patterns with business value', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns with business value', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with RequirementsDocumentCodec', () => { @@ -662,8 +662,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Generate individual requirement detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with PRD patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatterns() }); + Given('a PatternGraph with PRD patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatterns() }); }); When('decoding with generateDetailFiles enabled for requirements', () => { @@ -688,8 +688,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Requirement detail file contains acceptance criteria from scenarios', ({ Given, When, Then, And }) => { - Given('a MasterDataset with PRD patterns with scenarios', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with PRD patterns with scenarios', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatternsWithScenarios(), }); }); @@ -720,8 +720,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Requirement detail file contains business rules section', ({ Given, When, Then }) => { - Given('a MasterDataset with PRD patterns with rules', () => { - state!.dataset = createTestMasterDataset({ patterns: createPrdPatternsWithRules() }); + Given('a PatternGraph with PRD patterns with rules', () => { + state!.dataset = createTestPatternGraph({ patterns: createPrdPatternsWithRules() }); }); When('decoding with generateDetailFiles enabled for requirements', () => { @@ -742,10 +742,10 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Implementation links from relationshipIndex', ({ Given, When, Then }) => { - Given('a MasterDataset with PRD patterns with implementations', () => { + Given('a PatternGraph with PRD patterns with implementations', () => { // Create patterns with implementations via relationshipIndex const patterns = createPrdPatterns(); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); // Manually add relationshipIndex entries with full structure const patternKey = patterns[0].patternName ?? patterns[0].name; @@ -792,9 +792,9 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('AdrDocumentCodec documents architecture decisions', ({ RuleScenario }) => { RuleScenario('No ADR patterns produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with no ADR patterns', () => { + Given('a PatternGraph with no ADR patterns', () => { // Empty dataset has no ADR patterns - state!.dataset = createTestMasterDataset(); + state!.dataset = createTestPatternGraph(); }); When('decoding with AdrDocumentCodec', () => { @@ -813,8 +813,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows status counts and categories', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with AdrDocumentCodec', () => { @@ -846,8 +846,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADRs grouped by category', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with AdrDocumentCodec', () => { @@ -867,8 +867,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADRs grouped by phase option', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with AdrDocumentCodec using groupBy phase', () => { @@ -889,8 +889,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADRs grouped by date (quarter) option', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns with quarters', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatternsWithQuarters() }); + Given('a PatternGraph with ADR patterns with quarters', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatternsWithQuarters() }); }); When('decoding with AdrDocumentCodec using groupBy date', () => { @@ -914,8 +914,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADR index table with all decisions', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with AdrDocumentCodec', () => { @@ -939,8 +939,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADR entries use clean text without emojis', ({ Given, When, Then }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with AdrDocumentCodec', () => { @@ -968,8 +968,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Context, Decision, Consequences sections from Rule keywords', ({ Given, When, Then }) => { - Given('a MasterDataset with ADR patterns with semantic rules', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with ADR patterns with semantic rules', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatternsWithSemanticRules(), }); }); @@ -1009,8 +1009,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('ADR supersedes rendering', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns with supersession', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatternsWithSupersession() }); + Given('a PatternGraph with ADR patterns with supersession', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatternsWithSupersession() }); }); When('decoding with AdrDocumentCodec', () => { @@ -1027,8 +1027,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate individual ADR detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with ADR patterns', () => { - state!.dataset = createTestMasterDataset({ patterns: createAdrPatterns() }); + Given('a PatternGraph with ADR patterns', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatterns() }); }); When('decoding with generateDetailFiles enabled for ADR', () => { @@ -1047,8 +1047,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('ADR detail file contains full content', ({ Given, When, Then, And }) => { - Given('a MasterDataset with ADR patterns with semantic rules', () => { - state!.dataset = createTestMasterDataset({ + Given('a PatternGraph with ADR patterns with semantic rules', () => { + state!.dataset = createTestPatternGraph({ patterns: createAdrPatternsWithSemanticRules(), }); }); diff --git a/tests/steps/behavior/codecs/session-codecs.steps.ts b/tests/steps/behavior/codecs/session-codecs.steps.ts index 224e5be3..f9eaf5af 100644 --- a/tests/steps/behavior/codecs/session-codecs.steps.ts +++ b/tests/steps/behavior/codecs/session-codecs.steps.ts @@ -22,11 +22,11 @@ import type { TableBlock, CollapsibleBlock, } from '../../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, - createMasterDatasetWithStatus, - createMasterDatasetWithTimeline, + createTestPatternGraph, + createPatternGraphWithStatus, + createPatternGraphWithTimeline, createTestPattern, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -46,7 +46,7 @@ import type { DataTableRow } from '../../../support/world.js'; // ============================================================================= interface SessionCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -166,7 +166,7 @@ function findCollapsibleWithSummary( return collapsibles.find((c) => c.summary.includes(summaryText)) ?? null; } -function createDatasetWithOnlyCompleted(): MasterDataset { +function createDatasetWithOnlyCompleted(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Feature 1', @@ -181,10 +181,10 @@ function createDatasetWithOnlyCompleted(): MasterDataset { quarter: 'Q4-2025', }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithBlockedPatterns(): MasterDataset { +function createDatasetWithBlockedPatterns(): PatternGraph { const patterns = [ createTestPattern({ name: 'Foundation Pattern', @@ -208,10 +208,10 @@ function createDatasetWithBlockedPatterns(): MasterDataset { phase: 3, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithManyPlannedPatterns(): MasterDataset { +function createDatasetWithManyPlannedPatterns(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Base', @@ -231,10 +231,10 @@ function createDatasetWithManyPlannedPatterns(): MasterDataset { ); } - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithPrioritizedPatterns(): MasterDataset { +function createDatasetWithPrioritizedPatterns(): PatternGraph { const patterns = [ createTestPattern({ name: 'Critical Feature', @@ -261,10 +261,10 @@ function createDatasetWithPrioritizedPatterns(): MasterDataset { priority: 'low', }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithActionablePatterns(): MasterDataset { +function createDatasetWithActionablePatterns(): PatternGraph { // Create a dataset where some planned patterns are actionable (not blocked) const patterns = [ createTestPattern({ @@ -297,7 +297,7 @@ function createDatasetWithActionablePatterns(): MasterDataset { dependsOn: ['Active Work'], }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } // ============================================================================= @@ -325,8 +325,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Decode empty dataset produces minimal session context', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with SessionContextCodec', () => { @@ -353,8 +353,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Decode dataset with timeline patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with SessionContextCodec', () => { @@ -381,13 +381,13 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Session status shows current focus', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with status distribution:', + 'a PatternGraph with status distribution:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status] = parseInt(row.count); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -415,8 +415,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Phase navigation for incomplete phases', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with SessionContextCodec', () => { @@ -448,8 +448,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Active work grouped by phase', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with SessionContextCodec', () => { @@ -471,7 +471,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Blocked items section with dependencies', ({ Given, When, Then, And }) => { - Given('a MasterDataset with blocked patterns', () => { + Given('a PatternGraph with blocked patterns', () => { state!.dataset = createDatasetWithBlockedPatterns(); }); @@ -495,7 +495,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('No blocked items section when disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with blocked patterns', () => { + Given('a PatternGraph with blocked patterns', () => { state!.dataset = createDatasetWithBlockedPatterns(); }); @@ -512,8 +512,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Recent completions collapsible', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with SessionContextCodec', () => { @@ -535,8 +535,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate session phase detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles enabled for session', () => { @@ -555,8 +555,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('No detail files when disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles disabled for session', () => { @@ -579,7 +579,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('RemainingWorkCodec aggregates incomplete work by phase', ({ RuleScenario }) => { RuleScenario('All work complete produces celebration message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with only completed patterns', () => { + Given('a PatternGraph with only completed patterns', () => { state!.dataset = createDatasetWithOnlyCompleted(); }); @@ -600,13 +600,13 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Summary shows remaining counts', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with status distribution:', + 'a PatternGraph with status distribution:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status] = parseInt(row.count); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -633,8 +633,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Phase navigation with remaining count', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with RemainingWorkCodec', () => { @@ -658,7 +658,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('By priority shows ready vs blocked', ({ Given, When, Then, And }) => { - Given('a MasterDataset with blocked patterns', () => { + Given('a PatternGraph with blocked patterns', () => { state!.dataset = createDatasetWithBlockedPatterns(); }); @@ -685,7 +685,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Next actionable items section', ({ Given, When, Then, And }) => { - Given('a MasterDataset with actionable patterns', () => { + Given('a PatternGraph with actionable patterns', () => { state!.dataset = createDatasetWithActionablePatterns(); }); @@ -738,7 +738,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Next actionable respects maxNextActionable limit', ({ Given, When, Then }) => { - Given('a MasterDataset with many planned patterns', () => { + Given('a PatternGraph with many planned patterns', () => { state!.dataset = createDatasetWithManyPlannedPatterns(); }); @@ -771,8 +771,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Sort by phase option', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with sortBy set to {string}', (_ctx: unknown, sortBy: string) => { @@ -804,7 +804,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Sort by priority option', ({ Given, When, Then }) => { - Given('a MasterDataset with prioritized patterns', () => { + Given('a PatternGraph with prioritized patterns', () => { state!.dataset = createDatasetWithPrioritizedPatterns(); }); @@ -824,8 +824,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate remaining work detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles enabled for remaining', () => { @@ -847,8 +847,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('No detail files when disabled for remaining', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles disabled for remaining', () => { diff --git a/tests/steps/behavior/codecs/shape-matcher.steps.ts b/tests/steps/behavior/codecs/shape-matcher.steps.ts index dd011582..a0145072 100644 --- a/tests/steps/behavior/codecs/shape-matcher.steps.ts +++ b/tests/steps/behavior/codecs/shape-matcher.steps.ts @@ -8,10 +8,10 @@ import { matchesShapePattern, filterShapesBySelectors, } from '../../../../src/renderable/codecs/shape-matcher.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedShape } from '../../../../src/validation-schemas/extracted-shape.js'; import { createTestPattern, resetPatternCounter } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; // ============================================================================ // State @@ -19,7 +19,7 @@ import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js' interface ShapeMatcherState { matchResult: boolean | null; - dataset: MasterDataset | null; + dataset: PatternGraph | null; extractedShapes: readonly ExtractedShape[]; } @@ -191,7 +191,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'Shapes are selected from matching source glob patterns', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with patterns:', + 'a PatternGraph with patterns:', (_ctx: unknown, dataTable: Array>) => { const patterns = dataTable.map((row) => createTestPattern({ @@ -207,7 +207,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ], }) ); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); @@ -232,7 +232,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Duplicate shape names are deduplicated', ({ Given, When, Then }) => { Given( - 'a MasterDataset with patterns:', + 'a PatternGraph with patterns:', (_ctx: unknown, dataTable: Array>) => { const patterns = dataTable.map((row) => createTestPattern({ @@ -248,7 +248,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ], }) ); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); @@ -263,7 +263,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('No shapes returned when glob does not match', ({ Given, When, Then }) => { Given( - 'a MasterDataset with patterns:', + 'a PatternGraph with patterns:', (_ctx: unknown, dataTable: Array>) => { const patterns = dataTable.map((row) => createTestPattern({ @@ -279,7 +279,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ], }) ); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); diff --git a/tests/steps/behavior/codecs/shape-selector.steps.ts b/tests/steps/behavior/codecs/shape-selector.steps.ts index f0b83d95..166967a6 100644 --- a/tests/steps/behavior/codecs/shape-selector.steps.ts +++ b/tests/steps/behavior/codecs/shape-selector.steps.ts @@ -9,13 +9,13 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { filterShapesBySelectors } from '../../../../src/renderable/codecs/shape-matcher.js'; import type { ShapeSelector } from '../../../../src/renderable/codecs/shape-matcher.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedShape, ShapeKind, } from '../../../../src/validation-schemas/extracted-shape.js'; import { createTestPattern, resetPatternCounter } from '../../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../../fixtures/dataset-factories.js'; // ============================================================================ // Helpers @@ -39,7 +39,7 @@ interface ShapeRow { Kind: string; } -function buildDatasetFromRows(rows: readonly ShapeRow[]): MasterDataset { +function buildDatasetFromRows(rows: readonly ShapeRow[]): PatternGraph { resetPatternCounter(); // Group rows by pattern source const bySource = new Map(); @@ -62,7 +62,7 @@ function buildDatasetFromRows(rows: readonly ShapeRow[]): MasterDataset { }); }); - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } // ============================================================================ @@ -70,7 +70,7 @@ function buildDatasetFromRows(rows: readonly ShapeRow[]): MasterDataset { // ============================================================================ interface SelectorTestState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; resultShapes: readonly ExtractedShape[]; } @@ -105,7 +105,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Select specific shapes by source and names', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with patterns containing these extracted shapes:', + 'a PatternGraph with patterns containing these extracted shapes:', (_ctx: unknown, table: readonly ShapeRow[]) => { state!.dataset = buildDatasetFromRows(table); } @@ -140,7 +140,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Select all shapes in a group', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with patterns containing these extracted shapes:', + 'a PatternGraph with patterns containing these extracted shapes:', (_ctx: unknown, table: readonly ShapeRow[]) => { state!.dataset = buildDatasetFromRows(table); } @@ -172,7 +172,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Select all tagged shapes from a source file', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with patterns containing these extracted shapes:', + 'a PatternGraph with patterns containing these extracted shapes:', (_ctx: unknown, table: readonly ShapeRow[]) => { state!.dataset = buildDatasetFromRows(table); } @@ -194,7 +194,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Source-only selector returns all matching shapes', ({ Given, When, Then }) => { Given( - 'a MasterDataset with patterns containing these extracted shapes:', + 'a PatternGraph with patterns containing these extracted shapes:', (_ctx: unknown, table: readonly ShapeRow[]) => { state!.dataset = buildDatasetFromRows(table); } diff --git a/tests/steps/behavior/codecs/timeline-codecs.steps.ts b/tests/steps/behavior/codecs/timeline-codecs.steps.ts index 13c07123..54108179 100644 --- a/tests/steps/behavior/codecs/timeline-codecs.steps.ts +++ b/tests/steps/behavior/codecs/timeline-codecs.steps.ts @@ -21,11 +21,11 @@ import { CurrentWorkCodec, } from '../../../../src/renderable/codecs/timeline.js'; import type { RenderableDocument, TableBlock } from '../../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, - createMasterDatasetWithStatus, - createMasterDatasetWithTimeline, + createTestPatternGraph, + createPatternGraphWithStatus, + createPatternGraphWithTimeline, createTestPattern, resetPatternCounter, } from '../../../fixtures/dataset-factories.js'; @@ -45,7 +45,7 @@ import type { DataTableRow } from '../../../support/world.js'; // ============================================================================= interface TimelineCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -127,7 +127,7 @@ function findPhaseNavigationTable(doc: RenderableDocument): TableBlock | null { /** * Find a phase section by phase number. * Note: Phase name mappings (Foundation Types, CMS Integration, etc.) - * align with createMasterDatasetWithTimeline() output. + * align with createPatternGraphWithTimeline() output. */ function findPhaseSection( doc: RenderableDocument, @@ -181,7 +181,7 @@ function findQuarterlyTimelineTable(doc: RenderableDocument): TableBlock | null return null; } -function createDatasetWithOnlyPlanned(): MasterDataset { +function createDatasetWithOnlyPlanned(): PatternGraph { const patterns = [ createTestPattern({ name: 'Planned Feature 1', @@ -194,10 +194,10 @@ function createDatasetWithOnlyPlanned(): MasterDataset { phase: 2, }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithOnlyCompleted(): MasterDataset { +function createDatasetWithOnlyCompleted(): PatternGraph { const patterns = [ createTestPattern({ name: 'Completed Feature 1', @@ -212,10 +212,10 @@ function createDatasetWithOnlyCompleted(): MasterDataset { quarter: 'Q4-2025', }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } -function createDatasetWithDeliverables(): MasterDataset { +function createDatasetWithDeliverables(): PatternGraph { const patterns = [ createTestPattern({ name: 'Active Pattern', @@ -227,7 +227,7 @@ function createDatasetWithDeliverables(): MasterDataset { ], }), ]; - return createTestMasterDataset({ patterns }); + return createTestPatternGraph({ patterns }); } // ============================================================================= @@ -257,8 +257,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Decode empty dataset produces minimal roadmap', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with RoadmapDocumentCodec', () => { @@ -285,8 +285,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Decode dataset with multiple phases', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with RoadmapDocumentCodec', () => { @@ -313,13 +313,13 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Progress section shows correct status counts', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with status distribution:', + 'a PatternGraph with status distribution:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status] = parseInt(row.count); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -347,8 +347,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Phase navigation table with progress', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with RoadmapDocumentCodec', () => { @@ -375,8 +375,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Phase sections show pattern tables', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with RoadmapDocumentCodec', () => { @@ -401,8 +401,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate phase detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles enabled for roadmap', () => { @@ -421,8 +421,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('No detail files when disabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles disabled for roadmap', () => { @@ -439,8 +439,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Quarterly timeline shown when quarters exist', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with RoadmapDocumentCodec', () => { @@ -478,7 +478,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'CompletedMilestonesCodec shows only completed patterns grouped by quarter', ({ RuleScenario }) => { RuleScenario('No completed patterns produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with only planned patterns', () => { + Given('a PatternGraph with only planned patterns', () => { state!.dataset = createDatasetWithOnlyPlanned(); }); @@ -498,8 +498,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows completed counts', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CompletedMilestonesCodec', () => { @@ -525,8 +525,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Quarterly navigation with completed patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CompletedMilestonesCodec', () => { @@ -549,8 +549,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario( 'Completed phases shown in collapsible sections', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CompletedMilestonesCodec', () => { @@ -571,8 +571,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); RuleScenario('Recent completions section with limit', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CompletedMilestonesCodec', () => { @@ -605,8 +605,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate quarterly detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles enabled for milestones', () => { @@ -635,7 +635,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { Rule('CurrentWorkCodec shows only active patterns with deliverables', ({ RuleScenario }) => { RuleScenario('No active work produces empty message', ({ Given, When, Then, And }) => { - Given('a MasterDataset with only completed patterns', () => { + Given('a PatternGraph with only completed patterns', () => { state!.dataset = createDatasetWithOnlyCompleted(); }); @@ -655,8 +655,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Summary shows overall progress', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CurrentWorkCodec', () => { @@ -684,8 +684,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Active phases with progress bars', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CurrentWorkCodec', () => { @@ -710,7 +710,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Deliverables rendered when configured', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns with deliverables', () => { + Given('a PatternGraph with patterns with deliverables', () => { state!.dataset = createDatasetWithDeliverables(); }); @@ -727,8 +727,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('All active patterns table', ({ Given, When, Then, And }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with CurrentWorkCodec', () => { @@ -763,8 +763,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario('Generate current work detail files when enabled', ({ Given, When, Then }) => { - Given('a MasterDataset with timeline patterns', () => { - state!.dataset = createMasterDatasetWithTimeline(); + Given('a PatternGraph with timeline patterns', () => { + state!.dataset = createPatternGraphWithTimeline(); }); When('decoding with generateDetailFiles enabled for current work', () => { diff --git a/tests/steps/behavior/context-inference.steps.ts b/tests/steps/behavior/context-inference.steps.ts index ae934bfb..6fafc35c 100644 --- a/tests/steps/behavior/context-inference.steps.ts +++ b/tests/steps/behavior/context-inference.steps.ts @@ -2,7 +2,7 @@ * Context Inference Step Definitions * * BDD step definitions for testing the context auto-inference feature - * in transformToMasterDataset. This feature infers bounded context from + * in transformToPatternGraph. This feature infers bounded context from * file paths when patterns have archLayer but no explicit archContext. * * @architect @@ -11,9 +11,9 @@ import { expect } from 'vitest'; import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; import type { ContextInferenceRule } from '../../../src/generators/pipeline/context-inference.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { DEFAULT_CONTEXT_INFERENCE_RULES } from '../../../src/config/defaults.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; @@ -27,7 +27,7 @@ import type { DataTableRow } from '../../support/world.js'; interface ContextInferenceState { patterns: ExtractedPattern[]; rules: readonly ContextInferenceRule[] | undefined; - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; } // ============================================================================= @@ -124,7 +124,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -182,7 +182,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -237,7 +237,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -290,7 +290,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -338,7 +338,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -392,7 +392,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -446,7 +446,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -498,7 +498,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -559,7 +559,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -611,7 +611,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { When('transforming to master dataset with rules', () => { if (!state) throw new Error('State not initialized'); - state.dataset = transformToMasterDataset({ + state.dataset = transformToPatternGraph({ patterns: state.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/behavior/description-headers.steps.ts b/tests/steps/behavior/description-headers.steps.ts index 2857bd27..5c01458c 100644 --- a/tests/steps/behavior/description-headers.steps.ts +++ b/tests/steps/behavior/description-headers.steps.ts @@ -12,9 +12,9 @@ import { expect } from 'vitest'; import { createPatternsCodec } from '../../../src/renderable/codecs/patterns.js'; import { stripLeadingHeaders } from '../../../src/renderable/utils.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -26,7 +26,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface DescriptionHeadersState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; patternDocument: RenderableDocument | null; inputText: string | null; @@ -119,7 +119,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: docString, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { @@ -161,7 +161,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: docString, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { @@ -200,7 +200,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: docString, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { @@ -240,7 +240,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: docString, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { @@ -267,7 +267,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: docString, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { @@ -298,7 +298,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { name: 'TestPattern', description: descWithMiddleHeader, }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('the pattern detail document is generated', () => { diff --git a/tests/steps/behavior/description-quality-foundation.steps.ts b/tests/steps/behavior/description-quality-foundation.steps.ts index 2637cb9f..5ede522e 100644 --- a/tests/steps/behavior/description-quality-foundation.steps.ts +++ b/tests/steps/behavior/description-quality-foundation.steps.ts @@ -15,10 +15,10 @@ import { inferBehaviorFilePath } from '../../../src/extractor/gherkin-extractor. import { TraceabilityCodec } from '../../../src/renderable/codecs/reporting.js'; import { RemainingWorkCodec } from '../../../src/renderable/codecs/session.js'; import type { RenderableDocument, TableBlock } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../src/types/index.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -30,7 +30,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface DescriptionQualityState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; pattern: ExtractedPattern | null; displayName: string | null; @@ -264,7 +264,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { behaviorFileVerified: row.BehaviorFile ? verified : undefined, }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -419,7 +419,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { name: 'TestPattern', status: 'roadmap', }); - state.dataset = createTestMasterDataset({ patterns: [state.pattern] }); + state.dataset = createTestPatternGraph({ patterns: [state.pattern] }); } ); @@ -455,7 +455,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { name: 'TestPattern', status: 'roadmap', }); - state.dataset = createTestMasterDataset({ patterns: [state.pattern] }); + state.dataset = createTestPatternGraph({ patterns: [state.pattern] }); }); When('generating PRD with includeScenarioSteps disabled', () => { @@ -486,7 +486,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { name: 'LongDescriptionPattern', description: longDescription, }); - state.dataset = createTestMasterDataset({ patterns: [state.pattern] }); + state.dataset = createTestPatternGraph({ patterns: [state.pattern] }); } ); @@ -540,7 +540,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { businessValue: row.BusinessValue, }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); diff --git a/tests/steps/behavior/implementation-links.steps.ts b/tests/steps/behavior/implementation-links.steps.ts index 42afb5eb..c1c5df33 100644 --- a/tests/steps/behavior/implementation-links.steps.ts +++ b/tests/steps/behavior/implementation-links.steps.ts @@ -10,10 +10,10 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { createPatternsCodec, normalizeImplPath } from '../../../src/renderable/codecs/patterns.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createTestPattern, resetPatternCounter } from '../../fixtures/pattern-factories.js'; import type { DataTableRow } from '../../support/world.js'; @@ -23,7 +23,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface ImplementationLinksState { - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; document: RenderableDocument | null; patternDocument: RenderableDocument | null; filePath: string | null; @@ -54,10 +54,10 @@ function initState(): ImplementationLinksState { // ============================================================================= /** - * Build the dataset from patterns using transformToMasterDataset + * Build the dataset from patterns using transformToPatternGraph */ function buildDataset(): void { - state!.dataset = transformToMasterDataset({ + state!.dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/behavior/pattern-relationships/depends-on-tag.steps.ts b/tests/steps/behavior/pattern-relationships/depends-on-tag.steps.ts index e700782b..4e267aac 100644 --- a/tests/steps/behavior/pattern-relationships/depends-on-tag.steps.ts +++ b/tests/steps/behavior/pattern-relationships/depends-on-tag.steps.ts @@ -24,9 +24,9 @@ import { extractPatternTags, } from '../../../../src/scanner/gherkin-ast-parser.js'; import { Result } from '../../../../src/types/result.js'; -import { transformToMasterDataset } from '../../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../../src/validation-schemas/index.js'; -import type { RelationshipEntry } from '../../../../src/validation-schemas/master-dataset.js'; +import type { RelationshipEntry } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../../src/types/index.js'; import { asPatternId, asCategoryName, asSourceFilePath } from '../../../../src/types/branded.js'; import { missingRelationshipTarget, type LintContext } from '../../../../src/lint/rules.js'; @@ -336,7 +336,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -370,7 +370,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); diff --git a/tests/steps/behavior/pattern-relationships/extends-tag.steps.ts b/tests/steps/behavior/pattern-relationships/extends-tag.steps.ts index ff2cdfad..1b1866da 100644 --- a/tests/steps/behavior/pattern-relationships/extends-tag.steps.ts +++ b/tests/steps/behavior/pattern-relationships/extends-tag.steps.ts @@ -25,9 +25,9 @@ import { extractPatternTags, } from '../../../../src/scanner/gherkin-ast-parser.js'; import { Result } from '../../../../src/types/result.js'; -import { transformToMasterDataset } from '../../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../../src/validation-schemas/index.js'; -import type { RelationshipEntry } from '../../../../src/validation-schemas/master-dataset.js'; +import type { RelationshipEntry } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../../src/types/index.js'; import { asPatternId, asCategoryName, asSourceFilePath } from '../../../../src/types/branded.js'; @@ -251,7 +251,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); diff --git a/tests/steps/behavior/pattern-relationships/implements-tag.steps.ts b/tests/steps/behavior/pattern-relationships/implements-tag.steps.ts index e4dcea89..ac28b9cf 100644 --- a/tests/steps/behavior/pattern-relationships/implements-tag.steps.ts +++ b/tests/steps/behavior/pattern-relationships/implements-tag.steps.ts @@ -29,8 +29,8 @@ import { import { RelationshipEntrySchema, type RelationshipEntry, -} from '../../../../src/validation-schemas/master-dataset.js'; -import { transformToMasterDataset } from '../../../../src/generators/pipeline/transform-dataset.js'; +} from '../../../../src/validation-schemas/pattern-graph.js'; +import { transformToPatternGraph } from '../../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../../src/validation-schemas/index.js'; import type { ExtractedPattern } from '../../../../src/types/index.js'; import { asPatternId, asCategoryName, asSourceFilePath } from '../../../../src/types/branded.js'; @@ -260,7 +260,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -295,7 +295,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); diff --git a/tests/steps/behavior/pattern-relationships/mermaid-rendering.steps.ts b/tests/steps/behavior/pattern-relationships/mermaid-rendering.steps.ts index abb4111d..1e7bf1b9 100644 --- a/tests/steps/behavior/pattern-relationships/mermaid-rendering.steps.ts +++ b/tests/steps/behavior/pattern-relationships/mermaid-rendering.steps.ts @@ -14,9 +14,9 @@ import { expect } from 'vitest'; import { fileURLToPath } from 'node:url'; import { dirname, resolve } from 'node:path'; -import { transformToMasterDataset } from '../../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../../src/validation-schemas/index.js'; -import type { RelationshipEntry } from '../../../../src/validation-schemas/master-dataset.js'; +import type { RelationshipEntry } from '../../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../../src/types/index.js'; import { asPatternId, asCategoryName, asSourceFilePath } from '../../../../src/types/branded.js'; @@ -151,7 +151,7 @@ describeFeature(feature, ({ Rule }) => { When('the Mermaid graph is generated', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -179,7 +179,7 @@ describeFeature(feature, ({ Rule }) => { When('the Mermaid graph is generated', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -203,7 +203,7 @@ describeFeature(feature, ({ Rule }) => { When('the Mermaid graph is generated', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -227,7 +227,7 @@ describeFeature(feature, ({ Rule }) => { When('the Mermaid graph is generated', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -309,7 +309,7 @@ describeFeature(feature, ({ Rule }) => { When('the Mermaid graph is generated', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); diff --git a/tests/steps/behavior/pattern-relationships/uses-tag.steps.ts b/tests/steps/behavior/pattern-relationships/uses-tag.steps.ts index 3ecbe0d6..03b9b370 100644 --- a/tests/steps/behavior/pattern-relationships/uses-tag.steps.ts +++ b/tests/steps/behavior/pattern-relationships/uses-tag.steps.ts @@ -28,8 +28,8 @@ import { import { RelationshipEntrySchema, type RelationshipEntry, -} from '../../../../src/validation-schemas/master-dataset.js'; -import { transformToMasterDataset } from '../../../../src/generators/pipeline/transform-dataset.js'; +} from '../../../../src/validation-schemas/pattern-graph.js'; +import { transformToPatternGraph } from '../../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../../src/validation-schemas/index.js'; import type { ExtractedPattern } from '../../../../src/types/index.js'; import { asPatternId, asCategoryName, asSourceFilePath } from '../../../../src/types/branded.js'; @@ -288,7 +288,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); @@ -322,7 +322,7 @@ describeFeature(feature, ({ Rule }) => { When('the relationship index is built', () => { const tagRegistry = createDefaultTagRegistry(); - const dataset = transformToMasterDataset({ + const dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry, }); diff --git a/tests/steps/behavior/patterns-codec.steps.ts b/tests/steps/behavior/patterns-codec.steps.ts index df46814b..323976e7 100644 --- a/tests/steps/behavior/patterns-codec.steps.ts +++ b/tests/steps/behavior/patterns-codec.steps.ts @@ -11,12 +11,12 @@ import { PatternsDocumentCodec, } from '../../../src/renderable/codecs/patterns.js'; import type { RenderableDocument, TableBlock } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, - createMasterDatasetWithStatus, - createMasterDatasetWithCategories, - createMasterDatasetWithRelationships, + createTestPatternGraph, + createPatternGraphWithStatus, + createPatternGraphWithCategories, + createPatternGraphWithRelationships, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -36,7 +36,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface PatternsCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; markdown: string; } @@ -153,8 +153,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { 'Document structure includes progress tracking and category navigation', ({ RuleScenario }) => { RuleScenario('Decode empty dataset', ({ Given, When, Then, And }) => { - Given('an empty MasterDataset', () => { - state!.dataset = createTestMasterDataset(); + Given('an empty PatternGraph', () => { + state!.dataset = createTestPatternGraph(); }); When('decoding with PatternsDocumentCodec', () => { @@ -184,10 +184,10 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { 'Decode dataset with patterns - document structure', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with {int} patterns across {int} categories', + 'a PatternGraph with {int} patterns across {int} categories', (_ctx: unknown, patternCount: number, categoryCount: number) => { const categories = ['core', 'ddd', 'saga'].slice(0, categoryCount); - state!.dataset = createMasterDatasetWithCategories( + state!.dataset = createPatternGraphWithCategories( categories, Math.ceil(patternCount / categoryCount) ); @@ -219,13 +219,13 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { RuleScenario('Progress summary shows correct counts', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with status distribution:', + 'a PatternGraph with status distribution:', (_ctx: unknown, dataTable: DataTableRow[]) => { const counts: Record = {}; for (const row of dataTable) { counts[row.status] = parseInt(row.count); } - state!.dataset = createMasterDatasetWithStatus(counts); + state!.dataset = createPatternGraphWithStatus(counts); } ); @@ -260,8 +260,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { Rule('Pattern table presents all patterns sorted by status then name', ({ RuleScenario }) => { RuleScenario('Pattern table includes all patterns', ({ Given, When, Then, And }) => { - Given('a MasterDataset with {int} patterns', (_ctx: unknown, count: number) => { - state!.dataset = createTestMasterDataset({ patternCount: count }); + Given('a PatternGraph with {int} patterns', (_ctx: unknown, count: number) => { + state!.dataset = createTestPatternGraph({ patternCount: count }); }); When('decoding with PatternsDocumentCodec', () => { @@ -285,7 +285,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }); RuleScenario('Pattern table is sorted by status then name', ({ Given, When, Then }) => { - Given('a MasterDataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { + Given('a PatternGraph with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const patterns = dataTable.map((row) => { // Status values now match directly (roadmap, active, completed, deferred) return createTestPattern({ @@ -293,7 +293,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { status: (row.status ?? 'completed') as 'roadmap' | 'active' | 'completed' | 'deferred', }); }); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); }); When('decoding with PatternsDocumentCodec', () => { @@ -320,7 +320,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { Rule('Category sections group patterns by domain', ({ RuleScenario }) => { RuleScenario('Category sections with pattern lists', ({ Given, When, Then }) => { Given( - 'a MasterDataset with patterns in categories:', + 'a PatternGraph with patterns in categories:', (_ctx: unknown, dataTable: DataTableRow[]) => { const patterns = []; for (const row of dataTable) { @@ -329,7 +329,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { patterns.push(createTestPattern({ category: row.category })); } } - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); @@ -354,7 +354,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { RuleScenario('Filter to specific categories', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with patterns in categories:', + 'a PatternGraph with patterns in categories:', (_ctx: unknown, dataTable: DataTableRow[]) => { const patterns = []; for (const row of dataTable) { @@ -363,7 +363,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { patterns.push(createTestPattern({ category: row.category })); } } - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); @@ -402,8 +402,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { Rule('Dependency graph visualizes pattern relationships', ({ RuleScenario }) => { RuleScenario('Dependency graph included when relationships exist', ({ Given, When, Then }) => { - Given('a MasterDataset with pattern relationships', () => { - state!.dataset = createMasterDatasetWithRelationships(); + Given('a PatternGraph with pattern relationships', () => { + state!.dataset = createPatternGraphWithRelationships(); }); When('decoding with default options', () => { @@ -417,8 +417,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }); RuleScenario('No dependency graph when no relationships', ({ Given, When, Then }) => { - Given('a MasterDataset without relationships', () => { - state!.dataset = createTestMasterDataset({ patternCount: 3 }); + Given('a PatternGraph without relationships', () => { + state!.dataset = createTestPatternGraph({ patternCount: 3 }); }); When('decoding with default options', () => { @@ -432,8 +432,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }); RuleScenario('Dependency graph disabled by option', ({ Given, When, Then }) => { - Given('a MasterDataset with pattern relationships', () => { - state!.dataset = createMasterDatasetWithRelationships(); + Given('a PatternGraph with pattern relationships', () => { + state!.dataset = createPatternGraphWithRelationships(); }); When('decoding with includeDependencyGraph disabled', () => { @@ -454,7 +454,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { Rule('Detail file generation creates per-pattern pages', ({ RuleScenario }) => { RuleScenario('Generate individual pattern files when enabled', ({ Given, When, Then, And }) => { - Given('a MasterDataset with named patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { + Given('a PatternGraph with named patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const patterns = []; for (const row of dataTable) { patterns.push( @@ -465,7 +465,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }) ); } - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); }); When('decoding with generateDetailFiles enabled', () => { @@ -534,9 +534,9 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }); RuleScenario('No detail files when disabled', ({ Given, When, Then, And }) => { - Given('a MasterDataset with patterns in {int} categories', (_ctx: unknown, count: number) => { + Given('a PatternGraph with patterns in {int} categories', (_ctx: unknown, count: number) => { const categories = ['core', 'ddd', 'saga'].slice(0, count); - state!.dataset = createMasterDatasetWithCategories(categories, 2); + state!.dataset = createPatternGraphWithCategories(categories, 2); }); When('decoding with generateDetailFiles disabled', () => { @@ -574,7 +574,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { RuleScenario('Individual pattern file contains full details', ({ Given, When, Then, And }) => { Given( - 'a MasterDataset with a pattern named {string} in category {string}', + 'a PatternGraph with a pattern named {string} in category {string}', (_ctx: unknown, name: string, category: string) => { const patterns = [ createTestPattern({ @@ -584,7 +584,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { description: `Description for ${name}`, }), ]; - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); } ); diff --git a/tests/steps/behavior/pr-changes-generation.steps.ts b/tests/steps/behavior/pr-changes-generation.steps.ts index 3b29d202..1df2d2ae 100644 --- a/tests/steps/behavior/pr-changes-generation.steps.ts +++ b/tests/steps/behavior/pr-changes-generation.steps.ts @@ -21,10 +21,10 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { generateDocument } from '../../../src/renderable/generate.js'; import type { PrChangesCodecOptions } from '../../../src/renderable/codecs/pr-changes.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, type TestDeliverable, @@ -37,7 +37,7 @@ import type { DataTableRow } from '../../support/world.js'; interface PrChangesGenerationState { patterns: ExtractedPattern[]; - dataset: MasterDataset | null; + dataset: PatternGraph | null; output: string; options: PrChangesCodecOptions; } @@ -66,7 +66,7 @@ function initState(): PrChangesGenerationState { * Generate PR changes markdown from dataset with options */ function generatePrChangesMarkdown( - dataset: MasterDataset, + dataset: PatternGraph, options: PrChangesCodecOptions = {} ): string { const files = generateDocument('pr-changes', dataset, { 'pr-changes': options }); @@ -76,8 +76,8 @@ function generatePrChangesMarkdown( /** * Build dataset from accumulated patterns */ -function buildDataset(): MasterDataset { - return createTestMasterDataset({ patterns: state!.patterns }); +function buildDataset(): PatternGraph { + return createTestPatternGraph({ patterns: state!.patterns }); } /** diff --git a/tests/steps/behavior/remaining-work-enhancement.steps.ts b/tests/steps/behavior/remaining-work-enhancement.steps.ts index 8f8d9af5..415c8134 100644 --- a/tests/steps/behavior/remaining-work-enhancement.steps.ts +++ b/tests/steps/behavior/remaining-work-enhancement.steps.ts @@ -22,9 +22,9 @@ import type { HeadingBlock, ListBlock, } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -41,7 +41,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface RemainingWorkEnhancementState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; options: Partial; effortString: string | null; @@ -212,7 +212,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('generating remaining work with sortBy: priority', () => { @@ -258,7 +258,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('generating remaining work with sortBy: priority', () => { @@ -301,7 +301,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('generating remaining work with sortBy: priority', () => { @@ -346,7 +346,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('generating remaining work with sortBy: effort', () => { @@ -448,7 +448,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -494,7 +494,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); And('all phases have incomplete deliverables', () => { @@ -544,7 +544,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -593,7 +593,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }) ); } - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); And('maxPlannedToShow is {int}', (_ctx: unknown, _max: number) => { @@ -650,7 +650,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }) ); } - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); And('maxNextActionable is {int}', (_ctx: unknown, max: number) => { @@ -697,7 +697,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { RuleScenario('Empty backlog handling', ({ Given, When, Then }) => { Given('no roadmap phases', () => { state = initState(); - state.dataset = createTestMasterDataset({ patterns: [] }); + state.dataset = createTestPatternGraph({ patterns: [] }); }); When('generating remaining work with sortBy: priority', () => { @@ -736,7 +736,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); } ); @@ -778,7 +778,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('generating remaining work with default config', () => { @@ -811,7 +811,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { }); }); - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); And('all phases have incomplete deliverables', () => { diff --git a/tests/steps/behavior/remaining-work-totals.steps.ts b/tests/steps/behavior/remaining-work-totals.steps.ts index bf5fb396..ebc44d9a 100644 --- a/tests/steps/behavior/remaining-work-totals.steps.ts +++ b/tests/steps/behavior/remaining-work-totals.steps.ts @@ -11,9 +11,9 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { RemainingWorkCodec } from '../../../src/renderable/codecs/session.js'; import type { RenderableDocument, TableBlock } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -25,7 +25,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface RemainingWorkTotalsState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; patternData: Array<{ id: string; @@ -331,7 +331,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -368,7 +368,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Summary includes completed patterns correctly', ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -412,7 +412,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -464,7 +464,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('All patterns in backlog when none have phases', ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -503,7 +503,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -545,7 +545,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Mixed patterns with and without patternName', ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -602,7 +602,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Multiple phases shown in order', ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); @@ -641,7 +641,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { RuleScenario('Completed phases not shown in remaining work', ({ Given, When, Then, And }) => { Given('a dataset with patterns:', (_ctx: unknown, dataTable: DataTableRow[]) => { const { patterns, patternData } = createPatternsFromTable(dataTable); - state!.dataset = createTestMasterDataset({ patterns }); + state!.dataset = createTestPatternGraph({ patterns }); state!.patternData = patternData; }); diff --git a/tests/steps/behavior/session-handoffs.steps.ts b/tests/steps/behavior/session-handoffs.steps.ts index 41ae015c..c901384b 100644 --- a/tests/steps/behavior/session-handoffs.steps.ts +++ b/tests/steps/behavior/session-handoffs.steps.ts @@ -16,9 +16,9 @@ import { join } from 'path'; import { createSessionContextCodec } from '../../../src/renderable/codecs/session.js'; import { createSessionFindingsCodec } from '../../../src/renderable/codecs/planning.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -30,7 +30,7 @@ import type { DataTableRow } from '../../support/world.js'; // ============================================================================= interface SessionHandoffsState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; findingsDocument: RenderableDocument | null; includeHandoffContext: boolean; @@ -129,7 +129,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { phase: 1, status: 'active', }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('generating SESSION-CONTEXT.md with includeHandoffContext enabled', () => { @@ -187,7 +187,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { discoveredImprovements: improvements.length > 0 ? improvements : undefined, discoveredLearnings: learnings.length > 0 ? learnings : undefined, }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('generating SESSION-CONTEXT.md with includeHandoffContext enabled', () => { @@ -255,7 +255,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { status: 'active', discoveredLearnings: [pauseIndicator], }); - state!.dataset = createTestMasterDataset({ patterns: [pattern] }); + state!.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('generating SESSION-CONTEXT.md with includeHandoffContext enabled', () => { @@ -504,7 +504,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { phase: 1, status: 'active', }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('generating SESSION-CONTEXT.md with includeHandoffContext enabled', () => { @@ -543,7 +543,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { status: 'active', discoveredGaps: ['Some gap'], }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('generating SESSION-CONTEXT.md with includeHandoffContext disabled', () => { @@ -587,7 +587,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { status: 'roadmap', }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('a session ends before phase completion', () => { @@ -627,7 +627,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { status: 'roadmap', }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); }); When('following the coordination pattern documented in PROCESS_SETUP.md', () => { @@ -664,7 +664,7 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { discoveredImprovements: ['Could optimize with caching'], discoveredLearnings: ['Parser requires strict formatting'], }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); }); When('following the retrospective checklist', () => { diff --git a/tests/steps/behavior/transform-dataset.steps.ts b/tests/steps/behavior/transform-dataset.steps.ts index 5b2d8ee4..ec57b611 100644 --- a/tests/steps/behavior/transform-dataset.steps.ts +++ b/tests/steps/behavior/transform-dataset.steps.ts @@ -1,21 +1,21 @@ /** * Transform Dataset Step Definitions * - * BDD step definitions for testing the transformToMasterDataset function + * BDD step definitions for testing the transformToPatternGraph function * and related utility functions (completionPercentage, isFullyCompleted). */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import type { - RuntimeMasterDataset, + RuntimePatternGraph, RawDataset, } from '../../../src/generators/pipeline/transform-types.js'; import { - transformToMasterDataset, + transformToPatternGraph, completionPercentage, isFullyCompleted, } from '../../../src/generators/pipeline/transform-dataset.js'; -import type { StatusCounts } from '../../../src/validation-schemas/master-dataset.js'; +import type { StatusCounts } from '../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import type { LoadedWorkflow } from '../../../src/config/workflow-loader.js'; import { @@ -35,7 +35,7 @@ interface TransformDatasetState { workflow: LoadedWorkflow | undefined; // Results - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; // For utility function tests statusCounts: StatusCounts | null; @@ -104,8 +104,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { // state.patterns is already empty }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('the dataset has {int} patterns', (_ctx: unknown, count: number) => { @@ -149,8 +149,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('byStatus.completed has {int} patterns', (_ctx: unknown, count: number) => { @@ -185,8 +185,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('each pattern is grouped in the expected status bucket', () => { @@ -213,8 +213,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -239,8 +239,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { addPattern({ phase: 2, name: 'Phase 2 Pattern' }); }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('byPhase is sorted as [1, 2, 3]', () => { @@ -256,8 +256,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { addPattern({ phase: 1, status: 'active' }); }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('phase 1 counts are:', (_ctx: unknown, dataTable: DataTableRow[]) => { @@ -285,8 +285,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('byPhase has {int} phase group', (_ctx: unknown, count: number) => { @@ -314,8 +314,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -345,8 +345,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('byQuarter has {int} quarter', (_ctx: unknown, count: number) => { @@ -364,8 +364,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -403,8 +403,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('bySourceType.typescript has {int} patterns', (_ctx: unknown, count: number) => { @@ -429,8 +429,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('bySourceType.roadmap has {int} patterns', (_ctx: unknown, count: number) => { @@ -459,8 +459,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -510,8 +510,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -541,8 +541,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -565,8 +565,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -594,8 +594,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { } ); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -713,7 +713,7 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { }); When('transforming with the workflow', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then( @@ -736,8 +736,8 @@ describeFeature(feature, ({ Rule, Background, AfterEachScenario }) => { addPattern({ name: 'Pattern 2' }); }); - When('transforming to MasterDataset', () => { - state!.dataset = transformToMasterDataset(createRawDataset()); + When('transforming to PatternGraph', () => { + state!.dataset = transformToPatternGraph(createRawDataset()); }); Then('the result does not include workflow', () => { diff --git a/tests/steps/cli/data-api-cache.steps.ts b/tests/steps/cli/data-api-cache.steps.ts index 065bc16e..bfee2ee5 100644 --- a/tests/steps/cli/data-api-cache.steps.ts +++ b/tests/steps/cli/data-api-cache.steps.ts @@ -1,7 +1,7 @@ /** * Data API CLI Cache Step Definitions * - * BDD step definitions for testing MasterDataset caching + * BDD step definitions for testing PatternGraph caching * between CLI invocations: cache hits, mtime invalidation, * and --no-cache bypass. * @@ -22,7 +22,7 @@ import { getResult, writePatternFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Extended State for Cache Tests @@ -104,10 +104,10 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); // --------------------------------------------------------------------------- - // Rule: MasterDataset is cached between invocations + // Rule: PatternGraph is cached between invocations // --------------------------------------------------------------------------- - Rule('MasterDataset is cached between invocations', ({ RuleScenario }) => { + Rule('PatternGraph is cached between invocations', ({ RuleScenario }) => { RuleScenario('Second query uses cached dataset', ({ Given, When, Then, And }) => { Given('TypeScript files with pattern annotations', async () => { await writePatternFiles(state); diff --git a/tests/steps/cli/data-api-dryrun.steps.ts b/tests/steps/cli/data-api-dryrun.steps.ts index dc9b13a6..c955310f 100644 --- a/tests/steps/cli/data-api-dryrun.steps.ts +++ b/tests/steps/cli/data-api-dryrun.steps.ts @@ -18,7 +18,7 @@ import { runCLICommand, writePatternFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Module-level state (reset per scenario) diff --git a/tests/steps/cli/data-api-help.steps.ts b/tests/steps/cli/data-api-help.steps.ts index 48932349..867f612a 100644 --- a/tests/steps/cli/data-api-help.steps.ts +++ b/tests/steps/cli/data-api-help.steps.ts @@ -16,7 +16,7 @@ import { getResult, runCLICommand, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Module-level state (reset per scenario) diff --git a/tests/steps/cli/data-api-metadata.steps.ts b/tests/steps/cli/data-api-metadata.steps.ts index 07d36c1f..d451215d 100644 --- a/tests/steps/cli/data-api-metadata.steps.ts +++ b/tests/steps/cli/data-api-metadata.steps.ts @@ -17,7 +17,7 @@ import { runCLICommand, writePatternFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // JSON Metadata Parsing diff --git a/tests/steps/cli/data-api-repl.steps.ts b/tests/steps/cli/data-api-repl.steps.ts index 9129b13e..a99f4cb4 100644 --- a/tests/steps/cli/data-api-repl.steps.ts +++ b/tests/steps/cli/data-api-repl.steps.ts @@ -16,7 +16,7 @@ import { initState, writePatternFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; import { runCLI } from '../../support/helpers/cli-runner.js'; // ============================================================================= diff --git a/tests/steps/cli/process-api-core.steps.ts b/tests/steps/cli/process-api-core.steps.ts index 07de1821..7d4e8f4d 100644 --- a/tests/steps/cli/process-api-core.steps.ts +++ b/tests/steps/cli/process-api-core.steps.ts @@ -6,7 +6,7 @@ * status, query, pattern, arch basics, missing args, edge cases. * * @architect - * @architect-implements ProcessStateAPICLI + * @architect-implements PatternGraphAPICLI */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; @@ -20,7 +20,7 @@ import { writePatternFiles, writeArchPatternFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Module-level state (reset per scenario) diff --git a/tests/steps/cli/process-api-modifiers-rules.steps.ts b/tests/steps/cli/process-api-modifiers-rules.steps.ts index 821bb0b1..aa181b12 100644 --- a/tests/steps/cli/process-api-modifiers-rules.steps.ts +++ b/tests/steps/cli/process-api-modifiers-rules.steps.ts @@ -5,7 +5,7 @@ * output modifiers, arch health, and rules subcommand. * * @architect - * @architect-implements ProcessStateAPICLI + * @architect-implements PatternGraphAPICLI */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; @@ -19,7 +19,7 @@ import { writeDanglingRefFiles, writeFeatureFilesWithRules, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Module-level state (reset per scenario) diff --git a/tests/steps/cli/process-api-subcommands.steps.ts b/tests/steps/cli/process-api-subcommands.steps.ts index c2033df0..af0c1e8d 100644 --- a/tests/steps/cli/process-api-subcommands.steps.ts +++ b/tests/steps/cli/process-api-subcommands.steps.ts @@ -6,7 +6,7 @@ * tags/sources, extended arch, unannotated. * * @architect - * @architect-implements ProcessStateAPICLI + * @architect-implements PatternGraphAPICLI */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; @@ -22,7 +22,7 @@ import { writeTwoContextFiles, writeMixedAnnotationFiles, createTempDir, -} from '../../support/helpers/process-api-state.js'; +} from '../../support/helpers/pattern-graph-api-state.js'; // ============================================================================= // Module-level state (reset per scenario) diff --git a/tests/steps/doc-generation/architecture-doc-refactoring.steps.ts b/tests/steps/doc-generation/architecture-doc-refactoring.steps.ts index 222d05ae..1de973ef 100644 --- a/tests/steps/doc-generation/architecture-doc-refactoring.steps.ts +++ b/tests/steps/doc-generation/architecture-doc-refactoring.steps.ts @@ -328,8 +328,8 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ); }); - Rule('MasterDataset shapes appear in ARCHITECTURE-TYPES reference', ({ RuleScenario }) => { - RuleScenario('Core MasterDataset types appear in ARCHITECTURE-TYPES', ({ When, Then }) => { + Rule('PatternGraph shapes appear in ARCHITECTURE-TYPES reference', ({ RuleScenario }) => { + RuleScenario('Core PatternGraph types appear in ARCHITECTURE-TYPES', ({ When, Then }) => { When('reading file {string}', (_ctx: unknown, filePath: string) => { const fullPath = path.join(process.cwd(), filePath); state!.currentFileContent = fs.readFileSync(fullPath, 'utf-8'); @@ -360,7 +360,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { }); RuleScenario( - 'Unified Transformation section has full MasterDataset content', + 'Unified Transformation section has full PatternGraph content', ({ When, Then, And }) => { When('reading the {string} section', (_ctx: unknown, section: string) => { state!.currentSectionName = section; diff --git a/tests/steps/doc-generation/index-codec.steps.ts b/tests/steps/doc-generation/index-codec.steps.ts index d81c7736..c070d272 100644 --- a/tests/steps/doc-generation/index-codec.steps.ts +++ b/tests/steps/doc-generation/index-codec.steps.ts @@ -16,9 +16,9 @@ import { } from '../../../src/renderable/codecs/index-codec.js'; import type { RenderableDocument, SectionBlock } from '../../../src/renderable/schema.js'; import { heading, paragraph } from '../../../src/renderable/schema.js'; -import { createTestMasterDataset } from '../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../fixtures/dataset-factories.js'; import { createTestPattern } from '../../fixtures/pattern-factories.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/doc-generation/index-codec.feature'); @@ -29,7 +29,7 @@ const feature = await loadFeature('tests/features/doc-generation/index-codec.fea interface TestState { // Input options: Partial; - dataset: MasterDataset | null; + dataset: PatternGraph | null; documentEntries: DocumentEntry[]; // Output @@ -150,7 +150,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Document metadata is correctly set', ({ RuleScenario }) => { RuleScenario('Document title is Documentation Index', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -163,7 +163,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Document purpose references @libar-dev/architect', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -176,7 +176,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Default options produce all sections', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -201,7 +201,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Package metadata section renders correctly', ({ RuleScenario }) => { RuleScenario('Package name shows @libar-dev/architect', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -224,7 +224,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Purpose shows context engineering platform description', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -246,7 +246,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('License shows MIT', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -268,7 +268,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Pattern counts reflect dataset', ({ When, Then }) => { When('decoding with a dataset containing 3 completed and 2 active patterns', () => { - state.dataset = createTestMasterDataset({ + state.dataset = createTestPatternGraph({ statusDistribution: { completed: 3, active: 2 }, }); const codec = createIndexCodec(); @@ -296,7 +296,7 @@ describeFeature(feature, ({ Background, Rule }) => { createTestPattern({ name: 'PatternA', productArea: 'Generation', status: 'completed' }), createTestPattern({ name: 'PatternB', productArea: 'Analysis', status: 'completed' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -322,7 +322,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Package metadata section can be disabled', ({ When, Then }) => { When('decoding with includePackageMetadata disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ includePackageMetadata: false }); state.document = codec.decode(state.dataset); }); @@ -345,7 +345,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Document inventory groups entries by topic', ({ RuleScenario }) => { RuleScenario('Empty entries produces no inventory section', ({ When, Then }) => { When('decoding with no document entries', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ documentEntries: [] }); state.document = codec.decode(state.dataset); }); @@ -371,7 +371,7 @@ describeFeature(feature, ({ Background, Rule }) => { topic, }, ]; - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ documentEntries: state.documentEntries }); state.document = codec.decode(state.dataset); }); @@ -403,7 +403,7 @@ describeFeature(feature, ({ Background, Rule }) => { topic: 'Reference', }, ]; - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ includeDocumentInventory: false, documentEntries: state.documentEntries, @@ -435,7 +435,7 @@ describeFeature(feature, ({ Background, Rule }) => { createTestPattern({ name: 'PatternA', productArea: area1, status: 'completed' }), createTestPattern({ name: 'PatternB', productArea: area2, status: 'completed' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); } @@ -469,7 +469,7 @@ describeFeature(feature, ({ Background, Rule }) => { createTestPattern({ name: 'PatternA', productArea: 'Generation', status: 'completed' }), createTestPattern({ name: 'PatternB', productArea: 'Analysis', status: 'completed' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -496,7 +496,7 @@ describeFeature(feature, ({ Background, Rule }) => { createTestPattern({ name: 'P3', productArea: 'Generation', status: 'completed' }), createTestPattern({ name: 'P4', productArea: 'Generation', status: 'completed' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -517,7 +517,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Product area stats can be disabled', ({ When, Then }) => { When('decoding with includeProductAreaStats disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ includeProductAreaStats: false }); state.document = codec.decode(state.dataset); }); @@ -540,7 +540,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Phase progress summarizes pattern status', ({ RuleScenario }) => { RuleScenario('Phase progress shows total counts', ({ When, Then }) => { When('decoding with a dataset containing 3 completed and 2 active patterns', () => { - state.dataset = createTestMasterDataset({ + state.dataset = createTestPatternGraph({ statusDistribution: { completed: 3, active: 2 }, }); const codec = createIndexCodec(); @@ -561,7 +561,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Status distribution table shows completed/active/planned', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -589,7 +589,7 @@ describeFeature(feature, ({ Background, Rule }) => { createTestPattern({ name: 'PhasePattern1', phase: 1, status: 'completed' }), createTestPattern({ name: 'PhasePattern2', phase: 2, status: 'active' }), ]; - state.dataset = createTestMasterDataset({ patterns }); + state.dataset = createTestPatternGraph({ patterns }); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -606,7 +606,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Phase progress can be disabled', ({ When, Then }) => { When('decoding with includePhaseProgress disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ includePhaseProgress: false }); state.document = codec.decode(state.dataset); }); @@ -629,7 +629,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Regeneration footer contains commands', ({ RuleScenario }) => { RuleScenario('Regeneration section has heading "Regeneration"', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -643,7 +643,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Code blocks contain pnpm commands', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -673,7 +673,7 @@ describeFeature(feature, ({ Background, Rule }) => { 'Default layout order is metadata, stats, progress, regeneration', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -712,7 +712,7 @@ describeFeature(feature, ({ Background, Rule }) => { topic, }, ]; - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const preambleSection = paragraph('This is the editorial preamble.'); const codec = createIndexCodec({ preamble: [preambleSection], @@ -758,7 +758,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Separators appear between sections', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec(); state.document = codec.decode(state.dataset); }); @@ -781,7 +781,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Custom purpose text overrides default', ({ RuleScenario }) => { RuleScenario('purposeText replaces auto-generated purpose', ({ When, Then }) => { When('decoding with purposeText {string}', (_ctx: unknown, purposeText: string) => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ purposeText }); state.document = codec.decode(state.dataset); }); @@ -794,7 +794,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Empty purposeText uses auto-generated purpose', ({ When, Then }) => { When('decoding with empty purposeText', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ purposeText: '' }); state.document = codec.decode(state.dataset); }); @@ -813,7 +813,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Epilogue replaces regeneration footer', ({ RuleScenario }) => { RuleScenario('Epilogue replaces built-in footer', ({ When, Then, And }) => { When('decoding with epilogue sections', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const epilogueSections = [ heading(2, 'Custom Footer'), paragraph('This is a custom footer replacing regeneration.'), @@ -840,7 +840,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Empty epilogue preserves regeneration footer', ({ When, Then }) => { When('decoding with empty epilogue', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ epilogue: [] }); state.document = codec.decode(state.dataset); }); @@ -862,7 +862,7 @@ describeFeature(feature, ({ Background, Rule }) => { When( 'decoding with packageMetadataOverrides name {string}', (_ctx: unknown, name: string) => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ packageMetadataOverrides: { name }, }); @@ -892,7 +892,7 @@ describeFeature(feature, ({ Background, Rule }) => { When( 'decoding with packageMetadataOverrides purpose {string}', (_ctx: unknown, purpose: string) => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ packageMetadataOverrides: { purpose }, }); @@ -919,7 +919,7 @@ describeFeature(feature, ({ Background, Rule }) => { When( 'decoding with packageMetadataOverrides license {string}', (_ctx: unknown, license: string) => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ packageMetadataOverrides: { license }, }); @@ -946,7 +946,7 @@ describeFeature(feature, ({ Background, Rule }) => { When( 'decoding with packageMetadataOverrides name {string}', (_ctx: unknown, name: string) => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createIndexCodec({ packageMetadataOverrides: { name }, }); diff --git a/tests/steps/doc-generation/taxonomy-codec.steps.ts b/tests/steps/doc-generation/taxonomy-codec.steps.ts index 66f24814..cf672062 100644 --- a/tests/steps/doc-generation/taxonomy-codec.steps.ts +++ b/tests/steps/doc-generation/taxonomy-codec.steps.ts @@ -1,7 +1,7 @@ /** * Step definitions for Taxonomy Codec behavior tests * - * Tests the Taxonomy Codec that transforms MasterDataset into a + * Tests the Taxonomy Codec that transforms PatternGraph into a * RenderableDocument for tag taxonomy reference documentation (TAXONOMY.md). */ @@ -12,8 +12,8 @@ import { type TaxonomyCodecOptions, } from '../../../src/renderable/codecs/taxonomy.js'; import type { RenderableDocument, SectionBlock } from '../../../src/renderable/schema.js'; -import { createTestMasterDataset } from '../../fixtures/dataset-factories.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import { createTestPatternGraph } from '../../fixtures/dataset-factories.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import { createDefaultTagRegistry, type MetadataTagDefinition, @@ -28,7 +28,7 @@ const feature = await loadFeature('tests/features/doc-generation/taxonomy-codec. interface TestState { // Input options: Partial; - dataset: MasterDataset | null; + dataset: PatternGraph | null; customMetadataTags: MetadataTagDefinition[]; // Output @@ -187,7 +187,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Document metadata is correctly set', ({ RuleScenario }) => { RuleScenario('Document title is Taxonomy Reference', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -200,7 +200,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Document purpose describes tag taxonomy', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -213,7 +213,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Detail level reflects generateDetailFiles option', ({ When, Then }) => { When('decoding with generateDetailFiles disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ generateDetailFiles: false }); state.document = codec.decode(state.dataset); }); @@ -232,7 +232,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Categories section is generated from TagRegistry', ({ RuleScenario }) => { RuleScenario('Categories section is included in output', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -246,7 +246,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Category table has correct columns', ({ When, Then, And }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -276,7 +276,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('LinkOut to detail file when generateDetailFiles enabled', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -297,7 +297,7 @@ describeFeature(feature, ({ Background, Rule }) => { 'With groupByDomain enabled tags are grouped into subsections', ({ When, Then }) => { When('decoding with groupByDomain enabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ groupByDomain: true }); state.document = codec.decode(state.dataset); }); @@ -319,7 +319,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('With groupByDomain disabled single table rendered', ({ When, Then, And }) => { When('decoding with groupByDomain disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ groupByDomain: false }); state.document = codec.decode(state.dataset); }); @@ -367,7 +367,7 @@ describeFeature(feature, ({ Background, Rule }) => { const customRegistry = createTagRegistryWithMetadataTags( state.customMetadataTags.map((t) => t.tag) ); - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); // Override the tag registry in the dataset (state.dataset as { tagRegistry: typeof customRegistry }).tagRegistry = customRegistry; const codec = createTaxonomyCodec({ groupByDomain: true }); @@ -401,7 +401,7 @@ describeFeature(feature, ({ Background, Rule }) => { const customRegistry = createTagRegistryWithMetadataTags( state.customMetadataTags.map((t) => t.tag) ); - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); (state.dataset as { tagRegistry: typeof customRegistry }).tagRegistry = customRegistry; const codec = createTaxonomyCodec({ groupByDomain: true }); state.document = codec.decode(state.dataset); @@ -434,7 +434,7 @@ describeFeature(feature, ({ Background, Rule }) => { const customRegistry = createTagRegistryWithMetadataTags( state.customMetadataTags.map((t) => t.tag) ); - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); (state.dataset as { tagRegistry: typeof customRegistry }).tagRegistry = customRegistry; const codec = createTaxonomyCodec({ groupByDomain: true }); state.document = codec.decode(state.dataset); @@ -467,7 +467,7 @@ describeFeature(feature, ({ Background, Rule }) => { const customRegistry = createTagRegistryWithMetadataTags( state.customMetadataTags.map((t) => t.tag) ); - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); (state.dataset as { tagRegistry: typeof customRegistry }).tagRegistry = customRegistry; const codec = createTaxonomyCodec({ groupByDomain: true }); state.document = codec.decode(state.dataset); @@ -500,7 +500,7 @@ describeFeature(feature, ({ Background, Rule }) => { const customRegistry = createTagRegistryWithMetadataTags( state.customMetadataTags.map((t) => t.tag) ); - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); (state.dataset as { tagRegistry: typeof customRegistry }).tagRegistry = customRegistry; const codec = createTaxonomyCodec({ groupByDomain: true }); state.document = codec.decode(state.dataset); @@ -524,7 +524,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Optional sections can be disabled via codec options', ({ RuleScenario }) => { RuleScenario('includeFormatTypes disabled excludes Format Types section', ({ When, Then }) => { When('decoding with includeFormatTypes disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ includeFormatTypes: false }); state.document = codec.decode(state.dataset); }); @@ -541,7 +541,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('includePresets disabled excludes Presets section', ({ When, Then }) => { When('decoding with includePresets disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ includePresets: false }); state.document = codec.decode(state.dataset); }); @@ -558,7 +558,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('includeArchDiagram disabled excludes Architecture section', ({ When, Then }) => { When('decoding with includeArchDiagram disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ includeArchDiagram: false }); state.document = codec.decode(state.dataset); }); @@ -581,7 +581,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Detail files are generated for progressive disclosure', ({ RuleScenario }) => { RuleScenario('generateDetailFiles creates 3 additional files', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -595,7 +595,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Detail files have correct paths', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); @@ -611,7 +611,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('generateDetailFiles disabled creates no additional files', ({ When, Then }) => { When('decoding with generateDetailFiles disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec({ generateDetailFiles: false }); state.document = codec.decode(state.dataset); }); @@ -631,7 +631,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Format types are documented with descriptions and examples', ({ RuleScenario }) => { RuleScenario('All 6 format types are documented', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createTaxonomyCodec(); state.document = codec.decode(state.dataset); }); diff --git a/tests/steps/doc-generation/validation-rules-codec.steps.ts b/tests/steps/doc-generation/validation-rules-codec.steps.ts index 6be0a9d4..61f340aa 100644 --- a/tests/steps/doc-generation/validation-rules-codec.steps.ts +++ b/tests/steps/doc-generation/validation-rules-codec.steps.ts @@ -1,7 +1,7 @@ /** * Step definitions for Validation Rules Codec behavior tests * - * Tests the Validation Rules Codec that transforms MasterDataset into a + * Tests the Validation Rules Codec that transforms PatternGraph into a * RenderableDocument for Process Guard validation rules reference (VALIDATION-RULES.md). */ @@ -12,8 +12,8 @@ import { type ValidationRulesCodecOptions, } from '../../../src/renderable/codecs/validation-rules.js'; import type { RenderableDocument, SectionBlock } from '../../../src/renderable/schema.js'; -import { createTestMasterDataset } from '../../fixtures/dataset-factories.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import { createTestPatternGraph } from '../../fixtures/dataset-factories.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; const feature = await loadFeature('tests/features/doc-generation/validation-rules-codec.feature'); @@ -24,7 +24,7 @@ const feature = await loadFeature('tests/features/doc-generation/validation-rule interface TestState { // Input options: Partial; - dataset: MasterDataset | null; + dataset: PatternGraph | null; // Output document: RenderableDocument | null; @@ -214,7 +214,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Document metadata is correctly set', ({ RuleScenario }) => { RuleScenario('Document title is Validation Rules', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -227,7 +227,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Document purpose describes Process Guard', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -240,7 +240,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Detail level reflects generateDetailFiles option', ({ When, Then }) => { When('decoding with generateDetailFiles disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ generateDetailFiles: false }); state.document = codec.decode(state.dataset); }); @@ -259,7 +259,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('All validation rules are documented in a table', ({ RuleScenario }) => { RuleScenario('All 6 rules appear in table', ({ When, Then, And }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -289,7 +289,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Rules have correct severity levels', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -317,7 +317,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('FSM state diagram is generated from transitions', ({ RuleScenario }) => { RuleScenario('Mermaid diagram generated when includeFSMDiagram enabled', ({ When, Then }) => { When('decoding with includeFSMDiagram enabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ includeFSMDiagram: true }); state.document = codec.decode(state.dataset); }); @@ -331,7 +331,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Diagram includes all 4 states', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -348,7 +348,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('FSM diagram excluded when includeFSMDiagram disabled', ({ When, Then }) => { When('decoding with includeFSMDiagram disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ includeFSMDiagram: false }); state.document = codec.decode(state.dataset); }); @@ -368,7 +368,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Protection level matrix shows status protections', ({ RuleScenario }) => { RuleScenario('Matrix shows all 4 statuses with protection levels', ({ When, Then, And }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -393,7 +393,7 @@ describeFeature(feature, ({ Background, Rule }) => { 'Protection matrix excluded when includeProtectionMatrix disabled', ({ When, Then }) => { When('decoding with includeProtectionMatrix disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ includeProtectionMatrix: false }); state.document = codec.decode(state.dataset); }); @@ -417,7 +417,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('CLI usage is documented with options and exit codes', ({ RuleScenario }) => { RuleScenario('CLI example code block included', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -431,7 +431,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('All 6 CLI options documented', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -454,7 +454,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('Exit codes documented', ({ When, Then }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -468,7 +468,7 @@ describeFeature(feature, ({ Background, Rule }) => { RuleScenario('CLI section excluded when includeCLIUsage disabled', ({ When, Then }) => { When('decoding with includeCLIUsage disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ includeCLIUsage: false }); state.document = codec.decode(state.dataset); }); @@ -491,7 +491,7 @@ describeFeature(feature, ({ Background, Rule }) => { Rule('Escape hatches are documented for special cases', ({ RuleScenario }) => { RuleScenario('All 3 escape hatches documented', ({ When, Then, And }) => { When('decoding with default options', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec(); state.document = codec.decode(state.dataset); }); @@ -514,7 +514,7 @@ describeFeature(feature, ({ Background, Rule }) => { 'Escape hatches section excluded when includeEscapeHatches disabled', ({ When, Then }) => { When('decoding with includeEscapeHatches disabled', () => { - state.dataset = createTestMasterDataset(); + state.dataset = createTestPatternGraph(); const codec = createValidationRulesCodec({ includeEscapeHatches: false }); state.document = codec.decode(state.dataset); }); diff --git a/tests/steps/generation/design-review-generator.steps.ts b/tests/steps/generation/design-review-generator.steps.ts index 3fda0a68..c26ada33 100644 --- a/tests/steps/generation/design-review-generator.steps.ts +++ b/tests/steps/generation/design-review-generator.steps.ts @@ -12,18 +12,18 @@ import { expect } from 'vitest'; import type { GeneratorOutput } from '../../../src/generators/types.js'; import { createDesignReviewGenerator } from '../../../src/generators/built-in/design-review-generator.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; import { createTempDir, writeTempFile, type TempDirContext, } from '../../support/helpers/file-system.js'; -import { createTestMasterDataset, createTestPattern } from '../../fixtures/dataset-factories.js'; +import { createTestPatternGraph, createTestPattern } from '../../fixtures/dataset-factories.js'; import { createSequenceRule } from '../../support/helpers/design-review-state.js'; interface DesignReviewGeneratorState { tempContext: TempDirContext | null; - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; output: GeneratorOutput | null; } @@ -88,7 +88,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { ], }); - requireState().dataset = createTestMasterDataset({ patterns: [pattern] }); + requireState().dataset = createTestPatternGraph({ patterns: [pattern] }); } ); @@ -102,7 +102,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { baseDir: current.tempContext!.tempDir, outputDir: '.', registry: createDefaultTagRegistry(), - masterDataset: current.dataset, + patternGraph: current.dataset, }); }); diff --git a/tests/steps/generators/business-rules-generator.steps.ts b/tests/steps/generators/business-rules-generator.steps.ts index 74568bb5..c4522518 100644 --- a/tests/steps/generators/business-rules-generator.steps.ts +++ b/tests/steps/generators/business-rules-generator.steps.ts @@ -11,8 +11,8 @@ import { expect } from 'vitest'; import { createBusinessRulesCodec } from '../../../src/renderable/codecs/business-rules.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import type { RenderableDocument, TableBlock } from '../../../src/renderable/schema.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import type { BusinessRule } from '../../../src/validation-schemas/extracted-pattern.js'; @@ -30,7 +30,7 @@ import type { SectionBlock } from '../../../src/renderable/schema.js'; // ============================================================================= interface BusinessRulesState { - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; document: RenderableDocument | null; markdown: string; patterns: ExtractedPattern[]; @@ -99,7 +99,7 @@ function createPatternWithRules( * Build the dataset from patterns and run the generator */ function buildDataset(): void { - state!.dataset = transformToMasterDataset({ + state!.dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/generators/codec-based.steps.ts b/tests/steps/generators/codec-based.steps.ts index 0b1b93c3..16964f1e 100644 --- a/tests/steps/generators/codec-based.steps.ts +++ b/tests/steps/generators/codec-based.steps.ts @@ -3,7 +3,7 @@ * * BDD step definitions for testing the CodecBasedGenerator class. * Tests codec delegation and codec options pass-through. - * MasterDataset is required by type — no runtime null guard needed. + * PatternGraph is required by type — no runtime null guard needed. * * Uses Rule() + RuleScenario() pattern as feature file uses Rule: blocks. */ @@ -14,7 +14,7 @@ import type { GeneratorContext, GeneratorOutput } from '../../../src/generators/ import type { GenerationError } from '../../../src/generators/orchestrator.js'; import type { DocumentType } from '../../../src/renderable/generate.js'; import { - createTestMasterDataset, + createTestPatternGraph, createDefaultTagRegistry, createTestPattern, } from '../../fixtures/dataset-factories.js'; @@ -87,8 +87,8 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - And('a context with MasterDataset containing patterns', () => { - const dataset = createTestMasterDataset({ + And('a context with PatternGraph containing patterns', () => { + const dataset = createTestPatternGraph({ patterns: [ createTestPattern({ id: 'pattern-00000001', @@ -103,7 +103,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { baseDir: '/test', outputDir: '/test/output', registry: createDefaultTagRegistry(), - masterDataset: dataset, + patternGraph: dataset, }; }); @@ -143,9 +143,9 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - And('a context with MasterDataset', () => { + And('a context with PatternGraph', () => { // Create patterns with file paths matching the filter - const dataset = createTestMasterDataset({ + const dataset = createTestPatternGraph({ patterns: [ createTestPattern({ id: 'pattern-00000001', @@ -175,7 +175,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { baseDir: '/test', outputDir: '/test/output', registry: createDefaultTagRegistry(), - masterDataset: dataset, + patternGraph: dataset, }; }); diff --git a/tests/steps/generators/pr-changes-options.steps.ts b/tests/steps/generators/pr-changes-options.steps.ts index c0d554ef..13507a95 100644 --- a/tests/steps/generators/pr-changes-options.steps.ts +++ b/tests/steps/generators/pr-changes-options.steps.ts @@ -9,7 +9,7 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { generateDocument } from '../../../src/renderable/generate.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { createTestPattern, resetPatternCounter, @@ -17,7 +17,7 @@ import { } from '../../fixtures/dataset-factories.js'; import type { CodecOptions } from '../../../src/renderable/generate.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; import type { OutputFile } from '../../../src/renderable/render.js'; import type { DataTableRow } from '../../support/world.js'; @@ -27,7 +27,7 @@ import type { DataTableRow } from '../../support/world.js'; interface PrChangesOptionsState { patterns: ExtractedPattern[]; - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; outputFiles: OutputFile[]; markdown: string; codecOptions: CodecOptions; @@ -55,10 +55,10 @@ function initState(): PrChangesOptionsState { // ============================================================================= /** - * Build MasterDataset from current patterns + * Build PatternGraph from current patterns */ -function buildDataset(): RuntimeMasterDataset { - return transformToMasterDataset({ +function buildDataset(): RuntimePatternGraph { + return transformToPatternGraph({ patterns: state!.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/generators/prd-implementation-section.steps.ts b/tests/steps/generators/prd-implementation-section.steps.ts index b00d8b0e..4dcc8904 100644 --- a/tests/steps/generators/prd-implementation-section.steps.ts +++ b/tests/steps/generators/prd-implementation-section.steps.ts @@ -12,8 +12,8 @@ import { expect } from 'vitest'; import { createPatternsCodec } from '../../../src/renderable/codecs/patterns.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { createTestPattern, resetPatternCounter } from '../../fixtures/dataset-factories.js'; @@ -26,7 +26,7 @@ import { toKebabCase } from '../../../src/utils/index.js'; // ============================================================================= interface PrdImplementationState { - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; document: RenderableDocument | null; markdown: string; patterns: ExtractedPattern[]; @@ -104,7 +104,7 @@ function createImplementationPattern(options: { * Build the dataset from patterns */ function buildDataset(): void { - state!.dataset = transformToMasterDataset({ + state!.dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/generators/table-extraction.steps.ts b/tests/steps/generators/table-extraction.steps.ts index a0f15949..b1c625de 100644 --- a/tests/steps/generators/table-extraction.steps.ts +++ b/tests/steps/generators/table-extraction.steps.ts @@ -13,8 +13,8 @@ import { createBusinessRulesCodec } from '../../../src/renderable/codecs/busines import { stripMarkdownTables } from '../../../src/renderable/codecs/helpers.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; -import type { RuntimeMasterDataset } from '../../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDataset } from '../../../src/generators/pipeline/transform-dataset.js'; +import type { RuntimePatternGraph } from '../../../src/generators/pipeline/transform-types.js'; +import { transformToPatternGraph } from '../../../src/generators/pipeline/transform-dataset.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import type { BusinessRule } from '../../../src/validation-schemas/extracted-pattern.js'; @@ -26,7 +26,7 @@ import { findTables, findParagraphs } from '../../support/helpers/document-asser // ============================================================================= interface TableExtractionState { - dataset: RuntimeMasterDataset | null; + dataset: RuntimePatternGraph | null; document: RenderableDocument | null; markdown: string; patterns: ExtractedPattern[]; @@ -97,7 +97,7 @@ function createPatternWithRules( * Build the dataset from patterns and run the generator */ function buildDataset(): void { - state!.dataset = transformToMasterDataset({ + state!.dataset = transformToPatternGraph({ patterns: state!.patterns, tagRegistry: createDefaultTagRegistry(), workflow: undefined, diff --git a/tests/steps/mcp/mcp-server.steps.ts b/tests/steps/mcp/mcp-server.steps.ts index 41cb3cb5..e9ac76d6 100644 --- a/tests/steps/mcp/mcp-server.steps.ts +++ b/tests/steps/mcp/mcp-server.steps.ts @@ -54,7 +54,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); Background(({ Given }) => { - Given('a test MasterDataset is initialized for MCP', () => { + Given('a test PatternGraph is initialized for MCP', () => { state = initMcpState(); }); }); @@ -80,7 +80,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { // Session already retrieved during initialization }); - Then('the session contains a MasterDataset with patterns', () => { + Then('the session contains a PatternGraph with patterns', () => { expect(state!.session).not.toBeNull(); expect(state!.session!.dataset.patterns.length).toBeGreaterThan(0); }); diff --git a/tests/support/helpers/design-review-state.ts b/tests/support/helpers/design-review-state.ts index aaad2d54..43142bd1 100644 --- a/tests/support/helpers/design-review-state.ts +++ b/tests/support/helpers/design-review-state.ts @@ -5,23 +5,23 @@ * the SequenceIndex builder and DesignReviewCodec pipeline. * * @architect - * @architect-uses SequenceIndex, DesignReviewCodec, MasterDataset + * @architect-uses SequenceIndex, DesignReviewCodec, PatternGraph */ import type { BusinessRule } from '../../../src/validation-schemas/extracted-pattern.js'; import type { SequenceIndexEntry, - MasterDataset, -} from '../../../src/validation-schemas/master-dataset.js'; + PatternGraph, +} from '../../../src/validation-schemas/pattern-graph.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; import { getSequenceEntry } from '../../../src/api/pattern-helpers.js'; import { buildSequenceIndexEntry } from '../../../src/generators/pipeline/sequence-utils.js'; import type { ValidationSummary } from '../../../src/generators/pipeline/transform-types.js'; -import { transformToMasterDatasetWithValidation } from '../../../src/generators/pipeline/transform-dataset.js'; +import { transformToPatternGraphWithValidation } from '../../../src/generators/pipeline/transform-dataset.js'; import { createDesignReviewCodec } from '../../../src/renderable/codecs/design-review.js'; import { renderToMarkdown } from '../../../src/renderable/render.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; -import { createTestMasterDataset, createTestPattern } from '../../fixtures/dataset-factories.js'; +import { createTestPatternGraph, createTestPattern } from '../../fixtures/dataset-factories.js'; // ============================================================================= // State Types @@ -37,10 +37,10 @@ export interface DesignReviewState { /** Result of buildSequenceIndexEntry */ entry: SequenceIndexEntry | undefined; - /** MasterDataset for codec tests */ - dataset: MasterDataset | null; + /** PatternGraph for codec tests */ + dataset: PatternGraph | null; - /** Validation summary from transformToMasterDatasetWithValidation */ + /** Validation summary from transformToPatternGraphWithValidation */ validation: ValidationSummary | null; /** Pattern name for codec lookup */ @@ -139,7 +139,7 @@ export function buildEntry(state: DesignReviewState): void { } /** - * Build a MasterDataset with a single pattern that has sequence data, + * Build a PatternGraph with a single pattern that has sequence data, * and generate the design review document from it. */ export function generateDesignReview(state: DesignReviewState): void { @@ -158,7 +158,7 @@ export function generateDesignReview(state: DesignReviewState): void { }); // Build the dataset with this pattern - const dataset = createTestMasterDataset({ patterns: [pattern] }); + const dataset = createTestPatternGraph({ patterns: [pattern] }); // The transform pipeline should have built the sequenceIndex state.dataset = dataset; @@ -181,7 +181,7 @@ export function transformWithValidation(state: DesignReviewState): void { sequenceOrchestrator: state.orchestrator, }); - const result = transformToMasterDatasetWithValidation({ + const result = transformToPatternGraphWithValidation({ patterns: [pattern], tagRegistry: createDefaultTagRegistry(), workflow: undefined, @@ -207,7 +207,7 @@ export function resolveSequenceEntry( sequenceOrchestrator: state.orchestrator, }); - state.dataset = createTestMasterDataset({ patterns: [pattern] }); + state.dataset = createTestPatternGraph({ patterns: [pattern] }); state.entry = getSequenceEntry(state.dataset, queryName); return state.entry; } diff --git a/tests/support/helpers/mcp-state.ts b/tests/support/helpers/mcp-state.ts index 9a805cd5..ac90ded2 100644 --- a/tests/support/helpers/mcp-state.ts +++ b/tests/support/helpers/mcp-state.ts @@ -4,13 +4,13 @@ * Shared state and mock infrastructure for MCP server tests. * * @architect - * @architect-uses MCPPipelineSession, ProcessStateAPI, TagRegistry + * @architect-uses MCPPipelineSession, PatternGraphAPI, TagRegistry */ import type { PipelineSession, ParsedOptions } from '../../../src/mcp/index.js'; -import { createTestMasterDataset } from '../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../fixtures/dataset-factories.js'; import { createTestPattern } from '../../fixtures/pattern-factories.js'; -import { createProcessStateAPI } from '../../../src/api/process-state.js'; +import { createPatternGraphAPI } from '../../../src/api/pattern-graph-api.js'; import { createDefaultTagRegistry } from '../../../src/validation-schemas/tag-registry.js'; // ============================================================================= @@ -64,13 +64,13 @@ export class MockMcpServer { /** * Creates a PipelineSession from test factories. - * Avoids real file I/O by using in-memory MasterDataset. + * Avoids real file I/O by using in-memory PatternGraph. */ export function createTestPipelineSession(): PipelineSession { - const dataset = createTestMasterDataset({ + const dataset = createTestPatternGraph({ statusDistribution: { completed: 3, active: 2, planned: 1 }, }); - const api = createProcessStateAPI(dataset); + const api = createPatternGraphAPI(dataset); const registry = createDefaultTagRegistry(); return { @@ -94,8 +94,8 @@ export function createFilterTestSession(): PipelineSession { createTestPattern({ name: 'CompletedP46', status: 'completed', phase: 46 }), createTestPattern({ name: 'RoadmapP5', status: 'roadmap', phase: 5 }), ]; - const dataset = createTestMasterDataset({ patterns }); - const api = createProcessStateAPI(dataset); + const dataset = createTestPatternGraph({ patterns }); + const api = createPatternGraphAPI(dataset); const registry = createDefaultTagRegistry(); return { @@ -146,8 +146,8 @@ export function createRichPatternSession(): PipelineSession { }, ], }); - const dataset = createTestMasterDataset({ patterns: [focal, dep] }); - const api = createProcessStateAPI(dataset); + const dataset = createTestPatternGraph({ patterns: [focal, dep] }); + const api = createPatternGraphAPI(dataset); const registry = createDefaultTagRegistry(); return { diff --git a/tests/support/helpers/process-api-state.ts b/tests/support/helpers/pattern-graph-api-state.ts similarity index 100% rename from tests/support/helpers/process-api-state.ts rename to tests/support/helpers/pattern-graph-api-state.ts diff --git a/tests/support/helpers/pr-changes-codec-state.ts b/tests/support/helpers/pr-changes-codec-state.ts index bd81b1ab..2c72382e 100644 --- a/tests/support/helpers/pr-changes-codec-state.ts +++ b/tests/support/helpers/pr-changes-codec-state.ts @@ -6,10 +6,10 @@ * @architect */ import type { RenderableDocument, TableBlock } from '../../../src/renderable/schema.js'; -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import type { ExtractedPattern } from '../../../src/validation-schemas/index.js'; import { - createTestMasterDataset, + createTestPatternGraph, createTestPattern, resetPatternCounter, } from '../../fixtures/dataset-factories.js'; @@ -29,7 +29,7 @@ import type { DataTableRow } from '../world.js'; // ============================================================================= export interface PrChangesCodecState { - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } @@ -177,8 +177,8 @@ export function getDocumentText(doc: RenderableDocument): string { // ============================================================================= export { findHeadings, findTableWithHeader, findLists }; -export { createTestMasterDataset, createTestPattern }; -export type { DataTableRow, RenderableDocument, MasterDataset, ExtractedPattern }; +export { createTestPatternGraph, createTestPattern }; +export type { DataTableRow, RenderableDocument, PatternGraph, ExtractedPattern }; // ============================================================================= // Pattern Factory Helpers diff --git a/tests/support/helpers/reference-codec-state.ts b/tests/support/helpers/reference-codec-state.ts index a2fa54ee..daa7b15e 100644 --- a/tests/support/helpers/reference-codec-state.ts +++ b/tests/support/helpers/reference-codec-state.ts @@ -6,7 +6,7 @@ * reference-codec-diagram-types.steps.ts, and reference-codec-detail-rendering.steps.ts. */ -import type { MasterDataset } from '../../../src/validation-schemas/master-dataset.js'; +import type { PatternGraph } from '../../../src/validation-schemas/pattern-graph.js'; import type { RenderableDocument } from '../../../src/renderable/schema.js'; import type { DetailLevel } from '../../../src/renderable/codecs/types/base.js'; import { @@ -14,7 +14,7 @@ import { type ReferenceDocConfig, } from '../../../src/renderable/codecs/reference.js'; import { createTestPattern, resetPatternCounter } from '../../fixtures/pattern-factories.js'; -import { createTestMasterDataset } from '../../fixtures/dataset-factories.js'; +import { createTestPatternGraph } from '../../fixtures/dataset-factories.js'; import { findHeadings, findLists, @@ -29,7 +29,7 @@ import { export { createReferenceCodec, createTestPattern, - createTestMasterDataset, + createTestPatternGraph, findHeadings, findLists, findParagraphs, @@ -38,7 +38,7 @@ export { findCollapsibles, findLinkOuts, }; -export type { MasterDataset, RenderableDocument, DetailLevel, ReferenceDocConfig }; +export type { PatternGraph, RenderableDocument, DetailLevel, ReferenceDocConfig }; // ============================================================================ // State @@ -46,7 +46,7 @@ export type { MasterDataset, RenderableDocument, DetailLevel, ReferenceDocConfig export interface ReferenceCodecState { config: ReferenceDocConfig | null; - dataset: MasterDataset | null; + dataset: PatternGraph | null; document: RenderableDocument | null; } From 8c60e3f47e4ac34175e2924c82fca722f85acc26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Wed, 1 Apr 2026 17:42:08 +0200 Subject: [PATCH 2/6] =?UTF-8?q?fix:=20address=20adversarial=20review=20?= =?UTF-8?q?=E2=80=94=20complete=20process-api=E2=86=92pattern-graph-cli=20?= =?UTF-8?q?rename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 2: Renamed ProcessStateAPI implementation layer - ProcessAPICLIImpl → PatternGraphCLIImpl (type + annotations) - ProcessApiReferenceGenerator → CliReferenceGenerator - ProcessStateTypes → PatternGraphAPITypes - process-api.ts → pattern-graph-cli.ts (CLI entry point) - PROCESS-API-REFERENCE.md → CLI-REFERENCE.md (output file) - 14 file renames (source, specs, tests, docs-sources) Wave 3: CLI test infrastructure - All test command strings: "process-api ..." → "pattern-graph-cli ..." - @process-api tags → @pattern-graph-cli - loadFeature() paths updated for renamed test files Wave 4: Documentation and natural language - Stale JSDoc "Master Dataset" → "PatternGraph" in schema - Stale comments in barrel exports and spec text - Broken import path in docs/ARCHITECTURE.md - All remaining "process-api" in CLAUDE.md, specs, docs All 8,808 tests pass. 152 files changed. --- CLAUDE.md | 6 +- README.md | 2 +- _claude-md/api/data-api-cli.md | 2 +- _claude-md/api/dual-source.md | 2 +- _claude-md/core/architecture.md | 2 +- _claude-md/testing/testing-policy.md | 2 +- architect.config.ts | 4 +- ...006-single-read-model-architecture.feature | 2 +- .../pdr-001-session-workflow-commands.feature | 2 +- architect/design-reviews/setup-command.md | 4 +- ...ss-api-layered-extraction-findings.feature | 22 ++-- .../architecture-doc-refactoring.feature | 8 +- architect/specs/cli-recipe-codec.feature | 28 ++--- ...ature => cli-reference-generation.feature} | 46 ++++---- .../config-based-workflow-definition.feature | 8 +- .../cross-cutting-document-inclusion.feature | 2 +- .../data-api-architecture-queries.feature | 28 ++--- .../specs/data-api-cli-ergonomics.feature | 28 ++--- .../specs/data-api-context-assembly.feature | 36 +++---- .../specs/data-api-output-shaping.feature | 46 ++++---- .../data-api-platform-integration.feature | 16 +-- .../specs/data-api-relationship-graph.feature | 20 ++-- .../specs/data-api-session-support.feature | 14 +-- .../specs/data-api-stub-integration.feature | 20 ++-- .../specs/design-review-generation.feature | 2 +- .../specs/mcp-server-integration.feature | 2 +- architect/specs/monorepo-support.feature | 12 +-- ...strator-pipeline-factory-migration.feature | 20 ++-- architect/specs/pattern-graph-api-cli.feature | 6 +- ... pattern-graph-layered-extraction.feature} | 44 ++++---- architect/specs/setup-command.feature | 8 +- ...validator-read-model-consolidation.feature | 6 +- .../handoff-generator.ts | 2 +- .../scope-validator.ts | 2 +- .../cli-recipe-codec/cli-recipe-generator.ts | 14 +-- .../stubs/cli-recipe-codec/recipe-schema.ts | 2 +- .../arch-queries.ts | 2 +- .../coverage-analyzer.ts | 2 +- .../context-assembler.ts | 2 +- .../context-formatter.ts | 2 +- .../data-api-output-shaping/fuzzy-match.ts | 2 +- .../output-pipeline.ts | 2 +- .../data-api-output-shaping/summarize.ts | 2 +- .../stub-resolver.ts | 2 +- .../index-codec-options.ts | 2 +- ...eview-progressive-disclosure-and-codecs.md | 2 +- docs-inbox/codebase-exploration-findings.md | 2 +- docs-inbox/reimplementation-drift-analysis.md | 2 +- ...on-prompt-generator-architecture-review.md | 2 +- docs-inbox/session-prompt-generator-brief.md | 2 +- docs-inbox/session-prompt-generator-manual.md | 2 +- docs-live/ARCHITECTURE.md | 40 +++---- docs-live/CHANGELOG-GENERATED.md | 102 +++++++++--------- docs-live/INDEX.md | 8 +- .../annotation/annotation-overview.md | 2 +- docs-live/business-rules/data-api.md | 10 +- docs-live/business-rules/generation.md | 2 +- .../adr-006-single-read-model-architecture.md | 8 +- docs-live/product-areas/ANNOTATION.md | 22 ++-- docs-live/product-areas/CONFIGURATION.md | 6 +- docs-live/product-areas/DATA-API.md | 84 +++++++-------- docs-live/product-areas/GENERATION.md | 74 ++++++------- docs-live/reference/ARCHITECTURE-TYPES.md | 4 +- ...CESS-API-REFERENCE.md => CLI-REFERENCE.md} | 0 docs-live/reference/PROCESS-API-RECIPES.md | 6 +- docs-live/reference/REFERENCE-SAMPLE.md | 16 +-- ...{process-api-recipes.md => cli-recipes.md} | 0 docs-sources/index-navigation.md | 4 +- docs/ARCHITECTURE.md | 8 +- docs/DOCS-GAP-ANALYSIS.md | 58 +++++----- docs/PROCESS-API.md | 8 +- package.json | 10 +- src/api/arch-queries.ts | 2 +- src/api/context-assembler.ts | 2 +- src/api/context-formatter.ts | 2 +- src/api/coverage-analyzer.ts | 2 +- src/api/fuzzy-match.ts | 2 +- src/api/handoff-generator.ts | 2 +- src/api/scope-validator.ts | 2 +- src/api/stub-resolver.ts | 2 +- src/api/summarize.ts | 2 +- src/api/types.ts | 2 +- src/cli/cli-schema.ts | 10 +- src/cli/output-pipeline.ts | 2 +- .../{process-api.ts => pattern-graph-cli.ts} | 16 +-- .../built-in/cli-recipe-generator.ts | 4 +- ...enerator.ts => cli-reference-generator.ts} | 16 +-- src/generators/built-in/codec-generators.ts | 10 +- src/generators/pipeline/build-pipeline.ts | 2 +- src/renderable/codecs/index-codec.ts | 2 +- src/validation-schemas/index.ts | 2 +- src/validation-schemas/pattern-graph.ts | 4 +- ...eference.feature => cli-reference.feature} | 14 +-- .../codecs/reference-generators.feature | 2 +- .../behavior/context-inference.feature | 20 ++-- tests/features/cli/data-api-cache.feature | 2 +- tests/features/cli/data-api-dryrun.feature | 6 +- tests/features/cli/data-api-help.feature | 8 +- tests/features/cli/data-api-metadata.feature | 6 +- tests/features/cli/data-api-repl.feature | 2 +- ...feature => pattern-graph-cli-core.feature} | 42 ++++---- ...pattern-graph-cli-modifiers-rules.feature} | 32 +++--- ... => pattern-graph-cli-subcommands.feature} | 30 +++--- .../features/generation/design-review.feature | 2 +- ...erence.steps.ts => cli-reference.steps.ts} | 20 ++-- .../codecs/reference-generators.steps.ts | 2 +- .../steps/behavior/context-inference.steps.ts | 20 ++-- tests/steps/cli/data-api-cache.steps.ts | 12 +-- tests/steps/cli/data-api-repl.steps.ts | 2 +- ...eps.ts => pattern-graph-cli-core.steps.ts} | 8 +- ...attern-graph-cli-modifiers-rules.steps.ts} | 8 +- ...=> pattern-graph-cli-subcommands.steps.ts} | 8 +- tests/steps/generation/design-review.steps.ts | 2 +- tests/support/helpers/design-review-state.ts | 2 +- .../helpers/pattern-graph-api-state.ts | 2 +- 115 files changed, 656 insertions(+), 656 deletions(-) rename architect/specs/{process-api-hybrid-generation.feature => cli-reference-generation.feature} (82%) rename architect/specs/{process-api-layered-extraction.feature => pattern-graph-layered-extraction.feature} (90%) rename docs-live/reference/{PROCESS-API-REFERENCE.md => CLI-REFERENCE.md} (100%) rename docs-sources/{process-api-recipes.md => cli-recipes.md} (100%) rename src/cli/{process-api.ts => pattern-graph-cli.ts} (99%) rename src/generators/built-in/{process-api-reference-generator.ts => cli-reference-generator.ts} (88%) rename tests/features/behavior/cli/{process-api-reference.feature => cli-reference.feature} (90%) rename tests/features/cli/{process-api-core.feature => pattern-graph-cli-core.feature} (86%) rename tests/features/cli/{process-api-modifiers-rules.feature => pattern-graph-cli-modifiers-rules.feature} (82%) rename tests/features/cli/{process-api-subcommands.feature => pattern-graph-cli-subcommands.feature} (86%) rename tests/steps/behavior/cli/{process-api-reference.steps.ts => cli-reference.steps.ts} (93%) rename tests/steps/cli/{process-api-core.steps.ts => pattern-graph-cli-core.steps.ts} (98%) rename tests/steps/cli/{process-api-modifiers-rules.steps.ts => pattern-graph-cli-modifiers-rules.steps.ts} (98%) rename tests/steps/cli/{process-api-subcommands.steps.ts => pattern-graph-cli-subcommands.steps.ts} (97%) diff --git a/CLAUDE.md b/CLAUDE.md index 297c8563..ef2b4ad9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -135,7 +135,7 @@ See the **Context Gathering Protocol** section above for mandatory session start - `pattern ` returns ~66KB for completed patterns — prefer `context --session` for interactive sessions. - `query getPattern ` shows raw JSON including `extractedShapes` — use for debugging shape extraction. - Output modifiers (`--names-only`, `--count`, `--fields`) compose with any list/query command. -- `pnpm` outputs a banner to stdout. For clean JSON piping, use `npx tsx src/cli/process-api.ts` directly. +- `pnpm` outputs a banner to stdout. For clean JSON piping, use `npx tsx src/cli/pattern-graph-cli.ts` directly. ### MCP Server — Native AI Context Tools @@ -283,7 +283,7 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - **Schema-First**: Zod schemas in `src/validation-schemas/` define types with runtime validation - **Registry Pattern**: Tag registry (`src/taxonomy/`) defines categories, status values, and tag formats - **Codec-Based Rendering**: Generators in `src/generators/` use codecs to transform data to markdown -- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. +- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, pattern-graph-cli, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. - **Single Read Model** (ADR-006): PatternGraph is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. **Live module inventory:** `pnpm architect:query -- arch context` and `pnpm architect:query -- arch layer` @@ -315,7 +315,7 @@ Tests use Vitest with BDD/Gherkin integration: - **Support**: `tests/support/` - test helpers and setup utilities - **Shared state helpers**: `tests/support/helpers/` - reusable state management for split test suites -Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `process-api-state.ts`). +Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-cli-state.ts`). Run a single test file: `pnpm test tests/steps/scanner/file-discovery.steps.ts` diff --git a/README.md b/README.md index b25634c1..383a89e8 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ All output goes to [`docs-live/`](docs-live/INDEX.md) — 57+ auto-generated fil | Command | Purpose | Docs | | ------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- | | `architect-generate` | Generate documentation from annotated sources | `architect-generate --help` | -| `architect` | Query delivery state for AI coding sessions | [Process API Reference](docs-live/reference/PROCESS-API-REFERENCE.md) | +| `architect` | Query delivery state for AI coding sessions | [Process API Reference](docs-live/reference/CLI-REFERENCE.md) | | `architect-lint-patterns` | Validate annotation quality (missing tags, etc.) | [Validation Rules](docs-live/VALIDATION-RULES.md) | | `architect-guard` | Validate delivery workflow FSM transitions | [Process Guard Reference](docs-live/reference/PROCESS-GUARD-REFERENCE.md) | | `architect-lint-steps` | Validate vitest-cucumber feature/step compatibility | [Validation Rules](docs-live/VALIDATION-RULES.md) | diff --git a/_claude-md/api/data-api-cli.md b/_claude-md/api/data-api-cli.md index 51db3d8b..4819cc2f 100644 --- a/_claude-md/api/data-api-cli.md +++ b/_claude-md/api/data-api-cli.md @@ -11,4 +11,4 @@ See the **Context Gathering Protocol** section above for mandatory session start - `pattern ` returns ~66KB for completed patterns — prefer `context --session` for interactive sessions. - `query getPattern ` shows raw JSON including `extractedShapes` — use for debugging shape extraction. - Output modifiers (`--names-only`, `--count`, `--fields`) compose with any list/query command. -- `pnpm` outputs a banner to stdout. For clean JSON piping, use `npx tsx src/cli/process-api.ts` directly. +- `pnpm` outputs a banner to stdout. For clean JSON piping, use `npx tsx src/cli/pattern-graph-cli.ts` directly. diff --git a/_claude-md/api/dual-source.md b/_claude-md/api/dual-source.md index 0c3c26b8..67450b2d 100644 --- a/_claude-md/api/dual-source.md +++ b/_claude-md/api/dual-source.md @@ -36,4 +36,4 @@ When pattern exists in both TypeScript AND feature file: **Warning:** If TypeScript file is missing `@architect-status`, the pattern data is **ignored** and not merged with feature file. -**Implementation:** `mergePatterns()` in `src/generators/pipeline/merge-patterns.ts`. Conflict strategy is per-consumer: `fatal` (orchestrator/process-api) or `concatenate` (validator). +**Implementation:** `mergePatterns()` in `src/generators/pipeline/merge-patterns.ts`. Conflict strategy is per-consumer: `fatal` (orchestrator/pattern-graph-cli) or `concatenate` (validator). diff --git a/_claude-md/core/architecture.md b/_claude-md/core/architecture.md index 371465a2..f5b7a65f 100644 --- a/_claude-md/core/architecture.md +++ b/_claude-md/core/architecture.md @@ -16,7 +16,7 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC - **Schema-First**: Zod schemas in `src/validation-schemas/` define types with runtime validation - **Registry Pattern**: Tag registry (`src/taxonomy/`) defines categories, status values, and tag formats - **Codec-Based Rendering**: Generators in `src/generators/` use codecs to transform data to markdown -- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, process-api, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. +- **Pipeline Factory**: Shared `buildPatternGraph()` in `src/generators/pipeline/build-pipeline.ts` — all consumers (orchestrator, pattern-graph-cli, validate-patterns) call this instead of wiring inline pipelines. Per-consumer behavior via `PipelineOptions`. - **Single Read Model** (ADR-006): PatternGraph is the sole read model. No consumer re-derives data from raw scanner/extractor output. Anti-patterns: Parallel Pipeline, Lossy Local Type, Re-derived Relationship. **Live module inventory:** `pnpm architect:query -- arch context` and `pnpm architect:query -- arch layer` diff --git a/_claude-md/testing/testing-policy.md b/_claude-md/testing/testing-policy.md index 3ce55fb3..bdbe2d21 100644 --- a/_claude-md/testing/testing-policy.md +++ b/_claude-md/testing/testing-policy.md @@ -6,7 +6,7 @@ Tests use Vitest with BDD/Gherkin integration: - **Support**: `tests/support/` - test helpers and setup utilities - **Shared state helpers**: `tests/support/helpers/` - reusable state management for split test suites -Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `process-api-state.ts`). +Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-cli-state.ts`). Run a single test file: `pnpm test tests/steps/scanner/file-discovery.steps.ts` diff --git a/architect.config.ts b/architect.config.ts index e21d150d..bce6894b 100644 --- a/architect.config.ts +++ b/architect.config.ts @@ -57,7 +57,7 @@ const INDEX_DOCUMENT_ENTRIES: readonly DocumentEntry[] = [ // --- Reference Guides --- { title: 'Annotation Reference', path: 'reference/ANNOTATION-REFERENCE.md', description: 'Annotation mechanics, shape extraction, tag reference', audience: 'Developers', topic: 'Reference Guides' }, { title: 'Session Workflow Guide', path: 'reference/SESSION-WORKFLOW-GUIDE.md', description: 'Planning, Design, Implementation session workflows', audience: 'AI/Devs', topic: 'Reference Guides' }, - { title: 'Process API Reference', path: 'reference/PROCESS-API-REFERENCE.md', description: 'CLI command reference with flags and examples', audience: 'AI/Devs', topic: 'Reference Guides' }, + { title: 'Process API Reference', path: 'reference/CLI-REFERENCE.md', description: 'CLI command reference with flags and examples', audience: 'AI/Devs', topic: 'Reference Guides' }, { title: 'Process API Recipes', path: 'reference/PROCESS-API-RECIPES.md', description: 'CLI workflow recipes and session guides', audience: 'AI/Devs', topic: 'Reference Guides' }, { title: 'Process Guard Reference', path: 'reference/PROCESS-GUARD-REFERENCE.md', description: 'Pre-commit hooks, error codes, programmatic API', audience: 'Team Leads', topic: 'Reference Guides' }, { title: 'Architecture Codecs', path: 'reference/ARCHITECTURE-CODECS.md', description: 'All codecs with factory patterns and options', audience: 'Developers', topic: 'Reference Guides' }, @@ -256,7 +256,7 @@ export default defineConfig({ 'claude-modules': { outputDirectory: '_claude-md', }, - 'process-api-reference': { + 'cli-reference': { outputDirectory: 'docs-live', }, 'cli-recipe': { diff --git a/architect/decisions/adr-006-single-read-model-architecture.feature b/architect/decisions/adr-006-single-read-model-architecture.feature index ed81518a..31a6b41e 100644 --- a/architect/decisions/adr-006-single-read-model-architecture.feature +++ b/architect/decisions/adr-006-single-read-model-architecture.feature @@ -54,7 +54,7 @@ Feature: ADR-006 - Single Read Model Architecture **Verified by:** Feature consumers import from PatternGraph not from raw pipeline stages | Layer | May Import | Examples | - | Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, process-api.ts pipeline setup | + | Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, pattern-graph-cli.ts pipeline setup | | Feature Consumption | PatternGraph, relationshipIndex | codecs, PatternGraphAPI, validators, query handlers | Exception: `lint-patterns.ts` is a pure stage-1 consumer. It validates diff --git a/architect/decisions/pdr-001-session-workflow-commands.feature b/architect/decisions/pdr-001-session-workflow-commands.feature index 023f0c07..e7de1cbf 100644 --- a/architect/decisions/pdr-001-session-workflow-commands.feature +++ b/architect/decisions/pdr-001-session-workflow-commands.feature @@ -145,5 +145,5 @@ Feature: PDR-001 - Session Workflow Commands Design Decisions @acceptance-criteria @happy-path Scenario: Active pattern infers implement session Given a pattern with status "active" - When running "process-api handoff --pattern MyPattern" + When running "pattern-graph-cli handoff --pattern MyPattern" Then the session summary shows session type "implement" diff --git a/architect/design-reviews/setup-command.md b/architect/design-reviews/setup-command.md index 6646f149..7a348af7 100644 --- a/architect/design-reviews/setup-command.md +++ b/architect/design-reviews/setup-command.md @@ -74,7 +74,7 @@ sequenceDiagram init_cli->>init_cli: exit(1) end - Note over init_cli: Rule 4 — Injected scripts reference bin names (process-api, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via —esm flag. + Note over init_cli: Rule 4 — Injected scripts reference bin names (pattern-graph-cli, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via —esm flag. init_cli->>+augment_package_json: InitConfig augment_package_json-->>-init_cli: package.json updated with process and docs scripts @@ -86,7 +86,7 @@ sequenceDiagram init_cli->>+generate_example: InitConfig generate_example-->>-init_cli: directories created for source globs, example annotated .ts file - Note over init_cli: Rule 6 — After all files are generated, init runs process-api overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information. + Note over init_cli: Rule 6 — After all files are generated, init runs pattern-graph-cli overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information. init_cli->>+validate_setup: targetDir: string validate_setup-->>-init_cli: SetupResult diff --git a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature index 83a10607..a9d03a61 100644 --- a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature +++ b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature @@ -1,16 +1,16 @@ @ideation @ideation-status:active -@ideation-scope:process-api,pipeline-factory,process-guard,adr-006-enforcement +@ideation-scope:pattern-graph-cli,pipeline-factory,process-guard,adr-006-enforcement @relates-to:ProcessAPILayeredExtraction,ADR006SingleReadModelArchitecture,ProcessGuardLinter,ValidatorReadModelConsolidation Feature: Process API Layered Extraction — Investigation Findings Trigger: ADR-006 architectural investigation revealed concrete violations - in process-api.ts (1,703 lines, three responsibilities), pipeline duplication + in pattern-graph-cli.ts (1,703 lines, three responsibilities), pipeline duplication across four consumers, and a previously undocumented fifth consumer in the Process Guard. These findings inform the design session for ProcessAPILayeredExtraction. - Rule: Three responsibilities confirmed in process-api.ts + Rule: Three responsibilities confirmed in pattern-graph-cli.ts Investigation verified the spec claim. The file contains: @@ -41,12 +41,12 @@ Feature: Process API Layered Extraction — Investigation Findings Rule: Pipeline duplication is four consumers, not three - The spec identifies orchestrator.ts, process-api.ts, and + The spec identifies orchestrator.ts, pattern-graph-cli.ts, and validate-patterns.ts. Investigation found a fourth: | Consumer | File | What It Imports | | Orchestrator | src/generators/orchestrator.ts:51-55 | scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin | - | Process API CLI | src/cli/process-api.ts:45-47 | scanPatterns, extractPatterns, scanGherkinFiles | + | Process API CLI | src/cli/pattern-graph-cli.ts:45-47 | scanPatterns, extractPatterns, scanGherkinFiles | | Validate Patterns CLI | src/cli/validate-patterns.ts:32-35 | scanPatterns, scanGherkinFiles, extractPatterns, extractProcessMetadata | | Process Guard | src/lint/process-guard/derive-state.ts:33 | scanGherkinFiles, extractDeliverables | @@ -90,12 +90,12 @@ Feature: Process API Layered Extraction — Investigation Findings move with the domain logic. parseBusinessRuleAnnotations() is already in src/api/ or should be extracted there. - Rule: Orchestrator pipeline differs from process-api pipeline + Rule: Orchestrator pipeline differs from pattern-graph-cli pipeline The orchestrator (src/generators/orchestrator.ts) has a richer pipeline - than process-api.ts. Key differences: + than pattern-graph-cli.ts. Key differences: - | Step | orchestrator.ts | process-api.ts | + | Step | orchestrator.ts | pattern-graph-cli.ts | | Gherkin extraction | extractPatternsFromGherkin (full) | extractProcessMetadata + extractDeliverables (partial) | | Pattern merging | mergePatterns() | mergePatterns() | | Hierarchy | computeHierarchyChildren() | computeHierarchyChildren() | @@ -103,7 +103,7 @@ Feature: Process API Layered Extraction — Investigation Findings | Transform | transformToPatternGraph() | transformToPatternGraphWithValidation() | The pipeline factory must accommodate both: orchestrator needs the - basic PatternGraph, process-api needs the validation summary too. + basic PatternGraph, pattern-graph-cli needs the validation summary too. transformToPatternGraphWithValidation returns both — the factory should return TransformResult and let callers destructure what they need. @@ -113,7 +113,7 @@ Feature: Process API Layered Extraction — Investigation Findings ProcessAPILayeredExtraction design spec: **1. Output pipeline integration** - process-api.ts has an output pipeline (src/cli/output-pipeline.ts) for + pattern-graph-cli.ts has an output pipeline (src/cli/output-pipeline.ts) for formatting, field selection, and output modifiers. The CLI shell needs to apply this after getting results from API modules. The interface between API module return values and the output pipeline is a design @@ -126,7 +126,7 @@ Feature: Process API Layered Extraction — Investigation Findings monad pattern. **3. RouteContext type** - process-api.ts defines RouteContext (line 1285) as the parameter type + pattern-graph-cli.ts defines RouteContext (line 1285) as the parameter type for handlers. When domain logic moves to src/api/, the context type either moves too or is replaced by explicit parameters. The cleaner option is explicit parameters (dataset, filters, modifiers) — RouteContext diff --git a/architect/specs/architecture-doc-refactoring.feature b/architect/specs/architecture-doc-refactoring.feature index 32220c9d..5055e92b 100644 --- a/architect/specs/architecture-doc-refactoring.feature +++ b/architect/specs/architecture-doc-refactoring.feature @@ -290,9 +290,9 @@ Feature: Architecture Document Refactoring Rule: PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document **Invariant:** DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using - shapeSelectors with group master-dataset to extract PatternGraph schema types, + shapeSelectors with group pattern-graph to extract PatternGraph schema types, RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files - tagged with @architect-shape pattern-graph and @architect-include master-dataset + tagged with @architect-shape pattern-graph contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. @@ -308,7 +308,7 @@ Feature: Architecture Document Refactoring @acceptance-criteria @happy-path Scenario: PatternGraph shapes extracted via shape selectors Given source files tagged with @architect-shape pattern-graph - And a ReferenceDocConfig with shapeSelectors targeting master-dataset group + And a ReferenceDocConfig with shapeSelectors targeting pattern-graph group When the reference codec generates ARCHITECTURE-TYPES.md Then PatternGraphSchema, RuntimePatternGraph, and RawDataset types appear And each shape includes its TypeScript declaration and JSDoc description @@ -316,7 +316,7 @@ Feature: Architecture Document Refactoring @acceptance-criteria @happy-path Scenario: Pipeline types included in ARCHITECTURE-TYPES reference doc Given PipelineOptions and PipelineResult tagged with @architect-shape pattern-graph - And @architect-include master-dataset on their source files + And @architect-shape pattern-graph on their source files When the reference codec generates ARCHITECTURE-TYPES.md Then PipelineOptions and PipelineResult shapes appear in the API Types section And both detailed and compact outputs are produced diff --git a/architect/specs/cli-recipe-codec.feature b/architect/specs/cli-recipe-codec.feature index cd82202c..37cba835 100644 --- a/architect/specs/cli-recipe-codec.feature +++ b/architect/specs/cli-recipe-codec.feature @@ -6,15 +6,15 @@ @architect-effort:2w @architect-product-area:Generation @architect-depends-on:DocsConsolidationStrategy -@architect-depends-on:ProcessApiHybridGeneration +@architect-depends-on:CliReferenceGeneration @architect-business-value:replaces-460-lines-of-manual-PROCESS-API-md-prose-with-generated-recipe-and-narrative-content @architect-priority:medium Feature: CLI Recipe Codec **Problem:** `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after - Phase 43 (ProcessApiHybridGeneration) extracted 3 reference tables to - `docs-live/reference/PROCESS-API-REFERENCE.md`. The remaining content includes: + Phase 43 (CliReferenceGeneration) extracted 3 reference tables to + `docs-live/reference/CLI-REFERENCE.md`. The remaining content includes: "Why Use This" motivation (30 lines), Quick Start with example output (32 lines), Session Types decision tree (12 lines), Session Workflow Commands with 6 narrative command descriptions and output examples (125 lines), Pattern Discovery with 8 @@ -26,7 +26,7 @@ Feature: CLI Recipe Codec **Solution:** Create a standalone `CliRecipeGenerator` that extends CLI_SCHEMA with recipe definitions and narrative metadata, producing `docs-live/reference/PROCESS-API-RECIPES.md`. - The generator is a sibling to `ProcessApiReferenceGenerator` -- both are standalone + The generator is a sibling to `CliReferenceGenerator` -- both are standalone (ADR-006 compliant) and consume CLI_SCHEMA directly. Editorial content that cannot be derived from schema (motivation prose, session decision tree) uses the preamble mechanism. `docs/PROCESS-API.md` retains a slim editorial introduction and links @@ -51,13 +51,13 @@ Feature: CLI Recipe Codec **Design Session Findings (2026-03-06):** | Finding | Impact | Resolution | | DD-1: Recipes need separate RecipeGroup[] field, not inline per-option | Recipes span multiple option groups (e.g., "Starting a Session" uses overview + scope-validate + context) | Added RecipeGroup[] and CommandNarrativeGroup[] as optional fields on CLISchema -- existing consumers unchanged | - | DD-2: CLI_SCHEMA extension is additive with two new optional fields | ProcessApiReferenceGenerator and showHelp ignore unknown fields | recipes and commandNarratives fields added to CLISchema interface, not a separate extended type | + | DD-2: CLI_SCHEMA extension is additive with two new optional fields | CliReferenceGenerator and showHelp ignore unknown fields | recipes and commandNarratives fields added to CLISchema interface, not a separate extended type | | DD-3: Preamble mechanism proven by ReferenceDocConfig and ErrorGuideCodec stubs | Why Use This (30 lines), Quick Start (32 lines), Session Types (12 lines) are editorial judgment | Generator accepts preamble SectionBlock[] via CliRecipeGeneratorConfig, configured in architect.config.ts | | DD-4: CommandNarrative type needed, not just CLIOptionGroup.description extension | Session Workflow has 6 commands each needing description + usage example + expected output | New CommandNarrative interface with command, description, usageExample, details, expectedOutput fields | | DD-5: Recipes grouped by task intent, not session type or command | Matches existing Common Recipes structure in PROCESS-API.md | 5 groups: Starting a Session, Finding Work, Investigating, Design Prep, Ending a Session | | Content audit: ~460 lines map to 3 schema locations + preamble | Zero information loss from manual to generated | recipes (42 lines), commandNarratives (287 lines), preamble (74 lines), kept in manual (70 lines) | - | ProcessApiReferenceGenerator is 113 lines and proven stable | Extending it risks regressions on Phase 43 deliverables | CliRecipeGenerator is a separate sibling class, same DocumentGenerator interface | - | Generator registration follows process-api-reference pattern | generatorOverrides already has process-api-reference entry | Add cli-recipe entry with same outputDirectory: docs-live | + | CliReferenceGenerator is 113 lines and proven stable | Extending it risks regressions on Phase 43 deliverables | CliRecipeGenerator is a separate sibling class, same DocumentGenerator interface | + | Generator registration follows cli-reference pattern | generatorOverrides already has cli-reference entry | Add cli-recipe entry with same outputDirectory: docs-live | **Design Stubs:** | Stub | Location | Key Decisions | @@ -78,17 +78,17 @@ Feature: CLI Recipe Codec Rule: CLI recipes are a separate generator from reference tables **Invariant:** The `CliRecipeGenerator` is a standalone sibling to - `ProcessApiReferenceGenerator`, not an extension of it. Both implement + `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the - reference generator produces `docs-live/reference/PROCESS-API-REFERENCE.md`. + reference generator produces `docs-live/reference/CLI-REFERENCE.md`. **Rationale:** Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator - responsible for two distinct content types. ProcessApiReferenceGenerator is + responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. @@ -98,10 +98,10 @@ Feature: CLI Recipe Codec @acceptance-criteria @happy-path Scenario: CliRecipeGenerator produces recipe file independently Given the CliRecipeGenerator is registered in the orchestrator - And the ProcessApiReferenceGenerator is also registered + And the CliReferenceGenerator is also registered When docs:all runs Then docs-live/reference/PROCESS-API-RECIPES.md is created - And docs-live/reference/PROCESS-API-REFERENCE.md is also created + And docs-live/reference/CLI-REFERENCE.md is also created And neither generator imports nor depends on the other @acceptance-criteria @validation @@ -194,7 +194,7 @@ Feature: CLI Recipe Codec **Invariant:** After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: - `docs-live/reference/PROCESS-API-REFERENCE.md` (option tables from Phase 43) and + `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. @@ -216,7 +216,7 @@ Feature: CLI Recipe Codec Scenario: PROCESS-API.md links to both generated files Given PROCESS-API.md has been trimmed after CliRecipeCodec completion When reading the manual file - Then it contains a link to docs-live/reference/PROCESS-API-REFERENCE.md + Then it contains a link to docs-live/reference/CLI-REFERENCE.md And it contains a link to docs-live/reference/PROCESS-API-RECIPES.md And the total line count is under 100 lines diff --git a/architect/specs/process-api-hybrid-generation.feature b/architect/specs/cli-reference-generation.feature similarity index 82% rename from architect/specs/process-api-hybrid-generation.feature rename to architect/specs/cli-reference-generation.feature index 5a4ee0d7..0da2214c 100644 --- a/architect/specs/process-api-hybrid-generation.feature +++ b/architect/specs/cli-reference-generation.feature @@ -1,12 +1,12 @@ @architect -@architect-pattern:ProcessApiHybridGeneration +@architect-pattern:CliReferenceGeneration @architect-status:completed @architect-unlock-reason:Retroactive-completion-during-rebrand @architect-phase:43 @architect-effort:1d @architect-product-area:Generation @architect-depends-on:DocsConsolidationStrategy -@architect-business-value:keeps-process-api-reference-tables-in-sync-with-cli-schema-automatically +@architect-business-value:keeps-cli-reference-tables-in-sync-with-cli-schema-automatically @architect-priority:low Feature: PROCESS-API.md Hybrid Generation @@ -14,18 +14,18 @@ Feature: PROCESS-API.md Hybrid Generation `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source code: Global Options (lines 382-389, 6 rows), Output Modifiers (lines 397-403, 5 rows), and List Filters (lines 415-424, 8 rows). - These ~41 lines are pure data derived from code constants in `src/cli/process-api.ts` + These ~41 lines are pure data derived from code constants in `src/cli/pattern-graph-cli.ts` and `src/cli/output-pipeline.ts`. When CLI options change, these tables require manual updates and risk falling out of sync with the implementation. - Additionally, the `showHelp()` function (lines 271-370 of `src/cli/process-api.ts`) + Additionally, the `showHelp()` function (lines 271-370 of `src/cli/pattern-graph-cli.ts`) is a hardcoded third copy of the same information, creating three-way drift risk: parser code, help text, and markdown tables. **Solution:** Create a declarative CLI schema (`src/cli/cli-schema.ts`) as the single source of - truth. A standalone `ProcessApiReferenceGenerator` reads this schema and produces - a complete generated reference file at `docs-live/reference/PROCESS-API-REFERENCE.md`. + truth. A standalone `CliReferenceGenerator` reads this schema and produces + a complete generated reference file at `docs-live/reference/CLI-REFERENCE.md`. The "Output Reference" section in `docs/PROCESS-API.md` (lines 376-424) is replaced with a heading and link to the generated file. The `showHelp()` function is refactored to consume the same schema, eliminating three-way sync. @@ -38,7 +38,7 @@ Feature: PROCESS-API.md Hybrid Generation **Design Findings (2026-03-05):** | Finding | Impact | Resolution | - | Original spec references src/cli/parser.ts | File does not exist | Fix to src/cli/process-api.ts + src/cli/output-pipeline.ts | + | Original spec references src/cli/parser.ts | File does not exist | Fix to src/cli/pattern-graph-cli.ts + src/cli/output-pipeline.ts | | Orchestrator only does full-file writes | Marker-based partial replacement not supported | Split Output Reference into separate generated file | | ReferenceDocConfig is PatternGraph-sourced | CLI schema data is not annotation-derived | Standalone generator, not ReferenceDocConfig (ADR-006) | | --format in Output Modifiers table but not in OutputModifiers interface | Would produce incomplete table | Schema includes --format alongside modifiers | @@ -69,22 +69,22 @@ Feature: PROCESS-API.md Hybrid Generation | Deliverable | Status | Location | Tests | Test Type | | Create declarative CLI schema with option groups | complete | src/cli/cli-schema.ts | Yes | unit | | Sync test verifying schema entries match parseArgs behavior | complete | tests/features/behavior/cli/ | Yes | integration | - | ProcessApiReferenceGenerator producing complete reference file | complete | src/generators/built-in/process-api-reference-generator.ts | Yes | integration | + | CliReferenceGenerator producing complete reference file | complete | src/generators/built-in/cli-reference-generator.ts | Yes | integration | | Register generator in orchestrator config | complete | architect.config.ts | Yes | integration | | Trim PROCESS-API.md Output Reference to link to generated file | complete | docs/PROCESS-API.md | Yes | manual | - | Refactor showHelp to consume CLI schema | complete | src/cli/process-api.ts | Yes | integration | - | Behavior spec with scenarios for all 3 generated tables | complete | tests/features/behavior/cli/process-api-reference.feature | Yes | integration | + | Refactor showHelp to consume CLI schema | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | Behavior spec with scenarios for all 3 generated tables | complete | tests/features/behavior/cli/cli-reference.feature | Yes | integration | Rule: CLI schema is single source of truth for reference tables **Invariant:** A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in - `docs-live/reference/PROCESS-API-REFERENCE.md` are generated from this schema by - a standalone `ProcessApiReferenceGenerator`. The schema also drives `showHelp()`. + `docs-live/reference/CLI-REFERENCE.md` are generated from this schema by + a standalone `CliReferenceGenerator`. The schema also drives `showHelp()`. **Rationale:** CLI options are defined imperatively in `parseArgs()` (lines 132-265 - of `src/cli/process-api.ts`) and `OutputModifiers`/`ListFilters` interfaces + of `src/cli/pattern-graph-cli.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from @@ -96,11 +96,11 @@ Feature: PROCESS-API.md Hybrid Generation @acceptance-criteria @happy-path Scenario: Generated tables match CLI schema definitions Given a CLI schema defining global options, output modifiers, and list filters - When the ProcessApiReferenceGenerator runs - Then PROCESS-API-REFERENCE.md contains a Global Options table with all defined flags + When the CliReferenceGenerator runs + Then CLI-REFERENCE.md contains a Global Options table with all defined flags And the table includes flag name, short alias, description, and default columns - And PROCESS-API-REFERENCE.md contains an Output Modifiers table with all defined modifiers - And PROCESS-API-REFERENCE.md contains a List Filters table with all defined filter keys + And CLI-REFERENCE.md contains an Output Modifiers table with all defined modifiers + And CLI-REFERENCE.md contains a List Filters table with all defined filter keys @acceptance-criteria @validation Scenario: CLI schema stays in sync with parser @@ -128,14 +128,14 @@ Feature: PROCESS-API.md Hybrid Generation @acceptance-criteria @validation Scenario: Prose sections unchanged after regeneration Given PROCESS-API.md with narrative sections including "Why Use This" and "Common Recipes" - When the ProcessApiReferenceGenerator runs + When the CliReferenceGenerator runs Then PROCESS-API.md is not modified by the generator - And only PROCESS-API-REFERENCE.md is created or updated - And PROCESS-API.md contains a link to PROCESS-API-REFERENCE.md in the Output Reference section + And only CLI-REFERENCE.md is created or updated + And PROCESS-API.md contains a link to CLI-REFERENCE.md in the Output Reference section Rule: Standalone generator respects ADR-006 single read model - **Invariant:** The `ProcessApiReferenceGenerator` imports CLI schema data directly + **Invariant:** The `CliReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. @@ -150,9 +150,9 @@ Feature: PROCESS-API.md Hybrid Generation @acceptance-criteria @integration Scenario: Generator produces complete reference file - Given the ProcessApiReferenceGenerator is registered in the orchestrator + Given the CliReferenceGenerator is registered in the orchestrator When docs:all runs - Then docs-live/reference/PROCESS-API-REFERENCE.md is created + Then docs-live/reference/CLI-REFERENCE.md is created And the file contains three sections: Global Options, Output Modifiers, List Filters And each section includes a markdown table with headers and data rows And inter-table prose (config auto-detection, valid fields, precedence) is included diff --git a/architect/specs/config-based-workflow-definition.feature b/architect/specs/config-based-workflow-definition.feature index df066eea..c0f7f1f4 100644 --- a/architect/specs/config-based-workflow-definition.feature +++ b/architect/specs/config-based-workflow-definition.feature @@ -55,7 +55,7 @@ Feature: Config-Based Workflow Definition | Remove dead code paths | complete | src/config/workflow-loader.ts | | Update public API exports | complete | src/config/index.ts | | Remove async and try-catch in orchestrator | complete | src/generators/orchestrator.ts | - | Remove async and try-catch in process-api | complete | src/cli/process-api.ts | + | Remove async and try-catch in pattern-graph-cli | complete | src/cli/pattern-graph-cli.ts | | Delete orphaned JSON file | n/a | architect/6-phase-standard.json | | Amend ADR-001 with phase definitions rule | complete | architect/decisions/adr-001-taxonomy-canonical-values.feature | @@ -71,7 +71,7 @@ Feature: Config-Based Workflow Definition **Rationale:** The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, - process-api) already handle the failure gracefully, proving the system + pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. @@ -86,12 +86,12 @@ Feature: Config-Based Workflow Definition | Remove dead code paths | Delete getCatalogueWorkflowsPath, loadWorkflowConfig, DEFAULT_WORKFLOW_NAME, dead imports | workflow-loader.ts cleanup | | Remove loadWorkflowConfig from public API | Update src/config/index.ts exports | Breaking change (safe: function always threw) | | Update orchestrator call site | Remove await and try-catch (lines 410-418) | orchestrator.ts | - | Update process-api call site | Remove await and try-catch (lines 549-555) | process-api.ts | + | Update pattern-graph-cli call site | Remove await and try-catch (lines 549-555) | pattern-graph-cli.ts | @acceptance-criteria @happy-path Scenario: Default workflow loads without warning Given the Architect package with no workflow JSON file - When the process-api runs an overview command + When the pattern-graph-cli runs an overview command Then no workflow warning appears in output And the overview displays progress, active phases, and blocking info diff --git a/architect/specs/cross-cutting-document-inclusion.feature b/architect/specs/cross-cutting-document-inclusion.feature index e7da766d..492b174a 100644 --- a/architect/specs/cross-cutting-document-inclusion.feature +++ b/architect/specs/cross-cutting-document-inclusion.feature @@ -102,7 +102,7 @@ Feature: Cross-Cutting Document Inclusion | reference.ts | Rename DiagramScope.archView to include, add includeTags to ReferenceDocConfig, add inclusion pass | ~35 lines | | project-config-schema.ts | Rename archView to include, add includeTags | ~5 lines | | transform-dataset.ts | Rename archView references to include in dataset views | ~10 lines | - | master-dataset.ts | Rename byArchView to byInclude in dataset schema | ~5 lines | + | pattern-graph.ts | Rename byArchView to byInclude in dataset schema | ~5 lines | | reference-generators.ts | Update built-in configs from archView to include | ~5 lines | | pattern-scanner.ts | Rename arch-view extraction to include | ~3 lines | | architect.config.ts | Update showcase config: rename archView, add includeTags | ~5 lines | diff --git a/architect/specs/data-api-architecture-queries.feature b/architect/specs/data-api-architecture-queries.feature index 0ad3a144..2ad46ccd 100644 --- a/architect/specs/data-api-architecture-queries.feature +++ b/architect/specs/data-api-architecture-queries.feature @@ -36,12 +36,12 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | arch neighborhood handler | complete | src/cli/process-api.ts | Yes | integration | - | arch compare handler | complete | src/cli/process-api.ts | Yes | integration | + | arch neighborhood handler | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | arch compare handler | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | arch coverage analyzer | complete | src/api/coverage-analyzer.ts | Yes | unit | - | tags subcommand | complete | src/cli/process-api.ts | Yes | integration | - | sources subcommand | complete | src/cli/process-api.ts | Yes | integration | - | unannotated subcommand | complete | src/cli/process-api.ts | Yes | integration | + | tags subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | sources subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | unannotated subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | # ============================================================================ # RULE 1: Extended Architecture Queries @@ -71,7 +71,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration Given a pattern "OrderSaga" in the "orders" context And "OrderSaga" uses "CommandBus" and "EventStore" And "OrderSaga" is used by "SagaRouter" - When running "process-api arch neighborhood OrderSaga" + When running "pattern-graph-cli arch neighborhood OrderSaga" Then the output shows "Uses: CommandBus, EventStore" And the output shows "Used by: SagaRouter" And the output shows sibling patterns in the "orders" context @@ -79,7 +79,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @happy-path Scenario: Cross-context comparison Given contexts "orders" and "inventory" with some shared dependencies - When running "process-api arch compare orders inventory" + When running "pattern-graph-cli arch compare orders inventory" Then the output shows shared dependencies between contexts And the output shows unique dependencies per context And the output identifies integration points @@ -87,7 +87,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @validation Scenario: Neighborhood for nonexistent pattern returns error Given no pattern named "NonExistent" exists - When running "process-api arch neighborhood NonExistent" + When running "pattern-graph-cli arch neighborhood NonExistent" Then the command fails with a pattern-not-found error And the error message suggests checking the pattern name @@ -118,7 +118,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @happy-path Scenario: Architecture coverage report Given 41 annotated files out of 50 scannable files - When running "process-api arch coverage" + When running "pattern-graph-cli arch coverage" Then the output shows "41/50 files annotated (82%)" And the output lists the 9 unannotated files And the output shows unused taxonomy values @@ -126,14 +126,14 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @happy-path Scenario: Find unannotated files with path filter Given some TypeScript files without the @architect opt-in marker - When running "process-api unannotated --path 'src/generators/**/*.ts'" + When running "pattern-graph-cli unannotated --path 'src/generators/**/*.ts'" Then the output lists only unannotated files matching the glob And each file shows its location relative to base directory @acceptance-criteria @validation Scenario: Coverage with no scannable files returns zero coverage Given the input globs match 0 files - When running "process-api arch coverage" + When running "pattern-graph-cli arch coverage" Then the output shows "0/0 files annotated (0%)" And the unannotated files list is empty @@ -169,7 +169,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @happy-path Scenario: List all tags with usage counts Given patterns with various tags applied - When running "process-api tags" + When running "pattern-graph-cli tags" Then the output lists each tag name with its usage count And category tags show their value distribution And status tags show their value distribution @@ -177,7 +177,7 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @happy-path Scenario: Source file inventory Given TypeScript, Gherkin, and stub files in the pipeline - When running "process-api sources" + When running "pattern-graph-cli sources" Then the output shows file counts by type And the output shows location patterns for each type And the total matches the pipeline scan count @@ -185,6 +185,6 @@ Feature: Data API Architecture Queries - Deep Architecture Exploration @acceptance-criteria @validation Scenario: Tags listing with no patterns returns empty report Given the pipeline has 0 patterns - When running "process-api tags" + When running "pattern-graph-cli tags" Then the output shows an empty tag report with 0 pattern count And no tag entries are listed diff --git a/architect/specs/data-api-cli-ergonomics.feature b/architect/specs/data-api-cli-ergonomics.feature index 4588a4cf..ba437a12 100644 --- a/architect/specs/data-api-cli-ergonomics.feature +++ b/architect/specs/data-api-cli-ergonomics.feature @@ -10,19 +10,19 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode **Problem:** - The process-api CLI runs the full pipeline (scan, extract, transform) on every + The pattern-graph-cli CLI runs the full pipeline (scan, extract, transform) on every invocation, taking 2-5 seconds. During design sessions with 10-20 queries, this adds up to 1-2 minutes of waiting. There is no way to keep the pipeline loaded - between queries. Per-subcommand help is missing -- `process-api context --help` + between queries. Per-subcommand help is missing -- `pattern-graph-cli context --help` does not work. FSM-only queries (like `isValidTransition`) run the full pipeline even though FSM rules are static. **Solution:** Add performance and ergonomic improvements: 1. **Pipeline caching** -- Cache PatternGraph to temp file with mtime invalidation - 2. **REPL mode** -- `process-api repl` keeps pipeline loaded for interactive queries + 2. **REPL mode** -- `pattern-graph-cli repl` keeps pipeline loaded for interactive queries 3. **FSM short-circuit** -- FSM queries skip the scan pipeline entirely - 4. **Per-subcommand help** -- `process-api --help` with examples + 4. **Per-subcommand help** -- `pattern-graph-cli --help` with examples 5. **Dry-run mode** -- `--dry-run` shows what would be scanned without running 6. **Validation summary** -- Include pipeline health in response metadata @@ -38,10 +38,10 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode | Deliverable | Status | Location | Tests | Test Type | | PatternGraph cache with mtime invalidation | complete | src/cli/dataset-cache.ts | Yes | unit | | REPL mode handler | complete | src/cli/repl.ts | Yes | integration | - | FSM short-circuit for static queries | complete | src/cli/process-api.ts | Yes | unit | - | Per-subcommand help system | complete | src/cli/process-api.ts | Yes | integration | - | Dry-run mode | complete | src/cli/process-api.ts | Yes | integration | - | Validation summary in metadata | complete | src/cli/process-api.ts | Yes | unit | + | FSM short-circuit for static queries | complete | src/cli/pattern-graph-cli.ts | Yes | unit | + | Per-subcommand help system | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | Dry-run mode | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | Validation summary in metadata | complete | src/cli/pattern-graph-cli.ts | Yes | unit | # ============================================================================ # RULE 1: Pipeline Caching @@ -64,7 +64,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode Scenario: Second query uses cached dataset Given a previous query has cached the PatternGraph And no source files have been modified since - When running "process-api status" + When running "pattern-graph-cli status" Then the query completes in under 200ms And the response metadata indicates cache hit @@ -72,7 +72,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode Scenario: Cache invalidated on source file change Given a cached PatternGraph exists And a source TypeScript file has been modified - When running "process-api status" + When running "pattern-graph-cli status" Then the pipeline runs fresh (cache miss) And the new dataset is cached for subsequent queries @@ -93,7 +93,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode @acceptance-criteria @happy-path Scenario: REPL accepts multiple queries - Given REPL mode is started with "process-api repl" + Given REPL mode is started with "pattern-graph-cli repl" When entering "status" then "pattern OrderSaga" then "dep-tree OrderSaga" Then each query returns results without pipeline re-initialization And "quit" exits the REPL @@ -123,14 +123,14 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode @acceptance-criteria @happy-path Scenario: Per-subcommand help output - When running "process-api context --help" + When running "pattern-graph-cli context --help" Then the output shows the context subcommand usage And the output lists available flags (--session, --related) And the output includes example commands @acceptance-criteria @happy-path Scenario: Dry-run shows pipeline scope - When running "process-api --dry-run status" + When running "pattern-graph-cli --dry-run status" Then the output shows the number of files that would be scanned And the output shows the config file being used And the output shows input glob patterns @@ -139,7 +139,7 @@ Feature: Data API CLI Ergonomics - Performance and Interactive Mode @acceptance-criteria @happy-path Scenario: Validation summary in response metadata Given the pipeline detects 2 dangling references - When running "process-api status" + When running "pattern-graph-cli status" Then the response metadata includes pattern count And the response metadata includes dangling reference count And the response metadata includes any pipeline warnings diff --git a/architect/specs/data-api-context-assembly.feature b/architect/specs/data-api-context-assembly.feature index df7b650b..03168463 100644 --- a/architect/specs/data-api-context-assembly.feature +++ b/architect/specs/data-api-context-assembly.feature @@ -43,10 +43,10 @@ Feature: Data API Context Assembly - One-Command Session Context | Deliverable | Status | Location | Tests | Test Type | | ContextBundle type | complete | src/api/context-assembler.ts | Yes | unit | | Context assembler | complete | src/api/context-assembler.ts | Yes | unit | - | context subcommand | complete | src/cli/process-api.ts | Yes | integration | - | files subcommand | complete | src/cli/process-api.ts | Yes | integration | - | dep-tree subcommand | complete | src/cli/process-api.ts | Yes | integration | - | overview subcommand | complete | src/cli/process-api.ts | Yes | integration | + | context subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | files subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | dep-tree subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | overview subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Context text renderer | complete | src/api/context-formatter.ts | Yes | unit | # ============================================================================ @@ -85,7 +85,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Assemble design session context Given a pattern "AgentLLMIntegration" with dependencies and stubs - When running "process-api context AgentLLMIntegration --session design" + When running "pattern-graph-cli context AgentLLMIntegration --session design" Then the output contains the pattern metadata section And the output contains the spec file path And the output contains dependency stubs with target paths @@ -96,7 +96,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Assemble planning session context Given a pattern "AgentLLMIntegration" with dependencies - When running "process-api context AgentLLMIntegration --session planning" + When running "pattern-graph-cli context AgentLLMIntegration --session planning" Then the output contains pattern metadata and status And the output contains the dependency chain with status And the output does NOT contain stubs or architecture details @@ -105,7 +105,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Assemble implementation session context Given a pattern "ProcessGuardLinter" with completed deliverables - When running "process-api context ProcessGuardLinter --session implement" + When running "pattern-graph-cli context ProcessGuardLinter --session implement" Then the output contains the spec file path And the output contains the deliverables checklist with status And the output contains FSM state and valid transitions @@ -114,7 +114,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @validation Scenario: Context for nonexistent pattern returns error with suggestion Given a pattern "AgentLLMIntegration" exists - When running "process-api context NonExistentPattern --session design" + When running "pattern-graph-cli context NonExistentPattern --session design" Then the command fails with a pattern-not-found error And the error message suggests similar pattern names @@ -145,7 +145,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: File reading list with related patterns Given a pattern "OrderSaga" with uses and usedBy relationships - When running "process-api files OrderSaga --related" + When running "pattern-graph-cli files OrderSaga --related" Then the output lists primary files first And the output lists completed dependency files And the output lists architecture neighbor files @@ -154,14 +154,14 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: File reading list without related patterns Given a pattern "OrderSaga" exists - When running "process-api files OrderSaga" + When running "pattern-graph-cli files OrderSaga" Then the output lists only the primary spec and stub files And no dependency or neighbor files are included @acceptance-criteria @validation Scenario: Files for pattern with no resolvable paths returns minimal output Given a pattern "MinimalPattern" with no stubs or dependencies - When running "process-api files MinimalPattern --related" + When running "pattern-graph-cli files MinimalPattern --related" Then the output lists only the primary spec file And the completed, roadmap, and neighbor sections are empty @@ -193,7 +193,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Dependency tree with status markers Given a dependency chain: A (completed) -> B (completed) -> C (roadmap) - When running "process-api dep-tree C --status" + When running "pattern-graph-cli dep-tree C --status" Then the output shows the tree with completion markers And completed dependencies are marked as such And the focal pattern is highlighted @@ -201,14 +201,14 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Dependency tree with depth limit Given a deep dependency chain with 5 levels - When running "process-api dep-tree C --depth 2" + When running "pattern-graph-cli dep-tree C --depth 2" Then the output shows at most 2 levels of dependencies And truncated branches are indicated @acceptance-criteria @validation Scenario: Dependency tree handles circular dependencies safely Given patterns A depends on B and B depends on A - When running "process-api dep-tree A" + When running "pattern-graph-cli dep-tree A" Then the output shows the cycle without infinite recursion And the visited node is marked to indicate a cycle @@ -231,7 +231,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Multi-pattern context merges dependencies Given patterns "AgentLLM" and "AgentCommand" sharing dependency "AgentBC" - When running "process-api context AgentLLM AgentCommand --session design" + When running "pattern-graph-cli context AgentLLM AgentCommand --session design" Then shared dependencies appear once with a "shared" marker And unique dependencies are listed per pattern And the combined context is smaller than two separate calls @@ -239,7 +239,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @validation Scenario: Multi-pattern context with one invalid name reports error Given a pattern "AgentLLM" exists but "InvalidName" does not - When running "process-api context AgentLLM InvalidName --session design" + When running "pattern-graph-cli context AgentLLM InvalidName --session design" Then the command fails with a pattern-not-found error for "InvalidName" And no partial context is returned @@ -267,7 +267,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @happy-path Scenario: Executive overview Given 36 completed, 3 active, and 30 planned patterns - When running "process-api overview" + When running "pattern-graph-cli overview" Then the output shows "69 patterns (36 completed, 3 active, 30 planned) = 52%" And the output lists active phases with counts And the output shows blocking relationships @@ -275,7 +275,7 @@ Feature: Data API Context Assembly - One-Command Session Context @acceptance-criteria @validation Scenario: Overview with empty pipeline returns zero-state summary Given the pipeline has 0 patterns - When running "process-api overview" + When running "pattern-graph-cli overview" Then the output shows "0 patterns (0 completed, 0 active, 0 planned) = 0%" And the active phases section is empty And the blocking section is empty diff --git a/architect/specs/data-api-output-shaping.feature b/architect/specs/data-api-output-shaping.feature index 355e9c52..632083cd 100644 --- a/architect/specs/data-api-output-shaping.feature +++ b/architect/specs/data-api-output-shaping.feature @@ -39,11 +39,11 @@ Feature: Data API Output Shaping - Compact Output for AI Agents | Deliverable | Status | Location | Tests | Test Type | | summarizePattern() projection | complete | src/api/summarize.ts | Yes | unit | | Output modifier pipeline | complete | src/cli/output-pipeline.ts | Yes | unit | - | QueryResult envelope wiring | complete | src/cli/process-api.ts | Yes | unit | - | list subcommand | complete | src/cli/process-api.ts | Yes | integration | - | search subcommand | complete | src/cli/process-api.ts | Yes | integration | + | QueryResult envelope wiring | complete | src/cli/pattern-graph-cli.ts | Yes | unit | + | list subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | search subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Fuzzy pattern matching | complete | src/api/fuzzy-match.ts | Yes | unit | - | Config file default resolution | complete | src/cli/process-api.ts | Yes | unit | + | Config file default resolution | complete | src/cli/pattern-graph-cli.ts | Yes | unit | | pnpm banner fix | complete | package.json | No | N/A | # ============================================================================ @@ -74,7 +74,7 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: List queries return compact summaries Given patterns exist in the dataset - When running "process-api query getCurrentWork" + When running "pattern-graph-cli query getCurrentWork" Then each pattern in the output contains only summary fields And the output does not contain "directive" or "code" fields And total output size is under 1KB for typical results @@ -82,21 +82,21 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: Full flag returns complete patterns Given patterns exist in the dataset - When running "process-api query getCurrentWork --full" + When running "pattern-graph-cli query getCurrentWork --full" Then each pattern contains all ExtractedPattern fields And the output includes "directive" and "code" fields @acceptance-criteria @happy-path Scenario: Single pattern detail is unaffected Given a pattern "MyPattern" exists - When running "process-api pattern MyPattern" + When running "pattern-graph-cli pattern MyPattern" Then the output contains full pattern detail And the output includes deliverables, dependencies, and relationships @acceptance-criteria @validation Scenario: Full flag combined with names-only is rejected Given patterns exist in the dataset - When running "process-api query getCurrentWork --full --names-only" + When running "pattern-graph-cli query getCurrentWork --full --names-only" Then the command fails with an error about conflicting modifiers And the error message lists the conflicting flags @@ -124,27 +124,27 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: Names-only output for list queries Given 5 patterns exist with status "roadmap" - When running "process-api query getRoadmapItems --names-only" + When running "pattern-graph-cli query getRoadmapItems --names-only" Then the output is a JSON array of 5 strings And each string is a pattern name @acceptance-criteria @happy-path Scenario: Count output for list queries Given 3 active patterns and 5 roadmap patterns - When running "process-api query getCurrentWork --count" + When running "pattern-graph-cli query getCurrentWork --count" Then the output is the integer 3 @acceptance-criteria @happy-path Scenario: Field selection for list queries Given patterns exist in the dataset - When running "process-api query getCurrentWork --fields patternName,status,phase" + When running "pattern-graph-cli query getCurrentWork --fields patternName,status,phase" Then each pattern in the output contains only the requested fields And no other fields are present @acceptance-criteria @validation Scenario: Invalid field name in field selection is rejected Given patterns exist in the dataset - When running "process-api query getCurrentWork --fields patternName,nonExistentField" + When running "pattern-graph-cli query getCurrentWork --fields patternName,nonExistentField" Then the command fails with an error about invalid field names And the error message lists valid field names for the current output mode @@ -174,21 +174,21 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: Successful query returns typed envelope Given patterns exist in the dataset - When running "process-api status" + When running "pattern-graph-cli status" Then the output JSON has "success" set to true And the output JSON has a "data" field with the result And the output JSON has a "metadata" field with pattern count @acceptance-criteria @validation Scenario: Failed query returns error envelope - When running "process-api query nonExistentMethod" + When running "pattern-graph-cli query nonExistentMethod" Then the output JSON has "success" set to false And the output JSON has an "error" field with a message @acceptance-criteria @happy-path Scenario: Compact format strips empty fields Given a pattern with empty arrays and null values - When running "process-api pattern MyPattern" + When running "pattern-graph-cli pattern MyPattern" Then the output does not contain empty arrays And the output does not contain null values And the output does not contain empty strings @@ -222,34 +222,34 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: List with single filter Given patterns with various statuses and categories - When running "process-api list --status active" + When running "pattern-graph-cli list --status active" Then only active patterns are returned And results use the compact summary format @acceptance-criteria @happy-path Scenario: List with composed filters Given patterns with various statuses and categories - When running "process-api list --status roadmap --category projection" + When running "pattern-graph-cli list --status roadmap --category projection" Then only roadmap patterns in the projection category are returned @acceptance-criteria @happy-path Scenario: Search with fuzzy matching Given a pattern named "AgentCommandInfrastructure" - When running "process-api search AgentCommand" + When running "pattern-graph-cli search AgentCommand" Then the result includes "AgentCommandInfrastructure" And results are ranked by match quality @acceptance-criteria @happy-path Scenario: Pagination with limit and offset Given 20 roadmap patterns exist - When running "process-api list --status roadmap --limit 5 --offset 10" + When running "pattern-graph-cli list --status roadmap --limit 5 --offset 10" Then exactly 5 patterns are returned And they start from the 11th pattern @acceptance-criteria @validation Scenario: Search with no results returns empty with suggestion Given patterns exist but none match "zzNonexistent" - When running "process-api search zzNonexistent" + When running "pattern-graph-cli search zzNonexistent" Then the result contains an empty matches array And the output includes a hint that no patterns matched @@ -280,20 +280,20 @@ Feature: Data API Output Shaping - Compact Output for AI Agents @acceptance-criteria @happy-path Scenario: Config file provides default input paths Given a architect.config.ts exists with input and features paths - When running "process-api status" without --input or --features flags + When running "pattern-graph-cli status" without --input or --features flags Then the pipeline uses paths from the config file And the output shows correct pattern counts @acceptance-criteria @validation Scenario: Fuzzy pattern name suggestion on not-found Given a pattern "AgentCommandInfrastructure" exists - When running "process-api pattern AgentCommand" + When running "pattern-graph-cli pattern AgentCommand" Then the error message includes "Did you mean: AgentCommandInfrastructure?" @acceptance-criteria @validation Scenario: Empty result provides contextual hint Given no patterns have status "active" And 3 patterns have status "roadmap" - When running "process-api list --status active" + When running "pattern-graph-cli list --status active" Then the output includes a hint about roadmap patterns And the hint suggests "Try: list --status roadmap" diff --git a/architect/specs/data-api-platform-integration.feature b/architect/specs/data-api-platform-integration.feature index eb12ac4b..c7ee23a8 100644 --- a/architect/specs/data-api-platform-integration.feature +++ b/architect/specs/data-api-platform-integration.feature @@ -10,7 +10,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support **Problem:** - The process-api CLI requires subprocess invocation for every query, adding + The pattern-graph-cli CLI requires subprocess invocation for every query, adding shell overhead and preventing stateful interaction. Claude Code's native tool integration mechanism is Model Context Protocol (MCP), which the process API does not support. Additionally, in the monorepo context, queries must specify @@ -46,7 +46,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support | MCP session state management | superseded | src/mcp/session.ts | Yes | unit | | CLAUDE.md context layer generator | superseded | src/generators/claude-md-generator.ts | Yes | unit | | Cross-package dependency analyzer | superseded | src/api/cross-package.ts | Yes | unit | - | Package-scoped filter flag | superseded | src/cli/process-api.ts | Yes | integration | + | Package-scoped filter flag | superseded | src/cli/pattern-graph-cli.ts | Yes | integration | | Multi-package config support | superseded | src/config/multi-package.ts | Yes | unit | | Per-package coverage report | superseded | src/api/coverage-analyzer.ts | Yes | unit | @@ -121,7 +121,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support @acceptance-criteria @happy-path Scenario: Generate CLAUDE.md context layer for bounded context Given annotated patterns in the "orders" bounded context - When running "process-api generate-context-layer --context orders" + When running "pattern-graph-cli generate-context-layer --context orders" Then a CLAUDE.md section is generated with pattern metadata And the section includes relationship summaries And the section includes a file reading list @@ -136,7 +136,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support @acceptance-criteria @edge-case Scenario: Context layer for bounded context with no annotations Given a bounded context directory with no @architect annotations - When running "process-api generate-context-layer --context empty-context" + When running "pattern-graph-cli generate-context-layer --context empty-context" Then the output indicates no patterns found in the context And the CLAUDE.md section contains a placeholder with discovery guidance @@ -160,21 +160,21 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support @acceptance-criteria @happy-path Scenario: Cross-package dependency view Given patterns across "platform-core" and "platform-bc" packages - When running "process-api cross-package" + When running "pattern-graph-cli cross-package" Then the output shows which packages depend on which patterns And completed vs roadmap dependencies are distinguished @acceptance-criteria @happy-path Scenario: Package-scoped query filtering Given patterns from multiple packages in the dataset - When running "process-api list --package platform-core --status active" + When running "pattern-graph-cli list --package platform-core --status active" Then only patterns from "platform-core" are returned And the package filter composes with other filters @acceptance-criteria @edge-case Scenario: Query for non-existent package returns empty result Given patterns from "platform-core" and "platform-bc" packages - When running "process-api list --package non-existent-package" + When running "pattern-graph-cli list --package non-existent-package" Then the output is an empty result set And no error is raised @@ -203,7 +203,7 @@ Feature: Data API Platform Integration - MCP Server and Monorepo Support @acceptance-criteria @happy-path Scenario: Watch mode re-generates on file change - Given watch mode is running with "process-api watch --generate architecture" + Given watch mode is running with "pattern-graph-cli watch --generate architecture" When a source file is modified Then the architecture docs are regenerated automatically And only affected doc sections are updated diff --git a/architect/specs/data-api-relationship-graph.feature b/architect/specs/data-api-relationship-graph.feature index 4590f8fd..a5583cf4 100644 --- a/architect/specs/data-api-relationship-graph.feature +++ b/architect/specs/data-api-relationship-graph.feature @@ -41,7 +41,7 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | | Graph traversal engine | pending | src/api/graph-traversal.ts | Yes | unit | - | graph subcommand | pending | src/cli/process-api.ts | Yes | integration | + | graph subcommand | pending | src/cli/pattern-graph-cli.ts | Yes | integration | | Impact analysis | pending | src/api/graph-traversal.ts | Yes | unit | | Path finding algorithm | pending | src/api/graph-traversal.ts | Yes | unit | | Dangling reference detector | pending | src/api/graph-health.ts | Yes | unit | @@ -67,14 +67,14 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis @acceptance-criteria @happy-path Scenario: Recursive graph traversal Given a chain: A -> B -> C -> D with uses relationships - When running "process-api graph A --depth 3 --direction down" + When running "pattern-graph-cli graph A --depth 3 --direction down" Then the output shows A -> B -> C -> D as a tree And each node shows its status and phase @acceptance-criteria @happy-path Scenario: Bidirectional traversal with depth limit Given a pattern "C" in the middle of a chain - When running "process-api graph C --depth 1 --direction both" + When running "pattern-graph-cli graph C --depth 1 --direction both" Then the output shows direct parents (1 up) and direct children (1 down) And deeper relationships are not included @@ -96,14 +96,14 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis @acceptance-criteria @happy-path Scenario: Impact analysis shows transitive dependents Given "EventStore" is used by "Saga" which is used by "Orchestrator" - When running "process-api graph impact EventStore" + When running "pattern-graph-cli graph impact EventStore" Then the output shows "Saga" and "Orchestrator" as affected And the output shows the chain of impact @acceptance-criteria @happy-path Scenario: Impact analysis for leaf pattern Given a pattern with no usedBy or enables relationships - When running "process-api graph impact LeafPattern" + When running "pattern-graph-cli graph impact LeafPattern" Then the output indicates no downstream impact # ============================================================================ @@ -126,14 +126,14 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis @acceptance-criteria @happy-path Scenario: Find path between connected patterns Given a chain: EventStore -> Saga -> Orchestrator -> Workflow - When running "process-api graph path EventStore Workflow" + When running "pattern-graph-cli graph path EventStore Workflow" Then the output shows the chain: EventStore -> Saga -> Orchestrator -> Workflow And each hop shows the relationship type @acceptance-criteria @edge-case Scenario: No path between disconnected patterns Given "PatternA" and "PatternZ" with no connecting relationships - When running "process-api graph path PatternA PatternZ" + When running "pattern-graph-cli graph path PatternA PatternZ" Then the output indicates no path exists between the patterns # ============================================================================ @@ -156,21 +156,21 @@ Feature: Data API Relationship Graph - Deep Dependency Analysis @acceptance-criteria @happy-path Scenario: Detect dangling references Given a pattern with uses "NonExistentPattern" - When running "process-api graph dangling" + When running "pattern-graph-cli graph dangling" Then the output includes the broken reference And the output shows which pattern references it @acceptance-criteria @happy-path Scenario: Detect orphan patterns Given a pattern with no uses, usedBy, dependsOn, or enables - When running "process-api graph orphans" + When running "pattern-graph-cli graph orphans" Then the output includes the isolated pattern And the output suggests adding relationship tags @acceptance-criteria @happy-path Scenario: Show blocking chains Given patterns blocked by incomplete dependencies - When running "process-api graph blocking" + When running "pattern-graph-cli graph blocking" Then the output shows each blocked pattern with its blocker And the output shows the chain from blocker to blocked And completed dependencies are excluded from the blocked list diff --git a/architect/specs/data-api-session-support.feature b/architect/specs/data-api-session-support.feature index f52265e8..39c8a617 100644 --- a/architect/specs/data-api-session-support.feature +++ b/architect/specs/data-api-session-support.feature @@ -42,9 +42,9 @@ Feature: Data API Design Session Support - Automated Session Workflows Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | | Scope validation logic | complete | src/api/scope-validator.ts | Yes | unit | - | scope-validate subcommand | complete | src/cli/process-api.ts | Yes | integration | + | scope-validate subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Handoff document generator | complete | src/api/handoff-generator.ts | Yes | unit | - | handoff subcommand | complete | src/cli/process-api.ts | Yes | integration | + | handoff subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | # ============================================================================ # RULE 1: Scope Validation @@ -75,14 +75,14 @@ Feature: Data API Design Session Support - Automated Session Workflows @acceptance-criteria @happy-path Scenario: All scope validation checks pass Given a pattern with all prerequisites met - When running "process-api scope-validate MyPattern --type implement" + When running "pattern-graph-cli scope-validate MyPattern --type implement" Then all checklist items show green/passing And the output indicates "Ready for implementation session" @acceptance-criteria @validation Scenario: Dependency blocker detected Given a pattern "X" depending on "Y" with status "roadmap" - When running "process-api scope-validate X --type implement" + When running "pattern-graph-cli scope-validate X --type implement" Then the dependencies check shows "BLOCKED" And the output identifies "Y (roadmap)" as the blocker And the output suggests "Complete Y first or change session type to design" @@ -90,7 +90,7 @@ Feature: Data API Design Session Support - Automated Session Workflows @acceptance-criteria @validation Scenario: FSM transition blocker detected Given a pattern with status "completed" - When running "process-api scope-validate CompletedPattern --type implement" + When running "pattern-graph-cli scope-validate CompletedPattern --type implement" Then the FSM check shows "BLOCKED" And the output indicates transition to active is not valid from completed @@ -124,7 +124,7 @@ Feature: Data API Design Session Support - Automated Session Workflows @acceptance-criteria @happy-path Scenario: Generate handoff for in-progress pattern Given an active pattern with 3 completed and 2 remaining deliverables - When running "process-api handoff --pattern MyPattern" + When running "pattern-graph-cli handoff --pattern MyPattern" Then the output shows the session summary And the output lists 3 completed deliverables And the output lists 2 remaining deliverables as next priorities @@ -133,7 +133,7 @@ Feature: Data API Design Session Support - Automated Session Workflows @acceptance-criteria @happy-path Scenario: Handoff captures discovered items Given a pattern with discovery tags in feature file comments - When running "process-api handoff --pattern MyPattern" + When running "pattern-graph-cli handoff --pattern MyPattern" Then the output includes discovered gaps And the output includes discovered improvements And the output includes discovered learnings diff --git a/architect/specs/data-api-stub-integration.feature b/architect/specs/data-api-stub-integration.feature index 1b4e4c68..eaca53e6 100644 --- a/architect/specs/data-api-stub-integration.feature +++ b/architect/specs/data-api-stub-integration.feature @@ -46,9 +46,9 @@ Feature: Data API Stub Integration - Unlocking Design Session Data | Scan path configuration (pre-existing) | complete | package.json | No | N/A | | @architect-target taxonomy tag | complete | src/taxonomy/registry-builder.ts | Yes | unit | | @architect-since taxonomy tag | complete | src/taxonomy/registry-builder.ts | Yes | unit | - | stubs subcommand | complete | src/cli/process-api.ts | Yes | integration | - | decisions subcommand | complete | src/cli/process-api.ts | Yes | integration | - | pdr subcommand | complete | src/cli/process-api.ts | Yes | integration | + | stubs subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | decisions subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | pdr subcommand | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Stub-to-implementation resolver | complete | src/api/stub-resolver.ts | Yes | unit | # ============================================================================ @@ -122,7 +122,7 @@ Feature: Data API Stub Integration - Unlocking Design Session Data @acceptance-criteria @happy-path Scenario: List all stubs with implementation status Given stubs exist for 4 patterns with targets - When running "process-api stubs" + When running "pattern-graph-cli stubs" Then the output lists each stub with its target path And each stub shows whether the target file exists And stubs are grouped by parent pattern @@ -130,20 +130,20 @@ Feature: Data API Stub Integration - Unlocking Design Session Data @acceptance-criteria @happy-path Scenario: List stubs for a specific pattern Given 5 stubs implement "AgentCommandInfrastructure" - When running "process-api stubs AgentCommandInfrastructure" + When running "pattern-graph-cli stubs AgentCommandInfrastructure" Then only stubs for that pattern are returned And each stub shows target, session, and implementation status @acceptance-criteria @happy-path Scenario: Filter unresolved stubs Given 3 stubs with existing targets and 2 without - When running "process-api stubs --unresolved" + When running "pattern-graph-cli stubs --unresolved" Then only the 2 stubs without existing target files are returned @acceptance-criteria @validation Scenario: Stubs for nonexistent pattern returns empty result Given no stubs implement "NonExistentPattern" - When running "process-api stubs NonExistentPattern" + When running "pattern-graph-cli stubs NonExistentPattern" Then the result is empty And the error message suggests checking the pattern name @@ -185,7 +185,7 @@ Feature: Data API Stub Integration - Unlocking Design Session Data @acceptance-criteria @happy-path Scenario: Query design decisions for a pattern Given stubs for "AgentCommandInfrastructure" with AD-N items - When running "process-api decisions AgentCommandInfrastructure" + When running "pattern-graph-cli decisions AgentCommandInfrastructure" Then the output lists each AD-N decision with its description And the output shows referenced PDR numbers And the output shows the source design session @@ -193,7 +193,7 @@ Feature: Data API Stub Integration - Unlocking Design Session Data @acceptance-criteria @happy-path Scenario: Cross-reference a PDR number Given patterns and stubs referencing "PDR-012" - When running "process-api pdr 012" + When running "pattern-graph-cli pdr 012" Then the output lists all patterns referencing PDR-012 And the output shows the decision feature file location And the output shows stub count per pattern @@ -201,6 +201,6 @@ Feature: Data API Stub Integration - Unlocking Design Session Data @acceptance-criteria @validation Scenario: PDR query for nonexistent number returns empty Given no patterns or stubs reference "PDR-999" - When running "process-api pdr 999" + When running "pattern-graph-cli pdr 999" Then the result indicates no references found And the output includes "No patterns reference PDR-999" diff --git a/architect/specs/design-review-generation.feature b/architect/specs/design-review-generation.feature index ff27087f..736be9b5 100644 --- a/architect/specs/design-review-generation.feature +++ b/architect/specs/design-review-generation.feature @@ -32,7 +32,7 @@ Feature: Design Review Diagram Generation | BusinessRule errorScenarioNames | complete | src/validation-schemas/extracted-pattern.ts | | DesignReviewCodec | complete | src/renderable/codecs/design-review.ts | | Design review generator | complete | src/generators/built-in/design-review-generator.ts | - | Process API sequence subcommand | complete | src/cli/process-api.ts | + | Process API sequence subcommand | complete | src/cli/pattern-graph-cli.ts | | Config wiring | complete | architect.config.ts | Rule: SequenceIndex pre-computes ordered steps from rule-level tags diff --git a/architect/specs/mcp-server-integration.feature b/architect/specs/mcp-server-integration.feature index 03e600d8..d71bce79 100644 --- a/architect/specs/mcp-server-integration.feature +++ b/architect/specs/mcp-server-integration.feature @@ -12,7 +12,7 @@ Feature: MCP Server Integration **Problem:** - Claude Code accesses PatternGraphAPI through subprocess calls to the process-api + Claude Code accesses PatternGraphAPI through subprocess calls to the pattern-graph-cli CLI. Each invocation runs the full 8-step pipeline (config, scan, extract, merge, hierarchy, workflow, transform, validate), taking 2-5 seconds. During a typical session with 10-20 queries, this adds 30-90 seconds of pure pipeline overhead. diff --git a/architect/specs/monorepo-support.feature b/architect/specs/monorepo-support.feature index b448e51f..b4b98325 100644 --- a/architect/specs/monorepo-support.feature +++ b/architect/specs/monorepo-support.feature @@ -112,13 +112,13 @@ Feature: Monorepo Cross-Package Support @acceptance-criteria @happy-path Scenario: Package filter returns only matching patterns Given patterns from "platform-core" and "platform-bc" in the dataset - When running "process-api list --package platform-core" + When running "pattern-graph-cli list --package platform-core" Then only patterns with package "platform-core" are returned @acceptance-criteria @happy-path Scenario: Package filter composes with status filter Given active and roadmap patterns in both packages - When running "process-api list --package platform-core --status active" + When running "pattern-graph-cli list --package platform-core --status active" Then only active patterns from "platform-core" are returned Rule: Cross-package dependencies are visible as a package-level graph @@ -137,13 +137,13 @@ Feature: Monorepo Cross-Package Support @acceptance-criteria @happy-path Scenario: Cross-package dependency view shows package edges Given "OrderHandler" in "platform-bc" uses "EventStore" in "platform-core" - When running "process-api cross-package" + When running "pattern-graph-cli cross-package" Then the output shows platform-bc depends on platform-core @acceptance-criteria @edge-case Scenario: Intra-package dependencies are excluded Given "Scanner" uses "ASTParser" and both are in "platform-core" - When running "process-api cross-package" + When running "pattern-graph-cli cross-package" Then no self-referencing edge for platform-core appears Rule: Coverage analysis reports annotation completeness per package @@ -161,11 +161,11 @@ Feature: Monorepo Cross-Package Support @acceptance-criteria @happy-path Scenario: Coverage report includes per-package breakdown Given a multi-package config with two packages - When running "process-api arch coverage" + When running "pattern-graph-cli arch coverage" Then the report shows per-package coverage with annotated counts and percentages @acceptance-criteria @edge-case Scenario: Single-package config shows flat coverage report Given a config with no packages field - When running "process-api arch coverage" + When running "pattern-graph-cli arch coverage" Then the report shows a single aggregate coverage number diff --git a/architect/specs/orchestrator-pipeline-factory-migration.feature b/architect/specs/orchestrator-pipeline-factory-migration.feature index 983ac5a5..f8ac34d2 100644 --- a/architect/specs/orchestrator-pipeline-factory-migration.feature +++ b/architect/specs/orchestrator-pipeline-factory-migration.feature @@ -15,7 +15,7 @@ Feature: Orchestrator Pipeline Factory Migration `orchestrator.ts` is the last feature consumer that wires the 8-step scan-extract-merge-transform pipeline inline (lines 282-427). This is the Parallel Pipeline anti-pattern identified in ADR-006. The shared - pipeline factory in `build-pipeline.ts` already serves `process-api.ts` + pipeline factory in `build-pipeline.ts` already serves `pattern-graph-cli.ts` and `validate-patterns.ts`, but the orchestrator — the original pipeline host — was deferred (ProcessAPILayeredExtraction DD-3) because it collects structured warnings (scan errors with file details, extraction @@ -72,7 +72,7 @@ Feature: Orchestrator Pipeline Factory Migration `GenerationWarning` in a thin adapter — `'gherkin-parse'` maps to `'scan'`, and generator-level warning types (`'overwrite-skipped'`, `'config'`, `'cleanup'`) are produced by the orchestrator itself, not - the pipeline. Existing consumers (process-api, validate-patterns) that + the pipeline. Existing consumers (pattern-graph-cli, validate-patterns) that ignore warnings or use flat strings are unaffected — they can read `.message` only. @@ -86,7 +86,7 @@ Feature: Orchestrator Pipeline Factory Migration DD-3: Pipeline factory gains an includeValidation option. The orchestrator calls `transformToPatternGraph` (no validation), - while process-api calls `transformToPatternGraphWithValidation`. + while pattern-graph-cli calls `transformToPatternGraphWithValidation`. The factory already calls the validation variant. Adding `includeValidation?: boolean` (default true) lets the orchestrator opt out, since doc generation doesn't need validation summaries. @@ -114,7 +114,7 @@ Feature: Orchestrator Pipeline Factory Migration failures are always fatal. For partial failures (individual files with parse errors within an otherwise successful scan), the new `failOnScanErrors?: boolean` option controls behavior. When true - (default for process-api), partial scan errors produce `Result.err`. + (default for pattern-graph-cli), partial scan errors produce `Result.err`. When false (orchestrator), partial errors are captured in `PipelineResult.warnings` as structured `PipelineWarning` objects and the pipeline continues with successfully scanned files. @@ -130,7 +130,7 @@ Feature: Orchestrator Pipeline Factory Migration patterns array for `GenerateResult.patterns` and generator context is `dataset.patterns` from the PatternGraph. - DD-7: validate-patterns.ts and process-api.ts are unaffected. + DD-7: validate-patterns.ts and pattern-graph-cli.ts are unaffected. They already consume the factory. The only change they see is `PipelineResult.warnings` widening from `readonly string[]` to `readonly PipelineWarning[]`, which is backward-compatible (they @@ -164,7 +164,7 @@ Feature: Orchestrator Pipeline Factory Migration - Generator dispatch, file writing, PR-changes detection (orchestrator core) - Session cleanup, generateFromConfig, groupGenerators (orchestrator utilities) - generate-docs CLI (calls generateDocumentation unchanged) - - process-api.ts, validate-patterns.ts (already migrated) + - pattern-graph-cli.ts, validate-patterns.ts (already migrated) - Existing test scenarios for orchestrator (same observable behavior) Background: Deliverables @@ -205,7 +205,7 @@ Feature: Orchestrator Pipeline Factory Migration @acceptance-criteria Scenario: Factory is sole pipeline definition - Given the three CLI consumers: process-api, validate-patterns, orchestrator + Given the three CLI consumers: pattern-graph-cli, validate-patterns, orchestrator When each needs a PatternGraph Then each calls buildPatternGraph from build-pipeline.ts And no consumer wires the 8-step pipeline inline @@ -246,7 +246,7 @@ Feature: Orchestrator Pipeline Factory Migration objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers - that need simple messages (process-api) read `.message` only. + that need simple messages (pattern-graph-cli) read `.message` only. **Rationale:** The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured @@ -267,7 +267,7 @@ Feature: Orchestrator Pipeline Factory Migration @acceptance-criteria Scenario: Existing consumers unaffected - Given process-api.ts and validate-patterns.ts consuming the factory + Given pattern-graph-cli.ts and validate-patterns.ts consuming the factory When PipelineResult.warnings changes from string[] to PipelineWarning[] Then both consumers compile without changes And runtime behavior is unchanged @@ -281,7 +281,7 @@ Feature: Orchestrator Pipeline Factory Migration **Rationale:** The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable - files even if some files have syntax errors. The process-api treats + files even if some files have syntax errors. The pattern-graph-cli treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration. diff --git a/architect/specs/pattern-graph-api-cli.feature b/architect/specs/pattern-graph-api-cli.feature index 020b7b51..9a7a2e47 100644 --- a/architect/specs/pattern-graph-api-cli.feature +++ b/architect/specs/pattern-graph-api-cli.feature @@ -39,9 +39,9 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | process:query CLI command | complete | src/cli/process-api.ts | Yes | integration | - | CLI argument parser | complete | src/cli/process-api.ts | Yes | integration | - | JSON output formatter | complete | src/cli/process-api.ts | Yes | integration | + | process:query CLI command | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | CLI argument parser | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | JSON output formatter | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Text output formatter | n/a | N/A | No | N/A | | Root package.json script | complete | package.json | No | N/A | | CLAUDE.md documentation update | complete | CLAUDE.md | No | N/A | diff --git a/architect/specs/process-api-layered-extraction.feature b/architect/specs/pattern-graph-layered-extraction.feature similarity index 90% rename from architect/specs/process-api-layered-extraction.feature rename to architect/specs/pattern-graph-layered-extraction.feature index a2c14bcd..8eb2a406 100644 --- a/architect/specs/process-api-layered-extraction.feature +++ b/architect/specs/pattern-graph-layered-extraction.feature @@ -7,12 +7,12 @@ @architect-product-area:DataAPI @architect-include:process-workflow @architect-depends-on:ValidatorReadModelConsolidation -@architect-business-value:separate-cli-shell-from-domain-logic-in-process-api +@architect-business-value:separate-cli-shell-from-domain-logic-in-pattern-graph-cli @architect-priority:high Feature: Process API Layered Extraction **Problem:** - `process-api.ts` is 1,700 lines containing two remaining architectural + `pattern-graph-cli.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. **Parallel Pipeline**: `buildPipeline()` (lines 488-561) wires the @@ -28,7 +28,7 @@ Feature: Process API Layered Extraction API layer, not the CLI file. Most subcommand handlers already delegate correctly. Of the 16 handlers - in process-api.ts, 13 are thin wrappers over `src/api/` modules: + in pattern-graph-cli.ts, 13 are thin wrappers over `src/api/` modules: | Handler | Delegates To | | handleStatus | PatternGraphAPI methods | @@ -68,7 +68,7 @@ Feature: Process API Layered Extraction Location: `src/generators/pipeline/build-pipeline.ts`, re-exported from `src/generators/pipeline/index.ts`. The factory returns `Result` so each consumer can map errors - to its own strategy (process-api calls `process.exit(1)`, + to its own strategy (pattern-graph-cli calls `process.exit(1)`, validate-patterns throws, orchestrator returns `Result.err()`). `PipelineResult` contains `{ dataset: RuntimePatternGraph, validation: ValidationSummary }`. The `TagRegistry` is accessible via @@ -76,7 +76,7 @@ Feature: Process API Layered Extraction DD-2: Merge conflict strategy as a pipeline option. The factory accepts `mergeConflictStrategy: 'fatal' | 'concatenate'`. - `'fatal'` returns `Result.err()` on conflicts (process-api behavior). + `'fatal'` returns `Result.err()` on conflicts (pattern-graph-cli behavior). `'concatenate'` falls back to `[...ts, ...gherkin]` (validate-patterns behavior per DD-1 in ValidatorReadModelConsolidation). This is the most significant semantic difference between consumers. @@ -88,7 +88,7 @@ Feature: Process API Layered Extraction orchestrator has 155 lines of pipeline with structured warning collection (scan errors, extraction errors, Gherkin parse errors as `GenerationWarning[]`). Integrating this into the factory adds risk to a - first extraction. This spec migrates process-api.ts and + first extraction. This spec migrates pattern-graph-cli.ts and validate-patterns.ts only. DD-4: handleRules domain logic extracts to `src/api/rules-query.ts`. @@ -127,7 +127,7 @@ Feature: Process API Layered Extraction placement on raw scanned files). DD-8: Line count invariant replaced with qualitative criterion. - The original 500-line target for process-api.ts is unrealistic. After + The original 500-line target for pattern-graph-cli.ts is unrealistic. After extracting buildPipeline (74 lines) and handleRules (184 lines), the file is ~1,400 lines. The remaining code is legitimate CLI responsibility: parseArgs (134), showHelp (143), routeSubcommand (96), main (59), 13 thin @@ -142,11 +142,11 @@ Feature: Process API Layered Extraction | Step | What | Verification | | 1 | Create src/generators/pipeline/build-pipeline.ts with PipelineOptions and factory | pnpm typecheck | | 2 | Export from src/generators/pipeline/index.ts barrel | pnpm typecheck | - | 3 | Migrate process-api.ts buildPipeline to factory call | pnpm typecheck, pnpm process:query -- overview | - | 4 | Remove unused scanner/extractor imports from process-api.ts | pnpm lint | + | 3 | Migrate pattern-graph-cli.ts buildPipeline to factory call | pnpm typecheck, pnpm process:query -- overview | + | 4 | Remove unused scanner/extractor imports from pattern-graph-cli.ts | pnpm lint | | 5 | Migrate validate-patterns.ts PatternGraph pipeline to factory call | pnpm validate:patterns (0 errors, 0 warnings) | | 6 | Create src/api/rules-query.ts with queryBusinessRules | pnpm typecheck | - | 7 | Slim handleRules in process-api.ts to thin delegation | pnpm process:query -- rules | + | 7 | Slim handleRules in pattern-graph-cli.ts to thin delegation | pnpm process:query -- rules | | 8 | Export from src/api/index.ts barrel | pnpm typecheck | | 9 | Full verification | pnpm build, pnpm test, pnpm lint, pnpm validate:patterns | @@ -157,7 +157,7 @@ Feature: Process API Layered Extraction | src/generators/pipeline/index.ts | Add re-export of build-pipeline | +2 | | src/api/rules-query.ts | NEW: business rules query from handleRules | +~200 | | src/api/index.ts | Add re-exports for rules-query | +5 | - | src/cli/process-api.ts | Replace buildPipeline + handleRules with delegations | -~280 net | + | src/cli/pattern-graph-cli.ts | Replace buildPipeline + handleRules with delegations | -~280 net | | src/cli/validate-patterns.ts | Replace PatternGraph pipeline with factory call | -~30 net | **What does NOT change:** @@ -175,7 +175,7 @@ Feature: Process API Layered Extraction Given the following deliverables: | Deliverable | Status | Location | | Create shared pipeline factory | complete | src/generators/pipeline/build-pipeline.ts | - | process-api.ts consumes pipeline factory | complete | src/cli/process-api.ts | + | pattern-graph-cli.ts consumes pipeline factory | complete | src/cli/pattern-graph-cli.ts | | validate-patterns.ts consumes pipeline factory (PatternGraph only) | complete | src/cli/validate-patterns.ts | | Extract handleRules to rules-query.ts | complete | src/api/rules-query.ts | | Update barrel exports | complete | src/api/index.ts, src/generators/pipeline/index.ts | @@ -183,7 +183,7 @@ Feature: Process API Layered Extraction Rule: CLI file contains only routing, no domain logic - **Invariant:** `process-api.ts` parses arguments, calls the pipeline + **Invariant:** `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()` @@ -198,7 +198,7 @@ Feature: Process API Layered Extraction @acceptance-criteria Scenario: No domain data structures in handlers - Given the refactored process-api.ts + Given the refactored pattern-graph-cli.ts When inspecting handler functions Then no Map or Set construction exists for domain data grouping And no imports from renderable/codecs/ exist in the CLI file @@ -210,7 +210,7 @@ Feature: Process API Layered Extraction When extracted to src/api/rules-query.ts Then the CLI handler parses filters, calls queryBusinessRules, and formats output And the queryBusinessRules function is a pure function taking RuntimePatternGraph - And the nested Map construction lives in rules-query.ts, not process-api.ts + And the nested Map construction lives in rules-query.ts, not pattern-graph-cli.ts Rule: Pipeline factory is shared across CLI consumers @@ -220,7 +220,7 @@ Feature: Process API Layered Extraction independently. The factory accepts `mergeConflictStrategy` to handle behavioral differences between consumers. - **Rationale:** Three consumers (process-api, validate-patterns, + **Rationale:** Three consumers (pattern-graph-cli, validate-patterns, orchestrator) independently wire the same 8-step sequence: loadConfig, scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin, mergePatterns, computeHierarchyChildren, @@ -232,10 +232,10 @@ Feature: Process API Layered Extraction @acceptance-criteria Scenario: CLI consumers use factory - Given process-api.ts and validate-patterns.ts + Given pattern-graph-cli.ts and validate-patterns.ts When each needs a PatternGraph Then each calls the shared pipeline factory from build-pipeline.ts - And process-api.ts does not import from scanner/ or extractor/ + And pattern-graph-cli.ts does not import from scanner/ or extractor/ And validate-patterns.ts uses the factory for PatternGraph but retains direct scans for DoD and anti-patterns @acceptance-criteria @@ -257,7 +257,7 @@ Feature: Process API Layered Extraction **Rationale:** `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. + 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.). @@ -273,7 +273,7 @@ Feature: Process API Layered Extraction @acceptance-criteria Scenario: handleRules slim wrapper - Given the refactored handleRules in process-api.ts + Given the refactored handleRules in pattern-graph-cli.ts When inspecting the function Then it parses filters from CLI sub-args And calls queryBusinessRules for the domain result @@ -284,11 +284,11 @@ Feature: Process API Layered Extraction **Invariant:** The factory returns `Result` rather than throwing or calling `process.exit()`. Each consumer maps the - error to its own strategy: process-api.ts calls `process.exit(1)`, + error to its own strategy: pattern-graph-cli.ts calls `process.exit(1)`, validate-patterns.ts throws, and orchestrator.ts (future) returns `Result.err()`. - **Rationale:** The current `buildPipeline()` in process-api.ts calls + **Rationale:** 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 diff --git a/architect/specs/setup-command.feature b/architect/specs/setup-command.feature index aa617e6f..78c4bd7a 100644 --- a/architect/specs/setup-command.feature +++ b/architect/specs/setup-command.feature @@ -168,7 +168,7 @@ Feature: Interactive Setup Command @architect-sequence-module:augment-package-json Rule: Npm scripts are injected using bin command names - **Invariant:** Injected scripts reference bin names (process-api, generate-docs) + **Invariant:** Injected scripts reference bin names (pattern-graph-cli, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via --esm flag. @@ -187,7 +187,7 @@ Feature: Interactive Setup Command Scenario: Injected scripts use bin command names Given a package.json with no Architect scripts When the init command injects scripts - Then package.json contains process:query using "process-api" + Then package.json contains process:query using "pattern-graph-cli" And contains docs:all using "generate-docs" And preserves the existing "type" field @@ -219,14 +219,14 @@ Feature: Interactive Setup Command @acceptance-criteria @happy-path Scenario: Example annotation file is detected by the pipeline Given the init command generated an example annotated file - When running process-api overview + When running pattern-graph-cli overview Then the output shows 1 pattern detected @architect-sequence-step:6 @architect-sequence-module:validate-setup Rule: Init validates the complete setup by running the pipeline - **Invariant:** After all files are generated, init runs process-api overview and + **Invariant:** After all files are generated, init runs pattern-graph-cli overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information. diff --git a/architect/specs/validator-read-model-consolidation.feature b/architect/specs/validator-read-model-consolidation.feature index 8c1e5b37..fdc11bbe 100644 --- a/architect/specs/validator-read-model-consolidation.feature +++ b/architect/specs/validator-read-model-consolidation.feature @@ -60,9 +60,9 @@ Feature: Validator Read Model Consolidation **Design Decisions:** - DD-1: Reuse the same pipeline as process-api.ts — not a shared factory yet. + DD-1: Reuse the same pipeline as pattern-graph-cli.ts — not a shared factory yet. The validator will wire scan-extract-merge-transform inline, mirroring - how process-api.ts does it today (lines 490-558). Extracting a shared + how pattern-graph-cli.ts does it today (lines 490-558). Extracting a shared pipeline factory is scoped to ProcessAPILayeredExtraction, not this spec. This keeps the refactoring focused on data-access only. @@ -79,7 +79,7 @@ Feature: Validator Read Model Consolidation DD-4: The validator will import transformToPatternGraphWithValidation from generators/pipeline/index.js, plus the merge and hierarchy helpers - already used by process-api.ts. This is a temporary parallel pipeline + already used by pattern-graph-cli.ts. This is a temporary parallel pipeline (acknowledged) that will be replaced when the pipeline factory exists. DD-5: Phase tag removal from utility patterns is a separate atomic step diff --git a/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts b/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts index 7b00ee43..0a3ca5b2 100644 --- a/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts +++ b/architect/stubs/DataAPIDesignSessionSupport/handoff-generator.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIDesignSessionSupport * @architect-uses PatternGraphAPI, PatternGraph, ContextFormatterImpl - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/handoff-generator.ts * @architect-since DS-E * diff --git a/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts b/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts index cf0b32b8..5797da1b 100644 --- a/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts +++ b/architect/stubs/DataAPIDesignSessionSupport/scope-validator.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIDesignSessionSupport * @architect-uses PatternGraphAPI, PatternGraph, StubResolver - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/scope-validator.ts * @architect-since DS-E * diff --git a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts index cebc4983..349ef5ff 100644 --- a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts +++ b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts @@ -7,7 +7,7 @@ * ## CliRecipeGenerator — Standalone Generator for CLI Recipes and Narratives * * Produces `docs-live/reference/PROCESS-API-RECIPES.md` from the declarative - * CLI schema. Sibling to `ProcessApiReferenceGenerator` — both implement + * CLI schema. Sibling to `CliReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends * on PatternGraph (ADR-006 compliant). * @@ -16,7 +16,7 @@ * different cadences. Reference tables change when CLI flags are added or * removed. Recipes change when workflow recommendations evolve. Coupling * them in one generator would force both to change together. - * `ProcessApiReferenceGenerator` is already completed and tested (Phase 43) — + * `CliReferenceGenerator` is already completed and tested (Phase 43) — * extending it risks regressions. Two small standalone generators are easier * to test and maintain than one large one. * @@ -181,7 +181,7 @@ function buildRecipeDocument( // // // 1. Auto-generation notice // sections.push(paragraph( - // '> Auto-generated from CLI schema. See [CLI Reference](./PROCESS-API-REFERENCE.md) for flag tables.' + // '> Auto-generated from CLI schema. See [CLI Reference](./CLI-REFERENCE.md) for flag tables.' // )); // // // 2. Preamble (editorial prose) @@ -239,14 +239,14 @@ export interface CliRecipeGeneratorConfig { /** * Standalone generator producing PROCESS-API-RECIPES.md from CLI schema. * - * Follows the same pattern as ProcessApiReferenceGenerator: + * Follows the same pattern as CliReferenceGenerator: * - Implements DocumentGenerator interface * - Consumes CLI_SCHEMA directly (no PatternGraph dependency) * - Returns OutputFile[] via standard orchestrator write path * - Registered in architect.config.ts generatorOverrides * - * Key difference from ProcessApiReferenceGenerator: - * - ProcessApiReferenceGenerator reads CLIOptionGroup → produces flag tables + * Key difference from CliReferenceGenerator: + * - CliReferenceGenerator reads CLIOptionGroup → produces flag tables * - CliRecipeGenerator reads RecipeGroup[] + CommandNarrativeGroup[] → produces recipes * - Both read from the same CLI_SCHEMA constant */ @@ -296,7 +296,7 @@ export function createCliRecipeGenerator( /** * Registration follows the programmatic pattern from codec-generators.ts. - * The generator is registered similarly to createProcessApiReferenceGenerator(). + * The generator is registered similarly to createCliReferenceGenerator(). * * Output directory override is set in architect.config.ts: * ```typescript diff --git a/architect/stubs/cli-recipe-codec/recipe-schema.ts b/architect/stubs/cli-recipe-codec/recipe-schema.ts index db9e8b13..33cc80a5 100644 --- a/architect/stubs/cli-recipe-codec/recipe-schema.ts +++ b/architect/stubs/cli-recipe-codec/recipe-schema.ts @@ -66,7 +66,7 @@ * | `commandNarratives` | `CommandNarrativeGroup[]` | Per-command narrative descriptions | * * Both are optional to preserve backward compatibility with existing consumers - * (ProcessApiReferenceGenerator, showHelp). + * (CliReferenceGenerator, showHelp). */ // ============================================================================= diff --git a/architect/stubs/data-api-architecture-queries/arch-queries.ts b/architect/stubs/data-api-architecture-queries/arch-queries.ts index 8486974f..257cd885 100644 --- a/architect/stubs/data-api-architecture-queries/arch-queries.ts +++ b/architect/stubs/data-api-architecture-queries/arch-queries.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIArchitectureQueries * @architect-uses PatternGraphAPI, PatternGraph, Pattern Scanner - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/arch-queries.ts * @architect-since DS-D * diff --git a/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts b/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts index 45c52ad1..415f3e8d 100644 --- a/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts +++ b/architect/stubs/data-api-architecture-queries/coverage-analyzer.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIArchitectureQueries * @architect-uses Pattern Scanner, PatternGraph - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/coverage-analyzer.ts * @architect-since DS-D * diff --git a/architect/stubs/data-api-context-assembly/context-assembler.ts b/architect/stubs/data-api-context-assembly/context-assembler.ts index af4e8481..fa2bce05 100644 --- a/architect/stubs/data-api-context-assembly/context-assembler.ts +++ b/architect/stubs/data-api-context-assembly/context-assembler.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIContextAssembly * @architect-uses PatternGraphAPI, PatternGraph, PatternSummarizer - * @architect-used-by ProcessAPICLIImpl, ContextFormatter + * @architect-used-by PatternGraphCLIImpl, ContextFormatter * @architect-target src/api/context-assembler.ts * @architect-since DS-C * diff --git a/architect/stubs/data-api-context-assembly/context-formatter.ts b/architect/stubs/data-api-context-assembly/context-formatter.ts index b09c2310..e50d6cd2 100644 --- a/architect/stubs/data-api-context-assembly/context-formatter.ts +++ b/architect/stubs/data-api-context-assembly/context-formatter.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIContextAssembly * @architect-uses ContextAssembler - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/context-formatter.ts * @architect-since DS-C * diff --git a/architect/stubs/data-api-output-shaping/fuzzy-match.ts b/architect/stubs/data-api-output-shaping/fuzzy-match.ts index 5a542da4..d67ce2d7 100644 --- a/architect/stubs/data-api-output-shaping/fuzzy-match.ts +++ b/architect/stubs/data-api-output-shaping/fuzzy-match.ts @@ -2,7 +2,7 @@ * @architect * @architect-status roadmap * @architect-implements DataAPIOutputShaping - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/fuzzy-match.ts * @architect-since DS-A * diff --git a/architect/stubs/data-api-output-shaping/output-pipeline.ts b/architect/stubs/data-api-output-shaping/output-pipeline.ts index bcac61b3..f2407964 100644 --- a/architect/stubs/data-api-output-shaping/output-pipeline.ts +++ b/architect/stubs/data-api-output-shaping/output-pipeline.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIOutputShaping * @architect-uses PatternSummarizer - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/cli/output-pipeline.ts * @architect-since DS-A * diff --git a/architect/stubs/data-api-output-shaping/summarize.ts b/architect/stubs/data-api-output-shaping/summarize.ts index 323097d3..584a769f 100644 --- a/architect/stubs/data-api-output-shaping/summarize.ts +++ b/architect/stubs/data-api-output-shaping/summarize.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIOutputShaping * @architect-uses PatternGraphAPI - * @architect-used-by OutputPipeline, ProcessAPICLIImpl + * @architect-used-by OutputPipeline, PatternGraphCLIImpl * @architect-target src/api/summarize.ts * @architect-since DS-A * diff --git a/architect/stubs/data-api-stub-integration/stub-resolver.ts b/architect/stubs/data-api-stub-integration/stub-resolver.ts index e636fee0..5c335357 100644 --- a/architect/stubs/data-api-stub-integration/stub-resolver.ts +++ b/architect/stubs/data-api-stub-integration/stub-resolver.ts @@ -3,7 +3,7 @@ * @architect-status roadmap * @architect-implements DataAPIStubIntegration * @architect-uses PatternGraphAPI - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/stub-resolver.ts * @architect-since DS-B * diff --git a/architect/stubs/enhanced-index-generation/index-codec-options.ts b/architect/stubs/enhanced-index-generation/index-codec-options.ts index c6be6c59..6413e462 100644 --- a/architect/stubs/enhanced-index-generation/index-codec-options.ts +++ b/architect/stubs/enhanced-index-generation/index-codec-options.ts @@ -14,7 +14,7 @@ * (`byProductArea`, `byPhase`, `byStatus`, `byCategory`) to generate statistics. * Only codecs registered in CodecRegistry receive PatternGraph via the * `codec.decode(dataset)` pipeline. A standalone generator (like - * ProcessApiReferenceGenerator) would need to wire its own PatternGraph access, + * CliReferenceGenerator) would need to wire its own PatternGraph access, * duplicating what CodecBasedGenerator already provides. The codec approach also * gets free integration with `generateDocument('index', dataset)`, * `generateAllDocuments()`, and the `CodecOptions` type-safe options pipeline. diff --git a/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md b/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md index 0738be66..ab97a295 100644 --- a/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md +++ b/docs-inbox/architectural-review-progressive-disclosure-and-codecs.md @@ -331,7 +331,7 @@ When `generateFromConfig()` is used (the high-level orchestrator path), config i 1. **Externally** by `loadProjectConfig()` → `ResolvedConfig` 2. **Inside** `buildPatternGraph()` at `build-pipeline.ts:172` which calls `loadConfig(baseDir)` again -The second load exists because `buildPatternGraph()` is designed as a standalone entry point (used by 5 consumers: orchestrator, process-api CLI, validate-patterns CLI, REPL, MCP server). +The second load exists because `buildPatternGraph()` is designed as a standalone entry point (used by 5 consumers: orchestrator, pattern-graph-cli CLI, validate-patterns CLI, REPL, MCP server). **Fix:** `PipelineOptions` should accept an optional pre-loaded `TagRegistry`. When provided, skip the internal `loadConfig()`. The 4 non-orchestrator consumers continue to omit it. The orchestrator passes its already-loaded config. Zero behavioral change, one fewer disk read + config resolution. diff --git a/docs-inbox/codebase-exploration-findings.md b/docs-inbox/codebase-exploration-findings.md index db74d6f0..aaa1aded 100644 --- a/docs-inbox/codebase-exploration-findings.md +++ b/docs-inbox/codebase-exploration-findings.md @@ -200,7 +200,7 @@ generate.ts ──depends-on──> codecs/index.ts (barrel) ──depends-on──> schema.ts (RenderableDocument) ──depends-on──> codecs/types/base.ts (DocumentCodec, BaseCodecOptions) -Each codec ──depends-on──> validation-schemas/master-dataset.ts (PatternGraph) +Each codec ──depends-on──> validation-schemas/pattern-graph.ts (PatternGraph) ──depends-on──> schema.ts (block builders) ──depends-on──> codecs/types/base.ts (BaseCodecOptions, mergeOptions) ──depends-on──> codecs/shared-schema.ts (RenderableDocumentOutputSchema) diff --git a/docs-inbox/reimplementation-drift-analysis.md b/docs-inbox/reimplementation-drift-analysis.md index 1f92bfd2..c5c380ce 100644 --- a/docs-inbox/reimplementation-drift-analysis.md +++ b/docs-inbox/reimplementation-drift-analysis.md @@ -21,7 +21,7 @@ The important part, and most important feature in the whole repo was introduced **Process API for AI Coding Agents** This untracked file is important for context: -@\_working-docs/01-process-api/03-process-api-data-api-context.md +@\_working-docs/01-pattern-graph-cli/03-pattern-graph-cli-data-api-context.md And these specs are scope for the features introduced: diff --git a/docs-inbox/session-prompt-generator-architecture-review.md b/docs-inbox/session-prompt-generator-architecture-review.md index d76ee761..61c1ac87 100644 --- a/docs-inbox/session-prompt-generator-architecture-review.md +++ b/docs-inbox/session-prompt-generator-architecture-review.md @@ -195,7 +195,7 @@ The formatter: ### Step 4: Wire `session-prompt` subcommand -Add to `src/cli/process-api.ts` following the established CLI pattern. +Add to `src/cli/pattern-graph-cli.ts` following the established CLI pattern. ```bash pnpm architect:query -- session-prompt DataAPIDesignSessionSupport --type implement diff --git a/docs-inbox/session-prompt-generator-brief.md b/docs-inbox/session-prompt-generator-brief.md index 4df74c59..7f9f2252 100644 --- a/docs-inbox/session-prompt-generator-brief.md +++ b/docs-inbox/session-prompt-generator-brief.md @@ -199,7 +199,7 @@ CLAUDE.md retains its role as the entry point, but convention sections become ** | ------------------------------- | ------------------------------------------------- | ----------------- | | Session prompt assembler | `src/api/session-prompt.ts` | Yes (unit) | | Session prompt text formatter | `src/api/session-prompt.ts` (co-located per DD-7) | Yes (unit) | -| `session-prompt` CLI subcommand | `src/cli/process-api.ts` | Yes (integration) | +| `session-prompt` CLI subcommand | `src/cli/pattern-graph-cli.ts` | Yes (integration) | --- diff --git a/docs-inbox/session-prompt-generator-manual.md b/docs-inbox/session-prompt-generator-manual.md index d9dcafc9..1c9cd384 100644 --- a/docs-inbox/session-prompt-generator-manual.md +++ b/docs-inbox/session-prompt-generator-manual.md @@ -54,7 +54,7 @@ After the API commands, read these for implementation patterns: | `architect/specs/data-api-session-support.feature` | Spec with deliverables and scenarios | | `src/api/context-assembler.ts` | Reusable helpers: `requirePattern()`, `resolveFsm()` | | `src/api/context-formatter.ts` | `=== MARKERS ===` text formatting conventions | -| `src/cli/process-api.ts` | CLI subcommand wiring pattern (how to add new subcommands) | +| `src/cli/pattern-graph-cli.ts` | CLI subcommand wiring pattern (how to add new subcommands) | | `src/validation/dod-validator.ts` | `isDeliverableComplete()` for handoff completion logic | ### Execution order (CRITICAL) diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index 78bd9777..b3eb5b07 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -43,7 +43,7 @@ graph TB end subgraph cli["Cli BC"] ReplMode["ReplMode[service]"] - ProcessAPICLIImpl["ProcessAPICLIImpl[service]"] + PatternGraphCLIImpl["PatternGraphCLIImpl[service]"] OutputPipelineImpl["OutputPipelineImpl[service]"] MCPServerBin["MCPServerBin[infrastructure]"] DatasetCache["DatasetCache[infrastructure]"] @@ -69,11 +69,11 @@ graph TB ContentDeduplicator["ContentDeduplicator[infrastructure]"] CodecBasedGenerator["CodecBasedGenerator[service]"] FileCache["FileCache[infrastructure]"] - DesignReviewGenerator["DesignReviewGenerator[service]"] - DecisionDocGenerator["DecisionDocGenerator[service]"] TransformDataset["TransformDataset[service]"] SequenceTransformUtils["SequenceTransformUtils[service]"] RelationshipResolver["RelationshipResolver[service]"] + DesignReviewGenerator["DesignReviewGenerator[service]"] + DecisionDocGenerator["DecisionDocGenerator[service]"] end subgraph lint["Lint BC"] LintRules["LintRules[service]"] @@ -126,19 +126,22 @@ graph TB MCPModule --> MCPFileWatcher MCPModule --> MCPToolRegistry LintEngine --> LintRules + SourceMapper -.-> DecisionDocCodec + SourceMapper -.-> GherkinASTParser + Documentation_Generation_Orchestrator --> Pattern_Scanner GherkinExtractor --> GherkinASTParser DualSourceExtractor --> GherkinExtractor DualSourceExtractor --> GherkinScanner Document_Extractor --> Pattern_Scanner - SourceMapper -.-> DecisionDocCodec - SourceMapper -.-> GherkinASTParser - Documentation_Generation_Orchestrator --> Pattern_Scanner + ConfigResolver --> ArchitectFactory + ArchitectFactory --> RegexBuilders + ConfigLoader --> ArchitectFactory ReplMode --> PatternGraphAPI - ProcessAPICLIImpl --> PatternGraphAPI - ProcessAPICLIImpl --> PatternGraph - ProcessAPICLIImpl --> PatternSummarizerImpl - ProcessAPICLIImpl --> FuzzyMatcherImpl - ProcessAPICLIImpl --> OutputPipelineImpl + PatternGraphCLIImpl --> PatternGraphAPI + PatternGraphCLIImpl --> PatternGraph + PatternGraphCLIImpl --> PatternSummarizerImpl + PatternGraphCLIImpl --> FuzzyMatcherImpl + PatternGraphCLIImpl --> OutputPipelineImpl OutputPipelineImpl --> PatternSummarizerImpl MCPServerBin --> MCPServerImpl PatternSummarizerImpl --> PatternGraphAPI @@ -158,20 +161,17 @@ graph TB ContextAssemblerImpl --> FuzzyMatcherImpl ArchQueriesImpl --> PatternGraphAPI ArchQueriesImpl --> PatternGraph - ConfigResolver --> ArchitectFactory - ArchitectFactory --> RegexBuilders - ConfigLoader --> ArchitectFactory FSMValidator --> FSMTransitions FSMValidator --> FSMStates DesignReviewCodec --> PatternGraph ArchitectureCodec --> PatternGraph ProcessGuardDecider --> FSMValidator + TransformDataset --> PatternGraph + SequenceTransformUtils --> PatternGraph DesignReviewGenerator --> DesignReviewCodec DesignReviewGenerator --> PatternGraph DecisionDocGenerator -.-> DecisionDocCodec DecisionDocGenerator -.-> SourceMapper - TransformDataset --> PatternGraph - SequenceTransformUtils --> PatternGraph ``` --- @@ -213,7 +213,7 @@ All components with architecture annotations: | 🚧 Dataset Cache | cli | infrastructure | infrastructure | src/cli/dataset-cache.ts | | 🚧 MCP Server Bin | cli | infrastructure | infrastructure | src/cli/mcp-server.ts | | 🚧 Output Pipeline Impl | cli | service | application | src/cli/output-pipeline.ts | -| 🚧 Process API CLI Impl | cli | service | application | src/cli/process-api.ts | +| 🚧 Pattern Graph CLI Impl | cli | service | application | src/cli/pattern-graph-cli.ts | | 🚧 Repl Mode | cli | service | application | src/cli/repl.ts | | ✅ Configuration Defaults | config | - | domain | src/config/defaults.ts | | ✅ Configuration Presets | config | - | domain | src/config/presets.ts | @@ -231,12 +231,12 @@ All components with architecture annotations: | ✅ Dual Source Extractor | extractor | service | application | src/extractor/dual-source-extractor.ts | | ✅ Gherkin Extractor | extractor | service | application | src/extractor/gherkin-extractor.ts | | Cli Recipe Generator | generator | - | application | src/generators/built-in/cli-recipe-generator.ts | +| ✅ Cli Reference Generator | generator | - | application | src/generators/built-in/cli-reference-generator.ts | | ✅ Context Inference Impl | generator | - | application | src/generators/pipeline/context-inference.ts | | 🚧 Git Branch Diff | generator | - | infrastructure | src/git/branch-diff.ts | | 🚧 Git Helpers | generator | - | infrastructure | src/git/helpers.ts | | 🚧 Git Module | generator | - | infrastructure | src/git/index.ts | | 🚧 Git Name Status Parser | generator | - | infrastructure | src/git/name-status.ts | -| ✅ Process Api Reference Generator | generator | - | application | src/generators/built-in/process-api-reference-generator.ts | | 🚧 Transform Types | generator | - | application | src/generators/pipeline/transform-types.ts | | ✅ Content Deduplicator | generator | infrastructure | infrastructure | src/generators/content-deduplicator.ts | | 🚧 File Cache | generator | infrastructure | infrastructure | src/cache/file-cache.ts | @@ -321,15 +321,15 @@ All components with architecture annotations: | ✅ Normalized Status | - | - | - | src/taxonomy/normalized-status.ts | | 🚧 Normalized Status Testing | - | - | - | tests/features/types/normalized-status.feature | | ✅ Orchestrator Pipeline Factory Migration | - | - | - | architect/specs/orchestrator-pipeline-factory-migration.feature | +| 🚧 Pattern Graph API Types | - | - | - | src/api/types.ts | | ✅ Pipeline Factory | - | - | - | src/generators/pipeline/build-pipeline.ts | | ✅ Pipeline Module | - | - | - | src/generators/pipeline/index.ts | | ✅ Planning Codecs | - | - | - | src/renderable/codecs/planning.ts | | ✅ Pr Changes Codec | - | - | - | src/renderable/codecs/pr-changes.ts | -| ✅ Process API Layered Extraction | - | - | - | architect/specs/process-api-layered-extraction.feature | +| ✅ Process API Layered Extraction | - | - | - | architect/specs/pattern-graph-layered-extraction.feature | | 🚧 Process Guard Module | - | - | - | src/lint/process-guard/index.ts | | ✅ Process Guard Testing | - | - | - | tests/features/validation/process-guard.feature | | 🚧 Process Guard Types | - | - | - | src/lint/process-guard/types.ts | -| 🚧 Process State Types | - | - | - | src/api/types.ts | | ✅ Reference Codec | - | - | - | src/renderable/codecs/reference-types.ts | | ✅ Reference Codec | - | - | - | src/renderable/codecs/reference-diagrams.ts | | ✅ Reference Codec | - | - | - | src/renderable/codecs/reference-builders.ts | diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 3ff495b1..0a7b65d4 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -15,11 +15,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. -- **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. -- **MCP Server Impl**: Main entry point for the Architect MCP server. -- **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. -- **MCP Module**: Public API for the MCP server module. -- **MCP File Watcher**: Watches source file globs and triggers debounced pipeline rebuilds. - **Git Name Status Parser**: Parses NUL-delimited git name-status output into categorized file lists. - **Git Module**: Shared git utilities used by both generators and lint layers. - **Git Helpers**: Low-level helpers for safe git command execution and input sanitization. @@ -29,8 +24,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Project Config Schema**: Zod validation schema for `ArchitectProjectConfig`. - **Source Merger**: Computes effective sources for a specific generator by applying per-generator overrides to the base resolved sources. - **Define Config**: Identity function for type-safe project configuration. +- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. +- **Pattern Graph CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. +- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. +- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. +- **Lint Process CLI**: Validates git changes against workflow rules. +- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **File Cache**: Simple Map-based cache for file contents during a single generation run. -- **Process State Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. +- **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. +- **MCP Server Impl**: Main entry point for the Architect MCP server. +- **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. +- **MCP Module**: Public API for the MCP server module. +- **MCP File Watcher**: Watches source file globs and triggers debounced pipeline rebuilds. +- **Pattern Graph API Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. - **Pattern Summarizer Impl**: Projects the full ExtractedPattern (~3.5KB per pattern) down to a PatternSummary (~100 bytes) for list queries. - **Stub Resolver Impl**: Identifies design session stubs in the PatternGraph and resolves them against the filesystem to determine... - **Pattern Helpers**: Common helper functions used by context-assembler, arch-queries, and other API modules that need pattern name... @@ -41,12 +47,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Context Formatter Impl**: First plain-text formatter in the codebase. - **Context Assembler Impl**: Pure function composition over PatternGraph. - **Arch Queries Impl**: Pure functions over PatternGraph for deep architecture exploration. -- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. -- **Process API CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. -- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. -- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. -- **Lint Process CLI**: Validates git changes against workflow rules. -- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **FSM Validator**: :PDR005MvpWorkflow Pure validation functions following the Decider pattern: - No I/O, no side effects - Return... - **FSM Transitions**: :PDR005MvpWorkflow Defines valid transitions between FSM states per PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **FSM States**: :PDR005MvpWorkflow Defines the 4-state FSM from PDR-005 MVP Workflow: - roadmap: Planned work (fully editable) -... @@ -66,21 +66,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Relationship Resolver**: Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) and detects dangling references in... - **Reference Generator Registration**: Registers all reference document generators. - **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. -- **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the process-api CLI. +- **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the pattern-graph-cli CLI. - **Design Review Generation**: Design reviews require manual creation of sequence and component diagrams that duplicate information already captured... -- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. -- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Workflow Config Schemas Validation**: The workflow configuration module defines Zod schemas for validating delivery workflow definitions with statuses,... - **Tag Registry Schemas Validation**: The tag registry configuration module provides schema-validated taxonomy definitions for organizing patterns by... - **Codec Utils Validation**: The codec utilities provide factory functions for creating type-safe JSON parsing and serialization pipelines using... +- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. +- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Tag Registry Builder Testing**: The tag registry builder constructs a complete TagRegistry from TypeScript constants. - **Normalized Status Testing**: The normalized status module maps any status input — raw FSM states (roadmap, active, completed, deferred),... - **Deliverable Status Taxonomy Testing**: The deliverable status module defines the 6 canonical status values for deliverables in Gherkin Background tables:... - **Load Preamble Parser**: The parseMarkdownToBlocks function converts raw markdown content into a readonly SectionBlock[] array using a 5-state... - **Design Review Generation Tests**: Tests the full design review generation pipeline: sequence annotations are extracted from patterns with business... - **Design Review Generator Lifecycle Tests**: The design review generator cleans up stale markdown files when annotated patterns are renamed or removed from the... -- **Architecture Doc Refactoring Testing**: Validates that ARCHITECTURE.md retains its full reference content and that generated documents in docs-live/ coexist... - **Claude Metadata Parity Testing**: The extractor must preserve Claude routing metadata from TypeScript directives and keep the sync and async Gherkin... +- **Architecture Doc Refactoring Testing**: Validates that ARCHITECTURE.md retains its full reference content and that generated documents in docs-live/ coexist... - **Process Api Cli Repl**: Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. - **Process Api Cli Metadata**: Response metadata includes validation summary and pipeline timing for diagnostics. - **Process Api Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. @@ -88,13 +88,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Process Api Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. - **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... - **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... +- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... +- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... +- **Arch Queries Test** - **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... - **Pattern Helpers Tests** - **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. - **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. -- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... -- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... -- **Arch Queries Test** - **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. - **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. @@ -142,6 +142,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Utils Module**: Common helper functions used across the Architect package. - **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. - **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. +- **Result Monad Types**: Explicit error handling via discriminated union. +- **Error Factory Types**: Structured, discriminated error types with factory functions. +- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. +- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. +- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... +- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). - **Risk Levels**: Three-tier risk classification for roadmap planning. - **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. @@ -150,10 +156,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... - **Format Types**: Defines how tag values are parsed and validated. - **Category Definitions**: Categories are used to classify patterns and organize documentation. -- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. -- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. -- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... -- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. @@ -162,11 +164,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. - **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. - **Lint Engine**: Orchestrates lint rule execution against parsed directives. -- **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... -- **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. -- **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. -- **Dual Source Extractor**: Extracts pattern metadata from both TypeScript code stubs (@architect-_) and Gherkin feature files (@architect-_),... -- **Document Extractor**: Converts scanned file data into complete ExtractedPattern objects with unique IDs, inferred names, categories, and... - **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. - **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. - **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. @@ -175,6 +172,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... - **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. - **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. +- **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... +- **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. +- **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. +- **Dual Source Extractor**: Extracts pattern metadata from both TypeScript code stubs (@architect-_) and Gherkin feature files (@architect-_),... +- **Document Extractor**: Converts scanned file data into complete ExtractedPattern objects with unique IDs, inferred names, categories, and... - **Workflow Loader**: Provides the default 6-phase workflow as an inline constant and loads custom workflow overrides from JSON files via... - **Configuration Types**: Type definitions for the Architect configuration system. - **Regex Builders**: Type-safe regex factory functions for tag detection and normalization. @@ -182,17 +184,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architect Factory**: Main factory function for creating configured Architect instances. - **Configuration Defaults**: Centralized default constants for the Architect package. - **Config Loader**: Discovers and loads `architect.config.ts` or `architect.config.js` files for hierarchical configuration. -- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. -- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. -- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. -- **Result Monad Types**: Explicit error handling via discriminated union. -- **Error Factory Types**: Structured, discriminated error types with factory functions. - **CLI Version Helper**: Reads package version from package.json for CLI --version flag. - **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. - **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. - **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. - **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. - **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. +- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. +- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. +- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. - **Validation Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. - **Timeline Codec**: :Generation Purpose: Development roadmap organized by phase with progress tracking. - **Taxonomy Codec**: :Generation Transforms PatternGraph into a RenderableDocument for taxonomy reference output. @@ -220,10 +220,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Pipeline Module**: Barrel export for the unified transformation pipeline components. - **Context Inference Impl**: Auto-infers bounded context from file paths using configurable rules. - **Pipeline Factory**: Invariant: `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... -- **Process Api Reference Generator**: :Generation Generates `PROCESS-API-REFERENCE.md` from the declarative CLI schema. - **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. - **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. - **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. +- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Codec Base Options**: :Add-createDecodeOnlyCodec-helper Shared types, interfaces, and utilities for all document codecs. - **ADR 006 Single Read Model Architecture**: The Architect package applies event sourcing to itself: git is the event store, annotated source files are... - **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (PatternGraph) into markdown files. @@ -238,9 +238,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Reference Doc Showcase**: The Reference Generation Sample document exercises a small fraction of the reference codec's capabilities: 2... - **Readme Rationalization**: `README.md` is 504 lines and serves three different audiences in one document: (a) npm package consumers who need... - **Publishing Relocation**: `docs/PUBLISHING.md` (144 lines) is deployed to libar.dev as part of the `docs/` directory, but its content is... -- **Process API Layered Extraction**: `process-api.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. -- **Process Api Hybrid Generation**: `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source... - **Procedural Guide Codec**: Two manual docs contain procedural content with no annotation source for generation: `docs/SESSION-GUIDES.md` (389... +- **Process API Layered Extraction**: `pattern-graph-cli.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. - **Pattern Graph API Relationship Queries**: Problem: PatternGraphAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, `enables`) but lacks... - **Pattern Graph API CLI**: The PatternGraphAPI provides 27 typed query methods for efficient state queries, but Claude Code sessions cannot use... - **Orchestrator Pipeline Factory Migration**: `orchestrator.ts` is the last feature consumer that wires the 8-step scan-extract-merge-transform pipeline inline... @@ -254,20 +253,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Declaration Level Shape Tagging**: The current shape extraction system operates at file granularity. - **Data API Stub Integration**: Design sessions produce code stubs in `architect/stubs/` with rich metadata: `@architect-target` (destination file... - **Data API Design Session Support**: Starting a design or implementation session requires manually compiling elaborate context prompts. -- **Data API Platform Integration**: The process-api CLI requires subprocess invocation for every query, adding shell overhead and preventing stateful... +- **Data API Platform Integration**: The pattern-graph-cli CLI requires subprocess invocation for every query, adding shell overhead and preventing... - **Data API Output Shaping**: The PatternGraphAPI CLI returns raw `ExtractedPattern` objects via `JSON.stringify`. - **Data API Context Assembly**: Starting a Claude Code design or implementation session requires assembling 30-100KB of curated, multi-source context... -- **Data API CLI Ergonomics**: The process-api CLI runs the full pipeline (scan, extract, transform) on every invocation, taking 2-5 seconds. +- **Data API CLI Ergonomics**: The pattern-graph-cli CLI runs the full pipeline (scan, extract, transform) on every invocation, taking 2-5 seconds. - **Data API Architecture Queries**: The current `arch` subcommand provides basic queries (roles, context, layer, graph) but lacks deeper analysis needed... - **Cross Cutting Document Inclusion**: The reference doc codec assembles content from four sources, each with its own selection mechanism: conventionTags... - **Config Based Workflow Definition**: Every `pnpm process:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow (6-phase-standard):... - **Codec Driven Reference Generation**: Each reference document (Process Guard, Taxonomy, Validation, etc.) required a hand-coded recipe feature that... -- **Cli Recipe Codec**: `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (ProcessApiHybridGeneration)... +- **Cli Reference Generation**: `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source... +- **Cli Recipe Codec**: `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (CliReferenceGeneration)... - **Claude Module Generation**: Problem: CLAUDE.md modules are hand-written markdown files that drift from source code over time. - **Architecture Doc Refactoring**: ARCHITECTURE.md is 1,287 lines of manually-maintained documentation covering 14 sections. - **Architecture Diagram Core**: Problem: Architecture documentation requires manually maintaining mermaid diagrams that duplicate information already... - **Architecture Diagram Advanced**: Problem: Core diagram generation (see ArchitectureDiagramCore) produces component-level diagrams from `arch-*` tags. -- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Status Transition Detection Testing**: Tests for the detectStatusTransitions function that parses git diff output. - **Process Guard Testing**: Pure validation functions for enforcing delivery process rules per PDR-005. - **FSM Validator Testing**: Pure validation functions for the 4-state FSM defined in PDR-005. @@ -275,6 +274,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Detect Changes Testing**: Tests for the detectDeliverableChanges function that parses git diff output. - **Config Schema Validation**: Configuration schemas validate scanner and generator inputs with security constraints to prevent path traversal... - **Anti Pattern Detector Testing**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... +- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Result Monad**: The Result type provides explicit error handling via a discriminated union. - **Error Factories**: Error factories create structured, discriminated error types with consistent message formatting. - **Gherkin Ast Parser**: The Gherkin AST parser extracts feature metadata, scenarios, and steps from .feature files for timeline generation... @@ -287,17 +287,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Rule Individual Testing**: Individual lint rules that check parsed directives for completeness. - **Lint Rule Advanced Testing**: Complex lint rule logic and collection-level behavior. - **Lint Engine Testing**: The lint engine orchestrates rule execution, aggregates violations, and formats output for human and machine... -- **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... -- **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... -- **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... -- **Source Mapping Validator Testing**: Context: Source mappings reference files that may not exist, use invalid extraction methods, or have incompatible... -- **Source Mapper Testing**: The Source Mapper aggregates content from multiple source files based on source mapping tables parsed from decision... -- **Robustness Integration**: Context: Document generation pipeline needs validation, deduplication, and warning collection to work together... -- **Poc Integration**: End-to-end integration tests that exercise the full documentation generation pipeline using the actual POC decision... -- **Index Codec Testing**: Validates the Index Codec that transforms PatternGraph into a RenderableDocument for the main documentation... -- **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . -- **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... -- **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. - **Table Extraction**: Tables in business rule descriptions should appear exactly once in output. - **Generator Registry Testing**: Tests the GeneratorRegistry registration, lookup, and listing capabilities. - **Prd Implementation Section Testing**: Tests the Implementations section rendering in pattern documents. @@ -317,6 +306,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. - **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... - **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... +- **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... +- **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... +- **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... +- **Source Mapping Validator Testing**: Context: Source mappings reference files that may not exist, use invalid extraction methods, or have incompatible... +- **Source Mapper Testing**: The Source Mapper aggregates content from multiple source files based on source mapping tables parsed from decision... +- **Robustness Integration**: Context: Document generation pipeline needs validation, deduplication, and warning collection to work together... +- **Poc Integration**: End-to-end integration tests that exercise the full documentation generation pipeline using the actual POC decision... +- **Index Codec Testing**: Validates the Index Codec that transforms PatternGraph into a RenderableDocument for the main documentation... +- **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . +- **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... +- **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. - **Validate Patterns Cli**: Command-line interface for cross-validating TypeScript patterns vs Gherkin feature files. - **Process Api Cli Subcommands**: Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. - **Process Api Cli Modifiers And Rules**: Output modifiers, arch health, and rules subcommand. diff --git a/docs-live/INDEX.md b/docs-live/INDEX.md index 5024a073..9ad90393 100644 --- a/docs-live/INDEX.md +++ b/docs-live/INDEX.md @@ -27,7 +27,7 @@ | Understand the tag taxonomy | [TAXONOMY.md](TAXONOMY.md) | | Check validation rules | [VALIDATION-RULES.md](VALIDATION-RULES.md) | | Browse the changelog | [CHANGELOG-GENERATED.md](CHANGELOG-GENERATED.md) | -| Query process state via CLI | [Process API Reference](reference/PROCESS-API-REFERENCE.md) | +| Query process state via CLI | [Process API Reference](reference/CLI-REFERENCE.md) | | Find CLI workflow recipes | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | | Run AI coding sessions | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | @@ -55,7 +55,7 @@ 1. **[Annotation Reference](reference/ANNOTATION-REFERENCE.md)** -- Annotation mechanics and tag reference 2. **[Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md)** -- Planning, Design, Implementation workflows -3. **[Process API Reference](reference/PROCESS-API-REFERENCE.md)** -- CLI command reference with flags and examples +3. **[Process API Reference](reference/CLI-REFERENCE.md)** -- CLI command reference with flags and examples 4. **[Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md)** -- Pre-commit hooks, error codes, programmatic API --- @@ -122,7 +122,7 @@ | --------------------------------------------------------------- | -------------------------------------------------------------------- | ---------- | | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | Annotation mechanics, shape extraction, tag reference | Developers | | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | Planning, Design, Implementation session workflows | AI/Devs | -| [Process API Reference](reference/PROCESS-API-REFERENCE.md) | CLI command reference with flags and examples | AI/Devs | +| [Process API Reference](reference/CLI-REFERENCE.md) | CLI command reference with flags and examples | AI/Devs | | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | CLI workflow recipes and session guides | AI/Devs | | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | Pre-commit hooks, error codes, programmatic API | Team Leads | | [Architecture Codecs](reference/ARCHITECTURE-CODECS.md) | All codecs with factory patterns and options | Developers | @@ -226,6 +226,6 @@ pnpm docs:business-rules # Business rules pnpm docs:taxonomy # Taxonomy reference pnpm docs:validation # Validation rules pnpm docs:claude-modules # Claude context modules -pnpm docs:process-api-reference # Process API CLI reference +pnpm docs:cli-reference # Process API CLI reference pnpm docs:cli-recipe # CLI recipes & workflow guide ``` diff --git a/docs-live/_claude-md/annotation/annotation-overview.md b/docs-live/_claude-md/annotation/annotation-overview.md index 667930e6..737875e3 100644 --- a/docs-live/_claude-md/annotation/annotation-overview.md +++ b/docs-live/_claude-md/annotation/annotation-overview.md @@ -19,8 +19,8 @@ | MetadataTagDefinitionForRegistry | interface | | CategoryDefinition | interface | | CategoryTag | type | -| isShapeOnlyDirective | function | | buildRegistry | function | +| isShapeOnlyDirective | function | | METADATA_TAGS_BY_GROUP | const | | CATEGORIES | const | | CATEGORY_TAGS | const | diff --git a/docs-live/business-rules/data-api.md b/docs-live/business-rules/data-api.md index 9ebb5e45..cc7af478 100644 --- a/docs-live/business-rules/data-api.md +++ b/docs-live/business-rules/data-api.md @@ -911,7 +911,7 @@ _Core CLI infrastructure: help, version, input validation, status, query, patter - Integer arguments are coerced for phase queries - Double-dash separator is handled gracefully -_process-api-core.feature_ +_pattern-graph-cli-core.feature_ ### Process Api Cli Dry Run @@ -1023,7 +1023,7 @@ _Output modifiers, arch health, and rules subcommand._ - Rules for non-existent product area returns hint - Rules combines product area and only-invariants filters -_process-api-modifiers-rules.feature_ +_pattern-graph-cli-modifiers-rules.feature_ ### Process Api Cli Repl @@ -1140,7 +1140,7 @@ _Discovery subcommands: list, search, context assembly, tags/sources, extended a - Unannotated finds files missing architect marker -_process-api-subcommands.feature_ +_pattern-graph-cli-subcommands.feature_ ### Process Api Reference Tests @@ -1150,7 +1150,7 @@ _Verifies that the declarative CLI schema drives reference table generation_ #### Generated reference file contains all three table sections -> **Invariant:** PROCESS-API-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema. +> **Invariant:** CLI-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema. **Verified by:** @@ -1182,7 +1182,7 @@ _Verifies that the declarative CLI schema drives reference table generation_ - Help text includes schema-defined options -_process-api-reference.feature_ +_cli-reference.feature_ ### Scope Validator Tests diff --git a/docs-live/business-rules/generation.md b/docs-live/business-rules/generation.md index 07d3bf15..a2fe53c9 100644 --- a/docs-live/business-rules/generation.md +++ b/docs-live/business-rules/generation.md @@ -1611,7 +1611,7 @@ _Tests the full design review generation pipeline: sequence annotations are_ #### Process API sequence lookup resolves pattern names case-insensitively -> **Invariant:** The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented process-api queries. +> **Invariant:** The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented pattern-graph queries. > > **Rationale:** Design review consumers should not need exact display-name casing when querying sequence data from the CLI. diff --git a/docs-live/decisions/adr-006-single-read-model-architecture.md b/docs-live/decisions/adr-006-single-read-model-architecture.md index 52c2a688..d257f3a3 100644 --- a/docs-live/decisions/adr-006-single-read-model-architecture.md +++ b/docs-live/decisions/adr-006-single-read-model-architecture.md @@ -55,10 +55,10 @@ consume the same pre-computed read model. **Rationale:** Bypassing the read model forces consumers to re-derive data that the PatternGraph already computes, creating duplicate logic and divergent behavior when the pipeline evolves. -| Layer | May Import | Examples | -| ---------------------- | ------------------------------- | --------------------------------------------------- | -| Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, process-api.ts pipeline setup | -| Feature Consumption | PatternGraph, relationshipIndex | codecs, PatternGraphAPI, validators, query handlers | +| Layer | May Import | Examples | +| ---------------------- | ------------------------------- | ---------------------------------------------------- | +| Pipeline Orchestration | scanner/, extractor/, pipeline/ | orchestrator.ts, pattern-graph-cli.ts pipeline setup | +| Feature Consumption | PatternGraph, relationshipIndex | codecs, PatternGraphAPI, validators, query handlers | **Verified by:** diff --git a/docs-live/product-areas/ANNOTATION.md b/docs-live/product-areas/ANNOTATION.md index f9d6eaa1..773cad42 100644 --- a/docs-live/product-areas/ANNOTATION.md +++ b/docs-live/product-areas/ANNOTATION.md @@ -210,35 +210,35 @@ interface CategoryDefinition { type CategoryTag = (typeof CATEGORIES)[number]['tag']; ``` -### isShapeOnlyDirective (function) +### buildRegistry (function) ```typescript /** - * Check if a directive is a shape-only annotation (declaration-level @architect-shape). + * Build the complete tag registry from TypeScript constants * - * Shape directives annotate individual interfaces/types for documentation extraction. - * They inherit context from a parent pattern and should not enter the directive pipeline - * as standalone patterns. + * This is THE single source of truth for the taxonomy. + * All consumers should use this function instead of loading JSON. */ ``` ```typescript -function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; +function buildRegistry(): TagRegistry; ``` -### buildRegistry (function) +### isShapeOnlyDirective (function) ```typescript /** - * Build the complete tag registry from TypeScript constants + * Check if a directive is a shape-only annotation (declaration-level @architect-shape). * - * This is THE single source of truth for the taxonomy. - * All consumers should use this function instead of loading JSON. + * Shape directives annotate individual interfaces/types for documentation extraction. + * They inherit context from a parent pattern and should not enter the directive pipeline + * as standalone patterns. */ ``` ```typescript -function buildRegistry(): TagRegistry; +function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; ``` ### METADATA_TAGS_BY_GROUP (const) diff --git a/docs-live/product-areas/CONFIGURATION.md b/docs-live/product-areas/CONFIGURATION.md index ab7be1de..5a295bb2 100644 --- a/docs-live/product-areas/CONFIGURATION.md +++ b/docs-live/product-areas/CONFIGURATION.md @@ -973,7 +973,7 @@ const PRESETS: Record; | Rule | Invariant | Rationale | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Default workflow is built from an inline constant | `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. | The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, process-api) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. | +| Default workflow is built from an inline constant | `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. | The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. | | Custom workflow files still work via --workflow flag | `loadWorkflowFromPath()` remains available for projects that need custom workflow definitions. The `--workflow ` CLI flag and `workflowPath` config field continue to work. | The inline default replaces file-based _default_ loading, not file-based _custom_ loading. Projects may define custom phases or additional statuses via JSON files. | | FSM validation and Process Guard are not affected | The FSM transition matrix, protection levels, and Process Guard rules remain hardcoded in `src/validation/fsm/` and `src/lint/process-guard/`. They do not read from `LoadedWorkflow`. | FSM and workflow are separate concerns. FSM enforces status transitions (4-state model from PDR-005). Workflow defines phase structure (6-phase USDP). The workflow JSON declared `transitionsTo` on its statuses, but no code ever read those values — the FSM uses its own `VALID_TRANSITIONS` constant. This separation is correct and intentional. Blast radius analysis confirmed zero workflow imports in: - src/validation/fsm/ (4 files) - src/lint/process-guard/ (5 files) - src/taxonomy/ (all files) | | Workflow as a configurable preset field is deferred | The inline default workflow constant is the only workflow source until preset integration is implemented. No preset or project config field exposes workflow customization. | Coupling workflow into the preset/config system before the inline fix ships would widen the blast radius and risk type regressions across all config consumers. | @@ -1051,9 +1051,9 @@ const PRESETS: Record; | Init detects existing project context before making changes | The init command reads the target directory for package.json, tsconfig.json, architect.config.ts (or .js), and monorepo markers before prompting or generating any files. Detection results determine which steps are skipped. | Blindly generating files overwrites user configuration and breaks working setups. Context detection enables safe adoption into existing projects by skipping steps that are already complete. | | Interactive prompts configure preset and source paths with smart defaults | The init command prompts for preset selection from the two available presets (libar-generic, ddd-es-cqrs) with descriptions, and for source glob paths with defaults inferred from project structure. The --yes flag skips non-destructive selection prompts and uses defaults. Destructive overwrites require an explicit --force flag; otherwise init exits without modifying existing files. | New users do not know which preset to choose or what glob patterns to use. Smart defaults reduce decisions to confirmations. The --yes flag enables scripted adoption in CI. | | Generated config file uses defineConfig with correct imports | The generated architect.config.ts (or .js) imports defineConfig from the correct path, uses the selected preset, and includes configured source globs. An existing config file is never overwritten without confirmation. | The config file is the most important artifact. An incorrect import path or malformed glob causes every subsequent command to fail. The overwrite guard prevents destroying custom configuration. | -| Npm scripts are injected using bin command names | Injected scripts reference bin names (process-api, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via --esm flag. | The tutorial uses long fragile dist paths. Bin commands are the stable public API. Setting type:module ensures ESM imports work for the config. | +| Npm scripts are injected using bin command names | Injected scripts reference bin names (pattern-graph-cli, generate-docs) resolved via node_modules/.bin, not dist paths. Existing scripts are preserved. The package.json "type" field is preserved. ESM migration is an explicit opt-in via --esm flag. | The tutorial uses long fragile dist paths. Bin commands are the stable public API. Setting type:module ensures ESM imports work for the config. | | Directory structure and example annotation enable immediate first run | The init command creates directories for configured source globs and generates one example annotated TypeScript file with the minimum annotation set (opt-in marker, pattern tag, status, category, description). | Empty source globs produce a confusing "0 patterns" result. An example file proves the pipeline works and teaches annotation syntax by example. | -| Init validates the complete setup by running the pipeline | After all files are generated, init runs process-api overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information. | Generating files without verification produces false confidence. Running the pipeline as the final step proves config, globs, directories, and the example annotation all work together. | +| Init validates the complete setup by running the pipeline | After all files are generated, init runs pattern-graph-cli overview and reports whether the pipeline detected the example pattern. Success prints a summary and next steps. Failure prints diagnostic information. | Generating files without verification produces false confidence. Running the pipeline as the final step proves config, globs, directories, and the example annotation all work together. | ### Source Merging diff --git a/docs-live/product-areas/DATA-API.md b/docs-live/product-areas/DATA-API.md index 842c4e95..a2690831 100644 --- a/docs-live/product-areas/DATA-API.md +++ b/docs-live/product-areas/DATA-API.md @@ -45,7 +45,7 @@ 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. @@ -66,6 +66,11 @@ Scoped architecture diagram showing component relationships: graph TB subgraph api["Api"] PatternGraph[/"PatternGraph"/] + MCPToolRegistry("MCPToolRegistry") + MCPServerImpl("MCPServerImpl") + MCPPipelineSession("MCPPipelineSession") + MCPModule[/"MCPModule"/] + MCPFileWatcher[/"MCPFileWatcher"/] PatternSummarizerImpl("PatternSummarizerImpl") ScopeValidatorImpl("ScopeValidatorImpl") PatternHelpers["PatternHelpers"] @@ -76,15 +81,10 @@ graph TB ContextFormatterImpl("ContextFormatterImpl") ContextAssemblerImpl("ContextAssemblerImpl") ArchQueriesImpl("ArchQueriesImpl") - MCPToolRegistry("MCPToolRegistry") - MCPServerImpl("MCPServerImpl") - MCPPipelineSession("MCPPipelineSession") - MCPModule[/"MCPModule"/] - MCPFileWatcher[/"MCPFileWatcher"/] end subgraph cli["Cli"] ReplMode("ReplMode") - ProcessAPICLIImpl("ProcessAPICLIImpl") + PatternGraphCLIImpl("PatternGraphCLIImpl") OutputPipelineImpl("OutputPipelineImpl") MCPServerBin[/"MCPServerBin"/] DatasetCache[/"DatasetCache"/] @@ -98,7 +98,6 @@ graph TB RulesQueryModule["RulesQueryModule"]:::neighbor FSMValidator["FSMValidator"]:::neighbor PipelineFactory["PipelineFactory"]:::neighbor - ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor PhaseStateMachineValidation["PhaseStateMachineValidation"]:::neighbor PatternGraphAPICLI["PatternGraphAPICLI"]:::neighbor MCPServerIntegration["MCPServerIntegration"]:::neighbor @@ -107,18 +106,35 @@ graph TB DataAPIContextAssembly["DataAPIContextAssembly"]:::neighbor DataAPICLIErgonomics["DataAPICLIErgonomics"]:::neighbor DataAPIArchitectureQueries["DataAPIArchitectureQueries"]:::neighbor + CliReferenceGeneration["CliReferenceGeneration"]:::neighbor end + MCPToolRegistry -->|uses| PatternGraphAPI + MCPToolRegistry -->|uses| MCPPipelineSession + MCPToolRegistry ..->|implements| MCPServerIntegration + MCPServerImpl -->|uses| MCPPipelineSession + MCPServerImpl -->|uses| MCPToolRegistry + MCPServerImpl -->|uses| MCPFileWatcher + MCPServerImpl ..->|implements| MCPServerIntegration + MCPPipelineSession -->|uses| PipelineFactory + MCPPipelineSession -->|uses| PatternGraphAPI + MCPPipelineSession -->|uses| ConfigLoader + MCPPipelineSession ..->|implements| MCPServerIntegration + MCPModule -->|uses| MCPServerImpl + MCPModule -->|uses| MCPPipelineSession + MCPModule -->|uses| MCPFileWatcher + MCPModule -->|uses| MCPToolRegistry + MCPFileWatcher ..->|implements| MCPServerIntegration ReplMode -->|uses| PipelineFactory ReplMode -->|uses| PatternGraphAPI ReplMode ..->|implements| DataAPICLIErgonomics - ProcessAPICLIImpl -->|uses| PatternGraphAPI - ProcessAPICLIImpl -->|uses| PatternGraph - ProcessAPICLIImpl -->|uses| PipelineFactory - ProcessAPICLIImpl -->|uses| RulesQueryModule - ProcessAPICLIImpl -->|uses| PatternSummarizerImpl - ProcessAPICLIImpl -->|uses| FuzzyMatcherImpl - ProcessAPICLIImpl -->|uses| OutputPipelineImpl - ProcessAPICLIImpl ..->|implements| PatternGraphAPICLI + 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 @@ -126,7 +142,7 @@ graph TB DatasetCache -->|uses| PipelineFactory DatasetCache -->|uses| WorkflowConfigSchema DatasetCache ..->|implements| DataAPICLIErgonomics - CLISchema ..->|implements| ProcessApiHybridGeneration + CLISchema ..->|implements| CliReferenceGeneration PatternSummarizerImpl -->|uses| PatternGraphAPI PatternSummarizerImpl ..->|implements| DataAPIOutputShaping ScopeValidatorImpl -->|uses| PatternGraphAPI @@ -156,22 +172,6 @@ graph TB ArchQueriesImpl -->|uses| PatternGraphAPI ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries - MCPToolRegistry -->|uses| PatternGraphAPI - MCPToolRegistry -->|uses| MCPPipelineSession - MCPToolRegistry ..->|implements| MCPServerIntegration - MCPServerImpl -->|uses| MCPPipelineSession - MCPServerImpl -->|uses| MCPToolRegistry - MCPServerImpl -->|uses| MCPFileWatcher - MCPServerImpl ..->|implements| MCPServerIntegration - MCPPipelineSession -->|uses| PipelineFactory - MCPPipelineSession -->|uses| PatternGraphAPI - MCPPipelineSession -->|uses| ConfigLoader - MCPPipelineSession ..->|implements| MCPServerIntegration - MCPModule -->|uses| MCPServerImpl - MCPModule -->|uses| MCPPipelineSession - MCPModule -->|uses| MCPFileWatcher - MCPModule -->|uses| MCPToolRegistry - MCPFileWatcher ..->|implements| MCPServerIntegration StubResolverImpl -->|uses| PatternGraphAPI FSMValidator ..->|implements| PhaseStateMachineValidation PipelineFactory -->|uses| PatternGraph @@ -246,7 +246,7 @@ interface PipelineResult { ```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. @@ -800,19 +800,19 @@ ArchIndexSchema = z.object({ ### Process API Layered Extraction -| Rule | Invariant | Rationale | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| CLI file contains only routing, no domain logic | `process-api.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 (process-api, 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 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` 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` 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. | | +| 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. | | diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index f6f40e96..d1776b62 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -64,15 +64,15 @@ graph TB GitBranchDiff["GitBranchDiff"] SourceMapper[/"SourceMapper"/] Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") - ProcessApiReferenceGenerator["ProcessApiReferenceGenerator"] - DesignReviewGenerator("DesignReviewGenerator") - DecisionDocGenerator("DecisionDocGenerator") - CliRecipeGenerator["CliRecipeGenerator"] TransformTypes["TransformTypes"] TransformDataset("TransformDataset") SequenceTransformUtils("SequenceTransformUtils") RelationshipResolver("RelationshipResolver") ContextInferenceImpl["ContextInferenceImpl"] + DesignReviewGenerator("DesignReviewGenerator") + DecisionDocGenerator("DecisionDocGenerator") + CliReferenceGenerator["CliReferenceGenerator"] + CliRecipeGenerator["CliRecipeGenerator"] end subgraph renderer["Renderer"] loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser["loadPreambleFromMarkdown — Shared Markdown-to-SectionBlock Parser"] @@ -90,10 +90,10 @@ graph TB ShapeExtractor["ShapeExtractor"]:::neighbor PatternHelpers["PatternHelpers"]:::neighbor ReferenceDocShowcase["ReferenceDocShowcase"]:::neighbor - ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor ProceduralGuideCodec["ProceduralGuideCodec"]:::neighbor PatternRelationshipModel["PatternRelationshipModel"]:::neighbor DesignReviewGeneration["DesignReviewGeneration"]:::neighbor + CliReferenceGeneration["CliReferenceGeneration"]:::neighbor CliRecipeCodec["CliRecipeCodec"]:::neighbor ContextInference["ContextInference"]:::neighbor end @@ -110,13 +110,6 @@ graph TB DesignReviewCodec ..->|implements| DesignReviewGeneration CompositeCodec ..->|implements| ReferenceDocShowcase ArchitectureCodec -->|uses| PatternGraph - ProcessApiReferenceGenerator ..->|implements| ProcessApiHybridGeneration - DesignReviewGenerator -->|uses| DesignReviewCodec - DesignReviewGenerator -->|uses| PatternGraph - DesignReviewGenerator ..->|implements| DesignReviewGeneration - DecisionDocGenerator -.->|depends on| DecisionDocCodec - DecisionDocGenerator -.->|depends on| SourceMapper - CliRecipeGenerator ..->|implements| CliRecipeCodec TransformTypes -->|uses| PatternGraph TransformDataset -->|uses| PatternGraph TransformDataset ..->|implements| PatternRelationshipModel @@ -124,8 +117,15 @@ graph TB SequenceTransformUtils ..->|implements| DesignReviewGeneration RelationshipResolver -->|uses| PatternHelpers ContextInferenceImpl ..->|implements| ContextInference + DesignReviewGenerator -->|uses| DesignReviewCodec + DesignReviewGenerator -->|uses| PatternGraph + DesignReviewGenerator ..->|implements| DesignReviewGeneration + DecisionDocGenerator -.->|depends on| DecisionDocCodec + DecisionDocGenerator -.->|depends on| SourceMapper + CliReferenceGenerator ..->|implements| CliReferenceGeneration + CliRecipeGenerator ..->|implements| CliRecipeCodec DesignReviewGeneration -.->|depends on| MermaidDiagramUtils - CliRecipeCodec -.->|depends on| ProcessApiHybridGeneration + CliRecipeCodec -.->|depends on| CliReferenceGeneration classDef neighbor stroke-dasharray: 5 5 ``` @@ -359,7 +359,7 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; | Heading match in convention extractor handles whitespace correctly | The convention extractor's heading parser uses `matchEnd` (the character position after the full regex match) rather than `indexOf('\n',
heading.index)` to calculate where content starts after a heading. This prevents the `\s*` prefix in the heading regex from consuming leading newlines, which would cause `heading.index` to point to those newlines instead of the heading text. | Discovered during Phase 2 implementation. The heading regex `/^\s*##\s+(.+)$/gm` matches headings with optional leading whitespace. When a heading has leading newlines, `heading.index` points to the first newline (part of the `\s*` match), not the `##` character. Using `indexOf('\n', heading.index)` then finds the newline BEFORE the heading, producing content that includes the heading text itself. The fix uses the regex match's end position directly. | | Section disposition follows content-type routing | DD-3: Each ARCHITECTURE.md section is routed based on content type. Three routing strategies apply: (1) product area absorption -- sections describing a specific pipeline stage move to the corresponding product area document where they get live diagrams and relationship graphs; (2) generated shapes -- sections documenting TypeScript interfaces move to generated shape reference docs; (3) generated diagrams -- ASCII/text data flow diagrams are replaced by live Mermaid diagrams generated from architecture annotations. | The routing heuristic is: if a generated equivalent already exists, replace with pointer; if content is convention-taggable in source files, tag and generate; if editorial content that cannot be expressed as annotations, retain. This ensures each section lands in the location with the best maintenance model for its content type. | | Product area absorption validates content coverage before pointer replacement | DD-4: Product area absorption replaces ARCHITECTURE.md sections with pointers only when the target product area document already covers the equivalent content. Three sections route to product areas: Configuration Architecture (L70-139) to CONFIGURATION.md, Source Systems (L585-692) to ANNOTATION.md, and Workflow Integration (L959-1068) to PROCESS.md. Annotation format examples from Source Systems merge into the Four-Stage Pipeline retained section rather than being lost. Workflow API code examples are dropped -- Claude reads source files directly. | Product area documents are generated from annotated source code and already contain live diagrams, relationship graphs, and API types. Absorbing manual Architecture sections into these generated docs eliminates drift while preserving the content in a maintained location. The key test is: does the product area doc cover the same technical facts? If yes, the manual section becomes a 4-line pointer. | -| PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group master-dataset to extract PatternGraph schema types, RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape pattern-graph and @architect-include master-dataset contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. | The PatternGraph is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md. | +| PatternGraph shapes generate a dedicated ARCHITECTURE-TYPES reference document | DD-6: A new ReferenceDocConfig produces ARCHITECTURE-TYPES.md using shapeSelectors with group pattern-graph to extract PatternGraph schema types, RuntimePatternGraph, RawDataset, PipelineOptions, and PipelineResult. Source files tagged with @architect-shape pattern-graph contribute shapes to the reference doc. The Unified Transformation section (L345-478) is replaced with a condensed narrative (~15 lines) and pointer to ARCHITECTURE-TYPES.md. | The PatternGraph is the central data structure -- the sole read model per ADR-006. It deserves dedicated reference doc treatment alongside ARCHITECTURE-CODECS.md. Shape extraction from TypeScript declarations provides exact type signatures that stay in sync with code, unlike the manual schema table in ARCHITECTURE.md. | | Pipeline architecture convention content replaces ASCII data flow diagrams | DD-7: The Data Flow Diagrams section (L774-957) contains 4 ASCII diagrams totaling ~183 lines. These are replaced using a hybrid approach: convention tag pipeline-architecture (already registered, currently unused) on orchestrator.ts and build-pipeline.ts produces prose descriptions of pipeline steps and consumer architecture. A new pattern-graph-views hardcoded diagram source generates a Mermaid fan-out diagram showing dataset view relationships. DD-8: Both convention content and diagram source are configured on the ARCHITECTURE-TYPES.md ReferenceDocConfig, keeping all architecture reference content in one generated document. | ASCII diagrams cannot be generated from code annotations. The hybrid approach maximizes generated coverage: convention-tagged JSDoc captures the narrative (pipeline steps, ADR-006 consumer pattern) while the hardcoded diagram source produces visual Mermaid output. Using the already-registered pipeline-architecture convention tag avoids new taxonomy entries. | | Usefulness-driven editorial trimming targets Claude as primary consumer | DD-9: ARCHITECTURE.md serves Claude (primary audience) and human developers (secondary). Content retained must answer architectural "why" and "how things connect" questions. Content available via source file reads or generated reference documents is removed. Post-decomposition target: ~320 lines (~75% reduction from 1,287 lines). Sections dropped entirely: Programmatic Usage (L1070-1125) and Extending the System (L1127-1194) -- Claude reads source files directly and infers extension patterns from existing codec implementations. DD-5: Key Design Patterns section (L693-772) trimmed from ~80 to ~15 lines: Result Monad becomes a pointer to CORE-TYPES.md, Schema-First Validation becomes a 3-line summary with source pointer, Tag Registry becomes a 4-line summary with source pointer. | Claude has direct access to source files and generated reference docs. Duplicating this content in ARCHITECTURE.md wastes context window tokens. The remaining editorial sections (Executive Summary, Four-Stage Pipeline, Codec Architecture, Progressive Disclosure) provide the mental model and architectural "why" that cannot be inferred from code alone. | @@ -427,13 +427,21 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ### Cli Recipe Codec -| Rule | Invariant | Rationale | -| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `ProcessApiReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the reference generator produces `docs-live/reference/PROCESS-API-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. ProcessApiReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | -| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | -| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | -| Generated recipe file complements manual PROCESS-API.md | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/PROCESS-API-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | -| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | +| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | +| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | +| Generated recipe file complements manual PROCESS-API.md | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | +| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | + +### Cli Reference Generation + +| Rule | Invariant | Rationale | +| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/CLI-REFERENCE.md` are generated from this schema by a standalone `CliReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/pattern-graph-cli.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). | +| Narrative prose sections remain manual | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | +| Standalone generator respects ADR-006 single read model | The `CliReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | ### Codec Based Generator Testing @@ -586,7 +594,7 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; | Mermaid-sensitive text is escaped across rendered labels | Participant aliases, subgraph labels, type hexagon text, and edge labels escape Mermaid-sensitive characters such as quotes, pipes, and comment markers before rendering. | Design review diagrams are generated directly from annotations. Valid annotation text must not break Mermaid parsing when rendered into different label positions. | | Design questions table includes auto-computed metrics | The Design Questions section contains a table with auto-computed step count, type count, and error path count drawn from the SequenceIndexEntry data. | Auto-computed metrics reduce manual counting during design reviews and highlight coverage gaps (e.g., 0 error paths). | | Invalid sequence annotations are skipped with validation warnings | Patterns with ambiguous sequence-step numbering or empty sequence-module tags are excluded from sequenceIndex and reported through malformedPatterns. | Design reviews should never render misleading diagrams from malformed annotations. The transform pass is the correct place to validate and suppress bad sequence entries. | -| Process API sequence lookup resolves pattern names case-insensitively | The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented process-api queries. | Design review consumers should not need exact display-name casing when querying sequence data from the CLI. | +| Process API sequence lookup resolves pattern names case-insensitively | The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented pattern-graph queries. | Design review consumers should not need exact display-name casing when querying sequence data from the CLI. | ### Design Review Generator Lifecycle Tests @@ -763,13 +771,13 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ### Orchestrator Pipeline Factory Migration -| Rule | Invariant | Rationale | -| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Orchestrator delegates pipeline to factory | `generateDocumentation()` calls `buildPatternGraph()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`). | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit. | -| mergePatterns lives in pipeline module | The `mergePatterns()` function lives in `src/generators/pipeline/merge-patterns.ts` as a pipeline step. It is not defined in consumer code (orchestrator or CLI files). | `mergePatterns` is step 5 of the 8-step pipeline. It was defined in orchestrator.ts for historical reasons (the orchestrator was the first pipeline host). Now that the pipeline factory exists, the function belongs alongside other pipeline steps (scan, extract, transform). The public API re-export in `generators/index.ts` preserves backward compatibility. | -| Factory provides structured warnings for all consumers | `PipelineResult.warnings` contains typed warning objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers that need simple messages (process-api) read `.message` only. | The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured `GenerationWarning` objects. The factory must provide equivalent structure to eliminate the orchestrator's need to run the pipeline directly. The `PipelineWarning` type is structurally similar to `GenerationWarning` to minimize mapping complexity. | -| Pipeline factory supports partial success mode | When `failOnScanErrors` is false, the factory captures scan errors and extraction errors as warnings and continues with successfully processed files. When true (default), the factory returns `Result.err` on the first scan failure. | The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable files even if some files have syntax errors. The process-api treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration. | -| End-to-end verification confirms behavioral equivalence | After migration, all CLI commands and doc generation produce identical output to pre-refactor behavior. | The migration must not change observable behavior for any consumer. Full verification confirms the factory migration is a pure refactor. | +| Rule | Invariant | Rationale | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Orchestrator delegates pipeline to factory | `generateDocumentation()` calls `buildPatternGraph()` for the scan-extract-merge-transform sequence. It does not import from `scanner/` or `extractor/` for pipeline orchestration. Direct imports are permitted only for types used in GenerateResult (e.g., `ExtractedPattern`). | The orchestrator is the original host of the inline pipeline. After this migration, the pipeline factory is the sole definition of the 8-step sequence. Any future changes to pipeline steps (adding caching, parallel scanning, incremental extraction) happen in one place and all consumers benefit. | +| mergePatterns lives in pipeline module | The `mergePatterns()` function lives in `src/generators/pipeline/merge-patterns.ts` as a pipeline step. It is not defined in consumer code (orchestrator or CLI files). | `mergePatterns` is step 5 of the 8-step pipeline. It was defined in orchestrator.ts for historical reasons (the orchestrator was the first pipeline host). Now that the pipeline factory exists, the function belongs alongside other pipeline steps (scan, extract, transform). The public API re-export in `generators/index.ts` preserves backward compatibility. | +| Factory provides structured warnings for all consumers | `PipelineResult.warnings` contains typed warning objects with `type`, `message`, optional `count`, and optional `details` (file, line, column, message). Consumers that need granular diagnostics (orchestrator) use the full structure. Consumers that need simple messages (pattern-graph-cli) read `.message` only. | The orchestrator collects scan errors, skipped directives, extraction errors, and Gherkin parse errors as structured `GenerationWarning` objects. The factory must provide equivalent structure to eliminate the orchestrator's need to run the pipeline directly. The `PipelineWarning` type is structurally similar to `GenerationWarning` to minimize mapping complexity. | +| Pipeline factory supports partial success mode | When `failOnScanErrors` is false, the factory captures scan errors and extraction errors as warnings and continues with successfully processed files. When true (default), the factory returns `Result.err` on the first scan failure. | The orchestrator treats scan errors as non-fatal warnings — documentation generation should succeed for all scannable files even if some files have syntax errors. The pattern-graph-cli treats scan errors as fatal because the query layer requires a complete dataset. The factory must support both strategies via configuration. | +| End-to-end verification confirms behavioral equivalence | After migration, all CLI commands and doc generation produce identical output to pre-refactor behavior. | The migration must not change observable behavior for any consumer. Full verification confirms the factory migration is a pure refactor. | ### Patterns Codec Testing @@ -877,14 +885,6 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; | Decision trees render as Mermaid flowcharts | Session type decision trees and annotation workflow decision trees render as Mermaid flowchart diagrams in the detailed output level. The session type decision tree replaces the ASCII art tree in SESSION-GUIDES.md with a Mermaid `graph TD` diagram that renders as an interactive flowchart on the Starlight website. Decision tree content is authored as fenced mermaid code blocks in the markdown source file, parsed into `MermaidBlock` entries by `loadPreambleFromMarkdown()` at config load time. At summary level, decision trees render as compact text tables instead of diagrams. | The manual SESSION-GUIDES.md uses an ASCII art tree for the session decision flow, which renders poorly on the website and cannot be interacted with. Mermaid flowcharts are already supported by the Starlight website (proven by product area docs with C4Context and graph LR diagrams). Converting decision trees to Mermaid provides visual clarity, click-through navigation, and consistent rendering across platforms. The content block type `mermaid` is already one of the 9 supported SectionBlock types (proven by ReferenceDocShowcase). | | Generated guide supersedes manual only at quality parity | The manual `docs/SESSION-GUIDES.md` is retained in the repository until the generated equivalent matches or exceeds its quality across all content dimensions: completeness (all checklists present), accuracy (all FSM states current), visual clarity (decision trees render correctly), and usability (verified by comparison audit). The SessionGuidesModuleSource invariant ("not deleted, shortened, or replaced with a redirect") is respected during the transition period. The quality comparison deliverable produces an explicit audit document recording which sections have parity and which gaps remain. Only after the audit confirms full parity is the manual file replaced with a pointer to the generated output. | SESSION-GUIDES.md is cited in the SessionGuidesModuleSource spec as "the authoritative public human reference" serving developers on libar.dev. Replacing it prematurely with a generated equivalent that lacks checklists, has formatting issues, or omits edge cases would degrade the developer experience. The quality-gated approach ensures the generated version earns its place as the replacement by demonstrating equivalent or better quality, not merely by existing. This is the same principle applied by DocsConsolidationStrategy: "Manual docs retain editorial and tutorial content" until generation quality is sufficient. | -### Process Api Hybrid Generation - -| Rule | Invariant | Rationale | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/PROCESS-API-REFERENCE.md` are generated from this schema by a standalone `ProcessApiReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/process-api.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). | -| Narrative prose sections remain manual | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | -| Standalone generator respects ADR-006 single read model | The `ProcessApiReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | - ### Publishing Relocation | Rule | Invariant | Rationale | diff --git a/docs-live/reference/ARCHITECTURE-TYPES.md b/docs-live/reference/ARCHITECTURE-TYPES.md index c31dfc6d..e92ae2ee 100644 --- a/docs-live/reference/ARCHITECTURE-TYPES.md +++ b/docs-live/reference/ARCHITECTURE-TYPES.md @@ -11,7 +11,7 @@ ```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. @@ -406,7 +406,7 @@ 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. diff --git a/docs-live/reference/PROCESS-API-REFERENCE.md b/docs-live/reference/CLI-REFERENCE.md similarity index 100% rename from docs-live/reference/PROCESS-API-REFERENCE.md rename to docs-live/reference/CLI-REFERENCE.md diff --git a/docs-live/reference/PROCESS-API-RECIPES.md b/docs-live/reference/PROCESS-API-RECIPES.md index 9252b116..73d15456 100644 --- a/docs-live/reference/PROCESS-API-RECIPES.md +++ b/docs-live/reference/PROCESS-API-RECIPES.md @@ -1,6 +1,6 @@ # Process API CLI — Recipes & Workflow Guide -> Auto-generated from CLI schema. See [CLI Reference](./PROCESS-API-REFERENCE.md) for flag tables. +> Auto-generated from CLI schema. See [CLI Reference](./CLI-REFERENCE.md) for flag tables. ## Why Use This @@ -139,7 +139,7 @@ File: src/api/context-assembler.ts === CONSUMERS === ContextFormatterImpl (active) -ProcessAPICLIImpl (active) +PatternGraphCLIImpl (active) === ARCHITECTURE (context: api) === PatternGraph (completed, read-model) @@ -169,7 +169,7 @@ Example output: ``` === PRIMARY === -src/cli/process-api.ts +src/cli/pattern-graph-cli.ts === ARCHITECTURE NEIGHBORS === src/cli/version.ts diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index 4860aea7..70c51571 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -269,14 +269,14 @@ classDiagram class ContextInferenceImpl { +ContextInferenceRule interface } - class ProcessApiReferenceGenerator { - } class DesignReviewGenerator { <> } class DecisionDocGenerator { <> } + class CliReferenceGenerator { + } class CliRecipeGenerator { } class PatternGraph @@ -286,9 +286,9 @@ classDiagram class PatternHelpers class DesignReviewCodec class DecisionDocCodec - class ProcessApiHybridGeneration class PatternRelationshipModel class DesignReviewGeneration + class CliReferenceGeneration class CliRecipeCodec class ContextInference GitModule ..> GitBranchDiff : uses @@ -304,16 +304,16 @@ classDiagram SequenceTransformUtils ..|> DesignReviewGeneration : implements RelationshipResolver ..> PatternHelpers : uses ContextInferenceImpl ..|> ContextInference : implements - ProcessApiReferenceGenerator ..|> ProcessApiHybridGeneration : implements DesignReviewGenerator ..> DesignReviewCodec : uses DesignReviewGenerator ..> PatternGraph : uses DesignReviewGenerator ..|> DesignReviewGeneration : implements DecisionDocGenerator ..> DecisionDocCodec : depends on DecisionDocGenerator ..> SourceMapper : depends on + CliReferenceGenerator ..|> CliReferenceGeneration : implements CliRecipeGenerator ..|> CliRecipeCodec : implements DesignReviewCodec ..> PatternGraph : uses DesignReviewCodec ..|> DesignReviewGeneration : implements - CliRecipeCodec ..> ProcessApiHybridGeneration : depends on + CliRecipeCodec ..> CliReferenceGeneration : depends on ``` --- @@ -413,15 +413,15 @@ graph LR subgraph related["Related"] PatternGraphAPI["PatternGraphAPI"]:::neighbor TypeScriptTaxonomyImplementation["TypeScriptTaxonomyImplementation"]:::neighbor - ProcessApiHybridGeneration["ProcessApiHybridGeneration"]:::neighbor ProceduralGuideCodec["ProceduralGuideCodec"]:::neighbor PhaseStateMachineValidation["PhaseStateMachineValidation"]:::neighbor DataAPIOutputShaping["DataAPIOutputShaping"]:::neighbor DataAPIArchitectureQueries["DataAPIArchitectureQueries"]:::neighbor + CliReferenceGeneration["CliReferenceGeneration"]:::neighbor end TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - CLISchema ..->|implements| ProcessApiHybridGeneration + CLISchema ..->|implements| CliReferenceGeneration ProjectConfigTypes -->|uses| ConfigurationTypes ProjectConfigTypes -->|uses| ConfigurationPresets ConfigurationPresets -->|uses| ConfigurationTypes @@ -935,7 +935,7 @@ Design Decisions (DS-1, 2026-02-15): **Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. -**Rationale:** The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, process-api) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. +**Rationale:** The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. **Verified by:** diff --git a/docs-sources/process-api-recipes.md b/docs-sources/cli-recipes.md similarity index 100% rename from docs-sources/process-api-recipes.md rename to docs-sources/cli-recipes.md diff --git a/docs-sources/index-navigation.md b/docs-sources/index-navigation.md index 3394a261..81d71cec 100644 --- a/docs-sources/index-navigation.md +++ b/docs-sources/index-navigation.md @@ -9,7 +9,7 @@ | Understand the tag taxonomy | [TAXONOMY.md](TAXONOMY.md) | | Check validation rules | [VALIDATION-RULES.md](VALIDATION-RULES.md) | | Browse the changelog | [CHANGELOG-GENERATED.md](CHANGELOG-GENERATED.md) | -| Query process state via CLI | [Process API Reference](reference/PROCESS-API-REFERENCE.md) | +| Query process state via CLI | [Process API Reference](reference/CLI-REFERENCE.md) | | Find CLI workflow recipes | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | | Run AI coding sessions | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | @@ -37,7 +37,7 @@ 7. **[Annotation Reference](reference/ANNOTATION-REFERENCE.md)** -- Annotation mechanics and tag reference 8. **[Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md)** -- Planning, Design, Implementation workflows -9. **[Process API Reference](reference/PROCESS-API-REFERENCE.md)** -- CLI command reference with flags and examples +9. **[Process API Reference](reference/CLI-REFERENCE.md)** -- CLI command reference with flags and examples 10. **[Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md)** -- Pre-commit hooks, error codes, programmatic API --- diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e9caa55a..d897fda3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -141,7 +141,7 @@ defineConfig(userConfig) ## Four-Stage Pipeline -The pipeline has two entry points. The orchestrator (`src/generators/orchestrator.ts`) runs all 10 steps end-to-end for documentation generation. The shared pipeline factory `buildPatternGraph()` (`src/generators/pipeline/build-pipeline.ts`) runs steps 1-8 and returns a `Result` for CLI consumers like process-api and validate-patterns (see [Pipeline Factory](#pipeline-factory-adr-006)). +The pipeline has two entry points. The orchestrator (`src/generators/orchestrator.ts`) runs all 10 steps end-to-end for documentation generation. The shared pipeline factory `buildPatternGraph()` (`src/generators/pipeline/build-pipeline.ts`) runs steps 1-8 and returns a `Result` for CLI consumers like pattern-graph-cli and validate-patterns (see [Pipeline Factory](#pipeline-factory-adr-006)). ### Stage 1: Scanner @@ -212,7 +212,7 @@ interface ExtractedPattern { **Dual-Source Merging:** -After extraction, patterns from both sources are merged with conflict detection. Merge behavior varies by consumer: `'fatal'` mode (used by process-api and orchestrator) returns an error if the same pattern name exists in both TypeScript and Gherkin; `'concatenate'` mode (used by validate-patterns) falls back to concatenation on conflict, since the validator needs both sources for cross-source matching. +After extraction, patterns from both sources are merged with conflict detection. Merge behavior varies by consumer: `'fatal'` mode (used by pattern-graph-cli and orchestrator) returns an error if the same pattern name exists in both TypeScript and Gherkin; `'concatenate'` mode (used by validate-patterns) falls back to concatenation on conflict, since the validator needs both sources for cross-source matching. ### Pipeline Factory (ADR-006) @@ -1178,7 +1178,7 @@ buildPatternGraph(options) ▼ Result │ - ├── process-api CLI (mergeConflictStrategy: 'fatal') + ├── pattern-graph-cli CLI (mergeConflictStrategy: 'fatal') │ └── query handlers consume dataset │ ├── validate-patterns CLI (mergeConflictStrategy: 'concatenate') @@ -1461,7 +1461,7 @@ if (document.additionalFiles) { ```typescript import { z } from 'zod'; -import { PatternGraphSchema, type PatternGraph } from '../validation-schemas/master-dataset'; +import { PatternGraphSchema, type PatternGraph } from '../validation-schemas/pattern-graph'; import { type RenderableDocument, document, heading, paragraph } from '../renderable/schema'; import { RenderableDocumentOutputSchema } from '../renderable/codecs/shared-schema'; diff --git a/docs/DOCS-GAP-ANALYSIS.md b/docs/DOCS-GAP-ANALYSIS.md index 7d14342c..063ac083 100644 --- a/docs/DOCS-GAP-ANALYSIS.md +++ b/docs/DOCS-GAP-ANALYSIS.md @@ -113,7 +113,7 @@ generated equivalents. Work packages in this gap analysis should map to its phas | `publishing-relocation.feature` | PublishingRelocation | completed | 40 | Moved PUBLISHING.md to MAINTAINERS.md | | `codec-driven-reference-generation.feature` | CodecDrivenReferenceGeneration | completed | 27 | Foundation: config-driven codec factory | | `doc-generation-proof-of-concept.feature` | DocGenerationProofOfConcept | completed | 27 | Historical: ADR-021 POC (superseded) | -| `process-api-hybrid-generation.feature` | ProcessApiHybridGeneration | completed | 43 | CLI schema as single source for reference tables | +| `cli-reference-generation.feature` | CliReferenceGeneration | completed | 43 | CLI schema as single source for reference tables | | `claude-module-generation.feature` | ClaudeModuleGeneration | completed | 25 | Claude module tags + behavior spec sourcing | | `reference-doc-showcase.feature` | ReferenceDocShowcase | completed | 30 | All 9 content block types across 3 detail levels | | `validator-read-model-consolidation.feature` | ValidatorReadModelConsolidation | completed | 100 | PatternGraph as single read model (ADR-006) | @@ -216,17 +216,17 @@ architect/ ### What `pnpm docs:all` Generates (9 generators) -| Generator | Output Location | Files | Content | -| ----------------------- | ------------------------- | ----- | ------------------------------------------------ | -| `adrs` | docs-live/decisions/ | 8 | ADR index + 7 individual ADRs | -| `business-rules` | docs-live/business-rules/ | 8 | Overview + 7 area breakdowns (569 rules) | -| `taxonomy` | docs-live/taxonomy/ | 4 | Overview + categories, formats, metadata tags | -| `validation-rules` | docs-live/validation/ | 4 | Overview + error catalog, FSM, protection levels | -| `reference-docs` | docs-live/reference/ | 4 | Codecs, types, process-API ref, sample | -| `product-area-docs` | docs-live/product-areas/ | 8 | Overview + 7 area docs with diagrams | -| `claude-modules` | docs-live/\_claude-md/ | 10 | Compact AI context modules | -| `process-api-reference` | docs-live/reference/ | 1 | CLI command reference | -| `cli-recipe` | docs-live/reference/ | 1 | CLI recipes & workflow guide | +| Generator | Output Location | Files | Content | +| ------------------- | ------------------------- | ----- | ------------------------------------------------ | +| `adrs` | docs-live/decisions/ | 8 | ADR index + 7 individual ADRs | +| `business-rules` | docs-live/business-rules/ | 8 | Overview + 7 area breakdowns (569 rules) | +| `taxonomy` | docs-live/taxonomy/ | 4 | Overview + categories, formats, metadata tags | +| `validation-rules` | docs-live/validation/ | 4 | Overview + error catalog, FSM, protection levels | +| `reference-docs` | docs-live/reference/ | 4 | Codecs, types, process-API ref, sample | +| `product-area-docs` | docs-live/product-areas/ | 8 | Overview + 7 area docs with diagrams | +| `claude-modules` | docs-live/\_claude-md/ | 10 | Compact AI context modules | +| `cli-reference` | docs-live/reference/ | 1 | CLI command reference | +| `cli-recipe` | docs-live/reference/ | 1 | CLI recipes & workflow guide | ### What `pnpm docs:all-preview` Adds (14 more generators) @@ -301,17 +301,17 @@ reference content from `docs-live/` instead of `docs-generated/`. These `docs-live/` subdirectories exist but have no sync function: -| Directory | Files | Content | -| ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | -| `docs-live/reference/` | 5 files | ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, PROCESS-API-REFERENCE.md, REFERENCE-SAMPLE.md | -| `docs-live/taxonomy/` | 3 files | categories.md, format-types.md, metadata-tags.md | -| `docs-live/validation/` | 3 files | error-catalog.md, fsm-transitions.md, protection-levels.md | -| `docs-live/business-rules/` | 7 files | Per-area business rule extractions | -| `docs-live/_claude-md/` | 10 files | AI context (may not need website publishing) | -| `docs-live/INDEX.md` | 1 file | Generated docs master index | -| `docs-live/TAXONOMY.md` | 1 file | Taxonomy overview | -| `docs-live/VALIDATION-RULES.md` | 1 file | Validation rules overview | -| `docs-live/BUSINESS-RULES.md` | 1 file | Business rules overview | +| Directory | Files | Content | +| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | +| `docs-live/reference/` | 5 files | ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md | +| `docs-live/taxonomy/` | 3 files | categories.md, format-types.md, metadata-tags.md | +| `docs-live/validation/` | 3 files | error-catalog.md, fsm-transitions.md, protection-levels.md | +| `docs-live/business-rules/` | 7 files | Per-area business rule extractions | +| `docs-live/_claude-md/` | 10 files | AI context (may not need website publishing) | +| `docs-live/INDEX.md` | 1 file | Generated docs master index | +| `docs-live/TAXONOMY.md` | 1 file | Taxonomy overview | +| `docs-live/VALIDATION-RULES.md` | 1 file | Validation rules overview | +| `docs-live/BUSINESS-RULES.md` | 1 file | Business rules overview | --- @@ -334,7 +334,7 @@ These `docs-live/` subdirectories exist but have no sync function: | **ARCHITECTURE.md** | 1,638 | docs-live/product-areas/GENERATION.md (1,065 lines) + docs-live/reference/ARCHITECTURE-CODECS.md (630 lines) + docs-live/reference/ARCHITECTURE-TYPES.md (429 lines) | Partial | Generated covers pipeline stages and codec listings well. Missing: executive summary, data flow diagrams, workflow integration section, "Extending the System" guide, programmatic usage examples, quick reference card. | | **GHERKIN-PATTERNS.md** | 366 | None | None | Authoring style guide: 4 essential patterns, DataTable/DocString usage, tag conventions, feature file rich content rules, step linting reference. Pure editorial guidance -- no annotation source exists. | | **ANNOTATION-GUIDE.md** | 270 | docs-live/taxonomy/metadata-tags.md (649 lines) | Partial | Generated has exhaustive tag reference (56 tags). Missing: getting-started guide, shape extraction modes explanation, "Zod schema gotcha" documentation, verification steps, common issues troubleshooting table. | -| **PROCESS-API.md** | ~60 | docs-live/reference/PROCESS-API-REFERENCE.md + PROCESS-API-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | +| **PROCESS-API.md** | ~60 | docs-live/reference/CLI-REFERENCE.md + PROCESS-API-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | | **PROCESS-GUARD.md** | 341 | docs-live/validation/error-catalog.md (79 lines) + docs-live/validation/fsm-transitions.md (49 lines) + docs-live/validation/protection-levels.md | Partial | Generated has error types, FSM matrix, protection levels. Missing: error fix rationale ("why this rule exists"), escape hatch alternatives, pre-commit setup instructions (Husky), programmatic API guide, Decider pattern architecture diagram. | | **VALIDATION.md** | 418 | docs-live/product-areas/VALIDATION.md (1,115 lines) | Partial | Generated has pattern listings and business rules. Missing: "Which command do I run?" decision tree, 32+ individual lint rule explanations with code examples, anti-pattern detection rationale, CI/CD integration patterns (GitHub Actions YAML), vitest-cucumber two-pattern problem explanation. | | **TAXONOMY.md** | 107 | docs-live/TAXONOMY.md (199 lines) + docs-live/taxonomy/ (3 files) | Good | Generated taxonomy reference is actually more comprehensive than manual. Manual adds: architecture explanation (file structure of src/taxonomy/), preset-to-taxonomy mapping, generation commands. Small gap. | @@ -559,7 +559,7 @@ This replaces the manual PROCESS-GUARD.md "Error Messages and Fixes" section. **Type:** Design + Implementation **Scope:** architect repo **Effort:** Medium (2-3 sessions) -**Spec alignment:** Extends ProcessApiHybridGeneration (Phase 43, completed). Phase 43 +**Spec alignment:** Extends CliReferenceGeneration (Phase 43, completed). Phase 43 generated reference tables from CLI schema; this adds recipe/guide content. The manual PROCESS-API.md prose was explicitly kept in Phase 43 -- this WP addresses that remainder. @@ -573,7 +573,7 @@ This replaces manual PROCESS-API.md "Common Recipes" and "Session Workflow Comma **Design questions for session:** -- Extend `ProcessApiReferenceGenerator` or create separate recipe generator? +- Extend `CliReferenceGenerator` or create separate recipe generator? - Where should recipe annotations live? (CLI schema? Feature files? New recipe files?) - How to handle "Why Use This" motivational prose? (Preamble?) @@ -736,7 +736,7 @@ ProceduralGuideCodec) have completed design sessions with findings and code stub load time by a shared `loadPreambleFromMarkdown()` utility (DD-7/DD-8). - **ErrorGuideCodec** extends the existing `ValidationRulesCodec` with a new `includeErrorGuide` toggle and convention-tagged annotations on `src/lint/` source. -- **CliRecipeCodec** creates a sibling `CliRecipeGenerator` to `ProcessApiReferenceGenerator`, +- **CliRecipeCodec** creates a sibling `CliRecipeGenerator` to `CliReferenceGenerator`, both standalone `DocumentGenerator` implementations consuming `CLI_SCHEMA` directly. - **EnhancedIndexGeneration** creates a new `IndexCodec` registered in `CodecRegistry`, composing PatternGraph-driven statistics with editorial preamble navigation content. @@ -782,7 +782,7 @@ adr-001 through adr-006, adr-021 annotation.md, configuration.md, core-types.md, data-api.md, generation.md, process.md, validation.md **Reference (5 files):** -ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, PROCESS-API-REFERENCE.md, REFERENCE-SAMPLE.md +ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md **Taxonomy (3 files):** categories.md, format-types.md, metadata-tags.md @@ -806,6 +806,6 @@ error-catalog.md, fsm-transitions.md, protection-levels.md ### D. Codec Inventory (22 total) -**In docs:all (9):** adrs, business-rules, taxonomy, validation-rules, reference-docs, product-area-docs, claude-modules, process-api-reference, cli-recipe +**In docs:all (9):** adrs, business-rules, taxonomy, validation-rules, reference-docs, product-area-docs, claude-modules, cli-reference, cli-recipe **In docs:all-preview only (14):** patterns, roadmap, milestones, requirements, session, remaining, current, session-plan, session-findings, pr-changes, changelog, traceability, architecture, overview-rdm diff --git a/docs/PROCESS-API.md b/docs/PROCESS-API.md index 5fa758d5..12331a40 100644 --- a/docs/PROCESS-API.md +++ b/docs/PROCESS-API.md @@ -1,6 +1,6 @@ # Data API CLI -> **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/PROCESS-API-REFERENCE.md) and [Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes). +> **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md) and [Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes). > > Query process state directly from annotated source code. @@ -17,7 +17,7 @@ > This document retains operational reference (JSON envelope, exit codes, piping). > For full CLI documentation, see the generated references below. -- **[CLI Reference Tables](../docs-live/reference/PROCESS-API-REFERENCE.md)** — all flags, options, filters, and modifiers +- **[CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md)** — all flags, options, filters, and modifiers - **[Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md)** — command descriptions, usage examples, and common recipes --- @@ -58,8 +58,8 @@ On error: ### JSON Piping -`pnpm` outputs a banner line to stdout (`> @libar-dev/...`). For clean JSON piping, use `npx tsx src/cli/process-api.ts` directly: +`pnpm` outputs a banner line to stdout (`> @libar-dev/...`). For clean JSON piping, use `npx tsx src/cli/pattern-graph-cli.ts` directly: ```bash -npx tsx src/cli/process-api.ts list --status roadmap --names-only | jq '.data[]' +npx tsx src/cli/pattern-graph-cli.ts list --status roadmap --names-only | jq '.data[]' ``` diff --git a/package.json b/package.json index b9782750..0a643dd3 100644 --- a/package.json +++ b/package.json @@ -63,7 +63,7 @@ } }, "bin": { - "architect": "./dist/cli/process-api.js", + "architect": "./dist/cli/pattern-graph-cli.js", "architect-generate": "./dist/cli/generate-docs.js", "architect-lint-patterns": "./dist/cli/lint-patterns.js", "architect-guard": "./dist/cli/lint-process.js", @@ -104,14 +104,14 @@ "docs:reference": "tsx src/cli/generate-docs.ts -g reference-docs", "docs:product-areas": "tsx src/cli/generate-docs.ts -g product-area-docs", "docs:claude-modules": "tsx src/cli/generate-docs.ts -g claude-modules", - "docs:process-api-reference": "tsx src/cli/generate-docs.ts -g process-api-reference", + "docs:cli-reference": "tsx src/cli/generate-docs.ts -g cli-reference", "docs:cli-recipe": "tsx src/cli/generate-docs.ts -g cli-recipe", "docs:index": "tsx src/cli/generate-docs.ts -g index", "docs:design-review": "tsx src/cli/generate-docs.ts -g design-review", - "docs:all": "pnpm docs:decisions && pnpm docs:product-areas && pnpm docs:taxonomy && pnpm docs:business-rules && pnpm docs:validation && pnpm docs:reference && pnpm docs:claude-modules && pnpm docs:process-api-reference && pnpm docs:cli-recipe && pnpm docs:architecture && pnpm docs:changelog && pnpm docs:design-review && pnpm docs:index", + "docs:all": "pnpm docs:decisions && pnpm docs:product-areas && pnpm docs:taxonomy && pnpm docs:business-rules && pnpm docs:validation && pnpm docs:reference && pnpm docs:claude-modules && pnpm docs:cli-reference && pnpm docs:cli-recipe && pnpm docs:architecture && pnpm docs:changelog && pnpm docs:design-review && pnpm docs:index", "docs:all-preview": "pnpm docs:patterns && pnpm docs:roadmap && pnpm docs:remaining && pnpm docs:changelog && pnpm docs:architecture && pnpm docs:decisions && pnpm docs:reference && pnpm docs:product-areas && pnpm docs:taxonomy && pnpm docs:validation && pnpm docs:requirements && pnpm docs:current && pnpm docs:milestones && pnpm docs:business-rules", - "architect:query": "tsx src/cli/process-api.ts", - "architect:q": "tsx src/cli/process-api.ts", + "architect:query": "tsx src/cli/pattern-graph-cli.ts", + "architect:q": "tsx src/cli/pattern-graph-cli.ts", "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{json,md,yml}\"", "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{json,md,yml}\"", "preversion": "pnpm test && pnpm typecheck && pnpm lint && pnpm format:check", diff --git a/src/api/arch-queries.ts b/src/api/arch-queries.ts index 1c7d7dd0..c2a87d8d 100644 --- a/src/api/arch-queries.ts +++ b/src/api/arch-queries.ts @@ -4,7 +4,7 @@ * @architect-status active * @architect-implements DataAPIArchitectureQueries * @architect-uses PatternGraphAPI, PatternGraph - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer domain diff --git a/src/api/context-assembler.ts b/src/api/context-assembler.ts index 7d4c8512..79fe2e58 100644 --- a/src/api/context-assembler.ts +++ b/src/api/context-assembler.ts @@ -4,7 +4,7 @@ * @architect-status active * @architect-implements DataAPIContextAssembly * @architect-uses PatternGraphAPI, PatternGraph, PatternSummarizerImpl, FuzzyMatcherImpl, StubResolverImpl - * @architect-used-by ProcessAPICLIImpl, ContextFormatterImpl + * @architect-used-by PatternGraphCLIImpl, ContextFormatterImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application diff --git a/src/api/context-formatter.ts b/src/api/context-formatter.ts index 5017d7dc..99e0d8c3 100644 --- a/src/api/context-formatter.ts +++ b/src/api/context-formatter.ts @@ -4,7 +4,7 @@ * @architect-status active * @architect-implements DataAPIContextAssembly * @architect-uses ContextAssemblerImpl - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application diff --git a/src/api/coverage-analyzer.ts b/src/api/coverage-analyzer.ts index ded77944..d041657c 100644 --- a/src/api/coverage-analyzer.ts +++ b/src/api/coverage-analyzer.ts @@ -4,7 +4,7 @@ * @architect-status active * @architect-implements DataAPIArchitectureQueries * @architect-uses Pattern Scanner, PatternGraph - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application diff --git a/src/api/fuzzy-match.ts b/src/api/fuzzy-match.ts index 51c790c3..7d29e641 100644 --- a/src/api/fuzzy-match.ts +++ b/src/api/fuzzy-match.ts @@ -4,7 +4,7 @@ * @architect-pattern FuzzyMatcherImpl * @architect-status active * @architect-implements DataAPIOutputShaping - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application diff --git a/src/api/handoff-generator.ts b/src/api/handoff-generator.ts index 17f68986..cf86978c 100644 --- a/src/api/handoff-generator.ts +++ b/src/api/handoff-generator.ts @@ -4,7 +4,7 @@ * @architect-status completed * @architect-implements DataAPIDesignSessionSupport * @architect-uses PatternGraphAPI, PatternGraph, ContextFormatterImpl - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/handoff-generator.ts * @architect-arch-role service * @architect-arch-context api diff --git a/src/api/scope-validator.ts b/src/api/scope-validator.ts index 6126f17a..137c6075 100644 --- a/src/api/scope-validator.ts +++ b/src/api/scope-validator.ts @@ -4,7 +4,7 @@ * @architect-status completed * @architect-implements DataAPIDesignSessionSupport * @architect-uses PatternGraphAPI, PatternGraph, StubResolverImpl - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-target src/api/scope-validator.ts * @architect-arch-role service * @architect-arch-context api diff --git a/src/api/stub-resolver.ts b/src/api/stub-resolver.ts index 1fac459b..bbc462d5 100644 --- a/src/api/stub-resolver.ts +++ b/src/api/stub-resolver.ts @@ -4,7 +4,7 @@ * @architect-status active * @architect-implements DataAPIStubIntegration * @architect-uses PatternGraphAPI - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * * ## StubResolver — Design Stub Discovery and Resolution * diff --git a/src/api/summarize.ts b/src/api/summarize.ts index e4e4c765..7c0ac7e1 100644 --- a/src/api/summarize.ts +++ b/src/api/summarize.ts @@ -5,7 +5,7 @@ * @architect-status active * @architect-implements DataAPIOutputShaping * @architect-uses PatternGraphAPI - * @architect-used-by OutputPipeline, ProcessAPICLIImpl + * @architect-used-by OutputPipeline, PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context api * @architect-arch-layer application diff --git a/src/api/types.ts b/src/api/types.ts index 897e652e..38fe6089 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -1,7 +1,7 @@ /** * @architect * @architect-core - * @architect-pattern ProcessStateTypes + * @architect-pattern PatternGraphAPITypes * @architect-status active * @architect-depends-on:PatternGraph * diff --git a/src/cli/cli-schema.ts b/src/cli/cli-schema.ts index 06d990b5..dbed7f56 100644 --- a/src/cli/cli-schema.ts +++ b/src/cli/cli-schema.ts @@ -3,7 +3,7 @@ * @architect-pattern CLISchema * @architect-status completed * @architect-unlock-reason:Add-recipe-and-narrative-fields-for-CliRecipeCodec - * @architect-implements ProcessApiHybridGeneration + * @architect-implements CliReferenceGeneration * @architect-arch-context cli * @architect-arch-layer domain * @architect-product-area:DataAPI @@ -12,8 +12,8 @@ * * Declarative schema defining all CLI options for the architect command. * Consumed by: - * - `showHelp()` in process-api.ts (terminal help text) - * - `ProcessApiReferenceGenerator` (generated markdown reference) + * - `showHelp()` in pattern-graph-cli.ts (terminal help text) + * - `CliReferenceGenerator` (generated markdown reference) * * This eliminates three-way sync between parser code, help text, and docs. */ @@ -295,7 +295,7 @@ export const CLI_SCHEMA: CLISchema = { '', '=== CONSUMERS ===', 'ContextFormatterImpl (active)', - 'ProcessAPICLIImpl (active)', + 'PatternGraphCLIImpl (active)', '', '=== ARCHITECTURE (context: api) ===', 'PatternGraph (completed, read-model)', @@ -318,7 +318,7 @@ export const CLI_SCHEMA: CLISchema = { usageExample: 'pnpm architect:query -- files MyPattern --related', expectedOutput: [ '=== PRIMARY ===', - 'src/cli/process-api.ts', + 'src/cli/pattern-graph-cli.ts', '', '=== ARCHITECTURE NEIGHBORS ===', 'src/cli/version.ts', diff --git a/src/cli/output-pipeline.ts b/src/cli/output-pipeline.ts index d6f2027a..543a53ff 100644 --- a/src/cli/output-pipeline.ts +++ b/src/cli/output-pipeline.ts @@ -5,7 +5,7 @@ * @architect-status active * @architect-implements DataAPIOutputShaping * @architect-uses PatternSummarizerImpl - * @architect-used-by ProcessAPICLIImpl + * @architect-used-by PatternGraphCLIImpl * @architect-arch-role service * @architect-arch-context cli * @architect-arch-layer application diff --git a/src/cli/process-api.ts b/src/cli/pattern-graph-cli.ts similarity index 99% rename from src/cli/process-api.ts rename to src/cli/pattern-graph-cli.ts index f9306cf4..7334cdb5 100644 --- a/src/cli/process-api.ts +++ b/src/cli/pattern-graph-cli.ts @@ -2,7 +2,7 @@ /** * @architect * @architect-core @architect-cli - * @architect-pattern ProcessAPICLIImpl + * @architect-pattern PatternGraphCLIImpl * @architect-status active * @architect-implements PatternGraphAPICLI * @architect-arch-role service @@ -143,7 +143,7 @@ import type { RulesFilters } from '../api/rules-query.js'; // CLI Config // ============================================================================= -interface ProcessAPICLIConfig { +interface PatternGraphCLIConfig { input: string[]; features: string[]; baseDir: string; @@ -166,7 +166,7 @@ interface ProcessAPICLIConfig { /** Mutable state accumulated during argument parsing. */ interface ParseState { - readonly config: ProcessAPICLIConfig; + readonly config: PatternGraphCLIConfig; namesOnly: boolean; count: boolean; fields: string[] | null; @@ -305,7 +305,7 @@ function handlePositionalArg(state: ParseState, arg: string): void { } } -function parseArgs(argv: string[] = process.argv.slice(2)): ProcessAPICLIConfig { +function parseArgs(argv: string[] = process.argv.slice(2)): PatternGraphCLIConfig { const state: ParseState = { config: { input: [], @@ -596,7 +596,7 @@ function getSubcommandOptionGroups(subcommand: string): readonly string[] { /** * Execute dry-run: show pipeline scope (files, config, cache) without processing. */ -async function executeDryRun(opts: ProcessAPICLIConfig): Promise { +async function executeDryRun(opts: PatternGraphCLIConfig): Promise { const baseDir = path.resolve(opts.baseDir); // Resolve globs to file lists @@ -640,7 +640,7 @@ async function executeDryRun(opts: ProcessAPICLIConfig): Promise { * Prefers loadProjectConfig() for repos with a project config file, * falls back to filesystem auto-detection for repos without one. */ -async function applyConfigDefaults(config: ProcessAPICLIConfig): Promise { +async function applyConfigDefaults(config: PatternGraphCLIConfig): Promise { const applied = await applyProjectSourceDefaults(config); if (applied) { return; @@ -654,7 +654,7 @@ async function applyConfigDefaults(config: ProcessAPICLIConfig): Promise { * Filesystem-based auto-detection fallback for repos without a config file. * Checks for conventional directory structures and applies defaults. */ -async function applyConfigDefaultsFallback(config: ProcessAPICLIConfig): Promise { +async function applyConfigDefaultsFallback(config: PatternGraphCLIConfig): Promise { const baseDir = path.resolve(config.baseDir); if (config.input.length === 0) { @@ -692,7 +692,7 @@ function formatConfigStatus(configPath: string | null): string { // Pipeline // ============================================================================= -async function buildPipeline(config: ProcessAPICLIConfig): Promise { +async function buildPipeline(config: PatternGraphCLIConfig): Promise { const result = await buildPatternGraph({ input: config.input, features: config.features, diff --git a/src/generators/built-in/cli-recipe-generator.ts b/src/generators/built-in/cli-recipe-generator.ts index 077cf95a..4790d528 100644 --- a/src/generators/built-in/cli-recipe-generator.ts +++ b/src/generators/built-in/cli-recipe-generator.ts @@ -9,7 +9,7 @@ * ## Standalone Generator for CLI Recipes and Command Narratives * * Generates `PROCESS-API-RECIPES.md` from the declarative CLI schema. - * Sibling to `ProcessApiReferenceGenerator` — both implement + * Sibling to `CliReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends * on PatternGraph (ADR-006 compliant). * @@ -119,7 +119,7 @@ function buildRecipeDocument(preamble: readonly SectionBlock[]): string { // 1. Auto-generation notice sections.push( paragraph( - '> Auto-generated from CLI schema. See [CLI Reference](./PROCESS-API-REFERENCE.md) for flag tables.' + '> Auto-generated from CLI schema. See [CLI Reference](./CLI-REFERENCE.md) for flag tables.' ) ); diff --git a/src/generators/built-in/process-api-reference-generator.ts b/src/generators/built-in/cli-reference-generator.ts similarity index 88% rename from src/generators/built-in/process-api-reference-generator.ts rename to src/generators/built-in/cli-reference-generator.ts index 8ddfebe2..a1472062 100644 --- a/src/generators/built-in/process-api-reference-generator.ts +++ b/src/generators/built-in/cli-reference-generator.ts @@ -1,15 +1,15 @@ /** * @architect - * @architect-pattern ProcessApiReferenceGenerator + * @architect-pattern CliReferenceGenerator * @architect-status completed - * @architect-implements ProcessApiHybridGeneration + * @architect-implements CliReferenceGeneration * @architect-arch-context generator * @architect-arch-layer application * @architect-product-area:Generation * * ## Standalone Generator for Process API CLI Reference * - * Generates `PROCESS-API-REFERENCE.md` from the declarative CLI schema. + * Generates `CLI-REFERENCE.md` from the declarative CLI schema. * Does NOT consume PatternGraph (ADR-006 compliant — CLI schema is static * TypeScript, not annotation-derived data). */ @@ -90,8 +90,8 @@ function buildReferenceDocument(): string { // Generator // ============================================================================= -class ProcessApiReferenceGeneratorImpl implements DocumentGenerator { - readonly name = 'process-api-reference'; +class CliReferenceGeneratorImpl implements DocumentGenerator { + readonly name = 'cli-reference'; readonly description = 'Generate CLI reference tables from declarative schema'; generate(_patterns: readonly unknown[], _context: GeneratorContext): Promise { @@ -100,7 +100,7 @@ class ProcessApiReferenceGeneratorImpl implements DocumentGenerator { return Promise.resolve({ files: [ { - path: 'reference/PROCESS-API-REFERENCE.md', + path: 'reference/CLI-REFERENCE.md', content, }, ], @@ -108,6 +108,6 @@ class ProcessApiReferenceGeneratorImpl implements DocumentGenerator { } } -export function createProcessApiReferenceGenerator(): DocumentGenerator { - return new ProcessApiReferenceGeneratorImpl(); +export function createCliReferenceGenerator(): DocumentGenerator { + return new CliReferenceGeneratorImpl(); } diff --git a/src/generators/built-in/codec-generators.ts b/src/generators/built-in/codec-generators.ts index 37ae8b98..382b8fb2 100644 --- a/src/generators/built-in/codec-generators.ts +++ b/src/generators/built-in/codec-generators.ts @@ -3,7 +3,7 @@ * @architect-core * @architect-pattern CodecGeneratorRegistration * @architect-status completed - * @architect-uses DesignReviewGenerator, DecisionDocGenerator, ProcessApiReferenceGenerator, CliRecipeGenerator + * @architect-uses DesignReviewGenerator, DecisionDocGenerator, CliReferenceGenerator, CliRecipeGenerator * * ## Codec-Based Generator Registration * @@ -30,7 +30,7 @@ import { generatorRegistry } from '../registry.js'; import { createCodecGenerator } from '../codec-based.js'; import { createDecisionDocGenerator } from './decision-doc-generator.js'; import { createDesignReviewGenerator } from './design-review-generator.js'; -import { createProcessApiReferenceGenerator } from './process-api-reference-generator.js'; +import { createCliReferenceGenerator } from './cli-reference-generator.js'; import { createCliRecipeGenerator } from './cli-recipe-generator.js'; import { loadPreambleFromMarkdown } from '../../renderable/load-preamble.js'; import type { SectionBlock } from '../../renderable/schema.js'; @@ -194,10 +194,10 @@ generatorRegistry.register(createDesignReviewGenerator()); /** * Process API CLI Reference Generator - * Generates PROCESS-API-REFERENCE.md from declarative CLI schema. + * Generates CLI-REFERENCE.md from declarative CLI schema. * Standalone: does not consume PatternGraph (ADR-006). */ -generatorRegistry.register(createProcessApiReferenceGenerator()); +generatorRegistry.register(createCliReferenceGenerator()); // ═══════════════════════════════════════════════════════════════════════════ // CLI Recipe Generator (Schema-Based, not Codec-Based) @@ -210,7 +210,7 @@ generatorRegistry.register(createProcessApiReferenceGenerator()); */ let cliRecipePreamble: readonly SectionBlock[] = []; try { - cliRecipePreamble = loadPreambleFromMarkdown('docs-sources/process-api-recipes.md'); + cliRecipePreamble = loadPreambleFromMarkdown('docs-sources/cli-recipes.md'); } catch { // Preamble file may not exist in test environments (e.g., CLI integration tests // that run generate-docs in a temp directory). Fall back to empty preamble. diff --git a/src/generators/pipeline/build-pipeline.ts b/src/generators/pipeline/build-pipeline.ts index cc9878d9..e5422f09 100644 --- a/src/generators/pipeline/build-pipeline.ts +++ b/src/generators/pipeline/build-pipeline.ts @@ -25,7 +25,7 @@ * * ## 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. diff --git a/src/renderable/codecs/index-codec.ts b/src/renderable/codecs/index-codec.ts index a3975479..00fe7874 100644 --- a/src/renderable/codecs/index-codec.ts +++ b/src/renderable/codecs/index-codec.ts @@ -400,7 +400,7 @@ function buildRegenerationFooter(context: CodecContext): SectionBlock[] { 'pnpm docs:taxonomy # Taxonomy reference', 'pnpm docs:validation # Validation rules', 'pnpm docs:claude-modules # Claude context modules', - 'pnpm docs:process-api-reference # Process API CLI reference', + 'pnpm docs:cli-reference # Process API CLI reference', 'pnpm docs:cli-recipe # CLI recipes & workflow guide', ].join('\n'), 'bash' diff --git a/src/validation-schemas/index.ts b/src/validation-schemas/index.ts index ab98bd33..f75de70f 100644 --- a/src/validation-schemas/index.ts +++ b/src/validation-schemas/index.ts @@ -172,7 +172,7 @@ export { type RegistryMetadataOutput, } from './output-schemas.js'; -// Master Dataset schemas and types (unified transformation pipeline) +// Pattern Graph schemas and types (unified transformation pipeline) export { StatusGroupsSchema, StatusCountsSchema, diff --git a/src/validation-schemas/pattern-graph.ts b/src/validation-schemas/pattern-graph.ts index 50cc9d62..4eaefcf5 100644 --- a/src/validation-schemas/pattern-graph.ts +++ b/src/validation-schemas/pattern-graph.ts @@ -251,11 +251,11 @@ export const SequenceIndexEntrySchema = z.object({ export const SequenceIndexSchema = z.record(z.string().trim().min(1), SequenceIndexEntrySchema); // ═══════════════════════════════════════════════════════════════════════════ -// Master Dataset Schema +// Pattern Graph Schema // ═══════════════════════════════════════════════════════════════════════════ /** - * 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. diff --git a/tests/features/behavior/cli/process-api-reference.feature b/tests/features/behavior/cli/cli-reference.feature similarity index 90% rename from tests/features/behavior/cli/process-api-reference.feature rename to tests/features/behavior/cli/cli-reference.feature index 9ba25f04..6220434a 100644 --- a/tests/features/behavior/cli/process-api-reference.feature +++ b/tests/features/behavior/cli/cli-reference.feature @@ -1,10 +1,10 @@ @architect @architect-pattern:ProcessApiReferenceTests -@architect-implements:ProcessApiHybridGeneration +@architect-implements:CliReferenceGeneration @architect-status:completed @architect-unlock-reason:Retroactive-completion-during-rebrand @architect-product-area:DataAPI -@behavior @cli @process-api-reference +@behavior @cli @cli-reference Feature: Process API CLI Reference Generation Verifies that the declarative CLI schema drives reference table generation @@ -12,13 +12,13 @@ Feature: Process API CLI Reference Generation Rule: Generated reference file contains all three table sections - **Invariant:** PROCESS-API-REFERENCE.md contains Global Options, Output Modifiers, + **Invariant:** CLI-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema. @acceptance-criteria @happy-path Scenario: Generated file contains Global Options table Given the CLI schema is loaded - When the ProcessApiReferenceGenerator produces output + When the CliReferenceGenerator produces output Then the output contains a "Global Options" heading And the output contains a table with columns "Flag", "Short", "Description", "Default" And the table has 6 rows for global options @@ -26,7 +26,7 @@ Feature: Process API CLI Reference Generation @acceptance-criteria @happy-path Scenario: Generated file contains Output Modifiers table Given the CLI schema is loaded - When the ProcessApiReferenceGenerator produces output + When the CliReferenceGenerator produces output Then the output contains an "Output Modifiers" heading And the output contains a table with columns "Output Modifier", "Description" And the table has 5 rows for output modifiers @@ -34,7 +34,7 @@ Feature: Process API CLI Reference Generation @acceptance-criteria @happy-path Scenario: Generated file contains List Filters table Given the CLI schema is loaded - When the ProcessApiReferenceGenerator produces output + When the CliReferenceGenerator produces output Then the output contains a "List Filters" heading And the output contains a table with columns "List Filter", "Description" And the table has 8 rows for list filters @@ -42,7 +42,7 @@ Feature: Process API CLI Reference Generation @acceptance-criteria @happy-path Scenario: Generated file includes inter-table prose Given the CLI schema is loaded - When the ProcessApiReferenceGenerator produces output + When the CliReferenceGenerator produces output Then the output contains the following prose fragments: | fragment | | Config auto-detection | diff --git a/tests/features/behavior/codecs/reference-generators.feature b/tests/features/behavior/codecs/reference-generators.feature index 30a9a939..0af551af 100644 --- a/tests/features/behavior/codecs/reference-generators.feature +++ b/tests/features/behavior/codecs/reference-generators.feature @@ -85,7 +85,7 @@ Feature: Reference Document Generator Registration @integration Scenario: ARCHITECTURE-TYPES generator produces shapes and convention content - Given a PatternGraph with pipeline architecture conventions and master dataset shapes + Given a PatternGraph with pipeline architecture conventions and pattern graph shapes When running the "architecture-types-reference" generator Then the output has 1 file And the output file path starts with "reference/" diff --git a/tests/features/behavior/context-inference.feature b/tests/features/behavior/context-inference.feature index 10df2fb8..8626c52d 100644 --- a/tests/features/behavior/context-inference.feature +++ b/tests/features/behavior/context-inference.feature @@ -31,7 +31,7 @@ Feature: Context Auto-Inference from File Paths Scenario Outline: Recursive wildcard matches nested paths Given a pattern rule "" for context "test-context" And a pattern at file path "" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "" Examples: @@ -56,7 +56,7 @@ Feature: Context Auto-Inference from File Paths Scenario Outline: Single-level wildcard matches direct children only Given a pattern rule "" for context "test-context" And a pattern at file path "" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "" Examples: @@ -79,7 +79,7 @@ Feature: Context Auto-Inference from File Paths Scenario Outline: Prefix matching behavior Given a pattern rule "" for context "test-context" And a pattern at file path "" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "" Examples: @@ -101,7 +101,7 @@ Feature: Context Auto-Inference from File Paths Scenario: Empty rules array returns undefined Given no context inference rules And a pattern at file path "src/unknown/file.ts" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern has no inferred archContext And the pattern is not in archIndex byContext @@ -109,7 +109,7 @@ Feature: Context Auto-Inference from File Paths Scenario: File path does not match any rule Given default context inference rules And a pattern at file path "unknown/path/file.ts" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern has no inferred archContext And the pattern is not in archIndex byContext @@ -127,7 +127,7 @@ Feature: Context Auto-Inference from File Paths Scenario: Single matching rule infers context Given default context inference rules And a pattern at file path "src/validation/rules.ts" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "validation" And the pattern appears in archIndex byContext under "validation" @@ -138,7 +138,7 @@ Feature: Context Auto-Inference from File Paths | src/validation/** | validation | | src/** | general | And a pattern at file path "src/validation/rules.ts" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "validation" # ═══════════════════════════════════════════════════════════════════════════ @@ -155,7 +155,7 @@ Feature: Context Auto-Inference from File Paths Scenario: Explicit context takes precedence over inference Given default context inference rules And a pattern at file path "src/validation/rules.ts" with archLayer "application" and archContext "custom" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "custom" And the pattern appears in archIndex byContext under "custom" @@ -173,7 +173,7 @@ Feature: Context Auto-Inference from File Paths Scenario: Pattern without archLayer is still added to byContext if context is inferred Given default context inference rules And a pattern at file path "src/validation/rules.ts" without archLayer - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern is in archIndex all And the pattern appears in archIndex byContext under "validation" @@ -191,7 +191,7 @@ Feature: Context Auto-Inference from File Paths Scenario Outline: Default directory mappings Given default context inference rules And a pattern at file path "" with archLayer "application" - When transforming to master dataset with rules + When transforming to pattern graph with rules Then the pattern archContext should be "" Examples: diff --git a/tests/features/cli/data-api-cache.feature b/tests/features/cli/data-api-cache.feature index 25aaf8cc..7ac578bc 100644 --- a/tests/features/cli/data-api-cache.feature +++ b/tests/features/cli/data-api-cache.feature @@ -3,7 +3,7 @@ @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI -@cli @process-api @cache +@cli @pattern-graph-cli @cache Feature: Process API CLI - Dataset Cache PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. diff --git a/tests/features/cli/data-api-dryrun.feature b/tests/features/cli/data-api-dryrun.feature index 502ab347..c4683db6 100644 --- a/tests/features/cli/data-api-dryrun.feature +++ b/tests/features/cli/data-api-dryrun.feature @@ -3,7 +3,7 @@ @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI -@cli @process-api @dry-run +@cli @pattern-graph-cli @dry-run Feature: Process API CLI - Dry Run Dry-run mode shows pipeline scope without processing data. @@ -23,7 +23,7 @@ Feature: Process API CLI - Dry Run @happy-path Scenario: Dry-run shows file counts Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' --dry-run status" + When running "pattern-graph-cli -i 'src/**/*.ts' --dry-run status" Then exit code is 0 And stdout contains dry run marker, file counts, config, and cache status And stdout does not contain "success" @@ -32,7 +32,7 @@ Feature: Process API CLI - Dry Run Scenario: Dry-run reports architect.config.js auto-detection Given TypeScript files with pattern annotations And an architect.config.js with TypeScript sources - When running "process-api --dry-run status" + When running "pattern-graph-cli --dry-run status" Then exit code is 0 And stdout contains "architect.config.js (auto-detected)" And stdout does not contain "success" diff --git a/tests/features/cli/data-api-help.feature b/tests/features/cli/data-api-help.feature index 789b9c22..a5fae379 100644 --- a/tests/features/cli/data-api-help.feature +++ b/tests/features/cli/data-api-help.feature @@ -3,7 +3,7 @@ @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI -@cli @process-api @help +@cli @pattern-graph-cli @help Feature: Process API CLI - Per-Subcommand Help Per-subcommand help displays usage, flags, and examples for individual subcommands. @@ -21,19 +21,19 @@ Feature: Process API CLI - Per-Subcommand Help @happy-path Scenario: Per-subcommand help for context - When running "process-api context --help" + When running "pattern-graph-cli context --help" Then exit code is 0 And stdout contains context usage and session flag And stdout contains "Usage:" @happy-path Scenario: Global help still works - When running "process-api --help" + When running "pattern-graph-cli --help" Then exit code is 0 And stdout contains "Usage:" @validation Scenario: Unknown subcommand help - When running "process-api foobar --help" + When running "pattern-graph-cli foobar --help" Then exit code is 0 And stdout contains "No detailed help" diff --git a/tests/features/cli/data-api-metadata.feature b/tests/features/cli/data-api-metadata.feature index e88a3c84..e7119394 100644 --- a/tests/features/cli/data-api-metadata.feature +++ b/tests/features/cli/data-api-metadata.feature @@ -3,7 +3,7 @@ @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI -@cli @process-api @metadata +@cli @pattern-graph-cli @metadata Feature: Process API CLI - Response Metadata Response metadata includes validation summary and pipeline timing for diagnostics. @@ -22,7 +22,7 @@ Feature: Process API CLI - Response Metadata @acceptance-criteria @happy-path Scenario: Validation summary in response metadata Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' status" + When running "pattern-graph-cli -i 'src/**/*.ts' status" Then exit code is 0 And stdout is valid JSON with key "metadata" And metadata has a validation object with count fields @@ -31,6 +31,6 @@ Feature: Process API CLI - Response Metadata @happy-path Scenario: Pipeline timing in metadata Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' status" + When running "pattern-graph-cli -i 'src/**/*.ts' status" Then exit code is 0 And metadata has a numeric pipelineMs field diff --git a/tests/features/cli/data-api-repl.feature b/tests/features/cli/data-api-repl.feature index de898ea4..c5e0acd7 100644 --- a/tests/features/cli/data-api-repl.feature +++ b/tests/features/cli/data-api-repl.feature @@ -3,7 +3,7 @@ @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI -@cli @process-api @repl +@cli @pattern-graph-cli @repl Feature: Process API CLI - REPL Mode Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. diff --git a/tests/features/cli/process-api-core.feature b/tests/features/cli/pattern-graph-cli-core.feature similarity index 86% rename from tests/features/cli/process-api-core.feature rename to tests/features/cli/pattern-graph-cli-core.feature index 6e15cd38..f833289c 100644 --- a/tests/features/cli/process-api-core.feature +++ b/tests/features/cli/pattern-graph-cli-core.feature @@ -4,7 +4,7 @@ @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI -@cli @process-api +@cli @pattern-graph-cli Feature: Process API CLI - Core Infrastructure Core CLI infrastructure: help, version, input validation, status, query, pattern, arch basics, missing args, edge cases. @@ -22,18 +22,18 @@ Feature: Process API CLI - Core Infrastructure @happy-path Scenario: Display help with --help flag - When running "process-api --help" + When running "pattern-graph-cli --help" Then exit code is 0 And stdout contains "Usage:" @happy-path Scenario: Display version with -v flag - When running "process-api -v" + When running "pattern-graph-cli -v" Then exit code is 0 @validation Scenario: No subcommand shows help - When running "process-api -i 'src/**/*.ts'" + When running "pattern-graph-cli -i 'src/**/*.ts'" Then exit code is 1 And output contains "Usage:" @@ -48,7 +48,7 @@ Feature: Process API CLI - Core Infrastructure @validation Scenario: Fail without --input flag when running status - When running "process-api status" + When running "pattern-graph-cli status" Then exit code is 1 And output contains "--input" @@ -56,13 +56,13 @@ Feature: Process API CLI - Core Infrastructure Scenario: Use architect.config.js sources when --input is omitted Given TypeScript files with pattern annotations And an architect.config.js with TypeScript sources - When running "process-api status" + When running "pattern-graph-cli status" Then exit code is 0 And stdout is valid JSON with key "success" @validation Scenario: Reject unknown options - When running "process-api --unknown-flag" + When running "pattern-graph-cli --unknown-flag" Then exit code is 1 And output contains "Unknown option" @@ -78,7 +78,7 @@ Feature: Process API CLI - Core Infrastructure @happy-path Scenario: Status shows counts and completion percentage Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' status" + When running "pattern-graph-cli -i 'src/**/*.ts' status" Then exit code is 0 And stdout is valid JSON with key "success" @@ -94,21 +94,21 @@ Feature: Process API CLI - Core Infrastructure @happy-path Scenario: Query getStatusCounts returns count object Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' query getStatusCounts" + When running "pattern-graph-cli -i 'src/**/*.ts' query getStatusCounts" Then exit code is 0 And stdout is valid JSON @happy-path Scenario: Query isValidTransition with arguments Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' query isValidTransition roadmap active" + When running "pattern-graph-cli -i 'src/**/*.ts' query isValidTransition roadmap active" Then exit code is 0 And stdout is valid JSON @validation Scenario: Unknown API method shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' query nonExistentMethod" + When running "pattern-graph-cli -i 'src/**/*.ts' query nonExistentMethod" Then exit code is 1 And output contains "Unknown" @@ -124,7 +124,7 @@ Feature: Process API CLI - Core Infrastructure @happy-path Scenario: Pattern lookup returns full detail Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' pattern CompletedPattern" + When running "pattern-graph-cli -i 'src/**/*.ts' pattern CompletedPattern" Then exit code is 0 And stdout is valid JSON And stdout contains "CompletedPattern" @@ -132,7 +132,7 @@ Feature: Process API CLI - Core Infrastructure @validation Scenario: Pattern not found shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' pattern NonExistent" + When running "pattern-graph-cli -i 'src/**/*.ts' pattern NonExistent" Then exit code is 1 And output contains "not found" @@ -148,21 +148,21 @@ Feature: Process API CLI - Core Infrastructure @happy-path Scenario: Arch roles lists roles with counts Given TypeScript files with architecture annotations - When running "process-api -i 'src/**/*.ts' arch roles" + When running "pattern-graph-cli -i 'src/**/*.ts' arch roles" Then exit code is 0 And stdout is valid JSON @happy-path Scenario: Arch context filters to bounded context Given TypeScript files with architecture annotations - When running "process-api -i 'src/**/*.ts' arch context testctx" + When running "pattern-graph-cli -i 'src/**/*.ts' arch context testctx" Then exit code is 0 And stdout is valid JSON @happy-path Scenario: Arch layer lists layers with counts Given TypeScript files with architecture annotations - When running "process-api -i 'src/**/*.ts' arch layer" + When running "pattern-graph-cli -i 'src/**/*.ts' arch layer" Then exit code is 0 And stdout is valid JSON @@ -178,21 +178,21 @@ Feature: Process API CLI - Core Infrastructure @validation Scenario: Query without method name shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' query" + When running "pattern-graph-cli -i 'src/**/*.ts' query" Then exit code is 1 And output contains "Usage:" @validation Scenario: Pattern without name shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' pattern" + When running "pattern-graph-cli -i 'src/**/*.ts' pattern" Then exit code is 1 And output contains "Usage:" @validation Scenario: Unknown subcommand shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' foobar" + When running "pattern-graph-cli -i 'src/**/*.ts' foobar" Then exit code is 1 And output contains "Unknown subcommand" @@ -208,10 +208,10 @@ Feature: Process API CLI - Core Infrastructure @edge-case Scenario: Integer arguments are coerced for phase queries Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' query getPatternsByPhase 1" + When running "pattern-graph-cli -i 'src/**/*.ts' query getPatternsByPhase 1" Then exit code is 0 @edge-case Scenario: Double-dash separator is handled gracefully - When running "process-api -- --help" + When running "pattern-graph-cli -- --help" Then exit code is 0 diff --git a/tests/features/cli/process-api-modifiers-rules.feature b/tests/features/cli/pattern-graph-cli-modifiers-rules.feature similarity index 82% rename from tests/features/cli/process-api-modifiers-rules.feature rename to tests/features/cli/pattern-graph-cli-modifiers-rules.feature index f4f0dc22..56f97d31 100644 --- a/tests/features/cli/process-api-modifiers-rules.feature +++ b/tests/features/cli/pattern-graph-cli-modifiers-rules.feature @@ -4,7 +4,7 @@ @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI -@cli @process-api +@cli @pattern-graph-cli Feature: Process API CLI - Output Modifiers and Rules Output modifiers, arch health, and rules subcommand. @@ -26,21 +26,21 @@ Feature: Process API CLI - Output Modifiers and Rules @happy-path Scenario: Count modifier after list subcommand returns count Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' list --count" + When running "pattern-graph-cli -i 'src/**/*.ts' list --count" Then exit code is 0 And stdout JSON data is a number @happy-path Scenario: Names-only modifier after list subcommand returns names Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' list --names-only" + When running "pattern-graph-cli -i 'src/**/*.ts' list --names-only" Then exit code is 0 And stdout JSON data is a string array @happy-path Scenario: Count modifier combined with list filter Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' list --status completed --count" + When running "pattern-graph-cli -i 'src/**/*.ts' list --status completed --count" Then exit code is 0 And stdout JSON data is a number @@ -59,7 +59,7 @@ Feature: Process API CLI - Output Modifiers and Rules @happy-path Scenario: Arch dangling returns broken references Given TypeScript files with a dangling reference - When running "process-api -i 'src/**/*.ts' arch dangling" + When running "pattern-graph-cli -i 'src/**/*.ts' arch dangling" Then exit code is 0 And stdout JSON data is an array And stdout JSON data contains an entry with field "missing" @@ -67,7 +67,7 @@ Feature: Process API CLI - Output Modifiers and Rules @happy-path Scenario: Arch orphans returns isolated patterns Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' arch orphans" + When running "pattern-graph-cli -i 'src/**/*.ts' arch orphans" Then exit code is 0 And stdout JSON data is an array And stdout JSON data contains an entry with field "pattern" @@ -75,7 +75,7 @@ Feature: Process API CLI - Output Modifiers and Rules @happy-path Scenario: Arch blocking returns blocked patterns Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' arch blocking" + When running "pattern-graph-cli -i 'src/**/*.ts' arch blocking" Then exit code is 0 And stdout JSON data is an array @@ -95,7 +95,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules returns business rules from feature files Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules" Then exit code is 0 And stdout JSON data has fields: | field | @@ -107,7 +107,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules filters by product area Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area Validation" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area Validation" Then exit code is 0 And stdout JSON data has field "productAreas" @@ -115,7 +115,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules with count modifier returns totals Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --count" Then exit code is 0 And stdout JSON data has fields: | field | @@ -126,7 +126,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules with names-only returns flat array Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --names-only" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --names-only" Then exit code is 0 And stdout JSON data is an array @@ -134,7 +134,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules filters by pattern name Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --pattern CoreUtilsTest --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --pattern CoreUtilsTest --count" Then exit code is 0 And stdout JSON data has field values: | field | value | @@ -145,7 +145,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules with only-invariants excludes rules without invariants Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --only-invariants --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --only-invariants --count" Then exit code is 0 And stdout JSON data has field values: | field | value | @@ -156,7 +156,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules product area filter excludes non-matching areas Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area Validation --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area Validation --count" Then exit code is 0 And stdout JSON data has field values: | field | value | @@ -166,7 +166,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules for non-existent product area returns hint Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area NonExistent --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area NonExistent --count" Then exit code is 0 And stdout JSON data has field "hint" @@ -174,7 +174,7 @@ Feature: Process API CLI - Output Modifiers and Rules Scenario: Rules combines product area and only-invariants filters Given TypeScript files with pattern annotations And Gherkin feature files with business rules - When running "process-api -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area CoreTypes --only-invariants --count" + When running "pattern-graph-cli -i 'src/**/*.ts' -f 'specs/**/*.feature' rules --product-area CoreTypes --only-invariants --count" Then exit code is 0 And stdout JSON data has field values: | field | value | diff --git a/tests/features/cli/process-api-subcommands.feature b/tests/features/cli/pattern-graph-cli-subcommands.feature similarity index 86% rename from tests/features/cli/process-api-subcommands.feature rename to tests/features/cli/pattern-graph-cli-subcommands.feature index f94fc68f..6d0fbc67 100644 --- a/tests/features/cli/process-api-subcommands.feature +++ b/tests/features/cli/pattern-graph-cli-subcommands.feature @@ -4,7 +4,7 @@ @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI -@cli @process-api +@cli @pattern-graph-cli Feature: Process API CLI - Discovery Subcommands Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. @@ -23,14 +23,14 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: List all patterns returns JSON array Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' list" + When running "pattern-graph-cli -i 'src/**/*.ts' list" Then exit code is 0 And stdout is valid JSON with key "success" @validation Scenario: List with invalid phase shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' list --phase abc" + When running "pattern-graph-cli -i 'src/**/*.ts' list --phase abc" Then exit code is 1 And output contains "Invalid --phase" @@ -46,7 +46,7 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Search returns matching patterns Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' search Completed" + When running "pattern-graph-cli -i 'src/**/*.ts' search Completed" Then exit code is 0 And stdout is valid JSON And stdout contains "CompletedPattern" @@ -54,7 +54,7 @@ Feature: Process API CLI - Discovery Subcommands @validation Scenario: Search without query shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' search" + When running "pattern-graph-cli -i 'src/**/*.ts' search" Then exit code is 1 And output contains "Usage:" @@ -70,7 +70,7 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Context returns curated text bundle Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' context CompletedPattern" + When running "pattern-graph-cli -i 'src/**/*.ts' context CompletedPattern" Then exit code is 0 And stdout is non-empty And stdout contains "CompletedPattern" @@ -78,14 +78,14 @@ Feature: Process API CLI - Discovery Subcommands @validation Scenario: Context without pattern name shows error Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' context" + When running "pattern-graph-cli -i 'src/**/*.ts' context" Then exit code is 1 And output contains "Usage:" @happy-path Scenario: Overview returns executive summary text Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' overview" + When running "pattern-graph-cli -i 'src/**/*.ts' overview" Then exit code is 0 And stdout is non-empty And stdout contains "PROGRESS" @@ -93,7 +93,7 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Dep-tree returns dependency tree text Given TypeScript files with architecture annotations and dependencies - When running "process-api -i 'src/**/*.ts' dep-tree ScannerService" + When running "pattern-graph-cli -i 'src/**/*.ts' dep-tree ScannerService" Then exit code is 0 And stdout is non-empty @@ -109,14 +109,14 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Tags returns tag usage counts Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' tags" + When running "pattern-graph-cli -i 'src/**/*.ts' tags" Then exit code is 0 And stdout is valid JSON with key "data" @happy-path Scenario: Sources returns file inventory Given TypeScript files with pattern annotations - When running "process-api -i 'src/**/*.ts' sources" + When running "pattern-graph-cli -i 'src/**/*.ts' sources" Then exit code is 0 And stdout is valid JSON @@ -132,7 +132,7 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Arch neighborhood returns pattern relationships Given TypeScript files with architecture annotations and dependencies - When running "process-api -i 'src/**/*.ts' arch neighborhood ScannerService" + When running "pattern-graph-cli -i 'src/**/*.ts' arch neighborhood ScannerService" Then exit code is 0 And stdout is valid JSON And stdout contains "ScannerService" @@ -140,14 +140,14 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Arch compare returns context comparison Given TypeScript files with two architecture contexts - When running "process-api -i 'src/**/*.ts' arch compare scanner codec" + When running "pattern-graph-cli -i 'src/**/*.ts' arch compare scanner codec" Then exit code is 0 And stdout is valid JSON @happy-path Scenario: Arch coverage returns annotation coverage Given TypeScript files with architecture annotations - When running "process-api -i 'src/**/*.ts' arch coverage" + When running "pattern-graph-cli -i 'src/**/*.ts' arch coverage" Then exit code is 0 And stdout is valid JSON @@ -163,6 +163,6 @@ Feature: Process API CLI - Discovery Subcommands @happy-path Scenario: Unannotated finds files missing architect marker Given TypeScript files with mixed annotations - When running "process-api -i 'src/**/*.ts' unannotated" + When running "pattern-graph-cli -i 'src/**/*.ts' unannotated" Then exit code is 0 And stdout is valid JSON diff --git a/tests/features/generation/design-review.feature b/tests/features/generation/design-review.feature index ad43f5c9..ce6d139b 100644 --- a/tests/features/generation/design-review.feature +++ b/tests/features/generation/design-review.feature @@ -194,7 +194,7 @@ Feature: Design Review Generation Pipeline Rule: Process API sequence lookup resolves pattern names case-insensitively - **Invariant:** The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented process-api queries. + **Invariant:** The sequence subcommand resolves pattern names with the same case-insensitive matching behavior as other pattern-oriented pattern-graph queries. **Rationale:** Design review consumers should not need exact display-name casing when querying sequence data from the CLI. **Verified by:** Sequence lookup accepts lowercase pattern name diff --git a/tests/steps/behavior/cli/process-api-reference.steps.ts b/tests/steps/behavior/cli/cli-reference.steps.ts similarity index 93% rename from tests/steps/behavior/cli/process-api-reference.steps.ts rename to tests/steps/behavior/cli/cli-reference.steps.ts index b8693e4c..97ae38c3 100644 --- a/tests/steps/behavior/cli/process-api-reference.steps.ts +++ b/tests/steps/behavior/cli/cli-reference.steps.ts @@ -5,7 +5,7 @@ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; import { expect } from 'vitest'; import { CLI_SCHEMA, type CLIOptionGroup, type CLISchema } from '../../../../src/cli/cli-schema.js'; -import { createProcessApiReferenceGenerator } from '../../../../src/generators/built-in/process-api-reference-generator.js'; +import { createCliReferenceGenerator } from '../../../../src/generators/built-in/cli-reference-generator.js'; import type { GeneratorContext } from '../../../../src/generators/types.js'; // ============================================================================ @@ -74,7 +74,7 @@ function schemaFlagsFor( // Feature // ============================================================================ -const feature = await loadFeature('tests/features/behavior/cli/process-api-reference.feature'); +const feature = await loadFeature('tests/features/behavior/cli/cli-reference.feature'); describeFeature(feature, ({ AfterEachScenario, Rule }) => { AfterEachScenario(() => { @@ -92,8 +92,8 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { expect(CLI_SCHEMA).toBeDefined(); }); - When('the ProcessApiReferenceGenerator produces output', async () => { - const generator = createProcessApiReferenceGenerator(); + When('the CliReferenceGenerator produces output', async () => { + const generator = createCliReferenceGenerator(); const output = await generator.generate([], createMockGeneratorContext()); state!.generatedContent = output.files[0].content; }); @@ -125,8 +125,8 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { state = { generatedContent: null }; }); - When('the ProcessApiReferenceGenerator produces output', async () => { - const generator = createProcessApiReferenceGenerator(); + When('the CliReferenceGenerator produces output', async () => { + const generator = createCliReferenceGenerator(); const output = await generator.generate([], createMockGeneratorContext()); state!.generatedContent = output.files[0].content; }); @@ -158,8 +158,8 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { state = { generatedContent: null }; }); - When('the ProcessApiReferenceGenerator produces output', async () => { - const generator = createProcessApiReferenceGenerator(); + When('the CliReferenceGenerator produces output', async () => { + const generator = createCliReferenceGenerator(); const output = await generator.generate([], createMockGeneratorContext()); state!.generatedContent = output.files[0].content; }); @@ -188,8 +188,8 @@ describeFeature(feature, ({ AfterEachScenario, Rule }) => { state = { generatedContent: null }; }); - When('the ProcessApiReferenceGenerator produces output', async () => { - const generator = createProcessApiReferenceGenerator(); + When('the CliReferenceGenerator produces output', async () => { + const generator = createCliReferenceGenerator(); const output = await generator.generate([], createMockGeneratorContext()); state!.generatedContent = output.files[0].content; }); diff --git a/tests/steps/behavior/codecs/reference-generators.steps.ts b/tests/steps/behavior/codecs/reference-generators.steps.ts index 9730c896..6b8867be 100644 --- a/tests/steps/behavior/codecs/reference-generators.steps.ts +++ b/tests/steps/behavior/codecs/reference-generators.steps.ts @@ -278,7 +278,7 @@ describeFeature(feature, ({ Background, AfterEachScenario, Rule }) => { 'ARCHITECTURE-TYPES generator produces shapes and convention content', ({ Given, When, Then, And }) => { Given( - 'a PatternGraph with pipeline architecture conventions and master dataset shapes', + 'a PatternGraph with pipeline architecture conventions and pattern graph shapes', () => { state!.dataset = createTestPatternGraph({ patterns: [ diff --git a/tests/steps/behavior/context-inference.steps.ts b/tests/steps/behavior/context-inference.steps.ts index 6fafc35c..ce80d772 100644 --- a/tests/steps/behavior/context-inference.steps.ts +++ b/tests/steps/behavior/context-inference.steps.ts @@ -122,7 +122,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { ); }); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -180,7 +180,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { ); }); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -235,7 +235,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { ); }); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -288,7 +288,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -336,7 +336,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -390,7 +390,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -444,7 +444,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -496,7 +496,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -557,7 +557,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { } ); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, @@ -609,7 +609,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { ); }); - When('transforming to master dataset with rules', () => { + When('transforming to pattern graph with rules', () => { if (!state) throw new Error('State not initialized'); state.dataset = transformToPatternGraph({ patterns: state.patterns, diff --git a/tests/steps/cli/data-api-cache.steps.ts b/tests/steps/cli/data-api-cache.steps.ts index bfee2ee5..1122cd1a 100644 --- a/tests/steps/cli/data-api-cache.steps.ts +++ b/tests/steps/cli/data-api-cache.steps.ts @@ -114,7 +114,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); When('running status and capturing the first result', async () => { - await runCLICommand(state, "process-api -i 'src/**/*.ts' status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).firstResult = getResult(state); @@ -123,7 +123,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { And('running status and capturing the second result', async () => { // Reset result before the second run getCacheState(state).result = null; - await runCLICommand(state, "process-api -i 'src/**/*.ts' status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).secondResult = getResult(state); @@ -153,7 +153,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); When('running status and capturing the first result', async () => { - await runCLICommand(state, "process-api -i 'src/**/*.ts' status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).firstResult = getResult(state); @@ -170,7 +170,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { And('running status and capturing the second result', async () => { getCacheState(state).result = null; - await runCLICommand(state, "process-api -i 'src/**/*.ts' status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).secondResult = getResult(state); @@ -190,7 +190,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { }); When('running status and capturing the first result', async () => { - await runCLICommand(state, "process-api -i 'src/**/*.ts' status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).firstResult = getResult(state); @@ -198,7 +198,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { And('running status with --no-cache and capturing the second result', async () => { getCacheState(state).result = null; - await runCLICommand(state, "process-api -i 'src/**/*.ts' --no-cache status", { + await runCLICommand(state, "pattern-graph-cli -i 'src/**/*.ts' --no-cache status", { timeout: CACHE_QUERY_TIMEOUT_MS, }); getCacheState(state).secondResult = getResult(state); diff --git a/tests/steps/cli/data-api-repl.steps.ts b/tests/steps/cli/data-api-repl.steps.ts index a99f4cb4..616488d2 100644 --- a/tests/steps/cli/data-api-repl.steps.ts +++ b/tests/steps/cli/data-api-repl.steps.ts @@ -59,7 +59,7 @@ function getReplResult(state: ReplTestState | null): CLIResult { async function runRepl(state: ReplTestState | null, commands: string[]): Promise { const s = getReplState(state); const stdinData = commands.join('\n') + '\n'; - s.replResult = await runCLI('process-api', ['-i', "'src/**/*.ts'", 'repl'], { + s.replResult = await runCLI('pattern-graph-cli', ['-i', "'src/**/*.ts'", 'repl'], { cwd: getTempDir(state), timeout: 30000, stdin: stdinData, diff --git a/tests/steps/cli/process-api-core.steps.ts b/tests/steps/cli/pattern-graph-cli-core.steps.ts similarity index 98% rename from tests/steps/cli/process-api-core.steps.ts rename to tests/steps/cli/pattern-graph-cli-core.steps.ts index 7d4e8f4d..12385ecf 100644 --- a/tests/steps/cli/process-api-core.steps.ts +++ b/tests/steps/cli/pattern-graph-cli-core.steps.ts @@ -1,7 +1,7 @@ /** - * process-api CLI Core Step Definitions + * pattern-graph CLI Core Step Definitions * - * BDD step definitions for testing the process-api CLI + * BDD step definitions for testing the pattern-graph CLI * core infrastructure: help, version, input validation, * status, query, pattern, arch basics, missing args, edge cases. * @@ -32,7 +32,7 @@ let state: CLITestState | null = null; // Feature Definition // ============================================================================= -const feature = await loadFeature('tests/features/cli/process-api-core.feature'); +const feature = await loadFeature('tests/features/cli/pattern-graph-cli-core.feature'); function createJsProjectConfig(): string { return `export default { @@ -62,7 +62,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { Background(({ Given }) => { Given('a temporary working directory', async () => { state = initState(); - state.tempContext = await createTempDir({ prefix: 'cli-process-api-test-' }); + state.tempContext = await createTempDir({ prefix: 'cli-pattern-graph-test-' }); }); }); diff --git a/tests/steps/cli/process-api-modifiers-rules.steps.ts b/tests/steps/cli/pattern-graph-cli-modifiers-rules.steps.ts similarity index 98% rename from tests/steps/cli/process-api-modifiers-rules.steps.ts rename to tests/steps/cli/pattern-graph-cli-modifiers-rules.steps.ts index aa181b12..4bacf323 100644 --- a/tests/steps/cli/process-api-modifiers-rules.steps.ts +++ b/tests/steps/cli/pattern-graph-cli-modifiers-rules.steps.ts @@ -1,7 +1,7 @@ /** - * process-api CLI Modifiers and Rules Step Definitions + * pattern-graph CLI Modifiers and Rules Step Definitions * - * BDD step definitions for testing the process-api CLI + * BDD step definitions for testing the pattern-graph CLI * output modifiers, arch health, and rules subcommand. * * @architect @@ -31,7 +31,7 @@ let state: CLITestState | null = null; // Feature Definition // ============================================================================= -const feature = await loadFeature('tests/features/cli/process-api-modifiers-rules.feature'); +const feature = await loadFeature('tests/features/cli/pattern-graph-cli-modifiers-rules.feature'); describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { // --------------------------------------------------------------------------- @@ -52,7 +52,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { Background(({ Given }) => { Given('a temporary working directory', async () => { state = initState(); - state.tempContext = await createTempDir({ prefix: 'cli-process-api-test-' }); + state.tempContext = await createTempDir({ prefix: 'cli-pattern-graph-test-' }); }); }); diff --git a/tests/steps/cli/process-api-subcommands.steps.ts b/tests/steps/cli/pattern-graph-cli-subcommands.steps.ts similarity index 97% rename from tests/steps/cli/process-api-subcommands.steps.ts rename to tests/steps/cli/pattern-graph-cli-subcommands.steps.ts index af0c1e8d..4bcc573e 100644 --- a/tests/steps/cli/process-api-subcommands.steps.ts +++ b/tests/steps/cli/pattern-graph-cli-subcommands.steps.ts @@ -1,7 +1,7 @@ /** - * process-api CLI Subcommands Step Definitions + * pattern-graph CLI Subcommands Step Definitions * - * BDD step definitions for testing the process-api CLI + * BDD step definitions for testing the pattern-graph CLI * discovery subcommands: list, search, context assembly, * tags/sources, extended arch, unannotated. * @@ -34,7 +34,7 @@ let state: CLITestState | null = null; // Feature Definition // ============================================================================= -const feature = await loadFeature('tests/features/cli/process-api-subcommands.feature'); +const feature = await loadFeature('tests/features/cli/pattern-graph-cli-subcommands.feature'); describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { // --------------------------------------------------------------------------- @@ -55,7 +55,7 @@ describeFeature(feature, ({ Background, Rule, AfterEachScenario }) => { Background(({ Given }) => { Given('a temporary working directory', async () => { state = initState(); - state.tempContext = await createTempDir({ prefix: 'cli-process-api-test-' }); + state.tempContext = await createTempDir({ prefix: 'cli-pattern-graph-test-' }); }); }); diff --git a/tests/steps/generation/design-review.steps.ts b/tests/steps/generation/design-review.steps.ts index 0dce0ae5..86a1133f 100644 --- a/tests/steps/generation/design-review.steps.ts +++ b/tests/steps/generation/design-review.steps.ts @@ -11,7 +11,7 @@ * - Component diagram module grouping * - Type hexagon rendering with fields * - Design questions auto-computed metrics - * - Case-insensitive process-api sequence lookup + * - Case-insensitive pattern-graph CLI sequence lookup * - Mermaid-safe escaping across rendered label positions * * @architect diff --git a/tests/support/helpers/design-review-state.ts b/tests/support/helpers/design-review-state.ts index 43142bd1..0ceed29b 100644 --- a/tests/support/helpers/design-review-state.ts +++ b/tests/support/helpers/design-review-state.ts @@ -193,7 +193,7 @@ export function transformWithValidation(state: DesignReviewState): void { } /** - * Resolve a sequence entry using the same case-insensitive lookup helper as process-api. + * Resolve a sequence entry using the same case-insensitive lookup helper as pattern-graph-cli. */ export function resolveSequenceEntry( state: DesignReviewState, diff --git a/tests/support/helpers/pattern-graph-api-state.ts b/tests/support/helpers/pattern-graph-api-state.ts index bab3fffe..95a6b62c 100644 --- a/tests/support/helpers/pattern-graph-api-state.ts +++ b/tests/support/helpers/pattern-graph-api-state.ts @@ -1,7 +1,7 @@ /** * Process API CLI Shared Test State and Fixture Builders * - * Extracted from process-api.steps.ts to be shared across + * Extracted from pattern-graph-cli.steps.ts to be shared across * the split test files (core, subcommands, modifiers-rules). * * @architect From 444e4796ee14c9791feecee44e2107d31678f541 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Thu, 2 Apr 2026 03:30:26 +0200 Subject: [PATCH 3/6] =?UTF-8?q?fix:=20address=20adversarial=20review=20?= =?UTF-8?q?=E2=80=94=20MasterPhaseGroup=20alias,=20doc=20title=20renames,?= =?UTF-8?q?=20external=20agent=20gaps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename MasterPhaseGroup → SchemaPhaseGroup (vestige of old naming in import alias) - Fix "Process API Reference/Recipes" → "CLI Reference/Recipes" in doc index tables - Fix "Process API coverage" → "Pattern Graph CLI coverage" in SESSION-WORKFLOW-GUIDE - Accept external agent fixes: Process State API → Pattern Graph API in comments, ProcessAPILayeredExtraction → PatternGraphLayeredExtraction in specs/tags, generator titles, config paths, and PROCESS-API-RECIPES.md deletion --- README.md | 2 +- architect.config.ts | 4 +- ...ss-api-layered-extraction-findings.feature | 10 +- architect/specs/cli-recipe-codec.feature | 18 +-- ...strator-pipeline-factory-migration.feature | 6 +- .../pattern-graph-layered-extraction.feature | 4 +- ...validator-read-model-consolidation.feature | 2 +- .../cli-recipe-codec/cli-recipe-generator.ts | 14 +- docs-inbox/codebase-exploration-findings.md | 2 +- docs-live/ARCHITECTURE.md | 16 +-- docs-live/CHANGELOG-GENERATED.md | 114 +++++++-------- docs-live/INDEX.md | 16 +-- .../annotation/annotation-overview.md | 2 +- .../_claude-md/process/process-overview.md | 2 +- docs-live/business-rules/data-api.md | 132 +++++++++--------- docs-live/product-areas/ANNOTATION.md | 22 +-- docs-live/product-areas/DATA-API.md | 86 ++++++------ docs-live/product-areas/GENERATION.md | 22 +-- docs-live/product-areas/PROCESS.md | 6 +- docs-live/product-areas/VALIDATION.md | 4 +- ...{PROCESS-API-RECIPES.md => CLI-RECIPES.md} | 2 +- docs-live/reference/CLI-REFERENCE.md | 4 +- docs-live/reference/REFERENCE-SAMPLE.md | 2 +- docs-live/reference/SESSION-WORKFLOW-GUIDE.md | 2 +- docs-sources/index-navigation.md | 10 +- docs/DOCS-GAP-ANALYSIS.md | 50 +++---- docs/PROCESS-API.md | 4 +- src/api/index.ts | 8 +- src/api/pattern-graph-api.ts | 12 +- src/api/rules-query.ts | 4 +- src/api/types.ts | 2 +- .../built-in/cli-recipe-generator.ts | 6 +- .../built-in/cli-reference-generator.ts | 6 +- src/generators/built-in/codec-generators.ts | 6 +- src/generators/pipeline/build-pipeline.ts | 2 +- src/renderable/codecs/index-codec.ts | 2 +- tests/features/api/pattern-graph-api.feature | 4 +- .../behavior/cli/cli-reference.feature | 4 +- tests/features/cli/data-api-cache.feature | 4 +- tests/features/cli/data-api-dryrun.feature | 4 +- tests/features/cli/data-api-help.feature | 4 +- tests/features/cli/data-api-metadata.feature | 4 +- tests/features/cli/data-api-repl.feature | 4 +- .../cli/pattern-graph-cli-core.feature | 6 +- .../pattern-graph-cli-modifiers-rules.feature | 6 +- .../cli/pattern-graph-cli-subcommands.feature | 6 +- tests/steps/api/pattern-graph-api.steps.ts | 2 +- .../steps/behavior/cli/cli-reference.steps.ts | 2 +- .../helpers/pattern-graph-api-state.ts | 2 +- 49 files changed, 329 insertions(+), 329 deletions(-) rename docs-live/reference/{PROCESS-API-RECIPES.md => CLI-RECIPES.md} (99%) diff --git a/README.md b/README.md index 383a89e8..e3429d5a 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ All output goes to [`docs-live/`](docs-live/INDEX.md) — 57+ auto-generated fil | Command | Purpose | Docs | | ------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- | | `architect-generate` | Generate documentation from annotated sources | `architect-generate --help` | -| `architect` | Query delivery state for AI coding sessions | [Process API Reference](docs-live/reference/CLI-REFERENCE.md) | +| `architect` | Query delivery state for AI coding sessions | [CLI Reference](docs-live/reference/CLI-REFERENCE.md) | | `architect-lint-patterns` | Validate annotation quality (missing tags, etc.) | [Validation Rules](docs-live/VALIDATION-RULES.md) | | `architect-guard` | Validate delivery workflow FSM transitions | [Process Guard Reference](docs-live/reference/PROCESS-GUARD-REFERENCE.md) | | `architect-lint-steps` | Validate vitest-cucumber feature/step compatibility | [Validation Rules](docs-live/VALIDATION-RULES.md) | diff --git a/architect.config.ts b/architect.config.ts index bce6894b..4d218d06 100644 --- a/architect.config.ts +++ b/architect.config.ts @@ -57,8 +57,8 @@ const INDEX_DOCUMENT_ENTRIES: readonly DocumentEntry[] = [ // --- Reference Guides --- { title: 'Annotation Reference', path: 'reference/ANNOTATION-REFERENCE.md', description: 'Annotation mechanics, shape extraction, tag reference', audience: 'Developers', topic: 'Reference Guides' }, { title: 'Session Workflow Guide', path: 'reference/SESSION-WORKFLOW-GUIDE.md', description: 'Planning, Design, Implementation session workflows', audience: 'AI/Devs', topic: 'Reference Guides' }, - { title: 'Process API Reference', path: 'reference/CLI-REFERENCE.md', description: 'CLI command reference with flags and examples', audience: 'AI/Devs', topic: 'Reference Guides' }, - { title: 'Process API Recipes', path: 'reference/PROCESS-API-RECIPES.md', description: 'CLI workflow recipes and session guides', audience: 'AI/Devs', topic: 'Reference Guides' }, + { title: 'CLI Reference', path: 'reference/CLI-REFERENCE.md', description: 'Pattern Graph CLI command reference with flags and examples', audience: 'AI/Devs', topic: 'Reference Guides' }, + { title: 'CLI Recipes', path: 'reference/CLI-RECIPES.md', description: 'Pattern Graph CLI workflow recipes and session guides', audience: 'AI/Devs', topic: 'Reference Guides' }, { title: 'Process Guard Reference', path: 'reference/PROCESS-GUARD-REFERENCE.md', description: 'Pre-commit hooks, error codes, programmatic API', audience: 'Team Leads', topic: 'Reference Guides' }, { title: 'Architecture Codecs', path: 'reference/ARCHITECTURE-CODECS.md', description: 'All codecs with factory patterns and options', audience: 'Developers', topic: 'Reference Guides' }, { title: 'Architecture Types', path: 'reference/ARCHITECTURE-TYPES.md', description: 'PatternGraph interface and type shapes', audience: 'Developers', topic: 'Reference Guides' }, diff --git a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature index a9d03a61..f9ea8222 100644 --- a/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature +++ b/architect/ideations/2026-02-16-process-api-layered-extraction-findings.feature @@ -1,14 +1,14 @@ @ideation @ideation-status:active @ideation-scope:pattern-graph-cli,pipeline-factory,process-guard,adr-006-enforcement -@relates-to:ProcessAPILayeredExtraction,ADR006SingleReadModelArchitecture,ProcessGuardLinter,ValidatorReadModelConsolidation -Feature: Process API Layered Extraction — Investigation Findings +@relates-to:PatternGraphLayeredExtraction,ADR006SingleReadModelArchitecture,ProcessGuardLinter,ValidatorReadModelConsolidation +Feature: Pattern Graph Layered Extraction — Investigation Findings Trigger: ADR-006 architectural investigation revealed concrete violations in pattern-graph-cli.ts (1,703 lines, three responsibilities), pipeline duplication across four consumers, and a previously undocumented fifth consumer in the Process Guard. These findings inform the design session for - ProcessAPILayeredExtraction. + PatternGraphLayeredExtraction. Rule: Three responsibilities confirmed in pattern-graph-cli.ts @@ -46,7 +46,7 @@ Feature: Process API Layered Extraction — Investigation Findings | Consumer | File | What It Imports | | Orchestrator | src/generators/orchestrator.ts:51-55 | scanPatterns, extractPatterns, scanGherkinFiles, extractPatternsFromGherkin | - | Process API CLI | src/cli/pattern-graph-cli.ts:45-47 | scanPatterns, extractPatterns, scanGherkinFiles | + | Pattern Graph CLI | src/cli/pattern-graph-cli.ts:45-47 | scanPatterns, extractPatterns, scanGherkinFiles | | Validate Patterns CLI | src/cli/validate-patterns.ts:32-35 | scanPatterns, scanGherkinFiles, extractPatterns, extractProcessMetadata | | Process Guard | src/lint/process-guard/derive-state.ts:33 | scanGherkinFiles, extractDeliverables | @@ -110,7 +110,7 @@ Feature: Process API Layered Extraction — Investigation Findings Rule: Suggestions for deeper analysis in a dedicated design session The following topics require focused investigation before writing the - ProcessAPILayeredExtraction design spec: + PatternGraphLayeredExtraction design spec: **1. Output pipeline integration** pattern-graph-cli.ts has an output pipeline (src/cli/output-pipeline.ts) for diff --git a/architect/specs/cli-recipe-codec.feature b/architect/specs/cli-recipe-codec.feature index 37cba835..1379adf3 100644 --- a/architect/specs/cli-recipe-codec.feature +++ b/architect/specs/cli-recipe-codec.feature @@ -25,7 +25,7 @@ Feature: CLI Recipe Codec **Solution:** Create a standalone `CliRecipeGenerator` that extends CLI_SCHEMA with recipe - definitions and narrative metadata, producing `docs-live/reference/PROCESS-API-RECIPES.md`. + definitions and narrative metadata, producing `docs-live/reference/CLI-RECIPES.md`. The generator is a sibling to `CliReferenceGenerator` -- both are standalone (ADR-006 compliant) and consume CLI_SCHEMA directly. Editorial content that cannot be derived from schema (motivation prose, session decision tree) uses the preamble @@ -69,7 +69,7 @@ Feature: CLI Recipe Codec Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | | Extend CLI_SCHEMA with recipe definitions per command group | complete | src/cli/cli-schema.ts | Yes | unit | - | Create CliRecipeGenerator producing PROCESS-API-RECIPES.md | complete | src/generators/built-in/cli-recipe-generator.ts | Yes | integration | + | Create CliRecipeGenerator producing CLI-RECIPES.md | complete | src/generators/built-in/cli-recipe-generator.ts | Yes | integration | | Register generator in orchestrator config | complete | architect.config.ts | Yes | integration | | Preamble content for Why Use This and session decision tree | complete | architect.config.ts | No | n/a | | Replace PROCESS-API.md prose sections with pointers to generated files | complete | docs/PROCESS-API.md | No | n/a | @@ -81,7 +81,7 @@ Feature: CLI Recipe Codec `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe - generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the + generator produces `docs-live/reference/CLI-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. **Rationale:** Reference tables and recipe guides serve different audiences and @@ -100,7 +100,7 @@ Feature: CLI Recipe Codec Given the CliRecipeGenerator is registered in the orchestrator And the CliReferenceGenerator is also registered When docs:all runs - Then docs-live/reference/PROCESS-API-RECIPES.md is created + Then docs-live/reference/CLI-RECIPES.md is created And docs-live/reference/CLI-REFERENCE.md is also created And neither generator imports nor depends on the other @@ -177,7 +177,7 @@ Feature: CLI Recipe Codec Scenario: Generated file starts with preamble editorial content Given a CliRecipeGenerator with preamble containing Why Use This prose And the preamble includes a comparison table and Quick Start example - When the generator produces PROCESS-API-RECIPES.md + When the generator produces CLI-RECIPES.md Then the file begins with the Why Use This section And the Quick Start section follows with command examples and output And generated recipe sections appear after the preamble content @@ -195,7 +195,7 @@ Feature: CLI Recipe Codec a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and - `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this + `docs-live/reference/CLI-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. @@ -217,17 +217,17 @@ Feature: CLI Recipe Codec Given PROCESS-API.md has been trimmed after CliRecipeCodec completion When reading the manual file Then it contains a link to docs-live/reference/CLI-REFERENCE.md - And it contains a link to docs-live/reference/PROCESS-API-RECIPES.md + And it contains a link to docs-live/reference/CLI-RECIPES.md And the total line count is under 100 lines @acceptance-criteria @validation Scenario: No recipe content duplicated between manual and generated files - Given PROCESS-API.md and PROCESS-API-RECIPES.md both exist + Given PROCESS-API.md and CLI-RECIPES.md both exist When comparing their content Then the Common Recipes section does not appear in PROCESS-API.md And Session Workflow Commands section does not appear in PROCESS-API.md And Pattern Discovery section does not appear in PROCESS-API.md - And these sections appear in PROCESS-API-RECIPES.md + And these sections appear in CLI-RECIPES.md Rule: Command narrative descriptions are sourced from schema metadata diff --git a/architect/specs/orchestrator-pipeline-factory-migration.feature b/architect/specs/orchestrator-pipeline-factory-migration.feature index f8ac34d2..a6349ffa 100644 --- a/architect/specs/orchestrator-pipeline-factory-migration.feature +++ b/architect/specs/orchestrator-pipeline-factory-migration.feature @@ -6,7 +6,7 @@ @architect-effort:2d @architect-product-area:Generation @architect-include:process-workflow,codec-transformation -@architect-depends-on:ProcessAPILayeredExtraction +@architect-depends-on:PatternGraphLayeredExtraction @architect-business-value:eliminate-last-parallel-pipeline-and-unify-pipeline-definition @architect-priority:high Feature: Orchestrator Pipeline Factory Migration @@ -17,7 +17,7 @@ Feature: Orchestrator Pipeline Factory Migration the Parallel Pipeline anti-pattern identified in ADR-006. The shared pipeline factory in `build-pipeline.ts` already serves `pattern-graph-cli.ts` and `validate-patterns.ts`, but the orchestrator — the original pipeline - host — was deferred (ProcessAPILayeredExtraction DD-3) because it + host — was deferred (PatternGraphLayeredExtraction DD-3) because it collects structured warnings (scan errors with file details, extraction error counts, Gherkin parse errors with line/column) that the factory's flat `readonly string[]` warnings cannot represent. @@ -90,7 +90,7 @@ Feature: Orchestrator Pipeline Factory Migration The factory already calls the validation variant. Adding `includeValidation?: boolean` (default true) lets the orchestrator opt out, since doc generation doesn't need validation summaries. - This was foreshadowed in ProcessAPILayeredExtraction DD-3. + This was foreshadowed in PatternGraphLayeredExtraction DD-3. DD-4: Scan result counts flow through PipelineResult. The orchestrator needs scan result counts for constructing its warning diff --git a/architect/specs/pattern-graph-layered-extraction.feature b/architect/specs/pattern-graph-layered-extraction.feature index 8eb2a406..572db43e 100644 --- a/architect/specs/pattern-graph-layered-extraction.feature +++ b/architect/specs/pattern-graph-layered-extraction.feature @@ -1,5 +1,5 @@ @architect -@architect-pattern:ProcessAPILayeredExtraction +@architect-pattern:PatternGraphLayeredExtraction @architect-status:completed @architect-unlock-reason:PR28-review-structural-fixes @architect-phase:100 @@ -9,7 +9,7 @@ @architect-depends-on:ValidatorReadModelConsolidation @architect-business-value:separate-cli-shell-from-domain-logic-in-pattern-graph-cli @architect-priority:high -Feature: Process API Layered Extraction +Feature: Pattern Graph Layered Extraction **Problem:** `pattern-graph-cli.ts` is 1,700 lines containing two remaining architectural diff --git a/architect/specs/validator-read-model-consolidation.feature b/architect/specs/validator-read-model-consolidation.feature index fdc11bbe..a48d3b47 100644 --- a/architect/specs/validator-read-model-consolidation.feature +++ b/architect/specs/validator-read-model-consolidation.feature @@ -63,7 +63,7 @@ Feature: Validator Read Model Consolidation DD-1: Reuse the same pipeline as pattern-graph-cli.ts — not a shared factory yet. The validator will wire scan-extract-merge-transform inline, mirroring how pattern-graph-cli.ts does it today (lines 490-558). Extracting a shared - pipeline factory is scoped to ProcessAPILayeredExtraction, not this spec. + pipeline factory is scoped to PatternGraphLayeredExtraction, not this spec. This keeps the refactoring focused on data-access only. DD-2: The validatePatterns() function signature changes from diff --git a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts index 349ef5ff..f34bd2e3 100644 --- a/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts +++ b/architect/stubs/cli-recipe-codec/cli-recipe-generator.ts @@ -6,7 +6,7 @@ * * ## CliRecipeGenerator — Standalone Generator for CLI Recipes and Narratives * - * Produces `docs-live/reference/PROCESS-API-RECIPES.md` from the declarative + * Produces `docs-live/reference/CLI-RECIPES.md` from the declarative * CLI schema. Sibling to `CliReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends * on PatternGraph (ADR-006 compliant). @@ -35,17 +35,17 @@ * `architect.config.ts`, not in the generator source. * * **Design Decision DD-5 (No claude-md output):** - * The generator produces only `docs-live/reference/PROCESS-API-RECIPES.md`. + * The generator produces only `docs-live/reference/CLI-RECIPES.md`. * It does NOT produce `_claude-md/` output because CLAUDE.md already has * a manually-authored "Data API CLI" section that serves the AI context use * case. Adding generated claude-md modules would create duplicate content. * * ### Output File Structure * - * The generated `PROCESS-API-RECIPES.md` has this structure: + * The generated `CLI-RECIPES.md` has this structure: * * ``` - * # Process API CLI — Recipes & Workflow Guide + * # Pattern Graph CLI Recipes & Workflow Guide * > Auto-generated from CLI schema. * * [Preamble: Why Use This, Quick Start, Session Types] @@ -206,7 +206,7 @@ function buildRecipeDocument( // } // } // - // const doc = document('Process API CLI - Recipes & Workflow Guide', sections); + // const doc = document('Pattern Graph CLI Recipes & Workflow Guide', sections); // return renderToMarkdown(doc); throw new Error('CliRecipeCodec not yet implemented - roadmap pattern'); @@ -237,7 +237,7 @@ export interface CliRecipeGeneratorConfig { // ============================================================================= /** - * Standalone generator producing PROCESS-API-RECIPES.md from CLI schema. + * Standalone generator producing CLI-RECIPES.md from CLI schema. * * Follows the same pattern as CliReferenceGenerator: * - Implements DocumentGenerator interface @@ -269,7 +269,7 @@ class CliRecipeGeneratorImpl { return Promise.resolve({ files: [ { - path: 'reference/PROCESS-API-RECIPES.md', + path: 'reference/CLI-RECIPES.md', content, }, ], diff --git a/docs-inbox/codebase-exploration-findings.md b/docs-inbox/codebase-exploration-findings.md index aaa1aded..b34b0c95 100644 --- a/docs-inbox/codebase-exploration-findings.md +++ b/docs-inbox/codebase-exploration-findings.md @@ -364,7 +364,7 @@ Two presets: 7. Load workflow 8. Transform to PatternGraph -**5 consumers:** Orchestrator, Process API CLI, validate-patterns CLI, REPL, MCP server. +**5 consumers:** Orchestrator, Pattern Graph CLI, validate-patterns CLI, REPL, MCP server. **`PipelineOptions` does NOT carry config:** It has raw glob arrays, not `ResolvedConfig`. The pipeline internally calls `loadConfig()` to get the registry, causing the double-load when orchestrator already loaded config. diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index b3eb5b07..4ec126d6 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -125,17 +125,11 @@ graph TB MCPModule --> MCPPipelineSession MCPModule --> MCPFileWatcher MCPModule --> MCPToolRegistry - LintEngine --> LintRules - SourceMapper -.-> DecisionDocCodec - SourceMapper -.-> GherkinASTParser - Documentation_Generation_Orchestrator --> Pattern_Scanner GherkinExtractor --> GherkinASTParser DualSourceExtractor --> GherkinExtractor DualSourceExtractor --> GherkinScanner Document_Extractor --> Pattern_Scanner - ConfigResolver --> ArchitectFactory - ArchitectFactory --> RegexBuilders - ConfigLoader --> ArchitectFactory + LintEngine --> LintRules ReplMode --> PatternGraphAPI PatternGraphCLIImpl --> PatternGraphAPI PatternGraphCLIImpl --> PatternGraph @@ -144,6 +138,12 @@ graph TB PatternGraphCLIImpl --> OutputPipelineImpl OutputPipelineImpl --> PatternSummarizerImpl MCPServerBin --> MCPServerImpl + ConfigResolver --> ArchitectFactory + ArchitectFactory --> RegexBuilders + ConfigLoader --> ArchitectFactory + SourceMapper -.-> DecisionDocCodec + SourceMapper -.-> GherkinASTParser + Documentation_Generation_Orchestrator --> Pattern_Scanner PatternSummarizerImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraph @@ -322,11 +322,11 @@ All components with architecture annotations: | 🚧 Normalized Status Testing | - | - | - | tests/features/types/normalized-status.feature | | ✅ Orchestrator Pipeline Factory Migration | - | - | - | architect/specs/orchestrator-pipeline-factory-migration.feature | | 🚧 Pattern Graph API Types | - | - | - | src/api/types.ts | +| ✅ Pattern Graph Layered Extraction | - | - | - | architect/specs/pattern-graph-layered-extraction.feature | | ✅ Pipeline Factory | - | - | - | src/generators/pipeline/build-pipeline.ts | | ✅ Pipeline Module | - | - | - | src/generators/pipeline/index.ts | | ✅ Planning Codecs | - | - | - | src/renderable/codecs/planning.ts | | ✅ Pr Changes Codec | - | - | - | src/renderable/codecs/pr-changes.ts | -| ✅ Process API Layered Extraction | - | - | - | architect/specs/pattern-graph-layered-extraction.feature | | 🚧 Process Guard Module | - | - | - | src/lint/process-guard/index.ts | | ✅ Process Guard Testing | - | - | - | tests/features/validation/process-guard.feature | | 🚧 Process Guard Types | - | - | - | src/lint/process-guard/types.ts | diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 0a7b65d4..05d127af 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -14,7 +14,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added -- **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. +- **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. +- **MCP Server Impl**: Main entry point for the Architect MCP server. +- **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. +- **MCP Module**: Public API for the MCP server module. +- **MCP File Watcher**: Watches source file globs and triggers debounced pipeline rebuilds. - **Git Name Status Parser**: Parses NUL-delimited git name-status output into categorized file lists. - **Git Module**: Shared git utilities used by both generators and lint layers. - **Git Helpers**: Low-level helpers for safe git command execution and input sanitization. @@ -31,17 +35,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Process CLI**: Validates git changes against workflow rules. - **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **File Cache**: Simple Map-based cache for file contents during a single generation run. -- **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. -- **MCP Server Impl**: Main entry point for the Architect MCP server. -- **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. -- **MCP Module**: Public API for the MCP server module. -- **MCP File Watcher**: Watches source file globs and triggers debounced pipeline rebuilds. +- **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. - **Pattern Graph API Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. - **Pattern Summarizer Impl**: Projects the full ExtractedPattern (~3.5KB per pattern) down to a PatternSummary (~100 bytes) for list queries. - **Stub Resolver Impl**: Identifies design session stubs in the PatternGraph and resolves them against the filesystem to determine... - **Pattern Helpers**: Common helper functions used by context-assembler, arch-queries, and other API modules that need pattern name... - **Pattern Graph API**: TypeScript interface for querying project state. -- **API Module**: Central export for the Process State API, providing a TypeScript interface for querying project state. +- **API Module**: Central export for the PatternGraphAPI, providing a TypeScript interface for querying the pattern graph and delivery... - **Fuzzy Matcher Impl**: Provides fuzzy matching for pattern names with tiered scoring: exact (1.0) > prefix (0.9) > substring (0.7) >... - **Coverage Analyzer Impl**: Reports annotation completeness by comparing scannable files (from glob) against annotated patterns in PatternGraph. - **Context Formatter Impl**: First plain-text formatter in the codebase. @@ -61,18 +61,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... - **Derive Process State**: :GherkinScanner,FSMValidator Derives process state from @architect-\* annotations in files. - **Process Guard Decider**: :FSMValidator,DeriveProcessState,DetectChanges Pure function that validates changes against process rules. +- **Reference Generator Registration**: Registers all reference document generators. +- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **Transform Types**: Type definitions for the dataset transformation pipeline. - **Sequence Transform Utils**: :Generation Builds pre-computed SequenceIndexEntry objects from patterns that have sequence diagram annotations. - **Relationship Resolver**: Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) and detects dangling references in... -- **Reference Generator Registration**: Registers all reference document generators. -- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the pattern-graph-cli CLI. - **Design Review Generation**: Design reviews require manual creation of sequence and component diagrams that duplicate information already captured... +- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. +- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Workflow Config Schemas Validation**: The workflow configuration module defines Zod schemas for validating delivery workflow definitions with statuses,... - **Tag Registry Schemas Validation**: The tag registry configuration module provides schema-validated taxonomy definitions for organizing patterns by... - **Codec Utils Validation**: The codec utilities provide factory functions for creating type-safe JSON parsing and serialization pipelines using... -- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. -- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Tag Registry Builder Testing**: The tag registry builder constructs a complete TagRegistry from TypeScript constants. - **Normalized Status Testing**: The normalized status module maps any status input — raw FSM states (roadmap, active, completed, deferred),... - **Deliverable Status Taxonomy Testing**: The deliverable status module defines the 6 canonical status values for deliverables in Gherkin Background tables:... @@ -81,20 +81,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Design Review Generator Lifecycle Tests**: The design review generator cleans up stale markdown files when annotated patterns are renamed or removed from the... - **Claude Metadata Parity Testing**: The extractor must preserve Claude routing metadata from TypeScript directives and keep the sync and async Gherkin... - **Architecture Doc Refactoring Testing**: Validates that ARCHITECTURE.md retains its full reference content and that generated documents in docs-live/ coexist... -- **Process Api Cli Repl**: Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. -- **Process Api Cli Metadata**: Response metadata includes validation summary and pipeline timing for diagnostics. -- **Process Api Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. -- **Process Api Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. -- **Process Api Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. +- **Pattern Graph Cli Repl**: Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. +- **Pattern Graph Cli Metadata**: Response metadata includes validation summary and pipeline timing for diagnostics. +- **Pattern Graph Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. +- **Pattern Graph Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. +- **Pattern Graph Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. - **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... - **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... -- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... -- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... -- **Arch Queries Test** - **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... - **Pattern Helpers Tests** - **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. - **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. +- **Arch Queries Test** +- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... +- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... - **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. - **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. @@ -125,6 +125,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. - **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). - **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... +- **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. +- **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... +- **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. +- **Anti Pattern Detector**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... - **Workflow Config Schema**: Zod schemas for validating workflow configuration files that define status models, phase definitions, and artifact... - **Tag Registry Configuration**: Defines the structure and validation for tag taxonomy configuration. - **Pattern Graph**: Defines the schema for a pre-computed dataset that holds all extracted patterns along with derived views (by status,... @@ -134,10 +138,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Dual Source Schemas**: Zod schemas for dual-source extraction types. - **Doc Directive Schema**: Zod schemas for validating parsed @architect-\* directives from JSDoc comments. - **Codec Utils**: Provides factory functions for creating type-safe JSON parsing and serialization pipelines using Zod schemas. -- **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. -- **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... -- **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. -- **Anti Pattern Detector**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... - **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... - **Utils Module**: Common helper functions used across the Architect package. - **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. @@ -148,14 +148,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. - **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... - **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... -- **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). -- **Risk Levels**: Three-tier risk classification for roadmap planning. -- **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. -- **Normalized Status**: The Architect system uses a two-level status taxonomy: 1. -- **Layer Types**: Inferred from feature file directory paths: - timeline: Process/workflow features (architect) - domain: Business... -- **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... -- **Format Types**: Defines how tag values are parsed and validated. -- **Category Definitions**: Categories are used to classify patterns and organize documentation. - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. @@ -164,14 +156,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. - **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. - **Lint Engine**: Orchestrates lint rule execution against parsed directives. -- **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. -- **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. -- **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. -- **Source Mapper**: Aggregates content from multiple source files based on source mapping tables parsed from decision documents. -- **Generator Registry**: Manages registration and lookup of document generators (both built-in and custom). -- **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... -- **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. -- **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. - **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... - **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. - **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. @@ -184,12 +168,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architect Factory**: Main factory function for creating configured Architect instances. - **Configuration Defaults**: Centralized default constants for the Architect package. - **Config Loader**: Discovers and loads `architect.config.ts` or `architect.config.js` files for hierarchical configuration. +- **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. +- **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. +- **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. +- **Source Mapper**: Aggregates content from multiple source files based on source mapping tables parsed from decision documents. +- **Generator Registry**: Manages registration and lookup of document generators (both built-in and custom). +- **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... +- **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. +- **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. - **CLI Version Helper**: Reads package version from package.json for CLI --version flag. - **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. - **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. - **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. - **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. - **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. +- **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). +- **Risk Levels**: Three-tier risk classification for roadmap planning. +- **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. +- **Normalized Status**: The Architect system uses a two-level status taxonomy: 1. +- **Layer Types**: Inferred from feature file directory paths: - timeline: Process/workflow features (architect) - domain: Business... +- **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... +- **Format Types**: Defines how tag values are parsed and validated. +- **Category Definitions**: Categories are used to classify patterns and organize documentation. - **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. - **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. - **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. @@ -215,15 +215,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Business Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for business rules output. - **Architecture Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing architecture diagrams (Mermaid) generated... - **Adr Document Codec**: :Generation Transforms PatternGraph into RenderableDocument for Architecture Decision Records. +- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. +- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. +- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. +- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Transform Dataset**: Transforms raw extracted patterns into a PatternGraph with all pre-computed views. - **Merge Patterns**: Merges patterns from TypeScript and Gherkin sources with conflict detection. - **Pipeline Module**: Barrel export for the unified transformation pipeline components. - **Context Inference Impl**: Auto-infers bounded context from file paths using configurable rules. - **Pipeline Factory**: Invariant: `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... -- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. -- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. -- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. -- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Codec Base Options**: :Add-createDecodeOnlyCodec-helper Shared types, interfaces, and utilities for all document codecs. - **ADR 006 Single Read Model Architecture**: The Architect package applies event sourcing to itself: git is the event store, annotated source files are... - **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (PatternGraph) into markdown files. @@ -239,7 +239,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Readme Rationalization**: `README.md` is 504 lines and serves three different audiences in one document: (a) npm package consumers who need... - **Publishing Relocation**: `docs/PUBLISHING.md` (144 lines) is deployed to libar.dev as part of the `docs/` directory, but its content is... - **Procedural Guide Codec**: Two manual docs contain procedural content with no annotation source for generation: `docs/SESSION-GUIDES.md` (389... -- **Process API Layered Extraction**: `pattern-graph-cli.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. +- **Pattern Graph Layered Extraction**: `pattern-graph-cli.ts` is 1,700 lines containing two remaining architectural violations of ADR-006: 1. - **Pattern Graph API Relationship Queries**: Problem: PatternGraphAPI currently supports dependency queries (`uses`, `usedBy`, `dependsOn`, `enables`) but lacks... - **Pattern Graph API CLI**: The PatternGraphAPI provides 27 typed query methods for efficient state queries, but Claude Code sessions cannot use... - **Orchestrator Pipeline Factory Migration**: `orchestrator.ts` is the last feature consumer that wires the 8-step scan-extract-merge-transform pipeline inline... @@ -267,6 +267,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architecture Doc Refactoring**: ARCHITECTURE.md is 1,287 lines of manually-maintained documentation covering 14 sections. - **Architecture Diagram Core**: Problem: Architecture documentation requires manually maintaining mermaid diagrams that duplicate information already... - **Architecture Diagram Advanced**: Problem: Core diagram generation (see ArchitectureDiagramCore) produces component-level diagrams from `arch-*` tags. +- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Status Transition Detection Testing**: Tests for the detectStatusTransitions function that parses git diff output. - **Process Guard Testing**: Pure validation functions for enforcing delivery process rules per PDR-005. - **FSM Validator Testing**: Pure validation functions for the 4-state FSM defined in PDR-005. @@ -274,7 +275,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Detect Changes Testing**: Tests for the detectDeliverableChanges function that parses git diff output. - **Config Schema Validation**: Configuration schemas validate scanner and generator inputs with security constraints to prevent path traversal... - **Anti Pattern Detector Testing**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... -- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Result Monad**: The Result type provides explicit error handling via a discriminated union. - **Error Factories**: Error factories create structured, discriminated error types with consistent message formatting. - **Gherkin Ast Parser**: The Gherkin AST parser extracts feature metadata, scenarios, and steps from .feature files for timeline generation... @@ -299,13 +299,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Extraction Pipeline Enhancements Testing**: Validates extraction pipeline capabilities for ReferenceDocShowcase: function signature surfacing, full... - **Dual Source Extractor Testing**: Extracts and combines pattern metadata from both TypeScript code stubs (@architect-) and Gherkin feature files... - **Declaration Level Shape Tagging Testing**: Tests the discoverTaggedShapes function that scans TypeScript source code for declarations annotated with the... -- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... -- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... -- **Preset System**: Presets provide pre-configured taxonomies for different project types. -- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... -- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. -- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... -- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... - **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... - **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... @@ -317,14 +310,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . - **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... - **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. +- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... +- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... +- **Preset System**: Presets provide pre-configured taxonomies for different project types. +- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... +- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. +- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... +- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Validate Patterns Cli**: Command-line interface for cross-validating TypeScript patterns vs Gherkin feature files. -- **Process Api Cli Subcommands**: Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. -- **Process Api Cli Modifiers And Rules**: Output modifiers, arch health, and rules subcommand. -- **Process Api Cli Core**: Core CLI infrastructure: help, version, input validation, status, query, pattern, arch basics, missing args, edge cases. +- **Pattern Graph Cli Subcommands**: Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. +- **Pattern Graph Cli Modifiers And Rules**: Output modifiers, arch health, and rules subcommand. +- **Pattern Graph Cli Core**: Core CLI infrastructure: help, version, input validation, status, query, pattern, arch basics, missing args, edge cases. - **Lint Process Cli**: Command-line interface for validating changes against delivery process rules. - **Lint Patterns Cli**: Command-line interface for validating pattern annotation quality. - **Generate Docs Cli**: Command-line interface for generating documentation from annotated TypeScript. -- **Pattern Graph API Testing**: Programmatic interface for querying delivery process state. +- **Pattern Graph API Testing**: Programmatic interface for querying the pattern graph and delivery process state. - **Transform Dataset Testing**: The transformToPatternGraph function transforms raw extracted patterns into a PatternGraph with all pre-computed... - **Session Handoffs**: The delivery process supports mid-phase handoffs between sessions and coordination across multiple developers through... - **Session File Lifecycle**: Orphaned session files are automatically cleaned up during generation, maintaining a clean docs-living/sessions/... @@ -353,7 +353,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Linter Validation Testing**: Tests for lint rules that validate relationship integrity, detect conflicts, and ensure bidirectional traceability... - **Implements Tag Processing**: Tests for the @architect-implements tag which links implementation files to their corresponding roadmap pattern... - **Extends Tag Testing**: Tests for the @architect-extends tag which establishes generalization relationships between patterns (pattern... -- **Process Api Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... +- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform PatternGraph into... - **Shape Selector Testing**: Tests the filterShapesBySelectors function that provides fine-grained shape selection via structural discriminated... - **Shape Matcher Testing**: Matches file paths against glob patterns for TypeScript shape extraction. diff --git a/docs-live/INDEX.md b/docs-live/INDEX.md index 9ad90393..5280b9a0 100644 --- a/docs-live/INDEX.md +++ b/docs-live/INDEX.md @@ -27,8 +27,8 @@ | Understand the tag taxonomy | [TAXONOMY.md](TAXONOMY.md) | | Check validation rules | [VALIDATION-RULES.md](VALIDATION-RULES.md) | | Browse the changelog | [CHANGELOG-GENERATED.md](CHANGELOG-GENERATED.md) | -| Query process state via CLI | [Process API Reference](reference/CLI-REFERENCE.md) | -| Find CLI workflow recipes | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | +| Query process state via CLI | [CLI Reference](reference/CLI-REFERENCE.md) | +| Find CLI workflow recipes | [CLI Recipes](reference/CLI-RECIPES.md) | | Run AI coding sessions | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | | Learn annotation mechanics | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | @@ -55,7 +55,7 @@ 1. **[Annotation Reference](reference/ANNOTATION-REFERENCE.md)** -- Annotation mechanics and tag reference 2. **[Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md)** -- Planning, Design, Implementation workflows -3. **[Process API Reference](reference/CLI-REFERENCE.md)** -- CLI command reference with flags and examples +3. **[CLI Reference](reference/CLI-REFERENCE.md)** -- Pattern Graph CLI command reference with flags and examples 4. **[Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md)** -- Pre-commit hooks, error codes, programmatic API --- @@ -73,8 +73,8 @@ | CHANGELOG-GENERATED.md | Everyone | Project changelog from release specs | | Annotation Reference | Developers | Annotation mechanics, shape extraction | | Session Workflow Guide | AI/Devs | Session decision trees and workflow checklists | -| Process API Reference | AI/Devs | CLI command reference with flags and examples | -| Process API Recipes | AI/Devs | CLI workflow recipes and session guides | +| CLI Reference | AI/Devs | CLI command reference with flags and examples | +| CLI Recipes | AI/Devs | CLI workflow recipes and session guides | | Process Guard Reference | Team Leads | Pre-commit hooks, error codes, programmatic API | | Architecture Codecs | Developers | All codecs with factory patterns and options | | Architecture Types | Developers | PatternGraph interface and type shapes | @@ -122,8 +122,8 @@ | --------------------------------------------------------------- | -------------------------------------------------------------------- | ---------- | | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | Annotation mechanics, shape extraction, tag reference | Developers | | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | Planning, Design, Implementation session workflows | AI/Devs | -| [Process API Reference](reference/CLI-REFERENCE.md) | CLI command reference with flags and examples | AI/Devs | -| [Process API Recipes](reference/PROCESS-API-RECIPES.md) | CLI workflow recipes and session guides | AI/Devs | +| [CLI Reference](reference/CLI-REFERENCE.md) | Pattern Graph CLI command reference with flags and examples | AI/Devs | +| [CLI Recipes](reference/CLI-RECIPES.md) | Pattern Graph CLI workflow recipes and session guides | AI/Devs | | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | Pre-commit hooks, error codes, programmatic API | Team Leads | | [Architecture Codecs](reference/ARCHITECTURE-CODECS.md) | All codecs with factory patterns and options | Developers | | [Architecture Types](reference/ARCHITECTURE-TYPES.md) | PatternGraph interface and type shapes | Developers | @@ -226,6 +226,6 @@ pnpm docs:business-rules # Business rules pnpm docs:taxonomy # Taxonomy reference pnpm docs:validation # Validation rules pnpm docs:claude-modules # Claude context modules -pnpm docs:cli-reference # Process API CLI reference +pnpm docs:cli-reference # Pattern Graph CLI reference pnpm docs:cli-recipe # CLI recipes & workflow guide ``` diff --git a/docs-live/_claude-md/annotation/annotation-overview.md b/docs-live/_claude-md/annotation/annotation-overview.md index 737875e3..667930e6 100644 --- a/docs-live/_claude-md/annotation/annotation-overview.md +++ b/docs-live/_claude-md/annotation/annotation-overview.md @@ -19,8 +19,8 @@ | MetadataTagDefinitionForRegistry | interface | | CategoryDefinition | interface | | CategoryTag | type | -| buildRegistry | function | | isShapeOnlyDirective | function | +| buildRegistry | function | | METADATA_TAGS_BY_GROUP | const | | CATEGORIES | const | | CATEGORY_TAGS | const | diff --git a/docs-live/_claude-md/process/process-overview.md b/docs-live/_claude-md/process/process-overview.md index 8ac4354c..d49818de 100644 --- a/docs-live/_claude-md/process/process-overview.md +++ b/docs-live/_claude-md/process/process-overview.md @@ -124,4 +124,4 @@ | superseded | Replaced by another | | n/a | Not applicable | -**Components:** Other (ADR006SingleReadModelArchitecture, ADR003SourceFirstPatternArchitecture, ADR002GherkinOnlyTesting, ADR001TaxonomyCanonicalValues, ValidatorReadModelConsolidation, StepDefinitionCompletion, SessionFileCleanup, ProcessAPILayeredExtraction, OrchestratorPipelineFactoryMigration, MvpWorkflowImplementation, LivingRoadmapCLI, EffortVarianceTracking, ConfigBasedWorkflowDefinition, CliBehaviorTesting, SessionHandoffs, SessionFileLifecycle) +**Components:** Other (ADR006SingleReadModelArchitecture, ADR003SourceFirstPatternArchitecture, ADR002GherkinOnlyTesting, ADR001TaxonomyCanonicalValues, ValidatorReadModelConsolidation, StepDefinitionCompletion, SessionFileCleanup, PatternGraphLayeredExtraction, OrchestratorPipelineFactoryMigration, MvpWorkflowImplementation, LivingRoadmapCLI, EffortVarianceTracking, ConfigBasedWorkflowDefinition, CliBehaviorTesting, SessionHandoffs, SessionFileLifecycle) diff --git a/docs-live/business-rules/data-api.md b/docs-live/business-rules/data-api.md index cc7af478..7ed54de0 100644 --- a/docs-live/business-rules/data-api.md +++ b/docs-live/business-rules/data-api.md @@ -746,40 +746,7 @@ _- Markdown generation is not ideal for programmatic access_ _pattern-graph-api.feature_ -### Pattern Summarize Tests - -_Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to_ - ---- - -#### summarizePattern projects to compact summary - -> **Invariant:** 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. -> -> **Rationale:** Compact summaries reduce token usage by 80-90% compared to full patterns — they provide enough context for navigation without overwhelming AI context windows. - -**Verified by:** - -- Summary includes all 6 fields for a TypeScript pattern -- Summary includes all 6 fields for a Gherkin pattern -- Summary uses patternName tag over name field -- Summary omits undefined optional fields - ---- - -#### summarizePatterns batch processes arrays - -> **Invariant:** summarizePatterns must batch-process an array of patterns, returning a correctly-sized array of compact summaries. -> -> **Rationale:** Batch processing avoids N individual function calls — the API frequently needs to summarize all patterns matching a query in a single operation. - -**Verified by:** - -- Batch summarization returns correct count - -_summarize.feature_ - -### Process Api Cli Cache +### Pattern Graph Cli Cache _PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass._ @@ -799,7 +766,7 @@ _PatternGraph caching between CLI invocations: cache hits, mtime invalidation, a _data-api-cache.feature_ -### Process Api Cli Core +### Pattern Graph Cli Core _Core CLI infrastructure: help, version, input validation, status, query, pattern, arch basics, missing args, edge cases._ @@ -913,7 +880,7 @@ _Core CLI infrastructure: help, version, input validation, status, query, patter _pattern-graph-cli-core.feature_ -### Process Api Cli Dry Run +### Pattern Graph Cli Dry Run _Dry-run mode shows pipeline scope without processing data._ @@ -932,7 +899,7 @@ _Dry-run mode shows pipeline scope without processing data._ _data-api-dryrun.feature_ -### Process Api Cli Help +### Pattern Graph Cli Help _Per-subcommand help displays usage, flags, and examples for individual subcommands._ @@ -952,7 +919,7 @@ _Per-subcommand help displays usage, flags, and examples for individual subcomma _data-api-help.feature_ -### Process Api Cli Metadata +### Pattern Graph Cli Metadata _Response metadata includes validation summary and pipeline timing for diagnostics._ @@ -971,7 +938,7 @@ _Response metadata includes validation summary and pipeline timing for diagnosti _data-api-metadata.feature_ -### Process Api Cli Modifiers And Rules +### Pattern Graph Cli Modifiers And Rules _Output modifiers, arch health, and rules subcommand._ @@ -1025,7 +992,49 @@ _Output modifiers, arch health, and rules subcommand._ _pattern-graph-cli-modifiers-rules.feature_ -### Process Api Cli Repl +### Pattern Graph Cli Reference Tests + +_Verifies that the declarative CLI schema drives reference table generation_ + +--- + +#### Generated reference file contains all three table sections + +> **Invariant:** CLI-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema. + +**Verified by:** + +- Generated file contains Global Options table +- Generated file contains Output Modifiers table +- Generated file contains List Filters table +- Generated file includes inter-table prose + +--- + +#### CLI schema stays in sync with parser + +> **Invariant:** Every flag recognized by parseArgs() has a corresponding entry in the CLI schema. A missing schema entry means the sync test fails. + +**Verified by:** + +- Schema covers all global option flags +- Schema covers all output modifier flags +- Schema covers all list filter flags +- Schema covers session option + +--- + +#### showHelp output reflects CLI schema + +> **Invariant:** The help text rendered by showHelp() includes all options from the CLI schema, formatted for terminal display. + +**Verified by:** + +- Help text includes schema-defined options + +_cli-reference.feature_ + +### Pattern Graph Cli Repl _Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload._ @@ -1056,7 +1065,7 @@ _Interactive REPL mode keeps the pipeline loaded for multi-query sessions and su _data-api-repl.feature_ -### Process Api Cli Subcommands +### Pattern Graph Cli Subcommands _Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated._ @@ -1142,47 +1151,38 @@ _Discovery subcommands: list, search, context assembly, tags/sources, extended a _pattern-graph-cli-subcommands.feature_ -### Process Api Reference Tests - -_Verifies that the declarative CLI schema drives reference table generation_ - ---- - -#### Generated reference file contains all three table sections - -> **Invariant:** CLI-REFERENCE.md contains Global Options, Output Modifiers, and List Filters tables generated from the CLI schema. - -**Verified by:** +### Pattern Summarize Tests -- Generated file contains Global Options table -- Generated file contains Output Modifiers table -- Generated file contains List Filters table -- Generated file includes inter-table prose +_Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to_ --- -#### CLI schema stays in sync with parser +#### summarizePattern projects to compact summary -> **Invariant:** Every flag recognized by parseArgs() has a corresponding entry in the CLI schema. A missing schema entry means the sync test fails. +> **Invariant:** 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. +> +> **Rationale:** Compact summaries reduce token usage by 80-90% compared to full patterns — they provide enough context for navigation without overwhelming AI context windows. **Verified by:** -- Schema covers all global option flags -- Schema covers all output modifier flags -- Schema covers all list filter flags -- Schema covers session option +- Summary includes all 6 fields for a TypeScript pattern +- Summary includes all 6 fields for a Gherkin pattern +- Summary uses patternName tag over name field +- Summary omits undefined optional fields --- -#### showHelp output reflects CLI schema +#### summarizePatterns batch processes arrays -> **Invariant:** The help text rendered by showHelp() includes all options from the CLI schema, formatted for terminal display. +> **Invariant:** summarizePatterns must batch-process an array of patterns, returning a correctly-sized array of compact summaries. +> +> **Rationale:** Batch processing avoids N individual function calls — the API frequently needs to summarize all patterns matching a query in a single operation. **Verified by:** -- Help text includes schema-defined options +- Batch summarization returns correct count -_cli-reference.feature_ +_summarize.feature_ ### Scope Validator Tests diff --git a/docs-live/product-areas/ANNOTATION.md b/docs-live/product-areas/ANNOTATION.md index 773cad42..f9d6eaa1 100644 --- a/docs-live/product-areas/ANNOTATION.md +++ b/docs-live/product-areas/ANNOTATION.md @@ -210,35 +210,35 @@ interface CategoryDefinition { type CategoryTag = (typeof CATEGORIES)[number]['tag']; ``` -### buildRegistry (function) +### isShapeOnlyDirective (function) ```typescript /** - * Build the complete tag registry from TypeScript constants + * Check if a directive is a shape-only annotation (declaration-level @architect-shape). * - * This is THE single source of truth for the taxonomy. - * All consumers should use this function instead of loading JSON. + * Shape directives annotate individual interfaces/types for documentation extraction. + * They inherit context from a parent pattern and should not enter the directive pipeline + * as standalone patterns. */ ``` ```typescript -function buildRegistry(): TagRegistry; +function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; ``` -### isShapeOnlyDirective (function) +### buildRegistry (function) ```typescript /** - * Check if a directive is a shape-only annotation (declaration-level @architect-shape). + * Build the complete tag registry from TypeScript constants * - * Shape directives annotate individual interfaces/types for documentation extraction. - * They inherit context from a parent pattern and should not enter the directive pipeline - * as standalone patterns. + * This is THE single source of truth for the taxonomy. + * All consumers should use this function instead of loading JSON. */ ``` ```typescript -function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; +function buildRegistry(): TagRegistry; ``` ### METADATA_TAGS_BY_GROUP (const) diff --git a/docs-live/product-areas/DATA-API.md b/docs-live/product-areas/DATA-API.md index a2690831..ac516902 100644 --- a/docs-live/product-areas/DATA-API.md +++ b/docs-live/product-areas/DATA-API.md @@ -707,41 +707,13 @@ ArchIndexSchema = z.object({ | 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. | -### Pattern Helpers Tests - -| 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. | - -### Pattern Summarize Tests - -| 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. | - -### PDR 001 Session Workflow Commands - -| 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. | - -### Process Api Cli Cache +### Pattern Graph Cli Cache | 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 | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -754,25 +726,25 @@ ArchIndexSchema = z.object({ | 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 | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -780,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 | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -798,7 +778,7 @@ 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 | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -808,13 +788,33 @@ ArchIndexSchema = z.object({ | Pipeline factory returns Result for consumer-owned error handling | The factory returns `Result` 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 +### Pattern Helpers 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. | | +| 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. | + +### Pattern Summarize Tests + +| 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. | + +### PDR 001 Session Workflow Commands + +| 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 diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index d1776b62..274926d7 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -59,11 +59,11 @@ Scoped architecture diagram showing component relationships: ```mermaid graph TB subgraph generator["Generator"] + SourceMapper[/"SourceMapper"/] + Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") GitModule["GitModule"] GitHelpers["GitHelpers"] GitBranchDiff["GitBranchDiff"] - SourceMapper[/"SourceMapper"/] - Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") TransformTypes["TransformTypes"] TransformDataset("TransformDataset") SequenceTransformUtils("SequenceTransformUtils") @@ -98,12 +98,12 @@ graph TB ContextInference["ContextInference"]:::neighbor end loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - GitModule -->|uses| GitBranchDiff - GitModule -->|uses| GitHelpers SourceMapper -.->|depends on| DecisionDocCodec SourceMapper -.->|depends on| ShapeExtractor SourceMapper -.->|depends on| GherkinASTParser Documentation_Generation_Orchestrator -->|uses| Pattern_Scanner + GitModule -->|uses| GitBranchDiff + GitModule -->|uses| GitHelpers PatternsCodec ..->|implements| PatternRelationshipModel DesignReviewCodec -->|uses| PatternGraph DesignReviewCodec -->|uses| MermaidDiagramUtils @@ -427,13 +427,13 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ### Cli Recipe Codec -| Rule | Invariant | Rationale | -| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/PROCESS-API-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | -| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | -| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | -| Generated recipe file complements manual PROCESS-API.md | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/PROCESS-API-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | -| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/CLI-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | +| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | +| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | +| Generated recipe file complements manual PROCESS-API.md | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/CLI-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | +| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | ### Cli Reference Generation diff --git a/docs-live/product-areas/PROCESS.md b/docs-live/product-areas/PROCESS.md index 99080207..79d4c68a 100644 --- a/docs-live/product-areas/PROCESS.md +++ b/docs-live/product-areas/PROCESS.md @@ -236,7 +236,7 @@ graph LR ValidatorReadModelConsolidation["ValidatorReadModelConsolidation"] StepDefinitionCompletion["StepDefinitionCompletion"] SessionFileCleanup["SessionFileCleanup"] - ProcessAPILayeredExtraction["ProcessAPILayeredExtraction"] + PatternGraphLayeredExtraction["PatternGraphLayeredExtraction"] OrchestratorPipelineFactoryMigration["OrchestratorPipelineFactoryMigration"] MvpWorkflowImplementation["MvpWorkflowImplementation"] LivingRoadmapCLI["LivingRoadmapCLI"] @@ -252,8 +252,8 @@ graph LR ValidatorReadModelConsolidation -.->|depends on| ADR006SingleReadModelArchitecture StepDefinitionCompletion -.->|depends on| ADR002GherkinOnlyTesting SessionFileCleanup -.->|depends on| SessionFileLifecycle - ProcessAPILayeredExtraction -.->|depends on| ValidatorReadModelConsolidation - OrchestratorPipelineFactoryMigration -.->|depends on| ProcessAPILayeredExtraction + PatternGraphLayeredExtraction -.->|depends on| ValidatorReadModelConsolidation + OrchestratorPipelineFactoryMigration -.->|depends on| PatternGraphLayeredExtraction LivingRoadmapCLI -.->|depends on| MvpWorkflowImplementation EffortVarianceTracking -.->|depends on| MvpWorkflowImplementation ConfigBasedWorkflowDefinition -.->|depends on| MvpWorkflowImplementation diff --git a/docs-live/product-areas/VALIDATION.md b/docs-live/product-areas/VALIDATION.md index 51e7f4a6..be820f56 100644 --- a/docs-live/product-areas/VALIDATION.md +++ b/docs-live/product-areas/VALIDATION.md @@ -45,8 +45,8 @@ C4Context System(FSMTransitions, "FSMTransitions") System(FSMStates, "FSMStates") } - System_Ext(CodecUtils, "CodecUtils") System_Ext(DoDValidationTypes, "DoDValidationTypes") + System_Ext(CodecUtils, "CodecUtils") System_Ext(DualSourceExtractor, "DualSourceExtractor") System_Ext(DetectChanges, "DetectChanges") System_Ext(DeriveProcessState, "DeriveProcessState") @@ -95,8 +95,8 @@ graph LR FSMStates[/"FSMStates"/] end subgraph related["Related"] - CodecUtils["CodecUtils"]:::neighbor DoDValidationTypes["DoDValidationTypes"]:::neighbor + CodecUtils["CodecUtils"]:::neighbor DualSourceExtractor["DualSourceExtractor"]:::neighbor DetectChanges["DetectChanges"]:::neighbor DeriveProcessState["DeriveProcessState"]:::neighbor diff --git a/docs-live/reference/PROCESS-API-RECIPES.md b/docs-live/reference/CLI-RECIPES.md similarity index 99% rename from docs-live/reference/PROCESS-API-RECIPES.md rename to docs-live/reference/CLI-RECIPES.md index 73d15456..5ae529f2 100644 --- a/docs-live/reference/PROCESS-API-RECIPES.md +++ b/docs-live/reference/CLI-RECIPES.md @@ -1,4 +1,4 @@ -# Process API CLI — Recipes & Workflow Guide +# Pattern Graph CLI Recipes & Workflow Guide > Auto-generated from CLI schema. See [CLI Reference](./CLI-REFERENCE.md) for flag tables. diff --git a/docs-live/reference/CLI-REFERENCE.md b/docs-live/reference/CLI-REFERENCE.md index a14620f6..8b79d8f5 100644 --- a/docs-live/reference/CLI-REFERENCE.md +++ b/docs-live/reference/CLI-REFERENCE.md @@ -1,6 +1,6 @@ -# Process API CLI Reference +# Pattern Graph CLI Reference -> Auto-generated from CLI schema. See [Process API Guide](../../docs/PROCESS-API.md) for usage examples and recipes. +> Auto-generated from CLI schema. See [Pattern Graph CLI Guide](../../docs/PROCESS-API.md) for usage examples and recipes. ## Global Options diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index 70c51571..0b1f2990 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -421,7 +421,6 @@ graph LR end TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - CLISchema ..->|implements| CliReferenceGeneration ProjectConfigTypes -->|uses| ConfigurationTypes ProjectConfigTypes -->|uses| ConfigurationPresets ConfigurationPresets -->|uses| ConfigurationTypes @@ -429,6 +428,7 @@ graph LR ArchQueriesImpl -->|uses| PatternGraphAPI ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries + CLISchema ..->|implements| CliReferenceGeneration FSMTransitions ..->|implements| PhaseStateMachineValidation FSMStates ..->|implements| PhaseStateMachineValidation PatternGraphAPI -->|uses| PatternGraph diff --git a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md index d885edb2..38272754 100644 --- a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md +++ b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md @@ -205,7 +205,7 @@ Three-layer architecture after Phase 39: | No CLAUDE.md drift | Session workflow section generated, not hand-authored | | Single annotated source | This spec owns all session workflow invariants | | Correct audience alignment | Public guide stays in docs/, AI context in \_claude-md/ | -| Process API coverage | Session workflow content queryable via `pnpm process:query -- rules` | +| Pattern Graph CLI coverage | Session workflow content queryable via `pnpm architect:query -- rules` | | Immediately useful | Rule: blocks are queryable today, generation follows when Phase 25 ships | **Design Session Findings (2026-03-05):** diff --git a/docs-sources/index-navigation.md b/docs-sources/index-navigation.md index 81d71cec..3a78c6ac 100644 --- a/docs-sources/index-navigation.md +++ b/docs-sources/index-navigation.md @@ -9,8 +9,8 @@ | Understand the tag taxonomy | [TAXONOMY.md](TAXONOMY.md) | | Check validation rules | [VALIDATION-RULES.md](VALIDATION-RULES.md) | | Browse the changelog | [CHANGELOG-GENERATED.md](CHANGELOG-GENERATED.md) | -| Query process state via CLI | [Process API Reference](reference/CLI-REFERENCE.md) | -| Find CLI workflow recipes | [Process API Recipes](reference/PROCESS-API-RECIPES.md) | +| Query process state via CLI | [CLI Reference](reference/CLI-REFERENCE.md) | +| Find CLI workflow recipes | [CLI Recipes](reference/CLI-RECIPES.md) | | Run AI coding sessions | [Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md) | | Enforce delivery process rules | [Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md) | | Learn annotation mechanics | [Annotation Reference](reference/ANNOTATION-REFERENCE.md) | @@ -37,7 +37,7 @@ 7. **[Annotation Reference](reference/ANNOTATION-REFERENCE.md)** -- Annotation mechanics and tag reference 8. **[Session Workflow Guide](reference/SESSION-WORKFLOW-GUIDE.md)** -- Planning, Design, Implementation workflows -9. **[Process API Reference](reference/CLI-REFERENCE.md)** -- CLI command reference with flags and examples +9. **[CLI Reference](reference/CLI-REFERENCE.md)** -- Pattern Graph CLI command reference with flags and examples 10. **[Process Guard Reference](reference/PROCESS-GUARD-REFERENCE.md)** -- Pre-commit hooks, error codes, programmatic API --- @@ -55,8 +55,8 @@ | CHANGELOG-GENERATED.md | Everyone | Project changelog from release specs | | Annotation Reference | Developers | Annotation mechanics, shape extraction | | Session Workflow Guide | AI/Devs | Session decision trees and workflow checklists | -| Process API Reference | AI/Devs | CLI command reference with flags and examples | -| Process API Recipes | AI/Devs | CLI workflow recipes and session guides | +| CLI Reference | AI/Devs | CLI command reference with flags and examples | +| CLI Recipes | AI/Devs | CLI workflow recipes and session guides | | Process Guard Reference | Team Leads | Pre-commit hooks, error codes, programmatic API | | Architecture Codecs | Developers | All codecs with factory patterns and options | | Architecture Types | Developers | PatternGraph interface and type shapes | diff --git a/docs/DOCS-GAP-ANALYSIS.md b/docs/DOCS-GAP-ANALYSIS.md index 063ac083..656ba3ab 100644 --- a/docs/DOCS-GAP-ANALYSIS.md +++ b/docs/DOCS-GAP-ANALYSIS.md @@ -301,17 +301,17 @@ reference content from `docs-live/` instead of `docs-generated/`. These `docs-live/` subdirectories exist but have no sync function: -| Directory | Files | Content | -| ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -| `docs-live/reference/` | 5 files | ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md | -| `docs-live/taxonomy/` | 3 files | categories.md, format-types.md, metadata-tags.md | -| `docs-live/validation/` | 3 files | error-catalog.md, fsm-transitions.md, protection-levels.md | -| `docs-live/business-rules/` | 7 files | Per-area business rule extractions | -| `docs-live/_claude-md/` | 10 files | AI context (may not need website publishing) | -| `docs-live/INDEX.md` | 1 file | Generated docs master index | -| `docs-live/TAXONOMY.md` | 1 file | Taxonomy overview | -| `docs-live/VALIDATION-RULES.md` | 1 file | Validation rules overview | -| `docs-live/BUSINESS-RULES.md` | 1 file | Business rules overview | +| Directory | Files | Content | +| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | +| `docs-live/reference/` | 5 files | ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, CLI-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md | +| `docs-live/taxonomy/` | 3 files | categories.md, format-types.md, metadata-tags.md | +| `docs-live/validation/` | 3 files | error-catalog.md, fsm-transitions.md, protection-levels.md | +| `docs-live/business-rules/` | 7 files | Per-area business rule extractions | +| `docs-live/_claude-md/` | 10 files | AI context (may not need website publishing) | +| `docs-live/INDEX.md` | 1 file | Generated docs master index | +| `docs-live/TAXONOMY.md` | 1 file | Taxonomy overview | +| `docs-live/VALIDATION-RULES.md` | 1 file | Validation rules overview | +| `docs-live/BUSINESS-RULES.md` | 1 file | Business rules overview | --- @@ -334,7 +334,7 @@ These `docs-live/` subdirectories exist but have no sync function: | **ARCHITECTURE.md** | 1,638 | docs-live/product-areas/GENERATION.md (1,065 lines) + docs-live/reference/ARCHITECTURE-CODECS.md (630 lines) + docs-live/reference/ARCHITECTURE-TYPES.md (429 lines) | Partial | Generated covers pipeline stages and codec listings well. Missing: executive summary, data flow diagrams, workflow integration section, "Extending the System" guide, programmatic usage examples, quick reference card. | | **GHERKIN-PATTERNS.md** | 366 | None | None | Authoring style guide: 4 essential patterns, DataTable/DocString usage, tag conventions, feature file rich content rules, step linting reference. Pure editorial guidance -- no annotation source exists. | | **ANNOTATION-GUIDE.md** | 270 | docs-live/taxonomy/metadata-tags.md (649 lines) | Partial | Generated has exhaustive tag reference (56 tags). Missing: getting-started guide, shape extraction modes explanation, "Zod schema gotcha" documentation, verification steps, common issues troubleshooting table. | -| **PROCESS-API.md** | ~60 | docs-live/reference/CLI-REFERENCE.md + PROCESS-API-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | +| **PROCESS-API.md** | ~60 | docs-live/reference/CLI-REFERENCE.md + CLI-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | | **PROCESS-GUARD.md** | 341 | docs-live/validation/error-catalog.md (79 lines) + docs-live/validation/fsm-transitions.md (49 lines) + docs-live/validation/protection-levels.md | Partial | Generated has error types, FSM matrix, protection levels. Missing: error fix rationale ("why this rule exists"), escape hatch alternatives, pre-commit setup instructions (Husky), programmatic API guide, Decider pattern architecture diagram. | | **VALIDATION.md** | 418 | docs-live/product-areas/VALIDATION.md (1,115 lines) | Partial | Generated has pattern listings and business rules. Missing: "Which command do I run?" decision tree, 32+ individual lint rule explanations with code examples, anti-pattern detection rationale, CI/CD integration patterns (GitHub Actions YAML), vitest-cucumber two-pattern problem explanation. | | **TAXONOMY.md** | 107 | docs-live/TAXONOMY.md (199 lines) + docs-live/taxonomy/ (3 files) | Good | Generated taxonomy reference is actually more comprehensive than manual. Manual adds: architecture explanation (file structure of src/taxonomy/), preset-to-taxonomy mapping, generation commands. Small gap. | @@ -354,18 +354,18 @@ These `docs-live/` subdirectories exist but have no sync function: ### 7.1 Missing Content Types in Generated Docs -| Content Type | Present in docs/ | Present in docs-live/ | Examples | -| ---------------------------- | ---------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------- | -| Decision trees | Yes (3 docs) | No | "Which validation command?", "Which session type?", "When to use design session?" | -| Step-by-step checklists | Yes (SESSION-GUIDES) | No | Planning session checklist, implementation 5-step execution order | -| CLI recipes with output | Yes (PROCESS-API) | Yes (PROCESS-API-RECIPES.md) | WP-6 complete: generated from CLI_SCHEMA | -| Error fix guides | Yes (PROCESS-GUARD) | Partial (error-catalog) | "completed-protection: add unlock-reason tag" with alternatives | -| Code examples (before/after) | Yes (VALIDATION) | No | Lint rule violation + fix side-by-side | -| Philosophical rationale | Yes (METHODOLOGY) | No | USDP inversion thesis, event sourcing analogy | -| Integration patterns | Yes (VALIDATION, PROCESS-GUARD) | No | Husky pre-commit, GitHub Actions YAML, package.json scripts | -| Getting-started guides | Yes (ANNOTATION-GUIDE) | No | "Add your first annotation" walkthrough | -| Gotcha documentation | Yes (ANNOTATION-GUIDE, GHERKIN-PATTERNS) | No | "Zod schema needs constant not type alias", "# kills Gherkin parsing" | -| Audience-based navigation | Yes (INDEX) | No | "New user read X, Developer read Y, Team Lead read Z" | +| Content Type | Present in docs/ | Present in docs-live/ | Examples | +| ---------------------------- | ---------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | +| Decision trees | Yes (3 docs) | No | "Which validation command?", "Which session type?", "When to use design session?" | +| Step-by-step checklists | Yes (SESSION-GUIDES) | No | Planning session checklist, implementation 5-step execution order | +| CLI recipes with output | Yes (PROCESS-API) | Yes (CLI-RECIPES.md) | WP-6 complete: generated from CLI_SCHEMA | +| Error fix guides | Yes (PROCESS-GUARD) | Partial (error-catalog) | "completed-protection: add unlock-reason tag" with alternatives | +| Code examples (before/after) | Yes (VALIDATION) | No | Lint rule violation + fix side-by-side | +| Philosophical rationale | Yes (METHODOLOGY) | No | USDP inversion thesis, event sourcing analogy | +| Integration patterns | Yes (VALIDATION, PROCESS-GUARD) | No | Husky pre-commit, GitHub Actions YAML, package.json scripts | +| Getting-started guides | Yes (ANNOTATION-GUIDE) | No | "Add your first annotation" walkthrough | +| Gotcha documentation | Yes (ANNOTATION-GUIDE, GHERKIN-PATTERNS) | No | "Zod schema needs constant not type alias", "# kills Gherkin parsing" | +| Audience-based navigation | Yes (INDEX) | No | "New user read X, Developer read Y, Team Lead read Z" | ### 7.2 Structural Quality Comparison @@ -782,7 +782,7 @@ adr-001 through adr-006, adr-021 annotation.md, configuration.md, core-types.md, data-api.md, generation.md, process.md, validation.md **Reference (5 files):** -ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, PROCESS-API-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md +ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md, CLI-RECIPES.md, CLI-REFERENCE.md, REFERENCE-SAMPLE.md **Taxonomy (3 files):** categories.md, format-types.md, metadata-tags.md diff --git a/docs/PROCESS-API.md b/docs/PROCESS-API.md index 12331a40..656ebf04 100644 --- a/docs/PROCESS-API.md +++ b/docs/PROCESS-API.md @@ -1,6 +1,6 @@ # Data API CLI -> **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md) and [Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes). +> **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md) and [CLI Recipes & Workflow Guide](../docs-live/reference/CLI-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes). > > Query process state directly from annotated source code. @@ -18,7 +18,7 @@ > For full CLI documentation, see the generated references below. - **[CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md)** — all flags, options, filters, and modifiers -- **[Recipes & Workflow Guide](../docs-live/reference/PROCESS-API-RECIPES.md)** — command descriptions, usage examples, and common recipes +- **[CLI Recipes & Workflow Guide](../docs-live/reference/CLI-RECIPES.md)** — command descriptions, usage examples, and common recipes --- diff --git a/src/api/index.ts b/src/api/index.ts index 8588dffa..c7a308f9 100644 --- a/src/api/index.ts +++ b/src/api/index.ts @@ -4,10 +4,10 @@ * @architect-pattern APIModule * @architect-status active * - * ## API Module - Programmatic Process State Interface + * ## API Module - Programmatic Pattern Graph Interface * - * Central export for the Process State API, providing a TypeScript - * interface for querying project state. + * Central export for the PatternGraphAPI, providing a TypeScript + * interface for querying the pattern graph and delivery state. * * ### When to Use * @@ -58,7 +58,7 @@ export type { export { createSuccess, createError, QueryApiError } from './types.js'; export type { NeighborEntry } from './types.js'; -// Process State API +// Pattern Graph API export type { PatternGraphAPI } from './pattern-graph-api.js'; export { createPatternGraphAPI } from './pattern-graph-api.js'; diff --git a/src/api/pattern-graph-api.ts b/src/api/pattern-graph-api.ts index 29e02760..88b22c66 100644 --- a/src/api/pattern-graph-api.ts +++ b/src/api/pattern-graph-api.ts @@ -9,7 +9,7 @@ * @architect-arch-layer application * @architect-uses PatternGraph, FSMValidator * - * ## Process State API - Programmatic Query Interface + * ## Pattern Graph API - Programmatic Query Interface * * TypeScript interface for querying project state. * Designed for Claude Code integration and programmatic access. @@ -49,7 +49,7 @@ import type { PatternGraph, ExtractedPattern, - PhaseGroup as MasterPhaseGroup, + PhaseGroup as SchemaPhaseGroup, } from '../validation-schemas/index.js'; import type { ProcessStatusValue } from '../taxonomy/index.js'; import { @@ -78,7 +78,7 @@ import type { } from './types.js'; // ============================================================================= -// Process State API Interface +// Pattern Graph API Interface // ============================================================================= /** @@ -296,7 +296,7 @@ export interface PatternGraphAPI { } // ============================================================================= -// Process State API Implementation +// Pattern Graph API Implementation // ============================================================================= /** @@ -311,8 +311,8 @@ export function createPatternGraphAPI(dataset: PatternGraph): PatternGraphAPI { return dataset.patterns.filter((p) => p.status === status); } - // Helper to convert MasterPhaseGroup to PhaseGroup - function convertPhaseGroup(mpg: MasterPhaseGroup): PhaseGroup { + // Helper to convert SchemaPhaseGroup to PhaseGroup + function convertPhaseGroup(mpg: SchemaPhaseGroup): PhaseGroup { return { phaseNumber: mpg.phaseNumber, phaseName: mpg.phaseName, diff --git a/src/api/rules-query.ts b/src/api/rules-query.ts index a0f39943..14742256 100644 --- a/src/api/rules-query.ts +++ b/src/api/rules-query.ts @@ -3,7 +3,7 @@ * @architect-core * @architect-pattern RulesQueryModule * @architect-status completed - * @architect-implements ProcessAPILayeredExtraction + * @architect-implements PatternGraphLayeredExtraction * @architect-product-area DataAPI * @architect-uses BusinessRulesCodec, CodecHelpers * @@ -13,7 +13,7 @@ * Groups rules by product area, phase, and feature pattern. * * Target: src/api/rules-query.ts - * See: DD-4 (ProcessAPILayeredExtraction) + * See: DD-4 (PatternGraphLayeredExtraction) * * **When to Use:** When querying business rules and invariants from Gherkin specs via the `rules` CLI subcommand. */ diff --git a/src/api/types.ts b/src/api/types.ts index 38fe6089..d37a5119 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -5,7 +5,7 @@ * @architect-status active * @architect-depends-on:PatternGraph * - * ## Process State API Types + * ## Pattern Graph API Types * * Type definitions for the PatternGraphAPI query interface. * Designed for programmatic access by Claude Code and other tools. diff --git a/src/generators/built-in/cli-recipe-generator.ts b/src/generators/built-in/cli-recipe-generator.ts index 4790d528..d2e6caf3 100644 --- a/src/generators/built-in/cli-recipe-generator.ts +++ b/src/generators/built-in/cli-recipe-generator.ts @@ -8,7 +8,7 @@ * * ## Standalone Generator for CLI Recipes and Command Narratives * - * Generates `PROCESS-API-RECIPES.md` from the declarative CLI schema. + * Generates `CLI-RECIPES.md` from the declarative CLI schema. * Sibling to `CliReferenceGenerator` — both implement * `DocumentGenerator`, both consume `CLI_SCHEMA` directly, neither depends * on PatternGraph (ADR-006 compliant). @@ -145,7 +145,7 @@ function buildRecipeDocument(preamble: readonly SectionBlock[]): string { } } - const doc = document('Process API CLI \u2014 Recipes & Workflow Guide', sections); + const doc = document('Pattern Graph CLI Recipes & Workflow Guide', sections); return renderToMarkdown(doc); } @@ -169,7 +169,7 @@ class CliRecipeGeneratorImpl implements DocumentGenerator { return Promise.resolve({ files: [ { - path: 'reference/PROCESS-API-RECIPES.md', + path: 'reference/CLI-RECIPES.md', content, }, ], diff --git a/src/generators/built-in/cli-reference-generator.ts b/src/generators/built-in/cli-reference-generator.ts index a1472062..aa815c57 100644 --- a/src/generators/built-in/cli-reference-generator.ts +++ b/src/generators/built-in/cli-reference-generator.ts @@ -7,7 +7,7 @@ * @architect-arch-layer application * @architect-product-area:Generation * - * ## Standalone Generator for Process API CLI Reference + * ## Standalone Generator for CLI Reference * * Generates `CLI-REFERENCE.md` from the declarative CLI schema. * Does NOT consume PatternGraph (ADR-006 compliant — CLI schema is static @@ -54,7 +54,7 @@ function buildReferenceDocument(): string { sections.push( paragraph( - '> Auto-generated from CLI schema. See [Process API Guide](../../docs/PROCESS-API.md) for usage examples and recipes.' + '> Auto-generated from CLI schema. See [Pattern Graph CLI Guide](../../docs/PROCESS-API.md) for usage examples and recipes.' ) ); @@ -82,7 +82,7 @@ function buildReferenceDocument(): string { sections.push(separator()); sections.push(...buildOptionSection(CLI_SCHEMA.sessionOptions, twoCol)); - const doc = document('Process API CLI Reference', sections); + const doc = document('Pattern Graph CLI Reference', sections); return renderToMarkdown(doc); } diff --git a/src/generators/built-in/codec-generators.ts b/src/generators/built-in/codec-generators.ts index 382b8fb2..2f5b58a2 100644 --- a/src/generators/built-in/codec-generators.ts +++ b/src/generators/built-in/codec-generators.ts @@ -189,11 +189,11 @@ generatorRegistry.register(createDecisionDocGenerator()); generatorRegistry.register(createDesignReviewGenerator()); // ═══════════════════════════════════════════════════════════════════════════ -// Process API Reference Generator (Schema-Based, not Codec-Based) +// CLI Reference Generator (Schema-Based, not Codec-Based) // ═══════════════════════════════════════════════════════════════════════════ /** - * Process API CLI Reference Generator + * Pattern Graph CLI Reference Generator * Generates CLI-REFERENCE.md from declarative CLI schema. * Standalone: does not consume PatternGraph (ADR-006). */ @@ -205,7 +205,7 @@ generatorRegistry.register(createCliReferenceGenerator()); /** * CLI Recipe & Workflow Guide Generator - * Generates PROCESS-API-RECIPES.md from declarative CLI schema. + * Generates CLI-RECIPES.md from declarative CLI schema. * Standalone: does not consume PatternGraph (ADR-006). */ let cliRecipePreamble: readonly SectionBlock[] = []; diff --git a/src/generators/pipeline/build-pipeline.ts b/src/generators/pipeline/build-pipeline.ts index e5422f09..c7b36e02 100644 --- a/src/generators/pipeline/build-pipeline.ts +++ b/src/generators/pipeline/build-pipeline.ts @@ -3,7 +3,7 @@ * @architect-generator @architect-infra * @architect-pattern PipelineFactory * @architect-status completed - * @architect-implements ProcessAPILayeredExtraction + * @architect-implements PatternGraphLayeredExtraction * @architect-product-area DataAPI * @architect-uses PatternScanner, GherkinScanner, DocExtractor, GherkinExtractor, PatternGraph * @architect-convention pipeline-architecture diff --git a/src/renderable/codecs/index-codec.ts b/src/renderable/codecs/index-codec.ts index 00fe7874..017cd6af 100644 --- a/src/renderable/codecs/index-codec.ts +++ b/src/renderable/codecs/index-codec.ts @@ -400,7 +400,7 @@ function buildRegenerationFooter(context: CodecContext): SectionBlock[] { 'pnpm docs:taxonomy # Taxonomy reference', 'pnpm docs:validation # Validation rules', 'pnpm docs:claude-modules # Claude context modules', - 'pnpm docs:cli-reference # Process API CLI reference', + 'pnpm docs:cli-reference # Pattern Graph CLI reference', 'pnpm docs:cli-recipe # CLI recipes & workflow guide', ].join('\n'), 'bash' diff --git a/tests/features/api/pattern-graph-api.feature b/tests/features/api/pattern-graph-api.feature index e99aec33..e0eb2f38 100644 --- a/tests/features/api/pattern-graph-api.feature +++ b/tests/features/api/pattern-graph-api.feature @@ -5,8 +5,8 @@ @behavior @pattern-graph-api @architect-pattern:PatternGraphAPITesting @architect-product-area:DataAPI -Feature: Process State API - Programmatic interface for querying delivery process state. +Feature: Pattern Graph API + Programmatic interface for querying the pattern graph and delivery process state. Designed for Claude Code integration and tool automation. **Problem:** diff --git a/tests/features/behavior/cli/cli-reference.feature b/tests/features/behavior/cli/cli-reference.feature index 6220434a..f32566d0 100644 --- a/tests/features/behavior/cli/cli-reference.feature +++ b/tests/features/behavior/cli/cli-reference.feature @@ -1,11 +1,11 @@ @architect -@architect-pattern:ProcessApiReferenceTests +@architect-pattern:PatternGraphCliReferenceTests @architect-implements:CliReferenceGeneration @architect-status:completed @architect-unlock-reason:Retroactive-completion-during-rebrand @architect-product-area:DataAPI @behavior @cli @cli-reference -Feature: Process API CLI Reference Generation +Feature: Pattern Graph CLI Reference Generation Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser implementation. diff --git a/tests/features/cli/data-api-cache.feature b/tests/features/cli/data-api-cache.feature index 7ac578bc..3bc027d2 100644 --- a/tests/features/cli/data-api-cache.feature +++ b/tests/features/cli/data-api-cache.feature @@ -1,10 +1,10 @@ @architect -@architect-pattern:ProcessApiCliCache +@architect-pattern:PatternGraphCliCache @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI @cli @pattern-graph-cli @cache -Feature: Process API CLI - Dataset Cache +Feature: Pattern Graph CLI - Dataset Cache PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. Background: diff --git a/tests/features/cli/data-api-dryrun.feature b/tests/features/cli/data-api-dryrun.feature index c4683db6..ce00547b 100644 --- a/tests/features/cli/data-api-dryrun.feature +++ b/tests/features/cli/data-api-dryrun.feature @@ -1,10 +1,10 @@ @architect -@architect-pattern:ProcessApiCliDryRun +@architect-pattern:PatternGraphCliDryRun @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI @cli @pattern-graph-cli @dry-run -Feature: Process API CLI - Dry Run +Feature: Pattern Graph CLI - Dry Run Dry-run mode shows pipeline scope without processing data. Background: diff --git a/tests/features/cli/data-api-help.feature b/tests/features/cli/data-api-help.feature index a5fae379..1260dda6 100644 --- a/tests/features/cli/data-api-help.feature +++ b/tests/features/cli/data-api-help.feature @@ -1,10 +1,10 @@ @architect -@architect-pattern:ProcessApiCliHelp +@architect-pattern:PatternGraphCliHelp @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI @cli @pattern-graph-cli @help -Feature: Process API CLI - Per-Subcommand Help +Feature: Pattern Graph CLI - Per-Subcommand Help Per-subcommand help displays usage, flags, and examples for individual subcommands. Background: diff --git a/tests/features/cli/data-api-metadata.feature b/tests/features/cli/data-api-metadata.feature index e7119394..f0748c8d 100644 --- a/tests/features/cli/data-api-metadata.feature +++ b/tests/features/cli/data-api-metadata.feature @@ -1,10 +1,10 @@ @architect -@architect-pattern:ProcessApiCliMetadata +@architect-pattern:PatternGraphCliMetadata @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI @cli @pattern-graph-cli @metadata -Feature: Process API CLI - Response Metadata +Feature: Pattern Graph CLI - Response Metadata Response metadata includes validation summary and pipeline timing for diagnostics. Background: diff --git a/tests/features/cli/data-api-repl.feature b/tests/features/cli/data-api-repl.feature index c5e0acd7..21448489 100644 --- a/tests/features/cli/data-api-repl.feature +++ b/tests/features/cli/data-api-repl.feature @@ -1,10 +1,10 @@ @architect -@architect-pattern:ProcessApiCliRepl +@architect-pattern:PatternGraphCliRepl @architect-implements:DataAPICLIErgonomics @architect-status:active @architect-product-area:DataAPI @cli @pattern-graph-cli @repl -Feature: Process API CLI - REPL Mode +Feature: Pattern Graph CLI - REPL Mode Interactive REPL mode keeps the pipeline loaded for multi-query sessions and supports reload. Background: diff --git a/tests/features/cli/pattern-graph-cli-core.feature b/tests/features/cli/pattern-graph-cli-core.feature index f833289c..c2ea3574 100644 --- a/tests/features/cli/pattern-graph-cli-core.feature +++ b/tests/features/cli/pattern-graph-cli-core.feature @@ -1,11 +1,11 @@ @architect -@architect-pattern:ProcessApiCliCore -@architect-implements:ProcessApiCli +@architect-pattern:PatternGraphCliCore +@architect-implements:PatternGraphAPICLI @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI @cli @pattern-graph-cli -Feature: Process API CLI - Core Infrastructure +Feature: Pattern Graph CLI - Core Infrastructure Core CLI infrastructure: help, version, input validation, status, query, pattern, arch basics, missing args, edge cases. Background: diff --git a/tests/features/cli/pattern-graph-cli-modifiers-rules.feature b/tests/features/cli/pattern-graph-cli-modifiers-rules.feature index 56f97d31..fe8a27d1 100644 --- a/tests/features/cli/pattern-graph-cli-modifiers-rules.feature +++ b/tests/features/cli/pattern-graph-cli-modifiers-rules.feature @@ -1,11 +1,11 @@ @architect -@architect-pattern:ProcessApiCliModifiersAndRules -@architect-implements:ProcessApiCli +@architect-pattern:PatternGraphCliModifiersAndRules +@architect-implements:PatternGraphAPICLI @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI @cli @pattern-graph-cli -Feature: Process API CLI - Output Modifiers and Rules +Feature: Pattern Graph CLI - Output Modifiers and Rules Output modifiers, arch health, and rules subcommand. Background: diff --git a/tests/features/cli/pattern-graph-cli-subcommands.feature b/tests/features/cli/pattern-graph-cli-subcommands.feature index 6d0fbc67..9632c866 100644 --- a/tests/features/cli/pattern-graph-cli-subcommands.feature +++ b/tests/features/cli/pattern-graph-cli-subcommands.feature @@ -1,11 +1,11 @@ @architect -@architect-pattern:ProcessApiCliSubcommands -@architect-implements:ProcessApiCli +@architect-pattern:PatternGraphCliSubcommands +@architect-implements:PatternGraphAPICLI @architect-status:completed @architect-unlock-reason:'Split-from-original' @architect-product-area:DataAPI @cli @pattern-graph-cli -Feature: Process API CLI - Discovery Subcommands +Feature: Pattern Graph CLI - Discovery Subcommands Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. Background: diff --git a/tests/steps/api/pattern-graph-api.steps.ts b/tests/steps/api/pattern-graph-api.steps.ts index a46a4375..887fa3ea 100644 --- a/tests/steps/api/pattern-graph-api.steps.ts +++ b/tests/steps/api/pattern-graph-api.steps.ts @@ -1,5 +1,5 @@ /** - * Process State API Step Definitions + * Pattern Graph API Step Definitions * * BDD step definitions for testing the PatternGraphAPI query interface. * diff --git a/tests/steps/behavior/cli/cli-reference.steps.ts b/tests/steps/behavior/cli/cli-reference.steps.ts index 97ae38c3..643f2ed3 100644 --- a/tests/steps/behavior/cli/cli-reference.steps.ts +++ b/tests/steps/behavior/cli/cli-reference.steps.ts @@ -1,5 +1,5 @@ /** - * Step definitions for Process API CLI Reference Generation tests (Phase 43) + * Step definitions for Pattern Graph CLI reference generation tests (Phase 43) */ import { loadFeature, describeFeature } from '@amiceli/vitest-cucumber'; diff --git a/tests/support/helpers/pattern-graph-api-state.ts b/tests/support/helpers/pattern-graph-api-state.ts index 95a6b62c..1807b4d1 100644 --- a/tests/support/helpers/pattern-graph-api-state.ts +++ b/tests/support/helpers/pattern-graph-api-state.ts @@ -1,5 +1,5 @@ /** - * Process API CLI Shared Test State and Fixture Builders + * Pattern Graph CLI Shared Test State and Fixture Builders * * Extracted from pattern-graph-cli.steps.ts to be shared across * the split test files (core, subcommands, modifiers-rules). From dc6c703e40cc38cb5e402eef36ef8ba4c13a3e44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Thu, 2 Apr 2026 03:32:58 +0200 Subject: [PATCH 4/6] =?UTF-8?q?docs:=20regenerate=20all=20docs=20after=20p?= =?UTF-8?q?rocess-api=E2=86=92pattern-graph-cli=20rename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs-live/ARCHITECTURE.md | 32 +++---- docs-live/CHANGELOG-GENERATED.md | 96 +++++++++---------- docs-live/PRODUCT-AREAS.md | 4 +- .../core-types/core-types-overview.md | 2 +- docs-live/product-areas/CORE-TYPES.md | 4 +- docs-live/product-areas/GENERATION.md | 8 +- docs-live/product-areas/VALIDATION.md | 4 +- docs-live/reference/REFERENCE-SAMPLE.md | 8 +- docs-live/reference/SESSION-WORKFLOW-GUIDE.md | 2 +- 9 files changed, 80 insertions(+), 80 deletions(-) diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index 4ec126d6..4fb96f01 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -69,11 +69,11 @@ graph TB ContentDeduplicator["ContentDeduplicator[infrastructure]"] CodecBasedGenerator["CodecBasedGenerator[service]"] FileCache["FileCache[infrastructure]"] + DesignReviewGenerator["DesignReviewGenerator[service]"] + DecisionDocGenerator["DecisionDocGenerator[service]"] TransformDataset["TransformDataset[service]"] SequenceTransformUtils["SequenceTransformUtils[service]"] RelationshipResolver["RelationshipResolver[service]"] - DesignReviewGenerator["DesignReviewGenerator[service]"] - DecisionDocGenerator["DecisionDocGenerator[service]"] end subgraph lint["Lint BC"] LintRules["LintRules[service]"] @@ -125,25 +125,17 @@ graph TB MCPModule --> MCPPipelineSession MCPModule --> MCPFileWatcher MCPModule --> MCPToolRegistry + LintEngine --> LintRules + SourceMapper -.-> DecisionDocCodec + SourceMapper -.-> GherkinASTParser + Documentation_Generation_Orchestrator --> Pattern_Scanner GherkinExtractor --> GherkinASTParser DualSourceExtractor --> GherkinExtractor DualSourceExtractor --> GherkinScanner Document_Extractor --> Pattern_Scanner - LintEngine --> LintRules - ReplMode --> PatternGraphAPI - PatternGraphCLIImpl --> PatternGraphAPI - PatternGraphCLIImpl --> PatternGraph - PatternGraphCLIImpl --> PatternSummarizerImpl - PatternGraphCLIImpl --> FuzzyMatcherImpl - PatternGraphCLIImpl --> OutputPipelineImpl - OutputPipelineImpl --> PatternSummarizerImpl - MCPServerBin --> MCPServerImpl ConfigResolver --> ArchitectFactory ArchitectFactory --> RegexBuilders ConfigLoader --> ArchitectFactory - SourceMapper -.-> DecisionDocCodec - SourceMapper -.-> GherkinASTParser - Documentation_Generation_Orchestrator --> Pattern_Scanner PatternSummarizerImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraph @@ -161,17 +153,25 @@ graph TB ContextAssemblerImpl --> FuzzyMatcherImpl ArchQueriesImpl --> PatternGraphAPI ArchQueriesImpl --> PatternGraph + ReplMode --> PatternGraphAPI + PatternGraphCLIImpl --> PatternGraphAPI + PatternGraphCLIImpl --> PatternGraph + PatternGraphCLIImpl --> PatternSummarizerImpl + PatternGraphCLIImpl --> FuzzyMatcherImpl + PatternGraphCLIImpl --> OutputPipelineImpl + OutputPipelineImpl --> PatternSummarizerImpl + MCPServerBin --> MCPServerImpl FSMValidator --> FSMTransitions FSMValidator --> FSMStates DesignReviewCodec --> PatternGraph ArchitectureCodec --> PatternGraph ProcessGuardDecider --> FSMValidator - TransformDataset --> PatternGraph - SequenceTransformUtils --> PatternGraph DesignReviewGenerator --> DesignReviewCodec DesignReviewGenerator --> PatternGraph DecisionDocGenerator -.-> DecisionDocCodec DecisionDocGenerator -.-> SourceMapper + TransformDataset --> PatternGraph + SequenceTransformUtils --> PatternGraph ``` --- diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 05d127af..1b3cf0f3 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. - **MCP Tool Registry**: Defines all MCP tools with Zod input schemas and handler functions. - **MCP Server Impl**: Main entry point for the Architect MCP server. - **MCP Pipeline Session**: Manages the in-memory PatternGraph lifecycle for the MCP server. @@ -28,14 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Project Config Schema**: Zod validation schema for `ArchitectProjectConfig`. - **Source Merger**: Computes effective sources for a specific generator by applying per-generator overrides to the base resolved sources. - **Define Config**: Identity function for type-safe project configuration. -- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. -- **Pattern Graph CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. -- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. -- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. -- **Lint Process CLI**: Validates git changes against workflow rules. -- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **File Cache**: Simple Map-based cache for file contents during a single generation run. -- **Deliverable Status Taxonomy**: Canonical status values for deliverables in Gherkin Background tables. - **Pattern Graph API Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. - **Pattern Summarizer Impl**: Projects the full ExtractedPattern (~3.5KB per pattern) down to a PatternSummary (~100 bytes) for list queries. - **Stub Resolver Impl**: Identifies design session stubs in the PatternGraph and resolves them against the filesystem to determine... @@ -47,6 +41,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Context Formatter Impl**: First plain-text formatter in the codebase. - **Context Assembler Impl**: Pure function composition over PatternGraph. - **Arch Queries Impl**: Pure functions over PatternGraph for deep architecture exploration. +- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. +- **Pattern Graph CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. +- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. +- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. +- **Lint Process CLI**: Validates git changes against workflow rules. +- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **FSM Validator**: :PDR005MvpWorkflow Pure validation functions following the Decider pattern: - No I/O, no side effects - Return... - **FSM Transitions**: :PDR005MvpWorkflow Defines valid transitions between FSM states per PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **FSM States**: :PDR005MvpWorkflow Defines the 4-state FSM from PDR-005 MVP Workflow: - roadmap: Planned work (fully editable) -... @@ -61,11 +61,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... - **Derive Process State**: :GherkinScanner,FSMValidator Derives process state from @architect-\* annotations in files. - **Process Guard Decider**: :FSMValidator,DeriveProcessState,DetectChanges Pure function that validates changes against process rules. -- **Reference Generator Registration**: Registers all reference document generators. -- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **Transform Types**: Type definitions for the dataset transformation pipeline. - **Sequence Transform Utils**: :Generation Builds pre-computed SequenceIndexEntry objects from patterns that have sequence diagram annotations. - **Relationship Resolver**: Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) and detects dangling references in... +- **Reference Generator Registration**: Registers all reference document generators. +- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the pattern-graph-cli CLI. - **Design Review Generation**: Design reviews require manual creation of sequence and component diagrams that duplicate information already captured... - **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. @@ -86,13 +86,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Pattern Graph Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. - **Pattern Graph Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. - **Pattern Graph Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. -- **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... -- **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... - **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... - **Pattern Helpers Tests** - **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. - **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. - **Arch Queries Test** +- **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... +- **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... - **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... - **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... - **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. @@ -118,13 +118,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Public API**: Main entry point for the @libar-dev/architect package. -- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. -- **MCPServer — Entry Point and Lifecycle Manager**: Main entry point for the Architect MCP server. -- **PipelineSessionManager — In-Memory PatternGraph Lifecycle**: Manages the persistent PatternGraph that all MCP tool calls read from. -- **McpFileWatcher — Debounced Source File Watcher**: Watches TypeScript and Gherkin source files for changes, triggering debounced pipeline rebuilds. -- **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. -- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). -- **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... - **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. - **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... - **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. @@ -138,24 +131,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Dual Source Schemas**: Zod schemas for dual-source extraction types. - **Doc Directive Schema**: Zod schemas for validating parsed @architect-\* directives from JSDoc comments. - **Codec Utils**: Provides factory functions for creating type-safe JSON parsing and serialization pipelines using Zod schemas. -- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... -- **Utils Module**: Common helper functions used across the Architect package. -- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. -- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. -- **Result Monad Types**: Explicit error handling via discriminated union. -- **Error Factory Types**: Structured, discriminated error types with factory functions. +- **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). +- **Risk Levels**: Three-tier risk classification for roadmap planning. +- **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. +- **Normalized Status**: The Architect system uses a two-level status taxonomy: 1. +- **Layer Types**: Inferred from feature file directory paths: - timeline: Process/workflow features (architect) - domain: Business... +- **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... +- **Format Types**: Defines how tag values are parsed and validated. +- **Category Definitions**: Categories are used to classify patterns and organize documentation. - **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. - **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. - **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... - **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... +- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... +- **Utils Module**: Common helper functions used across the Architect package. +- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. +- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. - **Renderable Document Model(RDM)**: Unified document generation using codecs and a universal renderer. - **Document Generator**: Simplified document generation using codecs. +- **Result Monad Types**: Explicit error handling via discriminated union. +- **Error Factory Types**: Structured, discriminated error types with factory functions. - **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. - **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. - **Lint Engine**: Orchestrates lint rule execution against parsed directives. +- **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. +- **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. +- **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. +- **Source Mapper**: Aggregates content from multiple source files based on source mapping tables parsed from decision documents. +- **Generator Registry**: Manages registration and lookup of document generators (both built-in and custom). +- **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... +- **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. +- **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. - **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... - **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. - **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. @@ -168,31 +177,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architect Factory**: Main factory function for creating configured Architect instances. - **Configuration Defaults**: Centralized default constants for the Architect package. - **Config Loader**: Discovers and loads `architect.config.ts` or `architect.config.js` files for hierarchical configuration. -- **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. -- **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. -- **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. -- **Source Mapper**: Aggregates content from multiple source files based on source mapping tables parsed from decision documents. -- **Generator Registry**: Manages registration and lookup of document generators (both built-in and custom). -- **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... -- **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. -- **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. +- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. +- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. +- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. - **CLI Version Helper**: Reads package version from package.json for CLI --version flag. - **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. - **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. - **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. - **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. - **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. -- **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). -- **Risk Levels**: Three-tier risk classification for roadmap planning. -- **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. -- **Normalized Status**: The Architect system uses a two-level status taxonomy: 1. -- **Layer Types**: Inferred from feature file directory paths: - timeline: Process/workflow features (architect) - domain: Business... -- **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... -- **Format Types**: Defines how tag values are parsed and validated. -- **Category Definitions**: Categories are used to classify patterns and organize documentation. -- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. -- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. -- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. +- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. +- **MCPServer — Entry Point and Lifecycle Manager**: Main entry point for the Architect MCP server. +- **PipelineSessionManager — In-Memory PatternGraph Lifecycle**: Manages the persistent PatternGraph that all MCP tool calls read from. +- **McpFileWatcher — Debounced Source File Watcher**: Watches TypeScript and Gherkin source files for changes, triggering debounced pipeline rebuilds. +- **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. +- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). +- **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... - **Validation Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. - **Timeline Codec**: :Generation Purpose: Development roadmap organized by phase with progress tracking. - **Taxonomy Codec**: :Generation Transforms PatternGraph into a RenderableDocument for taxonomy reference output. @@ -215,15 +215,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Business Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for business rules output. - **Architecture Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing architecture diagrams (Mermaid) generated... - **Adr Document Codec**: :Generation Transforms PatternGraph into RenderableDocument for Architecture Decision Records. -- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. -- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. -- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. -- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Transform Dataset**: Transforms raw extracted patterns into a PatternGraph with all pre-computed views. - **Merge Patterns**: Merges patterns from TypeScript and Gherkin sources with conflict detection. - **Pipeline Module**: Barrel export for the unified transformation pipeline components. - **Context Inference Impl**: Auto-infers bounded context from file paths using configurable rules. - **Pipeline Factory**: Invariant: `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... +- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. +- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. +- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. +- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Codec Base Options**: :Add-createDecodeOnlyCodec-helper Shared types, interfaces, and utilities for all document codecs. - **ADR 006 Single Read Model Architecture**: The Architect package applies event sourcing to itself: git is the event store, annotated source files are... - **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (PatternGraph) into markdown files. @@ -349,11 +349,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Zod Codec Migration**: All JSON parsing and serialization uses type-safe Zod codec pattern, replacing raw JSON.parse/stringify with... - **Scope Validator Tests**: Starting an implementation or design session without checking prerequisites wastes time when blockers are discovered... - **Handoff Generator Tests**: Multi-session work loses critical state between sessions when handoff documentation is manual or forgotten. +- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Mermaid Relationship Rendering**: Tests for rendering all relationship types in Mermaid dependency graphs with distinct visual styles per relationship... - **Linter Validation Testing**: Tests for lint rules that validate relationship integrity, detect conflicts, and ensure bidirectional traceability... - **Implements Tag Processing**: Tests for the @architect-implements tag which links implementation files to their corresponding roadmap pattern... - **Extends Tag Testing**: Tests for the @architect-extends tag which establishes generalization relationships between patterns (pattern... -- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform PatternGraph into... - **Shape Selector Testing**: Tests the filterShapesBySelectors function that provides fine-grained shape selection via structural discriminated... - **Shape Matcher Testing**: Matches file paths against glob patterns for TypeScript shape extraction. diff --git a/docs-live/PRODUCT-AREAS.md b/docs-live/PRODUCT-AREAS.md index 38184a89..086a5075 100644 --- a/docs-live/PRODUCT-AREAS.md +++ b/docs-live/PRODUCT-AREAS.md @@ -120,9 +120,9 @@ C4Context System(DataAPIContextAssembly, "DataAPIContextAssembly") System(CrossCuttingDocumentInclusion, "CrossCuttingDocumentInclusion") System(CodecDrivenReferenceGeneration, "CodecDrivenReferenceGeneration") - System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") + System(StringUtils, "StringUtils") System(ExtractionPipelineEnhancementsTesting, "ExtractionPipelineEnhancementsTesting") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") @@ -199,9 +199,9 @@ graph LR DataAPIContextAssembly["DataAPIContextAssembly"] CrossCuttingDocumentInclusion["CrossCuttingDocumentInclusion"] CodecDrivenReferenceGeneration["CodecDrivenReferenceGeneration"] - StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] + StringUtils["StringUtils"] ExtractionPipelineEnhancementsTesting["ExtractionPipelineEnhancementsTesting"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] diff --git a/docs-live/_claude-md/core-types/core-types-overview.md b/docs-live/_claude-md/core-types/core-types-overview.md index 9eeab236..8c7bbafe 100644 --- a/docs-live/_claude-md/core-types/core-types-overview.md +++ b/docs-live/_claude-md/core-types/core-types-overview.md @@ -9,7 +9,7 @@ - Branded nominal types: `Branded` creates compile-time distinct types from structural TypeScript. Prevents mixing `PatternId` with `CategoryName` even though both are `string` at runtime - String transformation consistency: `slugify` produces URL-safe identifiers, `camelCaseToTitleCase` preserves acronyms (e.g., "APIEndpoint" becomes "API Endpoint"), `toKebabCase` handles consecutive uppercase correctly -**Components:** Other (StringUtils, FileCacheTesting, TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, KebabCaseSlugs, ErrorHandlingUnification) +**Components:** Other (TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, StringUtils, FileCacheTesting, KebabCaseSlugs, ErrorHandlingUnification) #### API Types diff --git a/docs-live/product-areas/CORE-TYPES.md b/docs-live/product-areas/CORE-TYPES.md index 999f7864..0bd9e85e 100644 --- a/docs-live/product-areas/CORE-TYPES.md +++ b/docs-live/product-areas/CORE-TYPES.md @@ -33,9 +33,9 @@ Scoped architecture diagram showing component relationships: ```mermaid C4Context title Core Type System - System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") + System(StringUtils, "StringUtils") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") Rel(KebabCaseSlugs, StringUtils, "depends on") @@ -51,9 +51,9 @@ Scoped architecture diagram showing component relationships: ```mermaid graph LR - StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] + StringUtils["StringUtils"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] KebabCaseSlugs -.->|depends on| StringUtils diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index 274926d7..34756472 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -59,11 +59,11 @@ Scoped architecture diagram showing component relationships: ```mermaid graph TB subgraph generator["Generator"] - SourceMapper[/"SourceMapper"/] - Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") GitModule["GitModule"] GitHelpers["GitHelpers"] GitBranchDiff["GitBranchDiff"] + SourceMapper[/"SourceMapper"/] + Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") TransformTypes["TransformTypes"] TransformDataset("TransformDataset") SequenceTransformUtils("SequenceTransformUtils") @@ -98,12 +98,12 @@ graph TB ContextInference["ContextInference"]:::neighbor end loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec + GitModule -->|uses| GitBranchDiff + GitModule -->|uses| GitHelpers SourceMapper -.->|depends on| DecisionDocCodec SourceMapper -.->|depends on| ShapeExtractor SourceMapper -.->|depends on| GherkinASTParser Documentation_Generation_Orchestrator -->|uses| Pattern_Scanner - GitModule -->|uses| GitBranchDiff - GitModule -->|uses| GitHelpers PatternsCodec ..->|implements| PatternRelationshipModel DesignReviewCodec -->|uses| PatternGraph DesignReviewCodec -->|uses| MermaidDiagramUtils diff --git a/docs-live/product-areas/VALIDATION.md b/docs-live/product-areas/VALIDATION.md index be820f56..51e7f4a6 100644 --- a/docs-live/product-areas/VALIDATION.md +++ b/docs-live/product-areas/VALIDATION.md @@ -45,8 +45,8 @@ C4Context System(FSMTransitions, "FSMTransitions") System(FSMStates, "FSMStates") } - System_Ext(DoDValidationTypes, "DoDValidationTypes") System_Ext(CodecUtils, "CodecUtils") + System_Ext(DoDValidationTypes, "DoDValidationTypes") System_Ext(DualSourceExtractor, "DualSourceExtractor") System_Ext(DetectChanges, "DetectChanges") System_Ext(DeriveProcessState, "DeriveProcessState") @@ -95,8 +95,8 @@ graph LR FSMStates[/"FSMStates"/] end subgraph related["Related"] - DoDValidationTypes["DoDValidationTypes"]:::neighbor CodecUtils["CodecUtils"]:::neighbor + DoDValidationTypes["DoDValidationTypes"]:::neighbor DualSourceExtractor["DualSourceExtractor"]:::neighbor DetectChanges["DetectChanges"]:::neighbor DeriveProcessState["DeriveProcessState"]:::neighbor diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index 0b1f2990..18000ec0 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -421,14 +421,14 @@ graph LR end TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - ProjectConfigTypes -->|uses| ConfigurationTypes - ProjectConfigTypes -->|uses| ConfigurationPresets - ConfigurationPresets -->|uses| ConfigurationTypes + CLISchema ..->|implements| CliReferenceGeneration PatternHelpers ..->|implements| DataAPIOutputShaping ArchQueriesImpl -->|uses| PatternGraphAPI ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries - CLISchema ..->|implements| CliReferenceGeneration + ProjectConfigTypes -->|uses| ConfigurationTypes + ProjectConfigTypes -->|uses| ConfigurationPresets + ConfigurationPresets -->|uses| ConfigurationTypes FSMTransitions ..->|implements| PhaseStateMachineValidation FSMStates ..->|implements| PhaseStateMachineValidation PatternGraphAPI -->|uses| PatternGraph diff --git a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md index 38272754..d885edb2 100644 --- a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md +++ b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md @@ -205,7 +205,7 @@ Three-layer architecture after Phase 39: | No CLAUDE.md drift | Session workflow section generated, not hand-authored | | Single annotated source | This spec owns all session workflow invariants | | Correct audience alignment | Public guide stays in docs/, AI context in \_claude-md/ | -| Pattern Graph CLI coverage | Session workflow content queryable via `pnpm architect:query -- rules` | +| Process API coverage | Session workflow content queryable via `pnpm process:query -- rules` | | Immediately useful | Rule: blocks are queryable today, generation follows when Phase 25 ships | **Design Session Findings (2026-03-05):** From 2ed3bafd725b8f7fe1248b558e8c74995365d55b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Thu, 2 Apr 2026 03:48:12 +0200 Subject: [PATCH 5/6] fix: complete terminology alignment across docs, specs, and _claude-md modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sweep residual stale terminology from two rename waves: - MasterDataset→PatternGraph, ProcessStateAPI→PatternGraphAPI (this PR) - process:query→architect:query, lint-process→architect-guard (prior rebrand) Manual fixes: 7 _claude-md modules, 5 feature specs (with unlock-reason tags for completed specs), AGENTS.md paths, 4 docs/ files, memory files. Regenerated CLAUDE.md and all docs-live/ from updated sources. --- AGENTS.md | 34 ++--- CLAUDE.md | 40 +++--- _claude-md/api/data-api-cli.md | 2 +- _claude-md/api/mcp-server.md | 2 +- _claude-md/core/architecture.md | 2 +- _claude-md/core/context-protocol.md | 2 +- _claude-md/guides/product-area-enrichment.md | 5 +- _claude-md/metadata.json | 2 +- _claude-md/testing/testing-policy.md | 2 +- _claude-md/workflow/session-workflows.md | 12 +- .../config-based-workflow-definition.feature | 4 +- architect/specs/pattern-graph-api-cli.feature | 48 ++++---- .../pattern-graph-layered-extraction.feature | 12 +- .../session-guides-module-source.feature | 12 +- architect/specs/setup-command.feature | 2 +- docs-inbox/codebase-exploration-findings.md | 4 +- docs-live/ARCHITECTURE.md | 16 +-- docs-live/CHANGELOG-GENERATED.md | 116 +++++++++--------- docs-live/PRODUCT-AREAS.md | 4 +- .../architecture/reference-sample.md | 2 +- .../core-types/core-types-overview.md | 2 +- docs-live/product-areas/CORE-TYPES.md | 4 +- docs-live/product-areas/GENERATION.md | 22 ++-- docs-live/reference/REFERENCE-SAMPLE.md | 42 +++---- docs-live/reference/SESSION-WORKFLOW-GUIDE.md | 6 +- docs/DOCS-GAP-ANALYSIS.md | 2 +- docs/INDEX.md | 24 ++-- docs/PROCESS-API.md | 2 +- docs/VALIDATION.md | 4 +- 29 files changed, 215 insertions(+), 216 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 570efb66..02f14299 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,17 +10,17 @@ This file helps future Codex sessions ramp up quickly in this repository. ## Where To Read First -1. Manual docs index: `/Users/darkomijic/dev-projects/architect/docs/INDEX.md` -2. Config entry point: `/Users/darkomijic/dev-projects/architect/architect.config.ts` -3. Live generated area index: `/Users/darkomijic/dev-projects/architect/docs-live/PRODUCT-AREAS.md` +1. Manual docs index: `/Users/darkomijic/dev-projects/delivery-process/docs/INDEX.md` +2. Config entry point: `/Users/darkomijic/dev-projects/delivery-process/architect.config.ts` +3. Live generated area index: `/Users/darkomijic/dev-projects/delivery-process/docs-live/PRODUCT-AREAS.md` 4. Key generated area docs: - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/ANNOTATION.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/CONFIGURATION.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/CORE-TYPES.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/DATA-API.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/GENERATION.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/PROCESS.md` - - `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/VALIDATION.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/ANNOTATION.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CONFIGURATION.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CORE-TYPES.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/DATA-API.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/GENERATION.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/PROCESS.md` + - `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/VALIDATION.md` ## Onboarding Context (Tutorial WIP) @@ -64,15 +64,15 @@ Use `architect.config.ts` or `.js` as the main integration contract and keep scr ## Repository Map -- Source code: `/Users/darkomijic/dev-projects/architect/src` +- Source code: `/Users/darkomijic/dev-projects/delivery-process/src` - Feature specs (roadmap/process/decisions/releases): - - `/Users/darkomijic/dev-projects/architect/architect/specs` - - `/Users/darkomijic/dev-projects/architect/architect/decisions` - - `/Users/darkomijic/dev-projects/architect/architect/releases` -- Design stubs (non-compiled on purpose): `/Users/darkomijic/dev-projects/architect/architect/stubs` + - `/Users/darkomijic/dev-projects/delivery-process/architect/specs` + - `/Users/darkomijic/dev-projects/delivery-process/architect/decisions` + - `/Users/darkomijic/dev-projects/delivery-process/architect/releases` +- Design stubs (non-compiled on purpose): `/Users/darkomijic/dev-projects/delivery-process/architect/stubs` - Tests: - - Feature files: `/Users/darkomijic/dev-projects/architect/tests/features` - - Step definitions: `/Users/darkomijic/dev-projects/architect/tests/steps` + - Feature files: `/Users/darkomijic/dev-projects/delivery-process/tests/features` + - Step definitions: `/Users/darkomijic/dev-projects/delivery-process/tests/steps` ## Session Workflow (Project Convention) diff --git a/CLAUDE.md b/CLAUDE.md index ef2b4ad9..003450b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ Both generated from the SAME annotated sources. Features are planned for **reusa ### Context Gathering Protocol (MANDATORY) -**Rule: Always query the Process Data API BEFORE using grep, explore agents, or reading files.** +**Rule: Always query the Data API BEFORE using grep, explore agents, or reading files.** The API returns structured, current data using 5-10x less context than file reads. Annotations and relationships in source files feed the API — invest in annotations, not manual notes. @@ -124,7 +124,7 @@ pnpm architect:query -- overview # Project health sum ### Data API CLI -Query process state directly from the terminal. **Use this instead of reading generated markdown or launching explore agents** — targeted queries use 5-10x less context. +Query the pattern graph directly from the terminal. **Use this instead of reading generated markdown or launching explore agents** — targeted queries use 5-10x less context. **Run `pnpm architect:query -- --help` for the full command reference**, including workflow recipes, session types, architecture queries, output modifiers, and available API methods. @@ -197,7 +197,7 @@ Steps 1-2 can run in parallel (no dependencies between them). | Tool | Description | | ------------------- | ------------------------------------------------------ | -| `architect_rebuild` | Force dataset rebuild from current source files | +| `architect_rebuild` | Force PatternGraph rebuild from current source files | | `architect_config` | Show source globs, base dir, build time, pattern count | | `architect_help` | List all available tools with descriptions | @@ -299,7 +299,7 @@ Architecture and process decisions are recorded as annotated Gherkin specs in `a | ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | | ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | | ADR-006 | Single read model — PatternGraph is the sole read model for all consumers | -| PDR-001 | Session workflow commands — Process Data API CLI design decisions | +| PDR-001 | Session workflow commands — Data API CLI design decisions | Query decisions: `pnpm architect:query -- decisions ` @@ -315,7 +315,7 @@ Tests use Vitest with BDD/Gherkin integration: - **Support**: `tests/support/` - test helpers and setup utilities - **Shared state helpers**: `tests/support/helpers/` - reusable state management for split test suites -Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-cli-state.ts`). +Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-api-state.ts`). Run a single test file: `pnpm test tests/steps/scanner/file-discovery.steps.ts` @@ -495,13 +495,13 @@ The parser sees: Issues discovered during step definition implementation: -| Issue | Description | Fix | -| --------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | -| Pattern not in `bySource.gherkin` | TraceabilityCodec shows "No Timeline Patterns" | Set `filePath: '...feature'` in `createTestPattern()` - source categorization uses file extension | -| Business value not found | REMAINING-WORK.md business value is in `additionalFiles` | Check detail files via `doc.additionalFiles` not main document sections | -| Codec output mismatch | Spec says "Next Actionable table" but codec uses list format | Debug actual output with `console.log(JSON.stringify(doc.sections))` then align test expectations | -| `behaviorFileVerified` undefined | Patterns created without explicit verification status | Add `behaviorFileVerified: true/false` to `createTestPattern()` when testing traceability | -| Discovery tags missing | SessionFindingsCodec shows "No Findings" | Pass `discoveredGaps`, `discoveredImprovements`, `discoveredLearnings` to factory | +| Issue | Description | Fix | +| ------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | +| Pattern not in `bySourceType.gherkin` | TraceabilityCodec shows "No Timeline Patterns" | Set `filePath: '...feature'` in `createTestPattern()` - source categorization uses file extension | +| Business value not found | REMAINING-WORK.md business value is in `additionalFiles` | Check detail files via `doc.additionalFiles` not main document sections | +| Codec output mismatch | Spec says "Next Actionable table" but codec uses list format | Debug actual output with `console.log(JSON.stringify(doc.sections))` then align test expectations | +| `behaviorFileVerified` undefined | Patterns created without explicit verification status | Add `behaviorFileVerified: true/false` to `createTestPattern()` when testing traceability | +| Discovery tags missing | SessionFindingsCodec shows "No Findings" | Pass `discoveredGaps`, `discoveredImprovements`, `discoveredLearnings` to factory | ### Coding & Linting Standards @@ -578,7 +578,7 @@ console.log(JSON.stringify(doc.sections, null, 2)); #### Design sessions produce decisions and stubs only -**Invariant:** A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage. +**Invariant:** A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Data API must precede any explore agent usage. **Rationale:** Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts. @@ -615,15 +615,15 @@ console.log(JSON.stringify(doc.sections, null, 2)); | session-scope (warning) | Modified file outside session scope | Add to scope OR use --ignore-session | | session-excluded | Modified excluded pattern during session | Remove from exclusion OR override | -| Situation | Solution | Example | -| ---------------------------- | --------------------- | -------------------------------------- | -| Fix bug in completed spec | Add unlock reason tag | @architect-unlock-reason:Fix-typo | -| Modify outside session scope | Use ignore flag | lint-process --staged --ignore-session | -| CI treats warnings as errors | Use strict flag | lint-process --all --strict | +| Situation | Solution | Example | +| ---------------------------- | --------------------- | ----------------------------------------- | +| Fix bug in completed spec | Add unlock reason tag | @architect-unlock-reason:Fix-typo | +| Modify outside session scope | Use ignore flag | architect-guard --staged --ignore-session | +| CI treats warnings as errors | Use strict flag | architect-guard --all --strict | #### Handoff captures session-end state for continuity -**Invariant:** Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes. +**Invariant:** Multi-session work requires handoff documentation generated from the Data API. Handoff output always reflects actual annotation state, not manual notes. **Rationale:** Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes. @@ -631,7 +631,7 @@ console.log(JSON.stringify(doc.sections, null, 2)); **Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. -**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. +**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. --- diff --git a/_claude-md/api/data-api-cli.md b/_claude-md/api/data-api-cli.md index 4819cc2f..46576d21 100644 --- a/_claude-md/api/data-api-cli.md +++ b/_claude-md/api/data-api-cli.md @@ -1,6 +1,6 @@ ### Data API CLI -Query process state directly from the terminal. **Use this instead of reading generated markdown or launching explore agents** — targeted queries use 5-10x less context. +Query the pattern graph directly from the terminal. **Use this instead of reading generated markdown or launching explore agents** — targeted queries use 5-10x less context. **Run `pnpm architect:query -- --help` for the full command reference**, including workflow recipes, session types, architecture queries, output modifiers, and available API methods. diff --git a/_claude-md/api/mcp-server.md b/_claude-md/api/mcp-server.md index 9f6b0f99..0a64fe3e 100644 --- a/_claude-md/api/mcp-server.md +++ b/_claude-md/api/mcp-server.md @@ -58,7 +58,7 @@ Steps 1-2 can run in parallel (no dependencies between them). | Tool | Description | | ------------------- | ------------------------------------------------------ | -| `architect_rebuild` | Force dataset rebuild from current source files | +| `architect_rebuild` | Force PatternGraph rebuild from current source files | | `architect_config` | Show source globs, base dir, build time, pattern count | | `architect_help` | List all available tools with descriptions | diff --git a/_claude-md/core/architecture.md b/_claude-md/core/architecture.md index f5b7a65f..116da25c 100644 --- a/_claude-md/core/architecture.md +++ b/_claude-md/core/architecture.md @@ -32,6 +32,6 @@ Architecture and process decisions are recorded as annotated Gherkin specs in `a | ADR-003 | Source-first pattern architecture — code drives docs, not the reverse | | ADR-005 | Codec-based markdown rendering — Zod codecs transform data to markdown | | ADR-006 | Single read model — PatternGraph is the sole read model for all consumers | -| PDR-001 | Session workflow commands — Process Data API CLI design decisions | +| PDR-001 | Session workflow commands — Data API CLI design decisions | Query decisions: `pnpm architect:query -- decisions ` diff --git a/_claude-md/core/context-protocol.md b/_claude-md/core/context-protocol.md index c3e07ea5..fc7dd482 100644 --- a/_claude-md/core/context-protocol.md +++ b/_claude-md/core/context-protocol.md @@ -1,6 +1,6 @@ ### Context Gathering Protocol (MANDATORY) -**Rule: Always query the Process Data API BEFORE using grep, explore agents, or reading files.** +**Rule: Always query the Data API BEFORE using grep, explore agents, or reading files.** The API returns structured, current data using 5-10x less context than file reads. Annotations and relationships in source files feed the API — invest in annotations, not manual notes. diff --git a/_claude-md/guides/product-area-enrichment.md b/_claude-md/guides/product-area-enrichment.md index 8e7f4f62..576590e3 100644 --- a/_claude-md/guides/product-area-enrichment.md +++ b/_claude-md/guides/product-area-enrichment.md @@ -2,8 +2,7 @@ Workflow for adding live Mermaid diagrams, enriched intros, and API Types sections to product area documents in `docs-live/product-areas/`. -**Completed:** Annotation, Configuration, CoreTypes -**Remaining:** Generation, Validation, DataAPI, Process +**All 7 product areas complete:** Annotation, Configuration, CoreTypes, DataAPI, Generation, Process, Validation #### Pre-Flight (Run First) @@ -28,7 +27,7 @@ pnpm architect:query -- list --product-area --names-only | 3 | Add `@architect-depends-on` to feature files | Creates relationship edges in diagrams | | 4 | Add `@architect-shape` + `@architect-include` to key type declarations | Populates API Types section | | 5 | Add `@architect-product-area:` to TS file annotations | Routes TS patterns to product area | -| 6 | Update `PRODUCT_AREA_META` in `reference.ts` (~line 237) | Enriched intro, invariants, `diagramScopes` | +| 6 | Update `PRODUCT_AREA_META` in `product-area-metadata.ts` | Enriched intro, invariants, `diagramScopes` | | 7 | `pnpm build && pnpm test && pnpm docs:product-areas` | Verify end-to-end | #### PRODUCT_AREA_META Entry Structure diff --git a/_claude-md/metadata.json b/_claude-md/metadata.json index 25b88322..64c54764 100644 --- a/_claude-md/metadata.json +++ b/_claude-md/metadata.json @@ -45,7 +45,7 @@ { "path": "api/data-api-cli.md", "tags": ["core"], - "description": "Data API CLI for querying process state" + "description": "Data API CLI for querying the pattern graph" }, { "path": "api/mcp-server.md", diff --git a/_claude-md/testing/testing-policy.md b/_claude-md/testing/testing-policy.md index bdbe2d21..1d5e2d01 100644 --- a/_claude-md/testing/testing-policy.md +++ b/_claude-md/testing/testing-policy.md @@ -6,7 +6,7 @@ Tests use Vitest with BDD/Gherkin integration: - **Support**: `tests/support/` - test helpers and setup utilities - **Shared state helpers**: `tests/support/helpers/` - reusable state management for split test suites -Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-cli-state.ts`). +Large test files are split into focused domain files with shared state extracted to helpers (e.g., `ast-parser-state.ts`, `pattern-graph-api-state.ts`). Run a single test file: `pnpm test tests/steps/scanner/file-discovery.steps.ts` diff --git a/_claude-md/workflow/session-workflows.md b/_claude-md/workflow/session-workflows.md index a00a158a..def34c00 100644 --- a/_claude-md/workflow/session-workflows.md +++ b/_claude-md/workflow/session-workflows.md @@ -78,11 +78,11 @@ | session-scope (warning) | Modified file outside session scope | Add to scope OR use --ignore-session | | session-excluded | Modified excluded pattern during session | Remove from exclusion OR override | -| Situation | Solution | Example | -| ---------------------------- | --------------------- | -------------------------------------- | -| Fix bug in completed spec | Add unlock reason tag | @architect-unlock-reason:Fix-typo | -| Modify outside session scope | Use ignore flag | lint-process --staged --ignore-session | -| CI treats warnings as errors | Use strict flag | lint-process --all --strict | +| Situation | Solution | Example | +| ---------------------------- | --------------------- | ----------------------------------------- | +| Fix bug in completed spec | Add unlock reason tag | @architect-unlock-reason:Fix-typo | +| Modify outside session scope | Use ignore flag | architect-guard --staged --ignore-session | +| CI treats warnings as errors | Use strict flag | architect-guard --all --strict | #### Handoff captures session-end state for continuity @@ -94,4 +94,4 @@ **Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. -**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. +**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. diff --git a/architect/specs/config-based-workflow-definition.feature b/architect/specs/config-based-workflow-definition.feature index c0f7f1f4..793fcec6 100644 --- a/architect/specs/config-based-workflow-definition.feature +++ b/architect/specs/config-based-workflow-definition.feature @@ -1,7 +1,7 @@ @architect @architect-pattern:ConfigBasedWorkflowDefinition @architect-status:completed -@architect-unlock-reason:Add-missing-Invariant-Rationale-annotations +@architect-unlock-reason:Terminology-alignment-rebrand @architect-phase:99 @architect-effort:2h @architect-product-area:Configuration @@ -12,7 +12,7 @@ Feature: Config-Based Workflow Definition **Problem:** - Every `pnpm process:query` and `pnpm docs:*` invocation prints: + Every `pnpm architect:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow (6-phase-standard): Workflow file not found` The `loadDefaultWorkflow()` function resolves to `catalogue/workflows/` diff --git a/architect/specs/pattern-graph-api-cli.feature b/architect/specs/pattern-graph-api-cli.feature index 9a7a2e47..be278b41 100644 --- a/architect/specs/pattern-graph-api-cli.feature +++ b/architect/specs/pattern-graph-api-cli.feature @@ -2,7 +2,7 @@ @architect-pattern:PatternGraphAPICLI @architect-status:completed @architect-completed:2026-02-09 -@architect-unlock-reason:Normalize-deliverable-status-taxonomy +@architect-unlock-reason:Terminology-alignment-rebrand @architect-phase:24 @architect-product-area:DataAPI @architect-effort:2d @@ -20,7 +20,7 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions - Documentation claims API is "directly usable" but practical usage is blocked **Solution:** - Add a CLI command `pnpm process:query` that exposes key PatternGraphAPI methods: + Add a CLI command `pnpm architect:query` that exposes key PatternGraphAPI methods: - `--status active|roadmap|completed` - Filter patterns by status - `--phase N` - Get patterns in specific phase - `--progress` - Show completion percentage and counts @@ -39,7 +39,7 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions Background: Deliverables Given the following deliverables: | Deliverable | Status | Location | Tests | Test Type | - | process:query CLI command | complete | src/cli/pattern-graph-cli.ts | Yes | integration | + | architect:query CLI command | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | CLI argument parser | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | JSON output formatter | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Text output formatter | n/a | N/A | No | N/A | @@ -72,21 +72,21 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Query active patterns Given feature files with patterns in various statuses - When running "pnpm process:query --status active" + When running "pnpm architect:query --status active" Then output shows only patterns with status "active" And each pattern shows name, phase, and categories @acceptance-criteria @happy-path Scenario: Query roadmap items Given feature files with roadmap and deferred patterns - When running "pnpm process:query --roadmap-items" + When running "pnpm architect:query --roadmap-items" Then output shows patterns with status "roadmap" or "deferred" And output excludes completed and active patterns @acceptance-criteria @happy-path Scenario: Query completed patterns with limit Given many completed patterns - When running "pnpm process:query --status completed --limit 5" + When running "pnpm architect:query --status completed --limit 5" Then output shows at most 5 patterns And patterns are sorted by completion recency @@ -114,21 +114,21 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Query patterns in a specific phase Given patterns in Phase 18 with various statuses - When running "pnpm process:query --phase 18" + When running "pnpm architect:query --phase 18" Then output shows all patterns tagged with phase 18 And each pattern shows its status @acceptance-criteria @happy-path Scenario: Query phase progress Given Phase 18 with 3 completed and 2 roadmap patterns - When running "pnpm process:query --phase 18 --progress" + When running "pnpm architect:query --phase 18 --progress" Then output shows "Phase 18: 3/5 complete (60%)" And output lists pattern names by status @acceptance-criteria @happy-path Scenario: List all phases Given patterns across phases 14, 18, 19, 20, 21, 22 - When running "pnpm process:query --phases" + When running "pnpm architect:query --phases" Then output shows each phase with pattern count And phases are sorted numerically @@ -155,7 +155,7 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Overall progress summary Given 62 completed, 3 active, 26 planned patterns - When running "pnpm process:query --progress" + When running "pnpm architect:query --progress" Then output shows: """ Overall Progress: 62/91 (68%) @@ -169,7 +169,7 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Status distribution with percentages Given patterns in various statuses - When running "pnpm process:query --distribution" + When running "pnpm architect:query --distribution" Then output shows each status with count and percentage And percentages sum to 100% @@ -196,7 +196,7 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: JSON output format Given active patterns exist - When running "pnpm process:query --current-work --format json" + When running "pnpm architect:query --current-work --format json" Then output is valid JSON And JSON contains array of pattern objects And each pattern has: name, status, phase, categories @@ -204,13 +204,13 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Text output format (default) Given active patterns exist - When running "pnpm process:query --current-work" + When running "pnpm architect:query --current-work" Then output is human-readable text And patterns are formatted in a table @acceptance-criteria @validation Scenario: Invalid format flag - When running "pnpm process:query --format xml" + When running "pnpm architect:query --format xml" Then command exits with error And error message suggests valid formats: text, json @@ -238,20 +238,20 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Lookup pattern by name Given a pattern "DurableFunctionAdapters" exists - When running "pnpm process:query --pattern DurableFunctionAdapters" + When running "pnpm architect:query --pattern DurableFunctionAdapters" Then output shows pattern name, status, phase And output shows categories and description @acceptance-criteria @happy-path Scenario: Query pattern deliverables Given a pattern with 4 deliverables - When running "pnpm process:query --pattern EventStoreDurability --deliverables" + When running "pnpm architect:query --pattern EventStoreDurability --deliverables" Then output shows each deliverable with status and location @acceptance-criteria @validation Scenario: Pattern not found Given no pattern named "NonExistent" - When running "pnpm process:query --pattern NonExistent" + When running "pnpm architect:query --pattern NonExistent" Then command exits with error And error message says "Pattern 'NonExistent' not found" And suggests using --status roadmap to see available patterns @@ -274,20 +274,20 @@ Feature: PatternGraphAPI CLI - Direct Queries for Planning Sessions @acceptance-criteria @happy-path Scenario: Help output shows all flags - When running "pnpm process:query --help" + When running "pnpm architect:query --help" Then output lists all available flags And each flag has a description And common use cases are shown as examples @acceptance-criteria @happy-path Scenario: Help shows examples - When running "pnpm process:query --help" + When running "pnpm architect:query --help" Then output includes example commands: """ Examples: - pnpm process:query --current-work # What's active? - pnpm process:query --roadmap-items # What can I start? - pnpm process:query --phase 18 --progress # Phase 18 status - pnpm process:query --pattern DCB --deliverables # Pattern details - pnpm process:query --progress --format json # For AI parsing + pnpm architect:query --current-work # What's active? + pnpm architect:query --roadmap-items # What can I start? + pnpm architect:query --phase 18 --progress # Phase 18 status + pnpm architect:query --pattern DCB --deliverables # Pattern details + pnpm architect:query --progress --format json # For AI parsing """ diff --git a/architect/specs/pattern-graph-layered-extraction.feature b/architect/specs/pattern-graph-layered-extraction.feature index 572db43e..a1924df0 100644 --- a/architect/specs/pattern-graph-layered-extraction.feature +++ b/architect/specs/pattern-graph-layered-extraction.feature @@ -1,7 +1,7 @@ @architect @architect-pattern:PatternGraphLayeredExtraction @architect-status:completed -@architect-unlock-reason:PR28-review-structural-fixes +@architect-unlock-reason:Terminology-alignment-rebrand @architect-phase:100 @architect-effort:2d @architect-product-area:DataAPI @@ -142,11 +142,11 @@ Feature: Pattern Graph Layered Extraction | Step | What | Verification | | 1 | Create src/generators/pipeline/build-pipeline.ts with PipelineOptions and factory | pnpm typecheck | | 2 | Export from src/generators/pipeline/index.ts barrel | pnpm typecheck | - | 3 | Migrate pattern-graph-cli.ts buildPipeline to factory call | pnpm typecheck, pnpm process:query -- overview | + | 3 | Migrate pattern-graph-cli.ts buildPipeline to factory call | pnpm typecheck, pnpm architect:query -- overview | | 4 | Remove unused scanner/extractor imports from pattern-graph-cli.ts | pnpm lint | | 5 | Migrate validate-patterns.ts PatternGraph pipeline to factory call | pnpm validate:patterns (0 errors, 0 warnings) | | 6 | Create src/api/rules-query.ts with queryBusinessRules | pnpm typecheck | - | 7 | Slim handleRules in pattern-graph-cli.ts to thin delegation | pnpm process:query -- rules | + | 7 | Slim handleRules in pattern-graph-cli.ts to thin delegation | pnpm architect:query -- rules | | 8 | Export from src/api/index.ts barrel | pnpm typecheck | | 9 | Full verification | pnpm build, pnpm test, pnpm lint, pnpm validate:patterns | @@ -319,6 +319,6 @@ Feature: Pattern Graph Layered Extraction Given the complete refactored codebase When running pnpm build, pnpm test, pnpm lint, and pnpm validate:patterns Then all pass with zero errors - And pnpm process:query -- overview produces the same output as before - And pnpm process:query -- rules produces the same output as before - And pnpm process:query -- rules --product-area DataAPI produces the same output as before + And pnpm architect:query -- overview produces the same output as before + And pnpm architect:query -- rules produces the same output as before + And pnpm architect:query -- rules --product-area DataAPI produces the same output as before diff --git a/architect/specs/session-guides-module-source.feature b/architect/specs/session-guides-module-source.feature index 2f4130ae..8bb6045d 100644 --- a/architect/specs/session-guides-module-source.feature +++ b/architect/specs/session-guides-module-source.feature @@ -1,7 +1,7 @@ @architect @architect-pattern:SessionGuidesModuleSource @architect-status:completed -@architect-unlock-reason:Add-include-tag-for-ProceduralGuideCodec +@architect-unlock-reason:Terminology-alignment-rebrand @architect-phase:39 @architect-effort:0.5d @architect-product-area:Generation @@ -53,7 +53,7 @@ Feature: Session Guides as Annotated Module Source | No CLAUDE.md drift | Session workflow section generated, not hand-authored | | Single annotated source | This spec owns all session workflow invariants | | Correct audience alignment | Public guide stays in docs/, AI context in _claude-md/ | - | Process API coverage | Session workflow content queryable via `pnpm process:query -- rules` | + | Process API coverage | Session workflow content queryable via `pnpm architect:query -- rules` | | Immediately useful | Rule: blocks are queryable today, generation follows when Phase 25 ships | **Design Session Findings (2026-03-05):** @@ -283,8 +283,8 @@ Feature: Session Guides as Annotated Module Source | Situation | Solution | Example | | Fix bug in completed spec | Add unlock reason tag | @architect-unlock-reason:Fix-typo | - | Modify outside session scope | Use ignore flag | lint-process --staged --ignore-session | - | CI treats warnings as errors | Use strict flag | lint-process --all --strict | + | Modify outside session scope | Use ignore flag | architect-guard --staged --ignore-session | + | CI treats warnings as errors | Use strict flag | architect-guard --all --strict | @acceptance-criteria @happy-path Scenario: All FSM errors have documented recovery paths @@ -308,7 +308,7 @@ Feature: Session Guides as Annotated Module Source **Verified by:** Handoff output reflects annotation state - Generate handoff via: pnpm process:query -- handoff --pattern PatternName + Generate handoff via: pnpm architect:query -- handoff --pattern PatternName Options: --git (include recent commits), --session (session identifier) Output includes: deliverable statuses, blockers, modification date, and next @@ -334,7 +334,7 @@ Feature: Session Guides as Annotated Module Source successful verified generation. **Rationale:** The annotation work (Rule blocks in this spec) is immediately - useful — queryable via `pnpm process:query -- rules`. Generation deliverables + useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. diff --git a/architect/specs/setup-command.feature b/architect/specs/setup-command.feature index 78c4bd7a..7f8004d0 100644 --- a/architect/specs/setup-command.feature +++ b/architect/specs/setup-command.feature @@ -187,7 +187,7 @@ Feature: Interactive Setup Command Scenario: Injected scripts use bin command names Given a package.json with no Architect scripts When the init command injects scripts - Then package.json contains process:query using "pattern-graph-cli" + Then package.json contains architect:query using "pattern-graph-cli" And contains docs:all using "generate-docs" And preserves the existing "type" field diff --git a/docs-inbox/codebase-exploration-findings.md b/docs-inbox/codebase-exploration-findings.md index b34b0c95..53fae847 100644 --- a/docs-inbox/codebase-exploration-findings.md +++ b/docs-inbox/codebase-exploration-findings.md @@ -444,9 +444,9 @@ Both produce `ExtractedPattern` and validate via `ExtractedPatternSchema.safePar **Shape rendering in wrong layer:** `renderShapesAsMarkdown()` defined in `shape-extractor.ts` (extraction layer), consumed by `codecs/helpers.ts` (renderable layer). -### 4.3 Process Data API (14 files, 4,110 lines) +### 4.3 Data API (14 files, 4,110 lines) -**`PatternGraphAPI` (process-state.ts line 87):** 25-method interface in 5 groups: +**`PatternGraphAPI` (pattern-graph-api.ts line 87):** 25-method interface in 5 groups: - Status queries (5 methods) - Phase queries (4 methods) diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index 4fb96f01..68638fbf 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -136,6 +136,14 @@ graph TB ConfigResolver --> ArchitectFactory ArchitectFactory --> RegexBuilders ConfigLoader --> ArchitectFactory + ReplMode --> PatternGraphAPI + PatternGraphCLIImpl --> PatternGraphAPI + PatternGraphCLIImpl --> PatternGraph + PatternGraphCLIImpl --> PatternSummarizerImpl + PatternGraphCLIImpl --> FuzzyMatcherImpl + PatternGraphCLIImpl --> OutputPipelineImpl + OutputPipelineImpl --> PatternSummarizerImpl + MCPServerBin --> MCPServerImpl PatternSummarizerImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraph @@ -153,14 +161,6 @@ graph TB ContextAssemblerImpl --> FuzzyMatcherImpl ArchQueriesImpl --> PatternGraphAPI ArchQueriesImpl --> PatternGraph - ReplMode --> PatternGraphAPI - PatternGraphCLIImpl --> PatternGraphAPI - PatternGraphCLIImpl --> PatternGraph - PatternGraphCLIImpl --> PatternSummarizerImpl - PatternGraphCLIImpl --> FuzzyMatcherImpl - PatternGraphCLIImpl --> OutputPipelineImpl - OutputPipelineImpl --> PatternSummarizerImpl - MCPServerBin --> MCPServerImpl FSMValidator --> FSMTransitions FSMValidator --> FSMStates DesignReviewCodec --> PatternGraph diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 1b3cf0f3..28fcda3c 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -51,28 +51,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **FSM Transitions**: :PDR005MvpWorkflow Defines valid transitions between FSM states per PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **FSM States**: :PDR005MvpWorkflow Defines the 4-state FSM from PDR-005 MVP Workflow: - roadmap: Planned work (fully editable) -... - **FSM Module**: :PDR005MvpWorkflow Central export for the 4-state FSM defined in PDR-005: ``` roadmap ──→ active ──→ completed │ ... -- **Reference Document Codec**: :Generation A single codec factory that creates reference document codecs from configuration objects. -- **Design Review Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing design review artifacts: sequence diagrams,... -- **Composite Codec**: :Generation Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. -- **Codec Registry Barrel**: Collects all codecMeta exports into a single array. -- **Claude Module Codec**: :Generation Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. - **Process Guard Types**: :FSMValidator Defines types for the process guard linter including: - Process state derived from file annotations -... - **Process Guard Module**: :FSMValidator,DeriveProcessState,DetectChanges,ProcessGuardDecider Enforces workflow rules by validating changes... - **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... - **Derive Process State**: :GherkinScanner,FSMValidator Derives process state from @architect-\* annotations in files. - **Process Guard Decider**: :FSMValidator,DeriveProcessState,DetectChanges Pure function that validates changes against process rules. +- **Reference Document Codec**: :Generation A single codec factory that creates reference document codecs from configuration objects. +- **Design Review Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing design review artifacts: sequence diagrams,... +- **Composite Codec**: :Generation Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. +- **Codec Registry Barrel**: Collects all codecMeta exports into a single array. +- **Claude Module Codec**: :Generation Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. +- **Reference Generator Registration**: Registers all reference document generators. +- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **Transform Types**: Type definitions for the dataset transformation pipeline. - **Sequence Transform Utils**: :Generation Builds pre-computed SequenceIndexEntry objects from patterns that have sequence diagram annotations. - **Relationship Resolver**: Computes reverse relationship lookups (implementedBy, extendedBy, enables, usedBy) and detects dangling references in... -- **Reference Generator Registration**: Registers all reference document generators. -- **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **MCP Server Integration**: Claude Code accesses PatternGraphAPI through subprocess calls to the pattern-graph-cli CLI. - **Design Review Generation**: Design reviews require manual creation of sequence and component diagrams that duplicate information already captured... -- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. -- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Workflow Config Schemas Validation**: The workflow configuration module defines Zod schemas for validating delivery workflow definitions with statuses,... - **Tag Registry Schemas Validation**: The tag registry configuration module provides schema-validated taxonomy definitions for organizing patterns by... - **Codec Utils Validation**: The codec utilities provide factory functions for creating type-safe JSON parsing and serialization pipelines using... +- **Git Branch Diff Testing**: The branch diff utility returns changed files relative to a base branch for PR-scoped generation. +- **File Cache Testing**: The file cache provides request-scoped content caching for generation runs. - **Tag Registry Builder Testing**: The tag registry builder constructs a complete TagRegistry from TypeScript constants. - **Normalized Status Testing**: The normalized status module maps any status input — raw FSM states (roadmap, active, completed, deferred),... - **Deliverable Status Taxonomy Testing**: The deliverable status module defines the 6 canonical status values for deliverables in Gherkin Background tables:... @@ -86,15 +86,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Pattern Graph Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. - **Pattern Graph Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. - **Pattern Graph Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. -- **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... -- **Pattern Helpers Tests** -- **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. -- **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. -- **Arch Queries Test** - **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... - **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... +- **Arch Queries Test** - **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... - **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... +- **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... +- **Pattern Helpers Tests** +- **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. +- **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. - **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. - **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. @@ -118,10 +118,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added - **Public API**: Main entry point for the @libar-dev/architect package. -- **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. -- **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... -- **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. -- **Anti Pattern Detector**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... +- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. +- **MCPServer — Entry Point and Lifecycle Manager**: Main entry point for the Architect MCP server. +- **PipelineSessionManager — In-Memory PatternGraph Lifecycle**: Manages the persistent PatternGraph that all MCP tool calls read from. +- **McpFileWatcher — Debounced Source File Watcher**: Watches TypeScript and Gherkin source files for changes, triggering debounced pipeline rebuilds. +- **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. +- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). +- **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... - **Workflow Config Schema**: Zod schemas for validating workflow configuration files that define status models, phase definitions, and artifact... - **Tag Registry Configuration**: Defines the structure and validation for tag taxonomy configuration. - **Pattern Graph**: Defines the schema for a pre-computed dataset that holds all extracted patterns along with derived views (by status,... @@ -131,6 +134,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Dual Source Schemas**: Zod schemas for dual-source extraction types. - **Doc Directive Schema**: Zod schemas for validating parsed @architect-\* directives from JSDoc comments. - **Codec Utils**: Provides factory functions for creating type-safe JSON parsing and serialization pipelines using Zod schemas. +- **DoD Validation Types**: Types and schemas for Definition of Done (DoD) validation and anti-pattern detection. +- **Validation Module**: Barrel export for validation module providing: - Definition of Done (DoD) validation for completed phases -... +- **DoD Validator**: Validates that completed phases meet Definition of Done criteria: 1. +- **Anti Pattern Detector**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... +- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... +- **Utils Module**: Common helper functions used across the Architect package. +- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. +- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. +- **Result Monad Types**: Explicit error handling via discriminated union. +- **Error Factory Types**: Structured, discriminated error types with factory functions. +- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. +- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. +- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... +- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). - **Risk Levels**: Three-tier risk classification for roadmap planning. - **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. @@ -139,24 +156,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... - **Format Types**: Defines how tag values are parsed and validated. - **Category Definitions**: Categories are used to classify patterns and organize documentation. -- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. -- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. -- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... -- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... -- **String Utilities**: Provides shared utilities for string manipulation used across the Architect package, including slugification for... -- **Utils Module**: Common helper functions used across the Architect package. -- **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. -- **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. +- **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. +- **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. +- **Lint Engine**: Orchestrates lint rule execution against parsed directives. - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. - **Renderable Document Model(RDM)**: Unified document generation using codecs and a universal renderer. - **Document Generator**: Simplified document generation using codecs. -- **Result Monad Types**: Explicit error handling via discriminated union. -- **Error Factory Types**: Structured, discriminated error types with factory functions. -- **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. -- **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. -- **Lint Engine**: Orchestrates lint rule execution against parsed directives. +- **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... +- **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. +- **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. +- **Dual Source Extractor**: Extracts pattern metadata from both TypeScript code stubs (@architect-_) and Gherkin feature files (@architect-_),... +- **Document Extractor**: Converts scanned file data into complete ExtractedPattern objects with unique IDs, inferred names, categories, and... - **Warning Collector**: Provides a unified system for capturing, categorizing, and reporting non-fatal issues during document generation. - **Generator Types**: Minimal interface for pluggable generators that produce documentation from patterns. - **Source Mapping Validator**: Performs pre-flight checks on source mapping tables before extraction begins. @@ -165,11 +177,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Documentation Generation Orchestrator**: Invariant: The orchestrator is the integration boundary for full docs generation: it delegates dataset construction... - **Content Deduplicator**: Identifies and merges duplicate sections extracted from multiple sources. - **Codec Based Generator**: Adapts the new RenderableDocument Model (RDM) codec system to the existing DocumentGenerator interface. -- **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... -- **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. -- **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. -- **Dual Source Extractor**: Extracts pattern metadata from both TypeScript code stubs (@architect-_) and Gherkin feature files (@architect-_),... -- **Document Extractor**: Converts scanned file data into complete ExtractedPattern objects with unique IDs, inferred names, categories, and... - **Workflow Loader**: Provides the default 6-phase workflow as an inline constant and loads custom workflow overrides from JSON files via... - **Configuration Types**: Type definitions for the Architect configuration system. - **Regex Builders**: Type-safe regex factory functions for tag detection and normalization. @@ -186,13 +193,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. - **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. - **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. -- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to PatternGraphAPI methods and CLI subcommands. -- **MCPServer — Entry Point and Lifecycle Manager**: Main entry point for the Architect MCP server. -- **PipelineSessionManager — In-Memory PatternGraph Lifecycle**: Manages the persistent PatternGraph that all MCP tool calls read from. -- **McpFileWatcher — Debounced Source File Watcher**: Watches TypeScript and Gherkin source files for changes, triggering debounced pipeline rebuilds. -- **Index Preamble Configuration — DD-3, DD-4 Decisions**: Decision DD-3 (Audience paths: preamble vs annotation-derived): Use full preamble for audience reading paths. -- **IndexCodec Factory — DD-1 Implementation Stub**: Creates the IndexCodec as a Zod codec (PatternGraph -> RenderableDocument). -- **IndexCodecOptions — DD-1, DD-5 Decisions**: Decision DD-1 (New IndexCodec vs extend existing): Create a new IndexCodec registered in CodecRegistry, NOT a... - **Validation Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. - **Timeline Codec**: :Generation Purpose: Development roadmap organized by phase with progress tracking. - **Taxonomy Codec**: :Generation Transforms PatternGraph into a RenderableDocument for taxonomy reference output. @@ -215,15 +215,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Business Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for business rules output. - **Architecture Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing architecture diagrams (Mermaid) generated... - **Adr Document Codec**: :Generation Transforms PatternGraph into RenderableDocument for Architecture Decision Records. +- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. +- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. +- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. +- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Transform Dataset**: Transforms raw extracted patterns into a PatternGraph with all pre-computed views. - **Merge Patterns**: Merges patterns from TypeScript and Gherkin sources with conflict detection. - **Pipeline Module**: Barrel export for the unified transformation pipeline components. - **Context Inference Impl**: Auto-infers bounded context from file paths using configurable rules. - **Pipeline Factory**: Invariant: `buildPatternGraph()` is the shared factory for Steps 1-8 of the architecture pipeline and returns... -- **Built In Generators**: Registers all codec-based generators on import using the RDM (RenderableDocument Model) architecture. -- **Decision Doc Generator**: Orchestrates the full pipeline for generating documentation from decision documents (ADR/PDR in .feature format): 1. -- **Codec Generator Registration**: Registers codec-based generators for the RenderableDocument Model (RDM) system. -- **Cli Reference Generator**: :Generation Generates `CLI-REFERENCE.md` from the declarative CLI schema. - **Codec Base Options**: :Add-createDecodeOnlyCodec-helper Shared types, interfaces, and utilities for all document codecs. - **ADR 006 Single Read Model Architecture**: The Architect package applies event sourcing to itself: git is the event store, annotated source files are... - **ADR 005 Codec Based Markdown Rendering**: The documentation generator needs to transform structured pattern data (PatternGraph) into markdown files. @@ -259,7 +259,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Data API CLI Ergonomics**: The pattern-graph-cli CLI runs the full pipeline (scan, extract, transform) on every invocation, taking 2-5 seconds. - **Data API Architecture Queries**: The current `arch` subcommand provides basic queries (roles, context, layer, graph) but lacks deeper analysis needed... - **Cross Cutting Document Inclusion**: The reference doc codec assembles content from four sources, each with its own selection mechanism: conventionTags... -- **Config Based Workflow Definition**: Every `pnpm process:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow (6-phase-standard):... +- **Config Based Workflow Definition**: Every `pnpm architect:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow... - **Codec Driven Reference Generation**: Each reference document (Process Guard, Taxonomy, Validation, etc.) required a hand-coded recipe feature that... - **Cli Reference Generation**: `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source... - **Cli Recipe Codec**: `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (CliReferenceGeneration)... @@ -267,7 +267,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architecture Doc Refactoring**: ARCHITECTURE.md is 1,287 lines of manually-maintained documentation covering 14 sections. - **Architecture Diagram Core**: Problem: Architecture documentation requires manually maintaining mermaid diagrams that duplicate information already... - **Architecture Diagram Advanced**: Problem: Core diagram generation (see ArchitectureDiagramCore) produces component-level diagrams from `arch-*` tags. -- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Status Transition Detection Testing**: Tests for the detectStatusTransitions function that parses git diff output. - **Process Guard Testing**: Pure validation functions for enforcing delivery process rules per PDR-005. - **FSM Validator Testing**: Pure validation functions for the 4-state FSM defined in PDR-005. @@ -275,15 +274,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Detect Changes Testing**: Tests for the detectDeliverableChanges function that parses git diff output. - **Config Schema Validation**: Configuration schemas validate scanner and generator inputs with security constraints to prevent path traversal... - **Anti Pattern Detector Testing**: Detects violations of the dual-source documentation architecture and process hygiene issues that lead to... +- **String Utils**: String utilities provide consistent text transformations across the codebase. - **Result Monad**: The Result type provides explicit error handling via a discriminated union. - **Error Factories**: Error factories create structured, discriminated error types with consistent message formatting. +- **Rule Keyword Po C**: This feature tests whether vitest-cucumber supports the Rule keyword for organizing scenarios under business rules. - **Gherkin Ast Parser**: The Gherkin AST parser extracts feature metadata, scenarios, and steps from .feature files for timeline generation... - **File Discovery**: The file discovery system uses glob patterns to find TypeScript files for documentation extraction. - **Doc String Media Type**: DocString language hints (mediaType) should be preserved through the parsing pipeline from feature files to rendered... - **Ast Parser Relationships Edges**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Metadata**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Exports**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. -- **Rule Keyword Po C**: This feature tests whether vitest-cucumber supports the Rule keyword for organizing scenarios under business rules. - **Lint Rule Individual Testing**: Individual lint rules that check parsed directives for completeness. - **Lint Rule Advanced Testing**: Complex lint rule logic and collection-level behavior. - **Lint Engine Testing**: The lint engine orchestrates rule execution, aggregates violations, and formats output for human and machine... @@ -299,6 +299,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Extraction Pipeline Enhancements Testing**: Validates extraction pipeline capabilities for ReferenceDocShowcase: function signature surfacing, full... - **Dual Source Extractor Testing**: Extracts and combines pattern metadata from both TypeScript code stubs (@architect-) and Gherkin feature files... - **Declaration Level Shape Tagging Testing**: Tests the discoverTaggedShapes function that scans TypeScript source code for declarations annotated with the... +- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... +- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... +- **Preset System**: Presets provide pre-configured taxonomies for different project types. +- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... +- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. +- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... +- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... - **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... - **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... @@ -310,13 +317,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . - **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... - **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. -- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... -- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... -- **Preset System**: Presets provide pre-configured taxonomies for different project types. -- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... -- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. -- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... -- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Validate Patterns Cli**: Command-line interface for cross-validating TypeScript patterns vs Gherkin feature files. - **Pattern Graph Cli Subcommands**: Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. - **Pattern Graph Cli Modifiers And Rules**: Output modifiers, arch health, and rules subcommand. @@ -349,7 +349,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Zod Codec Migration**: All JSON parsing and serialization uses type-safe Zod codec pattern, replacing raw JSON.parse/stringify with... - **Scope Validator Tests**: Starting an implementation or design session without checking prerequisites wastes time when blockers are discovered... - **Handoff Generator Tests**: Multi-session work loses critical state between sessions when handoff documentation is manual or forgotten. -- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Mermaid Relationship Rendering**: Tests for rendering all relationship types in Mermaid dependency graphs with distinct visual styles per relationship... - **Linter Validation Testing**: Tests for lint rules that validate relationship integrity, detect conflicts, and ensure bidirectional traceability... - **Implements Tag Processing**: Tests for the @architect-implements tag which links implementation files to their corresponding roadmap pattern... @@ -372,6 +371,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Dedent Helper**: The dedent helper function normalizes indentation in code blocks extracted from DocStrings. - **Convention Extractor Testing**: Extracts convention content from PatternGraph decision records tagged with @architect-convention. - **Composite Codec Testing**: Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. +- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... - **Layered Diagram Generation**: As a documentation generator I want to generate layered architecture diagrams from metadata So that system... - **Arch Generator Registration**: As a CLI user I want an architecture generator registered in the generator registry So that I can run pnpm... - **Component Diagram Generation**: As a documentation generator I want to generate component diagrams from architecture metadata So that system... diff --git a/docs-live/PRODUCT-AREAS.md b/docs-live/PRODUCT-AREAS.md index 086a5075..38184a89 100644 --- a/docs-live/PRODUCT-AREAS.md +++ b/docs-live/PRODUCT-AREAS.md @@ -120,9 +120,9 @@ C4Context System(DataAPIContextAssembly, "DataAPIContextAssembly") System(CrossCuttingDocumentInclusion, "CrossCuttingDocumentInclusion") System(CodecDrivenReferenceGeneration, "CodecDrivenReferenceGeneration") + System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") - System(StringUtils, "StringUtils") System(ExtractionPipelineEnhancementsTesting, "ExtractionPipelineEnhancementsTesting") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") @@ -199,9 +199,9 @@ graph LR DataAPIContextAssembly["DataAPIContextAssembly"] CrossCuttingDocumentInclusion["CrossCuttingDocumentInclusion"] CodecDrivenReferenceGeneration["CodecDrivenReferenceGeneration"] + StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] - StringUtils["StringUtils"] ExtractionPipelineEnhancementsTesting["ExtractionPipelineEnhancementsTesting"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] diff --git a/docs-live/_claude-md/architecture/reference-sample.md b/docs-live/_claude-md/architecture/reference-sample.md index 79f898de..b21a2b82 100644 --- a/docs-live/_claude-md/architecture/reference-sample.md +++ b/docs-live/_claude-md/architecture/reference-sample.md @@ -106,10 +106,10 @@ | Type | Kind | | ------------------------- | --------- | +| SectionBlock | type | | normalizeStatus | function | | DELIVERABLE_STATUS_VALUES | const | | CategoryDefinition | interface | -| SectionBlock | type | #### Behavior Specifications diff --git a/docs-live/_claude-md/core-types/core-types-overview.md b/docs-live/_claude-md/core-types/core-types-overview.md index 8c7bbafe..9eeab236 100644 --- a/docs-live/_claude-md/core-types/core-types-overview.md +++ b/docs-live/_claude-md/core-types/core-types-overview.md @@ -9,7 +9,7 @@ - Branded nominal types: `Branded` creates compile-time distinct types from structural TypeScript. Prevents mixing `PatternId` with `CategoryName` even though both are `string` at runtime - String transformation consistency: `slugify` produces URL-safe identifiers, `camelCaseToTitleCase` preserves acronyms (e.g., "APIEndpoint" becomes "API Endpoint"), `toKebabCase` handles consecutive uppercase correctly -**Components:** Other (TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, StringUtils, FileCacheTesting, KebabCaseSlugs, ErrorHandlingUnification) +**Components:** Other (StringUtils, FileCacheTesting, TagRegistryBuilderTesting, ResultMonad, NormalizedStatusTesting, ErrorFactories, DeliverableStatusTaxonomyTesting, KebabCaseSlugs, ErrorHandlingUnification) #### API Types diff --git a/docs-live/product-areas/CORE-TYPES.md b/docs-live/product-areas/CORE-TYPES.md index 0bd9e85e..999f7864 100644 --- a/docs-live/product-areas/CORE-TYPES.md +++ b/docs-live/product-areas/CORE-TYPES.md @@ -33,9 +33,9 @@ Scoped architecture diagram showing component relationships: ```mermaid C4Context title Core Type System + System(StringUtils, "StringUtils") System(ResultMonad, "ResultMonad") System(ErrorFactories, "ErrorFactories") - System(StringUtils, "StringUtils") System(KebabCaseSlugs, "KebabCaseSlugs") System(ErrorHandlingUnification, "ErrorHandlingUnification") Rel(KebabCaseSlugs, StringUtils, "depends on") @@ -51,9 +51,9 @@ Scoped architecture diagram showing component relationships: ```mermaid graph LR + StringUtils["StringUtils"] ResultMonad["ResultMonad"] ErrorFactories["ErrorFactories"] - StringUtils["StringUtils"] KebabCaseSlugs["KebabCaseSlugs"] ErrorHandlingUnification["ErrorHandlingUnification"] KebabCaseSlugs -.->|depends on| StringUtils diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index 34756472..dc43dd2c 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -1063,17 +1063,17 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ### Session Guides Module Source -| Rule | Invariant | Rationale | -| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SESSION-GUIDES.md is the authoritative public human reference | `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or replaced with a redirect. Its comprehensive checklists, CLI command examples, and session decision trees serve developers on libar.dev. | Session workflow guidance requires two formats for two audiences. Public developers need comprehensive checklists with full examples. AI sessions need compact invariants they can apply without reading 389 lines. | -| CLAUDE.md session workflow content is derived, not hand-authored | After Phase 39 generation deliverables complete, the "Session Workflows" section in CLAUDE.md contains no manually-authored content. It is composed from generated `_claude-md/workflow/` modules. | A hand-maintained CLAUDE.md session section creates two copies of session workflow guidance with no synchronization mechanism. Regeneration from annotated source eliminates drift. | -| Session type determines artifacts and FSM changes | Four session types exist, each with defined input, output, and FSM impact. Mixing outputs across session types (e.g., writing code in a planning session) violates session discipline. | Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types. | -| Planning sessions produce roadmap specs only | A planning session creates a roadmap spec with metadata, deliverables table, Rule: blocks with invariants, and scenarios. It must not produce implementation code, transition to active, or prompt for implementation readiness. | Planning is the cheapest session type — it produces .feature file edits, no compilation needed. Mixing implementation into planning defeats the cost advantage and introduces untested code without a locked scope. | -| Design sessions produce decisions and stubs only | A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage. | Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts. | -| Implementation sessions follow FSM-enforced execution order | Implementation sessions must follow a strict 5-step execution order. Transition to active must happen before any code changes. Transition to completed must happen only when ALL deliverables are done. Skipping steps causes Process Guard rejection at commit time. | The execution order ensures FSM state accurately reflects work state at every point. Writing code before transitioning to active means Process Guard sees changes to a roadmap spec (no scope protection). Marking completed with incomplete work creates a hard-locked state that requires unlock-reason to fix. | -| FSM errors have documented fixes | Every Process Guard error code has a defined cause and fix. The error codes, causes, and fixes form a closed set — no undocumented error states exist. | Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity. | -| Handoff captures session-end state for continuity | Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes. | Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes. | -| ClaudeModuleGeneration is the generation mechanism | Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. | The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. | +| Rule | Invariant | Rationale | +| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| SESSION-GUIDES.md is the authoritative public human reference | `docs/SESSION-GUIDES.md` exists and is not deleted, shortened, or replaced with a redirect. Its comprehensive checklists, CLI command examples, and session decision trees serve developers on libar.dev. | Session workflow guidance requires two formats for two audiences. Public developers need comprehensive checklists with full examples. AI sessions need compact invariants they can apply without reading 389 lines. | +| CLAUDE.md session workflow content is derived, not hand-authored | After Phase 39 generation deliverables complete, the "Session Workflows" section in CLAUDE.md contains no manually-authored content. It is composed from generated `_claude-md/workflow/` modules. | A hand-maintained CLAUDE.md session section creates two copies of session workflow guidance with no synchronization mechanism. Regeneration from annotated source eliminates drift. | +| Session type determines artifacts and FSM changes | Four session types exist, each with defined input, output, and FSM impact. Mixing outputs across session types (e.g., writing code in a planning session) violates session discipline. | Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types. | +| Planning sessions produce roadmap specs only | A planning session creates a roadmap spec with metadata, deliverables table, Rule: blocks with invariants, and scenarios. It must not produce implementation code, transition to active, or prompt for implementation readiness. | Planning is the cheapest session type — it produces .feature file edits, no compilation needed. Mixing implementation into planning defeats the cost advantage and introduces untested code without a locked scope. | +| Design sessions produce decisions and stubs only | A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage. | Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts. | +| Implementation sessions follow FSM-enforced execution order | Implementation sessions must follow a strict 5-step execution order. Transition to active must happen before any code changes. Transition to completed must happen only when ALL deliverables are done. Skipping steps causes Process Guard rejection at commit time. | The execution order ensures FSM state accurately reflects work state at every point. Writing code before transitioning to active means Process Guard sees changes to a roadmap spec (no scope protection). Marking completed with incomplete work creates a hard-locked state that requires unlock-reason to fix. | +| FSM errors have documented fixes | Every Process Guard error code has a defined cause and fix. The error codes, causes, and fixes form a closed set — no undocumented error states exist. | Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity. | +| Handoff captures session-end state for continuity | Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes. | Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes. | +| ClaudeModuleGeneration is the generation mechanism | Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. | The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. | ### Shape Matcher Testing diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index 18000ec0..a54769bd 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -419,16 +419,16 @@ graph LR DataAPIArchitectureQueries["DataAPIArchitectureQueries"]:::neighbor CliReferenceGeneration["CliReferenceGeneration"]:::neighbor end - TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - CLISchema ..->|implements| CliReferenceGeneration + TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation + ProjectConfigTypes -->|uses| ConfigurationTypes + ProjectConfigTypes -->|uses| ConfigurationPresets + ConfigurationPresets -->|uses| ConfigurationTypes PatternHelpers ..->|implements| DataAPIOutputShaping ArchQueriesImpl -->|uses| PatternGraphAPI ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries - ProjectConfigTypes -->|uses| ConfigurationTypes - ProjectConfigTypes -->|uses| ConfigurationPresets - ConfigurationPresets -->|uses| ConfigurationTypes + CLISchema ..->|implements| CliReferenceGeneration FSMTransitions ..->|implements| PhaseStateMachineValidation FSMStates ..->|implements| PhaseStateMachineValidation PatternGraphAPI -->|uses| PatternGraph @@ -441,6 +441,21 @@ graph LR ## API Types +### SectionBlock (type) + +```typescript +type SectionBlock = + | HeadingBlock + | ParagraphBlock + | SeparatorBlock + | TableBlock + | ListBlock + | CodeBlock + | MermaidBlock + | CollapsibleBlock + | LinkOutBlock; +``` + ### normalizeStatus (function) ````typescript @@ -535,21 +550,6 @@ interface CategoryDefinition { | description | Brief description of the category's purpose and typical patterns | | aliases | Alternative tag names that map to this category (e.g., "es" for "event-sourcing") | -### SectionBlock (type) - -```typescript -type SectionBlock = - | HeadingBlock - | ParagraphBlock - | SeparatorBlock - | TableBlock - | ListBlock - | CodeBlock - | MermaidBlock - | CollapsibleBlock - | LinkOutBlock; -``` - --- ## Behavior Specifications @@ -892,7 +892,7 @@ These are the durable constants of the delivery process. [View ConfigBasedWorkflowDefinition source](architect/specs/config-based-workflow-definition.feature) **Problem:** -Every `pnpm process:query` and `pnpm docs:*` invocation prints: +Every `pnpm architect:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow (6-phase-standard): Workflow file not found` The `loadDefaultWorkflow()` function resolves to `catalogue/workflows/` diff --git a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md index d885edb2..4dd424ac 100644 --- a/docs-live/reference/SESSION-WORKFLOW-GUIDE.md +++ b/docs-live/reference/SESSION-WORKFLOW-GUIDE.md @@ -205,7 +205,7 @@ Three-layer architecture after Phase 39: | No CLAUDE.md drift | Session workflow section generated, not hand-authored | | Single annotated source | This spec owns all session workflow invariants | | Correct audience alignment | Public guide stays in docs/, AI context in \_claude-md/ | -| Process API coverage | Session workflow content queryable via `pnpm process:query -- rules` | +| Process API coverage | Session workflow content queryable via `pnpm architect:query -- rules` | | Immediately useful | Rule: blocks are queryable today, generation follows when Phase 25 ships | **Design Session Findings (2026-03-05):** @@ -349,7 +349,7 @@ Three-layer architecture after Phase 39: - Handoff output reflects annotation state - Handoff output reflects annotation state - Generate handoff via: pnpm process:query -- handoff --pattern PatternName + Generate handoff via: pnpm architect:query -- handoff --pattern PatternName Options: --git (include recent commits) - --session (session identifier) @@ -370,7 +370,7 @@ Three-layer architecture after Phase 39: **Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@architect-claude-module` and `@architect-claude-section:workflow` tags to this spec will cause ClaudeModuleGeneration to produce `_claude-md/workflow/` output files. The hand-written `_claude-md/workflow/` files are deleted after successful verified generation. -**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm process:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. +**Rationale:** The annotation work (Rule blocks in this spec) is immediately useful — queryable via `pnpm architect:query -- rules`. Generation deliverables cannot complete until Phase 25 ships the ClaudeModuleCodec. This sequencing is intentional: the annotation investment has standalone value regardless of whether the codec exists yet. **Prerequisite:** Phase 25 must add `workflow` to the `claude-section` enum values (currently: core, process, testing, infrastructure). diff --git a/docs/DOCS-GAP-ANALYSIS.md b/docs/DOCS-GAP-ANALYSIS.md index 656ba3ab..303b6295 100644 --- a/docs/DOCS-GAP-ANALYSIS.md +++ b/docs/DOCS-GAP-ANALYSIS.md @@ -623,7 +623,7 @@ METHODOLOGY.md (238 lines) contains philosophy that cannot be extracted from cod The master spec already decided to keep it. Design session should confirm and decide: 1. **Keep as-is** (aligned with master spec) -2. **Encode as invariants** in a feature file for queryability via Process Data API +2. **Encode as invariants** in a feature file for queryability via Data API 3. **Merge relevant parts into README.md** as part of Phase 42 **Recommendation:** Option 1, with option 2 as enhancement. The philosophy is diff --git a/docs/INDEX.md b/docs/INDEX.md index a5fa9dfe..22806842 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -231,18 +231,18 @@ ### VALIDATION.md (Lines 1-281) -| Section | Lines | Key Topics | -| --------------------- | ------- | ------------------------------------------------- | -| Which Command? | 7-24 | Decision tree for validation commands | -| Command Summary | 26-35 | lint-patterns, lint-steps, lint-process, validate | -| lint-patterns | 37-74 | 8 rules table, CLI flags | -| lint-steps | 76-98 | 12 rules, 3 categories, vitest-cucumber traps | -| lint-process | 100-121 | What it validates, reference links | -| validate-patterns | 123-197 | CLI flags, checks, anti-patterns, DoD | -| CI/CD Integration | 199-238 | Consumer scripts, hooks, GitHub Actions | -| Exit Codes | 240-248 | Per-command exit code table | -| Programmatic API | 250-272 | Import paths for all validators | -| Related Documentation | 274-281 | Links to GHERKIN-PATTERNS, PROCESS-GUARD, CONFIG | +| Section | Lines | Key Topics | +| --------------------- | ------- | ---------------------------------------------------- | +| Which Command? | 7-24 | Decision tree for validation commands | +| Command Summary | 26-35 | lint-patterns, lint-steps, architect-guard, validate | +| lint-patterns | 37-74 | 8 rules table, CLI flags | +| lint-steps | 76-98 | 12 rules, 3 categories, vitest-cucumber traps | +| architect-guard | 100-121 | What it validates, reference links | +| validate-patterns | 123-197 | CLI flags, checks, anti-patterns, DoD | +| CI/CD Integration | 199-238 | Consumer scripts, hooks, GitHub Actions | +| Exit Codes | 240-248 | Per-command exit code table | +| Programmatic API | 250-272 | Import paths for all validators | +| Related Documentation | 274-281 | Links to GHERKIN-PATTERNS, PROCESS-GUARD, CONFIG | --- diff --git a/docs/PROCESS-API.md b/docs/PROCESS-API.md index 656ebf04..4c3b6752 100644 --- a/docs/PROCESS-API.md +++ b/docs/PROCESS-API.md @@ -2,7 +2,7 @@ > **Deprecated:** The full CLI documentation is now auto-generated. See [CLI Reference Tables](../docs-live/reference/CLI-REFERENCE.md) and [CLI Recipes & Workflow Guide](../docs-live/reference/CLI-RECIPES.md). This file retains only quick-start guidance and operational reference (JSON envelope, exit codes). > -> Query process state directly from annotated source code. +> Query the pattern graph directly from annotated source code. > **For AI coding agents:** Start every session with these three commands: > diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 1a2166ad..625431fa 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -16,7 +16,7 @@ Need to check vitest-cucumber compatibility? ├─ Yes → lint-steps │ Need FSM workflow validation? -├─ Yes → lint-process +├─ Yes → architect-guard │ Need cross-source or DoD validation? ├─ Yes → validate-patterns @@ -234,7 +234,7 @@ Step files: tests/steps/**/*.steps.ts --- -## lint-process +## architect-guard FSM validation for delivery workflow (PDR-005). Enforces status transitions and protection levels. From 55562f45efc40176dee3736bfe5a38b3e0ddbdf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Mijic=CC=81?= Date: Thu, 2 Apr 2026 04:11:06 +0200 Subject: [PATCH 6/6] =?UTF-8?q?fix:=20rename=20docs/PROCESS-API.md=20?= =?UTF-8?q?=E2=86=92=20CLI.md=20and=20exclude=20.md=20from=20CodeRabbit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename deprecated PROCESS-API.md pointer file to CLI.md - Update all 60+ references across src, specs, stubs, and docs - Fix cli-reference-generator link to point to non-deprecated CLI-RECIPES.md - Update .coderabbit.yaml to exclude all .md files from review (reduces file count below 150-file limit that caused "Review skipped") - Regenerate all docs to propagate rename through pipeline --- .coderabbit.yaml | 5 +- CLAUDE.md | 4 +- architect/specs/cli-recipe-codec.feature | 28 +-- .../specs/cli-reference-generation.feature | 18 +- .../specs/docs-consolidation-strategy.feature | 6 +- .../specs/readme-rationalization.feature | 2 +- .../stubs/cli-recipe-codec/recipe-data.ts | 22 +- .../stubs/cli-recipe-codec/recipe-schema.ts | 6 +- .../index-preamble-config.ts | 8 +- docs-live/ARCHITECTURE.md | 14 +- docs-live/CHANGELOG-GENERATED.md | 94 +++---- .../annotation/annotation-overview.md | 2 +- .../architecture/reference-sample.md | 18 +- docs-live/product-areas/ANNOTATION.md | 22 +- docs-live/product-areas/GENERATION.md | 48 ++-- docs-live/product-areas/VALIDATION.md | 4 +- docs-live/reference/CLI-REFERENCE.md | 2 +- docs-live/reference/REFERENCE-SAMPLE.md | 236 +++++++++--------- docs/{PROCESS-API.md => CLI.md} | 0 docs/DOCS-GAP-ANALYSIS.md | 42 ++-- docs/INDEX.md | 10 +- docs/SESSION-GUIDES.md | 6 +- src/cli/cli-schema.ts | 4 +- .../built-in/cli-reference-generator.ts | 2 +- 24 files changed, 300 insertions(+), 303 deletions(-) rename docs/{PROCESS-API.md => CLI.md} (100%) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 5adbc1a4..9d61e359 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -17,12 +17,9 @@ reviews: - '!pnpm-lock.yaml' - '!docs-generated/**' - '!catalogue/artefact-sets/**' - - 'README.md' - - 'CLAUDE.md' - - 'docs-sources/**' + - '!**/*.md' - 'src/**' - 'tests/**' - - 'docs/**' - '.github/**' - 'architect/**/*.feature' diff --git a/CLAUDE.md b/CLAUDE.md index 003450b7..2443fc6d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -578,7 +578,7 @@ console.log(JSON.stringify(doc.sections, null, 2)); #### Design sessions produce decisions and stubs only -**Invariant:** A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Data API must precede any explore agent usage. +**Invariant:** A design session makes architectural decisions and creates code stubs with interfaces. It must not produce implementation code. Context gathering via the Process Data API must precede any explore agent usage. **Rationale:** Design sessions resolve ambiguity before implementation begins. Code stubs in architect/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts. @@ -623,7 +623,7 @@ console.log(JSON.stringify(doc.sections, null, 2)); #### Handoff captures session-end state for continuity -**Invariant:** Multi-session work requires handoff documentation generated from the Data API. Handoff output always reflects actual annotation state, not manual notes. +**Invariant:** Multi-session work requires handoff documentation generated from the Process Data API. Handoff output always reflects actual annotation state, not manual notes. **Rationale:** Manual session notes drift from actual deliverable state. The handoff command derives state from annotations, ensuring the next session starts from ground truth rather than stale notes. diff --git a/architect/specs/cli-recipe-codec.feature b/architect/specs/cli-recipe-codec.feature index 1379adf3..9f7df61e 100644 --- a/architect/specs/cli-recipe-codec.feature +++ b/architect/specs/cli-recipe-codec.feature @@ -7,12 +7,12 @@ @architect-product-area:Generation @architect-depends-on:DocsConsolidationStrategy @architect-depends-on:CliReferenceGeneration -@architect-business-value:replaces-460-lines-of-manual-PROCESS-API-md-prose-with-generated-recipe-and-narrative-content +@architect-business-value:replaces-460-lines-of-manual-CLI-md-prose-with-generated-recipe-and-narrative-content @architect-priority:medium Feature: CLI Recipe Codec **Problem:** - `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after + `docs/CLI.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (CliReferenceGeneration) extracted 3 reference tables to `docs-live/reference/CLI-REFERENCE.md`. The remaining content includes: "Why Use This" motivation (30 lines), Quick Start with example output (32 lines), @@ -29,7 +29,7 @@ Feature: CLI Recipe Codec The generator is a sibling to `CliReferenceGenerator` -- both are standalone (ADR-006 compliant) and consume CLI_SCHEMA directly. Editorial content that cannot be derived from schema (motivation prose, session decision tree) uses the preamble - mechanism. `docs/PROCESS-API.md` retains a slim editorial introduction and links + mechanism. `docs/CLI.md` retains a slim editorial introduction and links to both generated files (reference tables + recipes). **Why It Matters:** @@ -54,7 +54,7 @@ Feature: CLI Recipe Codec | DD-2: CLI_SCHEMA extension is additive with two new optional fields | CliReferenceGenerator and showHelp ignore unknown fields | recipes and commandNarratives fields added to CLISchema interface, not a separate extended type | | DD-3: Preamble mechanism proven by ReferenceDocConfig and ErrorGuideCodec stubs | Why Use This (30 lines), Quick Start (32 lines), Session Types (12 lines) are editorial judgment | Generator accepts preamble SectionBlock[] via CliRecipeGeneratorConfig, configured in architect.config.ts | | DD-4: CommandNarrative type needed, not just CLIOptionGroup.description extension | Session Workflow has 6 commands each needing description + usage example + expected output | New CommandNarrative interface with command, description, usageExample, details, expectedOutput fields | - | DD-5: Recipes grouped by task intent, not session type or command | Matches existing Common Recipes structure in PROCESS-API.md | 5 groups: Starting a Session, Finding Work, Investigating, Design Prep, Ending a Session | + | DD-5: Recipes grouped by task intent, not session type or command | Matches existing Common Recipes structure in CLI.md | 5 groups: Starting a Session, Finding Work, Investigating, Design Prep, Ending a Session | | Content audit: ~460 lines map to 3 schema locations + preamble | Zero information loss from manual to generated | recipes (42 lines), commandNarratives (287 lines), preamble (74 lines), kept in manual (70 lines) | | CliReferenceGenerator is 113 lines and proven stable | Extending it risks regressions on Phase 43 deliverables | CliRecipeGenerator is a separate sibling class, same DocumentGenerator interface | | Generator registration follows cli-reference pattern | generatorOverrides already has cli-reference entry | Add cli-recipe entry with same outputDirectory: docs-live | @@ -72,7 +72,7 @@ Feature: CLI Recipe Codec | Create CliRecipeGenerator producing CLI-RECIPES.md | complete | src/generators/built-in/cli-recipe-generator.ts | Yes | integration | | Register generator in orchestrator config | complete | architect.config.ts | Yes | integration | | Preamble content for Why Use This and session decision tree | complete | architect.config.ts | No | n/a | - | Replace PROCESS-API.md prose sections with pointers to generated files | complete | docs/PROCESS-API.md | No | n/a | + | Replace CLI.md prose sections with pointers to generated files | complete | docs/CLI.md | No | n/a | | Behavior spec with scenarios for recipe generation | n/a | tests/features/behavior/cli/cli-recipe-generation.feature | Yes | acceptance | Rule: CLI recipes are a separate generator from reference tables @@ -189,9 +189,9 @@ Feature: CLI Recipe Codec Then the file begins directly with the first recipe group heading And no empty sections or separators appear at the top - Rule: Generated recipe file complements manual PROCESS-API.md + Rule: Generated recipe file complements manual CLI.md - **Invariant:** After this pattern completes, `docs/PROCESS-API.md` is trimmed to + **Invariant:** After this pattern completes, `docs/CLI.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and @@ -213,8 +213,8 @@ Feature: CLI Recipe Codec Recipe sections no longer duplicated in manual file @acceptance-criteria @happy-path - Scenario: PROCESS-API.md links to both generated files - Given PROCESS-API.md has been trimmed after CliRecipeCodec completion + Scenario: CLI.md links to both generated files + Given CLI.md has been trimmed after CliRecipeCodec completion When reading the manual file Then it contains a link to docs-live/reference/CLI-REFERENCE.md And it contains a link to docs-live/reference/CLI-RECIPES.md @@ -222,11 +222,11 @@ Feature: CLI Recipe Codec @acceptance-criteria @validation Scenario: No recipe content duplicated between manual and generated files - Given PROCESS-API.md and CLI-RECIPES.md both exist + Given CLI.md and CLI-RECIPES.md both exist When comparing their content - Then the Common Recipes section does not appear in PROCESS-API.md - And Session Workflow Commands section does not appear in PROCESS-API.md - And Pattern Discovery section does not appear in PROCESS-API.md + Then the Common Recipes section does not appear in CLI.md + And Session Workflow Commands section does not appear in CLI.md + And Pattern Discovery section does not appear in CLI.md And these sections appear in CLI-RECIPES.md Rule: Command narrative descriptions are sourced from schema metadata @@ -239,7 +239,7 @@ Feature: CLI Recipe Codec and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. - **Rationale:** The manual PROCESS-API.md contains narrative descriptions for each + **Rationale:** The manual CLI.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates diff --git a/architect/specs/cli-reference-generation.feature b/architect/specs/cli-reference-generation.feature index 0da2214c..520c8d87 100644 --- a/architect/specs/cli-reference-generation.feature +++ b/architect/specs/cli-reference-generation.feature @@ -8,10 +8,10 @@ @architect-depends-on:DocsConsolidationStrategy @architect-business-value:keeps-cli-reference-tables-in-sync-with-cli-schema-automatically @architect-priority:low -Feature: PROCESS-API.md Hybrid Generation +Feature: CLI.md Hybrid Generation **Problem:** - `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually + `docs/CLI.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source code: Global Options (lines 382-389, 6 rows), Output Modifiers (lines 397-403, 5 rows), and List Filters (lines 415-424, 8 rows). These ~41 lines are pure data derived from code constants in `src/cli/pattern-graph-cli.ts` @@ -26,7 +26,7 @@ Feature: PROCESS-API.md Hybrid Generation Create a declarative CLI schema (`src/cli/cli-schema.ts`) as the single source of truth. A standalone `CliReferenceGenerator` reads this schema and produces a complete generated reference file at `docs-live/reference/CLI-REFERENCE.md`. - The "Output Reference" section in `docs/PROCESS-API.md` (lines 376-424) is replaced + The "Output Reference" section in `docs/CLI.md` (lines 376-424) is replaced with a heading and link to the generated file. The `showHelp()` function is refactored to consume the same schema, eliminating three-way sync. @@ -46,7 +46,7 @@ Feature: PROCESS-API.md Hybrid Generation | showHelp() lines 271-370 is third copy of same data | Three-way sync risk | Schema drives both help text and doc generation | | Inter-table prose is only ~10 lines total | Must appear in generated file | Encode as description/postNote fields in schema | - **Section Audit — docs/PROCESS-API.md (509 lines):** + **Section Audit — docs/CLI.md (509 lines):** | Section | Lines | Action | Rationale | | Intro + Why Use This | 1-30 | KEEP | Editorial context | | Quick Start | 31-62 | KEEP | Examples with output | @@ -71,7 +71,7 @@ Feature: PROCESS-API.md Hybrid Generation | Sync test verifying schema entries match parseArgs behavior | complete | tests/features/behavior/cli/ | Yes | integration | | CliReferenceGenerator producing complete reference file | complete | src/generators/built-in/cli-reference-generator.ts | Yes | integration | | Register generator in orchestrator config | complete | architect.config.ts | Yes | integration | - | Trim PROCESS-API.md Output Reference to link to generated file | complete | docs/PROCESS-API.md | Yes | manual | + | Trim CLI.md Output Reference to link to generated file | complete | docs/CLI.md | Yes | manual | | Refactor showHelp to consume CLI schema | complete | src/cli/pattern-graph-cli.ts | Yes | integration | | Behavior spec with scenarios for all 3 generated tables | complete | tests/features/behavior/cli/cli-reference.feature | Yes | integration | @@ -112,7 +112,7 @@ Feature: PROCESS-API.md Hybrid Generation Rule: Narrative prose sections remain manual - **Invariant:** PROCESS-API.md sections covering "Why Use This", session type + **Invariant:** CLI.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from @@ -127,11 +127,11 @@ Feature: PROCESS-API.md Hybrid Generation @acceptance-criteria @validation Scenario: Prose sections unchanged after regeneration - Given PROCESS-API.md with narrative sections including "Why Use This" and "Common Recipes" + Given CLI.md with narrative sections including "Why Use This" and "Common Recipes" When the CliReferenceGenerator runs - Then PROCESS-API.md is not modified by the generator + Then CLI.md is not modified by the generator And only CLI-REFERENCE.md is created or updated - And PROCESS-API.md contains a link to CLI-REFERENCE.md in the Output Reference section + And CLI.md contains a link to CLI-REFERENCE.md in the Output Reference section Rule: Standalone generator respects ADR-006 single read model diff --git a/architect/specs/docs-consolidation-strategy.feature b/architect/specs/docs-consolidation-strategy.feature index d36ad18d..fec57b4c 100644 --- a/architect/specs/docs-consolidation-strategy.feature +++ b/architect/specs/docs-consolidation-strategy.feature @@ -41,7 +41,7 @@ Feature: Documentation Consolidation Strategy | METHODOLOGY.md | 238 | Keep: philosophy and core thesis | | SESSION-GUIDES.md | 389 | Phase 39: retained as public reference; CLAUDE.md session section generated from annotated behavior specs | | GHERKIN-PATTERNS.md | 515 | Phase 41: trim to ~250 lines, Step Linting moves to VALIDATION.md | - | PROCESS-API.md | 507 | Phase 43: keep prose, generate 3 reference tables from CLI schema | + | CLI.md | 507 | Phase 43: keep prose, generate 3 reference tables from CLI schema | | PUBLISHING.md | 144 | Phase 40: relocate to MAINTAINERS.md at repo root | | README.md | ~504 | Phase 42: trim to ~150 lines, move pitch content to website | | docs-generated/ structure | n/a | Phase 37: consolidate to docs-live/ as single output directory | @@ -63,7 +63,7 @@ Feature: Documentation Consolidation Strategy | Phase 40 - PUBLISHING.md relocation to MAINTAINERS.md | complete | docs/PUBLISHING.md | No | n/a | | Phase 41 - GHERKIN-PATTERNS.md restructure | complete | docs/GHERKIN-PATTERNS.md, docs/VALIDATION.md | No | n/a | | Phase 42 - README.md rationalization | complete | README.md | No | n/a | - | Phase 43 - PROCESS-API.md hybrid generation | complete | docs/PROCESS-API.md, src/cli/ | Yes | integration | + | Phase 43 - CLI.md hybrid generation | complete | docs/CLI.md, src/cli/ | Yes | integration | | Promote architecture generator from preview to docs:all | complete | package.json, architect.config.ts | No | n/a | | Promote changelog generator from preview to docs:all | complete | package.json, architect.config.ts | No | n/a | @@ -142,7 +142,7 @@ Feature: Documentation Consolidation Strategy **Invariant:** Documents containing philosophy (METHODOLOGY.md) remain fully manual with no generated equivalent (~238 lines). Documents that were originally manual but now have generated equivalents or have been restructured (SESSION-GUIDES.md, - GHERKIN-PATTERNS.md, PROCESS-API.md) retain their editorial content as preamble + GHERKIN-PATTERNS.md, CLI.md) retain their editorial content as preamble within generated outputs. PUBLISHING.md was relocated to MAINTAINERS.md at the repository root. diff --git a/architect/specs/readme-rationalization.feature b/architect/specs/readme-rationalization.feature index 0cb36a5e..be3683ae 100644 --- a/architect/specs/readme-rationalization.feature +++ b/architect/specs/readme-rationalization.feature @@ -156,4 +156,4 @@ Feature: README Rationalization When the rationalization is complete Then install instructions appear within the first 20 lines of README.md And Quick Start steps cover annotate, generate, and enforce - And the Documentation section links to CONFIGURATION.md, METHODOLOGY.md, ARCHITECTURE.md, SESSION-GUIDES.md, GHERKIN-PATTERNS.md, PROCESS-GUARD.md, VALIDATION.md, PROCESS-API.md, and TAXONOMY.md + And the Documentation section links to CONFIGURATION.md, METHODOLOGY.md, ARCHITECTURE.md, SESSION-GUIDES.md, GHERKIN-PATTERNS.md, PROCESS-GUARD.md, VALIDATION.md, CLI.md, and TAXONOMY.md diff --git a/architect/stubs/cli-recipe-codec/recipe-data.ts b/architect/stubs/cli-recipe-codec/recipe-data.ts index e21fe1c9..5644ef22 100644 --- a/architect/stubs/cli-recipe-codec/recipe-data.ts +++ b/architect/stubs/cli-recipe-codec/recipe-data.ts @@ -6,21 +6,21 @@ * * ## Recipe Data — Example Definitions for CLI_SCHEMA Extension * - * Demonstrates how recipe content from docs/PROCESS-API.md maps to the + * Demonstrates how recipe content from docs/CLI.md maps to the * structured `RecipeGroup[]` and `CommandNarrativeGroup[]` schema types * defined in `recipe-schema.ts`. * * **Content source:** All recipe and narrative content below is extracted from - * the manually-maintained `docs/PROCESS-API.md` (509 lines). During + * the manually-maintained `docs/CLI.md` (509 lines). During * implementation, this content moves into `CLI_SCHEMA` in - * `src/cli/cli-schema.ts` and the manual prose sections in PROCESS-API.md + * `src/cli/cli-schema.ts` and the manual prose sections in CLI.md * are replaced with links to the generated file. * * **Coverage:** This stub shows 2 of 5 recipe groups and 2 of 6 command * narratives to validate the schema design. The full implementation will - * include all content from PROCESS-API.md sections: + * include all content from CLI.md sections: * - * | PROCESS-API.md Section | Schema Location | Content Type | + * | CLI.md Section | Schema Location | Content Type | * |------------------------|-----------------|--------------| * | Common Recipes (5 blocks, 42 lines) | `CLI_SCHEMA.recipes` | RecipeGroup[] | * | Session Workflow Commands (6 cmds, 125 lines) | `CLI_SCHEMA.commandNarratives[0]` | CommandNarrativeGroup | @@ -51,7 +51,7 @@ import type { /** * "Starting a Session" recipe — the recommended 3-command startup sequence. * - * Source: docs/PROCESS-API.md lines 470-476 (Common Recipes section). + * Source: docs/CLI.md lines 470-476 (Common Recipes section). */ const startingASessionRecipe: RecipeExample = { title: 'Starting a Session', @@ -75,7 +75,7 @@ const startingASessionRecipe: RecipeExample = { /** * "Finding What to Work On" recipe — discover available work. * - * Source: docs/PROCESS-API.md lines 478-484. + * Source: docs/CLI.md lines 478-484. */ const findingWorkRecipe: RecipeExample = { title: 'Finding What to Work On', @@ -99,7 +99,7 @@ const findingWorkRecipe: RecipeExample = { /** * Example RecipeGroup composing the two recipe examples above. * - * During implementation, all 5 recipe groups from PROCESS-API.md are defined: + * During implementation, all 5 recipe groups from CLI.md are defined: * 1. Starting a Session * 2. Finding What to Work On * 3. Investigating a Pattern @@ -119,7 +119,7 @@ const COMMON_RECIPES: RecipeGroup = { /** * Narrative for the `overview` command. * - * Source: docs/PROCESS-API.md lines 86-91. + * Source: docs/CLI.md lines 86-91. */ const overviewNarrative: CommandNarrative = { command: 'overview', @@ -146,7 +146,7 @@ const overviewNarrative: CommandNarrative = { /** * Narrative for the `scope-validate` command. * - * Source: docs/PROCESS-API.md lines 94-117. + * Source: docs/CLI.md lines 94-117. */ const scopeValidateNarrative: CommandNarrative = { command: 'scope-validate', @@ -201,7 +201,7 @@ const SESSION_WORKFLOW_NARRATIVES: CommandNarrativeGroup = { * 2. Quick Start — 3-command sequence with example `overview` output * 3. Session Types — table + decision tree sentence * - * Source: docs/PROCESS-API.md lines 13-77. + * Source: docs/CLI.md lines 13-77. * * Note: The preamble is configured in architect.config.ts, NOT in * CLI_SCHEMA. This keeps editorial prose separate from structured command diff --git a/architect/stubs/cli-recipe-codec/recipe-schema.ts b/architect/stubs/cli-recipe-codec/recipe-schema.ts index 33cc80a5..c90c437d 100644 --- a/architect/stubs/cli-recipe-codec/recipe-schema.ts +++ b/architect/stubs/cli-recipe-codec/recipe-schema.ts @@ -54,7 +54,7 @@ * Pattern", "Design Session Prep", "Ending a Session". Each `RecipeExample` * has a title, purpose string, array of `RecipeStep` (command + comment), * and optional expected output. This mirrors the existing Common Recipes - * section structure in PROCESS-API.md, ensuring zero information loss. + * section structure in CLI.md, ensuring zero information loss. * * ### Integration with CLISchema * @@ -157,7 +157,7 @@ export interface RecipeGroup { * * Carries the rich description and usage example that appears in the * generated recipe file alongside the command. This replaces the manually - * maintained prose in docs/PROCESS-API.md sections like "Session Workflow + * maintained prose in docs/CLI.md sections like "Session Workflow * Commands" and "Pattern Discovery". * * @example @@ -191,7 +191,7 @@ export interface CommandNarrative { * A group of related command narratives under a shared section heading. * * Maps to sections like "Session Workflow Commands" (6 text commands) - * and "Pattern Discovery" (8 JSON commands) in docs/PROCESS-API.md. + * and "Pattern Discovery" (8 JSON commands) in docs/CLI.md. */ export interface CommandNarrativeGroup { /** Section heading (e.g., 'Session Workflow Commands') */ diff --git a/architect/stubs/enhanced-index-generation/index-preamble-config.ts b/architect/stubs/enhanced-index-generation/index-preamble-config.ts index 300afe60..119e4e79 100644 --- a/architect/stubs/enhanced-index-generation/index-preamble-config.ts +++ b/architect/stubs/enhanced-index-generation/index-preamble-config.ts @@ -113,7 +113,7 @@ export const QUICK_NAVIGATION_SECTIONS: readonly SectionBlock[] = [ ['Write Gherkin specs', '[GHERKIN-PATTERNS.md](docs/GHERKIN-PATTERNS.md)'], ['Enforce delivery process rules', '[PROCESS-GUARD.md](docs/PROCESS-GUARD.md)'], ['Validate annotation quality', '[VALIDATION.md](docs/VALIDATION.md)'], - ['Query process state via CLI', '[PROCESS-API.md](docs/PROCESS-API.md)'], + ['Query process state via CLI', '[CLI.md](docs/CLI.md)'], ['Browse product area overviews', '[PRODUCT-AREAS.md](docs-live/PRODUCT-AREAS.md)'], ['Review architecture decisions', '[DECISIONS.md](docs-live/DECISIONS.md)'], ['Check business rules', '[BUSINESS-RULES.md](docs-live/BUSINESS-RULES.md)'], @@ -159,7 +159,7 @@ export const READING_ORDER_SECTIONS: readonly SectionBlock[] = [ type: 'paragraph' as const, text: [ '4. **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** -- Four-stage pipeline, codecs, PatternGraph', - '5. **[PROCESS-API.md](docs/PROCESS-API.md)** -- Data API CLI query interface', + '5. **[CLI.md](docs/CLI.md)** -- Data API CLI query interface', '6. **[SESSION-GUIDES.md](docs/SESSION-GUIDES.md)** -- Planning/Design/Implementation workflows', '7. **[GHERKIN-PATTERNS.md](docs/GHERKIN-PATTERNS.md)** -- Writing effective Gherkin specs', '8. **[ANNOTATION-GUIDE.md](docs/ANNOTATION-GUIDE.md)** -- Annotation mechanics, shape extraction', @@ -201,7 +201,7 @@ export const DOCUMENT_ROLES_SECTIONS: readonly SectionBlock[] = [ ['METHODOLOGY.md', 'Everyone', 'Why -- core thesis, principles'], ['CONFIGURATION.md', 'Users', 'Setup -- presets, tags, config'], ['ARCHITECTURE.md', 'Developers', 'How -- pipeline, codecs, schemas'], - ['PROCESS-API.md', 'AI/Devs', 'Data API CLI query interface'], + ['CLI.md', 'AI/Devs', 'Data API CLI query interface'], ['SESSION-GUIDES.md', 'AI/Devs', 'Workflow -- day-to-day usage'], ['GHERKIN-PATTERNS.md', 'Writers', 'Specs -- writing effective Gherkin'], ['PROCESS-GUARD.md', 'Team Leads', 'Governance -- enforcement rules'], @@ -336,7 +336,7 @@ export const INDEX_DOCUMENT_ENTRIES: readonly DocumentEntry[] = [ }, { title: 'Process API', - path: 'docs/PROCESS-API.md', + path: 'docs/CLI.md', description: 'Data API CLI query interface for session context', audience: 'AI/Devs', topic: 'Development Workflow', diff --git a/docs-live/ARCHITECTURE.md b/docs-live/ARCHITECTURE.md index 68638fbf..0c19e087 100644 --- a/docs-live/ARCHITECTURE.md +++ b/docs-live/ARCHITECTURE.md @@ -69,11 +69,11 @@ graph TB ContentDeduplicator["ContentDeduplicator[infrastructure]"] CodecBasedGenerator["CodecBasedGenerator[service]"] FileCache["FileCache[infrastructure]"] - DesignReviewGenerator["DesignReviewGenerator[service]"] - DecisionDocGenerator["DecisionDocGenerator[service]"] TransformDataset["TransformDataset[service]"] SequenceTransformUtils["SequenceTransformUtils[service]"] RelationshipResolver["RelationshipResolver[service]"] + DesignReviewGenerator["DesignReviewGenerator[service]"] + DecisionDocGenerator["DecisionDocGenerator[service]"] end subgraph lint["Lint BC"] LintRules["LintRules[service]"] @@ -133,9 +133,6 @@ graph TB DualSourceExtractor --> GherkinExtractor DualSourceExtractor --> GherkinScanner Document_Extractor --> Pattern_Scanner - ConfigResolver --> ArchitectFactory - ArchitectFactory --> RegexBuilders - ConfigLoader --> ArchitectFactory ReplMode --> PatternGraphAPI PatternGraphCLIImpl --> PatternGraphAPI PatternGraphCLIImpl --> PatternGraph @@ -144,6 +141,9 @@ graph TB PatternGraphCLIImpl --> OutputPipelineImpl OutputPipelineImpl --> PatternSummarizerImpl MCPServerBin --> MCPServerImpl + ConfigResolver --> ArchitectFactory + ArchitectFactory --> RegexBuilders + ConfigLoader --> ArchitectFactory PatternSummarizerImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraphAPI ScopeValidatorImpl --> PatternGraph @@ -166,12 +166,12 @@ graph TB DesignReviewCodec --> PatternGraph ArchitectureCodec --> PatternGraph ProcessGuardDecider --> FSMValidator + TransformDataset --> PatternGraph + SequenceTransformUtils --> PatternGraph DesignReviewGenerator --> DesignReviewCodec DesignReviewGenerator --> PatternGraph DecisionDocGenerator -.-> DecisionDocCodec DecisionDocGenerator -.-> SourceMapper - TransformDataset --> PatternGraph - SequenceTransformUtils --> PatternGraph ``` --- diff --git a/docs-live/CHANGELOG-GENERATED.md b/docs-live/CHANGELOG-GENERATED.md index 28fcda3c..a6ebb72d 100644 --- a/docs-live/CHANGELOG-GENERATED.md +++ b/docs-live/CHANGELOG-GENERATED.md @@ -30,6 +30,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Source Merger**: Computes effective sources for a specific generator by applying per-generator overrides to the base resolved sources. - **Define Config**: Identity function for type-safe project configuration. - **File Cache**: Simple Map-based cache for file contents during a single generation run. +- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. +- **Pattern Graph CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. +- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. +- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. +- **Lint Process CLI**: Validates git changes against workflow rules. +- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **Pattern Graph API Types**: :PatternGraph Type definitions for the PatternGraphAPI query interface. - **Pattern Summarizer Impl**: Projects the full ExtractedPattern (~3.5KB per pattern) down to a PatternSummary (~100 bytes) for list queries. - **Stub Resolver Impl**: Identifies design session stubs in the PatternGraph and resolves them against the filesystem to determine... @@ -41,26 +47,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Context Formatter Impl**: First plain-text formatter in the codebase. - **Context Assembler Impl**: Pure function composition over PatternGraph. - **Arch Queries Impl**: Pure functions over PatternGraph for deep architecture exploration. -- **Repl Mode**: Loads the pipeline once and accepts multiple queries on stdin. -- **Pattern Graph CLI Impl**: Exposes PatternGraphAPI methods as CLI subcommands with JSON output. -- **Output Pipeline Impl**: Post-processing pipeline that transforms raw API results into shaped CLI output. -- **MCP Server Bin**: Handles stdout isolation, CLI arg parsing, and process lifecycle. -- **Lint Process CLI**: Validates git changes against workflow rules. -- **Dataset Cache**: Caches the full PipelineResult (PatternGraph + ValidationSummary + warnings) to a JSON file. - **FSM Validator**: :PDR005MvpWorkflow Pure validation functions following the Decider pattern: - No I/O, no side effects - Return... - **FSM Transitions**: :PDR005MvpWorkflow Defines valid transitions between FSM states per PDR-005: ``` roadmap ──→ active ──→ completed │ ... - **FSM States**: :PDR005MvpWorkflow Defines the 4-state FSM from PDR-005 MVP Workflow: - roadmap: Planned work (fully editable) -... - **FSM Module**: :PDR005MvpWorkflow Central export for the 4-state FSM defined in PDR-005: ``` roadmap ──→ active ──→ completed │ ... -- **Process Guard Types**: :FSMValidator Defines types for the process guard linter including: - Process state derived from file annotations -... -- **Process Guard Module**: :FSMValidator,DeriveProcessState,DetectChanges,ProcessGuardDecider Enforces workflow rules by validating changes... -- **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... -- **Derive Process State**: :GherkinScanner,FSMValidator Derives process state from @architect-\* annotations in files. -- **Process Guard Decider**: :FSMValidator,DeriveProcessState,DetectChanges Pure function that validates changes against process rules. - **Reference Document Codec**: :Generation A single codec factory that creates reference document codecs from configuration objects. - **Design Review Codec**: :Generation Transforms PatternGraph into a RenderableDocument containing design review artifacts: sequence diagrams,... - **Composite Codec**: :Generation Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. - **Codec Registry Barrel**: Collects all codecMeta exports into a single array. - **Claude Module Codec**: :Generation Transforms PatternGraph into RenderableDocuments for CLAUDE.md module generation. +- **Process Guard Types**: :FSMValidator Defines types for the process guard linter including: - Process state derived from file annotations -... +- **Process Guard Module**: :FSMValidator,DeriveProcessState,DetectChanges,ProcessGuardDecider Enforces workflow rules by validating changes... +- **Detect Changes**: Detects changes from git diff including: - Modified, added, deleted files - Status transitions (@architect-status... +- **Derive Process State**: :GherkinScanner,FSMValidator Derives process state from @architect-\* annotations in files. +- **Process Guard Decider**: :FSMValidator,DeriveProcessState,DetectChanges Pure function that validates changes against process rules. - **Reference Generator Registration**: Registers all reference document generators. - **Design Review Generator**: :Generation Generates design review documents for patterns with sequence annotations. - **Transform Types**: Type definitions for the dataset transformation pipeline. @@ -86,17 +86,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Pattern Graph Cli Help**: Per-subcommand help displays usage, flags, and examples for individual subcommands. - **Pattern Graph Cli Dry Run**: Dry-run mode shows pipeline scope without processing data. - **Pattern Graph Cli Cache**: PatternGraph caching between CLI invocations: cache hits, mtime invalidation, and --no-cache bypass. +- **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. +- **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. - **Stub Taxonomy Tag Tests**: Stub metadata (target path, design session) was stored as plain text in JSDoc descriptions, invisible to structured... - **Stub Resolver Tests**: Design session stubs need structured discovery and resolution to determine which stubs have been implemented and... -- **Arch Queries Test** -- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... -- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... - **Pattern Summarize Tests**: Validates that summarizePattern() projects ExtractedPattern (~3.5KB) to PatternSummary (~100 bytes) with the correct... - **Pattern Helpers Tests** - **Output Pipeline Tests**: Validates the output pipeline transforms: summarization, modifiers, list filters, empty stripping, and format output. - **Fuzzy Match Tests**: Validates tiered fuzzy matching: exact > prefix > substring > Levenshtein. -- **Uses Tag Testing**: Tests extraction and processing of @architect-uses and @architect-used-by relationship tags from TypeScript files. -- **Depends On Tag Testing**: Tests extraction of @architect-depends-on and @architect-enables relationship tags from Gherkin files. +- **Context Formatter Tests**: Tests for formatContextBundle(), formatDepTree(), formatFileReadingList(), and formatOverview() plain text rendering... +- **Context Assembler Tests**: Tests for assembleContext(), buildDepTree(), buildFileReadingList(), and buildOverview() pure functions that operate... +- **Arch Queries Test** --- @@ -142,12 +142,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Utils Module**: Common helper functions used across the Architect package. - **Pattern Id Generator**: Generates unique, deterministic pattern IDs based on file path and line number. - **Collection Utilities**: Provides shared utilities for working with arrays and collections, such as grouping items by a key function. -- **Result Monad Types**: Explicit error handling via discriminated union. -- **Error Factory Types**: Structured, discriminated error types with factory functions. -- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. -- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. -- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... -- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Status Values**: THE single source of truth for FSM state values in the monorepo (per PDR-005 FSM). - **Risk Levels**: Three-tier risk classification for roadmap planning. - **Tag Registry Builder**: Constructs a complete TagRegistry from TypeScript constants. @@ -156,14 +150,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Hierarchy Levels**: Three-level hierarchy for organizing work: - epic: Multi-quarter strategic initiatives - phase: Standard work units... - **Format Types**: Defines how tag values are parsed and validated. - **Category Definitions**: Categories are used to classify patterns and organize documentation. -- **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. -- **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. -- **Lint Engine**: Orchestrates lint rule execution against parsed directives. +- **Pattern Scanner**: Discovers TypeScript files matching glob patterns and filters to only those with `@architect` opt-in. +- **Gherkin Scanner**: Scans .feature files for pattern metadata encoded in Gherkin tags. +- **Gherkin AST Parser**: Parses Gherkin feature files using @cucumber/gherkin and extracts structured data including feature metadata, tags,... +- **TypeScript AST Parser**: Parses TypeScript source files using @typescript-eslint/typescript-estree to extract @architect-\* directives with... - **Renderable Utils**: Utility functions for document codecs. - **Renderable Document**: Universal intermediate format for all generated documentation. - **Universal Renderer**: Converts RenderableDocument to output strings. - **Renderable Document Model(RDM)**: Unified document generation using codecs and a universal renderer. - **Document Generator**: Simplified document generation using codecs. +- **Lint Rules**: Defines lint rules that check @architect-\* directives for completeness and quality. +- **Lint Module**: Provides lint rules and engine for pattern annotation quality checking. +- **Lint Engine**: Orchestrates lint rule execution against parsed directives. - **Shape Extractor**: Extracts TypeScript type definitions (interfaces, type aliases, enums, function signatures) from source files for... - **Layer Inference**: Infers feature file layer (timeline, domain, integration, e2e, component) from directory path patterns. - **Gherkin Extractor**: Transforms scanned Gherkin feature files into ExtractedPattern objects for inclusion in generated documentation. @@ -184,15 +182,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Architect Factory**: Main factory function for creating configured Architect instances. - **Configuration Defaults**: Centralized default constants for the Architect package. - **Config Loader**: Discovers and loads `architect.config.ts` or `architect.config.js` files for hierarchical configuration. -- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. -- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. -- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. +- **Result Monad Types**: Explicit error handling via discriminated union. +- **Error Factory Types**: Structured, discriminated error types with factory functions. - **CLI Version Helper**: Reads package version from package.json for CLI --version flag. - **Validate Patterns CLI**: Cross-validates TypeScript patterns vs Gherkin feature files. - **Lint Patterns CLI**: Validates pattern annotations for quality and completeness. - **Documentation Generator CLI**: Replaces multiple specialized CLIs with one unified interface that supports multiple generators in a single run. - **CLI Error Handler**: Provides type-safe error handling for all CLI commands using the DocError discriminated union pattern. - **CLI Schema**: :DataAPI Declarative schema defining all CLI options for the architect command. +- **Scope Validator Impl**: Pure function composition over PatternGraphAPI and PatternGraph. +- **Rules Query Module**: Pure query function for business rules extracted from Gherkin Rule: blocks. +- **Handoff Generator Impl**: Pure function that assembles a handoff document from PatternGraphAPI and PatternGraph. - **Validation Rules Codec**: :Generation Transforms PatternGraph into a RenderableDocument for Process Guard validation rules reference. - **Timeline Codec**: :Generation Purpose: Development roadmap organized by phase with progress tracking. - **Taxonomy Codec**: :Generation Transforms PatternGraph into a RenderableDocument for taxonomy reference output. @@ -261,8 +261,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Cross Cutting Document Inclusion**: The reference doc codec assembles content from four sources, each with its own selection mechanism: conventionTags... - **Config Based Workflow Definition**: Every `pnpm architect:query` and `pnpm docs:*` invocation prints: `Failed to load default workflow... - **Codec Driven Reference Generation**: Each reference document (Process Guard, Taxonomy, Validation, etc.) required a hand-coded recipe feature that... -- **Cli Reference Generation**: `docs/PROCESS-API.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source... -- **Cli Recipe Codec**: `docs/PROCESS-API.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (CliReferenceGeneration)... +- **Cli Reference Generation**: `docs/CLI.md` (509 lines) contains three reference tables that manually mirror CLI definitions in source code: Global... +- **Cli Recipe Codec**: `docs/CLI.md` (~509 lines) retains ~460 lines of editorial prose after Phase 43 (CliReferenceGeneration) extracted 3... - **Claude Module Generation**: Problem: CLAUDE.md modules are hand-written markdown files that drift from source code over time. - **Architecture Doc Refactoring**: ARCHITECTURE.md is 1,287 lines of manually-maintained documentation covering 14 sections. - **Architecture Diagram Core**: Problem: Architecture documentation requires manually maintaining mermaid diagrams that duplicate information already... @@ -277,13 +277,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **String Utils**: String utilities provide consistent text transformations across the codebase. - **Result Monad**: The Result type provides explicit error handling via a discriminated union. - **Error Factories**: Error factories create structured, discriminated error types with consistent message formatting. -- **Rule Keyword Po C**: This feature tests whether vitest-cucumber supports the Rule keyword for organizing scenarios under business rules. - **Gherkin Ast Parser**: The Gherkin AST parser extracts feature metadata, scenarios, and steps from .feature files for timeline generation... - **File Discovery**: The file discovery system uses glob patterns to find TypeScript files for documentation extraction. - **Doc String Media Type**: DocString language hints (mediaType) should be preserved through the parsing pipeline from feature files to rendered... - **Ast Parser Relationships Edges**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Metadata**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. - **Ast Parser Exports**: The AST Parser extracts @architect-\* directives from TypeScript source files using the TypeScript compiler API. +- **Rule Keyword Po C**: This feature tests whether vitest-cucumber supports the Rule keyword for organizing scenarios under business rules. - **Lint Rule Individual Testing**: Individual lint rules that check parsed directives for completeness. - **Lint Rule Advanced Testing**: Complex lint rule logic and collection-level behavior. - **Lint Engine Testing**: The lint engine orchestrates rule execution, aggregates violations, and formats output for human and machine... @@ -299,13 +299,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Extraction Pipeline Enhancements Testing**: Validates extraction pipeline capabilities for ReferenceDocShowcase: function signature surfacing, full... - **Dual Source Extractor Testing**: Extracts and combines pattern metadata from both TypeScript code stubs (@architect-) and Gherkin feature files... - **Declaration Level Shape Tagging Testing**: Tests the discoverTaggedShapes function that scans TypeScript source code for declarations annotated with the... -- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... -- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... -- **Preset System**: Presets provide pre-configured taxonomies for different project types. -- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... -- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. -- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... -- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Warning Collector Testing**: The warning collector provides a unified system for capturing, categorizing, and reporting non-fatal issues during... - **Validation Rules Codec Testing**: Validates the Validation Rules Codec that transforms PatternGraph into a RenderableDocument for Process Guard... - **Taxonomy Codec Testing**: Validates the Taxonomy Codec that transforms PatternGraph into a RenderableDocument for tag taxonomy reference... @@ -317,6 +310,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Decision Doc Generator Testing**: The Decision Doc Generator orchestrates the full documentation generation pipeline from decision documents (ADR/PDR in . - **Decision Doc Codec Testing**: Validates the Decision Doc Codec that parses decision documents (ADR/PDR in .feature format) and extracts content for... - **Content Deduplication**: Context: Multiple sources may extract identical content, leading to duplicate sections in generated documentation. +- **Source Merging**: mergeSourcesForGenerator computes effective sources for a specific generator by applying per-generator overrides to... +- **Project Config Loader**: loadProjectConfig loads and resolves configuration from file, using the unified defineConfig project configuration... +- **Preset System**: Presets provide pre-configured taxonomies for different project types. +- **Define Config Testing**: The defineConfig identity function and ArchitectProjectConfigSchema provide type-safe configuration authoring with... +- **Configuration API**: The createArchitect factory provides a type-safe way to configure the package with custom tag prefixes and presets. +- **Config Resolution**: resolveProjectConfig transforms a raw ArchitectProjectConfig into a fully resolved ResolvedConfig with all defaults... +- **Config Loader Testing**: The config loader discovers and loads `architect.config.ts` files for hierarchical configuration, enabling... - **Validate Patterns Cli**: Command-line interface for cross-validating TypeScript patterns vs Gherkin feature files. - **Pattern Graph Cli Subcommands**: Discovery subcommands: list, search, context assembly, tags/sources, extended arch, unannotated. - **Pattern Graph Cli Modifiers And Rules**: Output modifiers, arch health, and rules subcommand. @@ -324,7 +324,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Lint Process Cli**: Command-line interface for validating changes against delivery process rules. - **Lint Patterns Cli**: Command-line interface for validating pattern annotation quality. - **Generate Docs Cli**: Command-line interface for generating documentation from annotated TypeScript. -- **Pattern Graph API Testing**: Programmatic interface for querying the pattern graph and delivery process state. - **Transform Dataset Testing**: The transformToPatternGraph function transforms raw extracted patterns into a PatternGraph with all pre-computed... - **Session Handoffs**: The delivery process supports mid-phase handoffs between sessions and coordination across multiple developers through... - **Session File Lifecycle**: Orphaned session files are automatically cleaned up during generation, maintaining a clean docs-living/sessions/... @@ -347,12 +346,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Description Header Normalization**: Pattern descriptions should not create duplicate headers when rendered. - **Context Inference**: Patterns in standard directories (src/validation/, src/scanner/) should automatically receive architecture context... - **Zod Codec Migration**: All JSON parsing and serialization uses type-safe Zod codec pattern, replacing raw JSON.parse/stringify with... -- **Scope Validator Tests**: Starting an implementation or design session without checking prerequisites wastes time when blockers are discovered... -- **Handoff Generator Tests**: Multi-session work loses critical state between sessions when handoff documentation is manual or forgotten. +- **Pattern Graph API Testing**: Programmatic interface for querying the pattern graph and delivery process state. - **Mermaid Relationship Rendering**: Tests for rendering all relationship types in Mermaid dependency graphs with distinct visual styles per relationship... - **Linter Validation Testing**: Tests for lint rules that validate relationship integrity, detect conflicts, and ensure bidirectional traceability... - **Implements Tag Processing**: Tests for the @architect-implements tag which links implementation files to their corresponding roadmap pattern... - **Extends Tag Testing**: Tests for the @architect-extends tag which establishes generalization relationships between patterns (pattern... +- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... +- **Layered Diagram Generation**: As a documentation generator I want to generate layered architecture diagrams from metadata So that system... +- **Arch Generator Registration**: As a CLI user I want an architecture generator registered in the generator registry So that I can run pnpm... +- **Component Diagram Generation**: As a documentation generator I want to generate component diagrams from architecture metadata So that system... +- **Arch Tag Extraction**: As a documentation generator I want architecture tags extracted from source code So that I can generate accurate... +- **Arch Index Dataset**: As a documentation generator I want an archIndex built during dataset transformation So that I can efficiently look... - **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform PatternGraph into... - **Shape Selector Testing**: Tests the filterShapesBySelectors function that provides fine-grained shape selection via structural discriminated... - **Shape Matcher Testing**: Matches file paths against glob patterns for TypeScript shape extraction. @@ -371,11 +375,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - **Dedent Helper**: The dedent helper function normalizes indentation in code blocks extracted from DocStrings. - **Convention Extractor Testing**: Extracts convention content from PatternGraph decision records tagged with @architect-convention. - **Composite Codec Testing**: Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections. -- **Pattern Graph Cli Reference Tests**: Verifies that the declarative CLI schema drives reference table generation and stays in sync with the parser... -- **Layered Diagram Generation**: As a documentation generator I want to generate layered architecture diagrams from metadata So that system... -- **Arch Generator Registration**: As a CLI user I want an architecture generator registered in the generator registry So that I can run pnpm... -- **Component Diagram Generation**: As a documentation generator I want to generate component diagrams from architecture metadata So that system... -- **Arch Tag Extraction**: As a documentation generator I want architecture tags extracted from source code So that I can generate accurate... -- **Arch Index Dataset**: As a documentation generator I want an archIndex built during dataset transformation So that I can efficiently look... +- **Scope Validator Tests**: Starting an implementation or design session without checking prerequisites wastes time when blockers are discovered... +- **Handoff Generator Tests**: Multi-session work loses critical state between sessions when handoff documentation is manual or forgotten. --- diff --git a/docs-live/_claude-md/annotation/annotation-overview.md b/docs-live/_claude-md/annotation/annotation-overview.md index 667930e6..737875e3 100644 --- a/docs-live/_claude-md/annotation/annotation-overview.md +++ b/docs-live/_claude-md/annotation/annotation-overview.md @@ -19,8 +19,8 @@ | MetadataTagDefinitionForRegistry | interface | | CategoryDefinition | interface | | CategoryTag | type | -| isShapeOnlyDirective | function | | buildRegistry | function | +| isShapeOnlyDirective | function | | METADATA_TAGS_BY_GROUP | const | | CATEGORIES | const | | CATEGORY_TAGS | const | diff --git a/docs-live/_claude-md/architecture/reference-sample.md b/docs-live/_claude-md/architecture/reference-sample.md index b21a2b82..7f77aab8 100644 --- a/docs-live/_claude-md/architecture/reference-sample.md +++ b/docs-live/_claude-md/architecture/reference-sample.md @@ -117,6 +117,15 @@ ##### DefineConfig +##### ConfigBasedWorkflowDefinition + +| Rule | Description | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| Default workflow is built from an inline constant | **Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without
file system access. It cannot fail. The... | +| Custom workflow files still work via --workflow flag | **Invariant:** `loadWorkflowFromPath()` remains available for projects
that need custom workflow definitions. The... | +| FSM validation and Process Guard are not affected | **Invariant:** The FSM transition matrix, protection levels, and Process
Guard rules remain hardcoded in... | +| Workflow as a configurable preset field is deferred | **Invariant:** The inline default workflow constant is the only workflow source until preset integration is... | + ##### ADR005CodecBasedMarkdownRendering | Rule | Description | @@ -141,15 +150,6 @@ | Canonical phase definitions (6-phase USDP standard) | **Invariant:** The default workflow defines exactly 6 phases in fixed
order. These are the canonical phase names... | | Deliverable status canonical values | **Invariant:** Deliverable status (distinct from pattern FSM status)
uses exactly 6 values, enforced by Zod... | -##### ConfigBasedWorkflowDefinition - -| Rule | Description | -| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| Default workflow is built from an inline constant | **Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without
file system access. It cannot fail. The... | -| Custom workflow files still work via --workflow flag | **Invariant:** `loadWorkflowFromPath()` remains available for projects
that need custom workflow definitions. The... | -| FSM validation and Process Guard are not affected | **Invariant:** The FSM transition matrix, protection levels, and Process
Guard rules remain hardcoded in... | -| Workflow as a configurable preset field is deferred | **Invariant:** The inline default workflow constant is the only workflow source until preset integration is... | - ##### ProcessGuardTesting | Rule | Description | diff --git a/docs-live/product-areas/ANNOTATION.md b/docs-live/product-areas/ANNOTATION.md index f9d6eaa1..773cad42 100644 --- a/docs-live/product-areas/ANNOTATION.md +++ b/docs-live/product-areas/ANNOTATION.md @@ -210,35 +210,35 @@ interface CategoryDefinition { type CategoryTag = (typeof CATEGORIES)[number]['tag']; ``` -### isShapeOnlyDirective (function) +### buildRegistry (function) ```typescript /** - * Check if a directive is a shape-only annotation (declaration-level @architect-shape). + * Build the complete tag registry from TypeScript constants * - * Shape directives annotate individual interfaces/types for documentation extraction. - * They inherit context from a parent pattern and should not enter the directive pipeline - * as standalone patterns. + * This is THE single source of truth for the taxonomy. + * All consumers should use this function instead of loading JSON. */ ``` ```typescript -function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; +function buildRegistry(): TagRegistry; ``` -### buildRegistry (function) +### isShapeOnlyDirective (function) ```typescript /** - * Build the complete tag registry from TypeScript constants + * Check if a directive is a shape-only annotation (declaration-level @architect-shape). * - * This is THE single source of truth for the taxonomy. - * All consumers should use this function instead of loading JSON. + * Shape directives annotate individual interfaces/types for documentation extraction. + * They inherit context from a parent pattern and should not enter the directive pipeline + * as standalone patterns. */ ``` ```typescript -function buildRegistry(): TagRegistry; +function isShapeOnlyDirective(directive: DocDirective, registry: TagRegistry): boolean; ``` ### METADATA_TAGS_BY_GROUP (const) diff --git a/docs-live/product-areas/GENERATION.md b/docs-live/product-areas/GENERATION.md index dc43dd2c..020afebd 100644 --- a/docs-live/product-areas/GENERATION.md +++ b/docs-live/product-areas/GENERATION.md @@ -64,15 +64,15 @@ graph TB GitBranchDiff["GitBranchDiff"] SourceMapper[/"SourceMapper"/] Documentation_Generation_Orchestrator("Documentation Generation Orchestrator") + DesignReviewGenerator("DesignReviewGenerator") + DecisionDocGenerator("DecisionDocGenerator") + CliReferenceGenerator["CliReferenceGenerator"] + CliRecipeGenerator["CliRecipeGenerator"] TransformTypes["TransformTypes"] TransformDataset("TransformDataset") SequenceTransformUtils("SequenceTransformUtils") RelationshipResolver("RelationshipResolver") ContextInferenceImpl["ContextInferenceImpl"] - DesignReviewGenerator("DesignReviewGenerator") - DecisionDocGenerator("DecisionDocGenerator") - CliReferenceGenerator["CliReferenceGenerator"] - CliRecipeGenerator["CliRecipeGenerator"] end subgraph renderer["Renderer"] loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser["loadPreambleFromMarkdown — Shared Markdown-to-SectionBlock Parser"] @@ -110,13 +110,6 @@ graph TB DesignReviewCodec ..->|implements| DesignReviewGeneration CompositeCodec ..->|implements| ReferenceDocShowcase ArchitectureCodec -->|uses| PatternGraph - TransformTypes -->|uses| PatternGraph - TransformDataset -->|uses| PatternGraph - TransformDataset ..->|implements| PatternRelationshipModel - SequenceTransformUtils -->|uses| PatternGraph - SequenceTransformUtils ..->|implements| DesignReviewGeneration - RelationshipResolver -->|uses| PatternHelpers - ContextInferenceImpl ..->|implements| ContextInference DesignReviewGenerator -->|uses| DesignReviewCodec DesignReviewGenerator -->|uses| PatternGraph DesignReviewGenerator ..->|implements| DesignReviewGeneration @@ -124,6 +117,13 @@ graph TB DecisionDocGenerator -.->|depends on| SourceMapper CliReferenceGenerator ..->|implements| CliReferenceGeneration CliRecipeGenerator ..->|implements| CliRecipeCodec + TransformTypes -->|uses| PatternGraph + TransformDataset -->|uses| PatternGraph + TransformDataset ..->|implements| PatternRelationshipModel + SequenceTransformUtils -->|uses| PatternGraph + SequenceTransformUtils ..->|implements| DesignReviewGeneration + RelationshipResolver -->|uses| PatternHelpers + ContextInferenceImpl ..->|implements| ContextInference DesignReviewGeneration -.->|depends on| MermaidDiagramUtils CliRecipeCodec -.->|depends on| CliReferenceGeneration classDef neighbor stroke-dasharray: 5 5 @@ -427,21 +427,21 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; ### Cli Recipe Codec -| Rule | Invariant | Rationale | -| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/CLI-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | -| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | -| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | -| Generated recipe file complements manual PROCESS-API.md | After this pattern completes, `docs/PROCESS-API.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/CLI-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | -| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual PROCESS-API.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI recipes are a separate generator from reference tables | The `CliRecipeGenerator` is a standalone sibling to `CliReferenceGenerator`, not an extension of it. Both implement `DocumentGenerator`, both consume `CLI_SCHEMA` directly, and both produce independent `OutputFile[]` via the standard orchestrator write path. The recipe generator produces `docs-live/reference/CLI-RECIPES.md` while the reference generator produces `docs-live/reference/CLI-REFERENCE.md`. | Reference tables and recipe guides serve different audiences and change at different cadences. Reference tables change when CLI flags are added or removed. Recipes change when workflow recommendations evolve. Coupling them in one generator would force both to change together and make the generator responsible for two distinct content types. CliReferenceGenerator is already completed and tested (Phase 43) -- extending it risks regressions. Two small standalone generators are easier to test and maintain than one large one. | +| Recipe content uses a structured schema extension | `CLI_SCHEMA` is extended with a `recipes` field containing `RecipeGroup[]`. Each `RecipeGroup` has a title, optional description, and an array of `RecipeExample` objects. Each `RecipeExample` has a title, a purpose description, an array of RecipeStep entries (each with a command string and optional comment), and an optional expected output block. The schema extension is additive -- existing `CLIOptionGroup` types are unchanged. | Recipes are multi-command sequences ("run these 3 commands in order") with explanatory context. They do not fit into `CLIOptionGroup` which models individual flags. A separate `RecipeGroup[]` keeps the schema type-safe and makes recipes independently testable. Static expected output strings in the schema are deterministic -- no build-time CLI execution needed. | +| Narrative prose uses preamble mechanism | Editorial content that cannot be derived from the CLI schema -- specifically "Why Use This" motivational prose, the Quick Start example with output, and the session type decision tree -- uses a preamble mechanism in the generator configuration. Preamble content is manually authored in `architect.config.ts` as structured section data and appears before all generated recipe content in the output file. | The "Why Use This" section explains the value proposition of the Data API CLI with a comparison table (CLI vs reading markdown). This is editorial judgment, not derivable from command metadata. The Quick Start shows a specific 3-command workflow with example terminal output. The session decision tree maps cognitive states ("Starting to code?") to session types. None of these have a source annotation -- they are instructional content authored for human understanding. The preamble mechanism exists precisely for this (proven by DocsConsolidationStrategy Phase 2 preamble implementation). | +| Generated recipe file complements manual CLI.md | After this pattern completes, `docs/CLI.md` is trimmed to a slim editorial introduction (~30 lines) containing the document title, a one-paragraph purpose statement, and links to both generated files: `docs-live/reference/CLI-REFERENCE.md` (option tables from Phase 43) and `docs-live/reference/CLI-RECIPES.md` (recipes and narratives from this pattern). The manual file retains the JSON Envelope, Exit Codes, and JSON Piping sections (~40 lines) which are operational reference unlikely to drift. All other prose sections are replaced by the generated recipe file. | Phase 43 established the hybrid pattern: keep editorial prose in the manual file, extract derivable content to generated files. This pattern extends the hybrid by recognizing that recipe content IS derivable from a structured schema. The ~460 lines of command descriptions, example output, and recipe blocks can be maintained as schema data rather than freeform markdown. What remains in the manual file (~70 lines total) is true operational reference (JSON envelope format, exit codes, piping tips) that changes rarely and has no schema source. | +| Command narrative descriptions are sourced from schema metadata | Each command group in the generated recipe file includes a narrative description sourced from the CLI schema, not hardcoded in the generator. The existing `CLIOptionGroup.description` and `CLIOptionGroup.postNote` fields carry per-group narrative text. For command groups not currently in CLI_SCHEMA (Session Workflow Commands, Pattern Discovery, Architecture Queries, Metadata and Inventory), new `CommandGroup` entries are added to the schema with title, description, and per-command narrative metadata. | The manual CLI.md contains narrative descriptions for each command ("Highest-impact command. Pre-flight readiness check that prevents wasted sessions.") that are valuable developer context. Hardcoding these in the generator would create a second maintenance location. Placing them in CLI_SCHEMA co-locates command metadata (what the command does) with command definition (what flags it accepts), following the same single-source-of-truth principle that drove Phase 43. | ### Cli Reference Generation -| Rule | Invariant | Rationale | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/CLI-REFERENCE.md` are generated from this schema by a standalone `CliReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/pattern-graph-cli.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). | -| Narrative prose sections remain manual | PROCESS-API.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | -| Standalone generator respects ADR-006 single read model | The `CliReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | +| Rule | Invariant | Rationale | +| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI schema is single source of truth for reference tables | A declarative CLI schema in `src/cli/cli-schema.ts` defines all global options, output modifiers, and list filters with their flags, descriptions, defaults, and value types. The three reference tables in `docs-live/reference/CLI-REFERENCE.md` are generated from this schema by a standalone `CliReferenceGenerator`. The schema also drives `showHelp()`. | CLI options are defined imperatively in `parseArgs()` (lines 132-265 of `src/cli/pattern-graph-cli.ts`) and `OutputModifiers`/`ListFilters` interfaces (lines 43-83 of `src/cli/output-pipeline.ts`). A declarative schema extracts this into a single structured definition that both documentation and help text consume. The existing `ReferenceDocConfig` system cannot be used because it sources from PatternGraph (annotation-derived data), not static constants (ADR-006). | +| Narrative prose sections remain manual | CLI.md sections covering "Why Use This", session type decision tree, workflow recipes, worked examples with expected output, and "Common Recipes" are not generated. They require editorial judgment and context that cannot be extracted from code annotations. The document's value comes from these sections — the generated reference tables are supporting material only. | Generated docs without prose context would be a bare options table — usable as reference but not as a learning resource. The hybrid approach gives both: accurate tables from code, readable narrative from editorial work. | +| Standalone generator respects ADR-006 single read model | The `CliReferenceGenerator` imports CLI schema data directly from `src/cli/cli-schema.ts`. It does NOT inject CLI data into PatternGraph or consume PatternGraph for table generation. It implements `DocumentGenerator` and returns `OutputFile[]` via the standard orchestrator write path. | ADR-006 establishes PatternGraph as the sole read model for annotation-sourced data. CLI schema is a static TypeScript constant, not extracted from annotations. Forcing it through PatternGraph would violate the "no parallel pipeline" anti-pattern. A standalone generator with its own data source is architecturally correct. | ### Codec Based Generator Testing @@ -621,7 +621,7 @@ function transformToPatternGraph(raw: RawDataset): RuntimePatternGraph; | Convention tags are the primary consolidation mechanism | Each consolidation phase follows the same pattern: register a convention tag value in `src/taxonomy/conventions.ts`, annotate source files with `@architect-convention` tags using structured JSDoc, add a `ReferenceDocConfig` entry in `architect.config.ts`, and replace the manual doc section with a pointer to the generated reference document. | Convention-tagged annotations are the only sustainable way to keep docs in sync with implementation. The reference codec (`createReferenceCodec`) already handles the 4-layer composition so each phase only needs annotation work and config — no new codec infrastructure required. | | Preamble preserves editorial context in generated docs | `ReferenceDocConfig.preamble` accepts `readonly SectionBlock[]` that are prepended before all generated content. Preamble sections appear in both detailed and summary (claude-md) outputs, followed by a separator. A config without preamble produces no extra separator or empty sections. | Not all documentation content can be extracted from code annotations. Introductory prose, cross-cutting context, and reading guides require human authorship. The preamble provides a designated place for this content within the generated document structure, avoiding a separate hand-maintained file. | | Each consolidation phase is independently deliverable | Each phase can be implemented and validated independently. A phase is complete when: the manual doc section has been replaced with a pointer to the generated equivalent, `pnpm docs:all` produces the generated output without errors, and the generated content covers the replaced manual content. No phase requires another uncompleted phase to function. | Independent phases allow incremental consolidation without blocking on the full initiative. Each merged PR reduces manual maintenance immediately. Phase ordering in the plan is a suggested sequence (simplest first), not a dependency chain. | -| Manual docs retain editorial and tutorial content | Documents containing philosophy (METHODOLOGY.md) remain fully manual with no generated equivalent (~238 lines). Documents that were originally manual but now have generated equivalents or have been restructured (SESSION-GUIDES.md, GHERKIN-PATTERNS.md, PROCESS-API.md) retain their editorial content as preamble within generated outputs. PUBLISHING.md was relocated to MAINTAINERS.md at the repository root. | The consolidation targets sections most likely to drift when code changes: reference tables, codec listings, validation rules, API types. Editorial content changes at a different cadence and requires human judgment to update. Forcing this into annotations would produce worse documentation. Documents that transitioned to hybrid generation preserve their editorial voice via preamble while keeping reference content in sync with source annotations. | +| Manual docs retain editorial and tutorial content | Documents containing philosophy (METHODOLOGY.md) remain fully manual with no generated equivalent (~238 lines). Documents that were originally manual but now have generated equivalents or have been restructured (SESSION-GUIDES.md, GHERKIN-PATTERNS.md, CLI.md) retain their editorial content as preamble within generated outputs. PUBLISHING.md was relocated to MAINTAINERS.md at the repository root. | The consolidation targets sections most likely to drift when code changes: reference tables, codec listings, validation rules, API types. Editorial content changes at a different cadence and requires human judgment to update. Forcing this into annotations would produce worse documentation. Documents that transitioned to hybrid generation preserve their editorial voice via preamble while keeping reference content in sync with source annotations. | | Audience alignment determines document location | Each document lives in the location matching its primary audience: `docs/` (deployed to libar.dev) for content that serves package users and developers; repo root for GitHub-visible metadata (CONTRIBUTING.md, SECURITY.md, MAINTAINERS.md); CLAUDE.md for AI session context. A document appearing in docs/ must be useful to a developer or user visiting the website — maintainer-only operational procedures (npm publishing workflow, GitHub Actions setup) belong at the repo root. | The audit found PUBLISHING.md (maintainer-only) in docs/ alongside user-facing guides. SESSION-GUIDES.md (AI session procedures) duplicates CLAUDE.md with 95% overlap. Audience mismatches increase website noise for users and create drift risk when the same content lives in two locations. | ### Docs Live Consolidation diff --git a/docs-live/product-areas/VALIDATION.md b/docs-live/product-areas/VALIDATION.md index 51e7f4a6..be820f56 100644 --- a/docs-live/product-areas/VALIDATION.md +++ b/docs-live/product-areas/VALIDATION.md @@ -45,8 +45,8 @@ C4Context System(FSMTransitions, "FSMTransitions") System(FSMStates, "FSMStates") } - System_Ext(CodecUtils, "CodecUtils") System_Ext(DoDValidationTypes, "DoDValidationTypes") + System_Ext(CodecUtils, "CodecUtils") System_Ext(DualSourceExtractor, "DualSourceExtractor") System_Ext(DetectChanges, "DetectChanges") System_Ext(DeriveProcessState, "DeriveProcessState") @@ -95,8 +95,8 @@ graph LR FSMStates[/"FSMStates"/] end subgraph related["Related"] - CodecUtils["CodecUtils"]:::neighbor DoDValidationTypes["DoDValidationTypes"]:::neighbor + CodecUtils["CodecUtils"]:::neighbor DualSourceExtractor["DualSourceExtractor"]:::neighbor DetectChanges["DetectChanges"]:::neighbor DeriveProcessState["DeriveProcessState"]:::neighbor diff --git a/docs-live/reference/CLI-REFERENCE.md b/docs-live/reference/CLI-REFERENCE.md index 8b79d8f5..d09e1bf9 100644 --- a/docs-live/reference/CLI-REFERENCE.md +++ b/docs-live/reference/CLI-REFERENCE.md @@ -1,6 +1,6 @@ # Pattern Graph CLI Reference -> Auto-generated from CLI schema. See [Pattern Graph CLI Guide](../../docs/PROCESS-API.md) for usage examples and recipes. +> Auto-generated from CLI schema. See [CLI Recipes & Workflow Guide](../../docs-live/reference/CLI-RECIPES.md) for usage examples and recipes. ## Global Options diff --git a/docs-live/reference/REFERENCE-SAMPLE.md b/docs-live/reference/REFERENCE-SAMPLE.md index a54769bd..fb27dedf 100644 --- a/docs-live/reference/REFERENCE-SAMPLE.md +++ b/docs-live/reference/REFERENCE-SAMPLE.md @@ -420,15 +420,15 @@ graph LR CliReferenceGeneration["CliReferenceGeneration"]:::neighbor end loadPreambleFromMarkdown___Shared_Markdown_to_SectionBlock_Parser ..->|implements| ProceduralGuideCodec - TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation ProjectConfigTypes -->|uses| ConfigurationTypes ProjectConfigTypes -->|uses| ConfigurationPresets ConfigurationPresets -->|uses| ConfigurationTypes + CLISchema ..->|implements| CliReferenceGeneration PatternHelpers ..->|implements| DataAPIOutputShaping ArchQueriesImpl -->|uses| PatternGraphAPI ArchQueriesImpl -->|uses| PatternGraph ArchQueriesImpl ..->|implements| DataAPIArchitectureQueries - CLISchema ..->|implements| CliReferenceGeneration + TagRegistryBuilder ..->|implements| TypeScriptTaxonomyImplementation FSMTransitions ..->|implements| PhaseStateMachineValidation FSMStates ..->|implements| PhaseStateMachineValidation PatternGraphAPI -->|uses| PatternGraph @@ -585,6 +585,122 @@ Validation happens later at load time via Zod schema in `loadProjectConfig()`. - In `architect.config.ts` at project root to get type-safe configuration with autocompletion. +### ConfigBasedWorkflowDefinition + +[View ConfigBasedWorkflowDefinition source](architect/specs/config-based-workflow-definition.feature) + +**Problem:** +Every `pnpm architect:query` and `pnpm docs:*` invocation prints: +`Failed to load default workflow (6-phase-standard): Workflow file not found` + +The `loadDefaultWorkflow()` function resolves to `catalogue/workflows/` +which does not exist. The directory was deleted during monorepo extraction. +The system already degrades gracefully (workflow = undefined), but the +warning is noise for both human CLI use and future hook consumers (HUD). + +The old `6-phase-standard.json` conflated three concerns: + +- Taxonomy vocabulary (status names) — already in `src/taxonomy/` +- FSM behavior (transitions) — already in `src/validation/fsm/` +- Workflow structure (phases) — orphaned, no proper home + +**Solution:** +Inline the default workflow as a constant in `workflow-loader.ts`, built +from canonical taxonomy values. Make `loadDefaultWorkflow()` synchronous. +Preserve `loadWorkflowFromPath()` for custom `--workflow ` overrides. + +The workflow definition uses only the 4 canonical statuses from ADR-001 +(roadmap, active, completed, deferred) — not the stale 5-status set from +the deleted JSON (which included non-canonical `implemented` and `partial`). + +Phase definitions (Inception, Elaboration, Session, Construction, +Validation, Retrospective) move from a missing JSON file to an inline +constant, making the default workflow always available without file I/O. + +Design Decisions (DS-1, 2026-02-15): + +| ID | Decision | Rationale | +| DD-1 | Inline constant in workflow-loader.ts, not preset integration | Minimal correct fix, zero type regression risk. Preset integration deferred. | +| DD-2 | Constant satisfies existing WorkflowConfig type | Reuse createLoadedWorkflow() from workflow-config.ts. No new types needed. | +| DD-3 | Remove dead code: getCatalogueWorkflowsPath, loadWorkflowConfig, DEFAULT_WORKFLOW_NAME | Dead since monorepo extraction. Public API break is safe (function always threw). | +| DD-4 | loadDefaultWorkflow() returns LoadedWorkflow synchronously | Infallible constant needs no async or error handling. | +| DD-5 | Amend ADR-001 with canonical phase definitions | Phase names are canonical values; fits existing governance in ADR-001. | + +
+Default workflow is built from an inline constant (2 scenarios) + +#### Default workflow is built from an inline constant + +**Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. + +**Rationale:** The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. + +**Verified by:** + +- Default workflow loads without warning +- Workflow constant uses canonical statuses only +- Workflow constant uses canonical statuses only + + Implementation approach: + +
+ +
+Custom workflow files still work via --workflow flag (1 scenarios) + +#### Custom workflow files still work via --workflow flag + +**Invariant:** `loadWorkflowFromPath()` remains available for projects that need custom workflow definitions. The `--workflow ` CLI flag and `workflowPath` config field continue to work. + +**Rationale:** The inline default replaces file-based _default_ loading, not file-based _custom_ loading. Projects may define custom phases or additional statuses via JSON files. + +**Verified by:** + +- Custom workflow file overrides default + +
+ +
+FSM validation and Process Guard are not affected + +#### FSM validation and Process Guard are not affected + +**Invariant:** The FSM transition matrix, protection levels, and Process Guard rules remain hardcoded in `src/validation/fsm/` and `src/lint/process-guard/`. They do not read from `LoadedWorkflow`. + +**Rationale:** FSM and workflow are separate concerns. FSM enforces status transitions (4-state model from PDR-005). Workflow defines phase structure (6-phase USDP). The workflow JSON declared `transitionsTo` on its statuses, but no code ever read those values — the FSM uses its own `VALID_TRANSITIONS` constant. This separation is correct and intentional. Blast radius analysis confirmed zero workflow imports in: - src/validation/fsm/ (4 files) - src/lint/process-guard/ (5 files) - src/taxonomy/ (all files) + +
+ +
+Workflow as a configurable preset field is deferred + +#### Workflow as a configurable preset field is deferred + +**Invariant:** The inline default workflow constant is the only workflow source until preset integration is implemented. No preset or project config field exposes workflow customization. + +**Rationale:** Coupling workflow into the preset/config system before the inline fix ships would widen the blast radius and risk type regressions across all config consumers. + +**Verified by:** + +- N/A - deferred until preset integration + + Adding `workflow` as a field on `ArchitectConfig` (presets) and + `ArchitectProjectConfig` (project config) is a natural next step + but NOT required for the MVP fix. + + The inline constant in `workflow-loader.ts` resolves the warning. Moving + workflow into the preset/config system enables: + - Different presets with different default phases (e.g. + +- 3-phase libar-generic) + - Per-project phase customization in architect.config.ts + - Phase definitions appearing in generated documentation + + See ideation artifact for design options: + architect/ideations/2026-02-15-workflow-config-and-fsm-extensibility.feature + +
+ ### ADR005CodecBasedMarkdownRendering [View ADR005CodecBasedMarkdownRendering source](architect/decisions/adr-005-codec-based-markdown-rendering.feature) @@ -887,122 +1003,6 @@ These are the durable constants of the delivery process. -### ConfigBasedWorkflowDefinition - -[View ConfigBasedWorkflowDefinition source](architect/specs/config-based-workflow-definition.feature) - -**Problem:** -Every `pnpm architect:query` and `pnpm docs:*` invocation prints: -`Failed to load default workflow (6-phase-standard): Workflow file not found` - -The `loadDefaultWorkflow()` function resolves to `catalogue/workflows/` -which does not exist. The directory was deleted during monorepo extraction. -The system already degrades gracefully (workflow = undefined), but the -warning is noise for both human CLI use and future hook consumers (HUD). - -The old `6-phase-standard.json` conflated three concerns: - -- Taxonomy vocabulary (status names) — already in `src/taxonomy/` -- FSM behavior (transitions) — already in `src/validation/fsm/` -- Workflow structure (phases) — orphaned, no proper home - -**Solution:** -Inline the default workflow as a constant in `workflow-loader.ts`, built -from canonical taxonomy values. Make `loadDefaultWorkflow()` synchronous. -Preserve `loadWorkflowFromPath()` for custom `--workflow ` overrides. - -The workflow definition uses only the 4 canonical statuses from ADR-001 -(roadmap, active, completed, deferred) — not the stale 5-status set from -the deleted JSON (which included non-canonical `implemented` and `partial`). - -Phase definitions (Inception, Elaboration, Session, Construction, -Validation, Retrospective) move from a missing JSON file to an inline -constant, making the default workflow always available without file I/O. - -Design Decisions (DS-1, 2026-02-15): - -| ID | Decision | Rationale | -| DD-1 | Inline constant in workflow-loader.ts, not preset integration | Minimal correct fix, zero type regression risk. Preset integration deferred. | -| DD-2 | Constant satisfies existing WorkflowConfig type | Reuse createLoadedWorkflow() from workflow-config.ts. No new types needed. | -| DD-3 | Remove dead code: getCatalogueWorkflowsPath, loadWorkflowConfig, DEFAULT_WORKFLOW_NAME | Dead since monorepo extraction. Public API break is safe (function always threw). | -| DD-4 | loadDefaultWorkflow() returns LoadedWorkflow synchronously | Infallible constant needs no async or error handling. | -| DD-5 | Amend ADR-001 with canonical phase definitions | Phase names are canonical values; fits existing governance in ADR-001. | - -
-Default workflow is built from an inline constant (2 scenarios) - -#### Default workflow is built from an inline constant - -**Invariant:** `loadDefaultWorkflow()` returns a `LoadedWorkflow` without file system access. It cannot fail. The default workflow constant uses only canonical status values from `src/taxonomy/status-values.ts`. - -**Rationale:** The file-based loading path (`catalogue/workflows/`) has been dead code since monorepo extraction. Both callers (orchestrator, pattern-graph-cli) already handle the failure gracefully, proving the system works without it. Making the function synchronous and infallible removes the try-catch ceremony and the warning noise. - -**Verified by:** - -- Default workflow loads without warning -- Workflow constant uses canonical statuses only -- Workflow constant uses canonical statuses only - - Implementation approach: - -
- -
-Custom workflow files still work via --workflow flag (1 scenarios) - -#### Custom workflow files still work via --workflow flag - -**Invariant:** `loadWorkflowFromPath()` remains available for projects that need custom workflow definitions. The `--workflow ` CLI flag and `workflowPath` config field continue to work. - -**Rationale:** The inline default replaces file-based _default_ loading, not file-based _custom_ loading. Projects may define custom phases or additional statuses via JSON files. - -**Verified by:** - -- Custom workflow file overrides default - -
- -
-FSM validation and Process Guard are not affected - -#### FSM validation and Process Guard are not affected - -**Invariant:** The FSM transition matrix, protection levels, and Process Guard rules remain hardcoded in `src/validation/fsm/` and `src/lint/process-guard/`. They do not read from `LoadedWorkflow`. - -**Rationale:** FSM and workflow are separate concerns. FSM enforces status transitions (4-state model from PDR-005). Workflow defines phase structure (6-phase USDP). The workflow JSON declared `transitionsTo` on its statuses, but no code ever read those values — the FSM uses its own `VALID_TRANSITIONS` constant. This separation is correct and intentional. Blast radius analysis confirmed zero workflow imports in: - src/validation/fsm/ (4 files) - src/lint/process-guard/ (5 files) - src/taxonomy/ (all files) - -
- -
-Workflow as a configurable preset field is deferred - -#### Workflow as a configurable preset field is deferred - -**Invariant:** The inline default workflow constant is the only workflow source until preset integration is implemented. No preset or project config field exposes workflow customization. - -**Rationale:** Coupling workflow into the preset/config system before the inline fix ships would widen the blast radius and risk type regressions across all config consumers. - -**Verified by:** - -- N/A - deferred until preset integration - - Adding `workflow` as a field on `ArchitectConfig` (presets) and - `ArchitectProjectConfig` (project config) is a natural next step - but NOT required for the MVP fix. - - The inline constant in `workflow-loader.ts` resolves the warning. Moving - workflow into the preset/config system enables: - - Different presets with different default phases (e.g. - -- 3-phase libar-generic) - - Per-project phase customization in architect.config.ts - - Phase definitions appearing in generated documentation - - See ideation artifact for design options: - architect/ideations/2026-02-15-workflow-config-and-fsm-extensibility.feature - -
- ### ProcessGuardTesting [View ProcessGuardTesting source](tests/features/validation/process-guard.feature) diff --git a/docs/PROCESS-API.md b/docs/CLI.md similarity index 100% rename from docs/PROCESS-API.md rename to docs/CLI.md diff --git a/docs/DOCS-GAP-ANALYSIS.md b/docs/DOCS-GAP-ANALYSIS.md index 303b6295..d6e95f1c 100644 --- a/docs/DOCS-GAP-ANALYSIS.md +++ b/docs/DOCS-GAP-ANALYSIS.md @@ -74,22 +74,22 @@ generated equivalents. Work packages in this gap analysis should map to its phas **Deliverable Status (from spec Background):** -| Deliverable | Status | Phase | Maps to WP | -| ------------------------------------------- | -------- | ----- | ----------------------------------------------- | -| Preamble capability on ReferenceDocConfig | complete | -- | N/A (done) | -| Phase 1 - Taxonomy consolidation | pending | 35 | Taxonomy deprecation | -| Phase 2 - Codec listings extraction | complete | 35 | N/A (done) | -| Phase 3 - Process Guard consolidation | pending | 35 | WP-5 | -| Phase 4 - Architecture decomposition | complete | 35 | N/A (done) | -| Phase 5 - Guide trimming | pending | 35 | WP-9 | -| Phase 6 - Index navigation update | pending | 35 | WP-2 | -| Phase 37 - docs-live/ consolidation | complete | 37 | N/A (done, commit 223ace6) | -| Phase 38 - Generated doc quality | pending | 38 | WP-9 | -| Phase 39 - Session workflow module gen | pending | 39 | Blocked on Phase 25 | -| Phase 40 - PUBLISHING.md relocation | complete | 40 | N/A (done) | -| Phase 41 - GHERKIN-PATTERNS.md restructure | pending | 41 | WP-7 | -| Phase 42 - README.md rationalization | pending | 42 | Not in this analysis | -| Phase 43 - PROCESS-API.md hybrid generation | complete | 43 | N/A (done); WP-6 extends with recipe generation | +| Deliverable | Status | Phase | Maps to WP | +| ------------------------------------------ | -------- | ----- | ----------------------------------------------- | +| Preamble capability on ReferenceDocConfig | complete | -- | N/A (done) | +| Phase 1 - Taxonomy consolidation | pending | 35 | Taxonomy deprecation | +| Phase 2 - Codec listings extraction | complete | 35 | N/A (done) | +| Phase 3 - Process Guard consolidation | pending | 35 | WP-5 | +| Phase 4 - Architecture decomposition | complete | 35 | N/A (done) | +| Phase 5 - Guide trimming | pending | 35 | WP-9 | +| Phase 6 - Index navigation update | pending | 35 | WP-2 | +| Phase 37 - docs-live/ consolidation | complete | 37 | N/A (done, commit 223ace6) | +| Phase 38 - Generated doc quality | pending | 38 | WP-9 | +| Phase 39 - Session workflow module gen | pending | 39 | Blocked on Phase 25 | +| Phase 40 - PUBLISHING.md relocation | complete | 40 | N/A (done) | +| Phase 41 - GHERKIN-PATTERNS.md restructure | pending | 41 | WP-7 | +| Phase 42 - README.md rationalization | pending | 42 | Not in this analysis | +| Phase 43 - CLI.md hybrid generation | complete | 43 | N/A (done); WP-6 extends with recipe generation | **Key Invariants from Spec:** @@ -334,7 +334,7 @@ These `docs-live/` subdirectories exist but have no sync function: | **ARCHITECTURE.md** | 1,638 | docs-live/product-areas/GENERATION.md (1,065 lines) + docs-live/reference/ARCHITECTURE-CODECS.md (630 lines) + docs-live/reference/ARCHITECTURE-TYPES.md (429 lines) | Partial | Generated covers pipeline stages and codec listings well. Missing: executive summary, data flow diagrams, workflow integration section, "Extending the System" guide, programmatic usage examples, quick reference card. | | **GHERKIN-PATTERNS.md** | 366 | None | None | Authoring style guide: 4 essential patterns, DataTable/DocString usage, tag conventions, feature file rich content rules, step linting reference. Pure editorial guidance -- no annotation source exists. | | **ANNOTATION-GUIDE.md** | 270 | docs-live/taxonomy/metadata-tags.md (649 lines) | Partial | Generated has exhaustive tag reference (56 tags). Missing: getting-started guide, shape extraction modes explanation, "Zod schema gotcha" documentation, verification steps, common issues troubleshooting table. | -| **PROCESS-API.md** | ~60 | docs-live/reference/CLI-REFERENCE.md + CLI-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | +| **CLI.md** | ~60 | docs-live/reference/CLI-REFERENCE.md + CLI-RECIPES.md | **Replaced** | Trimmed to pointer file with operational reference (JSON envelope, exit codes, piping). All prose content now generated by CliRecipeCodec (WP-6 complete). | | **PROCESS-GUARD.md** | 341 | docs-live/validation/error-catalog.md (79 lines) + docs-live/validation/fsm-transitions.md (49 lines) + docs-live/validation/protection-levels.md | Partial | Generated has error types, FSM matrix, protection levels. Missing: error fix rationale ("why this rule exists"), escape hatch alternatives, pre-commit setup instructions (Husky), programmatic API guide, Decider pattern architecture diagram. | | **VALIDATION.md** | 418 | docs-live/product-areas/VALIDATION.md (1,115 lines) | Partial | Generated has pattern listings and business rules. Missing: "Which command do I run?" decision tree, 32+ individual lint rule explanations with code examples, anti-pattern detection rationale, CI/CD integration patterns (GitHub Actions YAML), vitest-cucumber two-pattern problem explanation. | | **TAXONOMY.md** | 107 | docs-live/TAXONOMY.md (199 lines) + docs-live/taxonomy/ (3 files) | Good | Generated taxonomy reference is actually more comprehensive than manual. Manual adds: architecture explanation (file structure of src/taxonomy/), preset-to-taxonomy mapping, generation commands. Small gap. | @@ -561,7 +561,7 @@ This replaces the manual PROCESS-GUARD.md "Error Messages and Fixes" section. **Effort:** Medium (2-3 sessions) **Spec alignment:** Extends CliReferenceGeneration (Phase 43, completed). Phase 43 generated reference tables from CLI schema; this adds recipe/guide content. The manual -PROCESS-API.md prose was explicitly kept in Phase 43 -- this WP addresses that remainder. +CLI.md prose was explicitly kept in Phase 43 -- this WP addresses that remainder. Create a codec that generates CLI recipe guides from: @@ -569,7 +569,7 @@ Create a codec that generates CLI recipe guides from: - New `**Recipe:**` annotation in feature files - Session type metadata -This replaces manual PROCESS-API.md "Common Recipes" and "Session Workflow Commands". +This replaces manual CLI.md "Common Recipes" and "Session Workflow Commands". **Design questions for session:** @@ -692,7 +692,7 @@ All other work packages are complete. | TAXONOMY.md | Now (generated version is better) | WP-1 (sync fix) | | ARCHITECTURE.md | WP-3 + WP-9 | Architecture generator + quality polish | | PROCESS-GUARD.md | WP-5 | Error guide codec | -| PROCESS-API.md | Done (WP-6 complete) | Trimmed to pointer file | +| CLI.md | Done (WP-6 complete) | Trimmed to pointer file | | ANNOTATION-GUIDE.md | WP-7 (partial) | Guide codec with getting-started | | VALIDATION.md | WP-5 + WP-7 | Error guide + procedural guides | | SESSION-GUIDES.md | WP-7 | Procedural guide codec | @@ -761,7 +761,7 @@ pending until generated docs reach quality parity for manual doc archival. Phase | CONFIGURATION.md | 357 | Partial (options auto, rationale manual) | | GHERKIN-PATTERNS.md | 366 | Low (style guide is editorial) | | METHODOLOGY.md | 238 | None (philosophy) | -| PROCESS-API.md | ~60 | Complete (pointer file + generated recipes) | +| CLI.md | ~60 | Complete (pointer file + generated recipes) | | PROCESS-GUARD.md | 341 | Partial (rules auto, fix guides manual) | | SESSION-GUIDES.md | 389 | Low (checklists are procedural) | | TAXONOMY.md | 107 | High (generated version is better) | diff --git a/docs/INDEX.md b/docs/INDEX.md index 22806842..7438327e 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -29,7 +29,7 @@ | Write Gherkin specs | [GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md) | 1-515 | | Enforce process rules | [PROCESS-GUARD.md](./PROCESS-GUARD.md) | 1-341 | | Validate annotation quality | [VALIDATION.md](./VALIDATION.md) | 1-281 | -| Query process state via CLI | [PROCESS-API.md](./PROCESS-API.md) | 1-507 | +| Query pattern graph via CLI | [CLI.md](./CLI.md) | 1-507 | | Understand the taxonomy | [TAXONOMY.md](./TAXONOMY.md) | 1-105 | | Publish to npm | [MAINTAINERS.md](../MAINTAINERS.md) | — | | Learn annotation patterns | [ANNOTATION-GUIDE.md](./ANNOTATION-GUIDE.md) | 1-268 | @@ -49,7 +49,7 @@ ### For Developers / AI 4. **[ARCHITECTURE.md](./ARCHITECTURE.md)** — Four-stage pipeline, codecs, PatternGraph -5. **[PROCESS-API.md](./PROCESS-API.md)** — Data API CLI query interface +5. **[CLI.md](./CLI.md)** — Data API CLI query interface 6. **[SESSION-GUIDES.md](./SESSION-GUIDES.md)** — Planning/Design/Implementation workflows 7. **[GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md)** — Writing effective Gherkin specs 8. **[ANNOTATION-GUIDE.md](./ANNOTATION-GUIDE.md)** — Annotation mechanics, shape extraction, tag quick reference @@ -194,7 +194,7 @@ --- -### PROCESS-API.md (Lines 1-507) +### CLI.md (Lines 1-507) | Section | Lines | Key Topics | | ------------------------- | ------- | ----------------------------------------------------------- | @@ -301,7 +301,7 @@ deferred ──→ roadmap The CLI is the **recommended way** to gather context in any session type. It queries annotated sources in real time — not generated snapshots. -See [PROCESS-API.md](./PROCESS-API.md). +See [CLI.md](./CLI.md). ```bash pnpm architect:query -- scope-validate MyPattern implement # ALWAYS run first @@ -320,7 +320,7 @@ pnpm architect:query -- handoff --pattern MyPattern # Capture sessi | METHODOLOGY.md | Everyone | Why — core thesis, principles | | CONFIGURATION.md | Users | Setup — presets, tags, config | | ARCHITECTURE.md | Developers | How — pipeline, codecs, schemas | -| PROCESS-API.md | AI/Devs | Data API CLI query interface | +| CLI.md | AI/Devs | Data API CLI query interface | | SESSION-GUIDES.md | AI/Devs | Workflow — day-to-day usage | | GHERKIN-PATTERNS.md | Writers | Specs — writing effective Gherkin | | PROCESS-GUARD.md | Team Leads | Governance — enforcement rules | diff --git a/docs/SESSION-GUIDES.md b/docs/SESSION-GUIDES.md index 5ee651e5..e8953e14 100644 --- a/docs/SESSION-GUIDES.md +++ b/docs/SESSION-GUIDES.md @@ -104,7 +104,7 @@ pnpm architect:query -- dep-tree # Dependency cha pnpm architect:query -- stubs # Existing design stubs ``` -Use these **before** launching explore agents. See [PROCESS-API.md](./PROCESS-API.md). +Use these **before** launching explore agents. See [CLI.md](./CLI.md). ### When Required @@ -181,7 +181,7 @@ pnpm architect:query -- files --related The `scope-validate` command replaces the manual pre-flight checklist — it checks dependency completion, deliverable definitions, FSM validity, and design decisions. -See [PROCESS-API.md](./PROCESS-API.md#scope-validate). +See [CLI.md](./CLI.md#scope-validate). ### Execution Checklist @@ -387,5 +387,5 @@ Valid transitions: See [METHODOLOGY.md#fsm-enforced-workflow](./METHODOLOGY.md#f | [GHERKIN-PATTERNS.md](./GHERKIN-PATTERNS.md) | DataTables, DocStrings, Rule blocks | | [CONFIGURATION.md](./CONFIGURATION.md) | Tag prefixes, presets | | [TAXONOMY.md](./TAXONOMY.md) | Tag taxonomy concepts and API | -| [PROCESS-API.md](./PROCESS-API.md) | Data API CLI commands for all session types | +| [CLI.md](./CLI.md) | Data API CLI commands for all session types | | [VALIDATION.md](./VALIDATION.md) | CLI flags for lint-patterns and validate-patterns | diff --git a/src/cli/cli-schema.ts b/src/cli/cli-schema.ts index dbed7f56..3cb6d269 100644 --- a/src/cli/cli-schema.ts +++ b/src/cli/cli-schema.ts @@ -226,7 +226,7 @@ export const CLI_SCHEMA: CLISchema = { }, // =========================================================================== - // Command Narratives (from docs/PROCESS-API.md) + // Command Narratives (originally transcribed from docs/CLI.md) // =========================================================================== commandNarratives: [ @@ -512,7 +512,7 @@ export const CLI_SCHEMA: CLISchema = { ], // =========================================================================== - // Recipes (from docs/PROCESS-API.md "Common Recipes" section) + // Recipes (originally transcribed from docs/CLI.md "Common Recipes" section) // =========================================================================== recipes: [ diff --git a/src/generators/built-in/cli-reference-generator.ts b/src/generators/built-in/cli-reference-generator.ts index aa815c57..a43da51c 100644 --- a/src/generators/built-in/cli-reference-generator.ts +++ b/src/generators/built-in/cli-reference-generator.ts @@ -54,7 +54,7 @@ function buildReferenceDocument(): string { sections.push( paragraph( - '> Auto-generated from CLI schema. See [Pattern Graph CLI Guide](../../docs/PROCESS-API.md) for usage examples and recipes.' + '> Auto-generated from CLI schema. See [CLI Recipes & Workflow Guide](../../docs-live/reference/CLI-RECIPES.md) for usage examples and recipes.' ) );