instar 1.3.11 → 1.3.12

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

@@ -0,0 +1,44 @@
+/**
+ * transitions.ts — TS port of the feedback-factory lifecycle state machine.
+ *
+ * Scar (a) (the evidence gate, processor side) + part of scar (c)/(d). Byte-exact
+ * port of `V2_STATES` (:1000), `V2_TRANSITIONS` (:1009), `TRANSITION_GATES`
+ * (:1028), `can_transition` (:1045), and `detect_cycling` (:1139) from the
+ * reference `the-portal/.claude/scripts/feedback-processor.py`. These are the
+ * pure decision functions: which lifecycle transitions are legal, what evidence
+ * a terminal transition demands, the chronic circuit-breaker, and whether a
+ * cluster is cycling. The DB-coupled drivers (cmd_transition, the version-anchored
+ * half of can_transition_to_verified) are later increments — this module is the
+ * pure, parity-testable core.
+ *
+ * The reason strings interpolate Python's `sorted(set)` list-repr; pyListRepr()
+ * reproduces it (single-quoted, comma-space, alphabetical) so the parity harness
+ * matches BOTH the `allowed` decision and the `reason` text byte-for-byte.
+ */
+/** Python V2_STATES (:1000) — set membership only; order irrelevant. */
+export declare const V2_STATES: ReadonlySet<string>;
+/** Python V2_TRANSITIONS (:1009) — allowed target states per current state. */
+export declare const V2_TRANSITIONS: Readonly<Record<string, ReadonlySet<string>>>;
+/** Python TRANSITION_GATES (:1028) — extra hard gates beyond state legality. */
+export declare const TRANSITION_GATES: Readonly<Record<string, {
+    required_context: string;
+    error: string;
+}>>;
+export interface TransitionContext {
+    dispatch_id?: string;
+    recurrenceCount?: number;
+    [k: string]: unknown;
+}
+/**
+ * Port of Python `can_transition` (:1045). Returns `[allowed, reason]`.
+ * Pure: no I/O. Mirrors the reference's check order exactly (invalid target →
+ * unknown current → illegal transition → evidence gate → hard gate → chronic
+ * circuit-breaker), so the first-failing reason matches the reference.
+ */
+export declare function canTransition(currentStatus: string, newStatus: string, justification?: string | null, context?: TransitionContext | null): [boolean, string];
+/** Port of Python `detect_cycling` (:1139): fix_applied/new/investigating with recurrenceCount ≥ 2. */
+export declare function detectCycling(cluster: {
+    status?: string;
+    recurrenceCount?: number;
+}): boolean;
+//# sourceMappingURL=transitions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/transitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAMxC,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAexE,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAKlG,CAAC;AAUF,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,GACjC,CAAC,OAAO,EAAE,MAAM,CAAC,CAsCnB;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAM7F"}

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

