Skip to content

fix(config): migrate a 0.6.x materialized skills.lazy_load false once - #16148

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/lazy-load-provable-migration
Oct 2, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/lazy-load-provable-migration

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An install upgrading straight from 0.6.x or earlier gets the default skill index instead of the short skill entry it never chose.

0.6.x and earlier wrote every default into config.json, and their skills.lazy_load default was false, which then meant the full skills listing. #11996 changed what false means (it now selects the short entry naming only the hottest skills) and #12131 made true the default. A stored value beats the default, so on an upgraded install the false nobody chose now selects the narrowest skills mode, with no notice.

Why it matters

Every 0.6.x install that upgrades past 0.7 loses most of its skills from session start. The agent can still search for them, but nothing tells the operator why skills stopped showing up, and nobody on 0.6.x could have chosen this mode because it did not exist yet.

Not a goal

  • Rewriting false on installs that have already run any 0.7 build. There, false may be a deliberate choice of the short entry, so they keep their value (the report row in the paired PR below covers them).
  • Adding the report-only skills.lazy_load row to SUPERSEDED_DEFAULTS. That is branch fix/superseded-defaults-skills-stagger, driven separately.
  • A generic version-bounded migration framework.

What changed (motivation → approach → change)

An install upgrading straight from 0.6.x now starts with the default skill index instead of the short entry, because its stored false was written when false still meant "show every skill". Installs that have already run 0.7 or later keep their value.

Comparing values cannot tell a materialized false from a chosen one. The time it was written can, using the same boundary #9600 used for connections_ui. That migration's marker, connections_ui_migrated.json, first shipped in 0.7.0-insider.1, and every later clean load writes it.

So a config load (config/loader.py, deciding through config/migration.py) removes a stored skills.lazy_load: false once, and only when all of these hold:

  • meta.lastTouchedVersion names 0.6.x or older;
  • the marker is absent;
  • the adoption ledger is readable and does not already name the key.

The load decides on the base config.json before anything re-stamps it. The gateway's meta-stamp refresh holds off while the rewrite is still due, so a degraded first boot keeps the proof for the next clean load.

The removal goes through the existing adoption write-back:

  • it is re-checked inside the config write lock;
  • it is recorded in the ledger before the key is removed, in one record together with any other adoption that pass makes;
  • the in-memory value changes only after the write is confirmed, and not where config.local.json sets the key.

One WARNING names the key, the version that wrote it, and the command to choose the short entry. doctor and kirocrew config defaults replay the ledger entry with a restore command (config/superseded_defaults.py). A missing or unreadable stamp, an existing marker, an explicit true, or any non-boolean value stays as stored.

Stored config.json Before After
stamp 0.6.x, no marker, lazy_load: false 🟦 short entry, silently 🟩 key removed once, default index, one WARNING, ledger entry
stamp 0.7+ or marker present, false 🟦 short entry 🟦 unchanged
missing or unparsable stamp, false 🟦 short entry 🟦 unchanged
any stamp, lazy_load: true 🟦 index 🟦 unchanged
degraded first 0.9 boot over a 0.6.x config 🟦 stamp refreshed 🟨 stamp held until a clean load migrates

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

Pairs with branch fix/superseded-defaults-skills-stagger, which adds a report-only superseded-default row for skills.lazy_load. Without it, this PR leaves the excluded cohort silent. With it, that cohort is reported, and this loader already skips the key in the same load's report when it is the one being removed. Whichever lands second should make the row's text say that installs provably written by 0.6.x were migrated.

Specs updated: docs/system-specs/modules/config.md (new "The legacy skills.lazy_load rewrite" subsection, the module table, the default-context note), docs/system-specs/modules/memory-skills-hooks.md (discovery), and src/kiro_crew/docs/configuration.md ("When a Shipped Default Changes").

Backwards compatibility

Compatible: only a stored skills.lazy_load: false in a config provably last written by 0.6.x or earlier is removed, and only once. Every other config loads exactly as on main. The ledger sidecar gains one possible adopted key, which older readers already tolerate.

Tests

test/test_config_lazy_load_legacy_migration.py:

  • a 0.6.0 config is migrated once, and a second load leaves the config bytes, the ledger and the log unchanged;
  • every pre-0.7 stamp shape is accepted (0.5.0, 0.6.2, -insider.N, .N builds, rc1);
  • 0.7+ stamps are left alone and still reported when a registry row exists, and the migrated cohort is not;
  • an existing marker blocks the rewrite, and so do an explicit true and non-boolean values;
  • 10 missing or unparsable meta shapes do not migrate, and the marker still lands;
  • an unreadable ledger does not migrate, and an existing ledger entry keeps it one-shot without the marker;
  • a deferred write defers both the rewrite and the marker, then migrates on the next load;
  • an overlay value wins in memory;
  • a degraded first load keeps the stamp past refresh_config_meta_stamp, which still refreshes outside the cohort;
  • the in-lock re-checks of both value and stamp hold, a failed ledger record aborts the removal, and one record carries every removal of the pass;
  • doctor replays the entry with a lowercase false.

Mutation-checked: removing or inverting each of the 16 guards fails at least one test.

Manual verification

N/A: unit coverage is sufficient. The behaviour is a pure function of config.json, the marker and the ledger, and the tests drive real KiroCrewConfig.load() and refresh_config_meta_stamp() against a scratch home.

Related Issues

no linked issue: found while auditing upgrade behaviour of superseded defaults. Pairs with branch fix/superseded-defaults-skills-stagger (report-only row). Follows the #9600 precedent; addresses fallout from #11996 / #12131.

Pattern harvest

Not generalizable: the rewrite is sound only because the meaning of false changed at a release boundary that an existing marker already records. Most default changes have no such boundary and stay report-only.

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

@bolichen97
bolichen97 requested a review from a team as a code owner October 2, 2026 11:29
@bolichen97
bolichen97 requested a review from CrysisDeu October 2, 2026 11:29
@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 aa03dc973003483f06b326f08cd0b5dc2d6f05e8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm from release history that no pre-0.7 build ever wrote connections_ui_migrated.json — the entire proof-of-cohort rests on that one fact.

[DESIGN-REVIEWED] aa03dc9

Description read

[DESCRIPTION-READ] a2384602d6c697bf7b0e7a44271cbb9372854035ec42c756a8174da5eb0a73fc

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

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of aa03dc973003483f06b326f08cd0b5dc2d6f05e8 — 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 in release history that connections_ui_migrated.json first shipped in 0.7.0-insider.1, before the meaning change — the cohort proof rests on that unrecorded claim.

What this change ships

Inventory (9 items) — 9 justified

Intent: an install upgrading straight from 0.6.x gets the default skill index instead of the short skill entry it never chose — a FIX.

  1. A skills.lazy_load: false provably last written by 0.6.x is removed once on upgrade; the default index applies — justified
  2. One WARNING names the key, the writing version, the value now applying, and the restore command — justified
  3. doctor and kirocrew config defaults replay the removal with a restore command — justified
  4. The gateway's meta-stamp refresh holds while the rewrite is pending, so a degraded first boot keeps the proof — justified
  5. The superseded-defaults report skips the key on the load removing it (effective once the paired report-only row lands) — justified
  6. Every removal of one pass lands as a single ledger record — justified
  7. Restore commands spell boolean values as lowercase JSON — justified
  8. A fail-closed ledger reader (adopted_superseded_if_readable), also consumed by the existing adoption path — justified
  9. The user-facing configuration doc gains the one-time-fix note — justified

The marker-version claim is the one load-bearing premise with no record on the base (CHANGELOG and specs name the migration but not its first shipping build); grepped 0.7.0-insider repo-wide — only this PR's own text asserts it. If wrong in the late direction, an early-0.7 operator's chosen false is removed — warned, ledgered, one-command restorable, so bounded and reversible.

[FIRST-PRINCIPLES-REVIEWED] aa03dc9

Description read

[DESCRIPTION-READ] 691bd536aa9bda7a01bab66abe27c6164124a0d05c57ed81794dbadba9d8c18f

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

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] aa03dc9

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

@bolichen97

bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=1406acaca664 rebutted: 0.6.x builds do stamp meta.lastTouchedVersion

Verified against the v0.6.0 tag source: git show v0.6.0:src/kiro_crew/config/loader.py defines stamp_config_meta (line 1360) writing "lastTouchedVersion": __version__, and every full-rewrite writer calls it (lines 803, 1301, 3983: save() writes stamp_config_meta(d)).
v0.6.0's __version__ is "0.6.0" (git show v0.6.0:src/kiro_crew/__init__.py), and the stamp has shipped since v0.1.0 (rename commit 849a03f).
v0.6.0 also defaulted lazy_load to False (git show v0.6.0:src/kiro_crew/config/loader.py line 3712), so a 0.6.x save materializes exactly the stamped document the tests fabricate.
self-added: no

@bolichen97

bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=8d069c655352 rebutted: merge order is the maintainers' call, and either order is safe

This PR never merges anything, and the paired report-only row lives on another branch that another workflow is driving, so landing order is outside what this PR can decide. The body flags the pairing so the merger sees it.
Either order is safe. Alone, this PR strictly reduces the harm, because the provable cohort is fixed and every other install behaves exactly as on main. Alone, the row reports every cohort. Together, the loader already skips the key in the same load's report when it is the one being removed (pinned by test_the_report_skips_the_key_the_same_load_is_removing).
self-added: no

@bolichen97

bolichen97 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=c9bdb41b871f rebutted: the report skip is the pairing seam, kept on purpose

On main it is inert, as noted. It exists so that the moment the paired report-only row lands, whatever the merge order, the first upgraded load does not print "skills.lazy_load still holds a superseded default, run config defaults" on the same load that removes it. That is the same reason skip= already exists for auto-adopted keys.
It is two lines, it is pinned by test_the_report_skips_the_key_the_same_load_is_removing (the mutation check kills its removal), and dropping it would leave the paired PR owing a loader change in a file it does not touch.
self-added: yes
mechanism: report_skip.add(LAZY_LOAD_KEY) when the legacy rewrite is due

@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 aa03dc973003483f06b326f08cd0b5dc2d6f05e8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] aa03dc9

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

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

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 2, 2026
0.6.x and earlier materialized every default into config.json, and their
skills.lazy_load default was false -- the full skills listing. #11996
moved what false means (the short eight-name entry) and #12131 flipped
the default to true, so an upgraded install silently runs the narrowest
mode on bytes nobody chose.

Value equality cannot tell that noise from a choice made on a 0.7+
build, but WHEN the value was written can, the same boundary #9600 used
for connections_ui. A load removes a stored false once, only when
meta.lastTouchedVersion names 0.6.x or older AND connections_ui_migrated
.json (first shipped in 0.7.0, written by every clean 0.7+ load) is
absent AND the adoption ledger is readable and does not already name the
key. The decision is taken on the base document before any write or the
gateway's meta refresh re-stamps it.

The removal rides the adoption write-back: re-detected inside the config
write lock, ledger entry first, in-memory value moved only once the
write is confirmed and only where the overlay does not supply the key,
cache dropped and marker deferred when the write does not land. One
WARNING names the key, the writer's version and the command that picks
the short entry; doctor replays the ledger entry with a restore command.
An install that has already run 0.7.x, or whose stamp is missing or
unreadable, keeps its value and stays report-only.
@bolichen97
bolichen97 force-pushed the fix/lazy-load-provable-migration branch from a867c64 to aa03dc9 Compare October 2, 2026 12:06
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=964a6ea5f43f fixed: the rewrite WARNING no longer claims the default applies when config.local.json sets the key

Fixed in aa03dc9. loader.py now computes overlay_sets_it once. The WARNING says "config.local.json still sets the key, and its value applies." in that case and "The current default (the ranked skill index) applies." otherwise. The same flag gates the in-memory flip.
Pinned by test_an_overlay_value_wins_in_memory (asserts the overlay wording and the absence of the default claim) and by test_a_0_6_config_holding_false_is_migrated_once (asserts the default wording).
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=964a6ea5f43f rebutted: a real write by this build is meant to end the cohort; only the no-op refresh is held

refresh_config_meta_stamp is held because it changes nothing but the stamp. The bytes on disk are still the 0.6.x build's, so keeping the stamp is true and keeps the proof.
update_config_locked and save() are real writes by this build: a settings save or config set may be the operator choosing false under its current meaning. Holding the stamp across them would let the next load remove a value set on this build. Preventing that is the reason the in-lock re-check reads the stamp at all (pinned by test_the_transform_re_checks_the_stamp_inside_the_lock).
The residual is a missed improvement, never a destroyed choice. aa03dc9 documents it in config.md ("So does any other real write by this build during a degraded session").
self-added: yes

@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 readiness: checking Automated validation is still running labels Oct 2, 2026
@chenmingwei23
chenmingwei23 merged commit e3027e6 into main Oct 2, 2026
185 of 189 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/lazy-load-provable-migration branch October 2, 2026 16:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 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