@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/_lib/dispatch_import_closure.ts

@@ -0,0 +1,163 @@
+/**
+ * The static import closure of the hook dispatcher, and the class of each
+ * module in it.
+ *
+ * `check_kernel_edit_ratified` derives part of its watched set from this
+ * reading: a module the dispatcher reaches that decides an exit code needs a
+ * ratification record, whichever file the logic currently lives in. A hand
+ * list stayed correct until one function moved files; a derived set follows it.
+ *
+ * Deliberately static and deliberately narrow, so the reading is reproducible
+ * from a tree alone:
+ *
+ *   - only RELATIVE specifiers (`./x.js`, `../_lib/y.js`) are followed —
+ *     packages and `node:` builtins are not this repository's plumbing;
+ *   - `import … from`, `export … from` and side-effect `import '…'` count;
+ *     dynamic `import()` does not, because its target is not decidable here;
+ *   - the walk STOPS at the concern table. Every module `concern_registry.ts`
+ *     imports is a concern, classed `concern` and not walked into, because
+ *     concerns stay outside the fence — a governance concern is gated by its
+ *     own `block_*` pattern, and widening to every concern would turn routine
+ *     edits into record-carrying ones.
+ *
+ * Classes, decided from the module's own source text:
+ *
+ *   - `verdict` — names an exit-code constant (`EXIT_ALLOW`, `EXIT_BLOCK`,
+ *     `EXIT_WARN`, `EXIT_USAGE`), or exports a function whose name says it
+ *     decides a refusal (`deny…`, `…block…`, `…verdict…`, `…fail_closed…`).
+ *     The constants are how the dispatcher turns a crash, a timeout or a stdin
+ *     failure into the code a host acts on; the second signal catches a policy
+ *     that returns a boolean the dispatcher then maps — `denyOnStdinFailure`
+ *     names no constant and still decides whether a failed read refuses.
+ *   - `payload` — names the payload a concern receives (`payload`, `stdin`).
+ *   - `neither` — everything else (timing, state I/O, logging).
+ *   - `concern` — imported by the concern table; outside the fence.
+ *
+ * The classes read NAMES, not data flow. A module already in the closure as
+ * `payload` or `neither` that gains verdict-influencing logic under a neutral
+ * name is not reclassified; the gate covers the arrival of such a module
+ * (`closureArrivals`) and its declassification (the base∪head union), not this.
+ * Closing it needs call-graph analysis — a different design, not a tweak.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The dispatcher, repo-relative. The closure's root. */
+export const DISPATCHER_PATH = 'src/scripts/hooks/dispatch_hook.ts';
+
+/** The concern table. Its imports are concerns, the walk's boundary. */
+export const CONCERN_REGISTRY_PATH = 'src/scripts/hooks/concern_registry.ts';
+
+export type ModuleClass = 'verdict' | 'payload' | 'neither' | 'concern';
+
+export interface ClosureEntry {
+    /** Repo-relative POSIX path. */
+    path: string;
+    class: ModuleClass;
+}
+
+const EXIT_CONSTANT_RE = /\bEXIT_(?:ALLOW|BLOCK|WARN|USAGE)\b/;
+const VERDICT_EXPORT_RE =
+    /\bexport\s+(?:async\s+)?(?:function\s+|const\s+)([A-Za-z_$][\w$]*)/g;
+const VERDICT_NAME_RE = /deny|block|verdict|fail_?closed|refus/i;
+const PAYLOAD_RE = /\b(?:payload|stdin)\b/i;
+
+/**
+ * Relative specifiers in a module's source. Comments are stripped first so a
+ * commented-out import does not count as an edge.
+ */
+export function relativeSpecifiers(source: string): string[] {
+    const stripped = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+    const out: string[] = [];
+    const re = /(?:\bimport\s+(?:type\s+)?(?:[\s\S]*?\bfrom\s*)?|\bexport\s+(?:type\s+)?[\s\S]*?\bfrom\s*)['"](\.{1,2}\/[^'"]+)['"]/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(stripped)) !== null) {
+        if (m[1] !== undefined) {
+            out.push(m[1]);
+        }
+    }
+    return out;
+}
+
+/** Resolve a `.js` specifier from `fromRel` to the `.ts` source on disk. */
+function resolveSpecifier(root: string, fromRel: string, spec: string): string | null {
+    const base = path.posix.join(path.posix.dirname(fromRel), spec);
+    const candidates = [base.replace(/\.js$/, '.ts'), base, `${base}.ts`, `${base}/index.ts`];
+    for (const c of candidates) {
+        const norm = path.posix.normalize(c);
+        if (fs.existsSync(path.join(root, norm)) && fs.statSync(path.join(root, norm)).isFile()) {
+            return norm;
+        }
+    }
+    return null;
+}
+
+/** Classify one module from its source text. Never returns `concern`. */
+export function classifySource(source: string): Exclude<ModuleClass, 'concern'> {
+    if (EXIT_CONSTANT_RE.test(source)) {
+        return 'verdict';
+    }
+    for (const m of source.matchAll(VERDICT_EXPORT_RE)) {
+        if (VERDICT_NAME_RE.test(m[1] ?? '')) {
+            return 'verdict';
+        }
+    }
+    if (PAYLOAD_RE.test(source)) {
+        return 'payload';
+    }
+    return 'neither';
+}
+
+/**
+ * Walk the closure from the dispatcher under `root`. Returns `[]` when the
+ * dispatcher is absent, so a fixture tree without one yields an empty set
+ * rather than an error. The dispatcher itself is not in the result — it is
+ * already watched by name.
+ */
+export function dispatchImportClosure(root: string, entry: string = DISPATCHER_PATH): ClosureEntry[] {
+    if (!fs.existsSync(path.join(root, entry))) {
+        return [];
+    }
+    const seen = new Map<string, ModuleClass>();
+    const queue: string[] = [entry];
+    const visited = new Set<string>();
+    while (queue.length > 0) {
+        const rel = queue.shift() as string;
+        if (visited.has(rel)) {
+            continue;
+        }
+        visited.add(rel);
+        const source = fs.readFileSync(path.join(root, rel), 'utf8');
+        if (rel !== entry) {
+            seen.set(rel, classifySource(source));
+        }
+        const isRegistry = rel === CONCERN_REGISTRY_PATH;
+        for (const spec of relativeSpecifiers(source)) {
+            const target = resolveSpecifier(root, rel, spec);
+            if (target === null || target === entry) {
+                continue;
+            }
+            if (isRegistry) {
+                if (!seen.has(target)) {
+                    seen.set(target, 'concern');
+                }
+                visited.add(target);
+                continue;
+            }
+            if (!visited.has(target)) {
+                queue.push(target);
+            }
+        }
+    }
+    return [...seen.entries()]
+        .map(([p, c]) => ({ path: p, class: c }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** The verdict-deciding modules of the closure — the part the gate watches. */
+export function verdictModules(root: string): string[] {
+    return dispatchImportClosure(root)
+        .filter((e) => e.class === 'verdict')
+        .map((e) => e.path);
+}

package/src/scripts/_lib/git_base_ref.ts

@@ -0,0 +1,92 @@
+/**
+ * The one reading of a `--base` value, shared by `sync_pr_branch` and
+ * `check_branch_freshness`.
+ *
+ * The two resolvers used to accept different spellings: one prefixed every
+ * value with `origin/`, the other asked the server for `refs/heads/<value>`
+ * verbatim. A name copied from one tool's output into the other then named a
+ * ref nobody has (`origin/origin/main`, `refs/heads/origin/main`), and the
+ * freshness gate read that absent ref as an unreachable remote and passed.
+ *
+ * A value that already names where it lives is kept as given: a
+ * remote-tracking ref and `<remote>/x` for a configured remote. `refs/heads/x`
+ * names the branch on origin, so it maps to `refs/remotes/origin/x`: the local
+ * branch of that name is the same clone-time copy a bare name avoids, and a
+ * fetch never updates it. Anything else is a branch name on origin, slashes
+ * included, because `release/1.x` is a branch name and not a remote called
+ * `release`.
+ */
+
+export interface BaseRef {
+    /** The remote the server-side SHA is asked of. */
+    readonly remote: string;
+    /** The branch name on that remote. */
+    readonly branch: string;
+    /** The ref git operations use locally: as given, or `origin/<branch>` for a bare name. */
+    readonly ref: string;
+}
+
+const REMOTE_TRACKING = 'refs/remotes/';
+const LOCAL_HEADS = 'refs/heads/';
+
+/**
+ * The usage error for a `--base` given a blank value, or null for one that
+ * names something. Every tool that accepts `--base` rejects a blank one: an
+ * unset variable expands to nothing, and reading that as "no override" judged
+ * the run against the default branch without a word.
+ */
+export function blankBaseError(value: string): string | null {
+    return value.trim() === '' ? '--base was given an empty value — name the base branch (an unset variable expands to nothing); nothing was read or merged' : null;
+}
+
+/**
+ * The usage error for any `--base` value that must not reach git: a blank one,
+ * or one whose branch name starts with `-`, which git would read as an option.
+ * No branch can carry that name (`git check-ref-format --branch` refuses it).
+ */
+export function baseValueError(value: string, remotes: readonly string[] = []): string | null {
+    const blank = blankBaseError(value);
+    if (blank !== null) return blank;
+    const v = value.trim();
+    const branch = v.startsWith('-') ? v : (parseBaseRef(v, remotes)?.branch ?? v);
+    return branch.startsWith('-') ? `--base ${JSON.stringify(v)} names a branch that starts with "-", which git reads as an option — no branch has that name; nothing was read or merged` : null;
+}
+
+/** Read a `--base` value; null when it is empty. `remotes` are the configured remote names. */
+export function parseBaseRef(value: string, remotes: readonly string[] = []): BaseRef | null {
+    const v = value.trim();
+    if (v === '') return null;
+    if (v.startsWith(LOCAL_HEADS) && v.length > LOCAL_HEADS.length) {
+        const branch = v.slice(LOCAL_HEADS.length);
+        return { remote: 'origin', branch, ref: `${REMOTE_TRACKING}origin/${branch}` };
+    }
+    if (v.startsWith('refs/')) return splitResolvedRef(v);
+    const slash = v.indexOf('/');
+    const known = new Set(['origin', ...remotes]);
+    if (slash > 0 && slash < v.length - 1 && known.has(v.slice(0, slash))) {
+        return { remote: v.slice(0, slash), branch: v.slice(slash + 1), ref: v };
+    }
+    return { remote: 'origin', branch: v, ref: `origin/${v}` };
+}
+
+/**
+ * Split a ref that was already resolved by `parseBaseRef` or reported by git
+ * (`origin/main`, `refs/heads/main`). A full ref outside the branch namespaces
+ * keeps its whole name as the branch, so the server answers it as unknown.
+ */
+export function splitResolvedRef(ref: string): BaseRef {
+    if (ref.startsWith(LOCAL_HEADS)) return { remote: 'origin', branch: ref.slice(LOCAL_HEADS.length), ref };
+    if (ref.startsWith(REMOTE_TRACKING)) {
+        const rest = ref.slice(REMOTE_TRACKING.length);
+        const slash = rest.indexOf('/');
+        if (slash > 0) return { remote: rest.slice(0, slash), branch: rest.slice(slash + 1), ref };
+    }
+    if (ref.startsWith('refs/')) return { remote: 'origin', branch: ref, ref };
+    const slash = ref.indexOf('/');
+    return slash > 0 ? { remote: ref.slice(0, slash), branch: ref.slice(slash + 1), ref } : { remote: 'origin', branch: ref, ref: `origin/${ref}` };
+}
+
+/** `<remote>/<branch>`, the name a human reads and `task push-ready BASE=` accepts. */
+export function displayBase(b: BaseRef): string {
+    return `${b.remote}/${b.branch}`;
+}

package/src/scripts/_lib/git_convention.ts

@@ -0,0 +1,291 @@
+/**
+ * The one reader of the `git.*` convention keys.
+ *
+ * `load_agent_settings` merges a layer that does not parse as if it were absent
+ * and drops user-global keys off its whitelist without a word, which is right
+ * for a setting whose default is harmless and wrong for these three: a team that
+ * declares `rebase` and gets a merge commit because an unrelated line elsewhere
+ * in the file has an unclosed bracket has had its convention overridden by a
+ * default nobody chose. So every key is reported with one of six states, and a
+ * caller that acts on the value refuses on anything but `valid` or `absent`:
+ *
+ * - `valid`     — the deciding layer parsed and the value is allowed;
+ * - `absent`    — no layer sets the key; the template default is reported;
+ * - `malformed` — a layer at or above the deciding one does not parse, so the
+ *                 value is unknowable;
+ * - `invalid`   — the deciding layer sets a value the schema does not allow;
+ * - `discarded` — only a user-global file sets the key, and the loader drops
+ *                 user-global keys that are not whitelisted;
+ * - `unresolvable` — the commit a committed declaration must be read at cannot
+ *                 be resolved, so whether it declares anything is unknown.
+ *
+ * Where the layers come from is a {@link GitConventionSource}, so a reader of a
+ * committed declaration can replace the checkout cascade without touching the
+ * state logic.
+ */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+
+import type * as YamlModule from 'yaml';
+
+import { settings_layer_states, template_defaults, user_global_settings_paths } from './agent_settings.js';
+
+const _require = createRequire(import.meta.url);
+
+export const GIT_CONVENTION_KEYS = ['commit_format', 'branch_pattern', 'update_strategy'] as const;
+export type GitConventionKey = (typeof GIT_CONVENTION_KEYS)[number];
+
+export type GitConventionState = 'valid' | 'absent' | 'malformed' | 'invalid' | 'discarded' | 'unresolvable';
+
+/** Mirrors the enums in `agent-settings.schema.json`; a test pins the parity. */
+export const GIT_CONVENTION_ENUMS: Partial<Record<GitConventionKey, readonly string[]>> = {
+    commit_format: ['ticket-scope', 'ticket-conventional'],
+    update_strategy: ['merge', 'rebase'],
+};
+
+export type GitConventionReason =
+    | 'git-convention-malformed'
+    | 'git-convention-invalid'
+    | 'git-convention-discarded'
+    | 'git-convention-unresolvable';
+
+export interface GitConventionReading {
+    key: GitConventionKey;
+    value: string | null;
+    source: string | null;
+    state: GitConventionState;
+    reason: GitConventionReason | null;
+    detail: string | null;
+}
+
+export interface GitConventionLayer {
+    path: string;
+    parsed: 'absent' | 'valid' | 'malformed';
+    data: unknown;
+    /** False for a layer whose `git.*` values the loader discards. */
+    carries: boolean;
+    /** Why a `malformed` layer is unknown: it does not parse, or its document is not a map. */
+    why?: string;
+    /** Set when the document parses but is not the shape the file is read in; every key reads `invalid`. */
+    shapeError?: string;
+}
+
+export interface GitConventionSource {
+    /** Every layer, lowest precedence first. */
+    layers(): GitConventionLayer[];
+}
+
+export type GitConventionDefaults = Partial<Record<GitConventionKey, string>>;
+
+function _parse(p: string): Pick<GitConventionLayer, 'parsed' | 'data' | 'why'> {
+    let text: string;
+    try {
+        if (!fs.statSync(p).isFile()) return { parsed: 'absent', data: null };
+        text = fs.readFileSync(p, 'utf-8');
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { parsed: 'absent', data: null };
+        return { parsed: 'malformed', data: null, why: 'the file cannot be read' };
+    }
+    return parseLayerText(text);
+}
+
+/**
+ * Where the parse failed. An unquoted pattern (`{ticket}-{slug}`) is a flow
+ * mapping to YAML, and the error says nothing about quoting.
+ */
+function _parseFailure(text: string, err: unknown): string {
+    const line = (err as { linePos?: { line: number }[] }).linePos?.[0]?.line;
+    if (line === undefined) return 'the file does not parse';
+    const quote = (text.split('\n')[line - 1] ?? '').includes('{') ? `; a value containing \`{\` must be quoted, e.g. ${_quoteExample('branch_pattern')}` : '';
+    return `the file does not parse at line ${line}${quote}`;
+}
+
+function _quoteExample(key: GitConventionKey): string {
+    return `${key}: "${key === 'branch_pattern' ? '{ticket}-{slug}' : (GIT_CONVENTION_ENUMS[key]?.[0] ?? '…')}"`;
+}
+
+/** One layer's text, parsed the way the settings loader parses a file. */
+export function parseLayerText(text: string): Pick<GitConventionLayer, 'parsed' | 'data' | 'why'> {
+    let data: unknown;
+    try {
+        const YAML = _require('yaml') as typeof YamlModule;
+        data = YAML.parse(text, { version: '1.1' });
+    } catch (err) {
+        return { parsed: 'malformed', data: null, why: _parseFailure(text, err) };
+    }
+    if (data === null || data === undefined) return { parsed: 'valid', data: {} };
+    // The loader ignores a document that is not a map, which is the same silent
+    // fallback as a parse error.
+    if (typeof data !== 'object' || Array.isArray(data)) return { parsed: 'malformed', data: null, why: 'the document is not a map' };
+    return { parsed: 'valid', data };
+}
+
+/** Explicit files: the user-global ones carry nothing, the developer ones carry. */
+export function fileSource(files: { userGlobal?: readonly string[]; developer?: readonly string[] }): GitConventionSource {
+    return {
+        layers: () => [
+            ...(files.userGlobal ?? []).map((p) => ({ path: p, carries: false, ..._parse(p) })),
+            ...(files.developer ?? []).map((p) => ({ path: p, carries: true, ..._parse(p) })),
+        ],
+    };
+}
+
+/** The layers `load_agent_settings({ cwd })` reads for the checkout at `cwd`. */
+export function checkoutSource(cwd: string): GitConventionSource {
+    return {
+        layers: () => {
+            const userGlobalCount = user_global_settings_paths().length;
+            const all = settings_layer_states({ cwd }).map((l) => l.path);
+            return fileSource({ userGlobal: all.slice(0, userGlobalCount), developer: all.slice(userGlobalCount) }).layers();
+        },
+    };
+}
+
+type Lookup = { present: false } | { present: true; value: unknown } | { present: true; notAMap: true };
+
+function _lookup(data: unknown, key: GitConventionKey): Lookup {
+    if (data === null || typeof data !== 'object') return { present: false };
+    const git = (data as Record<string, unknown>).git;
+    if (git === undefined || git === null) return { present: false };
+    if (typeof git !== 'object' || Array.isArray(git)) return { present: true, notAMap: true };
+    const value = (git as Record<string, unknown>)[key];
+    if (value === undefined || value === null) return { present: false };
+    return { present: true, value };
+}
+
+const BRANCH_PLACEHOLDERS = ['type', 'ticket', 'slug'] as const;
+const BRANCH_SAMPLE: Record<(typeof BRANCH_PLACEHOLDERS)[number], string> = {
+    type: 'feat',
+    ticket: 'DEV-1234',
+    slug: 'sample-change',
+};
+/** A rendered name reaches shell commands, so the literal alphabet is closed. */
+const BRANCH_LITERAL = /^[A-Za-z0-9._/-]*$/;
+
+/** The pattern with every placeholder filled from a fixed sample. */
+export function renderBranchSample(pattern: string): string {
+    return pattern.replace(/\{(type|ticket|slug)\}/g, (_m, name: keyof typeof BRANCH_SAMPLE) => BRANCH_SAMPLE[name]);
+}
+
+function _branchPatternReason(pattern: string): string | null {
+    if (pattern === '') return 'the pattern is empty';
+    const literal = pattern.replace(/\{([^{}]*)\}/g, (match, name: string) => {
+        return (BRANCH_PLACEHOLDERS as readonly string[]).includes(name) ? '' : `\u0000${match}`;
+    });
+    const unknown = /\u0000(\{[^{}]*\})/.exec(literal);
+    if (unknown !== null) {
+        return `unknown placeholder ${unknown[1]}; allowed: ${BRANCH_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}`;
+    }
+    if (/[{}]/.test(literal)) return 'an unbalanced brace';
+    if (!BRANCH_LITERAL.test(literal)) {
+        const bad = [...new Set(literal.replace(/[A-Za-z0-9._/-]/g, ''))].join('');
+        return `literal character(s) ${JSON.stringify(bad)} outside [A-Za-z0-9._/-]`;
+    }
+    if (!pattern.includes('{slug}')) return 'the pattern must contain {slug}';
+    const sample = renderBranchSample(pattern);
+    const check = spawnSync('git', ['check-ref-format', '--branch', sample], { encoding: 'utf8' });
+    // Without git the closed alphabet above is the whole check.
+    if (check.error === undefined && check.status !== 0) {
+        return `the sample \`${sample}\` fails git check-ref-format --branch`;
+    }
+    return null;
+}
+
+/** Why `value` is not allowed for `key`, or null when it is. */
+export function invalidReason(key: GitConventionKey, value: string): string | null {
+    // The schema neither trims nor folds case, so neither does this check.
+    if (value !== value.trim()) return `\`${value}\` has leading or trailing whitespace`;
+    const allowed = GIT_CONVENTION_ENUMS[key];
+    if (allowed !== undefined) {
+        if (allowed.includes(value)) return null;
+        const caseOnly = allowed.includes(value.toLowerCase()) ? ' (values are case-sensitive)' : '';
+        return `\`${value}\` is not one of ${allowed.map((v) => `\`${v}\``).join(', ')}${caseOnly}`;
+    }
+    return _branchPatternReason(value);
+}
+
+function _defaults(): GitConventionDefaults {
+    const git = (template_defaults() as { git?: Record<string, unknown> }).git ?? {};
+    const out: GitConventionDefaults = {};
+    for (const key of GIT_CONVENTION_KEYS) {
+        if (typeof git[key] === 'string') out[key] = git[key] as string;
+    }
+    return out;
+}
+
+/** The template default for a key, or null when the template sets none. */
+export function conventionDefault(key: GitConventionKey): string | null {
+    return _defaults()[key] ?? null;
+}
+
+export function conventionReading(
+    key: GitConventionKey,
+    state: GitConventionState,
+    value: string | null,
+    source: string | null,
+    detail: string | null = null,
+): GitConventionReading {
+    const reason: GitConventionReason | null = isRefusal(state) ? (`git-convention-${state}` as GitConventionReason) : null;
+    return { key, value, source, state, reason, detail };
+}
+
+export function readGitConventionKey(
+    key: GitConventionKey,
+    source: GitConventionSource,
+    defaults: GitConventionDefaults = _defaults(),
+): GitConventionReading {
+    const layers = source.layers();
+    const fallback = defaults[key] ?? null;
+    for (const layer of [...layers].reverse().filter((l) => l.carries)) {
+        if (layer.parsed === 'malformed') {
+            return conventionReading(key, 'malformed', null, layer.path, `${layer.why ?? 'the file cannot be read'}, so the value it may set is unknown`);
+        }
+        if (layer.shapeError !== undefined) return conventionReading(key, 'invalid', null, layer.path, layer.shapeError);
+        const found = _lookup(layer.data, key);
+        if (!found.present) continue;
+        if ('notAMap' in found) return conventionReading(key, 'invalid', null, layer.path, '`git:` is not a map');
+        if (typeof found.value !== 'string') {
+            const shown = typeof found.value === 'object' && found.value !== null ? JSON.stringify(found.value) : String(found.value);
+            return conventionReading(key, 'invalid', shown, layer.path, `the value is not a string — quote the value, e.g. ${_quoteExample(key)}`);
+        }
+        const value = found.value;
+        const why = invalidReason(key, value);
+        return why === null ? conventionReading(key, 'valid', value, layer.path) : conventionReading(key, 'invalid', value, layer.path, why);
+    }
+    for (const layer of [...layers].reverse().filter((l) => !l.carries && l.parsed === 'valid')) {
+        const found = _lookup(layer.data, key);
+        if (!found.present || 'notAMap' in found) continue;
+        const value = typeof found.value === 'string' ? found.value : String(found.value);
+        if (fallback !== null && value === fallback) continue;
+        return conventionReading(
+            key,
+            'discarded',
+            value,
+            layer.path,
+            'user-global files do not carry git.* keys; set it in the project settings file',
+        );
+    }
+    return conventionReading(key, 'absent', fallback, null);
+}
+
+export function readGitConvention(
+    source: GitConventionSource,
+    defaults: GitConventionDefaults = _defaults(),
+): Record<GitConventionKey, GitConventionReading> {
+    const out = {} as Record<GitConventionKey, GitConventionReading>;
+    for (const key of GIT_CONVENTION_KEYS) out[key] = readGitConventionKey(key, source, defaults);
+    return out;
+}
+
+/** Every state a caller must not act on; `show`, `sync` and the `/pr:merge` prose share this one set. */
+export const REFUSAL_STATES: readonly GitConventionState[] = ['malformed', 'invalid', 'discarded', 'unresolvable'];
+
+export function isRefusal(state: GitConventionState): boolean {
+    return REFUSAL_STATES.includes(state);
+}
+
+/** One line naming the reason code, the key and the file. */
+export function describeRefusal(reading: GitConventionReading): string {
+    return `${reading.reason ?? 'git-convention-ok'}: git.${reading.key} in ${reading.source ?? '(no file)'} — ${reading.detail ?? reading.state}`;
+}