@libar-dev/architect 1.0.0-pre.3

package/docs-live/CHANGELOG-GENERATED.md

@@ -0,0 +1,375 @@
+# Changelog
+
+**Purpose:** Project changelog in Keep a Changelog format
+
+---
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+### 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 MasterDataset 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.
+- **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.
+- **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.
+- **Pattern Helpers**: Common helper functions used by context-assembler, arch-queries, and other API modules that need pattern name...
+- **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.
+- **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.
+- **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.
+- **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,...
+- **Composite Codec**: :Generation Assembles reference documents from multiple codec outputs by concatenating RenderableDocument sections.
+- **Claude Module Codec**: :Generation Transforms MasterDataset 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.
+- **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 ProcessStateAPI 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...
+- **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...
+- **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.
+- **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...
+- **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**
+
+---
+
+## [v1.0.0]
+
+### Added
+
+- **TypeScript Taxonomy Implementation**: As an Architect developer I want taxonomy defined in TypeScript with Zod integration So that I get compile-time...
+- **Process Guard Linter**: During planning and implementation sessions, accidental modifications occur: - Specs outside the intended scope get...
+- **Phase State Machine Validation**: Phase lifecycle state transitions are not enforced programmatically despite being documented in PROCESS_SETUP.md.
+- **Pattern Relationship Model**: Problem: The delivery process lacks a comprehensive relationship model between artifacts.
+- **Mvp Workflow Implementation**: PDR-005 defines a 4-state workflow FSM (`roadmap, active, completed, deferred`) but the Architect package validation...
+- **Gherkin Rules Support**: Feature files were limited to flat scenario lists.
+
+---
+
+## [Earlier]
+
+### Added
+
+- **Public API**: Main entry point for the @libar-dev/architect package.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+- **Configuration Presets**: Predefined configuration presets for common use cases.
+- **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.
+- **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.
+- **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.
+- **MCPToolRegistry — Tool Definitions with Zod Schemas**: Defines 25 MCP tools mapping to ProcessStateAPI 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.
+- **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).
+- **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 MasterDataset 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.
+- **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.
+- **Reporting Codecs**: :Generation Purpose: Keep a Changelog format changelog grouped by release version.
+- **Pr Changes Codec**: :Generation Transforms MasterDataset 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.
+- **Document Codecs**: Barrel export for all document codecs.
+- **Index Codec**: :Generation Purpose: Navigation hub composing editorial preamble with MasterDataset 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.
+- **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...
+- **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**: 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 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.
+- **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...
+- **Shape Extraction**: Documentation comments duplicate type definitions that exist in the same file.
+- **Session Guides Module Source**: CLAUDE.md contains a "Session Workflows" section (~160 lines) that is hand-maintained with no link to any annotated...
+- **Scoped Architectural View**: Full architecture diagrams show every annotated pattern in the project.
+- **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...
+- **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)...
+- **Error Guide Codec**: `docs/PROCESS-GUARD.md` (341 lines) is manually maintained with per-error-code diagnosis guides, escape hatch...
+- **Enhanced Index Generation**: `docs/INDEX.md` (354 lines) is a manually maintained navigation hub with audience-based reading orders, per-document...
+- **Docs Live Consolidation**: `docs-generated/` mixes production reference documents (ARCHITECTURE-CODECS.md, ARCHITECTURE-TYPES.md at 19 KB and 14...
+- **Docs Consolidation Strategy**: 14 manually-maintained docs (~5,400 lines in `docs/`) duplicate information that already exists in annotated source...
+- **Doc Generation Proof Of Concept**: Status: SUPERSEDED - This POC has been implemented.
+- **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 Output Shaping**: The ProcessStateAPI 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...
+- **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)...
+- **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.
+- **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.
+- **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...
+- **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...
+- **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...
+- **Claude Metadata Parity Testing**: The extractor must preserve Claude routing metadata from TypeScript directives and keep the sync and async Gherkin...
+- **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...
+- **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...
+- **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.
+- **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.
+- **Transform Dataset Testing**: The transformToMasterDataset function transforms raw extracted patterns into a MasterDataset 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...
+- **Rich Content Helpers Testing**: As a document codec author I need helpers to render Gherkin rich content So that DataTables, DocStrings, and...
+- **Renderer Output Formats**: The universal renderer converts RenderableDocument to markdown.
+- **Renderer Block Types**: The universal renderer converts RenderableDocument to markdown.
+- **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...
+- **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...
+- **Implementation Link Path Normalization**: Links to implementation files in generated pattern documents should have correct relative paths.
+- **Extract Summary**: The extractSummary function transforms multi-line pattern descriptions into concise, single-line summaries suitable...
+- **Error Handling Unification**: All CLI commands and extractors should use the DocError discriminated union pattern for consistent, structured error...
+- **Directive Detection**: Pure functions that detect @architect directives in TypeScript source code.
+- **Description Quality Foundation**: Enhanced documentation generation with human-readable names, behavior file verification, and numbered acceptance...
+- **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...
+- **Process State API Testing**: Programmatic interface for querying 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...
+- **Timeline Codec Testing**: The timeline codecs (RoadmapDocumentCodec, CompletedMilestonesCodec, CurrentWorkCodec) transform MasterDataset 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...
+- **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...
+- **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.
+- **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...
+- **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.
+
+---

