Skip to content

fix(config): warn once per deprecated field value - #20825

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
rubencu:fix/deprecated-field-warn-once
Oct 18, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
rubencu:fix/deprecated-field-warn-once

Conversation

@rubencu

@rubencu rubencu commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Show each populated deprecated config field warning once per process for one value, and show it once again when that value changes.

Every config load or reload emits the same WARNING for a populated deprecated field. The field stays in the config by design, so saving cannot clear the warning.

Why it matters

A healthy gateway repeats an unchangeable warning throughout its logs. This noise hides warnings that need action.

Not a goal

  • Changing config validation or normalization.
  • Removing deprecated fields from saved config.
  • Changing schema metadata or the warning text.

What changed (motivation → approach → change)

The validator treated each config read as a new deprecation event. src/kiro_crew/config/validation.py now hashes each deprecated value and remembers its (path, digest) pair for the life of the process. A repeated value stays quiet. A distinct value creates one new warning. A lock makes that check atomic across concurrent config reads. The digest keeps configured credentials out of the registry. The existing Telegram warning assertion resets this process-global state so test order cannot decide its result. docs/system-specs/modules/config.md records the warning frequency and fingerprint behavior.

Backwards compatibility

Compatible: validation results, saved config, schema entries, and first-warning text stay unchanged.

Removes nothing: the change only suppresses duplicate log records for a field value already reported in this process.

Tests

test/test_config_loader_agent_section.py::TestDynamicSubagentSizingFields::test_deprecated_warning_is_once_per_value loads one deprecated value twice, a distinct value twice, and the first value again. It proves one warning for each distinct value and silence for every repeat.

test/test_telegram_accounts_deprecated.py::TestEmptyAccountsAreNotMaterialized::test_a_populated_map_is_still_announced_as_deprecated isolates the process-global warning state and proves the registry does not retain either configured Telegram token.

Determinism proof: 20 independent serial repetitions passed, 10 independent -n4 runs beside neighboring tests passed, and a reordered-neighbor run passed. The full config suite passed with 2,208 tests and 1 skip. The 56-test flake-pattern ratchet passed. Diff-scoped Semgrep reported zero findings. A 16-thread smoke test emitted exactly one warning from concurrent validation calls.

Manual verification

N/A — unit coverage drives the real config loader and captures its production warning logger.

Related Issues

Closes #20812

Pattern harvest

Rule candidate: review-prompt
Pattern: a warning about intentionally preserved state needs process-level deduplication when routine reloads revisit that state.

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
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@rubencu
rubencu requested review from a team and KiroCrewCaptain as code owners October 15, 2026 12:34
@rubencu
rubencu requested a review from bolichen97 October 15, 2026 12:34
@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 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

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

Revision 59d4c01da08591ad7ea33872d22ee0fa05f89aff 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 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

Design-Verdict: PASS

Check that the dedup set never empties: switching a field back to a value it held earlier in the same process stays silent, and the new test asserts that.

[DESIGN-REVIEWED] 59d4c01

Description read

[DESCRIPTION-READ] d8904e7b1555bf408fb59875ccf287d8401ac725e94a48025c19286bd51762d1

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

Copy link
Copy Markdown
Contributor

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

Premise-level review of 59d4c01da08591ad7ea33872d22ee0fa05f89aff 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: validation.py:528 keeps the "unrecognized top-level keys" warning repeating on every reload, though save() keeps those sections (loader.py:6154). Is that intended?

What this change ships

Inventory (7 items) — 7 justified

Intent: stop a populated deprecated config field from logging the same warning on every config load or reload (#20812). This is a FIX.

  1. A populated deprecated field now logs its warning once per process for each value — justified
  2. Changing that field's value logs the warning one more time — justified
  3. The process remembers only a SHA-256 digest of each value, so tokens are never stored as raw text — justified
  4. Concurrent config reads still log a value's warning only once — justified
  5. The config spec now says how often the warning appears and how values are fingerprinted — justified
  6. The Telegram deprecation test clears the global state and checks that no token is retained — justified
  7. A test-local jsonschema skip marker, matching the one in test_config_loader_coercion.py:53 — justified

[FIRST-PRINCIPLES-REVIEWED] 59d4c01

Description read

[DESCRIPTION-READ] bc6424c5946869ac35863c038f7d583461b282b63d8fd9f8ca6ea7e16d788ba1

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 59d4c01

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 59d4c01

@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 15, 2026
@rubencu
rubencu force-pushed the fix/deprecated-field-warn-once branch from 97f648b to ced1c94 Compare October 16, 2026 20:44
@rubencu

rubencu commented Oct 16, 2026

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/config.md since this head went green (8f07eea -> 27ab938). The patch is unchanged (same git patch-id).

The rebase also picks up #20802, the fix for the earlier Backend Tests (Windows) (7) red in test_app_mcp_tool_policy_scope. A rerun reuses the old merge ref ad80220, so it could not include that fix.

Locally on the new base: the config/validation tests, the related backend set and the static gates pass. The fork workflows for ced1c94 are waiting for maintainer approval.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 17, 2026
Remember each populated deprecated field value after its first warning so repeated config reloads stay quiet. Warn once again when the value changes.
@rubencu
rubencu force-pushed the fix/deprecated-field-warn-once branch from ced1c94 to 59d4c01 Compare October 17, 2026 03:19
@rubencu

rubencu commented Oct 17, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto 055b3d55c4 because #21444 split test/test_config_loader.py into topic files and this PR's test no longer applied there.

  • test_deprecated_warning_is_once_per_value moved, unchanged, with its class TestDynamicSubagentSizingFields into test/test_config_loader_agent_section.py. That module now defines the same _requires_jsonschema skip marker the pre-split file had (from kiro_crew.config.loader._HAS_JSONSCHEMA). test/test_config_loader.py is main's file.
  • No other change. Head 59d4c01da08591ad7ea33872d22ee0fa05f89aff (was ced1c940fc). The Tests section names the new path.
  • Local on the new head: the config loader, validation and Telegram deprecation tests (367 passed, the moved test runs and passes), the flake-pattern and wait-discipline ratchets (97 passed), black, isort, flake8, mypy, the file line cap and docs lint. Push guard: single commit on base.

The fork workflows still wait for a maintainer to approve them.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 17, 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.

Looks good to ship. Head reviewed: 59d4c01.

What I checked:

  • Correctness: the membership check and the add run under one lock, so concurrent validation emits one record per key. The continue skips only the log call for that entry. The log call stays outside the lock.
  • Secrets: the warning text is still only the field path and help text. The registry keeps an in-memory SHA-256 digest of repr(value), never logged or saved. The new Telegram assertion pins that no raw token is retained.
  • Tests: the new test goes red if the dedup check is removed (the second identical load would log again). Both tests reset the process-global set with monkeypatch, so test order cannot decide the result. No other test on main asserts this warning, so no hidden order dependency remains.
  • Main: main still warns on every load, so this is not superseded. The PR applies cleanly and GitHub reports it mergeable.

One optional point inline about a change back to an earlier value. It does not block.

Remaining before merge: CI on this head is still queued and the readiness label is action required. The AI review comments still name the earlier head. I will check again when the checks finish.

value_digest = hashlib.sha256(repr(node).encode("utf-8")).digest()
warning_key = (entry.path, value_digest)
with _DEPRECATED_WARNING_LOCK:
if warning_key in _REPORTED_DEPRECATED_FIELDS:

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.

🟡 A change back to an earlier value is silent, and the Goal reads as if it should warn.

The registry keeps every (path, digest) pair seen in the process. When an operator sets 0.8, then 0.9, then 0.8 again, the third value is a change, but it logs nothing. The Goal says "show it once again when that value changes". The spec paragraph and the test describe "once per distinct value", so the two texts disagree.

with _DEPRECATED_WARNING_LOCK:
    if warning_key in _REPORTED_DEPRECATED_FIELDS:
        continue
    _REPORTED_DEPRECATED_FIELDS.add(warning_key)

Why it matters: an operator who reverts a value gets no notice for it. The set also grows by one entry per distinct value seen, with no bound. In practice that is small, because only the owner's config writes reach it.

Suggestion: keep only the last digest per path:

_LAST_DEPRECATED_DIGEST: dict[str, bytes] = {}
...
with _DEPRECATED_WARNING_LOCK:
    if _LAST_DEPRECATED_DIGEST.get(entry.path) == value_digest:
        continue
    _LAST_DEPRECATED_DIGEST[entry.path] = value_digest

This bounds memory at the number of deprecated fields and warns on every real change. If "each distinct value once" is the intended rule, I will withdraw this. A one-line edit to the Goal so it matches the spec is then enough.
Rule: Description and diff fidelity (PR template Goal)

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 17, 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 head 59d4c01.

Checked on this head: PR Readiness is passed, base is main, no merge conflict, no failing or pending required check (the cancelled entries are superseded runs), and no AI review lane reports a blocking finding. Earlier review notes on correctness and secret handling still hold: the membership check and the add share one lock, and only a digest of the value is kept, never logged. No security denylist path is touched and the linked issue is tier T1.

@bolichen97
bolichen97 merged commit b290e55 into kirodotdev:main Oct 18, 2026
142 of 152 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 18, 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.

Deprecated-field warning repeats on every config load

2 participants