You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
refactor(docs-naming): move the .claude/docs-naming.json settings to docs/conventions/docs-naming.yaml #9731
The docs-naming, docs-hygiene settings this repository keeps in .claude/docs-naming.json resolve from docs/conventions/docs-naming.yaml,
validated by a schema the plugin ships. The old location is read only when the YAML is absent, for one release.
The setup skill, if the plugin has one, writes the YAML.
Decisions
ADR 0064 Decision 1: a plugin's team settings live in one docs/conventions/<concern>.yaml, validated by a
JSON Schema at plugins/<plugin>/schemas/<concern>.schema.json (Decision 6), checked in CI by scripts/check-convention-yaml.sh (Decision 7). Script readers use the shared reader lib/parse-concern-value.sh.
ADR 0075: layers are plugin default < userConfig < team <home>/<concern>.yaml < personal <home>/<concern>.local.<ext>; every resolver reports the layer that supplied each value.
The docs-naming audit, gate generator and realign readers, plugins/docs-naming/reference/config.md, docs-hygiene's readers, scripts/check-docs-naming.sh.
Done when
docs/conventions/docs-naming.yaml carries every value of .claude/docs-naming.json and scripts/check-convention-yaml.sh --check exits 0 against plugins/docs-naming/schemas/docs-naming.schema.json.
The reader's tests include: the YAML wins when both exist, the old location is read when the YAML is absent, and the resolver names the layer that supplied each value.
No skill body tells an agent to read or write the old location: git grep -n for it under plugins/docs-naming, plugins/docs-hygiene prints only compatibility-read code, its tests and changelog lines.
The PR body lists each migrated setting with its new home and schema.
The work-resolve-issue lane stopped partway through this issue and needs a person.
Why, in the run's own words:
The run reported done, but apply-issue-patch did not commit its patch (patch-protected-path): the patch changes a path the issue lane may not push: a workflow, a CODEOWNERS file, submodule config or a settings file. The run's log names the path or check.
Builder: the Automation Lanes session builds this from the owner's machine. The fix edits .github/workflows, which the lanes App cannot push (patch-rules.json:3); that boundary stays. Its PR closes this issue. needs-human came off under the owner's 2026-10-26 rule (a person only for an intent or vision change, an implementation finding that alters intent or the primary design, or a HIGH/CRITICAL security issue); none applies. agent-ready stays off so the issue lane does not race the build.
Intake triage did not triage this issue after 2 dispatches, so the sweep no longer dispatches it and labeled it needs-triage for a maintainer. Triage it by hand, and read the runs for why intake did not:
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: none
Understood: move this repository's docs-naming and docs-hygiene settings from .claude/docs-naming.json to docs/conventions/docs-naming.yaml. The plugin ships a schema for the YAML. Readers fall back to the old file for one release when the YAML is absent. The setup skill writes the YAML. The old file's deletion is out of scope.
The issue is specified, and its done-when items can be checked. No open issue duplicates it. Earlier comments say the fix edits workflow files, which the lanes App can't push, so the owner's machine builds it. That is a delivery detail and doesn't change the scope.
The work-resolve-issue lane stopped on this issue (patch-protected-path): the change needs a path the issue lane may not push, which a maintainer session builds by hand.
It added host-run and removed agent-ready: an agent run on a host builds it, and it waits on no decision from a person.
In the run's words:
The run stopped early (patch-protected-path): its change needs a path the issue lane may not push, which a person changes instead. In the run's words: patch-protected-path: .github/workflows/pr-require-checks.yml. Its shell paths filter (line 477) starts the docs-naming gate (scripts/check-docs-naming.sh --check, line 758) only when .claude/docs-naming.json changes. Moving the settings to docs/conventions/docs-naming.yaml means adding that path to the filter, or an edit to the new YAML would skip the gate in CI. This lane cannot push to /.github/workflows/**. The owner's 2026-10-26 comment on the issue says the same: the fix edits .github/workflows, the Automation Lanes session builds it from the owner's machine, and agent-ready was to stay off so this lane would not race that build.
What the run says it did not do:
The whole issue (YAML file, schema, resolver fallback, setup skill, docs and changelog fragments): not started, because the change needs the protected path .github/workflows/pr-require-checks.yml
The repository checks check-changelog-fragments and check-affected: not run, because this run changed nothing
The issue has the agent-ready label, but the owner's comment says it should stay off so this lane does not race the owner-run build. Someone should check the label.
Host run. Built the docs-naming YAML settings move on the host, including the .github/workflows/pr-require-checks.yml path-filter edit the issue lane may not push, and opened #11197.
What ran (Claude Code 2.1.314):
Built on the earlier unpushed branch refactor/docs-naming-yaml-settings-9731. The work was done in a new worktree on host-run/9731-docs-naming-yaml, with origin/main merged in. A merge conflict in the config-cascade doc was resolved by moving the docs-naming row change to docs/contracts/config-cascade/README.md, where that table now lives.
Fixes on top of that branch: resynced the stale shared copy plugins/docs-naming/lib/yaml-subset.awk (scripts/sync-shared-copies.sh --check had reported drift), marked lib/layer-yaml.sh executable (the exec-bit check had failed), and reworded two citations of the retired docs-hygiene.json that the pre-push stale-path guard flagged.
Workflow change: one line, docs/conventions/docs-naming.yaml, added to the shell paths filter that starts scripts/check-docs-naming.sh --check. No permissions, tokens, secrets or action pins changed. actionlint is clean.
Acceptance criteria:
docs/conventions/docs-naming.yaml carries every value of .claude/docs-naming.json: pass. resolve-config.sh resolve gives identical output for a repo that holds only the old JSON and for this repo's YAML. scripts/check-convention-yaml.sh --check exits 0 (12 files validate).
scripts/run-test-file.sh on resolve-config.test.sh, setup-apply.test.sh and scripts/check-docs-naming.test.sh: pass, each exits 0. setup-check.test.sh also exits 0.
Reader tests cover three cases: the YAML wins when both files exist, the old location is read when the YAML is absent, and the resolver names the layer behind each value: pass.
git grep -n '\.claude/docs-naming' -- plugins/docs-naming plugins/docs-hygiene prints only compatibility-read code, tests and test fixtures, and changelog lines: pass.
The PR body lists each of the 11 migrated settings with its new home and schema: pass.
scripts/check-affected.sh --tests on the committed head: green (14 passed, 5 skipped). The pre-push hook passed on the final head.
PR: #11197. The body has Closes #9731. It is marked ready: the code and security reviews run in CI, verify is disabled by pre_ready, and CI started on the head. It is not merged and not armed.
Activity
melodic-automation-lanes commentedon Oct 24, 2026
The work-resolve-issue lane stopped partway through this issue and needs a person.
Why, in the run's own words:
Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40127088052
To retry, remove
needs-humanand addagent-readyagain.kyle-sexton commentedon Oct 26, 2026
Builder: the Automation Lanes session builds this from the owner's machine. The fix edits
.github/workflows, which the lanes App cannot push (patch-rules.json:3); that boundary stays. Its PR closes this issue.needs-humancame off under the owner's 2026-10-26 rule (a person only for an intent or vision change, an implementation finding that alters intent or the primary design, or a HIGH/CRITICAL security issue); none applies.agent-readystays off so the issue lane does not race the build.github-actions commentedon Oct 26, 2026
Intake triage did not triage this issue after 2 dispatches, so the sweep no longer dispatches it and labeled it needs-triage for a maintainer. Triage it by hand, and read the runs for why intake did not:
github-actions commentedon Oct 26, 2026
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: none
Understood: move this repository's docs-naming and docs-hygiene settings from
.claude/docs-naming.jsontodocs/conventions/docs-naming.yaml. The plugin ships a schema for the YAML. Readers fall back to the old file for one release when the YAML is absent. The setup skill writes the YAML. The old file's deletion is out of scope.The issue is specified, and its done-when items can be checked. No open issue duplicates it. Earlier comments say the fix edits workflow files, which the lanes App can't push, so the owner's machine builds it. That is a delivery detail and doesn't change the scope.
Automated triage, applied by the lanes App.
melodic-automation-lanes commentedon Oct 30, 2026
The work-resolve-issue lane stopped on this issue (
patch-protected-path): the change needs a path the issue lane may not push, which a maintainer session builds by hand.It added
host-runand removedagent-ready: an agent run on a host builds it, and it waits on no decision from a person.In the run's words:
What the run says it did not do:
Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/41015914172
To hand it back to the lane, remove
host-runand addagent-readyagain.kyle-sexton commentedon Oct 30, 2026
Host run. Built the docs-naming YAML settings move on the host, including the
.github/workflows/pr-require-checks.ymlpath-filter edit the issue lane may not push, and opened #11197.What ran (Claude Code 2.1.314):
refactor/docs-naming-yaml-settings-9731. The work was done in a new worktree onhost-run/9731-docs-naming-yaml, withorigin/mainmerged in. A merge conflict in the config-cascade doc was resolved by moving thedocs-namingrow change todocs/contracts/config-cascade/README.md, where that table now lives.plugins/docs-naming/lib/yaml-subset.awk(scripts/sync-shared-copies.sh --checkhad reported drift), markedlib/layer-yaml.shexecutable (theexec-bitcheck had failed), and reworded two citations of the retireddocs-hygiene.jsonthat the pre-push stale-path guard flagged.docs/conventions/docs-naming.yaml, added to the shell paths filter that startsscripts/check-docs-naming.sh --check. No permissions, tokens, secrets or action pins changed.actionlintis clean.Acceptance criteria:
docs/conventions/docs-naming.yamlcarries every value of.claude/docs-naming.json: pass.resolve-config.sh resolvegives identical output for a repo that holds only the old JSON and for this repo's YAML.scripts/check-convention-yaml.sh --checkexits 0 (12 files validate).scripts/run-test-file.shonresolve-config.test.sh,setup-apply.test.shandscripts/check-docs-naming.test.sh: pass, each exits 0.setup-check.test.shalso exits 0.git grep -n '\.claude/docs-naming' -- plugins/docs-naming plugins/docs-hygieneprints only compatibility-read code, tests and test fixtures, and changelog lines: pass.scripts/check-changelog-fragments.sh --check-required origin/mainexits 0: pass.scripts/check-affected.sh --testson the committed head: green (14 passed, 5 skipped). The pre-push hook passed on the final head.PR: #11197. The body has
Closes #9731. It is marked ready: the code and security reviews run in CI,verifyis disabled bypre_ready, and CI started on the head. It is not merged and not armed.Target labels: add none; remove host-run.