Deliver: Gate Legibility Lints (#98, #99, #101)

[seanrreid]

Delivers the approved plan .agents/plans/gate-legibility-lints.md, bundling three
gate-legibility defects found while delivering #91.

Closes #98
Closes #99
Closes #101

Why these three ship together

Each is a deterministic check whose output misleads the reader — the same family
as #91. Two of them edit scripts/lint-plan.sh, so splitting them would have
guaranteed a conflict.

The shared cost is calibration: a check that cries wolf, or fails for a reason the
author cannot infer, trains people to wave it through — which is exactly when a real
violation slips past. Every verdict and severity in this PR is unchanged. Only
messages, false positives, and documentation move.

What changed

#98 — bare-basename anchors false-positive. plan_cited_anchors qualified any
path:NNN token ending in a known extension, so prose citing `spine.js:51-53`
yielded the bare path spine.js, existence-checked at repo root, warning "stale
premise: spine.js not found" while the file sat at harness/spine.js. New
resolve_anchor_path helper: slash-bearing tokens pass through unchanged; a bare
basename resolves via git ls-files only on a unique match — zero or ≥2 matches
emit nothing, because a guess is worse than no signal. Separately, a path already
reported by "File in scope does not exist" no longer also produces a stale-premise
warning. One fact, one finding.

#99 — renames read as scope drift. check-scope.sh builds its declared-scope set
from the Files-in-Scope File column only, so a git mv destination described in
the prose Change column was invisible and every rename reported its own target as
drift. The check still fails — the message now names the deleted counterpart and
explains the two-row convention. A new plan-time advisory in lint-plan.sh catches
the same mistake at authoring time, and both /rad-plan and /rad-adopt now document
that a rename declares both paths as rows.

Deliberately not done: parsing the prose Change column into the scope set. Guessing
at natural language inside a fail-closed gate is worse than an honest failure
(plan Non-Goal).

#101 — a script committed non-executable. scripts/test-check-scope.sh was
committed 100644 while every sibling was 100755; invoked directly it exited 126,
and CI masked it via bash "$t". Fixed as a true mode change, plus a new
committed-mode pass in lint-shell-safety.sh that reads modes from the git index
rather than the filesystem — a local chmod that was never staged is precisely the
state the bug lived in, and a filesystem stat would have seen nothing wrong.

Design note worth reviewing

The committed-mode check is a separate pass, not an extension of the existing scan
loop. That loop skips test-*.sh and globs non-recursively — and the sole offender
was a test-*.sh. Folding it in would have produced a check structurally incapable
of catching the bug it was written for. The separate git ls-files -s pass recurses
into scripts/hooks/, which makes the *.sh.sample exclusion load-bearing rather than
decorative.

This was surfaced by writing the plan's ## Program Design section against the real
tree before delivery — the #79 advisory earning its keep.

Verification

The plan set its own acceptance fixture, and it is met: running
scripts/lint-plan.sh on this plan's own doc emitted 3 false stale-premise warnings
before (spine.js, ci.yml, lint-shell-safety.sh — all three files exist) and
emits 0 after, while all 11 self-protected warnings survive unchanged, exit 0.

• Population effect: stale-premise warnings across all 32 plans drop 30 → 21,
  with zero new warnings introduced. Noise reduction, not a reshuffle.

• True positives preserved: a plan citing a genuinely absent path still warns.

• Verdicts unchanged, verified in an independent fixture repo:

  Scenario	Exit	Output
  git mv of a declared file → undeclared path	1	names both dest and src
  Both source and destination declared	0	passes
  Unrelated new file	1	plain message, no rename hint

• Index-not-filesystem proven: re-staging the original bug with
  git update-index --chmod=-x while the file remained +x on disk is caught, exit 1.

• Tests: 42 → 65 cases across four suites (check-scope 3→7, lint-shell-safety
  11→15, plan-paths 9→16, lint-plan 19→27). All 14 shell suites pass; every
  pre-existing case kept its description, asserted exit code, and pass status.

• Harness: npm test --prefix harness → 216/216.

• Gates: check-scope.sh → 10 files, all in scope. check-tests-present.sh → 4
  test files present.

• All 14 scripts/test-*.sh are now committed 100755; no content edit dropped a mode.

• lint-shell-safety-baseline.txt is byte-identical — no grandfathering needed.

Out-of-scope finding, filed not fixed

#102 — scripts/lib/plan-paths.sh claims "bash 3.2 (macOS stock) compatible" in its
header but has not parsed under bash 3.2 since the freshness lint landed, so on a stock
macOS box lint-plan.sh exits 2 with a syntax error instead of linting. Pre-existing on
main, unrelated to #98, and outside this plan's approved scope — filed rather than
folded in.

Review notes

• scripts/lint-shell-safety.sh now holds itself to its own rule: the new
  git -C "$SCRIPTS_DIR" call tripped the lint's tainted-input check, resolved with a
  shape guard (exit 2 on whitespace/metacharacters) rather than a baseline entry.
• scripts/check-scope.sh's unresolvable-diff-range path now exits 2 with a logged
  reason, where set -e previously aborted with git's raw 128 and no message. Still
  fail-closed and non-zero; pinned by a test case asserting 2.
• Two wave tasks named a second required file only in prose, not in their File: field
  — flagged at Gate 1 and corrected in the wave prompts. Both rad-plan.md and
  rad-adopt.md (AC#6) and both test-plan-paths.sh and test-lint-plan.sh (AC#5)
  landed. Ironic given check-scope.sh cannot express a rename: a plan's git mv target always reports as out-of-scope drift #99 is about paths that live only in prose.

Full execution log: .agents/logs/gate-legibility-lints-2026-08-10.md