instar 1.2.42 → 1.2.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.42",
+  "version": "1.2.43",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/check-e2e-pairing.cjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// safe-git-allow: pre-commit-bootstrap — read-only `git diff --cached` to scan staged file list; runs before TS compile so cannot use SafeGitExecutor funnel.
+/**
+ * E2E-pairing gate — pre-commit check.
+ *
+ * Cherry-pick from the GSD-Instar integration spike. The spike's Tier-3
+ * "feature is alive" finding: features that ship with API routes but no
+ * E2E lifecycle test silently return 503 in production. CLAUDE.md calls
+ * the Tier-3 test "the single most important test for any feature with
+ * API routes" — but nothing structurally enforced its presence.
+ *
+ * This gate: if a commit stages a non-test `src/server/*.ts` file, it must
+ * also stage at least one `tests/e2e/*.test.ts` file. Otherwise the commit
+ * is blocked with a remediation message.
+ *
+ * This is a SIGNAL with commit-time authority — it errs toward false
+ * positives (a server refactor that genuinely needs no new e2e test is
+ * rarer than a feature shipped without one). Two escape hatches keep it
+ * from being tyrannical:
+ *   1. Env bypass: INSTAR_SKIP_E2E_PAIRING=1 git commit ...
+ *   2. Marker: include "E2E-PAIRING: EXEMPT — <reason>" in any staged
+ *      server file (for genuine refactors / type-only / comment changes).
+ *
+ * Exit codes:
+ *   0 — pass (no server change, or e2e test paired, or exempt)
+ *   1 — block (server change with no paired e2e test and no exemption)
+ */
+
+const { execSync } = require('node:child_process');
+
+if (process.env.INSTAR_SKIP_E2E_PAIRING === '1') {
+  process.exit(0);
+}
+
+function stagedFiles() {
+  try {
+    const out = execSync('git diff --cached --name-only --diff-filter=ACMR', { encoding: 'utf-8' });
+    return out.split('\n').map(s => s.trim()).filter(Boolean);
+  } catch {
+    // If we can't read the index, don't block the commit.
+    return [];
+  }
+}
+
+function stagedContent(file) {
+  try {
+    return execSync(`git show :${file}`, { encoding: 'utf-8' });
+  } catch {
+    return '';
+  }
+}
+
+const files = stagedFiles();
+
+// Server source files (excluding tests + type-declaration files).
+const serverChanges = files.filter(f =>
+  /^src\/server\/.*\.ts$/.test(f) &&
+  !/\.test\.ts$/.test(f) &&
+  !/\.d\.ts$/.test(f)
+);
+
+if (serverChanges.length === 0) {
+  process.exit(0); // No server change — nothing to enforce.
+}
+
+// Paired E2E test staged in the same commit?
+const hasE2e = files.some(f => /^tests\/e2e\/.*\.test\.ts$/.test(f));
+if (hasE2e) {
+  process.exit(0);
+}
+
+// Exemption marker in any staged server file?
+const exemptMarker = /E2E-PAIRING:\s*EXEMPT\s*[—-]/;
+for (const f of serverChanges) {
+  if (exemptMarker.test(stagedContent(f))) {
+    process.exit(0);
+  }
+}
+
+// Block.
+console.error('');
+console.error('╔════════════════════════════════════════════════════════════════════╗');
+console.error('║  E2E-PAIRING GATE — server change without a paired E2E test          ║');
+console.error('╚════════════════════════════════════════════════════════════════════╝');
+console.error('');
+console.error('  Staged server source files:');
+for (const f of serverChanges) console.error(`    ${f}`);
+console.error('');
+console.error('  No tests/e2e/*.test.ts file is staged in this commit.');
+console.error('');
+console.error('  CLAUDE.md: the Tier-3 "feature is alive" E2E test is the single most');
+console.error('  important test for any feature with API routes. Features that ship');
+console.error('  with routes but no E2E lifecycle test silently return 503 in prod.');
+console.error('');
+console.error('  Fix one of:');
+console.error('    1. Add/modify a tests/e2e/*.test.ts that boots the real server path');
+console.error('       and hits the route, then stage it.');
+console.error('    2. Genuine refactor / type-only / comment change? Add a comment');
+console.error('       "E2E-PAIRING: EXEMPT — <reason>" to a staged server file.');
+console.error('    3. One-off bypass: INSTAR_SKIP_E2E_PAIRING=1 git commit ...');
+console.error('');
+process.exit(1);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-23T03:29:25.734Z",
-  "instarVersion": "1.2.42",
+  "generatedAt": "2026-05-23T03:49:24.867Z",
+  "instarVersion": "1.2.43",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {

package/upgrades/1.2.43.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**feat(dev): e2e-pairing pre-commit gate — GSD cherry-pick.**
+
+New pre-commit gate (`scripts/check-e2e-pairing.cjs`, wired into `.husky/pre-commit`) that blocks any commit changing a non-test `src/server/*.ts` file unless it also stages at least one `tests/e2e/*.test.ts`. Structurally enforces the Tier-3 "feature is alive" discipline that CLAUDE.md calls the single most important test for any feature with API routes.
+
+From the GSD-Instar spike, where the gsd-planner methodology surfaced that the Topic Intent Layer's Tier-3 lifecycle test would have been forgotten under ad-hoc planning. This gate makes "ship a route without an e2e test" structurally hard rather than discipline-dependent.
+
+Two escape hatches keep it from being tyrannical: env bypass (`INSTAR_SKIP_E2E_PAIRING=1`) and an `E2E-PAIRING: EXEMPT — <reason>` marker in a staged server file (for genuine refactors / type-only / comment changes).
+
+This governs instar's OWN development commits (it's in instar's `.husky/`), not agent-installed files — so no migration parity needed.
+
+## Evidence
+
+8 unit tests, all green (tmp-git-repo harness): passes with no server files, blocks server-without-e2e, passes server-with-e2e, ignores server test files + .d.ts, respects env bypass + EXEMPT marker, blocks when only an unrelated unit test is staged. TypeScript clean.
+
+Verified the gate does not block this very PR (this PR changes scripts/ + .husky/ + tests/, not src/server/).
+
+Side-effects review: `upgrades/side-effects/e2e-pairing-gate.md`.
+
+## What to Tell Your User
+
+Nothing user-visible. Internal dev-discipline gate for instar contributors.
+
+## Summary of New Capabilities
+
+One new pre-commit gate script + one line in .husky/pre-commit. Signal-with-commit-authority (blocks), with two escape hatches. Errs toward false positives because a route shipped without an e2e test is the corruption-class failure being defended against.

package/upgrades/side-effects/e2e-pairing-gate.md

@@ -0,0 +1,30 @@
+# Side-Effects Review — E2E-Pairing Pre-Commit Gate
+
+**Source:** Cherry-pick from GSD-Instar spike (Tier-3 "feature is alive" finding)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+Could block legitimate server refactors / type-only changes that genuinely need no new e2e test. Mitigations: (a) `E2E-PAIRING: EXEMPT — <reason>` marker, (b) `INSTAR_SKIP_E2E_PAIRING=1` env bypass. Both are documented in the block message itself.
+
+## 2. Under-block
+Could pass a commit that stages a trivial/empty e2e test just to satisfy the gate. Accepted: the gate enforces PRESENCE, not quality. Quality is the reviewer's job + the existing CI E2E run. Presence-enforcement alone closes the "forgot the e2e test entirely" gap, which is the actual failure mode.
+
+## 3. Level-of-abstraction fit
+Pre-commit gate alongside check-rule3-coverage.cjs, protect-migration-guarantee.js, instar-dev-precommit.js. Same layer (instar dev discipline), same .husky/pre-commit wiring, same read-only-staged-diff pattern.
+
+## 4. Signal-vs-authority compliance
+This is a SIGNAL with commit-time authority (it blocks). Per signal-vs-authority: brittle low-context filters should only block when the defended-against failure is corruption-class and the false-positive cost is low. A route shipped without an e2e test silently 503s in prod (corruption-class); the false-positive cost is one comment marker or one env var (low). The two escape hatches keep the human/agent as the final authority. Compliant.
+
+## 5. Cross-feature interactions
+- Runs last in .husky/pre-commit, after lint + instar-dev-precommit + rule3 + migration-guarantee. Independent — reads staged diff, no shared state.
+- Does not interact with CI (CI runs the actual E2E suite; this gate just enforces a test FILE is staged).
+- Edge: a commit that splits a feature across two commits (server in commit 1, e2e test in commit 2) would block commit 1. Mitigation: the EXEMPT marker or env bypass for the intermediate commit; or stage both together. This is a deliberate nudge toward atomic feature commits.
+
+## 6. Rollback cost
+Trivial. One script + one line in .husky/pre-commit + one test file. Revert the commit; the gate stops running.
+
+## 7. Migration parity
+N/A — this is an instar-dev-repo gate (`.husky/pre-commit`), NOT an agent-installed file. It ships with the source repo and governs instar contributors' commits. Agents never receive `.husky/` hooks. No PostUpdateMigrator entry needed.
+
+## Conclusion
+Ship. Structurally enforces the Tier-3 discipline the spike identified as most-forgotten. Two escape hatches prevent tyranny. Trivial rollback. Seven-dimension review clean.