Skip to content

docs(goal-conductor): size dispatch waves by resource_status, not two or three per round - #36298

Merged
buluoray merged 1 commit into
mainfrom
conductor-wave-resource-gate
Nov 14, 2026
Merged

buluoray merged 1 commit into
mainfrom
conductor-wave-resource-gate

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A goal conductor dispatches every ready, independent item at once when the host has room, instead of one or two at a time.

The goal-conductor skill says "Keep concurrency small and constant — two or three items per round. More rounds beats more parallelism". Conductors follow it literally and dispatch one or two workers per round even when resource_status reads ample, so goals with many independent items run in many slow rounds.

Why it matters

Every goal run through a conductor (Ultra Mode, mate conductor) is slowed by a fixed brake that ignores real host capacity. The owner noticed conductors are "especially careful, one or two at a time" and asked that the conductor dispatch freely, checking resources first.

Not a goal

  • Changing the ledger's concurrency cap (DEFAULT_GOAL_CONCURRENCY_CAP, "at most 6 open") or its prose. That stays the hard ceiling.
  • Any code change. No new mechanism, number or setting.

What changed (motivation → approach → change)

Fixed brake in prose → reuse the rule the team-lead skill already ships (section 5, "Capacity decides the wave, not your plan") → src/kiro_crew/builtin_skills/goal-conductor/SKILL.md replaces the "two or three per round" paragraph with that rule: dispatch every ready, independent item up to the ledger cap; call resource_status before every wave and reseed wave; ample dispatches the wave, tight/unknown dispatch one item and queue the rest, critical dispatches none; each landing re-reads resource_status and dispatches from the queue; the patrol loop stays armed while anything is queued (the patrol tick resumes the conductor; a wave that dispatched nothing arms its own monitor_start(watch="work-ledger"), since no create or bind reply arms one), and patrol ends only when every item is terminal and nothing is queued; the chat is never reset while anything is queued, since a queued item has no ledger row and the chat is its only copy; carry no number of your own. team-lead/SKILL.md §5 drops its own copy of the capacity rule and keeps only a pointer to goal-conductor's "Capacity decides the wave" plus the "give the capacity back" step, so the team-lead agent (which loads both skills) reads one rule, not two that disagree. Behaviour change for a team lead: on tight or unknown it now dispatches one item and queues the rest, where team-lead §5 used to queue the whole wave.

Swept for other copies of the brake (two or three, More rounds, small and constant) across src/, docs/ and test/: this was the only one. agent_parts/spec_prompts.py already says "Capacity, before dispatching — resource_status".

Backwards compatibility

Compatible: prompt text only; the ledger cap still refuses past its limit.

Removes nothing: the paragraph is replaced by a capacity rule; no key, path or function changes.

Tests

Proof: not provable -- docs or config only

Ran the covering skill/conductor tests locally (test_builtin_agent_skill_resources, test_builtin_skill_index_line, test_conductor_*, test_mate_conductor_parity, test_goal_conductor_skill_grants, test_crew_mode_steer_ledger, test_ledger_conductor_agent, test_team_lead_agent, test_work_ledger_doc): 258 passed. No test pinned the old prose.

Manual verification

N/A — prompt-only change; behavior shows in the next goal run.

Related Issues

Closes #36294
Follow-up: #37192 syncs the "and nothing is queued" stop clause into patrol_ends, the tick texts and work-ledger.md.

Stands alone. No dependency on another PR: the rule uses only resource_status and the patrol tick, both on main.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass (no new test: prompt-only change, no new logic)
  • 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 November 13, 2026 02:07
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from 8410a87 to b4e5f2d Compare November 13, 2026 04:21
@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 Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 3c1f41e90d86ce0b44017aa043ac7702caa44525 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 3c1f41e90d86ce0b44017aa043ac7702caa44525 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Prompt-only change that swaps a fixed brake for the existing resource_status rule; the ledger cap still holds, and team-lead loads both skills, so the pointer resolves.

Notes

  • The patrol tick texts still say "call autonudge_stop when every item is terminal" (conductor_patrol.py:86-136, spec_prompts.py:190,425). A queued item has no ledger row, so on critical a conductor can follow the tick and stop with work still queued. Land Sync the 'and nothing is queued' patrol stop clause into patrol_ends, tick texts and work-ledger.md #37192 soon after this.
  • Team-lead behaviour changes without being stated: on tight/unknown it now dispatches one item where it used to queue the whole wave. That is fine, but the description only calls the change de-duplication.