@@ -0,0 +1,102 @@
+/**
+ * transitions.ts — TS port of the feedback-factory lifecycle state machine.
+ *
+ * Scar (a) (the evidence gate, processor side) + part of scar (c)/(d). Byte-exact
+ * port of `V2_STATES` (:1000), `V2_TRANSITIONS` (:1009), `TRANSITION_GATES`
+ * (:1028), `can_transition` (:1045), and `detect_cycling` (:1139) from the
+ * reference `the-portal/.claude/scripts/feedback-processor.py`. These are the
+ * pure decision functions: which lifecycle transitions are legal, what evidence
+ * a terminal transition demands, the chronic circuit-breaker, and whether a
+ * cluster is cycling. The DB-coupled drivers (cmd_transition, the version-anchored
+ * half of can_transition_to_verified) are later increments — this module is the
+ * pure, parity-testable core.
+ *
+ * The reason strings interpolate Python's `sorted(set)` list-repr; pyListRepr()
+ * reproduces it (single-quoted, comma-space, alphabetical) so the parity harness
+ * matches BOTH the `allowed` decision and the `reason` text byte-for-byte.
+ */
+/** Python V2_STATES (:1000) — set membership only; order irrelevant. */
+export const V2_STATES = new Set([
+    'new', 'investigating', 'research_complete', 'fix_applied',
+    'dispatched', 'verified_tentative', 'verified', 'closed',
+    'chronic', 'chronic_escalated', 'deferred',
+    'wontfix', 'duplicate',
+    'needs_human_verify', // legacy (accepted for backward compat)
+]);
+/** Python V2_TRANSITIONS (:1009) — allowed target states per current state. */
+export const V2_TRANSITIONS = {
+    new: new Set(['investigating', 'wontfix', 'duplicate', 'deferred']),
+    investigating: new Set(['research_complete', 'wontfix', 'duplicate', 'deferred']),
+    research_complete: new Set(['fix_applied', 'investigating']),
+    fix_applied: new Set(['dispatched', 'chronic']),
+    dispatched: new Set(['verified', 'verified_tentative', 'chronic']),
+    verified_tentative: new Set(['verified', 'closed', 'chronic']),
+    verified: new Set(['closed', 'chronic']),
+    chronic: new Set(['investigating', 'chronic_escalated', 'wontfix']),
+    deferred: new Set(['new']),
+    chronic_escalated: new Set(),
+    closed: new Set(),
+    wontfix: new Set(),
+    duplicate: new Set(),
+    needs_human_verify: new Set(['verified', 'wontfix', 'duplicate']),
+};
+/** Python TRANSITION_GATES (:1028) — extra hard gates beyond state legality. */
+export const TRANSITION_GATES = {
+    dispatched: {
+        required_context: 'dispatch_id',
+        error: 'Cannot transition to dispatched without dispatch_id. Dispatch creation is ATOMIC with dispatch transition.',
+    },
+};
+const EVIDENCE_REQUIRED = new Set(['wontfix', 'closed', 'chronic_escalated']);
+/** Reproduce Python's `repr(sorted(setOfStrings))` for simple identifier strings. */
+function pyListRepr(values) {
+    const sorted = [...values].sort();
+    return '[' + sorted.map((v) => `'${v}'`).join(', ') + ']';
+}
+/**
+ * Port of Python `can_transition` (:1045). Returns `[allowed, reason]`.
+ * Pure: no I/O. Mirrors the reference's check order exactly (invalid target →
+ * unknown current → illegal transition → evidence gate → hard gate → chronic
+ * circuit-breaker), so the first-failing reason matches the reference.
+ */
+export function canTransition(currentStatus, newStatus, justification, context) {
+    const ctx = context ?? {};
+    if (!V2_STATES.has(newStatus)) {
+        return [false, `Invalid state: ${newStatus}. Valid: ${pyListRepr(V2_STATES)}`];
+    }
+    if (!(currentStatus in V2_TRANSITIONS)) {
+        return [false, `Unknown current state: ${currentStatus}`];
+    }
+    const allowedTargets = V2_TRANSITIONS[currentStatus];
+    if (!allowedTargets.has(newStatus)) {
+        // Python: f"... Allowed: {sorted(...) or 'none (terminal)'}" — empty list is falsy.
+        const allowedStr = allowedTargets.size > 0 ? pyListRepr(allowedTargets) : 'none (terminal)';
+        return [false, `Cannot transition ${currentStatus} -> ${newStatus}. Allowed: ${allowedStr}`];
+    }
+    if (EVIDENCE_REQUIRED.has(newStatus)) {
+        if (!justification || justification.trim().length < 20) {
+            return [false, `Transitioning to '${newStatus}' requires justification (min 20 chars)`];
+        }
+    }
+    if (newStatus in TRANSITION_GATES) {
+        const gate = TRANSITION_GATES[newStatus];
+        const requiredKey = gate.required_context;
+        if (requiredKey && !ctx[requiredKey]) {
+            return [false, gate.error];
+        }
+    }
+    if (newStatus === 'chronic') {
+        const recurrence = ctx.recurrenceCount ?? 0;
+        if (recurrence >= 3) {
+            return [false, `chronicCount (${recurrence}) >= 3. Must transition to chronic_escalated instead (circuit breaker).`];
+        }
+    }
+    return [true, 'OK'];
+}
+/** Port of Python `detect_cycling` (:1139): fix_applied/new/investigating with recurrenceCount ≥ 2. */
+export function detectCycling(cluster) {
+    const status = cluster.status;
+    return ((status === 'fix_applied' || status === 'new' || status === 'investigating') &&
+        (cluster.recurrenceCount ?? 0) >= 2);
+}
+//# sourceMappingURL=transitions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/transitions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.11",
+  "version": "1.3.12",
   "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/feedback-factory/_py_transitions_ref.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Parity reference: lifecycle transitions from the REAL feedback-processor.py.
