Project-deployed guidance emits home-absolute links pointing outside the repository

[williamthorsen]

Problem

sync deploys declared skills, subagents, and rulebook-delivered skills into <projectRoot>/{homeDir}/…, but link rewriting anchors every target under ~/{pathPrefix}/: resolveSkillTarget sets SkillDeployContext.pathPrefix to the harness skills dir, subagent-deploy passes the harness home, and rewriteMarkdownPaths emits ~/{pathPrefix}/{resolved} unconditionally. A relative Markdown link in a project-deployed artifact therefore points into the user's home harness directory, which project-domain deployment never populates.

A sibling-skill link resolves only when that skill also happens to be deployed globally. Otherwise it names a path nothing creates, and it fails silently: a dead reference gets improvised past rather than raised.

Context

Asserted as current behavior in packages/agents/src/commands/__tests__/sync.test.ts.

The home-directory anchor is not itself the defect. #1088 establishes that sync's project-domain output is machine-local build product, so a home-absolute path is a legitimate form there -- and it is the correct address for a tree install populates and sync does not, such as the library's skills/_data/. The defect is narrower: the anchor is a constant, so it names the home tree even for targets the run just wrote into the project.

Delivering the library's support entries into the project domain is #1141; a declared source's are #1131. Both keep the harness-home branch of this ticket's rule until they land.

Proposed solution

Anchor each target by where the run actually deploys it. A target naming a skill directory this run writes into the domain's skills dir resolves against the domain base; every other target keeps the harness home. That set is the declared skills targeting the harness plus the rulebook-delivered skill names -- the two namespaces assertNoCrossNamespaceCollisions already keeps disjoint.

A link to a skill the run does not deploy stays home-anchored rather than being re-pointed into the project, where it could never resolve.

Skills, subagents, and rulebook bodies alike: all three deploy project-locally and all three thread a constant prefix today.

Two rejected alternatives, both keyed on the owning source rather than on the run's output:

• Not skills/_sources/<source>/ -- that namespace addresses support entries no run yet delivers, and belongs with A declared source's skill support files are neither delivered nor transformed #1131's delivery pass.
• Not a per-source set of skill directory names -- a source artifact's link to library content would miss that set and be misfiled. rulebook-transform.ts states the governing premise: a target resolves against the deployed tree, which unions library content with each declared source's content.

Acceptance criteria

Must have

• A relative Markdown link in a project-deployed skill, subagent, or rulebook body resolves against the tree that deploys its target: the domain base for a skill directory the same run writes, the harness home otherwise.
• A link to a skill the run does not deploy remains home-anchored.
• Home-domain deployment emits the paths it emits today.
• New/modified behavior in this change is covered by tests.

[williamthorsen]

Folded into #1131, which now carries the unified ticket.

Both are one cause: the renderer anchors every rewritten Markdown link at a constant, so it names trees the run does not populate. This ticket is that defect seen from the project domain; #1131 was it seen from a tree the constant cannot name. The acceptance criteria here are absorbed there, widened to cover project-deployed subagents, which share the code path.

Closes with #1131's work.

[williamthorsen]

Retracting the fold-in note above: this ticket keeps its own scope and its own pull request, and lands ahead of #1131 rather than with it.

Two notes carried over from the work done while the two were merged. The fix extends to project-deployed subagents, which share the code path with skills and the same constant anchor, so the acceptance criteria here read as covering both. And the change to a project-deployed artifact's rendered links reaches every relative Markdown link it carries, not only those into support files.