Skip to content

fix(config): render the adoption ledger and stop the degraded-load re-read - #11176

Merged
iamwhatever merged 1 commit into
mainfrom
fix/superseded-adopt-warning-10082
Sep 17, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/superseded-adopt-warning-10082

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

What

Closes the follow-ups recorded on #10082 after #9659 merged. The blocking-class item there (the adoption notice logged below the default level) was already fixed by #10367; this PR takes the rest:

  • kirocrew doctor (Stored Defaults) and a bare kirocrew config defaults now list what auto-adoption removed: one adopted: line per key with the removed value and the exact kirocrew config set <key> <old> restore command, rendered through a new shared adoption_summary(). adopted_superseded() gains its non-test caller and the doctor line record_adoptions promises now exists.
  • The degraded-sections branch of _load_resolved no longer drops the validated-data cache. Its retry condition is "the operator fixes the file", not "the next load", so the invalidation only forced a re-read and re-parse of config.json on every load() for as long as a malformed section coexisted with a stored stale timeout. Fixing the file changes its fingerprint, which misses the cache and retries the adoption on that load with no invalidation.
  • The three comments still describing the removed ledger-rollback scheme (_apply_document_migrations bullet 3, _persist_config_migration, adopted_superseded docstring) are rewritten to match what record_adoptions actually does (marker first, nothing rolled back, only landed removals confirmed in memory).
  • config.md states the downgrade residual: a pre-ledger build's --keep/--adopt serializes {"acked": ...} only, so a downgrade-then-write re-arms the one-shot on the next upgrade.
  • test_a_non_plain_leaf_is_still_replaced_rather_than_refused (unguarded duplicate of the POSIX-only symlink test) and test_every_adopting_key_clears_in_one_load (duplicate of test_both_timeout_keys_adopt_in_one_load) are deleted. test_the_loader_has_no_second_spelling_of_the_stored_value_lookup no longer asserts inspect.getsource text or the absence of a retired name; it pins the behaviour (the ledger entry the loader records equals the exported lookup's answer).

Why

An automatic rewrite of an operator-owned file was announced by one WARNING line in one gateway log and then nowhere else -- an operator asking "what did the upgrade change in my config" a week later had no surface to ask. The degraded-branch invalidation defeated the config cache for the whole life of a process on exactly the installs that already had a broken file. The stale comments contradicted record_adoptions and config.md, and the two duplicate tests cost a non-admin Windows dev box a red run.

How

  • superseded_defaults.py: adoption_summary(dotted_key, removed) treats both fields as untrusted (the sidecar is a file the agent sandbox can write): every character is rendered terminal-safe (control characters escaped via str.isprintable, same approach as snapshot._terminal_safe), and the pasteable restore command is built ONLY from SUPERSEDED_DEFAULTS literals after matching the entry by key and exact value -- no quoting scheme is portable across every shell an operator might paste into (POSIX quoting leaves cmd.exe metacharacters live), so an entry the registry does not vouch for is shown escaped with no command. It says "removed from config.json", not "the default applies", because the overlay may still carry the key, and notes the marker-first window (a failed config write leaves the value stored and still listed as drift). render_doctor_section prints the ledger BEFORE opening config.json, so a missing or unreadable config does not hide it. adopted_superseded docstring corrected.
  • cli_config.py: on a bare listing (no --adopt, --keep or named keys) _print_adopted() runs BEFORE config.json is opened, so a missing or corrupt config cannot hide the ledger. Not folded into the known set that --adopt/--keep validate against -- an adopted key has no stored value to act on.
  • loader.py: finally condition is adopt_keys and not adoption_landed and not cfg._degraded_sections; the comment names the real retry condition (fix the file AND restart -- degradation observations are sticky for the life of a process); the two stale comments rewritten.
  • config.md: cache paragraph now names two skip paths and the deliberate exclusion; new paragraphs on the on-demand rendering and the downgrade residual.

Tests

Red on the unmodified base, green after (python -m pytest -n0 test/test_config_superseded_defaults.py test/test_cli_config_defaults.py, 104 passed):

  • test_a_degraded_load_keeps_its_document_cached_instead_of_re_reading_forever -- reaches the branch deterministically via publish.allowed_destinations: "not-a-list" (the one shape the schema layer keeps and the loader then degrades); asserts the cache entry survives, a second load performs zero config.json reads, and a fixed file retries the adoption through the fingerprint miss. Base: a degraded load must stay cached.
  • test_doctor_lists_what_auto_adoption_removed_and_how_to_restore_it -- base: no adopted: line.
  • test_listing_shows_what_auto_adoption_already_removed (CLI) -- base: key absent from output.
  • test_adoption_summary_cannot_drive_the_terminal_or_offer_a_hostile_command -- an OSC 52 sequence in the key and a & calc & value reach the output as visible \\x1b/\\x07 escapes with NO config set command; a registered key with an unregistered value or type gets no command either; a registry-vouched entry gets the command spelled from registry literals.
  • test_doctor_renders_the_ledger_even_when_config_json_is_gone, test_listing_renders_the_ledger_even_without_a_config_file, test_listing_renders_the_ledger_before_a_corrupt_config_is_refused -- ledger shown with a missing and with a corrupt config.json, on both surfaces.
  • test_doctor_says_nothing_about_adoption_when_none_happened, test_an_adopted_key_is_not_an_adopt_or_keep_target pin the negative space.
  • Mutation: the base tree IS the mutant for each of the three behaviour changes (condition without the degraded exclusion; no ledger rendering) and each new test fails there as listed.

Gates run locally: black --check on all six files, flake8 on the four smaller ones, scripts/check_black_formatting.py (diff-scoped, post-commit), scripts/check_comment_history.py, scripts/docs_lint.py, prepare-pr preflight.py and push_guard.py --max-ahead 2.

Other

Backend-only (CLI/doctor text and a loader condition); no-screenshots label applied. Single commit.

Pattern harvest

Rule candidate: config cache invalidation
Pattern: invalidate a fingerprinted cache only where the retry condition is "next load"; when the retry condition is "the file changes", the fingerprint already misses and an invalidation is pure re-parse cost.

Closes #10082

@CrysisDeu
CrysisDeu requested a review from a team September 16, 2026 03:31
@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the fix-without-restart path: the new degraded test simulates restart via reset_degraded_observations(), so in-process fix behavior stays unpinned.

Suggestions

  • _print_adopted and the render_doctor_section loop are the same sorted-ledger render twice; folding the loop into one shared helper keeps the two surfaces from drifting apart in wording later.

[DESIGN-REVIEWED] 443b5cd

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 443b5cd

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

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 443b5cd58a7a35aa0fd1b9ab4ec4867d6bfc2f81 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 443b5cd

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

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

@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 Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 443b5cd58a7a35aa0fd1b9ab4ec4867d6bfc2f81 — 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: CONCERNS

_terminal_safe ships as a byte-identical second copy of snapshot._terminal_safe, and a loader comment still asserts the cache-drop this PR removes.

Not justified as shipped

  • Item 4 — duplicate of src/kiro_crew/snapshot.py:1311: the new _terminal_safe (superseded_defaults.py:917) is character-for-character the same function; the description itself says "same approach as snapshot._terminal_safe". Grepped _terminal_safe|isprintable: 2 identical definitions that will now diverge independently.
    Subtraction: delete one copy; keep the single definition in whichever module the import graph allows and import it from the other.
    Clears when: one definition remains, or the import direction is shown to force both copies.
  • Item 6 — symptom-level, 1 counted unfixed sibling: the rewrite fixed three stale comments but loader.py:4568-4571 still says "the degraded-sections branch below … drops the cache in the finally" — the exact behavior this PR removes (not cfg._degraded_sections now excludes it).
    Subtraction: delete the false "the degraded-sections branch below" clause from that comment.
    Clears when: that comment no longer names the degraded branch as a cache-dropping path.

What this change ships

Inventory (10 items) — 8 justified

Intent: give operators an on-demand answer to "what did the upgrade auto-remove from my config and how do I restore it", and stop degraded loads from defeating the config cache — a FIX (follow-ups recorded on linked issue #10082).

  1. kirocrew doctor lists each auto-adopted key with its exact restore command — justified
  2. Bare kirocrew config defaults lists the same adoption ledger — justified
  3. Ledger prints before config.json opens, so a missing or corrupt config cannot hide it — justified
  4. Hostile sidecar bytes render escaped; unvouched entries get no pasteable command — duplicate of src/kiro_crew/snapshot.py:1311
  5. A degraded load keeps its document cached instead of re-reading on every load — justified
  6. Three stale ledger-rollback comments rewritten — symptom-level: 1 unfixed sibling at loader.py:4568-4571
  7. config.md documents the cache exclusion, on-demand rendering, and downgrade residual — justified
  8. Two duplicate tests deleted, both covered by named guarded siblings (test lines 500, 1286) — justified
  9. Source-text lookup pin rewritten as a behavioural pin on the same guarantee — justified
  10. New tests pin the ledger rendering, escaping, and cache retention — justified

[FIRST-PRINCIPLES-REVIEWED] 443b5cd

@CrysisDeu
CrysisDeu force-pushed the fix/superseded-adopt-warning-10082 branch from f3c50f4 to 1c656c5 Compare September 16, 2026 03:44
@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 Sep 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/superseded-adopt-warning-10082 branch from 1c656c5 to 4c1bcf9 Compare September 16, 2026 03:53
@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 Sep 16, 2026
…-read (#10082)

The operator-visible WARNING for an auto-adopted superseded default landed
in #10367; this closes the remaining follow-ups recorded on #10082:

- `kirocrew doctor` and a bare `kirocrew config defaults` now render the
  sidecar's `adopted` map (key, removed value, exact restore command) through
  a shared `adoption_summary`, so `adopted_superseded()` has its non-test
  caller and the `doctor` line `record_adoptions` promises exists.
- The degraded-sections branch no longer drops the validated-data cache: its
  retry condition is "fix the file", and fixing the file misses the cache by
  fingerprint, so the invalidation only re-read and re-parsed config.json on
  every load while a malformed section coexisted with a stale timeout.
- Three comments describing the removed ledger-rollback scheme are rewritten
  to match `record_adoptions` (marker first, nothing rolled back).
- config.md states the downgrade residual (a pre-ledger build's `--keep` /
  `--adopt` rewrites the sidecar without `adopted`, re-arming the one-shot).
- Two duplicate tests deleted (one an unguarded copy of a POSIX-only symlink
  test), and the loader-source-text test rewritten to pin behaviour.

Closes #10082
@CrysisDeu
CrysisDeu force-pushed the fix/superseded-adopt-warning-10082 branch from 4c1bcf9 to 443b5cd Compare September 16, 2026 04:08
@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 Sep 16, 2026
@iamwhatever
iamwhatever merged commit e2e6e99 into main Sep 17, 2026
82 checks passed
@iamwhatever
iamwhatever deleted the fix/superseded-adopt-warning-10082 branch September 17, 2026 01:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…-read (kirodotdev#10082) (kirodotdev#11176)

The operator-visible WARNING for an auto-adopted superseded default landed
in kirodotdev#10367; this closes the remaining follow-ups recorded on kirodotdev#10082:

- `kirocrew doctor` and a bare `kirocrew config defaults` now render the
  sidecar's `adopted` map (key, removed value, exact restore command) through
  a shared `adoption_summary`, so `adopted_superseded()` has its non-test
  caller and the `doctor` line `record_adoptions` promises exists.
- The degraded-sections branch no longer drops the validated-data cache: its
  retry condition is "fix the file", and fixing the file misses the cache by
  fingerprint, so the invalidation only re-read and re-parsed config.json on
  every load while a malformed section coexisted with a stale timeout.
- Three comments describing the removed ledger-rollback scheme are rewritten
  to match `record_adoptions` (marker first, nothing rolled back).
- config.md states the downgrade residual (a pre-ledger build's `--keep` /
  `--adopt` rewrites the sidecar without `adopted`, re-arming the one-shot).
- Two duplicate tests deleted (one an unguarded copy of a POSIX-only symlink
  test), and the loader-source-text test rewritten to pin behaviour.

Closes kirodotdev#10082
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-screenshots PR has no visual delta; screenshot gate exempt

Projects

None yet

Development

Successfully merging this pull request may close these issues.

config: superseded-default auto-adoption mutates config.json below the default log level (follow-up to #9659)

2 participants