+
+Imports the reference processor without running its CLI main and calls its actual
+`can_transition` + `detect_cycling` over the shared corpus. Emits JSON so the Node
+harness can diff the TS port (both the allowed decision AND the reason string).
+
+Usage: python3 _py_transitions_ref.py <processor_path> <corpus_path>
+"""
+import sys
+import json
+import importlib.util
+
+
+def load_processor(path):
+    spec = importlib.util.spec_from_file_location("_feedback_processor_ref_tx", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("usage: _py_transitions_ref.py <processor_path> <corpus_path>", file=sys.stderr)
+        sys.exit(2)
+    processor_path, corpus_path = sys.argv[1], sys.argv[2]
+    proc = load_processor(processor_path)
+    with open(corpus_path, encoding="utf-8") as f:
+        corpus = json.load(f)
+
+    tx_out = []
+    for case in corpus["transitions"]:
+        allowed, reason = proc.can_transition(
+            case["current"],
+            case["new"],
+            case.get("justification"),
+            case.get("context"),
+        )
+        tx_out.append({"case": case, "allowed": allowed, "reason": reason})
+
+    cyc_out = []
+    for cluster in corpus["cycling"]:
+        cyc_out.append({"cluster": cluster, "cycling": proc.detect_cycling(cluster)})
+
+    sys.stdout.write(json.dumps({"transitions": tx_out, "cycling": cyc_out}, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/feedback-factory/transitions-corpus.json

@@ -0,0 +1,40 @@
+{
+  "_comment": "Parity corpus for the lifecycle state-machine port. `transitions`: cases for can_transition {current,new,justification?,context?} → [allowed, reason]. `cycling`: cases for detect_cycling {cluster} → bool. Covers legal/illegal transitions, terminal states, the evidence gate (both sides of 20 chars), the dispatch hard gate, and the chronic circuit-breaker (recurrence 2 vs 3).",
+  "transitions": [
+    { "current": "new", "new": "investigating" },
+    { "current": "new", "new": "verified" },
+    { "current": "investigating", "new": "research_complete" },
+    { "current": "research_complete", "new": "investigating" },
+    { "current": "fix_applied", "new": "dispatched", "context": { "dispatch_id": "dsp-123" } },
+    { "current": "fix_applied", "new": "dispatched" },
+    { "current": "fix_applied", "new": "verified" },
+    { "current": "closed", "new": "investigating" },
+    { "current": "chronic_escalated", "new": "investigating" },
+    { "current": "wontfix", "new": "new" },
+    { "current": "bogus_state", "new": "investigating" },
+    { "current": "new", "new": "not_a_real_state" },
+    { "current": "investigating", "new": "wontfix" },
+    { "current": "investigating", "new": "wontfix", "justification": "too short" },
+    { "current": "investigating", "new": "wontfix", "justification": "this is a sufficiently long justification over twenty chars" },
+    { "current": "verified", "new": "closed", "justification": "short" },
+    { "current": "verified", "new": "closed", "justification": "verified stable for 30 days, closing per policy" },
+    { "current": "chronic", "new": "chronic_escalated", "justification": "escalating after repeated regressions across three releases" },
+    { "current": "verified", "new": "chronic" },
+    { "current": "verified", "new": "chronic", "context": { "recurrenceCount": 2 } },
+    { "current": "verified", "new": "chronic", "context": { "recurrenceCount": 3 } },
+    { "current": "fix_applied", "new": "chronic", "context": { "recurrenceCount": 5 } },
+    { "current": "needs_human_verify", "new": "verified" },
+    { "current": "deferred", "new": "new" }
+  ],
+  "cycling": [
+    { "status": "fix_applied", "recurrenceCount": 2 },
+    { "status": "fix_applied", "recurrenceCount": 1 },
+    { "status": "new", "recurrenceCount": 3 },
+    { "status": "investigating", "recurrenceCount": 2 },
+    { "status": "investigating", "recurrenceCount": 0 },
+    { "status": "verified", "recurrenceCount": 5 },
+    { "status": "dispatched", "recurrenceCount": 9 },
+    { "status": "fix_applied" },
+    { "recurrenceCount": 4 }
+  ]
+}

package/scripts/feedback-factory/transitions-parity.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * transitions-parity.mjs — LOCAL parity gate for the lifecycle state-machine port.
+ *
+ * Runs the REAL reference Python (`can_transition` + `detect_cycling` from
+ * the-portal/.claude/scripts/feedback-processor.py) and the TS port over the
+ * shared corpus and asserts BOTH the `allowed` decision AND the `reason` string
+ * match byte-for-byte (the reason interpolates Python's sorted-list repr, which
+ * the port reproduces). LOCAL evidence gate, not CI (CI lacks the reference).
+ *
+ * Exit 0 = parity; exit 1 = mismatch.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+
+const PROCESSOR = process.env.PORTAL_PROCESSOR
+  || '/Users/justin/Documents/Projects/the-portal/.claude/scripts/feedback-processor.py';
+const CORPUS = path.join(__dirname, 'transitions-corpus.json');
+const PY_REF = path.join(__dirname, '_py_transitions_ref.py');
+
+if (!fs.existsSync(PROCESSOR)) {
+  console.error(`[tx-parity] reference processor not found: ${PROCESSOR}`);
+  console.error('[tx-parity] set PORTAL_PROCESSOR to the reference feedback-processor.py');
+  process.exit(2);
+}
+
+const py = spawnSync('python3', [PY_REF, PROCESSOR, CORPUS], { encoding: 'utf8' });
+if (py.status !== 0) {
+  console.error('[tx-parity] python reference failed:\n', py.stderr || py.stdout);
+  process.exit(2);
+}
+const reference = JSON.parse(py.stdout);
+
+const distUrl = new URL('file://' + path.join(ROOT, 'dist', 'feedback-factory', 'processor', 'transitions.js'));
+const { canTransition, detectCycling } = await import(distUrl.href);
+
+let mismatches = 0;
+
+for (const ref of reference.transitions) {
+  const c = ref.case;
+  const [allowed, reason] = canTransition(c.current, c.new, c.justification ?? null, c.context ?? null);
+  if (allowed !== ref.allowed || reason !== ref.reason) {
+    mismatches++;
+    console.error(`[MISMATCH tx] ${JSON.stringify(c)}`);
+    console.error(`   python: allowed=${ref.allowed} reason=${JSON.stringify(ref.reason)}`);
+    console.error(`   ts    : allowed=${allowed} reason=${JSON.stringify(reason)}`);
+  }
+}
+
+for (const ref of reference.cycling) {
+  const got = detectCycling(ref.cluster);
+  if (got !== ref.cycling) {
+    mismatches++;
+    console.error(`[MISMATCH cycling] ${JSON.stringify(ref.cluster)} — python=${ref.cycling} ts=${got}`);
+  }
+}
+
+const total = reference.transitions.length + reference.cycling.length;
+if (mismatches === 0) {
+  console.error(`[tx-parity] ✓ ${total}/${total} transition decisions + reasons + cycling results match the reference Python.`);
+  process.exit(0);
+} else {
+  console.error(`[tx-parity] ✗ ${mismatches}/${total} mismatches — the TS port diverges from the reference.`);
+  process.exit(1);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-27T05:23:34.820Z",
-  "instarVersion": "1.3.11",
+  "generatedAt": "2026-05-27T05:27:08.240Z",
+  "instarVersion": "1.3.12",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.12.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Third increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the **lifecycle state machine** — `can_transition` + `detect_cycling` and their state/transition/gate constants — from the reference Python (`the-portal/.claude/scripts/feedback-processor.py`) to TypeScript at `src/feedback-factory/processor/transitions.ts`.
+
+This is the heart of the evidence gate: the rules for how a bug cluster legally moves between lifecycle states (new → investigating → research_complete → fix_applied → dispatched → verified → closed, plus chronic/escalated/deferred/wontfix/duplicate), the requirement that any terminal transition (wontfix/closed/chronic_escalated) carry a ≥20-character justification, the atomic dispatch hard-gate, and the chronic circuit-breaker that blocks `chronic` once a bug has recurred 3+ times (forcing human escalation instead). Plus the cycling detector. Pure functions; **not wired into any route or job yet** — no behavioral change.
+
+## What to Tell Your User
+
+- More of the feedback "brain" moved in-house — this is the part that enforces "you can't quietly mark a bug closed without writing down why," and the circuit-breaker that escalates a bug to a human once it keeps coming back.
+- Same discipline: I proved my rewrite makes the exact same allow/deny decisions as Dawn's original — and even produces the exact same explanation text — across 33 cases.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Lifecycle state machine (TS port) | Internal module `src/feedback-factory/processor/transitions.ts` — not yet wired |
+| Transitions parity harness | `node scripts/feedback-factory/transitions-parity.mjs` (local; set `PORTAL_PROCESSOR`) |
+
+## Evidence
+
+- **Parity vs the real reference Python:** ran `can_transition` + `detect_cycling` from the reference processor and the TS port over 33 cases (legal/illegal transitions, terminal states, the evidence gate on both sides of 20 chars, the dispatch hard-gate, the chronic circuit-breaker at recurrence 2 vs 3, cycling). Result: **33/33 match** — both the allow/deny decision AND the exact reason text (the reasons interpolate Python's sorted-list formatting, which the port reproduces byte-for-byte), plus all cycling results.
+- **CI anchors:** unit tests assert the evidence gate, the circuit-breaker, terminal-state handling, and that every transition target is a known state — so a state-machine regression fails in CI even without the reference checkout.

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

@@ -0,0 +1,34 @@
+# Side-Effects Review — feedback-factory lifecycle state machine (Phase 1, increment 3)
+
+**Slug:** `feedback-factory-transitions`
+**Date:** `2026-05-26`
+**Author:** Echo
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The pure lifecycle decision logic — `V2_STATES`/`V2_TRANSITIONS`/`TRANSITION_GATES` constants, `can_transition` (:1045, scar a's evidence gate + the state machine + chronic circuit-breaker), and `detect_cycling` (:1139). The DB-coupled drivers (`cmd_transition`, the version-anchored half of `can_transition_to_verified`) are later increments.
+
+## Summary of the change
+
+Byte-exact port of the above from `the-portal/.claude/scripts/feedback-processor.py` to `src/feedback-factory/processor/transitions.ts`. Pure functions, no I/O. **Not wired into any route/job yet** — no behavioral change. Adds the transitions parity harness + Tier-1 unit tests.
+
+This is the heart of scar (a): the evidence gate (terminal transitions to `wontfix`/`closed`/`chronic_escalated` require ≥20-char justification — unified with the `clusters.ts` API hard gate) and the chronic circuit-breaker (auto-block `chronic` at `recurrenceCount ≥ 3`, forcing `chronic_escalated`).
+
+## Equivalence verification
+
+- **33/33 cases match the reference Python** — both the `allowed` decision AND the exact `reason` string (the reasons interpolate Python's `sorted(set)` list-repr; the port reproduces it via `pyListRepr` so even the diagnostic text is byte-identical), plus all `detect_cycling` results.
+- The check ORDER is preserved exactly (invalid target → unknown current → illegal transition → evidence gate → hard gate → chronic breaker), so the first-failing reason matches the reference for every case.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure deterministic functions, no I/O, no global state, not imported by any runtime path. Cannot affect existing behavior. The constants are exported read-only.
+2. **Level-of-abstraction fit** — Processor-logic layer, alongside the fingerprint + similarity ports. Correct home. The state machine is data (constants) + a pure validator — no DB coupling, which is why it ports cleanly now (the DB-coupled verification driver waits for the data layer).
+3. **Signal vs Authority** — `can_transition` is the structural evidence gate (scar a): it *enforces* that terminal transitions carry evidence, mirroring the `clusters.ts` API hard gate. This is legitimate authority that already exists in the reference (not new authority introduced by the port). The processor still never force-closes; it validates.
+4. **Interactions** — None. New isolated module; nothing imports it yet. Parity scripts are LOCAL-only (external reference path via `PORTAL_PROCESSOR`).
+5. **Rollback cost** — Trivial: delete the module + tests + scripts.
+6. **Migration parity** — N/A. New internal library code; touches no agent-installed file.
+7. **Failure modes** — (a) Port diverges from reference → caught by the parity harness (33/33, decisions+reasons+cycling) + unit assertions in CI. (b) A new lifecycle state added to the reference but not the port → the "every transition target is a known state" unit test + future parity runs catch drift; Dawn's review is the human backstop. (c) Reason-string repr divergence → parity asserts reasons byte-for-byte.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/transitions.test.ts` — state legality, terminal states, evidence gate (both sides of 20 chars), dispatch hard gate, chronic circuit-breaker (recurrence 2 vs 3), cycling detection, constants integrity. 12 tests.
+- Parity (local gate, evidence): `scripts/feedback-factory/transitions-parity.mjs` → **33/33** decisions + reasons + cycling identical to the reference Python.
+- No integration/E2E this increment: not yet wired to a route/job; those tiers attach with the clustering/transition driver. Reasoned decision, documented.