diff --git a/.changes/review/work-resolve-issue-issue-18006-44964496235-1-f19b0115.md b/.changes/review/work-resolve-issue-issue-18006-44964496235-1-f19b0115.md new file mode 100644 index 00000000000..363a841b846 --- /dev/null +++ b/.changes/review/work-resolve-issue-issue-18006-44964496235-1-f19b0115.md @@ -0,0 +1,12 @@ +--- +bump: minor +--- + +### Added + +- **Review-digest options.** The review plugin has six new options: `digest_policy`, `digest_max_files`, `digest_max_changed_lines`, `digest_blast_radius`, `digest_risk_paths` and `digest_opt_in_label`. The two list options each take a JSON list. Together they are the per-user layer of the review-digest settings that `/review:explain-change` and `/review:reviewer-media` read. The personal override is now `docs/conventions/review-digest.local.yaml` ([#18006](https://github.com/melodic-software/claude-code-plugins/issues/18006)). +- **`/review:setup` moves the old digest files.** `check` names each old file it finds and where each of its settings goes. `apply` previews the move and acts only after a yes. It adds the old personal settings that `docs/conventions/review-digest.local.yaml` lacks, keeps the ones that file already sets, checks that each moved value resolves the same, and then deletes `.claude/review-digest.local.json`. For `~/.claude/review-digest.json` it lists each option still unset. Once every old setting is covered by an option, it deletes the file after a yes. + +### Deprecated + +- **`~/.claude/review-digest.json` and `.claude/review-digest.local.json`.** Both files are still read while they exist, each just below the layer that replaces it, so a new layer wins on each key it sets. Each run prints one warning per old file that names `/review:setup apply`. A later release stops reading them. diff --git a/docs/contracts/config-cascade/README.md b/docs/contracts/config-cascade/README.md index f5b4cc5ac53..ef99c042c6a 100644 --- a/docs/contracts/config-cascade/README.md +++ b/docs/contracts/config-cascade/README.md @@ -723,7 +723,7 @@ its conformance cell. | `multi-agent` | no-floor | team: `/multi-agent.yaml`, `` being the bound convention home, else `docs/conventions`; user-global `~/.claude/multi-agent.yaml`; personal override `.claude/multi-agent.local.yaml` | all three | later layer | per-key | the team file is validated by `plugins/multi-agent/schemas/multi-agent.schema.json`. The old team locations, the config block in `docs/conventions/multi-agent.md` and `.claude/multi-agent.yaml`, are not read; `/multi-agent:setup check` names each one it finds, and while the YAML is absent the first `/multi-agent:setup apply --layer team` write copies one old file's keys into it, leaving that file in place. Rule 5 holds: a layer that does not parse or names another schema is skipped and named, and an unknown key or a value outside its allowed set is reported and inert. No policy-floor class: every key is a routing dial, and turning the fan-out guard off is a documented opt-in on whichever layer sets it. Keys owned by [`plugins/multi-agent/reference/config.md`](../../../plugins/multi-agent/reference/config.md); resolved by `plugins/multi-agent/scripts/resolve-roles.sh`, read by `/multi-agent:route`, `/multi-agent:audit-defaults` and `/multi-agent:setup check`; written by `/multi-agent:setup apply` (any of the three layers, after a preview and an explicit yes) | | `multi-agent` (`verification`) | team-only | team: `/multi-agent.yaml`, the role map's team file (`` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/multi-agent/schemas/multi-agent.schema.json`) | team only | the team file at the default branch; a skill entry over the plugin value; an invalid value resolves `standard`, no value `light` | per-key | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename) ([ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md)); no `userConfig` option, and the user-global and personal files do not set it: `scripts/resolve-roles.sh` passes over the keys in every layer, and `/multi-agent:setup apply` writes them to the team layer only. `verification_skills.` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/` after a fetch, never the working tree, so a branch cannot lower its own level, and names a working-tree copy that gives another level. An invalid value or a file that does not parse is named and resolves `standard`; no value resolves `light`. Levels owned by [`docs/contracts/verification-level/README.md`](../verification-level/README.md); read by `/multi-agent:audit-defaults`. This row covers `verification` and `verification_skills` | | `external-agents` | no-floor | team: `/external-agents.yaml` (schema `plugins/external-agents/schemas/external-agents.schema.json`), `` being the bound convention home, else `docs/conventions`; personal override `/external-agents.local.yaml` | plugin default, team and personal override; no `userConfig` option yet | later layer | per-key | conforms: read through `resolve` by `plugins/external-agents/scripts/lib/config.mjs` over the bundled `defaults.json`; no `~/.claude` file and no `.claude/*.local` file. Declared exception: `.binary_path` is honored only from the personal override and only when absolute, since it picks the executable that runs; a team value is reported and ignored | -| `review-digest` | no-floor | team: `docs/conventions/review-digest.yaml`; user-global `~/.claude/review-digest.json`; personal override `.claude/review-digest.local.json` | all three | later layer; `--policy` over every layer | per-key (lists replace) | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename): the team layer is the YAML file alone, the [ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md) team file. Rule 5 holds: a layer that does not parse is named and skipped, an invalid value is reported and ignored, and an unknown key is inert. Declared deviation from the per-layer verdicts: an untracked team layer is reported and resolved as absent rather than stopping, and a personal override that is not gitignored is reported and still applied, since every key only decides when a reader is offered a view. No policy-floor class. Keys owned by [`review-digest`](../../conventions/review-digest.md); resolved by `plugins/review/lib/review-digest.mjs` for `/review:explain-change` (whose `digest-policy.mjs` also reads the `rendered-views` `medium` key) and `/review:reviewer-media` | +| `review-digest` | no-floor | per user: the review plugin's `digest_*` options; team: `docs/conventions/review-digest.yaml`; personal override `docs/conventions/review-digest.local.yaml` | `userConfig` + team + personal override | later layer; `--policy` over every layer | per-key (lists replace) | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename): the team layer is the YAML file alone, the [ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md) team file. Dual-read window: the old `~/.claude/review-digest.json` and `.claude/review-digest.local.json` are still read just below the layer that replaces each, with one warning per file per run naming `/review:setup apply`, which moves them. Rule 5 holds: a layer that does not parse is named and skipped, an invalid value is reported and ignored, and an unknown key is inert. Declared deviation from the per-layer verdicts: an untracked team layer is reported and resolved as absent rather than stopping, and a personal override that is not gitignored is reported and still applied, since every key only decides when a reader is offered a view. No policy-floor class. Keys owned by [`review-digest`](../../conventions/review-digest.md); resolved by `plugins/review/lib/review-digest.mjs` for `/review:explain-change` (whose `digest-policy.mjs` also reads the `rendered-views` `medium` key) and `/review:reviewer-media` | | `reviewer-media` | team-only for `voice_command` and `allow_unattended_paid_voice`, no-floor otherwise | team: `docs/conventions/reviewer-media.yaml` read at the pull request's `baseRefOid`; personal override `docs/conventions/reviewer-media.local.yaml`, applied only when untracked | team and personal override; no user-global file | later layer; `--policy` over every layer | per-key (lists replace) | conforms: read through `readLayers` with the base-commit team text; an invalid team value falls to the default, an invalid personal value leaves the team value, and a team-only key in the personal override is refused. Keys owned by [`reviewer-media`](../../conventions/reviewer-media.md); resolved by `plugins/review/skills/reviewer-media/scripts/decide.mjs` | | `playbooks` | no-floor | team: `docs/conventions/playbooks.yaml` (schema `plugins/playbooks/schemas/playbooks.schema.json`); per user: the plugin's `userConfig` | `userConfig` + team | later layer | per-key | declared deviation: a [ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md) team file with no `~/.claude/` file and no personal override. An unexpanded `${user_config.}` reads as unset, and a value outside a key's list is named and resolves the default. Keys owned by the plugin's `reference/config.md`; read in the skill text of `/playbooks:fable-5` (`described_problem`), which reports the supplying layer | | `playbooks` (`verification`) | team-only | team: `docs/conventions/playbooks.yaml`, whatever the convention home, beside the plugin's other keys (schema `plugins/playbooks/schemas/playbooks.schema.json`) | team only | the team file at the default branch; a skill entry over the plugin value; an invalid value resolves `standard`, no value `light` | per-key | conforms to the [location axis](#location-of-the-team-layer-a-docs-convention-file-or-claudename) ([ADR 0064](../../adr/0064-home-plugin-customization-in-docs-conventions-yaml.md)); no `userConfig` option, no `~/.claude` file and no personal override. `verification_skills.` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/` after a fetch, never the working tree, so a branch cannot lower its own level, and names a working-tree copy that gives another level. An invalid value or a file that does not parse is named and resolves `standard`; no value resolves `light`. Levels owned by [`docs/contracts/verification-level/README.md`](../verification-level/README.md); read by `/playbooks:fable-5`, which passes `--file docs/conventions/playbooks.yaml` so the reader skips the convention home. This row covers `verification` and `verification_skills` | @@ -791,7 +791,7 @@ model-run skill with no reader script, so the rule lives in the skill text. | `docs-naming` | implements | `scripts/resolve-config.sh` sources its `lib/config-root.sh` copy and classifies `--root` (else the git toplevel of the current directory) against `--home`; `paths` reports team and personal override as not-applicable at a `home` or `non-repo` root | | `ai-slop` | implements | `skills/audit/scripts/detect.sh` sources its `lib/config-root.sh` copy and classifies its root (`CLAUDE_PROJECT_DIR`, else `git rev-parse --show-toplevel`, else `pwd`) before the team and personal override reads; a team or personal override file that is the user-global file is read once; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `multi-agent` | implements | `scripts/resolve-roles.sh` sources its `lib/config-root.sh` copy and classifies `--root` (else `CLAUDE_PROJECT_DIR`, else the git toplevel) against `--home`; team and personal override are reported not-applicable at a `home` or `non-repo` root, and a team or personal override path that is the user-global file is read once; `/multi-agent:setup apply --layer team` and `--layer local` refuse at a `home` or `non-repo` root; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | -| `review-digest` | implements | `lib/review-digest.mjs` classifies its root inline (`CLAUDE_PROJECT_DIR`, else the nearest directory holding `.git`) and skips team and personal override when the root is the home directory, above it, or not a working tree, and any team or personal override path that is the user-global file; it does not source the resolver | +| `review-digest` | implements | `lib/review-digest.mjs` classifies its root inline (`CLAUDE_PROJECT_DIR`, else the nearest directory holding `.git`) and skips team and personal override when the root is the home directory, above it, or not a working tree, and an old personal override path that is the old user-global file; it does not source the resolver | | `reviewer-media` | implements | `skills/reviewer-media/scripts/decide.mjs` classifies its root with `lib/review-digest.mjs` `projectRootOf` (`CLAUDE_PROJECT_DIR`, else the nearest directory holding `.git`) and skips team and personal override when the root is the home directory, above it, or not a working tree | | `attribution` | implements | `skills/audit/scripts/lib.sh` sources its `lib/config-root.sh` copy; `cfg_layers_init` skips team and personal override unless `config_root_classify` returns `repo`, and skips a layer that `config_root_paths_same` matches to the user-global file; the `verification` key is read by `lib/read-verification.sh`, which sources the plugin's `lib/config-root.sh` | | `code-metrics` | not yet | `scripts/resolve-config.py`: `git rev-parse --show-toplevel`, else the current directory; `CLAUDE_PROJECT_DIR` is not consulted | diff --git a/docs/conventions/review-digest.md b/docs/conventions/review-digest.md index d97f89dbaae..9d97e3e5d56 100644 --- a/docs/conventions/review-digest.md +++ b/docs/conventions/review-digest.md @@ -50,23 +50,30 @@ Layers resolve per the [config-cascade convention](../contracts/config-cascade/README.md), per-key override, a later layer replacing an earlier one key by key: -1. user-global `~/.claude/review-digest.json` +1. `userConfig`: the review plugin's options `digest_policy`, `digest_max_files`, + `digest_max_changed_lines`, `digest_blast_radius` and `digest_risk_paths` (each a JSON list), + and `digest_opt_in_label`. An empty option is unset, so an empty `opt_in_label` needs a file. 2. team: `docs/conventions/review-digest.yaml`, the only team file. An invalid value in it falls to the layer below. -3. personal override `.claude/review-digest.local.json` +3. personal override `docs/conventions/review-digest.local.yaml`, the same keys as the team file. - A 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](../contracts/config-cascade/locations.md) says. +The old files `~/.claude/review-digest.json` and `.claude/review-digest.local.json` are still read +while they exist, each just below the layer that replaces it, so the new layer wins on each key it +sets. Every run warns once per old file and names `/review:setup apply`, which moves the old file's +settings to its new home, checks they resolve the same, and deletes it. A later release stops +reading the old paths. -The result names the layer that supplied each value (`team :`, `user-global `, -`personal-override `, or `default`). Quote glob values in the YAML file (`"**/hooks/**"`), -since a plain `*` opens an alias. +The result names the layer that supplied each value (`team :`, `userConfig`, +`personal-override `, `user-global ` for the old per-user file, or `default`). Quote +glob values in the YAML files (`"**/hooks/**"`), since a plain `*` opens an alias. The team layer, and the rendered-views team file, are read from the pull request's base commit (`baseRefOid`), never the working tree, so a checked-out pull request cannot configure its own digest. When that commit is not in the clone, the team layer is skipped with a warning. The -personal override applies only when untracked, in any letter case, and is refused when `.claude` or the -personal override is a symlink, or when `.claude` is itself a tracked entry (a submodule or a tracked file) or -holds a `.git`; one that is not gitignored is reported and still applied. +personal override applies only when untracked, in any letter case, and is refused when the file or +a directory on its path is a symlink, or when such a directory is itself a tracked entry (a +submodule or a tracked file) or holds a `.git`; one that is not gitignored is reported and still +applied. An explicit `--policy` argument beats every layer. An unknown key is inert, and an invalid value is reported and ignored. Lists replace whole. No key is policy-floor: each one only decides when a diff --git a/plugins/review/.claude-plugin/plugin.json b/plugins/review/.claude-plugin/plugin.json index d4557754fda..b31c5004c1f 100644 --- a/plugins/review/.claude-plugin/plugin.json +++ b/plugins/review/.claude-plugin/plugin.json @@ -131,6 +131,38 @@ "description": "Your /review:council selection rules as a JSON list, the same shape as council_rules in docs/conventions/review.yaml. Empty (default): the repository's rules or none. A repository's value wins; invalid JSON is reported and ignored.", "default": "" }, + "digest_policy": { + "type": "string", + "title": "Digest policy", + "description": "When /review:explain-change offers a change digest: off, offer (the shipped default: when a trigger fires) or always (build at the ready flip). Empty (default): unset. The docs/conventions/review-digest YAML files win over this option." + }, + "digest_max_files": { + "type": "number", + "title": "Digest max files", + "description": "The digest files trigger fires when a pull request changes more files than this; shipped default 5. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option.", + "min": 0 + }, + "digest_max_changed_lines": { + "type": "number", + "title": "Digest max changed lines", + "description": "The digest changed-lines trigger fires when additions plus deletions exceed this; shipped default 200. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option.", + "min": 0 + }, + "digest_blast_radius": { + "type": "string", + "title": "Digest blast radius (JSON)", + "description": "Assessed blast radius levels that fire the digest offer, as a JSON list of LOW, MEDIUM, HIGH and CRITICAL; shipped default [\"HIGH\",\"CRITICAL\"]. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option." + }, + "digest_risk_paths": { + "type": "string", + "title": "Digest risk paths (JSON)", + "description": "Path globs that fire the digest offer when a changed path matches, as a JSON list of at most 64 globs of at most 256 characters each, e.g. [\"db/migrations/*\"]. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option." + }, + "digest_opt_in_label": { + "type": "string", + "title": "Digest opt-in label", + "description": "The pull request label that fires the digest offer; shipped default explain-change. Empty (default): unset, so to turn the label trigger off, set opt_in_label: \"\" in a docs/conventions/review-digest YAML file. Those files win over this option." + }, "medium": { "type": "string", "title": "Preferred delivery medium", diff --git a/plugins/review/README.md b/plugins/review/README.md index 6e98e9c1512..965ac635508 100644 --- a/plugins/review/README.md +++ b/plugins/review/README.md @@ -309,6 +309,12 @@ these and hands them to the plugin, see [User configuration](https://code.claude | `council_members` | string | *(none)* | Your /review:council member catalog as JSON, the shape of council_members in docs/conventions/review.yaml, e.g. {"codex-adv":{"provider":"codex","brief":"adversarial"}}. Empty (default): the repository's value or three Opus members. The repository's value wins; invalid JSON is reported and ignored. | | `council_panel` | string | *(none)* | Your /review:council fallback panel as a JSON list of member ids. Empty (default): the repository's value or every catalog member. A repository's value wins; invalid JSON is reported and ignored. | | `council_rules` | string | *(none)* | Your /review:council selection rules as a JSON list, the same shape as council_rules in docs/conventions/review.yaml. Empty (default): the repository's rules or none. A repository's value wins; invalid JSON is reported and ignored. | +| `digest_policy` | string | *(none)* | When /review:explain-change offers a change digest: off, offer (the shipped default: when a trigger fires) or always (build at the ready flip). Empty (default): unset. The docs/conventions/review-digest YAML files win over this option. | +| `digest_max_files` | number
*min 0* | *(none)* | The digest files trigger fires when a pull request changes more files than this; shipped default 5. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option. | +| `digest_max_changed_lines` | number
*min 0* | *(none)* | The digest changed-lines trigger fires when additions plus deletions exceed this; shipped default 200. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option. | +| `digest_blast_radius` | string | *(none)* | Assessed blast radius levels that fire the digest offer, as a JSON list of LOW, MEDIUM, HIGH and CRITICAL; shipped default \["HIGH","CRITICAL"\]. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option. | +| `digest_risk_paths` | string | *(none)* | Path globs that fire the digest offer when a changed path matches, as a JSON list of at most 64 globs of at most 256 characters each, e.g. \["db/migrations/*"\]. Empty (default): unset. The docs/conventions/review-digest YAML files win over this option. | +| `digest_opt_in_label` | string | *(none)* | The pull request label that fires the digest offer; shipped default explain-change. Empty (default): unset, so to turn the label trigger off, set opt_in_label: "" in a docs/conventions/review-digest YAML file. Those files win over this option. | | `medium` | string | `"auto"` | Where /review:explain-change sends a digest page. auto (default): the shipped artifact default, which the publish gate keeps local for a non-public repository or a credential-shaped diff; terminal: no page; file: a local file; artifact: publish anyway; hosted: the shared page host. | ### How to set these diff --git a/plugins/review/lib/review-digest.mjs b/plugins/review/lib/review-digest.mjs index 765d05c2ad2..eb38bcaab51 100644 --- a/plugins/review/lib/review-digest.mjs +++ b/plugins/review/lib/review-digest.mjs @@ -21,6 +21,7 @@ export const DEFAULTS = Object.freeze({ /** The config files themselves: a change to one always fires risk-path, whatever risk_paths says. */ export const CONFIG_PATHS = Object.freeze([ "docs/conventions/review-digest.yaml", + "docs/conventions/review-digest.local.yaml", ".claude/review-digest.local.json", "docs/conventions/rendered-views.yaml", "docs/conventions/rendered-views.local.yaml", @@ -28,6 +29,18 @@ export const CONFIG_PATHS = Object.freeze([ ]); /** The team file, validated by plugins/review/schemas/review-digest.schema.json. */ const TEAM_YAML = "docs/conventions/review-digest.yaml"; +export const PERSONAL_YAML = "docs/conventions/review-digest.local.yaml"; +export const RETIRED_USER = "review-digest.json"; +export const RETIRED_PERSONAL = ".claude/review-digest.local.json"; +export const SETUP_COMMAND = "/review:setup apply"; +export const OPTION_NAMES = Object.freeze({ + digest_policy: "digest_policy", + max_files: "digest_max_files", + max_changed_lines: "digest_max_changed_lines", + blast_radius: "digest_blast_radius", + risk_paths: "digest_risk_paths", + opt_in_label: "digest_opt_in_label", +}); const YAML_PARSER = fileURLToPath(new URL("./yaml-subset.awk", import.meta.url)); export const POLICIES = ["off", "offer", "always"]; export const LEVELS = ["LOW", "MEDIUM", "HIGH", "CRITICAL"]; @@ -46,6 +59,7 @@ const VALID = { risk_paths: isGlobs, opt_in_label: (v) => typeof v === "string", }; +export const isValidSetting = (key, value) => Object.hasOwn(VALID, key) && VALID[key](value); // ------------------------------------------------------------ layers @@ -95,19 +109,44 @@ export function projectRootOf(root) { return root && !within(real(homedir()), real(root)) && git(root, ["rev-parse", "--is-inside-work-tree"]) ? root : null; } -function layerPaths(root, userFile, teamFiles, personalOverrideFile) { - const home = real(homedir()); - const user = join(home, ".claude", userFile); +function layerPaths(root) { + const retiredUser = join(real(homedir()), ".claude", RETIRED_USER); if (!projectRootOf(root)) { - return { user, root: null, team: [], personalOverride: null }; + return { retiredUser, root: null, retiredPersonal: null, personal: null }; } - const notUser = (p) => real(p) !== real(user); - return { - user, - root, - team: teamFiles.filter((f) => notUser(join(root, f))), - personalOverride: notUser(join(root, personalOverrideFile)) ? join(root, personalOverrideFile) : null, - }; + const notUser = (p) => (real(p) !== real(retiredUser) ? p : null); + return { retiredUser, root, retiredPersonal: notUser(join(root, RETIRED_PERSONAL)), personal: join(root, PERSONAL_YAML) }; +} + +/** + * The digest options as the skill passed them, keyed by convention key: an empty value or an + * unrendered `${user_config.` placeholder is unset. A count reads as a whole number and a list as + * JSON; anything else stays a string for the key check to name. + */ +export function userConfigLayer(options) { + const value = Object.create(null); + for (const [key, name] of Object.entries(OPTION_NAMES)) { + const raw = options[name]; + if (typeof raw !== "string" || raw === "" || raw.startsWith("${user_config.")) continue; + if (COUNT_KEYS.includes(key)) value[key] = /^(0|[1-9]\d*)$/.test(raw) ? Number(raw) : raw; + else if (key === "blast_radius" || key === "risk_paths") { + try { + value[key] = JSON.parse(raw); + } catch { + value[key] = raw; + } + } else value[key] = raw; + } + return value; +} + +/** One `--setting