Skip to content

Accept cross-directory instruction adapter symlinks in workspace topology #53

Description

@phodal

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions