instar 1.3.296 → 1.3.297

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.296",
+  "version": "1.3.297",
   "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/decision-audit-presence-check.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// safe-git-allow: CI-only gate script — single read-only `git diff --name-status`
+//   against the Actions checkout; runs on ubuntu runners where the TS
+//   SafeGitExecutor is not importable from a standalone .mjs.
+/**
+ * decision-audit-presence-check — gate-bypass detector (task #81 close-out).
+ *
+ * Every commit that touches in-scope files (src/, scripts/, .husky/, skills/
+ * code) is supposed to pass through the local instar-dev pre-commit gate,
+ * which writes + stages a decision-audit record. When the gate is silently
+ * absent — the live case: a worktree created with raw `git worktree add` has
+ * no husky shim, so `git commit` runs ZERO hooks — the commits arrive with no
+ * audit record, and nothing notices. CI re-runs the substantive checks, but
+ * the audit trail has holes and gate-block UX (tier floors, deferral
+ * detection) never fired for those commits.
+ *
+ * Structure > Willpower: this check makes the bypass VISIBLE at the PR
+ * boundary. A PR whose changes include in-scope files must also carry gate
+ * evidence — a per-entry decision file (post-#827: one
+ * `.instar/instar-dev-decisions/<ts>-<slug>.json` added per gate run) or, as
+ * transition grace for PRs authored under the pre-#827 writer, a modification
+ * to the legacy `.instar/instar-dev-decisions.jsonl`.
+ *
+ * Exemptions mirror the eli16 PR gate: bot authors and the automated
+ * release-cut PR.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+// Keep in sync with inScope() in scripts/instar-dev-precommit.js — the gate
+// this check detects bypasses OF. (A drift here only weakens detection, never
+// blocks a legitimate PR: extra in-scope prefixes would require evidence from
+// PRs the local gate also covers.)
+export function isInScopeFile(file) {
+  if (file.startsWith('src/')) return true;
+  if (file.startsWith('scripts/')) return true;
+  if (file.startsWith('.husky/')) return true;
+  if (file.startsWith('skills/') && file.endsWith('SKILL.md')) return true;
+  if (file.startsWith('skills/') && (file.endsWith('.sh') || file.endsWith('.mjs') || file.endsWith('.js'))) return true;
+  return false;
+}
+
+function isGateEvidence(change) {
+  // Post-#827 per-entry file (added per gate evaluation)…
+  if (/^\.instar\/instar-dev-decisions\/.+\.json$/.test(change.file)) return true;
+  // …or the pre-#827 legacy JSONL append (transition grace for in-flight PRs).
+  if (change.file === '.instar/instar-dev-decisions.jsonl') return true;
+  return false;
+}
+
+/**
+ * Pure evaluation — exported for unit tests.
+ * @param {{ changes: Array<{status: string, file: string}>, title?: string, authorType?: string }} input
+ * @returns {{ ok: boolean, exempt?: string, reason?: string, inScopeFiles?: string[] }}
+ */
+export function evaluateDecisionAuditPresence(input) {
+  const title = String(input?.title ?? '');
+  if (String(input?.authorType ?? '') === 'Bot') return { ok: true, exempt: 'bot-author' };
+  if (/^chore:\s*release\b/i.test(title)) return { ok: true, exempt: 'release-cut' };
+
+  const changes = Array.isArray(input?.changes) ? input.changes : [];
+  const inScopeFiles = changes.map((c) => c.file).filter(isInScopeFile);
+  if (inScopeFiles.length === 0) {
+    return { ok: true, reason: 'no in-scope changes — local gate not required' };
+  }
+
+  const hasEvidence = changes.some(isGateEvidence);
+  if (hasEvidence) {
+    return { ok: true, reason: 'gate evidence present', inScopeFiles };
+  }
+
+  return {
+    ok: false,
+    inScopeFiles,
+    reason:
+      `This PR changes ${inScopeFiles.length} in-scope file(s) but carries NO decision-audit record — ` +
+      `the local instar-dev pre-commit gate did not run for these commits. The usual cause is a build ` +
+      `worktree without the husky shim (created with raw 'git worktree add' instead of 'instar worktree ` +
+      `create'). Fix: in the worktree run 'npm run prepare' (wires .husky/_), then re-commit so the gate ` +
+      `evaluates the change and its audit entry (.instar/instar-dev-decisions/<ts>-<slug>.json) rides the ` +
+      `commit. See tasks #81/#80 and PRs #827/#829.`,
+  };
+}
+
+/** Parse `git diff --name-status base...head` output into change records. */
+export function parseNameStatus(text) {
+  const changes = [];
+  for (const line of String(text).split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    // Format: "<STATUS>\t<path>" (renames: "R100\t<old>\t<new>" — take the new path).
+    const parts = t.split('\t');
+    if (parts.length < 2) continue;
+    const status = parts[0];
+    const file = parts[parts.length - 1];
+    changes.push({ status, file });
+  }
+  return changes;
+}
+
+// ── CLI entrypoint (CI) ────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
+if (invokedDirectly) {
+  const baseSha = process.env.BASE_SHA;
+  const headSha = process.env.HEAD_SHA;
+  if (!baseSha || !headSha) {
+    console.error('decision-audit gate: BASE_SHA and HEAD_SHA env vars are required.');
+    process.exit(2);
+  }
+  let diffOut;
+  try {
+    diffOut = execFileSync('git', ['diff', '--name-status', `${baseSha}...${headSha}`], { encoding: 'utf8' });
+  } catch (err) {
+    console.error(`decision-audit gate: git diff failed — ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(2);
+  }
+  const res = evaluateDecisionAuditPresence({
+    changes: parseNameStatus(diffOut),
+    title: process.env.PR_TITLE,
+    authorType: process.env.PR_AUTHOR_TYPE,
+  });
+  if (res.ok) {
+    console.log(`decision-audit gate: OK — ${res.exempt ? `exempt (${res.exempt})` : res.reason}`);
+    process.exit(0);
+  }
+  console.error('decision-audit gate: FAIL');
+  console.error(res.reason);
+  console.error('');
+  console.error('In-scope files without gate evidence:');
+  for (const f of res.inScopeFiles ?? []) console.error(`  - ${f}`);
+  process.exit(1);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T13:08:42.936Z",
-  "instarVersion": "1.3.296",
+  "generatedAt": "2026-06-05T13:18:11.152Z",
+  "instarVersion": "1.3.297",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.297.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+New `scripts/decision-audit-presence-check.mjs` (pure evaluator + CLI) and `.github/workflows/decision-audit-gate.yml`. The in-scope predicate mirrors `scripts/instar-dev-precommit.js`.
+
+## What to Tell Your User
+
+Nothing user-visible — contributor CI. Pull requests that change gate-scoped code now fail fast if the local pre-commit gate never ran for them (the silent-bypass case), with a message that says exactly how to fix it.
+
+## Summary of New Capabilities
+
+- `decision-audit-gate` CI check: a PR touching src/scripts/.husky/skills code must include a decision-audit record (per-entry file post-#827, or a legacy jsonl modification as transition grace). Bot + release-cut PRs exempt.
+- `.gitignore` now ignores a symlinked `node_modules` too (trailing-slash patterns only match real directories).
+
+## Evidence
+
+Live bypass this detects (2026-06-05): three build worktrees created with raw `git worktree add` had no husky shim — `git commit` ran zero hooks, so a full night's worktree commits carried no decision-audit records and nothing noticed (root fixed in #829; this is the structural backstop). Pinned by `tests/unit/decision-audit-presence-check.test.ts` (9 tests: scope predicate both sides, name-status parsing incl. renames, per-entry evidence passes, legacy-grace passes, the bypass shape FAILS with the actionable husky/`npm run prepare` message, docs-only passes, bot/release exemptions). CLI self-test green on an empty diff.

package/upgrades/decision-audit-presence.eli16.md

@@ -0,0 +1,5 @@
+# A new PR check catches commits that skipped the local safety gate
+
+Every code commit in this repo is supposed to pass through a local pre-commit gate that runs lint, tier checks, and writes a small audit record of the decision. That gate is wired up by husky, a tool that activates git hooks when dependencies are installed. We discovered (the hard way, across three build folders in one night) that folders created with raw git commands never get that wiring — so commits sail through with zero local checks and no audit record, and nothing anywhere notices. CI still re-runs the big checks on the pull request, but the gate's own protections (tier floors, deferral detection, the audit trail) silently never happened.
+
+The root cause in the worktree-creation command is fixed separately. This change adds the structural backstop: a pull-request check that looks at what the PR changes. If it touches gate-scoped code (src, scripts, hooks, skills) it must ALSO carry the gate's audit record — the small decision file the gate stages into every commit it evaluates. A code PR with no record means the gate never ran for those commits, and the check fails with a message that names the likely cause (a worktree without hook wiring) and the exact fix (run `npm run prepare`, then re-commit). Docs-only PRs, bot PRs, and the automated release PR are unaffected, and PRs from before the audit-format change are accepted via their old-format record. Also fixes the `.gitignore` pattern so a symlinked `node_modules` can't be accidentally committed (a slip this very investigation made once).

package/upgrades/side-effects/decision-audit-presence.md

@@ -0,0 +1,47 @@
+# Side-Effects Review — decision-audit presence PR gate (task #81 close-out)
+
+**Version / slug:** `decision-audit-presence`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; over-block analysis below covers every legitimate-PR shape considered`
+
+## Summary of the change
+
+New PR-boundary check (`scripts/decision-audit-presence-check.mjs` + `.github/workflows/decision-audit-gate.yml`): a PR whose diff touches gate-scoped files (src/, scripts/, .husky/, skills/ code — the same `inScope` predicate as the pre-commit gate) must also carry gate evidence: an added `.instar/instar-dev-decisions/*.json` per-entry file (post-#827) or a modified legacy `.instar/instar-dev-decisions.jsonl` (transition grace). Otherwise it fails with an actionable message naming the husky-shim cause and the `npm run prepare` fix. Plus: `.gitignore` `node_modules/` → `node_modules` so the worktree node_modules SYMLINK is ignored too (trailing-slash patterns match only directories; the symlink slipped into a commit once tonight).
+
+## Decision-point inventory
+
+- `evaluateDecisionAuditPresence` — add — pure; exemptions mirror the eli16 PR gate (Bot authors, `chore: release` titles).
+- `isInScopeFile` — add — duplicated from `scripts/instar-dev-precommit.js` `inScope()` with a sync comment; drift only weakens detection, never blocks a PR the local gate doesn't also cover.
+- Workflow — add — `pull_request` types opened/synchronize/reopened/ready_for_review, `contents: read`, full-depth checkout for the three-dot diff.
+- `.gitignore` — modified — one-line pattern fix.
+
+## 1. Over-block analysis (can this fail a legitimate PR?)
+
+- **Docs/tests/upgrades-only PRs** — pass (no in-scope files).
+- **In-flight pre-#827 PRs** — pass via the legacy-jsonl grace path (their gate appended a line).
+- **Gated code PRs** — pass: the gate stages an audit record into every evaluated commit (post-#814), so evidence is present by construction.
+- **The genuinely-blocked shape** — in-scope changes with NO record — is exactly the bypass this exists to surface. The failure message gives the one-command fix.
+- **Bots + release-cut** — exempt, mirroring the eli16 gate.
+- **Squash-merge interaction** — none: the check runs on the PR diff (base...head), not on merged history.
+- Residual risk: an operator hand-editing in-scope files via the GitHub web UI would fail the check — correctly, since the gate never evaluated that change; the fix message applies (commit locally through the gate).
+
+## 2. Under-block
+
+Evidence is presence-based, not per-commit: one gated commit in a PR vouches for the PR even if a sibling commit bypassed. Accepted for this slice — the common failure mode (a WHOLE worktree without hooks) produces zero evidence and is caught. Per-commit matching would need trace↔commit correlation; noted as a possible tightening, not promised.
+
+## 3. Signal vs authority
+
+Deterministic file-presence check — no LLM, no semantic classification. Authority shape matches existing required CI (eli16 gate, repo invariants).
+
+## 4. Migration parity
+
+None — repo CI infrastructure, not agent-installed files.
+
+## 5. Token/cost impact
+
+One ubuntu CI job per PR event, seconds long. No LLM calls.
+
+## 6. Rollback
+
+Delete the workflow file (or revert); the script is inert without it.