[DESIGN-REVIEWED] 3c1f41e

Description read

[DESCRIPTION-READ] 5cf2e3745948afdd4dda31a74eff8627d659e5f37a8ff9eaec9967cdbd55401d

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 Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 3c1f41e90d86ce0b44017aa043ac7702caa44525 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. The base RFC rfc-work-ledger-concurrency-cap.md (status partial) already decides this in §7: "resource_status decides each wave". On tight, though, the team lead now dispatches one item where it used to dispatch none, and the description doesn't say so.

Notes

  • Item 2 — undeclared: the description says it reuses "the rule the team-lead skill already ships". The deleted team-lead text said "on any of the last three, queue the rest of the wave instead of dispatching it", but the new text says "on tight or unknown dispatch one item and queue the rest". For the team lead, tight and unknown go from dispatching nothing to dispatching one. The diff also drops the reason that pinned unknown: "the one place where a lead decides from feel, which is the thing this section exists to stop". Subtraction: delete "dispatch one item and" so tight and unknown queue the whole wave, as the rule did before.

What this change ships

Inventory (7 items) — 6 justified

Intent: let a goal conductor run independent items in parallel when the host has room, instead of a fixed two or three per round. This is a FIX.

  1. The conductor dispatches every ready, independent item up to the ledger cap, not two or three per round — justified
  2. Per-posture counts: tight and unknown dispatch one item, critical dispatches none — undeclared; the team lead used to queue the whole wave on these
  3. Each time an item lands, the conductor re-reads resource_status and dispatches from the queue — justified
  4. Patrol stays armed while anything is queued; a wave that dispatched nothing arms its own work-ledger monitor — justified
  5. Patrol ends only when every item is terminal and nothing is queued — justified
  6. The chat is never reset while anything is queued — justified
  7. Team-lead §5 drops its copy of the capacity rule and points to goal-conductor's — justified

[FIRST-PRINCIPLES-REVIEWED] 3c1f41e

Description read

[DESCRIPTION-READ] 964c92e9287ae0ad623bd4b9b53c5712e0eea401e443a63717534b41beaca0b0

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 Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3c1f41e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 3c1f41e90d86ce0b44017aa043ac7702caa44525 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 3c1f41e

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 3c1f41e90d86ce0b44017aa043ac7702caa44525 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

Prompt-only change. It replaces goal-conductor's fixed "two or three items per round" limit with a rule that sizes each wave from resource_status, and team-lead §5 now points at that rule instead of keeping its own copy. Checks: team-lead always loads goal-conductor (service_agents.py:826). No other copy of the old limit exists anywhere in the repo. The host_pressure signal ("dispatch nothing") still wins over resource_status sizing (skill lines 693-694). The 6-open ledger cap is unchanged and still enforced by code. A gated work-ledger patrol still wakes the conductor through its quiet floor and the pressure-cleared wake, so queued items can be picked up. The existing tests on skill structure still match. The one AI-lane BLOCK (the rule duplicated in two skills) is fixed on this head. Left: the new "and nothing is queued" stop condition does not yet match the code-side patrol_ends text and the patrol tick texts. That is deferred to #37192 and only matters on a narrow path (all items terminal while the posture is critical). Non-blocking.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 3c1f41e90d · 42 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from b4e5f2d to 55d5142 Compare November 13, 2026 05:05
@iamwhatever

iamwhatever commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=1c12c52038a7 goal-conductor wave rule could queue every item and stall

fixed in 55d5142: tight/unknown now dispatch one item and queue the rest, critical dispatches none; each landing re-reads resource_status and dispatches from the queue; a critical host with nothing in flight is stated in the round report, since nothing will wake the conductor.

@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 Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from 55d5142 to b6363a3 Compare November 13, 2026 08:26
@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 Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from b6363a3 to d99573f Compare November 13, 2026 09:28
@iamwhatever

iamwhatever commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=1c12c52038a7 queued items live only in the conductor chat and a round-close reset drops them

fixed in d99573f: the "Never reset when" list now holds "anything is queued -- a queued item has no ledger row yet, so the chat is its only copy". The host_pressure clear wake named in the note lands with #36481, which merges before this PR.

@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 Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from d99573f to 606df60 Compare November 13, 2026 09:49
@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 Nov 13, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for dropping the host_pressure dependency. The new sentence now names only things that exist on main. One case from the earlier review is still open on this head.

  1. src/kiro_crew/builtin_skills/goal-conductor/SKILL.md:196: when resource_status reads critical at the first wave, the rule at :191-193 dispatches nothing, so no session_create or bind runs. On main, only those two paths call conductor_patrol.ensure_patrol (dashboard/handlers/session_control.py:554 and dashboard/handlers/work_ledger_conductor.py:480). The Patrol section (:324-330) tells the conductor to arm monitor_start only after it reads a create or bind reply, and a wave that sent nothing gets no reply. Line 196 then says "Keep the patrol loop armed while anything is queued; the patrol tick resumes you", but no loop exists. Outcome: the conductor says the queue will resume, and nothing resumes it. The goal stays at zero items until a person messages it. Smallest fix: add one sentence, for example "If a wave dispatched nothing and no patrol is armed yet, arm monitor_start(watch=\"work-ledger\") yourself." Or, on critical with nothing in flight, say in the round report that dispatch is paused until the user resumes it.

Earlier items:

  • Item 1, host_pressure wake: fixed. Line 196 no longer names that wake.
  • Item 1, first-wave case: still stands (item 1 above).
  • Optional items from the first review (the reset bullet in "What changed", and "dispatch one" on tight/unknown): answered.

Optional:

  • The "and nothing is queued" stop clause (:884) still has no named owner. spec_prompts.py patrol_ends and patrol_final_report, the conductor_patrol.py tick texts and src/kiro_crew/docs/work-ledger.md:318 still say to stop when every ledger item is terminal. Please name an issue that will sync them.
  • team-lead/SKILL.md:153 says to queue the rest of the wave on tight/unknown, and the same sentence hands the count to goal-conductor, which says to dispatch one. #36312 adds a third count. Please give the per-posture count one owner.
  • The checklist ticks "new tests added", but the diff adds no test. Either untick it or add a pin in test/test_conductor_team_management_rules.py.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 14, 2026
@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from 298a011 to fa1cf88 Compare November 14, 2026 10:59
@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 Nov 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

@KiroCrewCaptain thanks, all addressed in fa1cf88:

  1. First wave at critical, no patrol armed: fixed. Added after the "patrol tick resumes you" sentence: "If a wave dispatched nothing and no patrol is armed yet, arm monitor_start(watch="work-ledger") yourself, since no create or bind reply will arm one."

Optional:

Could you re-review?

@iamwhatever
iamwhatever force-pushed the conductor-wave-resource-gate branch from fa1cf88 to 3c1f41e Compare November 14, 2026 11:32
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=bcd9b8ff30f4 team-lead §5 is a second copy of goal-conductor's capacity rule

fixed in 3c1f41e: team-lead §5 drops its restated rule (reseed, four postures, unknown FAILED, "Carry no number"). It keeps one pointer to goal-conductor's "Capacity decides the wave", which owns the per-posture counts, plus the "give the capacity back" step. grep -E "reseed stands up as many sessions|posture of a reading|Carry no number of your own|Capacity decides the wave" now matches team-lead only in that pointer.

@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: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 14, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Thanks for closing the first-wave gap and for replacing team-lead's second copy of the capacity rule with a pointer. Nothing in the diff blocks a merge, but this head cannot be approved yet.

Earlier change request, item by item:

What still blocks: PR Readiness is red on this head because the CodeQL Analyze (python) and Analyze (javascript-typescript) check runs failed. The diff changes only two skill files, so this looks like a CI infrastructure failure, not something the diff caused. Rerun those two jobs and refresh readiness. This review found no other blocker. A simulated merge with current main is clean. The parity anchor resource_status decides the wave and the "Patrol ends on exactly two signals" heading are both still in the merged skill. The design is signed off under the standing maintainer sign-off for changes by team members. A maintainer will approve once readiness is green.

Optional:

  • No test pins the new per-posture paragraph. One anchor phrase added to CONDUCTOR_MODE_SKILL_ANCHORS["resource_wave"] in test/test_mate_conductor_parity.py, plus one check that "Capacity decides the wave" exists in goal-conductor, would catch a later edit that removes it or breaks team-lead's pointer.
  • The new "anything is queued" reset bar (goal-conductor/SKILL.md:718) can block the chat reset for a whole goal on a host that stays tight. The goal text's Plan already lists items before they are dispatched. Writing the queued items there or into session_ledger_record next would let the reset go ahead.
  • Round 0 still says "name the concurrency" (line 148) and lists "how many items per round" as an assumption to pick (line 167). Both conflict with "Carry no number of your own". Saying that resource_status sizes each wave would keep the rule in one place.

@KiroCrewCaptain
KiroCrewCaptain dismissed their stale review November 14, 2026 14:27

Withdrawn: every item in this review is fixed or answered on the current head (see the follow-up comment). Other holds on this PR are listed there.

@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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 14, 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.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

This PR is still needed, and I found no defect in it.

Current main still says "Keep concurrency small and constant — two or three items per round" in goal-conductor/SKILL.md. That line contradicts the rest of main. The shared conductor rule resource_wave in spec_prompts.py already says: on ample dispatch every ready item, on tight or unknown dispatch one and queue the rest, on critical dispatch none. The concurrency-cap RFC §7 (accepted 2026-11-13) also says resource_status decides each wave. This PR swaps the old line for the same counts that resource_wave uses, so the skill and the prompt now agree.

Earlier review points, checked on this head:

  • host_pressure wake named before it existed on main: fixed. The sentence now names only the patrol tick.
  • First wave on critical, with nothing armed to resume the conductor: fixed. The rule now says to arm monitor_start(watch="work-ledger") when a wave dispatched nothing.
  • Who owns the "and nothing is queued" stop clause: answered with #37192.
  • One owner for the per-posture count: fixed. team-lead §5 now points to goal-conductor's "Capacity decides the wave" and no longer keeps its own copy.
  • Test checklist box: fixed, it is unticked.
  • CodeQL red on PR Readiness: cleared. All checks on this head now pass (80 pass, 18 skipped, 0 failing).

Merge with current main (66dc266de3): clean, no conflicts. The merged skill reads as one rule. The only other wave text is main's host-pressure section, which says a present host_pressure level wins and resource_status sizes waves again once it clears. That order is stated, so the two do not disagree. The "Rounds are not gated, but spend is bounded" section already says "resource_status decides the wave", which matches.

Tests on the merged tree:

  • test/test_conductor_agent.py plus the parity, skill-grant, skill-resource, frontmatter, line-cap, team-lead and ledger-conductor tests: 624 passed.
  • All test_conductor_*, test_builtin_skill* and test_skill* files: 3158 passed, 881 skipped, 1 failed. The failure was test_skill_search_index.py::TestTransientLockDoesNotLatch::test_a_busy_database_is_retried, a lock-retry test. It passed when run alone, and it does not read either skill file.
  • test_back_to_back_rounds_keep_a_spend_bound: passed.

Optional, not blocking:

  • Round 0 still says "name the concurrency" and lists "how many items per round" as an assumption to pick. Both pull against "Carry no number of your own". Saying that resource_status sizes each wave there would keep one rule.
  • rfc-work-ledger-concurrency-cap.md §7.1 quotes "Carry no number of your own" as living in team-lead §5. After this PR that phrase lives in goal-conductor. The RFC pins its reads to an older commit, so this is only a stale pointer.
  • No test pins the new paragraph. One anchor phrase in CONDUCTOR_MODE_SKILL_ANCHORS["resource_wave"] in test/test_mate_conductor_parity.py would catch a later edit that drops it or breaks team-lead's pointer.

Verdict: APPROVE

@buluoray
buluoray enabled auto-merge (squash) November 14, 2026 19:06
@buluoray
buluoray merged commit f98bf61 into main Nov 14, 2026
110 of 114 checks passed
@buluoray
buluoray deleted the conductor-wave-resource-gate branch November 14, 2026 19:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 14, 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: dispatch waves sized by resource_status, not a fixed two-or-three per round

3 participants