feat: consolidate documentation — 5 new codecs, 900+ manual lines replaced by auto-generation

.claude/settings.json

@@ -1,4 +1,5 @@
 {
+  "plansDirectory": "./.plans",
   "attribution": {
     "commit": "",
     "pr": ""

.gitignore

@@ -5,6 +5,9 @@ node_modules/
 dist/
 *.tsbuildinfo
 
+# Generated intermediate artifacts (not website-published)
+docs-generated/
+
 # IDE
 .idea/
 .vscode/
@@ -36,3 +39,4 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
+.plans/

.husky/pre-push

@@ -1,5 +1,8 @@
 set -e
 
+echo "Running format check..."
+pnpm format:check
+
 echo "Running tests..."
 pnpm test
 

docs/PUBLISHING.md → MAINTAINERS.md

@@ -1,4 +1,4 @@
-# Publishing Guide
+# Maintainer Guide
 
 This guide covers how to publish `@libar-dev/delivery-process` to npm.
 

_claude-md/CLAUDE-MODULES.md

@@ -0,0 +1,9 @@
+### Claude Modules
+
+#### Generated Modules
+
+1 module(s) generated from annotated behavior specs.
+
+| Module | Section | Source Pattern | Content |
+| --- | --- | --- | --- |
+| session-workflows | workflow | SessionGuidesModuleSource | 9 rules |

_claude-md/api/data-api-cli.md

@@ -4,54 +4,7 @@ Query delivery process state directly from the terminal. **Use this instead of r
 
 **Run `pnpm process:query -- --help` for the full command reference**, including workflow recipes, session types, architecture queries, output modifiers, and available API methods.
 
-#### Session Start Recipe
-
-1. `pnpm process:query -- overview` — project health (progress, active phases, blockers)
-2. `pnpm process:query -- scope-validate <pattern> <session-type>` — pre-flight check (FSM, deps, prereqs)
-3. `pnpm process:query -- context <pattern> --session <type>` — curated context bundle
-
-Session types: `planning` (minimal), `design` (full: stubs + deps + deliverables), `implement` (focused: deliverables + FSM + tests).
-
-#### Key Commands
-
-| Command                 | When to Use                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------- |
-| `scope-validate`        | **Highest impact** — prevents wasted sessions by catching violations before you start |
-| `context --session`     | Primary context gathering — replaces manual file reads                                |
-| `dep-tree <pattern>`    | Understand dependency chains before implementation                                    |
-| `list --status roadmap` | Find available patterns to work on                                                    |
-| `arch blocking`         | Find patterns stuck on incomplete dependencies                                        |
-| `stubs --unresolved`    | Find design stubs missing implementations                                             |
-| `rules`                 | Business rules and invariants from Gherkin `Rule:` blocks                             |
-| `files <pattern>`       | File reading list with implementation paths — replaces manual path discovery          |
-| `decisions <pattern>`   | Design decisions (AD-N) from stub descriptions                                        |
-| `pdr <number>`          | Cross-reference patterns mentioning a PDR number                                      |
-| `handoff --pattern`     | Capture session-end state for multi-session work                                      |
-
-#### Annotation Exploration
-
-Run these **before** making annotation changes — they prevent debugging cycles:
-
-| Command                    | When to Use                                                                   |
-| -------------------------- | ----------------------------------------------------------------------------- |
-| `unannotated --path <dir>` | Find TS files missing `@libar-docs` — **run first** in any enrichment session |
-| `tags`                     | Tag usage inventory (counts per tag and value)                                |
-| `sources`                  | File inventory by type (TS, Gherkin, Stubs)                                   |
-| `query getPattern <name>`  | Full pattern JSON including `extractedShapes` and `productArea`               |
-
-**Lesson learned:** `unannotated --path src/types` would have immediately caught missing `@libar-docs` annotations on `result.ts` and `errors.ts` — saving ~30 minutes of debugging why shapes weren't appearing in generated docs.
-
-#### Architecture Queries
-
-Query architectural structure directly — avoids explore agents for structural questions:
-
-| Command               | When to Use                                          |
-| --------------------- | ---------------------------------------------------- |
-| `arch coverage`       | Annotation completeness across the project           |
-| `arch context [name]` | Patterns in bounded context (list all if no name)    |
-| `arch layer [name]`   | Patterns in architecture layer (list all if no name) |
-| `arch dangling`       | Broken references — pattern names that don't resolve |
-| `arch orphans`        | Isolated patterns with no relationships              |
+See the **Context Gathering Protocol** section above for mandatory session start commands and query recipes.
 
 #### Tips
 

_claude-md/authoring/feature-content.md

@@ -20,59 +20,6 @@ Rule: Reservations use atomic claim
 
 Code stubs live in `delivery-process/stubs/{pattern-name}/` — annotated TypeScript with `throw new Error("not yet implemented")`.
 
-#### Rule Block Structure (Mandatory)
-
-Every feature file MUST use `Rule:` blocks with structured descriptions:
-
-```gherkin
-Rule: Reservations prevent race conditions
-
-  **Invariant:** Only one reservation can exist for a given key at a time.
-
-  **Rationale:** Check-then-create patterns have TOCTOU vulnerabilities.
-
-  **Verified by:** Concurrent reservations, Expired reservation cleanup
-
-  @acceptance-criteria @happy-path
-  Scenario: Concurrent reservations
-    ...
-```
-
-| Element            | Purpose                                 | Extracted By             |
-| ------------------ | --------------------------------------- | ------------------------ |
-| `**Invariant:**`   | Business constraint (what must be true) | Business Rules generator |
-| `**Rationale:**`   | Business justification (why it exists)  | Business Rules generator |
-| `**Verified by:**` | Comma-separated scenario names          | Traceability generator   |
-
-#### Feature Description Structure
-
-Choose headers that fit your pattern (flexible, not rigid):
-
-| Structure        | Headers                                    | Best For                  |
-| ---------------- | ------------------------------------------ | ------------------------- |
-| Problem/Solution | `**Problem:**`, `**Solution:**`            | Pain point to fix         |
-| Value-First      | `**Business Value:**`, `**How It Works:**` | TDD-style, Gherkin spirit |
-| Context/Approach | `**Context:**`, `**Approach:**`            | Technical patterns        |
-
-Always include a benefits table:
-
-```gherkin
-**Business Value:**
-| Benefit | Impact |
-| ... | ... |
-```
-
-#### Valid Rich Content
-
-| Content Type  | Syntax                  | Appears in Docs  |
-| ------------- | ----------------------- | ---------------- |
-| Plain text    | Regular paragraphs      | Yes              |
-| Bold/emphasis | `**bold**`, `*italic*`  | Yes              |
-| Tables        | Markdown pipe tables    | Yes              |
-| Lists         | `- item` or `1. item`   | Yes              |
-| DocStrings    | `"""typescript`...`"""` | Yes (code block) |
-| Comments      | `# comment`             | No (ignored)     |
-
 #### Forbidden in Feature Descriptions
 
 | Forbidden           | Why                             | Alternative                      |
@@ -82,41 +29,6 @@ Always include a benefits table:
 | Nested DocStrings   | Gherkin parser error            | Reference code stub file         |
 | `#` at line start   | Gherkin comment — kills parsing | Remove, use `//`, or step DocStr |
 
-#### Description `"""` Blocks vs Step DocStrings (CRITICAL)
-
-**`"""` inside Feature/Rule descriptions is plain text, NOT a DocString.** Only `"""` as step arguments (Given/When/Then) creates real DocStrings. This means description content between `"""` is subject to Gherkin parser rules — including `#` = comment.
-
-**Symptom:** `expected: #EOF, #BackgroundLine... got 'some-content'`
-
-```gherkin
-Rule: My Rule
-
-    """bash
-    # This breaks! Parser sees Gherkin comment, terminates description
-    generate-docs --output docs
-    """
-```
-
-**Workarounds:**
-
-| Approach                    | When to Use                        |
-| --------------------------- | ---------------------------------- |
-| Remove `#` lines            | Simple cases                       |
-| Use `//` for comments       | When comment syntax doesn't matter |
-| Move to step DocString      | When you need code with `#`        |
-| Reference stub file instead | Complex examples (preferred)       |
-
-**Safe pattern — step DocString (content is real DocString, `#` is safe):**
-
-```gherkin
-  Scenario: Example usage
-    Given the following script:
-      """bash
-      # This is safe — real DocString, not description text
-      generate-docs --output docs
-      """
-```
-
 #### Tag Value Constraints
 
 **Tag values cannot contain spaces.** Use hyphens instead:

_claude-md/authoring/gherkin-patterns.md

@@ -29,16 +29,7 @@ Feature: Process Guard Linter
 | Value-First      | `**Business Value:**`, `**How It Works:**` | TDD-style specs    |
 | Context/Approach | `**Context:**`, `**Approach:**`            | Technical patterns |
 
-#### Tag Conventions
-
-| Tag                    | Purpose                     |
-| ---------------------- | --------------------------- |
-| `@happy-path`          | Primary success scenario    |
-| `@edge-case`           | Boundary conditions         |
-| `@error-handling`      | Error recovery scenarios    |
-| `@validation`          | Input validation rules      |
-| `@acceptance-criteria` | Required for DoD validation |
-| `@integration`         | Cross-component behavior    |
+Tag inventory: `pnpm process:query -- tags` (counts per tag and value across all sources).
 
 #### Rule Block Structure (Mandatory)
 

_claude-md/core/architecture.md

@@ -19,28 +19,19 @@ CONFIG → SCANNER → EXTRACTOR → TRANSFORMER → CODEC
 - **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.
 
-### Module Structure
-
-| Module                     | Purpose                                                              |
-| -------------------------- | -------------------------------------------------------------------- |
-| `src/config/`              | Configuration factory, presets (generic, ddd-es-cqrs)                |
-| `src/taxonomy/`            | Tag definitions - categories, status values, format types            |
-| `src/scanner/`             | TypeScript and Gherkin file scanning                                 |
-| `src/extractor/`           | Pattern extraction from AST/Gherkin                                  |
-| `src/generators/`          | Document generators, orchestrator, and pipeline factory              |
-| `src/generators/pipeline/` | `buildMasterDataset()` factory, `mergePatterns()`, dataset transform |
-| `src/renderable/`          | Markdown codec system                                                |
-| `src/validation/`          | FSM validation, DoD checks, anti-patterns                            |
-| `src/lint/`                | Pattern linting and process guard                                    |
-| `src/api/`                 | Query layer: Data API CLI, business rules query (`rules-query.ts`)   |
-| `delivery-process/stubs/`  | Design session code stubs (outside src/ for TS/ESLint isolation)     |
-
-**Live inventory:** `pnpm process:query -- arch context` and `pnpm process:query -- arch layer` reflect the actual annotated codebase structure.
-
-### Three Presets
-
-| Preset                    | Tag Prefix     | Categories | Use Case                           |
-| ------------------------- | -------------- | ---------- | ---------------------------------- |
-| `libar-generic` (default) | `@libar-docs-` | 3          | Simple projects (this package)     |
-| `ddd-es-cqrs`             | `@libar-docs-` | 21         | DDD/Event Sourcing architectures   |
-| `generic`                 | `@docs-`       | 3          | Simple projects with @docs- prefix |
+**Live module inventory:** `pnpm process:query -- arch context` and `pnpm process:query -- arch layer`
+
+### Decision Specs
+
+Architecture and process decisions are recorded as annotated Gherkin specs in `delivery-process/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          |
+
+Query decisions: `pnpm process:query -- decisions <pattern>`

_claude-md/core/common-commands.md

@@ -13,18 +13,12 @@ pnpm test <pattern>     # Run tests matching pattern (e.g., pnpm test scanner)
 # Linting
 pnpm lint               # ESLint on src and tests
 pnpm lint:fix           # Auto-fix lint issues
-pnpm lint-patterns      # Lint pattern annotations in src/**/*.ts
 
-# Validation
-pnpm validate:patterns  # Cross-source pattern validation
-pnpm validate:dod       # Definition of Done validation
-pnpm validate:all       # All validations including anti-patterns
+# Validation + Documentation
+pnpm validate:all       # All validations including anti-patterns and DoD
+pnpm docs:all           # Generate all doc types
 
-# Documentation generation
-pnpm docs:patterns      # Generate pattern docs
-pnpm docs:all           # Generate all doc types (patterns, roadmap, remaining, changelog)
-
-# Data API (see "Data API CLI" section for full reference)
+# Data API (see Context Gathering Protocol above)
 pnpm process:query -- --help                              # All subcommands and options
 pnpm process:query -- context <pattern> --session design  # Session context bundle
 pnpm process:query -- overview                            # Project health summary

_claude-md/core/context-protocol.md

@@ -0,0 +1,40 @@
+### Context Gathering Protocol (MANDATORY)
+
+**Rule: Always query the Process 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.
+
+#### PR / Session Start (run these FIRST)
+
+| Step | Command                                                    | What You Get                                |
+| ---- | ---------------------------------------------------------- | ------------------------------------------- |
+| 1    | `pnpm process:query -- overview`                           | Project health, active phases, blockers     |
+| 2    | `pnpm process:query -- scope-validate <pattern> <session>` | Pre-flight: FSM violations, missing deps    |
+| 3    | `pnpm process:query -- context <pattern> --session <type>` | Curated context bundle for the session      |
+| 4    | `pnpm process:query -- files <pattern> --related`          | File reading list with implementation paths |
+
+Session types: `planning` (minimal), `design` (full: stubs + deps + deliverables), `implement` (focused: deliverables + FSM + tests).
+
+#### When You Need More Context
+
+| Need                    | Command (NOT grep)                          | Why                                         |
+| ----------------------- | ------------------------------------------- | ------------------------------------------- |
+| Find code structure     | `arch context [name]` / `arch layer [name]` | Structured by annotations, not file paths   |
+| Find dependencies       | `dep-tree <pattern>`                        | Shows status of each dependency             |
+| Find business rules     | `rules --pattern <name>`                    | Extracted from Gherkin Rule: blocks         |
+| Find unannotated files  | `unannotated --path <dir>`                  | Catches missing @libar-docs markers         |
+| Check FSM state         | `query getProtectionInfo <status>`          | Protection level + allowed actions          |
+| Check valid transitions | `query getValidTransitionsFrom <status>`    | Valid next states from current status       |
+| Tag inventory           | `tags`                                      | Counts per tag and value across all sources |
+| Annotation coverage     | `arch coverage`                             | Files with/without @libar-docs annotations  |
+
+#### Why Annotations Beat Grep
+
+- **Structured**: `arch context` groups by bounded context; grep returns unstructured matches
+- **Queryable**: `rules --only-invariants` extracts 140+ business rules; grep can't parse Rule: blocks
+- **Feed generation**: Annotations produce generated docs; grep results are ephemeral
+- **Discoverable**: `unannotated --path` finds gaps; grep doesn't know what's missing
+
+**When adding new code:** Add `@libar-docs` annotations and relationship tags (`@libar-docs-depends-on`, `@libar-docs-uses`) so future sessions can discover the code via API queries instead of grep.
+
+Full CLI reference: `pnpm process:query -- --help`