instar 1.3.999 → 1.3.1001

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.999",
+  "version": "1.3.1001",
   "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/skills/instar-dev/scripts/write-trace.mjs

@@ -46,6 +46,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
 
 const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..');
 
@@ -157,6 +158,107 @@ function buildToolchain() {
   }
 }
 
+/**
+ * Verify the commit gate is actually INSTALLED before writing a trace that implies it ran.
+ *
+ * THE FAILURE THIS EXISTS TO CATCH. A worktree created with `git worktree add` and a
+ * symlinked (or absent) node_modules has no husky shim, so `core.hooksPath` points at a
+ * directory that does not exist. `git commit` then runs NO hook: it prints nothing and
+ * succeeds. **A working gate and an uninstalled gate look identical on screen — silence.**
+ * That is not hypothetical; it happened on 2026-07-27 and a whole change was committed
+ * believing the gate had passed it, when the gate had never executed.
+ *
+ * The gate cannot report its own absence — an uninstalled hook cannot run to say it is
+ * uninstalled. So the check belongs at the nearest chokepoint the agent DOES invoke by
+ * hand, which is this script. Writing a trace is the step that asserts "this change came
+ * through the skill", and that assertion is false if the gate cannot execute.
+ *
+ * SCOPE HONESTY: this is a SIGNAL, not an authority. It refuses to write the trace and
+ * says why; it cannot block a commit, because the very condition it detects is the one
+ * where no commit hook runs. Without a trace an in-scope commit is refused ANYWAY once the
+ * hook IS installed — so the two layers compose rather than overlap. Its whole job is to
+ * turn a silent absence into a loud one at the moment the agent would otherwise proceed.
+ *
+ * Set INSTAR_DEV_ALLOW_UNINSTALLED_GATE=1 to proceed anyway (a genuinely hookless
+ * environment, e.g. a test harness). The override is recorded IN THE TRACE rather than
+ * merely permitted, so a trace written without a live gate can never later be mistaken for
+ * one the gate approved.
+ */
+function inspectGateInstallation() {
+  const result = { installed: false, reason: '', hooksPath: null };
+  let hooksPath;
+  try {
+    hooksPath = execFileSync('git', ['config', '--get', 'core.hooksPath'], {
+      cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    hooksPath = '';
+  }
+
+  if (!hooksPath) {
+    // No hooksPath set at all — git falls back to .git/hooks. Check there instead of
+    // assuming absence: a repo may legitimately install the hook the classic way.
+    let gitDir;
+    try {
+      gitDir = execFileSync('git', ['rev-parse', '--git-dir'], {
+        cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      // NOT A GIT REPOSITORY AT ALL — the check does not apply.
+      //
+      // This is not a loophole, it is the check's actual scope. The hazard being guarded
+      // is "a git repo whose commit hook will not run". Where there is no repo there is no
+      // commit, so there is nothing to gate and nothing to be misled about. Test harnesses
+      // that drive this script inside a bare temp directory land here.
+      //
+      // Deliberately NOT solved by making every such harness set the override env var:
+      // that would push the burden onto whoever writes the next test remembering to do it,
+      // which is the willpower-over-structure trade this whole change exists to remove.
+      // It is also not a meaningful bypass — an agent cannot make the instar repo stop
+      // being a git repository.
+      return { installed: true, reason: '', hooksPath: null, notApplicable: true };
+    }
+    const classic = path.resolve(ROOT, gitDir, 'hooks', 'pre-commit');
+    if (fs.existsSync(classic)) return { installed: true, reason: '', hooksPath: classic };
+    return { ...result, reason: 'core.hooksPath is unset and .git/hooks/pre-commit does not exist' };
+  }
+
+  result.hooksPath = hooksPath;
+  const resolved = path.resolve(ROOT, hooksPath);
+  if (!fs.existsSync(resolved)) {
+    return { ...result, reason: `core.hooksPath is "${hooksPath}" but that directory does not exist — husky is not installed in this worktree (run \`npm ci\` then \`npx husky\`)` };
+  }
+  const preCommit = path.join(resolved, 'pre-commit');
+  if (!fs.existsSync(preCommit)) {
+    return { ...result, reason: `core.hooksPath is "${hooksPath}" but it contains no pre-commit hook` };
+  }
+  return { installed: true, reason: '', hooksPath };
+}
+
+const gate = inspectGateInstallation();
+const gateOverridden = process.env.INSTAR_DEV_ALLOW_UNINSTALLED_GATE === '1';
+if (!gate.installed && !gateOverridden) {
+  console.error('');
+  console.error('  ╔════════════════════════════════════════════════════════════════════╗');
+  console.error('  ║  REFUSING to write a trace — the commit gate is NOT installed      ║');
+  console.error('  ╚════════════════════════════════════════════════════════════════════╝');
+  console.error('');
+  console.error(`  ${gate.reason}`);
+  console.error('');
+  console.error('  A trace asserts this change came through /instar-dev. With no hook');
+  console.error('  installed, `git commit` runs NOTHING and succeeds silently — a passing');
+  console.error('  gate and an absent gate look identical on screen. Writing the trace now');
+  console.error('  would record an approval that was never given.');
+  console.error('');
+  console.error('  Fix it in this worktree:   npm ci && npx husky');
+  console.error('  Then verify:               git config core.hooksPath && ls .husky/_');
+  console.error('');
+  console.error('  If this environment genuinely has no hooks (e.g. a test harness), set');
+  console.error('  INSTAR_DEV_ALLOW_UNINSTALLED_GATE=1 — the override is recorded in the trace.');
+  console.error('');
+  process.exit(1);
+}
+
 const artifactPath = path.resolve(ROOT, artifact);
 if (!fs.existsSync(artifactPath)) {
   console.error(`Artifact not found: ${artifact}`);
@@ -235,6 +337,10 @@ const trace = {
   // Duplicate-build guard §3.4 — omitted when no stub exists so pre-guard
   // traces round-trip byte-identically.
   ...(duplicateBuildCheck ? { duplicateBuildCheck } : {}),
+  // Recorded ONLY when the gate-installation check was overridden, so a trace written
+  // without a live commit gate can never later be mistaken for one the gate approved.
+  // Absent on every normal trace, so existing traces round-trip byte-identically.
+  ...(gate.installed ? {} : { gateInstallationOverridden: true, gateInstallationReason: gate.reason }),
 };
 
 fs.writeFileSync(traceFile, JSON.stringify(trace, null, 2) + '\n');

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-27T09:13:24.898Z",
-  "instarVersion": "1.3.999",
+  "generatedAt": "2026-07-27T10:24:33.892Z",
+  "instarVersion": "1.3.1001",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.1000.md

@@ -0,0 +1,60 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`skills/instar-dev/scripts/write-trace.mjs` now verifies the instar-dev commit gate is actually
+installed before writing a trace, and refuses with an explanation when it is not.
+
+A worktree created with `git worktree add` inherits `core.hooksPath` (typically `.husky/_`) from the
+shared repo config, while that directory does not exist until `npm ci` plus `npx husky` have run. In
+that state `git commit` executes no hook: it prints nothing and succeeds. A working gate and an
+uninstalled gate are indistinguishable on screen, because both are silent — and on 2026-07-27 a
+change was committed on the belief the gate had passed it when the gate had never run.
+
+The gate cannot detect its own absence, since an uninstalled hook cannot execute to say so. The check
+therefore lives at the nearest chokepoint invoked by hand: writing the trace, which is the step that
+asserts the change came through the skill. `INSTAR_DEV_ALLOW_UNINSTALLED_GATE=1` overrides it, and
+the override is recorded in the trace so an unguarded trace can never be mistaken for an approved one.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Verified against a real hookless worktree before any test was written — `core.hooksPath` was already
+`.husky/_` in a freshly added worktree with no shim, confirming silently-no-gate is the default state
+rather than an exotic misconfiguration:
+
+```
+core.hooksPath is ".husky/_" but that directory does not exist — husky is not installed
+```
+
+Falsified by neutering the check in the script:
+
+```
+× THE FIX: refuses to write a trace when hooksPath points at a missing directory
+  → expected +0 to be 1
+× refuses when hooksPath is unset AND no classic hook exists
+  Tests  2 failed | 4 passed (6)
+```
+
+Restored byte-identical. The over-block was found by running the suites chosen from the diff rather
+than the files authored: the first implementation broke seven tests in `write-trace-tier` and
+`duplicate-build-guard-gates`, both of which drive the script inside bare temp directories. Scoping
+the check to git repositories only fixed it — a directory that is not a repo has no commit to gate.
+Final: `Test Files 3 passed (3) · Tests 23 passed (23)`.
+
+## Known limits
+
+The check verifies a pre-commit hook exists; it does not verify it is executable, non-empty, or that
+it is the instar-dev gate rather than another hook. A hook that exits 0 immediately would satisfy it
+while gating nothing. It also cannot help retroactively — a commit already made without the gate
+leaves no marker, because nothing ran to leave one.

package/upgrades/1.3.1001.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Adds `docs/specs/decision-replayability-standard.md` (plus its ELI16 companion) — the written
+standard for what must be recorded so a decision can be replayed and re-evaluated later, rather than
+merely asserted to have happened.
+
+It answers the question the operator asked directly: **is a screenshot an acceptable thing to store?**
+For a TERMINAL prompt the answer is no, and not for privacy reasons — the scrubbed pane TEXT of the
+prompt region carries identical information to an image of it, but only text is scrubbable,
+greppable, and diffable. Text is therefore *more* auditable, not less. Images remain the right medium
+only where no text form exists, such as a GUI or a browser.
+
+The standard carries three bounds so the rule cannot quietly become unbounded surveillance: capture
+the prompt REGION rather than full scrollback; scrub before write, never after; and mark a record
+`replayability: degraded` when scrubbing has hollowed it out, so a log can never silently become
+useless while still looking complete.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Docs-only: no runtime surface, no endpoint, no config key, no behaviour change. The standard's own
+`## Decision points touched` and `## Multi-machine posture` sections are present as the spec format
+requires.
+
+Shipped as its own change deliberately. The document was written and staged inside an unrelated
+worktree that is blocked awaiting operator approval — so a finished deliverable was sitting
+uncommitted behind a blocker it has no dependency on, one worktree removal away from being lost.
+Extracting it is the concrete application of the project's own rule that deferral is deletion.
+
+## Known limits
+
+This ships the standard, not its enforcement. Applying it to the first runtime consumer
+(`PermissionPromptAutoResolver`, which today records matched-pattern names and a one-way fingerprint
+but no replayable prompt region) is tracked separately as ACT-1312 and is deliberately NOT bundled
+here. Until that lands, the standard is a written rule with no mechanical guard behind it — which by
+this project's own measure means it is not yet enforced.

package/upgrades/side-effects/gate-installation-selfcheck.md

@@ -0,0 +1,83 @@
+# Side-effects review — write-trace gate-installation self-check
+
+**Change:** `skills/instar-dev/scripts/write-trace.mjs` refuses to write a trace when the instar-dev
+commit gate is not installed (hooksPath points at a missing directory, or no pre-commit hook exists).
+Overridable via `INSTAR_DEV_ALLOW_UNINSTALLED_GATE=1`, and the override is recorded in the trace.
+
+**Decision point touched?** Yes. This adds a refusal — the script now declines an operation it
+previously always performed. Per `docs/signal-vs-authority.md` the refusal is deliberately scoped as
+a SIGNAL: it cannot block a commit (the detected condition is precisely the one where no commit hook
+runs), it only refuses to emit an artifact that would assert an approval that never happened.
+
+---
+
+## 1. Over-block
+
+Real and found during the build, not theorised. The first implementation refused inside any directory
+whose hooks were absent, which broke seven existing tests in `write-trace-tier.test.ts` and
+`duplicate-build-guard-gates.test.ts` — both drive the script inside bare temp directories.
+
+Resolved by scoping the check to its actual hazard: a *git repository* whose hook will not run. A
+directory that is not a git repo has no commit to gate, so the check does not apply. Deliberately NOT
+resolved by setting the override env var in each harness — that would push the burden onto whoever
+writes the next test remembering to do it, which is the willpower-over-structure trade this change
+exists to remove.
+
+Remaining over-block risk: a repo that installs its pre-commit hook by some mechanism other than
+`core.hooksPath` or `.git/hooks/pre-commit` would be refused incorrectly. No such mechanism is used
+in this repo. The override exists for exactly that case and records itself.
+
+## 2. Under-block
+
+The check verifies a pre-commit hook *exists*; it does not verify it is executable, non-empty, or that
+it is actually the instar-dev gate rather than some other hook. A repo with a hook file that exits 0
+immediately would pass this check while gating nothing. Named rather than fixed: deeper verification
+would mean executing or parsing the hook, which is a larger change than the failure being closed.
+
+It also cannot help after the fact. A commit already made without the gate leaves no marker, because
+nothing ran to leave one.
+
+## 3. Level-of-abstraction fit
+
+Correct, and the placement is the substance of the change. The gate cannot detect its own absence —
+an uninstalled hook cannot execute to report that it is uninstalled — so the check must live in
+something that actually runs. Trace-writing is the nearest chokepoint the agent invokes by hand, and
+it is the step whose whole meaning is "this change came through the skill". Putting the check
+anywhere the agent might skip would reproduce the original problem one layer out.
+
+## 4. Signal vs authority compliance
+
+Compliant by construction. It holds no blocking authority over commits and could not acquire any:
+the condition it detects is defined by the absence of the mechanism that would do the blocking. It
+refuses to produce an artifact, which is the weakest possible action, and it fails loudly rather than
+silently. The escape hatch is recorded rather than merely permitted, so an overridden trace is
+distinguishable from an approved one by field presence.
+
+## 5. Interactions
+
+Composes with the pre-commit gate rather than duplicating it: without a trace an in-scope commit is
+refused anyway *once the hook is installed*, so the two layers cover different halves of the same
+failure. The trace gains two fields (`gateInstallationOverridden`, `gateInstallationReason`) emitted
+ONLY on override, so every normal trace round-trips byte-identically and existing readers are
+unaffected.
+
+Adds two `git config` / `git rev-parse` subprocess calls to a script that already shells out. No hot
+path; runs once per commit at most.
+
+## 6. External surfaces
+
+None. `write-trace.mjs` is a development-time script in the instar repo, not shipped behaviour, not
+an endpoint, not agent-visible at runtime. The only observers are instar developers and CI.
+
+## 7. Multi-machine posture
+
+Not applicable — this is a development-time script operating on the local checkout. It introduces no
+state, no persistence, and nothing to replicate, proxy, or reconcile. Every machine that develops
+instar runs its own copy against its own worktree, which is the correct and only sensible posture.
+
+## 8. Rollback cost
+
+Trivial. Remove the check function and its call site; the trace fields disappear with it (they are
+emitted only on override, so nothing else references them). No data migration, no persisted state, no
+agent state. The rollback re-creates the original silent-gate hazard, so it should be accompanied by
+a reason.