Skip to content

fix(context): restore the startup rule allowance to ~37,000 characters - #12657

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/lessons-startup-budget
Sep 22, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/lessons-startup-budget

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

The startup "Learned corrections" rule block collapsed from ~36,900 characters to
~7,158 characters, so only 8 of a user's 607 standing rules reach the model on a
fresh session. The omission notice reads:

[Context budget: omitted 599 of 607 retained rules above the 7458-character rule budget.]

Nothing was deleted from the library. Two landed changes combined to produce this:

  1. #11996 changed _CONTEXT_BUDGET_BASE from 165_000 to 33_000
    (src/kiro_crew/context.py). Every _budget(fraction) section cap shrank about
    fivefold with it, including _LESSONS_CAP = _budget(0.226): 37,290 -> 7,458.
  2. #12431 started passing directive_budget=caps.lessons at the four startup
    lesson renderers. When directive_budget is set, get_lessons_context /
    get_context bind the authored rule tier at that value unconditionally, so the
    rule block is pinned at 7,458 characters on every session.

The 5x cut in step 1 was invisible until step 2, because before step 2 the
background path filled the ~500,000-character protected ceiling and dropped
nothing.

Why it matters

Standing rules are the corrections a user taught the agent after a past mistake --
"never run the full pytest suite on this box", "force-push is allowed to non-main
branches", "close only bug issues, never feature issues". They are not
discretionary background material; the whole point is that they arrive on every
session. Dropping 599 of 607 means the agent silently loses almost all of its
learned corrections at startup and repeats mistakes the user already corrected.

What changed

The chain from symptom to root cause: the rule block is small (symptom) because
the authored rule tier is bounded by caps.lessons (mechanism), and caps.lessons
is small because it is a fraction of _CONTEXT_BUDGET_BASE, which #11996 pinned
to its smallest-window value (root cause). Standing rules were bound to a pool that
was never meant to size them.

This restores the startup rule allowance to the pre-#11996 1M-window level as a
window-INDEPENDENT constant, without touching the shared budget base:

  • Add _LESSONS_STARTUP_CAP = 37_000 (the 165,000 x 0.226 = 37,290 allowance a
    1M-window session shipped with before the base was pinned) and a matching
    caps.lessons_startup resolved cap.
  • Change the four startup lesson renderers to pass
    directive_budget=caps.lessons_startup instead of caps.lessons.

This is a restoration of a historical allowance, not a new cost: 37,000 characters
is what a 1M-window session carried before 2026-09-19. #12431's mechanism -- a
window-independent authored-tier budget passed as directive_budget -- is kept
intact; only its value changes.

Both store paths compute the rule-tier bound as min(directive_budget, <ceiling>),
where the ceiling is the model-safe protected bound each renderer hands in (about
500,000 characters at the 1M reference window, smaller on a smaller model). The
vector store names that outer bound hard_cap; the JSONL store names it cap, and
the JSONL renderers already pass the ceiling into cap. So min(37,000, ceiling)
= 37,000 binds the rule block symmetrically on both paths whenever the ceiling
exceeds it, and no budget arithmetic changes.

Tests

  • Extended TestBackgroundBudget in test/test_default_context_admission.py with
    test_startup_directive_tier_is_bound_by_lessons_startup_both_paths, driving the
    full startup path through ContextBuilder.build_session_context for both the
    JSONL and vector stores: a background render of ~200 rules (~165,000 characters)
    must bound the [Learned corrections] block at caps.lessons_startup -- greater
    than caps.lessons (7,458, the regression) and no larger than
    caps.lessons_startup plus header/footer framing (so not the ceiling).
    Mutation-verified: reverting directive_budget at a renderer to caps.lessons
    reddens it (assert 7458 < 7027). Ran only that file, -n0: 6 passed.
  • Extended test_all_caps_at_reference_window_equal_module_constants in
    test/test_context_dynamic_budget.py to pin
    caps.lessons_startup == _LESSONS_STARTUP_CAP. 1 passed.
  • Measured the rendered rule block directly on a synthetic 200-rule store with the
    change applied: JSONL path 36,685 characters, vector path 36,571 characters --
    both restored to ~37,000, versus ~7,000 on the pre-fix build.

Pattern harvest

Not generalizable: this is a value regression, not a code smell that semgrep could
catch. The reusable lesson is procedural -- a section cap derived from a shared
_budget(fraction) base couples an invariant that must not scale (standing rules)
to a pool that was rescaled for an unrelated reason (#11996). When a value must
hold across model windows it should be a named window-independent constant, not a
fraction of a base another change is free to move. The two callers here also name
the same role differently (hard_cap vs cap), which briefly masked the fix.

Any other suggestions on the work

  • learn.py's get_context uses cap for the SAME role that vector_memory.py's
    get_lessons_context calls hard_cap: the outer ceiling the authored tier is
    taken smaller than, NOT the ordinary caps.lessons budget. This naming collision
    is a real footgun (it briefly looked like the JSONL path needed a different fix)
    and is worth a standalone cleanup -- out of scope here.
  • The _CONTEXT_BUDGET_BASE cut from 165,000 to 33,000 in #11996 also shrank every
    OTHER section cap (preferences, projects, history, semantic, episodic, skills,
    steering) about fivefold. This PR deliberately addresses only the standing-rule
    tier and does not touch the shared base or the other caps.

@chenmingwei23
chenmingwei23 requested review from a team and hoang-phan98 September 21, 2026 23:40
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 21, 2026
@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

FINDING -- docs/system-specs/modules/memory-skills-hooks.md:2782 -- “under the lessons budget” contradicts the new lessons_startup bound -> Fix: delete the stale lessons budget clause.
[GPT-REVIEWED] 66af9a4

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 66af9a4cca933df2b7815e22d26804a4ca1812ed 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

Confirm #11996's fivefold base cut never intended to shrink the startup rule tier — this PR treats that as collateral, not a decision.

[DESIGN-REVIEWED] 66af9a4

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 66af9a4

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 66af9a4cca933df2b7815e22d26804a4ca1812ed via the fork AI-review pipeline — 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

Verify #12431 meant the ~500K-ceiling allowance, not 7,458: this PR reverses the base spec's "22.6% of the 33,000 base" pin on that premise.

The premise is well-evidenced in the checkout — the 22.6% fraction predates the base cut (165,000 × 0.226 = 37,290 matches, and _HISTORY_REFERENCE_BASE = 165_000 still sits in context.py), the added test reddens on base, and _scaled is identity so the window-independent claim is literal — but the intent of #12431's author is the one fact only a human can confirm.

What this change ships

Inventory (5 items) — 5 justified

Intent: restore the startup standing-rules block that a budget-base cut plus a later budget-binding change silently shrank ~5x — a FIX.

  1. Fresh sessions carry ~37,000 characters of standing rules again instead of ~7,458 — justified
  2. The startup rule allowance is now a named window-independent constant, decoupled from the shared budget base — justified
  3. Spec paragraph rewritten to document the new allowance and the two stores' hard_cap/cap naming — justified
  4. Existing test pin moved from _LESSONS_CAP to _LESSONS_STARTUP_CAP, with the reversal reasoned in-comment — justified
  5. New both-paths startup test plus a caps-constant pin, failing on base — justified

[FIRST-PRINCIPLES-REVIEWED] 66af9a4

@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 Sep 21, 2026
The startup "Learned corrections" block collapsed from ~36,900 characters to
~7,158, so only 8 of a user's 607 standing rules reached the model on a fresh
session. Nothing was deleted from the library; two landed changes combined:
`kirodotdev#11996` moved `_CONTEXT_BUDGET_BASE` from 165,000 to 33,000, shrinking every
`_budget(fraction)` cap about fivefold including `_LESSONS_CAP` (37,290 ->
7,458), and `kirodotdev#12431` then began passing `directive_budget=caps.lessons` at the
four startup lesson renderers, which binds the authored rule tier at that value
unconditionally. The fivefold cut was invisible until the second change,
because before it the background path filled the ~500,000-character protected
ceiling and dropped nothing.

Bind the startup rule tier to a window-INDEPENDENT allowance instead of a
fraction of the shared base: add `_LESSONS_STARTUP_CAP = 37_000` (the
165,000 x 0.226 allowance a 1M-window session shipped with before the base was
pinned) plus a matching `caps.lessons_startup`, and pass that as the four
startup renderers' `directive_budget`. `kirodotdev#12431`'s mechanism is kept intact;
only its value changes. No budget arithmetic moves: both stores compute the
tier as `min(directive_budget, <ceiling>)`, so `min(37,000, ceiling)` binds the
block symmetrically on the vector path (`hard_cap`) and the JSONL path (`cap`).

Tests: `test_startup_directive_tier_is_bound_by_lessons_startup_both_paths`
drives the full startup path through `ContextBuilder.build_session_context` for
both stores and pins the block above `caps.lessons` and inside
`caps.lessons_startup`; mutation-verified (reverting a renderer to
`caps.lessons` reddens it at `assert 7458 < 7027`).
`test_all_caps_at_reference_window_equal_module_constants` pins
`caps.lessons_startup == _LESSONS_STARTUP_CAP`.
`TestLessonsCap::test_over_cap_preserves_complete_explicit_rules` sized its
overflow fixture off `_LESSONS_CAP`, which the larger budget now fits, so it is
sized off `_LESSONS_STARTUP_CAP` instead -- it still proves whole-entry
trimming, full omission accounting, and the block staying inside its budget.
Measured on a synthetic 200-rule store: JSONL 36,685 characters, vector 36,571.
@chenmingwei23
chenmingwei23 force-pushed the fix/lessons-startup-budget branch from 37cf523 to 66af9a4 Compare September 22, 2026 00:36
@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 Sep 22, 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.

Blocking on one number, which I checked against main rather than against the body.

37,000 is larger than the whole admission budget, so a full rule block zeroes the discretionary pool.

  • context.py:498 -- _CONTEXT_BUDGET_BASE = 33_000.
  • context.py:1121-1123 -- max_context returns base, i.e. 33,000, and its own docstring says "One shared admission budget; section limits do not add capacity."
  • context.py:3747 -- max_context_chars = caps.max_context.
  • context.py:4164 -- remaining = max(0, max_context_chars - protected_chars).

The rule block is append_required, so it counts into protected_chars. A 37,000-character block therefore drives remaining to exactly 0 before anything discretionary is considered, and [DOCUMENTATION] (:3741), [USER PROFILE] (:3713) and the member-memory-unavailable notice (:3899) are all dropped with only "[Context budget: omitted background context]" to show for it.

The guard that looks like it would catch this does not fire. caps.protected_context is max(_PROTECTED_CONTEXT_FLOOR, window * 4 * 0.125) (:1177-1179) and _PROTECTED_CONTEXT_FLOOR = _CONTEXT_BUDGET_BASE * 3 (:1097), so it floors at 99,000 and is 500,000 at the reference window. The lessons-trimming path at :4144 needs protected_chars > caps.protected_context, which a 37,000 block never reaches. So nothing trims it and nothing warns.

This lands hardest on precisely the user the PR is for: the 607-rule user at ~36.9K loses their profile and documentation blocks to get their rules back. That is a trade, possibly the right one, but the body does not mention it and no test covers it.

Second thing, smaller: 7,458 reads as chosen, not collateral. #12431's body table assigns [Learned corrections] "the existing lessons cap (22.6% of the 33,000 base)" explicitly. _LESSONS_CAP = _budget(0.226) at context.py:1023 matches. So "value regression" is the wrong framing for a number another PR picked on purpose six hours earlier. Both AI lanes flagged this same open premise.

To clear the block, either of these works for me:

  1. Bound _LESSONS_STARTUP_CAP below max_context with enough headroom that the profile and documentation blocks still fit, and say in the body what the resulting rule allowance is; or
  2. Keep 37,000 and land a test that asserts what actually survives when the rule block is full -- if the answer is "nothing discretionary", the test should say so and the body should state it as the accepted cost, with a word from #12431's author that the 22.6% binding is being deliberately unwound.

Also needs fixing either way: docs/system-specs/modules/memory-skills-hooks.md:2782 still opens "renders in [Learned corrections] under the lessons budget (22.6% of the 33,000 base)" and then says the tier is bound by lessons_startup. The GPT lane reported it and it is unanswered.

The rest of the diff is clean -- the four renderers at :4053/:4070/:4082/:4094 all move to caps.lessons_startup consistently, and test_default_context_admission.py:479-550 does go red if any one of them is reverted.

@bolichen97
bolichen97 enabled auto-merge (squash) September 22, 2026 03:49
@bolichen97
bolichen97 merged commit 6d8fbc7 into kirodotdev:main Sep 22, 2026
96 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 22, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
kirodotdev#12657)

The startup "Learned corrections" block collapsed from ~36,900 characters to
~7,158, so only 8 of a user's 607 standing rules reached the model on a fresh
session. Nothing was deleted from the library; two landed changes combined:
`kirodotdev#11996` moved `_CONTEXT_BUDGET_BASE` from 165,000 to 33,000, shrinking every
`_budget(fraction)` cap about fivefold including `_LESSONS_CAP` (37,290 ->
7,458), and `kirodotdev#12431` then began passing `directive_budget=caps.lessons` at the
four startup lesson renderers, which binds the authored rule tier at that value
unconditionally. The fivefold cut was invisible until the second change,
because before it the background path filled the ~500,000-character protected
ceiling and dropped nothing.

Bind the startup rule tier to a window-INDEPENDENT allowance instead of a
fraction of the shared base: add `_LESSONS_STARTUP_CAP = 37_000` (the
165,000 x 0.226 allowance a 1M-window session shipped with before the base was
pinned) plus a matching `caps.lessons_startup`, and pass that as the four
startup renderers' `directive_budget`. `kirodotdev#12431`'s mechanism is kept intact;
only its value changes. No budget arithmetic moves: both stores compute the
tier as `min(directive_budget, <ceiling>)`, so `min(37,000, ceiling)` binds the
block symmetrically on the vector path (`hard_cap`) and the JSONL path (`cap`).

Tests: `test_startup_directive_tier_is_bound_by_lessons_startup_both_paths`
drives the full startup path through `ContextBuilder.build_session_context` for
both stores and pins the block above `caps.lessons` and inside
`caps.lessons_startup`; mutation-verified (reverting a renderer to
`caps.lessons` reddens it at `assert 7458 < 7027`).
`test_all_caps_at_reference_window_equal_module_constants` pins
`caps.lessons_startup == _LESSONS_STARTUP_CAP`.
`TestLessonsCap::test_over_cap_preserves_complete_explicit_rules` sized its
overflow fixture off `_LESSONS_CAP`, which the larger budget now fits, so it is
sized off `_LESSONS_STARTUP_CAP` instead -- it still proves whole-entry
trimming, full omission accounting, and the block staying inside its budget.
Measured on a synthetic 200-rule store: JSONL 36,685 characters, vector 36,571.
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
kirodotdev#12657)

The startup "Learned corrections" block collapsed from ~36,900 characters to
~7,158, so only 8 of a user's 607 standing rules reached the model on a fresh
session. Nothing was deleted from the library; two landed changes combined:
`kirodotdev#11996` moved `_CONTEXT_BUDGET_BASE` from 165,000 to 33,000, shrinking every
`_budget(fraction)` cap about fivefold including `_LESSONS_CAP` (37,290 ->
7,458), and `kirodotdev#12431` then began passing `directive_budget=caps.lessons` at the
four startup lesson renderers, which binds the authored rule tier at that value
unconditionally. The fivefold cut was invisible until the second change,
because before it the background path filled the ~500,000-character protected
ceiling and dropped nothing.

Bind the startup rule tier to a window-INDEPENDENT allowance instead of a
fraction of the shared base: add `_LESSONS_STARTUP_CAP = 37_000` (the
165,000 x 0.226 allowance a 1M-window session shipped with before the base was
pinned) plus a matching `caps.lessons_startup`, and pass that as the four
startup renderers' `directive_budget`. `kirodotdev#12431`'s mechanism is kept intact;
only its value changes. No budget arithmetic moves: both stores compute the
tier as `min(directive_budget, <ceiling>)`, so `min(37,000, ceiling)` binds the
block symmetrically on the vector path (`hard_cap`) and the JSONL path (`cap`).

Tests: `test_startup_directive_tier_is_bound_by_lessons_startup_both_paths`
drives the full startup path through `ContextBuilder.build_session_context` for
both stores and pins the block above `caps.lessons` and inside
`caps.lessons_startup`; mutation-verified (reverting a renderer to
`caps.lessons` reddens it at `assert 7458 < 7027`).
`test_all_caps_at_reference_window_equal_module_constants` pins
`caps.lessons_startup == _LESSONS_STARTUP_CAP`.
`TestLessonsCap::test_over_cap_preserves_complete_explicit_rules` sized its
overflow fixture off `_LESSONS_CAP`, which the larger budget now fits, so it is
sized off `_LESSONS_STARTUP_CAP` instead -- it still proves whole-entry
trimming, full omission accounting, and the block staying inside its budget.
Measured on a synthetic 200-rule store: JSONL 36,685 characters, vector 36,571.
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)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants