instar 1.3.734 → 1.3.736

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/skills/spec-converge/SKILL.md

@@ -91,7 +91,8 @@ The skill spawns reviewers in parallel:
 - **Security.** Attack surfaces, leaks, privilege escalation, auth on endpoints, prompt injection vectors, rotation races.
 - **Scalability/performance.** Hot-path cost, concurrent writes, memory churn, fail-open semantics, hook latency.
 - **Adversarial.** Misbehaving-session scenarios — bad-entry poisoning, self-reinforcing loops, stale claims, authority ambiguity, kind gaming.
-- **Integration/deployment.** Migration, backup/restore, multi-machine, config knobs, dashboard surface, rollback. **Multi-machine posture (Cross-Machine Coherence — mandatory check):** every feature/state surface the spec introduces must declare its posture when the agent runs on more than one machine — replicated (named replication path) / proxied-on-read (named merged read) / machine-local BY DESIGN (with the reason). A spec whose features silently assume a single machine is a MATERIAL finding: ~20 features shipped machine-blind before this check existed (2026-06-12 audit, topic 13481; MULTI-MACHINE-SEAMLESSNESS-SPEC is the cleanup bill). Probe specifically: user-facing notices (one-voice gating?), durable state (strands on topic transfer?), generated URLs (survive machine boundaries?).
+- **Integration/deployment.** Migration, backup/restore, multi-machine, config knobs, dashboard surface, rollback. **Multi-machine posture (Cross-Machine Coherence — mandatory check):** every feature/state surface the spec introduces must declare its posture when the agent runs on more than one machine — replicated (named replication path) / proxied-on-read (named merged read) / machine-local BY DESIGN (with the reason). A spec whose features silently assume a single machine is a MATERIAL finding: ~20 features shipped machine-blind before this check existed (2026-06-12 audit, topic 13481; MULTI-MACHINE-SEAMLESSNESS-SPEC is the cleanup bill). Probe specifically: user-facing notices (one-voice gating?), durable state (strands on topic transfer?), generated URLs (survive machine boundaries?). **Standard A — reject an UNDEFENDED machine-local (default is `unified`):** a *declared* posture is no longer enough — the DEFAULT posture is `unified`, and an undefended `machine-local` is itself a **MATERIAL FINDING** (this is the upgrade from "accepts a declaration" to "requires the correct default"; the tiered-intelligence consult-memory shipped machine-local-by-design and survived seven rounds because the check only tested for an *answer*). A machine-local surface is allowed ONLY with a `machine-local-justification: <key>` marker — one labeled `key: value` line per machine-local surface inside the spec's `## Multi-machine posture` section — whose `<key>` is drawn from a **CLOSED taxonomy**: `physical-credential-locality` (a login / key / token / service-binding that physically lives on one disk — e.g. a Claude OAuth login, a browser profile's cookies, a Telegram bot token + the forum/topic ids it namespaces), `hardware-bound-resource` (bound to specific physical hardware), or `operator-ratified-exception` (the operator explicitly ratified it — this key MUST cite a machine-verifiable, existence-checkable artifact ref: a commit SHA, a registry key, or a resolvable URL, NEVER a bare topic+date). Other locality reasons (availability, privacy/data-residency, cost/latency, an intentional per-machine cache) are DENIED by default — each is either not a real locality *requirement* or must be routed through `operator-ratified-exception`; a fourth key is a constitution-bound operator decision, never an author's convenience. The check is **BIDIRECTIONAL**: an *infeasible* `unified` (a surface that is inherently credential/hardware-bound but declared — or left to default — `unified`) is EQUALLY a MATERIAL FINDING, because "just claim unified" would otherwise be the trivial dodge (and invites an unsafe attempt to replicate a credential). The reviewer INDEPENDENTLY CONTESTS correctness in BOTH directions: a marker whose key is *present* but substantively *wrong* is still a finding — the marker's PRESENCE never satisfies the CORRECTNESS check (this spec's own first draft mislabeled its per-machine hub `hardware-bound-resource`; the correct key was `physical-credential-locality`, and this rule is what catches it). `operator-ratified-exception` is the escape hatch — treat each use as worth surfacing for operator visibility so the hatch can't quietly become the path of least resistance. (Signal vs. Authority: the `machine-local-justification` marker is the cheap deterministic signal; THIS reviewer holds the semantic authority. The purely-deterministic marker LINT lands with the registry ship, hard-sequenced — until then this reviewer + the per-spec `POST /spec/conformance-check` gate surface a missing/wrong marker; do NOT claim a no-LLM deterministic parse exists yet.)
+- **Self-Heal Before Notify (Standard B — escalation-gate review-check).** A spec that adds a **monitor / watcher / recurring-or-automated notice source** which raises operator notices MUST place its operator-facing attention-raise DOWNSTREAM of a `selfHealAttempted && selfHealExhausted` signal — the escalation path is UNREACHABLE on first detection. A first-detection escalation on a `recoverable` degradation is a **MATERIAL FINDING**. (Scope: a one-shot conversational reply is NOT a watcher and pays no self-heal cost.) The watcher MUST DECLARE, and the reviewer INDEPENDENTLY CONTESTS: (a) its self-heal step + `remediation-actions` — the concrete operations it invokes (re-register / restart / re-deliver); a no-op that merely flips `selfHealAttempted = true` to unlock escalation is a MATERIAL FINDING, and each side-effecting action MUST carry an idempotency guard + a compensation/rollback (a heal retried over a half-completed action is how these loops corrupt state); (b) that step's P19 brakes (per *No Unbounded Loops*) — `max-attempts`, `max-wall-clock`, `backoff`, `dedupe-key`, `breaker` (INCLUDING flapping: N heals of the same break within a window auto-reclassify to critical and escalate — a structural backstop a `recoverable` label can NEVER waive, per *Distrust Temporary Success*), `max-notification-latency` (an explicit duration WITH units, e.g. `120s`, and ≤ the constitutional ceiling at the registry key `standards.selfHealBeforeNotify.recoverableLatencyCeiling` — a recoverable watcher MUST tell the operator even while self-heal is still running once this ceiling passes; a missing/unitless value is a MATERIAL FINDING and a missing ceiling fails CLOSED = escalate-sooner), `audit-location` (a scrubbed, metadata-only trail — never raw secrets); (c) the severity `class` of each degradation — an **irreversible / data-loss / security** class escalates IMMEDIATELY (on the SAME detection tick, no heal-gate delay interposed) and self-heals CONCURRENTLY (notify-and-heal), while everything else is `recoverable`; a critical degradation MISLABELED `recoverable` to unlock the heal-first path is a MATERIAL FINDING (presence of a class field never satisfies the CORRECTNESS check — symmetric to Standard A's marker-correctness rule). Composes with *No Silent Degradation*: routing to self-heal is NEVER swallowing — every detection + heal attempt is audited, the audit trail IS the report, and the operator is the last resort, not the silent-drop alternative. The FIRST runtime application MUST extract the pattern into a reusable `SelfHealGate` — a THIN declaration + assertion layer over Instar's EXISTING in-process P19 breaker primitives (CrashLoopPauser and the breakers already threaded through the monitors), NEVER a new external workflow engine — plus a shared conformance fixture that exercises the stateful paths (unreachable-before-exhaustion, observable remediation evidence, flapping auto-escalation, and the latency backstop firing mid-heal). That runtime application is a downstream build task registered under Close the Loop, deliberately outside this review-check's own boundary — this bullet ships the review lens + the pattern, the code application follows.
 - **Decision-Completeness.** (Autonomy Principle 2 — `docs/specs/AUTONOMY-PRINCIPLES-ENFORCEMENT-SPEC.md` Piece 2.) Enumerates every point where the building agent would have to **stop mid-run and ask the user**. Each must be either **frontloaded** into a `## Frontloaded Decisions` section or explicitly tagged **cheap-to-change-after** because the work ships behind a named dark/dry-run/read-only phase. The reviewer **CONTESTS every cheap tag** — it independently asserts reversibility, and a closed non-cheap taxonomy overrides any tag: anything touching **durable external side-effects, money, identity, or a published/user-visible interface is NEVER cheap**, regardless of a "ships dark" label. A contested tag the reviewer rejects is a **material finding that blocks convergence**. Prompt: `templates/reviewer-decision-completeness.md`. Applies to ALL specs through this skill (D7) — no size gate, no per-spec override (D11; the rejected `disposition: override` escape hatch would reopen the exact skip-hatch Principle 2 closes).
 - **Lessons-aware.** Loads the canonical Instar Design Principles + Lessons Learned index (`docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md`) plus the running agent's local `.instar/memory/feedback_*.md` entries, then checks the spec for (a) direct contradictions of documented principles/lessons, (b) applicable lessons the spec fails to engage with, (c) behavioral lessons violated by agent-facing surfaces the spec proposes, and **(d) FOUNDATION/SUBSYSTEM AUDIT — the design the spec TESTS, EXTENDS, or BUILDS ON, not just the spec's own surface: does that foundation violate a known standard or repeat a known mistake?** The audit MUST reach one layer below the spec boundary. A spec can be internally clean while faithfully testing or extending a flawed foundation — e.g. a test-harness spec that correctly proves a permission gate which *itself* holds brittle blocking authority in violation of Signal-vs-Authority, or an extension spec built on a subsystem with an unaddressed gap. Taking the underlying subsystem "as given" is exactly how a standards violation survives review: the spec passes, the foundation's flaw is never weighed. When the foundation is flawed, the finding is "this spec is sound but the subsystem it depends on violates standard X / repeats mistake Y — surface it before building on/around it." Catches the "Phase 2" anti-pattern, the spec-converge-pre-auth-circular failure mode (see `feedback_spec_converge_pre_auth_circular`), and the foundation-not-audited gap (the Slack-permission-gate brittle-enum-as-authority that the harness convergence cleared because it audited only the harness, 2026-06-09).
 

package/skills/spec-converge/templates/reviewer-integration.md

@@ -19,17 +19,19 @@ Specifically check:
 
 3. **Auto-update path** — when a user pulls a new version of instar, what automatically propagates? What needs manual intervention?
 
-4. **Multi-machine** — if instar agents are paired across machines, does the new state stay coherent across both, or does each machine develop its own divergent view?
+4. **Multi-machine — Standard A: reject an UNDEFENDED machine-local (default is `unified`).** For EVERY state surface the spec introduces, the DEFAULT posture is `unified` across the agent's machines. A *declaration* of "machine-local BY DESIGN" is NOT sufficient — an undefended `machine-local` is a **MATERIAL FINDING**. A machine-local surface is allowed ONLY with a `machine-local-justification: <key>` marker (one labeled `key: value` line per surface, in the spec's `## Multi-machine posture` section) whose `<key>` is from the **CLOSED taxonomy**: `physical-credential-locality` (a login / key / token / service-binding that physically lives on one disk), `hardware-bound-resource` (bound to specific hardware), or `operator-ratified-exception` (operator-ratified, and MUST cite a machine-verifiable, existence-checkable ref — a commit SHA, registry key, or resolvable URL, never a bare topic+date). Other reasons (availability, privacy/data-residency, cost/latency, per-machine cache) are DENIED by default. The check is **BIDIRECTIONAL**: an *infeasible* `unified` (a credential/hardware-bound surface declared or defaulted `unified`) is EQUALLY a MATERIAL FINDING. CONTEST the justification INDEPENDENTLY in both directions — a marker whose key is present but substantively WRONG is still a finding; the marker's PRESENCE never satisfies the CORRECTNESS check. (Absence of any posture declaration defaults to `unified`-required.)
 
-5. **Backup/restore** — is new persistent state included in the backup manifest? If a user runs a snapshot/restore cycle, does the state survive?
+5. **Self-Heal Before Notify — Standard B (escalation-gate).** If the spec adds a **monitor / watcher / recurring-or-automated notice source** that raises operator notices, its operator-facing raise MUST be DOWNSTREAM of `selfHealAttempted && selfHealExhausted` — UNREACHABLE on first detection. A first-detection escalation on a `recoverable` degradation is a **MATERIAL FINDING** (a one-shot conversational reply is out of scope). The watcher MUST declare, and you CONTEST: its self-heal step + `remediation-actions` (concrete operations — a no-op flag-flip is a finding; each side-effecting action needs an idempotency guard + compensation); its P19 brakes — `max-attempts`, `max-wall-clock`, `backoff`, `dedupe-key`, `breaker` (incl. flapping auto-escalation), `max-notification-latency` (explicit units, ≤ `standards.selfHealBeforeNotify.recoverableLatencyCeiling`), `audit-location` (scrubbed); and the severity `class` of each degradation (an irreversible/data-loss/security class escalates IMMEDIATELY and heals concurrently; a critical-as-`recoverable` mislabel is a MATERIAL FINDING). This composes with *No Silent Degradation* — routing to self-heal is auditing, never swallowing.
 
-6. **Rollback** — if the feature is reverted, what happens to state files, config entries, and background jobs? Is cleanup provided?
+6. **Backup/restore** — is new persistent state included in the backup manifest? If a user runs a snapshot/restore cycle, does the state survive?
 
-7. **Dashboard / observability** — is there a UI surface where users can see what's happening? A feature affecting every session should be visible somewhere.
+7. **Rollback** — if the feature is reverted, what happens to state files, config entries, and background jobs? Is cleanup provided?
 
-8. **Config knob** — is there a way to disable the feature if it turns out to be harmful? Default on or off?
+8. **Dashboard / observability** — is there a UI surface where users can see what's happening? A feature affecting every session should be visible somewhere.
 
-9. **Anything else** about deployment, operations, or integration that might surprise in production.
+9. **Config knob** — is there a way to disable the feature if it turns out to be harmful? Default on or off?
+
+10. **Anything else** about deployment, operations, or integration that might surprise in production.
 
 Produce a SHORT report (under 400 words):
 

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-03T21:33:39.596Z",
+  "instarVersion": "1.3.736",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "57d09bfcdaad6aa9e466cfadf972a7fd27f55d5011fac7f82495ee44856f42c7",
+      "contentHash": "73d28859114fc58c042a25f2cb15703265118eb07a46cc26f333a43653658b1a",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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/1.3.736.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Enforcement machinery for three operator-ratified constitutional standards, per
+`docs/specs/three-standards-enforcement.md` (converged). This ships the STRUCTURE that makes
+each standard stick — the standard TEXTS ship separately under the already-granted ratification.
+
+- **Standard A — reject an undefended machine-local.** The `/spec-converge` integration reviewer
+  is upgraded from "a cross-machine posture is *declared*" to "the default posture is `unified`;
+  an undefended `machine-local` is a MATERIAL FINDING." A machine-local surface is now allowed
+  only with a `machine-local-justification: <key>` marker drawn from a CLOSED taxonomy
+  (`physical-credential-locality` / `hardware-bound-resource` / `operator-ratified-exception`),
+  and the check is bidirectional (an infeasible `unified` is equally a finding). The marker is the
+  cheap deterministic signal; the LLM reviewer holds the semantic authority (Signal vs. Authority).
+- **Standard B — self-heal before notify.** A new `/spec-converge` review-check that flags any
+  monitor/watcher/recurring-notice-source whose operator-facing escalation is reachable on first
+  detection. A watcher must declare its self-heal step, its `remediation-actions`, its P19 brakes
+  (including flapping detection and a `max-notification-latency`), and a contested severity class.
+- **Standard C — alerts-topic routing default.** A table-driven routing CONTRACT test at the
+  Telegram adapter boundary proving a topic-less non-critical notice routes to the one hub topic by
+  default, HIGH/URGENT keep their own topic, an existing-owning-topic send mints no new topic, and
+  an unresolvable hub falls back safely — plus a guard that the hub id is never a baked-in constant.
+- **Migration Parity.** `migrateThreeStandardsReviewChecks` re-copies the two upgraded spec-converge
+  skill files to already-installed agents, mirroring the existing multi-machine-posture migration.
+
+Honest framing: the purely-deterministic marker/field lints for A and B are hard-sequenced to land
+WITH each standard's registry guard, not in this change; until then A/B enforcement is the per-spec
+conformance-check gate plus the LLM review-lens (a semantic audit), never a no-LLM guarantee.
+
+## What to Tell Your User
+
+Nothing changes in how you talk to me day to day. This is internal development plumbing: when I
+design a new capability, my own spec-review now pushes back harder on two mistakes it used to let
+slide — quietly assuming a feature only ever runs on one of your machines, and building a watchdog
+that pings you the instant it sees a problem instead of trying to fix it first and telling you only
+when it genuinely cannot. It also adds a test proving stray housekeeping notices land in your one
+alerts topic instead of spawning a new topic each time. You do not need to do anything.
+
+## Summary of New Capabilities
+
+No new user-facing capability. Internal enforcement only: stronger spec-review checks for
+cross-machine posture and self-heal-before-notify, an idempotent migration so existing agents
+receive the upgraded checks, and a routing contract test for topic-less notices.
+
+## Evidence
+
+- `npx vitest run tests/unit/PostUpdateMigrator-threeStandardsReviewChecks.test.ts` — 7 passed
+  (content-presence of the A/B review-lenses in the shipped prompts + migration idempotency and
+  fingerprint-guard).
+- `npx vitest run tests/integration/notification-flood-burst-invariant.test.ts` — 12 passed
+  (5 new Standard C routing-contract cases + 7 existing burst-bound cases).
+- `npx tsc --noEmit` — clean.
+- Side-effects review: `upgrades/side-effects/three-standards-enforcement.md`.