docs(foundation): sharpen 'Decisions have a home' — principle only, state where memory lives without naming the substrate (tk-4jz9s)#217
Conversation
…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.
|
Codex signoff (pre-open, comment-only — not an approval): Code Review ResultsScope: branch-remote Reviewers: correctness, testing, maintainability, project-standards FindingsNo blocking findings. Coverage
|
|
Abandoning this approach per operator. Editing foundation.md was the wrong solution — the goal is a PROCESS mechanism (skill/guidance) that ensures agents write documentation to the right place, not a recorded belief. foundation.md stays untouched. Tracking the real work separately. |
1 participant
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).
Re-implemented with corrected (substrate-agnostic) scope per the PR #212 supersede.
Branch polecat/tk-4jz9s rebuilt from origin/main @4b09bd5 → single signed commit 2d06892.
docs/foundation.md "Decisions have a home" now states the principle WITHOUT naming the Gas City substrate: "memory lives in the durable record, not the state that coordinates the work." Wording confirmed with operator.
Old commit 82dedec (PR #212, closed UNMERGED — wrong altitude) dropped. Stale check.codex@82dedec and merged_target cleared so the pre-open codex gate re-runs on 2d06892 and opens a fresh PR (#212 stays closed).
Scope: docs/foundation.md only (1 line). file-structure.md, other beliefs, agent prompts, template-fragments untouched; lesson-capture (tk-63qgj) out of scope.
Refinery handoff
Issue:
tk-4jz9s(task, P2)Source branch:
polecat/tk-4jz9sTarget:
mainCodex signed off pre-open at
2d06892b; PR opened codex-green.Supersedes docs(foundation): 'Decisions have a home' must say where — durable work products materialize into the repo, beads carry operational state (tk-4jz9s) #212 (corrected substrate-agnostic scope; branch force-pushed to a divergent head, old PR closed-unmerged).