instar 1.3.1019 → 1.3.1021

package/upgrades/1.3.1021.md

@@ -0,0 +1,60 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The claim-verification observer now records **why** a protected-cue span was booked as an extraction
+gap, instead of only recording that one was. Per `docs/specs/claim-verification-sentinel.md` §2.1,
+the deterministic protected-predicate lane is specified to emit
+`ExtractionGapSignal {minimumCriticality, reason, span}`. That signal had never been built — the
+shipped code returned a deduped list of bare cue-family names, so all three spec-distinguished causes
+rendered as the same string.
+
+Each gapped span now carries one of three reasons: `no-overlapping-claim` (the model extracted
+nothing there), `unendorsed-overlap` (a claim *did* overlap, but only quoted/hedged/non-endorsed —
+the extractor classified it correctly and was charged for a gap anyway), or `invalid-envelope`.
+
+Two correctness fixes came with it:
+
+- The cue scan stopped at the first matching candidate per family, so a later uncovered span was
+  never examined. It now scans every span, as §2.1 requires. Gap counts rise as a result — this is
+  a measurement fix, not an extractor regression.
+- Audit rows written by this path are stamped `schemaVersion: 2`. **Gap rates must not be compared
+  across that boundary**: version-1 rows undercount and carry no reason.
+
+## What to Tell Your User
+
+Nothing — there is no user-visible change, no new command, and no behavior difference in any
+conversation. This is internal measurement plumbing for a feature that ships dark and runs in
+dry-run: it observes and records, and holds no authority to block, delay, or alter any message.
+
+If a user asks why it was worth doing: the observer had been running for days producing a number
+nobody could interpret. About 89% of recorded gaps were the completion family, but with only a
+family name stored there was no way to distinguish the observer genuinely missing a claim from the
+observer being penalised for correctly marking something as hedged or quoted. The reason field
+separates those two, which is what the accumulated data was missing.
+
+## Summary of New Capabilities
+
+None for users. Internally, the claim observer's gap events now carry a reason, a byte span, and a
+criticality floor per gapped span instead of a bare family name, and the audit rows that record them
+are capped per family with an explicit marker whenever trimming occurs, so a trimmed sample can
+never be mistaken for a complete one.
+
+## Evidence
+
+- `tests/unit/extraction-gap-signal.test.ts` — 20 tests covering all three reasons, the no-gap case
+  (endorsed overlap), the criticality floor per cue family, span correctness, the every-span fix,
+  `gapKinds` back-compat, per-family truncation, and rejection of malformed caller payloads.
+- Old-vs-new demonstrated directly: on `"The migration is done."` the previous algorithm emits
+  `["completion"]` for a hedged overlap **and** for a true no-overlap — identical output, different
+  cause. On `"The merge is done. The deploy is finished."` with the first sentence covered, it emits
+  `[]` and misses the genuine gap.
+- Per-family truncation bug caught in second-pass review and reproduced before fixing: 72 signals on
+  a 24-candidate message, of which a flat head-slice kept only `capacity` and dropped `completion`
+  and `state` entirely.
+- 36/36 green (20 new, 11 pre-existing `claim-observation-v1` untouched, 5 integration
+  `completion-claim-stats-route`).
+- Side-effects review with second-pass: `upgrades/side-effects/extraction-gap-signal-reason.md`.

package/upgrades/periodic-goal-realignment-phase1.eli16.md

@@ -0,0 +1,56 @@
+# ELI16 — A durable compass for long autonomous work (Phase 1)
+
+## What changed
+
+Long autonomous runs now have an observation-only alignment reviewer. On development
+agents, verified operator messages in an active run's topic feed a durable priority
+ledger, and a periodic reviewer compares that ledger with the run's current goal and
+unfinished tasks.
+
+Phase 1 only sees and records. It does not inject advice into sessions, edit the run
+plan, block work, create attention items, or notify the operator. The authenticated
+`GET /goal-realignment` status surface shows the candidate inbox, active/closed
+priorities, counters, and latest dry-run verdict.
+
+## Important lifetime rule
+
+The recency window controls discovery of new priorities only. Once a verified
+priority is recorded, it remains active until an explicit later operator message
+supersedes it or clearly confirms it addressed. Silence and age never remove it.
+
+The risky `diverged` verdict still requires validated evidence on both sides: an
+authoritative priority citation and an exact contradictory or abandoning quote from
+the current run focus. Missing, conflicting, or incomplete evidence becomes
+`indeterminate`.
+
+Incomplete is enforced before model review: truncated history, an unresolved
+candidate extraction, or a digest projection that omits a live priority records
+`indeterminate` at confidence zero and makes no reviewer call.
+
+## Durability and provenance
+
+- Every deterministic instruction-shaped operator message enters a candidate inbox
+  before model classification.
+- Extraction checkpoints persist the source cursor, exact raw provider output,
+  validated result, prompt ID, and model ID before any ledger event.
+- A crash after the checkpoint reuses it, producing the same deterministic priority
+  ID without another model call.
+- Telegram forwarded-message provenance now survives TopicMemory storage and
+  rebuilds. Legacy rows with unknown forwarded state remain ineligible.
+- Both LLM decisions emit bounded, identity-only decision provenance; raw operator
+  text and run-focus bodies are not copied into the provenance archive.
+
+## Rollout
+
+The feature is development-agent gated and structurally `dryRun: true`. Fleet agents
+remain dark. Existing TopicMemory databases migrate automatically from schema 4 to
+schema 5 by adding the nullable forwarded-provenance column. No operator action or
+configuration change is required.
+
+## Validation
+
+Refusal-first coverage pins the three acceptance cases: an old standing priority
+survives the discovery window, quoted-only instructions require operator
+confirmation, and crash replay reuses the checkpoint and priority ID. Unit,
+integration, end-to-end, type, lint, and build results are recorded in the Phase 1
+validation artifact.

package/upgrades/side-effects/extraction-gap-signal-reason.md

