Problem
workspace-topology now accepts a tracked instruction symlink only when the link and its target sit in the same directory (PR #51, spec docs/specs/2026-08-02-contained-structural-symlinks.md). The dominant real-world convention is cross-directory: a single canonical root agent guide plus provider adapter links that point up one or two levels.
Verified against real Git fixtures on the PR #51 head:
| Topology |
Result |
root CLAUDE.md -> AGENTS.md (same dir) |
complete |
packages/app/CLAUDE.md -> AGENTS.md (same dir) |
complete |
.github/copilot-instructions.md -> parent AGENTS.md |
partial + structure-entry-unsafe |
root CLAUDE.md -> absolute in-root AGENTS.md |
partial + structure-entry-unsafe |
Because scripts/harness-analysis/evidence-bundle/index.mjs treats any non-complete topology as fatal at normal depth, one adapter link makes the whole Evidence Bundle failed. Repositories using .claude/, .cursor/rules/, or .github/ adapter links therefore still cannot produce a normal Evidence Bundle after PR #51.
Why the current restriction may be stricter than needed
The redirect already requires: tracked provenance, a target that is itself a tracked instruction inventory entry, canonical containment in the topology root, a single relative hop (no chains), and a regular file. A .. hop does not weaken any of those guarantees — the target stays tracked and in-root.
Ownership is already attributed to the link's own route, which is where the coding agent actually reads the file, so a cross-directory link does not let one route fabricate another route's ownership.
Proposed acceptance criteria
- AC-1: A tracked instruction route whose relative single-hop target is a tracked instruction inventory entry inside the topology root resolves to
complete, regardless of how many .. segments the link uses.
- AC-2: Chained links, escaping targets, ignored/untracked targets, non-structural targets, and manifest aliases stay rejected with
structure-entry-unsafe.
- AC-3: The instruction scope is reported for the link's own route and provider, and the owner route stays derived from the link path, not the target path.
- AC-4: A normal Evidence Bundle completes for a repository whose only symlink is a cross-directory instruction adapter.
- AC-5: Decide explicitly whether an absolute link target inside the root is accepted, and document the choice.
Notes
Update the Non-goals section of docs/specs/2026-08-02-contained-structural-symlinks.md when this lands, since it currently records the cross-directory rejection as intended behavior.
Problem
workspace-topologynow accepts a tracked instruction symlink only when the link and its target sit in the same directory (PR #51, specdocs/specs/2026-08-02-contained-structural-symlinks.md). The dominant real-world convention is cross-directory: a single canonical root agent guide plus provider adapter links that point up one or two levels.Verified against real Git fixtures on the PR #51 head:
CLAUDE.md->AGENTS.md(same dir)completepackages/app/CLAUDE.md->AGENTS.md(same dir)complete.github/copilot-instructions.md-> parentAGENTS.mdpartial+structure-entry-unsafeCLAUDE.md-> absolute in-rootAGENTS.mdpartial+structure-entry-unsafeBecause
scripts/harness-analysis/evidence-bundle/index.mjstreats any non-completetopology as fatal atnormaldepth, one adapter link makes the whole Evidence Bundlefailed. Repositories using.claude/,.cursor/rules/, or.github/adapter links therefore still cannot produce a normal Evidence Bundle after PR #51.Why the current restriction may be stricter than needed
The redirect already requires: tracked provenance, a target that is itself a tracked instruction inventory entry, canonical containment in the topology root, a single relative hop (no chains), and a regular file. A
..hop does not weaken any of those guarantees — the target stays tracked and in-root.Ownership is already attributed to the link's own route, which is where the coding agent actually reads the file, so a cross-directory link does not let one route fabricate another route's ownership.
Proposed acceptance criteria
complete, regardless of how many..segments the link uses.structure-entry-unsafe.Notes
Update the
Non-goalssection ofdocs/specs/2026-08-02-contained-structural-symlinks.mdwhen this lands, since it currently records the cross-directory rejection as intended behavior.