instar 1.3.450 → 1.3.451

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.