instar 1.3.449 → 1.3.451

package/upgrades/1.3.451.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added **`GrowthMilestoneAnalyst`** — a new proactive growth & milestone analyst
+(`src/monitoring/`). It composes the existing tracking surfaces (`InitiativeTracker`
+rollout stages + staleness, `ApprovalLedger` approve-vs-change, `CorrectionLedger`
+recurrence) into one opinionated digest with five explicit notify-rules:
+
+- **R1** promotion-ready (a feature past its incubation window that proved itself)
+- **R2** incubation-expired-unproven (past window, never proved itself → extend/repair/retire)
+- **R3** initiative-stalling (reuses `tracker.digest()`)
+- **R4** spec approve-vs-change pattern
+- **R5** recurring-correction pattern
+
+The key lever is a TIGHT incubation window (3d low-risk / 7d standard) whose **expiry
+is itself the trigger**, so a feature can never be silently left behind. Promotion
+requires real proof-of-life, never elapsed time alone (a feature whose evidence
+source isn't wired is surfaced honestly as `proved:'unknown'` and can never be
+promotion-ready).
+
+Wires four read-only routes — `GET /growth/digest`, `GET /growth/findings`,
+`GET /growth/status`, `POST /growth/tick` — plus a `monitoring.growthAnalyst` config
+block (defaults OFF). Ships **DARK**: this slice computes and exposes findings only;
+it does NOT send to Telegram. Cadence/event-delivery and enabling the muted
+analyzers ride a later, flood-sensitive slice.
+
+## What to Tell Your User
+
+Nothing yet — this ships dark and disabled by default, and is agent-only. It does not
+message the user, change any existing behavior, or turn on any new surface until it
+is explicitly enabled in a later promotion slice. When asked "is anything checking on
+my initiatives, feature maturity, or patterns?", you can note the analyst exists and
+is being rolled out carefully from dark to live, and that you will be able to read its
+computed digest once it is turned on.
+
+## Summary of New Capabilities
+
+- New monitoring component `GrowthMilestoneAnalyst` (observe-only; no new sensors).
+- New read routes `GET /growth/digest|findings|status`, `POST /growth/tick`
+  (503 when disabled — the dark default).
+- New config block `monitoring.growthAnalyst` (ships disabled; tunable incubation
+  windows, proof-of-life threshold, per-rule flags) — auto-applies to existing
+  agents via ConfigDefaults deep-merge.
+- CLAUDE.md template documents the routes (Agent Awareness Standard).
+
+## Evidence
+
+Not a bug fix and not reproducible in dev — this is a new, dark-by-default capability,
+so there is no before/after to reproduce. It changes no existing behavior: with the
+flag off (the default) every new route returns 503 and nothing else references the
+analyst. Behavior is covered by 41 tests across all three tiers (unit semantic
+coverage on both sides of every window/proof boundary, integration route gating,
+wiring against a real InitiativeTracker, and an e2e "feature is alive" lifecycle).

