Skip to content

docs(rfc): work ledger caps a goal's open items; its item total is advisory - #19352

Merged
iamwhatever merged 1 commit into
mainfrom
docs/rfc-work-ledger-concurrency-cap
Oct 12, 2026
Merged

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

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the decision that the work ledger bounds a goal by how many items it has open at once, and reports its lifetime total instead of refusing on it.

Today _create_item in src/kiro_crew/work_ledger.py refuses a goal board's create with goal_item_cap_reached once the goal has created item_cap items (20 by default), closed ones and every re-plan counted. A goal whose items land and close quickly is refused with nothing running, and the conductor asks the user about "spend" when nothing is being spent. The user's ruling on the dispatch for #19338: cap parallel work, not lifetime totals; keep the total visible.

The implementation is open as #19338. Its First Principles lane blocks: a changed default for a first-class agent needs a decision recorded on the base branch. This document is that record.

Why it matters

The bound that protects the host and the budget is how many workers run at once: each open item is a live session. A lifetime total stalls a healthy goal on its own history. Without a per-goal bound on parallel work, the only one is the store's 32-open ceiling.

Not a goal

  • Changing any code. This PR adds one RFC and one index row.
  • Changing MAX_ITEMS_PER_CONDUCTOR (32) or the stored bound (256); the latter is rfc-work-fold-forget-closed.md's.
  • Bounding queue boards (pipeline, security conductors) that never record a goal.
  • Making the 6 and 20 defaults configuration.

What changed (motivation → approach → change)

docs/request-for-change/rfc-work-ledger-concurrency-cap.md, status accepted: the problem as the code stands at 0a47021090, what bounds spend, the decision (a new concurrency_cap, default 6, range 1..32, refusing create as goal_concurrency_cap_reached; item_cap kept as an advisory line with cap_exceeded on the read; goal_item_cap_reached removed), what is not decided, the alternatives considered, and how acceptance is recorded. It amends rfc-conductor-work-ledger.md in its own document, so that one is not edited here.

docs/request-for-change/README.md: one index row, accepted, verified against 0a47021090, pointing at #19338.

The status is accepted on landing because the maintainer (iamwhatever) already accepted this design in the conductor chat on 2026-10-12 at about 06:12 UTC: a hard cap on open items, the total cap advisory only. The RFC's status line, its acceptance section and the README row cite that. Merging this PR puts the record on the base; #19338 then rebases onto it.

Backwards compatibility

Compatible: documentation only.

Removes nothing: two documentation files gain text; no code, key or route changes.

Tests

N/A — documentation only. scripts/docs_lint.py and scripts/docs-lint.sh pass locally on this tree.

Manual verification

N/A — the Docs Lint gate reads both files; there is nothing to run.

Related Issues

Records the decision for #19338. Follows #18111 (the refusal this decision moves).

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)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 12, 2026 08:30
@iamwhatever
iamwhatever requested a review from buluoray October 12, 2026 08:30
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Before merge, a maintainer should confirm iamwhatever's acceptance. The RFC lands as accepted on the strength of a conductor-chat ruling that no reviewer can see.

[DESIGN-REVIEWED] e4f330c

Description read

[DESCRIPTION-READ] efb77a7b66eabe3c0ef1323b0a4e95466453e504a6dc21e55143665145a4d4a0

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 Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision e4f330c207b27ab6c7846d5eb702c7763292e7cc 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

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e4f330c

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

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

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e4f330c207b27ab6c7846d5eb702c7763292e7cc and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e4f330c

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

@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 Oct 12, 2026
…visory

Records the decision #19338 implements: a goal board refuses `create` on its
open-item count (`concurrency_cap`, default 6, 1..32,
`goal_concurrency_cap_reached`), and `item_cap` becomes an advisory line the
read reports as `cap_exceeded`. The user's ruling: cap parallel work, not
lifetime totals. Lands as `accepted` with an index row: the maintainer
accepted the design in the conductor chat on 2026-10-12 (~06:12 UTC). #19338
then rebases onto the base that carries it.
@iamwhatever
iamwhatever force-pushed the docs/rfc-work-ledger-concurrency-cap branch from 9b9f2ca to e4f330c Compare October 12, 2026 09:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): RECOMMEND APPROVE

This docs-only PR records the decision that a goal's board is bounded by open items (concurrency_cap, default 6, range 1..32, refusing goal_concurrency_cap_reached). item_cap becomes an advisory cap_exceeded line, and goal_item_cap_reached is removed. The RFC lands first so #19338's First Principles lane can read the decision from the base. I checked the RFC's code claims against origin/main, and they hold: DEFAULT_GOAL_ITEM_CAP = 20, MAX_ITEMS_PER_CONDUCTOR = 32, MAX_GOAL_ITEM_CAP = MAX_STORED_ITEMS_PER_CONDUCTOR, the goal_items_used >= live.item_cap refusal in _create_item, and no existing concurrency_cap. The README index row matches the RFC frontmatter. The alternatives and not-decided sections are scoped well. All lanes are PASS or skipped, and the checks are green. Reviewer note: the RFC lands as accepted on a conductor-chat ruling (2026-10-12 ~06:12 UTC) that no reviewer can see. Design Review flags this too, so the code owner should confirm that acceptance on the PR before merging. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 12, 2026 15:48

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

LGTM. I checked this at head e4f330c.

What it records: a goal is capped on items open at once (default 6) rather than on items created over its lifetime, and the lifetime total becomes advisory. Today a goal whose items finish quickly is refused at 20 even with nothing running, and the conductor then asks about "spend".

Checked:

  • The lifetime cap being moved is your own earlier work (#16987, #17076, #18111), and nothing in docs/decisions/ covers work-ledger caps, so no other maintainer's decision is overridden.
  • rfc-conductor-work-ledger.md is not edited; the new RFC amends its goal_item_cap_reached entry in its own document.
  • Cited symbols are real on main in work_ledger.py: _create_item, MAX_ITEMS_PER_CONDUCTOR = 32, DEFAULT_GOAL_ITEM_CAP = 20, MAX_GOAL_ITEM_CAP, CODE_GOAL_ITEM_CAP_REACHED, CODE_ITEM_CAP_EXCEEDED, ConductorRecord (no concurrency_cap yet), and the "spend is bounded" text in _CONDUCTOR_SYSTEM_PROMPT.
  • The planned check order (stored total, store open bound, then concurrency cap) means a concurrency_cap at its ceiling still yields item_cap_exceeded first, consistent with main's codes.
  • The README row matches. scripts/docs-lint.sh passes. CI at this head: 88 success, 13 skipped, 0 failed.

@iamwhatever
iamwhatever merged commit 6ec1522 into main Oct 12, 2026
103 checks passed
@iamwhatever
iamwhatever deleted the docs/rfc-work-ledger-concurrency-cap branch October 12, 2026 16:10
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants