@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/_lib/git_convention_carrier.ts

@@ -0,0 +1,389 @@
+/**
+ * The committed git convention: `.git-convention.yml` at the repository root
+ * (ADR-283), layered over the developer settings files.
+ *
+ * The developer files are gitignored, so a convention declared only there
+ * reaches the checkout it was written in and no worktree, fresh clone or CI
+ * run. The carrier is tracked, and where it is read from is the authority:
+ *
+ * - `update_strategy` at the resolved TARGET commit — the explicit `--base`
+ *   when given, else the default branch — as the server reports it. The
+ *   strategy that judges a pull request must not come from that pull request,
+ *   the same ruling `branch_convergence.ts` records; a value on the branch is a
+ *   candidate and is never adopted.
+ * - `commit_format` and `branch_pattern` at `HEAD`, at the repository root,
+ *   because they shape the branch's own commits and names.
+ *
+ * In both cases the carrier is the highest-precedence layer, over every
+ * developer layer including the gitignored local one (the owner's D8), and a
+ * carrier that does not set a key leaves it to the developer layers read at
+ * the repository root, never per subdirectory. A target commit that cannot be
+ * resolved is `unresolvable`, never the default.
+ *
+ * The target is never inferred from a forge. A caller acting on a pull request
+ * already knows its base and passes it as `--base`; the default branch is the
+ * answer only for an operation that is not about a pull request. Inferring the
+ * base downstream took seven review rounds without converging, and a wrong
+ * inference reads a valid carrier from the wrong commit and exits 0.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { find_project_root } from './agent_settings.js';
+import { parseBaseRef, splitResolvedRef } from './git_base_ref.js';
+import {
+    GIT_CONVENTION_KEYS,
+    checkoutSource,
+    conventionReading,
+    parseLayerText,
+    readGitConventionKey,
+    type GitConventionKey,
+    type GitConventionLayer,
+    type GitConventionReading,
+} from './git_convention.js';
+
+/** The tracked repository-root file a team declares its git convention in. */
+export const CARRIER_PATH = '.git-convention.yml';
+
+/** Sized for a ref lookup (`ls-remote`), which transfers no objects. */
+export const NETWORK_TIMEOUT_MS = 8_000;
+
+/**
+ * The target-commit fetch transfers objects, and the target is routinely a
+ * commit the server has advanced past the local fetch, so a large repository
+ * needs longer than a ref lookup does. Running out of time here makes the
+ * reading `unresolvable` and stops a sync, so the bound is generous.
+ */
+export const CARRIER_FETCH_TIMEOUT_MS = 60_000;
+
+export interface GitRunResult {
+    ok: boolean;
+    out: string;
+    err: string;
+    timedOut: boolean;
+}
+
+export type GitRunner = (cmd: string, args: readonly string[], cwd: string, timeoutMs: number) => GitRunResult;
+
+export const runGit: GitRunner = (cmd, args, cwd, timeoutMs) => {
+    const r = spawnSync(cmd, [...args], { cwd, encoding: 'utf-8', timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+    const code = (r.error as NodeJS.ErrnoException | undefined)?.code;
+    return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim(), timedOut: code === 'ETIMEDOUT' };
+};
+
+function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {
+    return runGit(cmd, args, cwd, NETWORK_TIMEOUT_MS);
+}
+
+/** The git questions target resolution asks, injected so no network is needed in tests. */
+export interface TargetDeps {
+    /** The default branch as a remote-tracking ref (`origin/main`), or null. */
+    readonly defaultBranch: () => string | null;
+    /** The SHA the server reports for a ref right now, or null. */
+    readonly remoteSha: (ref: string) => string | null;
+    /** The configured remote names; without it only `origin/` marks a remote. */
+    readonly remotes?: () => readonly string[];
+    /** The default branch another remote's server names (`upstream/main`), or null. */
+    readonly defaultBranchOf?: (remote: string) => string | null;
+}
+
+export type TargetReason = 'explicit-base-override' | 'repository-default-branch';
+
+export interface TargetRef {
+    readonly ref: string;
+    readonly reason: TargetReason;
+}
+
+/**
+ * The ref a branch is judged against: `--base`, else the default branch.
+ * `defaultRef` is passed by a caller that already asked for it.
+ */
+export function resolveTarget(deps: TargetDeps, override: string | null, defaultRef?: string | null): TargetRef | null {
+    // A bare name is the branch on origin: the local branch of that name is a
+    // clone-time copy nothing keeps current.
+    const given = override === null ? null : parseBaseRef(override, deps.remotes?.() ?? []);
+    if (given !== null) return { ref: given.ref, reason: 'explicit-base-override' };
+    const def = defaultRef === undefined ? deps.defaultBranch() : defaultRef;
+    return def === null ? null : { ref: def, reason: 'repository-default-branch' };
+}
+
+/**
+ * The default branch the SERVER reports, from `git ls-remote --symref origin HEAD`.
+ *
+ * Pure and exported so the parse is testable without a network round trip, and
+ * because it closes a measured defect rather than a hypothetical one. Until
+ * 2026-09-03 the default branch was read from `refs/remotes/origin/HEAD` alone —
+ * a clone-time ref that is simply absent in some checkouts. Measured in a
+ * worktree of this repository the same day: the local form returned null, so
+ * `sync_pr_branch` refused with "no open PR and no origin/HEAD" while
+ * `check_branch_freshness`, three lines later in the same documented sequence,
+ * resolved `origin/main` from the server symref and passed. Mirrors
+ * `check_branch_freshness.ts:223`.
+ */
+export function parseSymrefDefault(lsRemoteOut: string): string | null {
+    for (const line of lsRemoteOut.split('\n')) {
+        const t = line.trim();
+        if (!t.startsWith('ref:')) continue;
+        const name = t.slice('ref:'.length).trim().split(/\s+/)[0] ?? '';
+        if (!name.startsWith('refs/heads/')) continue;
+        const short = name.slice('refs/heads/'.length).trim();
+        if (short !== '') return `origin/${short}`;
+    }
+    return null;
+}
+
+/**
+ * The SHA of exactly `refs/heads/<branch>` in `git ls-remote` output.
+ *
+ * A ls-remote pattern matches every ref whose trailing path components equal
+ * it and the output is sorted by refname, so `backport/main` is listed before
+ * `main`: the first line is not the branch that was asked for. A SHA-256
+ * repository reports 64 hex digits, a SHA-1 one 40.
+ */
+export function parseExactHeadSha(lsRemoteOut: string, branch: string): string | null {
+    const want = `refs/heads/${branch}`;
+    for (const line of lsRemoteOut.split('\n')) {
+        const [sha, name] = line.trim().split(/\s+/);
+        if (name === want && sha !== undefined && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha)) return sha;
+    }
+    return null;
+}
+
+export function makeTargetDeps(repo: string, run: GitRunner = runGit): TargetDeps {
+    const ask = (cmd: string, args: readonly string[]): GitRunResult => run(cmd, args, repo, NETWORK_TIMEOUT_MS);
+    return {
+        // The server first, the local ref second: `refs/remotes/origin/HEAD` is
+        // not set in every checkout (see `parseSymrefDefault`).
+        defaultBranch: (): string | null => {
+            const remote = ask('git', ['ls-remote', '--symref', '--', 'origin', 'HEAD']);
+            const fromServer = remote.ok ? parseSymrefDefault(remote.out) : null;
+            if (fromServer !== null) return fromServer;
+            const head = ask('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+            return head.ok && head.out.trim() !== '' ? head.out.trim() : null;
+        },
+        remoteSha: (ref: string): string | null => {
+            const { remote, branch } = splitResolvedRef(ref);
+            const out = ask('git', ['ls-remote', '--', remote, `refs/heads/${branch}`]);
+            return out.ok ? parseExactHeadSha(out.out, branch) : null;
+        },
+        remotes: (): readonly string[] => {
+            const out = ask('git', ['remote']);
+            return out.ok ? out.out.split('\n').map((r) => r.trim()).filter((r) => r !== '') : [];
+        },
+        defaultBranchOf: (remote: string): string | null => {
+            const out = ask('git', ['ls-remote', '--symref', '--', remote, 'HEAD']);
+            const named = out.ok ? parseSymrefDefault(out.out) : null;
+            return named === null ? null : `${remote}/${named.slice('origin/'.length)}`;
+        },
+    };
+}
+
+/**
+ * The same questions, each asked of git at most once. One run reads the
+ * strategy and then syncs; without this each step asked again, paying the
+ * network twice and able to judge the strategy against one commit and sync
+ * against another when the target moves in between.
+ */
+export function memoTargetDeps<T extends TargetDeps>(deps: T): T {
+    const cache = new Map<string, unknown>();
+    const once = <V>(key: string, ask: () => V): V => {
+        if (!cache.has(key)) cache.set(key, ask());
+        return cache.get(key) as V;
+    };
+    return {
+        ...deps,
+        defaultBranch: (): string | null => once('default', () => deps.defaultBranch()),
+        remoteSha: (ref: string): string | null => once(`sha ${ref}`, () => deps.remoteSha(ref)),
+        ...(deps.remotes === undefined ? {} : { remotes: (): readonly string[] => once('remotes', () => (deps.remotes as () => readonly string[])()) }),
+        ...(deps.defaultBranchOf === undefined
+            ? {}
+            : { defaultBranchOf: (remote: string): string | null => once(`default ${remote}`, () => (deps.defaultBranchOf as (r: string) => string | null)(remote)) }),
+    };
+}
+
+/**
+ * `absent` (the commit has no carrier) and `no-commit` (the commit itself is
+ * unknown) are different facts; `timedOut` marks a commit the fetch ran out of
+ * time on, which says nothing about whether it exists.
+ */
+export type CommitBlob = { kind: 'absent' } | { kind: 'present'; text: string } | { kind: 'no-commit'; timedOut?: boolean };
+
+/**
+ * The carrier as one commit holds it. A commit the server reported but this
+ * clone has not fetched yet is fetched by its ref once; an answer of "the file
+ * does not exist" is only ever given for a commit that is present.
+ */
+export function carrierBlobAt(repo: string, sha: string, fetchRef: string | null, run: GitRunner = runGit): CommitBlob {
+    const local = (args: readonly string[]): GitRunResult => run('git', args, repo, NETWORK_TIMEOUT_MS);
+    const has = (): boolean => local(['cat-file', '-e', `${sha}^{commit}`]).ok;
+    if (!has()) {
+        const from = fetchRef === null ? null : splitResolvedRef(fetchRef);
+        const fetched = from === null ? null : run('git', ['fetch', '-q', '--', from.remote, from.branch], repo, CARRIER_FETCH_TIMEOUT_MS);
+        if (fetched?.timedOut === true) return { kind: 'no-commit', timedOut: true };
+        if (!has()) return { kind: 'no-commit' };
+    }
+    const listed = local(['ls-tree', '--name-only', sha, '--', CARRIER_PATH]);
+    if (!listed.ok) return { kind: 'no-commit' };
+    if (listed.out.trim() === '') return { kind: 'absent' };
+    const blob = local(['cat-file', '-p', `${sha}:${CARRIER_PATH}`]);
+    return blob.ok ? { kind: 'present', text: blob.out } : { kind: 'no-commit' };
+}
+
+/** A filename a carrier is sometimes given that nothing reads. */
+export const IGNORED_CARRIER_PATH = '.git-convention.yaml';
+
+/** The warning every reader prints when `root` holds a carrier under the name nothing reads, or null. */
+export function ignoredCarrierWarning(root: string): string | null {
+    return fs.existsSync(path.join(root, IGNORED_CARRIER_PATH))
+        ? `${IGNORED_CARRIER_PATH} is ignored — the team declaration is read only from ${CARRIER_PATH}; rename it to ${CARRIER_PATH}`
+        : null;
+}
+
+/**
+ * The carrier holds its keys under `git:`, as the settings files do. Keys set at
+ * the top level are read by nothing, and reading them as absent would apply the
+ * default the file was written to replace.
+ */
+function _parseCarrier(text: string): Pick<GitConventionLayer, 'parsed' | 'data' | 'why' | 'shapeError'> {
+    const parsed = parseLayerText(text);
+    if (parsed.parsed !== 'valid') return parsed;
+    const top = Object.keys(parsed.data as Record<string, unknown>).filter((k) => (GIT_CONVENTION_KEYS as readonly string[]).includes(k));
+    if (top.length === 0) return parsed;
+    const listed = top.map((k) => `\`${k}\``).join(', ');
+    return { ...parsed, shapeError: `${listed} set at the top level; the carrier reads its keys under \`git:\` (\`git:\` on one line, then \`  ${top[0]}: <value>\` indented)` };
+}
+
+function _carrierLayer(label: string, blob: Exclude<CommitBlob, { kind: 'no-commit' }>): GitConventionLayer {
+    if (blob.kind === 'absent') return { path: label, carries: true, parsed: 'absent', data: null };
+    return { path: label, carries: true, ..._parseCarrier(blob.text) };
+}
+
+/** Read failures map as `git_convention.ts` maps them for the developer files. */
+function _workingTreeLayer(root: string): GitConventionLayer {
+    const p = path.join(root, CARRIER_PATH);
+    let text: string;
+    try {
+        if (!fs.statSync(p).isFile()) return { path: p, carries: true, parsed: 'absent', data: null };
+        text = fs.readFileSync(p, 'utf-8');
+    } catch (err) {
+        const parsed = (err as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'malformed';
+        return { path: p, carries: true, parsed, data: null };
+    }
+    return { path: p, carries: true, ..._parseCarrier(text) };
+}
+
+/** The repository root, and whether it is a git repository at all. */
+export function conventionRoot(cwd: string): { root: string; git: boolean } {
+    const top = sh('git', ['rev-parse', '--show-toplevel'], cwd);
+    if (top.ok && top.out.trim() !== '') return { root: top.out.trim(), git: true };
+    return { root: find_project_root(cwd) ?? cwd, git: false };
+}
+
+export interface ConventionTarget extends TargetRef {
+    readonly sha: string | null;
+}
+
+export interface CommittedConvention {
+    readonly root: string;
+    /** The value in force per key. */
+    readonly readings: Partial<Record<GitConventionKey, GitConventionReading>>;
+    /** The commit the carrier was read at per key; null outside a git repository. */
+    readonly readAt: Partial<Record<GitConventionKey, string | null>>;
+    /** What `update_strategy` was judged against; null when no target was asked for. */
+    readonly target: ConventionTarget | null;
+    /** The checkout's own value per key, only where it differs from the value in force. */
+    readonly candidates: Partial<Record<GitConventionKey, GitConventionReading>>;
+}
+
+export interface CommittedOptions {
+    readonly override?: string | null;
+    readonly deps?: TargetDeps;
+    readonly keys?: readonly GitConventionKey[];
+    /** Runs the git calls that read the carrier at a commit. */
+    readonly run?: GitRunner;
+    /** `false` reads only a commit already in this checkout; a missing one is `unresolvable`, never fetched. */
+    readonly fetch?: boolean;
+}
+
+function _short(sha: string): string {
+    return sha.slice(0, 12);
+}
+
+/** The git convention in force for the repository that contains `cwd`. */
+export function readCommittedConvention(cwd: string, options: CommittedOptions = {}): CommittedConvention {
+    const keys = options.keys ?? GIT_CONVENTION_KEYS;
+    const { root, git } = conventionRoot(cwd);
+    const developer = checkoutSource(root).layers();
+    const readings: Partial<Record<GitConventionKey, GitConventionReading>> = {};
+    const readAt: Partial<Record<GitConventionKey, string | null>> = {};
+    const candidates: Partial<Record<GitConventionKey, GitConventionReading>> = {};
+    let target: ConventionTarget | null = null;
+
+    // Outside a git repository there is no committed layer to read.
+    if (!git) {
+        for (const key of keys) {
+            readings[key] = readGitConventionKey(key, { layers: () => developer });
+            readAt[key] = null;
+        }
+        return { root, readings, readAt, target, candidates };
+    }
+
+    const headSha = sh('git', ['rev-parse', '--verify', '-q', 'HEAD'], root).out.trim();
+    const headLabel = `${CARRIER_PATH} at ${headSha === '' ? 'HEAD' : _short(headSha)}`;
+    let headBlob: CommitBlob | null = null;
+    const atHead = (): CommitBlob => {
+        if (headBlob === null) headBlob = headSha === '' ? { kind: 'absent' } : carrierBlobAt(root, headSha, null, options.run);
+        return headBlob;
+    };
+
+    for (const key of keys) {
+        if (key !== 'update_strategy') {
+            const blob = atHead();
+            readings[key] = blob.kind === 'no-commit'
+                ? conventionReading(key, 'unresolvable', null, headLabel, `the carrier at HEAD (${_short(headSha)}) could not be read`)
+                : readGitConventionKey(key, { layers: () => [...developer, _carrierLayer(headLabel, blob)] });
+            readAt[key] = headSha === '' ? null : headSha;
+            continue;
+        }
+        const deps = options.deps ?? makeTargetDeps(root);
+        const ref = resolveTarget(deps, options.override ?? null);
+        const sha = ref === null ? null : deps.remoteSha(ref.ref);
+        target = ref === null ? null : { ...ref, sha };
+        readAt[key] = sha;
+        if (ref === null || sha === null) {
+            readings[key] = conventionReading(
+                key,
+                'unresolvable',
+                null,
+                CARRIER_PATH,
+                ref === null
+                    ? 'no --base was given and origin names no default branch, so the target commit is unknown'
+                    : `the server reports no commit for ${ref.ref} (no such branch on ${splitResolvedRef(ref.ref).remote}, no such remote, or it is unreachable)`,
+            );
+            continue;
+        }
+        const blob = carrierBlobAt(root, sha, options.fetch === false ? null : ref.ref, options.run);
+        if (blob.kind === 'no-commit') {
+            readings[key] = conventionReading(
+                key,
+                'unresolvable',
+                null,
+                `${CARRIER_PATH} at ${_short(sha)}`,
+                blob.timedOut === true
+                    ? `fetching commit ${_short(sha)} of ${ref.ref} timed out after ${CARRIER_FETCH_TIMEOUT_MS / 1000} s`
+                    : `commit ${_short(sha)} of ${ref.ref} could not be fetched`,
+            );
+            continue;
+        }
+        readings[key] = readGitConventionKey(key, { layers: () => [...developer, _carrierLayer(`${CARRIER_PATH} at ${_short(sha)}`, blob)] });
+    }
+
+    const tree = _workingTreeLayer(root);
+    for (const key of keys) {
+        const inForce = readings[key] as GitConventionReading;
+        const local = readGitConventionKey(key, { layers: () => [...developer, tree] });
+        if (local.value !== inForce.value || local.state !== inForce.state) candidates[key] = local;
+    }
+    return { root, readings, readAt, target, candidates };
+}

package/src/scripts/_lib/git_convention_grammar.ts

@@ -0,0 +1,246 @@
+/**
+ * The ticket grammar, the commit-subject grammars and the branch renderer.
+ *
+ * These were restated as regexes across several commands and checked by a model
+ * reading them, which let a ticket inside a compound scope pass and left an
+ * approved measured family with no validator at all. Pure: no I/O, so the CLI,
+ * the reference generator and the tests read the same values.
+ */
+
+export const TICKET_GRAMMAR = '[A-Z][A-Z0-9]+-[0-9]+';
+
+/**
+ * The grammar as a whole token: no letter or digit right before the key and no
+ * digit right after the number, so `fooDEV-12` holds no ticket. A version-like
+ * key (`HTTP2-1`, `V2-3`) is still ticket-shaped under the grammar; a card's
+ * `ticket_keys` is what tells it apart.
+ */
+export const TICKET_TOKEN = `(?<![A-Za-z0-9])${TICKET_GRAMMAR}(?![0-9])`;
+
+/** Prefixes of standard names that share the ticket shape (`UTF-8`, `CVE-2026-1234`). */
+export const TICKET_DENYLIST = ['UTF', 'ISO', 'SHA', 'RFC', 'CVE', 'CWE', 'GHSA'] as const;
+
+/**
+ * Protocol and language names that branch names carry with a major version
+ * (`HTTP-2`, `PHP-8`). Without a card such a key with a one-digit number is
+ * `version-like`, not a ticket; a card that lists the key keeps it a ticket.
+ * Two or more digits read as a ticket number, which is how the two are told apart.
+ */
+export const VERSION_LIKE_KEYS = ['HTTP', 'HTTPS', 'TLS', 'SSL', 'OAUTH', 'PHP', 'PYTHON', 'JAVA', 'JDK', 'NODE', 'ES', 'HTML', 'CSS'] as const;
+
+export type TicketStatus = 'ticket' | 'standard-name' | 'version-like' | 'unknown-key';
+
+export interface TicketCandidate {
+    token: string;
+    key: string;
+    status: TicketStatus;
+}
+
+/** The ticket token in either case, scanned only when a card names the keys. */
+const ANY_CASE_TOKEN = `(?<![A-Za-z0-9])[A-Za-z][A-Za-z0-9]+-[0-9]+(?![0-9])`;
+
+/**
+ * Every ticket-shaped token in `text`, in order. With `keys`, a candidate whose
+ * key is not listed is `unknown-key`, and a key written in another case is
+ * matched against the list and returned upper-cased; a lower-case token whose
+ * key is not listed is not a candidate. Without `keys` only upper-case tokens
+ * count, and the grammar, the denylist and the version-like names decide.
+ */
+export function ticketCandidates(text: string, keys?: readonly string[] | null): TicketCandidate[] {
+    const card = keys !== undefined && keys !== null && keys.length > 0 ? keys : null;
+    const out: TicketCandidate[] = [];
+    for (const m of text.matchAll(new RegExp(card === null ? TICKET_TOKEN : ANY_CASE_TOKEN, 'g'))) {
+        const dash = m[0].indexOf('-');
+        const written = m[0].slice(0, dash);
+        const key = written.toUpperCase();
+        const number = m[0].slice(dash + 1);
+        if (written !== key && !card?.includes(key)) continue;
+        let status: TicketStatus = 'ticket';
+        if ((TICKET_DENYLIST as readonly string[]).includes(key)) status = 'standard-name';
+        else if (card !== null) status = card.includes(key) ? 'ticket' : 'unknown-key';
+        else if (number.length === 1 && (VERSION_LIKE_KEYS as readonly string[]).includes(key)) status = 'version-like';
+        out.push({ token: `${key}-${number}`, key, status });
+    }
+    return out;
+}
+
+export function firstTicket(text: string, keys?: readonly string[] | null): string | null {
+    return ticketCandidates(text, keys).find((c) => c.status === 'ticket')?.token ?? null;
+}
+
+const KEY = /^[A-Z][A-Z0-9]+$/;
+
+/**
+ * The approved project keys from a convention card's `ticket_keys` line, or
+ * from that line's value alone. A card without the line yields none.
+ */
+export function parseTicketKeys(text: string): string[] {
+    const line = /^\s*ticket_keys\s*:(.*)$/m.exec(text)?.[1];
+    const value = line ?? (text.includes(':') ? '' : text);
+    return value
+        .replace(/[[\]"']/g, ' ')
+        .split(/[\s,]+/)
+        .filter((k) => KEY.test(k));
+}
+
+/** The keys a commitlint config's `issuePrefixes` names: offered for the card, never written by code. */
+export function commitlintIssuePrefixes(configText: string): string[] {
+    const list = /["']?issuePrefixes["']?\s*:\s*\[([^\]]*)\]/.exec(configText)?.[1] ?? '';
+    return [...list.matchAll(/["']([^"']*)["']/g)].map((m) => (m[1] as string).replace(/-$/, '')).filter((k) => KEY.test(k));
+}
+
+export const COMMIT_TYPES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'perf', 'style', 'build', 'ci', 'revert'] as const;
+
+export type CommitFormat = 'ticket-scope' | 'ticket-conventional';
+export type SubjectFamily = 'conventional' | 'ticket-conventional' | 'ticket-prefix' | 'gitmoji' | 'imperative-plain';
+
+const TYPES = COMMIT_TYPES.join('|');
+
+/** The `git.commit_format` grammars, in the syntax a JavaScript or PCRE engine reads. */
+export const FORMAT_GRAMMAR: Readonly<Record<CommitFormat, string>> = {
+    'ticket-scope': `^(${TYPES})(\\([^)]+\\))?!?: .+`,
+    'ticket-conventional': `^(${TICKET_GRAMMAR} )?(${TYPES})(\\([^)]+\\))?!?: .+`,
+};
+
+/**
+ * The measured families as POSIX extended regular expressions, matched in
+ * order, first hit wins; anything else is `other`.
+ */
+export const FAMILY_ERE: ReadonlyArray<readonly [SubjectFamily, string]> = [
+    ['conventional', '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([^)]+\\))?!?: '],
+    ['ticket-conventional', `^${TICKET_GRAMMAR} (build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\([^)]+\\))?!?: `],
+    ['ticket-prefix', `^\\[${TICKET_GRAMMAR}\\][: ]|^${TICKET_GRAMMAR}[: ]`],
+    // `[:ascii:]` is not a POSIX class (GNU and BSD grep reject it); a leading
+    // character outside printable ASCII, the controls and the spaces is the same set.
+    ['gitmoji', '^:[a-z0-9_+-]+:[[:space:]]|^[^ -~[:cntrl:][:space:]]'],
+    ['imperative-plain', '^[A-Z][a-z]+[[:space:]].*[^.]$'],
+];
+
+/** The two POSIX bracket expressions the families use, and nothing else, translated for a JavaScript engine. */
+function _js(ere: string): RegExp {
+    return new RegExp(ere.replaceAll('[^ -~[:cntrl:][:space:]]', '[^\\x00-\\x7F\\s]').replaceAll('[[:space:]]', '\\s'));
+}
+
+const FAMILY_JS: ReadonlyArray<readonly [SubjectFamily, RegExp]> = FAMILY_ERE.map(([f, ere]) => [f, _js(ere)] as const);
+
+export function classifySubject(subject: string): SubjectFamily | 'other' {
+    return FAMILY_JS.find(([, re]) => re.test(subject))?.[0] ?? 'other';
+}
+
+export type SubjectRule = { format: CommitFormat } | { family: SubjectFamily };
+export type SubjectVerdict = { ok: true } | { ok: false; rule: string };
+
+const SCOPE = /^[^(:]*\(([^)]*)\)/;
+
+/** Grammars where the ticket leads the subject, so a ticket in the scope is a second, misplaced copy. */
+function _ticketLeads(rule: SubjectRule): boolean {
+    return 'format' in rule ? rule.format === 'ticket-conventional' : rule.family === 'ticket-conventional';
+}
+
+export function ruleName(rule: SubjectRule): string {
+    return 'format' in rule ? `git.commit_format: ${rule.format}` : `approved family ${rule.family}`;
+}
+
+/** Subjects git writes itself (`commit --fixup`, `--squash`, `--fixup=amend:`, `revert`), valid under every format and every approved family. */
+export const GIT_OWN_SUBJECT = '^((fixup|squash|amend)! .+|Revert ".+")$';
+
+/**
+ * A family's form without its ticket, for the families whose ticket is a
+ * leading part (owner decision 2026-10-07): the ticket is optional, as under
+ * the `ticket-conventional` setting value, and when present it leads.
+ */
+export const TICKETLESS_FORM: Readonly<Partial<Record<SubjectFamily, string>>> = {
+    'ticket-prefix': '^\\S.*',
+    'ticket-conventional': FAMILY_ERE[0]?.[1] ?? '',
+};
+
+export function checkSubject(subject: string, rule: SubjectRule): SubjectVerdict {
+    if (new RegExp(GIT_OWN_SUBJECT).test(subject)) return { ok: true };
+    const grammar = 'format' in rule ? new RegExp(FORMAT_GRAMMAR[rule.format]) : (FAMILY_JS.find(([f]) => f === rule.family)?.[1] as RegExp);
+    const ticketless = 'family' in rule ? TICKETLESS_FORM[rule.family] : undefined;
+    if (!grammar.test(subject) && ticketless !== undefined) {
+        const family = (rule as { family: SubjectFamily }).family;
+        if (!_js(ticketless).test(subject)) {
+            return { ok: false, rule: `${ruleName(rule)} — does not match ${FAMILY_ERE.find(([f]) => f === family)?.[1] ?? ''}, nor its form without a ticket ${ticketless}` };
+        }
+        const stray = ticketCandidates(subject).find((c) => c.status === 'ticket');
+        if (stray !== undefined) {
+            return { ok: false, rule: `${ruleName(rule)} — the ticket \`${stray.token}\` stands outside the leading position; it leads the subject or is left out` };
+        }
+        return { ok: true };
+    }
+    if (!grammar.test(subject)) {
+        return { ok: false, rule: `${ruleName(rule)} — does not match ${'format' in rule ? FORMAT_GRAMMAR[rule.format] : (FAMILY_ERE.find(([f]) => f === rule.family)?.[1] ?? '')}` };
+    }
+    if (!_ticketLeads(rule)) return { ok: true };
+    const lead = /^(\S+) /.exec(subject)?.[1] ?? '';
+    const leading = ticketCandidates(lead).find((c) => c.token === lead);
+    if (leading !== undefined && leading.status === 'standard-name') {
+        return { ok: false, rule: `${ruleName(rule)} — \`${lead}\` is a standard name, not a ticket` };
+    }
+    const scope = SCOPE.exec(lead === '' || leading === undefined ? subject : subject.slice(lead.length + 1))?.[1] ?? '';
+    const inScope = ticketCandidates(scope).find((c) => c.status === 'ticket');
+    if (inScope !== undefined) {
+        return { ok: false, rule: `${ruleName(rule)} — the ticket \`${inScope.token}\` stands inside the scope; it leads the subject, never the scope` };
+    }
+    return { ok: true };
+}
+
+export interface BranchInput {
+    type?: string | null;
+    ticket?: string | null;
+    slug: string;
+}
+
+export type BranchRender = { ok: true; name: string } | { ok: false; reason: string };
+
+const VALUE = /^[A-Za-z0-9._-]+$/;
+const SEPARATORS = '-/_.';
+
+/**
+ * `pattern` with its placeholders filled. An empty placeholder drops together
+ * with the separator after it, or the one before it when it is last; a ticket
+ * the pattern has no slot for prefixes the slug. Literal characters of the
+ * pattern are never rewritten, and a value outside `[A-Za-z0-9._-]` is refused
+ * rather than repaired, because the name reaches shell commands.
+ */
+export function renderBranch(pattern: string, input: BranchInput): BranchRender {
+    const type = input.type ?? '';
+    const ticket = input.ticket ?? '';
+    let slug = input.slug;
+    if (slug === '' || !VALUE.test(slug)) return { ok: false, reason: `slug ${JSON.stringify(slug)} is empty or outside [A-Za-z0-9._-]` };
+    if (type !== '' && !VALUE.test(type)) return { ok: false, reason: `type ${JSON.stringify(type)} is outside [A-Za-z0-9._-]` };
+    if (ticket !== '' && !new RegExp(`^${TICKET_GRAMMAR}$`).test(ticket)) {
+        return { ok: false, reason: `ticket ${JSON.stringify(ticket)} does not match ${TICKET_GRAMMAR}` };
+    }
+    if (ticket !== '' && !pattern.includes('{ticket}') && slug !== ticket && !slug.startsWith(`${ticket}-`)) slug = `${ticket}-${slug}`;
+
+    const values: Record<string, string> = { type, ticket, slug };
+    const parts = pattern.split(/(\{(?:type|ticket|slug)\})/).filter((p) => p !== '');
+    const out: string[] = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i] as string;
+        const ph = /^\{(type|ticket|slug)\}$/.exec(part);
+        if (ph === null) {
+            out.push(part);
+            continue;
+        }
+        const value = values[ph[1] as string] as string;
+        if (value !== '') {
+            out.push(value);
+            continue;
+        }
+        const next = parts[i + 1];
+        if (next !== undefined && !next.startsWith('{') && SEPARATORS.includes(next[0] as string)) {
+            parts[i + 1] = next.slice(1);
+        } else if (next === undefined && out.length > 0) {
+            const prev = out[out.length - 1] as string;
+            if (SEPARATORS.includes(prev.slice(-1))) out[out.length - 1] = prev.slice(0, -1);
+        }
+    }
+    const name = out.join('');
+    if (name === '' || name.startsWith('/') || name.endsWith('/') || name.includes('//') || name.includes('..')) {
+        return { ok: false, reason: `the rendered name ${JSON.stringify(name)} is not a branch name` };
+    }
+    return { ok: true, name };
+}