Resolve seven open decisions from the deferred-issue audit

[dean0x]

Summary

A 2026-08-26 audit verified 57 "deferred past v0.4.0" issues on roadmap tracker #69 against main. Seven items needed an owner ruling rather than engineering. All seven now have an approved disposition: four were pure tracker changes (already applied — see below), three required code or documentation work, which is what this PR contains.

Nothing here is on the v0.4.0 tag path.

Commits

#	Commit	Content
1	feat(cli): warn on duplicate --set / --set-string keys	#200 — code, tests, docs, CHANGELOG
2	docs(spec): define the project root and disambiguate mds.json discovery	#201 — spec.md §5 / §4.6 / §7.8
3	docs(readme): document the .mdsroot project-root marker	#201 — README.md, SECURITY.md, example READMEs
4	docs(sourcemap): add the S-tag provenance legend	#188 CX-6
5	docs(resolver): re-tag @extends attribution comments to #114	#188 CX-6
6	docs(spec): source maps shipped; document the build source-map flags	spec staleness
7	docs(spec): fix duplicate section 9 numbering	spec staleness — droppable
8	docs(sourcemap,resolver): scope the S9 verification claim and re-anchor the #114 reference	alignment-audit fixes
9	docs(spec): retitle section 11 to "Out of Scope"	spec staleness — resolves the editorial flag below
10	fix(sourcemap): guard body_clean_len subtraction with saturating_sub	#219 sub-item #34
11	docs(sourcemap): correct clamp_trailing_trim doc comment for the saturating bound	#219 sub-item #34 — end-state cleanup

Commit 7 is deliberately isolated and can be dropped without reworking commits 1-6.

#200 — warn on duplicate --set / --set-string keys

Repeating a key within one flag group silently kept the last value. It now warns; last-value-wins behaviour is unchanged. Using the same key in both flags remains a hard error, and that check still runs first.

Stable user-facing contract:

warning: variable 'x' is set more than once by --set; the last value wins
warning: variable 'x' is set more than once by --set-string; the last value wins

build_runtime_vars returns a RuntimeVars struct carrying the duplicated keys; a named emit_duplicate_var_warnings owns the quiet check and wraps each key as safe_inline(key) syntactically at the interpolation site (AD-224-3 / AD-224-5), which is why no ALLOWED_UNTRACED_HELPER_ARGS entry was needed — print_discipline.rs is unchanged.

Returning pre-formatted message strings was rejected: the print-discipline guard cannot follow a value across a function boundary, and a pre-existing ("build.rs", "w", …) allowlist entry would have auto-exempted the new loop, silently inheriting a justification that would then be false.

Call sites: 5 emit, 4 discard. Emitting sites run once per process; rebuild paths never call the emitter, so watch mode produces no repeated noise. dir_watch_startup calls build_runtime_vars twice — the second call discards, or directory-watch startup would double-print.

Negative controls

"Warns exactly once" passes vacuously if the warning never fires, so each perturbation was run, observed, and reverted:

Perturbation	Predicted	Observed
emit at watch.rs:935	I8 ≥ 3	7 — every file rebuild re-emits
emit at watch.rs:2185	I9 = 2 with no edits	2 — double-print trap confirmed
emit at watch.rs:1914	I9 grows per batch	4 after one rebuild

Tests: U1–U5 unit, I1–I9 integration. I7 covers WIRE-escaping with a hostile key, asserting non-vacuity before absence (PF-013) and using braced \u{1b} / \u{202e} escapes (PF-018).

#201 — document .mdsroot

Previously undocumented, so users hitting import-containment errors had no way to discover the fix.

There is no precedence between .git and .mdsroot — the nearest ancestor holding either marker wins. The docs state this positively and name the resulting footgun: adding .mdsroot below an existing .git narrows the containment envelope. A mechanical grep -niE 'override|priorit|takes precedence|wins over' confirms none of those words appear in the new prose.