package/docs-live/DECISIONS.md

@@ -0,0 +1,78 @@
+# Architecture Decision Records
+
+**Purpose:** Architectural decisions extracted from feature files
+**Detail Level:** Summary with links to category details
+
+---
+
+## Summary
+
+| Metric     | Value |
+| ---------- | ----- |
+| Total ADRs | 7     |
+| Accepted   | 5     |
+| Proposed   | 0     |
+| Deprecated | 0     |
+| Superseded | 1     |
+| Categories | 4     |
+
+---
+
+## By Category
+
+### architecture
+
+3 decisions
+
+| ADR                                                            | Title                                  | Status   |
+| -------------------------------------------------------------- | -------------------------------------- | -------- |
+| [ADR-004](decisions/adr-004-session-workflow-commands.md)      | PDR 001 Session Workflow Commands      | accepted |
+| [ADR-005](decisions/adr-005-codec-based-markdown-rendering.md) | ADR 005 Codec Based Markdown Rendering | accepted |
+| [ADR-006](decisions/adr-006-single-read-model-architecture.md) | ADR 006 Single Read Model Architecture | proposed |
+
+---
+
+### documentation
+
+1 decisions
+
+| ADR                                                             | Title                           | Status     |
+| --------------------------------------------------------------- | ------------------------------- | ---------- |
+| [ADR-021](decisions/adr-021-doc-generation-proof-of-concept.md) | Doc Generation Proof Of Concept | superseded |
+
+---
+
+### process
+
+2 decisions
+
+| ADR                                                               | Title                                     | Status   |
+| ----------------------------------------------------------------- | ----------------------------------------- | -------- |
+| [ADR-001](decisions/adr-001-taxonomy-canonical-values.md)         | ADR 001 Taxonomy Canonical Values         | accepted |
+| [ADR-003](decisions/adr-003-source-first-pattern-architecture.md) | ADR 003 Source First Pattern Architecture | accepted |
+
+---
+
+### testing
+
+1 decisions
+
+| ADR                                                  | Title                        | Status   |
+| ---------------------------------------------------- | ---------------------------- | -------- |
+| [ADR-002](decisions/adr-002-gherkin-only-testing.md) | ADR 002 Gherkin Only Testing | accepted |
+
+---
+
+## ADR Index
+
+| ADR                                                               | Title                                     | Status     | Category      |
+| ----------------------------------------------------------------- | ----------------------------------------- | ---------- | ------------- |
+| [ADR-001](decisions/adr-001-taxonomy-canonical-values.md)         | ADR 001 Taxonomy Canonical Values         | accepted   | process       |
+| [ADR-002](decisions/adr-002-gherkin-only-testing.md)              | ADR 002 Gherkin Only Testing              | accepted   | testing       |
+| [ADR-003](decisions/adr-003-source-first-pattern-architecture.md) | ADR 003 Source First Pattern Architecture | accepted   | process       |
+| [ADR-004](decisions/adr-004-session-workflow-commands.md)         | PDR 001 Session Workflow Commands         | accepted   | architecture  |
+| [ADR-005](decisions/adr-005-codec-based-markdown-rendering.md)    | ADR 005 Codec Based Markdown Rendering    | accepted   | architecture  |
+| [ADR-006](decisions/adr-006-single-read-model-architecture.md)    | ADR 006 Single Read Model Architecture    | proposed   | architecture  |
+| [ADR-021](decisions/adr-021-doc-generation-proof-of-concept.md)   | Doc Generation Proof Of Concept           | superseded | documentation |
+
+---