Skip to content

fix(config): report nine superseded defaults old installs still store - #16190

Merged
bolichen97 merged 2 commits into
mainfrom
fix/superseded-defaults-skills-stagger
Oct 3, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/superseded-defaults-skills-stagger

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An upgraded install that still stores an old default for one of nine settings is told so, with the old and new values and how to adopt or keep it. config defaults --adopt asks for a restart only when a key needs one.

config.json holds every value, so a stored value beats a changed default. Nine default moves shipped without a superseded-default row: skills.lazy_load, agent.subagent_spawn_stagger_secs, session.watchdog_rss_max_mb, stt.language_code, decisions.history_budget_chars and four watchdog windows. An install that wrote the old value keeps it. The load warning, doctor and kirocrew config defaults say nothing about it. Separately, config defaults --adopt always ended with "restart the gateway", even when every adopted key is applied live.

Why it matters

Operators who upgrade from 0.5.x through 0.7.x keep old behaviour they never chose, and nothing tells them. Examples: no session recycling, English-only local dictation, a slow subagent fan-out, and tool-stall windows that cancel a tool after an hour. skills.lazy_load=false is worse because its meaning changed: on 0.6.0 it selected the full skills dump, and today it selects the short eight-name entry. An operator who keeps it believing nothing changed gets different behaviour. An unnecessary restart prompt costs a gateway restart for nothing.

Not a goal

  • Rewriting any stored value automatically. All nine new rows are report-only, because each old value is a setting an operator can choose on purpose.
  • A one-shot migration that removes a materialized skills.lazy_load=false for the provable 0.6.x cohort. fix(config): migrate a 0.6.x materialized skills.lazy_load false once #16148 shipped that on main; this PR's row composes with it (see below).
  • A CI gate that fails when a dataclass default moves without a registry row. Proposed as a follow-up PR (see below).
  • Changing the reach of bare --adopt / --keep, which act on every unacknowledged drifted key. That is the documented contract.

What changed (motivation → approach → change)

Old installs keep old defaults because a stored value wins, and the registry had no row for these nine moves. The fix extends the existing registry rather than adding a new mechanism.

  • Nine report-only rows in config/superseded_defaults.py. Each gives its reason in a comment and in the spec table. Old values were checked against materialized 0.5.0, 0.6.0 and 0.7.2 configs.
  • SupersededDefault.note. doctor, the config defaults listing and the --keep confirmation append it. The --keep confirmation in src/kiro_crew/cli_config.py repeats it. skills.lazy_load, the decision budget (adopting is bounded by the consented history ceiling) and the two coupled tool-stall windows (the window is the smaller of the two, so both must be adopted) carry one.
  • meaning_moved. It is set only on skills.lazy_load, and it puts that note on the one-line load warning too, so nobody runs --keep without seeing that false now means the short entry.
  • applies predicate. stt.language_code reports en-US only where the effective stt.provider (config.local.json included) is the local recogniser. Every other provider resolves "auto" to en-US anyway. The overlay is opened only when it is a regular file, as the loader does, because this runs inside load().
  • Composes with fix(config): migrate a 0.6.x materialized skills.lazy_load false once #16148's one-shot skills.lazy_load rewrite. While that rewrite is due the load report skips the key, as before. The new registry row has the same key and old value as the rewrite's ledger entry, so adoption_summary now vouches for that entry through the row, and a value a failed write left stored is listed as drift (its replay line now says so).
  • Remedy text spells values as JSON (true, "auto"). Both stt.provider degrade notices now name --adopt stt.provider, so following them no longer also adopts the report-only rows.
  • Restart hint (commit 2, src/kiro_crew/cli_config.py). --adopt lists each removed key and asks for a restart only for keys schema.requires_restart marks and whose effective value moved: a key config.local.json still overrides runs the same value afterwards, so it gets no restart hint. dashboard.loop_stall_exit_after_secs is read only at boot, so it now carries restart=True (config-baseline.json regenerated).

Spec updates (same commits): docs/system-specs/modules/config.md now has one table listing every row with its change and reason, plus the note / meaning_moved / applies fields, the --adopt / --keep bullets and the restart-marked list. The packaged guide src/kiro_crew/docs/configuration.md is updated too.

Backwards compatibility

Compatible: no stored value is rewritten and no accepted input is rejected. New rows only add report lines. The new dataclass fields have defaults. The only behaviour change is that --adopt leaves out the restart line when no adopted key needs one.

Tests

  • test_config_superseded_defaults.py: each new row is reported, not adopted, and loads unchanged (parametrized over the seven later moves plus the 0.6.0 pair). JSON remedy spelling. The lazy_load note on every surface. Only a meaning_moved note reaches the load line. The tool-stall pair and decision-budget notes. stt.language_code with transcribe/apple (quiet), local/absent/null (reported), overlay in both directions, a malformed overlay, and a FIFO overlay that must not be opened. The adopt/report split is pinned as two exact sets. test_the_spec_table_lists_every_registered_row keeps the spec table equal to the registry.
  • test_cli_config_defaults.py: the restart hint names only restart-bound keys. There is no hint for live-only keys. A boot-only key asks for a restart. An overlay-shadowed restart-bound key does not. --keep repeats a row's note, and a row without a note prints none.
  • test_stt_provider_off.py: following each degrade notice's exact command removes only stt.provider.
  • test_config_lazy_load_legacy_migration.py: the replay of fix(config): migrate a 0.6.x materialized skills.lazy_load false once #16148's ledger entry is vouched for by the registry row and says the value is still listed as drift if the write failed.

Manual verification

N/A: unit coverage is sufficient. Every surface (load warning, doctor, config defaults listing, --adopt, --keep) is exercised in tests through its real entry point against a scratch home.

Related Issues

No tracking issue. Follow-ups, not in this PR:

  • Proposed follow-up PR: a CI check that fails when a config dataclass default changes on an existing field without a matching SUPERSEDED_DEFAULTS row. These nine moves are evidence that review alone does not catch it.

Pattern harvest

Rule candidate: lint
Pattern: a config dataclass default changes on an existing field with no superseded-default registry row, so installs that materialized the old value never learn of it.

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

Contribution License Agreement

@bolichen97
bolichen97 requested a review from a team as a code owner October 2, 2026 16:26
@bolichen97
bolichen97 requested a review from CrysisDeu October 2, 2026 16:26
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the nine old-default literals against real 0.5.x–0.7.x materialized configs; a wrong value or type makes its row silently never fire.

[DESIGN-REVIEWED] 0de4426

Description read

[DESCRIPTION-READ] 4a879d28213d4ce97d9c08532ce21128815b0c9350343201b2cc8fec9886af91

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

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 0de4426208a68510d4cd57a4d87edaf0ef003f92 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0de4426

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

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 0de4426208a68510d4cd57a4d87edaf0ef003f92 — 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 the nine old-default literals against real materialized 0.5.0/0.6.0/0.7.2 configs — a wrong byte (e.g. 2.0 vs 2) makes its row silently inert.

The change extends the one existing mechanism (the SUPERSEDED_DEFAULTS registry) rather than adding a parallel one; current dataclass defaults match every claimed new value (verified in sections.py, service_sections.py, memory_sections.py); the rewritten pin in test_config_lazy_load_legacy_migration.py ("this key has no registry row to list it") is reversed by the diff itself adding that row, and the description declares it. The deferred CI gate (root cause: nothing forces a row when a default moves) is named in the description as a follow-up, which is the accepted form.

What this change ships

Inventory (10 items) — 10 justified

Intent: tell upgraded installs they still store nine old defaults, and stop --adopt demanding a restart it doesn't need — a FIX.

  1. Nine stored old defaults now reported by the load warning, doctor and config defaults — justified
  2. Four rows carry a one-sentence note on doctor, the listing and --keep — justified
  3. The skills.lazy_load note also reaches the one-line load warning (meaning_moved) — justified
  4. stt.language_code reported only where the local recogniser effectively runs (applies, overlay read) — justified
  5. --adopt asks for a restart only for restart-bound keys whose effective value moved — justified
  6. dashboard.loop_stall_exit_after_secs now marked restart-required (boot-only read) — justified
  7. STT degrade notices now name --adopt stt.provider, not bare --adopt — justified
  8. A failed legacy lazy_load rewrite now stays listed as drift; the legacy entry is vouched through the new row — justified
  9. Remedy text spells values as JSON (true, "auto") the way config.json takes them — justified
  10. The spec's row table is pinned equal to the registry by a new test — justified

[FIRST-PRINCIPLES-REVIEWED] 0de4426

Description read

[DESCRIPTION-READ] e3a621a01e8cdae814bbdd30e1eae6d13d41be218989913b3dbedeaef2e8b4fb

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

Nothing blocks; one advisory on an operator-facing cap claim that no test measures.

FINDING — src/kiro_crew/config/superseded_defaults.py:233 — the new _TOOL_STALL_PAIR_NOTE ships an actionable cap relationship to kirocrew config defaults, doctor and the --keep confirmation ("the tool-stall window is the smaller of watchdog.tool_stall_suspect_secs and watchdog.tool_stall_hard_cap_secs ... adopt both to get the current 5400-second window"), but its only pin re-implements the arithmetic over the registry's own literals (assert min(suspect.new_default, cap.old_default) == cap.old_default) instead of measuring session_handle.py's _full_suspect = min(_suspect, wd.tool_stall_hard_cap_secs), which is the an-operator-facing-string-states-what-was-measured shape (blocking: false) — the same note is repeated in docs/system-specs/modules/config.md's table, and decisions.history_budget_chars's note is pinned only by "ceiling" in row.note and "consent" in row.note rather than by gate.history_budget_chars's min(asked, ceiling) → Fix: drive session_handle's window selection with (suspect=5400, cap=3600) and (suspect=3600, cap=7200) asserting 3600 both ways, and the decision gate with history_budget_chars=2000 against a recorded consent of 0 asserting 0, and assert the falsified direction too.

[OPUS-REVIEWED] 0de4426

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

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

config.json is a full materialization, so a stored value beats a
changed default and an install keeps whatever it last wrote. Nine
default moves shipped with no superseded-default row, so nothing told
an upgraded install it still held the old value:

- skills.lazy_load false -> true (#12131)
- agent.subagent_spawn_stagger_secs 2.0 -> 0.25 (#12203)
- session.watchdog_rss_max_mb 0 -> 1536 (#9626)
- stt.language_code "en-US" -> "auto" (#9246)
- decisions.history_budget_chars 0 -> 2000 (#12928)
- the four watchdog windows #8949 widened

All nine are report-only: each old value is a setting an operator
makes on purpose, and each row states its reason and what holding the
old value costs.

A row can now carry a note, which doctor, config defaults and the
--keep confirmation show. The decision budget's note says adopting is
bounded by the consented history ceiling. The two tool-stall windows
share one: the session waits the smaller of the two, so adopting one
while the other holds 3600 leaves the window at an hour.

skills.lazy_load also changed meaning: false was the full skills dump
on 0.6.0 and now selects the short eight-name entry. Its row is marked
meaning_moved, which puts its note on the one-line load warning too,
so keeping false is not mistaken for keeping the old behaviour. No
other note reaches that line.

A row can also carry an applies predicate. stt.language_code uses it:
only the local recogniser auto-detects, so where the effective
provider (config.local.json included) is another one, a stored
"en-US" already behaves like the default and is not reported.

Both stt.provider load notices now name the key they mean
(--adopt stt.provider), so following them no longer also removes the
report-only values above.

The remedy now spells values as JSON (true, "auto"), the way
config.json takes them. The spec's one table lists every row with its
change, and a test keeps it equal to the registry. The adopt/report
split is pinned as two exact sets.
kirocrew config defaults --adopt always ended with "restart the
gateway", even for keys a running gateway takes live through the
config watcher, which costs operators a restart for nothing.

The hint now names exactly the adopted keys the schema marks
restart=True, the one statement of which fields a running gateway
cannot adopt, and is omitted when there are none. Each removed key is
still listed.

dashboard.loop_stall_exit_after_secs is read once at boot to build the
loop-stall watchdog and has no applier, so it now carries the mark.
Without it, adopting that key would have printed no restart hint while
the running gateway kept the old budget. The packaged configuration
guide and the spec's marked list say the same.
@bolichen97
bolichen97 force-pushed the fix/superseded-defaults-skills-stagger branch from c7b92d5 to 0de4426 Compare October 2, 2026 20:42
@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 Oct 2, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b48f5888cbf1 src/kiro_crew/config/superseded_defaults.py:192 overlay read in the language row

Outcome: FIXED.
_overlay_stt_provider now opens config.local.json only when is_file() holds, the same guard the loader's own overlay readers use, and otherwise returns "no overlay value" so the base provider decides.
Test: test_a_fifo_overlay_is_not_opened_by_the_language_row plants a FIFO at the overlay path and runs the drift check on a thread with a bounded join; it fails (the thread blocks) with the guard removed and passes with it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=a1c24af5df65 src/kiro_crew/cli_config.py:570 restart hint for an overlay-shadowed key

Outcome: FIXED.
restart_bound now leaves out keys config.local.json still carries: removing the base copy does not move the effective value, so a restart would change nothing.
Test: test_an_overlay_shadowed_restart_bound_key_asks_for_no_restart adopts mcp_gateway.forward_declared_env (marked restart) while the overlay sets it, and asserts no restart line.

@bolichen97

bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=ed69f4851379 src/kiro_crew/config/superseded_defaults.py:420 legacy lazy_load entry now vouched by the registry row

Outcome: FIXED.
Rebased onto main (which carries #16148). adoption_summary now vouches only through SUPERSEDED_DEFAULTS: the new skills.lazy_load row has the same key and old value as LEGACY_LAZY_LOAD_ADOPTION, so the tuple branch and its per-entry "listed" flag are gone. The replay line's "still listed as drift" is now true: with the ledger naming the key the rewrite is no longer due, so the load report and config defaults list a value a failed write left stored.
The constant's comment, the docstring, both config.md paragraphs and test_doctor_replays_the_rewrite_with_a_restore_command were updated; the test now also pins that the registry row and the constant agree.

@bolichen97

bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=60b796201d67 docs/system-specs/modules/config.md:551 note-row count

Outcome: FIXED.
The count is gone (a restated count goes stale); the paragraph now names skills.lazy_load alongside the decision budget and the tool-stall pair. The PR body was corrected the same way.

@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 2, 2026
@iamwhatever
iamwhatever added this pull request to the merge queue Oct 2, 2026
@bolichen97
bolichen97 merged commit c0671f5 into main Oct 3, 2026
97 checks passed
@bolichen97
bolichen97 deleted the fix/superseded-defaults-skills-stagger branch October 3, 2026 01:44
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 3, 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