instar 1.3.173 → 1.3.174

package/package.json

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

@@ -165,6 +165,27 @@ try {
       (srcChanges.length > 5 ? `\n      • ...and ${srcChanges.length - 5} more` : '')
     );
   }
+
+  // ── 3b. Release-fragment gate (#23: src change without a release note) ─
+  // A shippable src/ change MUST carry a release-note fragment. publish.yml
+  // SILENTLY skips the release when there is no upgrades/next/<slug>.md fragment
+  // (and no upgrades/NEXT.md) — so the fix merges but never ships, with no
+  // signal. Mirror of the src→tests check above. The "chore: release" cut commit
+  // touches upgrades/ but not src/, so it never trips this. Bypass genuine WIP
+  // with INSTAR_PRE_PUSH_SKIP=1.
+  const fragmentChanges = changedFiles.filter(f =>
+    f.startsWith('upgrades/next/') || f === 'upgrades/NEXT.md'
+  );
+  if (srcChanges.length > 0 && fragmentChanges.length === 0) {
+    errors.push(
+      `${srcChanges.length} source file(s) changed but no release-note fragment was added. ` +
+      `Without upgrades/next/<slug>.md (or upgrades/NEXT.md), publish.yml SILENTLY SKIPS the ` +
+      `release — your change would merge but never ship. Add a fragment describing the change:\n` +
+      srcChanges.slice(0, 5).map(f => `      • ${f}`).join('\n') +
+      (srcChanges.length > 5 ? `\n      • ...and ${srcChanges.length - 5} more` : '')
+    );
+  }
+
   // ── 4. Adapter contract test gate ─────────────────────────────────────
   // If messaging adapter source files changed, require contract test evidence.
   // This prevents shipping integration code verified only by mocked unit tests.

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-31T16:53:49.605Z",
-  "instarVersion": "1.3.173",
+  "generatedAt": "2026-05-31T18:41:05.487Z",
+  "instarVersion": "1.3.174",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.174.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Closed a silent-release-skip gap in the dev/release tooling. The post-merge
+publish workflow skips publishing when a change carries no release-note fragment
+— which is correct when nothing needs releasing, but meant a real code change
+could merge with no release note and then never ship, with no signal anywhere.
+The pre-push gate now catches this: if source files changed but no release-note
+fragment is included, the push is rejected with a clear message instead of
+sailing through to a silent no-release. It mirrors the existing "you changed code
+but added no tests" check, never trips on the routine release-cut commit, and
+respects the same work-in-progress bypass.
+
+## What to Tell Your User
+
+Nothing required — this is invisible developer-tooling robustness. It prevents a
+fix from quietly merging without ever being released.
+
+## Summary of New Capabilities
+
+- The pre-push gate now blocks a source change that has no accompanying
+  release-note fragment, so fixes can no longer merge and then silently fail to
+  publish.
+
+## Evidence
+
+- Root cause: publish.yml sets skip when there is no fragment and no NEXT.md, so a
+  source change with neither merges but never releases (the lived #23 failure).
+- New guard in the pre-push gate mirrors the existing source-changed-without-tests
+  check; never trips on the release-cut commit (touches upgrades, not source).
+- tests/unit/pre-push-gate.test.ts: +1 test; all 14 pass. Lint + type-check clean.
+- Spec: docs/specs/PRE-PUSH-RELEASE-FRAGMENT-GUARD-SPEC.md (+ ELI16 companion).

package/upgrades/side-effects/pre-push-release-fragment-guard.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — Pre-push release-fragment guard (#23)
+
+**Version / slug:** `pre-push-release-fragment-guard`
+**Date:** 2026-05-31
+**Author:** echo
+
+## Summary of the change
+
+`scripts/pre-push-gate.js` gains a check, mirroring the existing src→tests check:
+if `src/**.ts` changed in the branch diff and no `upgrades/next/*.md` fragment
+(or `upgrades/NEXT.md`) is present, it pushes an error → the gate exits non-zero.
+Closes the #23 silent-release-skip class (a shippable src change merging without
+a release note → publish.yml silently skips → fix never ships).
+
+**Files changed (source/scripts):**
+- `scripts/pre-push-gate.js` — +1 check (~13 lines) inside the existing git-diff
+  `try` block, after the src→tests check.
+
+**Files changed (tests):**
+- `tests/unit/pre-push-gate.test.ts` — +1 content-assertion test (matches the
+  file's testing approach for the gate's git-dependent checks).
+
+## Blast radius
+
+`scripts/pre-push-gate.js` runs only on `git push` (husky pre-push). It gates
+LOCAL pushes; CI remains the authority for tests. The new check adds one more
+reason a push can be rejected: a src change with no release fragment.
+
+## Behavior delta
+
+| Scenario | Before | After |
+|---|---|---|
+| src/ changed + a fragment/NEXT.md present | push proceeds | push proceeds (unchanged) |
+| src/ changed + NO fragment | push proceeds → merges → **silent no-release** | push **rejected** with a clear message |
+| `chore: release` cut commit (touches upgrades/, not src/) | proceeds | proceeds (srcChanges=0, check inert) |
+| docs/test-only PR (no src/**.ts) | proceeds | proceeds (srcChanges=0, check inert) |
+| git unavailable (CI / detached HEAD) | git-diff checks skipped | skipped (same `try/catch`) |
+
+## Risks considered
+
+- **False-positive blocking a legitimate push?** Only when src/ changed with no
+  release note — which is exactly the bug. Genuine WIP bypasses via the existing
+  `INSTAR_PRE_PUSH_SKIP=1`. The release-cut commit and docs/test-only PRs don't
+  trip it (no src/**.ts).
+- **Severity (error vs warning):** error, because a silent release-skip is a real
+  failure (the fix never ships), matching the adapter-contract gate's error
+  severity rather than the softer src→tests warning.
+- **No new dependencies, no network, no state.**
+
+## Migration parity
+
+None required. `scripts/pre-push-gate.js` is a dev/release tooling script run from
+the repo's husky hook — not an agent-installed file (hook/config/CLAUDE.md
+template/skill). It ships in the repo; no `PostUpdateMigrator` entry needed.
+
+## Test evidence
+
+`npx vitest run tests/unit/pre-push-gate.test.ts` → 14 passed (incl. the new
+content-assertion). `npm run lint` + `tsc --noEmit` clean. Dogfood: this PR
+itself carries `upgrades/next/pre-push-release-fragment-guard.md`, so the new
+guard would pass on this very change.