AGENTS.md mandates a contributor-specific build volume (/Volumes/Workspace), blocking verification on other machines

[GQAdonis]

Summary

AGENTS.md requires every compiling Cargo command to set CARGO_TARGET_DIR beneath /Volumes/Workspace/crabbuild-target, and to stop rather than fall back to a local target/ when that volume is absent:

• Before any Cargo command that can compile (build, check, test, clippy, bench, doc, install, package, or a Make target that invokes one), set CARGO_TARGET_DIR beneath /Volumes/Workspace/crabbuild-target.
• […] If /Volumes/Workspace is unavailable, stop and report it rather than falling back to a local target/ directory.

/Volumes/Workspace is a macOS mount point specific to one contributor's machine. It is not a property of the project, and there is no documented way to obtain or substitute it. On any checkout without that volume, an agent or contributor following AGENTS.md correctly concludes that no build, test, lint, or qualification step may be run at all.

Introduced in dd14b3c ("docs: add AI contributor guidance"). Present on main at the time of filing.

Impact

This is not confined to advisory prose. Two references are executable:

1. scripts/qualify_compass_store_release.sh hard-fails.

if [[ ! -d /Volumes/Workspace || ! -w /Volumes/Workspace ]]; then
  echo "error: /Volumes/Workspace must be mounted and writable" >&2
  exit 1
fi

The compass-store release qualification gate cannot be run by anyone without that volume.

2. Both qualification scripts silently redirect build output.

# scripts/qualify_code_graph_v1.sh
export CARGO_TARGET_DIR="${CARGO_TARGET_DIR:-/Volumes/Workspace/crabbuild-target/compass-main}"

# scripts/qualify_compass_store_release.sh
target_dir=${CARGO_TARGET_DIR:-/Volumes/Workspace/crabbuild-target/compass-store-phase9}

With CARGO_TARGET_DIR unset, these write to an absolute path outside the checkout.

3. skills/compass-release/SKILL.md lists the volume as a hard compatibility requirement and gates the release procedure on test -d /Volumes/Workspace.

The path also appears throughout PERFORMANCE.md, CLAUDE.md, docs/, advisor-plans/, and benchmarks/ — roughly 60 occurrences across ~25 tracked files.

Why this matters for agent workflows

AGENTS.md is explicitly the operating guide for AI coding agents, and the rule is stated as a hard stop. An agent that follows it faithfully on a machine without the volume refuses to verify anything — which is the correct reading of the instruction, and a total block. Agents that read AGENTS.md to derive build commands propagate the path into their own generated configuration, so the requirement spreads.

Suggested fix

Where build artifacts live is a per-contributor environment choice, not a repository rule. The genuinely useful guidance can be kept without hardcoding a path:

• give each checkout and worktree its own target directory (feature sets, build scripts, and locks collide otherwise);
• note that CARGO_TARGET_DIR does not persist between shell invocations;
• treat external qualification repositories as read-only inputs;
• run cargo clean only with the intended target directory explicitly set.

Scripts should honor CARGO_TARGET_DIR when set and otherwise fall back to Cargo's default, rather than defaulting to an absolute path or refusing to run. Documentation can use a placeholder such as <cargo-target-dir>.

If the disk-pressure concern behind the original rule is real, a note recommending an external target directory for large qualification runs would preserve the intent without making it mandatory.

Note

I have applied this fix in a fork (GQAdonis/compass) and am happy to open a PR against main if the direction is agreeable.