AGENTS.md: make "push a WIP commit before any minutes-long step" an ordering rule — the one lesson from the 2026-08-25 restart that is not already covered

[os-steve]

Filed unassigned, recording only.

A container restart on 2026-08-25 killed five in-flight os-dev agents. Four of tonight's five lessons turned out to be instances of rules the repo already has, and are recorded as findings rather than as new doctrine. This card is the one that is genuinely missing.

The gap, measured

AGENTS.md carries no rule about committing before a long-running step. Verified with a working control:

grep -niE 'commit before|before you wait|wip commit|push.*before' AGENTS.md → 0 hits
grep -ncE 'git stash' AGENTS.md → 2 hits (control: the grep works)

The nearest thing that exists is #11463, whose framing is parking: an agent that decides to wait should commit first. The restart showed that framing is too narrow — the rule has nothing to do with parking.

What the restart measured

card	ran for	committed?	outcome
#11694	~14 min	no	branch pushed empty (0 commits ahead), worktree clean — total loss
#11942	~14 min	no	branch pushed empty, worktree clean — total loss
#11525	hours	no	⭐ 2081 lines uncommitted — a 1194-line gate, an 864-line baseline, lint.yml +22, package.json +1
#9165 step 2	hours	no	scratch instruments survived on disk; the analysis died with the context
#9298	hours	n/a	worktree clean, nothing to recover

Only luck saved #11525: the worktrees outlived the processes, so a rescue dispatch could commit and push the work (f7e038cda). This environment documents that it reclaims the filesystem — so that luck is not repeatable.

⭐ Why the current phrasing cannot reach the agents that need it

The cost of not committing is inversely related to how well the agent is behaving. An agent that finishes fast commits soon and risks little. An agent deep in a hard card — measuring, ablating, re-deriving — defers committing because it is not done yet, and so accumulates the largest uncommitted surface exactly where the work is most expensive to reproduce. #11694 and #11942 lost 14 minutes each. #11525 lost hours because it was doing the card properly.

So the population that most needs the rule is the population least likely to be reached by it: "commit before you wait" does not fire for an agent that is not waiting — it is working.

The proposed rule

Change the trigger from "before you wait" to "before anything that is not the next edit" — before a build, a full test run, a gate sweep, an ablation, any step measured in minutes.

Push a WIP commit before every step that takes minutes — a build, a full test run, a gate sweep. Not because you are about to wait: because you are about to stop being the only copy.

#11463 already establishes that ordering rules are the instructable kind (do-not-end-the-turn survived three escalating strengths; commit-before-you-wait did not need to). Tonight's rescue is a second confirmation: told "commit and push before reading anything else," the agent did exactly that, and 2081 lines were safe on origin before it began verifying anything.

⚠️ The cost, measured — this needs paying for, not just writing

AGENTS.md is 1149 lines against a ceiling of 1149 — headroom 0, and scripts/pm/check-skill-line-ratchet.mjs is shrink-only: raising a ceiling "requires a maintainer ruling quoted in the raising PR's body" and wants "its own card".

So this is not a one-line edit. Two routes, and the first is preferred:

