fix(update-skill): write no line read from a drifted tree, and write the entry for a cited new export

[armelhbobdad]

Follow-up to #530: two update-skill gap-driven (--from-test-report) defects deferred from the reviews of #532.

---

1. Never write a line read from a drifted tree

The bug. Under --allow-workspace-drift with HEAD off the pinned commit, a spot-check could still record moved. write §3 then wrote a source_line read at HEAD while source_commit stayed pinned. Targeted re-extraction (§0a) also wrote full entries from HEAD.

What changes.

• The status is kept. Step 3 §0.a binds the drift helper's status ({workspace_drift_status}, plus {head_short_sha} and {pinned_short_sha}). Only overridden changes anything. The flag with HEAD at the pinned commit (ok) moves lines as before.
• Under overridden, spot-checks change no line:
  • moved becomes unknown with unknown_reason: drift-override and a WARN that names HEAD and the pinned commit.
  • An R5 verified read at HEAD also gets a WARN, carrying the definition lines from the test report, so the gap doesn't close silently.
  • The reachability check is skipped rather than read at HEAD.
• Gaps that need a line halt in step 3, before merge. This covers rule R3, a Critical/High gap routed to §0a by its remediation paths, and a Critical/High cited export not in the map. The status is halted-for-workspace-drift, and the message names the gaps, the full pinned commit, source_ref and the checkout command.
• A failed drift helper halts with blocked.
• Knock-on changes:
  • write §6a keys its line fixes on the same status, and its WARNs carry the drift note.
  • merge Priority 2 moves citations only for a moved outcome.
  • The report's Mode row shows the override, and warnings[] gets workspace_drift_overridden (the name the envelope schema already documents).
  • init.md, SKILL.md, docs/verifying-a-skill.md and docs/workflows.md describe the override this way.

2. Write the entry for a cited export not in the map

The bug. A cited export the map did not hold, whose spot-check pinned a line, had no write §3 branch that added its entry. The export was documented without provenance, and §6a reported it missing.

What changes.

• write §3 adds one entry at the pinned line, once per export and file, after the reachability check.
• The entry is labeled as read by eye: source-read, T1-low, null node type, signature_source T1-low. That is the pairing the stats helper checks.
• Merge cites it [SRC:] at that line.
• The name lookup now narrows entries that share a name by the citation's normalized file and line.

Verification

• Tests. npm test exits 0, with the real exit code: 4774 passed, 1 skipped. test/test-skf-update-source-tree-prose.py pins every rule above in eight new tests. One of them runs skf-render-metadata-stats.py on the new entry's labels read from write.md.
• Reviews. Two three-layer passes:
  • Pass 1 found that §0a could still write lines read at HEAD. The maintainer chose strict (nothing writes a line under the override; gaps that need one halt), and the change was re-derived.
  • Pass 2's fixes are applied.
  • Deferred: a pre-existing case where an uncited Critical/High gap with no remediation paths only halts after merge.

Not verified: no live claude -p gap-driven run with the new prose.

🤖 Generated with Claude Code