docs(foundation): 'Decisions have a home' must say where — durable work products materialize into the repo, beads carry operational state (tk-4jz9s)#212
Conversation
…rk products materialize into the repo, beads carry operational state (tk-4jz9s) The belief said documentation is the system's memory and that "what's written survives", but never said where "written" lands. An agent could satisfy it completely by writing a long analysis into a bead comment — durable-looking, and invisible to anyone who clones the repo. That ambiguity stalled four docs-only PRs (#171, #170, #108, #88) for 4-7 weeks: the open question was not review, it was whether those documents should exist as committed files at all. Per the operator decision of 2026-07-22, gc-toolkit's durable work products materialize as repo artifacts and the bead store holds operational state only — the bead carries the index and the verdict, the repo carries the body. Sharpened in place on the existing belief rather than added elsewhere: this is one rule and it belongs on the belief that already owns it. Supersedes the earlier attempt in docs/file-structure.md (PR #203, tk-zdkfe), which governs the documentation surface — where a file sits once it exists — not whether a work product materializes at all.
|
Codex signoff (pre-open, comment-only — not an approval): Codex pre-open signoff: COMMENT (pass) Reviewed branch: polecat/tk-4jz9s Findings: none. Scope checked: docs/foundation.md only, with consistency against docs/file-structure.md. The change directly satisfies tk-4jz9s acceptance by naming the repo as the home for durable work products, assigning operational state to the bead store, and closing the bead-comment-only loophole. It does not touch docs/file-structure.md, other foundation beliefs, agent prompts, template fragments, or the out-of-scope lesson-capture work. Verification: git diff --check origin/main...82dedec passed. gc mail inbox was attempted with timeout 15 and timed out during known mail-store degradation; no handoff context was applied. |
| **Agents make their edges visible.** Looking smart and being smart are different. Legible agents show which. | ||
|
|
||
| **Decisions have a home.** Documentation is the system's memory. What's written survives; what isn't, doesn't. | ||
| **Decisions have a home.** Documentation is the system's memory, and its home is the repo: durable work products materialize as committed files, while the bead store carries operational state. What's committed survives; what lives only in a bead comment doesn't. |
There was a problem hiding this comment.
Right premise, not sure foundation.md is the right place. Foundation is not an operational implementation document, it is a what's our strategic vision.
|
Superseded — re-dispatching tk-4jz9s with corrected scope. #212 encoded the how (repo vs bead-store, committed-file vs bead-comment) into The replacement states the principle only: memory lives in the durable record, not the state that coordinates the work — no substrate names. Branch polecat/tk-4jz9s will be re-implemented with the agreed one-line string. |
…he durable record, not the coordination state (tk-4jz9s) The belief said documentation is the system's memory and that "what's written survives", but never said where "written" lands. An agent could satisfy it completely by writing a long analysis into the transient state that coordinates the work — durable-looking, but not part of the record anyone inherits with the work. That ambiguity stalled four docs-only PRs (#171, #170, #108, #88) for 4-7 weeks: the open question was not review, it was whether those documents belonged in the durable record at all. Stated as a principle, not a substrate: memory lives in the durable record, not in the state that coordinates the work. Supersedes PR #212, which encoded the same rule by naming the Gas City substrate (repo vs bead-store, committed-file vs bead-comment) inside an engine-agnostic Core Belief — the wrong altitude for a belief a beadless engine must also be able to satisfy. Distinct from the earlier PR #203 (tk-zdkfe) attempt in docs/file-structure.md, which governs the documentation surface, not whether a work product joins the durable record at all. Sharpened in place on the existing belief; one line, two sentences, matching neighbouring belief density. docs/file-structure.md, other beliefs, agent prompts, and template-fragments untouched; lesson-capture (tk-63qgj) left out of scope.
|
Superseded by #217 — the branch was re-implemented at a corrected substrate-agnostic scope (divergent head |
2 participants
Summary
Problem
docs/foundation.mdalready carries the principle under Core Beliefs:It never says where "written" is. An agent can satisfy that belief completely
by writing a long analysis into a bead comment in Dolt — durable-looking, and
invisible to anyone who clones the repo.
That ambiguity has a measured cost. Four docs-only PRs (#171, #170, #108, #88) sat
unapproved for 4-7 weeks. The operator's stated reason was not the review gate --
approving was easy -- but uncertainty over whether those documents should exist as
committed files at all. The belief as written could not settle it.
Decision (operator, 2026-07-22)
gc-toolkit's durable work products materialize as repo artifacts. The bead
store holds operational state only.
Rationale, compactly:
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.
git blame-> commit -> bead is the lineage path the pack already depends on.disposable once the work completes. The repo is the durable artifact: the thing
cloned, forked, or handed to another operator.
carries the body.
Scope
Sharpen the EXISTING "Decisions have a home" belief in
docs/foundation.mdso itstates where "written" lands.
owns it.
docs/foundation.mdor touch other beliefs, Boundaries,Goals, or "Who It Is For".
each. This should not become a section.
Explicitly NOT
docs/file-structure.mdAn earlier attempt at this rule (PR #203 / bead tk-zdkfe) put it in
docs/file-structure.md. That was the wrong home and this bead supersedes it.file-structure.mdgoverns the documentation surface -- the two tiers,bead-keyed naming, the no-archiving rule, where a file sits once it exists. This
rule is broader and prior: it governs whether a work product materializes as a
repo artifact at all, and it is not documentation-specific.
Leave
docs/file-structure.mdunmodified in this bead.Related, deliberately out of scope
The sibling belief "Agents improve. Lessons come from doing; the system carries
them across restarts" -- and the intro's "every lesson compounds into the pack" --
raise the same materialization question for lessons rather than analysis. That is
tracked separately at tk-63qgj (lesson-capture approach: PR #88's fragment+doctrine
vs compound-engineering
ce-compound). Do NOT implement lesson-capture here, and doNOT edit agent prompts or
template-fragments/.Acceptance
docs/foundation.mdstates unambiguously that durable work products materializeinto the repo and that the bead store carries operational state, such that "what's
written survives" can no longer be satisfied by a bead comment alone. A reader
deciding "should this analysis be a committed file?" gets the answer from the
belief itself.
Implementation notes
Implemented: sharpened the existing 'Decisions have a home' belief in docs/foundation.md to state where 'written' lands — durable work products materialize as committed files in the repo, the bead store carries operational state, and the closing clause ('what lives only in a bead comment doesn't') closes the loophole named in the bead. One-line change, 2 sentences, matches neighbouring belief density. No new doc; docs/file-structure.md, other beliefs, Boundaries, Goals, 'Who It Is For', agent prompts and template-fragments all untouched. Lesson-capture (tk-63qgj) left out of scope. Branch polecat/tk-4jz9s @ 82dedec (signed, verified).
Refinery handoff
tk-4jz9s(task, P2)polecat/tk-4jz9smain82dedecc; PR opened codex-green.