instar 1.3.190 → 1.3.191

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.190",
+  "version": "1.3.191",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

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-01T22:39:21.302Z",
+  "instarVersion": "1.3.191",
   "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/side-effects/tier-classifier-and-tier1-path.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Tier classifier + Tier-1 PR path (Step A)
+
+**Slug:** `tier-classifier-and-tier1-path`
+**Date:** 2026-06-01
+**Author:** echo
+**Spec:** `docs/specs/tier-classifier-and-tier1-path-spec.md` (approved by Justin + abbreviated convergence)
+**Project:** Step A of the Tiered Development Process (`docs/projects/tiered-dev-process/PROJECT.md`)
+
+## Summary of the change
+
+Teaches the instar-dev commit gate to (1) compute + print a **tier signal** (size + risk),
+(2) let the agent **declare** the tier in its trace, (3) enforce the **chosen** tier's
+requirement set — adding a **Tier-1 path** (ELI16 + side-effects, no pre-approved
+converged spec) — and (4) **audit** every decision. First executable instance of the
+constitution's *The Body and the Mind*: the gate informs, the agent decides, the decision
+is recorded. Strictly additive: a commit with no declared tier behaves exactly as before.
+
+**Files changed (in-scope):**
+- `scripts/lib/classify-tier.mjs` (NEW) — pure `classifyTier({inScopeFiles, addedLines,
+  deletedLines, addedDiffText})` → `{suggestedTier, sizeTier, riskFloor, reasons}` +
+  `decideRequirementSet(declaredTier)`. Size tier (≤40 LOC / ≤3 files = 1). Risk floor
+  raised by safety-invariant proximity, irreversibility, migration/fleet-rollout, and
+  (diff-text-gated) new-capability. `suggestedTier = max(size, risk)`, never 3.
+- `scripts/instar-dev-precommit.js` — Step 3.5 computes + prints the signal (via
+  `git diff --cached --numstat`); Step 4.5 reads `trace.tier`/`trace.tierReasoning`,
+  routes via `decideRequirementSet`, writes one audit line to
+  `.instar/instar-dev-decisions.jsonl` (incl. `riskFloor` + `belowFloor`), and runs the
+  Tier-1 path (`enforceTier1`: staged ELI16 + side-effects, sha-matched) when `tier===1`.
+  **Tier-2/3/no-tier fall through to the existing Steps 5–8 unchanged.**
+- `skills/instar-dev/scripts/write-trace.mjs` — new flags `--tier`, `--tier-reasoning`,
+  `--eli16-path`, `--side-effects-path`; `--spec` optional when `--tier 1`. Undeclared
+  traces round-trip byte-identically to the legacy shape.
+
+**Files changed (tests, not in-scope):**
+- `tests/unit/classify-tier.test.ts` (NEW, 47) — size boundaries, every risk signal incl.
+  fleet-rollout, `max(size,risk)`, never-3, config-hint-gated new-capability.
+- `tests/unit/write-trace-tier.test.ts` (NEW, 5) — Tier-1/Tier-2/no-tier trace round-trips,
+  side-effects-path default, missing-ELI16 rejection.
+- `tests/unit/instar-dev-precommit-deferrals.test.ts` — named back-compat regression
+  (no-tier trace + approved spec passes the full Tier-2 path) + audit-line shape (incl.
+  `riskFloor`). `-sha-error.test.ts` — sandbox updated for the new static import.
+
+## Blast radius
+
+Additive and back-compatible. The classifier is pure (no I/O). The gate gains two new
+steps (3.5 signal print, 4.5 tier routing + audit) **before** the existing Steps 5–8,
+which are unchanged for Tier-2/no-tier. The default (no `tier` in trace) selects the exact
+current requirement set — verified by the named back-compat regression test. The only new
+relaxation is the Tier-1 path, still requiring ELI16 + side-effects. The risk floor is a
+loud, audited signal (`belowFloor`), never a silent downgrade; the audit is a learning
+signal, not a security boundary (PR review + the auto-merge spot-check are the human
+gates). New runtime cost: one `git diff --cached --numstat` + one classify call + one
+appended JSONL line per in-scope commit.
+
+## Risks considered
+
+- **Tier-1 as a loophole?** The agent declares its own tier; a risk change that evades the
+  heuristic globs isn't flagged `belowFloor`. Mitigation (documented in the spec §4): the
+  PR is the review surface for every Tier-1, the auto-merge operator spot-check is the
+  human gate, and `belowFloor` rates are reviewed on a cadence (Close the Loop) so blind
+  spots surface and the risk list grows.
+- **Breaking existing commits?** No — `no-tier → Tier-2` is byte-identical to today; named
+  regression test guards it.
+- **Leaking sensitive data?** No — the audit records tiers, reasons, file counts, LOC; no
+  content.
+
+## Migration parity
+
+`instar-dev-precommit.js` + `write-trace.mjs` ship in the instar repo for agents
+*developing* instar; they are not installed into arbitrary agent homes by `init`. No
+`PostUpdateMigrator` change for end agents. The instar-dev skill awareness update is a
+later project step (Step C).
+
+## Tests / lint
+
+`npx tsc --noEmit` exit 0; Step-A unit tests green (`classify-tier` 47, `write-trace-tier`
+5, gate `-deferrals`/`-sha-error` 13/1). Note: the worktree's full unit suite shows 28
+**pre-existing** failures (TunnelManager, watchdog-bind-probe, serendipity-capture,
+esm-compliance, no-silent-fallbacks) that fail **identically with and without** this change
+(verified by stash-test) — local-environment/harness/lint artifacts (real config + tunnel
+reachability + node v25.6.1), independent of Step A and green in clean CI.