Skip to content

Write the chief-of-staff record with commands and give status one verdict - #182

Merged
sreejithraman merged 10 commits into
mainfrom
feat/coordinator-record-commands
Nov 15, 2026
Merged

sreejithraman merged 10 commits into
mainfrom
feat/coordinator-record-commands

Conversation

@sreejithraman

Copy link
Copy Markdown
Owner

Summary

Chief of Staff now writes its program record with commands instead of hand edits. A new script, skills/chief-of-staff/scripts/record.py, handles each event (report, answer, resolve, start, land, wait, applied). Every event command:

  • stamps the time from the script clock;
  • fills defaults;
  • changes only what the event changes;
  • validates the record;
  • commits with a message naming the event, then renders the page.

A record with uncommitted changes is refused, and the diff is shown. status reads gh and T3, updates state, and gives the program one verdict. --turn-end fails while work could still run. This makes the record deterministic and makes "nothing left to do" checkable.

Command Example
start record.py start --state program.json --work W4 --owner "Search owner" --session t3-thread://… --mode delegated
report record.py report --state program.json --work W1 (reads the JSON block at the top of reports/W1.md, or stdin)
answer record.py answer --state program.json --decision W1-D7 --option 2 --source "user, 14:02 message", or --pasted with a page prompt on stdin
resolve record.py resolve --state program.json --decision W3-D2 --option 1 --basis "AGENTS.md says…; reversible by revert"
applied record.py applied --state program.json --decision W1-D7
land record.py land --state program.json --work W1,W2, then --landing L2 --to submitted / landed / withdrawn --note …
wait record.py wait --state program.json --on "CI on #181" --event "checks finish" --work W1, or --clear
status record.py status --state program.json [--json] [--exit-code] [--turn-end]

Verdict

status prints exactly one verdict, in text and with --json:

runnable  > start-able planned work, ready landings, idle owners owing work,
            answered decisions not yet applied, reversible halting Needs
working   > an owner thread is running
waiting   > lists each wait with its age
done

With --exit-code, the exit codes are done 0, waiting 3, working 4, and runnable 5. A digest changes only when the verdict, its items, or the open rows' state and layer facts change. Timestamps and reader error text do not change it. A heartbeat can compare digests cheaply; the heartbeat itself is PR 2. --turn-end commits nothing. It passes only when the record is clean, the page matches the record, and the verdict is not runnable.

Other changes

  • Owner reports start with a JSON block: outcome, state, layers with heads, proof, asks, waits. Its fields match Implement's report. A field you include replaces the recorded value, a field you leave out keeps it, and an empty list clears it.
  • The renderer wraps ISO times in prose in <time datetime>, so the page shows local times.
  • Each command prints page: behind record <commit> when the published page is behind the record.
  • program-state.md, SKILL.md, decisions.md, hosting.md, and owner-kickoff.md now use the commands. SOURCES.md records the local difference.

Decisions to check

  • Reversible field. I added an optional option field, reversible: true, instead of inferring it from weight: quick plus a recommended option. Quick describes how hard a question is to answer, not whether a choice can be undone. A Need counts as runnable only when:
    • its recommended option is reversible;
    • it halts work at start, access, or proof;
    • every other halting Need on that row is also reversible;
    • no work is provisional on it.
  • Answered vs resolved. answer records the user's choice (needs --source). resolve records the chief's own call (needs --basis). An answer gets applied: false until applied clears it, so an answer that has not been acted on stays runnable. Decisions answered before this change count as applied.
  • Shown Try work. A shown Try row with an open choice Need waits. Without one, it is runnable: a settled choice (merge, changes, or scrap) moves the outcome, so a row still shown owes work.
  • Scrap or rebase answers stay hand-written edits; the docs give the steps.

