instar 1.3.306 → 1.3.307

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.306",
+  "version": "1.3.307",
   "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

@@ -45,6 +45,23 @@ const TRACES_DIR = path.join(ROOT, '.instar', 'instar-dev-traces');
 // DECISIONS_DIR instead: distinct filenames can never conflict.
 // (The frozen legacy file remains at .instar/instar-dev-decisions.jsonl.)
 const DECISIONS_DIR = path.join(ROOT, '.instar', 'instar-dev-decisions');
+
+// Set by writeDecisionAudit; consumed by the process 'exit' handler that
+// finalizes the entry's verdict. BOTH the declaration AND the handler
+// registration live here, above the top-level audit call site — placed
+// after it, the declaration TDZ-throws inside writeDecisionAudit's
+// try/catch, and the handler registration is never even reached when
+// blockCommit exits first (top-level statements run in source order).
+let pendingAuditEntry = null;
+process.on('exit', (code) => {
+  if (!pendingAuditEntry) return;
+  try {
+    const { entryPath, entryData } = pendingAuditEntry;
+    entryData.verdict = code === 0 ? 'pass' : 'blocked';
+    fs.writeFileSync(entryPath, JSON.stringify(entryData, null, 2) + '\n');
+    execSync(`git add ${JSON.stringify(path.relative(ROOT, entryPath))}`, { cwd: ROOT });
+  } catch { /* best-effort — 'pending' is still more truthful than no verdict */ }
+});
 const WINDOW_MS = 60 * 60 * 1000; // 60 minutes
 const MIN_ARTIFACT_CHARS = 200;
 
@@ -811,23 +828,31 @@ function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, risk
     while (fs.existsSync(entryPath)) {
       entryPath = path.join(DECISIONS_DIR, `${ts.replace(/[:.]/g, '-')}-${safeSlug}-${n++}.json`);
     }
-    fs.writeFileSync(
-      entryPath,
-      JSON.stringify({
-        ts,
-        slug,
-        suggestedTier,
-        declaredTier,
-        // riskFloor (the number) keeps the entry self-contained for later review
-        // without re-running the classifier — not just the derived belowFloor.
-        riskFloor,
-        riskFloorReasons,
-        belowFloor,
-        files,
-        loc,
-      }, null, 2) + '\n',
-    );
+    const entryData = {
+      ts,
+      slug,
+      suggestedTier,
+      declaredTier,
+      // riskFloor (the number) keeps the entry self-contained for later review
+      // without re-running the classifier — not just the derived belowFloor.
+      riskFloor,
+      riskFloorReasons,
+      belowFloor,
+      files,
+      loc,
+      // 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
+      // header comment) is deliberate — but without a verdict, a rode-along
+      // entry written under a stale/unresolved trace slug READS as a real
+      // shipped decision for that slug. Live recurrence (2026-06-05): both
+      // echo (#836) and codey (#842) shipped mislabeled "unknown"/foreign-slug
+      // entries in one day. The verdict makes every entry self-describing.
+      verdict: 'pending',
+    };
+    fs.writeFileSync(entryPath, JSON.stringify(entryData, null, 2) + '\n');
     execSync(`git add ${JSON.stringify(path.relative(ROOT, entryPath))}`, { cwd: ROOT });
+    pendingAuditEntry = { entryPath, entryData };
     return entryPath;
   } catch {
     // best-effort — never block on audit I/O
@@ -835,6 +860,13 @@ function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, risk
   }
 }
 
+// ── Verdict finalization ──────────────────────────────────────────────────
+// The process 'exit' handler that finalizes each entry's verdict is
+// registered next to the pendingAuditEntry declaration near the top of this
+// file (it must be registered BEFORE the top-level gate flow can exit). One
+// hook covers every exit path: enforceTier1's process.exit(0), the Tier-2
+// fall-through, and every blockCommit.
+
 // ─── 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

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T15:43:57.729Z",
-  "instarVersion": "1.3.306",
+  "generatedAt": "2026-06-05T16:06:31.347Z",
+  "instarVersion": "1.3.307",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.307.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The instar-dev pre-commit gate's decision-audit entries gain a verdict field ('pass' | 'blocked', written as 'pending' and finalized by a process exit hook that also re-stages the corrected file). The riding-the-retry design is unchanged — blocked-run entries still ride the next successful commit — but each entry is now self-describing.
+
+## What to Tell Your User
+
+Nothing user-visible — contributor audit hygiene. Gate audit records that ride into a PR from earlier blocked attempts (often under an unresolved or stale slug) are now labeled as blocked evaluations instead of reading like real shipped decisions.
+
+## Summary of New Capabilities
+
+- Decision-audit entries carry verdict: pass | blocked (pending only if finalization itself failed). Reviewers can distinguish shipped decisions from rode-along blocked evaluations at a glance.
+
+## Evidence
+
+Live recurrence (2026-06-05, twice in one day): echo's PR #836 swept in a blocked-attempt entry labeled with a DIFFERENT PR's slug (the then-freshest stale trace), and codey's PR #842 shipped an "unknown"-slug entry from a pre-trace gate run — both read as real decisions and needed review-time explanation. Pinned by 2 new sandbox tests in tests/unit/instar-dev-precommit-audit-staging.test.ts (blocked run finalizes 'blocked' incl. the STAGED copy; passing Tier-1 run finalizes 'pass') alongside the existing 4; the development itself caught the source-order trap twice (TDZ on the shared variable, exit-before-registration on the hook) — both now documented in code comments and covered by the blocked-path test.

package/upgrades/gate-blocked-audit-hygiene.eli16.md

@@ -0,0 +1,11 @@
+# Gate audit entries now say whether the commit actually passed
+
+Every gated commit writes a small audit record — which tier the change declared, what the risk heuristic suggested, how big the diff was. By design, a record written during a BLOCKED attempt also survives: it gets staged, and when the developer fixes the problem and commits again, the old record rides along. The intent was honest bookkeeping — every gate evaluation leaves a trace.
+
+The problem: nothing in the record said whether the evaluation passed or was blocked. And blocked attempts often run before the developer's trace file is fully resolved, so the record gets written under the wrong name — the slug says "unknown", or worse, it carries the slug of some OTHER pull request whose stale trace happened to be the freshest file at that moment. The result reads like a real shipped decision for a change that never shipped under that name. This bit twice in one day: Echo's registry-fix PR carried a record labeled with a different PR's slug, and Codey's header PR carried an "unknown" record — both rode into main as confusing audit noise, and both had to be explained in review.
+
+The fix keeps the deliberate riding-the-retry design and makes every record self-describing: a **verdict** field, finalized the moment the gate process exits. Records start as "pending" when written, and a process exit hook — one hook covering every way the gate can finish — rewrites them as "pass" or "blocked" and re-stages the corrected file. A reviewer who sees verdict "blocked" next to a foreign slug now knows exactly what they're looking at: a failed evaluation under a stale trace, not a shipped decision.
+
+Two implementation traps are documented in the code because both actually fired during development: the shared variable and the exit hook must both live ABOVE the gate's main flow in the file, because the gate runs top-to-bottom and can exit (blocked) before ever reaching code placed lower down. The first draft had the hook at the bottom; blocked runs exited before the hook was registered, and the verdict silently stayed "pending" — caught by the new tests.
+
+Nothing changes about when records are written, staged, or how files are named. Old records without a verdict field remain valid history. Two new tests pin both sides: a blocked run's record finalizes as "blocked" (including the staged copy), and a passing Tier-1 run's record finalizes as "pass".

package/upgrades/side-effects/gate-blocked-audit-hygiene.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — Gate decision-audit verdict finalization
+
+**Version / slug:** `gate-blocked-audit-hygiene`
+**Date:** `2026-06-05`
+**Author:** `instar-echo`
+
+## Summary
+
+`writeDecisionAudit` writes entries with `verdict: 'pending'` and records `{entryPath, entryData}` in a module variable; a `process.on('exit')` hook (registered next to the variable, ABOVE the gate's top-level flow) rewrites the entry with `verdict: code === 0 ? 'pass' : 'blocked'` and re-stages it. Entry naming, staging, timing, and the riding-the-retry property are unchanged.
+
+## Decision-point inventory
+
+- Entry schema — extended — new `verdict` field ('pending' at write; finalized at exit). Additive: old entries without the field remain valid; no reader migration (the decision-audit-presence CI check matches by path, not schema — verified, its 9 tests untouched and green).
+- Exit hook — added — one hook covers every exit path (enforceTier1's exit(0), Tier-2 fall-through, every blockCommit's exit(1)); synchronous-only work; its own try/catch leaves 'pending' on failure (still more truthful than no verdict).
+- Source-order placement — the variable AND the hook registration live above the top-level audit call site. Both failure modes fired in development: a below-call-site declaration TDZ-throws inside writeDecisionAudit's try/catch (silently skipping tracking), and a below-flow registration is never reached when blockCommit exits early (verdict stayed 'pending' — caught by the new blocked-path test).
+
+## Direction of failure
+
+- Old failure: rode-along entries from blocked runs (often under 'unknown'/foreign slugs) read as real shipped decisions — twice in one day (echo #836, codey #842).
+- New behavior: every entry self-describes its outcome.
+- Conservative direction: a finalization failure leaves 'pending' — ambiguous but honest; never a wrong verdict.
+
+## Side-effects checklist
+
+1. **Over-block:** none — the gate's pass/block decisions are untouched; this only records them.
+2. **Exit-hook safety:** synchronous fs/execSync only (required in 'exit' handlers); wrapped in try/catch; cannot change the exit code (the 'exit' event can't).
+3. **Double-stage:** the entry is git-added at write AND at finalize — idempotent (same path, updated content).
+4. **CI interplay:** decision-audit-presence-check matches entries by PATH under .instar/instar-dev-decisions/ — schema-agnostic; its tests run green against the new field.
+5. **Level-of-abstraction fit:** the verdict is determined by the process outcome, not by threading state through every blockCommit call site — one mechanism, all paths.
+6. **External surfaces:** none — local gate script + committed JSON records.
+7. **Rollback cost:** revert; entries return to verdict-less (old shape), already-committed verdict entries remain valid.
+
+## Scope not taken
+
+- No slug-resolution improvement for blocked runs (the verdict defuses the mislabeling harm; resolving the "right" slug for an unmatched trace is guesswork).
+- No retroactive verdict backfill of historical entries.
+- No blocked-entry relocation/exclusion — riding-the-retry stays (deliberate #827-era design: every evaluation leaves a committed trace).
+
+## Rollback
+
+Revert the commit.