instar 1.3.1011 → 1.3.1013

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1011",
+  "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:51:46.153Z",
-  "instarVersion": "1.3.1011",
+  "generatedAt": "2026-07-27T20:30:23.365Z",
+  "instarVersion": "1.3.1013",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/{1.3.1011.md → 1.3.1012.md}

@@ -5,6 +5,15 @@
 
 ## What Changed
 
+Corrects the `rollout-evidence-ref` in `docs/specs/mutual-ssh-autobootstrap.md`. It named
+`/multi-machine/mutual-ssh` — a path with no route anywhere in `src/`. The rollout has been marked
+active and unmeasurable since the feature merged on 2026-07-21.
+
+The readout was never missing. It is `GET /machines/ssh-health`, wired the whole time, and it
+returns real data right now. The spec simply named the wrong address.
+
+Spec frontmatter only. No runtime surface, no route added, no behaviour change.
+
 Memory recall now retrieves semantically. Keyword matching becomes the fallback it was always
 meant to be.
 
@@ -41,6 +50,16 @@ the fallback.
 
 ## What to Tell Your User
 
+Some features are released carefully: switched on quietly first, and only turned up once there is
+evidence they work. Each one's plan names the readout you check to see that evidence.
+
+This feature's plan named a readout that does not exist — so there was no way to tell whether it was
+working, and it would have sat in its cautious first stage forever. The readout it should have named
+does exist and has all along.
+
+Nothing about the feature changed. What changed is that its progress can now be read, and right now
+it honestly reports that it is not ready yet — which is a much better answer than silence.
+
 Your agent has two ways to search its own memory: one that matches on meaning, and one that
 matches on words. The good one was built, fully switched on, and never called.
 
@@ -62,6 +81,9 @@ lookup, quietly, and everything after is fast.
 
 ## Summary of New Capabilities
 
+- The mutual-SSH feature's graduation evidence is readable at `GET /machines/ssh-health` instead of
+  pointing at a path that returns nothing.
+
 - Memory recall retrieves by meaning rather than keyword, using the embedding index that was
   already built and populated but never called.
 - Each recall reports which strategy served it, so running on the keyword fallback is
@@ -73,6 +95,26 @@ lookup, quietly, and everything after is fast.
 
 ## Evidence
 
+Both paths probed live against the running server:
+
+| path | result |
+|---|---|
+| `/multi-machine/mutual-ssh` (the ref as written) | **404** |
+| `/machines/ssh-health` (the real readout) | **200** — `enrollmentState: ssh-bootstrap-blocked`, `pairs[0].mutual: false`, `standingKeyInstalled: false` |
+
+So the graduation criterion — at least one peer pair with bidirectional readiness proof and no
+blocking reason — is now evaluable, and currently, correctly, **not met**. Before this change,
+"not met" and "not measurable" were the same 404.
+
+The route is served from `src/server/routes.ts` (`router.get('/machines/ssh-health')`) reading
+`MutualSshRuntime.status()`, so the corrected ref also satisfies the rollout-evidence lint.
+
+**A correction to my own earlier diagnosis, recorded because it is the more useful finding.** I
+first read the 404 and concluded the endpoint had never landed with the feature, and filed an action
+to build it. It had landed, under a different name. Concluding absence from a single lookup, without
+checking whether the thing exists elsewhere, is the same error this whole sweep is about — and I
+made it while running the sweep.
+
 New tests run against **unmodified source first**:
 
 | run | result |

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/mutual-ssh-evidence-ref.md

@@ -0,0 +1,45 @@
+# Side-effects review — mutual-ssh rollout-evidence-ref correction
+
+**Change:** one frontmatter line in `docs/specs/mutual-ssh-autobootstrap.md` —
+`rollout-evidence-ref: /multi-machine/mutual-ssh` → `/machines/ssh-health`.
+
+**Tier:** 0–1. Spec frontmatter only. No `src/` surface, no route, no config key, no persisted
+state, no migration. Rollback is reverting one line.
+
+## What reads this field
+
+`scripts/lint-rollout-evidence-resolvable.js` (string-matches the ref against `src/`) and any
+future rollout-graduation reader. Nothing at runtime dereferences it — the field is documentation
+of where a human or a check should look, so a wrong value cannot cause a runtime fault. Its failure
+mode is exactly what happened: silence.
+
+## Blast radius
+
+None at runtime. The one behavioural consequence is intended and desirable: the mutual-ssh rollout
+becomes *measurable*, and the first honest measurement says **not ready** (`enrollmentState:
+ssh-bootstrap-blocked`, `pairs[0].mutual: false`). A feature that previously could not be assessed
+now reports a negative. That is the point; it is not a regression.
+
+## Why not build `/multi-machine/mutual-ssh` instead
+
+That was the first plan, and it was wrong. Adding an alias route to satisfy a spec that named a
+non-existent path would have created a second address for one readout — two places to look, two
+things to keep in sync, and a permanent invitation to the same confusion. The spec was wrong; the
+spec was corrected.
+
+## Verification
+
+- `curl /multi-machine/mutual-ssh` → 404 (before and after — nothing was added).
+- `curl /machines/ssh-health` → 200 with live pair state.
+- `node scripts/lint-rollout-evidence-resolvable.js` → the corrected ref resolves.
+
+## Rollback
+
+`git revert` the one-line commit. The rollout returns to being unmeasurable, which is the state it
+has been in since 2026-07-21.
+
+## Known limitation, stated rather than hidden
+
+The lint that guards this field is a **string match against `src/`**. A route that is written but
+never mounted would still satisfy it. That limitation is documented in the lint's own header; the
+live probe above is what actually establishes that this particular ref resolves.

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.