From cb3d36afb0688cd9f8fb4df12410342a459dd56a Mon Sep 17 00:00:00 2001 From: Zook Bot <275398848+zook-bot@users.noreply.github.com> Date: Wed, 22 Jul 2026 07:42:25 +0000 Subject: [PATCH] docs(file-structure): state the repo-vs-bead-store rule for agent-written docs (tk-zdkfe) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit file-structure.md was the authority on WHERE in the repo a gc-toolkit-written doc goes — central docs/ vs local specs// — but never stated the tier above that: whether agent-written analysis should be a committed file at all, or just content on the bead. That silence had a measured cost. Four docs-only PRs (#171, #170, #108, #88) sat unapproved for 4-7 weeks; the stated reason was not the review gate but uncertainty over whether the docs should exist. Add one short section, placed before the two-tier rules because it is the prior question: agent-written analysis commits to the repo. The record belongs with the artifact it explains — a clone is self-contained, and git blame -> commit -> bead (the lineage path central docs already depend on) needs a commit to land on. Beads are operational state; the repo is the durable artifact. The bead carries the index and the verdict, the repo carries the body. No restructuring: the two-tier rules, the no-archiving rule, the naming conventions, and the doc's ## Scope are untouched. --- docs/file-structure.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/file-structure.md b/docs/file-structure.md index 674cbe4..9420012 100644 --- a/docs/file-structure.md +++ b/docs/file-structure.md @@ -39,6 +39,28 @@ document's own content, held by its [`## Scope`](#the-scope-section). | "I need to file a new \." | If it's durable and one-of-a-kind: central. If it's tied to a piece of work: local under that work's bead-ID. | | "Loading context for task X." | Bead-graph from the task's bead (via `bd dep`/`bd show`) + central docs. | +## Repo or bead store: analysis commits to the repo + +The two tiers below decide where a file goes. They assume there is a +file. The prior question — should this analysis be a committed file at +all, or just content on the bead? — has one answer: **agent-written +analysis commits to the repo.** + +The record belongs with the artifact it explains. A clone is +self-contained: whoever holds the repo holds the reasoning for why the +code looks the way it does. Left in the bead store alone, that reasoning +needs a live bead server, credentials, and the right city to reach, and +`git blame` → commit → bead — the lineage path central docs +[depend on](#inside-docs) — has nothing to land on. + +Beads are **operational state**: routing, status, assignment — per-city, +and disposable once the work completes. The repo is the **durable +artifact**, the thing that gets cloned, forked, or handed to another +operator. So the bead carries the index and the verdict; the repo +carries the body. That is the same +[read-when-linked-to](#two-tiers-central-authoritative-local-historical) +model `specs/` already runs on. + ## Two tiers: central authoritative, local historical *Mnemonic: central is what's true; local is what was thought.*