Skip to content

docs(rfc): work ledger v4 -- Phases 3 and 4 in flight, as actually built - #12882

Merged
iamwhatever merged 1 commit into
mainfrom
docs/rfc-work-ledger-v4
Sep 23, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
docs/rfc-work-ledger-v4

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

1. What is the problem?

docs/request-for-change/rfc-conductor-work-ledger.md describes Phase 3 (the wake
gate) 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__.py
build still 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:

  • The document names four actionable events (done, blocked, question and
    request) and gives request its own exit criterion. The store has no
    request event kind at all: EVENT_KINDS is create, bind, report,
    decision, verdict, close. There is nothing to fire on.
  • The document requires that "an unreadable ledger fires rather than going quiet,
    pinning fail-open". The probe instead answers FALLBACK and leaves the driver
    the timer it already had.
  • The Design section says the fingerprint is "the newest event id per open
    item". 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 bare status: partial rots silently. If
those 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 request event kind, and a reader who believes Phase 3 already fires
on request will not notice Phase 5 owns it. A reader who believes an unreadable
ledger 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:

  • Phase 3 gets (in flight, #12781) and an as-built block: the probe kind
    work-ledger registered beside gh-pr with build keeping its branch rather
    than 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-accepted or closed; and a cap of
    twelve wakes per item per hour past which a wake folds into the next delivered
    one.
  • Phase 4 gets (in flight, #12792) and an as-built block: /crew-board over
    a masked GET /api/crew-board in three bands (ruling, working, finished,
    with terminal winning over outstanding), the bind event's text emptied because
    the key is its text, and POST /api/crew-board/action scoped to orphaned items
    with the worker key resolved server-side and never returned.
  • The two decisions review keeps re-opening are recorded so each round stops
    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_IMPORTERS entries are a human's edit by design.
  • The one-call arm is named as a follow-up PR. The watch field, 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.md is cross-referenced for the division it states: a typed
    probe 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.py exits 0 with zero FAIL blocks, and neither changed file
    appears in its baseline.
  • Every premise was read at cc385211d8 (current main) or at the PR head it
    describes. EVENT_KINDS has no request kind; WAKE_STATUSES is
    {done, blocked, question} and WORKER_EVENT_KINDS is {report};
    MAX_WAKES_PER_ITEM_PER_HOUR is 12; build on main still maps one kind;
    ledger_entry.py is still shipped; the pipeline and security conductors still
    call _conductor_mcp_servers(config) with no work argument and the security
    installer still states @kirocrew-work is deliberately not mounted.
  • Re-verified after the rebase onto cc385211d8, because both described PR heads
    had moved. feat: wake a conductor from its work ledger instead of a timer #12781 advanced to c749aff0d4, a test-only change, so every
    mechanic in its as-built block still holds and its guard is still red with the
    allowlist naming only dashboard/handlers/work_ledger.py and ledger_sweep.py.
    feat: crew page work-item board over a masked work-ledger projection #12792 advanced to f0287a4a50 with a substantive CrewBoardPage.tsx change, so
    each Phase 4 claim was re-read there: the masked GET /api/crew-board?conductor=KEY
    projection, the three bands ruling / working / finished with finished
    collapsed behind an expander, take_over refusing 501 for want of a
    server-side re-own primitive, and stop going through session_control.
    is_stale is on main in work_ledger.py with the worker-not-running term inside
    it, and session_ledger.py exists on main so the relative link resolves.
  • The "deliberately red" guard is not an inference. The failing check on feat: wake a conductor from its work ledger instead of a timer #12781 is
    test/test_work_ledger.py::test_only_the_phase_2_seams_import_the_module, and
    its assertion names exactly ['ledger_wake.py', 'probes/work_ledger.py'].
  • Both new modules were confirmed to import the store directly, which is what trips
    that guard.
  • Two claims in the first revision of this PR were wrong and a reviewer caught them.
    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 is
    for item in items with no filter, and CLOSED_KEY is "all-closed". Both
    originated 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-pr stays the scalar 8842. An earlier draft of this revision set it to
[8842, 12735]. Every one of the directory's RFCs uses a scalar there and the
README 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 it
here 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 open
PRs 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-prs is unchanged for the same reason, since #12781 and #12792
have not landed.

audited-at: cc385211d8 covers the v4 material, not a re-audit of all 1040
lines.
The Summary now says which head each part was read at, and the index row's
older dd0dce2643 is left on the Phase 1/2/2.5 claims that were verified there
rather 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 what
counts, and says not to trust it on this document's last-audited date alone. The
alternative 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 id per 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, but docs_lint.py hard-fails on a line citation in prose, so
this document names symbols instead. The two rules contradict each other and the
gate wins; worth reconciling in the README rather than per-PR.

@chenmingwei23
chenmingwei23 requested review from a team and cixuuz September 22, 2026 18:20
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of f9189f77ae322b752553e11aad6bd485e7d421e7 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- docs/request-for-change/rfc-conductor-work-ledger.md:29 -- "outstanding band is the rendering of Phase 3's actionable set" is false because only unanswered question reports enter that band -> Fix: describe it as the unanswered-question subset.
FINDING -- docs/request-for-change/rfc-conductor-work-ledger.md:733 -- "both still learn ... by reading transcript tails" misstates the security conductor, which reads its ledgers -> Fix: distinguish the conductors’ reporting mechanisms here and in Q10.
FINDING -- docs/request-for-change/rfc-conductor-work-ledger.md:837 -- "without spending a turn on every failed read" contradicts FALLBACK, which fires the existing timer turn -> Fix: state that each failed-read tick preserves the timer turn.
FINDING -- docs/request-for-change/rfc-conductor-work-ledger.md:898 -- "button ships disabled" contradicts the conditional rendering, which omits Take over when unavailable -> Fix: say the control is hidden and its unavailability appears once as text.
[GPT-REVIEWED] f9189f7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f9189f77ae322b752553e11aad6bd485e7d421e7: <one-sentence reason>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 22, 2026
@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed f9189f77ae322b752553e11aad6bd485e7d421e7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f9189f7

Verdict parsed from the review's SHA-scoped output markers for commit f9189f77ae322b752553e11aad6bd485e7d421e7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable f9189f77ae322b752553e11aad6bd485e7d421e7: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of f9189f77ae322b752553e11aad6bd485e7d421e7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

@chenmingwei23
chenmingwei23 force-pushed the docs/rfc-work-ledger-v4 branch from 194b070 to 3db6ac4 Compare September 22, 2026 20:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
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.
@chenmingwei23
chenmingwei23 force-pushed the docs/rfc-work-ledger-v4 branch from 3db6ac4 to f9189f7 Compare September 22, 2026 22:12
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 22, 2026
@iamwhatever
iamwhatever merged commit ed28e94 into main Sep 23, 2026
93 checks passed
@iamwhatever
iamwhatever deleted the docs/rfc-work-ledger-v4 branch September 23, 2026 00:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…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.
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.

2 participants