instar 1.3.289 → 1.3.290

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.289",
+  "version": "1.3.290",
   "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

@@ -36,7 +36,15 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const ROOT = path.resolve(__dirname, '..');
 const TRACES_DIR = path.join(ROOT, '.instar', 'instar-dev-traces');
-const DECISIONS_LOG = path.join(ROOT, '.instar', 'instar-dev-decisions.jsonl');
+// Legacy single-file audit log (frozen 2026-06-05 — read-only history).
+// Every gated commit used to APPEND one line here; because the line rides the
+// commit (the task-#62 fix), any two PRs in flight both modified this file's
+// tail and conflicted at the merge point — a structural conflict generator at
+// parallel-PR cadence (live hit: PR #824 went CI-green then failed merge on
+// exactly this file). New entries are one-file-per-decision under
+// DECISIONS_DIR instead: distinct filenames can never conflict.
+// (The frozen legacy file remains at .instar/instar-dev-decisions.jsonl.)
+const DECISIONS_DIR = path.join(ROOT, '.instar', 'instar-dev-decisions');
 const WINDOW_MS = 60 * 60 * 1000; // 60 minutes
 const MIN_ARTIFACT_CHARS = 200;
 
@@ -257,7 +265,7 @@ const decision = decideRequirementSet(declaredTier);
 // belowFloor = the agent declared UNDER the risk-signaled floor. We never
 // block on it (the mind holds authority) — the record is the backstop.
 const belowFloor = declaredTier != null && declaredTier < tierSignal.riskFloor;
-writeDecisionAudit({
+const decisionEntryPath = writeDecisionAudit({
   slug,
   suggestedTier: tierSignal.suggestedTier,
   declaredTier,
@@ -276,7 +284,7 @@ if (belowFloor) {
   console.error(`  declared Tier ${declaredTier} < risk floor ${tierSignal.riskFloor}. Risk signals:`);
   for (const r of tierSignal.reasons) console.error(`    • ${r}`);
   if (tierReasoning) console.error(`  Your tierReasoning: ${tierReasoning}`);
-  console.error(`  Recorded to ${path.relative(ROOT, DECISIONS_LOG)} (belowFloor:true).`);
+  console.error(`  Recorded to ${path.relative(ROOT, decisionEntryPath ?? DECISIONS_DIR)} (belowFloor:true).`);
   console.error('');
 }
 
@@ -791,26 +799,39 @@ function blockCommit(files, reason) {
 // lines describe real gate evaluations.
 function writeDecisionAudit({ slug, suggestedTier, declaredTier, riskFloor, riskFloorReasons, belowFloor, files, loc }) {
   try {
-    fs.mkdirSync(path.dirname(DECISIONS_LOG), { recursive: true });
-    fs.appendFileSync(
-      DECISIONS_LOG,
+    fs.mkdirSync(DECISIONS_DIR, { recursive: true });
+    const ts = new Date().toISOString();
+    // Filename: sortable timestamp + sanitized slug → chronological `ls`,
+    // and a DISTINCT file per decision so parallel PRs can never conflict
+    // on the audit trail (each adds its own file; git merges additions of
+    // different paths trivially, including GitHub's server-side merge).
+    const safeSlug = String(slug).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
+    let entryPath = path.join(DECISIONS_DIR, `${ts.replace(/[:.]/g, '-')}-${safeSlug}.json`);
+    let n = 1;
+    while (fs.existsSync(entryPath)) {
+      entryPath = path.join(DECISIONS_DIR, `${ts.replace(/[:.]/g, '-')}-${safeSlug}-${n++}.json`);
+    }
+    fs.writeFileSync(
+      entryPath,
       JSON.stringify({
-        ts: new Date().toISOString(),
+        ts,
         slug,
         suggestedTier,
         declaredTier,
-        // riskFloor (the number) keeps the line self-contained for later review
+        // riskFloor (the number) keeps the entry self-contained for later review
         // without re-running the classifier — not just the derived belowFloor.
         riskFloor,
         riskFloorReasons,
         belowFloor,
         files,
         loc,
-      }) + '\n',
+      }, null, 2) + '\n',
     );
-    execSync(`git add ${JSON.stringify(path.relative(ROOT, DECISIONS_LOG))}`, { cwd: ROOT });
+    execSync(`git add ${JSON.stringify(path.relative(ROOT, entryPath))}`, { cwd: ROOT });
+    return entryPath;
   } catch {
     // best-effort — never block on audit I/O
+    return null;
   }
 }
 

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T11:25:48.194Z",
-  "instarVersion": "1.3.289",
+  "generatedAt": "2026-06-05T11:59:51.712Z",
+  "instarVersion": "1.3.290",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.290.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`writeDecisionAudit` in `scripts/instar-dev-precommit.js` writes one file per decision instead of appending a line to one shared JSONL. Two PRs each ADDING a distinct path can never merge-conflict; appending to the same file's tail always did. Same payload, same best-effort/never-block semantics, collision-suffixed filenames.
+
+## What to Tell Your User
+
+Nothing user-visible — this is contributor infrastructure. Pull requests no longer fail to merge over the development decision-audit log.
+
+## Summary of New Capabilities
+
+- Each gated commit's decision-audit record is now its own file under `.instar/instar-dev-decisions/<timestamp>-<slug>.json` (chronological by filename), staged so it still rides the commit it describes.
+- The legacy `.instar/instar-dev-decisions.jsonl` is frozen history — no new appends.
+
+## Evidence
+
+Live failure this fixes (2026-06-05): PR #824 passed all 19 CI checks, then `gh pr merge --squash --admin` failed with "Pull Request has merge conflicts" — `git merge` against main showed exactly ONE conflicted file, `.instar/instar-dev-decisions.jsonl`, because sibling PRs had appended their own audit lines to the same tail while #824 was in CI. Unblocked manually by union-resolving; this change removes the class. Pinned by `tests/unit/instar-dev-precommit-audit-staging.test.ts`: the gate-blocked commit still stages its entry file (the #814 property preserved), two evaluations produce two DISTINCT paths (the conflict-immunity property), and the frozen legacy JSONL is not appended to; the deferrals suite's audit-shape test re-pinned to the per-entry record (riskFloor number, belowFloor, suggestedTier, reasons array). 16/16 tests green.

package/upgrades/decisions-per-entry.eli16.md

@@ -0,0 +1,5 @@
+# Parallel PRs stop colliding on the decision-audit log
+
+Every gated commit records a small audit note (what tier was declared, what the risk classifier suggested). A recent fix made that note ride along inside the commit itself — which solved one problem (notes were evaporating with temporary build folders) but quietly created another: all the notes went into ONE shared file, each commit appending a line at the end. Git can't merge two different "last lines" of the same file, so whenever two pull requests were in flight at the same time — which is now the normal state with three agents shipping in parallel — the second one to merge hit a conflict on that file. This actually happened within hours: a PR passed every check and then failed to merge over nothing but the audit log.
+
+The fix: each decision now gets its own tiny file (named by timestamp and change name) inside a decisions folder, instead of a line appended to a shared file. Two PRs each ADDING a different file never conflict — git and GitHub merge that trivially. Nothing about the audit content changes, the note still rides the commit it describes, and the old log file stays in place as frozen history. The chronological order you used to get from reading the file top-to-bottom now comes from sorting filenames, which start with the timestamp.

package/upgrades/side-effects/decisions-per-entry.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — per-entry decision-audit files (task #80)
+
+**Version / slug:** `decisions-per-entry`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; the audit-continuity question (does the trail survive the format change?) addressed below`
+
+## Summary of the change
+
+`writeDecisionAudit` in the pre-commit gate writes each decision as its own file `.instar/instar-dev-decisions/<ts>-<slug>.json` (staged immediately, preserving #814's ride-the-commit property) instead of appending one line to the shared `.instar/instar-dev-decisions.jsonl`. Distinct paths per PR cannot merge-conflict — including GitHub's server-side merge, which does not honor custom merge drivers. The legacy JSONL freezes in place as history.
+
+## Decision-point inventory
+
+- `writeDecisionAudit` — modified — per-entry file write + stage; same payload fields (ts/slug/tiers/riskFloor/reasons/belowFloor/files/loc); collision-suffix counter for same-ms-same-slug; returns the entry path (used by the belowFloor console message).
+- `DECISIONS_LOG` const — removed (legacy path noted in comment); `DECISIONS_DIR` added.
+- Tests — `instar-dev-precommit-audit-staging.test.ts` re-pinned to the per-entry contract + a NEW conflict-immunity test (two evaluations → two distinct paths) + asserts the legacy JSONL is NOT created; `instar-dev-precommit-deferrals.test.ts` audit-shape test re-pinned.
+
+## 1. Direction-of-failure analysis
+
+- **Old failure (live, PR #824):** CI-green PR fails admin-merge on the audit file tail — recurring at parallel-PR cadence, blocks every second merge, requires manual union resolution each time.
+- **New worst case:** the writer remains best-effort (try/catch, never blocks the gate) — an audit I/O failure loses ONE entry, exactly as before. Filename collision (same ms + same slug) is suffix-countered, pinned by test.
+- **Audit continuity:** the legacy file is untouched history; new entries are chronologically sortable by filename (`ls` order = time order). Readers: only tests read the trail today (grep-verified); both updated.
+- **In-flight PRs written under the old scheme:** once main's shared file stops growing, their single appended line vs main's unchanged tail merges CLEANLY — landing this fix un-jams the conflict class for already-open PRs too (the conflict needed BOTH sides appending).
+
+## 2. Over-permit
+
+None — the gate's blocking logic is untouched; only where the audit record lands.
+
+## 3. Scope deliberately NOT taken
+
+- No migration of legacy JSONL lines into per-entry files — history stays where it was written; a reader that wants the full trail reads both (documented in the script comment).
+- No `.gitattributes merge=union` belt for the legacy file — GitHub's server-side merge ignores it, and with the file frozen the local-rebase benefit is moot.
+
+## 4. Migration parity
+
+None needed — the gate script lives in the repo (`scripts/`), not in agent-installed files; every checkout gets it with the commit. `.instar/instar-dev-decisions/` is created on demand by the writer.
+
+## 5. Token/cost impact
+
+None — same write volume, one file create vs one append per gated commit.
+
+## 6. Rollback
+
+Revert the commit; the writer returns to appending the shared JSONL (and the conflict class returns with it).