Unknown .apc/ Paths Should Not Become Hidden Instructions

A repository can contain a file under .apc/ without making that file part of the APC contract. The APC folder structure specification says consumers ignore unknown paths unless a formal APC extension defines them. That small rule gives teams room to experiment without making every local file an instruction for every agent.

APC is the portable context layer: AGENTS.md and defined .apc/ paths carry project-owned context across compatible tools. APX is the daily-use runtime and tooling layer that reads the project contract and keeps execution state, such as sessions and messages, in runtime storage. The boundary matters most when someone adds a new file that looks authoritative.

A Plausible but Unsafe Shortcut

Imagine a team adds this file during a trial:

.apc/triage-priority.md

It contains a list of customer incidents and a note saying to prioritize one queue. A custom local script reads it. Another tool walks the entire .apc/ tree and feeds every Markdown file to its agent as instructions. The same checkout now produces different behavior depending on which tool opens it. Worse, the second tool has silently promoted an experimental note into project policy. That is the failure mode the unknown-path rule prevents.

File Location Alone Is Not Enough

File location alone is not enough to assign semantics. A consumer needs to know which APC path it is reading and what that path means. If it cannot identify the path, it should leave it alone. Human reviewers can still read the file; the point is that a generic APC reader should not invent an interpretation.

Put Instructions on a Defined Surface

If the triage rule must apply throughout the repository, put the stable instruction in AGENTS.md. If it applies only to certain paths or tasks, use a defined file under .apc/rules/ with a clear description and scope. If it is a procedure an agent may invoke, use .apc/skills/. These surfaces give readers a reason to load the content and reviewers a way to check whether its reach is appropriate.

Experimental Data and Extensions

Keep the experimental data elsewhere until its role is decided. A normal project document can hold background information without claiming APC semantics. If the team needs a new machine-readable APC capability, define an extension instead of relying on a private filename convention. Then a consumer can deliberately support it and handle unsupported versions predictably.

Security and Privacy

This does not mean unknown files are harmless. Do not put credentials, raw conversations, caches, or private runtime memory in .apc/. APC's documented layout keeps those in local runtime storage; APX uses ~/.apx/projects/<project-id>/ for project runtime state. Ignoring an unknown path is a parsing rule, not a privacy control or a license to commit sensitive files.

Quick Review Test

When a new .apc/ file appears in a pull request, ask:

• Is this path defined by APC or an explicit extension?
• If yes, does its content match that path's purpose?
• If no, should it become an AGENTS.md rule, an APC rule or skill, or ordinary project documentation?
• Finally, would a compatible reader know when to load it without guessing?

That review keeps the portable layer predictable. APX can execute the project contract in daily work, and another compatible tool can read the same contract without inheriting undocumented behavior from whatever files happen to sit beside it.