instar 1.3.190 → 1.3.192

package/scripts/instar-dev-precommit.js

@@ -28,13 +28,15 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { checkEli16Overview } from './eli16-overview-check.mjs';
+import { checkEli16Overview, MIN_ELI16_CHARS } from './eli16-overview-check.mjs';
 import { verifyProposalDerivedRunbooks } from '../skills/instar-dev/scripts/verify-proposal-derived-runbook.mjs';
+import { classifyTier, decideRequirementSet } from './lib/classify-tier.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const ROOT = path.resolve(__dirname, '..');
 const TRACES_DIR = path.join(ROOT, '.instar', 'instar-dev-traces');
+const DECISIONS_LOG = path.join(ROOT, '.instar', 'instar-dev-decisions.jsonl');
 const WINDOW_MS = 60 * 60 * 1000; // 60 minutes
 const MIN_ARTIFACT_CHARS = 200;
 
@@ -135,6 +137,72 @@ if (bootstrapTrigger) {
   process.exit(0);
 }
 
+// ─── Step 3.5: compute + surface the tier signal ─────────────────────────
+// Pure classifier (scripts/lib/classify-tier.mjs). SIGNAL ONLY — the gate
+// SURFACES the suggestion; the agent DECLARES the real tier in its trace. The
+// classifier never decides for the agent and never blocks. (The Body and the
+// Mind: the body informs, the mind decides, the decision is audited.)
+
+let tierSignal = { suggestedTier: 2, sizeTier: 2, riskFloor: 1, reasons: [] };
+let totalChangedLoc = 0;
+{
+  let addedLines = 0;
+  let deletedLines = 0;
+  let addedDiffText = '';
+  try {
+    const numstat = execSync(
+      `git diff --cached --numstat -- ${inScopeFiles.map((f) => JSON.stringify(f)).join(' ')}`,
+      { cwd: ROOT, encoding: 'utf8' },
+    );
+    for (const line of numstat.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [a, d] = trimmed.split('\t');
+      // Binary files show "-\t-"; treat as 0 LOC.
+      addedLines += a === '-' ? 0 : parseInt(a, 10) || 0;
+      deletedLines += d === '-' ? 0 : parseInt(d, 10) || 0;
+    }
+  } catch {
+    // If numstat fails, leave LOC at 0 — sizeTier becomes 1, riskFloor still
+    // governs. We never crash the gate over a diff-stat hiccup.
+  }
+  try {
+    // Added-line-only diff text feeds the new-capability heuristic. We pull the
+    // full staged diff and keep only the added (`+`) lines, stripping the `+`.
+    const fullDiff = execSync(
+      `git diff --cached -- ${inScopeFiles.map((f) => JSON.stringify(f)).join(' ')}`,
+      { cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 },
+    );
+    addedDiffText = fullDiff
+      .split('\n')
+      .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+      .map((l) => l.slice(1))
+      .join('\n');
+  } catch {
+    // No added-diff text → classifier SKIPS the new-capability check (per spec).
+    addedDiffText = '';
+  }
+
+  totalChangedLoc = addedLines + deletedLines;
+
+  tierSignal = classifyTier({
+    inScopeFiles,
+    addedLines,
+    deletedLines,
+    addedDiffText: addedDiffText || undefined,
+  });
+
+  console.error(
+    `[instar-dev-precommit] tier signal: suggestedTier=${tierSignal.suggestedTier} ` +
+      `(size=${tierSignal.sizeTier}, riskFloor=${tierSignal.riskFloor}, ` +
+      `${addedLines + deletedLines} LOC across ${inScopeFiles.length} file(s))`,
+  );
+  if (tierSignal.reasons.length > 0) {
+    console.error('[instar-dev-precommit] risk-floor reasons:');
+    for (const r of tierSignal.reasons) console.error(`  • ${r}`);
+  }
+}
+
 // ─── Step 4: find a fresh trace ──────────────────────────────────────────
 
 if (!fs.existsSync(TRACES_DIR)) {
@@ -158,6 +226,75 @@ if (traceEntries.length === 0) {
   );
 }
 
