Repository navigation
docs(config): document config set --local object-vs-leaf overlay write (#22755) - #22781
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of 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
What this change shipsInventory (2 items) — 1 justifiedIntent: stop users wiping a
[FIRST-PRINCIPLES-REVIEWED] abc8e92 Description read[DESCRIPTION-READ] 854109ca5034160875ebc2564d08357585be1298910e6a9410085f48252dec09 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Docs-only change: the documented leaf-keeps-siblings and whole-object-replace behaviour matches [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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
a809392 to
186cef2
Compare
186cef2 to
6d26615
Compare
6d26615 to
3a4912d
Compare
3a4912d to
f11ab78
Compare
|
Thanks for the review. Opened #25076 to track the deferred stderr hint for a whole-object |
f11ab78 to
e330589
Compare
e330589 to
1467668
Compare
|
Updated at 1467668 (rebased onto main):
|
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.
1467668 to
abc8e92
Compare
bolichen97
left a comment
There was a problem hiding this comment.
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.
iamwhatever
left a comment
There was a problem hiding this comment.
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:
- First Principles: the config.md paragraph repeats the cli.md
config setrow. It is a three-line summary that ends in a pointer to that row, so this is a docs nit with no user harm.
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.
Problem / Motivation
Goal: a user changing one key in a
config.local.jsonsection stops accidentally wiping the section's other pinned keys.Bug fix: with
config.local.jsonholding{"slack": {"allowed_users": ["U1"]}},kirocrew config set --local slack '{"dm_activation": "mention"}'leaves the overlay as{"dm_activation": "mention"}—allowed_usersis 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_usersthat changes who can reach the gateway, since the value then falls back to whateverconfig.jsonholds.Not a goal
--mergeflag 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).config unsetandconfig editopens onlyconfig.json.--localset 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>'droppedallowed_users. Root cause is not a bug in the write path —config set --local slack.dm_activation mentionalready sets the one leaf and keeps siblings (the path walk in_dict_set_createpreserves 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:
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 atcli.md'sconfig setrow, which already describes the replace and the hint.test_local_set_emitted_elsewhere_key_keeps_overlay_siblings, fix(config): refuse unknown keys on config set --local #21794, andtest_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:test_local_set_emitted_elsewhere_key_keeps_overlay_siblings.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 mentionleftallowed_usersintact; 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
docs/system-specs/modules/config.md§ CLI Usage,src/kiro_crew/docs/configuration.md)