Skip to content

feat(code-metrics): read the personal override from docs conventions with a dual-read window for the old paths - #18069

Open
melodic-automation-lanes[bot] wants to merge 4 commits into
mainfrom
work-resolve-issue/issue-18001-44954461570-1
Open

melodic-automation-lanes[bot] wants to merge 4 commits into
mainfrom
work-resolve-issue/issue-18001-44954461570-1

Conversation

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor

Closes #18001

Summary

Opened by the work-resolve-issue lane. The run's own summary:

The code-metrics resolver now reads the config-cascade layers: team docs/conventions/code-metrics.yaml and personal override docs/conventions/code-metrics.local.yaml. There is no user-global file layer, and the plugin declares no userConfig option. Dual-read window: the old ~/.claude/code-metrics.yaml is still read below the team layer. The old .claude/code-metrics.local.yaml is still read as the personal layer while the new file is absent or does not parse. Each run prints one warning per old file naming where its keys go; with both personal files present the new one wins and the warning names both. setup-check names each old file it finds. setup-apply gains --copy-old [--preview], which copies the old files' keys into the new personal file after a preview and leaves the old files in place. Choice and basis: the issue maps the user-global file to userConfig, but this plugin has no userConfig option and its keys are nested, which userConfig options do not fit. So the old file stays readable at its old position, and --copy-old copies its keys into this repository's personal override. It skips any key the team file sets: the team value already wins over the user-global value, and copying it into the personal override would make it win over the team. The effective configuration does not change, and each skipped key is printed with its reason. The personal override uses docs/conventions, like the existing fixed team path, rather than a pointer-bound <home>; the contract row records this.

