Skip to content

docs(config): document config set --local object-vs-leaf overlay write (#22755) - #22781

Merged
iamwhatever merged 2 commits into
mainfrom
fix/issue-22755-config-set-local-merge
Nov 7, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/issue-22755-config-set-local-merge

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a user changing one key in a config.local.json section stops accidentally wiping the section's other pinned keys.

Bug fix: with config.local.json holding {"slack": {"allowed_users": ["U1"]}}, kirocrew config set --local slack '{"dm_activation": "mention"}' leaves the overlay as {"dm_activation": "mention"} — allowed_users is gone. Main now prints a stderr hint naming the dropped keys after such a write (_overlay_keys_dropped), but the guide never says the dotted-leaf form keeps siblings.

Why it matters

The overlay is the file a user reaches for to pin a setting. Losing a sibling key there changes the effective config silently. For slack.allowed_users that changes who can reach the gateway, since the value then falls back to whatever config.json holds.

Not a goal

  • Adding a --merge flag or any new write behaviour. The dotted-leaf form already does the sibling-preserving write; a second way to do it is redundant (and the first cut of this PR was correctly blocked for adding one).
  • Changing the whole-object replace semantics. The replace is load-bearing: it is the only way the CLI has to remove a pinned key, since there is no config unset and config edit opens only config.json.
  • A stderr hint when a whole-object --local set drops existing keys: main already has one (cli_config._overlay_keys_dropped, config: warn on stderr when a whole-object config set --local drops existing overlay keys #25076).

What changed (motivation → approach → change)

Symptom: config set --local slack '<object>' dropped allowed_users. Root cause is not a bug in the write path — config set --local slack.dm_activation mention already sets the one leaf and keeps siblings (the path walk in _dict_set_create preserves them). The real gap is that the whole-object form's replace is a sharp edge users hit without knowing the leaf form exists.

Approach: the honest, smallest fix is to make the existing leaf form discoverable and the replace explicit, not to add a flag. So this PR is docs only:

  • The user guide src/kiro_crew/docs/configuration.md (per the Design Review note) now states that a dotted leaf keeps siblings, a whole-section object replaces and names the dropped keys on stderr, and the replace is how you remove a pinned key.
  • docs/system-specs/modules/config.md § CLI Usage gets one line pointing at cli.md's config set row, which already describes the replace and the hint.
  • No test is added: main already pins both forms (test_local_set_emitted_elsewhere_key_keeps_overlay_siblings, fix(config): refuse unknown keys on config set --local #21794, and test_config_set_local_dropped_keys.py::test_a_whole_object_write_names_the_pinned_keys_it_drops).

No production code changes.

Backwards compatibility

Removes nothing: docs only; no path, flag, record, validator, key or function changes. Behaviour on main is unchanged and now documented.

Tests

test/test_config_overlay.py:

  • Leaf form (keeps siblings): covered on main by test_local_set_emitted_elsewhere_key_keeps_overlay_siblings.
  • Whole-object replace (and its stderr hint): covered on main by test/test_config_set_local_dropped_keys.py::test_a_whole_object_write_names_the_pinned_keys_it_drops.

Manual verification

Reproduced on a scratch KIROCREW_HOME: config set --local slack.dm_activation mention left allowed_users intact; the whole-object form replaced the section. Matches the two tests on main.

Related Issues

Fixes #22755.

Related: #25076 (the stderr hint, already on main)

Pattern harvest

Not generalizable: a single CLI ergonomics gap (object-set replace vs leaf-set merge) with no recurring code class to gate on.

Checklist

  • At most two commits, Conventional Commits title
  • Existing tests pass (docs-only change; behaviour already tested on main)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (docs/system-specs/modules/config.md § CLI Usage, src/kiro_crew/docs/configuration.md)
  • No secrets, credentials, or internal references in the diff

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision abc8e9254bc151d83dcad274eb187e33c29ba272 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 added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of abc8e9254bc151d83dcad274eb187e33c29ba272 — 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 does not.

First-Principles-Verdict: PASS

This is a docs-only fix. The user-guide paragraph is the fix; the spec line repeats a pointer that is already there.

Notes

  • Item 2 — duplicate of docs/system-specs/modules/cli.md (the config set row, line 628): the new spec text repeats behaviour that row already describes, quoted as "replaces it; when that removes keys the section held, a stderr hint … names each dropped dotted key". The paragraph just before it already ends with "Details: cli (config set)." Two copies of the same description will drift apart over time. Subtraction: delete the added three-line paragraph in docs/system-specs/modules/config.md § CLI Usage; the existing link already points readers to the config set row.

What this change ships

Inventory (2 items) — 1 justified

Intent: stop users wiping a config.local.json section's other pinned keys when they change one key. This is a FIX, made through documentation.

  1. The user guide now says a dotted --local key keeps the section's other keys, a whole-object write replaces the section and names the dropped keys on stderr, and the replace is how you remove a pinned key — justified
  2. The config spec gets a new line restating cli.md's description of the --local replace and its stderr hint — duplicate of docs/system-specs/modules/cli.md config set row

[FIRST-PRINCIPLES-REVIEWED] abc8e92

Description read

[DESCRIPTION-READ] 854109ca5034160875ebc2564d08357585be1298910e6a9410085f48252dec09

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of abc8e9254bc151d83dcad274eb187e33c29ba272 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only change: the documented leaf-keeps-siblings and whole-object-replace behaviour matches cli_config._overlay_keys_dropped already on main. Nothing is taken away.

[DESIGN-REVIEWED] abc8e92

Description read

[DESCRIPTION-READ] 3fe5cc86daea8ae47ac745e9bf14b325b12ca2474d6019705d8d245750dbb3c9

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] abc8e92

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

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] abc8e92

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

@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 21, 2026
@kyleseaman
kyleseaman force-pushed the fix/issue-22755-config-set-local-merge branch from a809392 to 186cef2 Compare October 21, 2026 14:08
@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 Oct 21, 2026
@kyleseaman
kyleseaman force-pushed the fix/issue-22755-config-set-local-merge branch from 186cef2 to 6d26615 Compare October 21, 2026 16:30
@kyleseaman kyleseaman changed the title fix(config): config set --local merges object values instead of dropping sibling keys docs(config): document config set --local object-vs-leaf overlay write (#22755) Oct 21, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever
iamwhatever force-pushed the fix/issue-22755-config-set-local-merge branch from 6d26615 to 3a4912d Compare October 27, 2026 19:11
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 27, 2026
@iamwhatever
iamwhatever force-pushed the fix/issue-22755-config-set-local-merge branch from 3a4912d to f11ab78 Compare October 27, 2026 19:22
@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 27, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thanks for the review. Opened #25076 to track the deferred stderr hint for a whole-object config set --local that drops existing keys (repro and cli_config.py links included), and linked it in the description (Not a goal and Related Issues). No code change.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 4, 2026
@kyleseaman
kyleseaman force-pushed the fix/issue-22755-config-set-local-merge branch from f11ab78 to e330589 Compare November 6, 2026 18:29
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 6, 2026
@kyleseaman
kyleseaman force-pushed the fix/issue-22755-config-set-local-merge branch from e330589 to 1467668 Compare November 6, 2026 19:33
@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 Nov 6, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Updated at 1467668 (rebased onto main):

  • The tracking issue you asked for: config: warn on stderr when a whole-object config set --local drops existing overlay keys #25076 is done. The stderr hint for a whole-object config set --local that drops pinned keys is on main (cli_config._overlay_keys_dropped). The description and the user guide now say so.
  • First Principles: the new test duplicated main's test_config_set_local_dropped_keys.py::test_a_whole_object_write_names_the_pinned_keys_it_drops, so it is removed, and the config.md paragraph now points at cli.md's config set row. The PR is docs only: the user-guide paragraph on the dotted-leaf versus whole-object write is the remaining change.

@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 Nov 6, 2026
Kyle Seaman added 2 commits November 6, 2026 22:07
config set --local <section> '<object>' replacing the whole section
surprised users into dropping sibling keys (e.g. slack.allowed_users).
The dotted-leaf form (config set --local slack.dm_activation mention)
already keeps siblings via the path walk; the whole-object replace is
how a pinned key is removed, since there is no config unset.

Document both in the config spec and the user configuration guide, and
lock the whole-object replace with a regression test (the leaf form is
already covered by test_local_set_emitted_elsewhere_key_keeps_overlay_siblings).
No code change: setting a leaf is the fix for #22755.
…li.md

First Principles: main already prints the dropped-keys hint on stderr and pins the
whole-object replace in test_config_set_local_dropped_keys.py, so this PR's test
repeated it and the spec paragraph repeated cli.md's config set row. Keep the user
guide paragraph, mention the hint there, and reduce the spec text to one line.
@kyleseaman
kyleseaman force-pushed the fix/issue-22755-config-set-local-merge branch from 1467668 to abc8e92 Compare November 6, 2026 22:10
@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 Nov 6, 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.

Approving at abc8e92. Docs only: the config spec and the user guide now say that a --local dotted-leaf write keeps an overlay section's other keys, and that a whole-object write replaces the section and names the dropped keys on stderr, with the dotted form as the way to change one key. No code or regex is added.

@iamwhatever, could you re-review? Your change request at f11ab78 asked for the deferred stderr hint to be tracked. Main now prints that hint after a whole-object --local write (_overlay_keys_dropped), and this head documents it, so nothing is left untracked.

Sensitive Change Review failed on a GitHub API rate limit ("re-run this job"), not on a finding, and Publish readiness signal follows it. Both need a re-run.

@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 07:10

@iamwhatever iamwhatever 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.

Approving abc8e92.

Docs only. The user guide now says that a --local dotted-leaf write keeps an overlay section's other keys, and that a whole-object write replaces the section and names the dropped keys on stderr (configuration.md#L30-L36). That matches the code: _overlay_keys_dropped produces the hint.

The r130 blocker is resolved. The deferred stderr hint shipped on main under #25076, and Not a goal says so.

AI findings judged non-blocking:

All checks are green. The one red Publish readiness signal row is an older publish attempt, and the PR Readiness status was set to success after it.

— crew-pr-reviewer (r149)

Red check Publish readiness signal (run 42302699543) does not count: its log shows "gh: API rate limit exceeded for installation" right before "Failed to publish the readiness status", and the PR Readiness status on this head is success.

@iamwhatever
iamwhatever merged commit 9c468dd into main Nov 7, 2026
151 of 166 checks passed
@iamwhatever
iamwhatever deleted the fix/issue-22755-config-set-local-merge branch November 7, 2026 20:51
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 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.

config set --local <section> '<object>' replaces the whole overlay section and drops existing keys

3 participants