instar 1.3.734 → 1.3.735

package/scripts/class-closure-declare.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * class-closure-declare — the AUTHOR's declaration helper for the Class-Closure
+ * Gate (docs/specs/class-closure-gate.md → Piece 1 host). It merges a
+ * `classClosure` block into the MOST-RECENT committed decision-audit entry
+ * (`.instar/instar-dev-decisions/<ts>-<slug>.json`) — the machine-readable host
+ * the gate lint validates.
+ *
+ * Self-contained ESM (no build step), idempotent (re-running with the same block
+ * is a no-op). The block is supplied EITHER as a whole JSON string via
+ * `--json '{"defectClass":"...","closure":"guard",...}'`, OR assembled from flags:
+ *
+ *   node scripts/class-closure-declare.mjs \
+ *     --class injection-credulity --closure guard \
+ *     --citation src/core/promptClauses.ts#authorityClause \
+ *     --enforcement gate --how-caught "the authority clause separates ..." \
+ *     --pr 1290 --component CoherenceReviewer
+ *
+ * For a gap: `--closure gap --gap-item ACT-1234`.
+ * For a novel class: `--class novel --novel-json '{"nearestExistingClass":"...","includes":[...],"excludes":[...],"severity":"normal"}'`.
+ *
+ * It only WRITES the review host; it does not touch the registry or grade the
+ * guard (the lint does the grading). Prints the merged block to stdout.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DECISIONS_REL = path.join('.instar', 'instar-dev-decisions');
+
+/** Parse `--key value` / `--flag` pairs into a plain object. */
+export function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a classClosure block from parsed args. Throws on a structurally-invalid
+ * request (so a bad declaration is caught at author time, not just at lint time).
+ * @returns {object} the classClosure block.
+ */
+export function buildClassClosureBlock(args) {
+  if (args.json) {
+    let parsed;
+    try {
+      parsed = JSON.parse(args.json);
+    } catch (err) {
+      throw new Error(`--json is not valid JSON: ${err && err.message ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== 'object') throw new Error('--json must be an object');
+    return normalizeBlock(parsed);
+  }
+
+  const block = {};
+  if (!args.class || typeof args.class !== 'string') throw new Error('--class <id|novel> is required');
+  block.defectClass = args.class;
+  const closure = args.closure;
+  if (closure !== 'guard' && closure !== 'gap') throw new Error("--closure must be 'guard' or 'gap'");
+  block.closure = closure;
+
+  if (closure === 'guard') {
+    if (!args.citation || typeof args.citation !== 'string') throw new Error("closure 'guard' requires --citation <path|route|symbol>");
+    block.guardEvidence = {
+      enforcementType: typeof args.enforcement === 'string' ? args.enforcement : undefined,
+      citation: args.citation,
+      howCaught: typeof args['how-caught'] === 'string' ? args['how-caught'] : undefined,
+    };
+  } else {
+    if (!args['gap-item'] || typeof args['gap-item'] !== 'string') throw new Error("closure 'gap' requires --gap-item <evolution-action-id>");
+    block.gapItem = args['gap-item'];
+  }
+
+  if (args.pr !== undefined) {
+    const n = Number(args.pr);
+    if (!Number.isFinite(n)) throw new Error('--pr must be a number');
+    block.prNumber = n;
+  }
+  if (typeof args.component === 'string') block.component = args.component;
+
+  if (args.class === 'novel') {
+    if (!args['novel-json']) throw new Error("--class novel requires --novel-json '{...}' with full class semantics");
+    let nc;
+    try {
+      nc = JSON.parse(args['novel-json']);
+    } catch (err) {
+      throw new Error(`--novel-json is not valid JSON: ${err && err.message ? err.message : String(err)}`);
+    }
+    if (!nc || typeof nc !== 'object' || !nc.nearestExistingClass) {
+      throw new Error('--novel-json must carry nearestExistingClass (+ includes/excludes/severity)');
+    }
+    block.novelClass = nc;
+  }
+
+  return normalizeBlock(block);
+}
+
+/** Strip undefined leaves so the written block is minimal + idempotent-comparable. */
+function normalizeBlock(block) {
+  const out = {};
+  for (const [k, v] of Object.entries(block)) {
+    if (v === undefined) continue;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out[k] = normalizeBlock(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/** Find the most-recent decision-audit entry file (by ts field, else filename). */
+export function findMostRecentDecisionEntry(repoRoot) {
+  const dir = path.join(repoRoot, DECISIONS_REL);
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return null;
+  }
+  if (files.length === 0) return null;
+  let best = null;
+  for (const f of files) {
+    let entry;
+    try {
+      entry = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+    } catch {
+      continue;
+    }
+    const tsKey = typeof entry.ts === 'string' ? entry.ts : f;
+    if (best === null || tsKey > best.tsKey || (tsKey === best.tsKey && f > best.file)) {
+      best = { file: f, entry, tsKey };
+    }
+  }
+  return best ? { file: path.join(dir, best.file), entry: best.entry } : null;
+}
+
+/**
+ * Merge the block into the most-recent entry + write it back. Idempotent — a
+ * re-run with an identical block returns { changed: false }.
+ * @returns {{ changed: boolean, file: string, block: object }}
+ */
+export function applyDeclaration(repoRoot, block) {
+  const target = findMostRecentDecisionEntry(repoRoot);
+  if (!target) {
+    throw new Error(`no decision-audit entry found under ${DECISIONS_REL} to attach the declaration to`);
+  }
+  const before = JSON.stringify(target.entry.classClosure ?? null);
+  const after = JSON.stringify(block);
+  if (before === after) {
+    return { changed: false, file: target.file, block };
+  }
+  target.entry.classClosure = block;
+  fs.writeFileSync(target.file, `${JSON.stringify(target.entry, null, 2)}\n`, 'utf-8');
+  return { changed: true, file: target.file, block };
+}
+
+// ── CLI entrypoint ──────────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
+if (invokedDirectly) {
+  const repoRoot = process.env.CLASS_CLOSURE_REPO_ROOT || process.cwd();
+  const args = parseArgs(process.argv.slice(2));
+  let block;
+  try {
+    block = buildClassClosureBlock(args);
+  } catch (err) {
+    console.error(`class-closure-declare: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+  let result;
+  try {
+    result = applyDeclaration(repoRoot, block);
+  } catch (err) {
+    console.error(`class-closure-declare: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+  console.log(`class-closure-declare: ${result.changed ? 'wrote' : 'no change (idempotent)'} classClosure into ${path.relative(repoRoot, result.file)}`);
+  console.log(JSON.stringify(result.block, null, 2));
+  process.exit(0);
+}

package/scripts/class-closure-lint.mjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// safe-git-allow: CI-only gate script — single read-only `git diff --name-status`
+//   against the Actions checkout; runs on ubuntu runners where the TS
+//   SafeGitExecutor is not importable from a standalone .mjs.
+/**
+ * class-closure-lint — the REPORT-ONLY CI lint for the Class-Closure Gate
+ * (docs/specs/class-closure-gate.md → Rollout step 1). Increment 1.
+ *
+ * A fix for a defect found in an AGENT-AUTHORED artifact (prompts, hooks,
+ * configs, skills, standards text) is supposed to declare, in its committed
+ * instar-dev decision-audit entry, WHAT CLASS of defect it is an instance of
+ * and HOW the class is closed (a live guard, or a tracked gap). This lint
+ * VALIDATES those declarations at the PR boundary — it does NOT mutate source
+ * (the periodic escalator pass owns mutation) and, in report-only mode (the
+ * increment-1 default), it prints findings and ALWAYS exits 0.
+ *
+ * What it does (all report-only unless enabled && !dryRun):
+ *   - repo-gate: no docs/defect-classes.json ⇒ "not an instar class-closure
+ *     repo", exit 0.
+ *   - load + validate the class registry (a malformed registry is a HARD
+ *     structural violation).
+ *   - read every classClosure declaration from committed decision-audit entries
+ *     (the SINGLE machine-readable counting host — C1: the side-effects mirror
+ *     is display-only and NOT summed here).
+ *   - grade each `closure:'guard'` citation via the self-contained grader
+ *     (evaluateGuardClosure) — a citation that does not resolve to a live
+ *     enforcing guard DOWNGRADES the declaration to `gap` (G3), logged.
+ *   - validate `defectClass:'novel'`: it must carry a full new class entry with
+ *     nearestExistingClass + includes/excludes/severity (a novel class with no
+ *     semantics is a HARD structural violation); a novel class enters
+ *     `unconfirmed` and CANNOT satisfy `closure:'guard'` (logged downgrade).
+ *   - derive per-class counts (deduped by PR) + compute deterministic escalation
+ *     crossings — LOGGED only (proposals/attention items are increment 3).
+ *   - assert mirror-consistency is trivially satisfiable (the side-effects mirror
+ *     is display-only; hosts are never summed).
+ *   - for an in-scope PR with NO declaration, LOG "missing class declaration
+ *     (report-only)" (the flip criterion measures population rate during dryRun).
+ *
+ * Exit codes: 0 in report-only ALWAYS. Nonzero ONLY when
+ * `prGate.classClosure.enabled && !dryRun` AND a hard structural violation exists
+ * (malformed registry, or a novel class with no semantics).
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  loadRegistry,
+  validateRegistry,
+  readDecisionDeclarations,
+  deriveClassData,
+  computeEscalation,
+  REGISTRY_REL_PATH,
+} from './lib/defect-class-registry.mjs';
+import { evaluateGuardClosure } from './lib/class-closure-grader.mjs';
+
+const DEFAULT_CONFIG = { enabled: false, dryRun: true, escalatorDrafting: false };
+
+/**
+ * The agent-authored-artifact predicate — a fix touching one of these is
+ * IN SCOPE for the class declaration (docs/specs/class-closure-gate.md →
+ * Frontloaded Decision 1: prompts, hooks, configs, skills, standards text).
+ */
+export function isAgentAuthoredArtifact(file) {
+  const f = String(file ?? '');
+  if (/^research\/llm-pathway-bench\/.*\/tasks\//.test(f)) return true;
+  if (f === 'src/core/promptClauses.ts') return true;
+  if (f.startsWith('src/core/promptParsers')) return true;
+  if (f === 'src/data/llmBenchCoverage.ts') return true;
+  if (f === 'docs/STANDARDS-REGISTRY.md') return true;
+  if (f.startsWith('.instar/hooks/')) return true;
+  if (f.startsWith('.claude/hooks/')) return true;
+  if (f.startsWith('skills/')) return true;
+  return false;
+}
+
+/**
+ * The gate's OWN source files — for the bounded, gate-source-ONLY self-wedge
+ * exemption (spec: a broken gate can never block its own repair; the exemption
+ * applies only when the diff touches EXCLUSIVELY these files).
+ */
+export function isGateSourceFile(file) {
+  const f = String(file ?? '');
+  return (
+    f === 'scripts/class-closure-lint.mjs' ||
+    f === 'scripts/class-closure-declare.mjs' ||
+    f === 'scripts/lib/class-closure-grader.mjs' ||
+    f === 'scripts/lib/defect-class-registry.mjs' ||
+    f === 'src/core/DefectClassRegistry.ts' ||
+    f === REGISTRY_REL_PATH ||
+    f === 'docs/defect-classes.json' ||
+    f === '.github/workflows/class-closure-gate.yml' ||
+    f === 'docs/specs/class-closure-gate.md' ||
+    /^tests\/(unit|integration)\/class-closure-/.test(f)
+  );
+}
+
+/** Load prGate.classClosure config from a repo checkout, or the report-only default. */
+export function loadClassClosureConfig(repoRoot) {
+  try {
+    const raw = fs.readFileSync(path.join(repoRoot, '.instar', 'config.json'), 'utf-8');
+    const cfg = JSON.parse(raw);
+    const cc = cfg && cfg.prGate && cfg.prGate.classClosure;
+    if (cc && typeof cc === 'object') {
+      return {
+        enabled: cc.enabled === true,
+        dryRun: cc.dryRun !== false, // default true (report-only) unless explicitly false
+        escalatorDrafting: cc.escalatorDrafting === true,
+      };
+    }
+  } catch {
+    // no config / unreadable → report-only default
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/** Validate one classClosure declaration's shape. Returns { findings, hardViolations }. */
+function validateDeclaration(repoRoot, decl, knownClassIds) {
+  const findings = [];
+  const hardViolations = [];
+  const where = `declaration in ${decl.source ?? '<unknown>'} (class="${decl.defectClass ?? '?'}")`;
+
+  if (!decl.defectClass || typeof decl.defectClass !== 'string') {
+    findings.push(`${where}: missing defectClass`);
+    return { findings, hardViolations };
+  }
+
+  const isNovel = decl.defectClass === 'novel';
+  if (!isNovel && !knownClassIds.has(decl.defectClass)) {
+    findings.push(`${where}: defectClass "${decl.defectClass}" is not a registered class id and is not 'novel'`);
+  }
+
+  if (decl.closure !== 'guard' && decl.closure !== 'gap') {
+    findings.push(`${where}: closure must be 'guard' or 'gap' (got "${decl.closure}")`);
+  }
+
+  // Novel class: REQUIRES full semantics (a hard violation if absent).
+  if (isNovel) {
+    const nc = decl.novelClass;
+    const missing = [];
+    if (!nc || typeof nc !== 'object') {
+      missing.push('novelClass block');
+    } else {
+      if (!nc.nearestExistingClass || typeof nc.nearestExistingClass !== 'string') missing.push('nearestExistingClass');
+      if (!Array.isArray(nc.includes) || nc.includes.length < 1) missing.push('≥1 includes');
+      if (!Array.isArray(nc.excludes) || nc.excludes.length < 1) missing.push('≥1 excludes');
+      if (nc.severity !== 'critical' && nc.severity !== 'normal') missing.push('severity (critical|normal)');
+    }
+    if (missing.length > 0) {
+      hardViolations.push(`${where}: novel class with no semantics — missing ${missing.join(', ')}`);
+    }
+    // A novel class enters `unconfirmed` and CANNOT satisfy closure:'guard'.
+    if (decl.closure === 'guard') {
+      findings.push(`${where}: a novel (unconfirmed) class cannot satisfy closure:'guard' — its fix carries closure:'gap' until operator-confirmed`);
+    }
+  }
+
+  // Guard closure: grade the citation (downgrade to gap if it does not resolve).
+  if (decl.closure === 'guard') {
+    const citation = decl.guardEvidence && decl.guardEvidence.citation;
+    if (!citation || typeof citation !== 'string') {
+      findings.push(`${where}: closure:'guard' requires guardEvidence.citation`);
+    } else {
+      const verdict = evaluateGuardClosure(repoRoot, citation);
+      if (verdict.effectiveClosure === 'gap') {
+        findings.push(`${where}: DOWNGRADE guard→gap — ${verdict.downgradeReason}`);
+      } else {
+        findings.push(`${where}: guard citation resolves (${verdict.gradedKind}) — closure:'guard' upheld`);
+      }
+    }
+  } else if (decl.closure === 'gap') {
+    if (!decl.gapItem || typeof decl.gapItem !== 'string') {
+      findings.push(`${where}: closure:'gap' should cite a tracked gap item (gapItem) — none provided`);
+    }
+  }
+
+  return { findings, hardViolations };
+}
+
+/**
+ * Pure evaluation over a prepared repo checkout — exported for tests.
+ * @param {{ repoRoot: string, changedFiles?: string[]|null, config: {enabled:boolean,dryRun:boolean,escalatorDrafting:boolean}, thresholds?: object }} input
+ * @returns {{ exitCode: number, repoGated?: boolean, findings: string[], hardViolations: string[], escalations: object[], inScope: boolean, exempt?: string, declarationCount: number }}
+ */
+export function runClassClosureLint(input) {
+  const { repoRoot, config } = input;
+  const thresholds = input.thresholds ?? {};
+  const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : null;
+  const findings = [];
+  const hardViolations = [];
+  const escalations = [];
+
+  // Repo-gate: no registry ⇒ not an instar class-closure repo.
+  if (!fs.existsSync(path.join(repoRoot, REGISTRY_REL_PATH))) {
+    return { exitCode: 0, repoGated: true, findings, hardViolations, escalations, inScope: false, declarationCount: 0 };
+  }
+
+  // Load + validate the registry (malformed = hard structural violation).
+  let registry = null;
+  const rawParse = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(repoRoot, REGISTRY_REL_PATH), 'utf-8'));
+    } catch (err) {
+      return { __parseError: err && err.message ? err.message : String(err) };
+    }
+  })();
+  if (rawParse && rawParse.__parseError) {
+    hardViolations.push(`registry unparseable: ${rawParse.__parseError}`);
+  } else {
+    const v = validateRegistry(rawParse);
+    if (!v.ok) {
+      hardViolations.push(`malformed registry: ${v.errors.join('; ')}`);
+    } else {
+      registry = rawParse;
+    }
+  }
+
+  // Read + grade declarations from the decision-audit host.
+  const declarations = readDecisionDeclarations(repoRoot);
+  const knownClassIds = new Set(registry ? registry.classes.map((c) => c.id) : []);
+  for (const decl of declarations) {
+    const r = validateDeclaration(repoRoot, decl, knownClassIds);
+    findings.push(...r.findings);
+    hardViolations.push(...r.hardViolations);
+  }
+
+  // Derive per-class counts + compute deterministic escalation crossings (LOG only).
+  if (registry) {
+    const derived = deriveClassData(declarations);
+    for (const cls of registry.classes) {
+      const d = derived.get(cls.id);
+      if (!d) continue;
+      const verdict = computeEscalation(
+        { severity: cls.severity, evidenceCountAtLastAck: cls.evidenceCountAtLastAck },
+        d,
+        thresholds,
+      );
+      if (verdict.shouldEscalate) {
+        escalations.push({ classId: cls.id, arm: verdict.arm, reason: verdict.reason, derivedCount: d.dedupedCount });
+        findings.push(`ESCALATION (report-only): class "${cls.id}" crossed threshold [${verdict.arm}] — ${verdict.reason}`);
+      }
+    }
+    // Mirror-consistency: the side-effects artifact mirror is DISPLAY-ONLY; the
+    // lint never sums the two hosts (C1). This invariant is satisfied by
+    // construction here — we counted the decision-audit host only.
+    findings.push('mirror-consistency: counted the decision-audit host only (side-effects mirror is display-only) — trivially satisfied');
+  }
+
+  // Diff-scope: does this PR touch an agent-authored artifact needing a declaration?
+  let inScope = false;
+  let exempt;
+  if (changedFiles && changedFiles.length > 0) {
+    const agentFiles = changedFiles.filter(isAgentAuthoredArtifact);
+    inScope = agentFiles.length > 0;
+    if (inScope) {
+      // Gate-source-ONLY self-wedge exemption: applies ONLY when the diff
+      // touches EXCLUSIVELY the gate's own source (a mixed PR cannot ride it).
+      const allGateSource = changedFiles.every(isGateSourceFile);
+      if (allGateSource) {
+        exempt = 'gate-source-only';
+        findings.push('exempt: diff touches EXCLUSIVELY the gate\'s own source (gate-source-only self-wedge exemption, logged)');
+      } else if (declarations.length === 0) {
+        findings.push('missing class declaration (report-only) — this PR touches agent-authored artifacts but carries no classClosure declaration');
+      }
+    }
+  }
+
+  // Exit code: report-only ALWAYS exits 0. Nonzero ONLY when enforcing AND a
+  // hard structural violation exists.
+  const enforcing = config.enabled && !config.dryRun;
+  const exitCode = enforcing && hardViolations.length > 0 ? 1 : 0;
+
+  return {
+    exitCode,
+    findings,
+    hardViolations,
+    escalations,
+    inScope,
+    exempt,
+    declarationCount: declarations.length,
+  };
+}
+
+/** Parse `git diff --name-status base...head` output into changed file paths. */
+export function parseNameStatus(text) {
+  const files = [];
+  for (const line of String(text).split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    const parts = t.split('\t');
+    if (parts.length < 2) continue;
+    files.push(parts[parts.length - 1]); // renames: take the new path
+  }
+  return files;
+}
+
+// ── CLI entrypoint (CI) ────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
+if (invokedDirectly) {
+  const repoRoot = process.env.CLASS_CLOSURE_REPO_ROOT || process.cwd();
+
+  // Repo-gate first (before anything else).
+  if (!fs.existsSync(path.join(repoRoot, REGISTRY_REL_PATH))) {
+    console.log('class-closure gate: not an instar class-closure repo (no docs/defect-classes.json) — skipping.');
+    process.exit(0);
+  }
+
+  const config = loadClassClosureConfig(repoRoot);
+
+  // Compute changed files from git when the PR SHAs are present; otherwise run
+  // scope-blind (still grades all committed declarations — the count host).
+  let changedFiles = null;
+  const baseSha = process.env.BASE_SHA;
+  const headSha = process.env.HEAD_SHA;
+  if (baseSha && headSha) {
+    try {
+      const diffOut = execFileSync('git', ['diff', '--name-status', `${baseSha}...${headSha}`], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+      });
+      changedFiles = parseNameStatus(diffOut);
+    } catch (err) {
+      console.warn(`class-closure gate: git diff failed (${err instanceof Error ? err.message : String(err)}) — running scope-blind.`);
+      changedFiles = null;
+    }
+  }
+
+  const res = runClassClosureLint({ repoRoot, changedFiles, config });
+
+  console.log('class-closure gate: report-only lint');
+  console.log(`  mode: ${config.enabled ? (config.dryRun ? 'enabled+dryRun (report-only)' : 'ENFORCING') : 'disabled (report-only)'}`);
+  console.log(`  declarations scanned: ${res.declarationCount}`);
+  if (changedFiles) console.log(`  changed files: ${changedFiles.length} (in-scope: ${res.inScope}${res.exempt ? `, exempt: ${res.exempt}` : ''})`);
+  for (const f of res.findings) console.log(`  - ${f}`);
+  if (res.hardViolations.length > 0) {
+    console.log('  HARD STRUCTURAL VIOLATIONS:');
+    for (const h of res.hardViolations) console.log(`    ! ${h}`);
+  }
+  if (res.exitCode !== 0) {
+    console.error('class-closure gate: FAIL (enforcing mode + hard structural violation)');
+  } else {
+    console.log('class-closure gate: OK (report-only — no build failure)');
+  }
+  process.exit(res.exitCode);
+}

package/scripts/lib/class-closure-grader.mjs

@@ -0,0 +1,139 @@
+// class-closure-grader.mjs — the SELF-CONTAINED deterministic guard grader used
+// by the class-closure gate's CI lint (scripts/class-closure-lint.mjs).
+//
+// WHY self-contained: PR-gate lints run on a fresh checkout with NO build step
+// (decision-audit-gate.yml precedent), so the lint cannot import the TS grader
+// from dist/. This mirrors the EXACT classification rules of
+// src/core/StandardsEnforcementAuditor.ts::classifyFileGuard/gradeGuardCitation;
+// tests/unit/class-closure-grader-parity.test.ts pins the two implementations
+// equivalent so they cannot drift (Structure > Willpower).
+//
+// The spec's rule (docs/specs/class-closure-gate.md → Piece 1 guardEvidence):
+// a citation that does not RESOLVE to a live enforcing guard — resolved:false,
+// or a resolved kind of `spec-only` — downgrades the closure declaration to
+// `gap` (G3: a dark/spec-only artifact guards nothing). Only ratchet/gate/lint
+// count as a live enforcing guard. Grader erroring ⇒ downgrade to gap
+// (fail-closed).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Classify a VERIFIED file ref into its guard weight (mirror of classifyFileGuard). */
+export function classifyFileGuard(ref) {
+  const base = ref.split('/').pop() ?? ref;
+  if (/\.test\.(ts|js|mjs)$/.test(base) || base.startsWith('no-') || /-coverage\.(mjs|js)$/.test(base)) {
+    return 'ratchet';
+  }
+  if (ref.startsWith('scripts/') && base.startsWith('lint-')) return 'lint';
+  if (ref.startsWith('.husky/') || /precommit/i.test(base)) return 'gate';
+  if (ref.startsWith('scripts/')) return 'lint';
+  if (ref.startsWith('docs/specs/')) return 'spec-only';
+  if (ref.startsWith('docs/')) return 'spec-only';
+  if (ref.startsWith('src/')) return 'gate';
+  return 'spec-only';
+}
+
+/** Scan src/server/*.ts for router.<verb>('...') tokens (mirror of loadRouteTable). */
+function loadRouteTable(projectDir) {
+  const serverDir = path.join(projectDir, 'src', 'server');
+  const out = new Set();
+  let files;
+  try {
+    files = fs.readdirSync(serverDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'));
+  } catch {
+    return out;
+  }
+  const re = /router\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]/g;
+  for (const f of files) {
+    let content;
+    try { content = fs.readFileSync(path.join(serverDir, f), 'utf-8'); } catch { continue; }
+    for (const m of content.matchAll(re)) out.add(`${m[1].toUpperCase()} ${m[2]}`);
+  }
+  return out;
+}
+
+/** Bounded grep for a single symbol across src/** (mirror of buildSymbolIndex, size 1). */
+function symbolExists(projectDir, symbol) {
+  const srcDir = path.join(projectDir, 'src');
+  try { if (!fs.statSync(srcDir).isDirectory()) return false; } catch { return false; }
+  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`\\b${escaped}\\b`);
+  const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+  let readBytes = 0;
+  let found = false;
+  const walk = (dir) => {
+    if (found) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (found) return;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+        walk(full);
+      } else if (/\.(ts|js|mjs|cjs)$/.test(e.name)) {
+        if (readBytes > MAX_TOTAL_BYTES) return;
+        let content;
+        try { content = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+        readBytes += content.length;
+        if (re.test(content)) { found = true; return; }
+      }
+    }
+  };
+  walk(srcDir);
+  return found;
+}
+
+/**
+ * Grade a single guard citation against a repo checkout. Mirror of
+ * StandardsEnforcementAuditor.gradeGuardCitation.
+ * @returns {{ resolved: boolean, kind: string|null, citation: string }}
+ */
+export function gradeGuardCitation(projectDir, citation) {
+  const raw = (citation ?? '').trim();
+  if (!raw) return { resolved: false, kind: null, citation: raw };
+
+  const routeMatch = /^(GET|POST|PUT|DELETE|PATCH)\s+(\/\S+)$/i.exec(raw);
+  if (routeMatch) {
+    const token = `${routeMatch[1].toUpperCase()} ${routeMatch[2]}`;
+    const resolved = loadRouteTable(projectDir).has(token);
+    return { resolved, kind: resolved ? 'gate' : null, citation: raw };
+  }
+
+  if (raw.includes('/')) {
+    const filePart = raw.split('#')[0].split(':')[0];
+    let resolved = false;
+    try { resolved = fs.existsSync(path.join(projectDir, filePart)); } catch { resolved = false; }
+    return { resolved, kind: resolved ? classifyFileGuard(filePart) : null, citation: raw };
+  }
+
+  const resolved = symbolExists(projectDir, raw);
+  return { resolved, kind: resolved ? 'gate' : null, citation: raw };
+}
+
+/**
+ * The closure verdict for a `guard` declaration: does the cited guard actually
+ * enforce (ratchet/gate/lint + resolved)? Otherwise the declaration downgrades
+ * to `gap`. Any thrown error ⇒ downgrade to gap (fail-closed).
+ * @returns {{ effectiveClosure: 'guard'|'gap', gradedKind: string|null, resolved: boolean, downgradeReason: string|null }}
+ */
+export function evaluateGuardClosure(projectDir, citation) {
+  try {
+    const g = gradeGuardCitation(projectDir, citation);
+    const enforcing = g.resolved && (g.kind === 'ratchet' || g.kind === 'gate' || g.kind === 'lint');
+    if (enforcing) {
+      return { effectiveClosure: 'guard', gradedKind: g.kind, resolved: true, downgradeReason: null };
+    }
+    const reason = !g.resolved
+      ? `guard citation "${citation}" does not resolve to a live guard on disk`
+      : `guard citation "${citation}" graded ${g.kind} — not a live enforcing guard (ratchet/gate/lint required)`;
+    return { effectiveClosure: 'gap', gradedKind: g.kind, resolved: g.resolved, downgradeReason: reason };
+  } catch (err) {
+    return {
+      effectiveClosure: 'gap',
+      gradedKind: null,
+      resolved: false,
+      downgradeReason: `grader error (fail-closed): ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+}