instar 1.3.881 → 1.3.882

package/package.json

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

@@ -337,8 +337,11 @@ if (traceEntries.length === 0) {
 }
 
 // ─── Step 4.5: read the agent's DECLARED tier + branch ───────────────────
-// The agent records its tier in the trace JSON. We peek the freshest fresh
-// trace to read `trace.tier` (1|2|3). decideRequirementSet() factors the pure
+// The agent records its tier in the trace JSON. Select the freshest trace that
+// actually covers THIS staged change before reading its identity or tier. A
+// merely-newer trace from another worktree/task must never label this decision
+// audit (the feedback-class failure behind fb-2b24aa04-540).
+// decideRequirementSet() factors the pure
 // enforcement decision:
 //   - tier 1            → 'tier1-lite'  (ELI16 + side-effects staged; no spec)
 //   - tier 2 / 3        → 'tier2-full'  (the EXISTING full validation, unchanged)
@@ -347,8 +350,28 @@ if (traceEntries.length === 0) {
 let declaredTier = null;
 let tierReasoning = '';
 let freshestTrace = null;
+let freshestTraceEntry = null;
+for (const entry of traceEntries) {
+  try {
+    const candidate = JSON.parse(fs.readFileSync(entry.file, 'utf8'));
+    const covered = new Set(candidate?.coveredFiles || []);
+    if (candidate?.phase === 'complete' && inScopeFiles.every((f) => covered.has(f))) {
+      freshestTrace = candidate;
+      freshestTraceEntry = entry;
+      break;
+    }
+  } catch {
+    // The full validation path below reports malformed attempts. They are not
+    // eligible to provide identity/tier metadata for this staged change.
+  }
+}
+if (!freshestTrace || !freshestTraceEntry) {
+  blockCommit(
+    inScopeFiles,
+    'No fresh complete trace covers this staged change. Run the /instar-dev skill for the files being committed.',
+  );
+}
 try {
-  freshestTrace = JSON.parse(fs.readFileSync(traceEntries[0].file, 'utf8'));
   if (freshestTrace && (freshestTrace.tier === 1 || freshestTrace.tier === 2 || freshestTrace.tier === 3)) {
     declaredTier = freshestTrace.tier;
   }
@@ -360,7 +383,13 @@ try {
   // path (the existing Step 5 loop will surface the malformed-JSON attempt).
 }
 
-const slug = (freshestTrace && (freshestTrace.slug || freshestTrace.name)) || 'unknown';
+const slug = (freshestTrace && (
+  freshestTrace.slug ||
+  freshestTrace.name ||
+  (typeof freshestTrace.artifactPath === 'string'
+    ? path.basename(freshestTrace.artifactPath, path.extname(freshestTrace.artifactPath))
+    : null)
+)) || 'unknown';
 const decision = decideRequirementSet(declaredTier);
 
 // ─── Step 4.55: causal autopsy (directive 2026-06-05) ───────────────────
@@ -480,7 +509,7 @@ if (belowFloor) {
 // (The tests/lint requirement from the spec lives in the pre-PUSH gate, not
 // here: this pre-COMMIT hook checks ARTIFACTS only.)
 if (decision.requirementSet === 'tier1-lite') {
-  enforceTier1(freshestTrace, traceEntries[0].file);
+  enforceTier1(freshestTrace, freshestTraceEntry.file);
   // enforceTier1 either passes through (process.exit(0)) or blockCommit()s.
 }
 

package/skills/instar-dev/scripts/write-trace.mjs

@@ -212,6 +212,9 @@ const duplicateBuildCheck = readDuplicateBuildCheck();
 
 const trace = {
   version: toolchain ? 3 : 2, // v3 only when enriched; readers ignore unknown fields either way
+  // Stable work-item identity. The pre-commit decision audit consumes this;
+  // omitting it forced valid generated traces into the `unknown` bucket.
+  slug,
   sessionId: process.env.INSTAR_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID || 'unknown',
   timestamp,
   artifactPath: artifact,

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-19T13:38:17.474Z",
-  "instarVersion": "1.3.881",
+  "generatedAt": "2026-07-19T21:04:24.400Z",
+  "instarVersion": "1.3.882",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.882.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Persisted stable work-item identity in generated Instar development traces.
+- Bound decision evidence to the staged change's matching trace before reading identity or tier, with a compatibility fallback for legacy traces.
+- Added regressions for missing generated identity and a newer foreign `unknown` trace competing with the correct trace.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- Feedback: `fb-2b24aa04-540`
+- Test: `tests/unit/instar-dev-precommit-audit-staging.test.ts`
+- Test: `tests/unit/write-trace-tier.test.ts`

package/upgrades/decision-audit-trace-binding.eli16.md

@@ -0,0 +1,9 @@
+# Decision audit trace binding
+
+Instar records a small decision artifact whenever its own development gate evaluates a change. That artifact is supposed to answer a simple future question: which work item was this decision about, and what change did the gate actually evaluate? The gate previously answered that question using the newest trace file written in the last hour. In a busy development environment, however, the newest trace can belong to another task or another attempted commit. That let a real change be recorded under `unknown` or under a foreign work-item name even though a correct trace for the staged files was present.
+
+This repair changes the binding rule for the whole class, not just the reported instance. The canonical trace writer now persists the stable slug it already derives from the side-effects artifact. Before the gate reads a trace's tier, slug, or causal record, it requires that trace to be complete and to cover every staged behavior file. Newer unrelated or malformed traces are skipped. For older generated traces that predate the slug field, the gate derives the same stable identity from `artifactPath`. If no trace covers the staged change, the commit is refused with a direct explanation instead of emitting misleading evidence.
+
+The important invariant is: development evidence is selected by scope first and recency second. A regression test creates two fresh traces—an older correct trace and a newer foreign `unknown` trace—and proves that the resulting decision record uses the correct work-item identity. This closes feedback item `fb-2b24aa04-540` and upgrades the development process so parallel work cannot recreate the same evidence-misbinding class.
+
+There is no runtime or user-facing behavior change. The affected surface is the Instar source repository's pre-commit ceremony. Rollback is a normal code revert; no persisted runtime state or migration is involved.

package/upgrades/side-effects/decision-audit-trace-binding.md

@@ -0,0 +1,72 @@
+# Side-Effects Review — decision audit trace binding
+
+**Version / slug:** `decision-audit-trace-binding`
+**Date:** `2026-07-19`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The trace writer now persists its derived slug, and the pre-commit gate selects the newest complete trace whose `coveredFiles` includes every staged behavior file before reading tier, slug, or class evidence. Legacy traces fall back to their artifact basename. Regression tests pin both causes from `fb-2b24aa04-540`: missing generated identity and a newer foreign trace.
+
+## Decision-point inventory
+
+- `scripts/instar-dev-precommit.js` trace selection — modified — deterministically binds evidence to the staged change and refuses when no binding exists.
+
+## 1. Over-block
+
+A legacy hand-written trace without `phase: complete` or without complete behavior-file coverage is now refused earlier. That is intentional: such a trace cannot honestly describe the staged decision.
+
+## 2. Under-block
+
+Two traces can both cover the same files; recency remains the tie-breaker. The trace SHA and artifact checks still validate the selected trace later in the gate.
+
+## 3. Level-of-abstraction fit
+
+The repair spans the canonical trace producer and the pre-commit evidence binder. It persists the already-derived artifact slug and reuses the existing `coveredFiles` contract instead of introducing another identity system.
+
+## 4. Signal vs authority compliance
+
+[docs/signal-vs-authority.md](../../docs/signal-vs-authority.md) applies. This is an enumerable integrity invariant: evidence either covers all staged behavior files or it does not. The deterministic gate correctly holds blocking authority over an invalid development commit.
+
+## 4b. Judgment-point check
+
+No competing-signals judgment is introduced. Scope membership is an exact set-containment invariant.
+
+## 5. Interactions
+
+The selector runs before Tier-1 branching and before the existing full trace validation. It cannot double-fire. Full artifact, SHA, and spec validation remain unchanged. Parallel worktrees may leave traces behind, but those traces no longer influence unrelated staged changes.
+
+## 6. External surfaces
+
+No runtime, user, operator, network, or API surface changes. The persistent decision audit becomes more accurate.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Machine-local by design: pre-commit traces and staged changes belong to one development worktree on one machine. It emits no user notice, creates no transferable runtime state, and generates no URL.
+
+## 8. Rollback cost
+
+Pure development-tooling code change. Revert and ship; no migration or agent-state repair is required.
+
+## Conclusion
+
+The class review found the missing standard was scope-bound evidence selection, and the process gap was reading identity from the newest trace before proving it described the staged files. The code and regression ratchet now enforce scope-first, recency-second selection. Clear to ship.
+
+## Second-pass review
+
+Not required: this does not touch runtime messaging, sessions, sentinels, guards, or watchdogs.
+
+## Evidence pointers
+
+- `tests/unit/instar-dev-precommit-audit-staging.test.ts`
+- `tests/unit/write-trace-tier.test.ts`
+- Feedback `fb-2b24aa04-540`
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: claim-vs-evidence`, `closure: guard`, `guardEvidence: { enforcementType: gate, citation: scripts/instar-dev-precommit.js#freshestTraceEntry, howCaught: the gate selects only a complete trace covering every staged behavior file before using its slug or tier, so a newer foreign or unknown trace cannot label the decision }`.