---

name: ledger-append-etiquette description: > Run BEFORE you append a row to agi-proof/failure-ledger.md, or write to any of this repo's append-heavy shared files — agi-proof/evidence-manifest.json, RESULTS.md, or the live SESSION-COORDINATION.md — and whenever a task adds/edits a failure-ledger row, records a NO-GO/candidate result, claims/releases work in the coordination ledger, or regenerates the evidence manifest. These files are touched concurrently by many Claude/Copilot/GLM/human sessions on ONE checkout; two sessions hand-editing the same one collide, a bad Status string silently flips OPEN→resolved, and a stale manifest fails CI. Use even if the edit "looks like one line". ALSO fires the instant you are about to >> / append / "add a row to" the failure ledger: the table ENDS at the first ## section (~line 530 of ~6900), so a row appended at end-of-file is parsed as section prose and SILENTLY DROPPED while validate_failure_ledger.py still exits 0 and prints structural validity: OK. Verify an append by the CHANGE IN tableRows/openCount, never by the exit code — see §2b. metadata: short-description: "Serialize + union-resolve appends to the shared ledger/manifest/coordination files without collisions or a fail-closed Status"

Ledger / manifest append etiquette (this repo)

See also ci-artifact-drift (the ledger is a CI-validated artifact; the evidence manifest is regenerable-not-committed, see §3), session-handover §1 (SESSION-COORDINATION.md is the live ownership ledger), and git-discipline §4 (isolate your changes; never git add -A).

Several files here are append-heavy and shared: every session adds rows/sections to the same tail. Because 5+ sessions run on one checkout, the recurring waste is (a) two sessions editing the same file in parallel PRs → merge conflict or a clobbered append, and (b) a Status string that fails CI after the GPU work is already done. This skill is the cheap pre-flight.

The files this governs:

| File | Shape | Gate | |---|---|---| | agi-proof/failure-ledger.md | append ## <id> sections + a table row | tools/validate_failure_ledger.py --check | | agi-proof/evidence-manifest.json | generated + gitignored — never hand-edit, never commit | regenerate locally with python tools/build_agi_proof_package.py; CI rebuilds it (see §3) | | RESULTS.md | generated from published-results.json — never hand-edit | tools/build_results_page.py --check | | SESSION-COORDINATION.md | live, untracked CLAIM/OWNS/DONE ledger | none (ephemeral) — but still collision-prone |

1. Route the append through the serializer — don't hand-race the tail

Two sessions writing the tail of the same shared file in parallel PRs is the #1 collision. Before appending:

• Prefer the append-serializer MCP tool (the sophia-agi MCP server, .mcp.json → sophia_mcp/server.py) when it is enabled — it takes a per-file lock, appends your block, and regenerates the dependent artifact atomically, so two sessions can't interleave.
• If you are hand-editing, first claim the file in SESSION-COORDINATION.md (append an OWNS: failure-ledger.md — <session-id> line, read the existing OWNS lines first). Never open a second PR that touches a shared file another live session already claimed.
• One shared file per PR. Do NOT hand-edit two of these files in the same branch/PR — split them so each lands (and conflict-resolves) independently.
• This pairs with the one-GPU-job invariant (spark-cluster-ops): finish and land the ledger row for a run before the next session launches over it.

2. The Status cell must NEVER contain the substring closed

tools/validate_failure_ledger.py classifies a row by substring: _RESOLVED_MARKERS = ("closed", "cleared", "superseded", "resolved", "fixed", …) and resolved beats open. So a Status like fail-closed, gate closed, or closed-loop on an item that is actually still OPEN is silently reclassified resolved — it drops off the "what still blocks the AGI claim" list. Footgun, not a feature.

