feat: auto-generate design review documents from spec annotations

_claude-md/CLAUDE-MODULES.md

@@ -4,6 +4,6 @@
 
 1 module(s) generated from annotated behavior specs.
 
-| Module | Section | Source Pattern | Content |
-| --- | --- | --- | --- |
+| Module            | Section  | Source Pattern            | Content |
+| ----------------- | -------- | ------------------------- | ------- |
 | session-workflows | workflow | SessionGuidesModuleSource | 9 rules |

_claude-md/workflow/session-workflows.md

@@ -0,0 +1,97 @@
+### SessionGuidesModuleSource
+
+#### SESSION-GUIDES.md is the authoritative public human reference
+
+**Invariant:** `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.
+
+**Rationale:** 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
+
+**Invariant:** 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.
+
+**Rationale:** 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
+
+**Invariant:** 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.
+
+**Rationale:** Session type confusion causes wasted work — a design mistake discovered mid-implementation wastes the entire session. Clear contracts prevent scope bleeding between session types.
+
+| Session           | Input               | Output                      | FSM Change                     |
+| ----------------- | ------------------- | --------------------------- | ------------------------------ |
+| Planning          | Pattern brief       | Roadmap spec (.feature)     | Creates roadmap                |
+| Design            | Complex requirement | Decision specs + code stubs | None                           |
+| Implementation    | Roadmap spec        | Code + tests                | roadmap to active to completed |
+| Planning + Design | Pattern brief       | Spec + stubs                | Creates roadmap                |
+
+#### Planning sessions produce roadmap specs only
+
+**Invariant:** 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.
+
+**Rationale:** 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.
+
+| Do                                                  | Do NOT                     |
+| --------------------------------------------------- | -------------------------- |
+| Extract metadata from pattern brief                 | Create .ts implementation  |
+| Create spec file with proper tags                   | Transition to active       |
+| Add deliverables table in Background                | Ask Ready to implement     |
+| Convert constraints to Rule: blocks                 | Write full implementations |
+| Add scenarios: 1 happy-path + 1 validation per Rule |                            |
+
+#### 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.
+
+**Rationale:** Design sessions resolve ambiguity before implementation begins. Code stubs in delivery-process/stubs/ live outside src/ to avoid TypeScript compilation and ESLint issues, making them zero-risk artifacts.
+
+| Use Design Session         | Skip Design Session |
+| -------------------------- | ------------------- |
+| Multiple valid approaches  | Single obvious path |
+| New patterns/capabilities  | Bug fix             |
+| Cross-context coordination | Clear requirements  |
+
+#### Implementation sessions follow FSM-enforced execution order
+
+**Invariant:** 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.
+
+**Rationale:** 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.
+
+| Do NOT                              | Why                                     |
+| ----------------------------------- | --------------------------------------- |
+| Add new deliverables to active spec | Scope-locked state prevents scope creep |
+| Mark completed with incomplete work | Hard-locked state cannot be undone      |
+| Skip FSM transitions                | Process Guard will reject               |
+| Edit generated docs directly        | Regenerate from source                  |
+
+#### FSM errors have documented fixes
+
+**Invariant:** 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.
+
+**Rationale:** Undocumented FSM errors cause session-blocking confusion. A lookup table from error code to fix eliminates guesswork and prevents workarounds that bypass process integrity.
+
+| Error                     | Cause                                          | Fix                                         |
+| ------------------------- | ---------------------------------------------- | ------------------------------------------- |
+| completed-protection      | File has completed status but no unlock tag    | Add libar-docs-unlock-reason tag            |
+| invalid-status-transition | Skipped FSM state (e.g., roadmap to completed) | Follow path: roadmap to active to completed |
+| scope-creep               | Added deliverable to active spec               | Remove deliverable OR revert to roadmap     |
+| 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 | libar-docs-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            |
+
+#### 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.
+
+**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.
+
+#### ClaudeModuleGeneration is the generation mechanism
+
+**Invariant:** Phase 39 depends on ClaudeModuleGeneration (Phase 25). Adding `@libar-docs-claude-module` and `@libar-docs-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.

delivery-process.config.ts

@@ -339,6 +339,9 @@ export default defineConfig({
     index: {
       outputDirectory: 'docs-live',
     },
+    'design-review': {
+      outputDirectory: 'delivery-process',
+    },
   },
   codecOptions: {
     index: {

delivery-process/design-reviews/setup-command.md

@@ -0,0 +1,188 @@
+# Design Review: SetupCommand
+
+**Purpose:** Auto-generated design review with sequence and component diagrams
+**Detail Level:** Design review artifact from sequence annotations
+
+---
+
+**Pattern:** SetupCommand | **Phase:** Phase 45 | **Status:** roadmap | **Orchestrator:** init-cli | **Steps:** 6 | **Participants:** 8
+
+**Source:** `delivery-process/specs/setup-command.feature`
+
+---
+
+## Annotation Convention
+
+This design review is generated from the following annotations:
+
+| Tag                   | Level    | Format | Purpose                            |
+| --------------------- | -------- | ------ | ---------------------------------- |
+| sequence-orchestrator | Feature  | value  | Identifies the coordinator module  |
+| sequence-step         | Rule     | number | Explicit execution ordering        |
+| sequence-module       | Rule     | csv    | Maps Rule to deliverable module(s) |
+| sequence-error        | Scenario | flag   | Marks scenario as error/alt path   |
+
+Description markers: `**Input:**` and `**Output:**` in Rule descriptions define data flow types for sequence diagram call arrows and component diagram edges.
+
+---
+
+## Sequence Diagram — Runtime Interaction Flow
+
+Generated from: `@libar-docs-sequence-step`, `@libar-docs-sequence-module`, `@libar-docs-sequence-error`, `**Input:**`/`**Output:**` markers, and `@libar-docs-sequence-orchestrator` on the Feature.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant init_cli as "init-cli.ts"
+    participant detect_context as "detect-context.ts"
+    participant prompts as "prompts.ts"
+    participant generate_config as "generate-config.ts"
+    participant augment_package_json as "augment-package-json.ts"
+    participant scaffold_dirs as "scaffold-dirs.ts"
+    participant generate_example as "generate-example.ts"
+    participant validate_setup as "validate-setup.ts"
+
+    User->>init_cli: invoke
+
+    Note over init_cli: Rule 1 — The init command reads the target directory for package.json, tsconfig.json, delivery-process.config.ts (or .js), and monorepo markers before prompting or generating any files. Detection results determine which steps are skipped.
+
+    init_cli->>+detect_context: targetDir: string
+    detect_context-->>-init_cli: ProjectContext
+
+    alt Fails gracefully when no package.json exists
+        init_cli-->>User: error
+        init_cli->>init_cli: exit(1)
+    end
+
+    Note over init_cli: Rule 2 — The init command prompts for preset selection from the three available presets (generic, 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.
+
+    init_cli->>+prompts: ProjectContext
+    prompts-->>-init_cli: InitConfig
+
+    alt Non-interactive mode refuses to overwrite existing config
+        init_cli-->>User: error
+        init_cli->>init_cli: exit(1)
+    end
+
+    Note over init_cli: Rule 3 — The generated delivery-process.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.
+
+    init_cli->>+generate_config: InitConfig
+    generate_config-->>-init_cli: delivery-process.config.ts written to targetDir
+
+    alt Existing config file is not overwritten without confirmation
+        init_cli-->>User: error
+        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.
+
+    init_cli->>+augment_package_json: InitConfig
+    augment_package_json-->>-init_cli: package.json updated with process and docs scripts
+
+    Note over init_cli: Rule 5 — 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).
+
+    init_cli->>+scaffold_dirs: InitConfig
+    scaffold_dirs-->>-init_cli: directories created for source globs, example annotated .ts file
+    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.
+
+    init_cli->>+validate_setup: targetDir: string
+    validate_setup-->>-init_cli: SetupResult
+
+    alt Failed validation prints diagnostic information
+        init_cli-->>User: error
+        init_cli->>init_cli: exit(1)
+    end
+
+```
+
+---
+
+## Component Diagram — Types and Data Flow
+
+Generated from: `@libar-docs-sequence-module` (nodes), `**Input:**`/`**Output:**` (edges and type shapes), deliverables table (locations), and `sequence-step` (grouping).
+
+```mermaid
+graph LR
+    subgraph phase_1["Phase 1: targetDir: string"]
+        phase_1_detect_context["detect-context.ts"]
+    end
+
+    subgraph phase_2["Phase 2: ProjectContext"]
+        phase_2_prompts["prompts.ts"]
+    end
+
+    subgraph phase_3["Phase 3: InitConfig"]
+        phase_3_generate_config["generate-config.ts"]
+        phase_3_augment_package_json["augment-package-json.ts"]
+        phase_3_scaffold_dirs["scaffold-dirs.ts"]
+        phase_3_generate_example["generate-example.ts"]
+    end
+
+    subgraph phase_4["Phase 4: targetDir: string"]
+        phase_4_validate_setup["validate-setup.ts"]
+    end
+
+    subgraph orchestrator["Orchestrator"]
+        init_cli["init-cli.ts"]
+    end
+
+    subgraph types["Key Types"]
+        ProjectContext{{"ProjectContext\n-----------\npackageJsonPath\npackageJson\ntsconfigExists\ntsconfigModuleResolution\nexistingConfigPath\nisMonorepo\nhasEsmType"}}
+        InitConfig{{"InitConfig\n-----------\ntargetDir\npreset\nsources\nforce\ncontext"}}
+        SetupResult{{"SetupResult\n-----------\nsuccess\npatternCount\ndiagnostics"}}
+    end
+
+    phase_1_detect_context -->|"ProjectContext"| init_cli
+    phase_2_prompts -->|"InitConfig"| init_cli
+    phase_4_validate_setup -->|"SetupResult"| init_cli
+    init_cli -->|"targetDir: string"| phase_1_detect_context
+    init_cli -->|"ProjectContext"| phase_2_prompts
+    init_cli -->|"InitConfig"| phase_3_generate_config
+    init_cli -->|"InitConfig"| phase_3_augment_package_json
+    init_cli -->|"InitConfig"| phase_3_scaffold_dirs
+    init_cli -->|"InitConfig"| phase_3_generate_example
+    init_cli -->|"targetDir: string"| phase_4_validate_setup
+```
+
+---
+
+## Key Type Definitions
+
+| Type             | Fields                                                                                                             | Produced By    | Consumed By                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------- |
+| `ProjectContext` | packageJsonPath, packageJson, tsconfigExists, tsconfigModuleResolution, existingConfigPath, isMonorepo, hasEsmType | detect-context | prompts                                                                |
+| `InitConfig`     | targetDir, preset, sources, force, context                                                                         | prompts        | generate-config, augment-package-json, scaffold-dirs, generate-example |
+| `SetupResult`    | success, patternCount, diagnostics                                                                                 | validate-setup |                                                                        |
+
+---
+
+## Design Questions
+
+Verify these design properties against the diagrams above:
+
+| #    | Question                             | Auto-Check                      | Diagram   |
+| ---- | ------------------------------------ | ------------------------------- | --------- |
+| DQ-1 | Is the execution ordering correct?   | 6 steps in monotonic order      | Sequence  |
+| DQ-2 | Are all interfaces well-defined?     | 3 distinct types across 6 steps | Component |
+| DQ-3 | Is error handling complete?          | 4 error paths identified        | Sequence  |
+| DQ-4 | Is data flow unidirectional?         | Review component diagram edges  | Component |
+| DQ-5 | Does validation prove the full path? | Review final step               | Both      |
+
+---
+
+## Findings
+
+Record design observations from reviewing the diagrams above. Each finding should reference which diagram revealed it and its impact on the spec.
+
+| #   | Finding                                     | Diagram Source | Impact on Spec |
+| --- | ------------------------------------------- | -------------- | -------------- |
+| F-1 | (Review the diagrams and add findings here) | —              | —              |
+
+---
+
+## Summary
+
+The SetupCommand design review covers 6 sequential steps across 8 participants with 3 key data types and 4 error paths.