Skip to content

feat(work-ledger): enforce the goal's item cap in code - #18111

Merged
iamwhatever merged 1 commit into
mainfrom
fix/work-ledger-goal-item-cap
Oct 9, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/work-ledger-goal-item-cap

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A conductor cannot dispatch more than its goal's item cap (20 by default) unless someone raises the cap, because the work ledger refuses the extra create.

Since #16987 the goal-conductor skill says a goal holds at most 20 items when the user set no budget. Only the prompt says so. The ledger's own cap, MAX_ITEMS_PER_CONDUCTOR, counts OPEN items, so a conductor that closes items as it goes can keep creating them with no limit.

Why it matters

The cap is the spend bound for back-to-back rounds. A model that forgets or miscounts it keeps dispatching workers, and each one costs tokens and host memory. A bound that lives only in prose is not a bound.

Not a goal

  • Changing MAX_ITEMS_PER_CONDUCTOR (open fan-out) or the stored bound (256).
  • Carrying the cap through the crew-log fold. A rebuild keeps the cached cap only when the cache is clean and in step with the log; otherwise it falls back to the default, counted from the board's first create.
  • The no-progress (two rounds, nothing accepted) check. It stays prompt-only.

What changed (motivation → approach → change)

Part Now
Cap each board header stores item_cap, default 20, range 1..256; enforced once the board has recorded a goal
Count creates since the current goal text was set, closed items included
Refusal a create at the cap is refused goal_item_cap_reached (409) and writes nothing
Raise work_ledger_record action=goal item_cap=N
New count only action=goal new_goal=true with the new goal text; rewording, rounds and cap raises keep the count
Rebuild keeps the cap only from a clean cache in step with the log; else cap 20, every create counted

The store change is in src/kiro_crew/work_ledger.py; the field is plumbed through the tool schema (src/kiro_crew/mcp_work.py, src/kiro_crew/validation.py) and the route (src/kiro_crew/dashboard/handlers/work_ledger.py). The count resets on an explicit new_goal flag, not on every goal_version bump and not on a changed goal text. Round and cap writes also bump goal_version, so a reset there would hand out a fresh 20 every round; a text compare would let a reworded goal reset it. Pipeline and security conductors never record a goal, so their queue boards keep only the open and stored bounds.

The cap is a forced checkpoint, not a hard limit: the refusal stops dispatch and tells the conductor to ask, but the same agent can raise item_cap or set new_goal. It catches a model that forgets or miscounts; it does not prove a person agreed. work_ledger_read also returns goal_items_used so the round report can say "items used: N of <item_cap>".

The goal-conductor skill (src/kiro_crew/builtin_skills/goal-conductor/SKILL.md), the conductor prompt (src/kiro_crew/agent.py), the work-ledger doc (src/kiro_crew/docs/work-ledger.md) and the work-ledger RFC's error list now point at the code check. Hitting the cap is a needs-human spend stop: pause and ask, do not stop the loop. The agent-spec byte pins are updated for the new conductor prompt text.

Backwards compatibility

Compatible: item_cap and new_goal are new optional fields. A header written before this PR has no stored count start, so its current goal is a legacy header: it starts counting at the upgrade, and earlier goals' items are not charged to it. Boards that never record a goal (pipeline, security) are unchanged.

Removes nothing: the new check only adds a refusal for creates past a per-goal count. No field, route or code is removed or renamed.

Tests

  • test/test_work_ledger.py: the 21st create is refused by default with a stable code (goal_item_cap_reached) and writes nothing; closed items still count; a raised cap admits more and keeps the count; round-only, same-text and reworded goal writes keep the count; new_goal=true starts a new count and needs the goal text; a board with no recorded goal is not goal-capped; an out-of-range item_cap is refused; a bad stored value reads as the default. The open-cap tests raise the goal cap first so they still reach the 32-open bound.
  • Upgrade: a pre-PR header with 22 items from an earlier goal admits the next create and counts from the upgrade (test_an_upgraded_header_counts_its_goal_from_the_upgrade); a goal write and a clean rebuild settle the start the same way.
  • test/test_work_ledger_projection.py: a clean rebuild keeps the cached cap; a dirty rebuild drops a refused goal write's cap and count start. A board from before the create counter starts a new goal's count after its records (in test/test_work_ledger.py). Both fixes were checked by reverting them: each test fails.
  • test/test_work_ledger_tools.py: over HTTP the cap answers 409 goal_item_cap_reached, action=goal item_cap raises it, the read shows item_cap and goal_items_used, and 257 is refused 400. The code→status map includes the new code.
  • test/test_agent_refactor_spec_bytes.py, test/test_agent_refactor_contracts.py: pins updated for the conductor prompt.

Determinism: the new tests have no timing, randomness or threads. They ran green repeatedly under -n 8 (random worker assignment) alongside the full work-ledger set.

Manual verification

N/A — unit and route tests cover the store and the HTTP path; there is no UI change.

Related Issues

Closes #17076

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 8, 2026 09:32
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d433d53485c5c0b8c309b17db26e4662d2ba0d1d 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 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d433d53485c5c0b8c309b17db26e4662d2ba0d1d — 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: PASS

The agent that hits the cap can raise it itself with item_cap=<N>. Check that #17076 only asks to catch miscounting, not to require human approval for more spend.

What this change ships

Inventory (9 items) — 9 justified

Intent: stop a goal conductor from creating more items than the goal's spend cap (20 by default) without someone deciding to allow it. This is a FIX: the cap was already promised by #16987's skill text but only the prompt enforced it.

  1. A create past the goal's cap is now refused with goal_item_cap_reached (409) and writes nothing — justified
  2. A conductor can set or raise the cap with action=goal item_cap=N (1..256) — justified
  3. new_goal=true starts a new count; rewording the goal, a new round or a cap raise keeps the count — justified
  4. work_ledger_read now returns goal_items_used — justified
  5. A board created before this change counts its current goal from the upgrade, not from earlier goals' items — justified
  6. A rebuild keeps the cached cap only from a clean, in-step cache; otherwise it falls back to 20 counted from the first create — justified
  7. Pipeline and security queue boards, which never record a goal, have no goal cap — justified
  8. The conductor prompt and goal-conductor skill point at the code check and add "pause, do not stop the loop" — justified
  9. The RFC error list and the work-ledger doc list the new code — justified

[FIRST-PRINCIPLES-REVIEWED] d433d53

Description read

[DESCRIPTION-READ] 664438311b38c5ec8f9a9dd218e91cc775989eabac748c6b3df9f206a41e1731

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that the refusal text names new_goal=true as well as item_cap. After a dirty rebuild every earlier goal's creates count again (base 0), and a conductor told only to raise the cap will ask about spend it never made.

[DESIGN-REVIEWED] d433d53

Description read

[DESCRIPTION-READ] 7b56e2036acf16b17d9941ada817b2561c45c036f36bb40cb9ec8116252e40d8

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 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d433d53

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

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d433d53

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

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

@iamwhatever
iamwhatever force-pushed the fix/work-ledger-goal-item-cap branch from 7b1c424 to 91a0bfb Compare October 8, 2026 09:50
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • The reset can be triggered by the agent itself span=c9e48c0183a1 -- fixed in 91a0bfb

A changed goal text no longer resets the count. Only action=goal new_goal=true (with the new goal text) moves goal_items_base.
A reworded goal, a round bump or a cap raise keeps goal_items_used.
Test: test_a_reworded_goal_does_not_reset_the_item_count (fails if the reset goes back to a text compare).

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • goal cap also applies to pipeline and security conductors span=4a3ed84e52ef -- fixed in 91a0bfb

The goal cap now applies only once a board has recorded a goal (goal_version > 0). Only the goal conductor writes action=goal.
Pipeline and security queue boards never do, so they keep only the 32-open and 256-stored bounds, as before.
Test: test_a_board_that_never_records_a_goal_has_no_goal_item_cap (21 creates with no goal write; fails without the gate).

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • The model being bounded decides whether the bound applies span=2e8abd9f1761 -- fixed in the description

The PR description now says plainly the cap is a forced checkpoint the agent can raise, not a hard limit: it catches a model that forgets or miscounts, and does not prove a person agreed.
Capping boards with no recorded goal would hit the pipeline and security queue boards, which never write goal (the Opus finding this head fixed).

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • A dirty rebuild sets a raised cap back to 20 span=3a47d5f57d09 -- rebutted

Fail-closed by design: a dirty cache may hold a refused goal write, so its raised cap cannot be trusted (the local GPT blocker this fixes).
The repeat ask is self-explaining: the refusal names the cap, the count and action=goal item_cap=<N> as the remedy, so the conductor re-raises after the user agrees.
A dirty rebuild is a rare recovery path; a doc line is not worth a full CI re-run on its own. It will go into the next push if one is needed.

@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 8, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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

