Skip to content

Commits and pull requests

One step per pull request. Subjects are checked by scripts/guards/commit-msg.ts. The pull-request job is .github/workflows/pr-shape.yml, which runs scripts/guards/change-shape.ts.

Subject

A subject is a step id, a space, and a summary.

RuleCheck
Step idP0–P6 or L, a dot, two digits, then one optional lowercase letter. P1.07, P0.09c, L.02
SummaryStarts with a capital letter. At most 50 characters. No trailing period
Whole subjectAt most 72 characters
PrefixA Conventional Commits prefix (type:, type(scope):, type!:) fails
BodyA blank line, then lines of at most 72 characters. A line that is only an http or https URL may be longer

The hook’s own example is P1.07 Enforce exact Origin match in CSRF gate. DL-6 asks for an imperative summary that completes “if applied, this commit will …”. Mood is review. The checker requires the capital letter. Delivery in CLAUDE.md states the same shape.

The pull request title uses the subject rules. A squash merge puts that title on main.

scripts/githooks/commit-msg runs the same check. The hook accepts the merge subjects git writes (Merge branch, Merge remote-tracking branch, Merge pull request #N from, Merge commit). The pull-request job reads git log --no-merges, so each remaining commit is held to the subject rules.

Labels

The kind of change is a label in .github/labels.json. pr-shape warns when the count of kind/* labels is anything other than one. The warning leaves the job green.

Labellabels.json
kind/featureNew behaviour
kind/fixCorrects behaviour that was wrong
kind/refactorNew structure, same behaviour
kind/docsDocumentation only
kind/buildCI, tooling, guards or dependencies

large-pr is the size override below.

Size and shape

scripts/guards/pr-size.ts sums added and deleted lines. It leaves out *.test.*, *.spec.*, tests/, fixtures/, package-lock.json, *.generated.* and shared/lexicons/**/*.json. Over 400 changed source lines warns. Over 800 fails unless the pull request has large-pr and a Large PR: line in the body.

DL-1 is one step and one ownership path, with refactoring and a behaviour change in separate commits.

D4 in that file, and the queue line in CLAUDE.md, cap waiting agent pull requests at three. Severity 1 and severity 2 fixes sit outside the cap. No guard counts open pull requests.

Template

.github/pull_request_template.md is the field list. scripts/guards/pr-template.ts requires every ## heading in the body. A heading may say n/a. An author whose login is renovate[bot] and whose type is Bot skips the heading check. The other pr-shape checks still run.

Heading
Step
What
How to test
Security review
What I am unsure about

The template then has the line AI notes: updated / none needed / which. Keep one of the three. scripts/docs/docs.ts checks that the template file still carries these headings, in this order, and that line after them.

pr-shape

The workflow runs on every pull request, drafts included (P0.07l). runChangeShape reports:

CheckWhen it fires
Title and each commitError on a subject or body rule above
SizeWarning over 400 source lines. Error over 800 without large-pr and a Large PR: reason
Template headingsError when one is missing. Renovate is the exception above
kind/*Warning unless there is exactly one
A trusted-base or check path without the security-review labelError, tagged [SE-6]. With the label, a notice lists those paths. Renovate labels its own pull requests
A -- why: speed indexError, tagged [PF-1], when Performance evidence lacks p50, p95 and p99 before and after

The trusted-base list is the last section of .github/CODEOWNERS (its path lines, # parsed: and # checks:), read by scripts/guards/trusted-base.ts. A pull request that changes a listed path merges on a recorded security review of its exact head, and a loosening also needs Alex’s own line (ADR 0044).

Docs-only allowlist

scripts/guards/docs-only-paths.ts decides the allowlist. Every changed path must be allowed, including a rename’s old path and a deletion. An empty list fails closed.

PathAllowed
README.mdyes
docs/site/**/*.mdyes
docs/ai/notes/**/*.mdyes
docs/human/**/*.md other than the four folders belowyes
docs/human/decisions/**, docs/human/engineering/**, docs/human/runbooks/**, docs/human/legal/**no
any file that is not .md, such as site config, go.mod, go.sum, vendored scripts, data files and imagesno
CLAUDE.md, AGENTS.md, docs/ai/PLAN.md, the step book, .github/**, scripts/**, a manifest, a lockfileno

The four docs/human folders are matched without regard to case. CLAUDE.md imports docs/human/engineering, so a change there changes every agent’s rules and is reviewed like code.

.github/workflows/docs-only.yml runs scripts/guards/docs-only.ts when the pull request is not a draft and has kind/docs. .github/workflows/docs-auto-merge.yml runs scripts/guards/docs-auto-merge.ts from the default branch. decide enables squash auto-merge when the head repository is this one, the pull request is not a draft, the file list is allowed, kind/docs is present, and GitHub Actions reports the docs-only check as success. A failed gate disables an auto-merge that is already on. A closed pull request, or a head that has moved, is left as it is. The record is ADR 0034. Its status line says Proposed (awaiting Alex).

Who may merge

ADR 0019 is accepted. A verifier session other than the author thread may merge when every condition in that record holds. The author thread leaves its own pull request unmerged. The merge is squash, with the title as the subject.

The same record keeps these with Alex:

Stays with Alex
A loosening of CI, a guard, lint or a security control
A new ADR, or one that supersedes another
An [ALEX] or [STOP] step
Ruleset and repository settings
Money, accounts, legal, production, deploys and secrets