Skip to content

feat(docs-naming): read per-person config from a file_names userConfig option - #18067

Open
melodic-automation-lanes[bot] wants to merge 2 commits into
mainfrom
work-resolve-issue/issue-18002-44954440976-1
Open

melodic-automation-lanes[bot] wants to merge 2 commits into
mainfrom
work-resolve-issue/issue-18002-44954440976-1

Conversation

@melodic-automation-lanes

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

Copy link
Copy Markdown
Contributor

Closes #18002

Summary

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

docs-naming's per-person layer moves from ~/.claude/docs-naming.json (and the retired docs-hygiene.json) into a file_names userConfig option, per the config-cascade layers. The option holds one JSON object of file_names keys. That shape follows the review plugin's JSON-string options, because userConfig options are scalar strings and the per-person layer carries lists and tier objects. The resolver reads the option from --user-config or CLAUDE_PLUGIN_OPTION_FILE_NAMES, and every skill passes it to its scripts with a new --user-config flag, because Bash-tool commands do not receive plugin options. Dual-read window: while the option is unset or invalid, the old file (docs-naming.json, else docs-hygiene.json) is still read in the option's place. Each resolve run that finds an old file prints one warning naming it and the option. With a valid option set, the option wins and the warning names both. setup check shows an 'old user file' row per file. setup apply runs the new setup-apply.sh --user-config-value, which writes nothing and previews the keys it would copy, then on a yes hands the value to Claude Code's native '/plugin configure' / 'claude plugin configure' flow. It does not write pluginConfigs itself, because this repository's plugin-reconfiguration convention forbids setup skills from writing it. It leaves the old file in place. Removing the old-file read is left to a later change, as the issue asks.

The run went past its turn budget (turns=231 max-turns=225): the work may be too big for one run.

Not verified

  • The plugin's bash suites (resolve-config.test.sh, setup-check.test.sh, setup-apply.test.sh, sweep.test.sh) could not be executed in this lane, which runs only the named wrappers; the new and changed assertions are desk-checked and left to the PR's CI
  • scripts/sync-plugin-options-docs.py --check, the eval-case validator and the comment lint are CI-only here; the README options block was rendered by hand from the generator's code
  • check-evals-quality does not apply: it takes evals.json files, and the edited eval is a case.yaml
  • --help of setup-check.sh, setup-apply.sh, inventory.sh, sweep.sh, emit-gate.sh and apply-rename.sh does not list the new --user-config / --user-config-value / --home flags: their help is their header comment, and the repo's comment lint blocks added comment lines. The flags are documented in…
  • An option that is valid JSON but carries a wrongly typed key (e.g. exempt_basenames as a string) stops the resolver with exit 2, the same as a malformed file layer, rather than being dropped per key
  • The setup skill does not save the option itself: on a yes it prints the native /plugin configure or claude plugin configure route, because the repo's plugin-reconfiguration convention forbids setup skills from writing pluginConfigs or user settings
  • Tidy not run: the change is over the tidy cutoffs (26 files, three areas, and it touches scripts/shared-copies.txt, a listed shared path)
  • review-venue.txt was absent, so the review ran locally in one fresh-context subagent; build/test verification is skipped for the reason above
  • Untracked dotfiles at the checkout root (.bash_profile, .bashrc, .gitconfig, .idea, .mcp.json, .profile, .ripgreprc, .vscode, .zprofile, .zshrc) were not created by this run and are not part of the change

