instar 1.3.962 → 1.3.964

package/src/scaffold/templates/jobs/instar/commitment-checkin-reminder.md

@@ -0,0 +1,38 @@
+---
+name: Commitment Check-In Reminder
+description: "Drives ONE check-in reminder pass (ACT-724; docs/specs/dated-commitment-reminder.md). Calls POST /commitments/check-in-reminder/pass: the server scans open commitments whose `checkInAt` has arrived and posts exactly one fixed-template reminder each to the commitment's own topic. Idempotent — the `checkInReminderSentAt` stamp is written only AFTER a successful send, so a re-run, a retried trigger, or two passes racing cannot double-send, and a failed send is retried (bounded) rather than silently marked delivered. Tier-0 supervision is JUSTIFIED: the pass is a deterministic predicate over durable state plus a fixed-template send — there is no LLM step for a supervisor to validate, and the endpoint's own idempotency and per-pass cap already bound it. Ships enabled:false (dark; the feature itself is dev-agent gated and dryRun-first). This job NEVER authors prose — the reminder text is code-generated and the job's own output is mechanical."
+schedule: "*/5 * * * *"
+priority: medium
+expectedDurationMinutes: 1
+supervision: tier0
+enabled: false
+tags:
+  - cat:commitments
+  - check-in-reminder
+  - role:worker
+gate: curl -sf http://localhost:${INSTAR_PORT:-4042}/health >/dev/null 2>&1
+toolAllowlist: "*"
+unrestrictedTools: true
+mcpAccess: none
+---
+Trigger one commitment check-in reminder pass. This is a mechanical cadence job — do NOT message the user yourself. The reminder message is composed and delivered server-side from a fixed template; your job is only to fire the pass and report the counts.
+
+AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
+PORT="${INSTAR_PORT:-4042}"
+
+curl -sS -m 60 -X POST \
+  -H "Authorization: Bearer $AUTH" \
+  -H "X-Instar-AgentId: $AGENT_ID" \
+  -H 'Content-Type: application/json' \
+  -d '{}' \
+  "http://localhost:${PORT}/commitments/check-in-reminder/pass"
+
+Interpreting the response:
+
+- `503 check-in-reminder-not-enabled` — the feature is dark on this agent. Expected on the fleet. Nothing to do, nothing to report.
+- `{"ran":true,"dryRun":true,"wouldSend":N}` — soak mode. The pass decided what it WOULD send and sent nothing. Normal during the dark window.
+- `{"ran":true,"sent":N}` — N reminders delivered.
+- `"gaveUp":N` greater than zero — N reminders are genuinely UNDELIVERED after exhausting retries. This is the one outcome worth surfacing: read `GET /commitments/check-in-reminder` for the `undelivered` list. Those are promises the user did not receive.
+
+Do not retry the pass yourself on a non-zero `failed` count — the next scheduled pass retries automatically, bounded, and the endpoint is idempotent.

package/upgrades/1.3.963.md

