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

[darko-mijic]

Summary

Replaces manually maintained documentation with auto-generated equivalents driven by annotated source code. Establishes a single output directory, builds 5 new generation codecs, and reduces manual doc maintenance by ~900 lines.

67 commits across 184 files (+22,184 / -5,442 lines):

Area	Files	Lines Added	Lines Removed
Source code (src/)	42	+3,035	-434
Tests (tests/)	14	+2,524	-2
Specs (delivery-process/specs/)	17	+2,851	-25
Generated docs (docs-live/)	55	+17,445	-1,120
Design stubs	14	+2,923	—
Manual docs, config, CI	42	—	—

Before vs After

Before this PR, documentation lived in three disconnected locations (docs/, docs-generated/, docs-live/) with ~4,500 lines of manually maintained content that drifted from the codebase.

After this PR:

• docs-generated/ is eliminated — all generated output goes to docs-live/
• 900+ lines of manual docs replaced with codec-generated equivalents
• 5 new codecs produce reference docs from annotated source code
• CLAUDE.md reduced 38% (1,085 → 671 lines) by mandating Process Data API queries over manual prose
• README.md reduced 72% (504 → 142 lines) by removing content already covered by the website

---

What Changed and Why

Unified Output Directory

Problem: Generated docs were scattered across docs-generated/ and docs-live/ with no clear ownership — consumers and the website sync script had to know which directory held what.

Solution: All generated output now goes to docs-live/. The docs-generated/ directory is removed from git tracking and added to .gitignore as a transient build cache only.

Before	After
docs-generated/ (14 files, 8,117 lines tracked)	Deleted from tracking, .gitignored
Output split across 2 directories	Single docs-live/ output directory

Generated Doc Quality Improvements

Problem: Generated docs had duplicate tables (ADR-006 violation), missing TOCs, inconsistent type ordering, and a wall-of-text introduction in the Generation product area doc.

Solution:

• Fixed REFERENCE-SAMPLE.md duplication
• Added TOC to long generated documents
• Reordered type documentation for logical reading flow
• Replaced Generation product area intro with structured pipeline stage + codec inventory tables

Session Workflow as Queryable Business Rules

Problem: Session workflow guidance was hand-authored in CLAUDE.md and duplicated across multiple locations with no synchronization mechanism.

Solution: Created a comprehensive spec (session-guides-module-source.feature) with 7 Rule blocks encoding session workflow invariants. These now serve as source for both:

• Compact AI context modules (_claude-md/workflow/session-workflow-guide.md)
• Public reference docs (docs-live/reference/SESSION-WORKFLOW-GUIDE.md, 384 lines)
• Queryable rules via pnpm process:query -- rules --pattern SessionGuidesModuleSource

Publishing Docs Relocated

Problem: docs/PUBLISHING.md was published to the website but contained maintainer-only npm publishing workflows irrelevant to end users.

Solution: Moved to MAINTAINERS.md at repo root — the audience-appropriate location for contributor-facing operational docs, excluded from website publishing.

Gherkin Patterns Restructured

Problem: docs/GHERKIN-PATTERNS.md (515 lines) contained a Step Linting Reference section that belongs with validation documentation, not authoring guidance.

Solution:

• Relocated Step Linting Reference to docs/VALIDATION.md (correct domain)
• Trimmed GHERKIN-PATTERNS.md to 366 lines (29% reduction)
• Focused remaining content on essential authoring patterns, tag constraints, and parser quirks

README Rationalized

Problem: README.md (504 lines) duplicated 10 sections already covered by website components and generated docs.

Solution: Trimmed to 142 lines (72% reduction) with outcome-focused messaging: Quick Start, How It Works, What Gets Generated, CLI Commands table, and documentation links.

Process API Docs Generated from Declarative Schema

Problem: docs/PROCESS-API.md (508 lines) was a manually maintained CLI reference that drifted from actual implementation whenever commands changed.

Solution:

• Created src/cli/cli-schema.ts (616 lines) — a declarative CLI schema that serves as single source of truth for both runtime help text and generated docs
• Built ProcessApiReferenceGenerator → generates reference tables from the schema
• Built CliRecipeGenerator → generates workflow recipes with editorial preamble
• Trimmed PROCESS-API.md to a 63-line pointer file (87% reduction)

New generated output:

• docs-live/reference/PROCESS-API-REFERENCE.md (63 lines) — command reference tables
• docs-live/reference/PROCESS-API-RECIPES.md (476 lines) — workflow recipes and examples

Claude Module Generation

Problem: _claude-md/ modules were hand-authored, creating maintenance burden for compact AI context that had to be manually kept in sync with spec changes.

Solution: Created ClaudeModuleCodec that extracts Rule blocks from patterns tagged with @libar-docs-claude-module and generates compact context modules with invariants, rationale, and decision tables derived from Scenario Outline examples.

New Index, Architecture, and Changelog Generators

Five generators were added or promoted to the standard build:

Generator	Output	Lines	What It Produces
IndexCodec	docs-live/INDEX.md	226	Navigation hub composing editorial preamble with MasterDataset statistics
CliRecipeGenerator	PROCESS-API-RECIPES.md	476	Workflow recipes generated from CLI schema
ProcessApiReferenceGenerator	PROCESS-API-REFERENCE.md	63	CLI command reference tables
Architecture generator	docs-live/ARCHITECTURE.md	564	Mermaid architecture diagrams
Changelog generator	docs-live/CHANGELOG-GENERATED.md	328	Release history from commit metadata

Plus 4 new reference documents via ReferenceDocConfig:

• PROCESS-GUARD-REFERENCE.md (179 lines) — error diagnosis, FSM states, pre-commit setup
• SESSION-WORKFLOW-GUIDE.md (384 lines) — session checklists with Mermaid decision tree
• ANNOTATION-REFERENCE.md (146 lines) — getting-started guide for @libar-docs annotations
• Enhanced ARCHITECTURE-CODECS.md (656 lines) and ARCHITECTURE-TYPES.md (429 lines)

---

New Source Code

Core infrastructure (src/)

File	Purpose
cli/cli-schema.ts	Declarative CLI schema — single source of truth for help text + doc generation
generators/built-in/cli-recipe-generator.ts	Generates recipe docs from CLI schema + markdown preambles
generators/built-in/process-api-reference-generator.ts	Generates CLI reference tables from schema
generators/built-in/codec-generators.ts	Wires all 23 generators into the registry
renderable/codecs/index-codec.ts	Composes editorial preamble with MasterDataset statistics for INDEX.md
renderable/codecs/claude-module.ts	Extracts Rule blocks → compact AI context modules
renderable/load-preamble.ts	5-state markdown parser: docs-sources/*.md → SectionBlock[]
taxonomy/claude-section-values.ts	Enum for _claude-md/ subdirectory organization

Key design pattern: loadPreambleFromMarkdown()

The src/renderable/load-preamble.ts utility (349 lines) eliminates the need to hand-author SectionBlock[] arrays in TypeScript config. Instead, editorial preamble content is authored as natural Markdown in docs-sources/ and parsed into structured blocks at config load time. This reduced per-codec config boilerplate by ~540 lines.

4 preamble source files in docs-sources/:

File	Content
annotation-guide.md	Getting started with @libar-docs annotations
index-navigation.md	Quick navigation table for generated docs
session-workflow-guide.md	Session decision tree (Mermaid flowchart)
process-api-recipes.md	CLI recipes with comparison tables

---

Specification Work

15 new spec files define the consolidation deliverables as executable specifications:

Spec	Pattern	Status
docs-consolidation-strategy.feature	DocsConsolidationStrategy	roadmap
docs-live-consolidation.feature	DocsLiveConsolidation	completed
publishing-relocation.feature	PublishingRelocation	completed
generated-doc-quality.feature	GeneratedDocQuality	completed
session-guides-module-source.feature	SessionGuidesModuleSource	completed
gherkin-patterns-restructure.feature	GherkinPatternsRestructure	completed
readme-rationalization.feature	ReadmeRationalization	completed
process-api-hybrid-generation.feature	ProcessApiHybridGeneration	completed
claude-module-generation.feature	ClaudeModuleGeneration	completed
architecture-doc-refactoring.feature	ArchitectureDocRefactoring	completed
enhanced-index-generation.feature	EnhancedIndexGeneration	completed
error-guide-codec.feature	ErrorGuideCodec	completed
cli-recipe-codec.feature	CliRecipeCodec	completed
procedural-guide-codec.feature	ProceduralGuideCodec	completed

14 design stub files in delivery-process/stubs/ provide interfaces and schemas for future implementation work.

---

Test Coverage

14 new test files (+2,524 lines), all in Gherkin .feature + step definition format:

Test File	What It Covers
process-api-reference.steps.ts	Reference table generation from declarative CLI schema
convention-extractor.steps.ts	Heading match for structured JSDoc convention annotations
generated-doc-quality.steps.ts	Duplicate table detection, TOC generation, type ordering
reference-codec-diagrams.steps.ts	Mermaid C4Context + graph LR diagram generation per product area
reference-generators.steps.ts	Config-driven reference doc generation pipeline
architecture-doc-refactoring.steps.ts	Convention tag decomposition of ARCHITECTURE.md
load-preamble.steps.ts	Markdown → SectionBlock[] 5-state parser

---

Manual Docs Impact

Trimmed (replaced by generated equivalents)

Document	Before	After	Reduction	Generated Replacement
PROCESS-API.md	508	63	87%	PROCESS-API-REFERENCE.md + PROCESS-API-RECIPES.md
README.md	504	142	72%	Website components
CLAUDE.md	1,085	671	38%	Process Data API queries
GHERKIN-PATTERNS.md	515	366	29%	Step Linting → VALIDATION.md

Relocated

Document	From	To	Reason
PUBLISHING.md	docs/	MAINTAINERS.md (root)	Audience alignment — maintainer content, not user content
Step Linting section	GHERKIN-PATTERNS.md	VALIDATION.md	Correct domain — validation rules belong with validation docs

Preserved as reference

Manual docs/ files are preserved until generated equivalents reach quality parity. Each file has a note pointing to its generated counterpart.

---

Documentation Architecture

After this PR, documentation follows a clear three-tier hierarchy:

┌─────────────────────────────────────────────────────┐
│ Tier 1: Annotated Source Code (single source)       │
│   TypeScript JSDoc + Gherkin Rule: blocks            │
│   → Queryable via: pnpm process:query               │
├─────────────────────────────────────────────────────┤
│ Tier 2: Generated Docs (auto-maintained)            │
│   docs-live/        → 55+ files, website-ready      │
│   _claude-md/       → 10 AI context modules         │
├─────────────────────────────────────────────────────┤
│ Tier 3: Editorial Docs (hand-maintained)            │
│   docs/             → Philosophy, gotchas, guides   │
│   docs-sources/     → Preambles injected into Tier 2│
│   CLAUDE.md         → Compact AI session context    │
└─────────────────────────────────────────────────────┘

The key insight: Tier 1 annotations feed Tier 2 generation automatically. Tier 3 exists only for irreducibly editorial content (philosophy, troubleshooting gotchas, authoring style guides) that cannot be extracted from code.

---

Remaining Work

Tracked in docs/DOCS-GAP-ANALYSIS.md:

Priority	Item	Description
P0	Website sync script fix	Update sync-content.mjs to read from docs-live/ instead of the now-empty docs-generated/
P1	Quality polish	Mobile-friendly tables, Mermaid rendering verification, cross-references, split oversized files
P3	Methodology disposition	Confirm METHODOLOGY.md stays manual (philosophy is irreducibly editorial)

---

How to Verify

# Regenerate all docs (should be idempotent — no diff after run)
pnpm docs:all

# Run full test suite
pnpm test

# Validate process integrity (FSM, anti-patterns, DoD)
pnpm validate:all

# Query project health
pnpm process:query -- overview

Test Plan

• pnpm test — all tests pass including 14 new test files (+2,524 lines)
• pnpm docs:all — regeneration is idempotent (no diff after run)
• pnpm validate:all — no anti-pattern or DoD violations
• pnpm typecheck — no type errors
• pnpm lint — no lint violations
• Website build reads from docs-live/ correctly (separate follow-up PR)

[coderabbitai]

Actionable comments posted: 54

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (6)

src/renderable/codecs/planning.ts (1)

204-204: 🧹 Nitpick | 🔵 Trivial

Consider relocating this import to the top with other imports.

This import sits between the options constants (lines 115-203) and the codec implementations (lines 206+), which breaks the conventional import-at-top structure. Moving it to the import block (around line 83) would improve readability.

♻️ Suggested relocation

Move this line to the import section at the top of the file (after line 83):

 import {
   type BaseCodecOptions,
   type NormalizedStatusFilter,
   DEFAULT_BASE_OPTIONS,
   mergeOptions,
 } from './types/base.js';
+import { RenderableDocumentOutputSchema } from './shared-schema.js';

Then remove the import from line 204.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/planning.ts` at line 204, The import of
RenderableDocumentOutputSchema is placed mid-file, breaking the convention of
keeping imports at the top; move the "import { RenderableDocumentOutputSchema }
from './shared-schema.js';" statement into the main import block with the other
imports (near the other top imports around where existing import declarations
are) and remove the duplicate/mid-file import so that
RenderableDocumentOutputSchema is only imported once before the constants and
codec implementations (e.g., used by the codec functions below).

src/renderable/codecs/convention-extractor.ts (1)

1-24: 🧹 Nitpick | 🔵 Trivial

Missing @libar-docs opt-in marker in file-level JSDoc.

The file-level JSDoc comment describes the module's purpose but lacks the @libar-docs marker required for pattern extraction scanning.

As per coding guidelines: "All TypeScript files in src/ must include @libar-docs opt-in marker in file-level JSDoc to be scanned for pattern extraction."

📝 Add opt-in marker to file JSDoc

 /**
  * Convention Extractor
  *
  * Filters MasterDataset for patterns tagged with `@libar-docs-convention`
  * and extracts convention content as structured data for reference codec
  * composition. Supports two sources:
  *
  * - **Gherkin**: Extracts from `Rule:` blocks on the pattern's `rules` array
  * - **TypeScript**: Decomposes JSDoc `directive.description` by `## Heading`
  *   sections, parsing each section for structured annotations
  *
  * Both sources produce the same `ConventionRuleContent` output, enabling
  * Gherkin and TypeScript convention content to merge in the same bundle.
  *
  * `@see` CodecDrivenReferenceGeneration spec
  * `@see` ReferenceDocShowcase spec
+ * `@libar-docs`
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/convention-extractor.ts` around lines 1 - 24, The
file-level JSDoc in convention-extractor.ts is missing the required `@libar-docs`
opt-in marker; add the line "@libar-docs" to the top JSDoc block (above the
imports) so the pattern extractor will scan this module. Ensure the marker
appears in the existing block that documents this module (the comment containing
"Convention Extractor") and keep the rest of the description intact so functions
like parseBusinessRuleAnnotations and exported types continue to be discovered.

src/renderable/codecs/session.ts (1)

85-112: ⚠️ Potential issue | 🟠 Major

Wire the new SessionCodecOptions flags into the renderer.

includeAcceptanceCriteria, includeDeliverables, includeRelatedPatterns, and includeHandoffContext are part of the exported options surface here, but the session rendering path only checks includeDependencies. Calling createSessionContextCodec() with those new flags currently produces the same document, which makes the API contract misleading. Either thread these flags through buildSessionPhaseDetailDocument() / buildSessionPatternList() or remove them until the corresponding sections exist.

Also applies to: 582-721

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/session.ts` around lines 85 - 112, The exported
SessionCodecOptions flags (includeAcceptanceCriteria, includeDeliverables,
includeRelatedPatterns, includeHandoffContext) are declared in
SessionCodecOptions/DEFAULT_SESSION_OPTIONS but never used in rendering; update
createSessionContextCodec to accept and propagate these flags into the rendering
pipeline and update buildSessionPhaseDetailDocument and buildSessionPatternList
(and any helper functions in the session rendering path around the 582-721
region) to accept a SessionCodecOptions parameter and conditionally include the
corresponding sections based on those flags (e.g., only append acceptance
criteria, deliverables, related patterns, or handoff context when the matching
option is true); alternatively, if those sections are not yet implemented,
remove the unused flags from SessionCodecOptions/DEFAULT_SESSION_OPTIONS to keep
the API consistent.

src/renderable/codecs/reporting.ts (1)

147-147: 🛠️ Refactor suggestion | 🟠 Major

Move import statement to the top of the file.

The import of RenderableDocumentOutputSchema is placed after the options constants rather than with the other imports at lines 46-70. This violates the standard convention of grouping all imports at the top of the file and reduces code readability.

📦 Proposed fix to relocate the import

Remove the import from line 147 and add it to the import block at the top:

 import {
   type RenderableDocument,
   type SectionBlock,
   heading,
   paragraph,
   separator,
   table,
   list,
   collapsible,
   document,
 } from '../schema.js';
+import { RenderableDocumentOutputSchema } from './shared-schema.js';
 import {
   getDisplayName,

And remove it from line 147:

   includePatternsSummary: true,
   includeTimelineSummary: true,
 };
-import { RenderableDocumentOutputSchema } from './shared-schema.js';
 
 // ═══════════════════════════════════════════════════════════════════════════

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/reporting.ts` at line 147, Move the import of
RenderableDocumentOutputSchema from its current location near the options
constants and place it with the other imports at the top import block so all
imports are grouped together; update the top import block to include
"RenderableDocumentOutputSchema" from './shared-schema.js' and remove the
redundant import statement that currently follows the options constants to
restore conventional import ordering.

src/renderable/codecs/reference.ts (1)

667-679: ⚠️ Potential issue | 🟠 Major

Don't dedupe shapes by name alone.

seenNames collapses every declaration named Config, Options, etc. into a single entry even when they come from different files. The new selector/include merging makes that silent data loss much more likely, and the same composite-key strategy should be used in the product-area path too.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/reference.ts` around lines 667 - 679, The current
dedupe uses seenNames keyed only by shape.name which collapses distinct
declarations with the same name; change deduplication to use a composite key
(e.g., name + file/module/source/path) so shapes from different files aren’t
lost: when building allShapes from extractShapesFromDataset(config.shapeSources)
and when merging selectorShapes from
filterShapesBySelectors(config.shapeSelectors) compute a uniqueKey for each
shape (for example `${shape.source || shape.filePath ||
shape.module}:${shape.name}`), store that in seenNames, and use it for both the
initial Set population and the membership checks/adds; apply the same
composite-key strategy to the product-area merge path as well so all merge
points use the same uniqueness criteria.

src/generators/pipeline/transform-dataset.ts (1)

318-347: ⚠️ Potential issue | 🟡 Minor

warningCount now undercounts repeated unknown statuses.

Using a Set is fine for deduplicating unknownStatuses, but warningCount now increases by distinct invalid status values instead of by warning occurrences. If ten patterns all use the same bad status, the summary reports one warning instead of ten.

Suggested fix

-  const unknownStatusSet = new Set<string>();
+  const unknownStatusSet = new Set<string>();
+  let unknownStatusCount = 0;
@@
-      unknownStatusSet.add(pattern.status);
+      unknownStatusSet.add(pattern.status);
+      unknownStatusCount++;
@@
-    warningCount: malformedPatterns.length + danglingReferences.length + unknownStatuses.length,
+    warningCount: malformedPatterns.length + danglingReferences.length + unknownStatusCount,

Also applies to: 654-660

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/generators/pipeline/transform-dataset.ts` around lines 318 - 347, The
current code uses unknownStatusSet to dedupe invalid status values which causes
warningCount to undercount repeated occurrences; update the logic in the loop
that checks pattern.status (and the analogous block around the other occurrence)
to increment a per-occurrence counter (e.g., unknownStatusCount) every time
pattern.status exists and !isKnownStatus(pattern.status), while still adding the
status string to unknownStatusSet for unique reporting; adjust any later uses of
warningCount to include unknownStatusCount so the summary reflects the total
number of invalid-status warnings, not just the number of distinct invalid
values.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@delivery-process/specs/architecture-doc-refactoring.feature`:
- Around line 35-50: Update the "Available Codecs" row in the Section
Disposition table so the source span matches the documented 368-line move:
change the Lines value for the "Available Codecs" row (currently "529-534") to
the correct range (start 529, end 896) so it reads "529-896"; edit the table
entry in delivery-process/specs/architecture-doc-refactoring.feature where the
Section Disposition table and the "Available Codecs" row are defined.
- Around line 1-10: The feature metadata is missing the required ownership and
timeline tags; add `@libar-docs-team` with the appropriate owning team identifier
(e.g., "DocsPlatform" or the correct team name) and `@libar-docs-quarter` with the
correct timeline value (e.g., "2026-Q1") to the feature header where the other
`@libar-docs-`* tags live; ensure these tags are placed in this feature file (not
in any TypeScript) and follow the same key:value format as the existing tags
like `@libar-docs-status` and `@libar-docs-effort`.

In `@delivery-process/specs/docs-live-consolidation.feature`:
- Around line 1-10: The feature file "Feature: Docs Live Directory
Consolidation" is missing required metadata tags; add the `@libar-docs-team`
(ownership), `@libar-docs-quarter` (timeline) and `@libar-docs-unlock-reason`
(unlock justification for completed pattern) tags at the top of the feature
header so the file satisfies the feature-file metadata contract and hard-lock
requirements; ensure the tag names match exactly (`@libar-docs-team`,
`@libar-docs-quarter`, `@libar-docs-unlock-reason`) and provide appropriate values
consistent with other pattern specs.

In `@delivery-process/specs/generated-doc-quality.feature`:
- Around line 77-80: The spec has conflicting size thresholds for compact files:
the invariant text for "_claude-md/<area>/<area>-overview.md" currently requires
"Minimum target: 4 KB" while the deliverable table states "5+ KB"; reconcile
them by choosing a single canonical threshold (preferably 5 KB to match the
deliverable table) and update the invariant text to "Minimum target: 5 KB" (or
update the table if you want 4 KB), then run/adjust any validation or executable
checks that reference the compact-size threshold so both the human-facing table
and the executable invariant use the same value.
- Around line 1-9: The feature header is missing the required metadata tags so
add `@libar-docs-quarter` and `@libar-docs-team` to the top tag block (alongside
existing tags like `@libar-docs`, `@libar-docs-pattern`, `@libar-docs-status`, etc.);
update the generated-doc-quality feature file's tag list to include the
appropriate quarter value for timeline views and the owning team value for
ownership reports, ensuring the tags are placed in the feature file header (not
in any TypeScript files) so tools that read `@libar-docs-quarter` and
`@libar-docs-team` can classify the spec correctly.
- Around line 34-40: The feature lists "Add generated TOC block to product area
doc headers" as a completed deliverable but lacks executable coverage; add a
Rule or Scenario in generated-doc-quality.feature that specifically exercises
this deliverable (use the exact title "Add generated TOC block to product area
doc headers"), placing it after the Background so the Given table applies, and
implement Given/When/Then steps that assert the TOC block is generated and
inserted into product area doc headers (match existing step definitions used by
other scenarios in this file so it runs as an integration test).

In `@delivery-process/specs/gherkin-patterns-restructure.feature`:
- Around line 1-10: The feature metadata block for GherkinPatternsRestructure is
missing required tags: add `@libar-docs-team` (team name), `@libar-docs-quarter`
(timeline, e.g., Q2-2026) and an `@libar-docs-unlock-reason` with the appropriate
justification; place these tags alongside the existing `@libar-docs-`* tags at the
top of the Feature declaration so the feature file (not any TypeScript) contains
ownership, timeline and the completed-spec unlock reason as required by the
guidelines.

In `@delivery-process/specs/process-api-hybrid-generation.feature`:
- Around line 1-10: The feature file "Feature: PROCESS-API.md Hybrid Generation"
is missing required metadata tags; add `@libar-docs-team` with the owning team
name, `@libar-docs-quarter` with the timeline (e.g., Qn-YYYY), and an
`@libar-docs-unlock-reason` explaining why the completed pattern spec is being
modified (to satisfy hard-lock requirements); place these tags alongside the
existing `@libar-docs-`* tags at the top of the file so the Feature header and
pattern identifier (ProcessApiHybridGeneration) include the new metadata.

In `@delivery-process/specs/publishing-relocation.feature`:
- Around line 1-9: The spec is missing required metadata tags
`@libar-docs-quarter` and `@libar-docs-team`; update the PublishingRelocation
feature header to include both tags (e.g., add
`@libar-docs-quarter`:<current-quarter> and `@libar-docs-team`:<owning-team>)
alongside the existing `@libar-docs-`* tags so timeline and ownership views pick
up this feature.
- Around line 149-154: The scenario "INDEX.md and website manifest are updated"
currently only asserts changes to docs/INDEX.md; add explicit assertions that
the website manifest (content-manifest.mjs) no longer references PUBLISHING.md
and that MAINTAINERS.md was rewritten as expected so regressions are caught.
Update the Scenario steps (under "Phase 40 (PublishingRelocation) is complete")
to include: a step asserting content-manifest.mjs has no PUBLISHING.md entry and
a step asserting MAINTAINERS.md content matches the rewritten form (or at least
contains the new expected maintainer text), referencing the files
content-manifest.mjs and MAINTAINERS.md in the step text so the acceptance
criteria are unambiguous.

In `@delivery-process/specs/readme-rationalization.feature`:
- Around line 1-10: The feature file is missing the required ownership and
timeline metadata tags; add `@libar-docs-team` and `@libar-docs-quarter` to the top
of the README Rationalization feature (the same header block that contains
`@libar-docs`, `@libar-docs-pattern`, etc.) so planning and ownership queries pick
it up; ensure the tags use the exact names `@libar-docs-team` and
`@libar-docs-quarter` and provide the appropriate team identifier and quarter
value consistent with other specs.

In `@delivery-process/specs/session-guides-module-source.feature`:
- Around line 72-73: The status table row for the deliverable named
"_claude-md/workflow/fsm-handoff.md" has the Location column incorrectly set to
"_claude-md/workflow/session-workflows.md"; update that Location entry to
"_claude-md/workflow/fsm-handoff.md" so the row for
"_claude-md/workflow/fsm-handoff.md" is internally consistent (edit the table
row that contains the deliverable name "_claude-md/workflow/fsm-handoff.md" and
change its Location value to "_claude-md/workflow/fsm-handoff.md").
- Around line 76-78: The feature file contains banner separator lines starting
with '#' (e.g., the block under "RULE 1: SESSION-GUIDES.MD IS THE PUBLIC HUMAN
REFERENCE") which are treated as Gherkin comments and get stripped; remove those
leading '#' banner lines from the Gherkin body and replace them with blank lines
or plain markdown emphasis (italics/bold) or normal text so the description and
rule content remain visible to the parser and adhere to the feature-file
formatting rule.
- Around line 1-13: The feature header is missing required ownership/timeline
tags; add the `@libar-docs-team` and `@libar-docs-quarter` annotations to the
feature file header (the block containing
`@libar-docs-pattern`:SessionGuidesModuleSource and other metadata) so the
Feature: Session Guides as Annotated Module Source participates in ownership and
planning reports; use the team identifier value expected by your project and the
appropriate quarter string (e.g., Q1-YYYY) following existing tag style.
- Around line 135-149: The spec erroneously treats "Planning + Design" as a
fourth canonical session type; remove the "Planning + Design" row from the
session table and any references in the Invariant and Rationale so the document
only lists the supported session types ("Planning", "Design", "Implementation"
and optional "Review"/handoff), and update the table and text to reflect that
combined workflows are not a distinct session type but a sequence of existing
types (do not add a new session identifier "Planning + Design" anywhere).

In `@docs/GHERKIN-PATTERNS.md`:
- Around line 348-355: The guidance for "Section comments `#`" is too broad and
must be qualified: update the text for Section comments `#` to warn that leading
`#` lines are a parser trap inside Feature and Rule description blocks (they are
treated as Gherkin comment terminators), and recommend using `#` only for
organizing content outside Feature/Rule descriptions (e.g., between scenarios or
at file-level), and add an inline pointer to the existing `lint-steps`
caveat/VALIDATION.md entry so readers see the linting limitation and examples.

In `@docs/INDEX.md`:
- Around line 22-30: The detailed TOC entries for ARCHITECTURE.md and
PROCESS-API.md are out of sync with the quick-nav ranges; update the detailed
section ranges to match the quick-nav values (ARCHITECTURE.md → 1-358 and
PROCESS-API.md → 1-464) so the INDEX.md is internally consistent; find the
detailed occurrences referencing ARCHITECTURE.md and PROCESS-API.md and replace
their old ranges (e.g., 1-1638 / 1-507) with the new range values shown in the
quick-nav.

In `@docs/PROCESS-API.md`:
- Line 380: Replace the broken internal anchors "#output-modifiers" and
"#list-filters" in the PROCESS-API.md text with links to the generated CLI
reference (the Process API CLI Reference at
../docs-live/reference/PROCESS-API-REFERENCE.md); search for any occurrences of
those anchors (e.g., the earlier copy that points to `#output-modifiers` and
`#list-filters`) and update the hrefs/text to point to the generated reference
page so the documentation no longer contains broken internal links.

In `@docs/VALIDATION.md`:
- Around line 217-224: The fenced block showing the "Scan scope" default paths
in docs/VALIDATION.md is unlabeled and triggers markdownlint MD040; update that
fenced code block by adding a language label (e.g., change the opening triple
backticks to "```text") so the block is no longer unlabeled—look for the block
containing "Feature files:" and "Step files:" and add the language token to the
opening fence.
- Line 94: The summary line text "12 rules across 3 categories (8 error, 4
warning)" is incorrect; update that string to reflect the actual table totals by
changing it to "12 rules across 3 categories (9 error, 3 warning)" and verify no
other occurrences of the old totals remain in VALIDATION.md so the header and
tables are consistent.

In `@src/cli/cli-schema.ts`:
- Around line 62-64: Update the postNote string in cli-schema.ts (the postNote
property) so it references both supported config filenames instead of hardcoding
delivery-process.config.ts; change the wording to indicate
"delivery-process.config.ts or delivery-process.config.js" (or
"delivery-process.config.ts or .js") as the main integration contract,
preserving the rest of the note about fallback detection and --input
requirement.
- Around line 1-8: Update the JSDoc annotation to use the canonical "tag value"
shape: replace the colon-separated `@libar-docs-product-area:DataAPI` with the
space-separated `@libar-docs-product-area DataAPI` in this module's header so it
matches the other `@libar-docs` annotations (check the top-of-file JSDoc block
around the CLISchema header).

In `@src/cli/process-api.ts`:
- Around line 285-289: The schema-driven help block builds help pieces via
formatHelpOptions(CLI_SCHEMA.*) and currently exposes the sessionOptions help as
if it applies to the scope-validate command (creating duplicate/conflicting
"Session Types" output); update the generation so sessionOptions is not
advertised for scope-validate — rename the variable (e.g., sessions ->
sessionOptionsHelp) to clarify intent and remove or conditionally render it
where scope-validate help is assembled (also apply the same change to the
repeated block referenced around the second occurrence), ensuring only the
explicit hand-written session-type section is shown for scope-validate and that
formatHelpOptions(CLI_SCHEMA.sessionOptions) is printed only where it truly
applies.

In `@src/extractor/gherkin-extractor.ts`:
- Around line 267-270: The async extractor extractPatternsFromGherkinAsync is
missing the Claude metadata fields when building directive and rawPattern;
update the async builder so it mirrors the sync path by applying
assignIfDefined(directive, 'claudeModule', metadata.claudeModule),
assignIfDefined(directive, 'claudeSection', metadata.claudeSection) and
assignIfNonEmpty(directive, 'claudeTags', metadata.claudeTags) wherever
directive/rawPattern are constructed in extractPatternsFromGherkinAsync (and the
second async occurrence around the other builder block referenced in the
comment), ensuring the same metadata assignment logic and order as the sync
implementation so async callers retain claudeModule/claudeSection/claudeTags.

In `@src/renderable/codecs/adr.ts`:
- Line 16: The documentation incorrectly states the codec emits category pages
at decisions/<category-slug>.md; update the doc to reflect the actual output
shape produced by buildAdrDetailFiles(), which creates one file per ADR using
adrToSlug(pattern). Replace the incorrect path reference with the per-ADR output
pattern (e.g., decisions/<adr-slug>.md or whatever adrToSlug(pattern) yields)
and ensure DECISIONS.md (ADR index) remains documented as an output.
- Line 7: The product-area tag uses a colon instead of a space so the metadata
extractor (the regex used by extractSingleValue:
'@libar-docs-product-area\s+(.+?)') fails to match; replace occurrences of
'@libar-docs-product-area:Generation' with '@libar-docs-product-area Generation'
(and similarly fix other files in the same codec set) so the tag matches the
extractSingleValue pattern and productArea is populated.

In `@src/renderable/codecs/business-rules.ts`:
- Around line 427-434: The regex NEXT_HEADER_PATTERN incorrectly uses a
start-of-line anchor inside an alternation which prevents matching indented
table rows; update NEXT_HEADER_PATTERN so it removes the ^ and uses a
non-capturing group, e.g., change the pattern from /\n\s*(\*\*[A-Z]|^\|)/m to
one that matches newline + optional whitespace followed by either a bold header
or a pipe without the caret (e.g., /\n\s*(?:\*\*[A-Z]|\|)/m), ensuring it still
detects CONTENT_HEADER_PATTERNS but also matches indented table rows.

In `@src/renderable/codecs/claude-module.ts`:
- Around line 233-239: The current code derives the human-facing documentation
link by uppercasing the module slug using pattern.claudeModule (or
pattern.name), which is incorrect; update the logic to use an explicit
metadata/config field for the human-doc target (e.g., pattern.humanDocsSlug or
pattern.fullDocsSlug) instead of pattern.claudeModule, and fall back to a safe
default only if that explicit field is absent; modify the block that checks
options.fullDocsPath to build fullPath from this new explicit field and keep the
separator() and linkOut(`Full Documentation`, fullPath) behavior unchanged so
the human docs link points to the canonical document rather than the compact
module filename.
- Around line 327-341: The extractExamplesTables function currently iterates
every step.dataTable and emits all step tables; change it to only lift tables
from Scenario Outline examples by first checking scenario-level metadata (e.g.,
presence of scenario.examples, scenario.isOutline, scenario.keyword ===
'Scenario Outline' or similar) before iterating steps: in extractExamplesTables,
skip scenarios that are not outlines (no examples metadata) and only map
step.dataTable entries for scenarios that qualify, so only Example/decision
tables are pushed via table([...dt.headers], rows).

In `@src/renderable/codecs/patterns.ts`:
- Around line 21-29: The header docs are out of sync with implementation: update
the doc block to reflect that buildIndividualPatternFiles() emits one file per
pattern slug (e.g., patterns/<slug>.md) rather than category detail files, and
replace or rename the generateDetailFiles option to accurately describe this
behavior (e.g., generateIndividualPatternFiles: boolean, default true). Also
ensure includeUseCases is actually respected by the renderer: either pass
options.includeUseCases into the code path that renders use cases (the function
that currently outputs use-case sections) or add a conditional check before
rendering use cases so use cases are skipped when includeUseCases is false.
Finally, update the options table (detailLevel, filterCategories, etc.) to match
the true supported names and defaults used by the
buildIndividualPatternFiles()/renderer code.
- Around line 11-12: Update the JSDoc tag to the canonical key/value form so the
product-area extractor sees it: replace the nonstandard
"@libar-docs-product-area:Generation" token with the canonical
"@libar-docs-product-area Generation" (keeping the "@libar-docs" prefix intact)
in the header JSDoc block in patterns.ts so the annotation matches the rest of
src/ metadata.

In `@src/renderable/codecs/reference.ts`:
- Around line 1797-1811: The MasterDataset fan-out diagram in
buildMasterDatasetViewsDiagram is missing the byProductArea view; update the
returned array in buildMasterDatasetViewsDiagram to include a new line for MD
--> byProductArea (use the same formatting as other nodes, e.g., '    MD -->
byProductArea["byProductArea<br/>(keyed by product area name)"]') so the
hardcoded diagram matches the dataset.byProductArea usage elsewhere.
- Around line 131-135: ReferenceDocConfig now includes a new optional preamble
field but the runtime Zod schema ReferenceDocConfigSchema in
project-config-schema.ts is missing it; update ReferenceDocConfigSchema to
include preamble: z.array(SectionBlockSchema).readonly().optional() (or the
appropriate SectionBlock schema identifier used in that file) so the preamble
array is validated at runtime, ensuring the ReferenceDocConfig interface and
ReferenceDocConfigSchema stay in sync.

In `@src/renderable/codecs/requirements.ts`:
- Around line 14-26: Update the JSDoc header to match the implementation: change
the Output Files description to state that the codec emits one detail file per
requirement using requirementToSlug(...) (e.g.,
`requirements/<requirement-slug>.md`) instead of `requirements/<area-slug>.md`,
and add the missing public option includeStepDetails (with its correct default)
to the options table so the documented option list matches the actual exported
options like includeScenarioSteps and includeBusinessValue.

In `@src/renderable/codecs/session.ts`:
- Around line 31-38: The RemainingWork codec currently accepts sortBy and
groupPlannedBy but never applies them; update the codec code that builds the
remaining-work lists (the session codec functions handling RemainingWork
rendering/serialization) to read options.sortBy and options.groupPlannedBy and
apply them: implement comparators for sortBy values
("phase","priority","effort","quarter") wherever lists are sorted (including
NextActionable and general item lists) and implement regrouping logic for
planned items when groupPlannedBy is "quarter","priority","level" (leave "none"
as-is), ensuring the same logic is applied in all code paths that emit remaining
work (the session/RemainingWork encode/render functions referenced in this
file).

In `@src/renderable/codecs/timeline.ts`:
- Around line 15-21: The public options table advertises knobs that the timeline
codec doesn't actually use; either remove those options from the public docs or
implement them. Modify the roadmap rendering flow (functions like renderRoadmap
/ generateMainDocument and buildPhaseDetailFiles / generateDetailFiles) to apply
filterPhases before any phase is rendered, apply filterStatus when selecting
items to include in phases, and respect includeProcess and includeDeliverables
when assembling both the main document and per-phase detail files;
alternatively, if you choose not to implement them, remove filterStatus,
includeProcess, includeDeliverables, and filterPhases from the exported
RoadmapOptions/docs so the public API matches actual behavior.
- Around line 6-7: The JSDoc tag '@libar-docs-product-area:Generation' in the
top comment of src/renderable/codecs/timeline.ts uses a colon form; update it to
the whitespace-separated convention used elsewhere and ensure it includes the
'@libar-docs' marker (change the tag text to '@libar-docs-product-area
Generation' in the file's leading JSDoc block), keeping the exact tag name so
automated parsers recognize it.

In `@src/renderable/codecs/validation-rules.ts`:
- Around line 14-23: Update the documentation header to accurately reflect the
actual detail files emitted by buildDetailFiles(): instead of saying
`validation/<category>.md`, list the three concrete outputs
`validation/fsm-transitions.md`, `validation/error-catalog.md`, and
`validation/protection-levels.md`, and ensure the Output Files section mentions
`VALIDATION-RULES.md` plus those three specific detail files; locate the header
comment near the top of the validation-rules codec (reference symbol
buildDetailFiles and the generated file names) and replace the misleading
category-based path with the explicit file names and brief descriptions for
each.
- Around line 6-7: Update the JSDoc block so the product-area tag uses the
canonical whitespace-separated format: replace
`@libar-docs-product-area:Generation` with `@libar-docs-product-area Generation`
(or better, follow the project's opt-in marker style and use
`@libar-docs-product-area Generation` under the `@libar-docs` marker), ensuring
the annotation matches the other files' `@libar-docs` tag style and
machine-parsable spacing.

In `@src/taxonomy/claude-section-values.ts`:
- Around line 1-18: The file-level JSDoc in
src/taxonomy/claude-section-values.ts is missing the required `@libar-docs` opt-in
marker; update the top-of-file comment block (above CLAUDE_SECTION_VALUES and
ClaudeSectionValue) to include the `@libar-docs` tag so the file is picked up by
the pattern extraction scanner, preserving the existing description and
annotations while inserting "@libar-docs" in that JSDoc header.

In `@tests/features/behavior/cli/process-api-reference.feature`:
- Around line 100-113: The scenario currently only asserts schema groups are
non-empty and never exercises showHelp(), so update the test to render and
inspect help output: add a step that calls the showHelp() function (or the CLI
help command runner used in tests) after the schema is loaded, capture its
output, and assert that the output contains the expected option names from each
group (globalOptions, outputModifiers, listFilters, sessionOptions) and basic
formatting tokens (option flags, descriptions, and a usage/help header). Locate
the test scenario and the step definitions that implement Given "the CLI schema
is loaded" and add/implement When "I render the help" and Then assertions
verifying showHelp() output includes specific option flags and formatted lines
for each schema group.
- Around line 51-98: The feature currently only checks the static schema and
never validates it against the actual parser; update the tests so the
parser-sync invariant exercises parseArgs() directly: add a scenario (or modify
existing ones) that calls parseArgs() to collect the set of recognized flags and
then assert that this set exactly matches the flags in the loaded CLI schema
(the step that loads the schema), ensuring any extra/missing flags are detected;
reference the parseArgs() function and the existing "CLI schema is loaded" step
(and the parser-sync rule) when adding the step definitions that compare the two
sets.
- Around line 12-16: The Rule blocks in the feature (notably the "Rule:
Generated reference file contains all three table sections" that lists the
Invariant "PROCESS-API-REFERENCE.md contains Global Options, Output Modifiers,
and List Filters tables") are missing the required **Rationale:** and **Verified
by:** subsections; update each Rule block (including the other Rule sections
referenced at the ranges corresponding to lines ~51-55 and ~100-103) to include
a brief **Rationale:** explaining why the invariant is required and a concise
**Verified by:** stating how the invariant will be checked (e.g., step or script
name that validates the generated PROCESS-API-REFERENCE.md contains those
tables), ensuring the three Rule blocks are complete and follow the repo
convention.
- Around line 1-6: The feature file is missing the required planning metadata
tags; add `@libar-docs-quarter`:<quarter> and `@libar-docs-team`:<team> to the
feature tag block (alongside the existing `@libar-docs`,
`@libar-docs-pattern`:ProcessApiReferenceTests,
`@libar-docs-implements`:ProcessApiHybridGeneration, and
`@libar-docs-status`:completed) so the feature satisfies the feature-spec
contract; ensure the two new tags are placed in the feature file header (not in
TypeScript) and use the canonical tag names `@libar-docs-quarter` and
`@libar-docs-team` with appropriate values.

In `@tests/features/behavior/codecs/convention-extractor.feature`:
- Around line 174-182: The two consecutive Gherkin assertions "Then the first
table row has Type value with escaped unions" and "Then the first table row has
Default value with quotes" should use "And" instead of "Then" to follow Gherkin
convention and avoid step-binding issues; update those step lines in the
"TypeScript table with escaped union pipes preserves full cell values" scenario
so the first assertion remains "Then ..." and the subsequent two lines begin
with "And ...".

In `@tests/features/behavior/codecs/generated-doc-quality.feature`:
- Around line 38-50: The Rule block titled "ARCHITECTURE-TYPES leads with type
definitions" is missing a "**Verified by:**" subsection; add a "**Verified
by:**" line inside that Rule block (ideally immediately after the Rationale
paragraph) to indicate who/what verifies the rule (e.g., reviewer name or test
automation), ensuring it sits before the acceptance-criteria tags and Scenario
definitions so the metadata is present for tooling that reads the Rule.
- Around line 51-64: The Rule block titled "Product area docs have a generated
table of contents" is missing the required "**Verified by:**" metadata; edit the
Rule block (the text starting "Rule: Product area docs have a generated table of
contents") and add a "**Verified by:**" line (e.g., "**Verified by:** <team or
role>") alongside the existing Invariant/Rationale lines so the rule includes
the verifier information for the Scenario "Product area doc with multiple
sections gets a TOC".
- Around line 16-29: Add a missing "**Verified by:**" subsection to the Rule
block titled "Behavior-specs renderer does not duplicate convention table
content" so the rule contains the required triplet of sections (**Invariant:**,
**Rationale:**, **Verified by:**); update the Rule header in
generated-doc-quality.feature (the block that includes the Invariant and
Rationale lines) by inserting a concise "**Verified by:**" line describing
who/what verifies the rule (e.g., test name or reviewer), ensuring the new
section follows the Rationale line and matches formatting of other Rule blocks
in the repo.
- Around line 65-80: The Rule block titled "Generation compact is
self-sufficient" is missing a "**Verified by:**" subsection; update the Rule
header to include a "**Verified by:**" line describing who or what verifies the
rule (e.g., QA team or automated test) so the rule metadata is complete—edit the
Rule block containing "Generation compact is self-sufficient" and add a
"**Verified by:**" entry directly under the Rule title (near the existing
**Invariant:** and **Rationale:** lines) to match the project's rule metadata
format.

In `@tests/features/doc-generation/architecture-doc-refactoring.feature`:
- Around line 95-98: Two identical scenarios assert the same behavior: the "Data
Flow Diagrams section is a pointer" scenario using the steps "When reading the
'Data Flow Diagrams' section" and "Then the section contains
'ARCHITECTURE-TYPES.md'". Remove the duplicated scenario (keep only one
instance) or consolidate them into a single scenario to avoid duplicate
assertions; specifically locate the scenario named "Data Flow Diagrams section
is a pointer" and delete the redundant copy so the feature file contains one
test that verifies the "Data Flow Diagrams" section contains
"ARCHITECTURE-TYPES.md".
- Around line 1-5: The feature file is missing required metadata tags: add an
appropriate `@libar-docs-quarter`:<quarter> tag (e.g., Q1-2026 or whatever
timeline applies) and an `@libar-docs-team`:<team-name> tag at the top alongside
existing tags (such as `@libar-docs`, `@libar-docs-pattern`, `@libar-docs-status`,
`@libar-docs-product-area`) so the feature conforms to the feature-spec metadata
contract; do this in the .feature file (not in TypeScript) near the other
`@libar-docs-`* tags.
- Line 15: The Rule blocks (starting with "Rule: Product area pointer
replacements link to covering documents" and the other Rule: entries in this
feature file) are missing the required structured sections; update each Rule:
block to include three sub-sections named "**Invariant:**", "**Rationale:**",
and "**Verified by:**" with concise content: state the invariant condition under
"**Invariant:**", explain why it exists under "**Rationale:**", and list the
verification approach or acceptance criteria under "**Verified by:**". Ensure
every Rule: block in this feature file follows that exact structure and tone so
the file meets the repository's Gherkin contract.

In `@tests/steps/behavior/cli/process-api-reference.steps.ts`:
- Around line 223-307: The tests currently only assert against CLI_SCHEMA (using
schemaFlagsFor and direct CLI_SCHEMA access) and never invoke the real parser or
showHelp, so they give false positives; update the RuleScenarios to call the
actual parser and help renderer (e.g., invoke parseArgs(...) with representative
args and call showHelp(...) or the function that returns rendered help text) and
assert that the parser/help outputs match CLI_SCHEMA: for the flag coverage
scenarios replace the expect(flags).toContain(...) checks with comparisons
between schemaFlagsFor(...) and the flags returned by parseArgs or the help
output parser, and for the "all schema groups contain at least one option"
scenario parse the help output (or call the function that returns structured
help data) and assert each group returned by showHelp/parseHelp has
options.length > 0; use the existing helpers schemaFlagsFor, CLI_SCHEMA,
parseArgs, and showHelp identifiers to locate and wire the assertions.

In `@tests/steps/behavior/codecs/convention-extractor.steps.ts`:
- Around line 678-692: There is a duplicate step definition: both Then and And
define the same pattern 'the first table row has cell {string} with value
{string}' with identical implementation (using
state!.result[0]!.rules[0]!.tables[0]!.rows[0] and firstRow); remove the
And(...) block (the duplicate starting at the second occurrence) and keep the
Then(...) implementation so the step is only defined once; also scan for any
other identical step strings and remove duplicates to avoid conflicts.

---

Outside diff comments:
In `@src/generators/pipeline/transform-dataset.ts`:
- Around line 318-347: The current code uses unknownStatusSet to dedupe invalid
status values which causes warningCount to undercount repeated occurrences;
update the logic in the loop that checks pattern.status (and the analogous block
around the other occurrence) to increment a per-occurrence counter (e.g.,
unknownStatusCount) every time pattern.status exists and
!isKnownStatus(pattern.status), while still adding the status string to
unknownStatusSet for unique reporting; adjust any later uses of warningCount to
include unknownStatusCount so the summary reflects the total number of
invalid-status warnings, not just the number of distinct invalid values.

In `@src/renderable/codecs/convention-extractor.ts`:
- Around line 1-24: The file-level JSDoc in convention-extractor.ts is missing
the required `@libar-docs` opt-in marker; add the line "@libar-docs" to the top
JSDoc block (above the imports) so the pattern extractor will scan this module.
Ensure the marker appears in the existing block that documents this module (the
comment containing "Convention Extractor") and keep the rest of the description
intact so functions like parseBusinessRuleAnnotations and exported types
continue to be discovered.

In `@src/renderable/codecs/planning.ts`:
- Line 204: The import of RenderableDocumentOutputSchema is placed mid-file,
breaking the convention of keeping imports at the top; move the "import {
RenderableDocumentOutputSchema } from './shared-schema.js';" statement into the
main import block with the other imports (near the other top imports around
where existing import declarations are) and remove the duplicate/mid-file import
so that RenderableDocumentOutputSchema is only imported once before the
constants and codec implementations (e.g., used by the codec functions below).

In `@src/renderable/codecs/reference.ts`:
- Around line 667-679: The current dedupe uses seenNames keyed only by
shape.name which collapses distinct declarations with the same name; change
deduplication to use a composite key (e.g., name + file/module/source/path) so
shapes from different files aren’t lost: when building allShapes from
extractShapesFromDataset(config.shapeSources) and when merging selectorShapes
from filterShapesBySelectors(config.shapeSelectors) compute a uniqueKey for each
shape (for example `${shape.source || shape.filePath ||
shape.module}:${shape.name}`), store that in seenNames, and use it for both the
initial Set population and the membership checks/adds; apply the same
composite-key strategy to the product-area merge path as well so all merge
points use the same uniqueness criteria.

In `@src/renderable/codecs/reporting.ts`:
- Line 147: Move the import of RenderableDocumentOutputSchema from its current
location near the options constants and place it with the other imports at the
top import block so all imports are grouped together; update the top import
block to include "RenderableDocumentOutputSchema" from './shared-schema.js' and
remove the redundant import statement that currently follows the options
constants to restore conventional import ordering.

In `@src/renderable/codecs/session.ts`:
- Around line 85-112: The exported SessionCodecOptions flags
(includeAcceptanceCriteria, includeDeliverables, includeRelatedPatterns,
includeHandoffContext) are declared in
SessionCodecOptions/DEFAULT_SESSION_OPTIONS but never used in rendering; update
createSessionContextCodec to accept and propagate these flags into the rendering
pipeline and update buildSessionPhaseDetailDocument and buildSessionPatternList
(and any helper functions in the session rendering path around the 582-721
region) to accept a SessionCodecOptions parameter and conditionally include the
corresponding sections based on those flags (e.g., only append acceptance
criteria, deliverables, related patterns, or handoff context when the matching
option is true); alternatively, if those sections are not yet implemented,
remove the unused flags from SessionCodecOptions/DEFAULT_SESSION_OPTIONS to keep
the API consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 06a1b138-8013-46b9-915c-13be90782395

📥 Commits

Reviewing files that changed from the base of the PR and between a030534 and 1ac4421.

⛔ Files ignored due to path filters (54)

• .claude/settings.json is excluded by none and included by none
• .gitignore is excluded by none and included by none
• CLAUDE.md is excluded by none and included by none
• MAINTAINERS.md is excluded by none and included by none
• README.md is excluded by none and included by none
• _claude-md/CLAUDE-MODULES.md is excluded by none and included by none
• _claude-md/metadata.json is excluded by none and included by none
• _claude-md/workflow/fsm-handoff.md is excluded by none and included by none
• _claude-md/workflow/session-details.md is excluded by none and included by none
• _claude-md/workflow/session-workflows.md is excluded by none and included by none
• delivery-process.config.ts is excluded by none and included by none
• docs-generated/BUSINESS-RULES.md is excluded by !docs-generated/** and included by none
• docs-generated/TAXONOMY.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/annotation.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/configuration.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/core-types.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/data-api.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/generation.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/process.md is excluded by !docs-generated/** and included by none
• docs-generated/business-rules/validation.md is excluded by !docs-generated/** and included by none
• docs-generated/taxonomy/categories.md is excluded by !docs-generated/** and included by none
• docs-generated/taxonomy/format-types.md is excluded by !docs-generated/** and included by none
• docs-generated/taxonomy/metadata-tags.md is excluded by !docs-generated/** and included by none
• docs-live/DECISIONS.md is excluded by none and included by none
• docs-live/PRODUCT-AREAS.md is excluded by none and included by none
• docs-live/_claude-md/annotation/annotation-overview.md is excluded by none and included by none
• docs-live/_claude-md/architecture/architecture-codecs.md is excluded by none and included by none
• docs-live/_claude-md/architecture/architecture-types.md is excluded by none and included by none
• docs-live/_claude-md/architecture/reference-sample.md is excluded by none and included by none
• docs-live/_claude-md/configuration/configuration-overview.md is excluded by none and included by none
• docs-live/_claude-md/core-types/core-types-overview.md is excluded by none and included by none
• docs-live/_claude-md/data-api/data-api-overview.md is excluded by none and included by none
• docs-live/_claude-md/generation/generation-overview.md is excluded by none and included by none
• docs-live/_claude-md/process/process-overview.md is excluded by none and included by none
• docs-live/_claude-md/validation/validation-overview.md is excluded by none and included by none
• docs-live/decisions/adr-001-taxonomy-canonical-values.md is excluded by none and included by none
• docs-live/decisions/adr-002-gherkin-only-testing.md is excluded by none and included by none
• docs-live/decisions/adr-003-source-first-pattern-architecture.md is excluded by none and included by none
• docs-live/decisions/adr-004-session-workflow-commands.md is excluded by none and included by none
• docs-live/decisions/adr-005-codec-based-markdown-rendering.md is excluded by none and included by none
• docs-live/decisions/adr-006-single-read-model-architecture.md is excluded by none and included by none
• docs-live/decisions/adr-021-doc-generation-proof-of-concept.md is excluded by none and included by none
• docs-live/product-areas/ANNOTATION.md is excluded by none and included by none
• docs-live/product-areas/CONFIGURATION.md is excluded by none and included by none
• docs-live/product-areas/CORE-TYPES.md is excluded by none and included by none
• docs-live/product-areas/DATA-API.md is excluded by none and included by none
• docs-live/product-areas/GENERATION.md is excluded by none and included by none
• docs-live/product-areas/PROCESS.md is excluded by none and included by none
• docs-live/product-areas/VALIDATION.md is excluded by none and included by none
• docs-live/reference/ARCHITECTURE-CODECS.md is excluded by none and included by none
• docs-live/reference/ARCHITECTURE-TYPES.md is excluded by none and included by none
• docs-live/reference/PROCESS-API-REFERENCE.md is excluded by none and included by none
• docs-live/reference/REFERENCE-SAMPLE.md is excluded by none and included by none
• package.json is excluded by none and included by none

📒 Files selected for processing (67)

• delivery-process/specs/architecture-doc-refactoring.feature
• delivery-process/specs/claude-module-generation.feature
• delivery-process/specs/docs-consolidation-strategy.feature
• delivery-process/specs/docs-live-consolidation.feature
• delivery-process/specs/generated-doc-quality.feature
• delivery-process/specs/gherkin-patterns-restructure.feature
• delivery-process/specs/process-api-hybrid-generation.feature
• delivery-process/specs/process-state-api-relationship-queries.feature
• delivery-process/specs/publishing-relocation.feature
• delivery-process/specs/readme-rationalization.feature
• delivery-process/specs/reference-doc-showcase.feature
• delivery-process/specs/session-guides-module-source.feature
• delivery-process/specs/step-lint-vitest-cucumber.feature
• docs/ARCHITECTURE.md
• docs/GHERKIN-PATTERNS.md
• docs/INDEX.md
• docs/PROCESS-API.md
• docs/VALIDATION.md
• src/cli/cli-schema.ts
• src/cli/process-api.ts
• src/config/project-config-schema.ts
• src/extractor/gherkin-extractor.ts
• src/generators/built-in/codec-generators.ts
• src/generators/built-in/process-api-reference-generator.ts
• src/generators/built-in/reference-generators.ts
• src/generators/orchestrator.ts
• src/generators/pipeline/build-pipeline.ts
• src/generators/pipeline/transform-dataset.ts
• src/lint/process-guard/detect-changes.ts
• src/renderable/codecs/adr.ts
• src/renderable/codecs/architecture.ts
• src/renderable/codecs/business-rules.ts
• src/renderable/codecs/claude-module.ts
• src/renderable/codecs/composite.ts
• src/renderable/codecs/convention-extractor.ts
• src/renderable/codecs/index.ts
• src/renderable/codecs/patterns.ts
• src/renderable/codecs/planning.ts
• src/renderable/codecs/pr-changes.ts
• src/renderable/codecs/reference.ts
• src/renderable/codecs/reporting.ts
• src/renderable/codecs/requirements.ts
• src/renderable/codecs/session.ts
• src/renderable/codecs/taxonomy.ts
• src/renderable/codecs/timeline.ts
• src/renderable/codecs/validation-rules.ts
• src/renderable/generate.ts
• src/scanner/gherkin-ast-parser.ts
• src/taxonomy/claude-section-values.ts
• src/taxonomy/conventions.ts
• src/taxonomy/index.ts
• src/taxonomy/registry-builder.ts
• src/validation-schemas/doc-directive.ts
• src/validation-schemas/extracted-pattern.ts
• src/validation-schemas/master-dataset.ts
• tests/features/behavior/cli/process-api-reference.feature
• tests/features/behavior/codecs/convention-extractor.feature
• tests/features/behavior/codecs/generated-doc-quality.feature
• tests/features/behavior/codecs/reference-codec-diagrams.feature
• tests/features/behavior/codecs/reference-generators.feature
• tests/features/doc-generation/architecture-doc-refactoring.feature
• tests/steps/behavior/cli/process-api-reference.steps.ts
• tests/steps/behavior/codecs/convention-extractor.steps.ts
• tests/steps/behavior/codecs/generated-doc-quality.steps.ts
• tests/steps/behavior/codecs/reference-codec-diagrams.steps.ts
• tests/steps/behavior/codecs/reference-generators.steps.ts
• tests/steps/doc-generation/architecture-doc-refactoring.steps.ts

[coderabbitai]

Review continued from previous batch...

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/renderable/codecs/reference.ts (1)

664-701: ⚠️ Potential issue | 🟠 Major

Don’t deduplicate shapes by bare name.

Lines 670 and 876 use only shape.name as the identity key. Two distinct declarations like Config from different files/modules will collide, and one disappears from the rendered reference. Please switch both paths to a source-qualified key instead of a name-only key.

Also applies to: 877-907

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/reference.ts` around lines 664 - 701, The code
currently deduplicates shapes using only shape.name (seenNames), which collapses
distinct shapes with the same name from different files/modules; change
deduplication to use a source-qualified key (e.g.,
`${shape.name}::${shape.source || shape.filePath || shape.moduleId}`) everywhere
name-only deduplication is used (the seenNames set and any other place that
checks shape.name, such as the selector merge and the include-tag merge and the
similar block around buildShapeSections and the later 876–907 region). Replace
the Set<string> seenNames with a Set of these composite keys (rename to
seenKeys), compute the key via a small helper (e.g., makeShapeKey(shape)) and
use that helper whenever adding/checking so distinct declarations with the same
name do not collide while preserving current merge logic around
extractShapesFromDataset, filterShapesBySelectors, dataset.patterns and
buildShapeSections.

♻️ Duplicate comments (1)

src/renderable/codecs/business-rules.ts (1)

434-434: ⚠️ Potential issue | 🟡 Minor

The NEXT_HEADER_PATTERN regex bug remains unfixed.

The ^\| branch cannot match indented table rows because \n\s* consumes whitespace before the anchor check. This causes tables with leading whitespace (e.g., \n | table |) to fail matching.

🐛 Proposed fix

-const NEXT_HEADER_PATTERN = /\n\s*(\*\*[A-Z]|^\|)/m;
+const NEXT_HEADER_PATTERN = /\n\s*(?:\*\*[A-Z]|\|)/m;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/renderable/codecs/business-rules.ts` at line 434, The NEXT_HEADER_PATTERN
regex incorrectly uses the ^ anchor inside the alternation causing indented
table rows to miss matches; update NEXT_HEADER_PATTERN so the pipe branch
matches after optional whitespace (e.g., replace /\n\s*(\*\*[A-Z]|^\|)/m with a
pattern that either removes the ^ or uses a lookahead such as
/\n\s*(\*\*[A-Z]|\|)/m or /\n(?=\s*(\*\*[A-Z]|\|))/m so that '\n  | table |' is
correctly recognized; change the constant NEXT_HEADER_PATTERN accordingly and
run tests that cover indented table rows and header detection.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/generators/built-in/process-api-reference-generator.ts`:
- Around line 93-109: Update the generate method signature on class
ProcessApiReferenceGeneratorImpl to match the DocumentGenerator interface by
replacing the parameter type readonly unknown[] with readonly ExtractedPattern[]
and import ExtractedPattern from the types module; specifically change
generate(_patterns: readonly unknown[], _context: GeneratorContext) to
generate(_patterns: readonly ExtractedPattern[], _context: GeneratorContext) and
add the corresponding import so the class (ProcessApiReferenceGeneratorImpl)
explicitly conforms to the interface.

In `@src/renderable/codecs/reference.ts`:
- Around line 943-949: The TOC is being inserted after the first separator
(firstSepIdx) which can be the separator added right after config.preamble,
causing the TOC to appear before the generated intro; change the insertion logic
to locate the separator that follows the intro block instead of the very first
separator. Specifically, when tocBlocks produced by
buildTableOfContents(sections) is non-empty, find the index of the intro block
(e.g., const introIdx = sections.findIndex(s => s.type === 'intro') or otherwise
compute the intro boundary) and then find the separator after that (e.g., const
sepAfterIntro = sections.findIndex((s, i) => i > introIdx && s.type ===
'separator')), and splice tocBlocks at sepAfterIntro + 1 (falling back to
firstSepIdx or end if no intro/separator found); update the code paths that
reference firstSepIdx, tocBlocks, buildTableOfContents and config.preamble
accordingly.
- Around line 1797-1809: The hardcoded byStatus label in
buildMasterDatasetViewsDiagram uses an incorrect vocabulary; update the byStatus
node string (the entry with byStatus["byStatus<br/>(... )"]) to list the
canonical lifecycle names in the correct/process-guard order (roadmap, active,
completed, deferred) so the diagram matches the dataset and the FSM rules
(roadmap → active → completed, deferred → roadmap).
- Around line 614-618: The preamble field from ReferenceDocConfig is only
honored inside decodeProductArea, so createReferenceCodec({ preamble, ... })
drops preamble for the normal decode path; to fix, apply the same
preamble-handling logic used by decodeProductArea in the standard decode branch
as well: extract/merge the preamble from the config and prepend or merge it into
the dataset/content before continuing with the regular decode flow. Update
createReferenceCodec (or the decoder entrypoint) so both branches (productArea
and non-productArea) invoke the preamble application step, keeping
decodeProductArea unchanged and reusing its preamble behavior.

---

Outside diff comments:
In `@src/renderable/codecs/reference.ts`:
- Around line 664-701: The code currently deduplicates shapes using only
shape.name (seenNames), which collapses distinct shapes with the same name from
different files/modules; change deduplication to use a source-qualified key
(e.g., `${shape.name}::${shape.source || shape.filePath || shape.moduleId}`)
everywhere name-only deduplication is used (the seenNames set and any other
place that checks shape.name, such as the selector merge and the include-tag
merge and the similar block around buildShapeSections and the later 876–907
region). Replace the Set<string> seenNames with a Set of these composite keys
(rename to seenKeys), compute the key via a small helper (e.g.,
makeShapeKey(shape)) and use that helper whenever adding/checking so distinct
declarations with the same name do not collide while preserving current merge
logic around extractShapesFromDataset, filterShapesBySelectors, dataset.patterns
and buildShapeSections.

---

Duplicate comments:
In `@src/renderable/codecs/business-rules.ts`:
- Line 434: The NEXT_HEADER_PATTERN regex incorrectly uses the ^ anchor inside
the alternation causing indented table rows to miss matches; update
NEXT_HEADER_PATTERN so the pipe branch matches after optional whitespace (e.g.,
replace /\n\s*(\*\*[A-Z]|^\|)/m with a pattern that either removes the ^ or uses
a lookahead such as /\n\s*(\*\*[A-Z]|\|)/m or /\n(?=\s*(\*\*[A-Z]|\|))/m so that
'\n  | table |' is correctly recognized; change the constant NEXT_HEADER_PATTERN
accordingly and run tests that cover indented table rows and header detection.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8958621e-e1aa-437c-bf71-ba2ad87d0d7d

📥 Commits

Reviewing files that changed from the base of the PR and between 1ac4421 and 8a96d44.

📒 Files selected for processing (3)

• src/generators/built-in/process-api-reference-generator.ts
• src/renderable/codecs/business-rules.ts
• src/renderable/codecs/reference.ts

[darko-mijic]

@coderabbitai Thank you for the thorough review. Here's our response to each comment group:

Addressed (10 comments)

The following comments identified valid issues and have been fixed:

Comment	File	Fix
003	generated-doc-quality.feature	Reconciled threshold: 5+ KB → 4+ KB to match Rule invariant
008	session-guides-module-source.feature	Fixed deliverable location: session-workflows.md → fsm-handoff.md
013	VALIDATION.md	Fixed severity count: (8 error, 4 warning) → (9 error, 3 warning)
014	VALIDATION.md	Added text language label to unlabeled code block
021	business-rules.ts	Fixed regex alternation: ^| anchor disconnected from \n\s* prefix
034	claude-section-values.ts	Added missing @libar-docs opt-in marker
035	convention-extractor.feature	Fixed Then → And for consecutive assertions
040	convention-extractor.steps.ts	Removed duplicate And step definition
046	INDEX.md	Fixed CHANGELOG.md line count: 1-26 → 1-31
053	architecture-doc-refactoring.feature	Removed duplicate "Data Flow Diagrams" scenario

Acknowledged — Deferred (13 comments)

These identify pre-existing documentation/implementation gaps not introduced by this PR. Tracked for future work:

• 005, 022, 023, 025, 027, 028, 029, 031, 033: Codec header JSDoc documents options or output structures that differ from actual implementation. These are aspirational docs from initial codec design — aligning them is a separate cleanup task.
• 049, 050, 054: Process API reference tests verify generator output and CLI schema sync, not parser execution. Enhanced integration tests that exercise parseArgs() and showHelp() directly are a separate scope.
• 042: Section Disposition line spans are internally consistent and non-overlapping. Verifying against the original pre-refactoring document requires that document as input.

Not Applicable (31 comments)

Tags are optional (comments 001, 004, 006, 007, 041, 043, 044, 045, 047, 051)

@libar-docs-team and @libar-docs-quarter are optional per the tag registry (src/taxonomy/registry-builder.ts — neither has required: true). Only 1 of 61 spec files in this project uses them. No validator enforces their presence. These are planning metadata tags used by the consumer monorepo, not required for this package's specs.

JSDoc colon format is intentional (comments 015, 019, 024, 030, 032)

@libar-docs-product-area:Generation uses colon syntax consistently across all codec JSDoc annotations. The space-separated format in the registry example applies to Gherkin feature file tags. JSDoc tags and Gherkin tags are parsed by different extractors. Changing JSDoc annotations without verifying TypeScript scanner compatibility would risk silent breakage.

Verified-by sections are aspirational (comments 036, 037, 038, 039, 048, 052)

**Verified by:** in Rule blocks is a documentation guideline but is not machine-enforced — no validator, extractor, or DoD check requires it. Many existing specs across the project omit it. Adding it uniformly is a documentation quality initiative, not a PR blocker.

Factually incorrect assessments (10 comments)

• 002: The file does have Rule blocks and scenarios covering all deliverables (lines 42–106 contain 2 Rules with 4 scenarios).
• 009: # banner lines at lines 76–78 are valid Gherkin comments between blocks (after Background, before Rule), not inside descriptions. The #-in-description parser trap only applies inside Feature/Rule description text.
• 010: "Planning + Design" is an intentional fourth session type, explicitly documented in CLAUDE.md's "Session type determines artifacts and FSM changes" section.
• 011: The quick reference table in GHERKIN-PATTERNS.md is accurately scoped for its purpose.
• 012: The relative path ../docs-live/reference/PROCESS-API-REFERENCE.md is correct — this is a cross-directory reference from docs/ to docs-live/.
• 016: The config note correctly states .ts only — delivery-process.config.ts is the sole supported config format.
• 017: All four option groups (global, modifiers, filters, sessions) are intentionally included in help output.
• 018: The async Gherkin extractor does assign claudeModule, claudeSection, and claudeTags at lines 268–270. Both sync and async paths have full parity.
• 020: ADR output file naming in header docs is correct.
• 026: The preamble field exists in the TypeScript interface and is used in the implementation (reference.ts line 796).

[coderabbitai]

@darko-mijic: Thank you for the detailed and well-structured response — this is exactly the kind of context that helps calibrate future reviews. Here's my summary:

Addressed (10 fixes): All confirmed and noted. The fixes for comment 021 (regex anchor), 035 (Then → And), 040 (duplicate step), and 053 (duplicate scenario) in particular were the most impactful corrections.

Deferred (13 items): Understood. Aspirational codec header docs vs. actual implementation is a valid separation of concerns, and the enhanced parser integration tests (049, 050, 054) are appropriately scoped to a future task.

Not Applicable (31 items): The explanations are clear and I'll record the key clarifications as learnings:

• JSDoc colon format: The @libar-docs-product-area:Generation colon syntax is correct for TypeScript scanner extraction — different from the space-separated Gherkin tag format. These are parsed by separate extractors.
• Optional tags: @libar-docs-team and @libar-docs-quarter have no required: true in the registry and are consumer-monorepo planning metadata, not enforced in this package.
• Verified-by sections: Aspirational documentation guideline, not machine-enforced or a PR blocker.
• Factual corrections: Accepted across all 10 points — particularly the async extractor parity (018), preamble field existence (026), and # banner comments being valid between blocks not inside descriptions (009).

(ﾉ◕ヮ◕)ﾉ*:･ﾟ✧

---

✏️ Learnings added

Learnt from: darko-mijic
URL: https://github.com/libar-dev/delivery-process/pull/32

Timestamp: 2026-03-06T02:26:14.460Z
Learning: In the delivery-process repository, `libar-docs-product-area:Generation` uses colon syntax (no space) in TypeScript JSDoc codec annotations. This is intentional and differs from the space-separated format used in Gherkin feature file tags. JSDoc tags and Gherkin tags are parsed by separate extractors (TypeScript scanner vs. Gherkin extractor). Do not flag colon-syntax JSDoc product-area annotations as errors.

---

Learnt from: darko-mijic
URL: https://github.com/libar-dev/delivery-process/pull/32

Timestamp: 2026-03-06T02:26:14.460Z
Learning: In the delivery-process repository, `libar-docs-team` and `libar-docs-quarter` are optional planning metadata tags per the tag registry (src/taxonomy/registry-builder.ts — neither has `required: true`). They are used by the consumer monorepo, not enforced in this package. Only 1 of 61 spec files uses them. Do not flag their absence as a missing required field.

---

Learnt from: darko-mijic
URL: https://github.com/libar-dev/delivery-process/pull/32

Timestamp: 2026-03-06T02:26:14.460Z
Learning: In the delivery-process repository, `**Verified by:**` sections in Gherkin Rule blocks are an aspirational documentation guideline. They are not machine-enforced by any validator, extractor, or DoD check. Many existing specs omit them. Do not treat their absence as a PR blocker.

---

Learnt from: darko-mijic
URL: https://github.com/libar-dev/delivery-process/pull/32

Timestamp: 2026-03-06T02:26:14.460Z
Learning: In the delivery-process repository, `#` banner comment lines in Gherkin feature files are valid between top-level blocks (e.g., after Background, before Rule). The concern about `#` characters in description text only applies when they appear inside Feature/Rule description body text (which confuses some parsers). Comments between blocks are valid Gherkin syntax.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

✅ Actions performed

Comments resolved. Auto-approval is disabled; enable reviews.request_changes_workflow to approve automatically.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (5)

delivery-process/specs/generated-doc-quality.feature (1)

34-40: ⚠️ Potential issue | 🟠 Major

Add the missing Rule for the TOC deliverable.

The Background marks four deliverables complete, but this file only defines three Rule blocks. The TOC behavior already exists in tests/features/behavior/codecs/generated-doc-quality.feature, Lines 51-63, so the executable spec and this planning spec have drifted. Add a matching Rule/Scenario here or stop listing that item as complete in the deliverables table.

As per coding guidelines, delivery-process/**/*.feature: Ensure scenarios define clear acceptance criteria.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@delivery-process/specs/generated-doc-quality.feature` around lines 34 - 40,
The Background table lists the "Add generated TOC block to product area doc
headers" deliverable as complete but there is no matching Rule/Scenario in this
file; either add a Rule/Scenario that mirrors the executable spec in
tests/features/behavior/codecs/generated-doc-quality.feature (see the TOC
scenario at lines ~51-63) or remove that deliverable row from the table; when
adding the Rule, place it alongside the other Rules in this feature, give it the
same title "Add generated TOC block to product area doc headers", include the
same acceptance steps and expectations from the referenced executable spec so
the planning spec stays in sync and meets the delivery-process/**/*.feature
guideline for clear acceptance criteria.

docs/VALIDATION.md (2)

219-224: ⚠️ Potential issue | 🟡 Minor

Add a language to the scan-scope fence.

This block is still unlabeled, so markdownlint MD040 will keep firing. text is enough here.

Suggested edit

-```
+```text
 Feature files:  tests/features/**/*.feature
                 delivery-process/specs/**/*.feature
                 delivery-process/decisions/**/*.feature
 Step files:     tests/steps/**/*.steps.ts

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/VALIDATION.md around lines 219 - 224, The unlabeled fenced code block
containing the scan-scope list should be marked with a language to satisfy
markdownlint MD040; edit the block in VALIDATION.md that starts with the triple
backticks before "Feature files:" (the scan-scope fence) and change it to a
labeled fence (e.g., add "text" after the opening ```), leaving the block
contents unchanged.

