Protected paths

The files an agent may not write without holding the right token — and where that list really comes from.

Some files in the repo are too important to edit casually: the policy itself, the invariants, the secrets, the deploy scripts, the dashboard sidebar. These are protected paths. A protected path is a glob pattern plus a required scope — the token an agent must hold for a write to that path to be allowed.

How a protected path is checked

When an agent tries to write or edit a file, the gate matches the path against the protected globs. Three outcomes:

• No match — the path isn’t protected; the write proceeds (subject to the gate’s other tiers).
• Match, and the agent holds the required token — allowed. The token comes from the worktree’s scope manifest.
• Match, and the token is missing — denied, and the attempt is written to the audit log.

The never-grantable case

A protected path can declare its required scope as null, which means no token can ever unlock it — not even an operator-issued one. The gate treats a null required scope as “always deny”. This is the strongest setting: the path is off-limits to every agent, full stop.

The scope tokens

Tokens are short labels naming a category of sensitive work. An agent only holds a token if the operator granted it for the current task. The recognised tokens include:

Token	Unlocks
auth	Authentication / secret-handling paths.
compose	Compose files and deploy definitions.
meta	The policy and governance files themselves (e.g. editing AGENT_POLICY.yaml).
migration	Database migration files.
container-new	Introducing a new container/service.
task-approved	The middle tier — a general code change the operator has approved a plan for.

Derived, not authored

This is the key fact about PROTECTED_PATHS.md: it is the human-readable rendering of the protected-path list, and it is derived from AGENT_POLICY.yaml — not the source. The YAML is canonical; the markdown is generated from it for people to read.

Edit the source, not the copy

If you change PROTECTED_PATHS.md by hand, a CI consistency check compares it against the YAML, finds the drift, and fails the build. The fix is always to edit AGENT_POLICY.yaml and regenerate. Two files, one source of truth.

Three layers guard the same paths

Protected paths are enforced at more than one checkpoint, on purpose:

• The gate blocks the write as it happens (write-time).
• The post-hoc sweep re-checks the diff after a run and reverts anything that slipped through (after-the-fact).
• CODEOWNERS routes the same paths to the operator for review at merge time (merge-time).

A write that dodges one layer still meets the next. That redundancy is the whole design.

See also

• Agent policy (YAML) — the canonical source these paths come from.
• Scope manifests — where an agent’s tokens live.
• The gate — the write-time check.
• Post-hoc sweep — the after-the-fact net.