fix(framework): a context reference in a form its tool cannot resolve - #751

🎯 What & why

AGENTS.md carried ten @aidd_docs/… lines. Codex, Cursor and OpenCode do not resolve that
import — it is inert text that loads nothing and reports nothing. This restores the markdown
links and adds the check that notices when a context file drifts back.

🛠️ How it works

Two ways it drifts, both observed today, and one code path covers neither by naming them.
A machine still holding the released [email protected] hook rewrites the block to @ on
every session start, because that older copy declares at for AGENTS.md — the fix landed
in #732 under a chore, which release-please does not version-bump, so no machine has it.
And a stale edit sitting in the index rides into an unrelated commit; that is literally how
the wrong form reached next, inside #749.

scripts/check-context-reference-form.js reads
TARGET_FILES from update_memory.js itself rather than restating the table, so the rule and
the writer cannot disagree. A table it cannot parse throws: a check that goes green because
it compared against nothing is worse than no check.

Only lines that are a reference are judged — the block also carries prose, an html comment and
the read-on-demand list. An unpaired marker yields nothing here: update_memory.js reports
that itself, and two voices for one fault help nobody.

Wired into pre-commit beside context-imports, and answering for the whole repository rather
than the staged files: the hook rewrites every target at once, so a partial view could call one
file clean while its sibling drifted in the same session.

🧪 How to verify

node --test 'scripts/__tests__/check-context-reference-form.test.js'   # 11
node scripts/check-context-reference-form.js                           # exit 0
node --test 'scripts/__tests__/*.test.js'                              # 344

On next before this branch, that second command prints the failure it exists for:

❌ 10 reference(s) in a form the reading tool cannot resolve
  AGENTS.md:43  @aidd_docs/memory/architecture.md
    declares "link", found "at"

Tests first, then the code, then the mutation for each guard — the form comparison, the
unreadable table, the stop-at-first, and what counts as a reference. All four die, each under
the test named for it, and M2 and M3 kill exactly one test each.

⚠️ Heads-up

The root cause is still open. The corrected hook cannot reach anyone: aidd-context is
pinned at 2.7.0, the only commit since that release touched it is a chore, and release-please
bumps on feat/fix alone. Until a legitimate change lands in plugins/aidd-context/, every
machine keeps the old hook and this check is what stops the drift from being committed. I did
not manufacture a version bump to work around it.

🔗 Linked issue

Refs #619

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp