instar 1.3.991 → 1.3.992

package/dist/core/RecurrenceReader.d.ts

@@ -0,0 +1,134 @@
+/**
+ * RecurrenceReader — one reader across the stores that already notice things.
+ *
+ * THE DEFECT THIS ADDRESSES (project convergence-towards-coherence, Tier 2).
+ * Instar notices constantly and in three separate places: the attention queue,
+ * the evolution action queue, and the sentinel event log. Nothing reads across
+ * them, so the same underlying problem is noticed dozens of times and closed
+ * zero times. The measured filing-to-completion ratio is roughly 30:1.
+ *
+ * Measured on this machine, 2026-07-27 — the number that makes the case:
+ *
+ *   371 OPEN attention items  →  49 distinct problems
+ *   the single largest cluster ("credential rebalancer") is 177 items — 48%
+ *
+ * Reading that queue item-by-item, nobody would ever see it. The items are all
+ * individually true and individually minor; the SHAPE is the finding, and the
+ * shape is invisible without a reader that groups.
+ *
+ * WHAT THIS IS NOT. It is not a new notification channel, and it must never
+ * become one (operator directive 2026-07-26 20:08Z: synthesis must lead to
+ * ACTION through the paths that already exist — a phase advance, a blocker
+ * raised, work queued — with the loop closed and without depending on the user).
+ * This module is READ-ONLY and returns a report; driving action from it is a
+ * separate, gated concern.
+ *
+ * THE HONEST-DENOMINATOR RULE APPLIES TO THIS READER TOO. Every store it could
+ * not read is named in `coverage`, and a report with any unreadable store is
+ * NEVER `complete`. "I found no recurrence" and "I could not look" are different
+ * answers, and conflating them is the exact failure this project exists to
+ * remove — a synthesiser that silently synthesised over two of three stores
+ * would be the most expensive instance of it yet.
+ */
+/** A single observation from any of the noticing stores. */
+export interface Observation {
+    /** Which store this came from. */
+    store: 'attention' | 'actions' | 'sentinel';
+    /** Stable id within that store, when it has one. */
+    id?: string;
+    /** Human title / summary — the recurrence key is derived from this. */
+    title: string;
+    /** Emitting subsystem, when known. `undefined` is itself a finding (see below). */
+    source?: string;
+    /** ISO timestamp, when known. */
+    at?: string;
+    /** Open / unresolved. Only open observations form recurrence clusters. */
+    open: boolean;
+}
+/** One recurring problem, as distinct from the many times it was noticed. */
+export interface RecurrenceCluster {
+    /** Normalized key the members share. */
+    key: string;
+    /** A readable exemplar (the first member's title, untruncated). */
+    exemplar: string;
+    /** How many times this was noticed. THE point of the whole module. */
+    count: number;
+    /** Which stores noticed it — a problem seen in more than one is stronger evidence. */
+    stores: Observation['store'][];
+    /** Sources that emitted it, when known. */
+    sources: string[];
+    /** Earliest / latest observation timestamps available. */
+    firstSeen?: string;
+    lastSeen?: string;
+    /**
+     * True when at least one member came from the ACTION queue — i.e. somebody has
+     * at some point committed to doing something about this. A high-count cluster
+     * with `tracked: false` is the sharpest signal available: noticed many times,
+     * never once turned into work.
+     */
+    tracked: boolean;
+}
+/** What the reader could and could not see. Never omitted, never inferred. */
+export interface Coverage {
+    /** Stores read successfully. */
+    read: Observation['store'][];
+    /** Stores that could NOT be read, with the reason. */
+    unreadable: {
+        store: Observation['store'];
+        reason: string;
+    }[];
+    /**
+     * `complete` only when every store was read. Any unreadable store makes this
+     * `partial`, and a partial report may never be presented as a clean bill.
+     */
+    completeness: 'complete' | 'partial';
+}
+export interface RecurrenceReport {
+    generatedAt: string;
+    coverage: Coverage;
+    /** Distinct problems, densest first. */
+    clusters: RecurrenceCluster[];
+    /** Open observations considered. */
+    observationsConsidered: number;
+    /**
+     * observations ÷ clusters — the noticing-to-problem ratio. `null` when there
+     * are no clusters: no denominator, no ratio (never a flattering 1, never a
+     * damning 0).
+     */
+    noticingRatio: number | null;
+    /**
+     * Present ONLY on a complete report. On a partial read this is absent and the
+     * caller must say "I could not look", never "nothing recurring was found".
+     */
+    verdict?: 'no-recurrence' | 'recurrence-found';
+}
+/**
+ * Derive the recurrence key from a title.
+ *
+ * Digits collapse to `N` and long hex runs to `H`, so "3 topics stranded on
+ * m_cc2ec…" and "7 topics stranded on m_91af…" are recognised as ONE problem
+ * rather than two. This is deliberately blunt: the goal is to surface shape, and
+ * an over-eager grouping that a human immediately recognises as one problem is
+ * more useful than a precise grouping that preserves the illusion of 371
+ * separate things.
+ */
+export declare function recurrenceKey(title: string): string;
+/**
+ * Group open observations into recurrence clusters.
+ *
+ * Pure over its input — every store read (and every read FAILURE) is the
+ * caller's job to supply, so this function cannot silently swallow one.
+ */
+export declare function buildRecurrenceReport(observations: Observation[], coverage: Coverage): RecurrenceReport;
+/**
+ * The clusters worth a human's attention, by a deterministic rule.
+ *
+ * `minCount` defaults to 2 because a thing noticed once is not yet recurrence.
+ * `untrackedOnly` narrows to the sharpest class: repeatedly noticed, never
+ * turned into work.
+ */
+export declare function significantClusters(report: RecurrenceReport, opts?: {
+    minCount?: number;
+    untrackedOnly?: boolean;
+}): RecurrenceCluster[];
+//# sourceMappingURL=RecurrenceReader.d.ts.map

package/dist/core/RecurrenceReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecurrenceReader.d.ts","sourceRoot":"","sources":["../../src/core/RecurrenceReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;IAC5C,oDAAoD;IACpD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAC/B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7B,sDAAsD;IACtD,UAAU,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D;;;OAGG;IACH,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,wCAAwC;IACxC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,oCAAoC;IACpC,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,kBAAkB,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,WAAW,EAAE,EAC3B,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CA0ClB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxD,iBAAiB,EAAE,CAKrB"}

package/dist/core/RecurrenceReader.js

@@ -0,0 +1,111 @@
+/**
+ * RecurrenceReader — one reader across the stores that already notice things.
+ *
+ * THE DEFECT THIS ADDRESSES (project convergence-towards-coherence, Tier 2).
+ * Instar notices constantly and in three separate places: the attention queue,
+ * the evolution action queue, and the sentinel event log. Nothing reads across
+ * them, so the same underlying problem is noticed dozens of times and closed
+ * zero times. The measured filing-to-completion ratio is roughly 30:1.
+ *
+ * Measured on this machine, 2026-07-27 — the number that makes the case:
+ *
+ *   371 OPEN attention items  →  49 distinct problems
+ *   the single largest cluster ("credential rebalancer") is 177 items — 48%
+ *
+ * Reading that queue item-by-item, nobody would ever see it. The items are all
+ * individually true and individually minor; the SHAPE is the finding, and the
+ * shape is invisible without a reader that groups.
+ *
+ * WHAT THIS IS NOT. It is not a new notification channel, and it must never
+ * become one (operator directive 2026-07-26 20:08Z: synthesis must lead to
+ * ACTION through the paths that already exist — a phase advance, a blocker
+ * raised, work queued — with the loop closed and without depending on the user).
+ * This module is READ-ONLY and returns a report; driving action from it is a
+ * separate, gated concern.
+ *
+ * THE HONEST-DENOMINATOR RULE APPLIES TO THIS READER TOO. Every store it could
+ * not read is named in `coverage`, and a report with any unreadable store is
+ * NEVER `complete`. "I found no recurrence" and "I could not look" are different
+ * answers, and conflating them is the exact failure this project exists to
+ * remove — a synthesiser that silently synthesised over two of three stores
+ * would be the most expensive instance of it yet.
+ */
+/**
+ * Derive the recurrence key from a title.
+ *
+ * Digits collapse to `N` and long hex runs to `H`, so "3 topics stranded on
+ * m_cc2ec…" and "7 topics stranded on m_91af…" are recognised as ONE problem
+ * rather than two. This is deliberately blunt: the goal is to surface shape, and
+ * an over-eager grouping that a human immediately recognises as one problem is
+ * more useful than a precise grouping that preserves the illusion of 371
+ * separate things.
+ */
+export function recurrenceKey(title) {
+    return (title || '')
+        .toLowerCase()
+        .replace(/[a-f0-9]{8,}/g, 'H')
+        .replace(/\d+/g, 'N')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80);
+}
+/**
+ * Group open observations into recurrence clusters.
+ *
+ * Pure over its input — every store read (and every read FAILURE) is the
+ * caller's job to supply, so this function cannot silently swallow one.
+ */
+export function buildRecurrenceReport(observations, coverage) {
+    const open = observations.filter((o) => o.open);
+    const byKey = new Map();
+    for (const o of open) {
+        const k = recurrenceKey(o.title);
+        if (!k)
+            continue;
+        const bucket = byKey.get(k);
+        if (bucket)
+            bucket.push(o);
+        else
+            byKey.set(k, [o]);
+    }
+    const clusters = [...byKey.entries()].map(([key, members]) => {
+        const times = members.map((m) => m.at).filter((t) => !!t).sort();
+        return {
+            key,
+            exemplar: members[0].title,
+            count: members.length,
+            stores: [...new Set(members.map((m) => m.store))],
+            sources: [...new Set(members.map((m) => m.source).filter((s) => !!s))],
+            firstSeen: times[0],
+            lastSeen: times[times.length - 1],
+            tracked: members.some((m) => m.store === 'actions'),
+        };
+    }).sort((a, b) => b.count - a.count);
+    const report = {
+        generatedAt: new Date().toISOString(),
+        coverage,
+        clusters,
+        observationsConsidered: open.length,
+        noticingRatio: clusters.length === 0 ? null : Number((open.length / clusters.length).toFixed(2)),
+    };
+    // A verdict is only meaningful over a COMPLETE read. On a partial read the
+    // field is absent entirely rather than set to a hedged value — an absent field
+    // forces the caller to handle it; a hedged value invites it to be rendered as
+    // if it were an answer.
+    if (coverage.completeness === 'complete') {
+        report.verdict = clusters.some((c) => c.count > 1) ? 'recurrence-found' : 'no-recurrence';
+    }
+    return report;
+}
+/**
+ * The clusters worth a human's attention, by a deterministic rule.
+ *
+ * `minCount` defaults to 2 because a thing noticed once is not yet recurrence.
+ * `untrackedOnly` narrows to the sharpest class: repeatedly noticed, never
+ * turned into work.
+ */
+export function significantClusters(report, opts = {}) {
+    const min = opts.minCount ?? 2;
+    return report.clusters.filter((c) => c.count >= min && (!opts.untrackedOnly || !c.tracked));
+}
+//# sourceMappingURL=RecurrenceReader.js.map

package/dist/core/RecurrenceReader.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.991",
+  "version": "1.3.992",
   "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-07-26T22:54:32.025Z",
-  "instarVersion": "1.3.991",
+  "generatedAt": "2026-07-27T03:37:34.934Z",
+  "instarVersion": "1.3.992",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.992.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Instar notices problems in three separate stores — the attention queue, the evolution action queue,
+and the sentinel log — and nothing has ever read across them. So the same problem is noticed dozens
+of times and closed zero times (measured filing-to-completion ≈ 30:1).
+
+`src/core/RecurrenceReader.ts` groups OPEN observations from all three into recurrence clusters,
+carrying a `coverage` block that names every store it could NOT read. Pure module, read-only, no
+route, no authority.
+
+## What to Tell Your User
+
+Nothing is required of you, and nothing visible changes yet — this ships the engine, not a surface.
+
+What it does, in plain terms: your agent writes down the things it notices in three different places,
+and until now nothing looked at all three together. So one recurring problem could be written down a
+hundred times and read as a hundred separate problems. This groups them.
+
+On a live agent it turned 2,068 unresolved items into 836 actual problems — and found 69 problems
+that had been noticed 1,242 times between them without a single one ever being picked up. The
+largest was one component's warnings repeating 177 times, nearly half that agent's attention queue.
+
+If you later ask your agent "what keeps going wrong?", this is what lets it answer honestly instead
+of reciting a list. And if it can only read some of its records, it will tell you that rather than
+reporting a clean bill — "nothing found" and "couldn't look" stay different answers.
+
+## Summary of New Capabilities
+
+- Groups repeated observations across the attention queue, action queue and sentinel log into
+  distinct problems, so recurrence becomes visible instead of buried in volume.
+- Flags problems noticed repeatedly that were **never** turned into tracked work — the sharpest
+  signal for what is actually being dropped.
+- Refuses to issue a verdict over an incomplete read: any unreadable store is named with its reason,
+  and the verdict field is omitted entirely rather than hedged.
+
+## Evidence
+
+Live data, 2026-07-27: **2,068 open observations → 836 distinct problems** (ratio 2.47). **69
+problems account for 1,242 noticings and none is tracked.** Largest clusters: 278x idle-timeout
+detection, 238x escalation-suppressed, 177x credential rebalancer (48% of the attention queue).
+
+Refusal, on real data with the action store made unreadable: reported the 59 clusters it could see
+and left `verdict` **absent** rather than claiming `no-recurrence`. Unit suite 11/11; `tsc` exit 0.
+
+## Known limits
+
+Title-only keying will not merge the same problem worded differently; semantic matching would mean an
+LLM and a judgment point, deliberately avoided. The blunt key can occasionally over-merge — `exemplar`
+and `sources` are carried so a reader spots it. Read-only: it reports, it does not act. Driving
+action through existing gated paths is the next increment, not this one.

package/upgrades/side-effects/recurrence-reader.md

@@ -0,0 +1,149 @@
+# Side-Effects Review — RecurrenceReader (Tier 2 core, read-only)
+
+**Version / slug:** `recurrence-reader`
+**Date:** `2026-07-27`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `see Phase 5`
+
+## Summary of the change
+
+One pure module (`src/core/RecurrenceReader.ts`) that groups OPEN observations from the attention
+queue, the evolution action queue and the sentinel log into recurrence clusters, plus a `coverage`
+block naming every store it could not read.
+
+Project `convergence-towards-coherence` Tier 2. The plan's diagnosis: instar notices constantly, in
+three places, and nothing reads across them — so one problem is noticed dozens of times and closed
+zero times (measured filing-to-completion ≈ 30:1).
+
+**Measured on live data, 2026-07-27:**
+
+```
+open observations across 3 stores : 2,068
+distinct problems                 :   836
+noticing ratio                    :  2.47
+noticed repeatedly, NEVER tracked :    69 problems / 1,242 noticings
+top clusters:  278x idle-timeout detection
+               238x escalation-suppressed (telegramEscalation disabled)
+               177x credential rebalancer  ← 48% of the attention queue alone
+```
+
+## Refusal evidence (constraint 2)
+
+The whole design risk is that a synthesiser becomes a MORE expensive version of the defect it
+detects: reading 2 of 3 stores and reporting "nothing recurring" with the authority of having looked.
+
+```
+REFUSAL — action store made unreadable, on REAL data
+  coverage      : partial
+  could NOT read: [{"store":"actions","reason":"ENOENT: evolution store unreadable"}]
+  clusters      : 59        ← still reports what it DID see
+  verdict       : ABSENT — refuses to say no-recurrence
+
+THE DISTINCTION THAT MATTERS
+  genuinely nothing there → "no-recurrence"
+  could not look         → undefined  (field absent, not hedged)
+```
+
+Unit suite: **11 passed (11)**; `tsc --noEmit` exit 0.
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| recurrence key (digits→N, hex→H) | `invariant` | Deterministic string normalization. No model. |
+| cluster grouping | `invariant` | Map by key. |
+| `verdict` emitted only on complete coverage | `invariant` | The load-bearing rule. |
+| `significantClusters` minCount / untrackedOnly | `invariant` | Caller-supplied thresholds, defaulted, not inferred. |
+
+No judgment points, no LLM, nothing gated. The module holds **no authority whatsoever** — it returns
+a report.
+
+## 1. Over-block
+
+Nothing is blocked; the module is read-only and returns data. The realistic over-*grouping* risk is
+the blunt key: two genuinely different problems whose titles differ only by digits would merge. That
+is a deliberate trade, stated in the source — surfacing shape is the goal, and an over-eager grouping
+a human instantly recognises as one problem beats a precise grouping that preserves the illusion of
+371 separate things. `exemplar` and `sources` are carried on every cluster so a reader can spot a bad
+merge immediately.
+
+## 2. Under-block
+
+**Title-only keying.** Two reports of the same underlying problem with genuinely different wording
+will not merge. Accepted: the alternative is semantic matching, which means an LLM, which means a
+judgment point in something that currently has none.
+
+**`open` is caller-supplied.** The module trusts the caller's open/closed determination per store.
+That is the correct seam — each store knows its own status vocabulary — but it means a caller that
+mis-maps status inflates or deflates the counts. The live harness maps `status === 'OPEN'`,
+`pending|in_progress`, and treats sentinel events as open.
+
+**No route yet, no action yet.** This increment is the reader only. Driving action is Tier 2 item 4,
+deliberately separate because it carries authority this does not.
+
+## 3. Level-of-abstraction fit
+
+A pure function over supplied observations, with I/O left entirely to the caller. That is
+deliberate: it means the module **cannot** silently swallow a failed store read — the caller must
+hand it a `coverage` block, so an unreadable store is structurally impossible to omit. Putting the
+reads inside would have made "forgot to report the failure" a one-line mistake.
+
+## 4. Signal vs authority compliance
+
+Textbook signal-producer. It returns a report and holds zero blocking, gating or notifying authority.
+`docs/signal-vs-authority.md` satisfied — and this is the exact seam the operator flagged: synthesis
+must drive action through EXISTING gated paths, never become a new notification channel. Keeping the
+reader authority-free is what makes that possible later.
+
+## 5. Interactions
+
+- **Attention queue / evolution actions / sentinel log** — read-only consumers, no writes, no schema
+  change. Nothing else observes this module yet.
+- **Nothing shadows or is shadowed.** New module, no existing caller.
+
+## 6. External surfaces
+
+**None in this increment.** No route, no config, no persisted state, no user-visible behaviour. A
+route is the obvious next step and is deliberately not here.
+
+## 6b. Operator-surface quality
+
+`coverage.unreadable[].reason` carries the actual failure text so a caller can say *why* it could not
+look, not merely that it could not. `noticingRatio` is `null` — never `0` — when there is no
+denominator, so a client that ignores the contract gets an obviously-missing value rather than a
+plausible wrong one.
+
+## 7. Multi-machine posture
+
+**Posture: `machine-local`.** `machine-local-justification: physical-credential-locality` — the three
+stores are per-machine records of what THAT machine noticed, and observation titles routinely carry
+machine ids, topic ids and account emails. Replicating them to synthesise centrally would multiply
+at-rest exposure of that context across every machine. The correct cross-machine read is the existing
+pool-scope fan-out (`?scope=pool`), which serves each machine's own data from that machine — a
+follow-up for whoever adds the route, noted rather than assumed.
+
+## 8. Rollback cost
+
+**Zero.** One new module and one new test file, with no callers. Deleting them removes the feature
+entirely; nothing else changes. No persisted state, no migration, no config.
+
+## Phase 5 — Second-pass review
+
+Not a gate, sentinel, guard or watchdog; no block/allow authority; no session lifecycle or trust
+surface; no LLM. High-risk trigger list not engaged. Author lenses:
+
+**Adversarial — "how would I make this useless?"** By letting it report a clean verdict over a
+partial read. That is the one thing it structurally cannot do, asserted from both directions
+(complete-and-empty → `no-recurrence`; incomplete → field absent) and demonstrated on real data.
+
+**"Would it have caught the incident?"** The incident is the project's premise, and yes — 2,068
+noticings collapsing to 836 problems with 69 untracked recurrers is precisely the shape nobody could
+see. It found it on first run.
+
+**"Symptom or cause?"** Cause, for the invisibility. NOT for the recurrence itself: this makes the
+69 untracked recurrers visible, it does not close them. Closing them is item 4, and claiming
+otherwise would be the filing-as-progress failure the project exists to remove.
+
+**Weakest point:** the blunt recurrence key. It will occasionally merge two things a human would
+separate. Mitigated by carrying `exemplar` + `sources`, and preferable to under-grouping — but it is
+the assumption most likely to need revisiting once a human reads a real report.