This moves the goal-conductor's 20-item spend bound from prompt-only prose into the work ledger (#17076, T2): a create past item_cap, closed items included, is refused goal_item_cap_reached (409) and writes nothing. It is the right fix because the old open-item cap let a conductor that closes as it goes dispatch without limit. I read the full prod diff: _create_item checks the cap under the per-board lock against the re-read header, item_cap is range-checked in both the validator and the store, new_goal requires goal text so rewording cannot reset the count, and queue boards that never write goal (pipeline/security) are exempt via goal_version > 0. A dirty or out-of-step rebuild falls back to cap 20 counted from the first create, which is the side that asks the user sooner. The Design CONCERNS are answered on the current head: the body now says plainly that the cap is a forced checkpoint the agent can raise, not a hard limit, and the dirty-rebuild reset is rebutted as fail-closed. I accept both, though a one-line doc note about the rebuild reset would be a cheap follow-up. Before merging, note the behaviour change First Principles flagged: a live goal board that already has 20 or more creates under its goal gets refused on its next create and will ask the user, which is the documented intent. Base is main, checks are green, there are no change requests and the scope is about 175 prod lines. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 8, 2026 15:51

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

Request changes at 91a0bfb45d9c5ab3d77b57076e0ac00e9fcbd62e. Enforcing the goal's item cap in the store is right, and the mechanics are sound: the check runs inside _create_item under _existing_conductor_lock with the header re-read (src/kiro_crew/work_ledger.py:1996, :2022), the counter moves in the same hold (:2062), and a refusal returns before any item is written. One upgrade problem blocks, because auto-merge is on and this is the last gate.

Blocking: existing goal boards are refused with a wrong count after upgrade

goal_items_used is created_total - goal_items_base (work_ledger.py:319-321), and a header written before this PR has no goal_items_base, so it loads as 0 (:363). On an upgraded board the "items this goal created" is therefore the board's whole lifetime total, every earlier goal included. Reproduced: one goal created 22 items, a second goal was then recorded the old way, and the next create is refused with this goal has created 22 items and its item cap is 20, although the current goal has created none. A board running a user-approved Round-0 plan larger than 20 (which the old skill text allowed) is likewise stopped at item 21.

The refusal is visible, but it interrupts conductor work that was running fine on main and asks the user to raise a budget on a number that is wrong. That breaks existing users on upgrade.

Fix: treat a header with no stored goal_items_base key as grandfathered: seed the base from the current created_total on first read (so the current goal starts counting from the upgrade), rather than defaulting to 0. Add a test that loads a pre-PR header with a non-zero created_total and asserts the next create succeeds.

Verified / fail-closed

  • _write_goal (:1914-1923) re-reads the header under the lock and only new_goal=True moves the base; a pre-counter board backfills created_total first.
  • Rebuild (:3407, :3474-3478) keeps a cached cap/base only when the cache is clean and goal_version matches; otherwise cap 20, base clamped. Fail-closed.
  • _stored_item_cap (:369): absent or out-of-range reads as the default. Queue boards (goal_version == 0) are unaffected.

Mutation: removing the cap check reddens 7 tests incl. test_the_goal_item_cap_refuses_the_twenty_first_create_by_default; removing the goal_version > 0 gate reddens test_a_board_that_never_records_a_goal_has_no_goal_item_cap; removing the new_goal base move reddens test_a_new_goal_starts_a_new_item_count.

Non-blocking follow-ups

  1. The goal-conductor skill's "Goal changes mid-flight" section should mention new_goal=true, so a replaced goal does not inherit the old count.
  2. A dirty rebuild resets a user-raised cap to 20 and the next refusal looks like a first hit; consider saying so in the refusal or in work_ledger_read.

CI: 86 success, 14 skipped, 0 failing. Not run: full suite, Windows/macOS, a real model end to end.

@iamwhatever
iamwhatever force-pushed the fix/work-ledger-goal-item-cap branch from 91a0bfb to 0a778bd Compare October 8, 2026 17:16
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray thanks, fixed in 0a778bd (rebased on main).

  • A header with no stored goal_items_base key now reads as grandfathered, not 0. Its current goal counts from the upgrade: goal_items_used is 0 until the first write.
  • The next create or goal write settles the start to the board's created_total, after the one-time created_total backfill, and stores the key. The default cap then counts from there.
  • A clean rebuild keeps the grandfather status and settles it against the rebuilt total. A dirty rebuild still falls back to counting every create.
  • Tests: test_an_upgraded_header_counts_its_goal_from_the_upgrade is your repro. It has 22 items from an earlier goal, then a second goal recorded the old way, and the next create now succeeds. There are also test_a_goal_write_settles_an_upgraded_headers_count_start and test_a_clean_rebuild_of_an_upgraded_header_counts_from_the_upgrade. All three fail when the default goes back to 0.

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

Copy link
Copy Markdown
Contributor Author

Follow-up: the same fix is now at de76739. It renames the constant to LEGACY_GOAL_BASE (wording) and keeps black's formatting. No behaviour change.

@iamwhatever
iamwhatever force-pushed the fix/work-ledger-goal-item-cap branch from 0a778bd to de76739 Compare October 8, 2026 17:32
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision 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 8, 2026
@iamwhatever
iamwhatever force-pushed the fix/work-ledger-goal-item-cap branch from de76739 to 5b50f4a Compare October 8, 2026 21:27
@iamwhatever
iamwhatever requested a review from buluoray October 8, 2026 21:27
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray could you re-review? Your upgrade blocker (headers with no goal_items_base now count from the upgrade, not from 0) is fixed. Rebased onto main at 5b50f4a; the only conflict was the agent-spec byte pins, regenerated. Repro test: test_an_upgraded_header_counts_its_goal_from_the_upgrade.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 8, 2026
chenmingwei23
chenmingwei23 previously approved these changes Oct 9, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@buluoray rebased onto main (after #18109 and #18113) at d433d53; the only conflicts were the agent-spec byte pins, regenerated. Your upgrade blocker stays fixed (test_an_upgraded_header_counts_its_goal_from_the_upgrade). Could you re-review? Your changes-requested is still on the old head 91a0bfb.

@iamwhatever
iamwhatever force-pushed the fix/work-ledger-goal-item-cap branch from 5b50f4a to d433d53 Compare October 9, 2026 07:44
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 9, 2026

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

Approve. The prior blocking finding is fixed at d433d53485.

Prior finding: FIXED. A header that has no goal_items_base now reads as LEGACY_GOAL_BASE instead of 0 (work_ledger.py:372-377). goal_items_used reports 0 for that state (:329-330). The first create or goal write under the lock then settles the base to the board's current created_total (_settle_goal_base, :391-394, called at :1955 and :2044). A clean rebuild settles it against the rebuilt total (:3535-3536). So after the upgrade, an existing board's goal starts counting from the upgrade and no longer from the board's first create. I checked this by mutation. Putting the old 0 default back in from_dict makes test_an_upgraded_header_counts_its_goal_from_the_upgrade, test_a_goal_write_settles_an_upgraded_headers_count_start and test_a_clean_rebuild_of_an_upgraded_header_counts_from_the_upgrade fail. Turning _settle_goal_base into a no-op, removing the goal_items_used legacy guard, removing the settle in _create_item, or forcing the rebuild's legacy branch to 0 each makes at least one of those tests fail.

I also checked that the -1 sentinel never reaches disk. If it did, it would read back as 0 and bring the bug back. Every writer of conductor.json either settles the base first (_write_goal, _create_item, _rebuild_locked), writes a fresh header with base 0 (ensure_conductor), or runs only after a goal write has already settled it (mark_goal_recorded).

What I ran: the work-ledger, projection, tools and agent-refactor golden tests at this head (490 passed), plus the mutations above. CI on this head: 85 success, 13 skipped, 0 failure, 0 pending.

Non-blocking follow-ups

  1. Nothing tests the _write_goal backfill branch for a legacy header (:1951, the current.goal_items_base == LEGACY_GOAL_BASE half). This is a board from before both created_total and goal_items_base whose first post-upgrade action is a goal write without new_goal. If that condition is narrowed back to new_goal only, every test stays green, but such a board would settle its base at 0 and then backfill created_total on the next create, which charges all earlier items to the current goal. Please add a test that strips both keys and then does action=goal round=N.
  2. A rebuild from a dirty cache, or one whose goal_version differs from the fold, falls back to base 0 (:3533-3534). That means an upgraded board that goes through that path counts its whole history against the default cap. This is deliberate (it asks the user sooner), the cause is rare, and the refusal names its remedy (item_cap), so it is not silent. Still, consider using the rebuilt total for a legacy header on this path as well, so the upgrade case behaves the same here as everywhere else.

Upgrade impact: existing goal boards keep working. Their current goal gets the default cap of 20, counted from the upgrade. Queue boards that never record a goal (pipeline and security conductors) have no goal cap. Audience fit: the default path is unchanged for boards without a goal. Goal conductors gain a bound enforced in code, and the refusal tells the conductor how to raise it.

@iamwhatever
iamwhatever merged commit 67c1304 into main Oct 9, 2026
103 of 104 checks passed
@iamwhatever
iamwhatever deleted the fix/work-ledger-goal-item-cap branch October 9, 2026 09:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 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.

goal-conductor: check the default item cap from the work ledger in code, not only in the prompt

3 participants