#1107 Render rulebook links and path tokens per harness

[williamthorsen]

What

Rulebooks can now address a file by linking to it: A Markdown link to a skill or script, or a home-directory placeholder anywhere in the body, reaches each harness with that harness's own absolute path filled in. A link target that names a place no harness creates is now rejected with an error naming the rulebook and the target. Links opening with a home-directory placeholder now resolve in skills and subagents as well.

Why

Guidance that has to name a harness-specific path had nowhere to live. The destination-tier doctrine holds that a harness-neutral file cannot carry a harness-scoped path and directs such content into an ambient rulebook instead, but a rulebook could not carry a path either, so the doctrine pointed at a destination that did not work. Content that should have moved stayed where it was, citing files in prose that a reader has no way to follow.

Relative paths are not a workaround: an agent cannot reliably resolve one, because it does not know the directory it was installed into. An absolute path produced by the delivery pipeline is the form that works, and it is what skills and subagents already receive.

Details

🎉 Features

• Rulebook bodies pass through a per-harness render before delivery, at both delivery points: the consult-<slug> skill write loop and ambient region injection. A target under skills/ or scripts/ becomes the target harness's absolute path with any anchor fragment preserved, and {harness_home_dir} and {harness_id} expand per harness. A rulebook delivered to two harnesses yields the correct path in each.
• Targets are validated before any rewriting. A target rooted outside the two linkable trees, or one escaping the content root, fails the run with every offending target reported together, naming the rulebook, the target as authored, and the reason it was rejected. Absolute, ~-prefixed, http(s), and anchor-only targets pass through untouched.
• Validation runs in the same pre-write pass as declared-skill rendering, so a bad link fails a dry run with nothing written and nothing retired.
• A link target that opens with a template token is now left for template expansion rather than resolved as a relative path first, which fixes the mangled output such a target produced in skills and subagents.
• The codeassembly-content-specification rulebook gains a "Links in rulebook bodies" section: the authoring convention, the two linkable trees and why each other tree is excluded, what a rejected target reports, and the one limitation an author documenting the convention needs to know.

♻️ Refactoring

• ResolvedRulebook and resolveRulebook move from the command layer into src/lib/rulebook-deploy.ts, matching how skill and subagent resolution already pair with their transform module.
• Harness detection resolves once per domain and is threaded into ambient host resolution, prompts.yml reconciliation, and the new validation pass, replacing five separate detection calls that could each have seen a different filesystem.
• The skill orphan scan carries the harness id of the target it was computed for, so the delivery loop reads directories, orphans, and render context from one list.
• The ambient-host writability guard now tests the declaration rather than the rendered body. That guard exists to protect a half-written region from being appended to, and rendering it to answer "is anything declared?" would have coupled it to link validity once rendering could fail.
• The Markdown link grammar is exported from path-rewriter.ts and shared, so the grammar and the passthrough predicate that together define what gets rewritten can no longer drift apart between the rewriter and the suites that inspect links.

🧪 Tests

• New rulebook-transform.test.ts covers link rewriting under both linkable roots, anchor preservation, the four passthrough forms, template expansion, per-harness output, and five rejection cases including batch reporting and the anchoring depth of the rewrite.
• sync.test.ts gains seven cases, among them a two-harness run asserting the correct absolute path in all four outputs (both SKILL.md files and both ambient hosts) and a dry run asserting a bad target writes nothing.
• content-link-resolution.test.ts now treats guidance/rulebooks/ as a host root, so rulebook links are checked for dead files and unresolvable anchors alongside skills and subagents.
• A new suite renders every shipped rulebook the way sync does, so a link target rooted outside a deployable tree fails the build rather than surfacing later as a broken sync. File existence alone cannot catch this: a link to an existing subagent file satisfies every other check and still fails every run.
• Harness-specific test fixtures that shared bare names were renamed for clarity.

Closes #1107

[github-actions]

Dependency audit

Production dependency audit passed.