docs(file-structure): state the repo-vs-bead-store rule for agent-written docs (tk-zdkfe)#203
Closed
zook-bot wants to merge 1 commit into
Closed
docs(file-structure): state the repo-vs-bead-store rule for agent-written docs (tk-zdkfe)#203zook-bot wants to merge 1 commit into
zook-bot wants to merge 1 commit into
Conversation
…tten docs (tk-zdkfe) file-structure.md was the authority on WHERE in the repo a gc-toolkit-written doc goes — central docs/ vs local specs/<bead-id>/ — 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.
Contributor
Author
|
Codex signoff (pre-open, comment-only — not an approval): Pre-open codex signoff: COMMENT (pass) Scope reviewed: origin/main...cb3d36a on branch polecat/tk-zdkfe. Findings: none. Verification:
No runtime tests apply; this is a docs-only insertion. |
zook-bot
added a commit
that referenced
this pull request
Jul 22, 2026
…xt step FOREVER — permanent per-molecule polecat burn, does NOT stop when the anchor lands (tk-p9ji9) (#205) ## Summary OBSERVED (gc-toolkit, 2026-07-17T09:21Z-09:32Z): four polecat sessions (lx-xz3a6, lx-94hvo, lx-8tznd, lx-r2nhg) were spawned ~5min apart and each claimed the SAME step bead tk-cnt3i (mol-polecat-work.load-context) for work that was already complete, shipped, and parked in the merge gate. Each session burned a wisp to re-derive "nothing to do" and drain. See tk-3b5hv notes for the per-incarnation record. MECHANISM: - mol-polecat-work (graph.v2) materializes 7 step beads but the polecat executes them INLINE in one session; no step contains `bd close`. Steps are meant to be finalized by machinery. - The step graph is chained: load-context blocks workspace-setup blocks ... So while load-context stays open it is the ONLY ready step. - load-context carries gc.routed_to=gc-toolkit/gc-toolkit.polecat. Open + ready + pool-routed = the pool re-offers it to every idle polecat, forever. - The workflow root (tk-6j9ue) appears to wait on its input convoy (tk-we737) to complete. The convoy's single member is the work bead tk-3b5hv, which stays OPEN by design under close-on-land until the refinery lands the PR. So the workflow cannot finalize while the PR sits in the gate, and the loop runs for the whole duration of the HUMAN approval wait (potentially hours/overnight). SCOPE: likely affects EVERY mr-mode PR awaiting operator approval, not just this bead. Corroborating: six "Finalize workflow" step beads are currently open in this rig (tk-nzuv8, tk-smqq0, tk-sbhp9, tk-f372s, tk-tdey1, tk-x82ck). DANGER — DO NOT "FIX" BY CLOSING THE STEP BEAD: Closing load-context to stop the churn would unblock workspace-setup, and the pool would walk the next polecat forward into implement/self-review on a branch that is ALREADY green-gated and PR'd. Any push there moves the head, which stales the anchor's `check.codex=green@<oid>` marker and BLOCKS the open PR from merging. The "polecat never closes mol-polecat-work step beads" rule exists for this reason. The correct fix is at the machinery level, not by hand on live workflow state. CANDIDATE FIXES (for triage, not prescriptive): 1. Stop pool-offering steps of a workflow whose root is already parked/waiting — e.g. clear/suppress gc.routed_to on step beads once submit-and-exit has run (the anchor carries merge_result=pre_open_gate|pull_request, a reliable signal that the workflow's inline execution is DONE). 2. Have the hook skip a ready step whose workflow root's convoy member already carries a terminal merge_result. 3. Finalize the step graph at submit-and-exit time rather than on convoy completion, so close-on-land's intentionally-open anchor stops holding the whole step graph open. RELATED: tk-qnsqhv (double-dispatch race — distinct: that is a bead re-pooled while its original polecat is still live; this is a completed workflow's dead step re-offered indefinitely). EVIDENCE ANCHOR: tk-3b5hv / PR #192 (open, non-draft, headRefOid=846c24a, check.codex=green@846c24a, reviewDecision=REVIEW_REQUIRED — normal awaiting- external-approval, not a stall). ## Implementation notes Implemented: witness-patrol now auto-quiesces completed mol-polecat-work husks (clears gc.routed_to AND assignee; never closes a step). Validated against live rig state — 12 steps quiesced across 2 done molecules, both re-offer paths confirmed dead, anchors/PR #203 undisturbed. 11/11 test suites green. RE-OFFER #1 (resumed session gc-toolkit__polecat-lx-vg082, 2026-07-22T08:14Z): load-context husk tk-fgkgk was re-offered on the hook. Verified NO action needed — this is the bug's own symptom, not new work. Anchor state: merge_result=pre_open_gate, branch polecat/tk-p9ji9 pushed at e9f8270, review bead tk-ghlvg OPEN and routed to gc-toolkit/gc-toolkit.polecat-codex (pre-open codex gate queued, in flight). Deliverable re-verified against the required scope in the 2026-07-22 comment: quiesce-completed-workflows.sh handles BOTH shapes (unassigned -> unset gc.routed_to; affine assignee+session_affinity=require -> clears assignee too), gated on anchor merge_result in {pre_open_gate,pull_request,merged}, never closes a step (DANGER clause honored), wired into mol-witness-patrol.toml with a hermetic test. No re-handoff, no re-implement, no close. Drained. RE-OFFER #2 (same session slot gc-toolkit__polecat-lx-vg082, 2026-07-22T08:19Z): husk tk-fgkgk re-offered via the ASSIGNED-WORK path (gc hook reason=existing_assignment — the assigned shape, so clearing gc.routed_to alone is a no-op). Re-verified: branch polecat/tk-p9ji9 @ e9f8270, local HEAD == origin; commit carries quiesce-completed-workflows.sh + .test.sh + mol-witness-patrol.toml wiring; no PR (correct for pre_open_gate); review bead tk-ghlvg in_progress with codex polecat lx-07t9t, gate in flight and healthy. No action needed. ESCALATED to gc-toolkit.witness (mail lx-wisp-ousk1) to de-route the husk (clear assignee AND gc.routed_to) and sweep siblings of root tk-zleg5; DANGER clause restated — no step bead closed. Future incarnations: escalation is already filed, verify silently and drain; do NOT re-escalate or re-append. ## Refinery handoff - Issue: `tk-p9ji9` (bug, P2) - Source branch: `polecat/tk-p9ji9` - Target: `main` - Codex signed off pre-open at `e9f82707`; PR opened codex-green.
Contributor
Author
|
Superseded by tk-4jz9s — wrong home for this rule.
The reasoning from this PR is preserved in tk-4jz9s's brief; nothing is lost. Closing rather than leaving it open so it does not become another stranded anchorless PR. |
zook-bot
added a commit
that referenced
this pull request
Jul 23, 2026
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Problem
docs/file-structure.mdis the authority on WHERE in the repo a gc-toolkit-writtendocument goes: central
docs/(authoritative, "what's true now", refreshed in place)vs local
specs/<bead-id>/(historical record, "what was thought", read whenlinked-to), plus the no-archiving rule.
It never states the tier above that: whether agent-written analysis should be a
committed file at all, vs. living only as bead content in Dolt.
That silence 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 -- it was that they "wasn't sure they should exist." The doc
answered "which directory" but not "should this be a file."
Decision (operator, 2026-07-22)
Agent-written analysis commits to the repo.
Rationale -- the record belongs with the artifact it explains:
code looks the way it does. Put it only in Dolt and understanding the repo
requires a live bead server plus the right credentials and city.
git blame-> commit -> bead is the lineage pathfile-structure.mdalreadydepends on (see its "Lineage in central docs is via git history" rule).
disposable once work completes. The repo is the durable artifact: it is what
gets cloned, forked, or handed to another operator.
carries the body. This matches the doc's existing "read when linked-to" access
model for
specs/.Scope
Add ONE short section to
docs/file-structure.mdstating this rule.name/description, a## Scopesection, the existing prose register).surrounding sections.
Acceptance
A reader deciding "should this analysis be a committed file, or just a bead
comment?" gets an unambiguous answer from
docs/file-structure.mdalone, withoutneeding to reconstruct the reasoning.
Implementation notes
Re-offer #2 verified (no-op): re-confirmed branch polecat/tk-zdkfe @ cb3d36a on remote, 1 commit, docs/file-structure.md +22/-0 — in scope. Anchor still open/unassigned at merge_result=pre_open_gate; codex review tk-ev0j0 now in_progress (gate live, nothing stalled). Root cause is the graph.v2 husk tk-qx74t (7 never-closed step beads, load-context tk-4p3af re-offered each pool cycle). ESCALATED ONCE to gc-toolkit/gc-toolkit.witness (mail lx-wisp-bj1da) to de-route the husk root downstream-first — do NOT re-escalate on the next re-offer, and do NOT force-close the step beads (partial close re-drives submit-and-exit -> duplicate PR). No re-implement, no re-handoff, nothing closed.
Refinery handoff
tk-zdkfe(task, P2)polecat/tk-zdkfemaincb3d36af; PR opened codex-green.