Planning Is Not a Guardrail in APC and APX

A planning note can explain why a project may change next week.

A guardrail has to explain how the project works today.

That difference matters more once you split portable context from runtime behavior.

APC is the portable context layer. It keeps project-owned facts in repository files such as AGENTS.md and .apc/, so another tool, another machine, or another contributor can recover the same contract from the clone itself.

APX is the daily-use runtime and tooling layer. It reads that contract, adds local runtime state, and turns it into actual work through the CLI, daemon, web admin, channels, sessions, and local stores.

That split only stays clean if durable rules live in tracked files, while planning stays local.

Why this boundary matters

The APX repo says it directly in spec/README.md: planning is not a guardrail.

That file keeps spec/ gitignored on purpose. Roadmaps, backlog notes, PRDs, and active design scratch work stay there because they are temporary, local, and often unsafe to publish as stable project truth.

The durable material lives elsewhere.

In the same repo, rules/ is the tracked engineering contract. It holds the workflow, architecture constraints, testing expectations, documentation rules, and decision records that contributors actually need in order to work correctly.

That is the right split.

If a new contributor clones the repo, a guardrail must already exist in the clone. A local planning note is not enough.

APC makes the distinction sharper

Without APC, many teams let this blur. A roadmap note, a scratch design doc, and an actual project rule all end up in some folder called docs or notes, and the runtime figures it out later.

APC makes that sloppiness more expensive.

Portable context is supposed to travel.

If you commit planning noise as if it were project contract, other tools will read unstable material as if it were durable truth. If you keep real rules only in local notes, fresh clones lose the instructions they actually need.

So APC should carry committed, reviewable project context.

APX should consume that context and keep its own local runtime state outside the repo.

Planning belongs to neither category. It is not stable enough for APC, and it is not runtime state either. It is just local working material.

Practical example

The APX repo uses three lanes that make the difference easy to see.

• AGENTS.md is the always-read root contract for agents and repo rules.
• rules/ holds tracked deep dives, workflows, and architectural decisions that other contributors must be able to read.
• spec/ holds local planning documents that do not ship.

That means a contributor can clone the repo and get the durable contract immediately.

They do not depend on one maintainer's unfinished roadmap file.

It also prevents another common failure: tracked files linking to local-only planning docs. The APX spec/README.md calls this out explicitly because those links were dead in fresh clones and on GitHub. That is exactly what happens when a team mistakes internal planning for public contract.

Why APX benefits from this too

APX is a runtime, so it already has to separate what belongs in the repository from what belongs on one machine.

Sessions, conversations, messages, caches, and secrets stay under ~/.apx/ because they are runtime-local.

But that does not mean every important note should become runtime state.

The workflow rules, architecture boundaries, and contributor-facing decisions still belong in tracked repo files, because they define how humans and tools should operate on the project itself.

So the real split is three-way:

• APC holds portable project context.
• APX holds local runtime state and tooling behavior.
• planning stays local until it becomes either durable project contract or disposable scratch work.

That middle step is easy to skip, but skipping it creates confusion fast.

Small rule, big payoff

The practical rule is simple:

If another contributor must rely on it today, track it.

If it only describes work in flight, keep it local.

That rule makes APC cleaner because portable context stays durable.

It makes APX cleaner because runtime storage does not become a dumping ground for project guidance.

And it makes the repo easier to trust, because readers can tell which files describe the project as it exists now versus one person's temporary plan.

Planning is useful.

It just is not the contract.