</details>

---

`94-168`: _⚠️ Potential issue_ | _🟡 Minor_

**`lint-steps` is still documenting the wrong rule set.**

`src/lint/steps/types.ts:32-117` currently defines 13 `STEP_LINT_RULES` (9 `error`, 4 `warning`), including the `pair-resolver` warning, but this section only documents 12. Please sync the totals and rule tables with the actual registry so the docs match the implementation.

 
As per coding guidelines "`docs/**/*.md`: Ensure documentation is clear, accurate, and up-to-date."

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/VALIDATION.md` around lines 94 - 168, The docs' Feature/Step/Cross-File
rules summary is out of sync with the implementation: STEP_LINT_RULES in
src/lint/steps/types.ts currently registers 13 rules (9 error, 4 warning)
including the pair-resolver warning while VALIDATION.md lists 12 rules (9 error,
3 warning); update VALIDATION.md to reflect the actual registry (adjust the
totals line and the rule tables to include the missing rule entry and correct
severities/counts) or alternatively update STEP_LINT_RULES to match the
documented 12-rule set—locate the STEP_LINT_RULES constant and the
"pair-resolver" rule identifier to decide which side to change and make the
totals and tables consistent.
```

</details>

</blockquote></details>
<details>
<summary>delivery-process/specs/session-guides-module-source.feature (1)</summary><blockquote>

