instar 1.3.759 → 1.3.760

package/scripts/instar-dev-precommit.js

@@ -33,6 +33,7 @@ import { verifyProposalDerivedRunbooks } from '../skills/instar-dev/scripts/veri
 import { classifyTier, decideRequirementSet } from './lib/classify-tier.mjs';
 import { recognizeConvergence } from './lib/convergence-recognition.mjs';
 import { isOperatorSurfaceFile, artifactAddressesOperatorSurfaceQuality, isAuthorizationSurfaceFile, artifactAddressesAgentProposesApproves, operatorSurfaceRequiresRawInput } from './lib/operator-surface.mjs';
+import { selfActionDeclarationVerdict } from './lib/self-action-detect.mjs';
 
 // Report-Backed Converging Audit (docs/specs/CONVERGING-AUDIT-DEFAULT.md, Part B).
 // The precommit reads NO config file and runs pre-compile, so it cannot import
@@ -180,10 +181,14 @@ if (bootstrapTrigger) {
 
 let tierSignal = { suggestedTier: 2, sizeTier: 2, riskFloor: 1, reasons: [] };
 let totalChangedLoc = 0;
+// Hoisted to module scope (docs/specs/self-action-convergence.md → E3 impl
+// note): addedDiffText is computed in the Step-3.5 block but consumed later by
+// assertSelfActionDeclared at BOTH the enforceTier1 and Tier-2 pass-through call
+// sites. It must outlive the block.
+let addedDiffText = '';
 {
   let addedLines = 0;
   let deletedLines = 0;
-  let addedDiffText = '';
   try {
     const numstat = execSync(
       `git diff --cached --numstat -- ${inScopeFiles.map((f) => JSON.stringify(f)).join(' ')}`,
@@ -337,6 +342,7 @@ const decisionEntryPath = writeDecisionAudit({
   files: inScopeFiles.length,
   loc: totalChangedLoc,
   causalAutopsy,
+  classClosure: (freshestTrace && typeof freshestTrace.classClosure === 'object' && freshestTrace.classClosure) || null,
 });
 // Malformed autopsy blocks AFTER the audit write — the blocked attempt is
 // recorded (verdict 'blocked' via the exit handler), same as every gate
@@ -886,6 +892,7 @@ if (!promotionGateResult.ok) {
 
 assertFrameworkGenerality(inScopeFiles, validTrace.trace);
 assertOperatorSurfaceQuality(staged, validTrace.trace);
+assertSelfActionDeclared(addedDiffText, inScopeFiles, validTrace.trace);
 
 console.error(
   `[instar-dev-precommit] OK — trace ${path.basename(validTrace.entry.file)} covers ${inScopeFiles.length} in-scope file(s), artifact ${validTrace.trace.artifactPath} verified, spec ${spec} is converged + approved` +
@@ -1035,6 +1042,90 @@ function assertOperatorSurfaceQuality(stagedFiles, trace) {
   }
 }
 
+// Self-Action Convergence gate (docs/specs/self-action-convergence.md → E3).
+// The light (Tier-1) path is where #1035 (swap-thrash) slipped through with no
+// adversarial reviewer. When an ADDED diff introduces/modifies a self-action
+// emit (restart|swap|respawn|spawn|notify|retry|re-drive|kill) AND a src/ file
+// is touched, the change must declare the `unbounded-self-action` class in the
+// TRACE — either a real classClosure declaration (guard|gap) OR an explicit
+// negative declaration (closure:'n/a' + reason) — the trace-level analog of the
+// D4 lint's allowlist. A genuine one-shot user-driven call costs one attested
+// line, never an unescapable block.
+//
+// FAIL-OPEN on tooling failure (the safe asymmetry): empty addedDiffText, no
+// src/ file, or an unreadable artifact does NOT fire — a false-negative here is
+// backstopped by the E2 CI lint; a false-positive that blocked all commits
+// would sever the developer's ability to ship. Called at BOTH pass-through
+// points (enforceTier1 + the Tier-2 fall-through) — the both-call-sites detail
+// is load-bearing (the light path is where #1035 escaped).
+function assertSelfActionDeclared(addedDiffText, inScopeFilesArg, trace) {
+  const verdict = selfActionDeclarationVerdict({
+    addedDiffText,
+    inScopeFiles: inScopeFilesArg,
+    classClosure: trace && trace.classClosure,
+  });
+  if (!verdict.required) return; // fail-open / not a self-action change
+
+  if (!verdict.satisfied) {
+    blockCommit(
+      inScopeFilesArg,
+      [
+        'Self-Action Convergence gate:',
+        '  This change ADDS or modifies a self-triggered action in src/ (a',
+        '  restart / swap / respawn / spawn / notify / retry / re-drive / kill),',
+        '  but the trace carries no `unbounded-self-action` class declaration.',
+        '',
+        '  A self-triggered action must be proven to CONVERGE under sustained',
+        '  pressure (not just be individually correct). Declare it in your trace:',
+        '',
+        '  • If it is a self-triggered controller — register it in',
+        '    src/testing/selfActionRegistry.ts (so tests/unit/self-action-convergence.test.ts',
+        '    proves it settles) and declare closure:"guard" citing that ratchet:',
+        '      node scripts/class-closure-declare.mjs --to-trace \\',
+        '        --class unbounded-self-action --closure guard \\',
+        '        --citation tests/unit/self-action-convergence.test.ts \\',
+        '        --enforcement ratchet --how-caught "<convergence argument: steady-state bound + settling brake>"',
+        '',
+        '  • If the guard is out of THIS change\'s scope — closure:"gap" with a',
+        '    tracked evolution-action id (--closure gap --gap-item <id>).',
+        '',
+        '  • If it is genuinely a ONE-SHOT / user-driven action (not a',
+        '    self-triggered loop) — an explicit negative declaration:',
+        '      { "defectClass": "unbounded-self-action", "closure": "n/a",',
+        '        "reason": "one-shot user-driven action, not a self-triggered loop" }',
+        '',
+        '  (Standard: docs/STANDARDS-REGISTRY.md → "Capacity Safety — No Unbounded',
+        '  Self-Action". Spec: docs/specs/self-action-convergence.md → Part E3.)',
+      ].join('\n'),
+    );
+  }
+
+  // Mirror check (the display-only human mirror — the two hosts #1347 uses).
+  // Fail-OPEN if the artifact is unreadable.
+  const artifactRel = trace && (trace.sideEffectsPath || trace.artifactPath);
+  if (artifactRel) {
+    const abs = path.resolve(ROOT, artifactRel);
+    if (fs.existsSync(abs)) {
+      const content = fs.readFileSync(abs, 'utf8');
+      if (!/unbounded-self-action/.test(content)) {
+        blockCommit(
+          inScopeFilesArg,
+          [
+            'Self-Action Convergence gate (mirror):',
+            '  The trace declares the unbounded-self-action class, but the staged',
+            `  side-effects artifact (${artifactRel}) never mentions it — the`,
+            '  display-only human mirror must AGREE with the machine-readable trace',
+            '  declaration (the two hosts #1347 uses).',
+            '',
+            '  Add the class-closure declaration to the side-effects artifact\'s',
+            '  "## Class-Closure Declaration" section.',
+          ].join('\n'),
+        );
+      }
+    }
+  }
+}
+
 function blockCommit(files, reason) {
   console.error('');
   console.error('╔════════════════════════════════════════════════════════════════════╗');
@@ -1065,7 +1156,7 @@ function blockCommit(files, reason) {
 // fire, the line just evaporated with the worktree). If the commit is later
 // blocked by the gate, the staged line simply rides the retry commit — both
 // lines describe real gate evaluations.
-function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, riskFloorReasons, belowFloor, files, loc, causalAutopsy = null }) {
+function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, riskFloorReasons, belowFloor, files, loc, causalAutopsy = null, classClosure = null }) {
   try {
     fs.mkdirSync(DECISIONS_DIR, { recursive: true });
     const ts = new Date().toISOString();
@@ -1097,6 +1188,12 @@ function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, risk
       // This is THE meta-analysis substrate: convergence vs whack-a-mole is
       // a query over these entries, not archaeology.
       causalAutopsy,
+      // Class-closure declaration (docs/specs/class-closure-gate.md +
+      // self-action-convergence.md → E3): persisted from the instar-dev TRACE
+      // into the machine-readable decision-audit host the CI class-closure lint
+      // reads — closing the chicken-and-egg (the trace is authored before the
+      // commit; the entry is written by this hook). null = not declared.
+      classClosure,
       // Finalized by the process exit handler below: 'pass' when the gate
       // allowed the commit, 'blocked' otherwise. The riding-the-retry design
       // (a blocked evaluation's entry rides the next successful commit, see
@@ -1231,6 +1328,7 @@ function enforceTier1(trace, traceFile) {
 
   assertFrameworkGenerality(inScopeFiles, trace);
   assertOperatorSurfaceQuality(staged, trace);
+  assertSelfActionDeclared(addedDiffText, inScopeFiles, trace);
 
   console.error(
     `[instar-dev-precommit] OK (Tier 1) — trace ${traceName} covers ${inScopeFiles.length} in-scope file(s), ` +

package/scripts/lib/self-action-detect.mjs

@@ -0,0 +1,162 @@
+// self-action-detect.mjs — the SINGLE shared detector for the
+// `unbounded-self-action` defect class (docs/specs/self-action-convergence.md
+// → Part E1). Dependency-free ESM, mirroring how the class-closure gate shares
+// `class-closure-grader.mjs` as one library used by both the CI lint and the
+// commit gate.
+//
+// It answers three questions, all deterministically (Signal vs. Authority — it
+// FORCES a declaration, it never LLM-guesses):
+//   1. Does an ADDED diff introduce/modify a self-action EMIT? (the trigger for
+//      the class declaration requirement — emit-anchored, comment/prose-safe).
+//   2. Is a file a self-action CONTROLLER source file? (the scope predicate the
+//      CI lint + forcing lint use).
+//   3. What is the raw verb-token set? (the single source the D3 ratchet's
+//      registry `actionVerb`s must be a subset of — coherence test E5/D5).
+//
+// SAFETY ASYMMETRY (fail-OPEN on tooling failure — the E3/E2 gates rely on it):
+// empty/blank added-diff text returns FALSE (no fire). A false-negative here is
+// backstopped by the CI lint; a false-positive that blocked all commits would
+// sever the developer's ability to ship. The obfuscation limit (a string-based
+// detector cannot beat DELIBERATE evasion — `const v='swap'; self[v]()`) is the
+// known gap named in the spec, tracked to the follow-on funnel (Part B).
+
+// ── The self-action verb TOKENS ────────────────────────────────────────────
+// Seeded from the synthesis taxonomy (restart|swap|respawn|spawn|notify|retry|
+// re-drive|kill) and widened to the concrete instar symbols those verbs appear
+// as. This is the SINGLE source: the emit regex is built from it, and the D3
+// ratchet's registry `actionVerb`s are asserted to each contain one of these
+// tokens (so a new controller can never register a verb the detector is blind
+// to). Keep alphabetized-by-family for review.
+export const SELF_ACTION_VERB_TOKENS = Object.freeze([
+  // restart / respawn family
+  'refresh', 'respawn', 'restart',
+  // reap / kill family
+  'reap', 'requestKill', 'kill',
+  // swap family
+  'swap', 'proactiveSwap',
+  // spawn family
+  'spawnSession', 'spawn',
+  // notify / emit family
+  'notify', 'createForumTopic', 'createAttentionItem', 'sendToTopic',
+  // re-drive / re-pin family
+  'reDrive', 'redrive', 'rePin', 'repin',
+  // retry / nudge / escalate family
+  'retry', 'nudge', 'escalate',
+]);
+
+// A call in an EMITTING position: `verb(` (a bare/qualified call) OR `.verb(`
+// (a method call). A bare NOUN in a comment or prose line does not match
+// because the line-level filter in addedDiffIntroducesSelfAction strips
+// comment/prose lines before testing; the regex itself additionally requires a
+// `(` so `// swap accounts` (no paren) never matches even if the filter is
+// bypassed.
+const CALL_VERBS = SELF_ACTION_VERB_TOKENS.join('|');
+// Method-position verbs — the subset that commonly appears as `obj.verb(`.
+const METHOD_VERBS = [
+  'refresh', 'respawn', 'restart', 'swap', 'reap', 'kill', 'retry',
+  'escalate', 'nudge', 'notify', 'spawn', 'redrive',
+].join('|');
+
+export const SELF_ACTION_EMIT = new RegExp(
+  `\\b(${CALL_VERBS})\\s*\\(|\\.\\s*(${METHOD_VERBS})\\s*\\(`,
+);
+
+// ── Comment / prose line detection ─────────────────────────────────────────
+// The added-diff text handed to us is already `+`-stripped by the precommit
+// hook (or a raw file line, for the forcing lint). We skip lines that are
+// obviously NOT an emitting statement — a comment, a markdown/prose line, an
+// import, or a string-literal-only mention — before testing the emit regex.
+function isNonEmitLine(line) {
+  const t = line.trimStart();
+  if (t === '') return true;
+  // Line comments / block-comment continuations / hash comments.
+  if (/^(\/\/|\*|\/\*|#)/.test(t)) return true;
+  // Import / export-from lines mention symbols but do not call them.
+  if (/^(import|export)\b/.test(t) && /\bfrom\b/.test(t)) return true;
+  return false;
+}
+
+/**
+ * Does the ADDED diff text introduce/modify a self-action emit? Emitting
+ * position only — a bare noun in a comment/prose line does NOT match. Empty /
+ * blank text → false (fail-open on a tooling hiccup).
+ * @param {string} addedDiffText  concatenation of added lines (`+`-stripped)
+ * @returns {boolean}
+ */
+export function addedDiffIntroducesSelfAction(addedDiffText) {
+  if (typeof addedDiffText !== 'string' || addedDiffText.trim() === '') return false;
+  for (const line of addedDiffText.split('\n')) {
+    if (isNonEmitLine(line)) continue;
+    if (SELF_ACTION_EMIT.test(line)) return true;
+  }
+  return false;
+}
+
+// ── Controller-source scope predicate ──────────────────────────────────────
+// A `src/` file whose NAME matches the controller shape, OR any file that
+// carries the `@self-action-controller` registration marker in its content.
+const CONTROLLER_NAME =
+  /(Monitor|Sentinel|Reaper|Beacon|Engine|Scheduler|Watchdog|Poller|Manager)\.ts$/;
+const CONTROLLER_MARKER = /@self-action-controller\s*:/;
+
+/**
+ * Is `file` a self-action controller source file (for scope)?
+ * @param {string} file  repo-relative path
+ * @param {string} [contentMaybe]  optional file content, to catch the marker
+ * @returns {boolean}
+ */
+export function isSelfActionControllerFile(file, contentMaybe) {
+  const f = String(file ?? '');
+  if (typeof contentMaybe === 'string' && CONTROLLER_MARKER.test(contentMaybe)) return true;
+  if (!f.startsWith('src/')) return false;
+  if (f.endsWith('.test.ts')) return false;
+  const base = f.split('/').pop() ?? f;
+  return CONTROLLER_NAME.test(base);
+}
+
+/**
+ * Parse the `@self-action-controller: <id>` marker id out of file content, if
+ * present. Returns the id string, or null. (Used by the forcing lint to
+ * cross-check the marker id against the SELF_ACTION_CONTROLLERS registry.)
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function selfActionControllerMarkerId(content) {
+  if (typeof content !== 'string') return null;
+  const m = content.match(/@self-action-controller\s*:\s*([A-Za-z0-9_-]+)/);
+  return m ? m[1] : null;
+}
+
+export const SELF_ACTION_CLASS_ID = 'unbounded-self-action';
+
+/**
+ * The PURE decision behind the instar-dev pre-commit gate `assertSelfActionDeclared`
+ * (Part E3). Extracted here so the decision is a tested function (Structure >
+ * Willpower) that BOTH the enforceTier1 and Tier-2 call sites exercise via one
+ * gate. FAIL-OPEN: no self-action emit, or no src/ file touched -> not required.
+ * A declaration is satisfied by a real classClosure (guard|gap) OR an explicit
+ * negative declaration (closure:'n/a' + reason).
+ * @param {{ addedDiffText: string, inScopeFiles: string[], classClosure: any }} input
+ * @returns {{ required: boolean, satisfied: boolean, reason: string }}
+ */
+export function selfActionDeclarationVerdict({ addedDiffText, inScopeFiles, classClosure }) {
+  if (!addedDiffIntroducesSelfAction(addedDiffText)) {
+    return { required: false, satisfied: true, reason: 'no self-action emit in added diff (fail-open)' };
+  }
+  const srcTouched = (inScopeFiles || []).some((f) => String(f).startsWith('src/'));
+  if (!srcTouched) {
+    return { required: false, satisfied: true, reason: 'no src/ file touched (false-positive-safe)' };
+  }
+  const cc = classClosure;
+  const named = cc && typeof cc === 'object' && cc.defectClass === SELF_ACTION_CLASS_ID;
+  const isRealDecl = Boolean(named && (cc.closure === 'guard' || cc.closure === 'gap'));
+  const isNegative = Boolean(
+    named && cc.closure === 'n/a' && typeof cc.reason === 'string' && cc.reason.trim().length > 0,
+  );
+  const satisfied = isRealDecl || isNegative;
+  return {
+    required: true,
+    satisfied,
+    reason: satisfied ? 'unbounded-self-action declared' : 'missing unbounded-self-action declaration',
+  };
+}

package/scripts/lint-no-unregistered-self-action.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// safe-git-allow: CI-only lint — single read-only `git diff --cached --name-only`
+//   to list staged files; runs on runners where the TS SafeGitExecutor is not
+//   importable from a standalone .js.
+/**
+ * lint-no-unregistered-self-action.js — the FORCING lint for the
+ * `unbounded-self-action` defect class (docs/specs/self-action-convergence.md
+ * → Part D4). Structural twin of `lint-no-unbounded-llm-spawn.js`, and — per
+ * both external reviewers (codex + gemini) — emit-anchored and fail-closed, NOT
+ * shape-heuristic: it keys on the self-action EMIT itself (the shared detector,
+ * scripts/lib/self-action-detect.mjs), so a developer cannot dodge it by
+ * renaming the driver method.
+ *
+ * THE RULE (fail-closed once enforcing): a self-action CONTROLLER source file
+ * (the E1 scope predicate — a src/ *Monitor|*Sentinel|*Reaper|*Beacon|*Engine|
+ * *Scheduler|*Watchdog|*Poller|*Manager.ts, or any file carrying the marker)
+ * that contains a self-action emit MUST EITHER:
+ *   - register — carry `@self-action-controller: <id>` AND have <id> present in
+ *     SELF_ACTION_CONTROLLERS (so the convergence ratchet covers it), OR
+ *   - be allowlisted — appear in ALLOWLIST with a stated reason that it is a
+ *     genuine one-shot / user-driven action, not a self-triggered loop.
+ * Anything else is a violation.
+ *
+ * ROLLOUT (matches the class-closure gate it composes with): REPORT-ONLY by
+ * default — it prints the population of unregistered controllers and ALWAYS
+ * exits 0. It exits nonzero ONLY when `prGate.classClosure.enabled && !dryRun`
+ * (the enforcing flip the operator makes on measured population). This is
+ * "enforcement first, report-only, graduate after a clean soak."
+ *
+ * SCOPE (report-only): controller-SHAPE files only (the E1 predicate) — the
+ * exact files the class is about — so the telemetry is actionable rather than a
+ * repo-wide wall of every `retry(` in src/. Widening to ALL src/ emits is gated
+ * behind the enforcing flip + the obfuscation-resistant funnel (Part B).
+ * <!-- tracked: CMT-1911 -->
+ *
+ * HONEST COVERAGE LIMIT (both reviewers, recorded): a string-based lint deters
+ * ACCIDENTAL unbounded loops; it is not a hard boundary against DELIBERATE
+ * obfuscation (`const v='swap'; self[v]()`). The obfuscation-resistant closure
+ * is the funnel (Part B); deliberately obfuscating an emit to evade this gate is
+ * a conduct violation, not a clever workaround.
+ *
+ * Usage:
+ *   node scripts/lint-no-unregistered-self-action.js            # full repo
+ *   node scripts/lint-no-unregistered-self-action.js --staged   # staged files
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import {
+  SELF_ACTION_EMIT,
+  isSelfActionControllerFile,
+  selfActionControllerMarkerId,
+} from './lib/self-action-detect.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(__filename), '..');
+
+const SCAN_DIRS = ['src'];
+const EXTENSIONS = new Set(['.ts']);
+
+// ── Allowlist (closed). Adding an entry requires a stated reason that the
+//    file's self-action emit is a genuine one-shot / user-driven action or is
+//    otherwise bounded outside the registry — same governance as the spawn
+//    lint's allowlist. ─────────────────────────────────────────────────────
+const ALLOWLIST = new Set([
+  // The controller-registration harness itself names verbs + the marker.
+  'src/testing/selfActionRegistry.ts',
+]);
+
+/** Read the prGate.classClosure config, or the report-only default. */
+export function loadEnforcementConfig(repoRoot) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.instar', 'config.json'), 'utf-8'));
+    const cc = cfg && cfg.prGate && cfg.prGate.classClosure;
+    if (cc && typeof cc === 'object') {
+      return { enabled: cc.enabled === true, dryRun: cc.dryRun !== false };
+    }
+  } catch {
+    /* no config → report-only default */
+  }
+  return { enabled: false, dryRun: true };
+}
+
+/** Parse the registered controller ids out of the registry source (greppable `id: '...'`). */
+export function loadRegistryIds(registrySource) {
+  const ids = new Set();
+  if (typeof registrySource !== 'string') return ids;
+  const re = /\bid:\s*['"`]([A-Za-z0-9_-]+)['"`]/g;
+  let m;
+  while ((m = re.exec(registrySource)) !== null) ids.add(m[1]);
+  return ids;
+}
+
+/** A line is an emitting statement if it matches the detector AND is not a comment/prose line. */
+function lineIsEmit(line) {
+  const t = line.trimStart();
+  if (t === '' || /^(\/\/|\*|\/\*|#)/.test(t)) return false;
+  if (/^(import|export)\b/.test(t) && /\bfrom\b/.test(t)) return false;
+  return SELF_ACTION_EMIT.test(line);
+}
+
+/**
+ * Pure evaluation over a prepared file set — exported for tests.
+ * @param {{ files: string[], registryIds: Set<string>, allowlist?: Set<string>, readFile: (rel:string)=>string|null }} input
+ * @returns {{ violations: Array<{file:string, reason:string, line:number}>, considered: number }}
+ */
+export function evaluateSelfActionLint({ files, registryIds, allowlist = ALLOWLIST, readFile }) {
+  const violations = [];
+  let considered = 0;
+  for (const rel of files) {
+    const norm = rel.split(path.sep).join('/');
+    if (!EXTENSIONS.has(path.extname(norm))) continue;
+    if (/(^|\/)tests\//.test(norm) || /\.test\.ts$/.test(norm)) continue;
+    if (allowlist.has(norm)) continue;
+    const content = readFile(norm);
+    if (content == null) continue;
+    // Scope: a controller-shape file OR a file carrying the marker.
+    if (!isSelfActionControllerFile(norm, content)) continue;
+    // Does it emit a self-action?
+    const lines = content.split('\n');
+    let emitLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lineIsEmit(lines[i])) { emitLine = i + 1; break; }
+    }
+    if (emitLine === -1) continue; // a controller-shape file with no emit is fine
+    considered += 1;
+    // Registered? — carries the marker AND its id is in the registry.
+    const markerId = selfActionControllerMarkerId(content);
+    if (markerId && registryIds.has(markerId)) continue; // registered — the ratchet covers it
+    if (markerId && !registryIds.has(markerId)) {
+      violations.push({
+        file: norm,
+        line: emitLine,
+        reason: `carries @self-action-controller: ${markerId} but that id is NOT in SELF_ACTION_CONTROLLERS (register it in src/testing/selfActionRegistry.ts)`,
+      });
+      continue;
+    }
+    violations.push({
+      file: norm,
+      line: emitLine,
+      reason: 'a self-action controller with an unregistered emit — add /* @self-action-controller: <id> */ and register <id> in SELF_ACTION_CONTROLLERS (or allowlist it with a one-shot/user-driven reason)',
+    });
+  }
+  return { violations, considered };
+}
+
+// ── CLI: gather files, evaluate, report/enforce ────────────────────────────
+function listFiles() {
+  const staged = process.argv.includes('--staged');
+  if (staged) {
+    const out = execSync('git diff --cached --name-only', { cwd: ROOT, encoding: 'utf-8' });
+    return out.split('\n').filter(Boolean).filter((f) => EXTENSIONS.has(path.extname(f)));
+  }
+  const files = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (EXTENSIONS.has(path.extname(e.name))) files.push(path.relative(ROOT, full));
+    }
+  };
+  for (const d of SCAN_DIRS) walk(path.join(ROOT, d));
+  return files;
+}
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
+if (invokedDirectly) {
+  const registrySource = (() => {
+    try { return fs.readFileSync(path.join(ROOT, 'src', 'testing', 'selfActionRegistry.ts'), 'utf-8'); }
+    catch { return ''; }
+  })();
+  const registryIds = loadRegistryIds(registrySource);
+  const files = listFiles();
+  const { violations, considered } = evaluateSelfActionLint({
+    files,
+    registryIds,
+    readFile: (rel) => {
+      try { return fs.readFileSync(path.join(ROOT, rel), 'utf-8'); } catch { return null; }
+    },
+  });
+  const { enabled, dryRun } = loadEnforcementConfig(ROOT);
+  const enforcing = enabled && !dryRun;
+
+  console.log(`lint-no-unregistered-self-action: ${enforcing ? 'ENFORCING' : 'report-only'} — ` +
+    `${considered} controller-shape emitter(s) scanned, ${violations.length} unregistered.`);
+  for (const v of violations) {
+    console[enforcing ? 'error' : 'log'](`  ${v.file}:${v.line} — ${v.reason}`);
+  }
+  if (enforcing && violations.length > 0) {
+    console.error(`\nlint-no-unregistered-self-action: ${violations.length} violation(s). ` +
+      `See docs/specs/self-action-convergence.md (Part D4).`);
+    process.exit(1);
+  }
+  if (violations.length > 0) {
+    console.log('  (report-only — no build failure; the enforcing flip is gated on prGate.classClosure.dryRun:false after a measured clean soak.)');
+  }
+  process.exit(0);
+}

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

@@ -183,7 +183,14 @@ pool-wide question is answered by a proxied-on-read merged view." Not abstractio
 
 **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
+`docs/specs/class-closure-gate.md`) **— OR adds/modifies a self-triggered
+controller (the `unbounded-self-action` class: a loop, monitor, sentinel,
+reaper, scheduler, or recovery path that fires a restart / swap / respawn /
+spawn / notify / retry / re-drive / kill on its own — see
+`docs/specs/self-action-convergence.md`).** For the self-action case, author the
+convergence argument (control-loop edge + steady-state bound + settling brake)
+INTO `guardEvidence.howCaught`, and cite the ratchet
+`tests/unit/self-action-convergence.test.ts`. 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