Skip to content

fix(work-ledger): count only open items toward the per-conductor cap - #13879

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
ash663:ledger-item-cap-open-only
Sep 29, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
ash663:ledger-item-cap-open-only

Conversation

@ash663

@ash663 ash663 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A conductor that has closed its items can keep dispatching new ones -- the per-conductor cap bounds live fan-out, not the conductor's lifetime -- while the board's stored record count stays bounded.

kiro_crew/work_ledger.py caps a conductor at MAX_ITEMS_PER_CONDUCTOR = 32 items, and _create_item counts every record list_work_items returns, closed ones included:

existing = list_work_items(slot_key)
if len(existing) >= MAX_ITEMS_PER_CONDUCTOR:
    raise WorkLedgerError(..., code=CODE_ITEM_CAP_EXCEEDED, field="items")

A long-lived queue conductor that mints one item per ticket and closes each as it lands (about a hundred per oncall shift) hits item_cap_exceeded within a day, even though almost every item behind the refusal is already accepted / rejected / abandoned and nothing is live.

Why it matters

The cap exists to bound live fan-out (the RFC lists it under "Unbounded growth"). Counted this way it instead bounds a conductor's lifetime: once it has closed 32 items it can never dispatch again, so every conductor that runs a queue rather than a one-shot goal is dead after its first day, and the only way out is deleting its own history. The refusal also names the wrong thing -- "conductor holds 32 items" -- when the conductor holds none open.

Not a goal

  • An archive or eviction design for closed items: no items-archive/, no closed/ subdirectory, no ring buffer, no automatic deletion. Closed records stay on the board until the operator retires the finished ledger with kirocrew ledger-sweep --purge.
  • Raising the open cap (32), or making either bound configurable.
  • Open-only counting anywhere beyond _create_item's cap check: list_work_items, read_work_item, the census, the purge and every other reader keep returning and counting closed items as they do today.
  • Any change to the crew log's work fold -- its item ceiling, its omitted accounting, FOLD_STATE_VERSION -- or to the crew_log_incomplete rebuild guard beyond stating that it is now defensive.
  • A schema bump for the conductor header: the new counter field defaults to 0 and old headers load unchanged.

What changed (motivation → approach → change)

Symptom: create refused with item_cap_exceeded on a conductor with zero open items. Root cause: the cap compares against len(list_work_items(...)), and list_work_items (deliberately) returns every readable record regardless of state, so closed items occupy seats forever. Change: two bounds, both checked under the conductor lock.

Open cap (32, MAX_ITEMS_PER_CONDUCTOR). _create_item counts only items whose state is not in TERMINAL_ITEM_STATES (work_vocab.WORK_ITEM_STATES is open plus the three terminal states), read off list_work_items, since only a readable record has a state. Closed items stay on disk, are still returned by list_work_items, still readable by read_work_item / read_work_brief, still counted by the purge census; no reader or layout changes. Two approaches were on the table:

  • count only open items (chosen) -- one filter at the check site; still evaluated under the conductor lock, so two concurrent creates cannot both see 31 open;
  • move closed items to a closed/ subdirectory that list_work_items also reads -- rejected as the larger blast radius: item_path, item_lock, the events path, bindings, census_items and purge_conductor all derive paths from the flat items/ directory and would each need a second location.

The refusal message says open items.

Stored bound (256, MAX_STORED_ITEMS_PER_CONDUCTOR) as a monotonic create counter. With closed items staying on the board, the open cap alone would leave the board's total record count with no bound at all (AutoSDE a-bound-bounds-every-field-it-retains). So _create_item also refuses, BEFORE the open-cap check, when the board has created MAX_STORED_ITEMS_PER_CONDUCTOR items over its life: code item_store_full (409, in the exhaustive store-code map and the RFC's error table), field: "items", a message naming the create count, the bound and the remedy -- kirocrew ledger-sweep --purge once every item is closed, which removes the finished ledger whole. The bound is measured against a new header field, ConductorRecord.created_total (default 0, no schema bump), and NOT against the files under items/: the crew log's fold counts creates in an append-only log, so a record removed from the cache -- torn, hand-deleted, lost, or removed per the cache_dirty remedy -- still has its create there, and a file count would admit one create more than the fold retains for every record it lost. Under the conductor lock _create_item re-reads the header (_header_under_lock), seeds a zero counter once from the it_*.json stems the board holds (a header from before the field -- a backfill that can only over-count the log, never under), refuses at the bound, and otherwise bumps the counter and writes the header in the same hold as the item record: header first, so a failure between the two leaves the counter ahead of the board and never behind it, with the header put back when the item write raises; every refusal, the item's own size ceiling included (_require_record_fits, factored out of _commit_item_locked so the create can run it early), is decided before the header write, so a refused create leaves every file byte-identical. Deleting a record reclaims nothing. _stored_item_ids stays as the rebuild's lock roster and the one-time seed. Nothing evicts a record; the board is a queue the operator retires, not a ring buffer.

A torn header refuses instead of standing the snapshot in. _header_under_lock refuses both conductor writers when the header is present but unreadable under the lock (no_ledger, the code the same header reads as everywhere else in the module -- corruption reads as absent -- with a message naming the torn header and rebuild_from_projection as the remedy). The pre-lock snapshot was read before every writer that held the lock since, so writing it back would put a lower create count into the header the next create reads (for a goal) or into the bound itself (for a create), and admit creates past what the fold retains.