@@ -0,0 +1,135 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A commitment can now carry a **check-in date**, and a background reconciler
+posts one reminder into that commitment's own topic when the date arrives.
+
+Before this, "I'll report back by Friday" lived in the session that said it. If
+that session ended, restarted, or compacted, Friday arrived and nothing
+happened. The PromiseBeacon nudges on *rhythm*, not on dates — it has no concept
+of a specific promised moment.
+
+**What ships (ACT-724 step 1 of 2):**
+
+- `Commitment.checkInAt` — an absolute instant, deliberately separate from the
+  beacon's `nextUpdateDueAt` / `softDeadlineAt` so a one-time dated reminder and
+  a rolling nudge cadence are not side effects of each other.
+- `CheckInReminderReconciler` — a scan over open commitments, driven by the new
+  `commitment-checkin-reminder` built-in job (every 5 minutes, `enabled: false`).
+- `POST /commitments/check-in-reminder/pass` and `GET /commitments/check-in-reminder`.
+
+**One recurring scan, not one alarm per commitment.** ACT-724 sketched a
+per-commitment scheduler entry; taken literally that reproduces two of the three
+defects the action itself lists — the two-file job dance (defect b) and
+self-disable by file edit (defect c). A scan has neither: coverage is a property
+of the scan, so there is no registration step that can be skipped, and teardown
+is just the commitment reaching a terminal status.
+
+**The ordering was wrong first, and the fix's own justification was unwired.**
+The first design stamped `checkInReminderSentAt` *before* sending — which made
+zero delivery a designed outcome, since a failed send left the commitment marked
+delivered and permanently ineligible. Inverted to send-then-stamp with bounded
+retry (5 attempts, then a loud `checkInReminderFailedAt`). The second review
+round then caught that the duplicate mitigation justifying that inversion —
+"the relay dedups" — was not connected: `sendToTopic` does not dedup, that lives
+in the `/telegram/reply` route. The send is now explicitly routed through the
+same durably-backed `OutboundContentDedup`.
+
+**Honest guarantee: at-least-once, deduped at the delivery layer** — not
+exactly-once. Both remaining windows are stated in the spec rather than designed
+away.
+
+A newly created scheduled job fired immediately on the next server restart —
+including one scheduled months ahead.
+
+At startup the scheduler sweeps for work that was missed while the machine was
+off. To decide, it compares now against the job's last run. For a job that has
+**never** run there is no last run, and the code resolved that case by treating
+it as overdue and triggering it. That is right for a job added while the server
+was down that slept through its window, and wrong for a job created minutes ago
+whose first window is in December — "has never run" describes both identically.
+
+The comment directly above that branch stated the correct rule —
+
+> *"Jobs that have never run: trigger on startup if their first expected run
+> time has already passed"*
+
+— and the code never checked the condition. It couldn't: nothing recorded when a
+job started existing, so there was no fact to reason from.
+
+`JobState.firstSeenAt` is now stamped once at registration, and the sweep applies
+the intended rule: a never-run job is missed only if it has existed longer than
+one of its own intervals. A December reminder created today waits; a job that has
+sat unrun through six four-hour windows still catches up.
+
+Every unknown resolves to **not firing** — missing or unparseable `firstSeenAt`,
+uncomputable interval. That asymmetry is deliberate: a skipped catch-up costs one
+delayed run, while a future-dated job that fires early marks itself delivered and
+never fires again, so nobody goes looking for it.
+
+**Why now:** this is the prerequisite for dated commitments materializing real
+scheduled reminders (ACT-724). A reminder built on a scheduler that fires
+future-dated jobs at boot would discharge itself before its date — worse than
+never having built it. The standard itself is not in this change.
+
+## What to Tell Your User
+
+Nothing changes until it's switched on. When it is: on the day the agent said it
+would check in on something, you get one short message in that conversation
+saying the date has arrived.
+
+It will not claim the work is done — a reminder that implies completion closes
+the question instead of reopening it.
+
+**Not yet true:** ACT-724 asks that a dated commitment without a reminder be
+structurally impossible. This ships dark, and a disabled watcher guarantees
+nothing. What is true today: if the reconciler is running, no dated commitment
+can slip past it individually. The creation-time gate that closes the rest is
+step 2, and it cannot itself ship dark.
+
+If you've ever seen a scheduled job run for no obvious reason shortly after a
+restart, this was probably it.
+
+The practical effect: reminders and scheduled work now happen when they're
+scheduled, not when the server next happens to reboot. A job that's been waiting
+less than one of its own cycles will now wait for its proper turn rather than
+firing at startup — that delay is the point.
+
+## Summary of New Capabilities
+
+- Commitments carry a first-class check-in date that produces a real reminder.
+- A reminder is never recorded as delivered unless it actually was; failures
+  retry and then give up visibly.
+- Two read/drive endpoints and a built-in job, all dark by default.
+
+- Scheduled jobs with a future first window are no longer discharged at server
+  startup.
+- Job state records when a job was first registered, so "brand new" and "long
+  overdue" are distinguishable facts rather than a guess.
+- The startup sweep fails toward not-running on every uncertainty.
+
+## Evidence
+
+- Tier 1 (41): the full eligibility predicate on both sides of every clause;
+  idempotency across repeated passes; **a failed send never reads as sent** (the
+  regression test for the round-1 finding); bounded retry to a loud terminal
+  state; per-pass cap deferring rather than dropping; the reminder text never
+  asserting completion.
+- Tier 2 (10): real Express routes + auth — delivery, HTTP-boundary idempotency,
+  dark 503, missing-transport 503, and `dryRun` defaulting ON when config omits it.
+- Tier 3 (4): real `AgentServer` boot with a real injected `CommitmentTracker`.
+
+- `tests/unit/job-scheduler-never-run-future-job.test.ts` (3 cases): a never-run
+  annual job and a freshly-registered daily job both stay at zero triggers; a job
+  registered 6h ago on a 5-minute cron still catches up. Written failing first —
+  the two "must not fire" cases failed against the old code, the catch-up case
+  already passed.
+- `tests/unit/job-scheduler-edge.test.ts`: the existing test that asserted the
+  buggy behaviour was **updated, not deleted** — it now seeds `firstSeenAt` in the
+  past so it exercises the scenario it was written for (a job that genuinely
+  missed windows), plus a new sibling pinning the other side of the boundary.
+- Full scheduler suite: 76 tests across 8 files, green.

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/side-effects/dated-commitment-reminder.md