`135-149`: _⚠️ Potential issue_ | _🟠 Major_

**Don't model `Planning + Design` as a fourth session type.**

This turns a valid sequence of sessions into a new canonical type. Because this spec feeds generated workflow docs, the table should keep the session taxonomy to the actual per-session contracts and describe combined flows as sequencing, not as a separate row.

<details>
<summary>Suggested edit</summary>

```diff
-    **Invariant:** Four session types exist, each with defined input, output, and
+    **Invariant:** Three 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.
@@
-    | Planning + Design | Pattern brief | Spec + stubs | Creates roadmap |
+    A combined planning→design workflow is a sequence of the Planning and Design
+    sessions above, not a separate session type.
```
</details>

 
Based on learnings Session planning must follow Decision Tree: planning → optional design → implementation, with output and FSM changes per session type.

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@delivery-process/specs/session-guides-module-source.feature` around lines 135
- 149, The table introduces an invalid fourth canonical session type "Planning +
Design" which conflates sequencing with a distinct contract; remove the
"Planning + Design" row from the table and instead document the allowed sequence
(planning → optional design → implementation) as a sequencing note in the
surrounding text (e.g., under the Invariant or Rationale); ensure the table only
lists the three atomic session types "Planning", "Design", and "Implementation"
with their Input, Output, and FSM Change, and add a short sentence describing
that combined flows are modeled as ordered sessions rather than a new session
type.
```