Documented: both starting points (the compiled file's directory, or the base directory a string compile supplies), depth 256, silent fallback, marker-not-config (contents never read), resolved once per compilation, and the two governed behaviours — import containment and SMv3 sources[] relativization. mds.json discovery is an independent walk sharing only the depth constant.

The open UX question — whether find_project_root should warn or error on a missing marker — is deliberately not settled here.

#188 CX-6 — S-tag provenance legend

The S-prefixed tags in mds-core had no legend in tracked source, and S8 was actively wrong. Adds a //! legend covering S3, S6, S7, S8, plus three disambiguations:

• S5 is not Stage 5. Proven from tracked sources only: source_map_vfs.rs names cases S5/stage-2 and S5/stage-4, pairing one S-tag with two Stage numbers. The legend states only this negative — S5's positive meaning exists solely in an untracked note the legend declares non-authoritative.
• S9 is struck. Zero occurrences in src/ at any commit; the resource-bound work it would have named shipped untagged and is documented at each item.
• Scope. S-prefixed source-map tags only. Names B1 because it modifies S7 — it dropped the source_map_mode gate, so Origin is now populated unconditionally (verified at evaluator.rs:653).

Three S8 comments in resolver.rs re-tagged to #114, narrowed on 2026-08-26 to exactly this remaining work, plus a fourth previously-untraceable site.

Spec staleness

• Deleted - Source maps from the exclusions list in spec.md §11 — the section was titled "What's NOT in v0.2" at the time of that commit and is titled "Out of Scope" today, retitled later in this same PR by 34af1ca. Source maps shipped in v0.4, and §7.5 already spends ~30 lines on source-map path semantics.

• Added --source-map, --no-source-map, --inline, --embed-sources to §7.2, with conflicts/requires traced to the clap attributes, plus build.source_map / build.embed_sources to §7.8 (required companion — the --no-source-map row references the config field).

• Fixed the duplicate ## 9 heading. Anchor-safety re-proven before renumbering: no spec.md# link exists anywhere in-repo, and no §9–§12 cross-reference exists in tracked source. All eight surviving § references still resolve.

• Retitled the renumbered heading to the version-agnostic ## 11. Out of Scope (34af1ca). Renumbering had left ## 11. What's NOT in v0.2 — a stale version number in a v0.4 spec. The owner chose a version-agnostic title over a mechanical bump to "What's NOT in v0.4" because the section lists permanent language-design exclusions, not v0.2-era deferrals; a version-pinned heading would just go stale again every release.

A repo-wide sweep before the retitle found no TOC entry, cross-reference, or markdown anchor targeting the old heading, and confirmed no in-repo link targets spec.md#… at all. The other v0.2 mention in spec.md — the v0.2.0 - Language enrichment release entry under ## 13. Status — was deliberately left untouched: that is a legitimate version-history record, not a stale title.

#219 sub-item #34 — saturating_sub guard in sourcemap.rs

2a5d252 changes let body_clean_len = final_body.len() - fm_prefix_len; to saturating_sub inside pub(crate) fn finalize (crates/mds-core/src/sourcemap.rs:823). The owner confirmed this is the site the original reviewer meant — the symbol the review text named (finalize_sub) has zero occurrences in the entire git history, so the location was reconstructed and then confirmed rather than recovered.

No behavior change. body_clean_len has exactly two uses in finalize: clamp_trailing_trim(points, body_clean_len), which drops every segment when the bound is 0, and an immediately following if body_clean_len == 0 early return producing an empty SourceMap. A saturated 0 therefore yields the empty map that is already the correct result when fm_prefix_len >= final_body.len(). No regression test was added: the underflow is unreachable by design, and the acceptance criteria required only saturating_sub plus a clippy-clean build.

The issue's stale sourcemap.rs:744 anchor was re-anchored to :823 in the same pass — the S-tag legend commit in this PR shifted the file, and :744 is now the closing brace of the unrelated pub(crate) fn source_index.

Doc comment corrected (4af7ef4). The doc block on clamp_trailing_trim still described the pre-2a5d252 arithmetic:

/// `body_clean_len = final_body.len() - fm_prefix_len` is computed by the caller

It now names .saturating_sub(fm_prefix_len). No behavioral clause was added — the surrounding doc block is terse, and a caveat there would not have matched its register. Correcting it is part of leaving the end state rather than the transition: a comment describing arithmetic the caller no longer performs is exactly the residue a fix tends to leave behind.

#219 stays open for sub-item #28 (unbounded loop form in formatter.rs). This PR does not close it.

Verification

Measured at 4af7ef4cf146fee082e0f47c272afc28ff1e4ca0 — the branch head when this table was stamped — with a clean working tree (git status --porcelain empty). The results below are a claim about that commit only. Any commit landing on this branch afterwards invalidates them until the suite is re-run and this table re-stamped; read an unmatched head SHA as "unverified", not as "passing".

Gate	Result
cargo fmt --all --check	PASS — 0 formatting issues
cargo clippy --workspace --all-targets -- -D warnings	PASS — 0 warnings, 0 errors
cargo nextest run --workspace	PASS — 2122 passed, 0 skipped (10.66s)
cargo test --doc	PASS — 51 passed (exact baseline; run separately because nextest skips doctests)
node scripts/verify-no-control-bytes.mjs	PASS — 531 files / 5,712,107 bytes scanned, clean
npm run test:gates	PASS — 41 suites, 150 tests, 0 failed

The doctest count is load-bearing: an unadorned ``` fence inside a //! comment compiles as a doctest, so the legend commit had to leave the count identical, not merely passing.

An alignment audit checked all 19 negative constraints and 10 positive requirements by reading diffs rather than commit messages. It found two real defects, fixed in commit 8:

1. The S9 zero-occurrence claim was falsified by the very commit that wrote it — rerunning the stated verification returned hits from the legend text itself. Now scoped and pinned to 6d41777.
2. (#114) was attached to a clause describing what the source-map branch already does correctly, making shipped behaviour read as deferred. Moved onto the map-off path's actual limitation.

Related Issues

Closes #200
Closes #201
Closes #188

Tracker dispositions applied separately (no code): #197 closed as not planned; #198 reframed as a feature decision and kept open; #219 sub-item #53 dropped; #214 AC1 amended to FileNotFoundError and marked satisfied. Follow-ups filed as #326, #327, #328, #329.