feat: consolidate documentation — 5 new codecs, 900+ manual lines replaced by auto-generation#32
Merged
darko-mijic merged 70 commits intomainfrom Mar 6, 2026
Merged
Conversation
…e doc decomposition Design session output: added Rules 5-8 covering product area absorption (DD-4), MasterDataset shapes reference (DD-6), pipeline diagram generation (DD-7/DD-8), and usefulness-driven editorial trimming (DD-5/DD-9). Updated Section Disposition table to reflect ~320 line target with Programmatic Usage and Extending the System sections dropped. Added editorial trim deliverable. Updated umbrella spec with Phase 4 cross-reference.
…notation examples into pipeline
…d complete deliverables
… deliverable All 12 deliverables were complete and tests passing (20/20) from prior commits. This commit records the FSM transition roadmap→active and marks the Phase 4 Architecture decomposition deliverable as complete in DocsConsolidationStrategy.
…ted) All 12 deliverables confirmed complete, 20/20 tests passing, ARCHITECTURE.md at 358 lines (target ~320). Pattern transitions to terminal completed state.
Improve heading extraction to handle structured JSDoc with ## headings inside @libar-docs-convention blocks. Fix restrict-plus-operands lint error on table row parser.
Establish docs-live/ as the single output directory for all website-published and Claude-readable content. Spec defines 4 deliverables for consolidating reference docs and compacts.
Move reference docs output from docs-generated/docs/ to docs-live/reference/ and architecture compacts to docs-live/_claude-md/architecture/. - Add outputDirectory: docs-live override for reference-docs - Change generator output prefix docs/ → reference/ - Add docs-generated/ to .gitignore - Remove docs-generated from package.json files array - Add docs-live/ to process guard isGeneratedDocsPath() - Update 4 cross-references in docs/ARCHITECTURE.md - Update 7 test file path references - Fix session-guides lint error (When → Once)
All 4 deliverables verified: - Reference docs at docs-live/reference/ - Architecture compacts at docs-live/_claude-md/architecture/ - docs-generated/ contains only intermediates - .gitignore updated
Reference docs now output to docs-live/reference/. Architecture compacts now at docs-live/_claude-md/architecture/. Remove docs-generated/ from git tracking (now gitignored, contains only intermediate build artifacts). Includes regenerated product areas, ADRs, compacts, and business rules reflecting current annotation state.
Add Phase 38-43 roadmap specs (GeneratedDocQuality, GherkinPatternsRestructure, ProcessApiHybridGeneration, PublishingRelocation, ReadmeRationalization) and session planning tracker.
Four quality improvements to generated docs: - D1: Remove duplicate convention tables from behavior-specs renderer - D2: Enrich Generation product area compact (1.4 KB → 4.3 KB) - D3: Add shapesFirst config to reorder ARCHITECTURE-TYPES.md - D4: Add generated TOC to product area doc headers
Design session revealed original plan to tag ADR-001/ADR-003/PDR-001 with claude-module was flawed — file-level tag pulls all Rules, most irrelevant to session workflows. Revised spec: this spec itself is the annotated source with 9 Rule blocks capturing session workflow invariants. Changes: - Rewrote session-guides-module-source.feature with 9 Rule blocks (session types, planning, design, implementation, FSM errors, handoff) - Restructured deliverables: 3 pending, 1 complete, 3 deferred on Phase 25 - Added 'workflow' to Phase 25 claude-section enum values - Updated tracker with design session report 123 test files, 7972 tests passing.
Revised line target from ~250 to ~370 after section audit showed only Step Linting (148 lines) is misplaced content. Added section disposition table, exact line ranges, VALIDATION.md integration point, INDEX.md deliverable, and 3 Rule blocks. No CLAUDE.md trim this phase.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
tests/features/doc-generation/architecture-doc-refactoring.feature
Outdated
Show resolved
Hide resolved
tests/features/doc-generation/architecture-doc-refactoring.feature
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
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 | 🟠 MajorDon’t deduplicate shapes by bare
name.Lines 670 and 876 use only
shape.nameas the identity key. Two distinct declarations likeConfigfrom 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 | 🟡 MinorThe
NEXT_HEADER_PATTERNregex 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
📒 Files selected for processing (3)
src/generators/built-in/process-api-reference-generator.tssrc/renderable/codecs/business-rules.tssrc/renderable/codecs/reference.ts
Contributor
Author
|
@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:
Acknowledged — Deferred (13 comments)These identify pre-existing documentation/implementation gaps not introduced by this PR. Tracked for future work:
Not Applicable (31 comments)Tags are optional (comments 001, 004, 006, 007, 041, 043, 044, 045, 047, 051)
JSDoc colon format is intentional (comments 015, 019, 024, 030, 032)
Verified-by sections are aspirational (comments 036, 037, 038, 039, 048, 052)
Factually incorrect assessments (10 comments)
|
|
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:
(ﾉ◕ヮ◕)ﾉ*:･ﾟ✧ ✏️ Learnings added
✅ Actions performedComments resolved. Auto-approval is disabled; enable |
- Reconcile conflicting size thresholds (5+ KB → 4+ KB) in generated-doc-quality spec - Fix deliverable location column (session-workflows.md → fsm-handoff.md) - Correct severity count (8 error, 4 warning → 9 error, 3 warning) in VALIDATION.md - Add language label to unlabeled code block in VALIDATION.md - Fix CHANGELOG.md line count (1-26 → 1-31) in INDEX.md - Fix regex alternation in NEXT_HEADER_PATTERN (disconnected ^ anchor) - Add @libar-docs opt-in marker to claude-section-values.ts - Remove duplicate "Data Flow Diagrams" scenario and step definition
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
delivery-process/specs/generated-doc-quality.feature (1)
34-40:⚠️ Potential issue | 🟠 MajorAdd 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 | 🟡 MinorAdd a language to the scan-scope fence.
This block is still unlabeled, so markdownlint MD040 will keep firing.
textis 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.mdaround 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 -->
CI was failing because format:check runs in CI but the pre-push hook only ran tests. Unformatted files outside the staged set would pass lint-staged (pre-commit) but fail CI's full-project format:check.
The hook was missing the executable bit, so git silently skipped it. This meant lint-staged (eslint --fix + prettier --write) never ran on staged files, letting formatting issues reach CI.
…andates Replace static reference tables with Process Data API query pointers and add a mandatory Context Gathering Protocol section. Key changes: - NEW: Context Gathering Protocol section (hard API-first mandate) - FIX: ClaudeModuleCodec skips Feature descriptions, only emits Rule blocks - MOVE: Guides section to api-reference additive layer - ADD: Decision specs (ADR/PDR) reference table in Architecture section - TRIM: 11 module files replacing tables with API query commands Static tables replaced by API queries: - Protection levels -> `query getProtectionInfo <status>` - Validation rules -> `rules --pattern ProcessGuard` - Module structure -> `arch context` / `arch layer` - Tag conventions -> `tags` - FSM transitions -> `query getValidTransitionsFrom <status>` CLAUDE.md reduction: 1,085 -> 670 lines (38%), ~13,100 -> ~8,700 tokens
Restore docs/ARCHITECTURE.md, docs/PROCESS-API.md, and docs/INDEX.md from main — manual reference docs are preserved in full, not replaced by redirect pointers to generated content. Move business-rules, taxonomy, and validation-rules generators from gitignored docs-generated/ to committed docs-live/ via outputDirectory overrides. Add docs:validation to docs:all chain. Create docs-live/INDEX.md as navigation hub for all 47 generated files. Update DocsLiveConsolidation spec invariant: docs-generated/ is now empty after docs:all (business-rules and taxonomy are no longer classified as intermediate artifacts). Add cross-references from manual docs to their generated counterparts. Update architecture-doc-refactoring tests to reflect coexistence of full manual docs with generated equivalents. 124 test files, 7,999 tests passing.
…ed tables The Generation intro was ~1,600 chars crammed into a single paragraph. Trimmed to 3 sentences and moved pipeline stages + codec inventory into structured tables via new optional `introSections` field on ProductAreaMeta. Tables render only at 'detailed' level — compact _claude-md/ output gets just the concise intro. Regenerated all docs.
…0+ lines of manual docs replaced Implements five work packages from the docs consolidation strategy: WP-3+4: Promote architecture and changelog generators from preview to docs:all WP-5 (ErrorGuideCodec): Extend ValidationRulesCodec with convention-tagged error rationale from decider.ts, generating PROCESS-GUARD-REFERENCE.md WP-7 (ProceduralGuideCodec): Two ReferenceDocConfig entries producing SESSION-WORKFLOW-GUIDE.md and ANNOTATION-REFERENCE.md from preamble + SessionGuidesModuleSource Rule: block extraction WP-6 (CliRecipeCodec): Standalone generator producing PROCESS-API-RECIPES.md from structured CLI_SCHEMA recipe/narrative fields, replacing 446 lines of manual PROCESS-API.md prose Cross-cutting: loadPreambleFromMarkdown() utility (DD-7/DD-8) parses markdown files into SectionBlock[] at config import time, reducing delivery-process.config.ts from 853 to 302 lines. Three markdown source files in docs-sources/. Planning/design specs created for all WPs plus EnhancedIndexGeneration (WP-2). 18 design stubs across 4 directories document architectural decisions. Key metrics: - 4 new generated reference files + 4 compact claude-md variants - PROCESS-API.md: 509 → 63 lines (pointers to 2 generated files) - delivery-process.config.ts: 853 → 302 lines (loadPreambleFromMarkdown) - 11 generators producing 56+ files via docs:all - 8,055 tests passing, 38 phases DoD-clean
…ming WP-2 — EnhancedIndexGeneration: - New IndexCodec (src/renderable/codecs/index-codec.ts) composing MasterDataset statistics with editorial preamble navigation - Editorial preamble in docs-sources/index-navigation.md loaded via loadPreambleFromMarkdown() (DD-7/DD-8 from WP-7) - 18 document entries across 6 topics in delivery-process.config.ts - Registered in CodecRegistry, DOCUMENT_TYPES, and docs:all chain - docs-live/INDEX.md now generated (112→232 lines) with live stats Phase 1 — Taxonomy consolidation: - docs/TAXONOMY.md reduced from 107→31 lines, points to generated output Phase 5 — Guide trimming: - docs/CONFIGURATION.md trimmed ~60 lines of duplicated preset tables Spec stays at roadmap — FSM transitions follow in separate commits. Master spec: 14/15 deliverables complete (Phase 38 quality polish remaining)
All 6 deliverables at terminal status (5 complete, 1 superseded).
… parity Reverts premature replacement of manual docs with pointer files. docs/ files are preserved as reference until generated docs-live/ equivalents reach desired quality for archival. Restored: - docs/INDEX.md (353 lines — full manual navigation content) - docs/TAXONOMY.md (107 lines — full manual taxonomy reference) - docs/CONFIGURATION.md (357 lines — full preset detail tables) Reverted Phase 1, Phase 5, Phase 6 to pending in master spec. Master spec: 11/15 deliverables complete.
Source code fixes: - Remove dead allocation in flushCodeFence (load-preamble.ts) - Simplify DEFAULT_INDEX_OPTIONS type to Required<IndexCodecOptions> - Extract resolveCodec helper to deduplicate generate.ts Test fixes: - Add **Invariant:**/**Rationale:**/**Verified by:** to all 7 Rule blocks in architecture-doc-refactoring.feature - Add @acceptance-criteria tags to one scenario per Rule block Regenerated all docs-live/ from annotated sources.
…al docs/ Remove all docs/ references from the two data sources feeding IndexCodec: - docs-sources/index-navigation.md: rewrite preamble with docs-live/-relative links - delivery-process.config.ts: replace INDEX_DOCUMENT_ENTRIES with 21 docs-live/ entries Also fixes path prefix bug where links like docs-live/PRODUCT-AREAS.md would resolve to docs-live/docs-live/PRODUCT-AREAS.md since INDEX.md lives inside docs-live/. All paths now relative to the file's location. Regenerated all docs via pnpm docs:all.
darko-mijic
changed the title
darko-mijic
changed the title
There was a problem hiding this comment.
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
⛔ Files ignored due to path filters (43)
delivery-process.config.tsis excluded by none and included by nonedocs-live/ARCHITECTURE.mdis excluded by none and included by nonedocs-live/BUSINESS-RULES.mdis excluded by none and included by nonedocs-live/CHANGELOG-GENERATED.mdis excluded by none and included by nonedocs-live/INDEX.mdis excluded by none and included by nonedocs-live/PRODUCT-AREAS.mdis excluded by none and included by nonedocs-live/TAXONOMY.mdis excluded by none and included by nonedocs-live/VALIDATION-RULES.mdis excluded by none and included by nonedocs-live/_claude-md/annotation/annotation-reference.mdis excluded by none and included by nonedocs-live/_claude-md/architecture/architecture-codecs.mdis excluded by none and included by nonedocs-live/_claude-md/architecture/reference-sample.mdis excluded by none and included by nonedocs-live/_claude-md/generation/generation-overview.mdis excluded by none and included by nonedocs-live/_claude-md/process/process-overview.mdis excluded by none and included by nonedocs-live/_claude-md/validation/process-guard.mdis excluded by none and included by nonedocs-live/_claude-md/workflow/session-workflow-guide.mdis excluded by none and included by nonedocs-live/business-rules/annotation.mdis excluded by none and included by nonedocs-live/business-rules/configuration.mdis excluded by none and included by nonedocs-live/business-rules/core-types.mdis excluded by none and included by nonedocs-live/business-rules/data-api.mdis excluded by none and included by nonedocs-live/business-rules/generation.mdis excluded by none and included by nonedocs-live/business-rules/process.mdis excluded by none and included by nonedocs-live/business-rules/validation.mdis excluded by none and included by nonedocs-live/product-areas/CORE-TYPES.mdis excluded by none and included by nonedocs-live/product-areas/GENERATION.mdis excluded by none and included by nonedocs-live/product-areas/PROCESS.mdis excluded by none and included by nonedocs-live/product-areas/VALIDATION.mdis excluded by none and included by nonedocs-live/reference/ANNOTATION-REFERENCE.mdis excluded by none and included by nonedocs-live/reference/ARCHITECTURE-CODECS.mdis excluded by none and included by nonedocs-live/reference/PROCESS-API-RECIPES.mdis excluded by none and included by nonedocs-live/reference/PROCESS-GUARD-REFERENCE.mdis excluded by none and included by nonedocs-live/reference/REFERENCE-SAMPLE.mdis excluded by none and included by nonedocs-live/reference/SESSION-WORKFLOW-GUIDE.mdis excluded by none and included by nonedocs-live/taxonomy/categories.mdis excluded by none and included by nonedocs-live/taxonomy/format-types.mdis excluded by none and included by nonedocs-live/taxonomy/metadata-tags.mdis excluded by none and included by nonedocs-live/validation/error-catalog.mdis excluded by none and included by nonedocs-live/validation/fsm-transitions.mdis excluded by none and included by nonedocs-live/validation/protection-levels.mdis excluded by none and included by nonedocs-sources/annotation-guide.mdis excluded by none and included by nonedocs-sources/index-navigation.mdis excluded by none and included by nonedocs-sources/process-api-recipes.mdis excluded by none and included by nonedocs-sources/session-workflow-guide.mdis excluded by none and included by nonepackage.jsonis excluded by none and included by none
📒 Files selected for processing (44)
delivery-process/specs/cli-recipe-codec.featuredelivery-process/specs/docs-consolidation-strategy.featuredelivery-process/specs/docs-live-consolidation.featuredelivery-process/specs/enhanced-index-generation.featuredelivery-process/specs/error-guide-codec.featuredelivery-process/specs/procedural-guide-codec.featuredelivery-process/specs/session-guides-module-source.featuredelivery-process/stubs/cli-recipe-codec/cli-recipe-generator.tsdelivery-process/stubs/cli-recipe-codec/recipe-data.tsdelivery-process/stubs/cli-recipe-codec/recipe-schema.tsdelivery-process/stubs/enhanced-index-generation/index-codec-options.tsdelivery-process/stubs/enhanced-index-generation/index-codec.tsdelivery-process/stubs/enhanced-index-generation/index-preamble-config.tsdelivery-process/stubs/error-guide-codec/convention-annotation-example.tsdelivery-process/stubs/error-guide-codec/enhanced-validation-options.tsdelivery-process/stubs/error-guide-codec/error-guide-config.tsdelivery-process/stubs/procedural-guide-codec/annotation-guide-preamble.tsdelivery-process/stubs/procedural-guide-codec/load-preamble.tsdelivery-process/stubs/procedural-guide-codec/procedural-codec-options.tsdelivery-process/stubs/procedural-guide-codec/procedural-codec.tsdelivery-process/stubs/procedural-guide-codec/session-guide-preamble.tsdocs/ANNOTATION-GUIDE.mddocs/DOCS-GAP-ANALYSIS.mddocs/PROCESS-API.mddocs/PROCESS-GUARD.mddocs/TAXONOMY.mddocs/VALIDATION.mdsrc/cli/cli-schema.tssrc/config/project-config-schema.tssrc/generators/built-in/cli-recipe-generator.tssrc/generators/built-in/codec-generators.tssrc/lint/process-guard/decider.tssrc/renderable/codecs/index-codec.tssrc/renderable/codecs/index.tssrc/renderable/codecs/reference.tssrc/renderable/codecs/validation-rules.tssrc/renderable/generate.tssrc/renderable/index.tssrc/renderable/load-preamble.tssrc/taxonomy/conventions.tstests/features/doc-generation/architecture-doc-refactoring.featuretests/features/generation/load-preamble.featuretests/steps/doc-generation/architecture-doc-refactoring.steps.tstests/steps/generation/load-preamble.steps.ts
delivery-process/stubs/error-guide-codec/enhanced-validation-options.ts
Outdated
Show resolved
Hide resolved
delivery-process/stubs/procedural-guide-codec/procedural-codec-options.ts
Show resolved
Hide resolved
Fixes 22 valid review comments from coderabbitai: Specs: - cli-recipe-codec: "command strings" → "RecipeStep entries" in invariant - docs-consolidation-strategy: fix phase count (13 not 6/10), docs/ → docs-live/ output path, update retention rule to reflect Phase 39-43 completions - docs-live-consolidation: fix legacy path assertion, narrow _claude-md rule to architecture compacts only, fix scenario title precision - enhanced-index-generation: scope table source matches DD-2 (static entries) - procedural-guide-codec: ANNOTATION-GUIDE.md → ANNOTATION-REFERENCE.md Stubs: - cli-recipe-codec: remove unused import, clarify type comments, fix registration JSDoc, un-export example data, remove stale CLISchemaExtended - enhanced-index-generation: fix auto-discovery JSDoc, remove eager throwing instantiation, headers → columns in table blocks, PUBLISHING → MAINTAINERS - error-guide-codec: fix import path (../../ → ../../../), remove Required<> wrapper, fix mermaid diagram API names, remove obsolete convention snippet - procedural-guide-codec: fix import paths (../../ → ../../../) in 3 files, update Annotation Guide config table to match delivery-process.config.ts
- What Gets Generated: expanded from 6 to 10 content types with file counts - CLI Commands: doc links now point to docs-live/ generated equivalents - Documentation: split into Generated (docs-live/INDEX.md) and Editorial (docs/) tiers - All links verified against existing files
This was referenced Mar 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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):
src/)tests/)delivery-process/specs/)docs-live/)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 todocs-live/What Changed and Why
Unified Output Directory
Problem: Generated docs were scattered across
docs-generated/anddocs-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/. Thedocs-generated/directory is removed from git tracking and added to.gitignoreas a transient build cache only.docs-generated/(14 files, 8,117 lines tracked).gitignoreddocs-live/output directoryGenerated 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:
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:_claude-md/workflow/session-workflow-guide.md)docs-live/reference/SESSION-WORKFLOW-GUIDE.md, 384 lines)pnpm process:query -- rules --pattern SessionGuidesModuleSourcePublishing Docs Relocated
Problem:
docs/PUBLISHING.mdwas published to the website but contained maintainer-only npm publishing workflows irrelevant to end users.Solution: Moved to
MAINTAINERS.mdat 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:
docs/VALIDATION.md(correct domain)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:
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 docsProcessApiReferenceGenerator→ generates reference tables from the schemaCliRecipeGenerator→ generates workflow recipes with editorial preambleNew generated output:
docs-live/reference/PROCESS-API-REFERENCE.md(63 lines) — command reference tablesdocs-live/reference/PROCESS-API-RECIPES.md(476 lines) — workflow recipes and examplesClaude 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
ClaudeModuleCodecthat extracts Rule blocks from patterns tagged with@libar-docs-claude-moduleand 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:
IndexCodecdocs-live/INDEX.mdCliRecipeGeneratorPROCESS-API-RECIPES.mdProcessApiReferenceGeneratorPROCESS-API-REFERENCE.mddocs-live/ARCHITECTURE.mddocs-live/CHANGELOG-GENERATED.mdPlus 4 new reference documents via
ReferenceDocConfig:PROCESS-GUARD-REFERENCE.md(179 lines) — error diagnosis, FSM states, pre-commit setupSESSION-WORKFLOW-GUIDE.md(384 lines) — session checklists with Mermaid decision treeANNOTATION-REFERENCE.md(146 lines) — getting-started guide for@libar-docsannotationsARCHITECTURE-CODECS.md(656 lines) andARCHITECTURE-TYPES.md(429 lines)New Source Code
Core infrastructure (
src/)cli/cli-schema.tsgenerators/built-in/cli-recipe-generator.tsgenerators/built-in/process-api-reference-generator.tsgenerators/built-in/codec-generators.tsrenderable/codecs/index-codec.tsrenderable/codecs/claude-module.tsrenderable/load-preamble.tsdocs-sources/*.md→SectionBlock[]taxonomy/claude-section-values.ts_claude-md/subdirectory organizationKey design pattern:
loadPreambleFromMarkdown()The
src/renderable/load-preamble.tsutility (349 lines) eliminates the need to hand-authorSectionBlock[]arrays in TypeScript config. Instead, editorial preamble content is authored as natural Markdown indocs-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/:annotation-guide.md@libar-docsannotationsindex-navigation.mdsession-workflow-guide.mdprocess-api-recipes.mdSpecification Work
15 new spec files define the consolidation deliverables as executable specifications:
docs-consolidation-strategy.featuredocs-live-consolidation.featurepublishing-relocation.featuregenerated-doc-quality.featuresession-guides-module-source.featuregherkin-patterns-restructure.featurereadme-rationalization.featureprocess-api-hybrid-generation.featureclaude-module-generation.featurearchitecture-doc-refactoring.featureenhanced-index-generation.featureerror-guide-codec.featurecli-recipe-codec.featureprocedural-guide-codec.feature14 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:process-api-reference.steps.tsconvention-extractor.steps.tsgenerated-doc-quality.steps.tsreference-codec-diagrams.steps.tsreference-generators.steps.tsarchitecture-doc-refactoring.steps.tsload-preamble.steps.tsManual Docs Impact
Trimmed (replaced by generated equivalents)
PROCESS-API.mdPROCESS-API-REFERENCE.md+PROCESS-API-RECIPES.mdREADME.mdCLAUDE.mdGHERKIN-PATTERNS.mdVALIDATION.mdRelocated
PUBLISHING.mddocs/MAINTAINERS.md(root)GHERKIN-PATTERNS.mdVALIDATION.mdPreserved 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:
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:
sync-content.mjsto read fromdocs-live/instead of the now-emptydocs-generated/METHODOLOGY.mdstays manual (philosophy is irreducibly editorial)How to Verify
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 violationspnpm typecheck— no type errorspnpm lint— no lint violationsdocs-live/correctly (separate follow-up PR)