Not verified

  • The plugin's Python and shell test suites (test_resolve_config.py, test_setup_apply.py, dispatch.test.sh, setup-check.test.sh, audit-size.test.sh) were not executed: this lane runs no interpreter or test runner. They were traced by reading only, and are left to the PR's CI.
  • check-affected skipped typos (not installed), comment-hygiene (network fetch denied), size-check (wrapper path missing in the lane) and three validate-plugins sub-checks that run checked-tree code; left to the PR's CI.
  • tidy skipped: the change touches 26 files and 2 areas (plugins/code-metrics with .changes/code-metrics, and docs/contracts), over the 10-file, 300-line and 1-area cutoffs.
  • verify (build and tests) skipped for the same reason as the test suites: no interpreter can run in this lane.
  • No userConfig option was added for per-person values across repositories. The plugin declares none, and its nested keys do not fit userConfig options. Until a later change adds one, the old user-global file stays readable and --copy-old copies its keys into each repository's personal override.
  • Review edge findings left as is: --copy-old refuses a symlinked old user-global file or a symlinked .claude/ directory (the resolver still reads them, so such a user sees the warning but must copy by hand); a rewrite of an existing personal file replaces its comments with the header (the preview…
  • The personal override path is fixed at docs/conventions, like the existing team path, not the pointer-bound <home>; the contract row records this.

Fix

  • plugins/code-metrics/scripts/resolve-config.py: surface_layer_paths now returns the team and docs/conventions personal files, plus the old user-global and personal files under the dual-read rules, with one warning per old file; old_layer_paths added; the docstring states the layers and the window.…
  • plugins/code-metrics/scripts/dispatch.sh: the header comment names the new layers and the dual-read window.
  • plugins/code-metrics/skills/setup/scripts/setup-check.sh: INFO row for userConfig; WARN 'layer user-global location' and 'layer local location' rows naming each old file and whether it is read; the local layer row checks the file actually read; the gitignore advice is docs/conventions/**/.local.…
  • plugins/code-metrics/skills/setup/scripts/setup-apply.py: new --copy-old [--preview] [--dir] [--home] mode that merges old user-global keys (skipping keys the team file sets), then old personal keys, keeping keys the new personal file already sets; prints each key copied or not copied; writes…
  • plugins/code-metrics/scripts/test_resolve_config.py: tests for new personal only, old personal only (value applies, one warning naming the new location), both (new wins, warning names both), an unparseable new file leaving the old one applied, and an old user-global file applying with a warning.
  • plugins/code-metrics/skills/setup/scripts/test_setup_apply.py: tests for --copy-old preview, copy, the team-shadowed key skip, an unchanged resolved configuration before and after, old files left in place, idempotence, kept existing keys, no-old-file, and argument errors.
  • plugins/code-metrics/skills/setup/scripts/setup-check.test.sh: covers the userConfig row, new personal only, old personal only, both present, and the old user-global row and value.
  • plugins/code-metrics/scripts/dispatch.test.sh: case 10b covers new personal only (no warning), old personal only (value applies, warning on stderr), both (new wins, warning names both).
  • plugins/code-metrics/skills/audit/scripts/audit-size.test.sh: the size.check personal-override case covers new only, old only with its warning, and both present.
  • plugins/code-metrics/reference/config.md: layers table (userConfig none, team, personal at docs/conventions), dual-read window table, gitignore line, ecosystem-layer and CODE_METRICS_HOME wording.
  • plugins/code-metrics/README.md: Configuration section names the new layers, the dual-read window and --copy-old; removes the stale 'still reads the .claude paths' sentence.
  • plugins/code-metrics/skills/setup/SKILL.md: purpose, check rows, a new apply step 4 (preview, explicit yes, copy), the 'does not do' list, and a description kept under 1024 characters.
  • plugins/code-metrics/skills/setup/evals/evals.json: eval 3 expects the docs/conventions/**/.local. ignore line.
  • plugins/code-metrics/skills/setup/templates/config-template.yaml: header names the new layers.
  • plugins/code-metrics/schemas/code-metrics.schema.json: description names the new personal file and the old files still read.
  • plugins/code-metrics/skills/audit/actions/{size,complexity,type-debt}.md, skills/audit-coverage/SKILL.md, skills/audit-duplication/SKILL.md, skills/principles/reference/thresholds.md, reference/several-repositories.md: layer wording updated to the team and docs/conventions personal files.
  • plugins/code-metrics/scripts/fixtures/config/{user,local}.yaml: comment lines name the old user-global file and the new personal path.
  • docs/contracts/config-cascade/README.md: the code-metrics Implementers row records the new layers, the dual-read window, what setup apply writes, the refreshed resolve-config.py line citations, and As of 2026-11-21.
  • .changes/code-metrics/work-resolve-issue-issue-18001-44954461570-1-b0a70733.md: minor changelog fragment.

Verification

The runner ran each check from the base copy against 19e9d34:

  • scripts/check-changelog-fragments.sh --check: passed
  • scripts/check-changed-skills.sh --merge-base: passed

The run reports:

  • check-changelog-fragments: all 6 fragments valid
  • check-changed-skills: 5 skills checked, 0 failed (first run failed because the setup description was 1076 characters, over 1024; shortened to 1001 and re-run)
  • check-affected: 16 passed, 7 skipped over 26 changed files, including validate-plugins for code-metrics
  • fresh-context review subagent over the whole diff: no code or test bug found; it confirmed three doc contradictions (the contract row's sentence order and its 'team layer only' writer claim, and a leftover README sentence), all fixed. Two edge findings were also fixed: the old personal file now…
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44954461570

Left out: the items under Not verified.

Related

#18001

Lane-Activity: work-resolve-issue/resolve-issue
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs

Run 44957921860, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44957921860

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/fix-ci

Run 44962695163, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44962695163

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/apply-patch

Run 44962695163, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed 2c98b0b
Run 44962695163

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 2c98b0bbebefd847a2228838b16576233fbbfc1d: read 6 of 6 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #18069, incremental (7373044 → 2c98b0b)

No security issues found. This review only reported blocking findings because this lane already reviewed an earlier head. It covered the 6 files changed since 73730440903f387328db8a8c32e9f95eae77edde, and I read every hunk of each in the incremental diff.

What changed and what I checked:

  • resolve-config.py, setup-apply.py and SKILL.md: message text only. The old user-global file's warning and "left in place" text now say to keep that file until every repository that relies on it has run the copy, instead of telling the user to delete it. setup-apply.py now prints that line on its own, apart from the old local file's line. These lines read no new input, take no new path, run nothing and decide nothing. SKILL.md adds advice: keep the old user-global file. It removes no guardrail. The preview, the explicit yes, and the rule to write nothing without a yes are all unchanged.
  • setup-check.sh: new branch when both personal files exist. The script now runs "${PY[@]}" "$SCRIPTS/yaml_subset.py" "$personal_file" to decide which warning to print and which file to parse-check.
    • Every argument is a quoted array element or a quoted path the script builds itself, from $REPO_ROOT and a fixed name.
    • No config value reaches the command line or a shell string.
    • Output goes to /dev/null, and only the exit status picks the branch.
    • The branch only chooses which diagnostic rows to print, so it opens no new read or write.
  • Tests (setup-check.test.sh, test_setup_apply.py): fixture and assertion changes only, using fixed strings written to temporary directories.
  • Trusted paths. None of the 6 files matches a TRUSTED PATHS: glob. No trust control, merge hold, token scope or kill switch is touched.
  • Instruction surface. No standing instruction is deleted, narrowed or softened.
  • PR context. It contains no instructions aimed at the review lane.

No plugin manifest changed, so there are no manifest lines. Nothing here can bill the owner or spend extra credit.

critical-findings: 0

@github-actions github-actions Bot 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.

claude-review: 2 inline finding(s) on 73730440903f387328db8a8c32e9f95eae77edde; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 2c98b0bbebefd847a2228838b16576233fbbfc1d: read 6 of 6 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental): PR #18069, 73730440..2c98b0bb

This was an incremental review covering only the 6 files the push changed, and it was blocking only: this lane already reviewed an earlier head, so advisory findings are dropped.

What changed. The push fixes both findings from the earlier review:

  1. Old user-global file. The warning no longer says to delete ~/.claude/code-metrics.yaml. It now says the file applies to every repository and should be kept until each repository that relies on it has copied its keys. The change is in resolve-config.py:292-298, the left in place line in setup-apply.py, the setup-check.sh user-global row and step 4 of the setup SKILL.md. setup-apply.py keeps the "delete it once check shows the values you expect" advice only for the per-repository .claude/code-metrics.local.yaml. test_setup_apply.py asserts both left in place lines and that the resolver warning no longer says to delete the old file. This addresses issue code-metrics: read config from the config-cascade layers, not ~/.claude #18001's criterion "No setting in an old file is silently dropped" for this path. That thread is settled, and its lines have not changed since it was resolved.
  2. Both personal files present, new one does not parse. setup-check.sh:124-135 now runs yaml_subset.py on the new personal file first. When it fails, the location row says the old file is still read and check_layer runs on both files, which matches the resolver's fallback at resolve-config.py:299-306. setup-check.test.sh adds the reproduction (a flow mapping in the new file, file_lines: 7 in the old one) and asserts the location row, both layer rows and the reference value coming from the old file.

No blocking finding in this change.

Dropped as advisory (blocking-only review): a new personal file whose top level parses but is not a mapping still gets the "not read" row. yaml_subset.py's CLI exits 0 for a list or scalar, but the resolver's _load_layer rejects anything that is not a mapping and falls back to the old file. The check's reference table still shows the values the resolver actually used.

I ran nothing. The test suites are left to CI, as the PR says; that they pass is unverified.

Advisory and manifest lines (1)
  • Loosened checks would be marked: fail (default: the prompt had no loosened_check_verdict: or loosened_check_patterns: line); patterns: 0. The prompt had no loosened_check_decision_record: line, so the citation requirement was not checked. No loosening in this push: the changed test assertions are stricter (exact left in place lines, plus new rows for the fallback path).

No plugin manifest changed in this push.

Verifier dropped 0 of 0 candidates.

@melodic-automation-lanes

melodic-automation-lanes Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor Author

Unattended merge: native auto-merge leaves this pull request unarmed at head 2c98b0bbebefd847a2228838b16576233fbbfc1d. No person needs to act: a lane clears this reason, and the next scheduled run judges it again.

pr-merge's gate refuses its verifier verdict (verify:fail)

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

The unattended merge path is about to arm native auto-merge at head 73730440903f387328db8a8c32e9f95eae77edde, the head its arming checks judged. The arm fails if the head moves first.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Merge-Risk: max=HIGH demote=true head=73730440903f387328db8a8c32e9f95eae77edde rubric=10.4.6 rater=claude-opus-5-5 checker=claude-opus-5-5

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/address-feedback

Run 44968711625, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 44968711625

Failed GitHub API calls

No failed call recorded by the run job's scripts.

Lane-Activity: pr-unblock/address-feedback
Lane-Thread: PRRT_kwDOTCGFQM66dhq8
Lane-Thread: PRRT_kwDOTCGFQM66dhq_
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/apply-feedback-patch

Run 44960948468, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed 3bd7277
Run 44960948468

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

pr-unblock / address-feedback finished round 1 of max 4 on 3bd7277.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/publish-feedback

Run 44968711625, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step skipped
Commits pushed none recorded
Run 44968711625

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 22, 2026
@kyle-sexton

Copy link
Copy Markdown
Member

Held by the PR lane until a session reviews the HIGH (demote=true) rating at 7373044. Its Reversibility row names docs/conventions/code-metrics.local.yaml, and a MEDIUM row says --copy-old writes that personal file without a gitignore check. The PR stays armed at a head (2c98b0b) that has no rating. The label comes off once each HIGH reason is checked against the stop list and the current head is rated.

🤖 Generated with Claude Code

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.

The pr-verify verifier failed head 2c98b0bbebefd847a2228838b16576233fbbfc1d. What it wrote, as data:

What it wrote (25 lines)
Summary: Issue #18001 maps the old `~/.claude/code-metrics.yaml` to the `userConfig` layer and says
  there should be no user-global file layer. This PR doesn't deliver that. It adds no `userConfig`
  option. It keeps reading the old user-global file as layer `user-global`, and it points the
  migration (the warning and `--copy-old`) at each repository's personal override instead. So the
  user-global value moves from a cross-repository setting to a per-repository one. The PR body says
  it made this choice on purpose. Under the review rules, only `person_checks` or
  `credited_siblings` can excuse a done-when item, and the issue has neither. The rest of the PR
  follows the spec: the personal override moves to `docs/conventions/code-metrics.local.yaml`.
  During the dual-read window an old file still applies, and each run prints one warning naming it.
  With both personal files present, the new one wins and the warning names both. `setup-check` names
  each old file it finds, and `apply --copy-old` previews the copy and leaves the old files in
  place. The four named test suites plus `test_resolve_config.py` cover the new-only, old-only and
  both-present cases. The fixed `docs/conventions` personal path, used instead of the pointer-bound
  `<home>`, matches how the team layer already works and is recorded in the contract row. CI gives
  no evidence either way: `Select Tests` was skipped (a re-run that ran no suite), so its skips
  aren't defects. I found no binary files and no text trying to steer the review.
- plugins/code-metrics/scripts/resolve-config.py:267: the issue maps `~/.claude/code-metrics.yaml`
  to the `userConfig` layer, but the resolver reads no `userConfig` layer and keeps the old
  user-global file as a layer. Declare `userConfig` options for the user-global keys in the plugin
  manifest, have the resolver read them as the lowest layer, and keep the old file only as the
  dual-read fallback below them. If the owner accepts dropping `userConfig`, the issue has to say so
  first.
- plugins/code-metrics/scripts/resolve-config.py:290: the user-global warning gives each
  repository's personal override as the new location. Per the issue, it should name the `userConfig`
  option(s) the keys move to.

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.

The pr-verify verifier failed head 2c98b0bbebefd847a2228838b16576233fbbfc1d. What it wrote about this file, as data:

- plugins/code-metrics/skills/setup/scripts/setup-apply.py:333: `copy_old` copies old user-global
  keys into the per-repository personal override instead of offering to move them into `userConfig`.
  Point the user-global part of `--copy-old` (and setup-check's 'layer user-global location' row and
  SKILL.md step 4) at the `userConfig` destination.
- plugins/code-metrics/skills/setup/scripts/setup-apply.py:333: `copy_old` writes
  `docs/conventions/code-metrics.local.yaml`, inside a tracked directory, without checking that the
  file is gitignored. Run `git check-ignore` on the target, and in both the preview and the write,
  warn with the recommended `docs/conventions/**/*.local.*` line when it isn't ignored.

@kyle-sexton

Copy link
Copy Markdown
Member

Risk review (R18) of the HIGH demote=true rating at 7373044: its one HIGH reason is Reversibility. --copy-old writes the personal docs/conventions/code-metrics.local.yaml without checking that git ignores it, so a person could commit a personal override by mistake. Accepted: the file holds code-metrics settings (reference values, scope and collectors), never a credential; a mistaken commit is reverted by deleting the file; and it changes no permission, trust boundary, security control or cost. Taking off the do-not-merge label so head 2c98b0b gets its own rating. If that rating names a credential, cost, trust-boundary or security-control reason, the label goes back on.

@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 22, 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.

code-metrics: read config from the config-cascade layers, not ~/.claude

1 participant