instar 1.3.282 → 1.3.283

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.282",
+  "version": "1.3.283",
   "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/instar-dev-precommit.js

@@ -780,6 +780,15 @@ function blockCommit(files, reason) {
 // Append exactly one JSON line to .instar/instar-dev-decisions.jsonl for every
 // in-scope commit (regardless of tier branch). Best-effort: a logging failure
 // must never crash the gate.
+//
+// The line is then STAGED so it rides the very commit it describes. Without
+// this, a pre-commit-hook append always lands AFTER staging, leaving the line
+// uncommitted in the building worktree's tracked decisions file — one-PR
+// worktrees never commit it, worktree reclaim deletes it, and the audit trail
+// silently leaks (the task-#62 "decision-audit didn't fire" mystery: it DID
+// fire, the line just evaporated with the worktree). If the commit is later
+// blocked by the gate, the staged line simply rides the retry commit — both
+// lines describe real gate evaluations.
 function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, riskFloorReasons, belowFloor, files, loc }) {
   try {
     fs.mkdirSync(path.dirname(DECISIONS_LOG), { recursive: true });
@@ -799,6 +808,7 @@ function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, risk
         loc,
       }) + '\n',
     );
+    execSync(`git add ${JSON.stringify(path.relative(ROOT, DECISIONS_LOG))}`, { cwd: ROOT });
   } catch {
     // best-effort — never block on audit I/O
   }

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T09:21:22.569Z",
-  "instarVersion": "1.3.282",
+  "generatedAt": "2026-06-05T09:56:36.782Z",
+  "instarVersion": "1.3.283",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.283.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+One change in `writeDecisionAudit` (auto-stage after append) + a regression test (`tests/unit/instar-dev-precommit-audit-staging.test.ts`) pinning that the line is written AND staged even when the gate blocks. Root cause of the task-#62 "decision-audit didn't fire" mystery: it fired; the line sat uncommitted in the building worktree and was deleted with it.
+
+## What to Tell Your User
+
+Nothing user-visible. An internal audit-trail leak is closed: the per-commit build-decision record (tier declared vs suggested) used to evaporate with reclaimed worktrees; it now travels inside the commit it describes.
+
+## Summary of New Capabilities
+
+- `scripts/instar-dev-precommit.js` stages `.instar/instar-dev-decisions.jsonl` right after appending the audit line, so the line lands in the same commit it audits.
+- A gate-blocked commit leaves the line staged; it rides the retry commit (both evaluations were real).
+
+## Evidence
+
+Reproduced live twice on 2026-06-05 before the fix: two build worktrees (`keychain-per-agent`, then `dev-claim-check`) each held an orphaned, uncommitted `+{"ts":"2026-06-05T08:49:24Z","slug":"keychain-per-agent-master-key",...}` line in the tracked `.instar/instar-dev-decisions.jsonl` after their PR commit — `git status` showed ` M .instar/instar-dev-decisions.jsonl` post-commit, and removing the worktree would have deleted the only copy (one line was hand-rescued before reclaim). After the fix, observed on PR #814's own commit: `git status --short .instar/instar-dev-decisions.jsonl` is CLEAN immediately post-commit and the commit diff contains the gate's own audit line for that very commit — the dogfood proof quoted in the PR body.

package/upgrades/decision-audit-self-commit.eli16.md

@@ -0,0 +1,3 @@
+# Decision-audit lines now ride their own commit
+
+Every gated commit writes one audit line recording what tier was declared vs suggested — the accountability record for build decisions. But the line was written DURING the commit (by the pre-commit hook), which means it landed just after the files were staged — so it sat uncommitted in the building worktree. Most worktrees produce exactly one PR and then get deleted, taking the audit line with them. The record looked like it "never fired" when it actually fired and evaporated. Now the hook stages the audit file right after writing it, so the line travels inside the very commit it describes. If the gate blocks the commit, the staged line simply rides the retry — both lines describe real evaluations.

package/upgrades/side-effects/decision-audit-self-commit.md

@@ -0,0 +1,40 @@
+# Side-Effects Review — decision-audit self-commit
+
+**Version / slug:** `decision-audit-self-commit`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane (one-line hook change, audit-integrity fix)`
+
+## Summary of the change
+
+`writeDecisionAudit` in `scripts/instar-dev-precommit.js` now stages `.instar/instar-dev-decisions.jsonl` immediately after appending the audit line, so the line rides the very commit it describes. Closes the task-#62 audit leak: pre-commit-hook appends land after staging, leaving the line uncommitted in the building worktree; one-PR worktrees never commit it and worktree reclaim deletes it (confirmed live twice on 2026-06-05).
+
+## Decision-point inventory
+
+- `writeDecisionAudit` — modified — `git add <decisions file>` inside the existing best-effort try block, after a successful append.
+
+## 1. Over-block
+
+None. The `git add` lives inside the existing best-effort catch — any failure (git unavailable, index lock) is swallowed exactly like an audit-write failure today; the gate never blocks on audit I/O.
+
+## 2. Over-permit
+
+None. Staging one known repo-tracked file adds no permissive path. The file was already tracked and union-style appended; lines now simply become part of commits.
+
+## 3. Behavioral notes
+
+- **Blocked commit:** the audit line is written + staged, then the gate may block. The staged line rides the author's retry commit — both evaluations were real; the record gains fidelity, not noise.
+- **Out-of-scope commits** (docs/tests-only) still exit before the audit by design — unchanged.
+- **Merge-conflict surface:** parallel PRs already both append to this tracked file; lines now actually LAND, so conflicts become possible where silent loss was before. The file is append-only JSONL — union-merge resolution is trivial and already practiced.
+
+## 4. Migration parity
+
+None needed — `scripts/` ships with the repo; agents get it on update like any source change. No config/hook-template/skill changes.
+
+## 5. Token/cost impact
+
+None. One `git add` of one file per gated commit.
+
+## 6. Rollback
+
+Revert the commit; audit lines return to being orphaned working-tree modifications (the prior, leaky behavior).