Repository navigation
docs(rfc): the work-ledger cache keeps every record, and the create check reads open items - #19437
akushonkamen wants to merge 1 commit into
Conversation
…heck reads open items Resolves the contradiction kirodotdev#19406 raises between the accepted rfc-work-fold-forget-closed and the shipped cache: nothing trims the items directory, so list_work_items reads O(lifetime) records on every create, a cost the 256 lifetime ceiling caps on main and kirodotdev#19068 unbinds. Amends the forget-closed RFC in its own document, per the convention that an accepted RFC is not edited: the cache-parity paragraph of its section 4.2 and the trim cell of its section 5 change table are retired, the rebuild's forgotten-record rules are permanent, and the store takes on a stated per-create bound instead — the open-count check reads O(open items), never lifetime records. The trim alternative and its unsolved worker-history placement are recorded so a maintainer can still pick it; the index implementation rides the open kirodotdev#19068 series. Drafted with AI assistance (Claude); the author can explain every line.
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Check before accepting: §6 has #19068 land "unchanged" before the create-check bound, so removing the ceiling leaves creates at O(lifetime) until the follow-up ships. [DESIGN-REVIEWED] 60f857e Description read[DESCRIPTION-READ] fbc4bb23790a07980a7859f7ed54f4aeed3b6c01871086feda95f3ddbb56f244 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 |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings block this merge. One advisory finding. FINDING — docs/request-for-change/rfc-work-cache-keeps-history.md:63 — The amendment's scope is narrower than what it retires. It names only the §4.2 parity paragraph and the [OPUS-REVIEWED] 60f857e |
cruisercohen
left a comment
There was a problem hiding this comment.
Reviewed on head 60f857e against current main ac8a96a. This review is about factual accuracy only. Which option to take is a maintainer decision, and this review takes no position on it.
Blocking: the document's account of main is out of date now that #19068 has merged (37fcadd, 2026-10-13). Several statements are false on current main, and the branch conflicts with it.
-
rfc-work-cache-keeps-history.mdlines 18-28 (the status block) say four things that are no longer true:- "Nothing is on main."
- The 256-create ceiling (
MAX_STORED_ITEMS_PER_CONDUCTOR) is something "#19068 removes". On main the constant is gone. - The accepted
rfc-work-fold-forget-closed.md§4.2 "requires closed records past the recent-closed window to leave the cache". - The document "lands first" so that #19068 can read it off the base.
On main,
rfc-work-fold-forget-closed.mdline 17 now readsStatus: accepted. Implementation in #19068. Its §4.2 carries an Implementation note (line 128) saying three things: the writer's cache keeps every record and only the fold forgets;list_work_itemsstill reads every record on each create; and a trim or an open-count index is the follow-up "if that cost shows up". -
Lines 44-45 say the forget-closed document "is not edited here; this one records the amendment". The decision that the cache keeps every record is already recorded on main, inside that document's §4.2. What this document still adds beyond main is narrower:
- it makes the rebuild's forgotten-record rules permanent;
- it makes the create-check bound (O(open items)) a required part of the decision, where main's note treats it as an optional follow-up.
§1, §3 and the §7 table should describe the document as a change against that implementation note, not against the parity paragraph alone.
-
Lines 167-171 (§6) are written in future tense ("#19068 lands unchanged", "A follow-up in the #19068 series"). #19068 has merged, and there is no open series to add to.
-
docs/request-for-change/README.mdline 31: the new row says "§4.2 still requires closed records past the recent-closed window to leave the cache", which is false on main. Lines 28 and 31 also conflict with #19068's own edits to that file. #19068 rewrote the forget-closed row toaccepted, with the "cache keeps every record" note. That is why the PR shows CONFLICTING.
These code claims still hold on main and need no change:
list_work_itemsinwork_ledger.py(line 1056) globs and parses everyit_*.json._create_itemcounts open items off that full listing (line 2183).MAX_ITEMS_PER_CONDUCTORis 32.- The lock order is conductor -> item -> binding (module docstring, line 36).
Requested: rebase onto main, re-audit at the current tip (audited-at and last-audited), and restate the status block, §1, §6 and the README row against the merged implementation note.
Unrelated to this diff: the Backend Tests (3.12, 2) red is test_provider_spawn_off_loop_18172 (cancel-during-spawn reap). It should clear on the rebased push.
|
#19068 merged and settled how the work-ledger cache treats closed items, so this proposal no longer matches main. I am closing it for that reason. If you still want the keep-every-record option, please open a new proposal written against current main. |
Problem / Motivation
Goal: put on main the record of the cache decision issue #19406 asks for, so the open work-ledger rebuild series reads a decision off the base branch instead of carrying a contradiction.
The accepted
rfc-work-fold-forget-closedrequires closed records past the recent-closed window to leave the item cache (§4.2,docs/request-for-change/rfc-work-fold-forget-closed.md:122-126; §5 change-table row at:134), and nothing on main trims the items directory:list_work_items(src/kiro_crew/work_ledger.py:1010) globs and parses everyit_*.json, and_create_item's open-count check (src/kiro_crew/work_ledger.py:2072-2074) plus each board listing (src/kiro_crew/dashboard/handlers/work_ledger_board.py:302and:445) read that whole listing, so every create pays O(lifetime records). Today the 256 lifetime-create ceiling (MAX_STORED_ITEMS_PER_CONDUCTOR) hides the cost; #19068 removes the ceiling, and from the moment it lands the cost is unbounded.Why it matters
#19068's rebuild rules are written as if the cache legitimately holds what the fold forgot — they read the decision off the base branch, and no decision is on it. Without one, either the rebuild series lands a contradiction with an accepted RFC, or every PR in the series carries a First Principles BLOCK that only a per-head maintainer override clears. The decision also fixes the store's complexity contract before the ceiling comes off: trim closed records past the window (option 2), or keep everything and state a per-create bound (option 1). One of the two has to be chosen; this document puts the choice where a maintainer can record it.
Not a goal
src/,test/orwebsite/moves here; the open-item index the per-create bound needs is implementation work that rides the open feat(work-ledger): the work fold forgets closed items, so a board never fills #19068 series.rfc-work-fold-forget-closed.md. Per this repo's convention (same pattern asrfc-question-card-auto-submit→rfc-question-card-pager), an accepted RFC is amended in its own document, so the accepted document is not edited and its acceptance does not extend to the amendment.draft,kind: decision, drafted for maintainer decision; it records both options, their comparison and three questions, so the trim alternative stays pickable.What changed (motivation → approach → change)
The symptom is the contradiction #19406 records; the root cause is that the accepted RFC's cache-parity clause was written for a store that trims, and the shipped store never trimmed; the change is one new decision document that resolves it by choosing option 1 and recording why over option 2.
docs/request-for-change/rfc-work-cache-keeps-history.md(kind: decision,status: draft, tracks #19406):workfold stays the bounded projection — open items, the recent-closed window, tombstones, counters. Once the fold forgets a closed item, the cache is the only whole copy of that item's worker history, which is exactly why the trim was cut from feat(work-ledger): the work fold forgets closed items, so a board never fills #19068 in review._create_item's open-count check reads records proportional to the OPEN items, never to lifetime creates. The open-item index is constrained by the total lock order conductor → item → binding; its implementation belongs with the feat(work-ledger): the work fold forgets closed items, so a board never fills #19068 series, not this document.docs/request-for-change/README.mdgains the index row (main-side reading verified atc4c51aac5) and the one revision-history sentence the file's revision paragraph shape requires. Front matter carrieslast-audited: 2026-10-12,audited-at: c4c51aac5.Backwards compatibility
Removes nothing. The diff is two documentation files: one new document and its index row plus revision sentence. No wire contract, route, tool, field, default or public function is rejected, renamed or removed, and no record or row is pruned. The superseded passages of the accepted RFC stay in that document as written, with the new document naming them and holding over them.
Tests
The change is pure decision documentation; the repo deliberately does not pin RFC prose (
test/test_work_ledger_doc.py:15, "Deliberately NOT pinned: the doc's prose..."), so there is no red→green pair to write. The gates that do read the tree were all run on this diff:The full suite was not run; per the work order the environment baseline is the same as recorded here (the three collection errors above predate this diff and live in modules this change does not touch).
Manual verification
Read the new document against each passage of
rfc-work-fold-forget-closed.mdit names (§4.2 lines 122-126, §5 table row line 134) to check every supersede is specific rather than wholesale, and that the amendment's claims about that text match it. Before claiming the issue, a cross-session dedup: the issue timeline held no prior record, and the only colliding open PR (#9115) is an unrelated dashboard fix.Related Issues
Fixes #19406
Checklist
docs(rfc): ...— one commit)AI assistance
Drafted with AI assistance (Claude); the author can explain every line — same disclosure as the commit message and the claim comment on the issue, per CONTRIBUTING's "Using AI Tools": the author remains responsible for the change.