instar 1.3.992 → 1.3.994

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

@@ -0,0 +1,130 @@
+# Side-Effects Review — RecurrenceActuator (Tier 2 item 4, plan-only)
+
+**Version / slug:** `recurrence-actuator`
+**Date:** `2026-07-27`
+**Author:** `Echo (instar-dev agent)`
+
+## Summary
+
+`RecurrenceReader` makes recurrence visible. Visibility was never the goal — the project's diagnosis
+is that instar notices constantly and closes almost nothing (≈30:1). A reader nobody acts on is that
+ratio with better typography.
+
+Operator directive 2026-07-26 20:08Z: *"the synthesis itself must lead to ACTION and a fully closed
+loop"*, minimal user dependence.
+
+`planActuation()` returns a PLAN: for clusters that genuinely recur AND are untracked, propose work on
+the EXISTING evolution action queue. Pure — the caller performs the write, so the write path and its
+gating stay exactly where they already are.
+
+**Live dry-run, 2026-07-27:** 836 clusters considered → **3 proposed, 17 deferred by cap**
+(278x idle-timeout, 238x escalation-suppressed, 177x credential rebalancer — all `high`).
+
+## Refusal evidence (constraint 2)
+
+```
+REFUSAL 1 — actions store unreadable  ⇒  propose NOTHING
+  refused.reason : actions-store-unreadable
+  detail         : "…so 'has anyone already committed to this?' is unanswerable for every
+                    cluster. Proposing work now would duplicate whatever is already tracked."
+  propose        : []          consideredClusters: 1   ← still honest about scope
+
+DELIBERATELY NOT SYMMETRIC — attention/sentinel unreadable ⇒ it DOES act
+  Those only UNDERSTATE counts, so a cluster still clearing the bar genuinely clears it.
+  Treating all partial reads alike would be lazy symmetry that blocks safe action.
+
+REFUSAL 2 — per-run cap: 10 qualifying clusters ⇒ propose 3, deferredByCap 7
+REFUSAL 3 — below threshold: seen 3x with minCount 10 ⇒ no-qualifying-clusters
+REFUSAL 4 — already tracked: a member from the action queue ⇒ propose nothing
+```
+
+Tests **10 passed (10)**; combined with the reader **21 passed (21)**; `tsc --noEmit` exit 0.
+
+## A test caught the documented over-merge risk, live
+
+My first cap test built clusters titled `problem 0`…`problem 9` and asserted 3 proposals. It got 1:
+the recurrence key normalizes digits to `N`, so all ten collapsed to one cluster. **The fixture was
+naive, not the code** — and it is a live demonstration of the over-merge trade the reader's
+side-effects review names as its weakest point. Fixed with word-titles and the reason recorded in
+the test.
+
+## Decision-point inventory
+
+| point | classification |
+|---|---|
+| actions-unreadable ⇒ refuse | `invariant` — the load-bearing rule |
+| untracked + minCount filter | `invariant` — deterministic thresholds |
+| per-run cap, densest-first | `invariant` |
+| priority from volume | `invariant` — fixed bands, no model |
+| `externalKey` from cluster key | `invariant` — stable, idempotent |
+
+No judgment points, no LLM.
+
+## 1. Over-block
+
+Refuses entirely when the actions store is unreadable — deliberately, since acting blind creates
+duplicates. Cost: on a broken actions store, nothing is proposed until it is fixed. Correct trade.
+
+The `minCount` default of 10 will skip genuine problems seen 4–9 times. Accepted: a work item per
+seen-twice observation is how the queue got to 371 open in the first place.
+
+## 2. Under-block
+
+**Nothing prevents the CALLER from ignoring the plan or writing it badly.** This module returns data;
+the write is the caller's. That is the right seam (the write path keeps its own gating) but it means
+"the loop closes" is only true once a caller is wired. No caller ships here — that is the next step
+and is not claimed.
+
+**Cancelled actions are not re-proposed-proof.** If a human cancels a proposed action, the cluster
+remains untracked, so a later run could propose it again. The `externalKey` makes it the same row
+rather than a new one, but a "dismissed, stop asking" state belongs to the action store, not here.
+Named as a real gap. <!-- tracked: ACT-1311 -->
+
+## 3. Level-of-abstraction fit
+
+Plan-only, pure over the report. It cannot flood, cannot notify, cannot write. The one thing it
+must never become — a fourth place that notices things — is structurally impossible: it has no
+output channel.
+
+## 4. Signal vs authority compliance
+
+It proposes; it holds no authority. Creating a tracked action QUEUES work for a human or agent to
+judge — it does not close, prioritise beyond a fixed volume rule, escalate, or act.
+
+## 5. Interactions
+
+Consumes `RecurrenceReport` only. No writes, no schema change, no existing caller. Depends on
+`RecurrenceReader` (same branch, PR #1662) — this is stacked on it.
+
+## 6. External surfaces
+
+**None.** No route, no config, no persisted state, no user-visible behaviour in this increment.
+
+## 7. Multi-machine posture
+
+**Posture: `machine-local`.** `machine-local-justification: physical-credential-locality` — it plans
+over one machine's stores, whose observation titles carry that machine's ids, topics and account
+emails. Cross-machine synthesis would mean replicating those records; the correct route is the
+existing pool-scope fan-out, serving each machine's data from that machine.
+
+## 8. Rollback cost
+
+**Zero.** One module, one test file, no callers. Delete removes the feature.
+
+## Phase 5 — Second-pass review
+
+No gate/sentinel/watchdog, no block/allow authority, no session lifecycle, no LLM. Author lenses:
+
+**Adversarial — "how would I make this useless?"** Let it propose blind when the actions store is
+down (duplicates existing work), or let it propose for everything at once (new backlog). Both are
+asserted refusals.
+
+**"Would it have caught the incident?"** The incident is 69 untracked recurrers. It selects exactly
+that class and would open the top three today.
+
+**"Symptom or cause?"** Cause for the never-gets-picked-up half. NOT for the recurrence itself —
+proposing work does not fix the 278x idle-timeout; it makes someone decide about it. Claiming
+otherwise would be filing-as-progress.
+
+**Weakest point:** no caller is wired, so "the loop closes" is a designed property, not yet a
+demonstrated one. The dry-run shows what it WOULD propose; nothing has been written.

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

@@ -0,0 +1,112 @@
+# Side-Effects Review — recurrenceLoop (the caller that closes the loop)
+
+**Version / slug:** `recurrence-loop` · **Date:** `2026-07-27` · **Author:** `Echo (instar-dev agent)`
+
+## Summary
+
+`RecurrenceReader` sees; `RecurrenceActuator` decides. Both are pure, which left **"the loop closes"
+a DESIGNED property, not a demonstrated one** — the weakest point named in the actuator's own review.
+This closes it: read three stores → group → plan → create, via a caller-supplied `createAction`.
+
+It is deliberately the ONLY I/O in the feature, so every read failure has exactly one reporting site
+and cannot be swallowed mid-pipeline.
+
+**Live run, writes intercepted, 2026-07-27:** coverage `complete` (attention, actions, sentinel);
+836 problems; **would create 3, deferred 17, 0 write failures, no refusal.**
+
+## Refusal evidence (constraint 2)
+
+```
+REFUSAL — action store unreadable ⇒ createAction NEVER CALLED
+  create spy      : not called          created: 0
+  refused.reason  : actions-store-unreadable      writeFailures: 0
+
+A FAILED WRITE IS NOT A REFUSAL  (the distinction this module exists to protect)
+  createAction throws '503 action store unavailable'
+    refused       : undefined      ← an outage must NOT present as judgement
+    writeFailures : [{ error: '503 …' }]
+    created       : 0
+
+  one failure among three ⇒ created 2, writeFailures 1 (others not abandoned)
+
+UNREADABLE STORE IS DATA, NOT AN EXCEPTION
+  sentinel throws ⇒ coverage.unreadable names it, completeness 'partial',
+    and it STILL creates 1 (sentinel only understates counts)
+  all three throw ⇒ verdict undefined, created 0, no crash
+```
+
+Tests **9 passed (9)**; whole feature **30 passed (30)**; `tsc --noEmit` exit 0.
+
+## Decision-point inventory
+
+| point | classification |
+|---|---|
+| read failure → coverage gap | `invariant` — try/catch → named entry, never a throw |
+| refusal vs write-failure separation | `invariant` — distinct fields, the load-bearing rule |
+| write loop continues past a failure | `invariant` |
+
+No judgment points, no LLM, no authority: `createAction` is supplied by the caller, so the write path
+keeps whatever gating it already has. This module never constructs an HTTP call.
+
+## 1. Over-block
+
+Refuses to write when the actions store is unreadable — inherited from the actuator and correct: it
+cannot tell what is already owned. Cost: a broken actions store stops proposals until fixed.
+
+## 2. Under-block
+
+**No scheduler/route calls it.** Running it is deliberate. So this demonstrates the loop CAN close,
+not that it closes *unattended*. Wiring a cadence is a separate increment with its own risk, and is
+not claimed here.
+
+**No dismissal memory.** A cancelled action leaves the cluster untracked, so a later run can propose
+it again (same `externalKey`, so one row, not many). A "dismissed, stop asking" state belongs to the
+action store. <!-- tracked: ACT-1311 -->
+
+**`createAction` failures are reported, not retried.** Deliberate: retry policy belongs to the write
+path, and a silent retry here would obscure the outage the separate field exists to surface.
+
+## 3. Level-of-abstraction fit
+
+All I/O in one place, everything else pure. The alternative — reads scattered through reader and
+actuator — is exactly how a failed read becomes an empty result that reads as "nothing found".
+
+## 4. Signal vs authority
+
+Holds none. It executes a plan produced by deterministic rules and writes through a function the
+caller owns.
+
+## 5. Interactions
+
+Consumes `RecurrenceReader` + `RecurrenceActuator` (same stack, PRs #1662 / actuator branch). Writes
+only via the injected function. No schema change.
+
+## 6. External surfaces
+
+**None.** No route, no config, no persisted state of its own.
+
+## 7. Multi-machine posture
+
+**Posture: `machine-local`.** `machine-local-justification: physical-credential-locality` — it reads
+one machine's stores, whose observation titles carry that machine's ids, topics and account emails,
+and writes to that machine's action queue. Cross-machine synthesis would mean replicating those
+records; the existing pool-scope fan-out is the correct route.
+
+## 8. Rollback cost
+
+**Zero.** One module, one test file, no callers.
+
+## Phase 5 — Second-pass review
+
+No gate/sentinel/watchdog, no block/allow authority, no LLM. Lenses:
+
+**Adversarial — "how would I make this useless?"** Report a write outage as a refusal, so breakage
+reads as judgement. Asserted against directly.
+
+**"Would it have caught the incident?"** It IS the incident's remedy: 69 untracked recurrers, top
+three actionable today.
+
+**"Symptom or cause?"** Cause for never-picked-up. Not for the recurrence itself — creating an item
+makes someone decide about the 278x idle-timeout; it does not fix it.
+
+**Weakest point:** nothing schedules it. "Closes unattended" remains unclaimed.

package/upgrades/side-effects/round-completion-verifies-merged.md

@@ -0,0 +1,137 @@
+# Side-effects review — round completion verifies merged state
+
+**Change:** `runRound`'s `verifyMergedItems` seam no longer defaults to a no-op that reports nothing
+verified. It defaults to the real git-backed `verifyMergedItemsViaGit`, the seam carries the
+three-state `MergedVerificationResult`, and a new `unverifiable` outcome records **no** round status.
+
+**Decision point touched:** yes — two of them. (a) whether a round is complete; (b) whether to spawn
+an autonomous child. Both previously ran on a verifier that could only ever say "nothing verified".
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+The one real risk is stalling a round that should proceed. `verifyMergedItemsViaGit` reports
+`unverifiable` for an item with **no `mergeCommitOid`**, which is the ordinary state of a round nobody
+has worked yet. A naive "any unverifiable ⇒ don't spawn" would deadlock **every fresh round** — a far
+worse defect than the one being fixed.
+
+Handled by splitting on **evidence**: only an item that *records* a merge commit and cannot be checked
+counts as genuinely uncheckable. An item with no recorded commit is not-done, and the child spawns.
+Pinned by `an item with NO merge commit recorded is NOT-DONE, not unknown — the child still spawns`.
+
+This test earned its place: the first draft applied the evidence rule at the pre-spawn check only,
+and the post-exit check kept the old conflation. The test failed, and the predicate is now defined
+once and used at both sites.
+
+## 2. Under-block — what does it still miss?
+
+- **CI-green is still not checked.** Verification remains merge-base reachability of a recorded
+  commit. An item merged with red CI verifies. Unchanged by this PR; `StageTransitionValidator`
+  performs the stronger check on the `/advance` path.
+- **No scheduling.** Nothing here makes rounds run; it makes a run able to conclude.
+- **`resolveCanonicalMainRef` is best-effort.** If `gh` is absent it falls back to `origin/main`,
+  which on a fork-origin home under-verifies (items read as regressed → a spawn, i.e. redoing work).
+  That is the pre-existing conservative default, now applied to this path too rather than left to a
+  caller to remember.
+
+## 3. Level-of-abstraction fit
+
+`resolveCanonicalMainRef` moved from `src/server/routes.ts` into `src/core/ProjectRoundExecution.ts`
+and is imported back. Both consumers — the lazy reconciler and this runner — need identical
+resolution, and a core module must not import from `server/`. Net: one definition, two callers,
+correct direction. The two source-grep tests in `merged-record-carries-its-evidence.test.ts` assert
+the *call* in `routes.ts`, not the definition, and still pass.
+
+## 4. Signal vs authority
+
+The verifier stays a **signal** — it reports three states and holds no blocking authority. `runRound`
+is the authority and now consumes all three rather than flattening them. The specific improvement:
+the authority can no longer be handed a value ("empty set") that is indistinguishable from a real
+negative reading. Per `docs/signal-vs-authority.md`, the failure was not a brittle check holding
+authority; it was an authority whose input could not express uncertainty.
+
+## 5. Interactions
+
+- **`/projects/:id/advance`** — untouched. Item-level stage transitions still go through
+  `StageTransitionValidator`; this only affects round-level outcome.
+- **`ProjectAutoAdvancePoller`** — unchanged; it clears `autoAdvanceAt` and counts unacked advances.
+  It now sees rounds that can actually reach `complete`.
+- **`ProjectDigestCache`** — unchanged, and this is the visible effect: the session-start
+  `N of M done` line can move off zero for the first time via the poller path.
+- **Double-fire / races** — none added. `unverifiable` performs strictly *fewer* writes than any
+  other outcome (it writes nothing), so it cannot race the tracker's OCC.
+
+## 6. External surfaces
+
+`RoundOutcome` gains `'unverifiable'` — a TypeScript-level addition on an exported union. In-repo
+consumers are `ProjectRoundExecution` itself and the tests; `recordOutcome` maps
+`Exclude<RoundOutcome,'unverifiable'>` so the compiler enforces the exhaustiveness rather than a
+runtime default swallowing it. No route, no config key, no user-visible string.
+
+## 7. Multi-machine posture
+
+**Machine-local BY DESIGN**, `machine-local-justification: hardware-bound-resource` — the check runs
+`git merge-base` against a working checkout on local disk, and the round runner already holds a
+host-local `ProjectRoundLock` (`.instar/local/round-runner.lock`). Round execution is bound to the
+machine holding the checkout; nothing here introduces state another machine would need to read. No
+notice, no durable cross-machine record, no generated URL.
+
+## 8. Rollback cost
+
+Low and local. One file's behavior plus a moved helper; no data migration, no config, no persisted
+schema. Reverting restores the prior behavior exactly — including the defect. A round left in
+`pending` by an `unverifiable` outcome is a normal pending round; nothing to repair.
+
+## Refusals demonstrated (command + output)
+
+Falsification 1 — neutralise the evidence predicate (`ids.filter(() => false && …)`):
+
+```
+× an item that RECORDS a merge commit but cannot be checked → no respawn, and NO round verdict
+× child exits 0 but the shortfall is entirely uncheckable → unverifiable, NOT partially-complete
+  Tests  2 failed | 8 passed (10)
+```
+
+Falsification 2 — re-introduce a default returning an unconditional empty verdict:
+
+```
+× the seam cannot default to silence again > has no default verifier that returns an unconditional empty set
+  Tests  1 failed | 9 passed (10)
+```
+
+Restored: `Tests 36 passed (36)` across the four affected files, `tsc --noEmit` exit 0.
+
+Falsification 3 — **a guard I did not anticipate, which changed the code.** The full suite failed on
+`lint-sync-subprocess-chokepoint`:
+
+```
+src/core/ProjectRoundExecution.ts:569 — raw sync spawn (execFileSync('gh', …)).
+A sync blocking op must funnel through withSyncOp() so the in-flight marker sees it.
+lint-sync-subprocess-chokepoint: 1 new violation(s).
+```
+
+In `routes.ts` that callsite sat on the lint's **frozen baseline** — grandfathered, not blessed.
+Moving it into core made it a NEW violation. The refusal is the useful part: `runRound` is called
+from the server's auto-advance poller, so a blocking `gh repo view` there stalls the event loop.
+Now funnelled through `withSyncOp` so the in-flight marker classes the stall instead of it
+presenting as an unexplained freeze. Lint after: `clean — 97 raw sync spawn(s), all grandfathered
+(142 baselined)`.
+
+Worth noting the lint is a deliberately **lexical, same-line** matcher (`/\bwithSyncOp\s*\(/`) and
+says so in its own header — it cannot prove runtime wrapping, which is the marker's unit test's job.
+My first wrap was semantically correct across three lines and still flagged. That is signal-vs-
+authority working as designed: a cheap check that names a hazard, not a proof.
+
+## Known-failing locally, verified NOT caused by this change
+
+`tests/e2e/dev-preflight-cli.test.ts` fails in this worktree. The cause is inside preflight's lint
+step, which shells out to `pnpm install`; reproduced standalone:
+
+```
+pnpm install → PNPM_EXIT=1
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: baileys, better-sqlite3, esbuild, sharp, …
+```
+
+That is a dependency build-script approval issue in a worktree installed with `npm ci`, naming only
+third-party packages and reading none of the changed files. Not run to completion deliberately —
+`pnpm install` would restructure the `node_modules` the 36 passing tests were validated against. CI
+installs the project its own way and is the arbiter; flagged here rather than quietly omitted.