+// ─── Step 4.5: read the agent's DECLARED tier + branch ───────────────────
+// The agent records its tier in the trace JSON. We peek the freshest fresh
+// trace to read `trace.tier` (1|2|3). decideRequirementSet() factors the pure
+// enforcement decision:
+//   - tier 1            → 'tier1-lite'  (ELI16 + side-effects staged; no spec)
+//   - tier 2 / 3        → 'tier2-full'  (the EXISTING full validation, unchanged)
+//   - missing / no tier → 'tier2-full'  (back-compat default — behaves as today)
+
+let declaredTier = null;
+let tierReasoning = '';
+let freshestTrace = null;
+try {
+  freshestTrace = JSON.parse(fs.readFileSync(traceEntries[0].file, 'utf8'));
+  if (freshestTrace && (freshestTrace.tier === 1 || freshestTrace.tier === 2 || freshestTrace.tier === 3)) {
+    declaredTier = freshestTrace.tier;
+  }
+  if (freshestTrace && typeof freshestTrace.tierReasoning === 'string') {
+    tierReasoning = freshestTrace.tierReasoning;
+  }
+} catch {
+  // Malformed freshest trace → declaredTier stays null → Tier-2 back-compat
+  // path (the existing Step 5 loop will surface the malformed-JSON attempt).
+}
+
+const slug = (freshestTrace && (freshestTrace.slug || freshestTrace.name)) || 'unknown';
+const decision = decideRequirementSet(declaredTier);
+
+// AUDIT (all in-scope cases): one JSON line, written regardless of branch.
+// belowFloor = the agent declared UNDER the risk-signaled floor. We never
+// block on it (the mind holds authority) — the record is the backstop.
+const belowFloor = declaredTier != null && declaredTier < tierSignal.riskFloor;
+writeDecisionAudit({
+  slug,
+  suggestedTier: tierSignal.suggestedTier,
+  declaredTier,
+  riskFloor: tierSignal.riskFloor,
+  riskFloorReasons: tierSignal.reasons,
+  belowFloor,
+  files: inScopeFiles.length,
+  loc: totalChangedLoc,
+});
+if (belowFloor) {
+  console.error('');
+  console.error('┌──────────────────────────────────────────────────────────────────┐');
+  console.error('│  ⚠ BELOW RISK FLOOR — declared tier is under the risk-signaled    │');
+  console.error('│    floor. NOT blocked (you hold authority), but recorded.         │');
+  console.error('└──────────────────────────────────────────────────────────────────┘');
+  console.error(`  declared Tier ${declaredTier} < risk floor ${tierSignal.riskFloor}. Risk signals:`);
+  for (const r of tierSignal.reasons) console.error(`    • ${r}`);
+  if (tierReasoning) console.error(`  Your tierReasoning: ${tierReasoning}`);
+  console.error(`  Recorded to ${path.relative(ROOT, DECISIONS_LOG)} (belowFloor:true).`);
+  console.error('');
+}
+
+// ─── Step 4.6: Tier-1 lite path ──────────────────────────────────────────
+// When the agent declared Tier 1, the requirement set is intentionally lighter:
+// a staged ELI16 (the "request" ELI16) + a staged side-effects artifact
+// (sha-matched if the trace records a sha) — and NO converged/approved spec.
+// (The tests/lint requirement from the spec lives in the pre-PUSH gate, not
+// here: this pre-COMMIT hook checks ARTIFACTS only.)
+if (decision.requirementSet === 'tier1-lite') {
+  enforceTier1(freshestTrace, traceEntries[0].file);
+  // enforceTier1 either passes through (process.exit(0)) or blockCommit()s.
+}
+
+// ── Otherwise: Tier-2 / Tier-3 / no-tier → the EXISTING full validation ──
+// Everything below (Steps 5–8) is unchanged. A Tier-3 project step is just a
+// Tier-2 spec; nothing new is enforced for "Tier 3" at the gate.
+
 // ─── Step 5: validate most recent trace against staged files ─────────────
 
 let validTrace = null;
@@ -539,3 +676,144 @@ function blockCommit(files, reason) {
   console.error('');
   process.exit(1);
 }
+
+// ─── Audit writer ─────────────────────────────────────────────────────────
+// Append exactly one JSON line to .instar/instar-dev-decisions.jsonl for every
+// in-scope commit (regardless of tier branch). Best-effort: a logging failure
+// must never crash the gate.
+function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, riskFloorReasons, belowFloor, files, loc }) {
+  try {
+    fs.mkdirSync(path.dirname(DECISIONS_LOG), { recursive: true });
+    fs.appendFileSync(
+      DECISIONS_LOG,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        slug,
+        suggestedTier,
+        declaredTier,
+        // riskFloor (the number) keeps the line self-contained for later review
+        // without re-running the classifier — not just the derived belowFloor.
+        riskFloor,
+        riskFloorReasons,
+        belowFloor,
+        files,
+        loc,
+      }) + '\n',
+    );
+  } catch {
+    // best-effort — never block on audit I/O
+  }
+}
+
+// ─── Tier-1 lite enforcement ──────────────────────────────────────────────
+// Tier-1 requirement set: a staged ELI16 (trace.eli16Path) passing the length
+// check + a staged side-effects artifact (trace.sideEffectsPath, sha-matched if
+// trace.artifactSha256 is present). NO specPath / review-convergence / approved.
+// On success this PASSES the whole gate (process.exit(0)); on any failure it
+// blockCommit()s with a Tier-1-specific message.
+function enforceTier1(trace, traceFile) {
+  const traceName = path.basename(traceFile);
+
+  // ── ELI16 (request overview) ──
+  const eli16Rel = trace.eli16Path;
+  if (!eli16Rel) {
+    blockCommit(
+      inScopeFiles,
+      [
+        `Tier-1 trace ${traceName} does not declare an ELI16 overview (trace.eli16Path is missing).`,
+        '',
+        'A Tier-1 commit still requires a plain-English ELI16 overview of the',
+        'change. Write it, stage it, and set "eli16Path": "<relative-path>" in the trace.',
+      ].join('\n'),
+    );
+  }
+  const eli16Abs = path.resolve(ROOT, eli16Rel);
+  if (!fs.existsSync(eli16Abs)) {
+    blockCommit(
+      inScopeFiles,
+      `Tier-1 ELI16 overview ${eli16Rel} (trace.eli16Path) does not exist.`,
+    );
+  }
+  if (!staged.includes(eli16Rel)) {
+    blockCommit(
+      inScopeFiles,
+      [
+        `Tier-1 ELI16 overview ${eli16Rel} is not staged for commit.`,
+        'It must ship alongside the change.',
+      ].join('\n'),
+    );
+  }
+  const eli16Content = fs.readFileSync(eli16Abs, 'utf8');
+  if (eli16Content.trim().length < MIN_ELI16_CHARS) {
+    blockCommit(
+      inScopeFiles,
+      [
+        `Tier-1 ELI16 overview ${eli16Rel} is too short`,
+        `(${eli16Content.trim().length} chars, need ${MIN_ELI16_CHARS}).`,
+        '',
+        "A stub isn't an overview — write a real one.",
+        'See skills/instar-dev/templates/eli16-overview.md for the expected shape.',
+      ].join('\n'),
+    );
+  }
+
+  // ── Side-effects artifact ──
+  const sideEffectsRel = trace.sideEffectsPath;
+  if (!sideEffectsRel) {
+    blockCommit(
+      inScopeFiles,
+      [
+        `Tier-1 trace ${traceName} does not declare a side-effects artifact (trace.sideEffectsPath is missing).`,
+        '',
+        'A Tier-1 commit still requires a side-effects review artifact. Write it,',
+        'stage it, and set "sideEffectsPath": "<relative-path>" in the trace.',
+      ].join('\n'),
+    );
+  }
+  const sideEffectsAbs = path.resolve(ROOT, sideEffectsRel);
+  if (!fs.existsSync(sideEffectsAbs)) {
+    blockCommit(
+      inScopeFiles,
+      `Tier-1 side-effects artifact ${sideEffectsRel} (trace.sideEffectsPath) does not exist.`,
+    );
+  }
+  if (!staged.includes(sideEffectsRel)) {
+    blockCommit(
+      inScopeFiles,
+      [
+        `Tier-1 side-effects artifact ${sideEffectsRel} is not staged for commit.`,
+        'It must ship alongside the change.',
+      ].join('\n'),
+    );
+  }
+  const sideEffectsContent = fs.readFileSync(sideEffectsAbs, 'utf8');
+  if (sideEffectsContent.trim().length < MIN_ARTIFACT_CHARS) {
+    blockCommit(
+      inScopeFiles,
+      `Tier-1 side-effects artifact ${sideEffectsRel} is too short ` +
+        `(${sideEffectsContent.trim().length} chars, need ${MIN_ARTIFACT_CHARS}).`,
+    );
+  }
+  // sha-match exactly as the existing artifact logic, when a sha is recorded.
+  if (trace.artifactSha256) {
+    const sha = crypto.createHash('sha256').update(sideEffectsContent).digest('hex');
+    if (trace.artifactSha256 !== sha) {
+      blockCommit(
+        inScopeFiles,
+        [
+          `Tier-1 side-effects artifact ${sideEffectsRel} sha mismatch —`,
+          `trace records ${String(trace.artifactSha256).slice(0, 12)}… but the staged bytes hash to ${sha.slice(0, 12)}….`,
+          `If the current artifact is correct, set "artifactSha256": "${sha}" in the trace,`,
+          're-stage BOTH the artifact and the trace, and commit fresh (do NOT amend).',
+        ].join('\n'),
+      );
+    }
+  }
+
+  console.error(
+    `[instar-dev-precommit] OK (Tier 1) — trace ${traceName} covers ${inScopeFiles.length} in-scope file(s), ` +
+      `ELI16 ${eli16Rel} (${eli16Content.trim().length} chars) + side-effects ${sideEffectsRel} staged & verified. ` +
+      `No converged spec required for Tier 1.`,
+  );
+  process.exit(0);
+}

package/scripts/lib/classify-tier.mjs

@@ -0,0 +1,191 @@
+/**
+ * classify-tier.mjs — pure tier classifier for the instar-dev commit gate.
+ *
+ * Step A of the Tiered Development Process
+ * (docs/specs/tier-classifier-and-tier1-path-spec.md).
+ *
+ * Computes a TIER SIGNAL from a staged change. This is signal only — the gate
+ * SURFACES the suggestion, but the agent (the mind) DECLARES the actual tier in
+ * its trace. This module never decides the tier for the agent and never blocks.
+ *
+ * `classifyTier({ inScopeFiles, addedLines, deletedLines, addedDiffText })`
+ *   → { suggestedTier, sizeTier, riskFloor, reasons }
+ *
+ *   - sizeTier: 1 when (addedLines + deletedLines) <= SIZE_LOC AND
+ *     inScopeFiles.length <= SIZE_FILES, else 2.
+ *   - riskFloor: starts at 1, RAISED to >= 2 by any safety-invariant proximity,
+ *     irreversibility, migration/fleet-rollout, or new-capability signal (each
+ *     pushes a reason).
+ *   - suggestedTier = max(sizeTier, riskFloor). NEVER 3 — Tier 3 is declared
+ *     (an approved project step), not auto-suggested.
+ */
+
+// ─── Tunable size thresholds ─────────────────────────────────────────────
+export const SIZE_LOC = 40;
+export const SIZE_FILES = 3;
+
+// ─── Risk signal: safety-invariant proximity (path-based) ────────────────
+// An in-scope path matching any of these raises the risk floor to >= 2.
+const SAFETY_INVARIANT_PATTERNS = [
+  { regex: /secret/i, label: 'SecretDrop / never-on-disk invariant' },
+  { regex: /relay/i, label: 'relay / delivery path' },
+  { regex: /Telegram.*Adapter/, label: 'Telegram adapter' },
+  { regex: /\bauth\b/i, label: 'auth path' },
+  { regex: /token/i, label: 'token handling' },
+  { regex: /SafeFsExecutor/, label: 'SafeFsExecutor (destructive-fs funnel)' },
+  { regex: /SafeGitExecutor/, label: 'SafeGitExecutor (destructive-git funnel)' },
+  { regex: /SourceTreeGuard/, label: 'SourceTreeGuard (source-tree mutation guard)' },
+  { regex: /Reaper/, label: 'session reaper' },
+  { regex: /session.*lifecycle/i, label: 'session lifecycle' },
+];
+
+// ─── Risk signal: irreversibility (path-based) ───────────────────────────
+const IRREVERSIBILITY_PATTERNS = [
+  { regex: /migration/i, label: 'migration' },
+  { regex: /schema/i, label: 'data-format / schema' },
+  { regex: /PostUpdateMigrator/, label: 'PostUpdateMigrator' },
+];
+
+// ─── Risk signal: migration / fleet-rollout surface (path-based) ─────────
+// A change here touches the machinery that rolls out to EVERY deployed agent
+// (the migration family) or the fleet release/publish path. This is where the
+// zombie-cleanup, lifeline-skew, and "one malformed NEXT.md jams all releases"
+// (#42) regressions lived — a one-line change here is never Tier-1. Distinct
+// reason string from irreversibility even though `PostUpdateMigrator` /
+// `migrate*` overlap, because the fleet-rollout blast radius is the concern.
+const FLEET_ROLLOUT_PATTERNS = [
+  { regex: /PostUpdateMigrator/, label: 'PostUpdateMigrator (fleet migration machinery)' },
+  { regex: /migrate/i, label: 'migrate*() migration family' },
+  { regex: /http-hook-templates/, label: 'http-hook-templates (settings/hook migration source)' },
+  { regex: /NEXT\.md/, label: 'upgrades/NEXT.md (fleet release manifest)' },
+  // Release / publish scripts under scripts/ — the fleet publish path.
+  { regex: /^scripts\/.*release/i, label: 'release script (fleet publish path)' },
+  { regex: /^scripts\/.*publish/i, label: 'publish script (fleet publish path)' },
+];
+
+// ─── Risk signal: new capability (diff-text-based, only when provided) ───
+// Net-new added lines (the diff text passed in should be ADDED lines only;
+// the caller is responsible for that). Each heuristic emits a reason.
+const NEW_CAPABILITY_PATTERNS = [
+  {
+    // A new route registration: router.get( / router.post( / app.use( etc.
+    regex: /\brouter\.(get|post|put|patch|delete|use|all|options|head)\s*\(/,
+    label: 'new route (router.<verb>()',
+  },
+  {
+    regex: /\bexport\s+class\s+/,
+    label: 'new exported class / subsystem',
+  },
+  {
+    // A new config key — a quoted key followed by a colon, or an object-literal
+    // identifier key, that reads like a config surface addition. Conservative:
+    // require it to look like a JSON/TS config entry.
+    regex: /^[+]?\s*["']?[A-Za-z_][A-Za-z0-9_]*["']?\s*:\s*.+,?\s*$/m,
+    label: 'new config key',
+    // The generic key pattern is noisy on its own — gate it behind a hint that
+    // the diff is actually touching a config surface. See evaluation below.
+    requiresConfigHint: true,
+  },
+];
+
+// Heuristic hint that the added diff is touching a config SURFACE (not just any
+// object literal). Without this guard the bare `key: value` pattern fires on
+// almost every TS change. We only treat a `key: value` addition as a new config
+// key when the diff also mentions a recognizable config anchor.
+const CONFIG_SURFACE_HINT = /(ConfigDefaults|config\.json|defaultConfig|InstarConfig|\.config\b|configSchema)/;
+
+/**
+ * @param {object} input
+ * @param {string[]} input.inScopeFiles    Staged in-scope file paths.
+ * @param {number}   input.addedLines      Total added lines across inScopeFiles.
+ * @param {number}   input.deletedLines    Total deleted lines across inScopeFiles.
+ * @param {string} [input.addedDiffText]   Concatenated ADDED-line diff text. When
+ *                                          absent, the new-capability check is SKIPPED
+ *                                          (we never guess without the diff).
+ * @returns {{ suggestedTier: 1|2, sizeTier: 1|2, riskFloor: 1|2, reasons: string[] }}
+ */
+export function classifyTier({ inScopeFiles, addedLines, deletedLines, addedDiffText } = {}) {
+  const files = Array.isArray(inScopeFiles) ? inScopeFiles : [];
+  const added = Number.isFinite(addedLines) ? addedLines : 0;
+  const deleted = Number.isFinite(deletedLines) ? deletedLines : 0;
+
+  const reasons = [];
+
+  // ── Size tier ──
+  const totalLoc = added + deleted;
+  const sizeTier = totalLoc <= SIZE_LOC && files.length <= SIZE_FILES ? 1 : 2;
+
+  // ── Risk floor ──
+  let riskFloor = 1;
+  const raise = (reason) => {
+    riskFloor = Math.max(riskFloor, 2);
+    reasons.push(reason);
+  };
+
+  // (a) safety-invariant proximity — path-based
+  for (const file of files) {
+    for (const { regex, label } of SAFETY_INVARIANT_PATTERNS) {
+      if (regex.test(file)) {
+        raise(`safety-invariant proximity: ${file} matches ${label}`);
+      }
+    }
+  }
+
+  // (b) irreversibility — path-based
+  for (const file of files) {
+    for (const { regex, label } of IRREVERSIBILITY_PATTERNS) {
+      if (regex.test(file)) {
+        raise(`irreversibility: ${file} touches ${label}`);
+      }
+    }
+  }
+
+  // (b2) migration / fleet-rollout surface — path-based
+  for (const file of files) {
+    for (const { regex, label } of FLEET_ROLLOUT_PATTERNS) {
+      if (regex.test(file)) {
+        raise(`migration / fleet-rollout surface: ${file} touches ${label}`);
+      }
+    }
+  }
+
+  // (c) new capability — diff-text-based, only when addedDiffText is provided.
+  // If absent, SKIP entirely (don't guess).
+  if (typeof addedDiffText === 'string' && addedDiffText.length > 0) {
+    for (const { regex, label, requiresConfigHint } of NEW_CAPABILITY_PATTERNS) {
+      if (requiresConfigHint && !CONFIG_SURFACE_HINT.test(addedDiffText)) {
+        continue;
+      }
+      if (regex.test(addedDiffText)) {
+        raise(`new capability: ${label} added`);
+      }
+    }
+  }
+
+  // ── Suggested tier ── NEVER 3.
+  const suggestedTier = Math.max(sizeTier, riskFloor);
+
+  return { suggestedTier, sizeTier, riskFloor, reasons };
+}
+
+/**
+ * decideRequirementSet(declaredTier) — pure helper factoring the gate's
+ * tier-enforcement DECISION so it is unit-testable without git/fs mocking.
+ *
+ * Given the agent's DECLARED tier (from the trace; `null`/`undefined` when no
+ * trace or no `tier` field), return WHICH requirement set the gate enforces.
+ *
+ *   - null/undefined (or any non-1/2/3 value) → 'tier2-full' (back-compat default)
+ *   - 1 → 'tier1-lite'
+ *   - 2 or 3 → 'tier2-full' (a Tier-3 project step is just a Tier-2 spec)
+ *
+ * @param {number|null|undefined} declaredTier
+ * @returns {{ requirementSet: 'tier1-lite'|'tier2-full', resolvedTier: 1|2 }}
+ */
+export function decideRequirementSet(declaredTier) {
+  if (declaredTier === 1) {
+    return { requirementSet: 'tier1-lite', resolvedTier: 1 };
+  }
+  // 2, 3, missing, or anything else → the existing full Tier-2 requirement set.
+  return { requirementSet: 'tier2-full', resolvedTier: 2 };
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-01T20:17:17.015Z",
-  "instarVersion": "1.3.190",
+  "generatedAt": "2026-06-02T00:19:44.300Z",
+  "instarVersion": "1.3.192",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.191.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The instar-dev commit gate now computes a **tier signal** (size + risk) for each staged
+change and prints it, the developing agent **declares** the tier in its trace, and the
+gate enforces the **chosen** tier's requirement set — adding a lighter **Tier-1 path**
+(ELI16 + side-effects, no pre-approved converged spec) for small, low-risk changes. Every
+decision is recorded to `.instar/instar-dev-decisions.jsonl`. This is Step A of the
+tiered-development project and the first executable instance of the constitution's
+**The Body and the Mind**: the gate *informs*, the agent *decides*, the decision is
+*audited*.
+
+## What to Tell Your User
+
+Nothing to do — this only affects how the agent commits changes to instar itself. Small
+changes now move through a lighter lane (overview + side-effects note), bigger changes
+still get the full spec. The agent's tier choice and the gate's suggestion are logged.
+
+## Summary of New Capabilities
+
+- `scripts/lib/classify-tier.mjs` — pure tier classifier (size + risk → suggested tier).
+- `instar-dev-precommit.js` — prints the tier signal, routes by the declared tier, audits
+  the decision; Tier-1 path requires ELI16 + side-effects (no converged spec). No declared
+  tier → the existing Tier-2 requirement set, byte-for-byte (back-compat).
+- `write-trace.mjs` — `--tier`, `--tier-reasoning`, `--eli16-path`, `--side-effects-path`
+  flags; `--spec` optional when `--tier 1`.
+
+## Evidence
+
+- `npx tsc --noEmit` exit 0; Step-A unit tests green (classify-tier 47, write-trace-tier 5,
+  gate -deferrals/-sha-error 13/1), including a named no-tier back-compat regression and
+  the audit-line shape (with `riskFloor`).
+- This very commit dogfoods the change: it is declared **Tier 2** in its own trace.

package/upgrades/1.3.192.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Spec-review-convergence's external **cross-model reviewer** is now real and framework-native:
+instead of a placeholder API path, it detects the installed **codex CLI** and runs a
+GPT-tier second opinion through the existing hardened codex provider — so any instar agent
+with codex gets cross-model review for free, no API keys. When no supported reviewer is
+installed (or a call fails, or convergence is abbreviated) the spec carries a loud,
+honest `cross-model-review:` flag; the review is **signal, never a gate**. Step B of the
+tiered-development project.
+
+## What to Tell Your User
+
+Nothing to do — this only affects how the agent reviews its own instar specs. Specs now get
+a real outside-model opinion when codex is present, and a clearly-marked note when they
+don't, so a spec that never got an external review can't quietly look like it did.
+
+## Summary of New Capabilities
+
+- `src/core/crossModelReviewer.ts` — codex-CLI reviewer detection + a supported-reviewer
+  registry + the reviewer driver (via the existing codex provider) + the honest flag
+  machinery (`codex-cli:<model>` / `degraded` / `degraded-all-rounds` / `unavailable` /
+  `skipped-abbreviated`), with deterministic, named context truncation.
+- `skills/spec-converge/scripts/cross-model-review.mjs` — the CLI the convergence skill
+  calls; `write-convergence-tag.mjs` gains `--cross-model-review`; `SKILL.md` + the reviewer
+  prompt template now describe the real, inlined-context, single-codex-pass mechanism.
+
+## Evidence
+
+- `npx tsc --noEmit` exit 0; Step-B tests 53 green (45 + 5 unit, 3 integration); `npm run
+  lint` green. Detection live-validated on this host: `{"available":true,
+  "framework":"codex-cli","model":"gpt-5.5"}`.
+- Dev-only tooling: `/spec-converge` is not shipped to end-agent homes, so no migration.

package/upgrades/side-effects/codex-crossreview-stepB.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Cross-model review on the codex CLI (Step B)
+
+**Slug:** `codex-crossreview-stepB`
+**Date:** 2026-06-01
+**Author:** echo
+**Spec:** `docs/specs/codex-crossreview-stepB-spec.md` (approved by Justin + abbreviated convergence, 5 findings folded)
+**Project:** Step B of the Tiered Development Process (`docs/projects/tiered-dev-process/PROJECT.md`)
+
+## Summary of the change
+
+Re-platforms the external **cross-model reviewer** in spec-review-convergence from the
+(placeholder) `/crossreview` API path onto the **installed codex CLI**, so every instar
+agent with codex gets a GPT-tier second opinion for free, no API keys. Honors the
+constitution's **Signal vs. Authority** — the external review is *signal*, never a
+blocking authority; an absent/failed reviewer is disclosed loudly, never faked.
+
+**Files changed (in-scope):**
+- `src/core/crossModelReviewer.ts` (NEW) — detection (`detectCodexReviewer` /
+  `detectCrossModelReviewer`: codex binary present AND OAuth `tokens.access_token` AND
+  Rule-1 clean), the `SUPPORTED_REVIEWER_FRAMEWORKS` registry (codex first; one entry per
+  future framework), the reviewer driver (routes the cross-model prompt through the
+  existing `buildIntelligenceProvider({framework:'codex-cli'})` → gpt-5.5, 120s, reusing
+  the provider's env allowlist + the factory circuit breaker), `assembleReviewerPrompt`
+  (inlines the spec in full + referenced context under a 60KB budget with **deterministic**
+  priority order — constitutional docs first — and a truncation note that **names** the
+  partial + omitted docs), `parseReviewerReply` (never throws/zeroes), and the flag
+  machinery: `buildCrossModelFlag` + `aggregateRoundOutcomes` producing one of
+  `codex-cli:<model>` (ran) / `degraded` / `degraded-all-rounds` / `unavailable` /
+  `skipped-abbreviated`. Never throws, never blocks.
+- `skills/spec-converge/scripts/cross-model-review.mjs` (NEW) — the thin CLI the skill
+  shells out to (does only repo file-I/O — codex is sandboxed with no repo access —
+  delegating logic to compiled `dist/core/crossModelReviewer.js`; always exits 0).
+- `skills/spec-converge/scripts/write-convergence-tag.mjs` — `--cross-model-review` /
+  `--cross-model-reason` args writing the `cross-model-review:` frontmatter field
+  (idempotent, YAML-safe quoting).
+- `skills/spec-converge/SKILL.md` — replaced the `/crossreview` placeholder with the real
+  invocation; Phase 3 documents per-round aggregation (→ `degraded-all-rounds` when a
+  framework was present but **zero** rounds got a successful pass); Phase 4 renders a loud
+  `⚠` banner for **every** non-ran state (a real pass is the only unmarked one); Phase 5
+  the valid flag values. Internal reviewers + the Standards-Conformance Gate unchanged.
+
+**Files changed (not in-scope):** `skills/spec-converge/templates/reviewer-cross-model.md`
+(patched: spec + context are "inlined below" — no file-read instruction codex can't
+follow — and dropped the three-phantom-model GPT/Gemini/Grok framing → one codex pass);
+the spec + ELI16; tests (`tests/unit/crossModelReviewer.test.ts` 45,
+`tests/unit/write-convergence-tag-crossmodel.test.ts` 5,
+`tests/integration/cross-model-review-flow.test.ts` 3).
+
+## Blast radius
+
+Additive. The new module is pure/injectable except the one provider call (reusing the
+hardened codex provider). The convergence flow gains a real external reviewer where it had
+a placeholder; the internal reviewers, the lessons-aware (non-skippable) reviewer, and the
+Standards-Conformance gate are untouched. The reviewer never throws and never blocks — the
+worst case is a loudly-disclosed `unavailable` / `degraded` / `degraded-all-rounds` flag.
+The `cross-model-review:` flag is **disclosure, not a gate**: it does NOT touch the
+`review-convergence` + `approved` enforcement in `instar-dev-precommit.js`.
+
+## Risks considered
+
+- **Could a failed/absent review read as a clean pass?** No (convergence Finding 1/2): every
+  non-ran state carries a loud `⚠` banner, and a convergence where a framework was present
+  but *no* round ever succeeded collapses to a spec-level `degraded-all-rounds` (as loud as
+  `unavailable`) — "never actually got an external opinion" surfaces at spec level.
+- **Silent partial context?** No (Finding 4): truncation is deterministic (constitutional
+  docs first) and the note names the partial + fully-omitted docs.
+- **API-key leak through codex?** No — reuses `buildCodexChildEnv()`'s allowlist; Rule-1
+  (`validateRule1`) forbids an API-key-shaped credential; detection requires OAuth.
+- **Cost?** Worst case ~10 capable-tier calls per spec (the 10-round convergence cap × 1
+  call/round), bounded by the account circuit breaker. Stated in the spec.
+
+## Migration parity
+
+**None needed — verified.** `/spec-converge` is dev-only tooling: it is NOT in
+`package.json` `files[]` and NOT installed by `installBuiltinSkills()`, so it never lands
+in an end-agent home. No `PostUpdateMigrator` change. (The agents that *develop* instar get
+it from the repo.)
+
+## Tests / lint
+
+`npx tsc --noEmit` exit 0; Step-B tests 53 green (45+5 unit, 3 integration); `npm run lint`
+(tsc + destructive/LLM-http/url-log/codex-drift) green. (The worktree's ~28 pre-existing
+local failures — node v25.6.1 + real-config + tunnel — are independent and CI-green.)