The rebuild sets the counter from the record. rebuild_from_projection writes the rebuilt header with created_total equal to the records the rebuilt board holds -- every item the fold retained plus every legacy record kept (a legacy item's first recorded mutation materialises it in the fold, where it takes a slot). The fold's omitted is deliberately not added: past the ceiling guard the fold dropped no create, and a non-zero omitted there counts entries that are not this board's creates (stragglers of a purged board, parked lines), which would refuse creates a board has room for. The header write moves after the item pass, since that is where the legacy set is known; the whole rebuild is snapshotted and restored on failure as before.

The fold's ceiling is the same number, by construction. The crew log's work fold keeps a board's first WORK_ITEM_LIMIT items and counts every later create in omitted (projection._work_step). WORK_ITEM_LIMIT and MAX_STORED_ITEMS_PER_CONDUCTOR both read work_vocab.WORK_STORED_ITEM_LIMIT (256) -- the leaf the store and the fold already share, because the fold may not import the store and the store may not load the crew log's storage subsystem on the boot path. Every create the store admits is one recorded create and the counter never goes down under the store's own writes, so a board the writer admits cannot overflow the fold: the fold is always the whole board and omitted stays 0. rebuild_from_projection still refuses a full fold that reports omissions (crew_log_incomplete) before the dirty-cache shortcut that trusts the fold over the cache -- only such a fold is necessarily a prefix of the board -- but with the two bounds equal that guard is defensive, not the working path, and the write/rebuild deadlock the design lanes described past 256 lifetime creates cannot arise: the 257th create is refused at the store instead of being recorded past the fold's ceiling. A full fold that omitted nothing is the whole board and rebuilds. No fold state changed (a stored-state change would move FOLD_STATE_VERSION).

Docs. src/kiro_crew/docs/work-ledger.md (Limits) states both bounds, describes the counter (record deletion does not reclaim capacity; an unreadable header refuses a create; a rebuild sets the counter from the record) and points a full board at "Cleaning up finished ledgers"; its ratchet test pins both numbers off the store's constants. The RFC's cap sentence, its rebuild paragraph, its error table and its "Unbounded growth" paragraph state both bounds and the counter, so "A ledger cannot grow without bound" is true as written. WORK_ITEM_LIMIT's comment, WORK_STORED_ITEM_LIMIT's, MAX_ITEMS_PER_CONDUCTOR's, MAX_STORED_ITEMS_PER_CONDUCTOR's, ConductorRecord.created_total's and _create_item's docstring state the relationship.

Backwards compatibility

Compatible for every board under 256 creates: every create that succeeded before still succeeds (the open count only shrinks the counted set); item_cap_exceeded, its field and the exception type are unchanged; no record layout or reader changes. The conductor header gains one field, created_total; a header without it loads as 0 and the first create on such a board seeds it from the records the board holds, so an existing board's bound starts where the board stands. Observable changes, all intended: a create that used to be refused because of closed items now succeeds; a create on a board that has created 256 items is refused with the new code item_store_full (409) whether or not its record files are all still present; a conductor goal or create that finds the header present but unreadable under the lock is refused with no_ledger and a message naming the torn header, where it used to rewrite the header from the pre-lock snapshot; a rebuild of a board whose fold is at its 256-item ceiling AND reports omissions is refused instead of rewriting a prefix; a rebuilt header's counter is the record's count, not the cache's.

Tests

test/test_work_ledger.py

  • test_the_item_cap_refuses_the_thirty_third_item (existing) -- 32 open items still refuse the 33rd, bytes untouched.
  • test_closed_items_do_not_count_toward_the_item_cap[accepted | rejected | abandoned] -- 32 open, close one in each terminal state, the 33rd create lands; refusal text names the open count.
  • test_closed_items_stay_on_disk_listed_and_readable_past_the_cap -- closed items past the open cap are still listed by list_work_items, readable by read_work_item, counted by the census.
  • test_the_stored_bound_refuses_a_create_on_a_board_of_closed_items -- a board that created MAX_STORED_ITEMS_PER_CONDUCTOR items, every one closed (zero open), refuses the next create with item_store_full, field == "items", the message naming the create count, the bound and kirocrew ledger-sweep --purge; every file under items/ unchanged; every closed record still listed and readable; the header's counter at the bound. The bound is patched small the way the projection tests patch WORK_ITEM_LIMIT; the number is pinned separately.
  • test_the_stored_bound_counts_a_record_the_listing_cannot_read -- a full board with one record torn to { (listed one short, zero open) is refused with item_store_full, items/ byte-identical.
  • test_removing_a_record_does_not_reclaim_stored_capacity -- a full board with one record file and its event log deleted (listed one short, _stored_item_ids one short) is refused with item_store_full, the message saying removing a record reclaims nothing, every remaining file under items/ byte-identical, the header bytes unchanged and created_total still at the bound.
  • test_a_header_from_before_the_counter_is_seeded_from_its_records_once -- a header with the field removed and two records loads as 0; the next create seeds it from the two records and bumps it to 3; with four records and the field removed again, the create at the bound is refused on the seed and writes nothing.
  • test_a_torn_but_present_header_refuses_both_writers_under_the_lock -- with a readable pre-lock snapshot and the header then torn, _create_item and _write_goal both refuse with no_ledger, the message says the header is present but unreadable and names the rebuild, the torn bytes are untouched and no record is minted.
  • test_the_stored_bound_is_checked_before_the_open_cap -- at both bounds at once the refusal is item_store_full.
  • test_the_stored_bound_is_the_folds_item_ceiling -- MAX_STORED_ITEMS_PER_CONDUCTOR == projection.WORK_ITEM_LIMIT == work_vocab.WORK_STORED_ITEM_LIMIT, and the open cap is below it.
  • test_caps_hold_their_rfc_values (existing) -- MAX_ITEMS_PER_CONDUCTOR == 32, MAX_STORED_ITEMS_PER_CONDUCTOR == 256.
  • test_a_record_lands_at_the_size_the_ceiling_measured (existing, adjusted) -- compares each record path against its last write, since the create rewrites the header after the bootstrap wrote it.

test/test_work_ledger_tools.py

  • test_every_store_code_maps_to_the_status_the_rfc_tabulates (existing, exhaustive over CODE_*) -- item_store_full: 409.
  • test_item_store_full_is_409 -- through the record route: a board of closed records at the bound answers 409 item_store_full.

test/test_work_ledger_projection.py

  • test_a_fold_at_its_item_ceiling_refuses_the_rebuild_even_on_a_dirty_cache -- a fold holding WORK_ITEM_LIMIT items with omitted = 1, a live board with a newer item flagged dirty: the rebuild raises crew_log_incomplete, every byte under items/ is unchanged, the newer item is still readable, the fold's item is not materialised, the dirty flag stands.
  • test_a_full_fold_that_omitted_nothing_is_the_whole_board_and_rebuilds -- exactly WORK_ITEM_LIMIT items and omitted == 0 rebuilds.
  • test_a_rebuild_sets_the_create_counter_to_what_the_record_holds -- a fold of one item with omitted = 3 (stragglers, not creates) rebuilt over a cache header holding 7 and then 0 leaves created_total == 1 both times; the rebuilt counter drives the next create (refused at a bound of 1, lands at 2 and bumps to 2).
  • test_items_from_before_the_projection_survive_a_rebuild (existing, extended) -- the rebuilt counter equals the fold's items plus the kept legacy records.
  • test_a_rebuild_that_fails_part_way_leaves_the_cache_as_it_was (existing, comment adjusted) -- the header write now follows the item writes; the undo still restores every byte.

test/test_work_ledger_doc.py -- the ratchet pins "32 open items per conductor" and "256 items stored per conductor in total" in the shipped page, both read off the constants.

Run on 6836d91a3: scripts/check_black_formatting.py, scripts/check_subprocess_encoding.py and scripts/check_comment_history.py (against upstream/main) pass; black --check, isort --check-only and flake8 clean on the touched files; mypy on the touched modules -> no issues; pytest over test_work_ledger.py test_work_ledger_doc.py test_work_ledger_tools.py test_work_ledger_projection.py test_mcp_work.py test_ledger_sweep.py test_error_code_contract.py test_crew_log_projection.py test_conductor_agent.py test_ledger_conductor_agent.py test_worker_agent.py test_crew_log_crew_emitter.py -> 879 passed, 0 failed; test_crew_log_emit.py test_crew_log_crew_types.py test_doctor_deprecated_agents.py test_docs_lint_fact_checks.py -> 445 passed; the seven other files that touch the store (test_cron_locking_regression.py test_deploy_lock_truncate.py test_hooks_json_shared_file.py test_pid_lifecycle.py test_pipeline_conductor_agent.py test_remove_slot_for_history_key.py test_session_control_owner_dm.py) -> 709 passed; scripts/docs_lint.py clean.

Manual verification

N/A -- unit coverage sufficient: the new tests drive the real store on disk through apply_conductor_action (create / close), which is the same call path the work_ledger_record MCP tool takes, and the 409 mappings of both codes are covered through the record route in test_work_ledger_tools.py.

Related Issues

None.

Pattern harvest

Rule candidate: review-prompt
Pattern: a resource cap enforced by counting every stored record, terminal ones included, instead of the live set it exists to bound -- the cap then measures history and refuses work once enough of it has finished. Its pair: narrowing such a cap to the live set without a second bound on the stored total, which removes the only bound the retained records had. A third: bounding a value the log counts monotonically (creates) by counting a cache that can shrink (files), so that losing or deleting a cached record reopens capacity the log has already spent.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) -- src/kiro_crew/docs/work-ledger.md, docs/request-for-change/rfc-conductor-work-ledger.md
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@dwu96

dwu96 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

1 similar comment
@dwu96

dwu96 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@ash663
ash663 marked this pull request as ready for review September 25, 2026 17:30
@ash663
ash663 requested review from a team and smeyffret September 25, 2026 17:30
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 25, 2026
@ash663

ash663 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

Round 1: Comment History Gate flagged src/kiro_crew/work_ledger.py:1766 ("no longer" on an added comment line); reworded in present tense in e67e7ae64. Await Fast Gate and Coverage Gate on b7c8b3da7 were downstream of that failure (Fast Gate concluded failure -> heavy matrix skipped -> coverage-combine skipped, failing closed), and PR Hygiene ran before the body carried the ## Pattern harvest section it now has; all three re-run on the new head.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings (all downgraded on adjudication)

Reviewed 89be90a5388ccb0e7eaba30fe8bfd1aa27588564 via the fork AI-review pipeline; updated in place on each push.

Opus 5 adjudication downgraded every blocking finding to advisory. Adjudication downgraded all 1 blocking finding(s) to advisory: the remedy each one requires is disproportionate to the harm it prevents. Read them as advice, not as merge conditions.

Review details

BLOCKING -- src/kiro_crew/work_ledger.py:1863 -- Legacy boards can under-seed the stored-item bound
live.created_total = len(_stored_item_ids(slot_key))
Lost recorded cache item -> file-count seed understates logged creates -> a later create overflows the fold and permanently makes rebuild return crew_log_incomplete.
Anchor: a-bound-bounds-every-field-it-retains
Fix: Seed legacy counts from the crew-log fold, or require a rebuild before creating.
[BLOCK-MERGE-DOWNGRADED] 89be90a
[GPT-REVIEWED] 89be90a

Adjudication (Opus 5) — is blocking on each finding proportionate?

HARM: LOW — a board-scoped, loudly-reported loss of one repair capability; no write occurs and no data is lost when it fires.

Conditions confirmed in this run: a header predating the counter reads created_total=0 (src/kiro_crew/work_ledger.py:334), the backfill seeds from the items/ directory listing rather than the log (work_ledger.py:954, work_ledger.py:1863), and the permanent refusal is the fold-ceiling guard at work_ledger.py:2891 — which additionally requires the fold to be FULL, i.e. ~256 lifetime creates on that one board after the lost record, on top of an out-of-band record deletion this module never performs. Recovery/visibility: the guard raises before _rebuild_locked writes anything, so the cache is preserved byte-for-byte; the only caller is the operator-initiated route src/kiro_crew/dashboard/handlers/work_ledger.py:1489, which returns an audited 409 naming the code (:1495-1496); the board keeps reading and, being at its stored bound, its documented exit is kirocrew ledger-sweep --purge (src/kiro_crew/ledger_sweep.py:854).

REMEDY COST: both fixes the author would ship are large and permanent. "Seed from the fold" puts a crew-log projection read on the create path under the conductor lock — the very import work_ledger.py:2696-2704 defers because a pinned boot-path invariant forbids loading the crew-log storage subsystem, and reading the fold requires the 5s crew_log_emit.flush at work_ledger.py:2716 — making a create depend on the crew log being on and readable and serializing the board behind a flush. "Require a rebuild before creating" refuses creates on every board already in the field until an operator runs a rebuild that itself needs the crew log enabled. Either way a permanent mechanism serving one legacy path, priced above a loud, cache-preserving refusal on an end-of-life board.

[ADJUDICATION] 89be90a total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/work_ledger.py:1863 reason=disproportionate-remedy
[GPT-ADJUDICATED] 89be90a

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 89be90a5388ccb0e7eaba30fe8bfd1aa27588564 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The lifetime wall reappears at 256: the PR's own queue conductor hits item_store_full within days, remedied only by a history-destroying operator purge.

Watch

  • The motivation says a queue conductor closing ~100 items per shift "can keep dispatching"; with MAX_STORED_ITEMS_PER_CONDUCTOR = 256 monotonic and nothing evicting ("Deleting a record reclaims nothing"), that same conductor is refused again in ~2–3 shifts, and the only reset is kirocrew ledger-sweep --purge, which removes the whole ledger and its closed history. The trade is stated in "Not a goal," but the residual wall is close enough to the original harm that a human should accept the purge cadence as the operating model for long-lived queues.
    Clears when: a maintainer confirms the 256-lifetime-creates + whole-ledger purge model is the intended operating model for queue conductors (or names the follow-up archive/eviction design).
  • test_a_torn_but_present_header_is_repaired_from_the_snapshot_not_refused pinned the opposite behavior ("the write repairs the header, as the store always did") and is rewritten to refuse both writers. The PR supersedes that decision for a stated cause (the snapshot would write a stale created_total back and admit creates past the fold), so it is reasoned, not a gap — but a crash-torn header now bricks the conductor's write path until an explicit rebuild_from_projection instead of self-healing on the next write.
    Clears when: a human reviewer explicitly signs off on trading torn-header self-repair for refusal-with-rebuild-remedy.

[DESIGN-REVIEWED] 89be90a

Description read

[DESCRIPTION-READ] 6de757462d6eb3d661c04a380e9b98584331b5ed8a1e871f4885aea0461a3dd6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 89be90a5388ccb0e7eaba30fe8bfd1aa27588564 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The rebuild's fold-ceiling refusal is new code framed as pre-existing — "still refuses a full fold that reports omissions" — and it can seal a board against rebuild forever.

Not justified as shipped

  • Item 7 — rides along: the description says rebuild_from_projection "still refuses a full fold that reports omissions" and Not-a-goal promises no change "beyond stating that it is now defensive", but base rebuild_from_projection has no fold-ceiling guard (grepped omitted in work_ledger.py: 0 hits outside comments; the diff adds the whole len(fold_items) >= WORK_ITEM_LIMIT block). The new refusal fires on a full board with any straggler or parked line in omitted — the fold IS whole there, yet the board becomes permanently unrebuildable, and the reader was told nothing changed.
    Clears when: the description declares the guard as added by this change and names that residual, or the guard is deleted.

What this change ships

Inventory (10 items) — 9 justified

Intent: FIX — a conductor that closes its items can keep dispatching; the 32-cap counted closed history and killed queue conductors in a day (added test fails on base).

  1. Closing an item frees its cap seat; the conductor keeps dispatching — justified
  2. Cap refusal now names the open count ("open items") — justified
  3. New 256-creates-per-conductor bound, item_store_full (409) naming the purge remedy — justified
  4. New persisted header counter created_total; deleting a record reclaims no capacity — justified
  5. A torn-but-present header now refuses both writers instead of self-repairing from the snapshot (reversed pin, declared, grounded in the counter the snapshot would clobber) — justified
  6. Rebuild sets the counter from the record, not the cached header — justified
  7. Rebuild newly refuses a fold at its ceiling that reports omissions — rides along: added guard framed as pre-existing ("still refuses")
  8. Shared WORK_STORED_ITEM_LIMIT (256) in work_vocab; fold ceiling and store bound read it (2 consumers) — justified
  9. Rebuild header write moved after the item pass (failure ordering flips) — justified
  10. Dashboard maps item_store_full to 409 — justified

[FIRST-PRINCIPLES-REVIEWED] 89be90a

Description read

[DESCRIPTION-READ] ca8d7f6d9f190dc8f8ef4fd147b1c66080e492f0e006dcb130b7b9d1d985d911

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 25, 2026
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 89be90a5388ccb0e7eaba30fe8bfd1aa27588564 via the fork AI-review pipeline; updated in place on each push.

Review details

No blocking findings.

FINDING — src/kiro_crew/work_ledger.py:2891 — the new ceiling guard reads omitted > 0 as proof the fold dropped creates, but _work_step also bumps omitted for a straggler worker entry from an earlier board under the same slot (if data.get("actor") != "conductor": ... state["omitted"] += 1) and for undrained parked entries — so after the documented lifecycle (board fills to 256 → ledger-sweep --purge → new board on the same slot, whose purged workers' units still join the fold via work_slots_naming_board), a second board that reaches the 256 create bound folds to len(fold_items) == WORK_ITEM_LIMIT with omitted >= 1 and rebuild_from_projection refuses crew_log_incomplete forever on a complete record; the guard runs before the dirty-cache shortcut, so a dirty board is then wedged (every write 409 cache_dirty, the named cure refusing) — the exact deadlock the comment at _refuse_fold_behind_cache was written to remove → Fix: gate on a count that means "creates dropped" (compare the fold's create count against the header's created_total) rather than on omitted, which the PR's own _rebuild_locked comment already says "counts entries that are not this board's creates".

FINDING — src/kiro_crew/work_ledger.py:1872 — the item_store_full refusal states "once every item is closed, kirocrew ledger-sweep --purge removes the finished ledger whole", but ledger_sweep._scan_work_ledgers keeps a board on a second condition the string omits (if age < older_than_days: kept += 1, DEFAULT_OLDER_THAN_DAYS = 30, age being the newest of the close/header-mtime/items-write readings), so a board refused the moment it closes its last item and purged by the command as named removes nothing for 30 days → Fix: name both conditions and the --older-than-days flag in the message (and in the constant's docstring at line 189, which repeats it).

[OPUS-REVIEWED] 89be90a

@ash663

ash663 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

Round 2 reply, applied in ccefe4e63 on this branch. History note: the branch was squashed to ONE commit (b7c8b3da7 + e67e7ae64 + the round-2 fix -> ccefe4e63, tree identical to the three-commit head) because PR Hygiene's Enforce commit count allows at most two; lane comments naming e67e7ae64 refer to the earlier revision of this same change.

GPT 5.6 F1 — work_ledger.py:1768 terminal items bypass the retained-item count bound (and the same point from Design Review and First Principles). Right: counting only open items left a live conductor's closed history with no bound, and the RFC's "Unbounded growth" sentence records the 32 as a total-growth bound. This head adds the missing half: MAX_CLOSED_ITEMS_PER_CONDUCTOR = 32. When a create admits another item, _prune_closed_items_locked drops the oldest-closed records past that number from the cache, under the conductor lock, each under its own item lock taken non-blocking the way _hold_every_item_lock takes it (a record another writer holds this instant is left for the next create); the lock file goes in the hold where the OS allows it and after release where it does not. So a board holds at most 32 open + 32 closed items, plus whatever closed since its last create (≤ 32). The crew log keeps every pruned item — only the cache forgets it; a worker still bound to one reads unknown_item; a rebuild that re-materialises them is bounded again by the next create. Why 32: symmetric with the open cap, on the RFC's own oldest-dropped model (200 events per item). Tests: test_a_create_drops_the_oldest_closed_item_past_the_retention_bound (33 closed → the oldest close's .json/.jsonl/.lock gone, 32 kept byte-identical, pruned names it, closing alone never prunes), test_a_closed_item_under_a_live_writer_is_left_for_the_next_create, the caps pin and the doc ratchet (src/kiro_crew/docs/work-ledger.md now names both bounds).

Design Review — create latency / listing payload. Bounded by the same change: list_work_items under the create reads at most 64 records plus the transient closes.

First Principles — the RFC text. Not edited: the RFC is the record of the decision; the shipped doc (work-ledger.md) is the page that states the live limits, and it now states both.

Backend Lint & Type Check (3.12) on e67e7ae64 — not our code. Job 108204268023: the black step (Check formatting (black, baselined)) ran 18:47:26Z–18:59:30Z and was killed with exit 143 (SIGTERM) before the gate printed a result; the job's 25-min budget was not reached. The same step died the same way in the same hour on #13878's head (job 108208094143) and on four unrelated PRs (e.g. job 108210651501 on feat/cron-project-dir; runs 36176089561, 36176063571, 36175788953). The black ratchet, isort, flake8 and mypy pass locally on this head.

@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from ccefe4e to d37fc55 Compare September 25, 2026 20:29
@ash663

ash663 commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

Round 3 reply, applied in d37fc555f on this branch (one squashed commit; the tree is identical to e67e7ae64, the revision before pruning was added).

GPT 5.6 F1 — work_ledger.py:1844 pruning permanently deletes unrecorded legacy items and Opus 5 F1 — :1787 the prune runs before the commit and outside the write's undo snapshot. Both right, and both are reasons this PR must not delete anything. The retention step is removed entirely: no MAX_CLOSED_ITEMS_PER_CONDUCTOR, no _prune_closed_items_locked, no unlink of any record, apply_conductor_action's "a refused call leaves every file byte-identical" contract and snapshot_for_write's "touch only the files named here" contract hold as before. The PR is again exactly "the cap counts open items only".

Opus 5 F2 — :1828 closed-items sort compares offset-bearing stamps lexically. Moot: no sort over closed items remains in this change.

Design Review / First Principles — no bound on retained history. Conceded as a real gap, and deliberately out of this PR's scope: bounding retention has to be NON-destructive — an archive move of closed records the way the operator-side archiver already does it (items older than a window moved to a sibling directory plus an index, nothing unlinked) — and it has to be inside the create's undo contract, which touches snapshot_for_write, the rebuild's legacy-item preservation and the fold's completeness check. That is a follow-up, not a rider on the cap fix. The description's scope paragraph now says so, and the RFC's "Unbounded growth" line keeps its 32 unchanged; this change narrows what the 32 counts.

Backend Lint & Type Check (3.12). Green on ccefe4e63 (job 108227130492, 21 min). The red on the earlier head e67e7ae64 was the black step killed with exit 143 (SIGTERM) before it printed a result (job 108204268023; the same kill hit #13878's 4040b3c37, job 108208094143, and e.g. feat/cron-project-dir, job 108210651501, in the same hour), not a formatting result. This tree is byte-identical to e67e7ae64 apart from the squash; black ratchet, isort, flake8 and mypy pass locally.

@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from d37fc55 to a291887 Compare September 25, 2026 21:30
@ash663

ash663 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

Round 4 reply, applied in a29188735 on this branch (one squashed commit replacing d37fc555f, for PR Hygiene's commit-count rule).

GPT 5.6 F1 — work_ledger.py:1768 terminal records escape every retained-item count bound (adjudication upheld). Right, and now bounded without deleting anything: MAX_TERMINAL_ITEMS_PER_CONDUCTOR (256, beside the open cap). After a create has committed, the oldest closed records past that number are MOVED from items/ into items-archive/ under the same conductor directory — record and event log renamed byte-identical on the same filesystem, one JSON line per move appended to items-archive/index.jsonl (id, title, state, closed_at, archived_at). Ordering is by parsed closed_at then parsed created_at (offset-aware instants, the way census_items reads stamps — never a string compare). Open items are never moved; a closed record whose stamp does not parse, or that the listing cannot read, is left in place and not counted. Each move takes the item lock non-blocking (the purge's rule) and leaves a held record for the next create. Every board reader globs items/ only, so the archive is out of sight but on disk; the ledger purge removes it with the directory. The step runs after the commit, so a refused create moves nothing and apply_conductor_action's byte-identical-on-refusal contract holds. Tests: test_a_create_moves_the_oldest_closed_items_past_the_bound_into_the_archive (bound patched to 3: files identical in the archive, lock gone, index line shape pinned, read_work_item/read_work_brief None, listing and census see the board only), test_open_items_and_unparseable_closes_are_never_archived, test_a_closed_item_under_a_live_writer_is_left_for_the_next_create, test_a_refused_create_moves_nothing, and the caps pin.

Opus 5 F1 — :1769 the board can outgrow the fold's 256-item ceiling, breaking work_ledger_rebuild and, on a dirty cache, unlinking the newest items. Right, and the more important finding of the round: projection._work_step keeps a board's first WORK_ITEM_LIMIT items and omits later creates, and its comment assumed the writer capped a board far lower. Reinstating a total lifetime cap would put the queue-conductor wall back at 256, so instead rebuild_from_projection now refuses a fold that is at its ceiling (crew_log_incomplete, "a board that minted more than the fold retains cannot be rebuilt from the record — keep the cache as it stands") before the dirty-cache shortcut could let _rebuild_locked unlink what the fold never held. Test test_work_ledger_projection.py::test_a_fold_at_its_item_ceiling_refuses_the_rebuild_even_on_a_dirty_cache (WORK_ITEM_LIMIT patched to 1, a full fold, a newer live item, the dirty flag set: refused, items/ byte-identical, flag left for the operator). The WORK_ITEM_LIMIT comment now states the relationship. No fold state changed (a stored-state change would move FOLD_STATE_VERSION), so no savepoint is retired.

Opus 5 finding — the RFC's cap sentences. Updated: line 301 and the "Unbounded growth" line now name the open cap, the 256 closed-items board bound and the archive, and say what bounds the archive (the ledger's own retention: the sweep removes the directory with a finished ledger).

Design / First Principles — growth bound. Addressed by the above: items/ is bounded at 32 open + 256 closed plus what closed since the last create; the archive holds the rest byte-identical.

Gates on a29188735: black ratchet, subprocess-encoding, comment-history, isort, flake8, mypy pass; 874 tests across the ledger, projection, sweep, agent and emitter files pass.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from a291887 to 451437e Compare September 25, 2026 22:34
@ash663

ash663 commented Sep 25, 2026

Copy link
Copy Markdown
Contributor Author

Round 5 reply, applied in 451437e4a on this branch (one squashed commit replacing a29188735, for PR Hygiene's commit-count rule).

GPT 5.6 F1 — work_ledger.py:1823 archive moves survive a refused create. Right: the move ran inside _create_item after the store commit but before the route's crew-log confirmation, so an unrecorded create was undone while its moves stayed. The archive is now a separate store entry point, archive_closed_items(slot_key), which the write route calls only AFTER on_work_recorded landed for a create (it re-takes the conductor lock and re-reads the board). _create_item moves nothing, so a refused create and an undone create both leave every file where it was — apply_conductor_action's byte-identical-on-refusal contract and snapshot_for_write's footprint contract hold unchanged. The route reports the moved ids (archived) in the payload and the audit row. Tests: test_a_refused_or_bare_create_moves_nothing (store) and test_work_ledger_projection.py::test_an_unrecorded_create_moves_no_closed_item_and_a_landed_one_archives (route: on_work_recorded → False gives 503 crew_log_unrecorded with records byte-identical and no archive; → True gives 200 with archived naming the oldest close).

GPT 5.6 F2 — :1897 partial archive rename corrupts an item. Right. The move is now ordered so no crash or refused rename can leave a split nothing revisits: the EVENT LOG is renamed first, the RECORD second, both os.replace on one filesystem (the two directories are checked to share a device first; a split mount moves nothing), and the index.jsonl line is appended only after both renames. Every reader finds an item by its record in items/, so a record is never absent while its events are still on the board; a crash between the renames leaves the record listed with its events archived (read_events answers empty, nothing lost) and the next pass completes the move because the record still selects it. A record rename that fails (a reader holding the file on Windows) renames the events back; if even that fails the pass stops, leaving the item exactly as the next pass will finish it. Tests with os.replace monkeypatched to fail on the first / second call: test_a_failed_events_rename_moves_nothing, test_a_failed_record_rename_puts_the_events_back_and_indexes_nothing (record byte-identical, listed, events readable, no index line, no archived copy), and test_a_record_left_on_the_board_with_archived_events_is_finished_by_the_next_pass.

Gates on 451437e4a: black ratchet, subprocess-encoding, comment-history, isort, flake8, mypy pass; 878 tests across the ledger, projection, sweep, agent and emitter files pass.

@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from 451437e to cdc0bd0 Compare September 25, 2026 23:18
@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Round 9 reply, applied in 25d9d568d on this branch (one squashed commit replacing 1cf2e4b2c, for PR Hygiene's commit-count rule). Retention decision taken as Opus 5 proposed: a second, cheap bound in _create_item, no archive, no new subsystem.

Opus 5 BLOCKING — work_ledger.py:1770 the open-only cap leaves a board's stored item count with no bound and GPT 5.6 F1 — :1771 closed records bypass every retained-item bound (adjudication upheld, a-bound-bounds-every-field-it-retains). Right, and fixed the way Opus's note says: MAX_STORED_ITEMS_PER_CONDUCTOR (256) beside the open cap, and _create_item refuses over the full len(list_work_items(slot_key)) BEFORE the open-items check -- new code item_store_full (409, in the exhaustive store-code map and the RFC's error table), field: "items", a message naming the stored count, the bound and the remedy (kirocrew ledger-sweep --purge once every item is closed removes the finished ledger whole). Nothing evicts a record. MAX_ITEMS_PER_CONDUCTOR (32) governs live fan-out; a board holds at most 32 open and 256 records in total, so work_ledger_read, the create's own listing and the rebuild's per-item fds are all bounded again. Tests: test_the_stored_bound_refuses_a_create_on_a_board_of_closed_items (a board of closed records at the bound, zero open: refused with item_store_full, items/ byte-identical, message names count / bound / remedy, every closed record still listed and readable), test_the_stored_bound_is_checked_before_the_open_cap, test_work_ledger_tools.py::test_item_store_full_is_409 (through the record route), the caps pin (== 256) and the exhaustive code->status map.

GPT 5.6 F2 — :2771 a pruned overflow is mistaken for a complete fold (fenced, upheld) and Opus 5 FINDING — :2770 the ceiling guard seals a dirty cache past 256 lifetime items (and the Design Review's deadlock). Both removed by construction rather than by more guard logic: the stored bound IS the fold's ceiling. MAX_STORED_ITEMS_PER_CONDUCTOR and projection.WORK_ITEM_LIMIT both read one value, work_vocab.WORK_STORED_ITEM_LIMIT (the leaf the store and the fold already share, since neither may import the other). Every stored item is one recorded create, so a board the writer admits can never overflow the fold: the fold is always the whole board, omitted stays 0, and a surviving 256-item fold with omitted == 0 after a unit deletion IS the complete board -- there is no post-ceiling create for a deleted unit to have held, because the 257th create was refused at the store. The deadlock has the same answer: a board cannot reach the state where the write path 409s cache_dirty and the rebuild 409s crew_log_incomplete, because no recorded board exceeds 256 items. The >= WORK_ITEM_LIMIT and omitted > 0 guard stays as a defensive check -- a full fold whose omitted counts a straggler or parked entry, the create of a record the listing skips as torn (the one way the store can admit a create the fold cannot hold), or records written past the bound by something other than this module -- refusing in the safe direction: the cache stands. Its comment says so. Test: test_the_stored_bound_is_the_folds_item_ceiling pins MAX_STORED_ITEMS_PER_CONDUCTOR == projection.WORK_ITEM_LIMIT == WORK_STORED_ITEM_LIMIT with the open cap below it; the two existing ceiling tests (omitted = 1 refuses on a dirty cache and touches nothing; omitted == 0 rebuilds) still pass.

GPT 5.6 finding — projection.py:3353 "a fold that is full is therefore a prefix" contradicts the permitted full fold with omitted == 0. Right; the WORK_ITEM_LIMIT comment now says only a full fold that reports omissions is necessarily a prefix of the board, states both bounds (32 open, 256 stored == this ceiling) and their relationship, and calls the rebuild guard defensive.

Design Review / First Principles item 3 — the RFC's "Unbounded growth" paragraph asserts a bound the diff removed. The paragraph, the RFC's cap sentence and the shipped doc's Limits paragraph now state both bounds: 32 open items and 256 stored per conductor in total, closed items staying on the board until that stored bound, a board at it refusing further creates and reclaimed whole by the ledger sweep. "A ledger cannot grow without bound" is true as written. The doc ratchet (test_the_doc_quotes_the_real_caps) pins both numbers off the store's constants.

First Principles item 7 / Design Review "phantom description" — the orphan items-archive test header and the archive paragraph in the description. The header line in test/test_work_ledger.py is deleted (the stored-bound tests sit where it stood); the description's rebuild-guard paragraph describing archive moves is gone, as is the "does NOT bound closed items / maintainer decision requested" text. The description now describes exactly the shipped diff: two bounds, one number shared with the fold, no archive.

Gates on 25d9d568d: black ratchet, subprocess-encoding, comment-history, isort, flake8, mypy pass; 875 tests across the ledger, doc, tools, projection, MCP work, sweep, error-code contract, agent and emitter files pass, plus 445 across the emitter boot-path, crew-types, doctor and docs-lint files; docs_lint.py clean.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from 25d9d56 to db932d2 Compare September 28, 2026 19:24
@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Round 10 reply, applied in db932d2ad on this branch (one squashed commit replacing 25d9d568d, for PR Hygiene's commit-count rule). Fixed exactly as the adjudication says: the stored bound counts record filenames, the open cap keeps the readable listing. The description is unchanged.

GPT 5.6 BLOCKING — work_ledger.py:1789 unreadable records bypass the stored-item cap (adjudication upheld, a-bound-bounds-every-field-it-retains). Right: list_work_items skips a torn record, one whose stored id names another item, and a plain read error, so len(list_work_items(slot_key)) counted readable records rather than records, and 256 files with one torn one counted 255, admitted a 257th create and its crew-log entry, and the fold then exceeded its ceiling with omitted > 0 -- at which point the rebuild's ceiling guard refuses that board unconditionally, before _refuse_fold_behind_cache, and removing the torn file does not clear it because the fold still carries the extra create. Fixed with the glob the rebuild already spelled: a new _stored_item_ids(slot_key) returns the stem of every it_*.json under items/ whose stem is a full it_<8 hex> id, whether or not the record reads (a stray it_bad.json is still excluded, as in the listing -- it was never minted and has no create in the fold), and both _create_item and rebuild_from_projection (which enumerated the same files to take their locks) call it. _create_item now reads stored = _stored_item_ids(slot_key) for the MAX_STORED_ITEMS_PER_CONDUCTOR refusal and list_work_items(slot_key) for the MAX_ITEMS_PER_CONDUCTOR one, since only a readable record has a state. So a torn record counts toward the stored bound and not toward the open cap, the fold's "every stored item is one recorded create" invariant holds for every record on the board rather than every readable one, and the construction argument from round 9 (stored bound == fold ceiling, so omitted stays 0 and the guard is defensive) is true again. No new state, no new ordering, no cross-module change. The constants comment, the _create_item docstring, the create-site comments and the ceiling guard's comment say which count reads what; the guard's list of what can still trip it drops "the create of a record the listing skips as torn" (that case is now counted at the store) and names the one remaining store-side undercount instead: a record removed from the board by hand. Test: test_the_stored_bound_counts_a_record_the_listing_cannot_read -- a board of MAX_STORED_ITEMS_PER_CONDUCTOR record files (bound patched to 4, as the sibling tests do), every item closed, one record then overwritten with {: the listing is one short and shows zero open items, and the next create is refused with item_store_full, field: "items", the message naming the stored count, and every file under items/ byte-identical before and after. The round-9 tests (test_the_stored_bound_refuses_a_create_on_a_board_of_closed_items, test_the_stored_bound_is_checked_before_the_open_cap, test_the_stored_bound_is_the_folds_item_ceiling, test_item_store_full_is_409) and the two ceiling-guard tests still pass; test_a_malformed_item_filename_is_skipped_not_raised pins that a foreign stem still counts toward neither bound.

Docs. The shipped Limits paragraph and the RFC's cap sentence and Unbounded-growth paragraph now say the stored bound is counted off the item records on the board, a torn one included, rather than off the readable listing; the doc ratchet (test_the_doc_quotes_the_real_caps) still pins both numbers. The item_store_full message never said "readable" or "listed" and is unchanged.

Gates on db932d2ad: black ratchet, subprocess-encoding, comment-history (against main), isort, flake8, mypy pass; 806 tests across the ledger, doc, tools, projection, MCP work, sweep, error-code contract, worker/conductor agent and emitter files pass, plus 677 across the emitter boot-path, crew-types, doctor and docs-lint files; docs_lint.py clean.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from db932d2 to 6836d91 Compare September 28, 2026 22:42
@ash663

ash663 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Round 11 reply, applied in 6836d91a3 on this branch (one squashed commit replacing db932d2ad, for PR Hygiene's commit-count rule). This round changes the design of the stored bound rather than what it counts: the bound is a monotonic per-board create counter kept in the conductor header, so the file-count vs log-count divergence the finding names cannot arise from any record going missing. The description's ## What changed describes the counter; every template heading, **Goal:** and ## Not a goal are as they were.

GPT 5.6 BLOCKING — work_ledger.py:1817 lost cache records reopen capacity beyond the fold ceiling (adjudication upheld, residual/crash-data-loss-corruption). Right: _stored_item_ids counted the it_*.json files under items/, the fold counts creates in an append-only log, and the two diverge the moment a record leaves the cache while its create stays in the log -- which is exactly what the module's own cache_dirty remedy tells an operator to do. 256 recorded closed creates, one record removed, the store counts 255, admits and records a 257th, the fold omits it, and the ceiling guard refuses that board's rebuild for good. Fixed by not counting files at all. ConductorRecord gains created_total: int = 0 (default, no schema bump; a header without the field loads as 0). _create_item re-reads the header under the conductor lock (_header_under_lock), seeds a zero counter once from the it_*.json stems the board holds -- the backfill for a header from before the field, which can only over-count the log, never under -- refuses item_store_full when created_total >= MAX_STORED_ITEMS_PER_CONDUCTOR (still the same work_vocab.WORK_STORED_ITEM_LIMIT the fold reads), and otherwise bumps the counter and writes the header in the same hold that writes the item record. Header first, item second: a failure between the two leaves the counter one ahead of the board, a create the fold never sees, and the header is put back when the item write raises; the other order would let a failed header write leave an item the counter never saw, which is the side that overflows the fold. Every refusal, the item's own size ceiling included (_require_record_fits, factored out of _commit_item_locked so the create can run it before the header write), is decided before the first write, so a refused create still leaves every file byte-identical. Why deleting a record file no longer moves the bound: nothing in the store lowers created_total -- a create bumps it, a refusal leaves it, mark_goal_recorded and goal carry it through -- so the counter tracks the log's creates, not the directory's contents, and a record removed by hand, torn, lost or removed per the cache_dirty remedy keeps the create it counted exactly as the log keeps that create's entry. The open cap is unchanged: it still reads list_work_items, since only a readable record has a state. _stored_item_ids stays as the rebuild's lock roster and the one-time seed; the rebuild guard's comment names what can still trip it (a full fold whose omitted counts stragglers or parked lines, or a header something other than this module wrote with a count below its creates). Test: test_removing_a_record_does_not_reclaim_stored_capacity -- a board of MAX_STORED_ITEMS_PER_CONDUCTOR creates (bound patched to 4, as the sibling tests do), every item closed, one record file and its event log deleted: _stored_item_ids and the listing are both one short, the next create is refused with item_store_full, the message says removing a record reclaims nothing, every remaining file under items/ is byte-identical, the header bytes are unchanged and created_total is still at the bound. test_a_header_from_before_the_counter_is_seeded_from_its_records_once pins the backfill: a header with the field removed and two records loads as 0, the next create seeds it to 2 and bumps it to 3, and with four records and the field removed again the create at the bound is refused on the seed and writes nothing. The round-10 test (test_the_stored_bound_counts_a_record_the_listing_cannot_read) keeps its scenario -- a torn record on a full board -- and is refused on the counter now; its docstring says so.

The torn-header case. _header_under_lock used to return the caller's pre-lock snapshot when the header was present but did not parse under the lock, and the write proceeded on that account. With the counter in the header that is a hole of the same class: the snapshot was read before every writer that held the lock since, so a create that trusted it would compare against a count it may hold low, and a goal that repaired the header from it would write that lower count into the header the next create then reads. Both writers refuse instead: no_ledger (the code the same header reads as everywhere else in the module -- corruption reads as absent -- and what apply_conductor_action would have answered for the same file a moment earlier), with a message that says the header is present but unreadable, that it holds the board's create count, and that a rebuild from the crew log is the remedy, since the rebuild writes the header from the record. The pre-lock record is written back by neither writer (the create still takes its depth check from it, before the lock). Test: test_a_torn_but_present_header_refuses_both_writers_under_the_lock (replacing the snapshot-repair test) -- a readable pre-lock snapshot, the header then overwritten with {tor: _create_item and _write_goal both raise no_ledger naming the torn header and the rebuild, the torn bytes are untouched, and no items/ directory exists afterwards.

The rebuild sets the counter from the record. rebuild_from_projection writes the rebuilt header with created_total = len(kept) + len(legacy): every item the fold retained plus every legacy record the rebuild keeps (a legacy item's first recorded mutation carries it as a baseline, which takes a fold slot). The fold's omitted is deliberately not added, and this is the one place the round's brief was read against the code rather than followed verbatim: the rebuild only reaches that write past the ceiling guard, which has already refused any full fold reporting omissions, so in every rebuild that runs the fold dropped no create and its retained count IS the log's create count -- while a non-zero omitted on a fold that is not full comes from the other increment sites the adjudication enumerates (generationless stragglers of a purged board, worker stragglers, id-less entries, duplicate creates, parked lines), none of which is a create this board admitted, and adding them would have a reused slot refuse creates it has room for. The header write moves after the item pass, where the legacy set is known; the rebuild's footprint snapshot already covered the header, so a failure part way still restores every byte (test_a_rebuild_that_fails_part_way_leaves_the_cache_as_it_was, comment adjusted). Tests: test_a_rebuild_sets_the_create_counter_to_what_the_record_holds -- a fold of one item with omitted = 3 rebuilt over a cache header holding 7 and then 0 leaves created_total == 1 both times, and the rebuilt counter is live (refused at a bound of 1, lands at a bound of 2 and bumps to 2); test_items_from_before_the_projection_survive_a_rebuild now also asserts the counter equals the fold's items plus the kept legacy records.

Docs. The shipped Limits paragraph, the RFC's cap sentence, its rebuild paragraph and its Unbounded-growth paragraph state that the stored bound is a monotonic per-conductor create counter in the header, that record deletion does not reclaim capacity, that an unreadable header refuses a create, and that a rebuild sets the counter from the record; present tense throughout. WORK_ITEM_LIMIT's and WORK_STORED_ITEM_LIMIT's comments say the writer counts creates the way the fold does. The item_store_full message names the create count ("has created N items over its life") rather than a stored count, and says removing a record reclaims nothing; the tests that quoted the old wording quote the new one. test_a_record_lands_at_the_size_the_ceiling_measured compares each record path against its last write, since the create rewrites the header the bootstrap wrote.

Gates on 6836d91a3: black ratchet, subprocess-encoding, comment-history (against upstream/main), isort, flake8, mypy pass; 879 tests across the ledger, doc, tools, projection, MCP work, sweep, error-code contract, crew-log projection, worker/conductor agent and emitter files pass, plus 445 across the emitter boot-path, crew-types, doctor and docs-lint files and 709 across the other seven files that touch the store; docs_lint.py clean.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
MAX_ITEMS_PER_CONDUCTOR (32) bounds live fan-out, which is the only thing a
per-conductor item cap is for. _create_item counts the OPEN items: an item
in a terminal state (accepted, rejected, abandoned) stays on the board,
listed and readable, and does not count. A queue conductor that mints one
item per ticket and closes each as it lands otherwise exhausts the cap on
its own history within a day, with nothing live behind the refusal. The
open count comes from list_work_items, since only a readable record has a
state; a torn record does not count there. The refusal names the open
count.

A second bound keeps the board's STORED total finite once closed items stay:
MAX_STORED_ITEMS_PER_CONDUCTOR (256) bounds the creates a board admits over
its life, open and closed together, and _create_item refuses past it with
item_store_full (409) before the open-cap check, naming the create count,
the bound and the remedy (kirocrew ledger-sweep --purge once every item is
closed). Nothing evicts a record. The number is the crew log fold's
per-board ceiling, WORK_ITEM_LIMIT, by construction: both read
work_vocab.WORK_STORED_ITEM_LIMIT, the leaf the store and the fold already
share. Every create the store admits is one recorded create, so a board the
writer admits cannot overflow the fold; the fold is always the whole board,
omitted stays 0, and the rebuild's ceiling guard (a full fold that reports
omissions is refused with crew_log_incomplete) is defensive rather than the
working path. Only a full fold reporting omissions is necessarily a prefix
of the board; the comments say so.

The stored bound is a monotonic counter, not a count of the files in
items/. ConductorRecord gains created_total (default 0, no schema bump):
_create_item re-reads the header under the conductor lock, seeds a zero
counter once from the it_*.json stems the board holds (a header from before
the field), refuses item_store_full at the bound, and otherwise bumps the
counter and writes the header in the same hold as the item record, header
first so a failure between the two leaves the counter ahead of the board
and never behind it (the header is put back when the item write raises;
every refusal, the item's own size included, is decided before the header
write). The fold counts creates in an append-only log, so a record removed
from the cache (torn, hand-deleted, lost, or removed per the cache_dirty
remedy) still has its create there; a file count would admit one create
more than the fold retains for every record it lost, and the ceiling guard
would then refuse that board for good. Deleting a record reclaims nothing.

A header that is present but unreadable under the lock refuses both
conductor writers (no_ledger, the code the same header reads as everywhere
else, with a message naming the torn header and the rebuild as the remedy)
instead of standing the pre-lock snapshot in for it: the snapshot was read
before every writer that held the lock since, so writing it back would put
a lower count into the header a create then reads. rebuild_from_projection
sets created_total to the records the rebuilt board holds, every item the
fold retained plus every legacy record kept; omitted is not added, because
past the ceiling guard the fold dropped no create and a non-zero omitted
there counts entries that are not this board's creates. _stored_item_ids
stays as the rebuild's lock roster and the one-time seed. The item-size
ceiling check moves into _require_record_fits so the create can run it
before the header write.

Docs: the shipped Limits paragraph, the RFC's cap sentence, its rebuild
paragraph and its Unbounded growth paragraph state both bounds (32 open,
256 created in total, a monotonic per-conductor counter in the header that
record deletion does not lower), so the RFC's growth claim holds again.

Tests: each terminal state frees its seat and the 33rd create lands; closed
items past the open cap stay listed and readable; a board of closed records
at the stored bound is refused with item_store_full, bytes untouched, the
message naming count, bound and remedy, the counter at the bound; a full
board with one record torn (listed one short, zero open) is refused and
items/ is byte-identical; a full board with one record and its event log
deleted is refused, items/ byte-identical and the header's counter
unchanged; a header from before the counter is seeded from its records on
the first create and refused at the bound on that seed; a torn header
under the lock refuses both writers with nothing written; a rebuild sets
the counter to the fold's item count whether the cache held more or less
and the rebuilt counter drives the next create; a legacy board's rebuilt
counter covers fold items plus kept legacy records; at both bounds the
stored one speaks first; the stored bound equals the fold's ceiling; the
route maps item_store_full to 409 and the status map stays exhaustive; a
fold at the ceiling with omissions refuses the rebuild on a dirty cache
and touches nothing; a full fold with none rebuilds; the doc ratchet pins
both numbers.
@ash663
ash663 force-pushed the ledger-item-cap-open-only branch from 6836d91 to 89be90a Compare September 29, 2026 01:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 29, 2026
@ash663

ash663 commented Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

@smeyffret @kyleseaman

State: head 89be90a is the round-11 change (the conductor header's created_total counter is the stored bound) rebased onto main -- same patch as 6836d91 (identical patch-id; the only file-level differences are main's own changes to projection.py, the ledger handler and work-ledger.md). Gates so far: CI 83 pass / 0 fail / 3 pending, GPT 5.6 and Opus 5 no blocking findings, PR Hygiene pass.

Pausing further rounds -- what's left are design calls for you, not defects. The Design Review is advisory (CONCERNS) with two items only a human can clear:

  1. Operating model: 256 lifetime creates per conductor, reset only by kirocrew ledger-sweep --purge. Closing or deleting items reclaims nothing, so a queue conductor closing ~100 items per shift is refused item_store_full again after 2-3 shifts and the purge drops its closed history. Recommendation: accept this for the PR and take archive/eviction as a follow-up issue -- the "Not a goal" section already scopes it out, and a bound that never exceeds the fold ceiling is what guarantees the fold is never a prefix.

  2. Torn conductor header under the lock: refuse the create (and the goal write) with the rebuild remedy, instead of repairing it from the pre-lock snapshot. Recommendation: keep the refusal. Self-repair writes a stale created_total back, and the next create trusts it and admits records past the fold ceiling -- the exact failure this round removes.

Also on this head, the GPT 5.6 advisory (comment): legacy boards seed created_total once from the it_*.json count rather than from the crew-log fold. Proposing to leave it, per the adjudication's own reading -- it takes an out-of-band record deletion on a legacy board plus ~256 creates on that same board to matter, nothing is written or lost when it does, and the outcome is an audited 409 -- unless you would rather have the fold seed.

Say which way on 1 and 2 and I'll do the last round, or merge as-is if the recommendations work for you.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 29, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Readiness sweep 2026-09-29 — held pending the author's open question to @smeyffret / @kyleseaman.

Mechanically ready (label, required check, mergeable, no CHANGES_REQUESTED, no open threads). Not merged from the sweep because the author explicitly paused on two design calls: (1) the 256 lifetime-creates ceiling per conductor with no reclaim on close/delete (reset only by ledger-sweep --purge), which Design Review notes re-creates the lifetime wall the PR set out to remove; (2) keeping the torn-header refusal. Whichever way you rule, ping and the sweep will merge the resulting head.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. The open cap counts only non-terminal items under the conductor lock; the stored bound (256) is checked before any write and the header counter is rolled back if the item write raises; old headers load with created_total defaulting to 0. No sandbox/auth/data-deletion touch. Tests cover the cap, the stored bound, unreadable records, the one-time seed, torn header and rebuild guard.

Minor, non-blocking: a header that exists but does not parse used to be repaired from the pre-lock snapshot; now goal/create refuse with no_ledger (ensure_conductor and rebuild still repair it). Worth one line in the description. Also no test pins the header rollback when the item write raises (work_ledger.py ~1912).

@iamwhatever
iamwhatever enabled auto-merge (squash) September 29, 2026 06:30
@iamwhatever
iamwhatever merged commit 49c371f into kirodotdev:main Sep 29, 2026
100 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants