instar 1.3.880 → 1.3.882

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.880",
+  "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-19T11:44:57.289Z",
-  "instarVersion": "1.3.880",
+  "generatedAt": "2026-07-19T21:04:24.400Z",
+  "instarVersion": "1.3.882",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.881.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Added the canonical WS3–WS4 Slack apprenticeship retrospective with attributed defects and durable lessons.
+- Added a non-executing WS5 scope stub for the future demo-channel responding rung, including preconditions, operator-only enforcement authority, rollback, and the required test matrix.
+
+## What to Tell Your User
+
+The Slack demo work is now consolidated into one durable retrospective: what succeeded, what failed, who caught each defect, and the rules those incidents earned. It also defines the next responding-mode rung without enabling it; the operator retains the decision to grant real speaking authority.
+
+## Summary of New Capabilities
+
+- No runtime capability is enabled by this documentation PR.
+- A future WS5 build now has an explicit acceptance matrix and operator-only enforcement boundary.
+
+## Evidence
+
+- `docs/apprenticeship/slack-workstream-retro.md`
+- PR #1518 (merge `4f80badcee8e72fd10a4ced155352aeba907199e`) and feedback entries `fb-b1010093-9db`, `fb-d54eb6d4-8d2`

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 }`.

package/upgrades/side-effects/slack-workstream-retro.md

@@ -0,0 +1,45 @@
+# Side-effects review: Slack workstream retrospective and WS5 scope
+
+This is a documentation-only change. It changes no runtime, configuration, credentials, Slack state, or enforcement posture.
+
+## Over-block
+
+None at runtime. The scope intentionally states that observe-to-respond requires an operator decision; this documents the existing authority boundary rather than adding a gate.
+
+## Under-block
+
+The WS5 matrix is a design stub, not executable enforcement. A future implementation must earn each assertion and must not cite this document as permission to flip responding on.
+
+## Level-of-abstraction fit
+
+The apprenticeship retrospective belongs under `docs/apprenticeship/`: it preserves attributed program evidence and converts incidents into reusable development constraints. The forward scope is colocated so the next increment starts from the earned evidence rather than chat archaeology.
+
+## Signal vs authority compliance
+
+The document explicitly separates readiness signals from the operator's authority to move the adapter from observe-only to responding. No detector or model verdict is granted authority.
+
+## Interactions
+
+No runtime interaction. The prose aligns the Slack reprovision runbook, PR #1518's source-bound relay, owned-identity self-unblock posture, and existing operator-only enforcement principle.
+
+## External surfaces
+
+The document is repository-visible. It contains non-secret identifiers only as issue/PR references and no Slack credentials, tokens, private message text, or raw user identifiers.
+
+## Multi-machine posture
+
+The scope requires owner-local refusal, durable custody, and exactly one speaking machine. This review makes no claim that those future cells are already implemented.
+
+## Rollback cost
+
+Documentation-only revert. No data or external-state repair would be required.
+
+## Operator-surface quality
+
+The future decision surface is specified to show exact scope, evidence freshness, known gaps, and rollback. No operator UI is added here.
+
+## Conclusion
+
+The retrospective is an honest consolidation of completed evidence, and the WS5 section is explicitly non-executing. No side-effect concern blocks publication.
+
+The operator-authority boundary remains unchanged by this documentation.

package/upgrades/slack-workstream-retro.eli16.md

@@ -0,0 +1,11 @@
+# Slack workstream retrospective and WS5 scope — plain-English overview
+
+This change records what Instar-codey and Echo learned while bringing a dedicated demo Slack app from provisioning through a real end-to-end conversation path. It does not turn on any new Slack behavior. The retrospective captures the successful pieces—distinct app identity, verified permissions and channel membership, live inbound events, thread routing, and the source-bound reply relay shipped in PR #1518—and it names the failures that made those contracts necessary.
+
+The most important lesson is that several green-looking signals are narrower than they appear. A connected Socket Mode WebSocket does not prove that Slack event subscriptions survived an app update. A manifest write does not prove a bot token gained the intended scopes. A plausible credential file does not replace a signed or owner-issued identity attestation. And a spawned session does not need arbitrary channel coordinates; it needs a narrowly bound way to answer the conversation that created it.
+
+The document also scopes the next Slack increment without building it. Today the demo adapter observes and records decisions but does not autonomously speak. WS5 would prove a real authorized human can direct the agent in a demo channel and receive one useful, thread-correct response. That observe-to-respond transition is a genuine authority change. Tests and reviewers can show readiness, but only the operator may enable it. The proposed matrix covers authorized and unauthorized senders, ambient traffic, duplicates, recovery, cross-machine owner-dark behavior, one-voice delivery, rollback, migration parity, and cleanup.
+
+The decision this document enables is simple: whether to authorize a future build of WS5 under those boundaries. This PR itself makes no configuration change, touches no Slack workspace, and grants no speaking authority.
+
+Readers should treat the proposed matrix as a future acceptance contract, never as evidence that respond mode is already ready or enabled.