instar 1.3.19 → 1.3.20

package/dist/feedback-factory/processor/reopen.d.ts

@@ -0,0 +1,39 @@
+/**
+ * reopen.ts — TS port of the auto-reopen-on-regression decision.
+ *
+ * Ports the decision embedded in cmd_apply_clusters (the-portal/.claude/scripts/
+ * feedback-processor.py, the regression branch ~:1543) out of the DB-write code
+ * into a pure function. When the clustering driver (cluster.ts) merges a new
+ * report into a cluster that was already fixed/resolved/deferred (a "possible
+ * regression" note), the cluster is auto-reopened. This computes the reopen
+ * outcome from the cluster's prior status:
+ *
+ *   - deferred  → AGED-REOPEN  → status 'new',          annotate actionTaken,   no recurrence bump
+ *   - otherwise → REGRESSION   → status 'investigating', annotate researchNotes, bump recurrenceCount
+ *
+ * The DB writes (the prisma update with `{ increment: 1 }` etc.) stay in the
+ * adapter; this is the pure decision + the audit-note text. `now` is injected.
+ * Reference is interleaved with DB I/O, so equivalence is by faithful
+ * transcription + exhaustive unit tests (no clean isolated reference function to
+ * run a cross-runtime harness against).
+ */
+import type { Cluster } from './types.js';
+export interface ReopenDecision {
+    /** New lifecycle status to set on the reopened cluster. */
+    newStatus: 'new' | 'investigating';
+    /** Whether to bump recurrenceCount (chronic-regression accounting; NOT for aged-reopen). */
+    bumpRecurrence: boolean;
+    /** Which cluster field the audit note is appended to. */
+    annotateField: 'actionTaken' | 'researchNotes';
+    /** The note tag. */
+    noteTag: 'AGED-REOPEN' | 'REGRESSION';
+    /** The audit note appended to the chosen field. */
+    note: string;
+}
+/**
+ * Compute the auto-reopen outcome for a cluster being merged into on a regression.
+ * `wasStatus` is the cluster's status before reopen; `feedbackId` is the incoming
+ * report; `now` is the injected ISO timestamp (reference uses new Date().toISOString()).
+ */
+export declare function computeReopen(cluster: Cluster, feedbackId: string, now: string): ReopenDecision;
+//# sourceMappingURL=reopen.d.ts.map

package/dist/feedback-factory/processor/reopen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reopen.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/reopen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,SAAS,EAAE,KAAK,GAAG,eAAe,CAAC;IACnC,4FAA4F;IAC5F,cAAc,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,aAAa,EAAE,aAAa,GAAG,eAAe,CAAC;IAC/C,oBAAoB;IACpB,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC;IACtC,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAiB/F"}

package/dist/feedback-factory/processor/reopen.js

@@ -0,0 +1,41 @@
+/**
+ * reopen.ts — TS port of the auto-reopen-on-regression decision.
+ *
+ * Ports the decision embedded in cmd_apply_clusters (the-portal/.claude/scripts/
+ * feedback-processor.py, the regression branch ~:1543) out of the DB-write code
+ * into a pure function. When the clustering driver (cluster.ts) merges a new
+ * report into a cluster that was already fixed/resolved/deferred (a "possible
+ * regression" note), the cluster is auto-reopened. This computes the reopen
+ * outcome from the cluster's prior status:
+ *
+ *   - deferred  → AGED-REOPEN  → status 'new',          annotate actionTaken,   no recurrence bump
+ *   - otherwise → REGRESSION   → status 'investigating', annotate researchNotes, bump recurrenceCount
+ *
+ * The DB writes (the prisma update with `{ increment: 1 }` etc.) stay in the
+ * adapter; this is the pure decision + the audit-note text. `now` is injected.
+ * Reference is interleaved with DB I/O, so equivalence is by faithful
+ * transcription + exhaustive unit tests (no clean isolated reference function to
+ * run a cross-runtime harness against).
+ */
+/**
+ * Compute the auto-reopen outcome for a cluster being merged into on a regression.
+ * `wasStatus` is the cluster's status before reopen; `feedbackId` is the incoming
+ * report; `now` is the injected ISO timestamp (reference uses new Date().toISOString()).
+ */
+export function computeReopen(cluster, feedbackId, now) {
+    const wasStatus = cluster.status ?? null;
+    const isAged = wasStatus === 'deferred';
+    const newStatus = isAged ? 'new' : 'investigating';
+    const noteTag = isAged ? 'AGED-REOPEN' : 'REGRESSION';
+    const fixedInVersion = cluster.fixedInVersion || 'n/a';
+    // Verbatim from the reference's regressionNote template.
+    const note = `[${noteTag} ${now}] New report matched cluster previously marked '${wasStatus}' (fixedInVersion=${fixedInVersion}). Auto-reopened to '${newStatus}' for review. Report: ${feedbackId}`;
+    return {
+        newStatus,
+        bumpRecurrence: !isAged,
+        annotateField: isAged ? 'actionTaken' : 'researchNotes',
+        noteTag,
+        note,
+    };
+}
+//# sourceMappingURL=reopen.js.map

package/dist/feedback-factory/processor/reopen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reopen.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/reopen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiBH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,UAAkB,EAAE,GAAW;IAC7E,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACzC,MAAM,MAAM,GAAG,SAAS,KAAK,UAAU,CAAC;IACxC,MAAM,SAAS,GAA4B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC;IAC5E,MAAM,OAAO,GAAiC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC;IACpF,MAAM,cAAc,GAAI,OAAO,CAAC,cAAyB,IAAI,KAAK,CAAC;IAEnE,yDAAyD;IACzD,MAAM,IAAI,GAAG,IAAI,OAAO,IAAI,GAAG,mDAAmD,SAAS,qBAAqB,cAAc,wBAAwB,SAAS,yBAAyB,UAAU,EAAE,CAAC;IAErM,OAAO;QACL,SAAS;QACT,cAAc,EAAE,CAAC,MAAM;QACvB,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe;QACvD,OAAO;QACP,IAAI;KACL,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.19",
+  "version": "1.3.20",
   "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/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-27T07:34:02.465Z",
-  "instarVersion": "1.3.19",
+  "generatedAt": "2026-05-27T07:58:06.900Z",
+  "instarVersion": "1.3.20",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.20.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Eighth increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the **auto-reopen-on-regression decision** from the reference Python (`cmd_apply_clusters` in `the-portal/.claude/scripts/feedback-processor.py`) into a pure function at `src/feedback-factory/processor/reopen.ts`.
+
+When a new report gets grouped onto a bug that was already marked fixed, resolved, or deferred, the bug is automatically reopened for review. This computes how: a long-deferred bug becomes "new" again (an aged-reopen, logged on its action trail); a fixed/resolved bug becomes "investigating" again and bumps its recurrence counter (a regression, logged on its research notes). It also writes the exact audit note. Pure function; **not wired into any route or job yet** — no behavioral change.
+
+## What to Tell Your User
+
+- The safety behavior that catches a bug "coming back from the dead" — a report landing on an already-fixed bug auto-reopens it instead of silently swallowing it — is now ported, including the audit note that records why it reopened.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-reopen decision (TS port) | Internal module `src/feedback-factory/processor/reopen.ts` — not yet wired |
+
+## Evidence
+
+- The decision is interleaved with database writes in the reference, so equivalence is by faithful transcription plus both-sides-of-boundary unit tests (5): the deferred (aged-reopen) branch vs the fixed/resolved (regression) branch — each asserting the right new status, which field gets annotated, and whether the recurrence counter bumps — plus the audit-note string asserted verbatim and the `fixedInVersion=n/a` fallback.

package/upgrades/side-effects/feedback-factory-reopen.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — auto-reopen-on-regression decision (Phase 1, increment 8)
+
+**Slug:** `feedback-factory-reopen`
+**Date:** `2026-05-27`
+**Author:** Echo (autonomous)
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The pure auto-reopen DECISION (which status/field/recurrence-bump + audit note) extracted from the regression branch of `cmd_apply_clusters`. The prisma writes stay in the (later) store adapter.
+
+## Summary of the change
+
+Ports the auto-reopen-on-regression decision into `src/feedback-factory/processor/reopen.ts` as the pure `computeReopen(cluster, feedbackId, now)`. When the clustering driver merges a report into a fixed/resolved/deferred cluster (a "possible regression"), the cluster is auto-reopened: `deferred → AGED-REOPEN → status 'new', annotate actionTaken, no recurrence bump`; otherwise `REGRESSION → status 'investigating', annotate researchNotes, bump recurrenceCount`. Also templates the audit note verbatim. `now` injected. **Not wired into any route/job yet.**
+
+## Equivalence verification
+
+The decision is interleaved with DB writes in the reference, so equivalence is by faithful transcription + both-sides-of-boundary unit tests (5): deferred vs fixed vs resolved → correct status/field/tag/recurrence; the audit-note string asserted verbatim (tag, time, prior status, `fixedInVersion`, new status, report id); `fixedInVersion=n/a` fallback.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure function, no I/O, no state, not imported by any runtime path. Returns the decision + note; the caller (store adapter) does the prisma update.
+2. **Level-of-abstraction fit** — Processor-logic layer, alongside cluster/transition/verify. The DB write (`{ increment: 1 }`, field append) is correctly left to the adapter.
+3. **Signal vs Authority** — N/A; produces a decision. The reopen is itself a legitimate guard (regression must not stay marked fixed) that exists in the reference.
+4. **Interactions** — None. New isolated module; nothing imports it yet. Pairs conceptually with `cluster.ts` (which emits the regression merge-note) but no code coupling yet.
+5. **Rollback cost** — Trivial: delete the module + tests.
+6. **Migration parity** — N/A. New internal library code; no agent-installed file touched.
+7. **Failure modes** — (a) Wrong field/status/recurrence per prior-status → both-sides tests. (b) Audit-note drift → asserted verbatim. (c) `now` non-determinism → injected.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/reopen.test.ts` — 5 tests (aged vs regression branches, resolved, verbatim note, n/a fallback).
+- No cross-runtime parity harness (decision interleaved with DB writes in the reference; equivalence by transcription + boundary tests).
+- No integration/E2E this increment: not wired; attaches when the apply/store layer lands. Reasoned, documented.