Skip to content

docs(rfc): the work-ledger cache keeps every record, and the create check reads open items - #19437

Closed
akushonkamen wants to merge 1 commit into
kirodotdev:mainfrom
akushonkamen:fix/19406-cache-decision-rfc
Closed

akushonkamen wants to merge 1 commit into
kirodotdev:mainfrom
akushonkamen:fix/19406-cache-decision-rfc

Conversation

@akushonkamen

Copy link
Copy Markdown
Contributor

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-closed requires 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 every it_*.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:302 and :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

  • No code change. Nothing in src/, test/ or website/ 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.
  • Not editing the accepted rfc-work-fold-forget-closed.md. Per this repo's convention (same pattern as rfc-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.
  • Not deciding for the maintainer. The document lands as 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):

  • The cache keeps every record the writer minted, for the board's whole life; the work fold 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.
  • The "cache keeps the same set the fold keeps" invariant is retired and replaced: the fold keeps a bounded subset of the cache, and in exchange the store takes on one stated requirement the invariant was implicitly paying for — _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.
  • Option 2 (trim past the window) is recorded with its comparison table and its unsolved problem — where a trimmed closed item's worker history goes — plus three questions for the maintainer, so the decision is a real choice rather than a formality.
  • What this supersedes in the accepted document is named, not rewritten: the cache-parity paragraph of its §4.2 and the trim cell of its §5 change table are retired wherever this document holds, and the rebuild's forgotten-record rules become permanent behaviour rather than a transitional allowance.

docs/request-for-change/README.md gains the index row (main-side reading verified at c4c51aac5) and the one revision-history sentence the file's revision paragraph shape requires. Front matter carries last-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:

$ timeout 300 python scripts/docs_lint.py
All documentation checks passed        # exit 0; 441 markdown files scanned, no finding names the new document
$ timeout 570 /tmp/kc19406-venv/bin/python -m pytest test/ -k work_ledger -q
645 passed, 2 skipped, 0 failed        # 142.94s; 3 collection errors are unrelated modules (test_ci_ipv6_routing,
                                       # test_ci_kernel_owner_routing, test_transcribe) missing coverage/imageio_ffmpeg
                                       # in the temporary venv, same as baseline
$ timeout 300 /tmp/kc19406-venv/bin/python -m pytest test/test_docs_lint_fact_checks.py -q -n0
98 passed                              # exit 0

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.md it 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

  • At most two commits (one is the norm), with a Conventional Commits title (docs(rfc): ... — one commit)
  • Existing tests pass and new tests added for new functionality (documentation gates run above; no code path changes, and no new test by design — the repo deliberately does not pin RFC prose)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) (this PR is the documentation)
  • No secrets, credentials, or internal references in the diff

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.

…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.
@akushonkamen
akushonkamen requested review from a team and KiroCrewCaptain as code owners October 12, 2026 13:29
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Oct 12, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 60f857e33186cafc1f518248fe10de17f63cead1 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 60f857e33186cafc1f518248fe10de17f63cead1 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

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 .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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 60f857e

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No 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 work_ledger.py §5 cell. §6 then says "only the §5 trim cell of the forget-closed RFC dies". That leaves two rows of the accepted forget-closed §5 table in force, and both contradict this document: the ledger_sweep.py row ("optional per-item trim of old closed records") conflicts with "Nothing trims it", and the _create_item backpressure row ("unchanged") conflicts with the new O(open items) bound. A reader of both accepted documents cannot tell which rule wins → Fix: In §1 and §6, also name the ledger_sweep.py trim row and the _create_item backpressure row as amended, and remove the word "only" from §6.

[OPUS-REVIEWED] 60f857e

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 12, 2026

@cruisercohen cruisercohen 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 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.

  1. rfc-work-cache-keeps-history.md lines 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.md line 17 now reads Status: 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_items still reads every record on each create; and a trim or an open-count index is the follow-up "if that cost shows up".

  2. 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.

  3. 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.

  4. docs/request-for-change/README.md line 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 to accepted, 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_items in work_ledger.py (line 1056) globs and parses every it_*.json.
  • _create_item counts open items off that full listing (line 2183).
  • MAX_ITEMS_PER_CONDUCTOR is 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.

@bolichen97

Copy link
Copy Markdown
Contributor

#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.

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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

work-ledger: cache keeps every record, the accepted RFC says trim past the window

3 participants