@@ -0,0 +1,254 @@
+# Side-Effects Review — ExtractionGapSignal reason + span (spec §2.1 conformance)
+
+**Version / slug:** `extraction-gap-signal-reason`
+**Date:** `2026-07-27`
+**Author:** `echo`
+**Second-pass reviewer:** `required — sentinel/observability surface (see Phase 5 section)`
+
+## Summary of the change
+
+`docs/specs/claim-verification-sentinel.md` §2.1 specifies that the deterministic
+protected-predicate lane emits `ExtractionGapSignal {minimumCriticality, reason, span}` when a
+protected cue "has no overlapping endorsed claim, has only quoted/hedged/non-endorsed overlap, or
+the envelope is invalid." That signal was never built: `git grep ExtractionGapSignal` returned zero
+hits across `src/` and `tests/`. The shipped `protectedCueGaps()` returned a deduped list of bare
+cue-family names, so all three spec-distinguished causes rendered as the same string.
+
+This change implements the signal. `extractionGapSignals()` (in `src/monitoring/ClaimObservation.ts`)
+scans every candidate span for every cue family and returns one signal per gapped span carrying the
+reason, the byte span, and the §2.5 criticality floor. `protectedCueGaps()` is retained, now derived
+from those signals, so existing counters and the `gapKinds` audit field are unchanged.
+`CompletionClaimVerifier.observe()` writes the new `gapSignals` array alongside `gapKinds`, and
+`ClaimObservationRecorder.recordEvent()` gains a strictly-clamped, per-family-capped allowlist
+branch for it, stamping `schemaVersion: 2`.
+
+`gapKinds` keeps its shape and its consumers, but its *values* are monotone-increasing — see §5.
+
+Files touched: `src/monitoring/ClaimObservation.ts`, `src/monitoring/CompletionClaimVerifier.ts`,
+`tests/unit/extraction-gap-signal.test.ts` (new).
+
+**Why now:** the missing `reason` is the measurement blocker that held EVO-005 across eleven review
+cycles. 89.1% of gap events (295/331 in the live audit) are the `completion` family, and with only a
+family name recorded there is no way to tell a real extractor miss from the extractor being charged
+for a span it correctly marked hedged or quoted. Demonstrated concretely: under the old algorithm a
+hedged overlap and a true no-overlap both emit exactly `["completion"]`.
+
+## Decision-point inventory
+
+- `protectedCueGaps` / `extractionGapSignals` (`src/monitoring/ClaimObservation.ts`) — **modify** —
+  deterministic cue detector. Produces observations only. Holds no blocking authority before or
+  after this change.
+- `CompletionClaimVerifier.observe` audit emission — **modify** — adds a field to an existing
+  dark, dry-run audit row. No change to any return value that a caller branches on.
+- `ClaimObservationRecorder.recordEvent` allowlist — **modify** — adds one clamped structural field.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The signal never gates a message. The
+feature is dark (`dryRun: true` in production today) and §2.1 states the shadow signal "never
+creates a factual claim or verdict." `observe()`'s return contract is untouched.
+
+The nearest analogue to an over-block is over-*counting*: the fixed scan now books gaps the old
+first-match-then-break loop skipped, so gap counts rise. That is the correct count per §2.1 ("every
+protected-cue span"), but see §5 for the baseline discontinuity it creates.
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.**
+
+What the change still does *not* measure, stated plainly:
+
+- **Cue over-breadth is untouched.** The `completion` regex fires on the noun "fix" (983 occurrences
+  in the local message corpus, the single dominant token) and on instar's own term of art "ships
+  dark", which means deliberately DISABLED — the opposite of a completion claim. Those produce
+  `no-overlapping-claim` signals indistinguishable from genuine extractor misses. Separating them
+  requires recording the matched cue token, which is **out of scope here and deliberately so**: §2.6
+  fixes a closed audit field list and forbids raw claim text and plain content hashes, so a cue-token
+  field is a spec change needing its own convergence and approval.
+  <!-- tracked: ACT-1433 -->
+- `reason` therefore quantifies the endorsement-filter share of the gap rate exactly, and leaves the
+  cue-over-breadth share unresolved. It narrows the ambiguity; it does not eliminate it.
+- The `injection` family is assigned a `high` floor rather than its own tier. §2.1 names only
+  approval/capacity/completion/credential for `high` and consequential-action premises for
+  `irreversible-precondition`; injection markers are conservatively floored at `high` because
+  uncertainty rounds up per §2.3.
+- **Per-family truncation.** A single turn emitting more than 8 gapped spans in one family keeps the
+  first 8 of that family and sets `gapSignalsTruncated: true`. Within-family reason shares are
+  therefore biased toward earlier spans on those (rare) rows. The truncation is recorded, so such
+  rows can be excluded from a reason-share computation rather than silently skewing it.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The detector already lives in `ClaimObservation.ts` and already computed the overlap
+relation this change reports — the information was being discarded one line after being derived, not
+gathered somewhere new. No higher layer could reconstruct it, because only this function sees both
+the cue span and the claim's endorsed/quoted/hedged flags at the same time.
+
+This feeds the existing audit lane rather than creating a parallel one, per §2.6's "one bounded
+origin-local append/read/rotation path."
+
+## 4. Signal vs authority compliance
+
+**Compliant.** Reference: `docs/signal-vs-authority.md`.
+
+This is a detector producing a strictly richer structured signal. It gains no blocking power, adds
+no new code path that can refuse or alter a message, and does not become an input to any authority
+in this change. Per §2.1 the gap signal "is the coarse non-LLM recall floor: a high-criticality
+observation, not a normalized factual claim, and therefore cannot support/refute."
+
+The `minimumCriticality` field is worth calling out specifically: it is a *label carried on an
+observation*, not a threshold anything acts on. Nothing in this change reads it back.
+
+## 5. Interactions
+
+- **`gapKinds` shape preserved; values monotone-increasing.** `protectedCueGaps()` keeps returning
+  deduped family names and still populates `gapKinds`. But old ⊆ new strictly: the old loop pushed a
+  family iff the *first* pattern-matching candidate was uncovered, the new one iff *any* is, so
+  `gapKinds` can gain a family and can never lose one. The existing `toContain('capacity')` assertion
+  is safe and all 11 pre-existing tests pass unmodified — but "unchanged" would be wrong, and callers
+  comparing counts across the boundary must not treat the two as the same measurement.
+- **`coverageIncompleteTurns` shifts too.** `CompletionClaimVerifier` bumps it on `gaps.length > 0`,
+  and `gaps` can now be non-empty on turns where it previously was not. That counter moves in the
+  same direction and for the same reason, and is not a regression.
+- **Baseline discontinuity — the real interaction risk.** Anyone comparing gap rates across this
+  deploy sees a step change that is a measurement fix, not an extractor regression. **Split on
+  `schemaVersion`**: pre-change rows are `1`, post-change rows are `2`. Key-absence was the first
+  proposed marker and is wrong — it only works via a coupling (the verifier happens to write the row
+  only when signals exist), and `recordEvent` will legitimately write a `gapSignals`-free row, which
+  a dedicated test asserts. The version stamp is the durable marker.
+- **`schemaVersion` is per-row-TYPE, not per-file.** `recordEvent` rows are now `2`, while
+  `record()` and `recordAuthoritativeOutcome` keep writing `1` into the same
+  `claim-observation-audit-v2.jsonl`. Splitting gap rows on `schemaVersion >= 2` is correct because
+  gap rows are event rows; an analyst splitting the *whole file* will find claim-observation rows
+  stay `1` forever, which is expected and not a bug.
+- **Truncation cannot silently bias the sample.** The per-family cap replaced a flat head-slice that
+  would have dropped whole trailing families. Because emission is family-outer, that slice kept only
+  `capacity` on a busy message and discarded `completion` (the family the statistic is about) and
+  `injection` (the adversarial family) entirely — reproduced at 72 signals → 1 surviving family
+  before the fix, and covered by a regression test now.
+- **No double-fire.** The audit row is emitted once per turn under the existing `gaps.length > 0`
+  guard, which is unchanged.
+- **Shared metric untouched.** `this.bump('protectedCueGaps')` still iterates deduped kinds, so the
+  `/metrics/features` magnitude is not redefined by the richer signal list.
+
+## 6. External surfaces
+
+No route, no schema served to another agent, no user-visible surface. The audit file is local and
+already exists. `/completion-claim/stats` is unaffected — its integration test passes unmodified.
+
+Privacy: the new field carries a cue-family name, a reason enum, a criticality enum, and two integer
+byte offsets. No message text.
+
+**On whether byte offsets sit inside the §2.6 boundary — the honest argument.** An earlier draft of
+this artifact claimed the offsets are "the same class already carried by
+`sourceStartByte`/`sourceEndByte` throughout §2.6." That is false and has been removed: in §2.6 those
+offsets appear only as HMAC inputs to `claimId`, never as a persisted plaintext field, so this is the
+first plaintext persistence of that value. The real basis is threefold:
+
+1. The §2.6 closed field list is already pervasively exceeded by shipped code — `recordEvent` today
+   writes `ts, evaluated, flagged, event, verdict, actionKind, hadToolCalls, reason, gapKinds`, none
+   of which are in the list, and `record()` persists `actualLatencyMs`, a plaintext un-bucketed
+   numeric of exactly the class at issue. `gapSignals` introduces no *new* class of deviation.
+2. The forbidden categories are enumerated — raw text, paths, URLs, identities, secrets, credentials,
+   commands/results, free-form rationale, plain content hashes. A byte offset is none of them.
+3. The §2.6 re-identification concern is about *joining* shape/model/timing/pseudonym. These
+   `protected-cue-unextracted` rows carry no join key at all — no `messagePseudonym`,
+   `topicPseudonym`, or `claimId` — so the offsets are not joinable to a message or topic.
+
+Residual disclosure is real and worth naming: an offset pair is a coarse sentence-length/position
+fingerprint in mode-0600 local operational data. It sits strictly below the existing
+`actualLatencyMs` bar. If a reviewer disagrees that (1) is acceptable, the correct response is a
+spec-level cleanup of the closed list, not a carve-out for this field.
+
+Clamping: `recordEvent` clamps every field, drops unknown keys, and caps per family — covered by a
+test asserting a planted `secretField` never reaches disk. **This guarantee is conditional on
+`opts.recorder` being set.** `CompletionClaimVerifier.appendAudit` has a fallback path that writes
+the raw row to `logs/completion-claim-audit.jsonl` with no clamping. That is pre-existing (`gapKinds`
+has identical exposure) and carries no live risk here because `gapSignals` is internally produced,
+never caller-supplied — but the guarantee is not unconditional and should not be stated as such.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN**, and strictly more so than the pooled-rows posture would require.
+
+`gapSignals` never enters the pool projection at all: `readPoolAggregates`/`readPoolPage` read the
+corpus path, not the audit path, and the peer merge in `routes.ts` is an explicit field allowlist
+(`day, claimShapeId, modelDoor, verifierVersion, count, verdicts`). So there is no pool-side surface
+to leak — a reviewer should not go looking for one. (An earlier draft said the field "inherits the
+pooled untrusted-display posture," which invited exactly that wasted search.)
+
+The consequence for measurement: a gap-reason figure is per-machine and cannot be assembled across
+the pool through any existing read. No user-facing notice, no durable state that strands on topic
+transfer, no generated URL.
+
+## 8. Rollback cost
+
+**Low.** The change is additive and observation-only. Reverting the commit restores the prior
+function body; no migration, no agent state repair, no data cleanup. Existing audit rows remain
+readable either way because `gapSignals` is an optional key that consumers must already tolerate the
+absence of (every historical row lacks it). No release is gated on it and nothing reads the field
+back yet.
+
+---
+
+## Phase 5 — second-pass review
+
+Required: the change touches a sentinel/observability surface in the claim-verification family.
+
+**Reviewer verdict: "Concern raised" — one blocking finding, since resolved; several should-fixes,
+all folded into the sections above.**
+
+**Blocking (fixed).** The persisted `gapSignals` array used a flat `.slice(0, 24)`. Because
+`extractionGapSignals` emits family-outer, that silently dropped whole trailing families —
+reproduced on a 24-candidate message at 72 signals where only `capacity` survived and `completion`
+and `state` were discarded entirely. The bias ran precisely against the change's purpose: the
+motivating figure is that ~89% of gaps are the `completion` family, and `completion` was the first
+thing dropped. Resolved with a per-family cap of 8 plus a `gapSignalsTruncated` marker, and a
+regression test. **This is the finding that justifies the phase** — the change would otherwise have
+shipped a measurement instrument biased in the one direction guaranteed to make it useless, and the
+bias would not have shown up in any of the tests written before the review.
+
+**Should-fixes, all applied:** the §2.6 span justification was factually wrong and has been rewritten
+with the real argument (§6); `gapKinds` was described as "unchanged" when it is monotone-increasing
+(§5, summary); the `coverageIncompleteTurns` shift was unlisted (§5); `schemaVersion` was not bumped
+and the proposed key-absence split marker rested on a coupling (§5, now `schemaVersion: 2`); the
+multi-machine section overstated exposure (§7); the clamping guarantee is conditional on
+`opts.recorder` (§6); and two `§2.5` citations were actually `§2.3` (fixed in both the artifact and
+the code comment).
+
+**Second round — reviewer verdict: "Concur."** The blocking finding was independently re-verified
+against the staged code (72 signals produced → 24 persisted as 8/8/8 across all three families,
+`gapSignalsTruncated: true`, `schemaVersion: 2`). The reviewer agreed with capping per-family at 8
+rather than raising to 144, on the grounds that the statistic is a per-family reason *share*, so
+preserving the family distribution is the property that matters, and that the residual within-family
+position bias is *recoverable* because truncated rows are marked and can be excluded.
+
+**One new finding, introduced by the blocking fix, since resolved.** Replacing the flat
+`.slice(0, 24)` removed the *unconditional* array bound: the per-family cap alone bounds the array
+at 8 × distinct kinds, and `kind` is caller-supplied. Probed at 5,000 invented kinds → 5,000
+persisted objects in a ~559KB row, with `gapSignalsTruncated` correctly false because nothing was
+dropped per family. Not reachable from the in-tree producer (6 families, ≤48 objects), but
+`recordEvent` is deliberately an untrusted-input boundary and `appendBounded` rotates-then-writes
+instead of rejecting an oversized row, so an unbounded row would cost audit *history*. Resolved with
+an unconditional `.slice(0, 48)` that also sets the truncation marker, plus a hostile-input test.
+
+**Reviewer answers to the two questions posed:**
+- **(a) Span inside the privacy boundary:** yes, but not for the reason originally given. Basis
+  rewritten in §6.
+- **(b) Raising counts mid-soak:** correct; do not flag-preserve the old behavior. The old scan is a
+  recall bug, not a baseline — §2.7 sets deterministic protected-gap recall at 1.0 on closed cue
+  fixtures, which the broken scan structurally cannot meet. Preserving it would keep accumulating a
+  measurement known to be false in a known direction. Old ⊆ new is provable, so the discontinuity is
+  monotone and interpretable.
+
+**Open question the review surfaced, not resolved here:** whether the §2.7 readiness clock (≥1,000
+admitted messages / 200 settled T0 claims over 14 days) restarts for gap-rate metrics, given that
+this changes the definition of the measured quantity mid-window. It plausibly should. That is a
+judgment about the soak's validity, not about this code, and belongs to whoever reads the re-soak.
+<!-- tracked: ACT-1433 -->
+
+**Confirmed clean by the reviewer:** no blocking authority (nothing reads `gapSignals` or
+`minimumCriticality` back — the sole consumer maps to `kind` and discards the rest);
+level-of-abstraction fit; rollback cost; no double-fire; and the §2 cue-over-breadth disclosure.

package/upgrades/side-effects/periodic-goal-realignment-phase1.md

@@ -0,0 +1,222 @@
+# Side-Effects Review — Periodic Goal Re-Alignment Phase 1
+
+**Version / slug:** `periodic-goal-realignment-phase1`
+**Date:** `2026-07-27`
+**Author:** `Instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds the observation-only first slice of periodic goal realignment:
+Telegram operator provenance survives `TopicMemory`, verified instruction-shaped
+messages enter a durable candidate inbox, semantic extraction is checkpointed before
+append-only priority events, and a cadence-shaped reviewer writes dry-run verdicts
+visible through authenticated `GET /goal-realignment`. It changes
+`TopicMemory`, Telegram/shared logging, config/types/capability/route registration,
+server wiring, a new `GoalRealignment` module, tests, and the approved spec's single
+operator-amended lifetime decision. There is no injection or action path.
+
+## Decision-point inventory
+
+- `detectCandidatePriority` — **add** — recall-biased deterministic detector decides
+  which verified messages enter the holding list; it cannot create authority or
+  retire a priority.
+- `GoalRealignmentIntake` provenance eligibility — **add** — hard boundary requiring
+  exact authenticated operator UID plus explicit `forwarded:false`.
+- `PriorityExtraction` — **add** — context-rich semantic classification proposes
+  priority/restatement/supersession/completion states, with exact authored grounding
+  and conservative confirmation thresholds.
+- `AlignmentReviewer` — **add** — semantic signal producer labels current run focus;
+  `diverged` is mechanically downgraded to `indeterminate` without valid two-sided
+  evidence.
+- `GoalDigestBuilder` — **add** — deterministic materialized projection excludes
+  only explicitly superseded or confirmed-addressed priorities; age never retires
+  authority.
+
+---
+
+## 1. Over-block
+
+No message-delivery or work-action block surface exists. A legitimate operator
+instruction that lacks every deterministic signal can fail to enter the Phase 1
+candidate inbox; this is an observation false negative, not a blocked user action.
+The detector intentionally recognizes broad imperative, priority, status, and
+confirmation language, while the dry-run status counters and inbox make recognized
+classification failures visible.
+
+Legacy `TopicMemory` rows whose forwarded state is unknown are excluded from
+authority. That can omit a legitimate historical operator message, but accepting an
+unknown forwarded row would permit quoted third-party content to become authority.
+New ingress persists explicit provenance.
+
+---
+
+## 2. Under-block
+
+No block surface exists. Remaining observation misses include implicit priorities
+without instruction-shaped language, paraphrased completion that the extractor
+cannot ground to an exact authored substring, and active-run focus expressed outside
+the registered condition/goal/task rows. These fail toward missing signal or
+`indeterminate`, never action.
+
+The source-history recovery read is bounded to 500 recent rows. If it reaches the
+bound it returns `complete:false` and performs no partial reconciliation, preventing
+false completeness but leaving the candidate backlog dependent on live intake until
+the source volume is reduced or a later implementation provides pagination.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The deterministic matcher is correctly a low-level detector feeding a durable inbox,
+not an authority. Semantic extraction is correctly delegated to the registered
+`GoalPriorityExtractor` reflector with existing priorities and authored/quoted
+separation. The `AlignmentReviewer` is also a registered reflector and produces only
+a stored observation. Mechanical citation validation sits below the model because
+exact identity, substring, enum, and size checks are enumerable invariants.
+
+The coordinator composes existing `TopicMemory`, `TopicOperatorStore`,
+`AutonomousRunStore`, shared `LlmQueue`, dev-agent gating, and capability routing. It
+does not introduce a parallel operator identity store, run state writer, or general
+workflow engine.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The candidate detector and both model-backed components emit structured evidence.
+They cannot block work, mutate the planner/run file, inject session context, notify
+the operator, or trigger recovery. `dryRun: true` is structural: the reviewer has no
+injection dependency to call even if configuration is accidentally changed.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+The candidate regex is not used at a competing-signals authority point; it only
+admits additional rows into a holding list. Semantic priority meaning and alignment
+remain reflector judgments. Exact sender/forwarded provenance, schema validation,
+idempotency, and two-sided citation grounding are enumerable invariant floors named
+in the driving spec's decision-point table.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the new `onMessageLogged` handler chains the pre-existing callback
+  before enqueueing intake. It does not replace TopicMemory, Presence Proxy, topic
+  intent capture, Usher, or correction learning callbacks.
+- **Independent boot:** initial wiring accidentally sat inside Presence Proxy's
+  initialization scope. Review moved it to its own Telegram/dev-gated boot path and
+  a source-level test pins ordering before `let presenceProxy`.
+- **Double-fire:** live intake and startup history reconciliation can see the same
+  message. The source-derived idempotency key and checkpoint/event IDs collapse both
+  paths to one extraction/event.
+- **Races:** coordinator intake is serialized through `intakeTail`; review awaits the
+  tail and is guarded by `reviewInFlight`. Atomic runtime writes precede event
+  application.
+- **Feedback loops:** reviewer output writes only its own audit/runtime status. It
+  never enters the autonomous state file or message history, so it cannot become its
+  own focus or source evidence.
+- **LLM contention:** both reflectors use the existing shared background queue.
+  Unchanged digest+focus hashes reuse the prior verdict with zero model calls.
+
+---
+
+## 6. External surfaces
+
+- New authenticated pull-only `GET /goal-realignment`; no mutation/action endpoint.
+- `TopicMemory` schema moves from 4 to 5 with one nullable `forwarded` column and a
+  tested automatic migration. Existing unknown values remain safely unknown.
+- New permission-restricted local stores:
+  candidate/checkpoint runtime, append-only priority events, and a scrubbed bounded
+  verdict log. The state registry declares resolution, compliance/archive, and
+  rotating-log retention respectively.
+- Development agents resolve the omitted enable flag live; fleet agents resolve dark.
+- No Telegram/Slack/attention notices, generated URLs, or operator actions are added.
+  Mobile-complete operator actions are therefore not applicable.
+- LLM/provider timing can fail. Failures increment pull-visible counters and leave a
+  recognized candidate pending instead of silently classifying it away.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No dashboard renderer, approval form, grant/revoke page, or other operator action
+surface is touched. The only surface is an authenticated JSON status read, so this
+section is not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN for Phase 1 dry-run observation.** The ledger is local to
+the machine that owns the active autonomous run and has authenticated Telegram
+history. Phase 1 neither speaks nor controls work, so it cannot double-notify or
+create cross-machine authority. `GET /goal-realignment` reports this machine's
+diagnostic state only.
+
+This slice emits no user-facing notices and generates no URLs. Durable rows can stay
+on the original machine if a topic transfers; they are not presented as a pool-wide
+answer, and active transfer delivery is explicitly outside this observation-only
+slice. The full approved design requires router-authoritative source reads,
+owner-fenced replicated correctness metadata, and a transfer freshness barrier
+before any later session-facing behavior is eligible. Phase 1's local evidence does
+not grant that later authority.
+
+---
+
+## 8. Rollback cost
+
+- **Hot-fix release:** disable explicitly with
+  `monitoring.goalRealignment.enabled:false` or revert the code and ship a patch.
+- **Data migration:** the added nullable SQLite column is backward-compatible and
+  need not be removed. New goal-realignment state is isolated under its own directory
+  and log.
+- **Agent state repair:** none required. Keeping the append-only evidence is safer
+  than deleting it; a later re-enable can reuse it.
+- **User visibility:** none during rollback because Phase 1 sends nothing.
+
+---
+
+## Conclusion
+
+The review found and fixed two substantive integration issues before commit: runtime
+wiring was coupled to Presence Proxy, and production checkpoints persisted only a
+re-serialized parsed result instead of exact provider output. It also added explicit
+confirmed-addressed evidence, bounded resolved inbox/checkpoint state, archival
+priority segments, and rotating verdict logs. With those corrections, the change is
+a dev-gated, pull-visible signal producer with no action authority and is clear for
+Tier 2 validation and ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+The change does not touch outbound/inbound blocking, dispatch, session lifecycle,
+recovery, a guard/gate/sentinel/watchdog, or other Phase-5 trigger. Its periodic loop
+computes a bounded observation and cannot actuate.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/goal-realignment-phase1.test.ts`
+- `tests/unit/topic-memory-forwarded-provenance.test.ts`
+- `tests/integration/goal-realignment-routes.test.ts`
+- `docs/specs/reports/periodic-goal-realignment-phase1-validation.md`
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect is being fixed. The cadence-shaped reviewer is not
+an `unbounded-self-action` controller: it does not restart, swap, respawn, spawn,
+notify, retry delivery, re-drive, or kill. Its only self-triggered effect is a
+dry-run observation; unchanged semantic input spends zero calls, overlapping ticks
+singleflight, and provider failure records a counter rather than self-retrying.