@hellraisercenobit/ai-engineering-gate 0.8.0

package/dist/ai-engineering-gate.mjs

@@ -0,0 +1,2762 @@
+// Generated by scripts/build-gate-bundle.mjs from packages/ai-engineering-gate/src. Do not edit.
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// packages/ai-engineering-gate/src/answer.mjs
+// Every command answers in one of two shapes, which the renderer and the exit code both read: a refusal
+// carrying the contract's code, or an acceptance carrying the line a human reads plus the payload the
+// JSON surface publishes.
+const refuse = (code, reason, details = [], cause = null) => ({
+  ok: false,
+  code,
+  reason,
+  details,
+  ...(cause ? { cause } : {}),
+});
+
+const accept = (text, payload = {}) => ({ ok: true, text, payload });
+
+// packages/ai-engineering-gate/src/hash.mjs
+// Content hashes only. A fingerprint never carries a revision, a timestamp or a path's mtime, so a
+// content-neutral rebase and a re-checkout leave every verdict current.
+
+function hashText(text) {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function hashFile(path) {
+  try {
+    if (!statSync(path).isFile()) return null;
+    return `sha256:${createHash('sha256').update(readFileSync(path)).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
+// Canonical JSON with sorted keys, so two equal documents hash equally whatever their key order.
+function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const entries = Object.keys(value).sort()
+    .filter(key => value[key] !== undefined)
+    .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+  return `{${entries.join(',')}}`;
+}
+
+function hashJson(value) {
+  return hashText(canonicalJson(value));
+}
+
+// One fingerprint from a set of named content hashes. `null` marks a member that does not exist,
+// so a deleted file changes the fingerprint instead of disappearing from it.
+function hashEntries(entries) {
+  const ordered = [...entries].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return hashText(ordered.map(([name, digest]) => `${name}\u0000${digest ?? 'absent'}`).join('\u0001'));
+}
+
+// packages/ai-engineering-gate/src/repo.mjs
+const MARKER_FILE = '.ai-engineering-suite.json';
+const DEFAULT_EVIDENCE_ROOT = join(homedir(), '.ai-engineering-gate', 'evidence');
+
+function git(args, cwd) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return {
+    ok: result.status === 0,
+    stdout: (result.stdout ?? '').trim(),
+    stderr: (result.stderr ?? '').trim(),
+  };
+}
+
+function gitLines(args, cwd) {
+  const result = git(args, cwd);
+  if (!result.ok) return [];
+  return result.stdout.split('\n').map(line => line.trim()).filter(Boolean);
+}
+
+function findRepoRoot(cwd) {
+  const result = git(['rev-parse', '--show-toplevel'], cwd);
+  return result.ok ? result.stdout : cwd;
+}
+
+function readMarker(repoRoot) {
+  const path = join(repoRoot, MARKER_FILE);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return join(homedir(), path.slice(2));
+  return path;
+}
+
+function resolveEvidenceRoot({ flag, env, marker, repoRoot }) {
+  const chosen = flag ?? env ?? marker?.evidenceRoot;
+  if (!chosen) return DEFAULT_EVIDENCE_ROOT;
+  const expanded = expandHome(chosen);
+  return isAbsolute(expanded) ? expanded : resolve(repoRoot, expanded);
+}
+
+// `feature/REF-15-something` names task REF-15, matching the delivery convention. A branch with no
+// ticket key falls back to a slug of the whole branch name, so the gate never goes silent for want
+// of a key, and an explicit flag or environment variable serves a detached pipeline head.
+function resolveTaskKey({ flag, env, repoRoot }) {
+  if (flag) return flag;
+  if (env) return env;
+  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot).stdout;
+  if (!branch || branch === 'HEAD') return 'detached-head';
+  const ticket = /(?<![A-Z0-9])([A-Z][A-Z0-9]+-\d+)(?![0-9])/.exec(branch.toUpperCase());
+  if (ticket) return ticket[1];
+  return branch.replaceAll(/[^A-Za-z0-9]+/g, '-').replaceAll(/^-+|-+$/g, '').toLowerCase() || 'unnamed';
+}
+
+// `*` matches inside one segment, `**` across segments, and a bare directory name matches
+// everything under it. Nothing else, so an ignore pattern cannot quietly widen.
+function matchesPattern(path, pattern) {
+  const clean = pattern.replace(/^\.\//, '').replace(/\/$/, '');
+  if (path === clean || path.startsWith(`${clean}/`)) return true;
+  const expression = clean.split('**').map(part => part
+    .replaceAll(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('*', '[^/]*')
+    .replaceAll('?', '[^/]')).join('.*');
+  return new RegExp(`^${expression}$`, 'u').test(path);
+}
+
+function isInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function toRepoRelative(repoRoot, path) {
+  const absolute = isAbsolute(path) ? path : resolve(repoRoot, path);
+  const rel = relative(repoRoot, absolute);
+  return rel.split(sep).join('/');
+}
+
+// packages/ai-engineering-gate/src/changeset.mjs
+// A path the gate owns or publishes is never part of the state a verdict binds to: the export
+// directory carries the verdicts themselves, an evidence root inside the checkout is the index, and
+// the marker configures enforcement rather than describing the change.
+function excludedFromChangeSet(context, path) {
+  return excluded(context, path);
+}
+
+function excluded(context, path) {
+  const { marker, repoRoot, evidenceRoot } = context;
+  if (path === MARKER_FILE) return true;
+  if (marker.exportDirectory && matchesPattern(path, marker.exportDirectory)) return true;
+  if (isInside(repoRoot, evidenceRoot) && matchesPattern(path, toRepoRelative(repoRoot, evidenceRoot))) return true;
+  return (marker.ignore ?? []).some(pattern => matchesPattern(path, pattern));
+}
+
+function mergeBase(repoRoot, base) {
+  if (!base) return null;
+  const found = git(['merge-base', base, 'HEAD'], repoRoot);
+  if (found.ok && found.stdout) return found.stdout;
+  const resolved = git(['rev-parse', '--verify', base], repoRoot);
+  return resolved.ok ? resolved.stdout : null;
+}
+
+// The tracked diff between the merge-base and the worktree, staged, unstaged and untracked files
+// included. A clean HEAD never identifies a dirty worktree, so the untracked half is not optional.
+function changeSet(context, base) {
+  const { repoRoot } = context;
+  const point = mergeBase(repoRoot, base);
+  const names = new Set();
+  if (point) {
+    for (const name of gitLines(['diff', '--name-only', point], repoRoot)) names.add(name);
+    for (const name of gitLines(['diff', '--name-only', '--cached', point], repoRoot)) names.add(name);
+  } else {
+    for (const name of gitLines(['diff', '--name-only', 'HEAD'], repoRoot)) names.add(name);
+  }
+  for (const name of gitLines(['ls-files', '--others', '--exclude-standard'], repoRoot)) names.add(name);
+  return [...names].filter(name => !excluded(context, name)).sort();
+}
+
+function filesUnder(context, repoRoot, relativePath, into) {
+  const absolute = join(repoRoot, relativePath);
+  if (!existsSync(absolute)) {
+    into.set(relativePath, null);
+    return;
+  }
+  if (statSync(absolute).isFile()) {
+    if (!excluded(context, relativePath)) into.set(relativePath, hashFile(absolute));
+    return;
+  }
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) {
+    if (entry.name === '.git') continue;
+    filesUnder(context, repoRoot, `${relativePath.replace(/\/$/, '')}/${entry.name}`, into);
+  }
+}
+
+// The union of the declared scope paths, the declared configuration files and the change set. A
+// scope entry that names a directory expands to its files, so a new file in scope moves the state.
+function sourceFingerprint(context, declaration, change) {
+  const { repoRoot } = context;
+  const entries = new Map();
+  for (const path of declaration?.scope?.paths ?? []) filesUnder(context, repoRoot, path, entries);
+  for (const path of declaration?.scope?.configuration ?? []) filesUnder(context, repoRoot, path, entries);
+  for (const path of change) {
+    if (entries.has(path)) continue;
+    entries.set(path, hashFile(join(repoRoot, path)));
+  }
+  return hashEntries(entries);
+}
+
+// Change-set paths outside every applicable declaration. Never a refusal: the gate does not guess
+// applicability, and the reviewer still sees what the builder did not declare.
+function undeclaredChanges(change, declarations) {
+  const scopes = declarations
+    .filter(declaration => declaration?.applicability === 'applicable')
+    .flatMap(declaration => declaration.scope?.paths ?? []);
+  return change.filter(path => !scopes.some(scope => matchesPattern(path, scope)));
+}
+
+function coveringDimensions(path, declarationsByDimension) {
+  return Object.entries(declarationsByDimension)
+    .filter(([, declaration]) => declaration?.applicability === 'applicable'
+      && (declaration.scope?.paths ?? []).some(scope => matchesPattern(path, scope)))
+    .map(([dimension]) => dimension);
+}
+
+// packages/ai-engineering-gate/src/registry.mjs
+const SHARED_SCHEMAS = [
+  'marker', 'declaration', 'decision-envelope', 'review-envelope',
+  'verdict-record', 'dispute', 'arbitration', 'evidence-append', 'gate-output',
+];
+
+// The gate resolves its members and its reference bundles from its own distribution root - the
+// plugin root, the npm package or this checkout - and never from the target project, so a
+// reference fingerprint means the same thing wherever the gate runs. Walk to the outermost
+// `contracts/members.json` so a staged copy inside the package never shadows this checkout.
+function findDistributionRoot() {
+  const override = process.env.AI_ENGINEERING_GATE_ROOT;
+  if (override) return override;
+  let directory = dirname(fileURLToPath(import.meta.url));
+  let found = null;
+  for (let depth = 0; depth < 12; depth += 1) {
+    if (existsSync(join(directory, 'contracts/members.json'))) found = directory;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  if (found) return found;
+  throw new Error('cannot resolve the gate distribution root: contracts/members.json not found');
+}
+
+function loadRegistry(distributionRoot) {
+  const manifest = JSON.parse(readFileSync(join(distributionRoot, 'contracts/members.json'), 'utf8'));
+  const schemas = {};
+  for (const name of SHARED_SCHEMAS) {
+    schemas[name] = JSON.parse(readFileSync(join(distributionRoot, `contracts/schemas/${name}.schema.json`), 'utf8'));
+  }
+  return { ...manifest, schemas, root: distributionRoot };
+}
+
+function gateVersion(distributionRoot) {
+  const candidates = [
+    join(distributionRoot, 'packages/ai-engineering-gate/package.json'),
+    join(distributionRoot, 'package.json'),
+  ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    const { version } = JSON.parse(readFileSync(candidate, 'utf8'));
+    if (version) return version;
+  }
+  return '0.0.0';
+}
+
+// The dimensions the project registered, resolved against the manifest. An identifier the manifest
+// does not carry is an unresolvable registry member, not a dimension the gate invents.
+function memberAgentType(member) {
+  return member.agent.split('/').pop().replace(/\.md$/, '');
+}
+
+function registeredMembers(registry, marker) {
+  const byName = new Map(registry.members.map(member => [member.dimension, member]));
+  const selected = marker.dimensions === 'all'
+    ? registry.members
+    : marker.dimensions.map(name => {
+      const member = byName.get(name);
+      if (!member) throw new Error(`the marker registers ${name}, which the member manifest does not`);
+      return member;
+    });
+  for (const member of selected) {
+    for (const path of [member.transpose, member.review, member.agent, member.decisionSchema]) {
+      if (!existsSync(join(registry.root, path))) {
+        throw new Error(`registry member ${member.dimension} does not resolve ${path}`);
+      }
+    }
+  }
+  return selected;
+}
+
+function memberDecisionSchema(registry, member) {
+  return JSON.parse(readFileSync(join(registry.root, member.decisionSchema), 'utf8'));
+}
+
+function memberEvidenceSchema(registry, member, kind) {
+  const path = member.evidenceSchemas?.[kind];
+  if (!path) return null;
+  return JSON.parse(readFileSync(join(registry.root, path), 'utf8'));
+}
+
+function walkFiles(root, into = []) {
+  if (!existsSync(root)) return into;
+  if (statSync(root).isFile()) {
+    into.push(root);
+    return into;
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) walkFiles(path, into);
+    else if (entry.isFile()) into.push(path);
+  }
+  return into;
+}
+
+// Catalog, decision schema, evidence schemas, guides, the review skill's references and the
+// generated contract copy, plus the contract version and the gate version. A catalog edit
+// therefore reopens every verdict that read it.
+function referenceFingerprint(registry, member, version) {
+  const entries = [
+    ['contract-version', registry.contractVersion],
+    ['gate-version', version],
+  ];
+  for (const bundle of member.referenceBundle) {
+    const absolute = join(registry.root, bundle);
+    for (const file of walkFiles(absolute)) {
+      entries.push([file.slice(registry.root.length + 1), hashFile(file)]);
+    }
+  }
+  return hashEntries(entries);
+}
+
+// The bundle the gate distributes is authoritative. When a discoverable installed copy of the same
+// skill differs from it, the state warns rather than guessing which one a reviewer read.
+function installedReferenceMismatch(registry, member) {
+  const home = process.env.HOME;
+  if (!home) return false;
+  const name = member.transpose.split('/').pop();
+  for (const base of [join(home, '.claude/skills'), join(home, '.agents/skills')]) {
+    const installed = join(base, name, 'references');
+    if (!existsSync(installed)) continue;
+    const distributed = join(registry.root, member.transpose, 'references');
+    for (const file of walkFiles(distributed)) {
+      const mirror = join(installed, file.slice(distributed.length + 1));
+      if (hashFile(mirror) !== hashFile(file)) return true;
+    }
+  }
+  return false;
+}
+
+// packages/ai-engineering-gate/src/store.mjs
+// Seven kinds of document live under a task's evidence directory. The first six are written through
+// a gate command; `index` is the gate's own and nobody else writes it.
+function taskPaths(evidenceRoot, task) {
+  const root = join(evidenceRoot, task);
+  return {
+    root,
+    declarations: join(root, 'declarations'),
+    records: join(root, 'records'),
+    evidence: join(root, 'evidence'),
+    disputes: join(root, 'disputes'),
+    arbitrations: join(root, 'arbitrations'),
+    index: join(root, 'index'),
+  };
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Write then rename, one document at a time, so concurrent attestations of two dimensions never
+// interleave and a crashed writer leaves no half document behind.
+function writeJsonAtomic(path, value) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(temporary, path);
+  return path;
+}
+
+function listDirectories(path) {
+  if (!existsSync(path)) return [];
+  return readdirSync(path, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort();
+}
+
+function listJsonFiles(path) {
+  if (!existsSync(path)) return [];
+  return readdirSync(path, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.json') && !entry.name.endsWith('.snapshot.json'))
+    .map(entry => entry.name)
+    .sort();
+}
+
+const revisionNumber = name => Number.parseInt(/^rev-(\d+)\.json$/.exec(name)?.[1] ?? '0', 10);
+
+function latestRevision(directory) {
+  const files = listJsonFiles(directory).filter(name => revisionNumber(name) > 0);
+  if (files.length === 0) return null;
+  const name = files.sort((a, b) => revisionNumber(a) - revisionNumber(b)).at(-1);
+  const document = readJson(join(directory, name));
+  return document && { number: revisionNumber(name), path: join(directory, name), document };
+}
+
+function readDeclaration(paths, dimension) {
+  return latestRevision(join(paths.declarations, dimension));
+}
+
+function declarationRevisions(paths, dimension) {
+  const directory = join(paths.declarations, dimension);
+  return listJsonFiles(directory)
+    .filter(name => revisionNumber(name) > 0)
+    .sort((a, b) => revisionNumber(a) - revisionNumber(b))
+    .map(name => ({ number: revisionNumber(name), document: readJson(join(directory, name)) }));
+}
+
+function writeDeclaration(paths, dimension, number, document) {
+  return writeJsonAtomic(join(paths.declarations, dimension, `rev-${number}.json`), document);
+}
+
+// A record identifier is `rec-001` per dimension; a revision is `rec-001@2`. Revision 1 opens a new
+// record, a later one names its predecessor and extends that chain, so no revision is overwritten.
+function recordIds(paths, dimension) {
+  return listDirectories(join(paths.records, dimension));
+}
+
+function readRecord(paths, dimension, recordId) {
+  const revision = latestRevision(join(paths.records, dimension, recordId));
+  return revision && { ...revision, id: recordId, reference: `${recordId}@${revision.number}` };
+}
+
+function readRecordRevision(paths, dimension, recordId, number) {
+  const path = join(paths.records, dimension, recordId, `rev-${number}.json`);
+  const document = readJson(path);
+  return document && { number, path, document, id: recordId, reference: `${recordId}@${number}` };
+}
+
+function currentRecords(paths, dimension) {
+  return recordIds(paths, dimension)
+    .map(id => readRecord(paths, dimension, id))
+    .filter(Boolean);
+}
+
+function nextRecordId(paths, dimension) {
+  const used = recordIds(paths, dimension)
+    .map(id => Number.parseInt(/^rec-(\d+)$/.exec(id)?.[1] ?? '0', 10));
+  return `rec-${String(Math.max(0, ...used) + 1).padStart(3, '0')}`;
+}
+
+function writeRecord(paths, dimension, recordId, number, document) {
+  return writeJsonAtomic(join(paths.records, dimension, recordId, `rev-${number}.json`), document);
+}
+
+function writeRecordSnapshot(paths, dimension, recordId, number, snapshot) {
+  return writeJsonAtomic(join(paths.records, dimension, recordId, `rev-${number}.snapshot.json`), snapshot);
+}
+
+function readRecordSnapshot(paths, dimension, recordId, number) {
+  return readJson(join(paths.records, dimension, recordId, `rev-${number}.snapshot.json`));
+}
+
+function appendEvidence(paths, dimension, document) {
+  const directory = join(paths.evidence, dimension);
+  const sequence = String(listJsonFiles(directory).length + 1).padStart(4, '0');
+  const name = `${sequence}-${document.kind.replaceAll(/[^a-z0-9-]/gi, '-')}.json`;
+  return writeJsonAtomic(join(directory, name), document);
+}
+
+function evidenceAppends(paths, dimension) {
+  const directory = join(paths.evidence, dimension);
+  return listJsonFiles(directory).map(name => readJson(join(directory, name))).filter(Boolean);
+}
+
+function sequencedWrite(directory, prefix, document) {
+  const sequence = String(listJsonFiles(directory).length + 1).padStart(3, '0');
+  const id = `${prefix}-${sequence}`;
+  writeJsonAtomic(join(directory, `${id}.json`), { ...document, id });
+  return id;
+}
+
+function sequencedList(directory) {
+  return listJsonFiles(directory).map(name => readJson(join(directory, name))).filter(Boolean);
+}
+
+function writeVerdict(paths, kind, dimension, document) {
+  const directory = join(paths.index, `${kind}s`, dimension);
+  const prefix = kind === 'attestation' ? 'att' : 'rep';
+  return sequencedWrite(directory, prefix, document);
+}
+
+function verdicts(paths, kind, dimension) {
+  return sequencedList(join(paths.index, `${kind}s`, dimension));
+}
+
+function writeDispute(paths, dimension, document) {
+  return sequencedWrite(join(paths.disputes, dimension), 'dis', document);
+}
+
+function disputes(paths, dimension) {
+  return sequencedList(join(paths.disputes, dimension));
+}
+
+function writeArbitration(paths, dimension, document) {
+  return sequencedWrite(join(paths.arbitrations, dimension), 'arb', document);
+}
+
+function arbitrations(paths, dimension) {
+  return sequencedList(join(paths.arbitrations, dimension));
+}
+
+function windowPath(paths, dimension) {
+  return join(paths.index, 'windows', `${dimension}.json`);
+}
+
+function readWindow(paths, dimension) {
+  return readJson(windowPath(paths, dimension));
+}
+
+function writeWindow(paths, dimension, document) {
+  return writeJsonAtomic(windowPath(paths, dimension), document);
+}
+
+function closeWindow(paths, dimension, outcome) {
+  const open = readWindow(paths, dimension);
+  if (!open) return null;
+  const directory = join(paths.index, 'closed-windows', dimension);
+  sequencedWrite(directory, 'win', { ...open, outcome, closedAt: new Date().toISOString() });
+  writeJsonAtomic(windowPath(paths, dimension), { closed: true });
+  return open;
+}
+
+function closedWindows(paths, dimension) {
+  return sequencedList(join(paths.index, 'closed-windows', dimension));
+}
+
+function readRounds(paths) {
+  return readJson(join(paths.index, 'rounds.json')) ?? { round: 0, conflictRounds: 0, history: [] };
+}
+
+function writeRounds(paths, value) {
+  return writeJsonAtomic(join(paths.index, 'rounds.json'), value);
+}
+
+function readStopSnapshot(paths) {
+  return readJson(join(paths.index, 'stop-snapshot.json'));
+}
+
+function writeStopSnapshot(paths, value) {
+  return writeJsonAtomic(join(paths.index, 'stop-snapshot.json'), value);
+}
+
+function invocationHash(command) {
+  const tokens = String(command).trim().split(/\s+/).filter(Boolean);
+  const gateAt = tokens.findIndex(token => token.includes('ai-engineering-gate'));
+  const rest = gateAt >= 0 ? tokens.slice(gateAt + 1) : tokens;
+  return hashText(canonicalJson(rest));
+}
+
+// Keyed on session, tool-use id and the hash of the gate argv so two same-verb calls
+// stay distinct, and a leftover of another verb cannot be consumed as this one.
+function handoffKey(session, toolUseId, commandHash) {
+  return hashText(canonicalJson([session ?? '', toolUseId ?? '', commandHash ?? ''])).slice(7, 39);
+}
+
+function writeHandoff(paths, key, document) {
+  return writeJsonAtomic(join(paths.index, 'handoffs', `${key}.json`), document);
+}
+
+function readHandoff(paths, key) {
+  return readJson(join(paths.index, 'handoffs', `${key}.json`));
+}
+
+function handoffs(paths) {
+  const directory = join(paths.index, 'handoffs');
+  return listJsonFiles(directory).map(name => ({ key: name.replace(/\.json$/, ''), document: readJson(join(directory, name)) }));
+}
+
+function dropHandoff(paths, key) {
+  const path = join(paths.index, 'handoffs', `${key}.json`);
+  if (existsSync(path)) writeJsonAtomic(path, { consumed: true, at: new Date().toISOString() });
+}
+
+function readBuilders(paths) {
+  return readJson(join(paths.index, 'builders.json')) ?? { agents: [], sessions: [] };
+}
+
+// The builder identities seen writing declarations, records and evidence. `attest` refuses a caller
+// that appears here, which checks consistency and never proves independence.
+function noteBuilder(paths, identity) {
+  const known = readBuilders(paths);
+  const agents = [...new Set([...known.agents, identity.agent].filter(Boolean))];
+  const sessions = [...new Set([...known.sessions, identity.session].filter(Boolean))];
+  writeJsonAtomic(join(paths.index, 'builders.json'), { agents, sessions });
+}
+
+// packages/ai-engineering-gate/src/context.mjs
+// Everything a command reads, resolved once. `marked` is false in a repository that carries no
+// marker, and every command then allows and prints nothing that blocks.
+function buildContext(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const repoRoot = findRepoRoot(cwd);
+  const marker = readMarker(repoRoot);
+  const distributionRoot = findDistributionRoot();
+  const registry = loadRegistry(distributionRoot);
+  const version = gateVersion(distributionRoot);
+  const context = {
+    cwd,
+    repoRoot,
+    marker,
+    marked: marker !== null,
+    registry,
+    version,
+    gateCommand: options.gateCommand ?? gateCommandLine(distributionRoot),
+    harness: options.harness ?? null,
+  };
+  if (!context.marked) return context;
+  context.members = registeredMembers(registry, marker);
+  context.dimensions = context.members.map(member => member.dimension);
+  context.evidenceRoot = resolveEvidenceRoot({
+    flag: options.evidenceRoot,
+    env: process.env.AI_ENGINEERING_GATE_EVIDENCE_ROOT,
+    marker,
+    repoRoot,
+  });
+  context.task = resolveTaskKey({
+    flag: options.task,
+    // A CI checkout is a detached merge ref, so no branch names the task. One export carries one
+    // task, which is a fact the export itself states better than a pipeline variable could.
+    env: process.env.AI_ENGINEERING_GATE_TASK ?? (options.fromExport ? soleTask(context.evidenceRoot) : null),
+    repoRoot,
+  });
+  context.paths = taskPaths(context.evidenceRoot, context.task);
+  context.conflictRoundCap = marker.conflictRoundCap ?? 3;
+  context.roundCap = marker.roundCap ?? 12;
+  context.allowReplay = marker.allowReplay !== false;
+  context.requireVerifiedIdentity = marker.requireVerifiedIdentity === true;
+  return context;
+}
+
+function soleTask(evidenceRoot) {
+  const tasks = listDirectories(evidenceRoot).filter(name => name !== 'index');
+  return tasks.length === 1 ? tasks[0] : null;
+}
+
+// The command line the gate prints for the next step. It names the entry point it is running from,
+// so a checkout, a plugin install and an npm install each print something the reader can paste.
+function gateCommandLine(distributionRoot) {
+  for (const candidate of ['packages/ai-engineering-gate/bin/ai-engineering-gate.mjs', 'bin/ai-engineering-gate.mjs']) {
+    if (existsSync(join(distributionRoot, candidate))) return `node ${join(distributionRoot, candidate)}`;
+  }
+  return 'ai-engineering-gate';
+}
+
+function memberOf(context, dimension) {
+  const member = context.members?.find(one => one.dimension === dimension);
+  if (!member) throw new Error(`${dimension} is not a dimension this project registers`);
+  return member;
+}
+
+function declarations(context) {
+  const found = {};
+  for (const dimension of context.dimensions) {
+    found[dimension] = readDeclaration(context.paths, dimension)?.document ?? null;
+  }
+  return found;
+}
+
+// The base a dimension compares against: its declaration's, the marker's default, or none.
+function baseOf(context, declaration) {
+  return declaration?.base ?? context.marker.base ?? null;
+}
+
+// The three fingerprints, always computed here and never accepted from a document.
+function fingerprintsOf(context, dimension, declaration) {
+  const member = memberOf(context, dimension);
+  const change = changeSet(context, baseOf(context, declaration));
+  return {
+    source: sourceFingerprint(context, declaration, change),
+    reference: referenceFingerprint(context.registry, member, context.version),
+    decision: decisionFingerprint(context, dimension),
+    change,
+  };
+}
+
+// The dimension's declaration and every one of its records, each with its revision number. A
+// re-declaration or a record revision therefore expires the verdicts that read the old ones.
+function decisionFingerprint(context, dimension) {
+  const declaration = readDeclaration(context.paths, dimension);
+  const entries = [
+    ['declaration', declaration ? `${declaration.number}:${hashJson(declaration.document)}` : 'absent'],
+  ];
+  for (const record of currentRecords(context.paths, dimension)) {
+    entries.push([`record:${record.id}`, `${record.number}:${hashJson(record.document)}`]);
+  }
+  return hashEntries(entries);
+}
+
+function undeclaredFor(context) {
+  const all = declarations(context);
+  const applicable = Object.values(all).filter(one => one?.applicability === 'applicable');
+  const base = applicable[0]?.base ?? context.marker.base ?? null;
+  return undeclaredChanges(changeSet(context, base), Object.values(all));
+}
+
+// packages/ai-engineering-gate/src/identity.mjs
+// Harnesses that expose an agent identifier in hook input inside a subagent call. Elsewhere the
+// identity claim cannot be checked, and the gate says so rather than pretending it verified one.
+const HARNESSES_WITH_AGENT_IDENTITY = new Set(['claude-code']);
+const HANDOFF_LIFETIME_MS = 5 * 60 * 1000;
+
+function nonempty(value) {
+  return value ? value : null;
+}
+
+function sessionIdentifier() {
+  return nonempty(process.env.CLAUDE_SESSION_ID)
+    ?? nonempty(process.env.CODEX_SESSION_ID)
+    ?? nonempty(process.env.AI_ENGINEERING_GATE_SESSION)
+    ?? null;
+}
+
+function toolUseIdentifier() {
+  return nonempty(process.env.CLAUDE_TOOL_USE_ID)
+    ?? nonempty(process.env.AI_ENGINEERING_GATE_TOOL_USE_ID)
+    ?? null;
+}
+
+// The hook sees a session id the invoked process sometimes does not, so both the tool-use key and
+// the session+command-hash key are written; a null-session twin is not, because a leftover of that
+// twin would make a typed command look like an agent.
+function recordHandoff(context, { session, verb, dimension, agent, agentType, toolUseId, command }) {
+  const commandHash = invocationHash(command);
+  const document = {
+    session, verb, dimension, agent, agentType, toolUseId, commandHash,
+    harness: context.harness,
+    recordedAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + HANDOFF_LIFETIME_MS).toISOString(),
+    consumed: false,
+  };
+  const keys = [...new Set([
+    handoffKey(session, toolUseId, commandHash),
+    handoffKey(session, null, commandHash),
+  ])];
+  for (const key of keys) writeHandoff(context.paths, key, document);
+  return keys;
+}
+
+function takeHandoff(context) {
+  const session = sessionIdentifier();
+  const commandHash = invocationHash(process.argv.slice(1).join(' '));
+  const keys = [...new Set([
+    handoffKey(session, toolUseIdentifier(), commandHash),
+    handoffKey(session, null, commandHash),
+  ])];
+  const found = keys
+    .map(key => ({ key, stored: readHandoff(context.paths, key) }))
+    .find(one => one.stored && !one.stored.consumed
+      && !(one.stored.expiresAt && one.stored.expiresAt < new Date().toISOString()));
+  if (!found) return null;
+  for (const key of keys) {
+    const stored = readHandoff(context.paths, key);
+    if (stored) writeHandoff(context.paths, key, { ...stored, consumed: true });
+  }
+  return found.stored;
+}
+
+// Every gate call carries the session identifier. The agent identifier arrives only through the
+// handoff a PreToolUse hook recorded, which is why its absence is the mechanical sign of a
+// human-typed command.
+function captureIdentity(context, verb, dimension) {
+  const handoff = takeHandoff(context, verb, dimension);
+  const providesAgents = HARNESSES_WITH_AGENT_IDENTITY.has(context.harness ?? handoff?.harness ?? '');
+  return {
+    session: sessionIdentifier(),
+    agent: handoff?.agent ?? null,
+    agentType: handoff?.agentType ?? null,
+    harness: context.harness ?? handoff?.harness ?? null,
+    handoffPresent: Boolean(handoff),
+    providesAgents,
+    verified: providesAgents && Boolean(handoff?.agent),
+  };
+}
+
+function stampBuilder(context, identity) {
+  noteBuilder(context.paths, identity);
+}
+
+function isBuilderIdentity(context, identity) {
+  const known = readBuilders(context.paths);
+  return Boolean(identity.agent) && known.agents.includes(identity.agent);
+}
+
+function storedIdentity(identity) {
+  return {
+    session: identity.session,
+    agent: identity.agent,
+    agentType: identity.agentType,
+    harness: identity.harness,
+    verified: identity.verified,
+  };
+}
+
+// packages/ai-engineering-gate/src/state.mjs
+const sameFingerprints = (stored, current) => stored.source === current.source
+  && stored.reference === current.reference
+  && stored.decision === current.decision;
+
+function staleCodes(stored, current) {
+  const codes = [];
+  if (stored.source !== current.source) codes.push('stale-source');
+  if (stored.reference !== current.reference) codes.push('stale-reference');
+  if (stored.decision !== current.decision) codes.push('stale-decision');
+  return codes;
+}
+
+// A planned artifact is produced when it exists in the worktree, under the task's evidence, or as an
+// append that names it. Nothing is dispatched to a reviewer to notice an omission a machine can see.
+function missingPlannedArtifacts(context, dimension, records) {
+  const appends = evidenceAppends(context.paths, dimension);
+  const produced = new Set(appends.map(append => append.produces).filter(Boolean));
+  const missing = [];
+  for (const record of records) {
+    for (const plan of record.document.plans ?? []) {
+      if (produced.has(plan.path)) continue;
+      if (existsSync(join(context.repoRoot, plan.path))) continue;
+      if (existsSync(join(context.paths.root, plan.path))) continue;
+      if (!missing.includes(plan.path)) missing.push(plan.path);
+    }
+  }
+  return missing;
+}
+
+const findingsOf = report => report?.envelope?.findings ?? [];
+
+function remedySatisfied(context, dimension, finding, report, records) {
+  const remedy = finding.remedy;
+  if (!remedy) return false;
+  const appends = evidenceAppends(context.paths, dimension)
+    .filter(append => (append.filedAt ?? '') > (report.filedAt ?? ''));
+  if (remedy.kind === 'produce') {
+    return appends.some(append => append.produces === remedy.artifact)
+      || existsSync(join(context.repoRoot, remedy.artifact))
+      || existsSync(join(context.paths.root, remedy.artifact));
+  }
+  if (remedy.kind === 'rerun') {
+    return appends.some(append => append.payload?.command === remedy.command);
+  }
+  if (remedy.kind === 'replay') {
+    return appends.some(append => append.replayed === true && append.payload?.scenario === remedy.scenario);
+  }
+  return false;
+}
+
+function judgmentAddressed(context, dimension, finding, report, records, current) {
+  const cites = records.some(record => (record.document.revision?.addresses ?? []).includes(finding.id));
+  if (!cites) return false;
+  return report.fingerprints.source !== current.source || report.fingerprints.decision !== current.decision;
+}
+
+// A finding is pending until it is addressed, disputed or closed by arbitration. A changed
+// fingerprint alone addresses nothing: touching a file reopens no review.
+function findingStatus(context, dimension, report, records, current) {
+  if (!report) return { pending: [], disputed: [], closed: [] };
+  const openDisputes = disputes(context.paths, dimension).filter(one => one.report === report.id);
+  const decided = arbitrations(context.paths, dimension);
+  const pending = [];
+  const disputed = [];
+  const closed = [];
+  for (const finding of findingsOf(report)) {
+    const dispute = openDisputes.find(one => one.finding === finding.id);
+    const arbitration = dispute && decided.find(one => one.dispute === dispute.id);
+    if (arbitration?.decision === 'uphold') {
+      closed.push(finding.id);
+      continue;
+    }
+    if (dispute && !arbitration) {
+      disputed.push(finding.id);
+      continue;
+    }
+    const addressed = finding.kind === 'evidence'
+      ? remedySatisfied(context, dimension, finding, report, records)
+      : judgmentAddressed(context, dimension, finding, report, records, current);
+    if (addressed) closed.push(finding.id);
+    else pending.push(finding.id);
+  }
+  return { pending, disputed, closed };
+}
+
+function dimensionState(context, dimension) {
+  const declarationRevision = readDeclaration(context.paths, dimension);
+  const declaration = declarationRevision?.document ?? null;
+  const warnings = [];
+  if (installedReferenceMismatch(context.registry, context.members.find(one => one.dimension === dimension))) {
+    warnings.push('reference-mismatch');
+  }
+  if (!declaration) {
+    return {
+      dimension, state: 'undeclared', codes: ['missing-declaration'], warnings, records: 0,
+      missingEvidence: [], openFindings: [], declaration: null,
+    };
+  }
+  if (declaration.applicability === 'non-applicable') {
+    return {
+      dimension,
+      state: 'non-applicable',
+      applicability: 'non-applicable',
+      codes: declaration.reason ? [] : ['missing-reason'],
+      warnings,
+      records: 0,
+      missingEvidence: [],
+      openFindings: [],
+      declaration,
+    };
+  }
+
+  const records = currentRecords(context.paths, dimension);
+  const current = fingerprintsOf(context, dimension, declaration);
+  const openWindow = (() => {
+    const found = readWindow(context.paths, dimension);
+    return found && !found.closed ? found : null;
+  })();
+  const attestations = verdicts(context.paths, 'attestation', dimension);
+  const reports = verdicts(context.paths, 'report', dimension);
+  const filed = [...attestations, ...reports].sort((a, b) => (a.filedAt < b.filedAt ? -1 : 1));
+  const latest = filed.at(-1) ?? null;
+  const currentAttestation = attestations.find(one => sameFingerprints(one.fingerprints, current)) ?? null;
+  const currentReport = reports.filter(one => sameFingerprints(one.fingerprints, current)).at(-1) ?? null;
+  const lastReport = reports.at(-1) ?? null;
+  const status = findingStatus(context, dimension, lastReport, records, current);
+  const unresolvedDispute = status.disputed.length > 0;
+
+  const codes = [];
+  if (records.length === 0) codes.push('missing-record');
+  const missingEvidence = missingPlannedArtifacts(context, dimension, records);
+  if (missingEvidence.length > 0) codes.push('missing-evidence');
+  if (openWindow) codes.push('review-in-flight');
+  if (unresolvedDispute) codes.push('unresolved-dispute');
+  if (currentReport && status.pending.concat(status.disputed).length > 0) codes.push('non-sound-review');
+  if (status.pending.length > 0) codes.push('remedies-pending');
+  if (!currentAttestation) {
+    const stale = filed.filter(one => !sameFingerprints(one.fingerprints, current)).at(-1) ?? null;
+    if (stale) codes.push(...staleCodes(stale.fingerprints, current));
+    else if (!currentReport) codes.push('missing-review');
+  }
+
+  const state = (() => {
+    if (unresolvedDispute) return 'disputed';
+    if (openWindow) return 'in-review';
+    if (currentAttestation) return 'attested';
+    if (currentReport) return 'reported';
+    if (latest) return 'stale';
+    if (records.length > 0) return 'recorded';
+    return 'declared';
+  })();
+
+  for (const record of records) {
+    const wider = (record.document.scope ?? [])
+      .some(path => !(declaration.scope?.paths ?? []).some(scope => matchesPattern(path, scope) || path.startsWith(scope)));
+    if (wider && !warnings.includes('scope-wider-than-declaration')) warnings.push('scope-wider-than-declaration');
+    const claims = (record.document.cites ?? []).map(citation => `${citation.path}\0${citation.claim}`);
+    if (new Set(claims).size !== claims.length && !warnings.includes('duplicate-evidence')) {
+      warnings.push('duplicate-evidence');
+    }
+  }
+  if (currentAttestation?.identity?.verified === false) warnings.push('identity-unverified');
+  const rounds = readRounds(context.paths);
+  if ((rounds.conflicts ?? []).includes(dimension)) warnings.push('cross-dimension-conflict');
+
+  return {
+    dimension,
+    state,
+    applicability: 'applicable',
+    codes: [...new Set(codes)],
+    warnings,
+    records: records.length,
+    missingEvidence,
+    openFindings: [...status.pending, ...status.disputed],
+    fingerprints: { source: current.source, reference: current.reference, decision: current.decision },
+    declaration,
+    recordRefs: records.map(record => record.reference),
+    releasedWindows: closedWindows(context.paths, dimension).filter(one => one.outcome === 'released').length,
+  };
+}
+
+function nextAction(context, states, code) {
+  if (code === 'missing-review') {
+    const agents = [...new Set(
+      states
+        .filter(state => state.codes.includes(code))
+        .map(state => memberAgentType(memberOf(context, state.dimension))),
+    )];
+    if (agents.length > 0) return `dispatch a review round: launch ${agents.join(', ')}`;
+  }
+  return NEXT_ACTION[code] ?? 'read the full status';
+}
+
+const NEXT_ACTION = {
+  'missing-declaration': 'park for the author: declare the dimension applicable or non-applicable with its reason, request and constraints',
+  'missing-reason': 'park for the author: re-declare the dimension with the reason it does not apply',
+  'missing-record': 'park for the author: write a decision record before the first affected write',
+  'missing-evidence': 'park for the author: file the planned artifacts through `evidence append`',
+  'missing-review': 'dispatch a review round: launch the registered reviewer',
+  'non-sound-review': 'park for the author: address or dispute every finding of the report',
+  'remedies-pending': 'dispatch a review round once the builder executes each remedy, or dispute it with counter-evidence',
+  'unresolved-dispute': 'park for the user: run `arbitrate` locally; no agent writes an arbitration',
+  'arbitration-required': 'park for the user: arbitrate the repeating cross-dimension conflict',
+  'round-cap-reached': 'park for the user: the task reached its total round cap',
+  'stale-source': 'dispatch a review round: the code moved since the verdict',
+  'stale-reference': 'dispatch a review round: a catalog, schema or guide moved',
+  'stale-decision': 'dispatch a review round: a declaration or record moved',
+  'review-in-flight': 'park for the author: wait for the open review to file or release',
+  'gate-failure': 'park as infrastructure: the gate itself failed; read the error and fix the setup',
+};
+
+function completionOf(context, states) {
+  const rounds = readRounds(context.paths);
+  const codes = states.flatMap(one => one.codes);
+  if ((rounds.conflictRounds ?? 0) >= context.conflictRoundCap) codes.push('arbitration-required');
+  if ((rounds.round ?? 0) >= context.roundCap) codes.push('round-cap-reached');
+  if (context.requireVerifiedIdentity && states.some(one => one.warnings.includes('identity-unverified'))) {
+    codes.push('non-sound-review');
+  }
+  const unique = [...new Set(codes)];
+  return {
+    complete: unique.length === 0,
+    codes: unique,
+    next: unique.map(code => `${code}: ${nextAction(context, states, code)}`),
+  };
+}
+
+function suiteState(context) {
+  const states = context.dimensions.map(dimension => dimensionState(context, dimension));
+  const undeclared = undeclaredFor(context);
+  if (undeclared.length > 0) {
+    for (const state of states) {
+      if (state.applicability === 'applicable' && !state.warnings.includes('undeclared-change')) {
+        state.warnings.push('undeclared-change');
+      }
+    }
+  }
+  return { states, undeclaredChanges: undeclared, completion: completionOf(context, states), rounds: readRounds(context.paths) };
+}
+
+// A round is ready when every applicable dimension has its records and its planned evidence, no
+// finding is pending, no dispute is open and no window is in flight.
+function reviewReady(states) {
+  const applicable = states.filter(one => one.applicability === 'applicable');
+  if (applicable.length === 0) return false;
+  return applicable.every(one => one.records > 0
+    && one.missingEvidence.length === 0
+    && one.openFindings.length === 0
+    && one.state !== 'in-review');
+}
+
+function blockingCause(states) {
+  const applicable = states.filter(one => one.applicability === 'applicable');
+  for (const code of ['missing-record', 'missing-evidence', 'remedies-pending', 'unresolved-dispute']) {
+    if (applicable.some(one => one.codes.includes(code))) return code;
+  }
+  return null;
+}
+
+// packages/ai-engineering-gate/src/schema.mjs
+// A JSON Schema 2020-12 subset validator, bundled so the gate carries no runtime dependency.
+// It covers the keywords the suite's own schemas use and refuses an unknown keyword rather
+// than ignoring it, so a schema this validator cannot enforce is never silently accepted.
+
+const KNOWN = new Set([
+  '$schema', '$id', '$defs', '$ref', '$comment', 'title', 'description', 'default', 'examples',
+  'type', 'const', 'enum', 'required', 'properties', 'patternProperties', 'additionalProperties',
+  'propertyNames', 'dependentRequired', 'items', 'prefixItems', 'minItems', 'maxItems',
+  'uniqueItems', 'contains', 'minContains', 'maxContains', 'minLength', 'maxLength', 'pattern',
+  'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+  'allOf', 'anyOf', 'oneOf', 'not', 'if', 'then', 'else',
+]);
+
+const typeOf = value => {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+};
+
+const typeMatches = (value, expected) => {
+  const actual = typeOf(value);
+  if (expected === 'number') return actual === 'number' || actual === 'integer';
+  if (expected === 'integer') return actual === 'integer';
+  return actual === expected;
+};
+
+const equals = (a, b) => {
+  if (a === b) return true;
+  if (typeOf(a) !== typeOf(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((item, index) => equals(item, b[index]));
+  if (a && typeof a === 'object') {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => equals(a[key], b[key]));
+  }
+  return false;
+};
+
+const resolvePointer = (root, reference) => {
+  if (!reference.startsWith('#')) throw new Error(`unsupported schema reference: ${reference}`);
+  let node = root;
+  for (const raw of reference.slice(1).split('/').filter(Boolean)) {
+    const token = decodeURIComponent(raw).replaceAll('~1', '/').replaceAll('~0', '~');
+    node = node?.[token];
+    if (node === undefined) throw new Error(`unresolved schema reference: ${reference}`);
+  }
+  return node;
+};
+
+const check = (schema, value, path, root, errors) => {
+  if (schema === true) return;
+  if (schema === false) {
+    errors.push({ path, keyword: 'false', message: 'no value is valid here' });
+    return;
+  }
+  for (const keyword of Object.keys(schema)) {
+    if (!KNOWN.has(keyword)) throw new Error(`unsupported schema keyword: ${keyword}`);
+  }
+  if (schema.$ref !== undefined) check(resolvePointer(root, schema.$ref), value, path, root, errors);
+
+  if (schema.type !== undefined) {
+    const expected = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!expected.some(one => typeMatches(value, one))) {
+      errors.push({ path, keyword: 'type', message: `expected ${expected.join(' or ')}, got ${typeOf(value)}` });
+      return;
+    }
+  }
+  if (schema.const !== undefined && !equals(value, schema.const)) {
+    errors.push({ path, keyword: 'const', message: `expected ${JSON.stringify(schema.const)}` });
+  }
+  if (schema.enum !== undefined && !schema.enum.some(one => equals(value, one))) {
+    errors.push({ path, keyword: 'enum', message: `expected one of ${JSON.stringify(schema.enum)}` });
+  }
+
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && [...value].length < schema.minLength) {
+      errors.push({ path, keyword: 'minLength', message: `shorter than ${schema.minLength}` });
+    }
+    if (schema.maxLength !== undefined && [...value].length > schema.maxLength) {
+      errors.push({ path, keyword: 'maxLength', message: `longer than ${schema.maxLength}` });
+    }
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern, 'u').test(value)) {
+      errors.push({ path, keyword: 'pattern', message: `does not match ${schema.pattern}` });
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) {
+      errors.push({ path, keyword: 'minimum', message: `below ${schema.minimum}` });
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+      errors.push({ path, keyword: 'maximum', message: `above ${schema.maximum}` });
+    }
+    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) {
+      errors.push({ path, keyword: 'exclusiveMinimum', message: `not above ${schema.exclusiveMinimum}` });
+    }
+    if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) {
+      errors.push({ path, keyword: 'exclusiveMaximum', message: `not below ${schema.exclusiveMaximum}` });
+    }
+    if (schema.multipleOf !== undefined && value % schema.multipleOf !== 0) {
+      errors.push({ path, keyword: 'multipleOf', message: `not a multiple of ${schema.multipleOf}` });
+    }
+  }
+
+  if (Array.isArray(value)) {
+    const prefix = schema.prefixItems ?? [];
+    prefix.forEach((item, index) => {
+      if (index < value.length) check(item, value[index], `${path}/${index}`, root, errors);
+    });
+    if (schema.items !== undefined) {
+      for (let index = prefix.length; index < value.length; index += 1) {
+        check(schema.items, value[index], `${path}/${index}`, root, errors);
+      }
+    }
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push({ path, keyword: 'minItems', message: `fewer than ${schema.minItems} items` });
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      errors.push({ path, keyword: 'maxItems', message: `more than ${schema.maxItems} items` });
+    }
+    if (schema.uniqueItems === true) {
+      const duplicate = value.some((item, index) => value.slice(index + 1).some(other => equals(item, other)));
+      if (duplicate) errors.push({ path, keyword: 'uniqueItems', message: 'items are not unique' });
+    }
+    if (schema.contains !== undefined) {
+      const matches = value.filter(item => valid(schema.contains, item, root)).length;
+      const min = schema.minContains ?? 1;
+      if (matches < min) {
+        errors.push({ path, keyword: 'contains', message: `fewer than ${min} matching items` });
+      }
+      if (schema.maxContains !== undefined && matches > schema.maxContains) {
+        errors.push({ path, keyword: 'maxContains', message: `more than ${schema.maxContains} matching items` });
+      }
+    }
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const key of schema.required ?? []) {
+      if (!Object.hasOwn(value, key)) {
+        errors.push({ path, keyword: 'required', message: `missing property ${key}` });
+      }
+    }
+    const declared = new Set(Object.keys(schema.properties ?? {}));
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (Object.hasOwn(value, key)) check(child, value[key], `${path}/${key}`, root, errors);
+    }
+    for (const [pattern, child] of Object.entries(schema.patternProperties ?? {})) {
+      const expression = new RegExp(pattern, 'u');
+      for (const key of Object.keys(value)) {
+        if (!expression.test(key)) continue;
+        declared.add(key);
+        check(child, value[key], `${path}/${key}`, root, errors);
+      }
+    }
+    if (schema.additionalProperties !== undefined) {
+      for (const key of Object.keys(value)) {
+        if (declared.has(key)) continue;
+        if (schema.additionalProperties === false) {
+          errors.push({ path: `${path}/${key}`, keyword: 'additionalProperties', message: 'property is not allowed' });
+        } else {
+          check(schema.additionalProperties, value[key], `${path}/${key}`, root, errors);
+        }
+      }
+    }
+    if (schema.propertyNames !== undefined) {
+      for (const key of Object.keys(value)) check(schema.propertyNames, key, `${path}/${key}`, root, errors);
+    }
+    for (const [key, dependents] of Object.entries(schema.dependentRequired ?? {})) {
+      if (!Object.hasOwn(value, key)) continue;
+      for (const dependent of dependents) {
+        if (!Object.hasOwn(value, dependent)) {
+          errors.push({ path, keyword: 'dependentRequired', message: `${key} requires ${dependent}` });
+        }
+      }
+    }
+  }
+
+  for (const child of schema.allOf ?? []) check(child, value, path, root, errors);
+  if (schema.anyOf !== undefined && !schema.anyOf.some(child => valid(child, value, root))) {
+    errors.push({ path, keyword: 'anyOf', message: 'matches no allowed alternative' });
+  }
+  if (schema.oneOf !== undefined) {
+    const matches = schema.oneOf.filter(child => valid(child, value, root)).length;
+    if (matches !== 1) {
+      errors.push({ path, keyword: 'oneOf', message: `matches ${matches} alternatives, expected exactly one` });
+    }
+  }
+  if (schema.not !== undefined && valid(schema.not, value, root)) {
+    errors.push({ path, keyword: 'not', message: 'matches a forbidden shape' });
+  }
+  if (schema.if !== undefined) {
+    const branch = valid(schema.if, value, root) ? schema.then : schema.else;
+    if (branch !== undefined) check(branch, value, path, root, errors);
+  }
+};
+
+const valid = (schema, value, root) => {
+  const errors = [];
+  check(schema, value, '', root, errors);
+  return errors.length === 0;
+};
+
+function schemaErrors(schema, value) {
+  const errors = [];
+  check(schema, value, '', schema, errors);
+  return errors.map(error => `${error.path || '/'}: ${error.message}`);
+}
+
+// packages/ai-engineering-gate/src/validate.mjs
+// A record is validated twice: against the envelope every dimension shares, and against the
+// dimension's own schema. The gate reads the envelope; the body stays the dimension's business.
+function recordErrors(context, dimension, document) {
+  const member = memberOf(context, dimension);
+  return [
+    ...schemaErrors(context.registry.schemas['decision-envelope'], document),
+    ...schemaErrors(memberDecisionSchema(context.registry, member), document),
+  ];
+}
+
+function sharedErrors(context, name, document) {
+  return schemaErrors(context.registry.schemas[name], document);
+}
+
+function evidenceErrors(context, dimension, document) {
+  const errors = sharedErrors(context, 'evidence-append', document);
+  const schema = memberEvidenceSchema(context.registry, memberOf(context, dimension), document.kind);
+  if (schema) errors.push(...schemaErrors(schema, document.payload));
+  return errors;
+}
+
+// A cited path must exist in the worktree or under the task's evidence when the record is validated.
+// `plans` are deliberately not checked here, so a record can precede the first affected write.
+function resolveCitation(context, path) {
+  for (const candidate of [join(context.repoRoot, path), join(context.paths.root, path)]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function danglingCitations(context, document) {
+  return (document.cites ?? [])
+    .map(citation => citation.path)
+    .filter(path => resolveCitation(context, path) === null);
+}
+
+function citationSnapshot(context, document) {
+  const cites = {};
+  for (const citation of document.cites ?? []) {
+    const resolved = resolveCitation(context, citation.path);
+    cites[citation.path] = resolved ? hashFile(resolved) : null;
+  }
+  return cites;
+}
+
+const CHECKABLE_FACT = /^unknown\b|^unknown$/i;
+
+function walkStrings(value, path, into) {
+  if (typeof value === 'string') {
+    into.push([path, value]);
+    return into;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walkStrings(item, `${path}/${index}`, into));
+    return into;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) walkStrings(child, `${path}/${key}`, into);
+  }
+  return into;
+}
+
+// A claim of unknown about a checkable fact is accepted only with the sources consulted cited, or
+// with the paths searched and not found. Nothing else: a fleet declared unknown without opening a
+// file is what this refuses.
+function unsourcedUnknowns(document) {
+  const citations = document.cites ?? [];
+  const searched = citations.some(citation => (citation.searched ?? []).length > 0);
+  if (searched) return [];
+  const covered = new Set(citations.flatMap(citation => citation.covers ?? []));
+  return walkStrings(document, '', [])
+    .filter(([path, value]) => CHECKABLE_FACT.test(value.trim()) && !path.startsWith('/cites'))
+    .filter(([path]) => {
+      const segments = path.split('/').filter(Boolean).filter(segment => !/^\d+$/.test(segment));
+      return !segments.some(segment => covered.has(segment)) && !covered.has(path);
+    })
+    .map(([path]) => path);
+}
+
+// A revision that announces a correction is refused when no cited artifact changed, so a record
+// cannot describe work a script did not apply.
+function revisionChangeErrors(context, dimension, recordId, document) {
+  const number = document.revision.number;
+  if (number < 2) return [];
+  const snapshot = readRecordSnapshot(context.paths, dimension, recordId, number - 1);
+  if (!snapshot) return [`no snapshot for revision ${number - 1} of ${recordId}`];
+  const current = citationSnapshot(context, document);
+  const named = document.revision.changed ?? null;
+  if (named) {
+    return named
+      .filter(path => (snapshot.cites?.[path] ?? null) === (current[path] ?? null))
+      .map(path => `${path} is named as changed and its content is identical`);
+  }
+  const moved = Object.keys(current).some(path => (snapshot.cites?.[path] ?? null) !== current[path]);
+  return moved ? [] : ['no cited artifact differs from the previous revision'];
+}
+
+// A dispute needs a pointer to counter-evidence that exists now.
+function danglingCounterEvidence(context, document) {
+  return (document.counterEvidence ?? [])
+    .map(pointer => pointer.path)
+    .filter(path => resolveCitation(context, path) === null);
+}
+
+function ignoredFingerprints(document) {
+  const found = walkStrings(document, '', [])
+    .map(([path]) => path)
+    .filter(path => /fingerprint/i.test(path));
+  const keys = Object.keys(document).filter(key => /fingerprint/i.test(key));
+  return found.length > 0 || keys.length > 0;
+}
+
+// packages/ai-engineering-gate/src/cmd-write.mjs
+function requireDimension(context, dimension) {
+  memberOf(context, dimension);
+  return dimension;
+}
+
+// A declaration locks once a record, a report, a window or a dispute depends on it, so a
+// re-declaration cannot erase a stored verdict. Widening the scope or adding constraints is allowed.
+function declarationLock(context, dimension, next) {
+  const previous = readDeclaration(context.paths, dimension);
+  if (!previous) return null;
+  const dependents = [
+    currentRecords(context.paths, dimension).length > 0 && 'a decision record',
+    verdicts(context.paths, 'report', dimension).length > 0 && 'a report',
+    verdicts(context.paths, 'attestation', dimension).length > 0 && 'an attestation',
+    readWindow(context.paths, dimension)?.closed === false && 'an open review window',
+    disputes(context.paths, dimension).length > 0 && 'a dispute',
+  ].filter(Boolean);
+  if (dependents.length === 0) return null;
+  if (onlyWidens(previous.document, next)) return null;
+  return dependents;
+}
+
+function onlyWidens(previous, next) {
+  if (previous.applicability !== next.applicability) return false;
+  if (previous.request !== next.request) return false;
+  if (previous.reason !== next.reason) return false;
+  if (previous.applicability === 'non-applicable') return false;
+  if (previous.base !== next.base) return false;
+  const kept = (previous.scope?.paths ?? []).every(path => (next.scope?.paths ?? []).includes(path));
+  const keptConfiguration = (previous.scope?.configuration ?? [])
+    .every(path => (next.scope?.configuration ?? []).includes(path));
+  const keptConstraints = (previous.constraints ?? []).every(one => (next.constraints ?? []).includes(one));
+  return kept && keptConfiguration && keptConstraints;
+}
+
+function commandDeclare(context, args, document) {
+  const dimension = requireDimension(context, args.dimension);
+  if (document?.dimension !== dimension) {
+    return refuse('invalid-document', `the document declares ${document?.dimension ?? 'no dimension'}, the command declares ${dimension}`);
+  }
+  const errors = sharedErrors(context, 'declaration', document);
+  if (errors.length > 0) return refuse('invalid-document', 'the declaration does not match its schema', errors);
+
+  const revisions = declarationRevisions(context.paths, dimension);
+  const expected = revisions.length + 1;
+  if (document.revision.number !== expected) {
+    return refuse('invalid-document', `the next declaration revision of ${dimension} is ${expected}`);
+  }
+  const locked = declarationLock(context, dimension, document);
+  if (locked) {
+    return refuse('declaration-locked', `${locked.join(' and ')} depends on the declaration of ${dimension}; a revision may only widen its scope or add constraints`);
+  }
+  const identity = captureIdentity(context, 'declare', dimension);
+  stampBuilder(context, identity);
+  const path = writeDeclaration(context.paths, dimension, document.revision.number, document);
+  return accept(
+    `declared ${dimension} ${document.applicability} at revision ${document.revision.number}\nnext: write a decision record before the first affected write`,
+    { document: { kind: 'declaration', dimension, revision: document.revision.number, path } },
+  );
+}
+
+function commandRecord(context, args, document) {
+  const dimension = requireDimension(context, args.dimension);
+  if (document?.dimension !== dimension) {
+    return refuse('invalid-document', `the document records ${document?.dimension ?? 'no dimension'}, the command records ${dimension}`);
+  }
+  const declaration = readDeclaration(context.paths, dimension)?.document ?? null;
+  if (!declaration) {
+    return refuse('invalid-document', `declare ${dimension} before recording a decision for it`);
+  }
+  if (declaration.applicability !== 'applicable') {
+    return refuse('invalid-document', `${dimension} is declared non-applicable; a non-applicable dimension has a declaration and nothing else`);
+  }
+  const errors = recordErrors(context, dimension, document);
+  if (errors.length > 0) return refuse('invalid-document', 'the record does not match its envelope or its dimension schema', errors);
+
+  const dangling = danglingCitations(context, document);
+  if (dangling.length > 0) {
+    return refuse('dangling-reference', 'a cited path does not exist in the worktree or under the task evidence', dangling);
+  }
+  const unsourced = unsourcedUnknowns(document);
+  if (unsourced.length > 0) {
+    return refuse('unknown-without-source', 'a claim of unknown about a checkable fact cites no source consulted and no path searched', unsourced);
+  }
+
+  const number = document.revision.number;
+  let recordId;
+  if (number === 1) {
+    recordId = nextRecordId(context.paths, dimension);
+  } else {
+    const reference = /^(rec-\d+)@(\d+)$/.exec(document.revision.previous ?? '');
+    if (!reference) {
+      return refuse('invalid-document', 'revision previous must name the preceding revision as `rec-001@1`');
+    }
+    recordId = reference[1];
+    const existing = readRecord(context.paths, dimension, recordId);
+    if (!existing) return refuse('invalid-document', `${recordId} is not a record of ${dimension} for this task`);
+    if (existing.number !== number - 1 || Number(reference[2]) !== number - 1) {
+      return refuse('invalid-document', `the next revision of ${recordId} is ${existing.number + 1}`);
+    }
+    const changeErrors = revisionChangeErrors(context, dimension, recordId, document);
+    if (changeErrors.length > 0) {
+      return refuse('revision-without-change', 'the revision announces a correction that no cited artifact shows', changeErrors);
+    }
+  }
+
+  const warnings = ignoredFingerprints(document) ? ['fingerprint-ignored'] : [];
+  const identity = captureIdentity(context, 'record', dimension);
+  stampBuilder(context, identity);
+  const path = writeRecord(context.paths, dimension, recordId, number, document);
+  writeRecordSnapshot(context.paths, dimension, recordId, number, {
+    revision: number,
+    cites: citationSnapshot(context, document),
+    builder: storedIdentity(identity),
+    writtenAt: new Date().toISOString(),
+  });
+  const planned = (document.plans ?? []).map(plan => plan.path);
+  const lines = [`recorded ${dimension} ${recordId}@${number}`];
+  if (planned.length > 0) lines.push(`plans: ${planned.join(', ')}`);
+  lines.push('next: write the implementation, then file every planned artifact through `evidence append`');
+  return accept(lines.join('\n'), {
+    document: { kind: 'record', dimension, id: recordId, revision: number, path },
+    warnings,
+  });
+}
+
+function commandEvidenceAppend(context, args, document) {
+  const dimension = requireDimension(context, args.dimension);
+  if (document?.dimension !== dimension) {
+    return refuse('invalid-document', `the append names ${document?.dimension ?? 'no dimension'}, the command names ${dimension}`);
+  }
+  const errors = evidenceErrors(context, dimension, document);
+  if (errors.length > 0) return refuse('invalid-document', 'the evidence append does not match its schema', errors);
+  const record = readRecord(context.paths, dimension, document.record.split('@')[0]);
+  if (!record) return refuse('invalid-document', `${document.record} is not a record of ${dimension} for this task`);
+
+  const identity = captureIdentity(context, 'evidence', dimension);
+  stampBuilder(context, identity);
+  const stamped = stampAppend(context, dimension, record, document, identity, false);
+  const stampErrors = sharedErrors(context, 'evidence-append', stamped);
+  if (stampErrors.length > 0) {
+    throw new Error(`the gate stamped an append its own schema refuses: ${stampErrors.join('; ')}`);
+  }
+  const path = appendEvidence(context.paths, dimension, stamped);
+  return accept(`appended ${document.kind} to ${dimension} ${record.reference}`, {
+    document: { kind: 'evidence-append', dimension, path },
+  });
+}
+
+// Every append carries the content hashes of the record's planned artifacts, by role, so an event
+// proves the state of test and production files at the moment it was filed.
+function stampAppend(context, dimension, record, document, identity, replayed, hashRoot = context.repoRoot) {
+  const roles = {};
+  for (const plan of record.document.plans ?? []) {
+    const digest = hashFile(join(hashRoot, plan.path)) ?? hashFile(join(context.paths.root, plan.path));
+    roles[plan.role] = { ...(roles[plan.role] ?? {}), [plan.path]: digest };
+  }
+  return {
+    ...document,
+    filedAt: new Date().toISOString(),
+    artifactHashes: roles,
+    builder: storedIdentity(identity),
+    replayed,
+  };
+}
+
+function commandDispute(context, args, document) {
+  const dimension = requireDimension(context, args.dimension);
+  const errors = sharedErrors(context, 'dispute', document);
+  if (errors.length > 0) return refuse('invalid-document', 'the dispute does not match its schema', errors);
+  if (document.dimension !== dimension) {
+    return refuse('invalid-document', `the dispute names ${document.dimension}, the command names ${dimension}`);
+  }
+  const report = verdicts(context.paths, 'report', dimension).find(one => one.id === document.report);
+  if (!report) return refuse('invalid-document', `${document.report} is not a report of ${dimension} for this task`);
+  const finding = (report.envelope.findings ?? []).find(one => one.id === document.finding);
+  if (!finding) return refuse('invalid-document', `${document.report} carries no finding ${document.finding}`);
+  const dangling = danglingCounterEvidence(context, document);
+  if (dangling.length > 0) {
+    return refuse('dispute-without-evidence', 'the counter-evidence points at a path that does not exist', dangling);
+  }
+  const already = disputes(context.paths, dimension).find(one => one.finding === document.finding
+    && !arbitrations(context.paths, dimension).some(decided => decided.dispute === one.id));
+  if (already) return refuse('invalid-document', `${document.finding} is already disputed as ${already.id}`);
+
+  const identity = captureIdentity(context, 'dispute', dimension);
+  stampBuilder(context, identity);
+  const id = writeDispute(context.paths, dimension, {
+    ...document, filedAt: new Date().toISOString(), builder: storedIdentity(identity),
+  });
+  return accept(
+    `disputed ${dimension} finding ${document.finding} as ${id}\nnext: the user decides; run \`${context.gateCommand} arbitrate --dimension ${dimension} --stdin\` yourself, no agent writes an arbitration`,
+    { document: { kind: 'dispute', dimension, id } },
+  );
+}
+
+// Only a human writes an arbitration. Every agent tool call the hook saw left a handoff; a command
+// the user types passes through no hook and leaves none, and that absence is the mechanical sign.
+function commandArbitrate(context, args, document) {
+  const dimension = requireDimension(context, args.dimension);
+  const identity = captureIdentity(context, 'arbitrate', dimension);
+  if (identity.handoffPresent) {
+    return refuse('agent-arbitration-refused', 'an agent tool call invoked arbitrate; only a command the user types can write an arbitration');
+  }
+  const errors = sharedErrors(context, 'arbitration', document);
+  if (errors.length > 0) return refuse('invalid-document', 'the arbitration does not match its schema', errors);
+  if (document.dimension !== dimension) {
+    return refuse('invalid-document', `the arbitration names ${document.dimension}, the command names ${dimension}`);
+  }
+  const dispute = disputes(context.paths, dimension).find(one => one.id === document.dispute);
+  if (!dispute) return refuse('invalid-document', `${document.dispute} is not a dispute of ${dimension} for this task`);
+  if (arbitrations(context.paths, dimension).some(one => one.dispute === document.dispute)) {
+    return refuse('invalid-document', `${document.dispute} is already arbitrated`);
+  }
+  const id = writeArbitration(context.paths, dimension, {
+    ...document, finding: dispute.finding, filedAt: new Date().toISOString(),
+  });
+  if (document.decision === 'uphold') {
+    const rounds = readRounds(context.paths);
+    writeRounds(context.paths, {
+      ...rounds, conflictRounds: 0, conflicts: [], upheld: [...(rounds.upheld ?? []), { dimension, arbitration: id }],
+    });
+  }
+  const next = document.decision === 'uphold'
+    ? `next: one fresh review of ${dimension} is allowed on this same state`
+    : `next: execute the remedy or correction of ${dispute.finding}`;
+  return accept(`arbitrated ${document.dispute} as ${document.decision} (${id})\n${next}`, {
+    document: { kind: 'arbitration', dimension, id },
+  });
+}
+
+function plannedEvidenceMissing(context, dimension) {
+  return missingPlannedArtifacts(context, dimension, currentRecords(context.paths, dimension));
+}
+
+// packages/ai-engineering-gate/src/plan.mjs
+// The gate never spawns, stops or messages an agent: it prints what to launch. The brief is rendered
+// from the declaration alone - the requester's wording, the factual constraints, the scope and the
+// base - so nothing of the builder's rationale reaches a reviewer.
+function neutralBrief(context, state, view) {
+  const member = memberOf(context, state.dimension);
+  const reviewSkill = member.review.split('/').pop();
+  const declaration = state.declaration;
+  const rounds = readRounds(context.paths);
+  const conflict = (rounds.conflicts ?? []).includes(state.dimension);
+  const lines = [
+    '```text',
+    `You are the fresh ${state.dimension} reviewer. Run /${reviewSkill} yourself; do not delegate.`,
+    'Read-only: do not modify any file, including code, records, catalogs or fixtures.',
+    `Scope: ${(declaration.scope?.paths ?? []).join(', ')}; repository: ${context.repoRoot}.`,
+    `Base: ${declaration.base}; include relevant uncommitted and new files.`,
+    'Use git diff and file reads, never git log or PR descriptions.',
+    `Original request: ${declaration.request}`,
+    `Factual constraints: ${(declaration.constraints ?? []).join(' | ') || 'none stated'}.`,
+    `Records: ${state.recordRefs.map(reference => join(context.paths.records, state.dimension, reference.replace('@', '/rev-') + '.json')).join(', ')}`,
+    `Check evidence: ${join(context.paths.evidence, state.dimension)}`,
+    `Undeclared changes: ${view.undeclaredChanges.join(', ') || 'none'}.`,
+  ];
+  if (declaration.scope?.configuration?.length) {
+    lines.push(`Relevant configuration: ${declaration.scope.configuration.join(', ')}.`);
+  }
+  if (state.warnings.includes('duplicate-evidence')) {
+    lines.push('Note: two cited evidence items in one record are identical.');
+  }
+  if (conflict) {
+    lines.push('Note: this dimension turned non-SOUND on a state produced by correcting another; the conflicting findings are in the previous reports.');
+  }
+  for (const arbitration of arbitrationsOf(view, state.dimension)) {
+    lines.push(`Note: the user arbitrated finding ${arbitration.finding} as ${arbitration.decision}: ${arbitration.words}`);
+  }
+  lines.push(`Open your window first: ${context.gateCommand} begin --dimension ${state.dimension}`);
+  lines.push('Report your frozen matrix before opening the records. End with the domain report');
+  lines.push('and one verdict, or explain incomplete execution without attestation.');
+  lines.push('```');
+  return lines.join('\n');
+}
+
+const arbitrationsOf = (view, dimension) => (view.arbitrations ?? []).filter(one => one.dimension === dimension);
+
+function dispatchPlan(context, view) {
+  if (!reviewReady(view.states)) return [];
+  return view.states
+    .filter(state => state.applicability === 'applicable' && state.state !== 'attested')
+    .map(state => {
+      const member = memberOf(context, state.dimension);
+      const fingerprints = fingerprintsOf(context, state.dimension, state.declaration);
+      return {
+        dimension: state.dimension,
+        agent: memberAgentType(member),
+        skill: member.review.split('/').pop(),
+        fingerprints: {
+          source: fingerprints.source,
+          reference: fingerprints.reference,
+          decision: fingerprints.decision,
+        },
+        brief: neutralBrief(context, state, view),
+      };
+    });
+}
+
+// packages/ai-engineering-gate/src/cmd-inspect.mjs
+function suiteView(context) {
+  const view = suiteState(context);
+  view.arbitrations = context.dimensions.flatMap(dimension => arbitrations(context.paths, dimension)
+    .map(one => ({ ...one, dimension })));
+  view.plan = dispatchPlan(context, view);
+  return view;
+}
+
+function commandStatus(context) {
+  const view = suiteView(context);
+  return { ok: true, view };
+}
+
+function commandCanStop(context) {
+  const view = suiteView(context);
+  return { ok: view.completion.complete, view };
+}
+
+function commandCanStopHook(context, reentrant) {
+  const view = suiteView(context);
+  if (view.completion.complete) return { ok: true, view, silent: true };
+  const fingerprint = hashJson(view.states.map(state => ({
+    dimension: state.dimension,
+    fingerprints: state.fingerprints ?? null,
+    codes: state.codes,
+  })));
+  const previous = readStopSnapshot(context.paths);
+  if (reentrant && previous?.fingerprint === fingerprint) return { ok: true, view, silent: true };
+  writeStopSnapshot(context.paths, { fingerprint });
+  return { ok: false, view };
+}
+
+// The text form answers the one question a builder asks - what does the gate see right now - while
+// `--json` stays the single status shape, whose dimensions already carry the same three digests.
+function commandFingerprint(context, args) {
+  const all = declarations(context);
+  const wanted = args.dimension ? [args.dimension] : context.dimensions;
+  const lines = wanted.map(dimension => {
+    const fingerprints = fingerprintsOf(context, dimension, all[dimension]);
+    return `${dimension}\n  source    ${fingerprints.source}\n  reference ${fingerprints.reference}\n  decision  ${fingerprints.decision}`;
+  });
+  return { ok: true, text: lines.join('\n'), view: suiteView(context) };
+}
+
+const WRITE_FORM = /(^|[\s;&|])(>|>>|tee\b|sed\s+-i|perl\s+-i|mv\b|cp\b)|git\s+(apply|checkout|restore|stash|clean|rm|mv)\b|\bpatch\b/u;
+
+// `can-write` is mechanical only. It decides by file path, never by the content of a write, and it
+// never infers applicability for the builder: a path outside every declared scope passes, except
+// while a review window is open, when the whole change set is frozen.
+function commandCanWrite(context, args) {
+  const paths = args.paths ?? [];
+  const command = args.command ?? null;
+  const all = declarations(context);
+
+  const openWindows = context.dimensions
+    .map(dimension => ({ dimension, window: readWindow(context.paths, dimension) }))
+    .filter(one => one.window && !one.window.closed)
+    .map(one => one.dimension);
+
+  const indexHit = paths.some(path => isInside(context.paths.index, absolute(context, path)))
+    || (command !== null && command.includes(context.paths.index) && WRITE_FORM.test(command));
+  if (indexHit) {
+    return refuse('invalid-document', `the gate index is written by gate commands only: ${context.paths.index}`);
+  }
+
+  const relatives = paths.map(path => toRepoRelative(context.repoRoot, path));
+  if (openWindows.length > 0) {
+    const hitsChangeSet = relatives.some(path => path && !excludedFromChangeSet(context, path))
+      || (command !== null && WRITE_FORM.test(command));
+    if (hitsChangeSet) {
+      return refuse(
+        'review-in-flight',
+        `a review is in flight on ${openWindows.join(', ')}; wait for it to file or release before editing the change set`,
+        openWindows,
+      );
+    }
+  }
+
+  const scoped = [];
+  for (const relative of relatives) {
+    for (const dimension of coveringDimensions(relative, all)) {
+      if (!scoped.includes(dimension)) scoped.push(dimension);
+    }
+  }
+  if (command !== null && WRITE_FORM.test(command)) {
+    for (const [dimension, declaration] of Object.entries(all)) {
+      if (declaration?.applicability !== 'applicable') continue;
+      const named = (declaration.scope?.paths ?? []).some(scope => command.includes(scope));
+      if (named && !scoped.includes(dimension)) scoped.push(dimension);
+    }
+  }
+  if (scoped.length === 0) {
+    return accept(paths.length > 0
+      ? `allowed: no declared scope covers ${paths.join(', ')}`
+      : 'allowed: nothing in a declared scope');
+  }
+  const without = scoped.filter(dimension => currentRecords(context.paths, dimension).length === 0);
+  if (without.length > 0) {
+    return refuse(
+      'invalid-document',
+      `${without.join(' and ')} has no validated decision record and this path is inside its declared scope; record the decision before the first affected write`,
+      without,
+    );
+  }
+  return accept(`allowed: ${scoped.join(', ')} already has a validated decision record`);
+}
+
+function absolute(context, path) {
+  return isAbsolute(path) ? path : resolve(context.repoRoot, path);
+}
+
+// Paths a harness edit tool names, whatever the tool's own shape.
+function editedPaths(toolInput) {
+  const found = [];
+  for (const key of ['file_path', 'filePath', 'notebook_path', 'notebookPath', 'path', 'target_file']) {
+    if (typeof toolInput?.[key] === 'string') found.push(toolInput[key]);
+  }
+  for (const edit of toolInput?.edits ?? []) {
+    if (typeof edit?.file_path === 'string') found.push(edit.file_path);
+    if (typeof edit?.path === 'string') found.push(edit.path);
+  }
+  for (const change of toolInput?.changes ?? []) {
+    if (typeof change?.path === 'string') found.push(change.path);
+  }
+  return [...new Set(found)];
+}
+
+function shellCommand(toolInput) {
+  for (const key of ['command', 'cmd', 'script']) {
+    if (typeof toolInput?.[key] === 'string') return toolInput[key];
+  }
+  return null;
+}
+
+// packages/ai-engineering-gate/src/cmd-review.mjs
+function reviewReadiness(context, dimension) {
+  const view = suiteState(context);
+  const own = view.states.find(state => state.dimension === dimension);
+  if (!own) return refuse('invalid-document', `${dimension} is not a dimension this project registers`);
+  if (own.applicability !== 'applicable') {
+    return refuse('not-review-ready', `${dimension} is declared non-applicable; there is nothing to review`, [], 'missing-declaration');
+  }
+  const open = readWindow(context.paths, dimension);
+  if (open && !open.closed) {
+    return refuse('review-in-flight', `${dimension} already has an open review window opened at ${open.openedAt}`);
+  }
+  // Corrections are batched: while any dimension of the task has a pending finding, no review reopens.
+  const cause = blockingCause(view.states);
+  if (cause) {
+    const upheld = (view.rounds.upheld ?? []).some(one => one.dimension === dimension);
+    if (!(cause === 'remedies-pending' && upheld)) {
+      const blocking = view.states.filter(state => state.codes.includes(cause)).map(state => state.dimension);
+      return refuse('not-review-ready', `${cause} on ${blocking.join(', ')}`, blocking, cause);
+    }
+  }
+  if ((view.rounds.conflictRounds ?? 0) >= context.conflictRoundCap) {
+    return refuse('not-review-ready', `${dimension} reached the cross-dimension conflict cap; the user arbitrates before another review`, [], 'arbitration-required');
+  }
+  if ((view.rounds.round ?? 0) >= context.roundCap) {
+    return refuse('not-review-ready', `the task reached its total round cap of ${context.roundCap}`, [], 'round-cap-reached');
+  }
+  return { ok: true, view, own };
+}
+
+function commandCanReview(context, args) {
+  const dimension = args.dimension;
+  if (!dimension) return accept('allowed: no dimension named, nothing to gate');
+  const readiness = reviewReadiness(context, dimension);
+  if (!readiness.ok) return readiness;
+  return accept(`allowed: ${dimension} is ready for a fresh review`);
+}
+
+function commandBegin(context, args) {
+  const dimension = args.dimension;
+  const readiness = reviewReadiness(context, dimension);
+  if (!readiness.ok) return readiness;
+  const identity = captureIdentity(context, 'begin', dimension);
+  if (identity.providesAgents && !identity.agent) {
+    return refuse('identity-refused', 'this harness reports an agent identifier and none reached the gate; a review cannot begin without one');
+  }
+  if (isBuilderIdentity(context, identity)) {
+    return refuse('identity-refused', 'the caller is the builder of this task; a review is dispatched to a fresh context');
+  }
+  const declaration = readDeclaration(context.paths, dimension).document;
+  const fingerprints = fingerprintsOf(context, dimension, declaration);
+  const window = {
+    dimension,
+    openedAt: new Date().toISOString(),
+    identity: storedIdentity(identity),
+    fingerprints: {
+      source: fingerprints.source,
+      reference: fingerprints.reference,
+      decision: fingerprints.decision,
+    },
+    closed: false,
+  };
+  writeWindow(context.paths, dimension, window);
+  const lines = [
+    `window open for ${dimension}`,
+    `state: source ${fingerprints.source} reference ${fingerprints.reference} decision ${fingerprints.decision}`,
+    `records: ${currentRecords(context.paths, dimension).map(record => record.reference).join(', ')}`,
+  ];
+  lines.push(`next: file with \`${context.gateCommand} attest --dimension ${dimension} --stdin\` for SOUND, \`report\` otherwise`);
+  return accept(lines.join('\n'), {
+    document: { kind: 'window', dimension, fingerprints: window.fingerprints },
+    warnings: identity.verified ? [] : ['identity-unverified'],
+  });
+}
+
+function fileVerdict(context, args, document, kind) {
+  const dimension = args.dimension;
+  const member = memberOf(context, dimension);
+  const errors = sharedErrors(context, 'review-envelope', document);
+  if (errors.length > 0) return refuse('invalid-document', 'the review envelope does not match its schema', errors);
+  if (document.dimension !== dimension) {
+    return refuse('invalid-document', `the envelope reviews ${document.dimension}, the command reviews ${dimension}`);
+  }
+  if (!member.contractVersions.includes(document.contractVersion)) {
+    return refuse('invalid-document', `${dimension} supports contract ${member.contractVersions.join(' or ')}, the envelope declares ${document.contractVersion}`);
+  }
+  if (kind === 'attestation' && document.verdict !== 'SOUND') {
+    return refuse('invalid-document', 'attest accepts SOUND only; file SMELLS and VIOLATIONS through report');
+  }
+  if (kind === 'report' && document.verdict === 'SOUND') {
+    return refuse('invalid-document', 'report accepts SMELLS and VIOLATIONS; file SOUND through attest');
+  }
+  for (const finding of document.findings) {
+    if (finding.kind === 'evidence' && !finding.remedy) {
+      return refuse('finding-without-remedy', `finding ${finding.id} is about evidence and names no remedy the builder can execute`);
+    }
+  }
+
+  const open = readWindow(context.paths, dimension);
+  if (!open || open.closed) {
+    return refuse('no-window', `no open review window for ${dimension}; run \`${context.gateCommand} begin --dimension ${dimension}\` first`);
+  }
+  const identity = captureIdentity(context, kind === 'attestation' ? 'attest' : 'report', dimension);
+  if (identity.providesAgents && !identity.agent) {
+    return refuse('identity-refused', 'this harness reports an agent identifier and none reached the gate');
+  }
+  if (identity.agent && open.identity.agent && identity.agent !== open.identity.agent) {
+    return refuse('no-window', `the window for ${dimension} was opened by another agent`);
+  }
+  if (isBuilderIdentity(context, identity)) {
+    return refuse('identity-refused', 'the caller is the builder of this task; only a fresh reviewer files a verdict');
+  }
+  if (context.requireVerifiedIdentity && !identity.verified) {
+    return refuse('identity-refused', 'the marker requires a verified agent identity and this harness reports none');
+  }
+
+  const state = dimensionState(context, dimension);
+  const missing = state.missingEvidence;
+  if (missing.length > 0) {
+    return refuse('not-review-ready', 'a planned artifact is still not produced', missing, 'missing-evidence');
+  }
+  const current = fingerprintsOf(context, dimension, state.declaration);
+  const moved = ['source', 'reference', 'decision'].filter(one => current[one] !== open.fingerprints[one]);
+  if (moved.length > 0) {
+    closeWindow(context.paths, dimension, 'voided');
+    return refuse('state-moved', `the ${moved.join(' and ')} fingerprint moved since this review began; the review is void and a fresh one is needed`, moved);
+  }
+
+  const warnings = [];
+  if (ignoredFingerprints(document)) warnings.push('fingerprint-ignored');
+  if (!identity.verified) warnings.push('identity-unverified');
+  if (document.reviewer.agentType && document.reviewer.agentType !== memberAgentType(member)) {
+    warnings.push('identity-unverified');
+  }
+
+  const rounds = readRounds(context.paths);
+  const round = (rounds.round ?? 0) + (rounds.filedOn === current.source ? 0 : 1);
+  const previous = verdicts(context.paths, 'attestation', dimension).at(-1) ?? null;
+  const verdict = {
+    document: kind,
+    documentVersion: '1.0.0',
+    dimension,
+    task: context.task,
+    round,
+    filedAt: new Date().toISOString(),
+    gateVersion: context.version,
+    fingerprints: {
+      source: current.source,
+      reference: current.reference,
+      decision: current.decision,
+    },
+    identity: storedIdentity(identity),
+    envelope: document,
+    ...(kind === 'report' ? { openFindings: document.findings.map(finding => finding.id) } : {}),
+    warnings,
+  };
+  // The gate holds itself to the same schema it holds every writer to, so a drift in what it stores
+  // fails here rather than reappearing as an unreadable index later.
+  const stored = sharedErrors(context, 'verdict-record', { ...verdict, id: 'pending' });
+  if (stored.length > 0) {
+    throw new Error(`the gate composed a ${kind} its own schema refuses: ${stored.join('; ')}`);
+  }
+  const id = writeVerdict(context.paths, kind, dimension, verdict);
+  closeWindow(context.paths, dimension, 'filed');
+
+  // A dimension that was SOUND and turns non-SOUND on a state produced by correcting another is a
+  // cross-dimension conflict. The next briefs carry it and a repeating one goes to the user.
+  const conflict = kind === 'report' && previous !== null;
+  const conflicts = new Set(rounds.conflicts ?? []);
+  if (conflict) conflicts.add(dimension);
+  const sameState = rounds.filedOn === current.source;
+  let conflictRounds = rounds.conflictRounds ?? 0;
+  if (!sameState) {
+    conflictRounds = conflict ? ((rounds.roundConflicted ? conflictRounds : 0) + 1) : 0;
+  } else if (conflict && !rounds.roundConflicted) {
+    conflictRounds += 1;
+  }
+  writeRounds(context.paths, {
+    ...rounds,
+    round,
+    filedOn: current.source,
+    conflicts: [...conflicts],
+    roundConflicted: sameState ? Boolean(rounds.roundConflicted) || conflict : conflict,
+    conflictRounds,
+    history: [...(rounds.history ?? []), { round, dimension, verdict: document.verdict, id }],
+  });
+
+  const lines = [`filed ${kind} ${id} for ${dimension}: ${document.verdict}`];
+  if (kind === 'report') {
+    lines.push(`findings: ${document.findings.map(finding => `${finding.id} (${finding.kind}, ${finding.severity})`).join(', ')}`);
+    lines.push('next: the builder addresses or disputes every finding before any review of this task reopens');
+  }
+  return accept(lines.join('\n'), {
+    document: { kind, dimension, id },
+    warnings: conflict ? [...warnings, 'cross-dimension-conflict'] : warnings,
+  });
+}
+
+function commandAttest(context, args, document) {
+  return fileVerdict(context, args, document, 'attestation');
+}
+
+function commandReport(context, args, document) {
+  return fileVerdict(context, args, document, 'report');
+}
+
+function commandRelease(context, args) {
+  const dimension = args.dimension;
+  if (!dimension) return accept('nothing to release: no dimension named');
+  const released = closeWindow(context.paths, dimension, 'released');
+  if (!released) return accept(`no open window for ${dimension}`);
+  return accept(`released the open review window for ${dimension}\nnext: dispatch a fresh reviewer for ${dimension}`);
+}
+
+// packages/ai-engineering-gate/src/cmd-transfer.mjs
+// The export directory carries the task's documents into the repository so a CI runner can recompute
+// the fingerprints from a clean checkout. It is excluded from the change set and never fingerprinted.
+function commandExport(context) {
+  const directory = context.marker.exportDirectory;
+  if (!directory) {
+    return refuse('invalid-document', 'the marker names no exportDirectory; add one before exporting');
+  }
+  const dirty = git(['status', '--porcelain'], context.repoRoot).stdout
+    .split('\n')
+    .map(line => line.slice(3).trim().replace(/^.* -> /, ''))
+    .filter(Boolean)
+    .filter(path => !path.startsWith(directory));
+  const change = dirty.filter(path => !excludedFromChangeSet(context, path));
+  if (change.length > 0) {
+    return refuse(
+      'state-moved',
+      'HEAD would recompute different fingerprints than the attestations; commit the change set first',
+      change.slice(0, 20),
+    );
+  }
+  const view = suiteView(context);
+  if (!view.completion.complete) {
+    return refuse('not-review-ready', 'the task is not complete, so its verdicts cannot be published', view.completion.codes);
+  }
+  const target = join(context.repoRoot, directory, context.task);
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(context.paths.root, target, { recursive: true });
+  const attested = view.states.filter(state => state.applicability === 'applicable').length;
+  return accept(
+    `exported ${attested} attested dimensions of ${context.task} to ${directory}/${context.task}\nnext: commit the export directory and let CI verify it from a clean checkout`,
+    { document: { kind: 'export', path: target } },
+  );
+}
+
+// The CI half of the direct-PR route: the same completion logic over exported evidence, plus the two
+// checks only a clean checkout can make - the gate version the attestations record, and the marker.
+function exportVerificationErrors(context, base) {
+  const errors = [];
+  for (const dimension of context.dimensions) {
+    for (const attestation of verdicts(context.paths, 'attestation', dimension)) {
+      if (attestation.gateVersion !== context.version) {
+        errors.push(`${dimension}: ${attestation.id} was filed by gate ${attestation.gateVersion} and this gate is ${context.version}`);
+      }
+    }
+  }
+  if (base) {
+    const onBase = git(['cat-file', '-e', `${base}:.ai-engineering-suite.json`], context.repoRoot).ok;
+    if (onBase && !context.marked) {
+      errors.push(`the marker exists on ${base} and not on this head`);
+    }
+  }
+  return errors;
+}
+
+function applyExportVerification(context, result, base) {
+  const errors = exportVerificationErrors(context, base);
+  if (errors.length === 0) return result;
+  const versionDrift = errors.some(one => one.includes('was filed by gate'));
+  const codes = new Set(result.view?.completion?.codes ?? []);
+  if (versionDrift) codes.add('stale-reference');
+  const view = result.view && {
+    ...result.view,
+    completion: {
+      complete: false,
+      codes: [...codes],
+      next: result.view.completion.next,
+    },
+  };
+  if (versionDrift) {
+    return { ok: false, view, details: errors };
+  }
+  return {
+    ok: false,
+    view,
+    code: 'invalid-document',
+    reason: 'the exported evidence does not verify against this checkout',
+    details: errors,
+  };
+}
+
+// The gate executes the replay, never the builder. An isolated copy at the record's base carries the
+// planned test artifacts alone, so the red it captures is a fact the gate stamped.
+function commandReplay(context, args) {
+  if (!context.allowReplay) {
+    return refuse('replay-forbidden', 'the marker forbids the replay remedy; rerun a full cycle instead');
+  }
+  const dimension = args.dimension;
+  const record = readRecord(context.paths, dimension, (args.record ?? '').split('@')[0]);
+  if (!record) return refuse('invalid-document', `${args.record} is not a record of ${dimension} for this task`);
+  if (!args.command) return refuse('invalid-document', 'replay needs the scenario command to run');
+  const plans = record.document.plans ?? [];
+  const tests = plans.filter(plan => plan.role === 'test');
+  const production = plans.filter(plan => plan.role === 'production');
+  if (tests.length === 0 || production.length === 0) {
+    return refuse('invalid-document', 'a replay needs planned artifacts of role test and of role production');
+  }
+  const base = record.document.base;
+  const point = git(['merge-base', base, 'HEAD'], context.repoRoot);
+  if (!point.ok) return refuse('invalid-document', `cannot resolve the record base ${base}`);
+
+  const isolated = mkdtempSync(join(tmpdir(), 'ai-engineering-replay-'));
+  const worktree = join(isolated, 'worktree');
+  const added = git(['worktree', 'add', '--detach', worktree, point.stdout], context.repoRoot);
+  if (!added.ok) {
+    rmSync(isolated, { recursive: true, force: true });
+    return refuse('invalid-document', `cannot create the isolated copy: ${added.stderr}`);
+  }
+  try {
+    for (const name of ['node_modules', '.venv']) {
+      const source = join(context.repoRoot, name);
+      if (existsSync(source) && !existsSync(join(worktree, name))) symlinkSync(source, join(worktree, name));
+    }
+    place(context, worktree, tests);
+    const red = run(args.command, worktree);
+    const identity = captureIdentity(context, 'replay', dimension);
+    const redEvent = appendEvidence(context.paths, dimension, stampAppend(context, dimension, record, {
+      document: 'evidence-append',
+      documentVersion: '1.0.0',
+      dimension,
+      record: record.reference,
+      kind: 'journal-event',
+      payload: {
+        record: record.reference,
+        scenario: args.scenario ?? 'scenario',
+        phase: 'red',
+        command: args.command,
+        exitCode: red.code,
+        output: writeOutput(context, args.scenario, 'red', red.output),
+        cause: firstFailure(red.output),
+        failureClass: 'expected-behavior-missing',
+      },
+    }, identity, true, worktree));
+    place(context, worktree, production);
+    const green = run(args.command, worktree);
+    const greenEvent = appendEvidence(context.paths, dimension, stampAppend(context, dimension, record, {
+      document: 'evidence-append',
+      documentVersion: '1.0.0',
+      dimension,
+      record: record.reference,
+      kind: 'journal-event',
+      payload: {
+        record: record.reference,
+        scenario: args.scenario ?? 'scenario',
+        phase: 'green',
+        command: args.command,
+        exitCode: green.code,
+        output: writeOutput(context, args.scenario, 'green', green.output),
+      },
+    }, identity, true, worktree));
+    const events = [redEvent, greenEvent];
+    const lines = [
+      `replayed ${dimension} ${record.reference} scenario ${args.scenario ?? 'scenario'}`,
+      `red exit ${red.code}, green exit ${green.code}`,
+    ];
+    if (red.code === 0) {
+      lines.push('warn: the test passed without the production change, so it discriminates nothing');
+    }
+    lines.push(`events: ${events.length} appended and stamped by the gate`);
+    return accept(lines.join('\n'), { document: { kind: 'replay', dimension, events } });
+  } finally {
+    git(['worktree', 'remove', '--force', worktree], context.repoRoot);
+    rmSync(isolated, { recursive: true, force: true });
+  }
+}
+
+function writeOutput(context, scenario, phase, output) {
+  const relative = join('replays', `${scenario ?? 'scenario'}-${phase}.txt`);
+  writeFileSync(ensure(join(context.paths.root, relative)), output);
+  return relative;
+}
+
+function ensure(path) {
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+}
+
+function place(context, worktree, plans) {
+  for (const plan of plans) {
+    const source = join(context.repoRoot, plan.path);
+    if (!existsSync(source)) continue;
+    writeFileSync(ensure(join(worktree, plan.path)), readFileSync(source));
+  }
+}
+
+// Variables a caller's own runner uses to talk to its children. Inherited, they change the reporter
+// and the exit code of the scenario, so a replay run from inside a test suite would read green where
+// a shell reads red.
+const RUNNER_PRIVATE = ['NODE_TEST_CONTEXT', 'NODE_V8_COVERAGE', 'VITEST', 'VITEST_WORKER_ID', 'JEST_WORKER_ID'];
+
+function run(command, cwd) {
+  const env = { ...process.env };
+  for (const name of RUNNER_PRIVATE) delete env[name];
+  const result = spawnSync(command, { cwd, env, shell: true, encoding: 'utf8', timeout: 10 * 60 * 1000 });
+  return {
+    code: result.status ?? 1,
+    output: `$ ${command}\n${result.stdout ?? ''}${result.stderr ?? ''}`,
+  };
+}
+
+function firstFailure(output) {
+  const line = output.split('\n').find(one => /fail|error|expected|assert/i.test(one));
+  return (line ?? 'the run failed').trim().slice(0, 300);
+}
+
+// packages/ai-engineering-gate/src/hookio.mjs
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readHookEvent() {
+  const raw = readStdin().trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function hookAgent(event) {
+  // Codex delivers a shell command at the top level of `beforeShellExecution`, with no tool name, so
+  // the two harnesses converge here rather than in every caller.
+  const shellEvent = typeof event.command === 'string' && !event.tool_name && !event.toolName;
+  return {
+    session: event.session_id ?? event.sessionId ?? event.conversation_id ?? null,
+    agent: event.agent_id ?? event.agentId ?? null,
+    agentType: event.agent_type ?? event.agentType ?? event.subagent_type ?? event.subagentType ?? null,
+    toolUseId: event.tool_use_id ?? event.toolUseId ?? event.call_id ?? null,
+    toolName: event.tool_name ?? event.toolName ?? event.tool ?? (shellEvent ? 'shell' : null),
+    toolInput: event.tool_input ?? event.toolInput ?? (shellEvent ? { command: event.command } : {}),
+    reentrant: event.stop_hook_active === true || event.stopHookActive === true,
+  };
+}
+
+const claudeCode = {
+  sessionContext: text => ({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text },
+  }),
+  toolDeny: reason => ({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  }),
+  stopBlock: reason => ({ decision: 'block', reason }),
+};
+
+// Codex shapes, from its documented output cheat sheet: a permission decision for `preToolUse`,
+// `beforeShellExecution` and `subagentStart`, and a follow-up message for the `stop` and
+// `subagentStop` loops. Codex documents no output field that injects context at `sessionStart`, so the
+// gate answers nothing there and the installer says so rather than pretending the status was delivered.
+const codex = {
+  sessionContext: () => null,
+  toolDeny: reason => ({ permission: 'deny', agent_message: reason, user_message: reason }),
+  stopBlock: reason => ({ followup_message: reason }),
+};
+
+const SHAPES = { 'claude-code': claudeCode, codex };
+
+const shapeOf = harness => SHAPES[harness] ?? claudeCode;
+
+const sessionContext = (text, harness) => shapeOf(harness).sessionContext(text);
+const toolDeny = (reason, harness) => shapeOf(harness).toolDeny(reason);
+const stopBlock = (reason, harness) => shapeOf(harness).stopBlock(reason);
+
+// packages/ai-engineering-gate/src/render.mjs
+// AXI shape: a useful no-argument output, a compact aggregate by default, reasons on request and one
+// `next` line per thing to do. Detail is behind `--full`, automation behind `--json`.
+function renderTable(rows, headers) {
+  if (rows.length === 0) return '';
+  const widths = headers.map((header, column) => Math.max(
+    header.length,
+    ...rows.map(row => String(row[column] ?? '').length),
+  ));
+  const line = cells => cells.map((cell, column) => String(cell ?? '').padEnd(widths[column])).join('  ').trimEnd();
+  return [line(headers), ...rows.map(line)].join('\n');
+}
+
+function renderStatus(context, view, { full = false } = {}) {
+  const lines = [];
+  lines.push(`task ${context.task}  round ${view.rounds.round ?? 0}  gate ${context.version}`);
+  lines.push(renderTable(
+    view.states.map(state => [state.dimension, state.state, describe(state)]),
+    ['dimension', 'state', 'why'],
+  ));
+  const warnings = [...new Set(view.states.flatMap(state => state.warnings))];
+  if (warnings.length > 0) lines.push(`warn: ${warnings.join(', ')}`);
+  for (const next of view.completion.next) lines.push(`next: ${next}`);
+  if (view.completion.complete) lines.push('next: nothing; every registered dimension is complete');
+
+  if (!full) {
+    lines.push(`help: ${context.gateCommand} status --full`);
+    return lines.filter(Boolean).join('\n');
+  }
+
+  for (const state of view.states) {
+    lines.push('');
+    lines.push(`## ${state.dimension} - ${state.state}`);
+    if (state.declaration) {
+      lines.push(`applicability: ${state.declaration.applicability} - ${state.declaration.reason}`);
+      if (state.declaration.scope) lines.push(`scope: ${state.declaration.scope.paths.join(', ')}`);
+    }
+    if (state.records) lines.push(`records: ${state.recordRefs.join(', ')}`);
+    if (state.missingEvidence?.length) lines.push(`missing evidence: ${state.missingEvidence.join(', ')}`);
+    if (state.openFindings?.length) lines.push(`open findings: ${state.openFindings.join(', ')}`);
+    if (state.fingerprints) {
+      lines.push(`fingerprints: source ${short(state.fingerprints.source)} reference ${short(state.fingerprints.reference)} decision ${short(state.fingerprints.decision)}`);
+    }
+    if (state.releasedWindows) lines.push(`released windows: ${state.releasedWindows}`);
+    for (const code of state.codes) lines.push(`code: ${code}`);
+    for (const warning of state.warnings) lines.push(`warn: ${warning}`);
+  }
+  if (view.undeclaredChanges.length > 0) {
+    lines.push('');
+    lines.push('## undeclared changes');
+    for (const path of view.undeclaredChanges) lines.push(`- ${path}`);
+  }
+  if (view.plan?.length) {
+    lines.push('');
+    lines.push('## dispatch plan');
+    lines.push('Launch every reviewer below in one turn, then wait for all filings.');
+    for (const entry of view.plan) {
+      lines.push('');
+      lines.push(`### ${entry.dimension} - agent ${entry.agent}`);
+      lines.push(`state: source ${short(entry.fingerprints.source)} reference ${short(entry.fingerprints.reference)} decision ${short(entry.fingerprints.decision)}`);
+      lines.push(entry.brief);
+    }
+  }
+  return lines.filter(line => line !== null).join('\n');
+}
+
+const short = digest => (digest ?? '').replace('sha256:', '').slice(0, 12);
+
+function describe(state) {
+  if (state.state === 'non-applicable') return state.declaration?.reason ?? '';
+  if (state.codes.length > 0) return state.codes.join(', ');
+  return 'complete';
+}
+
+function statusJson(context, view, extra = {}) {
+  return {
+    outputVersion: '1.0.0',
+    command: extra.command ?? 'status',
+    gateVersion: context.version,
+    marked: true,
+    ok: extra.ok ?? true,
+    task: context.task,
+    repository: context.repoRoot,
+    evidenceRoot: context.evidenceRoot,
+    gateCommand: context.gateCommand,
+    round: view.rounds.round ?? 0,
+    dimensions: view.states.map(state => ({
+      dimension: state.dimension,
+      state: state.state,
+      ...(state.applicability ? { applicability: state.applicability } : {}),
+      records: state.records,
+      codes: state.codes,
+      warnings: state.warnings,
+      missingEvidence: state.missingEvidence,
+      openFindings: state.openFindings,
+      ...(state.fingerprints ? { fingerprints: state.fingerprints } : {}),
+    })),
+    completion: view.completion,
+    warnings: [...new Set(view.states.flatMap(state => state.warnings))],
+    undeclaredChanges: view.undeclaredChanges,
+    ...(view.plan?.length ? { plan: view.plan } : {}),
+    ...extra.payload,
+  };
+}
+
+function silentJson(context, command) {
+  return {
+    outputVersion: '1.0.0',
+    command,
+    gateVersion: context.version,
+    marked: false,
+    ok: true,
+  };
+}
+
+// The gate validates its own JSON against the published output schema, so a drift in the machine
+// surface fails here rather than in a driver.
+function assertOutputShape(context, payload) {
+  const errors = schemaErrors(context.registry.schemas['gate-output'], payload);
+  if (errors.length > 0) throw new Error(`gate output does not match its schema: ${errors.join('; ')}`);
+  return payload;
+}
+
+// packages/ai-engineering-gate/src/main.mjs
+const DOCUMENT_VERBS = new Set([
+  'declare', 'record', 'evidence', 'begin', 'attest', 'report', 'dispute', 'arbitrate', 'replay', 'release',
+]);
+const WRITING_COMMANDS = new Set(['declare', 'record', 'evidence append', 'dispute', 'arbitrate']);
+const EDIT_TOOLS = /^(edit|write|multiedit|multi_edit|notebookedit|notebook_edit|apply_patch|str_replace|create_file)$/i;
+const SHELL_TOOLS = /^(bash|shell|run_terminal_cmd|terminal|exec)$/i;
+const DISPATCH_TOOLS = /^(task|agent|dispatch_agent|subagent)$/i;
+
+const HELP = `ai-engineering-gate - generic enforcement for the transpose/review suite
+
+usage: ai-engineering-gate [command] [options]
+
+With no command it prints the compact status of every registered dimension for this task.
+In a repository that carries no \`.ai-engineering-suite.json\` marker it prints nothing and allows.
+
+commands
+  status                     compact state of every registered dimension, plus the next action
+  declare  --dimension D --stdin    file a declaration before any record
+  record   --dimension D --stdin    file a decision record; refuses a dangling citation
+  evidence append --dimension D --stdin   append a journal event, a check output or a snapshot
+  replay   --dimension D --record R --scenario S --command C   the gate runs and stamps a red/green pair
+  begin    --dimension D     open a review window and freeze the state it binds to
+  attest   --dimension D --stdin    file a SOUND review envelope
+  report   --dimension D --stdin    file a SMELLS or VIOLATIONS review envelope
+  dispute  --dimension D --stdin    contest one finding with a pointer to counter-evidence
+  arbitrate --dimension D --stdin   the user's decision on a dispute; refused from an agent call
+  release  --dimension D     abandon an open review window
+  export                     copy the task's documents into the marker's export directory
+  can-write --path P ...     may this path be edited now
+  can-review --dimension D   may a fresh review of this dimension start now
+  can-stop                   is the task complete; the exit code is the publication lock
+  fingerprint [--dimension D]  the three fingerprints, as the gate computes them
+
+options
+  --json                     stable machine output, versioned and schema-checked
+  --full                     every reason, the missing evidence and the dispatch plan
+  --hook                     read the harness event on stdin and answer in its own shape
+  --harness NAME             the harness the hook wiring runs under
+  --task KEY                 the task key, for a pipeline or a detached head
+  --evidence-root PATH       where the evidence lives; also the export directory in CI
+  --base REF                 the comparison base, for CI verification
+  --from-export              verify exported evidence: gate version and the marker on the base
+
+exit codes
+  0 allowed or valid   2 denied by policy   1 gate or infrastructure failure`;
+
+function parseArguments(argv) {
+  const args = { paths: [], command: null };
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = () => argv[index += 1];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+    switch (token) {
+      case '--json': args.json = true; break;
+      case '--full': args.full = true; break;
+      case '--hook': args.hook = true; break;
+      case '--stdin': args.stdin = true; break;
+      case '--from-export': args.fromExport = true; break;
+      case '--help': args.help = true; break;
+      case '--version': args.version = true; break;
+      case '--dimension': args.dimension = next(); break;
+      case '--harness': args.harness = next(); break;
+      case '--task': args.task = next(); break;
+      case '--evidence-root': args.evidenceRoot = next(); break;
+      case '--record': args.record = next(); break;
+      case '--scenario': args.scenario = next(); break;
+      case '--base': args.base = next(); break;
+      case '--path': args.paths.push(next()); break;
+      case '--command': args.command = next(); break;
+      default: throw new Error(`unknown option ${token}; run --help`);
+    }
+  }
+  args.name = positional.length === 0
+    ? 'status'
+    : (positional[0] === 'evidence' ? positional.slice(0, 2).join(' ') : positional[0]);
+  args.positional = positional;
+  return args;
+}
+
+function documentRefusal(reason) {
+  const error = new Error(reason);
+  error.refusal = refuse('invalid-document', reason);
+  throw error;
+}
+
+function readDocument(args) {
+  const raw = readStdin();
+  if (!raw.trim()) {
+    documentRefusal(`${args.name} reads its document on stdin; pipe it and pass --stdin`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    documentRefusal(`the document on stdin is not JSON: ${error.message}`);
+  }
+}
+
+function requireDimensionFlag(args) {
+  if (!args.dimension) throw new Error(`${args.name} needs --dimension <identifier>`);
+}
+
+function runCommand(context, args) {
+  switch (args.name) {
+    case 'status': return commandStatus(context);
+    case 'can-stop': {
+      const result = commandCanStop(context);
+      if (!args.fromExport) return result;
+      return applyExportVerification(context, result, args.base);
+    }
+    case 'can-write': return commandCanWrite(context, args);
+    case 'can-review': return commandCanReview(context, args);
+    case 'fingerprint': return commandFingerprint(context, args);
+    case 'declare': requireDimensionFlag(args); return commandDeclare(context, args, readDocument(args));
+    case 'record': requireDimensionFlag(args); return commandRecord(context, args, readDocument(args));
+    case 'evidence append': requireDimensionFlag(args); return commandEvidenceAppend(context, args, readDocument(args));
+    case 'dispute': requireDimensionFlag(args); return commandDispute(context, args, readDocument(args));
+    case 'arbitrate': requireDimensionFlag(args); return commandArbitrate(context, args, readDocument(args));
+    case 'begin': requireDimensionFlag(args); return commandBegin(context, args);
+    case 'attest': requireDimensionFlag(args); return commandAttest(context, args, readDocument(args));
+    case 'report': requireDimensionFlag(args); return commandReport(context, args, readDocument(args));
+    case 'release': return commandRelease(context, args);
+    case 'replay': requireDimensionFlag(args); return commandReplay(context, args);
+    case 'export': return commandExport(context);
+    default: throw new Error(`unknown command ${args.name}; run --help`);
+  }
+}
+
+function render(context, args, result) {
+  if (args.json) {
+    const view = result.view ?? suiteView(context);
+    return JSON.stringify(assertOutputShape(context, statusJson(context, view, {
+      command: args.name,
+      ok: result.ok,
+      payload: {
+        ...(result.code ? { refusal: { code: result.code, reason: result.reason, ...(result.cause ? { cause: result.cause } : {}), ...(result.details?.length ? { details: result.details } : {}) } } : {}),
+        ...(result.payload?.document ? { document: result.payload.document } : {}),
+      },
+    })), null, 2);
+  }
+  if (!result.ok) {
+    const refusal = refusalText(result);
+    return result.view ? `${refusal}\n\n${renderStatus(context, result.view, { full: args.full })}` : refusal;
+  }
+  if (result.text) {
+    const warnings = [...new Set(result.payload?.warnings ?? [])];
+    return [result.text, ...(warnings.length > 0 ? [`warn: ${warnings.join(', ')}`] : [])].join('\n');
+  }
+  return renderStatus(context, result.view, { full: args.full });
+}
+
+function refusalText(result) {
+  const lines = [`refused: ${result.code}`, `reason: ${result.reason}`];
+  if (result.cause) lines.push(`cause: ${result.cause}`);
+  for (const detail of result.details ?? []) lines.push(`- ${detail}`);
+  return lines.join('\n');
+}
+
+// A hook answers on stdout in the event's own shape and exits 0. In a marked repository a failure of
+// the gate itself exits 2 with the failure as its reason, which both harnesses treat as blocking; a
+// failure is never an approval.
+function runHook(context, args) {
+  const event = readHookEvent();
+  const agent = hookAgent(event);
+  const harness = context.harness;
+  if (args.name === 'status') {
+    const view = suiteView(context);
+    const text = renderStatus(context, view, { full: false });
+    const answer = sessionContext(`Engineering suite gate: ${context.gateCommand}\n${text}`, harness);
+    return { ...(answer ? { stdout: JSON.stringify(answer) } : {}), exitCode: 0 };
+  }
+  if (args.name === 'can-write') {
+    if (DISPATCH_TOOLS.test(agent.toolName ?? '')) return { exitCode: 0 };
+    const paths = EDIT_TOOLS.test(agent.toolName ?? '') ? editedPaths(agent.toolInput) : [];
+    const command = SHELL_TOOLS.test(agent.toolName ?? '') ? shellCommand(agent.toolInput) : null;
+    if (command) noteHandoff(context, agent, command);
+    if (paths.length === 0 && !command) return { exitCode: 0 };
+    const result = commandCanWrite(context, { ...args, paths, command });
+    if (result.ok) return { exitCode: 0 };
+    return { stdout: JSON.stringify(toolDeny(refusalText(result), harness)), exitCode: 0 };
+  }
+  if (args.name === 'can-review') {
+    const reviewer = reviewerFor(context, agent.toolInput);
+    if (!reviewer) return { exitCode: 0 };
+    const result = commandCanReview(context, { ...args, dimension: reviewer });
+    if (result.ok) return { exitCode: 0 };
+    return { stdout: JSON.stringify(toolDeny(refusalText(result), harness)), exitCode: 0 };
+  }
+  if (args.name === 'can-stop') {
+    const result = commandCanStopHook(context, agent.reentrant);
+    if (result.ok) return { exitCode: 0 };
+    // Keep Stop compact. A full status leaks the reviewer brief into the builder conversation.
+    return { stdout: JSON.stringify(stopBlock(renderStatus(context, result.view, { full: false }), harness)), exitCode: 0 };
+  }
+  if (args.name === 'fingerprint') {
+    return { exitCode: 0 };
+  }
+  if (args.name === 'release') {
+    const reviewer = reviewerFor(context, { subagent_type: agent.agentType }) ?? args.dimension;
+    if (!reviewer) return { exitCode: 0 };
+    commandRelease(context, { ...args, dimension: reviewer });
+    return { exitCode: 0 };
+  }
+  throw new Error(`${args.name} has no hook form`);
+}
+
+// The agent identifier and agent type exist only in hook input inside a subagent call, so the hook
+// records them for the gate command that call is about to run.
+function noteHandoff(context, agent, command) {
+  if (!command.includes('ai-engineering-gate')) return;
+  const verb = /ai-engineering-gate(?:\.mjs)?["']?\s+(\S+)/.exec(command)?.[1];
+  if (!verb || !DOCUMENT_VERBS.has(verb)) return;
+  const dimension = /--dimension\s+([A-Za-z0-9-]+)/.exec(command)?.[1] ?? null;
+  recordHandoff(context, {
+    session: agent.session,
+    verb: verb === 'evidence' ? 'evidence' : verb,
+    dimension,
+    agent: agent.agent,
+    agentType: agent.agentType,
+    toolUseId: agent.toolUseId,
+    command,
+  });
+}
+
+function reviewerFor(context, toolInput) {
+  const type = toolInput?.subagent_type ?? toolInput?.agent_type ?? toolInput?.agentType ?? null;
+  if (!type) return null;
+  const member = context.members.find(one => memberAgentType(one) === type);
+  return member?.dimension ?? null;
+}
+
+function main(argv) {
+  let args;
+  try {
+    args = parseArguments(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+  if (args.help || args.name === 'help') {
+    process.stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  let context;
+  try {
+    context = buildContext({
+      harness: args.harness,
+      task: args.task,
+      evidenceRoot: args.evidenceRoot,
+      fromExport: args.fromExport,
+    });
+  } catch (error) {
+    process.stderr.write(`gate-failure: ${error.message}\n`);
+    return args.hook ? 2 : 1;
+  }
+  if (args.version) {
+    process.stdout.write(`${context.version}\n`);
+    return 0;
+  }
+  // Silence outside a marked repository, even on failure, so installing the hooks once for every
+  // project costs nothing elsewhere.
+  if (!context.marked) {
+    if (args.json) process.stdout.write(`${JSON.stringify(silentJson(context, args.name), null, 2)}\n`);
+    return 0;
+  }
+  if (args.hook) {
+    try {
+      const answer = runHook(context, args);
+      if (answer.stdout) process.stdout.write(`${answer.stdout}\n`);
+      return answer.exitCode;
+    } catch (error) {
+      process.stderr.write(`gate-failure: ${error.message}\n`);
+      return 2;
+    }
+  }
+  try {
+    const result = runCommand(context, args);
+    const text = render(context, args, result);
+    if (text) process.stdout.write(`${text}\n`);
+    return result.ok ? 0 : 2;
+  } catch (error) {
+    if (error.refusal) {
+      const text = render(context, args, error.refusal);
+      if (text) process.stdout.write(`${text}\n`);
+      return 2;
+    }
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({
+        outputVersion: '1.0.0',
+        command: args.name,
+        gateVersion: context.version,
+        marked: true,
+        ok: false,
+        completion: { complete: false, codes: ['gate-failure'] },
+        error: error.message,
+      }, null, 2)}\n`);
+    } else {
+      process.stderr.write(`gate-failure: ${error.message}\n`);
+    }
+    return 1;
+  }
+}
+
+function invokedAsCli() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsCli()) process.exitCode = main(process.argv.slice(2));
+
+export { main };
+