Fix

  • plugins/docs-naming/.claude-plugin/plugin.json: declares the file_names userConfig option (string, JSON object, default empty)
  • plugins/docs-naming/scripts/resolve-config.sh: reads the option (--user-config or CLAUDE_PLUGIN_OPTION_FILE_NAMES; empty, whitespace or a literal ${user_config.file_names} is unset; a non-object is warned about and ignored; a pasted whole old file is unwrapped to its file_names). Names the layer…
  • plugins/docs-naming/scripts/resolve-config.test.sh: covers option only (including env var, flag precedence and unset forms), old file only (values apply, one warning), both present (option wins, warning names both), both old files, an invalid option and a pasted whole file. Existing provenance…
  • plugins/docs-naming/skills/setup/scripts/setup-check.sh: takes --user-config; layer userConfig row (PASS/INFO/WARN) and an 'old user file' WARN row per old file, saying whether it is read
  • plugins/docs-naming/skills/setup/scripts/setup-check.test.sh: old-user-file rows, set and invalid option rows
  • plugins/docs-naming/skills/setup/scripts/setup-apply.sh: new --user-config-value mode (with --home, --user-config) that previews the merged option value and a values.json line. It adds keys the option lacks, appends old list entries the option's list lacks for the additive keys (as the resolver does), and flags docs-hygiene keys not in effect today. Writes nothing
  • plugins/docs-naming/skills/setup/scripts/setup-apply.test.sh: tests for --user-config-value, including an old list entry the option's list lacks
  • plugins/docs-naming/skills/audit-file-names/scripts/inventory.sh, sweep.sh, plugins/docs-naming/skills/generate-file-name-gate/scripts/emit-gate.sh, plugins/docs-naming/skills/realign-file-names/scripts/apply-rename.sh: accept --user-config and export it for the resolver; sweep.sh also treats a…
  • plugins/docs-naming/skills/audit-file-names/scripts/sweep.test.sh: a --user-config tier reaches the resolver, adds an unclaimed tier, and cannot loosen a team tier
  • plugins/docs-naming/skills/setup/SKILL.md: option layer in Purpose and check rows, passes ${user_config.file_names}, new apply step 5 (preview, yes, native configure route via the plugin-reconfiguration copy, old file kept)
  • plugins/docs-naming/skills/audit-file-names/SKILL.md, generate-file-name-gate/SKILL.md, realign-file-names/SKILL.md, realign-file-names/context/apply-recipe.md: pass --user-config '${user_config.file_names}' to every script call; the four skill bodies point at the manifest reference's Reference a saved value section instead of restating where an option value reaches
  • plugins/docs-naming/reference/config.md: layer table, Old user files section, paths rows, --user-config, option no longer 'declares none'
  • plugins/docs-naming/README.md: configuration prose and the generated Options reference block (hand-rendered to match scripts/sync-plugin-options-docs.py)
  • plugins/docs-naming/reference/plugin-reconfiguration.md: new generated shared copy of docs/contracts/plugin-reconfiguration/README.md, which the setup skill now cites
  • scripts/shared-copies.txt: registers that copy
  • plugins/docs-naming/evals/setup-check-layers-and-retired-team/case.yaml and samples/table-rows-intact.json: the layer-row grader expects userConfig instead of user-global; description line references refreshed
  • docs/contracts/config-cascade/README.md and CHANGELOG.md: the docs-naming implementers row names the userConfig option and the dual-read window
  • .changes/docs-naming/work-resolve-issue-issue-18002-44954440976-1-c691b314.md: minor changelog fragment

Verification

The runner ran each check from the base copy against 50ae432:

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

The run reports:

  • read https: //code.claude.com/docs/en/plugins-reference (manifest reference): userConfig types are string, number, boolean, directory or file; values reach skill content as ${user_config.KEY} and hook processes as CLAUDE_PLUGIN_OPTION_<KEY>, and are not present in commands Claude runs through…
  • read https: //code.claude.com/docs/en/settings-reference (pluginConfigs entry): non-sensitive option values are stored under pluginConfigs.<plugin><marketplace>.options in user or managed settings; Claude Code writes them when the dialog is filled
  • check-changelog-fragments: all 5 fragments valid
  • check-changed-skills: 4 skills checked, 0 failed (warnings only: description and body length, body growth)
  • check-affected: 15 passed, 8 skipped, 0 failed. The first run failed validate-plugins on a userConfig description over the 300-character budget; shortened and re-run
  • sync-shared-copies --check: all 1026 registered copies match their canonical sources
  • fresh-context review subagent over the whole diff: 2 medium and 7 low findings; fixed both mediums (an invalid option now falls back to the old file; a pasted whole old file is unwrapped) and the doc, test-isolation and preview findings
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44954440976

Left out: the items under Not verified.

Related

#18002

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 44957495349, attempt 1

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

Failed GitHub API calls

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

@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-security-review: 1 inline finding(s) on 50ae432a1f5f26b5b4adaada55028594f748b5b5; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

Comment on lines +24 to +29
"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": ""
}

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.

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

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

Security review: PR #18067, changes since 50ae432 (blocking only)

This is an incremental, blocking-only review: this lane already reviewed an earlier head, so it reports only CRITICAL and IMPORTANT findings. I read every hunk of the 6 files in scope. The new push adds no security finding. The one finding counted below is the earlier manifest flag, which is still open and whose lines have not changed.

What I checked

  • setup-apply.sh --user-config-value additive-list merge. For the keys the resolver treats as additive, the preview now appends old-file list entries that the option's list lacks. All values reach jq through --argjson, and ADDITIVE_KEYS is a fixed literal. No value reaches eval or an unquoted expansion. The mode still writes nothing: it prints from: / value: / values.json: and leaves saving to the native /plugin configure flow. Appending entries cannot supply the team-only generated key. A tier appended here is still stamped _layer: userConfig by the resolver, so it stays non-authoritative. No new path opens.
  • Skill text in the four SKILL.md files. The sentence "a Bash command never sees the option otherwise" is gone. In its place each file says to pass --user-config "on every call" and links to the docs on where a saved value reaches. The instruction to pass the value as one single-quoted argument with any single quote escaped is kept word for word. The removed sentence described behaviour and did not forbid anything, so no guardrail was removed or softened.
  • Tests. setup-apply.test.sh only adds assertions for the append and no-repeat behaviour.

Prior finding. The userConfig.file_names manifest flag is still open. Its lines in plugin.json have not changed since it was posted, so it is restated below and counted, not posted again.

critical-findings: 0

Manifest lines (1)

@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 50ae432a1f5f26b5b4adaada55028594f748b5b5; 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 082571e795f99e3d4848aa4ee0e100e349a9b555: read 6 of 6 changed file(s); 0 finding(s), 0 as inline comments.

CI code review: PR #18067, incremental (50ae432 → 082571e)

Blocking only: this lane already reviewed an earlier head, so this pass reports blocking findings only. I read all six files in the incremental scope, every hunk of each, and found none.

Both earlier findings are fixed in this push:

  1. setup-apply.sh --user-config-value reported already copied while it was losing list entries: fixed.
    • The preview now appends the old file's entries that the option's list lacks, for the additive keys. It compares entries by their tojson encoding, as the resolver's append_new does.
    • It reports those keys as adds entries to <key>. It prints already copied only when no key and no list entry is missing.
    • ADDITIVE_KEYS holds roots, exempt_basenames, exempt_paths, exempt_extensions, tiers, sweep_exclude and sweep_exclude_sites. That is exactly the resolver's additive class: its KEY_ORDER minus NEAREST_WINS (rule regex redirect_map) and TEAM_ONLY (generated), at resolve-config.sh#L54-L56.
    • setup-apply.test.sh adds the case the earlier comment asked for: option ["A.md"] with old file OLD.md gives ["A.md","OLD.md"] and no already copied. A second case checks that an entry already present is not added twice.
    • setup/SKILL.md now describes the new preview correctly.
  2. The four SKILL.md bodies gave product behavior as their reason: fixed.
    • "A Bash command never sees the option otherwise" is gone from audit-file-names, generate-file-name-gate, realign-file-names and setup.
    • Each body now states only our decision: pass --user-config on every call.
    • Each adds a pointer with a section anchor to the manifest reference § Reference a saved value. It carries no as-of date, as .claude/rules/skill-bodies-state-current-rules.md requires.

Loosened checks. Loosened checks would be marked: fail (the default: the prompt has no loosened_check_verdict/loosened_check_patterns lines; patterns: 0). I did not check the citation requirement, because the prompt has no loosened_check_decision_record: line. The test change makes a check stricter and loosens none: the old "exempt_basenames": [] case that expected already copied now expects the old entry to be appended.

Not verified: this lane has no shell, so neither setup-apply.test.sh nor any other suite ran here.

Verifier dropped 0 of 0 candidates.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/address-feedback

Run 44958804226, attempt 1

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

Failed GitHub API calls

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

Lane-Activity: pr-unblock/address-feedback
Lane-Thread: PRRT_kwDOTCGFQM66dTLJ
Lane-Thread: PRRT_kwDOTCGFQM66dTLO
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

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

Run 44958804226, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed 082571e
Run 44958804226

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 082571e.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/publish-feedback

Run 44958804226, attempt 1

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

Failed GitHub API calls

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

@melodic-automation-lanes melodic-automation-lanes Bot added the needs-session A pr-unblock stop a session builder takes: a change the lane cannot make. Not an owner stop. label Nov 21, 2026
@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

The pr-unblock lane stopped address-feedback on this pull request: the lane left a review finding open and no adjudicator verdict settled it: none was recorded, it found the finding does not hold where the lane had not disputed it (an UNCERTAIN or VALID-defer reply), which only an INCORRECT reply lets a verdict resolve, it found the finding asks only for tests whose covering check runs had not all passed when the round began, or it raised a security question on a finding the security-review lane rated below CRITICAL; so a session builder takes it. The lane labels it needs-session for a session builder, who makes the change this lane cannot, and the run ends in a failing pr-unblock/address-feedback status on the head the lane gated.

When a retry on this head can change the outcome, the lane runs one on its own, up to its per-head cap, and edits this comment if it stops again; a run that does not stop clears the status. When no retry can (a review thread the lane does not take or settle, or a failing check after the retries are spent), a person resolves the threads or gets the checks green, then dispatches the workflow below: that run finds the cause gone and clears the status. On a pull request the lanes App opened, the dispatchers start that run once per stop; on any other, a person does. A new commit to the branch starts clean.

To run it again on this head now, dispatch the pr-unblock workflow:

gh workflow run pr-unblock.yml -R melodic-software/claude-code-plugins -f pr-number=18067 -f activity=address-feedback

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/report-escalation

Run 44958804226, attempt 1

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

Failed GitHub API calls

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

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

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

a pr-unblock lane stopped its head (pr-unblock/address-feedback is failure), which clears when the
  lane runs again

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-session A pr-unblock stop a session builder takes: a change the lane cannot make. Not an owner stop.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs-naming: read config from the config-cascade layers, not ~/.claude

0 participants