fix: PR #711 follow-ups — canonical BR IDs, runtime state-version par…

[SiddhJog]

PR #711 follow-ups (2.6.2)

Follow-up fixes to the merged 2.6.1 design-output restructure (#711). This PR ships as 2.6.2 — the merged ## [2.6.1] release history is preserved byte-identical, and a new ## [2.6.2] entry is added on top. No stage-graph or artifact-name changes; this is a correctness/consistency patch.

Addresses leandro's three review rounds on #751 (findings converged across rounds; the list below reflects what actually ships in d8786a67).

Canonical business-rule ID format

Business rules use BRx.y end-to-end (the format the traceability sensor's regex recognizes). Removed the sensor-incompatible BR-NNN authoring instruction from Functional Design and the product-agent functional-design guide, and replaced the org-level stable-ID example BR-003 with BR1.1 in core/memory/org.md so agents no longer receive a conflicting authoritative example alongside the stage prose.

Runtime state-version guard + doctor unified through a shared classifier

Extracted classifyStateVersion() into core/tools/aidlc-lib.ts as the single source of truth. Both aidlc-orchestrate.ts (runtime next/report) and aidlc-utility.ts (doctor) call it, so they can't drift on how a state file is classified. The classifier returns ok | unparseable | past | future, and each caller renders the branch-appropriate message.

Hardened against every fail-open path the reviews flagged across rounds:

• Present-but-zero-byte aidlc-state.md is rejected. Both call sites now test !== null instead of truthiness (an empty string is falsy and previously slipped through).
• Cross-line whitespace regex bug fixed: parser uses [ \t]* (horizontal whitespace only) instead of \s*, so an empty value can no longer capture the leading - of the next state bullet as the bogus token -.
• Trailing content on the value line rejected: the value is anchored to end-of-line, so State Version: 8 garbage falls into the unparseable branch rather than being accepted as v8. 7 archived likewise routes as unparseable, not past-version.
• Non-numeric values route through the unparseable branch (the schema token must be a bare integer).
• Future numeric versions (e.g. v9) are reported as newer than this build's v8 with upgrade guidance, not archive-and-reinit — the past-version's mv aidlc aidlc.v{v}-archive template is deliberately absent from the future branch.
• Doctor now emits per-branch failing rows aligned with the runtime classifier: state version readable (unparseable), state version current (past), state version compatible (future), and the passing State Version: 8 row.

Domain Design traceability vocabulary

Constrained to components/entities defined in components.md (the stage's source of truth). Example is now AuthComponent rather than AuthService.login(), with a note that method- and API-level targets are pinned later in Contract Design and Functional Design.

Documentation alignment

• Units Generation output count corrected from 3 to 4 in both the reference doc (docs/reference/04-stages/inception.md) and the authored stage prose (core/aidlc-common/stages/inception/units-generation.md Step 6), so it matches the four artifacts declared in outputs: (including traceability.json).
• Units Generation Outputs table adds traceability.json in the reference doc.
• Domain Design Outputs table adds traceability.json in the reference doc.
• Delivery Planning Inputs list adds contract-summary.md in the reference doc.
• docs/reference/04-stages/inception.md "Key Outputs" summary numbering fixed after inserting Contract Summary.

(Note: ## Stage 2.8: Contract Design was authored in #711 and merged onto v2 — this PR does not add it.)

Verification

• bun scripts/package.ts --check clean across all seven harnesses
• bun tests/gen-coverage-registry.ts --check clean
• tests/unit/t282-state-version-doctor.test.ts: 17 pass / 0 fail (covers all four classifier branches for both runtime and doctor, plus zero-byte and trailing-content regressions)
• Full unit tier via 4 parallel runs: 202/203 pass; the 1 is t248-codekb-scope-diff, a known git-fingerprint environmental failure on clean v2
• Minimal-state spot-checks (t230, t229, t165, t224): 133 pass / 0 fail — the hardened guard does not break existing fixtures
• Classifier propagated to all seven harness dist/ trees (lib + orchestrate + utility)
• 0 behind / 1 ahead of v2

[leandrodamascena]

Siddhesh, thanks for following up on the review items from #711. I reviewed c1378b9 and verified that most of the requested changes are present:

• Functional Design and the product-agent guide now use the canonical BRx.y format.
• Domain Design traceability guidance now targets components/entities from components.md.
• The Inception reference now documents Contract Design, contract-summary.md, and the traceability outputs.
• Runtime tests were added for missing, empty, and malformed State Version values.
• Generated harness trees remain in parity.

I found the following remaining issues:

Merge blocker: the PR deletes the already-merged 2.6.1 release history

PR #711 has now merged into v2 as 2.6.1. This PR changes the existing release heading, version constant, README badge, and generated versions backward to 2.6.0.

The Changelog completeness check is correctly failing with:

this PR removes CHANGELOG entries present on the base:

• [2.6.1]

Now that 2.6.1 exists in merged history, it cannot be retroactively renamed or removed. This follow-up is a new user-visible patch and should:

• preserve the complete existing 2.6.1 changelog entry;
• add a new 2.6.2 heading describing these follow-up fixes and upgrade guidance;
• set core/tools/aidlc-version.ts and the README badge to 2.6.2;
• regenerate all harness dist/.../aidlc-version.ts copies.

If another version lands first, use the next available patch according to the conflict-trap policy.

P2: a zero-byte state file still bypasses the runtime compatibility guard

The new validator correctly rejects a non-empty state whose State Version field is missing. However, both call sites invoke it only when the loaded content is truthy:

• core/tools/aidlc-orchestrate.ts:2633
• core/tools/aidlc-orchestrate.ts:5223

A present but zero-byte aidlc-state.md returns an empty string, so the validator is skipped entirely. next can then proceed through workflow-creation behavior instead of refusing the corrupted state.

Please distinguish state file absent from state file present but empty, invoke the compatibility check for the latter, and add next/report regressions using an actual zero-byte state file.

P2: the State Version parser consumes the next line for an empty value

The runtime and doctor regex use:

/^- State Version:\s*(\S+)/m

Because \s* includes newlines, an empty State Version value can capture the leading - from the next state bullet. I confirmed this directly: an empty version followed by - Skeleton Stance: on produces the captured version "-".

The current test passes because it accepts either generic incompatibility wording or missing, empty, or unparseable, so it does not verify which parser branch ran.

Please:

• replace cross-line whitespace with horizontal whitespace, such as [ \t]*;
• validate the captured version as a supported numeric schema token;
• assert the exact missing/empty/malformed remediation in the tests;
• add a future numeric version case and report it as incompatible rather than saying it predates v8.

P3: global stable-ID guidance still advertises the removed BR format

The stage and product-agent guide now correctly use BR1.1, but the mandatory organization guidance still lists BR-003 as a preserved stable-ID token:

• core/memory/org.md:97

Agents receive this global rule alongside the stage instructions, so the old sensor-incompatible format remains a conflicting authoritative example.

Please update the global stable-ID guidance and regenerate the harness copies.

P3: Units Generation reference still says three outputs

The corrected output table now lists four artifacts, including traceability.json, but the generation step still says:

generate the 3 output artifacts

at:

• docs/reference/04-stages/inception.md:985-986

Please update that count to four.

The functional follow-ups are largely correct, but the changelog guard is a hard merge blocker and the State Version path still has two fail-open/parser gaps. I recommend keeping this changes requested until those are addressed.

[SiddhJog]

Thanks @leandrodamascena — all five items addressed on 76352512:

1. Changelog completeness — merge blocker resolved

The 2.6.1 entry is now preserved byte-identical to origin/v2 (verified via git diff --unified=0 origin/v2 -- CHANGELOG.md | grep -E '^-#' → empty). A new ## [2.6.2] - 2026-08-13 heading was added on top with the follow-up summary and upgrade guidance. aidlc-version.ts, the README badge, and all seven dist/*/.../tools/aidlc-version.ts copies are 2.6.2; t68 green.

2. Zero-byte state file bypass

Both call sites (next and report) now check stateContent !== null rather than truthiness, so a present-but-zero-byte aidlc-state.md returns "" and still invokes the guard. New t282 regressions write an actual zero-byte file (writeFileSync(..., "", "utf-8")) for both next and report and assert the unparseable-branch remediation.

3. State Version regex + numeric validation + future-version branch

• The \s* bug is fixed in both the runtime guard (aidlc-orchestrate.ts) and the doctor (aidlc-utility.ts): both now use /^- \*\*State Version\*\*:[ \t]*(\S+)/m. An empty version can no longer capture the next bullet's -.
• Captured version is validated as bare \d+; a non-numeric value goes through the unparseable branch.
• A future numeric version (e.g. 9) is reported as "newer than the current v8" with upgrade guidance, not as "predates v8".
• t282 assertions now pin the exact branch (UNPARSEABLE vs predates the current vs is newer than the current), so a future regression that trips the wrong branch is caught.

4. BR-003 in global stable-ID guidance

core/memory/org.md line 97 now reads stable IDs (`FR-1`, `ENT-001`, `BR1.1`). Grep for BR-003 / BR-NNN across core/ and harness/ returns no matches, so agents no longer receive a sensor-incompatible authoritative example alongside the stage instructions.

5. Units Generation "3 output artifacts"

docs/reference/04-stages/inception.md:986 now reads "generate the 4 output artifacts", coherent with the Outputs table (which already lists four including traceability.json).

Verification

• bun scripts/package.ts --check clean; coverage registry --check clean
• t282 (11 tests, includes zero-byte + future-version + exact-branch assertions): 0 fail
• Minimal-state spot-checks (t230, t229, t165, t224): 133 pass / 0 fail — the tightened guard doesn't break existing fixtures
• Full unit tier via 4 parallel runs: 203/204 pass; the 1 is t248-codekb-scope-diff, a known git-fingerprint environmental failure on clean v2
• An independent no-context review confirms each finding is fixed and dist/ is in byte-parity with authored source
• 0 behind / 1 ahead of v2

[leandrodamascena]

Siddhesh, thanks for the thorough follow-up. I re-reviewed 7635251 and verified that the previous blockers are resolved:

• the merged 2.6.1 history is preserved and the follow-up correctly ships as 2.6.2;
• zero-byte state files are now rejected by both next and report;
• State Version parsing no longer crosses line boundaries;
• malformed and future numeric versions are distinguished at runtime;
• the global BR guidance now uses the canonical BRx.y format;
• Units Generation and Inception reference documentation are aligned;
• all generated harness trees are in parity;
• CI, changelog completeness, smoke, and unit checks are green.

I found only the following non-blocking follow-ups:

P2: State Version parsing does not reject trailing content

State Version: 8 garbage is accepted as v8 because the parser captures only the first non-whitespace token and does not require the rest of the line to be empty:

• core/tools/aidlc-orchestrate.ts:587

I confirmed the parser captures 8. Please anchor the field value to the end of the line and add a malformed trailing-content regression.

P2: Doctor does not fully match runtime version classification

Runtime correctly distinguishes malformed and future numeric versions. Doctor still routes both through its generic non-current branch:

• core/tools/aidlc-utility.ts:2058-2069

A malformed value receives stale-version wording, and a future version receives archive/reinitialize guidance instead of upgrade guidance. Please share the parser/classification logic or add equivalent doctor branches and tests.

P3: Units Generation stage prose still says three outputs

The authored stage still says:

generate 3 artifacts

at:

• core/aidlc-common/stages/inception/units-generation.md:95-97

The stage produces four artifacts, including traceability.json. The reference documentation is corrected; this remaining authored count should also be updated.

These are edge-case and documentation follow-ups, not merge blockers. The requested fixes are substantially complete and the branch is healthy.

Approving.

[SiddhJog]

Thanks @leandrodamascena — all three follow-ups addressed on d8786a67:

1. State Version parsing rejects trailing content

The shared parser now anchors the value line: /^- \*\*State Version\*\*:[ \t]*(\S+)[ \t]*$/m (aidlc-lib.ts). State Version: 8 garbage no longer captures 8 — the trailing text breaks the tail anchor and routes the state through the unparseable branch. Same for 7 archived (unparseable, not past-version). New t282 regressions assert the exact unparseable branch for both next and report, and negatively assert predates and is newer never appear for these inputs.

2. Doctor matches runtime classification (via a shared classifier)

Extracted classifyStateVersion() into core/tools/aidlc-lib.ts as the single source of truth (returns ok | unparseable | past | future). Both aidlc-orchestrate.ts (runtime) and aidlc-utility.ts (doctor) now call it, so they can't drift. Doctor emits per-branch failing rows:

• Malformed → state version readable fail row (missing, empty, or unparseable)
• Past → state version current fail row (archive-and-reinit, mv aidlc aidlc.v{v}-archive)
• Future → state version compatible fail row (upgrade guidance, no archive template)
• Current → passing State Version: 8 row

New t282 doctor cases pin each branch: not-a-number → readable, 9 → compatible + Upgrade the framework + explicit negation of aidlc.v9-archive, 8 garbage → readable.

3. Units Generation authored prose says "4 artifacts"

core/aidlc-common/stages/inception/units-generation.md:97 now reads generate 4 artifacts ... (the three Unit artifacts below plus traceability.json, whose contents are specified in Step 7). Coherent with the frontmatter outputs: line already listing all four. Grep for generate 3 artifacts returns zero matches anywhere (including dist).

Verification

• bun scripts/package.ts --check clean; coverage registry --check clean
• t282: 17 pass / 0 fail (adds trailing-content + future-branch cases in both runtime and doctor blocks)
• Full unit tier via 4 parallel runs: 202/203 pass; the 1 is t248-codekb-scope-diff, a known git-fingerprint environmental failure on clean v2
• Minimal-state spot-checks (t230, t229, t165, t224): 133 pass / 0 fail — the hardened guard doesn't break existing fixtures
• Classifier propagation verified in all 7 harness dist trees (lib + orchestrate + utility)
• An independent no-context review confirms each fix and that no new inconsistency was introduced
• 0 behind / 1 ahead of v2

[apackeer]

Independent second review, round 2, of d8786a67 against origin/v2 (74a51a1). I reviewed the previous head c1378b9 and re-verified every follow-up on this head line by line.

Round-1 blockers and P2s: all resolved.

• Release history restored: ## [2.6.1] is preserved and the follow-up ships as ## [2.6.2], with user-facing bullets covering both the BR format canonicalization and the hardened runtime guard. Version constant and README badge agree (t68 and the CI changelog guard are green).
• Zero-byte state fail-open closed: both call sites now check !== null rather than truthiness, with next and report regressions using an actual zero-byte file.
• State Version parsing: the shared classifyStateVersion() in aidlc-lib.ts is a better shape than the point fixes requested. The anchored [ \t]*(\S+)[ \t]*$ parse (no newline crossing, no trailing content) plus ^\d+$ validation yields distinct ok/unparseable/past/future verdicts, and both runtime and doctor consume the same classifier, so parity is structural rather than copied. The future-version message correctly says "newer than the current" with upgrade guidance instead of "predates". I also probed the CRLF edge: it is safe, since JS multiline $ matches before \r.
• t282 now pins exact branches (including not.toMatch(/State Version - predates/) for the empty-value case, and unparseable for 8 garbage / 7 archived), closing the branch-masking gap from round 1.
• org.md stable-ID example is now BR1.1; both artifact counts (the reference doc and the authored units-generation.md) are corrected to four.

Non-blocking notes:

1. The PR description is stale: it still describes the abandoned 2.6.0 renumbering and says the Stage 2.8 section was added (that section pre-existed on base). Please refresh it before merge so a squash-merge does not enshrine the wrong description.
2. function:classifyStateVersion is registered UNCOVERED in tests/.coverage-registry.json even though t282 pins its behavior end to end; a covers-line addition plus registry regen would close that. Fine as a follow-up.
3. Slot awareness for maintainers: open #754 also claims 2.6.2 (and #749 claims 2.6.3); second-to-merge re-bumps per the conflict-trap policy in AGENTS.md.

Approving: CI is green at exactly this head (changelog completeness, parity + typecheck + lint, smoke + unit), and the dist trees verify as regenerated, not hand-edited.

[SiddhJog]

Coverage fix landed on 19f074cf:

• Added function:classifyStateVersion to the covers: line in tests/unit/t282-state-version-doctor.test.ts and regenerated the registry. The classifier's entry in tests/.coverage-registry.json now shows status: covered (coveredBy: [{"file": "tests/unit/t282-state-version-doctor.test.ts", "mechanism": "cli"}]). bun tests/gen-coverage-registry.ts --check passes.

Version-slot: leaving this at 2.6.2. Per the conflict-trap policy in AGENTS.md, second-to-merge re-bumps — no point pre-bumping while both #754 (2.6.2) and #749 (2.6.3) are still open. If #754 lands first I'll rebase and take 2.6.3; if #749 lands first this stays at 2.6.2.

PR description updated too.