instar 1.3.830 → 1.3.832

package/src/scaffold/templates/jobs/instar/llm-decision-grading.md

@@ -0,0 +1,32 @@
+---
+name: LLM-Decision Grading Pass
+description: "Hourly deterministic grading pass over the LLM-decision quality substrate. Runs POST /decision-quality/grade-pass: the endpoint walks NEW outcome evidence since the durable per-decision-point cursor (keyset (ts, correlation_id) — same-ms bursts cannot skip rows), applies the registered deterministic evidence rules, and upserts right/wrong/unknown grades idempotently (re-runs converge, never multiply; bounded per pass by provenance.quality.maxDecisionsPerPass). ZERO LLM spend in the pass itself — the grading ladder in this build is deterministic-only (FD11; the LLM evidence-interpreter rung ships NO code, ACT-1198). Ships enabled:false (cost-bearing job class); the operator read surface is GET /decision-quality. NEVER messages the user (FD5 — the meter is observe-only; grading produces rows, not messages). Runs per machine over that machine's local rows (the ratified machine-local data posture). Tier-1 supervised (this haiku job wraps the deterministic endpoint and sanity-checks the response shape). Spec docs/specs/llm-decision-quality-meter.md §5.5."
+schedule: "0 * * * *"
+priority: low
+expectedDurationMinutes: 2
+model: haiku
+supervision: tier1
+enabled: false
+tags:
+  - cat:observability
+  - decision-quality
+  - role:worker
+gate: curl -sf http://localhost:${INSTAR_PORT:-4042}/health >/dev/null 2>&1
+toolAllowlist: "*"
+unrestrictedTools: true
+mcpAccess: none
+perMachineIndependent: true
+---
+Run one deterministic LLM-decision grading pass. This is a mechanical, near-silent cadence job — do NOT message the user (FD5: the quality meter is observe-only; grading writes grade rows, never messages, and never interprets the grades — interpretation belongs to the operator's read of GET /decision-quality). It exists because outcome evidence accrues continuously, but nothing grades it without a production trigger; this job IS that trigger on the hourly cadence the evidence windows are derived from.
+
+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}"
+
+1. Trigger one grading pass:
+   `curl -s -X POST -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" -H "Content-Type: application/json" -d '{}' http://localhost:$PORT/decision-quality/grade-pass`
+   The body is `{}` on purpose — every knob (pass bound, evidence windows, retention) comes from config, never from this job. A 503 means the quality substrate is dark for this agent (`provenance.uniformSeam` resolves off) — exit silently, there is nothing to do. On 200 the response is `{ graded, byRule, cursors }` where `cursors` maps decisionPoint → the advanced boundary. The endpoint does ALL the deterministic work: durable-cursor keyset walk, bounded per pass, idempotent grade upserts, P19 backoff on a stuck rule.
+
+2. **Tier-1 supervision (your job).** Sanity-check the response shape before concluding: `graded` should be a number ≥ 0, `byRule` an object, and `cursors` an object (possibly empty — an idle pass is healthy, not an error). If the response is malformed or the curl fails, do NOT retry-flood — note it once and exit; the next hourly tick re-attempts, and re-runs converge by the endpoint's idempotency.
+
+3. Exit silently. This job is just the cadence — it produces grade rows, not user messages. Do NOT relay anything to Telegram, do NOT summarize, and do NOT interpret or act on the grades yourself.

package/src/scaffold/templates.ts

@@ -14,7 +14,7 @@
 // existing-agent migration there) so the two can never drift. Imported as a runtime
 // function call inside generateClaudeMd — no module-init cycle (PostUpdateMigrator
 // never imports templates).