1. Pay by in-place compression — the established idiom in this repo (see PR review-checklist: add the git-first spot-check row, paid by in-place compression #11987, "…paid by in-place compression"). Preferred: it keeps the ratchet honest and needs no ruling.
2. If compression cannot pay for it, this needs a ceiling ruling and should be re-labelled needs-user-decision rather than raising the ceiling quietly.

⚠️ Note that #11910 is an open, unresolved decision about this same ceiling family. Whoever takes this card should read it first — the two may want deciding together rather than separately.

Deliberately NOT filed as cards — already covered

Recording these so nobody re-files them as new doctrine. Each is a worked example of a rule the repo already has, and paying compression to restate an existing rule is negative value:

• Guessed script paths were wrong twice (scripts/ci-failure.mjs, scripts/affected-docs.mjs; real: scripts/pm/, scripts/docs-audit/). dispatch-gates.mjs printing "absent from this tree" is the tell. → instance of a zero needs a positive control.
• A code-block extraction by name pattern returned 0 lines on both sides, so a byte-comparison reported "identical" while measuring nothing. → same rule.
• list_issues treats labels as OR, not AND → already [finding] mcp__github__list_issues treats labels as OR, not AND — any seat computing "pm:queue ∩ domain:X" from one query gets an inflated count that looks plausible #11559.
• GraphQL-backed MCP writes are quota-blocked while REST writes succeed → already [Decision] The shared GitHub identity's GraphQL quota is being burned to 2× — MCP writes go through GraphQL, so seats are silently write-blocked while reads keep working #11742, with tonight's reproduction posted there.

Related

• [finding] The os-dev never-park clause LANDED and still does not hold — 3 of 5 devs ended a turn parked in one round at concurrency 5, all three on a shared-lock/long-suite wait #11463 — the parking finding this generalises (full analysis in its latest comment).
• review-checklist: add the git-first spot-check row, paid by in-place compression #11987 — the compression idiom.
• [Decision] AGENTS.md is at its line ceiling with ZERO headroom, so any honest repair of the published spellings mirror crosses it — how should the 8 lines be paid? #11910 — the open ceiling decision in the same family.

[os-trump]

Triage: re-routed domain:devx → domain:skills per the lane table — the landing site is AGENTS.md, an instruction-architecture file, and the card's own cost analysis is about the skill-line ratchet. finding kept: the skills seat self-triages its lane's findings. Two notes carried in for that seat: ① #12077 (turbo cache shared across worktrees) was routed to this lane in the same round and also wants an AGENTS.md line beside the stash rule — with headroom at 0, the two are natural fold candidates for one compression-paid edit; ② the card's own escalation clause stands — if compression cannot pay, it converts to needs-user-decision on the ceiling family together with the open #11910 rather than raising quietly.

---

Generated by Claude Code

[os-steve]

Skills-lane self-triage: finding → promoted pm:queue, folded with #12077 as one compression-paid AGENTS.md edit (chain head to be named at claim time; the five fold gates get answered in that claim). The ordering rule as proposed — the trigger is "before anything that is not the next edit", not "before you wait" — with the card's own rationale kept: the population that most needs it is the one working hardest. ⚠️ Both constraints stand as filed: AGENTS.md is at ceiling (headroom 0), payment is in-place compression with each cut verified to survive somewhere; if compression cannot pay, this converts to needs-user-decision on the ceiling family TOGETHER with open #11910 (the implementing dev reads #11910 first, per triage's carried note) rather than raising quietly.

---

Generated by Claude Code

[os-steve]

Claim: PM loop round R1 W2 — family dispatch chain head (members: this card + #12077)
Session: session_01JANH3y7qe3MD8aLaLXci8N
Branch: claude/issue-12024-agents-doctrine-pair (shared, named by this chain head)
Worktree: objectstack-issue-12024
Domain: domain:skills
File surface: AGENTS.md only (stop on breach; explain in the report)
Container & model: S+S folded, mode:subagent, model: claude-opus-5 — this round's node scripts/pm/dispatch-gates.mjs --tier AGENTS.md (fresh tree c026b0d2): "no path-derived mandate … the tier stays the PM's per-card judgment call"; compression-paid doctrine writing = judgment tier, compensated by this seat's fable-tier skill-face review
Clause-②: no — internal doctrine text
Fold-or-serial answered — the five gates: ① same defect form (a measured container fact missing from AGENTS.md doctrine) and same fix form (one doctrine line each, paid by in-place compression); ② same file, one worktree, one changeset-free PR, one queue slot; ③ both members graded by this seat this round (both pm:queue); ④ independently verifiable — each member has its own named line and its own acceptance reading (WIP-commit ordering rule present for #12024; cache-sharing carve-out beside the stash rule for #12077); ⑤ exclusion list — #12204 (os-dev.md ablation clause, different file), #12188/#12341 (os-dev/verify-lock family), and #11910 is NOT a member: it is the open ceiling-family decision the dev must READ FIRST — if compression cannot pay, this dispatch converts to needs-user-decision alongside it rather than raising the ceiling.
Serial constraints cleared: zero open PRs touch AGENTS.md (PR #12386 merged; this seat's three wave-1 PRs hold os-dev.md / pm-dispatch files / check-half-states.mjs — all disjoint). Ratchet live reading THIS round on the fresh tree: AGENTS.md 1158/1158, widest-row pin 1081 — headroom 0 (the card's 1149 figure is stale; ceiling has moved). Premise re-verified on c026b0d2: zero WIP-commit-rule hits (control git stash = 2), all five turbo mentions are build-command/hashing references — no cache carve-out exists.

---

Generated by Claude Code