instar 1.3.963 → 1.3.965

package/src/data/provenanceCoverage.ts

@@ -237,6 +237,9 @@ export const DP_COMPLETION_CLAIM_VERIFY = 'completion-claim-verify';
 /** Feedback cluster evidence → owned-work readiness judgment. */
 export const DP_FEEDBACK_READINESS = 'feedback-readiness';
 
+/** The stop-justified authority (src/core/UnjustifiedStopGate.ts). */
+export const DP_UNJUSTIFIED_STOP_GATE = 'unjustified-stop-gate';
+
 // ───────────────────────────────────────────────────────────────────────────
 // The census
 // ───────────────────────────────────────────────────────────────────────────
@@ -462,12 +465,36 @@ export const PROVENANCE_COVERAGE: ReadonlyArray<ProvenanceCoverageEntry> = [
       'Should-I-reply verdict over an inbound message; enrollment queued in the ACT-1193 uniform-provenance retrofit backlog.',
   },
   {
-    decisionPoint: 'unjustified-stop-gate',
+    decisionPoint: DP_UNJUSTIFIED_STOP_GATE,
     component: 'UnjustifiedStopGate',
-    status: 'pending:backlog:decision-quality-enrolment',
+    status: 'wired',
+    // The highest-volume UNENROLLED decision point in the census: ~1343 calls
+    // in the last 7 days (GET /metrics/features), second only to the tone gate
+    // among gates. A per-UTC-day COUNT budget rather than `full`: this fires on
+    // every stop attempt across every session, and an always-on gate must not
+    // grow the provenance archive without a hard ceiling. The ~250-byte
+    // decision_quality row is written for every settlement regardless, so the
+    // COUNTS stay complete even when the archive is valved.
+    volumeClass: 'budget:300',
+    // Content-bearing: the gate judges a session's stop rationale. It enters the
+    // row as IDENTITY ONLY — hashes, bounds, and code-derived features — never
+    // the rationale text or any transcript slice.
     contentClass: 'content-bearing',
+    // ── Grading posture ──────────────────────────────────────────────────
+    // MEASUREMENT-ONLY, declared rather than left as a silent gap.
+    gradingPosture: 'measurement-only',
+    gradingReason:
+      'No honest outcome rule exists YET. Grading "was this stop justified?" needs a ' +
+      'downstream fact — did the run resume and do real work after the gate allowed a ' +
+      'stop, or did the agent genuinely have nothing left after the gate held one? Those ' +
+      'signals exist (the resume queue, the autonomous liveness reconciler) but joining ' +
+      'them to a decision row is real plumbing, not a predicate. Enrolling the DECISION ' +
+      'side first is deliberate and is what this posture is for: the rows accumulate now, ' +
+      'so when the outcome join lands there is history to grade instead of a cold start. ' +
+      'Recording without grading is stated here so the census shows it rather than ' +
+      'implying this point is measured when only half of it is.',
     reason:
-      'Stop-justified verdict over session state; enrollment queued in the ACT-1193 uniform-provenance retrofit backlog.',
+      'The stop-justified authority — the highest-volume unenrolled point in the census.',
   },
   {
     decisionPoint: 'coherence-review',

package/src/scaffold/templates.ts

@@ -657,6 +657,11 @@ Two layers keep my machine-to-machine \"ropes\" (Tailscale / LAN / Cloudflare) h
 - Mark delivered when done: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments/:id/deliver\`
 - The PromiseBeacon fires cadenced heartbeats on open commitments so you actually follow through (and surfaces atRisk items), and the commitment-check job surfaces overdue ones.
 - **A promise survives its owning session's death (Escalation, ships dark).** When a beacon-enabled commitment's session dies before delivering, the beacon no longer silently terminalizes it — it escalates: **Rung 1** revives a fresh session bound to the topic to follow through; **Rung 2** sends an honest, state-specific interim status ("my session ended; I'm picking it back up") when it can't revive; **Rung 3** is a bounded loud give-up to the operator's Attention queue. A revived session carries **revivalMode** — every side-effecting external operation is BLOCKED until it revalidates (\`POST /commitments/:id/revalidate\` with a restated current-intent summary), so a revive grants no new authority. \`GET /commitments/:id\` exposes the escalation fields (\`escalationAttempts\`, \`currentRung\`, \`revalidatedAt\`); \`GET /commitments/escalation-metrics\` is the operator-facing aggregate counters. Ships dark + dry-run-first (\`monitoring.promiseBeacon.escalation\`).
+- **A promise with a DATE produces a real reminder (ACT-724 step 1, ships dark).** When you say "I'll check in on this by Friday", set \`checkInAt\` (an absolute ISO instant — resolve "Friday" to a real moment at creation time; never store a bare date) on the commitment. A recurring reconciler then posts EXACTLY ONE fixed-template reminder into that commitment's own topic when the instant arrives, and stops. Delivering or withdrawing the commitment first means no reminder ever fires — teardown is a status check, nothing to cancel.
+  - Read the dated backlog: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments/check-in-reminder\` → \`{ enabled, dryRun, datedCount, pending, undelivered }\`. **\`undelivered\` is the one to look at**: those are promises the user did NOT receive after retries were exhausted.
+  - Run one pass now: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/commitments/check-in-reminder/pass\` (idempotent — a re-run sends nothing).
+  - The guarantee is **at-least-once, deduped at the delivery layer** — not exactly-once. A reminder is marked sent ONLY after it actually sent, so a failed send retries (bounded) instead of being recorded as delivered; the crash-window duplicate is absorbed by the relay's content dedup.
+  - Ships dark (\`commitments.checkInReminder\`, dryRun defaulting TRUE, job \`commitment-checkin-reminder\` enabled:false). **Honest scope:** while the reconciler runs, no dated commitment can slip past it — but nothing yet guarantees the reconciler runs, so "structurally impossible to have a dated promise without a reminder" is NOT true yet. The creation-time gate that closes it is step 2.
 - **When to use** (PROACTIVE — this is the trigger): the moment you promise the user a future action, open a commitment. NEVER improvise the follow-through with a raw \`sleep\`/background timer or by "remembering" — those do not survive a session ending, a restart, or compaction, so the promise is silently dropped. A registered commitment is the ONLY durable path. (This is distinct from the Evolution Action Queue / \`/commit-action\`, which tracks self-improvement items, not promises to the user.)
 - **Action-Claim Follow-Through Sentinel (signal-only, dark by default).** A backstop for the word≠action gap (you say "relaunching now" / "I'll push the change" and then don't). A thin Stop hook posts each finished conversational turn to \`POST /action-claim/observe\`, which classifies a CONCRETE future-action claim (restart/relaunch/push/merge/deploy/fix/…) and opens an idempotent follow-through commitment for the topic — so the existing PromiseBeacon + the revival path make sure it actually happens. High-precision (vague "I'll take a look" never triggers it), de-duplicated by \`externalKey\` (a restated claim updates one commitment, not many), auto-expiring, per-topic capped. It NEVER blocks a message. Off by default; enable with the top-level \`actionClaim.enabled\` (dev-first soak before fleet — the block is top-level, NOT nested under \`messaging\`, which is an array of adapters). It now covers **Slack** conversations too (a promise born in a Slack thread registers a durable commitment bound to the conversation's minted id, delivered back into that exact thread across restarts — dev-gated dark behind \`messaging.actionClaim.slack\`, dryRun-first) and **time-boxed conversational promises** ("I'll post that in about 5 minutes / by EOD / I'll check in"), not just dev-ops verbs. Proactive: user asks "why did a commitment appear when I said I'd restart something / promised to post in 5 min?" → that's this sentinel tracking your stated action so it isn't silently dropped.
 

package/upgrades/1.3.964.md

@@ -0,0 +1,123 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`UnjustifiedStopGate` — the authority that decides whether an agent may stop
+working — is now enrolled in the LLM-Decision Quality Meter.
+
+At ~1343 calls / 7 days it was the **highest-volume unenrolled decision point in
+the census** and the second-busiest gate overall, yet nothing recorded what it
+decided or on what basis. The meter can only answer "is this judgment any good?"
+for points that record; this one didn't, so the question was unanswerable in
+principle.
+
+**What the row carries — identity only.** The gate reads untrusted session
+content (the stop rationale and up to ten recent conversation turns). None of it
+is recorded. The context is an explicit allowlist of derived values:
+
+- `stopReasonSha256` + `stopReasonChars` — distinguishes two rationales without
+  reproducing either
+- `artifactCount` / `artifactKinds` — the evidence the authority could cite
+- `signals` — code-derived booleans (not user text)
+- `recentTurnCount` / `recentTurnChars` — conversation shape only
+
+An allowlist rather than a filtered copy, so a future input field cannot appear
+in the row by default. Tests plant a fake API key and password in the input and
+assert neither reaches the serialized context.
+
+**Declared `measurement-only`, on purpose.** Recording a decision is not grading
+it. Grading this point needs a downstream fact — did work resume after an allowed
+stop; did the agent genuinely continue after a refused one — and joining those
+signals to a decision row is real plumbing. Rather than let `wired` imply more
+than exists, the entry declares `gradingPosture: 'measurement-only'` with an
+argued reason, so `findWiredWithoutGraders` reports it as an explicit posture
+instead of a silent contradiction.
+
+That distinction is the point: the easy version of this change moves a census
+number and leaves a reader believing the busiest judgment call is being
+evaluated. It isn't yet. Rows accumulate now so the grader has history when it
+lands, rather than starting cold.
+
+Volume is valved at `budget:300`/day (an always-on gate must not grow the archive
+unbounded); the `decision_quality` row is written for every settlement regardless,
+so counts stay complete.
+
+Spec clarification for the (unshipped, dark) cross-machine capability registry: `scanState` and row
+presence are INDEPENDENT. A machine with a model manifest and no doorway scan-state now returns
+`scanState: "never-observed"` **together with** its manifest-derived rows at status `unknown`,
+instead of zero rows.
+
+The earlier wording ("`200` with `scanState: never-observed` and empty entries when no observation
+exists") was ambiguous, and the ambiguity produced a real defect: the Increment-2 route derived ten
+rows from the real manifest and served none of them, because "no observation" was read as "no scan".
+Manifest rows ARE observations — the record admits them with `sourceDetail: doorway-manifest`, and
+the status matrix gives `manifest-only` evidence the status `unknown` precisely so documented
+existence is reportable without ever implying reachability.
+
+The rule now carries its failing input: on a machine with a manifest and no scan-state the route
+MUST return rows with status `unknown`; a change that makes it return zero rows must fail a test.
+
+## What to Tell Your User
+
+Nothing changes in how the agent behaves. This is instrumentation on an internal
+judgment — no new messages, no new settings, nothing you interact with.
+
+What it buys: the check that decides whether the agent may stop working is the
+busiest judgment call in the system, and until now nothing recorded what it
+decided. Now it does. So the question "is that check actually any good — too
+strict, too lenient, wrong half the time?" stops being unanswerable and becomes
+answerable once enough history accumulates.
+
+Worth being precise about what is NOT true yet: the decisions are recorded, not
+graded. Knowing whether a given call was *right* needs a later fact (did work
+resume after a stop was allowed?) that isn't connected up yet. The record says so
+explicitly rather than implying the check is being evaluated when only half of
+that is in place.
+
+None of the conversation is stored — only a fingerprint of the stop reason and
+counts describing the decision's shape.
+
+Nothing. This is a design-document correction for a feature that is switched off everywhere, so
+there is no user-visible change to announce. If a user asks why a capability list looked empty on a
+machine that had never run a scan, the honest answer is that it was a specification ambiguity: the
+catalog rows existed and were being discarded, and the corrected rule serves them marked as
+unverified rather than hiding them.
+
+## Summary of New Capabilities
+
+- The stop-justification authority now records every decision it makes, so its
+  quality can be evaluated rather than assumed.
+- Recording is identity-only by construction: an explicit allowlist of derived
+  values, tested against planted secrets, so session content cannot leak into the
+  provenance store.
+- The census now distinguishes "recorded and gradeable" from "recorded but not
+  yet gradeable", so the coverage number reflects what actually exists.
+
+None. This amendment adds no capability — it removes an ambiguity that was silently costing one
+(the ability to see what a machine's catalog claims before anything has probed it).
+
+## Evidence
+
+- `tests/unit/unjustified-stop-gate-provenance-enrollment.test.ts` (11): the
+  census declares it wired with a volume valve and content class; the
+  measurement-only posture carries a real argument; the provenance block names
+  the typed constant with the prompt hash; **planted secrets never reach the
+  context**; the hash distinguishes different rationales (so it isn't a constant);
+  empty input doesn't throw; the verdict is unchanged and `attribution` survives
+  alongside the new block.
+- Census ratchet: pending baseline shrinks by exactly one; typed-registration
+  check independently verifies the source imports `DP_UNJUSTIFIED_STOP_GATE`.
+- 72 green across the affected suites.
+
+Found by running the Increment-2 route's local-projection path against a real agent state dir rather
+than reading the diff: `durable projection ABSENT / fallback readDoorwaySources entries = 10 /
+scanState = never-observed`, and then observing that `classifyProjection` early-returned a single
+`no-data-yet` row, discarding all ten.
+
+## Audience
+
+Agent-only, maturity experimental. No user-visible behavior: the feature is dark everywhere, no
+route ships enabled by this change, and the amendment is spec text only.

package/upgrades/1.3.965.md

@@ -0,0 +1,58 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The dated check-in reminder (shipped in #1630) is now in the agent CLAUDE.md
+template — and reaches EXISTING agents, not just fresh installs.
+
+#1630 shipped routes, a built-in job, and 55 tests, and nothing in the agent
+template. Per the Agent Awareness Standard, "an agent that doesn't know about a
+capability effectively doesn't have it." No agent would have set `checkInAt`, so
+the reconciler would have scanned an empty set every five minutes, found nothing,
+and reported success forever. Working code, passing tests, green health check,
+zero reminders.
+
+**The migration is the substantive half.** The existing Commitments arm is
+guarded by `if (!content.includes('**Commitments & Follow-Through**'))` — every
+running agent already has that section, so anything added inside that branch
+reaches fresh installs ONLY. That is the exact Migration Parity failure the
+standard names, and it looks correct in a diff. The new subsection therefore gets
+its own arm keyed on "section present AND subsection absent", with a test
+asserting that separation rather than trusting it.
+
+A drifted CLAUDE.md gets an append rather than a skip: a misplaced paragraph
+beats an agent permanently unaware of a capability because it customised its own
+notes.
+
+The text states honest scope — dark by default, at-least-once rather than
+exactly-once, and that "structurally impossible to have a dated promise without a
+reminder" is NOT true yet. A briefing that oversells produces an agent
+confidently relying on something that isn't running.
+
+## What to Tell Your User
+
+Nothing changes in behaviour. This is the difference between the reminder
+feature existing and it being usable — without it, no agent would ever know to
+attach a date to a promise, and the feature would have run over an empty list
+indefinitely while looking healthy.
+
+## Summary of New Capabilities
+
+- Agents now know dated commitments produce reminders, which field to set, and
+  which field reveals promises that were never delivered.
+- Existing agents receive it on update, not only new installs.
+- The briefing states what the feature does NOT yet guarantee, so an agent
+  cannot over-rely on a capability that ships switched off.
+
+## Evidence
+
+- `tests/unit/claudemd-check-in-reminder-awareness.test.ts` (10): the template
+  documents the endpoint, names the `checkInAt` field an agent must set, carries
+  a proactive trigger rather than a bare endpoint, states the honest scope, and
+  points at `undelivered`; the migrator arm exists, is SEPARATE from the
+  Commitments arm, is idempotent, records what it did, and appends rather than
+  skipping on drift.
+- `feature-delivery-completeness`: 126 tests green.

package/upgrades/side-effects/enrol-unjustified-stop-gate.md

@@ -0,0 +1,126 @@
+# Side-effects review — enrol-unjustified-stop-gate
+
+**Change:** enrol `UnjustifiedStopGate` into the LLM-Decision Quality Meter
+(`pending:backlog:decision-quality-enrolment` → `wired`), with an identity-only
+provenance context and an explicitly declared `measurement-only` grading posture.
+
+**Why this point:** at ~1343 calls / 7 days (`GET /metrics/features`) it is the
+highest-volume UNENROLLED decision point in the census, and the second-busiest
+gate overall. This is the second half of the run's census task — the half where
+the backlog actually shrinks rather than merely becoming legible.
+
+**Tier:** 1 — one census entry, one context builder, one provenance block. No new
+route, config key, flag, or durable store.
+
+---
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+**Nothing.** Enrollment adds an `options.provenance` block to an existing
+provider call. It introduces no predicate, no branch, and no rejection path. The
+gate's continue/allow/escalate verdict is computed exactly as before — asserted
+directly by a test rather than argued.
+
+The one build-time narrowing: the census ratchet now requires this point to stay
+declared. Removing the enrollment without updating the census fails CI, which is
+the intent.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **It records decisions; it does not grade them.** This is the honest half and
+  is declared as `gradingPosture: 'measurement-only'` with a ≥40-char argument,
+  so `findWiredWithoutGraders` reports it as an explicit posture rather than a
+  silent contradiction. **The census number improves and the point is still not
+  measured end-to-end** — anyone reading "wired" without reading the posture will
+  overestimate what exists. That is why the posture is declared, tested, and
+  stated in the release note.
+- **Volume is capped at `budget:300`/day.** A day with more than 300 stop
+  decisions archives the first 300; the `decision_quality` row is still written
+  for every settlement, so counts stay complete while the archive is valved. A
+  loud `droppedByBudget` counter surfaces the truncation.
+- **The context is a fixed projection.** If a future reader needs a field I did
+  not include, the history will not have it retroactively. I chose the minimum
+  that reconstructs decision shape; widening later is additive but not backfillable.
+
+## 3. Level-of-abstraction fit
+
+The context builder is a private method on the gate, because only the gate knows
+which of its inputs are trusted evidence and which are untrusted session text.
+Building it anywhere else would require exporting that distinction — and a
+downstream builder that guesses wrong is precisely how a transcript ends up in
+a provenance store.
+
+The provenance block rides the existing `options` argument alongside
+`attribution`, so enrollment adds a signal rather than displacing one (tested).
+
+## 4. Signal vs authority compliance
+
+`docs/signal-vs-authority.md`. Enrollment holds **no authority at all** — it is
+pure observability. The settlement seam consumes the block and records on its own
+path; it never reaches the model and never alters the verdict.
+
+The gate itself remains what it was: an LLM authority with a deterministic
+fail-open contract. This change deliberately does not touch that.
+
+**The content-bearing contract is the safety property here**, and it is enforced
+by test rather than by care: the fixtures plant a fake API key and a fake
+password in the untrusted input, and the tests assert neither appears anywhere in
+the serialized context. A hash-distinctness test prevents a constant or empty
+hash from making the identity field useless while still passing the leak tests.
+
+## 5. Interactions
+
+- **`/metrics/features`** — unchanged; `attribution.component` is preserved
+  (explicitly tested, because losing it would silently drop this component from
+  the cost surface).
+- **The census ratchet** — the pending baseline shrinks by exactly one line, which
+  is the direction it is allowed to move. The typed-registration check
+  independently verifies the enrolling source imports `DP_UNJUSTIFIED_STOP_GATE`
+  rather than restating the string.
+- **The breaker / fail-open path** — untouched. A provenance write failure is
+  contained by the recorder's own fail-open contract, so it cannot convert into a
+  stop-decision failure.
+- **The prompt hash** — reused as `promptId`, so a row records WHICH prompt
+  decided. The gate already computed it; nothing new is derived.
+
+## 6. External surfaces
+
+- No route, config key, flag, env var, CLI, message, or notification.
+- `GET /decision-quality` will show one more `wired` point and one fewer
+  `pending`. Field shapes unchanged.
+- No user-visible behaviour whatsoever.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Unified.** The census is a shipped source constant, byte-identical on every
+install, so every machine enrolls the same point with the same volume valve and
+content class. The provenance rows themselves inherit the meter's existing
+posture — this change adds no new state surface, no notice, and no generated URL.
+
+## 8. Rollback cost
+
+Revert. The census entry returns to `pending:` (restoring the baseline line), the
+provenance block disappears, and previously-recorded rows remain inertly in the
+store — harmless, and still readable if the enrollment returns.
+
+## Second-pass review
+
+**Not required** by the Phase-5 trigger list: enrollment makes no block/allow
+decision, touches no session lifecycle, and adds no gate. The gate it observes is
+unchanged.
+
+Self-review, recorded rather than skipped:
+
+1. **Is this the honest version or the number-improving version?** The
+   temptation was real: flipping `pending` → `wired` shrinks census debt whether
+   or not anything can be graded. I took the declared `measurement-only` path
+   because the census distinguishes it and `findWiredWithoutGraders` surfaces it
+   — the gap stays visible instead of being absorbed into a better-looking
+   number. If that posture did not exist I would not have shipped this as-is.
+2. **Could the untrusted text leak by a route I did not consider?** The context is
+   an explicit allowlist of derived values, not a filtered copy of the input, so
+   a new input field cannot appear in the row by default. The leak tests assert
+   absence of planted secrets rather than presence of expected keys, which is the
+   direction that catches accidental widening.
+
+Tests: 11 new unit tests; 72 green across the affected suites.

package/upgrades/side-effects/reminder-agent-awareness.md

@@ -0,0 +1,124 @@
+# Side-effects review — reminder-agent-awareness
+
+**Change:** add the dated check-in reminder (ACT-724 step 1, merged in #1630) to
+the agent CLAUDE.md template, with a SEPARATE `PostUpdateMigrator` arm so
+existing agents receive it, plus tests pinning both halves.
+
+**Why:** #1630 shipped routes, a job, and 55 tests — and nothing in the agent
+template. Per the Agent Awareness Standard, "an agent that doesn't know about a
+capability effectively doesn't have it." No agent would ever set `checkInAt`, so
+the reconciler would scan an empty set forever and report success doing it.
+
+**Tier:** 1 — template text, one migration arm, tests. No runtime behaviour.
+
+---
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+Nothing. This adds documentation and one idempotent migration branch. No
+predicate, no gate, no rejection path.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **The Agent Awareness Standard remains unenforced in general.** This change
+  gates THIS capability; the next feature can still ship template-less and no
+  test will notice. That is the real defect and it is bigger than this PR — the
+  standard is prose with no structure behind it, which is precisely why I missed
+  it while shipping a feature about not relying on memory. Recorded rather than
+  quietly fixed for one case and forgotten.
+- **Drifted CLAUDE.md files get an append, not a placement.** If an agent
+  customised the section wording, the marker won't match and the subsection is
+  appended near the block instead of at the intended point. Deliberate: a
+  misplaced paragraph beats a permanently unaware agent.
+- **The template text can still drift from the shipped routes.** Nothing
+  cross-checks the documented curl against the real route path. A rename would
+  leave the briefing confidently wrong.
+
+## 3. Level-of-abstraction fit
+
+Right layer, and the migration arm placement is the substantive decision.
+
+The existing Commitments arm is guarded by
+`if (!content.includes('**Commitments & Follow-Through**'))`. Adding the
+subsection inside that branch would reach FRESH INSTALLS ONLY — every currently
+running agent already has that section and never re-enters the branch. That is
+the exact Migration Parity failure mode the standard names, and it looks
+completely correct in a diff.
+
+Hence a separate arm keyed on "section present AND subsection absent", with a
+test asserting that separation rather than trusting it.
+
+## 4. Signal vs authority compliance
+
+`docs/signal-vs-authority.md`. No authority: documentation plus an idempotent
+text patch. The migration decides only whether text is already present — a
+`String.includes` check at a dev/update chokepoint, not a runtime judgment.
+
+## 5. Interactions
+
+- **The Commitments migration arm** — untouched; the new arm runs after it and
+  is reachable in the state the old arm skips.
+- **Shadow-capability slicing** — the subsection sits INSIDE the existing
+  Commitments block rather than creating a new top-level marker, so the slicer's
+  boundaries are unchanged.
+- **`feature-delivery-completeness`** — passes (126 tests); this change adds
+  awareness for a feature that suite already tracks.
+
+## 6. External surfaces
+
+- **The agent-facing CLAUDE.md gains one subsection.** That IS the point: it is
+  the surface through which an agent discovers the capability.
+- No route, config key, flag, env var, or runtime behaviour.
+- The text states the honest scope — dark by default, at-least-once (not
+  exactly-once), and that "structurally impossible to have a dated promise
+  without a reminder" is NOT yet true. A briefing that oversells produces an
+  agent confidently relying on something that isn't running.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Unified.** The template is a shipped source constant and the migration runs
+per-machine against each machine's own CLAUDE.md, producing identical text
+everywhere. No new state, no notice, no generated URL, nothing to strand on a
+topic transfer.
+
+## 8. Rollback cost
+
+Revert. Agents that already received the subsection keep harmless extra
+documentation; the idempotency check means a re-run after revert re-adds it
+rather than duplicating.
+
+## Second-pass review
+
+**Not required** — no block/allow decision, no session lifecycle, no gate.
+
+Self-review, the one thing I went looking for: **did I put the migration where it
+would actually run?** I nearly appended to the Commitments arm, which would have
+been invisible in review and would have reached zero existing agents. The test
+`that arm is SEPARATE from the Commitments-section arm` exists specifically
+because I caught myself about to do the wrong thing, and a comment saying "don't
+do that" would not have survived the next edit.
+
+
+## Addendum — the migration emitted a literal placeholder
+
+CI rejected the first version, correctly.
+
+The subsection's example commands carry the agent's port, which the surrounding
+template literal interpolates. I authored the section inside a shell heredoc and
+escaped the interpolation so the shell would not consume it — and the escape
+survived into the TypeScript. A patched CLAUDE.md would therefore have contained
+the literal placeholder text instead of a port number, making **every curl
+example in the new section copy-paste-broken**, in the one document agents rely
+on to know how to call things.
+
+Caught by `tests/unit/PostUpdateMigrator-coordinationAwareness.test.ts`, which
+asserts no literal placeholder survives into a patched file. That guard exists
+because this has happened before; it earned its keep.
+
+**The generalizable bit:** authoring template-literal content through a shell
+heredoc puts two escaping regimes in series, and the second one is invisible in
+the diff — the TypeScript looks correct in isolation. Worth writing such content
+with a file-write tool rather than a heredoc when it contains interpolations.
+
+Side effects of the fix: none beyond the corrected string. No test was weakened;
+the existing guard is what caught it.

package/upgrades/side-effects/spec-round10-manifest-rows.md

@@ -0,0 +1,13 @@
+# Side effects — spec round 10 (scanState vs row presence)
+
+- **No code changes in this PR.** Spec text only; the feature is dark on every install.
+- **Downstream obligation created:** the Increment-2 route (merged behavior) currently returns zero
+  rows on a machine that has never scanned. Once this amendment lands, that behavior contradicts the
+  spec and must be fixed — tracked for Increment 3, with the failing input stated in the spec so the
+  fix is verifiable rather than asserted.
+- **Risk if NOT amended:** on any machine whose doorway-scan job is disabled (the shipped default),
+  the read surface would report nothing while holding a catalog it had already derived — the exact
+  "empty reads as unknown" conflation the three-way `scanState` exists to prevent.
+- **Rollback:** revert the spec paragraph; no deployed behavior changes either way.
+- **Provenance note:** this ambiguity was mine as the converging reviewer, not a build defect — the
+  implementation followed the spec as written. Recorded so the review history stays honest.