package/upgrades/side-effects/autonomous-legitimate-stops.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Autonomous "Legitimate Stop Conditions" allowlist
+
+**Version / slug:** `autonomous-legitimate-stops`
+**Date:** `2026-06-09`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds a new top-level section to the autonomous skill's instruction file — **"## Legitimate Stop Conditions (the ONLY valid reasons to exit)"** — enumerating the only three valid reasons a pre-approved autonomous session may exit: (a) a genuine hard external blocker the agent cannot resolve, (b) duration expiry, (c) the completion condition/promise genuinely met. It pairs that with an explicit NON-stops table (reversible decisions, milestones, late-hour, "needs your steer/opinion," "good stopping point," quiet off-ramp-with-no-reply) and reinforces the existing Anti-Patterns list with two new entries ("This Needs Your Steer" and "Quiet Off-Ramp"). Files touched: `.claude/skills/autonomous/SKILL.md` (the bundled shipping source — new agents get it via `init`/`installAutonomousSkill`), `src/core/PostUpdateMigrator.ts` (bumps the existing `migrateAutonomousStopHookTopicKeyed` SKILL.md marker from `PER-TOPIC (setup-race hardening)` to `LEGITIMATE_STOP_CONDITIONS` so existing agents receive the section on update), and `tests/unit/PostUpdateMigrator-autonomousStopHook.test.ts` (four new migration tests). This is prompt/skill CONTENT plus its Migration-Parity migration — NOT a change to any decision-point code logic.
+
+## Decision-point inventory
+
+The change touches **no runtime decision point.** It does NOT modify the autonomous stop hook's blocking logic (`autonomous-stop-hook.sh`), the completion-condition judge, the emergency-stop check, or any gate/sentinel/watchdog. The stop hook continues to decide exit exactly as before; this change only edits the prose the agent reads and adds a content-sniffing migration that re-deploys that prose to existing installs.
+
+- `migrateAutonomousStopHookTopicKeyed` (SKILL.md upgrade arm) — modify (marker bump only) — re-deploys the bundled SKILL.md to existing agents whose installed copy lacks the new sentinel.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The migration's `upgrade()` helper writes a file only when the installed copy lacks the new marker AND matches the stock fingerprint (`ALL_TASKS_COMPLETE`); a customized SKILL.md is left untouched (reported as `skipped`), so it cannot "over-write" operator customizations.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. As prose guidance, the section is advisory: the structural stop hook is what actually enforces continuation. An agent could still rationalize an early stop despite the guidance — but that is the stop-hook's job to catch (out of scope here, tracked as the separate Tier-2 stop-hook logic change). This change strengthens the guidance the agent reads each iteration; it does not claim to be the enforcement layer.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. This is skill CONTENT (prompt-level guidance), which is the correct layer for "here are the only valid reasons to exit." The structural enforcement (the stop hook) is a separate, lower layer that this content complements. The migration rides the EXISTING `migrateAutonomousStopHookTopicKeyed` path — the established, correct home for autonomous SKILL.md content updates — rather than introducing a parallel migration. The marker-bump mechanism is the same content-sniffing pattern already used for the prior SKILL.md fixes (per-topic write, registration-path fix), so it reuses rather than re-implements.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+This is documentation/skill-content plus an idempotent file-deployment migration. It makes no allow/block decision, holds no authority over message flow or session lifecycle, and adds no brittle detector. The migration only writes a markdown file under content-sniffing guards.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** None. The migration's SKILL.md arm shares the same `upgrade()` helper as the stop-hook and setup-script arms within `migrateAutonomousStopHookTopicKeyed`; each arm targets a distinct file path, so they cannot shadow each other. The marker bump on the SKILL.md arm does not affect the hook/setup arms (independent markers).
+- **Double-fire:** None. `installAutonomousSkill()` (init path) is install-if-missing and won't overwrite; the migration is the single content-update path. They do not both write the same file in the same run (init only writes when absent).
+- **Races:** None. The migration runs synchronously inside the PostUpdateMigrator sequence at update time; no shared concurrent state.
+- **Feedback loops:** None.
+
+One real interaction verified: the existing test `PostUpdateMigrator-autonomousStopHook.test.ts` already exercises this migration; the marker bump from `PER-TOPIC (setup-race hardening)` to `LEGITIMATE_STOP_CONDITIONS` required no change to the existing hook/setup test cases (those assert their own markers, not the SKILL.md marker), and the new SKILL.md tests were added alongside. Verified the bundled SKILL.md contains BOTH the new marker (so `next.includes(marker)` passes and the upgrade actually writes) AND the fingerprint.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the same machine: only their autonomous SKILL.md content updates on their next PostUpdateMigrator run — the intended Migration-Parity effect.
+- Other users of the install base: same — they get the new guidance on update.
+- External systems (Telegram, Slack, GitHub, Cloudflare): none.
+- Persistent state: none beyond rewriting the one markdown file the migration targets (only when stale + stock).
+- Timing/runtime conditions: none.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure content change — revert the SKILL.md edit and the marker bump, ship as the next patch. No persistent state to clean up, no data migration, no agent-state repair. Existing agents that already received the re-deployed SKILL.md would simply receive the reverted version on a subsequent marker bump (or keep the harmless prose section). No user-visible regression during the rollback window.
+
+---
+
+## Conclusion
+
+This review confirms the change is content-only with no decision-point surface. It adds the operator-requested "Legitimate Stop Conditions" allowlist + NON-stops table to the autonomous skill, ships it to new agents via the bundled source, and reaches existing agents via the established content-sniffing SKILL.md migration arm (marker bump, idempotent, customization-preserving). No design changes were required by the review. Clear to ship pending human review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+
+Tier 1, content-only, no block/allow or session-lifecycle decision logic touched — the Phase 5 second-pass triggers do not apply.
+
+---
+
+## Evidence pointers
+
+- `npx tsc --noEmit` → exit 0 (clean).
+- `npx vitest run tests/unit/PostUpdateMigrator-autonomousStopHook.test.ts` → 12 passed (8 prior + 4 new SKILL.md cases).
+- `npx vitest run tests/unit/autonomous-skill-deployment.test.ts tests/unit/migration-parity.test.ts tests/unit/PostUpdateMigrator-autonomousHookPath.test.ts tests/unit/autonomous-stop-hook-idle-backoff.test.ts` → 52 passed.
+- Bundled SKILL.md verified to contain both `LEGITIMATE_STOP_CONDITIONS` (marker) and `ALL_TASKS_COMPLETE` (fingerprint).

