instar 1.3.256 → 1.3.257

package/package.json

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

@@ -147,8 +147,23 @@ if (latestPublished) {
 
 try {
   const { execSync } = await import('node:child_process');
-  // Get files changed since the remote tracking branch
-  const remoteBranch = execSync('git rev-parse --abbrev-ref @{u} 2>/dev/null || echo origin/main', { encoding: 'utf-8' }).trim();
+  // Compute "what this PR changes" against its MERGE TARGET (main), not the
+  // branch's own upstream (@{u}). Using @{u} breaks when a PR is updated by
+  // MERGING main in (the no-force-push path): `@{u}...HEAD` then includes all of
+  // main's already-shipped changes, producing false "src changed without a
+  // release-note fragment" errors (which forced INSTAR_PRE_PUSH_SKIP=1 on merge-
+  // updated PRs). A three-dot diff against main is the PR's TRUE diff in both the
+  // normal-incremental and merge-from-main cases, and never UNDER-reports the
+  // PR's own changes (merge-base of main and HEAD is the branch point).
+  const pickRef = (cands) => {
+    for (const r of cands) {
+      try { execSync(`git rev-parse --verify --quiet ${r}`, { stdio: 'pipe', encoding: 'utf-8' }); return r; }
+      catch { /* ref not present in this clone */ }
+    }
+    return null;
+  };
+  const remoteBranch = pickRef(['JKHeadley/main', 'origin/main', 'upstream/main', 'main'])
+    || execSync('git rev-parse --abbrev-ref @{u} 2>/dev/null || echo origin/main', { encoding: 'utf-8' }).trim();
   const changedFiles = execSync(`git diff --name-only ${remoteBranch}...HEAD 2>/dev/null || git diff --name-only HEAD~1 2>/dev/null`, { encoding: 'utf-8' })
     .trim()
     .split('\n')

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T00:14:24.582Z",
-  "instarVersion": "1.3.256",
+  "generatedAt": "2026-06-05T00:23:37.925Z",
+  "instarVersion": "1.3.257",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.257.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/pre-push-gate.js` computed its "what files did this PR change" diff against `@{u}` (the
+branch's own upstream). When a PR is updated by MERGING main in (the no-force-push path to resolve
+conflicts), `@{u}...HEAD` then includes all of main's already-shipped files, so the gate's
+src→fragment / src→tests / internal-only checks false-flag 173+ unrelated files and force
+`INSTAR_PRE_PUSH_SKIP=1` (hit on #663, and complicated #766's re-trigger). The gate now diffs
+against the PR's merge target (`JKHeadley/main`||`origin/main`||`upstream/main`||`main`), falling
+back to `@{u}` only when no main ref resolves. A three-dot diff against main is the PR's true diff
+in both the normal-incremental and merge-from-main cases and never under-reports the PR's changes.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- Reproduced on #663 (merge-from-main → 173 false `src/` files → forced SKIP=1).
+- Safe-by-construction: `main...HEAD` (merge-base = branch point) always contains all the PR's
+  commits, so it can never under-report; the only error direction is over-reporting (safe).
+- 16 `tests/unit/pre-push-gate.test.ts` pass (incl. a new source-presence test for the main-ref
+  base); `node --check scripts/pre-push-gate.js` clean. Self-uses the internal-only lane (scripts +
+  test only, no `src/`).

package/upgrades/side-effects/prepush-gate-diff-base-main-ref.md

@@ -0,0 +1,45 @@
+# Side-Effects Review — pre-push gate diffs against the main ref, not @{u}
+
+**Version / slug:** `prepush-gate-diff-base-main-ref`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (build-gate diff base; safe-by-construction)`
+
+## Summary
+
+`scripts/pre-push-gate.js` computed `changedFiles` via `git diff --name-only ${remoteBranch}...HEAD`
+where `remoteBranch = @{u}` (the branch's OWN upstream). That breaks when a PR is updated by
+MERGING main in (the no-force-push path used to resolve conflicts): `@{u}...HEAD` then includes
+ALL of main's already-shipped changes, so the gate's section-3/3b checks see 173+ unrelated `src/`
+files → false "src changed without a release-note fragment" errors, forcing `INSTAR_PRE_PUSH_SKIP=1`
+(hit live on #663). The fix computes the diff against the PR's MERGE TARGET — the first resolvable
+of `JKHeadley/main`/`origin/main`/`upstream/main`/`main` — falling back to the old `@{u}` behaviour
+only when no main ref resolves.
+
+## 1. Over-block (what it still flags)
+
+Unchanged for the normal incremental-push case: `main...HEAD` (three-dot, from the merge-base =
+the branch point) == the PR's commits == what `@{u}...HEAD` gave for a never-merged-main branch.
+The src→tests, src→fragment (#23), and internal-only (§3c) checks all still fire on the PR's real
+`src/` changes. The "chore: release" commit (upgrades/ + version, no `src/`) still doesn't trip
+section-3b, same as before.
+
+## 2. Under-block (what it now lets through)
+
+Nothing it shouldn't. A three-dot diff against main can NEVER under-report the PR's own changes
+(the merge-base of main and HEAD is the branch point, so all the PR's commits are in the diff). The
+only direction it can err is OVER-reporting (if a branch is based off another branch, not main) —
+the safe direction (extra false-positives, never a missed src-change-without-fragment). The fix
+specifically REMOVES the merge-from-main false-positive without weakening any check.
+
+## 3. Blast radius
+
+One file: `scripts/pre-push-gate.js` (the `changedFiles` computation feeding sections 3/3b/3c) +
+its unit test. No `src/`, no runtime, no agent surface. `pickRef` is a local helper; on any error
+it falls through to the prior `@{u}` logic, so a clone without a `main` remote behaves exactly as
+before.
+
+## 4. Reversibility
+
+Fully reversible: revert the one hunk. No state. Verified: `node --check` clean; 16 pre-push-gate
+unit tests pass.