Files
msd-core/tests
Rezolv 16e59d0db5 fix(#2691): repair seven dangling references in the ADR corpus and contributor docs (#2692)
* fix(#2691): repair five dangling references in the ADR corpus and contributor docs

Found by the 2026-07-24 ADR corpus audit; each mechanism re-reproduced live
against next @ 3eb1cede before filing.

1. docs/adr/1239-gsd-embeddable-orchestration-engine.md linked the
   host-integration capability matrix as `reference/...` from inside
   docs/adr/, which resolves to the nonexistent docs/adr/reference/.
   Three occurrences (the #2584 amendment added two after the audit).
   All now `../reference/...`.

2. src/plan-drift-guard.cts cited docs/adr/0022-source-grounding-drift-guard.md,
   a path that has never existed (git log --all --diff-filter=A returns
   nothing). Corrected to docs/adr/22-plan-drift-guard.md. Comments survive
   tsc and ADR-457 builds at publish, so the bad citation shipped to users --
   verified by grepping the compiled gsd-core/bin/lib/plan-drift-guard.cjs.

3. CONTRIBUTING.md and docs/contributor-standards.md illustrated the ADR
   naming convention with issue #3485 -- a pre-rename number from the
   predecessor repo (get-shit-done-redux) that does not resolve in
   open-gsd/gsd-core. It is dangling, not invented: ADR filenames 3524 and
   3660 show pre-rename numbering reached the 3000s. The worked example now
   uses #2264, which resolves; the one genuinely historical mention is
   annotated rather than rewritten.

4. docs/adr/857-capability-system.md's H1 carried a stale [Proposed] bracket
   contradicting its "Accepted -- ratified 2026-07-17" Status field.
   gen-adr-index.cjs:213 strips the bracket rather than comparing it, so the
   contradiction was invisible to the gate; it is also the only in-repo
   consumer, so removal leaves the rendered index byte-identical.

5. gen-adr-index.cjs's back-link comment still described ADR-857 as Proposed
   and its claim over ADR-0011/ADR-58 as a supersession. Both were restated
   at ratification (the claim became Subsumes; the reciprocals were added).

Regression coverage folds into tests/adr-index-gate.test.cjs rather than a
new bug-* file (lint-regression-test-names): four cases covering link
resolution, H1-bracket-vs-Status agreement, the plan-drift-guard citation,
and the naming worked example. All four fail at the pre-fix tree.

No behavior change. lint:ci exit 0; adr-index-gate 35/35; index regenerates
unchanged (67 ADRs).

* chore(#2691): add the required pr: field to the changeset fragment

docs-lint rejected the fragment with fail_malformed_fragment / missing_pr: the
frontmatter needs both `type:` and `pr:`. The fragment was hand-authored before
the PR existed, so it carried only `type:`.

Note for future work: neither lint:docs nor lint:changeset is part of the
lint:ci chain, so a green lint:ci does not cover these two CI checks. Both were
run directly before this push:
  ok docs-lint: ok_no_triggering_fragments
  ok changeset-lint: ok_fragment_present

* fix(#2691): drop the false branch clause and repair two more matrix links

Review round 2 on #2692, both blocking findings.

F1: the worked example at CONTRIBUTING.md:101 asserted
'on branch docs/2264-golden-parity-redesign'. That branch never existed --
the ADR file carries the epic number (#2264) while the branch and commit
carry the Phase-0 sub-issue number (#2265, PR #2270, branch
docs/2265-golden-parity-adr). #2264 is therefore the one ADR in the corpus
where filename and branch numbers deliberately disagree, making it the worst
available illustration of 'the issue number becomes your prefix and your
branch'. The branch clause is dropped; the surviving claim is verified
(#2264 is open-and-approved with approved-enhancement, and the file is
2264-golden-parity-redesign.md).

F3: docs/how-to/install-on-your-runtime.md:460 and :476 linked the
host-integration capability matrix as a bare filename from inside
docs/how-to/, which resolves to the nonexistent
docs/how-to/host-integration-capability-matrix.md. Same defect class as
repair #1 in this PR. Both now use ../reference/..., matching the form
already used by the sibling add-or-update-a-host-integration.md:167.

* fix(#2691): take the review minors -- anchors, bracket, ADR path, token order

Review round 2 on #2692, non-blocking findings.

F4: ADR-1239:198,206 read '[capability matrix §codex](...matrix.md)' -- the
link text promised a section, the target carried no fragment. '## codex'
exists at docs/reference/host-integration-capability-matrix.md:85, and the
repo already uses that form (#zcode, #pi in the how-to).

F5: docs/adr/857-capability-system.md:1 had its stale [Proposed] bracket
dropped rather than corrected, making 857 the only ratified ADR with no H1
bracket while four other Accepted ADRs carry one. Restored as [Accepted],
which satisfies the H1-vs-Status invariant and preserves consistency. No
recorded rule mandates the bracket, so this is style, not contract.

F7: docs/CONFIGURATION.md:808 cited adr/1244-runtime-capability-registry-
overlay.md; the actual file is adr/1244-capability-ecosystem.md. Same defect
class as repair #2, one directory over.

F8: test 33 resolved the Status token with STATUS_TOKENS.find(), which
matches by array order rather than by position in the line. Since
STATUS_TOKENS[0] === 'Accepted', a future '- **Status:** Superseded by ADR-X
(was Accepted ...)' paired with an H1 [Superseded] would have reported a
false mismatch. Now resolved by earliest index in the line. No ADR has that
shape today, so this is latent; ADR-857's two-token Status line resolves to
'Accepted' under both the old and new rule.

Changeset updated: five repairs -> seven, adding the two how-to matrix links
and the CONFIGURATION.md ADR path, plus the (#2691) issue backlink that 46
of the other 47 fragments carry.

Not addressed here: F2 (widening the guard to resolve anchors and walk docs/
recursively) is filed separately as #2704, approved-enhancement.

---------

Co-authored-by: CI Rebase Check <ci@gsd-redux>
2026-07-28 18:02:11 -04:00
..