feat(governance): implement ADR-003 enforcement hooks (commit-msg, branch naming, pickup-issue skill)

[scottschreckengaust]

Summary

Implement the progressive enforcement mechanisms defined in ADR-003's enforcement table (added in PR #144).

Tasks

• Commit-msg hook (Tier 0) — Reject commits without Refs #N or Fixes #N in the message
• Branch naming validation (pre-push) — Validate branches match (feat|fix|chore|docs)/<issue-number>-*
• pickup-issue skill (Claude Code plugin) — Agent must invoke before implementation; hard-fails without valid issue
• Decompose ADR-003 into Guide + Skills (Phase 2 of ADR-012 migration plan)

Context

These were identified as "follow-up work after PR #144 merges" in that PR's comment thread. ADR-003 documents the enforcement table; this issue tracks the implementation.

References

• ADR-003 §Enforcement mechanisms (docs/decisions/003-contribution-governance.md)
• ADR-012 §Layer 3 — executable skills
• PR docs: ADR-005 through ADR-013 (feedback, flags, knowledge, DoD, security, recovery, conflicts, knowledge stack, validation pyramid) #144 comment (follow-up work list)

[scottschreckengaust]

Grooming 1/7 — Scope: governance iteration precedes enforcement

This issue currently tracks only the enforcement mechanisms from ADR-003's table. Proposal: add a phase 0 that iterates the governance content itself. Two practiced-but-uncodified steps (linked branch on assignment; draft-PR-first) exist only as tribal knowledge, and ADR-003 carries accuracy drift (details in follow-up comments). Hooks that enforce the current text as written would bake those gaps in.

Housekeeping: the References section points at docs/decisions/003-contribution-governance.md — renamed to ADR-003-contribution-governance.md in #220.

[scottschreckengaust]

Grooming 2/7 — Mechanism: amend vs supersede (resolve the README ↔ ADR-005 conflict)

docs/decisions/README.md says "To change an accepted decision, write a new ADR that supersedes it — do not edit the original," while ADR-005's evolution table says "Decision works but needs refinement → Amend via PR (minor, no new ADR)." ADR-005 is still proposed, so the stricter README rule technically governs — which makes legitimate refinement feel illegitimate.

Recommend codifying the standard's actual intent: supersede = reversal, amend = refinement. Nygard's immutability rule is explicitly scoped to reversals: "If a decision is reversed, we will keep the old one around, but mark it as superseded… it's still relevant to know that it was the decision, but is no longer the decision." Refinements that extend without contradicting should amend in place, with an ## Amendments log (date, PR, one line) preserving the audit trail. Keeping one readable canonical policy matters disproportionately here because the primary consumers are agents with fresh context windows (ADR-004).

References:

• Nygard 2011 (origin of the lifecycle): https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• MADR v4.0.0: https://adr.github.io/madr/ — templates: https://github.com/adr/madr/tree/4.0.0/template
• ADR org overview: https://adr.github.io/
• AWS Prescriptive Guidance on ADRs (permissive about amendment with a revision trail): https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html

Action: accept ADR-005's evolution table (or lift it into the README lifecycle) before amending ADR-003, so the amendment rides a binding mechanism.

[scottschreckengaust]

Grooming 3/7 — Formatting: MADR alignment is a reformat PR, not a contextual rewrite

Assessed docs/decisions/README.md's template against MADR v4.0.0:

MADR element	Current state	Change needed
Statuses proposed/accepted/superseded/deprecated	Identical (MADR adds rejected)	None; optionally add rejected
YAML front matter (status, date, decision-makers)	Bold-line header	Cosmetic; optional
Consequences	(+)/(-)/(!) notation	Keep — maps cleanly to MADR positive/negative/neutral
Confirmation section ("how is compliance with this decision verified")	Missing	Add to template — this is exactly the slot where ADR-003's enforcement table belongs, i.e., what this issue implements
Considered Options (required in MADR)	Absent from all 14 ADRs	Require for new ADRs only; do not retrofit — reconstructing rejected alternatives months later is archaeology, not documentation

Net: one reformat PR touching the README template + lifecycle rules is sufficient. No per-ADR rewrites required. The only MADR element that would demand significant contextual work (Considered Options) should be forward-only.

[scottschreckengaust]

Grooming 4/7 — ADR-003 amendment content (keep the ADR lean: what/why only)

Additions:

• After self-assign, create the branch on the remote, linked to the issue, before the first commit — the missing "claimed → working" state signal. Structural, not prose: shows in the issue's Development sidebar and is queryable via GraphQL linkedBranches.
• First push opens a draft PR; marking ready is the explicit "review requested" transition. Today this appears in no doc, prompt, or command — pure tribal knowledge.
• WIP-discipline companion rule: unassigning means deleting (or explicitly orphaning) the linked branch, so abandoned links don't accumulate as false "in progress" signals.

Accuracy fixes riding the same amendment:

• ADR-003 claims in present tense that "a GitHub Actions workflow validates that the label applicant is authorized" — no such workflow exists in .github/workflows/. Reword as planned, or pull implementation into this issue.
• Priority labels are now standardized P0/P1/P2 on the repo; ADR text reads p0/p1/p2 — align the case.

Procedure (commands, comment templates, diagrams) stays out of the ADR per ADR-012's layering — the skill carries the how (next comment).

[scottschreckengaust]

Grooming 5/7 — Skillification: pickup-issue carries the procedure

The skill (already in this issue's task list and ADR-012 §Layer 3) should encode, in order:

1. Gate — issue has approved label, is unassigned, predecessors complete (GraphQL blockedBy), no conflicting open PRs (including drafts).
2. Priority check — scan open P0/P1/P2 issues; if a higher-priority unassigned issue exists, surface the challenge ("Should I work on #X instead?") before claiming.
3. Self-assign.
4. gh issue develop <n> --name <type>/<n>-<slug> --base main — one command: branch created on the remote, already associated to the issue, before any commit exists.
5. Structured "Starting implementation" comment — priority-check result, predecessor result, scope confirmation, links to premise-proving research. Turns ADR-003's pre-start review from conversational into auditable.
6. First push → gh pr create --draft; ready-for-review is a deliberate later transition.

Target state machine — every transition is machine-checkable, and these transitions become the assertions for the enforcement hooks in this issue:

stateDiagram-v2
    [*] --> Open: issue created w/ acceptance criteria
    Open --> Workable: admin applies approved label
    Workable --> Claimed: self-assign (pickup-issue gate passed)
    Claimed --> Working: gh issue develop — linked branch on remote
    Working --> DraftPR: first push opens draft PR
    DraftPR --> ReadyPR: mark ready (review requested)
    ReadyPR --> Merged: approve + merge (Fixes #N)
    Claimed --> Workable: unassign + comment
    Working --> Workable: abandon — comment, unassign, delete linked branch
    Merged --> [*]

Loading

[scottschreckengaust]

Grooming 6/7 — Blocker for the branch-naming task: the platform violates its own convention

The ABCA runtime generates branches as bgagent/{taskId}/{slug} (cdk/src/handlers/shared/gateway.ts:41, agent/src/repo.py:30), which fails the (feat|fix|chore|docs)/<issue-number>-* pattern — and .abca/commands/review_pr.md flags exactly that shape as "unauthorized work." The pre-push branch-naming hook cannot ship until this is decided:

• (a) Document an explicit bgagent/ exemption in the amended ADR-003 — platform-generated branches carry task-id provenance instead of issue-number provenance; or
• (b) Migrate the generator to the convention — requires an issue number at task creation, which only some channels have.

Recommend (a): it is honest about the two trust domains (interactive contributor vs. platform runtime) rather than pretending one convention covers both.

[scottschreckengaust]

Grooming 7/7 — Proposed sequencing

1. PR 1 — docs/decisions/README.md lifecycle + template reformat: amend/supersede rule, Confirmation section, accept ADR-005's evolution table. Small, fast review, unblocks everything after it.
2. PR 2 — ADR-003 amendment: state ladder (linked branch, draft PR), accuracy fixes, the bgagent/ exemption decision — logging itself in the new ## Amendments section, becoming the worked example every future governance iteration follows.
3. PR 3+ — pickup-issue skill, then commit-msg and pre-push hooks asserting the state machine transitions.

All docs PRs must run mise //docs:sync so the Starlight mirrors stay in lockstep, or CI rejects on "Fail build on mutation."