Skip to content

fix(config): warn when a section key looks like a misspelled field - #19032

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/config-warn-unknown-nested-key
Oct 11, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/config-warn-unknown-nested-key

Conversation

@javenciu

@javenciu javenciu commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A key inside a config section that looks like a misspelled field is reported at load, naming the field it resembles.

A key inside a modelled section that no field reads loads with no warning. For example, agent.subagent_timeout_sec sits beside the real field agent.subagent_timeout_secs.
The setting the operator meant keeps its default, and the only trace is a DEBUG line from capture_extra_section_keys (src/kiro_crew/config/resolution.py).
A misspelled top-level section, by contrast, is reported at WARNING (Config: unrecognized top-level keys: ...).

Why it matters

A typo in a hand edit (kirocrew config edit, any editor) or in config set --local looks like a setting that does nothing, with no signal to the operator.
The dashboard settings view hides unknown keys on purpose (drop_extra_section_keys), so the typo cannot be spotted there either.

Not a goal

  • Reporting every unknown nested key. A key with no close field stays at DEBUG. A config file can carry keys an older build wrote that this build does not model: every shipped fixture config under src/kiro_crew/tests_fixtures carries dashboard.host, for example, and warning about those would report the product's own bookkeeping as an operator mistake.
  • Changing the round-trip. capture_extra_section_keys still keeps every unknown key, and save() still writes it back.
  • The kirocrew config set --local path (src/kiro_crew/cli_config.py). It checks only the top-level section name before writing. A misspelled key it writes is now reported on the next load, and refusing it at the CLI is a separate change.
  • The dashboard settings view.

What changed (motivation → approach → change)

  • Symptom: a misspelled key inside a section has no effect and no WARNING.
  • Root cause: the unknown nested keys are found only by capture_extra_section_keys, which keeps them for save() and logs them at DEBUG.
  • Change: the classification moves into a pure helper, _collect_extra_section_keys, which capture_extra_section_keys calls with its DEBUG lines unchanged.
  • Change: a new warn_misspelled_section_keys(data, cfg) logs ONE WARNING per load that reads the files, naming each unknown key whose closest field in the same section passes a difflib ratio of 0.8 (_MISSPELLING_CUTOFF), with that field: Config: unrecognized keys inside known sections, kept in the file but not in effect: agent.subagent_timeout_sec (did you mean agent.subagent_timeout_secs?). Named records are covered the same way (agents.<name>.<key>).
  • Change: build_config calls it over the merged document, so a misspelling in config.local.json is reported as well, only when the new ConfigDocument.disk_read field is true (config/loader.py:5687). read_config_document sets it on its disk-read return; a cache hit leaves it false, so a cached load does not repeat the warning. That is the same cadence as the top-level warning, which runs in validation on the disk-read path only.
  • Rejected: logging every captured key at WARNING. All 13 shipped fixture configs (src/kiro_crew/tests_fixtures/*/config.json) carry dashboard.host, a key no field of dashboard reads, so that rule would fire on each of them. Evidence: loading each fixture and listing what capture_extra_section_keys captures returns dashboard.host for all 13. Reporting only keys close to a real field keeps the warning to likely typos.
  • Rejected: additionalProperties: false in the schema. Validation would strip the key and break the round-trip.

Backwards compatibility

Compatible: the loaded config and the saved file are unchanged; the change adds one WARNING line on loads that read a file with a likely misspelling.

Security: no redaction, auth, sandbox, permission or deny code changes (none in this branch's diff).

Removes nothing: no key, value or log line is removed; the DEBUG lines of capture_extra_section_keys keep their text.

Tests

Added to test/test_config_extra_keys.py, beside the round-trip tests:

  • test_a_misspelled_section_key_is_reported_with_the_field_it_resembles: one WARNING names agent.subagent_timeout_sec and suggests agent.subagent_timeout_secs; the real field keeps its default and the key is still captured for the round-trip.
  • test_the_misspelling_warning_fires_once_per_disk_read: a cache-hit load adds no warning; a changed file is read again and reported again.
  • test_an_unknown_key_with_no_close_field_is_not_reported (control): agent.retired_knob stays quiet and is still captured.
  • test_a_misspelling_in_the_overlay_is_reported: a misspelling in config.local.json is reported.
  • test_a_misspelled_key_inside_a_named_record_is_reported: agents.my-agent.modle suggests agents.my-agent.model.

The tests count matching records, so they do not depend on log order.

Red on origin/main 7bb9d57 (this branch's test/test_config_extra_keys.py copied into a detached checkout of it), pytest test/test_config_extra_keys.py -p no:cacheprovider -q -n 0, RC=1 in 3 of 3 runs: 4 failed (the no-close-field test passes on both sides by design).

FAILED test/test_config_extra_keys.py::test_a_misspelled_section_key_is_reported_with_the_field_it_resembles - ValueError: not enough values to unpack (expected 1, got 0)
FAILED test/test_config_extra_keys.py::test_the_misspelling_warning_fires_once_per_disk_read - assert 0 == 1
FAILED test/test_config_extra_keys.py::test_a_misspelling_in_the_overlay_is_reported - ValueError: not enough values to unpack (expected 1, got 0)
FAILED test/test_config_extra_keys.py::test_a_misspelled_key_inside_a_named_record_is_reported - ValueError: not enough values to unpack (expected 1, got 0)
=================== 4 failed, 34 passed, 2 warnings in 3.23s ===================

Green on this branch, rebased onto 7bb9d57, the same command, RC=0 in 3 of 3 runs:

======================== 38 passed, 2 warnings in 3.05s ========================

The 35 test files that name capture_extra_section_keys, read_config_document, ConfigDocument or build_config, with every test_config_*.py file and test_session_control.py, less test/test_config_loader.py, which reads the real home directory, run serially: 1735 passed, 1 skipped, exit 0. Gates exit 0: mypy, flake8, isort --check-only, black --check, scripts/check_black_formatting.py, COMMENT_HISTORY_BASE_REF=origin/main scripts/check_comment_history.py, scripts/check_harness_parity.py, scripts/docs-lint.sh.

Manual verification

N/A — unit coverage sufficient: the tests drive KiroCrewConfig.load() over real files in tmp_path, including the cache-hit path.

Related Issues

No existing issue found (GitHub search for unrecognized top-level keys, unmodelled, _extra_keys, capture_extra_section_keys, misspelled config key).
Related, merged: #8946 added the nested-key capture for the round-trip. #11729, #17365 and #17847 removed false positives from the top-level warning, which is why this one reports only likely misspellings.

Pattern harvest

Rule candidate: review-prompt
Pattern: a value preserved for round-trip but never read, with no WARNING-level signal that it has no effect.

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

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 11, 2026 04:18
@javenciu
javenciu requested a review from buluoray October 11, 2026 04:18
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 0b5f1523534fa544ebca02579f2b2d5d29177d44 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 0b5f1523534fa544ebca02579f2b2d5d29177d44 via the fork AI-review pipeline — 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

Check before merge: a key that an older build wrote under a since-renamed field (e.g. *_sec → *_secs) now warns as an operator typo.

What this change ships

Inventory (5 items) — 5 justified

Intent: an operator who misspells a key inside a config section is told at load which field they probably meant. This is a FIX: today the typo does nothing and only logs at DEBUG.

  1. Loading a config with a key close to a real field of its section logs one WARNING naming the key and the field it resembles — justified
  2. The same check covers keys inside named records (agents.<name>.<key>) — justified
  3. A misspelling in config.local.json is reported too, because the check reads the merged view — justified
  4. The warning fires only when the files are actually read, not on a cached load (new ConfigDocument.disk_read, one consumer) — justified
  5. The existing DEBUG lines for preserved keys keep their text; only the classification moves into a shared helper — justified

[FIRST-PRINCIPLES-REVIEWED] 0b5f152

Description read

[DESCRIPTION-READ] 49854c184af1480a01e5702174fa950370c2dee17dd3cdaf4c23f9a4a50d1ce2

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of 0b5f1523534fa544ebca02579f2b2d5d29177d44 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

A field renamed with a small edit leaves its old key close to the new name, so the warning may fire on every disk read about a key the product itself kept.

Watch

  • Renamed keys can look like typos. The spec says _extra_keys exists because "a build that renamed or removed <section>.<key>" would otherwise lose the value on save. A rename is usually a small edit (_sec → _secs, timeout → timeout_secs), so the old key will often pass _MISSPELLING_CUTOFF = 0.8. save() writes that key back, so it stays in the file. The result is a WARNING on every load that reads the file, saying "did you mean" about a value the operator never mistyped. This is the false positive the "Not a goal" section rules out. The fixture check only shows that dashboard.host stays quiet. It does not check renamed fields.
    Clears when: the PR checks renamed fields past and present (any write-back migration or rename shim in config/) against the 0.8 cutoff and either shows none matches, or keeps known retired names out of the warning the way CONFIG_RESERVED_TOP_KEYS keeps reserved keys out of the top-level one.
  • The owning spec is not updated. docs/system-specs/modules/config.md §1316–1333 describes _extra_keys and the top-level warning, but not the new WARNING or its disk-read-only timing (ConfigDocument.disk_read). AGENTS.md requires the spec to change in the same commit.
    Clears when: config.md describes warn_misspelled_section_keys, its cutoff, and the rule that it fires only on a disk read.

[DESIGN-REVIEWED] 0b5f152

Description read

[DESCRIPTION-READ] 49e03e19ed261c95e23225a93d7af17055cc9389e186cba815c2b9b54467334e

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 0b5f1523534fa544ebca02579f2b2d5d29177d44 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0b5f152

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 0b5f1523534fa544ebca02579f2b2d5d29177d44 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0b5f152

Symptom: a key inside a modelled section that no field reads, such as
agent.subagent_timeout_sec beside the real subagent_timeout_secs, loaded
with no warning. The setting kept its default, and the only trace was a
DEBUG line. A misspelled top-level section is reported at WARNING.

Root cause: the unknown nested keys are found by
capture_extra_section_keys, which keeps them for the save round-trip
and logs them at DEBUG only.

Change: on a disk read, build_config calls
warn_misspelled_section_keys over the merged document. It logs one
WARNING naming each unknown key that is close to a real field of its
section (difflib), with that field. Keys with no close field stay at
DEBUG, and the round-trip capture is unchanged.
@javenciu
javenciu force-pushed the fix/config-warn-unknown-nested-key branch from 2ede38c to 0b5f152 Compare October 11, 2026 13:51
@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 Oct 11, 2026

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

This PR logs one WARNING per disk read when an unknown key inside a modelled config section (or inside a named record such as agents.<name>) is within difflib 0.8 of a real field, and names the field it resembles. That fixes the root cause: today a typo has no effect and leaves only a DEBUG trace. I read the full diff. The classification moves into _collect_extra_section_keys with the DEBUG lines unchanged, so the round-trip capture behaves exactly as before. The warning reads the merged view, so an overlay typo is caught. It runs only when ConfigDocument.disk_read is true, which is the same cadence as the top-level warning. I checked the Design lane's concern that renamed keys would be called typos. Renames the product still reads, such as knowledge.auto_ingest_doc_links and agent.yolo, are in _SECTION_KEYS_EMITTED_ELSEWHERE/_DELIBERATELY_DROPPED and are never collected, so they cannot warn. Any other near-match key really has no effect, so "kept in the file but not in effect" is a true statement. The message logs key names only, never values, so nothing secret leaks. The tests fail on main and pass here. The cache test changes the file size, so it does not depend on mtime resolution. One non-blocking nit: AGENTS.md asks for docs/system-specs/modules/config.md (around lines 1316-1333) to describe the new warning and its disk-read-only timing in the same commit. Please add that, and answer the open Design CONCERNS items on the PR. — crew-pr-reviewer (deep re-check)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 11, 2026 17:34
@iamwhatever
iamwhatever merged commit bb5f039 into kirodotdev:main Oct 11, 2026
104 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants