Prepare 1.0.0-pre.0 for initial npm publication#29
Merged
darko-mijic merged 11 commits intomainfrom Feb 22, 2026
Merged
Conversation
Add **Invariant:** and **Rationale:** annotations to every Gherkin Rule: block that was missing them across all 7 product areas (~65 feature files). Before: 115 missing invariants, 362 missing rationale out of 785 rules. After: 0 missing invariants, 0 missing rationale — 100% coverage. Regenerated product area docs and business rules docs to populate the Business Rules table columns. All 7801 tests pass unchanged.
Replace renderToClaudeContext with renderToClaudeMdModule in generators so _claude-md/ output uses standard markdown (H3-rooted headings) instead of custom === SECTION === markers. Add buildBoundarySummary to produce compact Components: lines in summary-level product area docs. Includes 7 new Gherkin scenarios covering heading offset, frontmatter omission, mermaid/link-out omission, collapsible flattening, and H6 clamping.
INSTRUCTIONS.md was a hand-maintained tag/CLI reference that drifted from source (30 of 53 tags documented). A package preaching "code is the single source of truth" should not ship with stale manual references. Consolidation: - generate-docs and generate-tag-taxonomy flags → README.md CLI section - lint-patterns and validate-patterns flags → docs/VALIDATION.md (now self-contained) - Tag reference links → docs/TAXONOMY.md + generated output via generate-tag-taxonomy - Removed 18 cross-references across 12 files (docs, package.json, .coderabbit.yaml)
📝 WalkthroughWalkthroughAdds GitHub issue templates, a small CI comment change, and extensive documentation-only additions (invariants, rationales, verifications, and usage notes) across delivery-process ADRs, specs, and stubs; no executable code or public API signatures were modified. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 20
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (11)
delivery-process/specs/session-file-cleanup.feature (1)
46-46:⚠️ Potential issue | 🟡 MinorInconsistent path in log message strings:
sessions/vssession/.Line 46 references
sessions/phase-31.md(plural) but line 74 referencessession/phase-31.md(singular, missing trailings). These should match the actual directory name used consistently throughout the spec.🐛 Proposed fix
- Then warning is logged "Failed to cleanup session/phase-31.md: Permission denied" + Then warning is logged "Failed to cleanup sessions/phase-31.md: Permission denied"Also applies to: 74-74
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/session-file-cleanup.feature` at line 46, The log message strings in the feature use inconsistent directory names: "sessions/phase-31.md" vs "session/phase-31.md"; update all occurrences so they match the actual directory name used elsewhere (use "sessions/..." consistently) by replacing the singular "session/phase-31.md" with "sessions/phase-31.md" in the scenario steps and any other assertions (look for the exact strings "sessions/phase-31.md" and "session/phase-31.md" to locate the lines).delivery-process/specs/release-association-rules.feature (1)
55-59: 🧹 Nitpick | 🔵 TrivialRedundant scenario — already covered by the Scenario Outline below.
The standalone
Scenario: Phase file with missing required annotationsat lines 55–59 tests only the@libar-docs-patterncase, which is already one of the rows in theScenario Outlineat lines 62–73. Removing this scenario eliminates duplicate coverage and keeps the outline as the single source of truth for annotation validation cases.♻️ Proposed removal
- `@acceptance-criteria` - Scenario: Phase file with missing required annotations - Given a TypeScript file in delivery-process/src/phases/ - When `@libar-docs-pattern` is missing - Then validation fails with "Required: `@libar-docs-pattern`" - `@acceptance-criteria` Scenario Outline: Phase file required annotations🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/release-association-rules.feature` around lines 55 - 59, The standalone Scenario titled "Phase file with missing required annotations" in delivery-process/specs/release-association-rules.feature is redundant because its `@libar-docs-pattern` case is already covered by the Scenario Outline below; remove that standalone Scenario (the block starting with "Scenario: Phase file with missing required annotations" and its steps) and keep the Scenario Outline (tagged `@acceptance-criteria`) as the single source of truth for missing-annotation validation, ensuring no other tests reference the removed Scenario.delivery-process/specs/phase-state-machine.feature (1)
63-68:⚠️ Potential issue | 🟡 MinorCanonical phase status value
completeshould becompletedin Examples tables.The newly added Invariant at Line 35 explicitly defines the four canonical phase status values as
roadmap,active,completed, anddeferred. However, the Examples tables for both Scenario Outlines usecomplete(without the-dsuffix) for the terminal state:
- Line 66:
| active | complete |→completed- Line 79:
| complete | active |→completed- Line 80:
| complete | roadmap |→completed- Line 81:
| roadmap | completed|→ already correctNote: The deliverables
Backgroundtable (lines 27–31) correctly usescomplete— that is the deliverable status enum, which is a separate domain from phase status.✏️ Proposed fix
Examples: | from | to | | roadmap | active | | roadmap | deferred | | roadmap | roadmap | - | active | complete | + | active | completed | | active | roadmap | | deferred | roadmap |Examples: | from | to | - | complete | active | - | complete | roadmap | + | completed | active | + | completed | roadmap | | roadmap | completed|Also applies to: 78-81
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/phase-state-machine.feature` around lines 63 - 68, The Examples tables in the Scenario Outlines use the wrong phase status token "complete" but the Invariant that defines canonical phase status values expects "completed"; update all Examples rows in the Scenario Outlines where a phase status value is "complete" to "completed" (specifically the rows currently showing "| active | complete |", "| complete | active |", and "| complete | roadmap |") so they match the canonical phase status enum declared in the Invariant.delivery-process/specs/shape-extraction.feature (2)
4-4:⚠️ Potential issue | 🟡 MinorUnlock-reason tag doesn't match the change being made
Line 4:
@libar-docs-unlock-reason:Fix-code-fence-formatting-per-PR-reviewdescribes a previous edit (code-fence formatting), not the current modification (adding Rationale annotations across all Rule blocks). For a completed spec file, the unlock reason should reflect the actual change so audit history is accurate.🔧 Suggested update
-@libar-docs-unlock-reason:Fix-code-fence-formatting-per-PR-review +@libar-docs-unlock-reason:Add-missing-Rationale-annotations-to-all-Rule-blocksBased on learnings: "Completed pattern specs require
@libar-docs-unlock-reasontag to be modified - hard-locked protection."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/shape-extraction.feature` at line 4, Update the `@libar-docs-unlock-reason` tag value to accurately describe the current change (adding Rationale annotations across all Rule blocks) rather than the stale text "Fix-code-fence-formatting-per-PR-review"; locate the tag string `@libar-docs-unlock-reason:Fix-code-fence-formatting-per-PR-review` and replace it with a concise reason such as `@libar-docs-unlock-reason:Add-Rationale-annotations-to-Rule-blocks` so the audit/history matches the actual modification.
93-97:⚠️ Potential issue | 🟡 MinorAll 10 Rule blocks are still missing
**Verified by:**The coding guidelines require Rule block descriptions to contain all three sections:
**Invariant:**,**Rationale:**, and**Verified by:**. This PR successfully completes the**Rationale:**gap across all rules, but**Verified by:**remains absent from every Rule block. Since this PR is the one closing the structured-description gap, the missing third section should be added here or tracked explicitly.Each Rule already has
@acceptance-criteria-tagged scenarios that serve as the natural verification reference — the**Verified by:**text can simply point to those scenarios. For example:Rule: extract-shapes tag is defined in registry **Invariant:** The `extract-shapes` tag must exist with CSV format to list multiple type names for extraction. **Rationale:** Without a CSV-format tag, there is no mechanism to specify which type names to extract, and the extractor cannot discover shapes from source files. + **Verified by:** Scenario: Tag registry contains extract-shapesBased on learnings: "Feature files must use Rule: blocks with structured descriptions containing Invariant:, Rationale:, and Verified by: sections."
Also applies to: 111-116, 211-215, 267-271, 315-320, 380-384, 422-426, 459-464, 514-518, 564-568
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/shape-extraction.feature` around lines 93 - 97, Every Rule block is missing the required "**Verified by:**" section; update each Rule (e.g., the "extract-shapes" Rule) to add a "**Verified by:**" line pointing to its corresponding `@acceptance-criteria` scenario(s) so the structured description contains Invariant, Rationale, and Verified by. Locate each Rule block (all 10 mentioned) and append a short "**Verified by:**" sentence that references the matching `@acceptance-criteria` scenario tag(s) used for acceptance testing, ensuring the Rule descriptions now include the three required sections.delivery-process/specs/doc-generation-proof-of-concept.feature (1)
7-7:⚠️ Potential issue | 🟡 Minor
@libar-docs-unlock-reasondoesn't match the actual change being made.The stated reason is
Fix-code-fence-formatting-per-PR-review, but the changes in this PR add**Invariant:**and**Rationale:**annotations across all Rule blocks — a structurally distinct modification. The unlock reason exists precisely so auditors can verify why acompletedspec was touched; an inaccurate reason defeats that purpose.📋 Suggested fix
-@libar-docs-unlock-reason:Fix-code-fence-formatting-per-PR-review +@libar-docs-unlock-reason:Add-missing-Invariant-and-Rationale-to-all-Rule-blocksAs per coding guidelines: "Completed pattern specs require
@libar-docs-unlock-reasontag to be modified - hard-locked protection."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/doc-generation-proof-of-concept.feature` at line 7, The `@libar-docs-unlock-reason` tag value is inaccurate: update the tag `@libar-docs-unlock-reason` to clearly describe the actual change (e.g., "Add-Invariant-and-Rationale-annotations-to-Rule-blocks") so auditors can verify why a completed spec was modified; ensure the updated tag value appears at the top of the feature and matches the structural change (addition of **Invariant:** and **Rationale:** annotations within Rule blocks) before committing.delivery-process/decisions/adr-006-single-read-model-architecture.feature (1)
1-9:⚠️ Potential issue | 🟠 MajorModifying a
completedspec without@libar-docs-unlock-reasonviolates hard-locked protection.
@libar-docs-status:completedis set (Line 6) but there is no@libar-docs-unlock-reasontag in the file header. Lines 52, 68, 76, 81, and 82 are all modified in this PR. Per the hard-lock policy, any edit to a completed spec must carry an unlock-reason explaining the exception.`@libar-docs-status`:completed +@libar-docs-unlock-reason:Add-rationale-sections-to-rule-blocks `@libar-docs-product-area`:GenerationBased on learnings: "Completed pattern specs require
@libar-docs-unlock-reasontag to be modified - hard-locked protection."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/decisions/adr-006-single-read-model-architecture.feature` around lines 1 - 9, This file is marked with `@libar-docs-status`:completed but was edited without the required `@libar-docs-unlock-reason`; add a new `@libar-docs-unlock-reason` header entry in the file header (near the existing tags such as `@libar-docs-status`:completed and `@libar-docs-adr`:006) that briefly states the justification for this edit, who authorized it, and a date or PR reference so the hard-lock policy is satisfied; keep the tag value concise and ensure it appears before the body so subsequent edits to lines 52, 68, 76, 81, and 82 are permitted.delivery-process/decisions/adr-002-gherkin-only-testing.feature (1)
7-7:⚠️ Potential issue | 🟡 Minor
@libar-docs-unlock-reasondescribes a prior change, not the current edit.The existing value
Add-process-workflow-include-tagrefers to adding the@libar-docs-includetag, but the current modification adds a**Rationale:**line. If Process Guard validates the reason against the change being made, this mismatch may cause confusion; at minimum it loses traceability of why this completed spec was opened again.Consider updating the unlock-reason value to reflect both reasons (hyphenated), e.g.:
-@libar-docs-unlock-reason:Add-process-workflow-include-tag +@libar-docs-unlock-reason:Add-process-workflow-include-tag-and-rationale🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/decisions/adr-002-gherkin-only-testing.feature` at line 7, Update the unlock-reason tag value so it reflects both changes (the include-tag addition and the new rationale line) instead of only "Add-process-workflow-include-tag": change the `@libar-docs-unlock-reason` value (the tag string shown in the diff) to a hyphenated compound like "Add-process-workflow-include-tag-Add-rationale-line" (or similar wording that includes both reasons) so Process Guard can validate and trace why this spec was reopened.delivery-process/specs/gherkin-rules-support.feature (1)
48-128:⚠️ Potential issue | 🟡 MinorAll four Rule blocks are missing the required
**Verified by:**section.The PR adds
**Invariant:**and**Rationale:**to each Rule block, but the guideline mandates all three sections. Every other spec in this PR (cli-behavior-testing,codec-behavior-testing,generator-infrastructure-testing) has a**Verified by:**entry summarising which scenarios exercise the invariant.Suggested additions (one per Rule block):
Rule: Rules flow through the entire pipeline without data loss **Invariant:** Rule data (name, description, tags, scenarios) must be preserved … **Rationale:** Any data loss at an intermediate stage makes rule content invisible … + **Verified by:** AST parser extraction, Scanner passthrough, Extractor mapping Rule: Generators can render rules as business documentation **Invariant:** Rules must render as human-readable Business Rules sections … **Rationale:** Business stakeholders cannot interpret Gherkin step definitions … + **Verified by:** PRD generator Business Rules rendering Rule: Custom content blocks render in acceptance criteria **Invariant:** DataTables and DocStrings attached to steps must appear … **Rationale:** Without rendering custom content blocks, acceptance criteria lose … + **Verified by:** DataTable Markdown rendering, DocString code block rendering Rule: vitest-cucumber executes scenarios inside Rules **Invariant:** Scenarios nested inside Rule blocks must be executable … **Rationale:** If Rule-scoped scenarios cannot execute, adding Rule blocks … + **Verified by:** Rule() + RuleScenario() executionBased on learnings: "Applies to **/*.feature : Feature files must use Rule: blocks with structured descriptions containing Invariant:, Rationale:, and Verified by: sections"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/gherkin-rules-support.feature` around lines 48 - 128, Each Rule block is missing the required "**Verified by:**" section; for each Rule title (Rules flow through the entire pipeline without data loss; Generators can render rules as business documentation; Custom content blocks render in acceptance criteria; vitest-cucumber executes scenarios inside Rules) add a "**Verified by:**" paragraph that enumerates which acceptance scenarios exercise that invariant (e.g., for the pipeline rule list "Rules are captured by AST parser", "Rules pass through scanner", "Rules are mapped to ExtractedPattern"; for the PRD rendering rule list "PRD generator renders Business Rules section"; for custom blocks list "DataTables render as Markdown tables" and "DocStrings render as code blocks"; for vitest-cucumber list "Rule scenarios execute with vitest-cucumber"). Ensure the text follows the existing style ("**Verified by:** <brief list>") and appears directly under the "**Rationale:**" line in each Rule block.delivery-process/specs/universal-doc-generator-robustness.feature (1)
120-218:⚠️ Potential issue | 🟡 MinorRules 3, 4, and 5 — which all have executable scenarios — are missing the required
**Verified by:**section.The PR adds
**Invariant:**and**Rationale:**to each Rule block but omits**Verified by:**. Rules 1, 2, and 6 ("Context", "Decision", "Consequence") contain no scenarios so a short**Verified by:** N/Asuffices there, but the three scenario-bearing rules below have clear scenario names to reference.Rule: Duplicate content must be detected and merged **Invariant:** No two sections in a generated document … **Rationale:** Duplicate sections confuse readers … + **Verified by:** Deduplication of identical fingerprints, Preservation of non-identical sections Rule: Invalid source mappings must fail fast with clear errors **Invariant:** Every source mapping must pass pre-flight validation … **Rationale:** Without pre-flight validation, invalid mappings produce silent failures … + **Verified by:** Valid mapping pass, Missing file error, Invalid method error, Unreadable file error Rule: Warnings must be collected and reported consistently **Invariant:** All non-fatal issues during extraction must be captured … **Rationale:** Scattered console.warn calls are lost in CI output … + **Verified by:** Warning collection during extraction, Multi-source aggregation, Result type inclusionBased on learnings: "Applies to **/*.feature : Feature files must use Rule: blocks with structured descriptions containing Invariant:, Rationale:, and Verified by: sections"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/universal-doc-generator-robustness.feature` around lines 120 - 218, Add a "**Verified by:**" section to each Rule block that contains executable scenarios: "Duplicate content must be detected and merged", "Invalid source mappings must fail fast with clear errors", and "Warnings must be collected and reported consistently"; for each, list the scenario names (e.g., "Identical sections are deduplicated", "Similar but non-identical sections are preserved", "Missing file produces validation error", "Invalid extraction method produces validation error", "Unreadable file produces validation error", "Warnings are collected during extraction", "Multiple warnings from different sources are aggregated", "Warnings are included in Result type") as the verification steps, or use a concise reference like "Verified by: scenarios: <scenario names>" so the Rule blocks comply with the required structured description..github/workflows/ci.yml (1)
19-19:⚠️ Potential issue | 🟠 MajorDrop Node.js 18 from the matrix — it reached End of Life on April 30, 2025.
Node.js 18 no longer receives security patches. Testing against it gives a false signal of support for an unsupported runtime and exposes the matrix to unfixed CVEs. For a library targeting its first npm release, this should be corrected before publication.
🔧 Proposed fix
- node-version: [18, 20, 22] + node-version: [20, 22]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/ci.yml at line 19, The CI matrix currently tests Node.js versions via the node-version key containing [18, 20, 22]; remove 18 from that array so the node-version matrix becomes [20, 22] (i.e., edit the node-version entry in the workflow to drop 18) to avoid testing an EOL runtime.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/ISSUE_TEMPLATE/bug_report.md:
- Around line 25-27: Update the fenced code block containing the placeholder
"Paste any error messages or unexpected output here." to include a language
specifier (e.g., text or plaintext) so the Markdown lint rule MD040 is
satisfied; locate the triple-backtick block in the template and change its
opening fence from ``` to ```text (or ```plaintext).
In `@delivery-process/decisions/adr-001-taxonomy-canonical-values.feature`:
- Line 51: Add a "**Verified by:**" section to each of the nine Rule: blocks in
adr-001-taxonomy-canonical-values.feature (the Rule blocks you updated with
"**Rationale:**") and point each one to the existing acceptance-check scenario
by referencing "Scenario: Canonical values are enforced" (the feature-level
`@acceptance-criteria` scenario) as the verifier; if you prefer per-rule
granularity you may alternatively create a small per-rule scenario and reference
that, but ensure every Rule block contains **Invariant:**, **Rationale:**, and
**Verified by:** sections and that Rules 2–9 mirror the same change you made to
Rule 1.
In `@delivery-process/decisions/adr-002-gherkin-only-testing.feature`:
- Line 50: The Rule block titled "Source-driven process benefit" is missing the
required "**Verified by:**" section; update that Rule in
adr-002-gherkin-only-testing.feature by adding a "**Verified by:**" subsection
that references the feature-level Scenario tagged "@acceptance-criteria" (i.e.,
point readers to the acceptance-criteria scenario as the verification artifact)
so the Rule contains the three structured descriptions: **Invariant:**,
**Rationale:**, and **Verified by:**.
In
`@delivery-process/decisions/adr-003-source-first-pattern-architecture.feature`:
- Line 54: Each Rule block is missing the required "**Verified by:**" section;
add a "**Verified by:** Scenario: TypeScript source is canonical pattern
definition" (or an equivalent scenario reference) immediately after the
"**Rationale:**" paragraph in each of the six Rule blocks (Rule 1 through Rule
6) so they reference the feature-level `@acceptance-criteria` Scenario (or a
rule-specific scenario where appropriate); ensure the text matches the format
"**Verified by:** Scenario: <scenario name>" to satisfy the structured Rule:
block requirement.
In `@delivery-process/decisions/adr-006-single-read-model-architecture.feature`:
- Line 52: Add an `@acceptance-criteria` Scenario that explicitly asserts the
single-read-model invariant (e.g., a Scenario titled "Single read model
invariant - acceptance criteria") so there is a concrete target to reference,
then update each Rule block in this file to include a **Verified by:** section
that cites that Scenario by tag/name. Specifically, create the
acceptance-criteria Scenario with the `@acceptance-criteria` tag and a short
Given/When/Then that verifies the single-read-model invariant, and edit every
Rule block (the ones that already have **Invariant:** and **Rationale:**) to
append **Verified by:** `@acceptance-criteria` (or the Scenario name) so each rule
points to the new acceptance criteria.
In `@delivery-process/decisions/pdr-001-session-workflow-commands.feature`:
- Around line 36-38: Add a "**Verified by:**" subsection to each Rule block DD-1
through DD-7 in the feature file so every Rule contains the three required parts
(**Invariant:**, **Rationale:**, **Verified by:**); for each Rule (e.g., the
blocks labeled DD-1, DD-2, ... DD-7) insert a short verification statement after
the existing **Rationale:** (for example "Checks: manual review of output
format" or an automated check name) to satisfy the coding guideline, and ensure
the same pattern is applied to the other affected blocks referenced in the diff
(the blocks at the same locations as the current **Invariant:**/**Rationale:**
pairs).
In `@delivery-process/specs/config-based-workflow-definition.feature`:
- Around line 155-157: The DEFERRED Rule block titled "Workflow as a
configurable preset field is deferred" is missing the required "**Verified
by:**" section; update that Rule to include a third section "**Verified by:**"
(for example "N/A - deferred until preset integration" or reference a future
spec/issue) so the block contains the mandatory **Invariant:**, **Rationale:**,
and **Verified by:** subsections and matches the structure used by the other
Rule blocks.
In `@delivery-process/specs/cross-source-validation.feature`:
- Around line 34-35: Add a "**Verified by:**" section to each of the three Rule
blocks so every Rule contains the required triplet (Invariant, Rationale,
Verified by); specifically, update the Rule titled "Pattern names must be
consistent across sources" (after the Invariant/Rationale at ~line 35), the Rule
titled "Circular dependencies are detected" (after the Invariant/Rationale at
~line 54), and the Rule titled "Dependency references must resolve" (after the
Invariant/Rationale at ~line 74) — for each Rule add a short verification note
(e.g., how to validate or test the invariant) under a bold "**Verified by:**"
heading to satisfy the feature-file structured-description guideline.
In `@delivery-process/specs/doc-generation-proof-of-concept.feature`:
- Around line 30-31: All Rule: blocks added/modified in this feature are missing
the mandatory "**Verified by:**" section; update each Rule block (the seven
Rule: sections around the comment locations) to include a "**Verified by:**"
line that references the appropriate acceptance test(s) (use the existing
`@acceptance-criteria` scenarios by tag or scenario name found in the acceptance
criteria section around lines 460–537) so every Rule contains **Invariant:**,
**Rationale:**, and **Verified by:**.
In `@delivery-process/specs/mvp-workflow-implementation.feature`:
- Around line 38-39: The Rule block in the feature file (the block containing
the lines starting with "**Invariant:**" and "**Rationale:**") is missing the
mandatory "**Verified by:**" section; update that Rule block by adding a
"**Verified by:**" line that states the verification method or owner (for
example: test name, automated check, or responsible role) so the Rule
description includes all three required sections: **Invariant:**,
**Rationale:**, and **Verified by:**.
- Around line 62-63: Update the Rule block to include a "**Verified by:**"
section and correct the Invariant's target filename: change the Invariant that
currently references "CHANGELOG" to "CHANGELOG-GENERATED.md" so it matches the
Scenario, and add a "**Verified by:**" line describing how the rule is validated
(e.g., reference to the Scenario or test that asserts the mapping).
In `@delivery-process/specs/phase-numbering-conventions.feature`:
- Around line 32-34: Each Rule block that starts with "No two specs within the
same release version may share the same phase number" is missing the required
"**Verified by:**" section; update each Rule block (the three occurrences) to
add a "**Verified by:**" line describing the concrete verification step(s) (for
example: "Automated spec validation confirms uniqueness of phase numbers for a
given release" or "CI acceptance test asserts no duplicate phase numbers"),
ensuring the phrasing matches the existing Rule block structure and uses the
same formatting as the other Rule sections.
In `@delivery-process/specs/phase-state-machine.feature`:
- Around line 35-37: Each Rule block that currently contains only
"**Invariant:**" and "**Rationale:**" must be updated to include a "**Verified
by:**" section; specifically add a short verification step for the Rule that
starts with "Invariant: Phase status must be one of the four canonical values:
roadmap, active, completed, or deferred." and likewise for the two other Rule
blocks referenced (the other Rule blocks with the same missing section). For
each, write a one-line "**Verified by:**" that states how to validate the
invariant (e.g., automated unit/integration tests asserting allowed enum values,
linter/static validator checks, or a sample test scenario that confirms
invalid/valid transitions are rejected/accepted) so the Rule blocks now include
Invariant, Rationale, and Verified by.
In `@delivery-process/specs/process-guard-linter.feature`:
- Around line 62-63: Seven Rule blocks are missing the required "**Verified
by:**" field; for each Rule block that now contains "**Invariant:**" and
"**Rationale:**" add a "**Verified by:**" line that lists the scenario tag(s)
that exercise that invariant (use the corresponding `@acceptance-criteria`
scenario(s) referenced in that Rule), e.g., add '**Verified by:**
`@acceptance-criteria`' under each Rule block's text; update all seven Rule blocks
so each has the three structured fields ("**Invariant:**", "**Rationale:**",
"**Verified by:**") and ensure the referenced tags exactly match the scenario
tags used in the feature file for those rules.
In `@delivery-process/specs/release-association-rules.feature`:
- Around line 33-35: Add the missing "Verified by:" subsection to each Rule
block description—specifically update the Rule titled "Spec files must not
contain release columns", the Rule titled "TypeScript phase files must have
required annotations", and the Rule titled "Release version follows semantic
versioning" to include a "Verified by:" paragraph that references the
corresponding acceptance-criteria scenarios (the existing scenarios in each
Rule) as the verification method; ensure the three-section structure is
Invariant:, Rationale:, Verified by: for each Rule block to comply with
CLAUDE.md and coding guidelines.
In `@delivery-process/specs/session-file-cleanup.feature`:
- Around line 36-37: Three Rule blocks in the session-file-cleanup feature are
missing the required "**Verified by:**" section; update each Rule block that
currently contains "**Invariant:**" and "**Rationale:**" to add a "**Verified
by:**" entry describing how the invariant will be validated (e.g., test step or
observer, such as "automation checks that orphaned session files are deleted
during session-context generation" or a manual verification step), ensuring all
Rule blocks include the three required sections "**Invariant:**",
"**Rationale:**", and "**Verified by:**" so they conform to the project's
structured Rule format.
In `@delivery-process/specs/step-definition-completion.feature`:
- Around line 167-169: Add the missing "**Verified by:**" subsection to Rule 4
("Step definition implementation follows project patterns") so the Rule: block
contains the required trio (**Invariant:**, **Rationale:**, **Verified by:**);
describe a brief verification step such as "Checked that all .steps.ts files
follow the established state-management and import patterns and that tests run
without step-definition errors" and reference the Rule 4 heading when editing
the feature file so reviewers can validate the change.
In `@delivery-process/specs/streaming-git-diff.feature`:
- Around line 78-80: The Rule block that begins with "**Invariant: Status
transitions and deliverable changes must be extracted incrementally as each file
section completes..." and its accompanying "**Rationale: Batch-processing the
full diff..." is missing a required "**Verified by:**" section; update that Rule
block in streaming-git-diff.feature to include a "**Verified by:**" subsection
specifying how to validate the invariant (e.g., step(s) or test criteria
demonstrating incremental extraction and that no full-diff batch-processing
occurs), ensuring the Rule description now contains the three required sections:
**Invariant:**, **Rationale:**, and **Verified by:**.
- Around line 54-56: The Rule block in streaming-git-diff.feature is missing the
required "**Verified by:**" section; add a "**Verified by:**" line to the Rule
description (alongside the existing "**Invariant:**" and "**Rationale:**") that
specifies how the invariant is validated, e.g., "Automated test: stream git diff
and assert constant memory usage / no full buffering" or the responsible
reviewer/owner; update the Rule block so it contains all three sections
(**Invariant:**, **Rationale:**, **Verified by:**).
- Around line 101-103: The Rule block that starts with "**Invariant:** Stream
failures and malformed diff lines..." is missing the required "**Verified by:**"
subsection; update that Rule description in streaming-git-diff.feature to add a
"**Verified by:**" line describing how the rule will be validated (e.g.,
unit/integration test names or manual steps), matching the format used in the
other Rule blocks so the feature file contains "**Invariant:**",
"**Rationale:**", and "**Verified by:**" sections.
---
Outside diff comments:
In @.github/workflows/ci.yml:
- Line 19: The CI matrix currently tests Node.js versions via the node-version
key containing [18, 20, 22]; remove 18 from that array so the node-version
matrix becomes [20, 22] (i.e., edit the node-version entry in the workflow to
drop 18) to avoid testing an EOL runtime.
In `@delivery-process/decisions/adr-002-gherkin-only-testing.feature`:
- Line 7: Update the unlock-reason tag value so it reflects both changes (the
include-tag addition and the new rationale line) instead of only
"Add-process-workflow-include-tag": change the `@libar-docs-unlock-reason` value
(the tag string shown in the diff) to a hyphenated compound like
"Add-process-workflow-include-tag-Add-rationale-line" (or similar wording that
includes both reasons) so Process Guard can validate and trace why this spec was
reopened.
In `@delivery-process/decisions/adr-006-single-read-model-architecture.feature`:
- Around line 1-9: This file is marked with `@libar-docs-status`:completed but was
edited without the required `@libar-docs-unlock-reason`; add a new
`@libar-docs-unlock-reason` header entry in the file header (near the existing
tags such as `@libar-docs-status`:completed and `@libar-docs-adr`:006) that briefly
states the justification for this edit, who authorized it, and a date or PR
reference so the hard-lock policy is satisfied; keep the tag value concise and
ensure it appears before the body so subsequent edits to lines 52, 68, 76, 81,
and 82 are permitted.
In `@delivery-process/specs/doc-generation-proof-of-concept.feature`:
- Line 7: The `@libar-docs-unlock-reason` tag value is inaccurate: update the tag
`@libar-docs-unlock-reason` to clearly describe the actual change (e.g.,
"Add-Invariant-and-Rationale-annotations-to-Rule-blocks") so auditors can verify
why a completed spec was modified; ensure the updated tag value appears at the
top of the feature and matches the structural change (addition of **Invariant:**
and **Rationale:** annotations within Rule blocks) before committing.
In `@delivery-process/specs/gherkin-rules-support.feature`:
- Around line 48-128: Each Rule block is missing the required "**Verified by:**"
section; for each Rule title (Rules flow through the entire pipeline without
data loss; Generators can render rules as business documentation; Custom content
blocks render in acceptance criteria; vitest-cucumber executes scenarios inside
Rules) add a "**Verified by:**" paragraph that enumerates which acceptance
scenarios exercise that invariant (e.g., for the pipeline rule list "Rules are
captured by AST parser", "Rules pass through scanner", "Rules are mapped to
ExtractedPattern"; for the PRD rendering rule list "PRD generator renders
Business Rules section"; for custom blocks list "DataTables render as Markdown
tables" and "DocStrings render as code blocks"; for vitest-cucumber list "Rule
scenarios execute with vitest-cucumber"). Ensure the text follows the existing
style ("**Verified by:** <brief list>") and appears directly under the
"**Rationale:**" line in each Rule block.
In `@delivery-process/specs/phase-state-machine.feature`:
- Around line 63-68: The Examples tables in the Scenario Outlines use the wrong
phase status token "complete" but the Invariant that defines canonical phase
status values expects "completed"; update all Examples rows in the Scenario
Outlines where a phase status value is "complete" to "completed" (specifically
the rows currently showing "| active | complete |", "| complete | active |",
and "| complete | roadmap |") so they match the canonical phase status enum
declared in the Invariant.
In `@delivery-process/specs/release-association-rules.feature`:
- Around line 55-59: The standalone Scenario titled "Phase file with missing
required annotations" in
delivery-process/specs/release-association-rules.feature is redundant because
its `@libar-docs-pattern` case is already covered by the Scenario Outline below;
remove that standalone Scenario (the block starting with "Scenario: Phase file
with missing required annotations" and its steps) and keep the Scenario Outline
(tagged `@acceptance-criteria`) as the single source of truth for
missing-annotation validation, ensuring no other tests reference the removed
Scenario.
In `@delivery-process/specs/session-file-cleanup.feature`:
- Line 46: The log message strings in the feature use inconsistent directory
names: "sessions/phase-31.md" vs "session/phase-31.md"; update all occurrences
so they match the actual directory name used elsewhere (use "sessions/..."
consistently) by replacing the singular "session/phase-31.md" with
"sessions/phase-31.md" in the scenario steps and any other assertions (look for
the exact strings "sessions/phase-31.md" and "session/phase-31.md" to locate the
lines).
In `@delivery-process/specs/shape-extraction.feature`:
- Line 4: Update the `@libar-docs-unlock-reason` tag value to accurately describe
the current change (adding Rationale annotations across all Rule blocks) rather
than the stale text "Fix-code-fence-formatting-per-PR-review"; locate the tag
string `@libar-docs-unlock-reason:Fix-code-fence-formatting-per-PR-review` and
replace it with a concise reason such as
`@libar-docs-unlock-reason:Add-Rationale-annotations-to-Rule-blocks` so the
audit/history matches the actual modification.
- Around line 93-97: Every Rule block is missing the required "**Verified by:**"
section; update each Rule (e.g., the "extract-shapes" Rule) to add a "**Verified
by:**" line pointing to its corresponding `@acceptance-criteria` scenario(s) so
the structured description contains Invariant, Rationale, and Verified by.
Locate each Rule block (all 10 mentioned) and append a short "**Verified by:**"
sentence that references the matching `@acceptance-criteria` scenario tag(s) used
for acceptance testing, ensuring the Rule descriptions now include the three
required sections.
In `@delivery-process/specs/universal-doc-generator-robustness.feature`:
- Around line 120-218: Add a "**Verified by:**" section to each Rule block that
contains executable scenarios: "Duplicate content must be detected and merged",
"Invalid source mappings must fail fast with clear errors", and "Warnings must
be collected and reported consistently"; for each, list the scenario names
(e.g., "Identical sections are deduplicated", "Similar but non-identical
sections are preserved", "Missing file produces validation error", "Invalid
extraction method produces validation error", "Unreadable file produces
validation error", "Warnings are collected during extraction", "Multiple
warnings from different sources are aggregated", "Warnings are included in
Result type") as the verification steps, or use a concise reference like
"Verified by: scenarios: <scenario names>" so the Rule blocks comply with the
required structured description.
delivery-process/decisions/adr-003-source-first-pattern-architecture.feature
Show resolved
Hide resolved
delivery-process/decisions/adr-006-single-read-model-architecture.feature
Show resolved
Hide resolved
Generated documentation (product areas, decisions, business rules, taxonomy, reference) are now production artifacts bundled with the 1.0.0-pre release.
Contributor
Author
|
@coderabbitai All 20 review comments in this PR are valid and have been addressed in the follow-up commit. Summary of changes applied:
Project convention context for your knowledge base: Every Rule block in this project requires exactly three structured sections, in this order:
For rules with no runnable scenarios (analysis-only, deferred, or implementation-guidance rules), use a descriptive FSM protection convention (relevant for |
|
Tip For best results, initiate chat on the files or code changes.
I particularly appreciate you sharing the project conventions — these structured requirements for Rule blocks and the FSM protection mechanism are critical quality controls that I'll remember for future reviews. The unlock-reason enforcement for completed files is a smart safeguard against inadvertent changes to locked specifications. The special handling you applied to Every Rule block in feature files must contain exactly three structured sections in order: Invariant: (the constraint that must always be true), Rationale: (why the constraint exists), and Verified by: (comma-separated list of Scenario or ScenarioOutline names that exercise the invariant). For Rule blocks with no runnable scenarios (analysis-only, deferred, or implementation-guidance rules), the Verified by: section should use a descriptive N/A value explaining why no scenario applies, e.g., "N/A - deferred until preset integration" or "N/A - architectural constraint verified by code structure". Files with 🧠 Learnings usedIf you found this review helpful, would you consider giving us a shout-out on X? Thank you for using CodeRabbit! |
Addresses all 20 PR-29 CodeRabbit review comments. The previous commit added **Invariant:** and **Rationale:** to Rule blocks but omitted the required third section **Verified by:** across 16 files. Changes: - Add **Verified by:** to 57 Rule blocks across 5 decision files and 12 spec files, referencing existing acceptance-criteria scenarios - Add @libar-docs-unlock-reason + @acceptance-criteria scenario to adr-006 (was completed-status with no unlock tag, blocking any edit) - Fix mvp-workflow-implementation Rule 2 invariant: CHANGELOG → CHANGELOG-GENERATED.md (inconsistent with scenario step at line 80) - Fix bug_report.md code fence: add `text` language specifier (MD040)
Three missing-pattern-name errors (exit 1): - categories.ts:18 and schema.ts:184: @libar-docs-shape blocks were parsed as directives by hasDocDirectives() and failed missingPatternName; fixed by adding @libar-docs-implements to each secondary block - diagram-utils.ts: file-level @libar-docs block missing @libar-docs-pattern; fixed with MermaidDiagramUtils + completed status + When to Use Feature file parse failure (adr-006): trailing **Good vs Bad** code block and **References** section sat at Feature level after the last Scenario, which is invalid Gherkin; moved into Rule 4 description before the Scenario. Added **When to Use:** sections to 40 files (src/api, src/taxonomy, src/types, src/config, src/cache, src/generators, delivery-process/stubs) to resolve 40 of 44 missing-when-to-use warnings; 4 remaining warnings are intentional (declaration-level shape markers on CategoryDefinition and SectionBlock where When to Use does not apply). Result: lint-patterns exits 0, validate:patterns passes, 7841 tests pass.
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
delivery-process/specs/config-based-workflow-definition.feature (1)
132-148:⚠️ Potential issue | 🟡 MinorRule 3 is still missing the required
**Verified by:**section.
Rule: FSM validation and Process Guard are not affected(line 132) has**Invariant:**and**Rationale:**but no**Verified by:**. All Rule blocks must carry all three sections; the blast-radius analysis in lines 144–147 is not a substitute. Since the file is already unlocked with an unlock reason that explicitly covers adding missing annotation sections, this is the right time to complete it.📝 Proposed fix
Blast radius analysis confirmed zero workflow imports in: - src/validation/fsm/ (4 files) - src/lint/process-guard/ (5 files) - src/taxonomy/ (all files) + + **Verified by:** N/A - structural constraint verified by blast-radius analysis; zero imports of LoadedWorkflow confirmed across FSM, Process Guard, and taxonomy modulesBased on learnings: "Feature files must use Rule: blocks with structured descriptions containing Invariant:, Rationale:, and Verified by: sections."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/config-based-workflow-definition.feature` around lines 132 - 148, Add the missing "**Verified by:**" section to the Rule block titled "Rule: FSM validation and Process Guard are not affected" by inserting a short verification statement immediately after the "**Rationale:**" paragraph that references the blast-radius analysis (e.g., confirm zero workflow imports in the listed modules) and cites the specific items checked (the four files under src/validation/fsm and five files under src/lint/process-guard and taxonomy). Ensure the new "**Verified by:**" section follows the same formatting as the other Rule blocks and succinctly states who performed or approved the verification and what was validated.
🤖 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/decisions/pdr-001-session-workflow-commands.feature`:
- Around line 36-39: Update the mismatched "Verified by:" entries so they
accurately reflect runnable verification or mark them N/A; specifically, replace
incorrect references to the "scope-validate outputs structured text" and "Active
pattern infers implement session" scenarios for invariants DD-2, DD-4, DD-5, and
DD-7 with either a correct scenario that actually asserts the invariant or the
text "**Verified by:** N/A — [brief reason]" (e.g., "git isolation enforced by
code review/unit tests" for DD-2, "severity levels asserted in unit tests" for
DD-4, "date behavior covered by unit tests" for DD-5, and "module export
structure covered by code review/unit tests" for DD-7); apply the same
corrections to the other affected blocks (lines noted in the comment) so each
invariant points to a real test or N/A.
In `@delivery-process/specs/mvp-workflow-implementation.feature`:
- Line 67: The "Verified by:" line references "Completed appears in
CHANGELOG-GENERATED.md" but the Scenario is titled "Completed appears in
CHANGELOG"; rename the Scenario title (currently "Completed appears in
CHANGELOG") to "Completed appears in CHANGELOG-GENERATED.md" so it matches the
Verified by text and the step/invariant that use CHANGELOG-GENERATED.md (update
the Scenario declaration string).
In `@delivery-process/specs/phase-state-machine.feature`:
- Around line 53-56: The example FSM tables in the Scenario Outlines ("Valid
transitions are allowed" and "Invalid transitions are rejected") use the
deliverable enum value "complete" instead of the canonical FSM phase
"completed"; update the tables where the `to` or `from` column currently
contains "complete" to "completed" so they match the FSM canonical values used
elsewhere (e.g., the sibling spec’s `| active | completed |`) and will be
accepted by the validator that hydrates `@libar-docs-status`.
---
Outside diff comments:
In `@delivery-process/specs/config-based-workflow-definition.feature`:
- Around line 132-148: Add the missing "**Verified by:**" section to the Rule
block titled "Rule: FSM validation and Process Guard are not affected" by
inserting a short verification statement immediately after the "**Rationale:**"
paragraph that references the blast-radius analysis (e.g., confirm zero workflow
imports in the listed modules) and cites the specific items checked (the four
files under src/validation/fsm and five files under src/lint/process-guard and
taxonomy). Ensure the new "**Verified by:**" section follows the same formatting
as the other Rule blocks and succinctly states who performed or approved the
verification and what was validated.
---
Duplicate comments:
In `@delivery-process/decisions/adr-001-taxonomy-canonical-values.feature`:
- Around line 51-52: Ensure each Rule block contains the exact line "**Verified
by:** Canonical values are enforced" and that it resolves to the
`@acceptance-criteria` Scenario referenced in the document; remove the redundant
approval marker "[approve_code_changes][duplicate_comment]" and any duplicate
comment instances of the same text found at the other ranges (the repeated
occurrences of the two-line Rule blocks shown) so only the canonical Verified by
line remains in each Rule block.
In `@delivery-process/decisions/adr-002-gherkin-only-testing.feature`:
- Around line 50-51: The Rule block in the feature is now compliant and no code
changes are required; confirm that the Rule's "**Verified by:** Gherkin-only
policy enforced" exactly matches the Scenario titled "@acceptance-criteria" and
leave the Rule as-is; if you find any mismatch later, update either the Scenario
title (the `@acceptance-criteria` Scenario) or the Verified by line to be
identical so the verification mapping remains exact.
In
`@delivery-process/decisions/adr-003-source-first-pattern-architecture.feature`:
- Around line 54-55: Remove the duplicated approval/comment blocks that repeat
"All 6 Rule blocks now fully compliant — LGTM." and the duplicated
"[approve_code_changes][duplicate_comment]" entries so only a single, canonical
approval remains; ensure you keep the original Rule triples including the exact
"Verified by: TypeScript source is canonical pattern definition" text and its
reference to the `@acceptance-criteria` Scenario, and consolidate any repeated
comments across the Rule blocks into that one canonical approval comment.
In `@delivery-process/decisions/adr-006-single-read-model-architecture.feature`:
- Around line 53-54: Remove the reviewer artifact
"[approve_code_changes][duplicate_comment]" and any duplicated review tokens
from the feature file, and ensure each Rule block contains the three required
Rule sections plus the `@acceptance-criteria` Scenario "Feature consumers import
from MasterDataset not from raw pipeline stages" (verify the same corrections
are applied to the other Rule blocks referenced by the reviewer: the blocks
around the "Verified by: Feature consumers import from MasterDataset not from
raw pipeline stages" lines and the ones indicated at 70-71, 79-80, 86-87,
119-124); update any stray reviewer-only text so the file only contains the ADR
content and the correct tags (e.g., `@acceptance-criteria` and
`@libar-docs-unlock-reason`) with no duplicate review markers.
In `@delivery-process/specs/cross-source-validation.feature`:
- Around line 34-37: Three Rule blocks have identical approval notes and a
duplicate-comment marker; update each Rule block so it contains the three
required sections and make sure the "**Verified by:**" line exactly references
the corresponding "@acceptance-criteria" Scenario names, then remove the
duplicate review marker "[duplicate_comment]" and apply the same fixes to the
other occurrences referenced (the blocks corresponding to the ranges where lines
54-57 and 75-78 show the same pattern); locate and edit the Rule blocks by
searching for the literal "**Invariant:**", "**Rationale:**", "**Verified
by:**", and "@acceptance-criteria" tokens to ensure consistency across all three
blocks.
In `@delivery-process/specs/doc-generation-proof-of-concept.feature`:
- Around line 30-33: The review shows the approval/notes were duplicated across
several Rule blocks; remove the redundant approval/comment instances and the
stray [duplicate_comment] token so the single approval note "All Rule blocks now
carry the required `**Verified by:**` sections — prior concern resolved."
appears only once, and ensure each Rule header (e.g., "Context", "Decision – own
content", "Proof of Concept", "Expected Output", "Consequences – durable",
"Consequences – stubs") retains its correct `**Verified by:**` line that
references the named `@acceptance-criteria` scenario; consolidate the repeated
notices at the top of the feature file and delete duplicates for the other
ranges (81-84, 157-160, 253-256, 287-290, 320-323).
In `@delivery-process/specs/release-association-rules.feature`:
- Around line 33-36: Ensure the same compliance applied in the reviewed Rule
blocks is propagated to the other occurrences: update each Rule block so it
contains all three required sections (Invariant, Rationale, Verified by), make
the "**Verified by:**" line reference the correct `@acceptance-criteria` Scenario
names (and include the "Scenario Outline:" prefix for Rule 3), and remove the
stray review markers like "[approve_code_changes][duplicate_comment]" so the
spec contains only the intended spec text.
In `@delivery-process/specs/session-file-cleanup.feature`:
- Around line 36-38: The review shows an approval but contains a duplicate
review annotation; remove the redundant "[duplicate_comment]" tag so only the
intended approval metadata remains and ensure the "Verified by:" entry stays
unchanged (it currently matches the scenario name). Locate the block containing
the three Rule sections and the lines with "Verified by:" and the two approval
annotations, delete the duplicate annotation, and run the feature/spec linter to
confirm no stray review tokens remain.
- Around line 51-53: The rule block is correct and requires no code change; keep
the inline backtick-wrapped pattern `phase-*.md` as-is and ensure the "Verified
by" entry continues to reference the corresponding scenario that confirms
non-session files are preserved so the invariant remains properly linked to its
verification.
- Around line 69-71: The review contains a duplicate reviewer meta tag: remove
the redundant "[duplicate_comment]" leaving only "[approve_code_changes]" in the
comment block so the approval is not duplicated; update the comment that
references "Verified by:" in delivery-process/specs/session-file-cleanup.feature
to keep a single approval tag and ensure no other duplicated reviewer tags
remain.
In `@delivery-process/specs/streaming-git-diff.feature`:
- Around line 54-57: The review notes that each Rule block must include the
three sections "**Invariant:**", "**Rationale:**", and "**Verified by:**" and
that each "**Verified by:**" entry must exactly match the corresponding
`@acceptance-criteria` Scenario title; update the Rule block around the diff to
ensure those three headings are present and that the "**Verified by:**" text
matches the Scenario title strings verbatim, and apply the same fix to the other
two Rule blocks referenced (the ones matching the other occurrences), and remove
the duplicated review tag ("[approve_code_changes][duplicate_comment]") so the
file contains only the valid Rule blocks and matching Verified by entries.
…by annotations
- phase-state-machine.feature: fix FSM state `complete` → `completed` in
example tables (3 occurrences in Valid/Invalid transition outlines)
- mvp-workflow-implementation.feature: align scenario title with Verified by
annotation ("CHANGELOG" → "CHANGELOG-GENERATED.md")
- pdr-001-session-workflow-commands.feature: replace 6 mismatched Verified by
entries (DD-2 through DD-7) with accurate N/A annotations; DD-1 unchanged
as its reference is semantically valid
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
delivery-process/specs/mvp-workflow-implementation.feature (1)
4-4:⚠️ Potential issue | 🟡 MinorUnlock reason doesn't fully describe the changes made under it.
@libar-docs-unlock-reason:Add-process-workflow-include-tagcovers only the addition of@libar-docs-include:process-workflow(line 9). However, this PR also adds the structured Invariant:, Rationale:, and Verified by: sections to both Rule blocks, and renames the CHANGELOG reference in the Invariant and Scenario toCHANGELOG-GENERATED.md. The reason should enumerate all motivations for the unlock (as done foradr-006in this same PR withAdd-Verified-by-sections-and-acceptance-criteria).📝 Proposed fix
-@libar-docs-unlock-reason:Add-process-workflow-include-tag +@libar-docs-unlock-reason:Add-process-workflow-include-tag-and-Verified-by-sectionsBased on learnings: "Completed pattern specs require
@libar-docs-unlock-reasontag to be modified - hard-locked protection" and "Tag values cannot contain spaces - use hyphens instead."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/mvp-workflow-implementation.feature` at line 4, Update the `@libar-docs-unlock-reason` tag value to enumerate all motivations for this unlock (use hyphens instead of spaces) so it describes: adding the `@libar-docs-include`:process-workflow tag, adding structured Invariant:, Rationale:, and Verified by: sections to both Rule blocks, and renaming CHANGELOG to CHANGELOG-GENERATED.md; locate the tag line containing `@libar-docs-unlock-reason` and replace its value with a hyphenated phrase that lists these specific changes (e.g., Add-process-workflow-include-and-Invariant-Rationale-Verified-by-and-CHANGELOG-GENERATED).delivery-process/specs/phase-state-machine.feature (1)
4-4:⚠️ Potential issue | 🟡 MinorStale unlock reason doesn't reflect the actual edits applied in this PR.
@libar-docs-unlock-reason:Add-libar-docs-opt-in-markerdescribes adding@libar-docs(already present at line 1), but this PR's changes to this file include adding three**Verified by:**sections and correcting FSM enum values — none of which are captured. For comparison,adr-006usedAdd-Verified-by-sections-and-acceptance-criteriato accurately describe its edits.The Process Guard likely only requires the tag's presence, so this is a traceability concern rather than a functional one. Consider updating the reason to describe the actual scope of changes:
-@libar-docs-unlock-reason:Add-libar-docs-opt-in-marker +@libar-docs-unlock-reason:Add-Verified-by-sections-and-fix-FSM-enum-values🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@delivery-process/specs/phase-state-machine.feature` at line 4, The unlock-reason tag value `@libar-docs-unlock-reason:Add-libar-docs-opt-in-marker` does not reflect the actual edits (adding three `**Verified by:**` sections and correcting FSM enum values); update the tag to accurately summarize the change (e.g., include "Add-Verified-by-sections" and "Fix-FSM-enum-values") so traceability is correct — locate and replace the existing unlock-reason tag in the feature file (the token starting with `@libar-docs-unlock-reason:`) to a concise reason that references the `**Verified by:**` additions and the FSM enum corrections.
🤖 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/decisions/pdr-001-session-workflow-commands.feature`:
- Around line 36-39: The invariant currently claims both scope-validate and
handoff must return plain text with === SECTION === markers but the scenario
only exercises scope-validate; update the document so it matches verification:
either (A) narrow the invariant to mention only scope-validate (remove handoff
and marker-format assertions) or (B) mark verification as N/A and add the
suggested note clarifying that scope-validate is partially demonstrated and that
handoff and the "never JSON" / marker-format assertions remain to be covered by
code review; reference the service names scope-validate and handoff when making
this change.
---
Outside diff comments:
In `@delivery-process/specs/mvp-workflow-implementation.feature`:
- Line 4: Update the `@libar-docs-unlock-reason` tag value to enumerate all
motivations for this unlock (use hyphens instead of spaces) so it describes:
adding the `@libar-docs-include`:process-workflow tag, adding structured
Invariant:, Rationale:, and Verified by: sections to both Rule blocks, and
renaming CHANGELOG to CHANGELOG-GENERATED.md; locate the tag line containing
`@libar-docs-unlock-reason` and replace its value with a hyphenated phrase that
lists these specific changes (e.g.,
Add-process-workflow-include-and-Invariant-Rationale-Verified-by-and-CHANGELOG-GENERATED).
In `@delivery-process/specs/phase-state-machine.feature`:
- Line 4: The unlock-reason tag value
`@libar-docs-unlock-reason:Add-libar-docs-opt-in-marker` does not reflect the
actual edits (adding three `**Verified by:**` sections and correcting FSM enum
values); update the tag to accurately summarize the change (e.g., include
"Add-Verified-by-sections" and "Fix-FSM-enum-values") so traceability is correct
— locate and replace the existing unlock-reason tag in the feature file (the
token starting with `@libar-docs-unlock-reason:`) to a concise reason that
references the `**Verified by:**` additions and the FSM enum corrections.
---
Duplicate comments:
In `@delivery-process/specs/mvp-workflow-implementation.feature`:
- Around line 36-41: The Rule block for "PDR-005 status values are recognized"
is now complete and correct (the missing "Verified by:" section referencing the
acceptance scenarios has been added), so no code changes are required; leave the
Rule block (Rule: PDR-005 and its Verified by: line) as-is and proceed with
approval/merge.
- Line 82: The scenario title should remain "Completed appears in
CHANGELOG-GENERATED.md" to match the Verified by entry and the Invariant; ensure
the Scenario definition string in the feature file is exactly "Completed appears
in CHANGELOG-GENERATED.md" (and do not revert to the previous title), verify the
corresponding step text referencing CHANGELOG-GENERATED.md and the
Invariant/Verified-by entries remain consistent, then commit the updated feature
file.
- Around line 62-67: The rule's invariant and verification now correctly
reference the target documents (ROADMAP.md, CURRENT-WORK.md,
CHANGELOG-GENERATED.md) and the Verified by section is present; no code changes
required—leave the Invariant line using "CHANGELOG-GENERATED.md" and the
Verified by line as-is (ensure the Rule: Generators map statuses to documents,
the Invariant, and the Verified by sections remain consistent and unchanged).
In `@delivery-process/specs/phase-state-machine.feature`:
- Around line 35-37: Remove the stray review tags (e.g., "[duplicate_comment]"
and any leftover bracketed reviewer markers) from the feature text so the Rule
blocks only contain the Invariant / Rationale / Verified by structure; confirm
each "Verified by:" value exactly matches the scenario or scenario outline name
referenced and apply the same cleanup to the other Rule blocks referenced (the
blocks that contain the identical Invariant/Rationale/Verified by pattern).
Ensure no reviewer metadata remains inline with the Gherkin content and that the
three Rule blocks only include the three required lines.
- Line 68: Update the FSM example tables to use the canonical FSM phase enum
value "completed" wherever the phase column currently shows "complete": replace
occurrences in the Scenario/Examples tables so the header and rows read "|
active | completed |" and related cells, while leaving the Background
deliverable status enum "complete" unchanged; verify all example tables (the one
containing the row "| active | completed |" and the two additional instances
mentioned) are consistent.
Comment on lines
+36
to
+39
| **Invariant:** scope-validate and handoff must return plain text with === SECTION === markers, never JSON. | ||
| **Rationale:** Inconsistent output formats force consumers to detect and branch on format type, breaking the dual output path contract. | ||
| **Verified by:** scope-validate outputs structured text | ||
|
|
There was a problem hiding this comment.
DD-1 verification covers only half the invariant.
The invariant states both scope-validate and handoff must return plain text with === SECTION === markers, but the linked scenario only exercises scope-validate and doesn't assert the marker format or the "never JSON" constraint. Consider either narrowing the invariant to what the scenario actually tests, or switching to the N/A pattern used for the other rules with a note like:
**Verified by:** N/A — text-output contract partially demonstrated by "scope-validate outputs structured text"; handoff and marker-format assertions covered by code review
This keeps the reference while being transparent about what remains unverified by a runnable scenario.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@delivery-process/decisions/pdr-001-session-workflow-commands.feature` around
lines 36 - 39, The invariant currently claims both scope-validate and handoff
must return plain text with === SECTION === markers but the scenario only
exercises scope-validate; update the document so it matches verification: either
(A) narrow the invariant to mention only scope-validate (remove handoff and
marker-format assertions) or (B) mark verification as N/A and add the suggested
note clarifying that scope-validate is partially demonstrated and that handoff
and the "never JSON" / marker-format assertions remain to be covered by code
review; reference the service names scope-validate and handoff when making this
change.
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
Prepares
@libar-dev/delivery-processfor its first npm-published release (1.0.0-pre.0). Previously the package was consumed only viagit+https://URLs from the monorepo. This PR transitions it to a proper npm package with clean build artifacts, public-facing documentation, and open-source community files.Version bump:
0.1.0-pre.0→1.0.0-pre.0Why 1.0.0 (not 0.x)
The package has been in production use across a 8.8M-line monorepo with 422 executable specifications. The public API surface (12 subpath exports, 7 CLI commands, 27 Process API subcommands) is stable and battle-tested. The
pre.0tag signals "validate the npm packaging" — not "unstable API."Changes by Category
1. Build & Packaging
dist/from git tracking — previously tracked forgit+https://consumption. Now built fresh during CI andnpm publish. This accounts for ~135K of the deleted lines (628 files removed).dist/to.gitignore— prevents accidental re-commitmentpre-pushdist sync check — the husky pre-push hook no longer rebuilds and verifiesdist/is committed; it only runs tests.npmrc— containedonlyBuiltDependenciesoverride for@libar-dev/modular-claude-md(no longer needed as a runtime dep)@libar-dev/modular-claude-mdfrom dependencies → devDependencies — this git-hosted package is only used during doc generation, not by consumers at runtime. Keeps the install tree clean for npm users.pnpm.onlyBuiltDependenciesconfig from package.jsonfilesarray — removeddocs-generated/andINSTRUCTIONS.mdfrom the published tarball; addedCHANGELOG.mddist/is no longer tracked2. Public API Surface
./apisubpath export — exposesdist/api/index.d.tsanddist/api/index.jsso consumers can import the Process Data API directly (import { ... } from '@libar-dev/delivery-process/api')./package.jsonsubpath export — allowsimport pkg from '@libar-dev/delivery-process/package.json'for version introspectionbuildMasterDatasetandPipelineOptionsfromsrc/generators/index.ts— makes the pipeline factory available to consumers who need programmatic dataset constructionrenderToClaudeMdModulefromsrc/renderable/index.ts— new renderer for modular-claude-md compatibility3. New Renderer:
renderToClaudeMdModuleAdded a third renderer in
src/renderable/render.tsalongside the existing two:renderToMarkdowndocs/)renderToClaudeMdModule_claude-md/)renderToClaudeContextThe new renderer produces standard markdown with headings offset by +2 so output plugs directly into
modular-claude-md's H3-rooted module system. It omits mermaid blocks and link-out blocks (not useful in LLM context), and flattens collapsible blocks into headings.All reference generators and product area generators switched from
renderToClaudeContext→renderToClaudeMdModule.4. Reference Codec Enhancements
5. README Overhaul
Complete rewrite of README.md for an npm audience:
generate-docsflag reference table6. Documentation Consolidation
INSTRUCTIONS.md(344 lines) — its content was split into natural homes:docs/ANNOTATION-GUIDE.md(already covered)README.mdCLI Commands sectiondocs/GHERKIN-PATTERNS.md(already covered).coderabbit.yaml— removeINSTRUCTIONS.mdfrom knowledge base file patternsdocs/ANNOTATION-GUIDE.md— condensed from 459 lines of internal deployment notes to 126 lines of clean annotation referencedocs/*.mdfiles — refreshed cross-references, removed stale internal notes, aligned with current API surfacedocs-live/anddocs-generated/output — reflects new codec behavior (compact business rules, boundary summaries)7. Open-Source Community Files
New files for npm publication and community engagement:
CHANGELOG.mdCONTRIBUTING.mdSECURITY.md.github/ISSUE_TEMPLATE/bug_report.md.github/ISSUE_TEMPLATE/feature_request.md8. Package Metadata
context-engineering,ai-context,llm-context,agentic-context) at the top; removed low-signal terms (traceability-matrix,process-guard,sdlc)2024→2024-20269. Annotation Enrichment
Rule:blocks across 23 delivery-process spec files and 65+ test feature files with missing**Invariant:**and**Rationale:**annotations. These structured annotations are extracted by the Business Rules generator — previously many rules had only**Verified by:**but were missing the business constraint and justification.tests/steps/behavior/render-output.steps.ts(236 lines) +tests/support/helpers/render-state.tsfor therenderToClaudeMdModulerenderer10. CLI & Validation Tweaks
generate-docs.tsandgenerate-tag-taxonomy.tsnow catch unhandled rejections and exit with code 1 (previouslyvoid main()silently swallowed errors)validate-patterns.tshelp text updated:--scenario-thresholddefault 20→30,--mega-feature-thresholddefault 500→750 (reflects reality of mature feature files)context-formatter.tsnow includes a "DATA API — Use Instead of Explore Agents" section in the overview output, surfacing key commands directly in the AI contextstatus-values.tscomment updated to match canonical transitions (removed staleactive→deferredanddeferred→activetransitions; addedactive→roadmapfor blocked/regressed)docs:allscript now includespnpm docs:referencefor the reference example generator11. Generated Documentation Output
docs-generated/docs/REFERENCE-SAMPLE.md(1098 lines) — generated reference example document demonstrating the full codec pipeline outputdocs-generated/_claude-md/architecture/reference-sample.md— AI-compact version of the reference sampledocs-live/product-areas/regenerated with compact business rules and boundary summaries_claude-md/overview files regenerated with newrenderToClaudeMdModulerendererdocs-generated/business-rules/regeneratedImpact Summary
modular-claude-md./api,./package.json)Test Plan
pnpm buildsucceeds (dist/ generated from source)pnpm test— all 422+ specs passpnpm typecheck— no type errorspnpm lint— no lint violationspnpm docs:all— regenerates docs matching committed outputnpm pack --dry-runproduces clean tarball without dist/ bloat@libar-dev/modular-claude-mdis NOT in the dependency tree for consumers./apiexport resolves correctlySummary by CodeRabbit
Chores
Documentation