Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion plugins/source-control/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "source-control",
"version": "0.36.0",
"version": "0.37.0",
"description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-Authored-By trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop — safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /babysit-loop (the loop-lane merge lane: a standing or drain loop that invokes babysit-prs per cycle, configured through repo-scoped babysit_loop_* keys on the layered source-control.md seam, with merge authority human-only until the target repo's tracked config adopts the lane, a gate-proven C2-mechanical baseline once adopted, and standing merge-rung raises binding from the team-tracked layer only — with one named exception, where an invocation line explicitly typing both the autopilot tier keyword and the dedicated raise argument --merge c3-this-run widens that single invocation's merge authority up to C3 behind a fresh independent frontier-tier resolver, while C4-structural and C5-untrusted-provenance stay unconditionally human-merge), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply — interview the repo and write the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep — never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.",
"author": {
"name": "Melodic Software",
Expand All @@ -23,6 +23,12 @@
"skill"
],
"userConfig": {
"pr_body_linkage_gate_enabled": {
"type": "boolean",
"title": "pr-body-linkage-gate hook",
"description": "Block a `gh pr create`/`gh pr edit` whose statically-readable PR body would fail the repository's required pr-issue-linkage check (missing a closing keyword, or a missing/empty `## Related` section). Enforced only in a repository that carries .github/workflows/pr-issue-linkage.yml; a body the hook cannot read statically always passes.",
"default": true
},
"babysit_watched_owners": {
"type": "string",
"multiple": true,
Expand Down
34 changes: 34 additions & 0 deletions plugins/source-control/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,40 @@
All notable changes to the `source-control` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.37.0]

### Added

- **A `PreToolUse` hook blocks a `gh pr create` / `gh pr edit` whose PR body would fail the
consuming repository's required `pr-issue-linkage` check.** The check is a merge gate, but nothing
enforced its contract at authoring time, so a body missing a closing keyword or a `## Related`
section was only ever caught post-hoc — one CI round trip after the PR was already open, on
almost every PR an agent filed directly. `/pull-request create` has always run the equivalent
pre-create gate (`skills/pull-request/reference/create.md` §2.4.2); this hook covers the calls
that never go through the skill. On a violation it exits blocking and names the missing half plus
the line to add, so the authoring agent self-corrects in the same turn instead of on the next CI
cycle.
- **Enforcement is keyed to the consumer's own policy**, not to a value this plugin ships: the
gate runs only when the repository root carries `.github/workflows/pr-issue-linkage.yml` (or
`.yaml`). A repository that does not run the check is never gated, so the hook cannot drift away
from what its consumer actually enforces. This is deliberately not the `pr_body_required_sections`
seam — that key is the repo's configurable section scaffold, whose portable default excludes
`Related` on purpose; the authority here is the workflow file that defines the check.
- **The validator is mirrored, not approximated.** HTML comments are stripped exactly as the
reusable `melodic-software/ci-workflows` workflow strips them (terminated spans, then an
unterminated comment opener swallowing the rest), a deeper `###` heading counts as the
`## Related` section's content rather than its terminator, and JavaScript's word boundaries are
transcribed explicitly so `Closes #12abc` and `unclosed #5` stay non-matches. A PR template
whose instructional prose names the markers inside comments therefore cannot pass vacuously.
- **Fail-open on extraction, fail-closed on a determinable bad body.** A `--body` literal, a
readable `--body-file` path, and the sole heredoc feeding `--body-file -` or a
`--body "$(cat <<'EOF' … EOF)"` substitution are judged. An unexpanded variable, several
heredocs, an unreadable file, an absent body flag (`--fill`, `--template`, `--editor`, the
interactive prompt), and any `--repo`-targeted invocation all allow — guessing at a body the
hook cannot see would block compliant calls.
- Toggleable via the new `pr_body_linkage_gate_enabled` userConfig option. The PowerShell tool and
direct `gh api …/pulls` calls are documented as out of scope at the hook's own site.

## [0.36.0]

### Added
Expand Down
38 changes: 36 additions & 2 deletions plugins/source-control/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,35 @@ call site) and runs the project's build/test gates before concluding via
`--continue`. `--abort` is never a resolution strategy — only an explicit
user decision to abandon the integration.

## Hooks

### `pr-body-linkage-gate`

A `PreToolUse` hook on the Bash tool. When a `gh pr create` / `gh pr edit`
carries a PR body the hook can read statically, it validates that body against
the same contract the repository's required `pr-issue-linkage` check enforces —
a closing keyword (or an explicit no-linked-issue marker) plus a non-empty
`## Related` section — and blocks the call with the missing half named, so the
failure surfaces before the PR exists rather than a CI round trip later.
`/source-control:pull-request create` already gates its own body; this covers
the calls that bypass the skill.

Enforcement is keyed to the consuming repository's own policy: it runs only
where `.github/workflows/pr-issue-linkage.yml` exists, and a body the hook
cannot read statically (an unexpanded variable, an absent body flag, a
`--repo`-targeted invocation) always passes. Set
`pr_body_linkage_gate_enabled` to `false` to turn it off.

#### Telemetry (opt-in)

The hook emits one structured
[hook-telemetry](../../docs/conventions/hook-telemetry/README.md) envelope per
run to whatever `HOOK_TELEMETRY_SINK` names — carrying `status` (`blocked` on a
block, `ok` otherwise), `duration_ms`, and a `data` payload of labels only: the
outcome and which body form was read (`body-literal`, `body-file`,
`stdin-heredoc`, `body-substitution`). Never the PR body, the command, or a
path. Unset `HOOK_TELEMETRY_SINK` → no-op.

## Works in any repo

- **Self-contained.** Everything runs on `git`, `gh` (authenticated), `jq`,
Expand Down Expand Up @@ -156,6 +185,7 @@ repo's owner.

| Key | Type | Default / absent behavior |
|---|---|---|
| `pr_body_linkage_gate_enabled` | boolean | `true` (the PR-body hook above; inert in a repo with no `pr-issue-linkage` workflow) |
| `babysit_watched_owners` | string (multiple) | infer the current repo's owner |
| `babysit_self_logins` | string (multiple) | your `gh api user` login (extras add to it) |
| `babysit_default_tier` | string | `safe` (explicit invocations only) |
Expand Down Expand Up @@ -197,8 +227,12 @@ The plugin-scope finding-classification gate accepts extra posting identities vi

## Security

- No hooks, no MCP servers, no telemetry, no outbound network beyond `git`
and `gh` against the repository the session already targets.
- One local hook (`pr-body-linkage-gate`, above), no MCP servers, no telemetry
unless you opt in (see below), no outbound network beyond `git` and `gh`
against the repository the session already targets. The hook reads only the
Bash command it is gating, the body file that command names, and the
repository's own workflow directory; it never runs `git`, `gh`, or any
network call.
- Writes to GitHub (comments, reactions, thread resolution, PR creation,
merge) happen only inside the documented `/pull-request` phases and the
`/babysit-prs` loop. `/babysit-prs` merges only in its explicit
Expand Down
Loading