</details>

</blockquote></details>
<details>
<summary>docs/INDEX.md (1)</summary><blockquote>

`25-30`: _⚠️ Potential issue_ | _🟡 Minor_

**Quick nav and detailed TOC still disagree on line ranges.**

These entries now say `ARCHITECTURE.md` is `1-358` and `PROCESS-API.md` is `1-464`, but the detailed sections below still use the old `1-1638` and `1-507` spans. Please update the detailed TOC too so the index stays internally consistent.

 
As per coding guidelines "`docs/**/*.md`: Ensure documentation is clear, accurate, and up-to-date."

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/INDEX.md` around lines 25 - 30, The quick nav TOC lists updated line
ranges for ARCHITECTURE.md (1-358) and PROCESS-API.md (1-464) but the detailed
TOC still shows the old spans (e.g., ARCHITECTURE.md 1-1638 and PROCESS-API.md
1-507); update the detailed TOC entries to match the quick nav ranges (adjust
the spans for ARCHITECTURE.md and PROCESS-API.md to 1-358 and 1-464
respectively) so the INDEX.md line-range references are internally consistent
with the quick nav; verify other file entries (SESSION-GUIDES.md,
GHERKIN-PATTERNS.md, PROCESS-GUARD.md, VALIDATION.md) match between quick nav
and detailed TOC and correct any discrepancies.
```

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @delivery-process/specs/generated-doc-quality.feature:

