instar 1.3.1012 → 1.3.1013

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1012",
+  "version": "1.3.1013",
   "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/pre-push-gate.js

@@ -345,44 +345,57 @@ if (!process.env.CI) {
   // isn't what this PR is changing. Falls back to the versioned guide when no
   // fragment / NEXT.md is staged (post-release-cut state).
   const inFlight = assembledContent !== null;
-  const guideContent = inFlight
-    ? assembledContent
-    : (versionedGuideExists ? fs.readFileSync(versionedGuidePath, 'utf-8') : null);
-  if (guideContent !== null) {
+
+  // This check is a RELEASE-LEVEL re-check on the notes THIS PUSH is shipping —
+  // which means it only has a subject when in-flight notes exist. It deliberately
+  // does NOT fall back to the versioned guide.
+  //
+  // Why (three recurrences, 2026: v1.3.492, v1.3.802, v1.3.1009): the release cut
+  // renames upgrades/next/*.md into upgrades/<version>.md and bumps package.json,
+  // but side-effects artifacts are named per CHANGE SLUG, never per version — so
+  // upgrades/side-effects/<version>.md is a file the release flow never creates.
+  // Falling back to the frozen guide therefore demanded a filename that cannot
+  // exist, on EVERY push from a clean post-release tree, for a release that had
+  // already shipped and already been reviewed.
+  //
+  // The damage was not the refusal, it was the REMEDY the message named: three
+  // separate times someone hand-wrote a placeholder upgrades/side-effects/<version>.md
+  // to get past it (see 1.3.492.md and 1.3.802.md, both of which say so in their
+  // own text). A gate whose advice is unfollowable teaches people to write junk
+  // that satisfies it.
+  //
+  // Nothing is weakened. Per-change enforcement lives in the pre-COMMIT gate
+  // (scripts/instar-dev-precommit.js — refuses in-scope staged files without an
+  // ELI16 + side-effects artifact), and check 3b above already refuses a
+  // release-relevant push that ships no fragment, with an actionable remedy.
+  if (inFlight) {
     // Extract "## What Changed" section
-    const whatChangedMatch = guideContent.match(/## What Changed\s*([\s\S]*?)(?=\n##\s|$)/);
+    const whatChangedMatch = assembledContent.match(/## What Changed\s*([\s\S]*?)(?=\n##\s|$)/);
     const whatChanged = whatChangedMatch ? whatChangedMatch[1] : '';
 
     const qualifies = FIX_PATTERNS.some((p) => p.test(whatChanged));
 
     if (qualifies) {
       const sideEffectsDir = path.join(ROOT, 'upgrades', 'side-effects');
-      // When in-flight notes (fragments/NEXT.md) drive the push, any fresh
-      // artifact (last 24h) counts — the versioned-filename requirement only
-      // applies when a versioned guide is being validated without in-flight notes.
-      const artifactName = (!inFlight && versionedGuideExists) ? `${version}.md` : null;
       let artifactFound = false;
 
       if (fs.existsSync(sideEffectsDir)) {
         const files = fs.readdirSync(sideEffectsDir).filter((f) => f.endsWith('.md'));
-        if (artifactName) {
-          artifactFound = files.includes(artifactName);
-        } else {
-          // For in-flight notes (fragments/NEXT.md), any fresh artifact from the
-          // last 24h counts. The expectation is that during release cut, the
-          // fragment/NEXT.md -> <version>.md rename pairs with an artifact rename.
-          const recent = files.filter((f) => {
-            const stat = fs.statSync(path.join(sideEffectsDir, f));
-            return Date.now() - stat.mtimeMs < 24 * 60 * 60 * 1000;
-          });
-          artifactFound = recent.length > 0;
-        }
+        // Any fresh artifact from the last 24h counts — the in-flight notes name
+        // the change, the artifact reviews it, and the two are paired by the PR
+        // rather than by filename.
+        const recent = files.filter((f) => {
+          const stat = fs.statSync(path.join(sideEffectsDir, f));
+          return Date.now() - stat.mtimeMs < 24 * 60 * 60 * 1000;
+        });
+        artifactFound = recent.length > 0;
       }
 
       if (!artifactFound) {
         errors.push(
-          `Upgrade notes claim a fix/feature but no matching side-effects review artifact found in upgrades/side-effects/. ` +
-          `Every change qualifying for review must ship with an artifact produced via the /instar-dev skill. ` +
+          `Your release-note fragment claims a fix/feature but no side-effects review artifact was written in the last 24h. ` +
+          `Add upgrades/side-effects/<slug>.md for this change (produced via the /instar-dev skill) — ` +
+          `do NOT create a version-named file to satisfy this check. ` +
           `See skills/instar-dev/SKILL.md and docs/signal-vs-authority.md.`
         );
       }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-27T19:56:42.745Z",
-  "instarVersion": "1.3.1012",
+  "generatedAt": "2026-07-27T20:30:23.365Z",
+  "instarVersion": "1.3.1013",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1013.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes the pre-push gate's side-effects-artifact check, which refused **every push from a clean
+post-release tree** and named an impossible remedy when it did.
+
+After a release cut there are no in-flight release-note fragments, so the check fell back to
+`upgrades/<version>.md` — the guide for the version that already shipped — and demanded
+`upgrades/side-effects/<version>.md`. Side-effects artifacts are named per change slug; the release
+flow has never produced a version-named one, so the demand could not be satisfied.
+
+The check is now scoped to the notes the push is actually shipping. With no notes in flight there is
+nothing to check and it stays silent. With notes in flight it fires exactly as before.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+**Three observed recurrences, self-documented in the repo.** `upgrades/side-effects/1.3.492.md` and
+`1.3.802.md` are hand-written placeholders whose own text says they exist only to satisfy this
+check; the second calls itself "its second observed recurrence". Today (v1.3.1009) was the third,
+and it refused a sibling branch before diagnosis.
+
+Both placeholders claim the gap "remains logged in the framework-issues ledger under dedupKey
+`pre-push-gate-versioned-artifact-fallback`". It is not. Queried four ways — unfiltered,
+`?status=fixed`, `?bucket=instar-integration-gap`, `?framework=instar` — the ledger holds 163 issues
+and zero matches, with no dedupKey containing `release`, `artifact`, or `push`. Declared tracked,
+never tracked, recurred. It is registered for real with this change.
+
+**Verified by reverting, because a passing test proves nothing:**
+
+| gate | result |
+|---|---|
+| OLD code, new tests | **3 failed** \| 16 passed (19) |
+| NEW code | **19 passed** (19) |
+
+Plus a live run against the real repo in its actual post-cut state: errors before, warnings only
+after.
+
+**Nothing is weakened, and this was the load-bearing question.** Per-change enforcement still lives
+in the pre-COMMIT gate (which refuses in-scope staged files lacking an ELI16 + side-effects artifact,
+and blocked this very change twice while it was being written); check 3b still refuses a
+release-relevant push with no fragment; and check 5 still fires when in-flight notes claim a fix with
+no fresh artifact — asserted by a dedicated negative-control test, since the easy mistake here is
+trading a false positive for a false negative.

package/upgrades/side-effects/prepush-gate-frozen-guide.md

@@ -0,0 +1,78 @@
+# Side-effects review — pre-push gate stops validating the frozen versioned guide
+
+**Change:** `scripts/pre-push-gate.js` check 5 (side-effects-artifact requirement) is scoped to
+in-flight release notes. It no longer falls back to `upgrades/<version>.md` — the guide for the
+version that already shipped.
+
+**Tier:** 1. One local developer gate. No `src/` surface, no route, no config, no persisted state,
+no migration. Not run in CI (`if (!process.env.CI)`), so it cannot change what merges — only what a
+developer can push from their own machine.
+
+## The defect, with its recurrence record
+
+Post-release-cut the tree has `upgrades/<version>.md` (frozen), no fragments, and no
+`upgrades/side-effects/<version>.md`. That last file is one the release flow never creates: artifacts
+are named per change slug. The fallback demanded it anyway, so **every push from a clean
+post-release tree was refused**.
+
+Three observed recurrences, all self-documented in the repo:
+
+| version | evidence |
+|---|---|
+| v1.3.492 | `upgrades/side-effects/1.3.492.md` — a hand-written placeholder that says so |
+| v1.3.802 | `upgrades/side-effects/1.3.802.md` — same, and calls itself "its second observed recurrence" |
+| v1.3.1009 | today; refused this branch's sibling PR before diagnosis |
+
+Both placeholders state the gap "remains logged in the framework-issues ledger under dedupKey
+`pre-push-gate-versioned-artifact-fallback`". **It is not.** Queried four ways
+(`GET /framework-issues` unfiltered, `?status=fixed`, `?bucket=instar-integration-gap`,
+`?framework=instar`): 163 issues, zero matches, and no dedupKey in the store containing `release`,
+`artifact`, or `push`. The tracking claim was hollow, which is why it recurred a third time. The
+issue is registered for real as part of this change.
+
+## What is NOT weakened — the load-bearing question
+
+Removing a check is the risky half of this. Three separate enforcement points remain:
+
+1. **`scripts/instar-dev-precommit.js` — untouched.** This is the real per-change enforcement: it
+   refuses a COMMIT whose in-scope staged files lack an ELI16 doc and a side-effects artifact, and
+   it verifies the artifact's sha against the decision trace. It blocked this very change twice
+   while it was being written.
+2. **Check 3b — untouched.** A push with release-relevant files and no fragment is still refused,
+   with an actionable remedy (`add upgrades/next/<slug>.md`).
+3. **Check 5 itself — still fires, scoped.** With in-flight notes claiming a fix and no fresh
+   artifact, it refuses exactly as before. Test:
+   `STILL refuses an in-flight fix-claiming fragment with no fresh side-effects artifact`.
+
+The narrowed case — "no in-flight notes, frozen guide claims a fix, no version-named artifact" — was
+never a real signal. It fired on a release that had already shipped and already been reviewed.
+
+## Blast radius
+
+A developer can now push from a clean post-release tree without hand-writing a placeholder. That is
+the entire behavioural change. Nothing in CI, publishing, or runtime reads this script.
+
+**Residual risk:** if the release process ever DID start producing version-named artifacts and
+someone relied on this check to enforce that, this would silently stop enforcing it. Judged
+acceptable: no such producer exists, and the 37 version-named artifacts already in the repo are
+release rollups and placeholders, not a maintained convention.
+
+## Verification
+
+Verified by REVERTING, because a passing test proves nothing:
+
+```
+against the OLD gate:  3 failed | 16 passed (19)
+  × ACCEPTS a post-release-cut tree with no fragment and no version-named artifact
+  × does not demand a version-named side-effects artifact even when one has never existed
+  × STILL refuses an in-flight fix-claiming fragment with no fresh side-effects artifact
+against the NEW gate:  19 passed (19)
+```
+
+Plus a live run against the real repo in its actual post-cut state (v1.3.1009, no fragments): errors
+before, warnings only after.
+
+## Rollback
+
+`git revert`. The gate returns to refusing every clean post-release push, and the next person writes
+`upgrades/side-effects/<version>.md` by hand for the fourth time.