Skip to content

Relink gate: refuse drift link on stale anchors unless explicitly reviewed#19

Merged
laulauland merged 7 commits intomainfrom
lau/relink-gate
Apr 14, 2026
Merged

Relink gate: refuse drift link on stale anchors unless explicitly reviewed#19
laulauland merged 7 commits intomainfrom
lau/relink-gate

Conversation

@laulauland
Copy link
Copy Markdown
Member

@laulauland laulauland commented Apr 10, 2026

Summary

drift link now refuses to restamp stale anchors. When a target's signature has changed, the command prints both sides — the doc section (spec) and the current code — then exits 1. The only way through is --doc-is-still-accurate, an explicit assertion that the doc was reviewed and doesn't need changes.

This prevents agents and humans from blindly relinking without reading what changed.

What happens on stale relink

For symbol anchors, drift prints the doc section and the current symbol body via tree-sitter. For heading anchors, it prints both heading sections. Output is capped at 10 lines per side.

── doc ── doc.md ##Authentication ──
The login function validates a username/password pair...

── code ── auth.ts#login (9 lines) ──
function login(username: string, password: string): string {
  ...
}
  STALE  auth.ts#login

refused: target changed since last link.
Review the doc, then relink with --doc-is-still-accurate.

Changes

  • src/commands/link.zigisDocGateBlocked checks staleness, printStaleContext shows both sides, printBlanketRefusal consolidates output for multi-anchor docs
  • src/main.zig--doc-is-still-accurate flag for the link command
  • src/markdown.zigextractHeadingSectionContent for heading target display
  • .claude/skills/drift/SKILL.md, docs/CLI.md — updated documentation

Test plan

  • zig build test passes
  • drift link <doc> on stale anchor → prints context, exits 1
  • drift link <doc> --doc-is-still-accurate → succeeds
  • Multi-anchor doc → doc section printed once, stale bindings listed

The doc: hash was a whole-file hash of the markdown doc. It powered the
relink gate by detecting whether the doc had changed since the last link.
Problem: any unrelated doc change (typo, different section) opened the
gate, giving false passes on bindings that weren't actually reviewed.

Simplify the gate to: stale binding → always require --doc-is-still-accurate.
No doc hash comparison needed. This is stricter but correct — the flag is
an explicit human assertion that the doc was reviewed.

- Remove computeDocHash and doc_hex plumbing from link.zig
- Simplify isDocGateBlocked to only check staleness
- Add Binding.removeField to strip leftover doc: from old lockfiles
- Strip doc: from drift.lock
- Update tests and docs
@laulauland laulauland changed the title Relink gate: refuse drift link when doc unchanged Relink gate: require explicit review for stale anchors Apr 13, 2026
@laulauland laulauland changed the title Relink gate: require explicit review for stale anchors Relink gate: refuse drift link on stale anchors unless explicitly reviewed Apr 14, 2026
@laulauland laulauland marked this pull request as ready for review April 14, 2026 08:50
@laulauland laulauland merged commit b96d58f into main Apr 14, 2026
5 checks passed
@laulauland laulauland deleted the lau/relink-gate branch April 14, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant