@event4u/agent-config 14.6.0 → 14.8.0

package/src/scripts/_lib/adr_frontmatter.ts

@@ -0,0 +1,459 @@
+/**
+ * One ADR frontmatter reader, for the three call sites that each had their own.
+ *
+ * Before this file the tree carried three independent parsers:
+ * `check_adr_frontmatter.parse_frontmatter` (folded indented continuations into
+ * the parent scalar), `adr_cite_check.parse_frontmatter` (the same, plus
+ * stripping a bare `>-` fold marker), and `adr/regenerate_index.fm` (a
+ * `^([a-z_]+):[ \t]*(.+?)[ \t]*$` regex, so a key with an empty value matched
+ * nothing and an indented line matched nothing either).
+ *
+ * Three readers were survivable while every field was a scalar. `provenance`
+ * and `evidence` are nested and carry lists, so the divergence stops being
+ * cosmetic: the regex reader would have read both as absent — silently, on the
+ * surface that renders the public index — while the other two would have folded
+ * them into one unusable string. Adding an axis to three parsers also pays for
+ * it three times, which is the reason this extraction lands BEFORE the axes
+ * rather than after.
+ *
+ * ## Scalar compatibility is the contract
+ *
+ * `scalars` reproduces the previous behaviour key-for-key, including the fold
+ * of an indented continuation into its parent and the `>-` strip. That is
+ * deliberate: the three call sites read `fm.status`, `fm.review_trigger`,
+ * `fm.superseded_by` and friends, and a reader that changed any of those
+ * values would be a behaviour change wearing a refactor's clothes.
+ *
+ * The one intentional difference: a key whose own value is empty and whose
+ * indented children look like `key: value` (or `- item`) becomes a **nested**
+ * entry and is kept out of `scalars` entirely, rather than folded into the
+ * garbage string the old readers produced. Nothing read those strings.
+ */
+
+/** A frontmatter value that is not a scalar. */
+export type AdrFrontmatterNode = string | string[] | { [key: string]: AdrFrontmatterNode };
+
+export interface AdrFrontmatter {
+    /**
+     * Scalar keys, byte-identical to what the three previous parsers produced
+     * for every shape that existed before the nested axes.
+     */
+    scalars: Record<string, string>;
+    /** Keys whose value is a nested map or a list. */
+    nested: Record<string, AdrFrontmatterNode>;
+    /** Source order of every top-level key, for diagnostics. */
+    keyOrder: string[];
+}
+
+/** Fold indicators: the value is a multi-line scalar, never a nested map. */
+const FOLD_MARKERS = new Set(['>', '>-', '>+', '|', '|-', '|+']);
+
+/**
+ * Consume an indented block as prose, with no map/list discrimination.
+ *
+ * Used whenever the parent carried a fold marker. Routing a folded block
+ * through `parseBlock` looked equivalent and was not: real `review_trigger`
+ * prose contains colons ("Reopen when an `exec:` claim is found green"), so the
+ * map branch claimed the first line and then stopped at the first line without
+ * one — truncating four ADRs' triggers to their opening clause. The corpus
+ * equivalence test is what caught it; a single-line fixture round-tripped
+ * correctly and hid the bug.
+ */
+function consumeFolded(lines: Line[], start: number, parentIndent: number): [string, number] {
+    const parts: string[] = [];
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent <= parentIndent) break;
+        parts.push(line.text);
+        i += 1;
+    }
+    return [parts.join(' ').trim(), i];
+}
+
+const QUOTED = /^["'](.*)["']$/;
+
+function stripQuotes(value: string): string {
+    return value.replace(QUOTED, '$1');
+}
+
+/** `[a, b, c]` → `['a','b','c']`; a bare `[]` → `[]`. */
+function parseInlineList(raw: string): string[] | null {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return null;
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner
+        .split(',')
+        .map((part) => stripQuotes(part.trim()))
+        .filter((part) => part !== '');
+}
+
+interface Line {
+    indent: number;
+    text: string;
+}
+
+/** Split the `---` block into significant lines, dropping blanks and comments. */
+function significantLines(block: string): Line[] {
+    const out: Line[] = [];
+    for (const raw of block.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (line === '') continue;
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('#')) continue;
+        out.push({ indent: line.length - trimmed.length, text: trimmed });
+    }
+    return out;
+}
+
+/**
+ * Parse one indented block into a map, a list, or a folded scalar.
+ *
+ * The discriminator is the block's own first line, not the parent key: `- x`
+ * opens a list, `k: v` opens a map, anything else is prose to fold. Keying on
+ * the parent name would have meant a hard-coded field list, which is the thing
+ * three divergent parsers already demonstrated does not survive a new axis.
+ */
+function parseBlock(lines: Line[], start: number, parentIndent: number): [AdrFrontmatterNode, number] {
+    const first = lines[start];
+    if (first === undefined) return ['', start];
+
+    // A list.
+    if (first.text.startsWith('- ') || first.text === '-') {
+        const items: string[] = [];
+        let i = start;
+        while (i < lines.length) {
+            const line = lines[i] as Line;
+            if (line.indent <= parentIndent || !line.text.startsWith('-')) break;
+            items.push(stripQuotes(line.text.replace(/^-\s*/, '').trim()));
+            i += 1;
+        }
+        return [items, i];
+    }
+
+    // A map — every child line at this indent carries a `key:`.
+    const colon = first.text.indexOf(':');
+    if (colon > 0) {
+        const map: Record<string, AdrFrontmatterNode> = {};
+        let i = start;
+        while (i < lines.length) {
+            const line = lines[i] as Line;
+            if (line.indent <= parentIndent) break;
+            const idx = line.text.indexOf(':');
+            if (idx <= 0) break;
+            const key = line.text.slice(0, idx).trim();
+            const rest = line.text.slice(idx + 1).trim();
+            i += 1;
+            if (rest === '' || FOLD_MARKERS.has(rest)) {
+                const next = lines[i];
+                if (next !== undefined && next.indent > line.indent) {
+                    if (FOLD_MARKERS.has(rest)) {
+                        const [folded, consumed] = consumeFolded(lines, i, line.indent);
+                        map[key] = folded;
+                        i = consumed;
+                        continue;
+                    }
+                    const [child, consumed] = parseBlock(lines, i, line.indent);
+                    map[key] = child;
+                    i = consumed;
+                    continue;
+                }
+                map[key] = '';
+                continue;
+            }
+            const inline = parseInlineList(rest);
+            map[key] = inline ?? stripQuotes(rest);
+        }
+        return [map, i];
+    }
+
+    // Prose — fold it.
+    const parts: string[] = [];
+    let i = start;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent <= parentIndent) break;
+        parts.push(line.text);
+        i += 1;
+    }
+    return [parts.join(' ').trim(), i];
+}
+
+/**
+ * Flatten a node back to the single string the old fold produced.
+ *
+ * A list renders as its inline literal (`[a, b]`) rather than as joined items,
+ * because that is what the previous parsers put in the scalar map for
+ * `protected_dimensions: [purpose]` and the corpus-equivalence test holds this
+ * reader to that byte-for-byte.
+ */
+function foldToString(node: AdrFrontmatterNode): string {
+    if (typeof node === 'string') return node;
+    if (Array.isArray(node)) return `[${node.join(', ')}]`;
+    return Object.entries(node)
+        .map(([k, v]) => `${k}: ${foldToString(v)}`)
+        .join(' ')
+        .trim();
+}
+
+/**
+ * Read the leading `---` block of an ADR.
+ *
+ * Returns `null` when there is no frontmatter at all — which is the honest
+ * answer for the seven per-area records, whose metadata lives in a blockquote
+ * line instead. `adr_cite_check` already declares them partial coverage for
+ * exactly this reason; this reader does not paper over it.
+ */
+export function readAdrFrontmatter(text: string): AdrFrontmatter | null {
+    if (!text.startsWith('---\n')) return null;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return null;
+
+    const lines = significantLines(text.slice(4, end));
+    const scalars: Record<string, string> = {};
+    const nested: Record<string, AdrFrontmatterNode> = {};
+    const keyOrder: string[] = [];
+
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] as Line;
+        if (line.indent > 0) {
+            // Orphan indented line with no parent — the old readers dropped
+            // these too (no key to fold into). Skip rather than invent one.
+            i += 1;
+            continue;
+        }
+        const idx = line.text.indexOf(':');
+        if (idx <= 0) {
+            i += 1;
+            continue;
+        }
+        const key = line.text.slice(0, idx).trim();
+        const rest = line.text.slice(idx + 1).trim();
+        keyOrder.push(key);
+        i += 1;
+
+        const next = lines[i];
+        const hasBlock = next !== undefined && next.indent > 0;
+
+        if (FOLD_MARKERS.has(rest) && hasBlock) {
+            const [folded, consumed] = consumeFolded(lines, i, 0);
+            scalars[key] = folded;
+            i = consumed;
+            continue;
+        }
+
+        if (rest === '' && hasBlock) {
+            const [child, consumed] = parseBlock(lines, i, 0);
+            i = consumed;
+            if (typeof child === 'string') {
+                scalars[key] = child;
+            } else {
+                nested[key] = child;
+            }
+            continue;
+        }
+
+        const inline = parseInlineList(rest);
+        if (inline !== null) {
+            nested[key] = inline;
+            continue;
+        }
+
+        // A plain scalar with continuation lines — prose, as the old readers
+        // treated it. The same colon hazard applies here.
+        if (hasBlock) {
+            const [folded, consumed] = consumeFolded(lines, i, 0);
+            scalars[key] = `${stripQuotes(rest)} ${folded}`.trim();
+            i = consumed;
+            continue;
+        }
+        scalars[key] = stripQuotes(rest).replace(/^>-?$/, '');
+    }
+
+    return { scalars, nested, keyOrder };
+}
+
+/**
+ * The scalar-only view, for the call sites that want exactly what they had.
+ *
+ * A nested key is rendered back into its folded string here so a caller that
+ * only knows about scalars still sees *something* for `provenance` rather than
+ * `undefined` — which matters for the index reader, where an absent key and an
+ * empty key print differently.
+ */
+export function readAdrFrontmatterScalars(text: string): Record<string, string> | null {
+    const parsed = readAdrFrontmatter(text);
+    if (parsed === null) return null;
+    const out: Record<string, string> = { ...parsed.scalars };
+    for (const [key, node] of Object.entries(parsed.nested)) {
+        out[key] = foldToString(node);
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Typed accessors for the two axes. Deliberately tolerant: a census proposal
+// and a hand-authored record both flow through here, and a malformed value has
+// to be reportable rather than fatal.
+// ---------------------------------------------------------------------------
+
+export const PROVENANCE_KINDS = ['human', 'agentic', 'mixed', 'unknown'] as const;
+export type ProvenanceKind = (typeof PROVENANCE_KINDS)[number];
+
+export const AGENTIC_MODES = ['single', 'council', 'delegated'] as const;
+export const EVIDENCE_STRENGTHS = ['E0', 'E1', 'E2', 'E3', 'E4'] as const;
+export type EvidenceStrength = (typeof EVIDENCE_STRENGTHS)[number];
+
+export const DISCOVERY_STATES = ['complete', 'incomplete'] as const;
+export const AUTHORITY_BASES = ['evidence', 'owner_intent'] as const;
+
+export interface AdrProvenance {
+    kind: string | null;
+    decisionMakers: string[];
+    humanDirected: string | null;
+    agenticMode: string | null;
+}
+
+export interface AdrEvidence {
+    strength: string | null;
+    discovery: string | null;
+    basis: string[];
+}
+
+function asString(node: AdrFrontmatterNode | undefined): string | null {
+    if (typeof node === 'string') return node === '' ? null : node;
+    return null;
+}
+
+function asList(node: AdrFrontmatterNode | undefined): string[] {
+    if (Array.isArray(node)) return node;
+    if (typeof node === 'string' && node !== '') return [node];
+    return [];
+}
+
+export function provenanceOf(fm: AdrFrontmatter): AdrProvenance | null {
+    const node = fm.nested.provenance;
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) return null;
+    return {
+        kind: asString(node.kind),
+        decisionMakers: asList(node.decision_makers),
+        humanDirected: asString(node.human_directed),
+        agenticMode: asString(node.agentic_mode),
+    };
+}
+
+export function evidenceOf(fm: AdrFrontmatter): AdrEvidence | null {
+    const node = fm.nested.evidence;
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) return null;
+    return {
+        strength: asString(node.strength),
+        discovery: asString(node.discovery),
+        basis: asList(node.basis),
+    };
+}
+
+export function authorityBasisOf(fm: AdrFrontmatter): string | null {
+    return fm.scalars.authority_basis ?? null;
+}
+
+/**
+ * Does this record's own metadata say a cite-time reader must NOT treat it as
+ * establishing that the alternatives remain invalid?
+ *
+ * True for an accepted record graded E0 or E1, whatever its provenance.
+ *
+ * **Provenance was in this predicate and has been removed** (neutral review,
+ * 2026-08-21). It required `kind === 'agentic'`, so an identical E0 record made
+ * by a human printed no notice at all. That was wrong on the claim's own terms:
+ * "this record does not by itself establish that alternatives remain invalid"
+ * is a statement about the strength of the EVIDENCE, and a human snapshot is
+ * exactly as thin as an agent snapshot. Gating it on who decided also sat one
+ * step sideways from `adr-layout`'s own line that a record's historical
+ * decision-maker does not determine how it is treated on citation.
+ *
+ * `authority_basis: owner_intent` is the one exemption, and it is the RIGHT
+ * discriminator where provenance was the wrong one. An owner purpose statement
+ * is legitimately E0 — that is the honest form — and its alternatives ARE
+ * foreclosed, by ownership rather than by evidence. Printing "this does not
+ * establish that alternatives remain invalid" over it would be false. The
+ * declared field says which kind of authority a record rests on, so it is the
+ * field that decides, and the burden table already reads `owner_intent` as
+ * binding until the owner changes it.
+ *
+ * That is also why the earlier provenance gate was subtly wrong rather than
+ * simply wrong: it was reaching for this exemption and grabbing a correlate.
+ * Most owner-intent records are human-made, so `kind === 'agentic'` approximated
+ * it — and silently withheld the notice from every thin HUMAN record that
+ * carried no owner claim at all.
+ *
+ * The name says `lowEvidence` rather than `provisionalAuthority` for a second
+ * reason from the same review: ADR-239 and the roadmap both explicitly REJECT
+ * the word "provisional" for this output, because it asserts a permission that
+ * does not exist. Identifiers carrying the rejected vocabulary would have been
+ * the doctrine contradicted in its own implementation.
+ *
+ * What the caller prints is `authority_effect: disabled-shadow-mode` — a
+ * DISABLED effect, not a provisional permission. No grade authorizes anything.
+ */
+export function isLowEvidenceAccepted(fm: AdrFrontmatter): boolean {
+    if ((fm.scalars.status ?? '') !== 'accepted') return false;
+    if (authorityBasisOf(fm) === 'owner_intent') return false;
+    const evidence = evidenceOf(fm);
+    return evidence?.strength === 'E0' || evidence?.strength === 'E1';
+}
+
+// ---------------------------------------------------------------------------
+// Index cells. The two nested axes rendered as two flat table cells, in ONE
+// place, because two generated tables print them (`adr/regenerate_index.ts`
+// and `audit_adr_coverage.render_area_readme`) and both are byte-compared by a
+// `--check` gate — a second copy of the em-dash-on-absent convention would be
+// two gates disagreeing about one record.
+// ---------------------------------------------------------------------------
+
+/** The placeholder both generated tables already use for an absent scalar. */
+const CELL_ABSENT = '—';
+
+/**
+ * Reserved row keys the index generators spread over their frontmatter scalars.
+ *
+ * Named apart from the frontmatter keys they derive from (`provenance`,
+ * `evidence`), which `readAdrFrontmatterScalars` also emits as folded strings —
+ * a folded `kind: agentic decision_makers: [...]` is not a table cell, and
+ * colliding with those keys would put it in one.
+ */
+export interface AdrAxisCells {
+    provenance_kind: string;
+    evidence_grade: string;
+}
+
+/**
+ * `provenance.kind` and `evidence.strength` as table cells.
+ *
+ * `discovery` rides in the evidence cell rather than in a third column: a bare
+ * `E0` collapses the five states `adr-layout § evidence.discovery` separates,
+ * so an index that printed the grade alone would re-create exactly the
+ * conflation the axis exists to undo.
+ *
+ * Most of the corpus carries neither axis and is not expected to — the backfill
+ * is deliberately out of this roadmap — so `—` is the common answer and means
+ * "not assessed", never "assessed as weak".
+ */
+export function readAdrAxisCells(text: string): AdrAxisCells {
+    const fm = readAdrFrontmatter(text);
+    if (fm === null) return { provenance_kind: CELL_ABSENT, evidence_grade: CELL_ABSENT };
+    const provenance = provenanceOf(fm);
+    const evidence = evidenceOf(fm);
+    const strength = evidence?.strength ?? null;
+    const discovery = evidence?.discovery ?? null;
+    return {
+        provenance_kind: provenance?.kind ?? CELL_ABSENT,
+        evidence_grade:
+            strength === null
+                ? CELL_ABSENT
+                : discovery === null
+                  ? strength
+                  : `${strength} (${discovery})`,
+    };
+}

package/src/scripts/_lib/agent_src.ts

@@ -277,10 +277,49 @@ export function _domains_command_logical(p: string): string | null {
     return `commands/${subpath}.md`;
 }
 
+/**
+ * Is this domains path inside a `__`-prefixed SCRATCH pack?
+ *
+ * ## Why this exists — a measured cross-test contamination
+ *
+ * A pack id is a lowercase slug (`slug_prefix` is validated against
+ * `^[a-z][a-z0-9-]*$`), so a directory whose name starts with `__` is not a
+ * pack that can ship. It is a test scratch marker, and the walkers must not
+ * count it.
+ *
+ * The defect this closes, measured 2026-08-20 on a full local suite run:
+ * `check_artefact_count_messaging`'s "live gate — real repo surfaces" test
+ * PASSED in isolation and FAILED in the suite, reporting
+ * `commands says 200, expected 207`. The +7 is exact and traceable:
+ * `lint_originality.test.ts` writes seven `command.md` files into the REAL tree
+ * at `src/domains/__origtest_batch/c1..c7/` (it must — that gate classifies an
+ * artefact by its PATH, so a tmpdir would not be a "command" at all), and
+ * removes them in `afterEach`. Vitest runs test files in parallel workers, so
+ * while those seven exist a concurrent worker counting the live tree sees 207.
+ *
+ * This is a SCOPE defect, not a flaky test: a gate asserting over the developer's
+ * live tree is not hermetic, and the remedy is a fixture boundary rather than a
+ * relaxed expectation. The boundary is placed here, at the point where a path
+ * becomes a counted artefact, because that is the one place that fixes it for
+ * every counter at once — and it weakens nothing: the count of real artefacts is
+ * still asserted exactly.
+ *
+ * Checked before shipping: no pack under `src/domains/` uses a `__` prefix, and
+ * `lint_originality` does not consume these walkers (it reads its corpus from
+ * the `--changed` paths it is handed), so its own batch test is unaffected.
+ */
+function _isScratchPack(domains_root: string, full: string): boolean {
+    const rel = path.relative(domains_root, full);
+    const first = rel.split(path.sep)[0];
+    return first !== undefined && first.startsWith('__');
+}
+
 /**
  * Yield `[physical_path, logical_relpath]` for every domains command, in
  * deterministic order. Naturally inert until `src/domains/*\/**\/command.md`
  * files exist. Mirrors `_iter_domains_commands`.
+ *
+ * Skips `__`-prefixed scratch packs — see `_isScratchPack`.
  */
 export function* _iter_domains_commands(): Generator<[string, string]> {
     const dom = _roots.SRC_DOMAINS;
@@ -291,6 +330,9 @@ export function* _iter_domains_commands(): Generator<[string, string]> {
         if (!_isFile(p)) {
             continue;
         }
+        if (_isScratchPack(dom, p)) {
+            continue;
+        }
         const logical = _domains_command_logical(p);
         if (logical !== null) {
             yield [p, logical];

package/src/scripts/_lib/bench_ab_pinned_repo.ts

@@ -0,0 +1,162 @@
+/**
+ * Delta #9 — a corpus task may name an EXTERNAL repository pinned at a SHA.
+ *
+ * Until this module, every v2 task resolved to a self-contained fixture tree
+ * under `internal/bench/ab/`, so the harness could only measure trap tasks this
+ * repository authored. Phase 3 of `road-to-solution-minimalism` asks for the
+ * opposite: a public repo nobody chose for the purpose, so a size effect cannot
+ * be an artefact of fixtures written by the same hand as the rule.
+ *
+ * ## Why a SHA and not a ref
+ *
+ * `sha` is a full 40-hex commit id, and a branch or tag name is REFUSED rather
+ * than resolved. A ref moves, so a report pinned to one records which repository
+ * answered but not which tree — and F7 of that roadmap forbids exactly that
+ * class of unreproducible number. The refusal is loud (a throw) because the
+ * quiet alternative, resolving the ref at run time, produces a report that looks
+ * pinned and is not.
+ *
+ * ## Materialisation, and what needs the network
+ *
+ * `ensure_pinned_tree` warms a cache ONCE per SHA — `git init` + a `--depth 1`
+ * fetch of that exact commit + `git archive` into a `.git`-free tree. Every
+ * per-trial workspace is then a local copy of that tree, so a sweep touches the
+ * network once per pinned task and never on the metered path. `is_materialised`
+ * answers the warm/cold question without touching the network, which is what
+ * lets `--mode selftest` and the offline complexity re-scorer report an honest
+ * "not materialised locally" instead of either hanging or scoring zero.
+ *
+ * The tree is `.git`-free on purpose. `changed_files` already skips `.git`, so
+ * carrying it would not corrupt a diff — it would just copy a repository per
+ * trial, and a sweep is 5 arms x 3 seeds per task.
+ *
+ * ## What this module deliberately does NOT do
+ *
+ * No sub-directory scoping, no submodules, no LFS, no authenticated remotes:
+ * `repo` must be an `https://` URL. Each of those is a real feature and none is
+ * needed to pin one task to one commit, which is the whole of delta #9.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** A task's pinned-repo coordinates, already validated. */
+export interface PinnedSpec {
+    repo: string;
+    sha: string;
+}
+
+/** A malformed or contradictory pin. Never swallowed into a fixture fallback. */
+export class PinnedRepoError extends Error {}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const REPO_URL_RE = /^https:\/\/[A-Za-z0-9._~:/?#@!$&'()*+,;=%-]+$/;
+const CACHE_ROOT = path.join(os.tmpdir(), 'agent-config-bench-v2-repos');
+/** Written into a warm cache entry so a half-finished fetch never reads as warm. */
+const STAMP = '.pinned-repo.json';
+
+type Dict = Record<string, unknown>;
+
+/**
+ * The pin declared by `task`, or `null` when it is an ordinary fixture task.
+ *
+ * Throws rather than returning `null` on a task that is *trying* to be pinned
+ * and failing: a half-declared pin silently treated as a fixture task is how a
+ * sweep would run the wrong tree and report it as the right one.
+ */
+export function pinnedSpecFor(task: Dict): PinnedSpec | null {
+    const repoRaw = task['repo'];
+    const shaRaw = task['sha'];
+    const id = task['id'] === undefined ? '<unknown>' : String(task['id']);
+    if (repoRaw === undefined && shaRaw === undefined) return null;
+    if (repoRaw === undefined || shaRaw === undefined) {
+        throw new PinnedRepoError(`task ${id}: \`repo\` and \`sha\` must be declared together`);
+    }
+    if (task['fixture'] !== undefined) {
+        throw new PinnedRepoError(`task ${id}: a pinned task must not also declare \`fixture\``);
+    }
+    const repo = String(repoRaw);
+    const sha = String(shaRaw);
+    if (!REPO_URL_RE.test(repo)) {
+        throw new PinnedRepoError(`task ${id}: \`repo\` must be an https:// URL, got ${repo}`);
+    }
+    if (!SHA_RE.test(sha)) {
+        throw new PinnedRepoError(
+            `task ${id}: \`sha\` must be a full 40-hex commit id, got ${sha} — ` +
+                'a branch or tag is refused because it moves and the report would not be reproducible',
+        );
+    }
+    return { repo, sha };
+}
+
+/** Cache directory for one pin. Keyed by the SHA — a commit id is content. */
+export function pinned_tree_dir(spec: PinnedSpec): string {
+    return path.join(CACHE_ROOT, spec.sha, 'tree');
+}
+
+/** True when this pin's tree is already on disk and complete. */
+export function is_materialised(spec: PinnedSpec): boolean {
+    const stampPath = path.join(CACHE_ROOT, spec.sha, STAMP);
+    if (!fs.existsSync(stampPath) || !fs.existsSync(pinned_tree_dir(spec))) return false;
+    try {
+        const stamp = JSON.parse(fs.readFileSync(stampPath, 'utf-8')) as Dict;
+        return String(stamp['repo']) === spec.repo && String(stamp['sha']) === spec.sha;
+    } catch {
+        return false;
+    }
+}
+
+function _git(cwd: string, args: readonly string[]): void {
+    execFileSync('git', [...args], { cwd, stdio: 'pipe' });
+}
+
+/**
+ * Materialise the pinned tree, fetching over the network only on a cold cache.
+ *
+ * Returns the tree path. A failed fetch leaves NO stamp, so the next call
+ * retries from scratch rather than reading a partial checkout as warm.
+ */
+export function ensure_pinned_tree(spec: PinnedSpec): string {
+    const tree = pinned_tree_dir(spec);
+    if (is_materialised(spec)) return tree;
+    const base = path.join(CACHE_ROOT, spec.sha);
+    fs.rmSync(base, { recursive: true, force: true });
+    const gitdir = path.join(base, 'src');
+    fs.mkdirSync(gitdir, { recursive: true });
+    fs.mkdirSync(tree, { recursive: true });
+    _git(gitdir, ['init', '-q', '.']);
+    _git(gitdir, ['remote', 'add', 'origin', spec.repo]);
+    _git(gitdir, ['fetch', '-q', '--depth', '1', 'origin', spec.sha]);
+    const tar = execFileSync('git', ['archive', '--format=tar', 'FETCH_HEAD'], {
+        cwd: gitdir,
+        maxBuffer: 512 * 1024 * 1024,
+    });
+    const tarPath = path.join(base, 'tree.tar');
+    fs.writeFileSync(tarPath, tar);
+    execFileSync('tar', ['-x', '-f', tarPath, '-C', tree], { stdio: 'pipe' });
+    fs.rmSync(tarPath, { force: true });
+    fs.rmSync(gitdir, { recursive: true, force: true });
+    fs.writeFileSync(path.join(base, STAMP), JSON.stringify({ repo: spec.repo, sha: spec.sha }), 'utf-8');
+    return tree;
+}
+
+/**
+ * Absolute path to a task's pristine tree — fixture or pinned repo.
+ *
+ * `offlineOnly` is for readers that must not reach the network (the offline
+ * re-scorer, `--mode selftest`): a cold cache returns `null` there, which every
+ * caller reports as "not measured" rather than as a zero.
+ */
+export function pristine_tree_for(
+    task: Dict,
+    opts: { fixturesRoot: string; offlineOnly?: boolean },
+): string | null {
+    const spec = pinnedSpecFor(task);
+    if (spec !== null) {
+        if (opts.offlineOnly === true) return is_materialised(spec) ? pinned_tree_dir(spec) : null;
+        return ensure_pinned_tree(spec);
+    }
+    if (task['fixture'] === undefined) return null;
+    return path.join(opts.fixturesRoot, String(task['fixture']));
+}