Before review

Git policies

Write a clear header, preview the description, and keep history reviewable.

They are commands and hooks, so they do not appear in the rule count.

Unnumbered commits: 5 default maximum
Descriptive subject: 72 characters · advisory
PR prose: 500 characters · default
Entire PR body: 2,000 characters · default

Write a commit header

docs(site): clarify rule activation

Grammar: [(i/N) ][TICKET] type(scope)!: description. The series marker, ticket, scope, and ! are optional. The type and description are required.

repo-standards commit-message .git/COMMIT_EDITMSG --fix-safe

Safe fixing normalizes only unambiguous type casing and structural spacing. Bodies and trailers stay untouched.

Types, length advice, and temporary messages

Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.

The shipped hook includes subject-length advice; standalone calls opt in with --advise. The 72-character target counts the descriptive subject after recognized series, ticket, type, and scope prefixes. Trailing (#123) and (GH-123) references do not count. Advice preserves syntax results and message bytes; keep essential identifiers.

Local hooks accept fixup!, squash!, and amend! for autosquash. Exact PR CI rejects them if they remain in review history. Real merge messages require Git's MERGE_HEAD as evidence.

Commit-message options

Preview the PR description

Keep the outcome, validation, and material caveats. Link detailed evidence.

repo-standards pull-request text PR_BODY.txt --title "docs: clarify setup"

Preview uses default budgets: 500 rendered prose characters and 2,000 total characters. The configured Review Policy check is authoritative.

Counting, formatting, and exit codes

Total length includes links, comments, and automation markup. A complete top-level Blacksmith codesmith:footer block is excluded; surrounding text still counts. Nonempty code fences must be closed and language-tagged.

Warnings exit 0. Unreadable, oversized, or invalid input exits 2. The shared commit Action runs advice on PR events, including metadata edits, without changing the PR or the commit-policy verdict.

Titles receive the same descriptive-subject advice. They also accept case-insensitive gh-123: and bpo-123: prefixes, optionally after a branch label such as [3.14]; these prefixes do not spend the target.

PR text options

Include merge-risk verdicts

Run the merge-risk skill before publishing. The create-pr skill adds its overall rating and five category verdicts:

npx skills add sarj-ai/repo-standards --skill create-pr --skill merge-risk --global

## Merge Risk

**Merge risk: medium**
**Alignment:** good ✅
**Impact:** medium 👀
**Verification:** decent 👀
**Rollback cost:** low ✅
**Error detection:** good ✅

Use the verdicts from your assessment. Keep explanations and numerical scores outside this section.

What Review Policy validates

This section is required even when no other headings are configured. Missing, duplicate, malformed, or incomplete verdicts fail. CI validates format and runs no model.

The original Warp merge-risk instructions are vendored byte for byte with their license and pinned source checksum. Install a release containing this policy through the pinned Review Policy Action. Existing verified transition exemptions remain supported.

Keep history reviewable

Count only non-merge commits.

Up to 5 commitsNo series numbering required by default.
More than 5Number every subject (1/N) through (N/N).
Before mergeCI checks the PR's direct base-to-head history.

Series markers must form a complete, ordered ASCII series with unique indices and the actual total. Partial or zero-padded markers fail.

repo-standards pull-request commits . --advisory --quiet

--quiet suppresses only a completed pass. Findings and missing evidence stay visible.

Trusted configuration and transition exemptions

Set local base discovery and narrowly scoped promotion edges in .repo-standards/repository.toml:

[commit_message]
enforcement = "strict" # use "observe" only for measured migrations

[pull_request.commit_history]
advisory_base_ref = "dev"
# maximum_commits = 5

[[pull_request.commit_history.transitions]]
id = "dev-preview"
source_ref = "dev"
base_ref = "preview"
head_prefix = "automation/promote-dev-"
# sha_prefix_length = 12

Strict CI reads the manifest from the exact PR base commit. A PR cannot raise its own limit or grant itself an exemption. Missing configuration keeps the five-commit default with no transition exemptions.

Each edge requires the configured destination, a same-repository PR, an immutable source-SHA branch suffix matching the PR head, and proof of source ancestry. Protect automation branch namespaces so only the promotion app can update them. Actors, bot identities, branch names alone, and forks grant no exemption.

Repeat one table per trusted edge. Ambiguous prefixes, unsafe refs, duplicate IDs, and more than 64 transitions are rejected. Explicit evidence and JSON transition flags remain available for non-GitHub providers.

Commit-history options

Connect local feedback and CI

Where each check runs
Stage	What runs
`pre-commit`	Exact staged repository checks; advisory history feedback.
`commit-msg`	Header validation and safe normalization.
`pre-push`	Advisory history check, including the latest commit.
PR CI	Authoritative direct history and every non-merge commit header.

Shared setup installs the canonical hooks. Local history is advisory because refs may be stale or shallow and pre-commit runs before the pending commit exists.

GitHub Actions integration

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
  merge_group:
    types: [checks_requested]

# Add these steps to an existing required job.
steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      fetch-depth: 0
      persist-credentials: false
  - uses: sarj-ai/repo-standards/pull-request-commits@9ec36427f34bab43589129d85d571dd476061c8e # v6.22.3

Pass the event payload as a file for direct CLI use:

repo-standards pull-request commits . --github-event "$GITHUB_EVENT_PATH"

CI uses exact direct base/head objects, refs, and numeric repository identities, never the synthetic merge commit in GITHUB_SHA. Exit 1 means a policy violation; 2 means incomplete evidence.

Stacked PRs use each PR's direct base. The Action marks merge_group as not applicable because those PRs were already evaluated; keep the containing required workflow enabled for it. The edited activity rechecks retargeted PRs.

Consumers that already lock Repo Standards can invoke its commands from their existing hook manager to share one environment.