instar 1.3.13 → 1.3.14

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

@@ -0,0 +1,33 @@
+/**
+ * cluster.ts — TS port of the feedback-factory clustering driver.
+ *
+ * Byte-exact port of the decision loop in `cmd_cluster` (:1405) of the reference
+ * `the-portal/.claude/scripts/feedback-processor.py`. Given the unprocessed items
+ * and the active (status != 'resolved') clusters, decide for each item whether it
+ * MERGES into an existing cluster or CREATES a new one, using Jaccard similarity
+ * (similarity.ts, already parity-verified) over `"{title} {description}"`.
+ *
+ * This is the orchestration on top of the parity'd primitives. It is PURE: the
+ * reference reads items+clusters from the DB, then runs this loop with no further
+ * I/O (the DB writes happen separately in cmd_apply_clusters). So this ports as a
+ * pure function and is parity-tested by monkeypatching the reference's DB query to
+ * feed fixtures and running the REAL cmd_cluster loop.
+ *
+ * ORDER-DEPENDENT within a batch (by design, matching the reference + the spec):
+ * a cluster created for an earlier item becomes a match candidate for later items.
+ */
+import type { FeedbackItem, Cluster, ClusterResult } from './types.js';
+/**
+ * Reproduce Python's `round(x, 3)` — round-half-to-even (banker's rounding) on the
+ * float, to 3 decimals. JS `Math.round` is round-half-up, so a naive port diverges
+ * on exact-half 4th decimals; this matches the reference. Verified by the parity
+ * harness (which seeds an exact-half case).
+ */
+export declare function pyRound3(x: number): number;
+/**
+ * Port of cmd_cluster's decision loop. Mutates a working copy of `clusters` by
+ * appending newly-created clusters (so later items can match them), exactly as the
+ * reference does. Returns one ClusterResult per item.
+ */
+export declare function clusterItems(items: FeedbackItem[], clusters: Cluster[]): ClusterResult[];
+//# sourceMappingURL=cluster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMvE;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS1C;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,CAkExF"}

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

@@ -0,0 +1,120 @@
+/**
+ * cluster.ts — TS port of the feedback-factory clustering driver.
+ *
+ * Byte-exact port of the decision loop in `cmd_cluster` (:1405) of the reference
+ * `the-portal/.claude/scripts/feedback-processor.py`. Given the unprocessed items
+ * and the active (status != 'resolved') clusters, decide for each item whether it
+ * MERGES into an existing cluster or CREATES a new one, using Jaccard similarity
+ * (similarity.ts, already parity-verified) over `"{title} {description}"`.
+ *
+ * This is the orchestration on top of the parity'd primitives. It is PURE: the
+ * reference reads items+clusters from the DB, then runs this loop with no further
+ * I/O (the DB writes happen separately in cmd_apply_clusters). So this ports as a
+ * pure function and is parity-tested by monkeypatching the reference's DB query to
+ * feed fixtures and running the REAL cmd_cluster loop.
+ *
+ * ORDER-DEPENDENT within a batch (by design, matching the reference + the spec):
+ * a cluster created for an earlier item becomes a match candidate for later items.
+ */
+import { jaccardSimilarity } from './similarity.js';
+const SIMILARITY_THRESHOLD = 0.35;
+const FIXED_CLUSTER_THRESHOLD = 0.55;
+const FIXED_STATUSES = new Set(['fixed', 'resolved', 'fix_applied']);
+/**
+ * Reproduce Python's `round(x, 3)` — round-half-to-even (banker's rounding) on the
+ * float, to 3 decimals. JS `Math.round` is round-half-up, so a naive port diverges
+ * on exact-half 4th decimals; this matches the reference. Verified by the parity
+ * harness (which seeds an exact-half case).
+ */
+export function pyRound3(x) {
+    const scaled = x * 1000;
+    const floor = Math.floor(scaled);
+    const diff = scaled - floor;
+    let r;
+    if (diff > 0.5)
+        r = floor + 1;
+    else if (diff < 0.5)
+        r = floor;
+    else
+        r = floor % 2 === 0 ? floor : floor + 1; // half → nearest even
+    return r / 1000;
+}
+/** Port of cmd_cluster's slug: `re.sub(r'[^a-z0-9]+','-', title.lower())[:60].strip('-')`. */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, 60)
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Port of cmd_cluster's decision loop. Mutates a working copy of `clusters` by
+ * appending newly-created clusters (so later items can match them), exactly as the
+ * reference does. Returns one ClusterResult per item.
+ */
+export function clusterItems(items, clusters) {
+    // Work on a shallow copy so the caller's array isn't mutated, while still
+    // letting created clusters become candidates for subsequent items in the batch.
+    const working = [...clusters];
+    const results = [];
+    for (const item of items) {
+        const itemText = `${item.title} ${item.description}`;
+        let bestMatch = null;
+        let bestScore = 0.0;
+        for (const cluster of working) {
+            const clusterText = `${cluster.title} ${cluster.description}`;
+            const score = jaccardSimilarity(itemText, clusterText);
+            if (score > bestScore) { // strict — first cluster reaching the max wins (tie keeps earlier)
+                bestScore = score;
+                bestMatch = cluster;
+            }
+        }
+        let threshold = SIMILARITY_THRESHOLD;
+        if (bestMatch && FIXED_STATUSES.has(bestMatch.status ?? '')) {
+            threshold = FIXED_CLUSTER_THRESHOLD;
+            if (bestScore >= SIMILARITY_THRESHOLD && bestScore < FIXED_CLUSTER_THRESHOLD) {
+                // FALSE-MERGE-GUARD near-miss — reference logs to stdout for observability.
+                // The pure port returns the decision (create); the log line is a side effect
+                // the caller/observability layer emits, so it is intentionally not produced here.
+            }
+        }
+        if (bestMatch && bestScore >= threshold) {
+            let mergeNote = '';
+            const st = bestMatch.status ?? '';
+            if (FIXED_STATUSES.has(st)) {
+                mergeNote = ' (merged into fixed cluster — possible regression)';
+            }
+            else if (st === 'deferred') {
+                mergeNote = ' (merged into deferred singleton — possible regression, reopening)';
+            }
+            const result = {
+                feedbackId: item.feedbackId,
+                action: 'merge',
+                clusterId: bestMatch.clusterId,
+                clusterTitle: bestMatch.title,
+                similarity: pyRound3(bestScore),
+            };
+            if (mergeNote)
+                result.note = mergeNote;
+            results.push(result);
+        }
+        else {
+            const clusterId = `cluster-${slugify(item.title)}`;
+            const newCluster = {
+                clusterId,
+                title: item.title,
+                description: item.description,
+                type: item.type,
+            };
+            working.push(newCluster); // visible to later items in the batch
+            results.push({
+                feedbackId: item.feedbackId,
+                action: 'create',
+                clusterId,
+                similarity: bestMatch ? pyRound3(bestScore) : 0.0,
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=cluster.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGpD,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5B,IAAI,CAAS,CAAC;IACd,IAAI,IAAI,GAAG,GAAG;QAAE,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;SACzB,IAAI,IAAI,GAAG,GAAG;QAAE,CAAC,GAAG,KAAK,CAAC;;QAC1B,CAAC,GAAG,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,sBAAsB;IACpE,OAAO,CAAC,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,8FAA8F;AAC9F,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;SACZ,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB,EAAE,QAAmB;IACrE,0EAA0E;IAC1E,gFAAgF;IAChF,MAAM,OAAO,GAAc,CAAC,GAAG,QAAQ,CAAC,CAAC;IACzC,MAAM,OAAO,GAAoB,EAAE,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrD,IAAI,SAAS,GAAmB,IAAI,CAAC;QACrC,IAAI,SAAS,GAAG,GAAG,CAAC;QAEpB,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YAC9D,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YACvD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC,CAAC,mEAAmE;gBAC1F,SAAS,GAAG,KAAK,CAAC;gBAClB,SAAS,GAAG,OAAO,CAAC;YACtB,CAAC;QACH,CAAC;QAED,IAAI,SAAS,GAAG,oBAAoB,CAAC;QACrC,IAAI,SAAS,IAAI,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;YAC5D,SAAS,GAAG,uBAAuB,CAAC;YACpC,IAAI,SAAS,IAAI,oBAAoB,IAAI,SAAS,GAAG,uBAAuB,EAAE,CAAC;gBAC7E,4EAA4E;gBAC5E,6EAA6E;gBAC7E,kFAAkF;YACpF,CAAC;QACH,CAAC;QAED,IAAI,SAAS,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;YACxC,IAAI,SAAS,GAAG,EAAE,CAAC;YACnB,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC;YAClC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC3B,SAAS,GAAG,oDAAoD,CAAC;YACnE,CAAC;iBAAM,IAAI,EAAE,KAAK,UAAU,EAAE,CAAC;gBAC7B,SAAS,GAAG,oEAAoE,CAAC;YACnF,CAAC;YACD,MAAM,MAAM,GAAkB;gBAC5B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,MAAM,EAAE,OAAO;gBACf,SAAS,EAAE,SAAS,CAAC,SAAS;gBAC9B,YAAY,EAAE,SAAS,CAAC,KAAK;gBAC7B,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC;aAChC,CAAC;YACF,IAAI,SAAS;gBAAE,MAAM,CAAC,IAAI,GAAG,SAAS,CAAC;YACvC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,GAAG,WAAW,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,UAAU,GAAY;gBAC1B,SAAS;gBACT,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,sCAAsC;YAChE,OAAO,CAAC,IAAI,CAAC;gBACX,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,MAAM,EAAE,QAAQ;gBAChB,SAAS;gBACT,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG;aAClD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * types.ts — shared data shapes for the feedback-factory processor.
+ *
+ * Mirror the reference (the-portal Prisma models InstarFeedback / InstarFeedbackCluster
+ * + the JSON the processor passes around). Only the fields the ported pure logic
+ * actually reads are required; the rest are optional so a real store adapter can
+ * pass full rows without the pure functions caring.
+ */
+/** A raw feedback report (subset of InstarFeedback used by the pure processor logic). */
+export interface FeedbackItem {
+    feedbackId: string;
+    title: string;
+    description: string;
+    type: string;
+    status?: string;
+    receivedAt?: string;
+    instarVersion?: string;
+    [k: string]: unknown;
+}
+/** A dedup cluster (subset of InstarFeedbackCluster used by the pure processor logic). */
+export interface Cluster {
+    clusterId: string;
+    title: string;
+    description: string;
+    type?: string;
+    status?: string;
+    fingerprint?: string;
+    recurrenceCount?: number;
+    reportCount?: number;
+    createdAt?: string;
+    updatedAt?: string;
+    fixedInVersion?: string;
+    fixAppliedAt?: string;
+    dispatchedAt?: string;
+    [k: string]: unknown;
+}
+/** One clustering decision for a feedback item (mirrors cmd_cluster's result dicts). */
+export interface ClusterResult {
+    feedbackId: string;
+    action: 'merge' | 'create';
+    clusterId: string;
+    similarity: number;
+    clusterTitle?: string;
+    note?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,0FAA0F;AAC1F,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

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

@@ -0,0 +1,10 @@
+/**
+ * types.ts — shared data shapes for the feedback-factory processor.
+ *
+ * Mirror the reference (the-portal Prisma models InstarFeedback / InstarFeedbackCluster
+ * + the JSON the processor passes around). Only the fields the ported pure logic
+ * actually reads are required; the rest are optional so a real store adapter can
+ * pass full rows without the pure functions caring.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "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_clustering_ref.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Parity reference: run the REAL cmd_cluster decision loop over a fixture.
+
+Imports the reference processor without running its CLI main, then MONKEYPATCHES
+its `run_prisma_query` so the two DB reads cmd_cluster does (unprocessed items,
+then active clusters) return our fixture arrays instead of hitting a database.
+cmd_cluster then runs its actual, unmodified decision loop and RETURNS the
+results — which is exactly what the TS port must reproduce. cmd_cluster's own
+stdout (FALSE-MERGE-GUARD logs + its json.dumps) is suppressed; we emit the
+captured return value as clean JSON.
+
+Usage: python3 _py_clustering_ref.py <processor_path> <fixture_path>
+"""
+import sys
+import io
+import json
+import importlib.util
+import contextlib
+
+
+def load_processor(path):
+    spec = importlib.util.spec_from_file_location("_feedback_processor_ref_cl", 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_clustering_ref.py <processor_path> <fixture_path>", file=sys.stderr)
+        sys.exit(2)
+    processor_path, fixture_path = sys.argv[1], sys.argv[2]
+    proc = load_processor(processor_path)
+    with open(fixture_path, encoding="utf-8") as f:
+        fixture = json.load(f)
+
+    # cmd_cluster calls run_prisma_query twice in order: items first, clusters second.
+    responses = [json.dumps(fixture["items"]), json.dumps(fixture["clusters"])]
+    call = {"n": 0}
+
+    def fake_query(*_args, **_kwargs):
+        i = call["n"]
+        call["n"] += 1
+        return responses[i] if i < len(responses) else "[]"
+
+    proc.run_prisma_query = fake_query
+
+    # Run the REAL loop; suppress cmd_cluster's stdout noise, capture its return.
+    with contextlib.redirect_stdout(io.StringIO()):
+        results = proc.cmd_cluster()
+
+    sys.stdout.write(json.dumps(results if results is not None else [], ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,17 @@
+{
+  "_comment": "Parity fixture for the clustering driver. `clusters` = pre-existing active clusters; `items` = unprocessed feedback processed in order. Exercises: create-new, merge into open cluster, the 0.55 fixed-cluster false-merge guard (score in [0.35,0.55) vs a fixed cluster → create), merge into fixed (regression note), merge into deferred (reopen note), order-dependence (a later item matching a cluster created for an earlier item), and slug generation. The Python ref runs the REAL cmd_cluster with its DB query monkeypatched to these arrays.",
+  "clusters": [
+    { "clusterId": "cluster-existing-open", "title": "GitSync pull fails intermittently", "description": "the pull step times out under load", "type": "bug", "status": "investigating" },
+    { "clusterId": "cluster-existing-fixed", "title": "auth token refresh broken", "description": "token refresh returns 401 after expiry", "type": "bug", "status": "fixed" },
+    { "clusterId": "cluster-existing-deferred", "title": "dashboard pin rotation edge case", "description": "pin rotation skips on concurrent login", "type": "bug", "status": "deferred" }
+  ],
+  "items": [
+    { "feedbackId": "fb-1", "title": "GitSync pull fails intermittently", "description": "the pull step times out under load", "type": "bug" },
+    { "feedbackId": "fb-2", "title": "completely different telemetry export bug", "description": "csv export drops the last row", "type": "bug" },
+    { "feedbackId": "fb-3", "title": "telemetry export bug csv", "description": "the export drops the final row of data", "type": "bug" },
+    { "feedbackId": "fb-4", "title": "auth token refresh broken", "description": "token refresh returns 401 after expiry", "type": "bug" },
+    { "feedbackId": "fb-5", "title": "auth token refresh sometimes", "description": "occasional 401 seen again", "type": "bug" },
+    { "feedbackId": "fb-6", "title": "dashboard pin rotation edge case", "description": "pin rotation skips on concurrent login", "type": "bug" },
+    { "feedbackId": "fb-7", "title": "Brand New Issue: Weird Unicode café title", "description": "something about an emoji in the report", "type": "feature" }
+  ]
+}

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * clustering-parity.mjs — LOCAL parity gate for the clustering driver port.
+ *
+ * Runs the REAL reference cmd_cluster (DB monkeypatched to a fixture) and the TS
+ * clusterItems() over the same fixture, and asserts the per-item decisions match
+ * exactly: action (merge/create), clusterId, rounded similarity, and the merge
+ * note. LOCAL evidence gate, not CI (CI lacks the reference checkout).
+ *
+ * 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 FIXTURE = path.join(__dirname, 'clustering-corpus.json');
+const PY_REF = path.join(__dirname, '_py_clustering_ref.py');
+
+if (!fs.existsSync(PROCESSOR)) {
+  console.error(`[cluster-parity] reference processor not found: ${PROCESSOR}`);
+  process.exit(2);
+}
+
+const py = spawnSync('python3', [PY_REF, PROCESSOR, FIXTURE], { encoding: 'utf8' });
+if (py.status !== 0) {
+  console.error('[cluster-parity] python reference failed:\n', py.stderr || py.stdout);
+  process.exit(2);
+}
+const reference = JSON.parse(py.stdout);
+
+const fixture = JSON.parse(fs.readFileSync(FIXTURE, 'utf8'));
+const distUrl = new URL('file://' + path.join(ROOT, 'dist', 'feedback-factory', 'processor', 'cluster.js'));
+const { clusterItems } = await import(distUrl.href);
+const got = clusterItems(fixture.items, fixture.clusters);
+
+let mismatches = 0;
+const norm = (r) => JSON.stringify({
+  feedbackId: r.feedbackId, action: r.action, clusterId: r.clusterId,
+  similarity: r.similarity, note: r.note ?? null,
+});
+
+if (got.length !== reference.length) {
+  console.error(`[cluster-parity] length mismatch: ts=${got.length} python=${reference.length}`);
+  mismatches++;
+}
+for (let i = 0; i < Math.max(got.length, reference.length); i++) {
+  const a = got[i] ? norm(got[i]) : '(missing)';
+  const b = reference[i] ? norm(reference[i]) : '(missing)';
+  if (a !== b) {
+    mismatches++;
+    console.error(`[MISMATCH #${i}]`);
+    console.error(`   python: ${b}`);
+    console.error(`   ts    : ${a}`);
+  }
+}
+
+const total = reference.length;
+if (mismatches === 0) {
+  console.error(`[cluster-parity] ✓ ${total}/${total} clustering decisions match the reference cmd_cluster.`);
+  process.exit(0);
+} else {
+  console.error(`[cluster-parity] ✗ ${mismatches} mismatch(es) — 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-27T06:03:48.163Z",
-  "instarVersion": "1.3.13",
+  "generatedAt": "2026-05-27T06:14:27.030Z",
+  "instarVersion": "1.3.14",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.14.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fourth increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the **clustering driver** — the decision loop of `cmd_cluster` — from the reference Python (`the-portal/.claude/scripts/feedback-processor.py`) to TypeScript at `src/feedback-factory/processor/cluster.ts` (`clusterItems`), plus shared types in `src/feedback-factory/processor/types.ts`.
+
+This is the orchestration that ties the brain together: for each incoming report it picks the most-similar existing cluster (via the already-ported Jaccard matcher) and either merges into it or creates a new one — applying the higher 0.55 similarity bar before merging into an already-fixed cluster (the false-merge guard), and flagging possible regressions/reopens. Pure functions; **not wired into any route or job yet** — no behavioral change.
+
+## What to Tell Your User
+
+- The part of the feedback brain that actually groups reports into "this is one bug" piles is now ported — including the safety rule that makes it harder to wrongly lump a new report onto an already-fixed bug.
+- Proven against Dawn's original the strongest way yet: I fed the same reports through her real grouping code and my rewrite and got identical grouping decisions, 7 for 7.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Clustering driver (TS port) | Internal module `src/feedback-factory/processor/cluster.ts` — not yet wired |
+| Clustering parity harness | `node scripts/feedback-factory/clustering-parity.mjs` (local; set `PORTAL_PROCESSOR`) |
+
+## Evidence
+
+- **Parity vs the REAL `cmd_cluster`:** the harness monkeypatches the reference's database query to feed a fixture (existing clusters + incoming items) and runs cmd_cluster's actual, unmodified decision loop, capturing its results — then compares to the TS port. Result: **7/7 identical** decisions (merge vs create, which cluster, rounded similarity, and the regression/reopen note). The fixture exercises create, merge-into-open, the 0.55 false-merge guard, merge-into-fixed (regression), merge-into-deferred (reopen), and order-dependence (a later report matching a cluster created moments earlier in the same batch).
+- **CI anchors:** unit tests assert each of those behaviors plus the Python-style half-to-even rounding, so a regression fails in CI even without the reference checkout.

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

@@ -0,0 +1,34 @@
+# Side-Effects Review — feedback-factory clustering driver (Phase 1, increment 4)
+
+**Slug:** `feedback-factory-clustering`
+**Date:** `2026-05-27`
+**Author:** Echo (autonomous)
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The clustering decision loop of `cmd_cluster` (:1405) — assign each unprocessed item to an existing cluster or create a new one. Pure orchestration over the already-parity'd Jaccard similarity. The DB read/write halves (the queries + `cmd_apply_clusters`) are the store/adapter layer, a later increment.
+
+## Summary of the change
+
+Byte-exact port of `cmd_cluster`'s decision loop from `the-portal/.claude/scripts/feedback-processor.py` to `src/feedback-factory/processor/cluster.ts` as the pure function `clusterItems(items, clusters)`. Adds shared types (`src/feedback-factory/processor/types.ts`: `FeedbackItem`/`Cluster`/`ClusterResult`), the clustering parity harness, and Tier-1 unit tests. Pure functions, no I/O. **Not wired into any route/job yet** — no behavioral change.
+
+The decision rules ported: per item, pick the highest-Jaccard cluster over `"{title} {description}"`; merge if score ≥ threshold (0.55 for `fixed`/`resolved`/`fix_applied` clusters — the false-merge guard — else 0.35); else create a new `cluster-<slug>` and make it a candidate for later items in the batch (order-dependent, by design). Regression/reopen merge-notes preserved.
+
+## Equivalence verification
+
+- **7/7 fixture decisions match the REAL `cmd_cluster`.** The parity harness monkeypatches the reference's `run_prisma_query` to feed (items, clusters) fixtures and runs cmd_cluster's actual, unmodified loop, capturing its returned results — so this is parity against the real code, not a re-implementation. Matched fields: action, clusterId, rounded similarity, and merge note. Fixture exercises create / merge-open / the 0.55 false-merge guard / merge-into-fixed (regression) / merge-into-deferred (reopen) / order-dependence / slug.
+- Builds on the already-parity'd `jaccardSimilarity` (increment 2, 20/20), so the only new surface is the orchestration + `pyRound3` (Python round-half-to-even, unit-tested on exact-half cases).
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure deterministic function, no I/O, no global state, not imported by any runtime path. Works on a shallow COPY of the clusters array so the caller's input isn't mutated (while still letting created clusters match later items, as the reference does).
+2. **Level-of-abstraction fit** — Processor-logic layer, on top of the similarity primitive. The DB I/O (reads + `cmd_apply_clusters` writes) is deliberately NOT here — it belongs to the store/adapter layer, keeping this pure + parity-testable.
+3. **Signal vs Authority** — N/A; pure computation producing a decision list. The FALSE-MERGE-GUARD near-miss LOG line is intentionally NOT emitted by the pure function (it's a stdout side effect of the reference); the observability layer emits it. The DECISION (create vs merge) is identical.
+4. **Interactions** — None. New isolated module; nothing imports it yet. Parity scripts LOCAL-only.
+5. **Rollback cost** — Trivial: delete the module + tests + scripts. `types.ts` is additive.
+6. **Migration parity** — N/A. New internal library code; no agent-installed file touched.
+7. **Failure modes** — (a) Port diverges from reference → parity harness (7/7, against the real loop) + unit tests. (b) `pyRound3` half-rounding divergence → unit-tested on exact-half cases + parity. (c) Order-dependence not reproduced → unit + parity both exercise a later-item-matches-earlier-created-cluster case. (d) The FALSE-MERGE-GUARD stdout log isn't reproduced → intentional (pure function); documented; the observability increment will emit it.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/cluster.test.ts` — pyRound3 (incl. half-to-even), create/merge, the 0.55 guard, regression + reopen notes, order-dependence. 8 tests.
+- Parity (local gate, evidence): `scripts/feedback-factory/clustering-parity.mjs` → **7/7** vs the real `cmd_cluster`.
+- No integration/E2E this increment: not wired to a route/job; those tiers attach when the store/apply layer + job land. Reasoned decision, documented.