Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
bump: minor
---

### Changed

- **The personal override moves to `docs/conventions/code-metrics.local.yaml`** ([#18001](https://github.com/melodic-software/claude-code-plugins/issues/18001)), beside the team file, per the config-cascade layers. The plugin declares no `userConfig` option, so there is no user-global file layer. Recommended `.gitignore` line: `docs/conventions/**/*.local.*`.
- **Dual-read window for the old paths.** `~/.claude/code-metrics.yaml` is still read below the team file, and `.claude/code-metrics.local.yaml` is still read as the personal layer while the new file is absent. 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. A later release stops reading the old paths.

### Added

- **`/code-metrics:setup apply --copy-old`** copies the old personal files into `docs/conventions/code-metrics.local.yaml` after a `--preview` and a yes, naming each key it copies or skips and leaving the old files in place. A key of the old user-global file that the team file sets is not copied, so the effective configuration does not change. `/code-metrics:setup check` names each old file it finds.
2 changes: 1 addition & 1 deletion docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -686,7 +686,7 @@ its conformance cell.
| `disk-hygiene` | no-floor | `.claude/disk-hygiene.json` | user-global + team | team over user-global; `--policy` replaces both | additive standing layers | declared deviation; no personal override layer |
| `ai-briefing` | no-floor | `.claude/ai-briefing/` | team only | team only | no personal override | declared deviation; team-only, no personal override (#3580). Named profile selection (`--profile`, `active_profile`, or `.claude/ai-briefing/<name>/`) is profile selection, not a `*.local.*` cascade layer. `sources.md`, optional `audience.md`, and optional `brand.json` are tracked profile files in the selected directory, not personal overrides |
| `code-tidying` | no-floor | `.claude/tidy-lanes/<lane>.md` | team only | team only; residual wholesale if no `## Merge semantics` | per-section when declared | declared deviation; no user-global or `*.local.*` personal override (#723). Team layer over a bundled default. A project lane declaring `## Merge semantics` merges per-section with its bundled lane (`Scope` per-section override, watch-for patterns additive, per `docs-prose` #701 and `shell-tooling` #724). Residual deviation: a project lane that declares nothing still resolves project-only wholesale, the first-match fallback retained in #701 so unmigrated consumer lanes keep working, undeclared at the layer that takes it. Personal variation is limited to lane names the team does not track, an uncommitted `.claude/tidy-lanes/<lane>.md` never added to the index; gitignoring a path the team already tracks does not make it personal |
| `code-metrics` | no-floor | `docs/conventions/code-metrics.yaml` (ADR 0064; schema `plugins/code-metrics/schemas/code-metrics.schema.json`) | all three | later layer | per-key | conforms (per-key override, declared because every value is a scalar or a closed list: `scope.exclude` and `lanes.<lane>.collectors.<measure>` replace whole), except declared divergences from "Resolution algorithm": (1) the root is `git rev-parse --show-toplevel`, else the working directory, and `CLAUDE_PROJECT_DIR` is not read (`plugins/code-metrics/scripts/resolve-config.py:221-234`; step 1); (2) no home-root or same-file classification of the team and personal override paths (`resolve-config.py:236-252`; step 2). The team layer is the docs file alone: the retired `.claude` team file of earlier releases is never read (`resolve-config.py:244-252`), and `/code-metrics:setup check` reports it. A layer outside the YAML subset reads as absent, and a value of the wrong shape is dropped by file, key and value and resolves from a valid higher layer, else the bundled default, never a lower layer; neither stops the run (`resolve-config.py:133-165,273-297`; ADR 0064 Decision 7). Unknown keys inert. Keys owned by [`plugins/code-metrics/reference/config.md`](../../../plugins/code-metrics/reference/config.md). Written (team layer only, carrying every declared key of a retired `.claude` file) by `/code-metrics:setup apply`; read by every audit skill. The consumer's `.claude/ecosystems/<lane>.yaml` files are a separate convention (ecosystem-commands); this surface does not absorb them. **Claim:** the plugin implements this row with the declared divergences above. **Basis:** `plugins/code-metrics/reference/config.md` "Layers and merge form" and the cited `resolve-config.py` lines. **As of:** 2026-11-02. **Recheck:** when that section adds a layer, changes merge form, or starts owning an ecosystem-commands key |
| `code-metrics` | no-floor | team `docs/conventions/code-metrics.yaml` (ADR 0064; schema `plugins/code-metrics/schemas/code-metrics.schema.json`); personal override `docs/conventions/code-metrics.local.yaml`; no `userConfig` option | team + personal override, plus the old files of the dual-read window | later layer | per-key | conforms to [the layers](#the-layers) (per-key override, declared because every value is a scalar or a closed list: `scope.exclude` and `lanes.<lane>.collectors.<measure>` replace whole), except declared divergences from "Resolution algorithm": (1) the root is `git rev-parse --show-toplevel`, else the working directory, and `CLAUDE_PROJECT_DIR` is not read (`plugins/code-metrics/scripts/resolve-config.py:244-257`; step 1); (2) no home-root or same-file classification of the team and personal override paths (`resolve-config.py:267-321`; step 2). The team layer is the docs file alone: the retired `.claude` team file of earlier releases is never read (`resolve-config.py:275-321`), and `/code-metrics:setup check` reports it. A layer outside the YAML subset reads as absent, and a value of the wrong shape is dropped by file, key and value and resolves from a valid higher layer, else the bundled default, never a lower layer; neither stops the run (`resolve-config.py:149-188,342-366`; ADR 0064 Decision 7). Unknown keys inert. Keys owned by [`plugins/code-metrics/reference/config.md`](../../../plugins/code-metrics/reference/config.md). The team and personal override files sit at `docs/conventions/` whatever home the repository binds. Dual-read window: the old `~/.claude/code-metrics.yaml` is still read below the team layer, and the old `.claude/code-metrics.local.yaml` as the personal layer only while the new personal file is absent or outside the YAML subset; each run names each old file in one warning, and removing those reads is a later change. Written by `/code-metrics:setup apply`: the team layer, carrying every declared key of a retired `.claude` team file, and, through `apply --copy-old` after a preview, the personal override, carrying the old personal files' keys and leaving those files in place; read by every audit skill. The consumer's `.claude/ecosystems/<lane>.yaml` files are a separate convention (ecosystem-commands); this surface does not absorb them. **Claim:** the plugin implements this row with the declared divergences above. **Basis:** `plugins/code-metrics/reference/config.md` "Layers and merge form" and the cited `resolve-config.py` lines. **As of:** 2026-11-21. **Recheck:** when that section adds a layer, changes merge form, or starts owning an ecosystem-commands key |
| `repo-fleet-hygiene` | no-floor | `.claude/repo-fleet-hygiene.conf` | user-global + team | `--config` then team then user-global | whole-file, no per-key | declared deviation; whole-file precedence (explicit `--config` > team > user-global fallback), no per-key merge, no personal override layer (#1099) |
| `work-items` | no-floor | the `tracker` mapping of `<home>/work-items.yaml` | team + personal override | personal override on the allowlist | per-key personal override | declared deviation ([ADR 0015](../../adr/0015-bind-the-tracker-at-repo-root-with-an-allowlisted-personal-overlay.md), superseded by ADR 0075): layers live in the convention home, not under `.claude/`; personal override (`<home>/work-items.local.yaml`) merges per-key over a deny-by-default allowlist (lease TTL, jira/linear/gitea auth identity, `docs`); deliberately no user-global layer, since a cross-repo personal rung would reopen the per-user provider trap the allowlist forecloses. Anchors at the repo root (`CLAUDE_PROJECT_DIR`, else git toplevel), no CWD climb. The personal override's gitignore line is outside the `.claude/**/*.local.*` one-liner, so `/work-items:setup apply` appends it, announced, a declared exception to the recommend default (ADR 0015) |
| `work-items` (recurring schedule) | no-floor | `.github/recurring-schedule.json` | team only | team only | single-layer | declared deviation ([ADR 0042](../../adr/0042-ratify-consumer-config-location-outliers-in-place.md)): the schedule lives under `.github/`, not `.claude/`, tracked and team-shared with no user-global layer and no personal override. Written by `track add` and `track recheck`; read by `track audit`, `done`, `due`, `search` and `stats`, by `work` candidate discovery, and by `setup`, which also writes it; anchors at `CLAUDE_PROJECT_DIR`, else git toplevel. Separate from the tracker binding row above |
Expand Down
18 changes: 11 additions & 7 deletions plugins/code-metrics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,11 +73,15 @@ run continues.

## Configuration

This plugin has no `userConfig`. Everything tunable lives in three layers: user-global
(`~/.claude/code-metrics.yaml`), team (`docs/conventions/code-metrics.yaml`, tracked, checked by
This plugin has no `userConfig`. Everything tunable lives in two file layers: team
(`docs/conventions/code-metrics.yaml`, tracked, checked by
[`schemas/code-metrics.schema.json`](schemas/code-metrics.schema.json); the retired team file
under `.claude/` is not read, and `/code-metrics:setup apply` moves its keys), and personal override (`.claude/code-metrics.local.yaml`, gitignored; recommended line
`.claude/**/*.local.*`) with per-key override, and every key has a bundled default
under `.claude/` is not read, and `/code-metrics:setup apply` moves its keys) and personal override
(`docs/conventions/code-metrics.local.yaml`, gitignored; recommended line
`docs/conventions/**/*.local.*`) with per-key override. The old `~/.claude/code-metrics.yaml` and
`.claude/code-metrics.local.yaml` are still read, each with a warning, until a later release
([dual-read window](reference/config.md#layers-and-merge-form)); `/code-metrics:setup apply`
copies their keys. Every key has a bundled default
(`scripts/config-defaults.json`), so the plugin works with no configuration at all; the one
opinionated default is `scope.exclude`, which drops `node_modules`, `vendor`, `dist`, and `build`
directories at any depth and reports what it dropped, and a team file that sets the key replaces
Expand All @@ -86,9 +90,9 @@ the list whole. The consumer's
and `enabled`. References ship with their provenance: cyclomatic 20 cites ISO/IEC 5055:2021
§8.2.117; the 1000-line file default is the plugin's own number and says so. Files are written in
a documented YAML subset (block style, flow sequences of scalars, no flow mappings). Every key:
`reference/config.md`; `/code-metrics:setup` writes the team layer and probes the collectors.

This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](reference/config-locations.md) says.
`reference/config.md`; `/code-metrics:setup` writes the team layer, copies old personal files into
the personal override, and probes the collectors. Where each layer lives across this marketplace's
plugins: [config locations](reference/config-locations.md).

## The report

Expand Down
39 changes: 26 additions & 13 deletions plugins/code-metrics/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,34 @@

Every tunable value in this plugin resolves through one set of config layers. This document is their
contract: the layers, the merge form, the YAML subset, and every key with its default and
provenance. `/code-metrics:setup` writes the team layer; every audit skill reads the resolved
provenance. `/code-metrics:setup` writes the team layer, and the personal override only when it
copies old files there; every audit skill reads the resolved
document at run time and prints the layer that supplied any value a personal layer changed. The
JSON Schema for every layer's keys is [`schemas/code-metrics.schema.json`](../schemas/code-metrics.schema.json).

## Layers and merge form

The surface follows the marketplace's config-cascade convention. Three layers, each optional,
resolved in this order over the bundled defaults (`scripts/config-defaults.json`):
The surface follows the marketplace's config-cascade convention ([config locations](config-locations.md)).
The layers, each optional, resolve in this order over the bundled defaults
(`scripts/config-defaults.json`):

| Order | Layer | Path | Belongs to |
|---|---|---|---|
| 1 | user-global | `~/.claude/code-metrics.yaml` | the operator, across repositories |
| 1 | `userConfig` | none: the plugin declares no `userConfig` option | the operator, across repositories |
| 2 | team | `<repo>/docs/conventions/code-metrics.yaml` | the repository, tracked |
| 3 | personal override | `<repo>/.claude/code-metrics.local.yaml` | one operator in one repository, gitignored |
| 3 | personal override | `<repo>/docs/conventions/code-metrics.local.yaml` | one operator in one repository, gitignored |

This plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](config-locations.md) says.
**Dual-read window.** Two old paths are still read, and each run prints one warning naming the
old file and where its keys go:

| Old path | Read as | When |
|---|---|---|
| `~/.claude/code-metrics.yaml` | layer `user-global`, below the team file | while it exists, since no file supplies the `userConfig` layer |
| `<repo>/.claude/code-metrics.local.yaml` | layer `local` | only while `docs/conventions/code-metrics.local.yaml` is absent or outside the YAML subset; with both present the new file wins and the warning names both |

`/code-metrics:setup check` names each old file it finds, and `/code-metrics:setup apply`
offers to copy their keys into `docs/conventions/code-metrics.local.yaml`, leaving the old files in
place. A later release stops reading the old paths.

The team layer is `docs/conventions/code-metrics.yaml` alone. The team file earlier releases read
from the repository's `.claude/` directory is retired and never read. `/code-metrics:setup check`
Expand All @@ -37,11 +49,12 @@ holding a newline, carriage return or tab, a `scope.exclude` glob the matcher ca
A later layer replaces an earlier layer's value key by key; a key absent from a later layer keeps
the earlier value; a list (`scope.exclude`, `lanes.<lane>.collectors.<measure>`) is a closed value
and is replaced whole, never concatenated. Unknown keys are inert. All three layers absent is
valid. The recommended consumer `.gitignore` line for the personal override is `.claude/**/*.local.*`; the
plugin never edits your `.gitignore`.
valid. The recommended consumer `.gitignore` line for the personal override is
`docs/conventions/**/*.local.*`; the plugin never edits your `.gitignore`.

The consumer's `.claude/ecosystems/<lane>.yaml` files (the ecosystem-commands convention) resolve
through the same three layers for their `globs` (which replace the bundled extension map for that
through that convention's own layers (`~/.claude/ecosystems/<lane>.yaml`, then the repository's
`<lane>.yaml` and `<lane>.local.yaml`) for their `globs` (which replace the bundled extension map for that
lane) and `enabled` (a resolved `false` opts the lane out). Only a lane named under `lanes` reads
its file: the bundled lanes, plus any extra id a layer lists there. A record whose id is not listed
creates no lane, because a record need not describe a programming language (a lint-only
Expand All @@ -67,10 +80,10 @@ warning. The files the globs match form the `rust` lane. With no shipped collect
measure on that lane reads `unavailable` with the reason `no shipped collector for the rust lane`,
except `file_lines`, which walks the `other` lane's collectors so the files keep their line count.

The user-global layer is looked up under `$HOME`; `CODE_METRICS_HOME`, when set, replaces that
directory for one run (the plugin's own suites use it to point at a scratch home, and a consumer
can use it the same way to try a personal layer without touching `~/.claude`). It is the only
environment variable the cascade reads; no key is settable from the environment.
The old user-global file and the ecosystem files' home layer are looked up under `$HOME`;
`CODE_METRICS_HOME`, when set, replaces that directory for one run (the plugin's own suites use it
to point at a scratch home). It is the only environment variable the cascade reads; no key is
settable from the environment.

## The YAML subset

Expand Down
4 changes: 2 additions & 2 deletions plugins/code-metrics/reference/several-repositories.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ With no target form, nothing here applies: each skill runs exactly as its own bo
- **Paths stay relative.** A path given with a target form (a scope path, `--artifacts`,
`--registry`, `--memory-dir`) must be relative, and is read from each root; refuse an absolute
one before the fan-out, since it would point every repository at one file or one directory. A
repository that lacks a named path, or a registry its resolved configuration names (the
user-global layer applies to every repository), reports the usage error as that repository's
repository that lacks a named path, or a registry its resolved configuration names (an old
user-global file, still read, applies to every repository), reports the usage error as that repository's
failure, and the others still run.
- **Every other argument** (`--json`, `--keep`, `--findings`) passes to each repository's run
unchanged.
Expand Down
2 changes: 1 addition & 1 deletion plugins/code-metrics/schemas/code-metrics.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/code-metrics/schemas/code-metrics.schema.json",
"title": "code-metrics team config",
"description": "Schema for a repository's docs/conventions/code-metrics.yaml, the team layer of the code-metrics plugin (ADR 0064). The same keys are valid in ~/.claude/code-metrics.yaml and .claude/code-metrics.local.yaml. Every key is optional; the plugin's reference/config.md gives each key's default and meaning. Reader: scripts/resolve-config.py, which drops an invalid value by name and keeps running.",
"description": "Schema for a repository's docs/conventions/code-metrics.yaml, the team layer of the code-metrics plugin (ADR 0064). The same keys are valid in the personal override docs/conventions/code-metrics.local.yaml and in the old files the dual-read window still reads, ~/.claude/code-metrics.yaml and .claude/code-metrics.local.yaml. Every key is optional; the plugin's reference/config.md gives each key's default and meaning. Reader: scripts/resolve-config.py, which drops an invalid value by name and keeps running.",
"type": "object",
"additionalProperties": false,
"$defs": {
Expand Down
Loading
Loading