Skip to content

docs(rfc): drop the fixed goal concurrency default; host pressure wakes the conductor - #36304

Merged
bolichen97 merged 1 commit into
mainfrom
docs/rfc-concurrency-cap-resource-pressure
Nov 13, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/rfc-concurrency-cap-resource-pressure

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the owner's decision that host resources, not a fixed number, bound how many workers a goal runs, and that host pressure is written on the work ledger and wakes the conductor so it pauses.

Every goal board is capped at 6 open items (DEFAULT_GOAL_CONCURRENCY_CAP in src/kiro_crew/work_ledger_records.py). The 6 was never measured and does not follow the host. When host memory gets tight, nothing tells a conductor: ResourcePressureNotifier only notifies the person, and a work-ledger create does not consult admission_check.

Why it matters

A fixed 6 holds back a healthy host and does nothing for a starved one. A conductor that never hears about pressure keeps dispatching into a host about to freeze. Both code changes change conductor defaults, so the First Principles lane needs this decision on main first.

Not a goal

  • Any code change. The two implementation PRs follow, pressure first.
  • A load, CI-queue or rate-limit trigger. The pressure RFC lists it as a known limit.
  • Removing the concurrency_cap field.

What changed (motivation → approach → change)

The owner asked to stop micro-managing with a fixed number, and to have tight resources recorded on the ledger and wake the conductor. Two linked RFCs record that, each saying the other is needed.

RFC Decision
rfc-work-ledger-concurrency-cap.md §7 (amended) Default concurrency_cap becomes MAX_ITEMS_PER_CONDUCTOR (32). The field stays for a bound the user sets. The refusal says wait for a seat. resource_status decides each wave, in Ultra Mode and Bot conductor rules. Reverses the earlier owner ruling that kept 6.
rfc-work-ledger-resource-pressure.md (new) The notifier writes an expiring host_pressure record. work_ledger_read shows it. Each watched conductor wakes once per episode level. Tight: stop dispatching (advice). Critical: create refused 409 host_pressure_critical. Clear: resume.

The concurrency-cap RFC moves to partial: §3 shipped in #19338, §7 is not built. The RFC index (docs/request-for-change/README.md) carries both rows.

Backwards compatibility

Compatible: documents only; no code, config or schema changes.

Removes nothing: the diff adds and amends RFC text; the 2026-10-12 decision text stays as the record.

Tests

Proof: not provable -- docs or config only

test/test_pr_quality_gates.py (the one related backend test file) passes locally: 97 passed. The pressure RFC lists the tests the code PR must carry.

Manual verification

Code references re-read at 9b32941be6 (origin/main): the cap check in _admit_create_locked, the notifier's 30 s / 600 s / 30 min constants, _fire, _watched_boards, _ALL_CLOSED_ENTRY, admission_check, and that ConductorRecord.to_dict always stores concurrency_cap (so boards that stored 6 keep it).

Related Issues

Closes #36301

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 November 13, 2026 02:15
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 7d35767308973c4db075a8a8447d6fce2438b3fc ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7d35767308973c4db075a8a8447d6fce2438b3fc 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 7d35767308973c4db075a8a8447d6fce2438b3fc — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only RFC changes: the decision is recorded with its alternatives, its compatibility story (stored 6s are kept) and its landing order (pressure first), and nothing ships yet.

Notes

  • §3.5 refuses only create at critical, yet §3.4 asks the conductor to stop bind and session_create too. At critical, a conductor that misses the rule can still bring up workers through those paths. Either name this gap in §7 or gate the same admission point in the code PR.
  • §3.3 has the notifier (notifications/) call conductor_wake directly. That couples the notification module to the ledger. A listener that the ledger registers on the notifier would keep it the one noticer without that coupling.

[DESIGN-REVIEWED] 7d35767

Description read

[DESCRIPTION-READ] d7151b0db9ca5a3a421a0b0fe48ab56902303f9f6076487464bc39c66989aada

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7d35767

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 7d35767308973c4db075a8a8447d6fce2438b3fc 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 7d35767308973c4db075a8a8447d6fce2438b3fc — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • rfc-work-ledger-concurrency-cap.md:30 still says Status: accepted. while the frontmatter now says partial. The amendment paragraph just above it names what shipped, but the status line itself was not updated.

[OPUS-REVIEWED] 7d35767

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

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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Docs-only PR: amends the concurrency-cap RFC (§7, default becomes 32, status partial) and adds a resource-pressure RFC. Every code claim checked holds at head: DEFAULT_GOAL_CONCURRENCY_CAP=6 and MAX_ITEMS_PER_CONDUCTOR=32; _admit_create_locked checks the store bound first, so a 32 default never fires; to_dict always stores concurrency_cap and absent or out-of-range values read as the default; the existing refusal text contradicts the 'never ask to raise it' prompt; the notifier constants and episode model match; _fire, _watched_boards, _ALL_CLOSED_ENTRY, admission_check and cached_admission_check exist with the stated fail-open behaviour. Trust: the planned 409 reads the live cached verdict, not the new file, so a stale or forged host_pressure.json can only cause an extra pause. The record expires after 90 s, the RFC adds no new authority, and it requires the pressure code to land before or with the default change. Nothing blocks.

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 4ce398ee9e · 345 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Not from this PR (docs only). Two reds on head 4ce398e:

@iamwhatever
iamwhatever force-pushed the docs/rfc-concurrency-cap-resource-pressure branch from 4ce398e to 7d35767 Compare November 13, 2026 03:21
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 13, 2026

@bolichen97 bolichen97 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. I read the whole diff on this head. It is docs only: the README rows, a §7 amendment to rfc-work-ledger-concurrency-cap.md, and the new rfc-work-ledger-resource-pressure.md. All checks are green.

What it decides

  • The concurrency-cap amendment (§7) drops the fixed default of 6 open items per goal. The default becomes MAX_ITEMS_PER_CONDUCTOR (32), and concurrency_cap stays as a bound the user can set. The refusal text says to wait for a seat instead of asking to raise the cap. resource_status decides each wave, in both the Ultra Mode and Bot conductor rules.
  • The pressure RFC has the gateway's existing ResourcePressureNotifier write a host host_pressure record that expires after 90 s, and show it in work_ledger_read. It wakes each watched conductor once per level change, through the existing _fire and probe budgets. At tight the conductor pauses dispatch, which is advice only. At critical, create is refused with 409 host_pressure_critical.

Why it is fine

  • Dropping the 6 loosens a default nobody measured. A board that already stored 6 keeps it, and no migration rewrites stored values.
  • The critical refusal is not new strictness of its own. It reuses cached_admission_check, which already refuses background work (cron, task-runner steps, helper turns) at critical on main. It admits on unknown and when agent.admission_gate is false, and writes nothing. This applies main's own rule to work-ledger create, a background path that skipped it.
  • The pressure record is the safety net that §7 needs once the fixed 6 is gone, and §10 asks for it to land first, or in the same PR.
  • No new tool, status, event kind or config key. Cost is about one conductor turn per conductor per level change.

Long-term debt: low. The known limits are written down: memory only, one host, and advice only at tight.

Direction signed by maintainer (bolichen97): both RFCs as written. The code PRs still need their own review, with the §5 tests.

@bolichen97
bolichen97 merged commit d1f229a into main Nov 13, 2026
99 of 100 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-concurrency-cap-resource-pressure branch November 13, 2026 07:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Work ledger: drop the fixed concurrency default and let host resource pressure pause the conductor

3 participants