Evidence

  • python3 scripts/check.py: passed, 108 chief-of-staff tests (52 in test_record.py). The new tests use fake gh and t3 readers and check record diffs path by path. They cover each verdict, the reversible-Need cases (including a second Need that is not reversible), exit codes, digest stability, and the turn-end rules. Before landing, the new tests were run against broken versions of the code, and they failed.
  • End to end: I ran the commands against a copy of example-state in a temp git repo, checking 12 assertions (start, report, answer/resolve, land, wait, dirty refusal, status, turn-end, publish flag, prose times, applied, verdict output). All 12 passed on cbe638e. The repairs since then are covered by unit tests. I called the real gh and T3 readers once, against PR Use any existing asc profile, not only a Keychain one #181 and a live thread, and both outputs parsed. Gap: no real program has run on these commands yet.
  • Review: review-fix-loop ran 7 passes (Primary, Thermo, Ponytail, Adversarial, Additional, then single-reviewer repair passes).

Merge Danger

Two-way door. The change is limited to skills/chief-of-staff/. The schema stays backward compatible: applied and reversible are optional, and existing records validate unchanged. A revert restores hand-written records. After a revert, the old validator rejects the new optional keys: applied on decisions and reversible on options. To roll back a live record, run applied on pending answers and drop any reversible keys.

🤖 Generated with Claude Code

sreejithraman and others added 10 commits November 15, 2026 09:24
Chiefs spent a third of their tool calls hand-editing program.json, guessed
timestamps, and missed idle owners. record.py now records each event
(start, report, answer, resolve, land, wait) with its own clock, refuses an
uncommitted record, validates, commits, and renders. status reads PRs from
gh and owner threads from the T3 CLI and lists what to do now; --turn-end
fails while open work is orphaned or the page is behind the record.

Owner reports open with a JSON block that report reads. The renderer turns
ISO times in prose into time elements the page localizes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
status now applies every forge fact before it validates, so row order no
longer decides which facts stay. A retargeted base resets readiness like a
moved head, and a landing whose PRs merge in separate runs lands. A
released landing no longer covers an idle owner, and turn-end fails on an
uncommitted record. Release refuses a layer stacked on unreleased work.
Pasted choices match labels the page reflows. Report waits are validated.
Scrap-or-rebase answers go through the hand write, and a kept dirty buffer
is checked before it is committed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
status now raises each row toward its forge facts in ID order until nothing
moves, so a rejected change holds back only its own row. A first-recorded
head or base unverifies readiness. A Need covers idle work only when it
halts it or the work waits on it at its stop. Reports cannot record merges
or terminal states; status reads those at the forge. start keeps a
recorded owner's plumbing and refuses another owner without --replace. A
failed commit restores the file, and a failed render says the record
changed. Turn-end guidance matches the code and leaves the page to a new
chief after a move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A report must repeat each merged layer unchanged, so it cannot swap a
merged layer's PR for an open one. When status sees a head or base move
whose facts the rules reject, it still withdraws readiness on the recorded
row, so the chief is not told to release stale work.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
status ends with exactly one verdict: runnable (start, release, idle
owner, an answer not yet applied, or a quick Need whose recommended option
halts unprovisional work), working, waiting (each Need, wait, and blocker
with its age from the record's UTC times), or done. It prints a digest of
those facts without times, --json prints them as one object, and
--exit-code maps the verdicts to 0, 3, 4, and 5. Turn-end also fails while
the verdict is runnable.

Answers now carry applied: false until the new applied command records
that the affected owners have them. The field is optional and omitted
from the page revision, so existing programs keep validating.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A ready layer whose observed status no longer meets its finish line's
readiness, including a closed PR under a live dependent, now loses
readiness even when the facts themselves need a hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Orphaned work is now runnable, so the verdict and turn-end agree. A
reversible Need is one whose recommended option sets the new optional
reversible flag; it counts as runnable only for startable work not
provisional on that exact decision. Waiting wins over done while a wait
remains, a recorded blocker covers an idle owner, and the digest carries
open rows' forge facts but not read-error text. Readiness lapses by the
finish line's rule for drafts too, and the fallback note names the
candidate it kept. Reopen and withdraw drop applied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A row counts as a provisional start only when every Need that halts it
recommends a reversible option. Orphan lines keep a stable reason so the
digest ignores reader error text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sreejithraman
sreejithraman added this pull request to stack #184 November 15, 2026 18:22
@sreejithraman
sreejithraman merged commit f218782 into main Nov 15, 2026
3 checks passed
@sreejithraman
sreejithraman deleted the feat/coordinator-record-commands branch November 15, 2026 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant