instar 1.2.42 → 1.2.44

package/dist/core/SafeFsExecutor.js

@@ -174,6 +174,74 @@ export class SafeFsExecutor {
             throw err;
         }
     }
+    // ── Atomic write ────────────────────────────────────────────────────
+    //
+    // Crash-safe file writes for file-backed state. The failure these prevent:
+    // a direct `fs.writeFileSync` truncates the target THEN writes; if the
+    // process crashes (or the disk fills) mid-write, the file is left
+    // truncated or partially written — and for append-only event logs / JSON
+    // state, that means silent data loss when the next reader hits a parse
+    // error and falls back to an empty skeleton.
+    //
+    // The pattern: write to a sibling temp file in the SAME directory (so the
+    // rename stays on one filesystem and is therefore atomic per POSIX),
+    // fsync the data to durable storage, then rename over the target. A crash
+    // at any point leaves EITHER the old file intact OR the fully-written new
+    // file — never a half-written one.
+    //
+    // Cherry-picked into Instar 2026-05-23 from the GSD-Instar integration
+    // spike (gsd-executor Rule 2 finding: file-backed state lacked atomic
+    // writes). Not a destructive op, so it does not go through the
+    // source-tree guard — but it lives here as the natural home for safe-fs
+    // primitives and shares the audit trail.
+    /**
+     * Atomically write a string to `target`. Writes to a temp sibling, fsyncs,
+     * then renames over the target. Creates parent directories if missing.
+     */
+    static atomicWriteFileSync(target, data, opts) {
+        const operation = opts?.operation ?? 'atomicWriteFileSync';
+        const resolved = path.resolve(target);
+        const dir = path.dirname(resolved);
+        // Ensure parent dir exists (matches the convenience of writeFileSync callers
+        // who often forget mkdir).
+        fs.mkdirSync(dir, { recursive: true });
+        // Temp file in the SAME directory so rename is atomic (same filesystem).
+        const tmp = path.join(dir, `.${path.basename(resolved)}.${process.pid}.${Date.now()}.tmp`);
+        let fd;
+        try {
+            fd = fs.openSync(tmp, 'w', opts?.mode ?? 0o644);
+            fs.writeSync(fd, data);
+            fs.fsyncSync(fd); // flush data to durable storage before rename
+            fs.closeSync(fd);
+            fd = undefined;
+            fs.renameSync(tmp, resolved); // atomic replace
+            audit('atomicWriteFileSync', operation, resolved, 'allowed');
+        }
+        catch (err) {
+            // Best-effort cleanup of the temp file; never mask the original error.
+            try {
+                if (fd !== undefined)
+                    fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+            try {
+                if (fs.existsSync(tmp))
+                    fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+            audit('atomicWriteFileSync', operation, resolved, 'denied', `write-error: ${err.message}`);
+            throw err;
+        }
+    }
+    /**
+     * Atomically write `value` as pretty-printed JSON to `target`.
+     * Convenience wrapper around atomicWriteFileSync — the common case for
+     * Instar's `.instar/state/*.json` files.
+     */
+    static atomicWriteJsonSync(target, value, opts) {
+        const json = JSON.stringify(value, null, opts?.indent ?? 2);
+        this.atomicWriteFileSync(target, json, { operation: opts?.operation ?? 'atomicWriteJsonSync', mode: opts?.mode });
+    }
 }
 // Re-export the guard error so call-site catch blocks don't have to import
 // from two modules.

package/dist/core/SafeFsExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"SafeFsExecutor.js","sourceRoot":"","sources":["../../src/core/SafeFsExecutor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SafeFsExecutor.js","sourceRoot":"","sources":["../../src/core/SafeFsExecutor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.42",
+  "version": "1.2.44",
   "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:52:30.990Z",
+  "instarVersion": "1.2.44",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -360,7 +360,7 @@
       "type": "skill",
       "domain": "skills",
       "sourcePath": ".claude/skills/build/SKILL.md",
-      "contentHash": "5b3557fa3662cf0c7b7bab85a252cc2e567b3fc64a04a92d430374ef1f264ca6",
+      "contentHash": "bdd16b784c3482372d442ff5986b271213f3d2a705784c7dbbd4345f217be2b2",
       "since": "2025-01-01"
     },
     "skill:instar-project": {
@@ -1040,7 +1040,7 @@
       "type": "template",
       "domain": "safety",
       "sourcePath": "src/templates/hooks/settings-template.json",
-      "contentHash": "557133aed5a8c543affac6df7a959bfb573df9b1e8197b0d29809e1de9d00aec",
+      "contentHash": "2cc950f0635f9c3412b768610f690288b466e7ace280285aee2481fbe514f230",
       "since": "2025-01-01"
     },
     "template:skill-usage-telemetry.sh": {
@@ -1472,7 +1472,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "66f1de9704cc6bebfa8e551f195202455902abfbe309fe53faa9fe10b5138f9f",
+      "contentHash": "2a4639dfdecd37347736d04e008f4a201cd17e9660fa1584df2a43dae2d7e4be",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/hooks/settings-template.json

@@ -31,6 +31,11 @@
             "command": "node .instar/hooks/instar/deferral-detector.js",
             "timeout": 5000
           },
+          {
+            "type": "command",
+            "command": "node .instar/hooks/instar/slopcheck-guard.js",
+            "timeout": 5000
+          },
           {
             "type": "command",
             "command": "node .instar/hooks/instar/external-communication-guard.js",

package/upgrades/1.2.44.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**feat(build): /build methodology bundle — four GSD cherry-picks + defense-in-depth doc.**
+
+Four enhancements to the /build skill, all from the GSD-Instar spike, bundled in one PR because they all touch the /build SKILL.md:
+
+- **Phase 0.5: MUST-HAVES (goal-backward)** — before planning HOW, state WHAT must be observably true: truths (consumer-perspective), artifacts (exist + substantive + wired), and key_links (grep patterns proving real wiring). Each truth becomes a Phase 3 verification gate. Prevents shipping a component that compiles + passes unit tests but is never instantiated.
+- **STRIDE threat pass** (LARGE builds only) — a small threat register where each mitigation binds to a specific test. Skipped for SMALL builds.
+- **Atomic-commit discipline** in Phase 2 EXECUTE — one commit per plan step, stage specific files by name (never `git add -A`), `{type}({scope}): {summary}` format, verify no accidental deletions. Replaces the old single-mega-commit guidance (which was unreviewable).
+- **SUMMARY.md deviation-tracking** in Phase 5 COMPLETE — enumerate deviations from plan, categorized by the executor Rule 1/2/3/4, plus the must-haves verification result and any infrastructure-backed deferrals.
+
+Also adds `docs/patterns/defense-in-depth-insert-and-projection.md` — the insert-time + projection-time pattern the spike surfaced (with the Topic Intent Layer affirmation cap as the worked example).
+
+## Evidence
+
+4 unit tests for the migration (migrateBuildSkillMethodology): stock skill updated, idempotent, customized skill untouched, no-throw on missing. TypeScript clean.
+
+Migration parity: installBuildSkill is install-if-missing, so existing agents get the methodology via a content-sniffed idempotent migration (only updates a stock /build skill lacking the "Phase 0.5: MUST-HAVES" marker; leaves customized skills alone).
+
+Side-effects review: `upgrades/side-effects/build-methodology-bundle.md`.
+
+## What to Tell Your User
+
+Your /build skill got sharper. It now asks "what must be true when this is done?" before planning, commits work in reviewable per-task chunks instead of one giant commit, and writes a short deviation log at the end so you can see exactly what changed from the original plan. On big builds it also does a quick threat pass. Nothing you have to do differently — /build just does more of the right thing automatically.
+
+## Summary of New Capabilities
+
+Four /build methodology sections + one pattern doc + one content-update migration + 4 migration tests. Framework-agnostic (prompt-skill content + a migration). The methodology is the GSD planner/executor discipline imported as Instar's own.

package/upgrades/side-effects/atomic-write-helper.md

@@ -0,0 +1,30 @@
+# Side-Effects Review — Atomic-Write Helper
+
+**Source:** Cherry-pick from GSD-Instar spike (gsd-executor Rule 2 finding)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+N/A — additive library function, blocks nothing.
+
+## 2. Under-block
+N/A — not a gate.
+
+## 3. Level-of-abstraction fit
+Lives in SafeFsExecutor alongside the other safe-fs primitives. Natural home. Static methods matching the existing `safeRmSync` etc. style.
+
+## 4. Signal-vs-authority compliance
+N/A — not a gate/filter. Pure fs primitive.
+
+## 5. Cross-feature interactions
+- Additive — no existing callsite changes. Existing `fs.writeFileSync` callers are untouched; they can migrate to the atomic helper incrementally.
+- Shares the destructive-ops audit trail (appendAuditEntry) — adds `atomicWriteFileSync` / `atomicWriteJsonSync` verbs to the JSONL. No schema change, just new verb values.
+- Temp file naming uses pid + timestamp in the same directory; concurrent writes to the same target from different processes each use a distinct temp, then race on rename (last-rename-wins, which is the correct atomic semantics — no corruption, just last-writer-wins).
+
+## 6. Rollback cost
+Trivial. Two new static methods + one test file. Revert the commit; any caller that adopted it would need reverting too, but at ship time there are zero adopters (the helper is introduced here; migration of existing callsites is a separate follow-up).
+
+## 7. Migration parity
+N/A — `SafeFsExecutor` is a compiled-in library module, not an agent-installed file (`.claude/settings.json` hook, config default, CLAUDE.md section, hook script, or skill). Ships with the package on `npm i instar@next`. No PostUpdateMigrator entry needed.
+
+## Conclusion
+Ship. Purely additive crash-safety primitive. Zero blast radius at introduction. Adopting it across existing `.instar/state/*.json` writers (TopicIntent store, etc.) is a separate follow-up that each gets its own review.

package/upgrades/side-effects/build-methodology-bundle.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — /build Methodology Bundle
+
+**Source:** Cherry-picks from GSD-Instar spike (gsd-planner + gsd-executor methodology)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+None — these are prompt-skill methodology sections, not gates. They add steps the agent runs, not blocks. The Phase 0.5 "quality gate" (must-haves.md exists before Phase 1) is a soft self-check inside the skill, not an external block.
+
+## 2. Under-block
+The methodology is advisory within /build. An agent could skip Phase 0.5. Enforcement of the spirit lives elsewhere (e2e-pairing pre-commit gate, /verify-claim, response-review). This bundle imports the DISCIPLINE; the structural gates are separate cherry-picks.
+
+## 3. Level-of-abstraction fit
+All four changes are content edits to the /build SKILL.md — the natural home for build methodology. The defense-in-depth doc lives in docs/patterns/ alongside other pattern docs. The migration follows the existing migrateSkillPortHardcoding content-sniff pattern.
+
+## 4. Signal-vs-authority compliance
+Compatible. Phase 0.5 must-haves PRODUCE the verification signals that Phase 3 (authority: the agent + reviewers) acts on. STRIDE mitigations bind to tests (the authority). The defense-in-depth doc explicitly reconciles itself with signal-vs-authority. No brittle filter is given blocking authority.
+
+## 5. Cross-feature interactions
+- Phase 0.5 key_links + /verify-claim (separate PR) compose: must-haves define the wiring; /verify-claim checks it.
+- Atomic-commit discipline aligns with the e2e-pairing pre-commit gate (per-task commits make the gate's per-commit check meaningful).
+- SUMMARY deviation-tracking references the executor Rule 1/2/3/4 vocabulary (consistent with the deferral-detector + the GSD methodology framing).
+- The old Phase 5 `git add -A` guidance is REPLACED (it contradicted the new atomic-commit discipline) — a deliberate fix, not just an addition.
+- Migration only touches a stock /build skill; customized skills are fingerprint-guarded.
+
+## 6. Rollback cost
+Moderate-low. Revert the SKILL.md edits + the migration method + the doc + the migration test. Existing agents that already ran the migration would keep the updated SKILL.md (harmless — the new sections are additive guidance). The migration is idempotent and conservative, so a revert-then-re-apply is safe.
+
+## 7. Migration parity
+- New agents: bundled SKILL.md (copied by installBuildSkill on fresh init) carries the sections.
+- Existing agents: migrateBuildSkillMethodology() content-sniffs for the Phase 0.5 marker and re-copies the bundled SKILL.md if absent AND the file matches the stock fingerprint. Wired into the migration sequence after migrateSkillPortHardcoding. Idempotent + fingerprint-guarded (verified by 4 tests).
+- The defense-in-depth doc is a repo doc, not an agent-installed file — ships with the package, no migration needed.
+
+## Conclusion
+Ship. Bundling the four /build-touching items into one PR is correct (separate PRs would self-conflict on SKILL.md). The methodology is the spike's planner+executor discipline imported as Instar's own. Migration parity covered with a conservative content-sniff migration + 4 tests. Seven-dimension review clean.

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.

package/upgrades/side-effects/slopcheck-guard.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Slopcheck Guard Hook
+
+**Source:** Cherry-pick from GSD-Instar spike (gsd-executor Rule 3 exclusion)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+Could over-fire on legitimate installs of new-but-real packages. Mitigation: NEVER blocks — signal-only nudge. Worst case is one extra checklist the agent reads and proceeds past. Familiar packages (in any manifest/lockfile) are silently skipped.
+
+## 2. Under-block
+Could miss a slopsquat if it happens to share a token with something in a lockfile. Mitigation: the lockfile presence check is deliberately loose (favors NOT nagging on known-safe). The nudge is a backstop, not the only defense — the agent still reasons about each install. Acceptable: under-block here means "no extra nudge", not "install proceeds unchecked" (the agent always sees the command).
+
+## 3. Level-of-abstraction fit
+PreToolUse Bash hook alongside dangerous-command-guard, deferral-detector, grounding-before-messaging. Same layer, same idiom, same generator pattern (PostUpdateMigrator getter).
+
+## 4. Signal-vs-authority compliance
+Compliant. Pure pattern-match + lockfile lookup = low-context filter emitting a signal (additionalContext). The agent (full-context authority) decides whether to install. Never blocks.
+
+## 5. Cross-feature interactions
+- dangerous-command-guard (PreToolUse Bash, blocking) runs first and independently — no overlap (it blocks destructive commands; slopcheck nudges on installs).
+- deferral-detector (PreToolUse Bash) matches communication commands — no overlap with install commands.
+- The hook reads project manifests read-only; no mutation, no shared state.
+- Edge: `echo npm install foo` would trigger the nudge (regex matches anywhere). Harmless — signal-only, rare, and erring toward caution on anything that looks like an install is the safe direction.
+
+## 6. Rollback cost
+Trivial. One generator method, one settings-template entry, one migrateSettings ensure-block, one manifest entry, one known-list entry, one test file. Revert the commit; the hook stops generating and existing copies become inert.
+
+## 7. Migration parity
+Full coverage:
+- New agents: settings-template.json PreToolUse Bash entry.
+- Existing agents: explicit ensure-block in migrateSettings() adds the slopcheck entry to the Bash matcher if absent (idempotent — checks `hasSlopcheck` first).
+- Hook script: always-overwritten by migrateHooks() (built-in hook).
+- builtin-manifest.json: registered.
+- known-builtin-hooks list: registered (orphan-cleanup safe).
+
+## Conclusion
+Ship. Real supply-chain defense Instar lacked. Signal-only, trivial rollback, full migration parity. Seven-dimension review clean.

package/upgrades/side-effects/verify-claim-skill.md

@@ -0,0 +1,33 @@
+# Side-Effects Review — /verify-claim Skill
+
+**Source:** Cherry-pick from GSD-Instar spike (gsd-verifier 4-level protocol)
+**Author:** Echo · autonomous run · 2026-05-23
+
+## 1. Over-block
+N/A — a prompt skill, blocks nothing. Worst case: the agent runs a few extra grep/test commands before claiming done. That's the intended cost.
+
+## 2. Under-block
+The skill is advisory — an agent could skip invoking it. Mitigation: it's wired into the recommended /build Phase 3 flow and the "before claiming shipped" trigger. Not a hard gate (that would be the e2e-pairing pre-commit hook + response-review). This is the verification METHODOLOGY made callable; enforcement lives elsewhere.
+
+## 3. Level-of-abstraction fit
+A user-invocable skill alongside the other built-in skills in installBuiltinSkills(). Same inline-content pattern, same install mechanism, same idempotency guarantee.
+
+## 4. Signal-vs-authority compliance
+N/A in the gate sense — it's a methodology the agent runs. It PRODUCES signals (the per-level status), and the agent (authority) acts on them. Aligned with the spike's whole verdict: import the methodology, let the agent wield it.
+
+## 5. Cross-feature interactions
+- Complements the e2e-pairing pre-commit gate (that enforces an e2e test FILE exists; this verifies a claim is actually wired). Different layers, no overlap.
+- Complements response-review (Stop hook). /verify-claim is invoked DURING work; response-review checks the outbound message.
+- Referenced from /build Phase 3 VERIFY as the per-must-have check.
+- Pure additive skill — no existing skill changes.
+
+## 6. Rollback cost
+Trivial. One entry in the installBuiltinSkills record + one test file. Revert the commit; the skill stops being installed for new agents. Existing agents that already have the SKILL.md keep an inert copy (harmless).
+
+## 7. Migration parity
+Adding a NEW skill needs no migration per the Migration Parity Standard: installBuiltinSkills() is called from refreshHooksAndSettings() on every update and is non-destructive (only writes missing SKILL.md files). Existing agents get verify-claim on their next update. Idempotency verified in the test (does not overwrite a customized copy).
+
+Note: a follow-up should add /verify-claim to the CLAUDE.md template's capability list (Agent Awareness Standard) so agents surface it conversationally — tracked, not blocking this PR.
+
+## Conclusion
+Ship. The spike's #1 cherry-pick by leverage. Pure additive prompt skill, trivial rollback, no migration needed. Seven-dimension review clean.