instar 1.3.733 → 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-03T18:48:01.036Z",
-  "instarVersion": "1.3.733",
+  "generatedAt": "2026-07-03T20:54:46.753Z",
+  "instarVersion": "1.3.735",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.734.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Three operator-ratified standards were landed into the constitution as TEXT — this change adds no runtime code, gate, hook, sentinel, or route. Each standard is written in both the enforceable registry (`docs/STANDARDS-REGISTRY.md`) and the earned-lessons catalog (`docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md`, entries P21-P23, with the lessons-aware reviewer loop bumped from P1-P20 to P1-P23):
+
+- **An Instar Agent Is Always a Multi-Machine Entity.** "Unified across my machines" is now the DEFAULT posture for every feature and state surface. "Machine-local" is an exception that must name a concrete reason it cannot be unified (a credential physically bound to one disk's keychain, a hardware-bound resource, or an operator-ratified exception). A bare "machine-local BY DESIGN" with no justification is a violation. This closes the gap the existing per-feature posture check missed — that check verified a feature *declared* a posture but accepted "machine-local BY DESIGN" as a valid answer, so it tested for a declaration rather than for the unified default. Distinct from *Cross-Machine Coherence*, which governs lease/seamlessness robustness; this governs the default posture of every new feature.
+- **Self-Heal Before Notify.** A watcher that detects an internal issue must attempt a bounded, audited self-heal FIRST and page the operator only when the self-healing itself has failed (exhausted, crashed, unable to recover) — never on first detection. Composes with *No Silent Degradation* by refining to WHOM the report goes: into the self-heal machinery (every detection, heal attempt, and outcome audited), with the operator as the last resort. It is the general rule beneath *Near-Silent Notifications*.
+- **Notices Route to the Alerts Topic, Never a New One.** A user-facing message that belongs to an existing conversation goes there; an ownerless notice (an alert, a system notice, a housekeeping escalation) routes to the ONE dedicated alerts/hub topic. Creating a new Telegram topic per alert or event is forbidden. This is the routing corollary of *Bounded Notification Surface* — that standard caps how many topics may be born; this one names where an ownerless notice goes instead. Much of the machinery already ships (the topic-creation budget, the attention-topic coalescing guard, the burst-invariant test); this standard makes the alerts-topic default the rule and closes the unique-source dodge.
+
+The enforcement build that mechanically polices each standard (the strengthened spec-converge cross-machine check that rejects undefended machine-local, the side-effects review posture-justification field, the conformance guard marker, and the alerts-topic routing assertion at the chokepoint) is a separate, tracked follow-up. From the moment this merges, the spec-converge lessons-aware reviewer already reads P21-P23 and asks their questions of every future spec.
+
+## What to Tell Your User
+
+Three rules your operator decided by hand are now written into my constitution, so I follow them from now on and my spec reviews cite them automatically. First, I treat myself as one agent spread across all your machines by default — a feature only stays tied to a single machine when there is a real reason it cannot be shared, like a login that physically lives on one computer. Second, when I notice something wrong inside myself, I try to fix it quietly first and only tell you if that self-repair fails — you hear from me on genuine trouble, not every small hiccup. Third, alerts that do not belong to an existing conversation all go to your one dedicated alerts topic instead of spawning a new topic per alert, so your Telegram stays calm and readable. This update writes the rules down; the automated enforcement that polices them is a follow-up I am building next.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Standard: An Instar Agent Is Always a Multi-Machine Entity | Documented in the constitution — the spec-converge lessons-aware reviewer applies it automatically to every future spec |
+| Standard: Self-Heal Before Notify | Documented in the constitution — watchers self-heal first, escalate to the operator only on self-heal exhaustion |
+| Standard: Notices Route to the Alerts Topic, Never a New One | Documented in the constitution — ownerless notices route to the one alerts/hub topic, never a per-alert topic |
+
+## Evidence
+
+Not reproducible in dev — this change lands constitution TEXT only, with no runtime surface to exercise. The three standards' historical evidence is the earned-from incidents recorded in each entry: (A) the tiered-intelligence-delegation spec that defaulted its consult memory to machine-local and survived seven convergence rounds before the operator caught it on read (2026-07-03, topic 29723); (B) the operator's directive while hardening that spec's watcher-for-the-watcher, that internal issues route to the self-healing parts of the system and reach the user only when self-healing fails; (C) the recurring topic-spam floods of the same shape — 2026-05-22 (sentinel), 2026-05-28 (collaboration-redrive), 2026-06-05 (worktree-detector, which dodged the per-source budget with unique sources). Verification for this change is structural: `git show --stat 11923c4c4` shows the two docs files landed (84 insertions), and `node scripts/pre-push-gate.js` passes with the release fragment validating and the fresh side-effects artifact present.

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.

package/upgrades/side-effects/three-constitutional-standards.md

@@ -0,0 +1,129 @@
+# Side-Effects Review — Three Operator-Ratified Constitutional Standards (multi-machine-always, self-heal-before-notify, alerts-topic-routing)
+
+**Version / slug:** `three-constitutional-standards`
+**Date:** `2026-07-03`
+**Author:** Echo (autonomous)
+**Second-pass reviewer:** not-required (Tier 1; documentation-only, no runtime surface, no decision point)
+
+## Summary of the change
+
+This change lands the TEXT of three operator-ratified constitutional standards into the constitution and nothing else. It touches two documentation files and adds this review's gate artifacts:
+
+- `docs/STANDARDS-REGISTRY.md` — three new enforceable standard entries: (A) *An Instar Agent Is Always a Multi-Machine Entity*, (B) *Self-Heal Before Notify — The Operator Hears Only When Self-Healing Fails*, (C) *Notices Route to the Alerts Topic, Never a New One*.
+- `docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md` — matching lessons-catalog entries P21, P22, P23, and the reviewer-loop range bump (P1-P20 → P1-P23).
+- `docs/specs/three-constitutional-standards.eli16.md` — the plain-English ELI16 overview (this Tier-1 gate artifact).
+- `upgrades/side-effects/three-constitutional-standards.md` — this artifact.
+- `upgrades/next/three-constitutional-standards.md` — the release-note fragment.
+
+No `src/`, `scripts/`, hook, skill, job, template, or route is touched. This is constitution text. The three standards each name an enforcement build in their "Applied through" section, but that build is a separate, tracked follow-up — it is NOT part of this change. There is no runtime surface here and no decision point is added, modified, removed, or shadowed.
+
+## Decision-point inventory
+
+This change has NO decision-point surface. It adds no gate, sentinel, watchdog, hook, or route; it blocks, allows, filters, or routes nothing at runtime. The standard texts describe decision points that a FUTURE enforcement build will implement, but this change lands only the prose. The rest of this section is intentionally empty per the template's "state that explicitly and skip the rest" instruction.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. This change adds no runtime code path; it rejects nothing at runtime. The one "gate" it interacts with is the spec-converge lessons-aware reviewer, which merely READS these entries and asks their questions of future specs — a reasoning input, not an automated blocker.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. There is no runtime check to miss a failure mode. The honest limitation is that landing the TEXT does not by itself enforce the standards: until the tracked enforcement build ships, a spec could still ship an undefended machine-local surface, a first-notify watcher, or a per-alert topic without an automated block. That gap is explicitly named in each standard's "Applied through" section and is out of scope for this text-only change.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Correct layer. These are constitutional standards, so the constitution (`docs/STANDARDS-REGISTRY.md`) and the lessons catalog (`docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md`) are exactly where they belong — they are the documents the spec-converge lessons-aware reviewer already loads. Standard (A) is deliberately placed as a sibling of the existing *Cross-Machine Coherence* standard and explicitly distinguishes itself from it (coherence governs lease/seamlessness robustness; (A) governs the default posture of every new feature). Standard (C) is placed as the routing corollary of the existing *Bounded Notification Surface* (P17). No lower-level primitive is re-implemented; each entry points at the machinery that already exists and names the enforcement build that will make it load-bearing.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+This is documentation text. It holds no authority of any kind at runtime — it neither blocks, delays, nor rewrites any message or action. Notably, standard (B) *Self-Heal Before Notify* itself encodes the signal-vs-authority spirit for the future enforcement build (a watcher self-heals first and escalates only on exhaustion), but landing (B)'s text adds no authority now.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** none. No runtime check runs before or after another. The only consumer of these entries is the spec-converge lessons-aware reviewer, which reads them additively.
+- **Double-fire:** none. No event is acted on.
+- **Races:** none. No shared runtime state is written.
+- **Feedback loops:** none at runtime. The one intended "loop" is intellectual: these entries feed the spec-converge reviewer, which asks their questions of future specs — the designed effect, not an uncontrolled feedback path.
+- **Document-level composition:** (A) is explicitly reconciled against *Cross-Machine Coherence*; (B) is explicitly composed with *No Silent Degradation* and *Near-Silent Notifications*; (C) is explicitly composed with *Bounded Notification Surface (P17)*. Each entry names the relationship rather than silently overlapping, so no reader is left to guess which standard governs.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the same machine? No.
+- Other users of the install base? Only as documentation — instar agents read the constitution; these entries become visible to the spec-converge lessons-aware reviewer on the next spec review. No behavior changes.
+- External systems (Telegram, Slack, GitHub, Cloudflare)? No.
+- Persistent state (databases, ledgers, memory files)? No — no state file is written or migrated.
+- Timing or runtime conditions? No.
+- **Operator surface (Mobile-Complete Operator Actions):** No operator-facing action is added or touched. This change adds no dashboard form, no approval page, no grant/revoke/secret-drop surface, and no PIN-gated or approval-class route. Not applicable.
+
+No external surface changes.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. This change touches no dashboard renderer/markup file, no approval page, and no grant/revoke/secret-drop form. It is documentation only.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**When this agent runs on MORE THAN ONE machine, what is this feature's posture?**
+
+**replicated** — these are constitution DOCS. The documentation tree (`docs/`) is versioned in git and ships to every machine through the same git-based distribution as all instar source; there is no per-machine copy and no per-machine divergence. A standard written once is identical on every machine by construction.
+
+Notably, this is the FIRST change authored *under* standard (A), and it satisfies (A) by default: its posture is unified (git-replicated), not machine-local, and it names the replication path (git). It emits no user-facing notice (nothing to one-voice-gate), holds no durable runtime state (nothing to strand on topic transfer), and generates no URLs (nothing to survive a machine boundary).
+
+---
+
+## 8. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. Pure documentation change — revert the commit (or ship a follow-up docs edit) and it is gone. No persistent state to clean up, no data migration, no agent state to repair, and no user-visible runtime regression during the rollback window. The only "cost" of a wrong standard is that the spec-converge lessons-aware reviewer would cite a bad rule until the revert lands — caught at spec-review time, not in a live incident.
+
+---
+
+## Conclusion
+
+This review confirms the change is documentation-only with no runtime surface, no decision point, and no external side effect. It lands the three operator-ratified standard texts (registry + lessons entries) and their Tier-1 gate artifacts. Multi-machine posture is unified-by-git-replication — and this change is itself the first artifact authored under the standard (A) it introduces, satisfying it by default. Rollback is a one-commit revert. The change is clear to ship. The enforcement build that mechanically polices each standard is a tracked, separate follow-up and is explicitly out of scope here.
+
+---
+
+## Second-pass review (if required)
+
+Not required. Tier 1, documentation-only, no block/allow surface, no session-lifecycle or gate/sentinel/watchdog/guard code — the Phase-5 high-risk triggers do not apply to a text-only constitution change.
+
+---
+
+## Evidence pointers
+
+- `git show --stat 11923c4c4` — the two docs files already committed (STANDARDS-REGISTRY + lessons catalog), 84 insertions.
+- `docs/specs/three-constitutional-standards.eli16.md` — plain-English overview, 6.8k chars (well over the 800-char floor), first-heading body ~1k chars before the first subheading.
+- `node scripts/pre-push-gate.js` — release-note fragment validates and the fresh side-effects artifact is present (this file).