Repository navigation
docs(rfc): work ledger v4 -- Phases 3 and 4 in flight, as actually built - #12882
Conversation
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- docs/request-for-change/rfc-conductor-work-ledger.md:29 -- False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the "re-audit at merge" pins on Phases 3/4 have an owner once #12781/#12792 land — nothing in the directory enforces that follow-up. [DESIGN-REVIEWED] f9189f7 |
194b070 to
3db6ac4
Compare
Phase 3 (the wake gate) and Phase 4 (the surfaces) are no longer planned work. Each is open on its own branch, so this revision records what the branches contain and keeps the phase list honest about where the code is. Neither phase is on main. Phase 3 is #12781 on feat/work-ledger-wake-gate, still a draft; Phase 4 is #12792 on feat/crew-page-work-items. The phase sections say so rather than claiming shipped behaviour, and the index row names each PR's own head instead of implying main. Two planned exit criteria came out different from the design and the deviation is recorded rather than quietly restated. The actionable set is three statuses, not four: the store has no request event kind, so that half of both the gate and the board waits for Phase 5. An unreadable ledger answers FALLBACK and leaves the driver its existing timer rather than firing, which still forbids reporting a failed read as "nothing changed". Records the two decisions review keeps re-opening on Phase 3. The gate has no configuration switch, asserted as a subtraction because arming is already opt-in and a loop is already stoppable. The two _PERMITTED_STORE_IMPORTERS entries are a human's edit by design: the guard test is red on the branch naming both new importers, and the allowlist's own note says a new seam must argue for itself in review rather than arrive with a passing suite. Records the one-call arm as a follow-up: the watch field, its payload, the applier and the authorization forward land together, and the last link is in autonudge_authz.py, which Phase 3's branch does not touch. Cross-references rfc-wake-judge.md, which carries the complementary half of the withdrawn proposal: a typed probe answers what can be typed and a judge reads only the prose a probe cannot. Phase 3 is the typed side, so its verdicts are the ones a judge may not mint. Every v3 statement is unchanged; a revision adds. doc-pr stays the scalar 8842 the directory convention defines as the PR that merged the document, and the two open PRs stay out of implementation-prs until they land.
3db6ac4 to
f9189f7
Compare
…ilt (kirodotdev#12882) Phase 3 (the wake gate) and Phase 4 (the surfaces) are no longer planned work. Each is open on its own branch, so this revision records what the branches contain and keeps the phase list honest about where the code is. Neither phase is on main. Phase 3 is kirodotdev#12781 on feat/work-ledger-wake-gate, still a draft; Phase 4 is kirodotdev#12792 on feat/crew-page-work-items. The phase sections say so rather than claiming shipped behaviour, and the index row names each PR's own head instead of implying main. Two planned exit criteria came out different from the design and the deviation is recorded rather than quietly restated. The actionable set is three statuses, not four: the store has no request event kind, so that half of both the gate and the board waits for Phase 5. An unreadable ledger answers FALLBACK and leaves the driver its existing timer rather than firing, which still forbids reporting a failed read as "nothing changed". Records the two decisions review keeps re-opening on Phase 3. The gate has no configuration switch, asserted as a subtraction because arming is already opt-in and a loop is already stoppable. The two _PERMITTED_STORE_IMPORTERS entries are a human's edit by design: the guard test is red on the branch naming both new importers, and the allowlist's own note says a new seam must argue for itself in review rather than arrive with a passing suite. Records the one-call arm as a follow-up: the watch field, its payload, the applier and the authorization forward land together, and the last link is in autonudge_authz.py, which Phase 3's branch does not touch. Cross-references rfc-wake-judge.md, which carries the complementary half of the withdrawn proposal: a typed probe answers what can be typed and a judge reads only the prose a probe cannot. Phase 3 is the typed side, so its verdicts are the ones a judge may not mint. Every v3 statement is unchanged; a revision adds. doc-pr stays the scalar 8842 the directory convention defines as the PR that merged the document, and the two open PRs stay out of implementation-prs until they land.
1. What is the problem?
docs/request-for-change/rfc-conductor-work-ledger.mddescribes Phase 3 (the wakegate) and Phase 4 (the Crew page surfaces) as unstarted work, and the directory's
index row says so outright: "Not started: the wake gate (
probes/__init__.pybuildstill maps exactly one kind,gh-pr) ... the Crew page surfaces".Both phases are now being built. Phase 3 is open as
#12781 and Phase 4 as
#12792. Worse than being
merely stale, three of the design's stated details turned out not to match what
the implementation could do, so a reader implementing from this document would
build to a contract the code has already departed from:
done,blocked,questionandrequest) and givesrequestits own exit criterion. The store has norequestevent kind at all:EVENT_KINDSiscreate,bind,report,decision,verdict,close. There is nothing to fire on.pinning fail-open". The probe instead answers
FALLBACKand leaves the driverthe timer it already had.
idper openitem". The probe loops over every item the ledger returns, with no open-item
filter.
2. Why this issue matters to the user
The RFC directory's whole claim on a reader's trust is
last-audited/audited-at, and the README says so: "a barestatus: partialrots silently. Ifthose two fields are far behind main, distrust the status." This document's fields
pointed at a commit from 2026-09-08.
The concrete cost is to whoever picks up the remaining phases. Phase 5 is the one
that adds the
requestevent kind, and a reader who believes Phase 3 already fireson
requestwill not notice Phase 5 owns it. A reader who believes an unreadableledger fires will write a test asserting a wake that the implementation
deliberately does not produce. Both are the kind of error that costs a review round
to discover rather than a read.
3. How our fix solves it
Docs only. Two files, +46/-8, no code touched.
The chain from symptom to cause is that the phase sections were written before the
phases were built, and nothing had re-read them against the branches. So each phase
section now carries what its branch actually contains, and the two mismatches are
recorded as deviations rather than silently restated:
(in flight, #12781)and an as-built block: the probe kindwork-ledgerregistered besidegh-prwithbuildkeeping its branch ratherthan becoming a registry; a fingerprint of the newest event id per open item;
liveness as
work_ledger.is_stale, whose conjunction is inside the function(quiet past the window AND worker not running AND the next move still the
worker's); a terminal outcome keyed
all-acceptedorclosed; and a cap oftwelve wakes per item per hour past which a wake folds into the next delivered
one.
(in flight, #12792)and an as-built block:/crew-boardovera masked
GET /api/crew-boardin three bands (ruling,working,finished,with terminal winning over outstanding), the
bindevent's text emptied becausethe key is its text, and
POST /api/crew-board/actionscoped to orphaned itemswith the worker key resolved server-side and never returned.
re-litigating them. The gate has no configuration switch, asserted as a
subtraction because arming is already opt-in and a loop is already stoppable. The
two
_PERMITTED_STORE_IMPORTERSentries are a human's edit by design.watchfield, its payload,the applier and the authorization forward land together, and the last link is in
autonudge_authz.py, which feat: wake a conductor from its work ledger instead of a timer #12781 does not touch.rfc-wake-judge.mdis cross-referenced for the division it states: a typedprobe answers what can be typed, a judge reads only the prose a probe cannot.
Phase 3 is the typed side, which is why its verdicts are the ones a judge may not
mint.
Every v3 statement is unchanged, because a revision adds. The eight deleted lines
are the four front-matter fields, the two README lines, and the two phase headings
that gained their
(in flight, #N)suffix.4. What tests we did
No code changed, so there is nothing to unit-test. The claims were verified instead,
which is the check that applies to this directory.
scripts/docs_lint.pyexits 0 with zero FAIL blocks, and neither changed fileappears in its baseline.
cc385211d8(current main) or at the PR head itdescribes.
EVENT_KINDShas norequestkind;WAKE_STATUSESis{done, blocked, question}andWORKER_EVENT_KINDSis{report};MAX_WAKES_PER_ITEM_PER_HOURis 12;buildon main still maps one kind;ledger_entry.pyis still shipped; the pipeline and security conductors stillcall
_conductor_mcp_servers(config)with noworkargument and the securityinstaller still states
@kirocrew-workis deliberately not mounted.cc385211d8, because both described PR headshad moved. feat: wake a conductor from its work ledger instead of a timer #12781 advanced to
c749aff0d4, a test-only change, so everymechanic in its as-built block still holds and its guard is still red with the
allowlist naming only
dashboard/handlers/work_ledger.pyandledger_sweep.py.feat: crew page work-item board over a masked work-ledger projection #12792 advanced to
f0287a4a50with a substantiveCrewBoardPage.tsxchange, soeach Phase 4 claim was re-read there: the masked
GET /api/crew-board?conductor=KEYprojection, the three bands
ruling/working/finishedwithfinishedcollapsed behind an expander,
take_overrefusing501for want of aserver-side re-own primitive, and
stopgoing throughsession_control.is_staleis on main inwork_ledger.pywith the worker-not-running term insideit, and
session_ledger.pyexists on main so the relative link resolves.test/test_work_ledger.py::test_only_the_phase_2_seams_import_the_module, andits assertion names exactly
['ledger_wake.py', 'probes/work_ledger.py'].that guard.
The as-built block said the fingerprint was "per open item" and that the terminal
key was
closed. Reading the source settled both against me: the loop isfor item in itemswith no filter, andCLOSED_KEYis"all-closed". Bothoriginated in the brief this PR was written from and were repeated without being
read, which is the error worth naming. The fingerprint scope is now recorded as a
third design-versus-build deviation rather than as a correction to the Design
section, because the Design section's own sentence is a v3 statement and a
revision adds.
5. Any other suggestions on the work
Five judgement calls, flagged rather than buried.
doc-prstays the scalar8842. An earlier draft of this revision set it to[8842, 12735]. Every one of the directory's RFCs uses a scalar there and theREADME annotates the field "the PR that merged this document", so a list breaks
convention; and #12735 merged
rfc-wake-judge.md, not this document, so naming ithere would also be wrong. This PR's own number is likewise absent: the README's
"Keeping this honest" section puts landed work in
implementation-prs, so two openPRs belong in prose, which is where they are. If the directory wants a field for a
revision PR, that is a README change and not this one.
implementation-prsis unchanged for the same reason, since #12781 and #12792have not landed.
audited-at: cc385211d8covers the v4 material, not a re-audit of all 1040lines. The Summary now says which head each part was read at, and the index row's
older
dd0dce2643is left on the Phase 1/2/2.5 claims that were verified thererather than being silently upgraded.
The two as-built blocks are pinned to a head and marked for re-audit at merge.
This is the disposition of Design Review's CONCERNS, which said the blocks describe
two PRs still under review while the document carries the directory's strongest
trust signal, so a design reversed before merge would leave this document asserting
a superseded state with fresher credentials than the truth. The finding is correct
and it is not hypothetical: both heads moved while this revision was in review,
which is how it was caught here. Each block now opens with
valid only at head <sha>; re-audit at merge, states that what merges is whatcounts, and says not to trust it on this document's
last-auditeddate alone. Thealternative the review offered, adding a re-verify task to #12781 and #12792, was
not taken because it writes to two other people's PRs to protect a claim this
document makes; the pin keeps the obligation where the claim is. The same review's
suggestion was also taken: the Design section's "newest event
idper open item"sentence now carries a pointer to the Phase 3 record of that difference, so a reader
working only from that section cannot build the filtered version by accident.
Line citations are omitted deliberately. The README's audit guidance says to
quote
file:line, butdocs_lint.pyhard-fails on a line citation in prose, sothis document names symbols instead. The two rules contradict each other and the
gate wins; worth reconciling in the README rather than per-PR.