@@ -0,0 +1,240 @@
+# Side-effects review — dated-commitment-reminder
+
+**Change:** commitments gain a first-class `checkInAt`; a recurring reconciler
+posts exactly one fixed-template reminder to the commitment's topic when that
+instant arrives; a built-in job drives it. ACT-724 (critical, pinned).
+
+**Spec:** `docs/specs/dated-commitment-reminder.md` (2 review rounds; round 1
+returned SERIOUS ISSUES and inverted the send/stamp ordering).
+
+**Ships dark:** dev-agent gated + `dryRun` defaulting true + job manifest
+`enabled: false`.
+
+---
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+- **A dated commitment with no `topicId` is never reminded** (`no-topic`). A
+  reminder with nowhere to go is not a reminder; it is reported as a skip reason
+  rather than silently dropped, and appears in the `pending` list.
+- **An unparseable `checkInAt` fails closed.** Deliberate: coercing it would make
+  the commitment look overdue since epoch and fire immediately — the exact
+  boot-fire shape fixed in `scheduler-never-run-window` days earlier.
+- **A pass is capped at 25.** An overdue backlog drains across passes rather than
+  flooding a topic. The cap logs when it drops work, so a truncated pass is never
+  reported as a complete one.
+- **Only `pending` counts as open.** A status added later is treated as not-open
+  (no reminder) until classified deliberately. Safe direction, but it does mean a
+  future status would silently stop reminders until someone adds it to the set.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **"Structurally impossible" is not yet true.** ACT-724 asks that a dated
+  commitment without a reminder be impossible. Shipping dark means the watcher
+  can be off, so a dated commitment CAN exist with nothing watching. What IS
+  structural today: given the reconciler runs, no individual commitment can be
+  missed (coverage is a property of the scan, not of a per-commitment
+  registration). The creation-time gate that closes the rest is the declared
+  graduation step, and it cannot itself ship dark. Called out because the spec's
+  own framing over-claimed until review pushed back.
+- **A duplicate is possible in one narrow window** — crash between send and
+  stamp. Accepted, and mitigated by the relay's existing content dedup rather
+  than by design novelty. Stated plainly instead of claimed away.
+- **Clock jumps** shift a reminder in time (late on a backwards jump, early on a
+  forwards one) but cannot double-send or permanently suppress.
+- **No escalation if a reminder is ignored.** Out of scope: this delivers the
+  date, it does not chase. The beacon owns chasing.
+
+## 3. Level-of-abstraction fit
+
+The decision (`isCheckInReminderDue`) is pure and lives in
+`checkInReminderCore.ts`; the effects (CAS, send, retry) live in the reconciler;
+the cadence lives in a built-in job. That split is what let both sides of every
+clause be tested without a store, a clock, or a transport.
+
+**The alternative I rejected is the more standard one.** A transactional outbox
+(`reminder_deliveries` with pending/sent/failed) is the textbook answer and is
+genuinely better at volume. Rejected here because the commitment record already
+IS durable single-writer state: a second store would add a consistency boundary
+— a new class of divergence bug — to serve tens of commitments. The fields on the
+commitment are a degenerate outbox with exactly one row per commitment. If volume
+ever justifies it, the migration is mechanical.
+
+## 4. Signal vs authority compliance
+
+`docs/signal-vs-authority.md`. Both decision points are `invariant`:
+
+- **The due predicate** is arithmetic over durable state (open ∧ date arrived ∧
+  unstamped ∧ routed ∧ retries remain). No competing signals, nothing to weigh.
+  The failure being fixed was an ABSENT mechanism, not a bad judgment.
+- **The reminder text** is a fixed template, deliberately not model-authored.
+  Generating it would add a judgment where none is wanted and a failure mode
+  (provider down) on a path whose entire purpose is to not fail.
+
+**Deliberate gate bypass, argued:** the reminder rides the deterministic delivery
+path, not the LLM tone gate. The tone gate fails closed, and a reminder that can
+be held by a failing gate is the defect this feature exists to fix. This is not
+weakening a safety control — the control is inapplicable, because the message
+carries no agent prose for it to judge. Nothing model-generated reaches the user
+through this path.
+
+## 5. Interactions
+
+- **PromiseBeacon** — untouched. `checkInAt` is a NEW field precisely so beacon
+  cadence (`nextUpdateDueAt`, `softDeadlineAt`) is not overloaded; a one-time
+  dated reminder and a rolling nudge cadence stay independent.
+- **`CommitmentTracker.mutate`** — the existing single-writer CAS is reused, not
+  replaced. Two passes racing cannot double-stamp.
+- **The relay's content dedup** (`outboundContentDedup`) — now load-bearing for
+  this feature's duplicate story. Documented in both the spec and the reconciler
+  so a future change to that window is understood to affect this.
+- **The scheduler** — this is why `scheduler-never-run-window` shipped first. A
+  reminder job on the old scheduler would have fired at boot.
+- **`installBuiltinJobs`** — writes both `jobs/instar` and `jobs/schedule` for
+  built-ins, which is exactly why ACT-724's defect (b) (the two-file dance) does
+  not apply: that dance is only manual for USER jobs.
+
+## 6. External surfaces
+
+- **New:** `POST /commitments/check-in-reminder/pass`, `GET
+  /commitments/check-in-reminder`. Both Bearer-authed, both 503 when dark.
+- **New built-in job** `commitment-checkin-reminder`, `enabled: false`.
+- **New commitment fields** — additive and optional; existing records load
+  unchanged, no migration.
+- **User-visible:** one message per dated commitment, at its date, in its own
+  topic. Fixed template. The only user-facing text this change introduces.
+- **A transport is required only to SEND.** A dry run needs none — surfaced by
+  the Tier-3 test, which would otherwise have reported the feature dead on an
+  agent with no messaging configured.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Unified, with a single-executor rule.**
+
+- `checkInAt` / `checkInReminderSentAt` / `checkInReminderAttempts` /
+  `checkInReminderFailedAt` live on the commitment record and inherit the
+  commitment store's existing posture. No new state surface.
+- **The pass must run on ONE machine.** The built-in job is per-machine (each
+  machine runs its own scheduler), so on a pool the pass must be lease-gated the
+  way the benchmark-divergence analysis pass is. Belt-and-braces: even if two
+  ran, the CAS stamp makes the second a no-op — the lease prevents wasted work,
+  the CAS prevents the duplicate.
+- **HONEST GAP:** the lease gate is specified in §Multi-machine posture but the
+  job ships `enabled: false`, so it is not yet wired in this change. Enabling the
+  job on a multi-machine pool BEFORE adding the lease check would risk two
+  machines both passing — the CAS still prevents a duplicate reminder, but the
+  work would be duplicated. Recorded as a precondition of enabling, not as done.
+- No notice routing, no generated URL, nothing that strands on topic transfer.
+
+## 8. Rollback cost
+
+Disable `commitments.checkInReminder` or the job manifest. The reconciler is the
+only reader of these fields; commitments keep them inertly. No migration, no
+durable cleanup, no agent-state repair. Reverting the commit is equally safe.
+
+## Second-pass review
+
+**Required** — this sends messages to users (outbound messaging is on the Phase-5
+trigger list).
+
+Two rounds of external cross-model review, the first of which returned **SERIOUS
+ISSUES** and changed the design:
+
+1. **Stamp-before-send made zero delivery a designed outcome.** A failed send
+   left the commitment marked `checkInReminderSentAt` and permanently
+   ineligible. Inverted to send-then-stamp with bounded retry; the duplicate risk
+   is covered by the relay's existing dedup. A regression test asserts a failed
+   send never reads as sent.
+2. **"Structurally impossible" over-claimed** for a feature behind a disableable
+   flag. Split into what is true now versus at graduation.
+3. **Time semantics under-specified** — `checkInAt` is now defined as an absolute
+   instant with normalization at the creation boundary, and DST/clock-jump
+   behaviour is stated.
+4. **Cadence and scale omitted** — 5-minute cadence, worst-case lateness, the
+   in-memory store's actual size, per-pass cap and backlog drain are now stated.
+5. **Alternatives not compared** — outbox, durable queue, one-shot entries, and
+   per-commitment scheduler entries are now compared with reasons.
+
+Self-review found one thing the reviewer did not: the Tier-3 test initially
+asserted that `AgentServer` self-constructs the `CommitmentTracker`. It does
+not — `server.ts` injects it — so the routes 503'd on the real boot path while
+Tier 2 passed happily against a hand-assembled context. That is exactly the
+wiring assumption Tier 3 exists to break, and the test now mirrors the
+production entrypoint. It also surfaced the dry-run/transport coupling in §6.
+
+Tests: 41 unit + 10 integration + 4 e2e = 55.
+
+
+## Class-Closure Declaration
+
+**Class:** `unbounded-self-action` · **Closure:** `guard` · **Enforcement:** ratchet
+**Citation:** `tests/unit/self-action-convergence.test.ts`
+
+This change adds a self-triggered controller: a cadenced pass that SENDS
+messages to users without a human in the loop. Under the "Capacity Safety — No
+Unbounded Self-Action" standard that has to be proven to CONVERGE under
+sustained pressure, not merely be individually correct.
+
+Registered as `check-in-reminder-pass` in `src/testing/selfActionRegistry.ts`.
+
+**Steady-state bound.** The emit is gated by a durable per-commitment attempt
+counter (`CHECK_IN_MAX_ATTEMPTS = 5`), persisted through the CAS `mutate()`
+BEFORE the send — so a crash-loop cannot buy fresh attempts, and the registry's
+restart model (which reconstructs from durable state) settles at the same bound.
+
+**Settling brake.** Two terminal states, both durable: a successful send writes
+`checkInReminderSentAt`, making the commitment permanently ineligible; repeated
+failure exhausts the counter and writes a loud `checkInReminderFailedAt`.
+
+**Modeled at the worst case.** The registry model has every send FAIL, so the
+success stamp never lands and only the attempt counter can stop it. Without that
+counter the model emits once per tick forever and the ratchet fails — which is
+the point: the bound is load-bearing, not decorative.
+
+**Instantaneous mass** is separately bounded by the per-pass cap (25), which logs
+when it defers rather than dropping silently.
+
+
+---
+
+## Addendum — three CI gates, and a coverage gap they led me to
+
+**1. Write-domain classification.** `POST /commitments/check-in-reminder/pass`
+mutates the commitment store and was undeclared. Classified `cluster-shared` in
+`WriteDomainRegistry`, matching the requirement that the pass run on the
+serving-lease holder only — the same single-writer shape as the feedback-factory
+routes. This does NOT weaken the honest gap in section 7: the lease gate is still
+not wired, and the classification records the intended posture rather than
+asserting the wiring exists.
+
+**2. Agent-id header.** The job's curl shipped Bearer-only; I dropped the
+AGENT_ID line when adapting the template I copied from. Restored. Worth noting
+as a pattern: adapting a template is where declared requirements silently fall
+out.
+
+**3. Docs coverage.** Job coverage fell 85% to 83% because the new built-in job
+was undocumented. Added to the default-jobs reference. That floor caught a real
+Agent-Awareness omission, not a bureaucratic one — an undocumented job is one no
+operator can discover.
+
+**And the thing worth more than all three: a coverage gap in the tone-gate suite.**
+
+While dogfooding I hit a live advisory I could not override — four attempts,
+byte-identical text, matching rule, sufficient reason, refused every time. That
+is the RELEASING half of the advisory migration failing in production.
+
+Investigating: every existing test in the advisory-migration integration file
+pins ONE verdict for the whole run via a fixed mock, so the rule is constant by
+construction and an ack always matches. The live gate RE-REVIEWS on every attempt
+and can return a different rule — mine went B20_INTERNAL_ID_LEAK then
+B11_STYLE_MISMATCH. That variability was not covered at all.
+
+Two tests added: (a) re-review returns the SAME acked rule, ack honored, message
+sent; (b) re-review returns a DIFFERENT rule, the stale ack is refused rather
+than silently passing an objection nobody reviewed.
+
+BOTH PASS, which exonerates the ack mechanism and kills my working hypothesis. I
+therefore have a reproducible symptom and NO diagnosis, and I am shipping the
+closed coverage gap rather than a guess dressed as a fix. The evidence and the
+candidates I have not ruled out are in the run log; the four tone-gate tracking
+actions stay OPEN because the releasing half is unproven in production.

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.