• For an open item use OPEN, PARTIAL, BLOCKED, PENDING, NOT YET (these hit _OPEN_MARKERS).
• Describe fail-closed behavior in the body prose, never in the Status cell/**Status:** line.
• To actually mark something done, use RESOLVED/CLEARED/SUPERSEDED — a word, deliberately.

2b. The row must land INSIDE the table — appending at EOF is a silent no-op

_parse_table stops at the first ## heading:

cutoff = next((i for i, ln in enumerate(lines) if ln.startswith("## ")), len(lines))

agi-proof/failure-ledger.md is a short table (ends ~line 530) followed by hundreds of ## <id> write-up sections. So the "tail" of the file is not the tail of the table. A row appended with >> at end-of-file is parsed as prose inside the last section, and:

• validate_failure_ledger.py exits 0,
• prints structural validity: OK,
• and the row does not exist as far as every consumer is concerned.

Nothing reports this. A clean exit means "nothing parsed", not "row accepted" — the same dishonest-failure shape as the :LINE citation trap at the top of the ledger. Measured 2026-08-03: a row appended at EOF left tableRows at 491 and openCount at 437, unchanged.

Append here instead — as the last line of the table, immediately before the first ## :

CUT=$(grep -n "^## " agi-proof/failure-ledger.md | head -1 | cut -d: -f1)
awk -v c="$CUT" 'NR<c && /^\|/ {last=NR} END{print "insert after line", last}' agi-proof/failure-ledger.md

Then verify by COUNT, never by exit code (this is the check that would have caught it):

python3.12 tools/validate_failure_ledger.py --json   # before and after
# tableRows and openCount MUST each rise by exactly 1, and your id MUST appear in openItems

If the counts did not move, your row is not in the ledger no matter what the exit code said.

3. The evidence manifest is regenerated, NOT committed — never git add it

agi-proof/evidence-manifest.json reads the ledger's OPEN/RESOLVED summary, so a new/edited row makes it stale. It used to be committed and regenerated in every PR — which made it the #1 recurring merge conflict in this repo: concurrent PRs each regenerated it and collided on its machine-generated body, and it cannot be auto-merged (its content is a function of the whole merged ledger, which git doesn't have while merging line-by-line). So it is now gitignored and untracked: CI (ci.yml validate-build, pages.yml) rebuilds it, and readers tolerate its absence. After touching the ledger:

python tools/validate_failure_ledger.py --check     # structure + Status sanity (see §2)
python tools/build_agi_proof_package.py             # regenerate the manifest LOCALLY (optional)
make claim-check                                     # the no-overclaim contract (must stay green)

• Only stage the ledger — git add agi-proof/failure-ledger.md (explicit path). The manifest is gitignored; do NOT git add/git add -f it back. Force-adding it re-tracks the file and re-introduces the exact conflict this design killed.
• Regenerating locally is only for your own inspection (the web build, a local bench read). It is never part of a commit and never needs to match anyone else's copy.
• Never hand-edit evidence-manifest.json or RESULTS.md — RESULTS.md is still committed, so regenerate it from published-results.json and stage it; the manifest is not.
• Do not wire python tools/build_agi_proof_package.py --check into any workflow — --check fail-closes on the (now normally-absent) file and would red the required checks.

4. On conflict, UNION-resolve — never drop a sibling's append

These are append-only logs: a conflict means two sessions each added a block at the tail.

• Keep BOTH sides. Resolve by concatenating the two appends (union), then re-sort/renumber ids if the format requires it — never take "ours" and discard the other session's row.
• After a union resolve, re-run tools/validate_failure_ledger.py --check (a merged table can duplicate an id). The manifest no longer needs conflict-resolving (§3) — it is gitignored, so a ledger merge never touches it; regenerate it locally only if you want a fresh local copy.
• For SESSION-COORDINATION.md (untracked, so no git conflict) union by hand: read the whole file fresh, append your line, keep every existing OWNS/DONE line.

Rules

• Faithful reporting only: a NO-GO/candidate result goes in the ledger as NO-GO/candidate — never soften it, never lower a gate to make it pass (ci-artifact-drift). This is dev-workflow etiquette; it makes no capability/AGI claim and canClaimAGI stays false.
• If your edit changes what is claimed (a result's status, "validated"), that is the no-overclaim contract — stop and follow sophia-agi/ci-artifact-drift, not just this skill.