Reference-pointer shape: repo-relative paths won't resolve against a foreign target repo

[Ljferrer]

From plan 2026-07-28-prompt-surface-simplification phase 3 (landed 53ef8a7), all three seats converged.

agents/war-auditor.md is the auditor's system prompt; its cwd is the TASK worktree of the target repo and its Bash is fail-closed to read-only git, so it cannot resolve ${CLAUDE_PLUGIN_ROOT}. The new pointers use ../skills/war/references/auditor-teach.md, which resolves only when the target repo IS this plugin repo. The evicted arms (submodule diff scope, gitlink-bump pin-validity) are precisely the ones that fire on multi-repo targets.

Not a hold — verified mitigations at the pin: the fail-closed gitlink refusal arm stays inline; each pointer keeps its load-bearing decision rule inline, so an auditor that cannot Read the reference still refuses correctly; and the card already used this citation idiom pre-diff. What is new is that a pointer is now load-bearing rather than decorative.

Decide once, at ADR 0042 D4 (trigger-pointer shape), then apply to Tasks 4.1/5.1 and back-fit Task 2.1's landed SKILL.md pointers: either anchor pointers at the plugin root (matching the node <plugin>/skills/_shared/war-memory.mjs idiom already in the worker prompt), or state in the ADR that references/ pointers are best-effort and every pointer MUST keep its decision rule inline (which this diff already does). Phases 4 and 5 evict the same way — settle this before 4.1 dispatches.

[Ljferrer]

SETTLED — Lead adjudication row O (campaign 2026-07-28-audit-doctrine-and-prompt-simplification, plan 2, at the phase-4 gate)

Adjudicated 2026-07-29 by the campaign Lead under AFK, before Task 4.1 dispatched. Threaded into Tasks 4.1 and 5.1 as args.adjudications row [O] and recorded in the run ledger. Precedence: task instruction > red-team/Lead adjudication > plan body literal > spec literal.

#	supersedes	ADJUDICATED	applies at	notes
O	this issue — references/ trigger-pointer path shape (ADR 0042 D4) for agent cards dispatched against a foreign target repo	(1) A pointer is best-effort enrichment, never the sole carrier of a blocking or anti-false-positive rule — that rule stays inline. (2) Shape is D4's existing skeleton read references/<file>, resolved owner-relative: a surface that OWNS the references/ dir (skills/war/SKILL.md) writes references/<file> bare; an agent card in agents/ names the owning skill — skills/war/references/<file> — and MUST NOT use a ../-prefixed path. (3) No plugin-root anchor is introduced.	Tasks 4.1, 5.1 — every new card and dispatched-literal pointer	no new shape is minted; (1) ratifies what phase 3 landed

Why not the plugin-root option

The issue offered plugin-root anchoring as the alternative. Verified, it does not work for any seat:

• ${CLAUDE_PLUGIN_ROOT} is not in the Lead's environment (env | grep -i plugin → unset outside a plugin hook/script invocation), so neither the Lead nor build-args can resolve it to an absolute path at args-build time.
• The Read tool does not expand environment variables. A literal ${CLAUDE_PLUGIN_ROOT}/skills/war/references/x.md handed to Read 404s for every seat, not just the auditor — it would only work as a <plugin>-style placeholder the agent resolves itself (the agents/war-worker.md:54 idiom).
• The auditor specifically cannot resolve such a placeholder: its Bash is fail-closed to a read-only git verb allowlist (hooks/validate-auditor-git.sh), so it has no shell to expand or discover anything.

So no path form resolves on a foreign target repo. Anchoring would buy nothing and would touch pointer text on cards outside every remaining task's slice. Keeping the decisive rule inline is the only real mitigation — which is what phase 3 already ships, and what the recorded lesson agent-card-reference-pointer-is-repo-relative-and-wont-resolve-against-a-foreign-target-repo independently concluded.

No three-way back-fit

The issue anticipated back-fitting Task 2.1. Measured at the landed tip 75eeeba, that is not needed:

• Task 2.1 (skills/war/SKILL.md) already conforms — every landed pointer is the bare owner-relative form, e.g. [references/setup.md](references/setup.md), [references/docker-gate.md](references/docker-gate.md). references/ is SKILL.md's own sibling directory. No change.
• Task 3.1 (agents/war-auditor.md) is the sole deviation — three [auditor-teach.md](../skills/war/references/auditor-teach.md) links (lines 20/33/35) plus one at line 54. They stay as landed: End state 2 pins byte-identity on the moved content, and the mitigation (decisive rule inline) holds. Normalizing the ../ prefix is cosmetic and stays open on this issue, to be closed post-plan alongside Dead relative links in evicted references/ files (byte-identity mandate blocks the fix in-plan) #1212 (dead relative links in evicted references/ files) — same files, same pass.

Net scope of the settlement: zero back-fit commits, one adjudication row constraining new pointers in Tasks 4.1 and 5.1.

Status: this issue stays open as the post-plan home for the ../-prefix normalization; the phase-4 gate is cleared.

[Ljferrer]

Phase-5 residue lands here (task 5.1, bd5faa9)

Two phase-5 findings are instances of this issue’s root, recorded here rather than as new issues since adjudication O(3) already settles the direction:

1. agents/war-worker.md:23 — the evicted §Submodule task mechanics steps (including Return WorkerResult as normal — worktree is the submodule worktree path, branch is the submodule task branch and notes records the SHA advanced to) are now sole-carried by skills/war/references/worker-servitor-edges.md. Submodule and gitlink-bump tasks are the cross-repo case, so that destination will essentially never resolve for the worker that needs it. Not held: O(1) is satisfied — every blocking rule stayed inline (the seat filed it disposition: note on exactly that basis).
2. The servitor’s dispatched skeleton cites its standing card by a repo-relative path with the same property.

This is the predicted shape, not a regression: O(3) records that no path form resolves on a foreign target repo, so inline retention is the only mitigation and the pointers are enrichment. Phase 5 kept the decisive rules inline, and workflow-template.test.mjs now pins them at the tip.

Consolidated scope for this issue when it is finally worked: normalize the ../-prefixed pointers on agents/war-auditor.md (phase 3), and re-examine whether the submodule-family evictions in worker-servitor-edges.md should be pulled back inline given they only ever fire cross-repo. Still paired with #1212.