From 6a06209ef5dbdc5df877a2a6ec287f51f41031ab Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 13 Sep 2026 21:45:28 +0000 Subject: [PATCH] fix: the doc boundary is on-demand, not off-limits This repo's six agent wrappers -- CLAUDE.md, CONVENTIONS.md, guidelines.md, replit.md, .devin/README.md and .grok/GROK.md -- all say "read `README.md` and `docs/` only when the task is to change them". AGENTS.md, which every one of them names as the source of truth, said `never_read` on both paths. The wrappers are right. chock settled this in its own repo in `4e85f97`: the rule is a context-economy one, not a secrecy one, and `never_read` overstated it -- two workers there stopped on it when asked to improve the very files it named. That fix reached the wrapper text chock emits but not the AGENTS.md template it scaffolds, so this repo was left with the two halves disagreeing. The overstatement matters more here than elsewhere: `llms.txt` points assistants at `docs/cli.md` and `docs/library.md`, and this is a repo whose whole subject is whether agent-facing instructions actually work. Wording taken verbatim from chock's own AGENTS.md, predicate and reason together, so there is nothing left to reconcile between the two repos. Verified: 407 passed, 1 skipped; `ruff check` clean; `ruff format --check` 241 files. `chock sync` does not manage this section -- `update_agents_md` rewrites only the pointer region -- so the edit is durable. Co-Authored-By: Claude Opus 5 Signed-off-by: Claude --- AGENTS.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b297d4..bbfe438 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,8 +20,14 @@ source_of_truth: AGENTS.md; adapters: thin_wrappers(delegate_here); authority: n ## Data boundaries -- never_read(file: README.md) -- never_read(path: docs/) +These are a context-economy rule, not a secrecy one. `README.md` and `docs/` are large, +human-facing, and irrelevant to most tasks, so loading them by default spends context an +agent needs for the actual work. They are **on-demand, not off-limits**: when the task is to +change one of them, read it and change it. + +- read_on_demand(file: README.md) — not read for general work; read and edit it when the task + is to change it +- read_on_demand(path: docs/) — same - agent_source: AGENTS.md, .agents/skills//SKILL.md, .agents/policies//manifest.yaml - human_source: docs/**