instar 1.3.734 → 1.3.735

package/scripts/lib/defect-class-registry.mjs

@@ -0,0 +1,236 @@
+// defect-class-registry.mjs — the SELF-CONTAINED ESM mirror of the pure
+// registry/derive/threshold logic in src/core/DefectClassRegistry.ts, used by
+// the class-closure gate's CI lint (scripts/class-closure-lint.mjs).
+//
+// WHY a mirror: PR-gate lints run on a fresh checkout with NO build step
+// (decision-audit-gate.yml precedent), so the lint cannot import the TS module
+// from dist/. This file re-implements the SAME pure functions the lint needs —
+// loadRegistry, validateRegistry, readDecisionDeclarations, deriveClassData,
+// computeEscalation (+ the small helpers/constants they lean on).
+//
+// tests/unit/class-closure-registry-parity.test.ts pins this mirror's outputs
+// EQUAL to src/core/DefectClassRegistry.ts for the same inputs, so the two
+// implementations cannot drift (Structure > Willpower). If you edit one, edit
+// the other and the parity test will hold you to it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_SPREAD_N = 3; // ≥N across ≥2 components (normal severity)
+export const DEFAULT_SINGLE_K = 5; // ≥K within one component (normal severity)
+export const DEFAULT_GAP_MAX_AGE_DAYS = 45;
+
+export const REGISTRY_REL_PATH = path.join('docs', 'defect-classes.json');
+
+/** Is `repoRoot` an instar checkout carrying the class registry (repo-gate)? */
+export function isClassClosureRepo(repoRoot) {
+  try {
+    return (
+      fs.existsSync(path.join(repoRoot, '.git')) &&
+      fs.existsSync(path.join(repoRoot, 'package.json')) &&
+      fs.existsSync(path.join(repoRoot, REGISTRY_REL_PATH))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Load + parse the registry file. Throws on missing/malformed JSON or invalid shape. */
+export function loadRegistry(repoRoot) {
+  const p = path.join(repoRoot, REGISTRY_REL_PATH);
+  const raw = fs.readFileSync(p, 'utf-8');
+  const parsed = JSON.parse(raw);
+  const v = validateRegistry(parsed);
+  if (!v.ok) {
+    throw new Error(`defect-classes.json is invalid: ${v.errors.join('; ')}`);
+  }
+  return parsed;
+}
+
+/** Structural validation (used by the lint + tests). Never throws. */
+export function validateRegistry(reg) {
+  const errors = [];
+  if (!reg || typeof reg !== 'object') return { ok: false, errors: ['registry is not an object'] };
+  const r = reg;
+  if (typeof r.version !== 'number') errors.push('version must be a number');
+  if (!Array.isArray(r.classes)) {
+    errors.push('classes must be an array');
+    return { ok: errors.length === 0, errors };
+  }
+  const ids = new Set();
+  for (const [i, c] of r.classes.entries()) {
+    const where = `class[${i}]`;
+    if (!c || typeof c !== 'object') { errors.push(`${where} is not an object`); continue; }
+    const e = c;
+    if (!e.id || typeof e.id !== 'string') errors.push(`${where}.id missing`);
+    else {
+      if (ids.has(e.id)) errors.push(`${where}.id duplicate: ${e.id}`);
+      ids.add(e.id);
+      if (!/^[a-z0-9-]+$/.test(e.id)) errors.push(`${where}.id must match ^[a-z0-9-]+$`);
+    }
+    if (!e.description || typeof e.description !== 'string') errors.push(`${where}.description missing`);
+    if (!Array.isArray(e.includes) || e.includes.length < 1) errors.push(`${where}.includes needs ≥1 entry`);
+    if (!Array.isArray(e.excludes) || e.excludes.length < 1) errors.push(`${where}.excludes needs ≥1 entry`);
+    if (!Array.isArray(e.canonicalExamples)) errors.push(`${where}.canonicalExamples must be an array`);
+    if (e.status !== 'confirmed' && e.status !== 'unconfirmed') errors.push(`${where}.status invalid`);
+    if (e.severity !== 'critical' && e.severity !== 'normal') errors.push(`${where}.severity invalid`);
+    if (typeof e.instanceCount !== 'number') errors.push(`${where}.instanceCount must be a number`);
+    if (typeof e.evidenceCountAtLastAck !== 'number') errors.push(`${where}.evidenceCountAtLastAck must be a number`);
+    if (!('closureStandard' in e)) errors.push(`${where}.closureStandard missing (nullable ok)`);
+    if (!('proposalId' in e)) errors.push(`${where}.proposalId missing (nullable ok)`);
+    // A novel class enters unconfirmed and REQUIRES a nearestExistingClass.
+    if (e.status === 'unconfirmed' && !e.nearestExistingClass) {
+      errors.push(`${where} is unconfirmed but has no nearestExistingClass`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Read the class-closure declarations from committed decision-audit entries.
+ * The decision-audit entry is the SINGLE machine-readable counting host — the
+ * side-effects artifact mirror is display-only and is NOT read here (C1 fix).
+ * @returns {Array<object>} declarations, each with `.source` (filename) + `.ts`.
+ */
+export function readDecisionDeclarations(repoRoot) {
+  const dir = path.join(repoRoot, '.instar', 'instar-dev-decisions');
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    let entry;
+    try {
+      entry = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+    } catch {
+      continue;
+    }
+    if (entry && entry.classClosure && typeof entry.classClosure === 'object') {
+      out.push({ ...entry.classClosure, source: f, ts: entry.ts });
+    }
+  }
+  return out;
+}
+
+/**
+ * Derive per-class counts from declarations, deduped by PR number. Two
+ * declarations citing the same PR + class count ONCE. A declaration with no
+ * prNumber falls back to its source filename as the dedup key (still counts once).
+ * @returns {Map<string, object>} classId → DerivedClassData.
+ */
+export function deriveClassData(declarations) {
+  const byClass = new Map();
+  for (const d of declarations) {
+    if (!d.defectClass) continue;
+    const list = byClass.get(d.defectClass) ?? [];
+    list.push(d);
+    byClass.set(d.defectClass, list);
+  }
+  const result = new Map();
+  for (const [classId, list] of byClass) {
+    const dedupKey = (d) => (d.prNumber != null ? `pr:${d.prNumber}` : `src:${d.source}`);
+    const seen = new Set();
+    const prs = new Set();
+    const components = new Set();
+    const perComponentKeys = new Map();
+    let hasOpenGap = false;
+    for (const d of list) {
+      const key = dedupKey(d);
+      seen.add(key);
+      if (d.prNumber != null) prs.add(d.prNumber);
+      const comp = d.component ?? '<unspecified>';
+      components.add(comp);
+      const compSet = perComponentKeys.get(comp) ?? new Set();
+      compSet.add(key);
+      perComponentKeys.set(comp, compSet);
+      if (d.closure === 'gap') hasOpenGap = true;
+    }
+    let maxSingleComponentCount = 0;
+    for (const s of perComponentKeys.values()) {
+      maxSingleComponentCount = Math.max(maxSingleComponentCount, s.size);
+    }
+    result.set(classId, {
+      dedupedCount: seen.size,
+      componentCount: components.size,
+      maxSingleComponentCount,
+      hasOpenGap,
+      prs: [...prs].sort((a, b) => a - b),
+      components: [...components].sort(),
+    });
+  }
+  return result;
+}
+
+/**
+ * Deterministic threshold logic. Fires ONLY when there is NEW evidence past the
+ * last-ack baseline (seeded-closed suppression + dedup re-raise) AND a severity
+ * arm crosses:
+ *   - critical  ⇒ escalates at ≥1 confirmed instance (any new evidence).
+ *   - normal    ⇒ ≥N across ≥2 components, OR ≥2 + an open gap, OR ≥K in one component.
+ * @param {{ severity: string, evidenceCountAtLastAck: number }} entry
+ * @param {object} derived  DerivedClassData
+ * @param {{ spreadN?: number, singleK?: number }} thresholds
+ */
+export function computeEscalation(entry, derived, thresholds = {}) {
+  const N = thresholds.spreadN ?? DEFAULT_SPREAD_N;
+  const K = thresholds.singleK ?? DEFAULT_SINGLE_K;
+  const newEvidence = derived.dedupedCount > entry.evidenceCountAtLastAck;
+  if (!newEvidence) {
+    return {
+      shouldEscalate: false,
+      arm: null,
+      reason: `no new evidence past ack baseline (derived ${derived.dedupedCount} ≤ ack ${entry.evidenceCountAtLastAck})`,
+      newEvidence: false,
+    };
+  }
+  if (entry.severity === 'critical') {
+    return {
+      shouldEscalate: true,
+      arm: 'critical-1',
+      reason: `critical class recurred (derived ${derived.dedupedCount} > ack ${entry.evidenceCountAtLastAck}); escalates at 1`,
+      newEvidence: true,
+    };
+  }
+  // normal severity — three arms.
+  if (derived.dedupedCount >= N && derived.componentCount >= 2) {
+    return {
+      shouldEscalate: true,
+      arm: 'spread',
+      reason: `≥${N} instances (${derived.dedupedCount}) across ≥2 components (${derived.componentCount})`,
+      newEvidence: true,
+    };
+  }
+  if (derived.dedupedCount >= 2 && derived.hasOpenGap) {
+    return {
+      shouldEscalate: true,
+      arm: 'gap-plus',
+      reason: `≥2 instances (${derived.dedupedCount}) + an open gap item`,
+      newEvidence: true,
+    };
+  }
+  if (derived.maxSingleComponentCount >= K) {
+    return {
+      shouldEscalate: true,
+      arm: 'single-component',
+      reason: `≥${K} instances (${derived.maxSingleComponentCount}) within one component`,
+      newEvidence: true,
+    };
+  }
+  return {
+    shouldEscalate: false,
+    arm: null,
+    reason: `no normal-severity arm crossed (count ${derived.dedupedCount}, components ${derived.componentCount}, maxSingle ${derived.maxSingleComponentCount})`,
+    newEvidence: true,
+  };
+}
+
+/** Whether a gap item is open past the max-age escalation ceiling. */
+export function gapOpenPastMaxAge(gapOpenedAtIso, now = Date.now(), maxAgeDays = DEFAULT_GAP_MAX_AGE_DAYS) {
+  const opened = Date.parse(gapOpenedAtIso);
+  if (Number.isNaN(opened)) return false;
+  const ageDays = (now - opened) / (24 * 60 * 60 * 1000);
+  return ageDays > maxAgeDays;
+}

package/skills/instar-dev/templates/side-effects-artifact.md

@@ -176,3 +176,42 @@ pool-wide question is answered by a proxied-on-read merged view." Not abstractio
 ## Evidence pointers
 
 [Optional. Links or file paths to the live verification artifacts produced during `/build` — reproduction steps, before/after logs, test output. These feed the "Evidence" section in the upgrade notes if the change is shipping as a release.]
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+**REQUIRED whenever this change FIXES a defect in an agent-authored artifact** (an
+LLM prompt, hook, config, skill, or standards text — see
+`docs/specs/class-closure-gate.md`). This section is the human-readable MIRROR of
+the machine-readable `classClosure` block in the commit's decision-audit entry
+(the host the CI lint validates). **Display-only:** the lint counts the
+decision-audit host ONLY and NEVER sums this mirror — the two are asserted to
+AGREE, never added (C1). If this change fixes no agent-authored-artifact defect,
+state: "No agent-authored-artifact defect — not applicable."
+
+- **`defectClass`** — a class id from `docs/defect-classes.json`, or `novel`. A
+  `novel` class is not a free pass: it REQUIRES a full new registry entry in the
+  same change carrying `nearestExistingClass` + ≥1 `includes` + ≥1 `excludes` +
+  `severity`, and it enters `status: "unconfirmed"` (an unconfirmed class CANNOT
+  satisfy `closure: guard` — its fix carries `closure: gap` until the operator
+  confirms it).
+- **`closure`** — either `guard` (the standard/test/lint that makes the class's
+  recurrence structurally refused or detected, cited by path/symbol) or `gap` (a
+  tracked standards-gap evolution-action id when the class-level guard is out of
+  this fix's scope).
+- **`guardEvidence`** (required with `closure: guard`) — the guard's enforcement
+  type as graded by the coverage audit's grader (`ratchet` / `gate` / `lint`),
+  the citation, and one line on *how this guard would have caught THIS defect*. A
+  citation that does not resolve to a LIVE enforcing guard on disk automatically
+  downgrades the declaration to `closure: gap` (G3 — a dark/spec-only artifact
+  guards nothing).
+- **`gap`** (with `closure: gap`) — the evolution-action id tracking the missing
+  guard. A gap is not fire-and-forget: it counts as escalation evidence and
+  re-surfaces on the evolution-action cadence.
+
+[Fill in the four fields (or "not applicable"). Example: "`defectClass:
+injection-credulity`, `closure: guard`, `guardEvidence: {enforcementType: gate,
+citation: src/core/promptClauses.ts#authorityClause, howCaught: the authority
+clause separates the trusted instruction surface from the quoted untrusted
+transcript excerpt, so the injected instruction is data not command}`."]

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-03T19:15:15.540Z",
-  "instarVersion": "1.3.734",
+  "generatedAt": "2026-07-03T20:54:46.753Z",
+  "instarVersion": "1.3.735",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.735.md

@@ -0,0 +1,67 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Increment 1 of the Class-Closure Gate (`docs/specs/class-closure-gate.md`, converged +
+approved). This is the mechanical arm of the constitutional principle **"Distrust Temporary
+Success: A Recurrence Is a Root Cause"** — until now nothing at fix-time asked *"what CLASS
+of defect is this, and what structural change makes the whole class unrepresentable?"* (the
+question only ever fired because the operator asked it).
+
+Increment 1 ships **CI tooling only — no runtime gates**:
+
+- A **defect-class registry** (`docs/defect-classes.json`) seeded with the four measured
+  classes, each carrying real semantics (includes/excludes/severity/closure-standard).
+- A pure count/threshold **library** (`src/core/DefectClassRegistry.ts`) that derives each
+  class's recurrence count from committed instar-dev decision-audit declarations, deduped by
+  PR number, and computes deterministic escalation-threshold crossings (critical-at-1;
+  normal: ≥3-across-2-components, ≥2+open-gap, or ≥5-in-one-component; seeded-closed
+  suppresses historical backfill).
+- A self-contained **guard grader** (`scripts/lib/class-closure-grader.mjs`, mirroring
+  `StandardsEnforcementAuditor` with a pinned parity test) that downgrades a `closure:guard`
+  declaration to `gap` when the cited guard does not resolve to a live enforcing guard (G3:
+  a dark/spec-only artifact guards nothing).
+- A **report-only PR-gate lint** (`scripts/class-closure-lint.mjs`) + CI workflow
+  (`.github/workflows/class-closure-gate.yml`, check name `class-closure`) that validates the
+  class-declaration field-set on fixes touching agent-authored artifacts and LOGS threshold
+  crossings.
+- An author declaration helper (`scripts/class-closure-declare.mjs`) and the side-effects
+  template's mirrored declaration section.
+
+Config-gated behind `prGate.classClosure = {enabled, dryRun, escalatorDrafting}` (defaults
+off/dry-run) and repo-gated (no-op on installs without `docs/defect-classes.json`). The
+escalator's LLM drafting arm, the proposals writer, the attention-item producer, the runtime
+read route, and the consolidated axis-requirements ratchet are the spec's OWN dark
+**increment 3** — deliberately not in this increment.
+
+## What to Tell Your User
+
+Nothing changes for you right now — this ships **dark and report-only**, and it is
+maintainer-only CI machinery (a no-op on your install unless you develop instar itself). It
+is the first brick of a system that will, later and only after an operator sign-off, notice
+when the same *kind* of bug keeps recurring and propose a structural fix for the whole class
+rather than patching instances one at a time. No behavior, message, or command changes today.
+
+## Summary of New Capabilities
+
+None active for end users in this increment — everything ships disabled/dry-run and
+repo-gated. (For instar maintainers: a report-only CI lint that logs missing/invalid
+defect-class declarations and deterministic class-recurrence threshold crossings, plus the
+class registry and grading libraries it rides on.)
+
+## Evidence
+
+- `npx vitest run tests/unit/class-closure-registry.test.ts tests/unit/class-closure-grader.test.ts tests/unit/class-closure-grader-parity.test.ts tests/unit/class-closure-registry-parity.test.ts tests/integration/class-closure-lint.test.ts`
+  → **5 files, 55 tests, 0 failures** (all four escalation arms + seeded-closed suppression +
+  newEvidence gate; guard-upheld vs 3 downgrade paths; report-only-exits-0 vs
+  enforcing-exits-nonzero for both hard-violation types; both mirror-parity suites).
+- `npx tsc --noEmit` → exit 0, zero errors.
+- Report-only guarantee is structural: `scripts/class-closure-lint.mjs` computes
+  `enforcing = config.enabled && !config.dryRun` and returns a nonzero exit ONLY when
+  `enforcing && hardViolations.length > 0` — so under the shipped defaults (disabled +
+  dry-run) it always exits 0 and cannot fail a PR.
+- Side-effects review: `upgrades/side-effects/class-closure-gate.md` (8 questions + Q7
+  multi-machine posture + signal-vs-authority), second-pass reviewed.

package/upgrades/side-effects/class-closure-gate.md

@@ -0,0 +1,111 @@
+# Side-Effects Review — Class-Closure Gate (increment 1: registry + report-only lint)
+
+**Version / slug:** `class-closure-gate`
+**Date:** `2026-07-03`
+**Author:** `echo`
+**Second-pass reviewer:** `CONCUR — no material concern (independent reviewer subagent, 2026-07-03)`
+
+> **Second-pass verdict (independent reviewer):** CONCUR — no material concern. Report-only
+> guarantee holds on every policy path (`class-closure-lint.mjs:271-272`: exit is nonzero only
+> when `enabled && !dryRun && hardViolations>0`; shipped defaults → exit 0 unconditionally,
+> confirmed on all four paths + a malformed-registry probe). Signal-only: no `docs/proposals`
+> writer, no attention-item producer, no `STANDARDS-REGISTRY.md` write in increment 1 (the sole
+> registry reference is a read-scope predicate). Scope honest: `escalatorDrafting` is plumbed
+> but never read (inert reserved key, not a half-built feature); the new TS has zero runtime
+> callers; the declare mutator is in no CI workflow. Drift guarded: both grader/registry parity
+> suites exist and pass. Interactions clean (complementary to `decision-audit-gate`, not
+> shadowing). Two minor non-blocking notes: (1) the CLI entrypoint lacks a top-level try/catch,
+> but all fs reads are individually try/caught so no throw on the real paths — inherent CI-script
+> fragility, not a policy path; (2) the config-default backfill claim is moot because an absent
+> key resolves to the report-only default. Neither requires a change before commit.
+
+## Summary of the change
+
+Increment 1 of the Class-Closure Gate (`docs/specs/class-closure-gate.md`, converged + approved). Ships **CI tooling only — no runtime gates**: a class registry (`docs/defect-classes.json`), a pure count/threshold library (`src/core/DefectClassRegistry.ts`), a self-contained guard grader (`scripts/lib/class-closure-grader.mjs`, mirroring `StandardsEnforcementAuditor`'s classification with a pinned parity test), a **report-only** PR-gate lint (`scripts/class-closure-lint.mjs`) that validates the class-declaration field-set on instar-dev decision-audit entries for fixes touching agent-authored artifacts, derives per-class recurrence counts (deduped by PR#), and LOGS any deterministic escalation-threshold crossing. A CI workflow (`.github/workflows/class-closure-gate.yml`) runs the lint report-only. Config-gated (`prGate.classClosure = {enabled, dryRun, escalatorDrafting}`, defaulting off/dry-run) and repo-gated (no-op on installs without `docs/defect-classes.json`). The escalator's LLM drafting arm, the `docs/proposals/*` writer, the attention-item producer, the runtime read route, and the consolidated axis-requirements ratchet are the spec's OWN dark **increment 3** — explicitly out of scope here, not orphan deferrals.
+
+## Decision-point inventory
+
+- `scripts/class-closure-lint.mjs` (CI PR-gate lint) — **add** — a build-time SIGNAL (report-only → later enforcing) that a fix to an agent-authored artifact carries a valid class declaration; feeds the operator, never a runtime allow/deny.
+- Deterministic recurrence trigger (inside the lint, via `computeEscalation`) — **add** — LOGS a threshold crossing; the acting-on-it (draft proposal + attention item) is increment 3.
+- `guardEvidence` grading (`evaluateGuardClosure`) — **add** — downgrades a `closure:guard` declaration to `gap` when the cited guard does not resolve to a live enforcing guard (ratchet/gate/lint). Report-only in increment 1.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+Increment 1 is **report-only** (`dryRun:true` default) — the lint ALWAYS exits 0 for declaration-content findings; it cannot reject any PR. The only nonzero exit is reserved for a hard structural violation (malformed registry JSON, a `novel` class with no semantics) AND only when `enabled && !dryRun` — which is a later increment's flip. So: **no over-block surface in increment 1.** (When the enforcing flip lands later, a legitimate fix whose guard citation doesn't resolve is not "blocked" — it downgrades to `closure:gap`, a valid tracked terminal state, per spec.)
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- A fix that bypasses the instar-dev gate entirely (no decision-audit entry) carries no `classClosure` block to validate. That bypass is caught separately by the existing `decision-audit-presence-check` at the PR boundary; this lint does not duplicate that.
+- **Classification accuracy** — an author who mislabels a defect's class (or picks a self-serving hyper-narrow class) is not caught here; the spec routes that to the escalator's periodic spot-check audit (increment 3) and to operator confirmation of `novel` classes. Increment 1 measures population/accuracy honestly during dryRun rather than enforcing.
+- Recurrence inside a single component below K=5 at normal severity does not escalate (by design — distinguishes a systemic pattern from one noisy component).
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes — a **CI PR-gate lint** in the same family as `decision-audit-gate`, `eli16-pr-gate`, `release-fragment-gate`. It is a SIGNAL producer at the build boundary, not a runtime authority, and it **reuses** the existing `StandardsEnforcementAuditor` grading logic (via a self-contained `.mjs` mirror pinned equivalent by a parity test, because PR-gate lints run on a fresh checkout with no build step) rather than re-implementing guard classification. The count/threshold math lives in a pure, unit-tested library (`DefectClassRegistry.ts`). No higher gate already does class-level closure; no lower primitive is being duplicated.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or produce a signal that feeds a smart gate?** (`docs/signal-vs-authority.md`)
+
+**COMPLIANT — signal only.** The report-only lint emits a green/annotation signal; it holds no blocking authority in increment 1. The deterministic trigger only LOGS crossings. The downstream escalator (increment 3) drafts a *proposal* and raises an *attention item* — it has **no write path to `STANDARDS-REGISTRY.md`**; adoption is the operator's (Agent Proposes, Operator Approves). No brittle check is given blocking authority; the one place enforcement is later added (the flip) is a deterministic structural validation (registry well-formedness, declaration presence/shape), not a semantic judgment.
+
+---
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, race with adjacent cleanup?**
+
+- Rides the PR-gate workflow family alongside `decision-audit-gate.yml`/`eli16-pr-gate.yml`/`release-fragment-gate.yml`. It reads the SAME decision-audit entries as `decision-audit-presence-check` but a DIFFERENT field (`classClosure`) — no shadowing, no double-fire (presence-check asserts an entry EXISTS; class-closure validates the entry's declaration content).
+- The self-contained grader mirror could DRIFT from `StandardsEnforcementAuditor.gradeGuardCitation`/`classifyFileGuard` — mitigated by a pinned parity test that fails if they diverge (Structure > Willpower).
+- Counts derive from decision-audit entries **only** (deduped by PR#); the side-effects mirror is display-only and never summed — prevents the round-3 double-counting finding.
+
+---
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+- Adds one new CI check named `class-closure` to PRs against `main` (green + optional annotations). Report-only, so it can never block a merge in increment 1.
+- Adds a config key `prGate.classClosure` (off/dry-run default).
+- Adds an author helper `scripts/class-closure-declare.mjs` (stamps a `classClosure` block onto a decision entry).
+- No agent-to-agent, Telegram, or dashboard surface in increment 1 (the attention-item producer is increment 3). No dependence on runtime/conversation state — the lint is a pure function of the repo checkout + the PR diff.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Replicated / proxied-on-read / machine-local-by-design?**
+
+**Replicated — via git (the repo IS the replication medium).** The class registry, the `classClosure` declarations (in committed decision-audit entries), and (later) proposal files are all committed to the canonical repo and therefore identical on every machine. Dedup is **repo-state**, never machine-local JSONL, so two machines cannot double-file or double-count. Increment 1 runs entirely in GitHub Actions (not per-machine), so it holds no machine-local runtime state. No user-facing notice (no one-voice concern), no durable per-machine state to strand on topic transfer, no generated URL. The spec declares this posture explicitly ("Multi-machine posture (declared)").
+
+---
+
+## 8. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial and safe. The lint is **report-only + config-gated (`prGate.classClosure` defaults off/dry-run) + repo-gated** — a buggy lint cannot block a merge (it exits 0 in dryRun) and is a no-op on any non-maintainer install. Back-out options, cheapest first: (a) leave defaults (already inert); (b) revert `.github/workflows/class-closure-gate.yml`; (c) revert the whole PR — no data migration, no agent-state repair, no runtime behavior to unwind (no runtime routes added in increment 1). The added `src/core` code is pure libraries with no callers in the runtime path yet.
+
+## Follow-up note — no-silent-fallbacks ratchet
+
+`DefectClassRegistry.ts` (`readDecisionDeclarations` absent-dir catch) and
+`StandardsEnforcementAuditor.gradeGuardCitation` (unresolvable-path catch) are pure
+libraries over a repo checkout with **no runtime / DegradationReporter surface** — their
+fail-closed catches return the correct answer (empty list / `resolved:false`, which the
+caller surfaces as a `gap` downgrade), not a degraded result. Both are tagged
+`@silent-fallback-ok` so the `no-silent-fallbacks` ratchet holds at baseline 491 rather than
+demanding a runtime degradation-report the library layer cannot emit.