A Portable Agent Contract Cannot Link to a Local Plan

An AGENTS.md file can tell every compatible agent how a repository should be handled. That promise breaks when a rule links to a planning file that exists only on one developer's machine. The link works for its author, then becomes a dead end in a fresh clone.

This is a small boundary, but it is a useful test for portable context. If a future contributor cannot read an instruction and every document it depends on, the instruction is not yet a project contract.

APC is the portable context layer. It keeps repository-owned rules, agent definitions, skills, and non-secret MCP expectations in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It runs agents and keeps local operational material—sessions, private runtime memory, caches, and machine-specific state—outside the repository.

A local plan belongs on the APX side of that boundary unless it has been deliberately promoted into a shareable project artifact.

A link is an ownership claim

Consider this root instruction:

Read `spec/release-notes.md` before changing the deployment flow.

If spec/ is ignored because it holds exploratory notes or raw QA evidence, a new clone has neither the file nor its reasoning. The root contract now asks an agent to follow unavailable context. Worse, a reviewer can miss the error because the author's working tree resolves the link perfectly.

The same problem appears with absolute paths, private issue exports, temporary design notes, and runtime logs. They may be useful during one task. They cannot be prerequisites for portable behavior.

Treat every link from AGENTS.md, .apc/, or tracked documentation as a claim: this target is durable, safe to share, and available to a clean checkout. If that claim is false, change the contract.

Promote the decision, not the scratchpad

A local plan often contains valuable thinking mixed with temporary material. Do not copy the whole file into APC merely to repair a broken link. Extract the part that survives review.

For example, a local release investigation might establish one lasting rule: generated assets must be checked before publishing. That rule can live directly in AGENTS.md, or a concise explanation can become a tracked decision document. The raw command output, incomplete alternatives, and machine paths remain local.

A practical promotion flow is:

1. Keep the working plan and raw evidence local while the task is active.
2. Identify the decision that future contributors actually need.
3. Rewrite it as a short, self-contained project rule or tracked document.
4. Link only to that tracked artifact from APC context.

This gives a clean clone enough guidance to act without importing private or stale task history.

Use the smallest durable surface

Not every note needs a new document. A repository-wide instruction belongs in AGENTS.md. A reusable procedure can become an APC skill. A rule for only one folder belongs in .apc/rules/. A longer, reviewable rationale can live in ordinary tracked project documentation.

The important part is not the filename. It is whether the content remains true, readable, and useful beyond the machine that produced it.

APX helps keep the other category useful without pretending it is portable. Its local runtime can retain sessions, messages, task state, and private working material under its own storage. That lets an active task keep detail without leaking that detail into the repository contract.

Fresh-clone test

Before adding a context link, ask one question: would this still help an agent that cloned the repository today on another machine?

If yes, keep it tracked and make the target self-contained. If no, leave it in the local plan or runtime state, then promote only the verified conclusion when it becomes a real project constraint.

Portable context is not a directory full of references. It is a contract that can stand on its own. APC carries that contract; APX carries the local work around it.