• Around line 77-99: The feature currently asserts an invariant for "Each
  product area compact" and "All area compacts" but only provides a scenario
  exercising the Generation compact; update the spec so it matches the intent:
  either (A) narrow the invariant/“Verified by:” text to only reference Generation
  (replace "Each product area compact" / "All area compacts" with "Generation
  compact") and keep the existing Scenario: "Generation compact contains codec
  inventory and pipeline summary", or (B) add parallel acceptance scenarios for
  each other product area (create scenarios mirroring "Scenario: Generation
  compact contains codec inventory and pipeline summary" for each area compact) so
  the Invariant/Verified by statements remain accurate; make the change in the
  same feature around the "Invariant", "Verified by" text and the existing
  "Scenario: Generation compact contains codec inventory and pipeline summary".

---

Duplicate comments:
In @delivery-process/specs/generated-doc-quality.feature:

• Around line 34-40: The Background table lists the "Add generated TOC block to
  product area doc headers" deliverable as complete but there is no matching
  Rule/Scenario in this file; either add a Rule/Scenario that mirrors the
  executable spec in tests/features/behavior/codecs/generated-doc-quality.feature
  (see the TOC scenario at lines ~51-63) or remove that deliverable row from the
  table; when adding the Rule, place it alongside the other Rules in this feature,
  give it the same title "Add generated TOC block to product area doc headers",
  include the same acceptance steps and expectations from the referenced
  executable spec so the planning spec stays in sync and meets the
  delivery-process/**/*.feature guideline for clear acceptance criteria.

In @delivery-process/specs/session-guides-module-source.feature:

• Around line 135-149: The table introduces an invalid fourth canonical session
  type "Planning + Design" which conflates sequencing with a distinct contract;
  remove the "Planning + Design" row from the table and instead document the
  allowed sequence (planning → optional design → implementation) as a sequencing
  note in the surrounding text (e.g., under the Invariant or Rationale); ensure
  the table only lists the three atomic session types "Planning", "Design", and
  "Implementation" with their Input, Output, and FSM Change, and add a short
  sentence describing that combined flows are modeled as ordered sessions rather
  than a new session type.

In @docs/INDEX.md:

• Around line 25-30: The quick nav TOC lists updated line ranges for
  ARCHITECTURE.md (1-358) and PROCESS-API.md (1-464) but the detailed TOC still
  shows the old spans (e.g., ARCHITECTURE.md 1-1638 and PROCESS-API.md 1-507);
  update the detailed TOC entries to match the quick nav ranges (adjust the spans
  for ARCHITECTURE.md and PROCESS-API.md to 1-358 and 1-464 respectively) so the
  INDEX.md line-range references are internally consistent with the quick nav;
  verify other file entries (SESSION-GUIDES.md, GHERKIN-PATTERNS.md,
  PROCESS-GUARD.md, VALIDATION.md) match between quick nav and detailed TOC and
  correct any discrepancies.

In @docs/VALIDATION.md:

• Around line 219-224: The unlabeled fenced code block containing the scan-scope
  list should be marked with a language to satisfy markdownlint MD040; edit the
  block in VALIDATION.md that starts with the triple backticks before "Feature
  files:" (the scan-scope fence) and change it to a labeled fence (e.g., add
  "text" after the opening ```), leaving the block contents unchanged.
• Around line 94-168: The docs' Feature/Step/Cross-File rules summary is out of
  sync with the implementation: STEP_LINT_RULES in src/lint/steps/types.ts
  currently registers 13 rules (9 error, 4 warning) including the pair-resolver
  warning while VALIDATION.md lists 12 rules (9 error, 3 warning); update
  VALIDATION.md to reflect the actual registry (adjust the totals line and the
  rule tables to include the missing rule entry and correct severities/counts) or
  alternatively update STEP_LINT_RULES to match the documented 12-rule set—locate
  the STEP_LINT_RULES constant and the "pair-resolver" rule identifier to decide
  which side to change and make the totals and tables consistent.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: ASSERTIVE

**Plan**: Pro

**Run ID**: `acfefe04-6b90-49c2-86a4-2a8b376e677a`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 8a96d44f15ceeb2d384684c97d2e288e6392503f and fde769829be13bdc6eb55e34c37966ceba11b5d4.

</details>

<details>
<summary>📒 Files selected for processing (8)</summary>

* `delivery-process/specs/generated-doc-quality.feature`
* `delivery-process/specs/session-guides-module-source.feature`
* `docs/INDEX.md`
* `docs/VALIDATION.md`
* `src/renderable/codecs/business-rules.ts`
* `src/taxonomy/claude-section-values.ts`
* `tests/features/doc-generation/architecture-doc-refactoring.feature`
* `tests/steps/doc-generation/architecture-doc-refactoring.steps.ts`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[coderabbitai]

Actionable comments posted: 25

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@delivery-process/specs/cli-recipe-codec.feature`:
- Around line 116-126: The invariant describes RecipeExample.commands as an
array of strings but the spec and stubs use per-step metadata via RecipeStep,
creating an inconsistency; update the invariant so CLI_SCHEMA's recipes field
defines RecipeGroup[] where each RecipeExample.commands is RecipeStep[] (not
string[]), and ensure the text mentions RecipeStep fields (e.g., command string,
optional comment, optional expectedOutput) while clarifying that this extension
is additive and does not change existing CLIOptionGroup types; adjust any
references to RecipeExample.commands accordingly to align the contract with the
RecipeStep model.

In `@delivery-process/specs/docs-consolidation-strategy.feature`:
- Around line 86-91: Update the feature scenarios so they expect generated
public reference output under docs-live/ instead of docs/; specifically change
the scenario "Convention tag produces a generated reference document" (and the
other similar scenarios referencing generated reference docs) to assert a
detailed docs-live/ file and a compact _claude-md/ file are produced, while
leaving the rest of the checks (that both contain the convention content
extracted from source JSDoc and that a ReferenceDocConfig entry matches the
convention tag) unchanged.
- Around line 139-159: The retention rule conflicts with the scope table: the
invariant names SESSION-GUIDES.md, GHERKIN-PATTERNS.md, PROCESS-API.md, and
PUBLISHING.md as fully manual while Phases 39–43 mark them as
trimmed/hybrid/relocated; update the spec so the invariant and the acceptance
Scenario align with the scope table. Either remove those filenames from the
"fully manual" list (leaving only true-manual docs like METHODOLOGY.md) or amend
the scope table/Phases 39–43 entries to mark them as retained; ensure the
Scenario "Retained documents have no generated equivalent" and the check for
ReferenceDocConfig reflect whichever choice.
- Around line 18-30: The document inconsistently references the number and
numbering of phases (mentions "6-phase consolidation" and "10 phases", and the
scope table lists "phases 1-6 plus 37-43"); pick the intended phase count
(either 6 or 10) and make all references consistent: update the summary header
phrase ("6-phase consolidation"), the later sentence that says "10 phases", and
the scope table entries (remove or renumber "37-43" and ensure it lists the
correct phase range such as "phases 1–6" or "phases 1–10"), and scan the nearby
section (the content around the current lines 33–47) to fix any remaining
mismatched mentions so the roadmap reads with a single, consistent phase count
and numbering.

In `@delivery-process/specs/docs-live-consolidation.feature`:
- Around line 91-95: Scenario title "docs-generated/ is empty after standard
generation" overstates the verification because the step "Then docs-generated/
contains no .md files" only checks for .md files; update either the title or the
assertion: either rename the scenario to "docs-generated/ contains no .md files
after standard generation" or replace the step with an explicit check that the
directory is absent or empty (e.g., assert "docs-generated/ does not exist" or
"docs-generated/ is empty") so the scenario's title and step(s) match the
intended post-consolidation state.
- Around line 59-64: The assertion at the end of the "Reference docs are
generated into docs-live/reference/" scenario is guarding the wrong legacy path;
change the negative check that currently verifies "docs-generated/docs/ does not
exist" to instead assert that "docs-generated/reference/ does not exist" so the
scenario fails if stale reference output is still emitted to the legacy
reference directory.
- Around line 66-72: The spec rule in docs-live-consolidation.feature conflicts
with the implementation: delivery-process.config.ts still routes the
claude-modules generator to the repo-root _claude-md, while the rule insists all
compact files live under docs-live/_claude-md/. Either narrow the feature rule
to only apply to architecture reference summaries (architecture-codecs,
architecture-types) or update delivery-process.config.ts to route the
claude-modules generator into docs-live/_claude-md/ (and adjust any references
to “_claude-md/” in the PR summary/spec accordingly); locate the rule text in
docs-live-consolidation.feature and the claude-modules generator config in
delivery-process.config.ts to apply the chosen change.

In `@delivery-process/specs/enhanced-index-generation.feature`:
- Around line 39-42: The acceptance criteria are contradictory: the Scope table
lists sources as “File system scan plus MasterDataset” while DD-2 and the
`documentEntries` behavior describe a static, no-I/O codec; pick a single source
model and make both places consistent. Decide whether the inventory is generated
from a FileSystem scan + MasterDataset or from static `documentEntries` (no
I/O), then update the Scope table entry and the DD-2 wording (and any scenario
text referencing `documentEntries`) to match that choice; also apply the same
change to the other affected scenario lines (the related entries around lines
61-62) so all scenarios and acceptance criteria are aligned.

In `@delivery-process/specs/procedural-guide-codec.feature`:
- Around line 214-220: The scenario asserts the wrong generated filename: the
ProceduralGuideCodec with ReferenceDocConfig produces
docs-live/reference/ANNOTATION-REFERENCE.md, not ANNOTATION-GUIDE.md; update the
feature scenario (the "Two separate guide files are generated" scenario) to
expect docs-live/reference/ANNOTATION-REFERENCE.md (keep the
SESSION-WORKFLOW-GUIDE.md expectation) so the test matches the configured
annotation output filename generated by ProceduralGuideCodec/ReferenceDocConfig.
- Around line 38-43: The feature text mixes two incompatible pipelines for
checklists and decision trees (SessionGuidesModuleSource vs docs-sources/*.md
loaded via loadPreambleFromMarkdown()), so pick one pipeline and update the spec
to reference only that source and its acceptance rules; e.g., if you choose
SessionGuidesModuleSource, change Solution/Scope and Rule 1/4 to state
checklists and decision trees are extracted from SessionGuidesModuleSource and
preserve the SESSION-GUIDES.md invariant, or if you choose docs-sources/*.md,
update Rule 2 and any references to extraction to use loadPreambleFromMarkdown()
and its acceptance criteria, and ensure all other affected blocks (lines noted:
54-67, 112-123, 152-190, 233-239) are made consistent with the single chosen
pipeline.

In `@delivery-process/stubs/cli-recipe-codec/cli-recipe-generator.ts`:
- Around line 297-313: The comment incorrectly points readers to
delivery-process.config.ts as the registration site; update the preamble to
state that although generatorOverrides in delivery-process.config.ts can
override outputDirectory, the actual registration for the "cli-recipe" generator
is done programmatically following the createProcessApiReferenceGenerator()
pattern in the built-in codec-generators registration module (i.e., where
built-in codec generators are registered), so change the example and wording to
reference that programmatic registration hook and remove the misleading
generatorOverrides-only claim.
- Around line 103-177: The functions buildRecipeSections and
buildNarrativeSections (and the generator exports
generate/createCliRecipeGenerator) are currently untyped (unknown) and must be
updated to the actual generator interfaces; change their signatures to use
SectionBlock[] for section arrays, implement generate(_patterns: readonly
unknown[], _context: GeneratorContext): Promise<GeneratorOutput>, and ensure
createCliRecipeGenerator(preamble: readonly SectionBlock[]): DocumentGenerator
returns an instance of CliRecipeGeneratorImpl which implements
DocumentGenerator; import and use the canonical types SectionBlock,
GeneratorOutput, DocumentGenerator, and GeneratorContext from the project's
types so the stub matches the real implementation at
src/generators/built-in/cli-recipe-generator.ts.

In `@delivery-process/stubs/cli-recipe-codec/recipe-data.ts`:
- Around line 109-113: COMMON_RECIPES, SESSION_WORKFLOW_NARRATIVES, and
EXAMPLE_PREAMBLE currently export concrete example payloads; remove those real
data objects from the module and replace each exported symbol with a stub that
throws new Error('PatternName not yet implemented - roadmap pattern') (e.g.,
export const COMMON_RECIPES = () => { throw new Error('COMMON_RECIPES not yet
implemented - roadmap pattern') }, or export const COMMON_RECIPES = (() => {
throw new Error('COMMON_RECIPES not yet implemented - roadmap pattern') })() )
so downstream code cannot import real examples; move the concrete examples
(startingASessionRecipe, findingWorkRecipe, narrative arrays, preamble text)
into JSDoc or a separate Markdown example section in the file rather than the
export surface and apply the same throw-only pattern to
SESSION_WORKFLOW_NARRATIVES and EXAMPLE_PREAMBLE.

In `@delivery-process/stubs/cli-recipe-codec/recipe-schema.ts`:
- Around line 211-244: Remove the duplicate, weakened CLISchemaExtended
interface and instead alias the canonical CLISchema: import the original
CLISchema (from src/cli/cli-schema.ts) and replace the interface declaration
`export interface CLISchemaExtended { ... }` with `export type CLISchemaExtended
= CLISchema;`, ensuring you no longer re-declare `globalOptions`,
`outputModifiers`, `listFilters`, `sessionOptions`, `recipes`, or
`commandNarratives` here so the concrete types from the source-of-truth are
preserved.

In `@delivery-process/stubs/enhanced-index-generation/index-codec-options.ts`:
- Around line 108-113: Update the JSDoc for documentEntries to remove any claim
that the codec merges entries with auto-discovered/generated documents from
MasterDataset; instead state that documentEntries is a static, explicit contract
(no filesystem or MasterDataset discovery), and clarify that MasterDataset
exposes pattern views rather than a document inventory so it is not used as a
source of documentEntries. Ensure the comment references the symbol
documentEntries and MasterDataset so readers know the intended static-only
contract and correct source-of-truth.

In `@delivery-process/stubs/enhanced-index-generation/index-codec.ts`:
- Line 101: The module currently invokes createIndexCodec during top-level
initialization by exporting IndexCodec = createIndexCodec(), which throws on
import; stop calling the throwing stub at module load by removing the immediate
invocation and instead export the factory or a thunk (e.g., export
createIndexCodec and/or export getIndexCodec/getIndexCodecInstance that calls
createIndexCodec at call time) so callers can opt-in to construction; update any
references to IndexCodec to call the factory/getter rather than rely on a
preconstructed instance.
- Around line 86-88: The createIndexCodec stub currently returns unknown and is
eagerly instantiated by export const IndexCodec = createIndexCodec(), which
causes import-time failure; change the signature of createIndexCodec to return
z.ZodCodec<MasterDatasetSchema, RenderableDocumentOutputSchema> (matching the
real contract and supporting .decode calls in generate.ts) and replace the eager
export with either no eager instantiation (remove export const IndexCodec) or
export a safe non-throwing placeholder codec from createIndexCodec that
implements decode (a minimal pass-through or runtime-safe stub) so the module
can be imported without throwing; update references to IndexCodec to call
createIndexCodec() lazily if needed.

In `@delivery-process/stubs/enhanced-index-generation/index-preamble-config.ts`:
- Line 211: Update the stale filename entry in the index preamble array: replace
occurrences of 'PUBLISHING.md' with the new 'MAINTAINERS.md' in the list items
(e.g., the array entry currently showing ['PUBLISHING.md', 'Maintainers',
'Release -- npm publishing']), and also scan and update the other matching
entries referenced (around the second occurrence at lines ~393-395) so the
generated index points to MAINTAINERS.md instead of the removed PUBLISHING.md.
- Around line 104-106: The SectionBlock 'table' variant is using a non-existent
headers property; update each table block (e.g., the object with type: 'table'
as const) to provide a columns property instead of headers so it matches the
SectionBlock table schema in src/renderable/schema.ts—replace headers: [...]
with columns: [...] for the blocks around the current change and the similar
block at the other occurrence (lines referenced in the review).

In `@delivery-process/stubs/error-guide-codec/enhanced-validation-options.ts`:
- Around line 118-126: The constant ENHANCED_DEFAULT_OPTIONS is typed with
Required<EnhancedValidationRulesCodecOptions>, which promotes the inherited
optional limits (from BaseCodecOptions/CodecLimits) to required but the literal
omits limits; fix by either adding a proper limits: CodecLimits value to
ENHANCED_DEFAULT_OPTIONS or change the typing to use "satisfies
EnhancedValidationRulesCodecOptions" so limits remains optional; update the
declaration for ENHANCED_DEFAULT_OPTIONS and ensure references to
EnhancedValidationRulesCodecOptions, BaseCodecOptions and CodecLimits are used
to construct or validate the limits value if you choose to add it.
- Line 40: Update the import for BaseCodecOptions in
enhanced-validation-options.ts to point to the repo root (use
../../../src/renderable/codecs/types/base.ts or
../../../src/renderable/codecs/types/base.js) so the type resolves correctly,
and fix the ENHANCED_DEFAULT_OPTIONS constant (typed as
Required<EnhancedValidationRulesCodecOptions>) by either adding a concrete
limits property of type CodecLimits to the object literal or loosening the type
wrapper (remove Required<> or make limits optional) so the missing limits field
no longer causes a TypeScript error; reference BaseCodecOptions,
EnhancedValidationRulesCodecOptions, ENHANCED_DEFAULT_OPTIONS, limits, and
CodecLimits when making the change.

In `@delivery-process/stubs/error-guide-codec/error-guide-config.ts`:
- Around line 215-237: Remove or reword the outdated registration snippet in the
comment block: the CONVENTION_VALUES example that lists 'process-guard-errors'
is obsolete because that value already exists; update the comment in
error-guide-config.ts to reflect the current state (either delete the entire
example block or replace it with a short note stating that
'process-guard-errors' is already included in CONVENTION_VALUES) and ensure
references to CONVENTION_VALUES and 'process-guard-errors' remain accurate.
- Around line 200-206: The mermaid node name "detectChanges" is ambiguous
compared to the exported functions used elsewhere; update the diagram to match
the real API names (e.g., replace the node with detectStagedChanges and/or
detectBranchChanges) or explicitly relabel it as a generic step like "change
detection" so readers won't assume a callable API; ensure the connected nodes
(deriveProcessState, validateChanges, ValidationResult) remain unchanged and the
label you choose aligns with the preamble/table terminology.

In `@delivery-process/stubs/procedural-guide-codec/load-preamble.ts`:
- Line 111: The import for SectionBlock in the procedural-guide-codec stubs is
using the wrong relative path; update the import statement that currently reads
"import type { SectionBlock } from '../../src/renderable/schema.js';" to use the
correct relative path "../../../src/renderable/schema.js" in all three
procedural-guide-codec stub files (the load-preamble, procedural-codec-options
and procedural-codec stubs) so the SectionBlock type resolves to the actual
schema module.

In `@delivery-process/stubs/procedural-guide-codec/procedural-codec-options.ts`:
- Around line 63-73: The Annotation Guide column in the
procedural-codec-options.ts stub is out of sync with the actual
ReferenceDocConfig used in delivery-process.config.ts; update the Annotation
Guide fields to match the real config by setting title to "Annotation Reference
Guide", setting conventionTags to ['annotation-system'], removing or leaving
includeTags empty (no includeTags), and changing claudeMdSection to 'annotation'
(verify docsFilename/claudeMdFilename remain correct) so the codec routes this
document through the annotation extraction path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3da80ecf-9a0a-4858-b856-d7954a18f39b

📥 Commits

Reviewing files that changed from the base of the PR and between fc60b6b and 5069717.

⛔ Files ignored due to path filters (43)

• delivery-process.config.ts is excluded by none and included by none
• docs-live/ARCHITECTURE.md is excluded by none and included by none
• docs-live/BUSINESS-RULES.md is excluded by none and included by none
• docs-live/CHANGELOG-GENERATED.md is excluded by none and included by none
• docs-live/INDEX.md is excluded by none and included by none
• docs-live/PRODUCT-AREAS.md is excluded by none and included by none
• docs-live/TAXONOMY.md is excluded by none and included by none
• docs-live/VALIDATION-RULES.md is excluded by none and included by none
• docs-live/_claude-md/annotation/annotation-reference.md is excluded by none and included by none
• docs-live/_claude-md/architecture/architecture-codecs.md is excluded by none and included by none
• docs-live/_claude-md/architecture/reference-sample.md is excluded by none and included by none
• docs-live/_claude-md/generation/generation-overview.md is excluded by none and included by none
• docs-live/_claude-md/process/process-overview.md is excluded by none and included by none
• docs-live/_claude-md/validation/process-guard.md is excluded by none and included by none
• docs-live/_claude-md/workflow/session-workflow-guide.md is excluded by none and included by none
• docs-live/business-rules/annotation.md is excluded by none and included by none
• docs-live/business-rules/configuration.md is excluded by none and included by none
• docs-live/business-rules/core-types.md is excluded by none and included by none
• docs-live/business-rules/data-api.md is excluded by none and included by none
• docs-live/business-rules/generation.md is excluded by none and included by none
• docs-live/business-rules/process.md is excluded by none and included by none
• docs-live/business-rules/validation.md is excluded by none and included by none
• docs-live/product-areas/CORE-TYPES.md is excluded by none and included by none
• docs-live/product-areas/GENERATION.md is excluded by none and included by none
• docs-live/product-areas/PROCESS.md is excluded by none and included by none
• docs-live/product-areas/VALIDATION.md is excluded by none and included by none
• docs-live/reference/ANNOTATION-REFERENCE.md is excluded by none and included by none
• docs-live/reference/ARCHITECTURE-CODECS.md is excluded by none and included by none
• docs-live/reference/PROCESS-API-RECIPES.md is excluded by none and included by none
• docs-live/reference/PROCESS-GUARD-REFERENCE.md is excluded by none and included by none
• docs-live/reference/REFERENCE-SAMPLE.md is excluded by none and included by none
• docs-live/reference/SESSION-WORKFLOW-GUIDE.md is excluded by none and included by none
• docs-live/taxonomy/categories.md is excluded by none and included by none
• docs-live/taxonomy/format-types.md is excluded by none and included by none
• docs-live/taxonomy/metadata-tags.md is excluded by none and included by none
• docs-live/validation/error-catalog.md is excluded by none and included by none
• docs-live/validation/fsm-transitions.md is excluded by none and included by none
• docs-live/validation/protection-levels.md is excluded by none and included by none
• docs-sources/annotation-guide.md is excluded by none and included by none
• docs-sources/index-navigation.md is excluded by none and included by none
• docs-sources/process-api-recipes.md is excluded by none and included by none
• docs-sources/session-workflow-guide.md is excluded by none and included by none
• package.json is excluded by none and included by none

📒 Files selected for processing (44)

• delivery-process/specs/cli-recipe-codec.feature
• delivery-process/specs/docs-consolidation-strategy.feature
• delivery-process/specs/docs-live-consolidation.feature
• delivery-process/specs/enhanced-index-generation.feature
• delivery-process/specs/error-guide-codec.feature
• delivery-process/specs/procedural-guide-codec.feature
• delivery-process/specs/session-guides-module-source.feature
• delivery-process/stubs/cli-recipe-codec/cli-recipe-generator.ts
• delivery-process/stubs/cli-recipe-codec/recipe-data.ts
• delivery-process/stubs/cli-recipe-codec/recipe-schema.ts
• delivery-process/stubs/enhanced-index-generation/index-codec-options.ts
• delivery-process/stubs/enhanced-index-generation/index-codec.ts
• delivery-process/stubs/enhanced-index-generation/index-preamble-config.ts
• delivery-process/stubs/error-guide-codec/convention-annotation-example.ts
• delivery-process/stubs/error-guide-codec/enhanced-validation-options.ts
• delivery-process/stubs/error-guide-codec/error-guide-config.ts
• delivery-process/stubs/procedural-guide-codec/annotation-guide-preamble.ts
• delivery-process/stubs/procedural-guide-codec/load-preamble.ts
• delivery-process/stubs/procedural-guide-codec/procedural-codec-options.ts
• delivery-process/stubs/procedural-guide-codec/procedural-codec.ts
• delivery-process/stubs/procedural-guide-codec/session-guide-preamble.ts
• docs/ANNOTATION-GUIDE.md
• docs/DOCS-GAP-ANALYSIS.md
• docs/PROCESS-API.md
• docs/PROCESS-GUARD.md
• docs/TAXONOMY.md
• docs/VALIDATION.md
• src/cli/cli-schema.ts
• src/config/project-config-schema.ts
• src/generators/built-in/cli-recipe-generator.ts
• src/generators/built-in/codec-generators.ts
• src/lint/process-guard/decider.ts
• src/renderable/codecs/index-codec.ts
• src/renderable/codecs/index.ts
• src/renderable/codecs/reference.ts
• src/renderable/codecs/validation-rules.ts
• src/renderable/generate.ts
• src/renderable/index.ts
• src/renderable/load-preamble.ts
• src/taxonomy/conventions.ts
• tests/features/doc-generation/architecture-doc-refactoring.feature
• tests/features/generation/load-preamble.feature
• tests/steps/doc-generation/architecture-doc-refactoring.steps.ts
• tests/steps/generation/load-preamble.steps.ts