-import { SESSION_LISTING_HYGIENE_CLAUDEMD_SECTION, PLAYWRIGHT_PROFILE_REGISTRY_CLAUDEMD_SECTION, MACHINE_LOAD_ASSESSMENT_CLAUDEMD_SECTION, DYNAMIC_MCP_CLAUDEMD_SECTION, SENDER_REJECTION_CLAUDEMD_SECTION, SCOPE_ACCRETION_CLAUDEMD_SECTION, MESH_SELF_HEALING_CLAUDEMD_SECTION, WRITE_ADMISSION_CLAUDEMD_SECTION, DOORWAY_REGISTRY_CLAUDEMD_SECTION, EXTERNAL_HOG_CLAUDEMD_SECTION, ROUTING_SPEND_CLAUDEMD_SECTION, DUPLICATE_RECONCILER_CLAUDEMD_SECTION, AUDIT_CONVERGENCE_CLAUDEMD_SECTION } from '../core/PostUpdateMigrator.js';
+import { SESSION_LISTING_HYGIENE_CLAUDEMD_SECTION, PLAYWRIGHT_PROFILE_REGISTRY_CLAUDEMD_SECTION, MACHINE_LOAD_ASSESSMENT_CLAUDEMD_SECTION, DYNAMIC_MCP_CLAUDEMD_SECTION, SENDER_REJECTION_CLAUDEMD_SECTION, SCOPE_ACCRETION_CLAUDEMD_SECTION, MESH_SELF_HEALING_CLAUDEMD_SECTION, WRITE_ADMISSION_CLAUDEMD_SECTION, DOORWAY_REGISTRY_CLAUDEMD_SECTION, EXTERNAL_HOG_CLAUDEMD_SECTION, ROUTING_SPEND_CLAUDEMD_SECTION, DECISION_QUALITY_CLAUDEMD_SECTION, DUPLICATE_RECONCILER_CLAUDEMD_SECTION, AUDIT_CONVERGENCE_CLAUDEMD_SECTION } from '../core/PostUpdateMigrator.js';
 
 export interface AgentIdentity {
   name: string;
@@ -886,6 +886,7 @@ ${MESH_SELF_HEALING_CLAUDEMD_SECTION(port)}
 ${WRITE_ADMISSION_CLAUDEMD_SECTION(port)}
 ${DOORWAY_REGISTRY_CLAUDEMD_SECTION(port)}
 ${ROUTING_SPEND_CLAUDEMD_SECTION(port)}
+${DECISION_QUALITY_CLAUDEMD_SECTION(port)}
 ${SESSION_LISTING_HYGIENE_CLAUDEMD_SECTION(port)}
 ${AUDIT_CONVERGENCE_CLAUDEMD_SECTION(port)}
 ${DUPLICATE_RECONCILER_CLAUDEMD_SECTION(port)}

package/upgrades/1.3.831.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The **LLM-Decision Quality Meter** (ACT-1193 uniform provenance + ACT-1194 outcome grading) — the remediation the LLM-decision audit named as the real gap. Instar has long had a *cost* meter for its AI decisions (tokens/latency per feature) but no *quality* meter: nothing recorded WHAT a high-stakes decision saw, and nothing checked afterward whether the call turned out right. This build lays that substrate:
+
+- **Correlation spine + uniform provenance:** every enrolled high-stakes AI decision now mints a safe correlation id and records the context it saw and the choice it made (replay-proof; the caller's data is never mutated; a failed attempt's cost can never be double-counted). Provenance was wired to exactly 2 of ~59 callsites before; the census + ratchet now track the whole surface.
+- **Outcome grading over time:** a deterministic, evidence-triggered grading pass stamps each recorded decision `right` / `wrong` / `unknown` as reality's evidence matures (did the killed process come back? did the "done" run actually finish?), exposed read-only at `GET /decision-quality` with a `POST /decision-quality/grade-pass` job.
+- **Ships dark + dry-run (measure-only)** behind `provenance.uniformSeam` (dev-gated; `dryRun` default true → metadata-only would-writes, no durable persistence). It changes NO decision and grades nothing durably until the seam is deliberately flipped live after soak. First graded customer is process-kill decisions; the completion-judge grader is a tracked fast-follow (ACT-1202).
+- **Two live production bug fixes ride along (these DO land live):** the dashboard file-browser could serve/edit the raw decision-provenance log (ACT-1200) — now denied; and the backup manager's per-file exclusion could be bypassed (ACT-1201) — now enforced.
+
+## What to Tell Your User
+
+Two things. First, a small privacy/robustness fix that takes effect immediately: an internal audit log could previously be opened (and edited) through the file browser, and a backup exclusion could be sidestepped — both are now closed. Second, the bigger piece is measure-only for now: I've built the machinery to grade *my own* automatic decisions — not just count how many I make or what they cost, but check whether they actually turned out right over time. That's the foundation for deciding when a bigger model or a better prompt is genuinely warranted. It's running in a safe, off-by-default mode that records but doesn't act, until it's soaked and you choose to turn it on.
+
+## Summary of New Capabilities
+
+- `GET /decision-quality` — read-only quality view (per-decision-point grade rates, strength-first, insufficient-evidence below sample floor, census debt, rejection counters; `?scope=pool` field-allowlisted). 503 when the seam is dark.
+- `POST /decision-quality/grade-pass` — deterministic, idempotent, budget-bounded grading job (keyset cursor; returns `{graded, byRule, cursors}`).
+- Correlation spine + `JudgmentProvenanceLog` uniform provenance seam (dark/dryRun behind `provenance.uniformSeam`; 59-point census + shrink-only coverage ratchet).
+- Live fixes: file-browser exposure of the decision-provenance log denied (ACT-1200); backup per-file exclusion bypass closed (ACT-1201).
+
+## Evidence
+
+- New unit/integration/e2e tiers green (read endpoint, grade-pass idempotency + rules, "feature-alive" 200-not-503, pool field-allowlist, dryRun would-write suppression, census/ratchet). Full CI sharded suite is the merge authority.
+- Converged spec (`/spec-converge`, 7 rounds; stamp validator-earned, cross-model codex-cli:gpt-5.5 ok 7/7); `docs/specs/llm-decision-quality-meter.md` + `.eli16.md` companion.
+- Follow-ups tracked: ACT-1202 (completion-judge realcheck grading — needs a Stop-hook protocol change), ACT-1203 (heavy-AgentServer test isolation), ACT-1195 (bench prompt-parity).

package/upgrades/1.3.832.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The always-on outbound **MessagingToneGate** is now enrolled as a wired LLM-decision provenance point, executing the pending→wired expansion the LLM-Decision Quality Meter (#1458) already defined. The tone gate is the highest-volume decision point in the fleet, so it records at a hard `budget:500/day` count ceiling (never `full`) and stores its content as **identity only** — a `sha256` of the candidate plus byte/char bounds and code-derived features (channel, message kind, recent-message count, gate-signal kinds). The outbound message body and any plaintext slice of it are **never** stored. Enrolling a fourth wired point activated the per-point round-robin grading sub-budget so grading capacity is shared fairly across points. Recording is observability-only — the tone gate's PASS/BLOCK verdict is byte-identical whether the provenance write succeeds, fails, or is disabled — and is dark-gated behind `provenance.uniformSeam` (enabled on the development agent, dark on the fleet).
+
+## What to Tell Your User
+
+None — internal, dev-gated observability with no user-facing surface. The change is dark on the fleet: it does not alter how the agent behaves, what it sends, or what a user sees. When enabled on a development agent it only records (machine-local, identity-only) what the always-on message-safety gate decided, so those decisions can later be graded. A user's messages, and the gate's block/allow behavior, are completely unaffected.
+
+## Summary of New Capabilities
+
+None user-facing. Internally: the outbound tone/leak gate now contributes to the LLM-decision quality record (dev-agent only, dark on fleet), giving the periodic grading pass its highest-volume data source while storing message identity only, never content.
+
+## Evidence
+
+- Side-effects review: `upgrades/side-effects/messaging-tone-gate-provenance-enrollment.md` (independent second-pass review concurred; verified critical-path inertness and no body-leak).
+- Tests: `tests/unit/messaging-tone-gate-provenance-enrollment.test.ts`, `tests/integration/messaging-tone-gate-provenance.test.ts`, plus the updated `tests/unit/provenance-coverage-ratchet.test.ts` and `tests/unit/decision-grading-pass.test.ts` sub-budget cases — 49 targeted tests green; full lint chain (typecheck + dark-gate + attribution + ratchet) clean.
+- Driven by the converged + approved spec `docs/specs/llm-decision-quality-meter.md` (§5.5 sub-budget, §5.6 volume valve + content classes).

package/upgrades/side-effects/llm-decision-quality-meter.md

@@ -0,0 +1,95 @@
+# Side-Effects Review — LLM-Decision Quality Meter (uniform provenance + outcome grading)
+
+**Version / slug:** `llm-decision-quality-meter`
+**Date:** `2026-07-12`
+**Author:** `echo`
+**Second-pass reviewer:** `echo (dedicated reviewer subagent) — high-risk (touches gate/sentinel decision points + a provenance seam)`
+
+## Summary of the change
+
+Adds the quality-meter substrate the LLM-decision audit named as the real gap (ACT-1193 uniform provenance, ACT-1194 outcome grading). Three parts: (1) a **correlation spine** — every enrolled high-stakes AI decision mints a replay-proof correlation id (`AutonomousRunStore`, `IntelligenceRouter`, `decisionQualityTypes`) so cost, provenance, and outcome all thread to one decision; (2) **uniform provenance** — `JudgmentProvenanceLog` recording extended from 2 callsites toward the full surface via `DecisionQualityRecorderImpl`, a 59-point census (`provenanceCoverage.ts`) and a shrink-only coverage ratchet; (3) **outcome grading** — a deterministic, evidence-triggered pass (`decisionGradingPass.ts`, `ExternalHogDecisionStore`, `AutonomousRealCheckAnnotator`) that stamps each recorded decision `right`/`wrong`/`unknown`, surfaced read-only at `GET /decision-quality` with a `POST /decision-quality/grade-pass` job, backed by 4 new `FeatureMetricsLedger` tables + a canonical view. The whole meter ships **dark + dryRun** behind `provenance.uniformSeam` (dev-gated; `dryRun` default true → metadata-only would-writes, nothing durable). Two live production bug fixes ride the same PR: `fileRoutes` no longer serves/edits the raw decision-provenance log (ACT-1200), and `BackupManager` per-file exclusion can no longer be bypassed (ACT-1201).
+
+## Decision-point inventory
+
+- `ExternalHogSentinel` kill decision (`ExternalHogScanTick`/`ExternalHogDecisionStore`/`ExternalHogServerPrimitives`) — **pass-through + record** — the kill verdict is UNCHANGED; the change only *records* provenance and grades on-supersede, and the durable write is suppressed while `dryRun`.
+- `CompletionEvaluator` (completion / P13-stop judge) — **pass-through + enroll** — the judge verdict is unchanged; it now mints/carries a correlation id (provenance enrollment). Realcheck-based grading of this customer is the tracked fast-follow ACT-1202, NOT in this build.
+- `decisionGradingPass` grade-stamp — **add (signal only)** — deterministic evidence rules stamp right/wrong/unknown. Never gates, blocks, or acts.
+- `GET /decision-quality` / `POST /decision-quality/grade-pass` — **add (read + job)** — 503 when the seam is dark; Bearer-authed; pool branch field-allowlisted.
+- `fileRoutes` serve/edit of the JP log — **add block (ACT-1200)** — deterministic path-based deny of a known-sensitive internal log.
+- `BackupManager` per-file exclusion — **modify (ACT-1201)** — closes a bypass so an excluded file stays excluded (incl. restore).
+
+---
+
+## 1. Over-block
+
+The meter itself has no block/allow surface — it records and grades; it never rejects an input. Over-block is only in scope for the two ride-along fixes:
+
+- **fileRoutes (ACT-1200):** the new deny is scoped to the decision-provenance log path(s), not a broad prefix. A legitimate project file that merely *contains* "provenance" in its name is not blocked — the deny matches the concrete JP-log location, verified by `tests/unit/fileRoutes-never-served.test.ts`. Risk of over-block: low, path-exact.
+- **BackupManager (ACT-1201):** enforcing an exclusion cannot over-exclude a file the operator didn't list — the change makes the *configured* exclusion actually apply; it adds no new patterns.
+
+---
+
+## 2. Under-block
+
+- **fileRoutes:** the deny covers the JP log; other internal `.jsonl` audit logs under `logs/` were already never in the file-browser's editable roots — but any FUTURE internal log added to a served root would need its own guard. Named residual, not introduced here.
+- **Grading under-block N/A** (not a block surface). The honest under-grade risk instead: an outcome whose evidence never arrives stays `unknown` (correct, not a miss); an outcome graded before its evidence window closes could mis-stamp — mitigated by evidence-triggered grading (the pass only stamps when the deterministic signal is present) + idempotent re-reads.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. Provenance recording lives at the decision recorder (`DecisionQualityRecorderImpl`), not smeared across each callsite; grading is a separate periodic consumer, not inlined into the gate that made the decision (so a gate never blocks on grading). The census/ratchet enforce coverage at the data layer where the contract lives. The meter feeds the existing `feature_metrics` cost surface rather than creating a parallel one — it extends, not duplicates.
+
+---
+
+## 4. Signal vs authority compliance
+
+Compliant. The quality meter is a pure **signal producer** — it records what a decision saw and grades how it turned out; it holds NO blocking authority and changes no verdict. Grading is deterministic evidence-rule stamping, never an LLM re-judgment in this build (the LLM evidence-interpreter is explicitly deferred, FD12/ACT-1198). The two ride-along fixes DO add blocking authority, but each is **deterministic and narrow** (a path-exact file deny; an exclusion-list enforcement) — not brittle heuristics with broad authority. `docs/signal-vs-authority.md` respected: no brittle check gained blocking power.
+
+---
+
+## 5. Interactions
+
+- Extends `feature_metrics` (adds tables + a view) — additive; existing cost rows/reads untouched (`FeatureMetricsLedger-quality.test.ts`, `CircuitBreaking-feature-metrics-tap.test.ts`).
+- Retrofits the `/judgment-provenance` pool branch with the same credential guard used by the new `/decision-quality` pool branch — one shared guard, no double-fire.
+- `grade-pass` classified in `WriteDomainRegistry` (`pool-scope-read-merge`, machine-local) so multi-machine write-admission doesn't misroute it.
+- The dryRun gate suppresses the durable `persist()` in `ExternalHogDecisionStore` while keeping in-memory grade-on-supersede + would-write logging — so nothing double-writes, and enabling the seam later can't retro-corrupt.
+- `evolutionActions.autoExpiry` cannot sweep the three deferred ACTs (they're pinned/critical-class per spec §5.6) — no race with queue cleanup.
+
+---
+
+## 6. External surfaces
+
+- New API routes (`GET /decision-quality`, `POST /decision-quality/grade-pass`) — 503 when dark, so on the fleet (seam off) they are inert. CLAUDE.md template + `CapabilityIndex` updated (agent-awareness); `PostUpdateMigrator` migration for existing agents (`decision-quality-claudemd-migration.test.ts`).
+- New job template `llm-decision-grading.md` ships `enabled:false`.
+- No message-path, dispatch, or session-lifecycle surface changes. No timing/conversation-state dependence beyond the grading pass's own keyset cursor (idempotent).
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN, proxied-on-read.** Provenance + grade rows are written machine-local (a decision happens on one machine; its evidence matures there). Reads merge across machines via the `?scope=pool` branch on `/decision-quality` (field-allowlisted so a hostile peer can't inject fields), matching the existing `/judgment-provenance` pool pattern. Cross-machine outcome ROUTING (a decision on machine A graded by evidence that lands on machine B) is explicitly deferred with honest-degradation shipping now — tracked **ACT-1199**. No user-facing notice surface here (API-only; dashboard is ACT-1197), so no one-voice gating needed. Durable state is per-machine and does not strand on topic transfer (it's not topic-keyed).
+
+---
+
+## 8. Rollback cost
+
+Low. The meter is dark/dryRun behind `provenance.uniformSeam` — the back-out for the whole grading/provenance surface is to leave the flag off (fleet default) or set `dryRun:true`; nothing durable was written. The two live fixes are two-file, self-contained denials — rollback is a revert of `fileRoutes.ts` / `BackupManager.ts` via hot-fix release, no data migration, no agent-state repair. No schema destruction: the 4 new tables are additive and unused while dark.
+
+---
+
+## Second-pass review
+
+_(Appended by the dedicated reviewer subagent — Phase 5, required: this change touches sentinel/gate decision points and a provenance seam.)_
+
+**Concur with the review.**
+
+Independently verified against the code, not the prose:
+
+1. **Signal-only holds end-to-end.** `decisionGradingPass.ts` only calls `annotate(...)` (never gates); the `POST /grade-pass` handler (routes.ts:15358) just runs `runDecisionGradingPass`; `ExternalHogSentinel.recordDecisions` (ExternalHogSentinel.ts:237-252) is pure observation — `store.record()` throws are swallowed into `dqStoreErrors`, so a persist failure can never alter the kill verdict.
+
+2. **dryRun is correct.** `this.dryRun = opts.dryRun !== false` (ExternalHogDecisionStore.ts:398, default TRUE); grade-on-supersede runs in-memory *before* the `if (this.dryRun) logWouldPersist()` else `persist()` branch (lines 528-583); `logWouldPersist` emits ledgerKey-count + byte-size only (line 473), no content. The pass treats a suppressed write as PENDING and does NOT advance the cursor (decisionGradingPass.ts:167-171) — a later `dryRun:false` flip won't skip ungraded rows.
+
+3. **Both fixes narrow.** `NEVER_SERVED_PREFIXES` is path-exact (fileRoutes.ts:97-117); `isDeniedForBackup` reuses three existing layers and is applied in dir-copy *and* restore (BackupManager.ts:353, 494).
+
+4. Both routes 503 when dark (15300/15359). 5. `pickDecisionQualityPointFields` is a real field allowlist applied instead of `{...row}` (15337); grade-pass classified machine-local in WriteDomainRegistry.ts:403. 6. Every deferral carries an ACT id; the "out of scope" mentions are non-goals, not dropped work. No missing failure mode.

package/upgrades/side-effects/messaging-tone-gate-provenance-enrollment.md

@@ -0,0 +1,68 @@
+# Side-Effects Review — MessagingToneGate Provenance Enrollment
+
+**Version / slug:** `messaging-tone-gate-provenance-enrollment`
+**Date:** `2026-07-12`
+**Author:** `echo`
+**Second-pass reviewer:** `independent reviewer subagent — CONCUR (verified all 6 axes; see Second-pass review section)`
+
+## Summary of the change
+
+Enrolls the **MessagingToneGate outbound gate** as a WIRED provenance decision point, executing the pending→wired expansion path that PR #1458's LLM-Decision Quality Meter (`docs/specs/llm-decision-quality-meter.md`, §5.6) already defined and tracked. The census (`src/data/provenanceCoverage.ts`) already carried `messaging-tone-gate` as `status: 'pending:ACT-1193'`; this flips it to `wired` with the mandatory volume valve, and adds the `provenance: {...}` enrollment to the tone gate's single verdict-producing LLM call — mirroring the exact `options.provenance` pattern #1458 established for CompletionEvaluator/ExternalHog. The tone gate is the highest-volume decision point in the fleet (3,641 of 4,098 LLM calls/24h on the dev agent per §5.6), so it enrolls at `budget:500/day` (a hard count ceiling with a loud `droppedByBudget` counter — never `full`), and its content is stored as **identity only** (a sha256 of the candidate + byte/char bounds + code-derived features: channel, messageKind, recent-message count, gate-signal kinds) — **never the message body and never any plaintext slice of it**. Enrolling a 4th wired customer structurally required activating the §5.5 per-point round-robin grading sub-budget (`decisionGradingPass.ts`, `SUBBUDGET_IMPLEMENTED` false→true), so grading capacity is shared fairly across points instead of one point starving the others. Files: `provenanceCoverage.ts`, `MessagingToneGate.ts`, `decisionGradingPass.ts`, + ratchet floor test + 2 new tests. Recording is dev-gated behind the same `provenance.uniformSeam` flag #1458 uses (ENABLED on dev, DARK on fleet).
+
+## Decision-point inventory
+
+- `MessagingToneGate` outbound-gate (`messaging-tone-gate`) — **pending→wired (observe)** — records the identity + verdict of the existing tone-gate authority. The gate's block/allow decision is untouched; the seam consumes the provenance block before any adapter and it never reaches the model.
+- `decisionGradingPass` (per-point sub-budget) — **modify (mechanism)** — a 4th wired point activates the §5.5 round-robin sub-budget; no decision authority added, it only allocates grading capacity fairly across points.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** Observability-only. The `provenance` block is passed into the tone gate's LLM call options and consumed by the router-settlement seam *before any adapter*; it never reaches the model, never gates, holds, delays, or filters a message. The tone gate's PASS/BLOCK verdict is byte-identical whether the provenance write succeeds, fails, or is disabled (fail-open, inherited from #1458's recorder; asserted by test).
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.** This records what the tone-gate authority already decided. The remaining ~49 pending census points stay tracked under `pending:ACT-1193` and the monotonic ratchet still forbids silent regression — this change *shrinks* the pending set by one (tone gate) and *grows* the wired set to 4.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer, and deliberately NOT a parallel mechanism. The enrollment sits at the tone gate's own verdict call (the only place the structured verdict exists), reusing #1458's census + recorder + envelope + ratchet rather than rebuilding any of it. The census entry was already authored as `pending:ACT-1193` for exactly this expansion; flipping it is the intended, ratchet-enforced growth path. (This increment is the corrective successor to a duplicate parallel build — PR #1460, closed — which is why it is scrupulously on #1458's seam.)
+
+## 4. Signal vs authority compliance
+
+**Fully compliant — pure signal-side, zero authority added.** Per `docs/signal-vs-authority.md`: this records the existing tone-gate authority's verdict; it adds no detector-with-authority and no new authority. The one forbidden direction — a graded outcome feeding back into a decision input — is not crossed: grading only reads recorded rows and writes verdicts to the quality store; nothing here wires a feedback edge into model/door/prompt/floor selection (that remains the future benchmark increment's own spec).
+
+## 5. Interactions
+
+- **Volume:** the tone gate fires on every drafted outbound message. The `budget:500/day` valve is the load control — a hard per-UTC-day count ceiling on the provenance JSONL archive with a loud `droppedByBudget` counter, deterministic rather than probabilistic. This is why `full` is forbidden for this point.
+- **Grading fairness:** activating the §5.5 sub-budget (required by the 4th point) means the periodic grading pass round-robins capacity across all wired points; without it a high-volume point could monopolise the grading budget. Covered by 3 new sub-budget tests.
+- **No shadow/double-fire:** one enrollment per verdict at the single `review()` call site; the deterministic availability-fallback paths are not the LLM decision and are not enrolled.
+- **`/metrics/features` agreement:** model/door/tokens come from the existing usage/attribution path, so the provenance row and cost row agree by construction.
+
+## 6. External surfaces
+
+- **`GET /judgment-provenance` / the decision-quality read surface** now also returns tone-gate rows (redacted, identity-only, Bearer-gated) — reusing #1458's existing envelope + `no-store` route. No new route.
+- **Privacy — the load-bearing property:** content is stored as `sha256(candidate)` + bounds + code-derived features, **never the body and never a plaintext head**. This deviates from the initial "hash + bounded head" instruction: an integration test (written first) caught the literal outbound body landing on the served row because the credential-scrub does NOT strip non-credential PII/prose. The head was dropped entirely, matching the CompletionEvaluator content-bearing sibling's hash-only discipline — the stricter, correct reading for the very text this gate inspects for leaks.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local write, proxied-on-read** — identical to #1458's provenance posture (inherited, not re-declared). Full rows are credential-scrubbed + machine-local (0700/0600, never-served-raw, short retention) and never replicated; the unified read is the existing redacted `?scope=pool` merge that #1458 built. Identity-only content further reduces the at-rest surface for this point. The ratchet + census are CI-level (machine-independent). No new machine-local surface is introduced.
+
+## 8. Rollback cost
+
+**Cheap and reversible.** Recording is dev-gated behind `provenance.uniformSeam` (dark on fleet); flipping it off leaves the tone gate behaving exactly as before with zero rows. Full back-out is a plain revert: the census entry returns to `pending:ACT-1193`, the enrollment is removed, and `SUBBUDGET_IMPLEMENTED` reverts (the sub-budget is inert with <2 wired high-volume points anyway). No migration, no persisted state beyond the short-retention JSONL, no fleet coordination. Because recording never touched the tone verdict, a revert cannot regress any outbound-messaging behavior.
+
+## Second-pass review (independent)
+
+**Concur with the review.** Verified against the real diff + code (not the artifact) on all six axes:
+
+- **A / critical-path (holds):** In `review()` the `provenance` block is added to `opts` (`MessagingToneGate.ts:737-742`) and passed to `provider.evaluate(prompt, opts)` — but `IntelligenceRouter.mintDecision` clones the options and `delete internal.provenance` BEFORE any attempt (`IntelligenceRouter.ts:1138-1139`), so it never reaches the model. Settlement runs on the router's own path after the verdict (`:1110-1116`), and the single write is try/catch-contained — "the decision call is never failed or delayed by its audit trail" (`recordSettlement` :1288-1290); an errored exit re-throws the ORIGINAL error unchanged (`:1113-1116`), which the gate's own fail-closed/tier logic handles. `buildToneDecisionContext` is built synchronously outside the try block, but it is throw-proof: `crypto` (node:crypto, imported :21), `Buffer.byteLength`, `String().slice`, and `detectGateSignals` (itself fully try/catch-guarded, returns `[]` on any input — `GateSignalDetectors.ts:238-258`). A recorder failure/slow-write/throw cannot alter or hold the verdict — fail-open is real, not asserted.
+- **B / body-leak (holds — load-bearing property intact):** `buildToneDecisionContext` (`MessagingToneGate.ts:128-160`) stores `candidate: {sha256, bytes, chars}` + `channel` (a 32-char slice of the CHANNEL name, not the body) + `messageKind` + `recentMessageCount` (a count) + `gateSignalKinds` (kind labels). Grepped the whole diff: the only `.slice` is on `context.channel`; no plaintext head/body field exists anywhere. The integration test drives a REAL gate→router→recorder→JPL→`GET /judgment-provenance` and asserts the distinctive body marker is absent from the served JSON AND `ctxParsed.candidate.head` is `undefined` (`messaging-tone-gate-provenance.test.ts:150-165`); the unit suite additionally proves a 1MB message yields a <512-byte envelope and an in-body secret never crosses. The router's `rawResponseHead` (`:1227-1230`) captures the MODEL's verdict JSON, never the candidate body.
+- **C / volume valve (enforced, not cosmetic):** census is `budget:500` (`provenanceCoverage.ts:200`), and the recorder genuinely enforces it — `resolveJsonlDisposition` parses `budget:<N>`, counts today's rows, returns `'budget-dropped'` past the ceiling and bumps the `droppedByBudget` counter (`DecisionQualityRecorderImpl.ts:300-302, 338-346`) while still writing the ~250-byte SQLite row. The ratchet fails a `full` valve for this point (`not.toBe('full')` + `toMatch(/^budget:[1-9]\d*$/)`).
+- **D / §5.5 sub-budget (no feedback edge):** `GRADE_PASS_POINTS = [DP_EXTERNAL_HOG_KILL_LEAVE]` (one point) → `perPointSubBudget(N,1)===N`, byte-identical to the prior single-point walk; the hog grading body was extracted verbatim into `gradeOnePoint`. The tone gate is explicitly NOT graded by this pass. The pass reads recorded rows + hog-store records and writes grades only — it touches no model/door/prompt/floor selection. Covered by 3 new sub-budget tests + the unchanged hog correctness tests.
+- **E / ratchet monotonicity:** the `messaging-tone-gate::…::ACT-1193` line was removed from `PENDING_BASELINE`, so a regression to pending fails the shrink-only pending pin (a new unbaselined line) AND the dedicated `status==='wired'` assertion — two independent failures. No other census entry changed (4 wired = 3 first-customer + tone; 6 exempt unchanged).
+- **F / dark-gate:** recording gates on the same `provenance.uniformSeam` flag #1458 uses (`DecisionQualityRecorderImpl.ts:195`, early-return `:212`) and the router no-ops when `getDecisionQualityRecorder()` is null. Gate-off = the inert `provenance` options block is never consumed; zero rows, zero behavior change.
+
+Ran the three unit suites (47 passing, incl. the typed-import wired-verification) + the integration test (2 passing, body-marker-absent) + `tsc --noEmit` (clean). One cosmetic note (non-blocking): the summary line calls tone-gate the "4th wired customer" whereas the census/tests correctly call it the "third enrolled CUSTOMER" (customers key on `baseOf(component)`, so CompletionEvaluator + /P13 collapse to one) — the code and ratchet are internally consistent; only the artifact's prose is loose. No parallel mechanism; it rides #1458's seam exactly.