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,13 @@
---
bump: minor
---

### Added

- **A `file_names` `userConfig` option is the per-person layer** ([#18002](https://github.com/melodic-software/claude-code-plugins/issues/18002)). It holds your own `file_names` keys as one JSON object and takes the place of the user-global `~/.claude/docs-naming.json`, per the config-cascade layers. It merges where that file did: under the team and personal override files, adding to the policy-floor keys and ignored for `generated`. A value that is not one JSON object is reported and ignored, and one holding a whole old file (`{"schema": 1, "file_names": {...}}`) is read as its `file_names` object. Every skill passes the option to its scripts through a new `--user-config` flag, and `scripts/resolve-config.sh` also reads `CLAUDE_PLUGIN_OPTION_FILE_NAMES`.
- **`setup-apply.sh --user-config-value`** previews copying the old user files' keys into the option: per file, the keys it would add, then the merged value and a `values.json` for `claude plugin configure`. It writes nothing. `/docs-naming:setup apply` shows the preview, and on a yes gives the native command that saves it, leaving the old file in place.

### Changed

- **`~/.claude/docs-naming.json` and `~/.claude/docs-hygiene.json` are read only while the option is unset or invalid**, the first that exists, in the option's place. Each `resolve` run that finds either file prints one warning naming each file and the option. With a valid option set, neither file is read. A later change removes the read.
- **The resolver names the per-person layer `userConfig`** in `layers` provenance and in each tier's `_layer`, where it said `user-global`. `paths` prints a `userConfig file_names` row (`present`, `absent` or `invalid`), then one row per old user file (`legacy` when read, `legacy-unread` when not). `/docs-naming:setup check` shows a `layer userConfig` row and an `old user file` WARN row per file.
4 changes: 4 additions & 0 deletions docs/contracts/config-cascade/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ adding an optional layer or relaxing a rule additively is a minor bump.

No contract change.

- **The `docs-naming` row reads `userConfig`, not `~/.claude/docs-naming.json`.** Its per-person
layer is the `file_names` option; the old user files are read only while it is unset or invalid,
with a warning, until a later change removes the read. The layering axis is unchanged, so
`contract_version` stays.
- **`locations.md` lists where plugin config lives.** One editable page of the four layers, the
`.local` naming and the paths outside the contract, pointing at this README's sections. Plugins
that teach a config location carry a generated copy at `reference/config-locations.md`. The
Expand Down
2 changes: 1 addition & 1 deletion docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -700,7 +700,7 @@ its conformance cell.
| `code-tidying` (`upkeep_*`) | no-floor | team: `<home>/code-tidying.yaml` (schema `plugins/code-tidying/schemas/code-tidying.schema.json`) | team only | team, then the default | per-key | declared deviation: no `userConfig` option and no personal override, since `upkeep_max_open` protects a shared review queue. A value outside the schema, or a file that does not parse, is named with its file and key and resolves to the default. Keys owned by [`plugins/code-tidying/reference/config.md`](../../../plugins/code-tidying/reference/config.md); read through `skills/tidy/scripts/upkeep-setting.sh` by `open-pr-count.sh` and the upkeep gate. `upkeep_spec_issue` has no default: the upkeep gate fails without it |
| `code-tidying` (`comment_lint*`) | team-only | team: `<home>/code-tidying.yaml` (schema `plugins/code-tidying/schemas/code-tidying.schema.json`) | team only | team, then the default | per-key | declared deviation: no `userConfig` option and no personal override, since the lint is a shared gate on what a change may add. `comment_lint` defaults to `off` and `comment_lint_allow` to an empty list; a level outside the schema is named with its file and resolves to `off`. The commit-time hook reads the working tree's file; a CI gate reads the merge base's, so a branch cannot lower its own level. Read through `scripts/comment-settings.sh` by the `comment-lint` git-hook entry. This row covers `comment_lint` and `comment_lint_allow` |
| `code-tidying` (`verification`) | team-only | team: `<home>/code-tidying.yaml` (`<home>` from the convention-home pointer line at the default branch, default `docs/conventions`; schema `plugins/code-tidying/schemas/code-tidying.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.<skill>` beats `verification`. `lib/read-verification.sh` (the plugin's copy) reads the file at `origin/<default>` 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 `/code-tidying:batch-simplify`. This row covers `verification` and `verification_skills` |
| `docs-naming` | team-only | team: `docs/conventions/docs-naming.yaml` (ADR 0064; schema `plugins/docs-naming/schemas/docs-naming.schema.json`); user-global `~/.claude/docs-naming.json`; personal override `docs/conventions/docs-naming.local.yaml` | all three | later layer; team on named policy-floor keys | per-key | conforms. The old team and personal override files, `.claude/docs-naming.json`, `.claude/docs-naming.local.json` and their retired `docs-hygiene` names, are not read; retirement records `docs-naming-r001` and `docs-naming-r002` are `report-only`, `/docs-naming:setup check` names each old file it finds, and while the YAML is absent the first `/docs-naming:setup apply` write copies the old team file's keys into it. The user-global `~/.claude/docs-hygiene.json` is still read, with a WARN, while `~/.claude/docs-naming.json` is absent; per-key override on `file_names.*`, with a policy-floor class on `tiers`, `generated`, `sweep_exclude`, `sweep_exclude_sites`, and the three `exempt_*` keys: a personal layer may add entries and never remove them, and `generated` is team-layer only. Those keys decide what `/docs-naming:realign-file-names` does to a tree (which files are frozen, which reference forms are rewritten, and which shell command runs after a move), so narrowing one from a single machine would weaken a team decision, while adding a scope root or an exemption weakens nothing and stays open. `rule`, `regex`, and `redirect_map` are nearest-wins. Keys owned by [`plugins/docs-naming/reference/config.md`](../../../plugins/docs-naming/reference/config.md), which also partitions them from plugin `userConfig` (this plugin declares none, so a layer naming one is an inert unknown key). Written by `/docs-naming:setup apply`, resolved by `plugins/docs-naming/scripts/resolve-config.sh` |
| `docs-naming` | team-only | team: `docs/conventions/docs-naming.yaml` (ADR 0064; schema `plugins/docs-naming/schemas/docs-naming.schema.json`); `userConfig` option `file_names` (one JSON object of `file_names` keys); personal override `docs/conventions/docs-naming.local.yaml` | all three | later layer; team on named policy-floor keys | per-key | conforms. The old team and personal override files, `.claude/docs-naming.json`, `.claude/docs-naming.local.json` and their retired `docs-hygiene` names, are not read; retirement records `docs-naming-r001` and `docs-naming-r002` are `report-only`, `/docs-naming:setup check` names each old file it finds, and while the YAML is absent the first `/docs-naming:setup apply` write copies the old team file's keys into it. In a dual-read window, while the option is unset or invalid, the old user file `~/.claude/docs-naming.json`, else `~/.claude/docs-hygiene.json`, is read in the option's place; every `resolve` run that finds either file WARNs naming it and the option, and `/docs-naming:setup apply` previews copying its keys into the option, leaving the file in place. Removing that read is a later change; per-key override on `file_names.*`, with a policy-floor class on `tiers`, `generated`, `sweep_exclude`, `sweep_exclude_sites`, and the three `exempt_*` keys: a personal layer may add entries and never remove them, and `generated` is team-layer only. Those keys decide what `/docs-naming:realign-file-names` does to a tree (which files are frozen, which reference forms are rewritten, and which shell command runs after a move), so narrowing one from a single machine would weaken a team decision, while adding a scope root or an exemption weakens nothing and stays open. `rule`, `regex`, and `redirect_map` are nearest-wins. Keys owned by [`plugins/docs-naming/reference/config.md`](../../../plugins/docs-naming/reference/config.md), which also documents the `file_names` option (a key inside it that is not a `file_names` key is inert). Written by `/docs-naming:setup apply`, resolved by `plugins/docs-naming/scripts/resolve-config.sh` |
| `rendered-views` | no-floor | team `docs/conventions/rendered-views.yaml`, personal override `docs/conventions/rendered-views.local.yaml`, and each view-lane plugin's `medium` `userConfig` option; the retired `~/.claude/rendered-views.md` and `.claude/rendered-views*.md` give a notice, never a value | `userConfig`, team and personal override | the publish trust walk, not plain precedence: the argument decides alone; a `terminal` or `file` value from any layer keeps the view local; a publishing value counts only from the untracked, gitignored personal override, then `userConfig`; a team file never publishes; with no layer deciding, the lane's own default | per-key | declared deviation from later-layer-wins: `medium` decides whether a view leaves the machine, so a branch-writable layer can keep a view local but never publish it. An invalid value is reported and ignored without dropping another layer's value. Keys owned by [`rendered-views`](../rendered-views/README.md#the-rendered-views-settings). Resolved by `lib/view-settings.mjs`, which reads each layer with `readLayers` |
| `testing` (`run-e2e`) | no-floor | `.claude/testing/e2e.md` for `recording` / `browser_mode`; `docs/conventions/testing.yaml`, `~/.claude/testing.yaml` and `.claude/testing.local.yaml` for `e2e_driver` / `reuse_running_instance` / `browser_driver` and the `map` scope's `map_unit` / `map_entry_points` / `map_report_order` / `file_findings` / `file_findings_floor`, over the plugin's `userConfig` | all three | later layer | per-key | conforms; per-key override, keys owned by `/testing:run-e2e`. The YAML keys are resolved by `resolve-config.sh e2e` and `resolve-config.sh map`, which report the supplying layer and resolve an unknown or refused value to the default without stopping |
| `testing` (`write`) | no-floor | `docs/conventions/testing.yaml` and `.claude/testing.local.yaml` for `tdd_refactor_step` (`on` \| `off`, default `on`) and `first_test` (`user-flow` \| `unit`, default `user-flow`); no user-global file, no `userConfig` | team + personal override | later layer | per-key | declared deviation: repository settings, so the user-global layer is skipped with a warning. Keys owned by `/testing:write`; resolved by `resolve-config.sh write`, which reports the supplying layer and resolves an unknown value to the default without stopping |
Expand Down
8 changes: 8 additions & 0 deletions plugins/docs-naming/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,13 @@
],
"metadata": {
"category": "maintenance"
},
"userConfig": {
"file_names": {
"type": "string",
"title": "Your file-name settings (JSON)",
"description": "Your file_names keys as one JSON object, the shape of docs/conventions/docs-naming.yaml, e.g. {\"exempt_basenames\":[\"NOTES.md\"]}. Empty (default): none. Repository files win; on policy-floor keys it only adds, and generated is ignored. Invalid JSON is reported and ignored.",
"default": ""
}
Comment on lines +24 to +29

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.

manifest userConfig.file_names: flag, added free-form string option with no options list (not a selector, not inert). Skill text substitutes ${user_config.file_names} into single-quoted Bash arguments for setup-check.sh, setup-apply.sh, inventory.sh, sweep.sh, emit-gate.sh and apply-rename.sh, and resolve-config.sh reads it

What installed users get on update: a new per-person config layer. The default "" is unset, so nothing changes until a user sets the option. Once it is set, the value joins the file_names merge between the bundled defaults and the team layer.

What bounds it:

  • It can never supply the team-only generated regenerator command (resolve-config.sh L345-357).
  • Its tiers are stamped _layer: userConfig, and sweep.sh L156 treats that layer as non-authoritative, so they cannot override a team tier.
  • The scripts hand the value to jq on stdin and never eval it.

Remaining exposure: when the agent builds the Bash command, keeping the value inside one single-quoted argument depends on the model following the skill's "escape any single quote in it" instruction. A value that contains ' and is pasted without escaping would break out of the argument. The value comes from the operator's own user settings, so only the operator can hurt themselves this way, not a third party. If you want this to rely on code rather than the model, pass the value on stdin or in a file instead of in the command line.

severity: IMPORTANT

claude-lane: claude-security-review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pr-unblock / address-feedback: UNCERTAIN, left open

Evidence: plugins/docs-naming/.claude-plugin/plugin.json:29, plugins/docs-naming/skills/setup/SKILL.md:31, plugins/docs-naming/scripts/resolve-config.sh:345

The code confirms what the finding describes. The file_names option is a free-form string. Four skills tell the agent to pass it as one single-quoted --user-config argument and to escape any single quote in it (setup/SKILL.md:31 and the matching lines in the audit, gate and realign skills). Once inside the scripts, the value goes to jq as data and is never evaluated. The resolver also keeps it away from the team-only generated command (resolve-config.sh:345). So the only gap left is the model's quoting, and only the operator's own setting can trigger it. The suggested fix would pass the value on stdin or in a file instead. That changes how six scripts (setup-check, setup-apply, inventory, sweep, emit-gate, apply-rename) take their input, plus the four skill bodies and their allowed-tools patterns. That is too big for one scoped change in this round, and it is a security design choice that the code alone cannot decide. A person should choose between keeping the quoting instruction, given the self-only exposure, and moving the value to stdin or a file in a follow-up.

}
}
50 changes: 46 additions & 4 deletions plugins/docs-naming/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ plugin.

## Configuration

The skills read one consumer surface, layered as user-global, team
The skills read one consumer surface, layered as `userConfig` (the plugin's
`file_names` option, a JSON object of your own `file_names` keys), team
(`docs/conventions/docs-naming.yaml`, tracked, validated by
[`schemas/docs-naming.schema.json`](schemas/docs-naming.schema.json)), and a
gitignored personal override (`docs/conventions/docs-naming.local.yaml`). All
Expand All @@ -47,9 +48,15 @@ The JSON files under `.claude/` the team layer and personal override used to liv
(`docs-naming.json`, `docs-naming.local.json`, and their `docs-hygiene` names)
are not read. `/docs-naming:setup check` names each one it finds, and while the
team YAML is absent `/docs-naming:setup apply` copies the old team file's keys
into it. A user-global file still at the retired `docs-hygiene` name
(`~/.claude/docs-hygiene.json`) is read, with a warning from the resolver; rename
it to retire the warning.
into it.

The user-global files `~/.claude/docs-naming.json` and
`~/.claude/docs-hygiene.json` are retired in favor of the `file_names` option.
While the option is unset or invalid, the first of them that exists is still read, and
every run warns about each one. `/docs-naming:setup check` names them, and
`/docs-naming:setup apply` previews copying their keys into the option and gives
the command that saves it. The options reference below says how to set the
option.

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.

Expand Down Expand Up @@ -84,6 +91,41 @@ unverified; the scripts avoid the constructs that differ there (no `${x,,}`, no
`sed -i`, existence asked of the git index rather than the filesystem), but no
runner covers it.

<!-- BEGIN GENERATED: plugin options. Edit plugin.json, then run scripts/sync-plugin-options-docs.py -->

### Options reference

Generated from this plugin's `.claude-plugin/plugin.json`. For how Claude Code asks for
these and hands them to the plugin, see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `file_names` | string | *(none)* | Your file_names keys as one JSON object, the shape of docs/conventions/docs-naming.yaml, e.g. {"exempt_basenames":\["NOTES.md"\]}. Empty (default): none. Repository files win; on policy-floor keys it only adds, and generated is ignored. Invalid JSON is reported and ignored. |

### How to set these

Set the options above for `docs-naming@<marketplace>`, replacing `<marketplace>` with the
marketplace you installed this plugin from:

- **In a session or headless:** [`/plugin` in a session](https://code.claude.com/docs/en/plugins/cli-reference#plugin-in-a-session) or
[`claude plugin configure`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure). The configure command is the preferred
headless route in the [plugin-reconfiguration convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md), which records its limits.
- **By hand:** under [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs) in your **user** settings.

Do **not** uninstall the plugin to reconfigure it: see [What an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps).
For a Claude Code release without `plugin configure`, see [Plugin install](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install).

### Upstream documentation

- [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)
- [Plugin configure](https://code.claude.com/docs/en/plugins/cli-reference#plugin-configure)
- [Plugin install options](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install)
- [Plugins and skills settings](https://code.claude.com/docs/en/settings-reference#plugins-and-skills)
- [Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect)
- [Manage installed plugins](https://code.claude.com/docs/en/plugins/install#manage-installed-plugins)

<!-- END GENERATED: plugin options -->

## License

MIT (SPDX-License-Identifier: MIT).
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
schema_version: "1.1"
name: setup-check-layers-and-retired-team
description: 'Legacy setup 1 and 5, merged on one fixture: an old .claude/docs-hygiene.json team file with a file_names block, and no layer the resolver reads. Refit: setup sets disable-model-invocation, so the legacy natural prompts become the slash command plus their text. The check table is presented with its PASS, WARN and INFO rows and the layer rows intact (setup SKILL.md lines 36-71), docs-naming-r001 is INFO (report-only, lines 82-84), the old file is no longer read, and nothing is written. ran-check is the with-only indicator; layers-and-remedy (llm) quotes the legacy expectations the regexes do not decide. The scaffold puts the old file under the workspace .claude/, where the bundled check reads it in a run. r001-not-fail rejects FAIL stated as r001''s status (a FAIL status cell, ": FAIL", "is FAIL", in any case and through bold or backticks), so a negated FAIL ("not FAIL", "rather than FAIL", "No FAIL rows") passes; no-shell-change guards a shell rewrite, rm or mv of the old file or the team YAML. Needs --scaffold --allow-tools Bash Write Edit.'
description: 'Legacy setup 1 and 5, merged on one fixture: an old .claude/docs-hygiene.json team file with a file_names block, and no layer the resolver reads. Refit: setup sets disable-model-invocation, so the legacy natural prompts become the slash command plus their text. The check table is presented with its PASS, WARN and INFO rows and the layer rows intact (setup SKILL.md lines 44-84), docs-naming-r001 is INFO (report-only, lines 95-99), the old file is no longer read, and nothing is written. ran-check is the with-only indicator; layers-and-remedy (llm) quotes the legacy expectations the regexes do not decide. The scaffold puts the old file under the workspace .claude/, where the bundled check reads it in a run. r001-not-fail rejects FAIL stated as r001''s status (a FAIL status cell, ": FAIL", "is FAIL", in any case and through bold or backticks), so a negated FAIL ("not FAIL", "rather than FAIL", "No FAIL rows") passes; no-shell-change guards a shell rewrite, rm or mv of the old file or the team YAML. Needs --scaffold --allow-tools Bash Write Edit.'
tags: [setup, check, scaffold, no-network]
plugins: ["../.."]
expected_outcome: 'setup-check.sh and the retirement detection run. The reply shows the table as printed, with the three layer rows absent (INFO) explained as valid because the bundled defaults supply the keys, the old team file WARN row, and docs-naming-r001 reported as INFO, not FAIL. It says the old file is no longer read and that setup apply seeds docs/conventions/docs-naming.yaml from it so its settings carry over. No file is written or edited.'
Expand All @@ -19,7 +19,7 @@ graders:
arm: with-only
- name: table-rows-intact
type: regex
pattern: '^(?=[\s\S]*\bPASS\b)(?=[\s\S]*\bINFO\b)(?=[\s\S]*\bWARN\b)(?=[\s\S]*user-global)(?=[\s\S]*personal[- ]override)'
pattern: '^(?=[\s\S]*\bPASS\b)(?=[\s\S]*\bINFO\b)(?=[\s\S]*\bWARN\b)(?=[\s\S]*userConfig)(?=[\s\S]*personal[- ]override)'
target: last_message
arm: both
- name: r001-info
Expand Down
Loading
Loading