package/upgrades/side-effects/growth-milestone-analyst-dev-gate.md

@@ -0,0 +1,99 @@
+# Side-Effects Review — GrowthMilestoneAnalyst dev-agent gate correction
+
+**Change:** Make the GrowthMilestoneAnalyst honor the standard `developmentAgent`
+dark-feature gate instead of a hardcoded `enabled: false`. The original slice-1
+implementation shipped dark for **every** agent (including dev agents like echo),
+which contradicts the established convention used by secret-sync, boot
+self-knowledge, the resource sampler, warm-session A2A, etc.: dark-features OMIT
+`enabled` from their config default and resolve `enabled ?? !!config.developmentAgent`
+at runtime so the dev agent (the dogfooding ground) runs them LIVE while the fleet
+stays DARK.
+
+**Files:**
+- `src/config/ConfigDefaults.ts` — removed the hardcoded `enabled: false` from the
+  `monitoring.growthAnalyst` block (and rewrote the comment to describe the gate).
+- `src/server/AgentServer.ts` — construction now resolves
+  `growthAnalystEnabled = monitoring?.growthAnalyst?.enabled ?? !!developmentAgent`,
+  and feeds that resolved value into `resolveGrowthSettings({ ...block, enabled })`
+  so `GET /growth/status` honestly reports `enabled: true` on a dev agent. The
+  `resolveGrowthSettings` call is now optional-chained so the gate can be true even
+  with no `monitoring.growthAnalyst` block present (dev agent, defaults only).
+- `tests/unit/growth-analyst-gate-wiring.test.ts` — new wiring-integrity tests
+  (config omits `enabled`, migration parity, both-sides resolution, source-level
+  gate assertions).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+None. The change ENABLES the feature on dev agents; it never rejects an input. An
+operator who explicitly sets `monitoring.growthAnalyst.enabled: false` still
+force-darks the feature even on a dev agent (explicit value wins via `??`), and an
+explicit `true` still enables it fleet-wide — both preserved and tested.
+
+## 2. Under-block — what failure modes does this still miss?
+The analyst remains slice-1: it COMPUTES + serves the digest over `/growth/*` but
+does NOT message the user on a schedule (that's the deliberately-separate next
+slice). So a dev agent now runs the analyst live but still won't proactively speak
+until the messaging slice lands. This is by design (avoid swinging from too-quiet
+to too-noisy), not a regression introduced here. No new under-block.
+
+## 3. Level-of-abstraction fit — right layer?
+Yes. The gate resolution lives in `AgentServer` construction exactly where every
+other dark-feature gate resolves (`standard_development_agent_dark_feature_gate`),
+and the default omission lives in `ConfigDefaults` exactly like warmSessionA2A and
+boot self-knowledge. No new layer; it joins the existing one.
+
+## 4. Signal vs authority compliance (docs/signal-vs-authority.md)
+Compliant. The GrowthMilestoneAnalyst is a SIGNAL-PRODUCER: it reads rollout
+stages, the approval ledger, and the correction ledger and computes findings. It
+holds NO blocking authority — it never filters a message, blocks an action, or
+gates information flow. This change only determines WHETHER that signal-producer
+runs on a given agent; it adds no brittle-check-with-authority. The routes remain
+read-only.
+
+## 5. Interactions — shadowing, double-fire, races?
+None. The construction is guarded by its own try/catch (failure is non-fatal and
+null-instances the analyst → `/growth/*` 503-stubs). No PostUpdateMigrator entry
+writes `growthAnalyst`, so the gate is the sole resolver — there's no migration
+that could write `enabled` to disk and shadow the runtime gate. The
+`resolveGrowthSettings({ ...block, enabled })` merge does not mutate config.
+
+## 6. External surfaces — visible to other agents/users/systems?
+On the dev agent only, `/growth/digest`, `/growth/findings`, `/growth/status`,
+`POST /growth/tick` flip from 503 to 200 after the next server boot (Claude Code
+loads config once at session/server start — running processes pick it up on
+restart). Fleet agents are unaffected (still 503). No agent-to-agent surface, no
+Telegram surface (the analyst does not message in this slice). The
+`/growth/status` `enabled` field now reads `true` on a dev agent (was a latent
+`false` had the routes ever been forced live) — this is the honesty fix.
+
+## 7. Rollback cost — back-out if wrong?
+Trivial and reversible. Two ways: (a) operator sets
+`monitoring.growthAnalyst.enabled: false` in `.instar/config.json` and restarts —
+force-darks it immediately, no code change; (b) git revert of this commit restores
+the hardcoded `enabled: false`. No data migration, no state repair — the analyst's
+only durable artifact is `state/growth-milestone-analyst/stage-journal.json`, which
+is observe-only and self-heals (a missing/stale journal just recomputes on the next
+observe). Worst case is a dev agent serving an unused read route.
+
+## No deferrals
+This change is complete: the gate is wired, the default is corrected, the status
+honesty is fixed, and the wiring tests cover both sides. Nothing is deferred.
+
+## Second-pass review (independent)
+**VERDICT: Concur with the review.** An independent reviewer audited the diff,
+the analyst source, the routes, and the migrators:
+- Read-only/signal-only confirmed: `computeFindings`/`buildDigest`/`getStatus`
+  never gate on `settings.enabled`; `isEnabled()` only feeds the informational
+  status field; routes guard solely on `if (!ctx.growthMilestoneAnalyst)` — so
+  constructing the analyst is sufficient to make it live, and the component holds
+  no blocking authority.
+- Gate matches the established convention (byte-identical to the resource
+  sampler's `?? !!options.config.developmentAgent`); explicit `enabled` wins both
+  ways; both sides tested.
+- No fleet leak / no disk write: non-dev agents resolve to false → null → 503;
+  grep of PostUpdateMigrator returned zero `growthAnalyst` references, so no
+  migration writes `enabled` to disk; `applyDefaults` only backfills missing
+  fields (operator `enabled:false` survives).
+- No optional-chaining/merge bug: `resolveGrowthSettings({ ...(block ?? {}),
+  enabled })` is safe when the block is absent and cannot throw; the spread sets
+  `enabled` last so it deterministically wins; no needed field dropped.
+- All seven side-effects claims match the code; new test file passes 6/6.

package/upgrades/side-effects/growth-milestone-analyst.md

@@ -0,0 +1,92 @@
+# Side-Effects Review — Growth & Milestone Analyst (slice 1)
+
+**Version / slug:** `growth-milestone-analyst`
+**Date:** `2026-06-08`
+**Author:** `echo`
+**Tier:** `1` (ships dark, flag-off, compute + read-only, fully reversible)
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds `GrowthMilestoneAnalyst` (`src/monitoring/`) — a pure observer that composes
+the existing `InitiativeTracker` (rollout stages + staleness), `ApprovalLedger`
+(approve-vs-change), and `CorrectionLedger` (recurrence) into one digest with five
+explicit notify-rules (R1 promotion-ready, R2 incubation-expired-unproven, R3
+initiative-stalling, R4 spec-pattern, R5 correction-pattern). It keeps ONE piece of
+internal bookkeeping — a stage-observation journal — so "days in stage" is robust
+where the rollout engines do not stamp it. Wires four read routes (`GET
+/growth/digest|findings|status`, `POST /growth/tick`), a `monitoring.growthAnalyst`
+config block (defaults OFF), and the AgentServer construction (guarded; null →
+routes 503). Ships DARK: compute + read only, no Telegram sending.
+
+## Decision-point inventory
+
+- **`classifyRollout`** (the window-expiry verdict): in-window / at-boundary /
+  expired × proved / unproved / unknown × stage. Both sides of every edge are unit
+  tested.
+- **Per-rule enable gates** (`settings.rules.*`): each rule suppresses iff its flag
+  is false.
+- **Construction gate** in AgentServer: analyst built only when
+  `monitoring.growthAnalyst.enabled === true` AND a tracker + stateDir exist.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** Nothing user-facing is rejected.
+The only "rejection" is structural: when the feature is OFF (the default), every
+`/growth/*` route returns 503 — by design, mirroring the established dark-feature
+contract (e.g. `correctionLearning`). No existing route, job, message, or gate
+changes behavior. The analyst never blocks, delays, or rewrites anything.
+
+## 2. Under-block
+
+**What does this still miss?** Three deliberate gaps, all deferred to later slices:
+(a) no Telegram/event delivery — it computes but does not speak, so a real milestone
+won't reach the operator until the sending slice; (b) proof-of-life
+(`evidenceCounter`) is unwired, so every expiry currently classifies as
+R2-unknown rather than R1 until a per-feature activation source is plumbed — this is
+surfaced honestly as `proved:'unknown'`, never masked; (c) the muted analyzers
+(`correctionLearning`, `failureLearning`) are NOT enabled here — that flood-sensitive
+step is its own slice.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The analyst lives in `src/monitoring/` beside the other
+observe-only components (TokenLedger, ResourceLedger). It reads through the engines'
+public methods (`tracker.list/digest`, `approvalLedger.summarize`,
+`correctionLedger.list`) rather than reaching into their storage. The stage journal
+is analyst-private state under `stateDir/state/growth-milestone-analyst/`.
+
+## 4. Reversibility
+
+Fully reversible: the feature ships behind `monitoring.growthAnalyst.enabled`
+(default false). Disabling it (or removing the construction block) returns the
+system to byte-identical prior behavior — the routes 503, nothing else references
+the analyst. The only persisted artifact is a small JSON journal that is pruned and
+self-heals.
+
+## 5. Anti-flood discipline (relevant because this REVERSES an over-silence)
+
+The whole point is to speak more, so overshooting into a new flood is the risk to
+guard. This slice does not send at all. The digest is structurally ONE object — a
+burst of N window-expiries aggregates into one digest with counts, never N messages
+(unit-tested at N=500). When the sending slice lands it must route through the
+existing budget-guarded attention/post-update surfaces and aggregate, never create
+one topic per feature. That guardrail is stated here so the next slice inherits it.
+
+## 6. Framework generality
+
+Not framework-specific. The analyst is a server-side monitoring component that reads
+instar's own ledgers/trackers; it does not spawn sessions, call an LLM, or route
+through any agentic framework (Claude/Codex/Gemini/pi). It behaves identically
+regardless of which framework the agent runs on. No per-framework branching exists
+or is needed.
+
+## 7. Migration parity
+
+- Config defaults auto-apply to existing agents via `ConfigDefaults` +
+  `applyDefaults` deep-merge (the established no-separate-migrateConfig path for a
+  new `monitoring.*` sub-key).
+- The CLAUDE.md template (`generateClaudeMd`) documents the routes for NEW agents.
+- A `migrateClaudeMd` content-sniff + the scheduled digest job are deferred to the
+  promotion slice — a dark, route-only feature needs no live agent-awareness
+  migration until it actually speaks.

package/upgrades/side-effects/slack-livetest-cleanups.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Slack live-test cleanups (#2 ambient-silence observability, #5 spec/type alignment)
+
+**Version / slug:** `slack-livetest-cleanups`
+**Date:** `2026-06-09`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `not required` (Tier-1; observability-only + doc-accuracy; no decision authority touched)
+
+## Summary of the change
+
+Two small cleanups the Slack-org live-test plan flagged.
+
+**Cleanup #2 (observability):** the `AmbientContributionGate` previously only left a trace when it SPOKE (the speak-path `console.log` + the `onDecision` log fires on `speak:true`). A wrongful SILENCE left no measurable record, so the ambient false-positive (wrongful-silence) / false-negative rate could not be measured during the observe-only live test. This adds a bounded, in-memory aggregate inside the gate — per-channel `{evaluated, spoke, silent, nearMissSilent, silentByReason}` plus a bounded ring of the most-recent near-miss silences — read via a new `getStats()` method, a `SlackAdapter.getAmbientStats()` passthrough, and a read-only `GET /permissions/ambient-stats` route (reads the live `ctx.slack` instance). Files: `src/permissions/AmbientContributionGate.ts`, `src/messaging/slack/SlackAdapter.ts`, `src/server/routes.ts`, plus unit + integration tests.
+
+**Cleanup #5 (doc accuracy):** `SLACK-ORG-INTEGRATION-SPEC.md` named a `respondMode: 'considered'` third mode, but the shipped `SlackRespondMode` type is `'all' | 'mention-only'`; ambient rides on `ambientContribution.enabledChannelIds` ON TOP of `mention-only`. The spec (§5.2 and the §15 migration-parity bullet) is rewritten to match the shipped reality — the lower-risk fix. No type value added; no code path needed it.
+
+## Decision-point inventory
+
+- `AmbientContributionGate.shouldSpeak` (the speak/silence decision) — **pass-through** — the verdict is computed exactly as before; the aggregate is updated AFTER the verdict is formed, inside `decide()`, wrapped in try/catch, and `decide()` returns the decision unchanged. The recording cannot alter the outcome.
+- `GET /permissions/ambient-stats` — **add** — read-only observability surface; performs no mutation and no messaging.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The aggregate is signal-only and the new route is read-only. The speak/silence decision is unchanged (a dedicated regression test asserts identical verdicts with the aggregate present).
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. The aggregate is an in-memory FP-measurement counter, not a gate. It is reset on restart, which is acceptable for an FP-rate-measurement surface (the durable per-decision record is the file-backed `/permissions/decisions`). Worst case is a momentary loss of accumulated counts after a restart — never an over- or under-speak.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The aggregate lives ON the gate that produces the decisions it counts, so every decision (including the previously-invisible silences) is observed at the single chokepoint `decide()` — no parallel detector, no double-counting. The route reads the live `ctx.slack` adapter (already in `RouteContext`), mirroring how the existing observe-only `/permissions/*` surfaces expose internal state. A durable counter could replace the in-memory map later without changing the contract.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or produce a signal?**
+
+Pure signal. Per `docs/signal-vs-authority.md`: the aggregate is a detector/observability surface with ZERO authority — it never blocks, delays, or rewrites a message, and it cannot change the speak/silence verdict (recording runs after the verdict and returns it unchanged; a stats bug is swallowed by try/catch). The ambient gate's own fail-to-silence authority is untouched.
+
+---
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, or race?**
+
+No. The new counters are independent of the existing `onDecision` hook and the speak-path `console.log` (both retained). No timer, no shared mutable state with another component. The `recordSpoke()` rate-limit budget is a separate concern and is not affected. The new route shares the `/permissions/*` prefix, already allowlisted as dark/internal in `CapabilityIndex` (line ~1023), so it does not trip the route-discoverability scan.
+
+---
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents / users / systems?**
+
+Only the new authenticated read-only route `GET /permissions/ambient-stats` (returns `{ present: false }` when no ambient gate is attached — the default). It creates NO Telegram message and NO forum topic, so it cannot contribute to a notification flood (verified: the notification-flood burst-invariant test still passes). It is dark unless a channel is opted into ambient contribution. No timing/conversation-state dependency.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivial. The aggregate is in-memory (no persistence, no migration, no agent-state repair) and the route is additive. Reverting the commit removes both with no residue. Cleanup #5 is a doc edit with zero runtime effect.