refactor(docs-naming): move the .claude/docs-naming.json settings to docs/conventions/docs-naming.yaml #9731

Activity

1. kyle-sexton

   added

   priority: mediumReal value, no hard deadline; normal backlog flow.Real value, no hard deadline; normal backlog flow.

   status: readyTriaged, unblocked, and fully specified; eligible to pick up.Triaged, unblocked, and fully specified; eligible to pick up.

   admission-deferred

   on Oct 24, 2026
2. kyle-sexton

   added the

   Task

   issue type on Oct 24, 2026
3. kyle-sexton

   added a parent issue on Oct 24, 2026

   • Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906
4. kyle-sexton

   marked this as blocking on Oct 24, 2026

   • chore: drop the one-release .claude config reads and this repository's old config files #9737
5. melodic-automation-lanes

   added

   agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.

   needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.Human-in-the-loop required; autonomous sessions must not resolve items carrying this.

   and removed

   admission-deferred

   agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.

   on Oct 24, 2026
6. melodic-automation-lanes commented on Oct 24, 2026

   

   melodic-automation-lanesBot

   on Oct 24, 2026

   Contributor

   More actions

   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.

   Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/40127088052

   To retry, remove needs-human and add agent-ready again.
7. melodic-automation-lanes

   marked this as blocking on Oct 25, 2026

   • Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906
8. kyle-sexton commented on Oct 26, 2026

   

   kyle-sexton

   on Oct 26, 2026

   MemberAuthor

   More actions

   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.
9. kyle-sexton

   removed

   needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.Human-in-the-loop required; autonomous sessions must not resolve items carrying this.

   on Oct 26, 2026
10. github-actions commented on Oct 26, 2026

    

    github-actionsBot

    on Oct 26, 2026 – with GitHub Actions

    Last edited by github-actions

    Contributor

    More actions

    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:

    • https://github.com/melodic-software/claude-code-plugins/actions/runs/40387168469 (success)
    • https://github.com/melodic-software/claude-code-plugins/actions/runs/40396533575 (success)
11. github-actions commented on Oct 26, 2026

    

    github-actionsBot

    on Oct 26, 2026 – with GitHub Actions

    Last edited by melodic-automation-lanes

    Contributor

    More actions

    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.

    _{Automated triage, applied by the lanes App.}
12. melodic-automation-lanes

    added

    work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.A briefed fix or small feature; blast radius bounded by the brief, tests exist.

    on Oct 26, 2026
13. github-actions

    added

    needs-triageNot yet classified. Floor until a type and one priority tier are set.Not yet classified. Floor until a type and one priority tier are set.

    and removed

    needs-triageNot yet classified. Floor until a type and one priority tier are set.Not yet classified. Floor until a type and one priority tier are set.

    on Oct 26, 2026
14. kyle-sexton

    removed

    status: readyTriaged, unblocked, and fully specified; eligible to pick up.Triaged, unblocked, and fully specified; eligible to pick up.

    on Oct 30, 2026
15. melodic-automation-lanes

    added

    status: readyTriaged, unblocked, and fully specified; eligible to pick up.Triaged, unblocked, and fully specified; eligible to pick up.

    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.Admitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.

    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.Needs an unattended run on a host; the host runner takes it, not a person or the issue lane.

    and removed

    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.Admitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.

    on Oct 30, 2026
16. melodic-automation-lanes commented on Oct 30, 2026

    

    melodic-automation-lanesBot

    on Oct 30, 2026

    Contributor

    More actions

    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.

    Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/41015914172

    To hand it back to the lane, remove host-run and add agent-ready again.
17. melodic-automation-lanes

    removed

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.Fully specified and briefed; eligible for autonomous pickup from the frontier.

    on Oct 30, 2026
18. kyle-sexton commented on Oct 30, 2026

    

    kyle-sexton

    on Oct 30, 2026

    MemberAuthor

    More actions

    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-changelog-fragments.sh --check-required origin/main exits 0: 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.

    Target labels: add none; remove host-run.
19. kyle-sexton

    removed

    host-runNeeds an unattended run on a host; the host runner takes it, not a person or the issue lane.Needs an unattended run on a host; the host runner takes it, not a person or the issue lane.

    on Oct 30, 2026
20. kyle-sexton

    closed this as completedin #11197on Oct 30, 2026