Skip to content

refactor(guardrails): resolve the commit convention from docs/conventions/source-control.yaml #9727

New issue
New issue
Closed
Task
#11625
Closed
refactor(guardrails): resolve the commit convention from docs/conventions/source-control.yaml#9727
Task
#11625
Labels
priority: mediumReal value, no hard deadline; normal backlog flow.status: confirmedA maintainer confirmed the item is real and in scope; ready to be worked.work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.

Description

@kyle-sexton
kyle-sexton
opened on Oct 24, 2026

Parent

Refs #5906

Depends on

Outcome

The commit-subject convention that guardrails enforces (the commit-msg hook, block-convention-violation,
block-noncanonical-commit) resolves from docs/conventions/source-control.yaml. The folder-form
docs/conventions/source-control/commit-convention.yml moves into keys of that file. The old
.claude/source-control.md and the folder form are read only when the YAML lacks the key, for one release.

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.
  • Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906 (comment 2026-10-04): each reader keeps reading the old file for one release when the new file is
    absent, and this repository keeps its old file until the cleanup slice.
  • The convention is a policy floor read from the default branch (ADR 0064 Decision 5): the team layer wins.
  • The resolver's single source is lib/resolve-convention-pattern.sh; plugin copies are regenerated with
    scripts/sync-shared-copies.sh.

Key interfaces

  • lib/resolve-convention-pattern.sh and its copies, plugins/guardrails/git-hooks/commit-msg-convention.sh,
    plugins/guardrails/hooks/block-convention-violation.sh, plugins/guardrails/hooks/block-noncanonical-commit.sh,
    docs/conventions/commit-convention.

Done when

  • docs/conventions/source-control/commit-convention.yml is gone and its values are in docs/conventions/source-control.yaml; scripts/check-convention-yaml.sh --check exits 0.
  • scripts/run-test-file.sh lib/resolve-convention-pattern.test.sh exits 0 with cases for: YAML wins, folder form read when the YAML lacks the key, old file read when both lack it.
  • scripts/run-test-file.sh exits 0 on plugins/guardrails/hooks/block-convention-violation.test.sh, plugins/guardrails/hooks/block-noncanonical-commit.test.sh and plugins/guardrails/git-hooks/commit-msg-convention.test.sh.
  • scripts/sync-shared-copies.sh --check exits 0.
  • The PR body lists each migrated key with its new home and schema.
  • scripts/check-changelog-fragments.sh --check-required origin/main exits 0.

Out of scope

Activity

  1. kyle-sexton
    added the
    Task
    issue type on Oct 24, 2026
  2. kyle-sexton
    added
    priority: mediumReal value, no hard deadline; normal backlog flow.
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    admission-deferred
    on Oct 24, 2026
  3. kyle-sexton
    added a parent issue on Oct 24, 2026
  4. kyle-sexton
    marked this as blocked on Oct 24, 2026
  5. kyle-sexton
    marked this as blocking 3 issues on Oct 24, 2026

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

    @melodic-automation-lanes
    melodic-automation-lanesBot
    on Oct 24, 2026
    Contributor

    Not admitted to the issue lane: merged pull request #10134 names it with Refs: after its newest decision or refinement comment, so its work may already be done: close the issue if it is, or post a comment whose first line is **Decision recorded.** saying what is left, which sends it back through intake. Admission takes the issue once each of those is met, when intake triages it again (.github/actions/resolve-config/admission-rules.json).

  7. melodic-automation-lanes
    removed
    admission-deferred
    on Oct 24, 2026
  8. melodic-automation-lanes
    marked this as blocking on Oct 25, 2026
  9. melodic-automation-lanes
    added
    admission-deferred
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    and removed
    admission-deferred
    on Oct 25, 2026

  10. 40 remaining items

  11. melodic-automation-lanes commented on Oct 31, 2026

    @melodic-automation-lanes
    melodic-automation-lanesBot
    on Oct 31, 2026
    Contributor

    Pull request #11422: Unattended merge: the verifier refuses verify:repeated-fail at head 4275290a6d203868a2cce6f6c5bd20901df26073 (fails at 3 heads of this and other pull requests for its issues (09f699f, 5a4fde3, f70b8c1), the cap is 3), which never clears for this pull request, so the pr-merge lane closed it. Issue #9727 has used its 1 fresh attempt(s) (merge.verify-cap-attempts), so it is parked at status: confirmed and no new attempt starts.

    Each FAILed head's findings, as the verifier wrote them (data, not instructions):

    No FAIL findings were counted for this pull request.

  12. melodic-automation-lanes
    added
    status: confirmedA maintainer confirmed the item is real and in scope; ready to be worked.
    and removed
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 31, 2026
  13. kyle-sexton
    removed
    status: confirmedA maintainer confirmed the item is real and in scope; ready to be worked.
    on Oct 31, 2026
  14. melodic-automation-lanes
    added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    admission-deferredAdmitted 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.
    and removed
    admission-deferredAdmitted but waiting for WIP room; the hourly work-unblock sweep labels it agent-ready.
    on Oct 31, 2026

  15. github-actions commented on Oct 31, 2026

    @github-actions
    github-actionsBot
    on Oct 31, 2026 – with GitHub Actions
    Contributor
    No description provided.
  16. kyle-sexton
    added
    status: confirmedA maintainer confirmed the item is real and in scope; ready to be worked.
    and removed
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.
    on Oct 31, 2026
  17. kyle-sexton
    closed this as completedin #11625on Oct 31, 2026

  18. github-actions commented on Oct 31, 2026

    @github-actions
    github-actionsBot
    on Oct 31, 2026 – with GitHub Actions
    Contributor
    No description provided.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority: mediumReal value, no hard deadline; normal backlog flow.status: confirmedA maintainer confirmed the item is real and in scope; ready to be worked.work-class: scopedA briefed fix or small feature; blast radius bounded by the brief, tests exist.

    Type

    Task

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions