instar 1.3.474 → 1.3.476

package/upgrades/1.3.475.md

@@ -0,0 +1,66 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The growth analyst (`GrowthMilestoneAnalyst`) has, since Slice 1, *computed* a full growth
+picture — stalling initiatives (R3), features that earned promotion (R1), incubation
+windows that expired unproven (R2), spec approve-vs-change patterns (R4), recurring
+corrections (R5), and dev-gate conformance (R6) — but nothing ever *sent* it. This slice
+adds the voice: `GrowthDigestPublisher` (`src/monitoring/GrowthDigestPublisher.ts`), an
+in-process component that, on the existing `monitoring.growthAnalyst.digestCron` cadence
+(default Monday 11:00), formats ONE consolidated "growth check-in" and routes it to the
+Agent Updates topic through the same flood-guarded path `/telegram/post-update` uses.
+
+To guarantee the publisher cannot bypass the dedup/budget/tone guards, the change carves a
+pure `res`-free `evaluateOutbound` funnel out of `checkOutboundMessage` and adds a
+`postToUpdatesTopic` helper the route and the publisher both share — one guarded chokepoint,
+not two. Hardening from the 8-reviewer convergence: a multi-machine lease gate (`isAwake`)
+so an in-process cron never double-sends on a paired agent, calm-week silence by default,
+missed-run catch-up (idempotent on the window ISO), a cadence sanity-floor, an in-flight
+guard, and a render-boundary secret-scrub with high-priority findings never abbreviated.
+
+It ships **dark**: `monitoring.growthAnalyst.digestDelivery` defaults to `'off'` — even on a
+development agent — so merging the code sends nothing. The rollout path is
+`off → dry-run (logs the would-send sample to logs/growth-digest.jsonl) → live`, opt-in by
+the operator, dogfooded on Echo first. The fleet stays off.
+
+## What to Tell Your User
+
+Nothing changes yet — this ships off by default, so no message is sent when it merges. Once
+you ask me to turn it on, I'll start in a quiet "show me what you'd send" mode and only go
+live once you're happy with a sample. From then on I post one short weekly growth check-in to
+your Agent Updates topic: a consolidated summary of what's waiting on you, what's ready to
+promote, and what's drifting — never a wall of items (big lists collapse to the top few with
+a "plus N more"), and I stay silent on a fully-calm week unless you ask me to send a steady
+heartbeat. I can only send the message or stay quiet — I never block or rewrite anything. You
+can also just ask me for the same picture on demand any time.
+
+## Summary of New Capabilities
+
+- `GrowthDigestPublisher` — cadenced, lease-gated, deterministic-format proactive growth
+  check-in to the Agent Updates topic (ships dark behind `digestDelivery`).
+- `monitoring.growthAnalyst.digestDelivery` (`off` | `dry-run` | `live`, default `off`),
+  `digestSendOnCalmWeeks` (default `false`), `digestTimezone` (default `UTC`).
+- A shared, `res`-free `evaluateOutbound` outbound-guard funnel + `postToUpdatesTopic`
+  helper — one chokepoint the route and the publisher both pass through.
+
+## Evidence
+
+- `src/monitoring/GrowthDigestPublisher.ts` — the publisher, pure `formatDigest`, and the
+  `logs/growth-digest.jsonl` audit sink.
+- `src/server/routes.ts` — `evaluateOutbound` (pure funnel), `checkOutboundMessage` (thin
+  adapter), `postToUpdatesTopic` (the publisher's guarded sender), `attachSender` hookup.
+- `src/server/AgentServer.ts` — construction gate (`analyst && digestDelivery !== 'off'`),
+  lease gate (`isAwake`), `.stop()` teardown.
+- 3-tier tests + wiring-integrity + burst-invariant: `tests/unit/GrowthDigestPublisher.test.ts`
+  (21), `tests/integration/growth-digest-publisher{,-wiring}.test.ts` (10),
+  `tests/e2e/growth-digest-publisher-lifecycle.test.ts` (3), and the growth-digest aggregation
+  block added to `tests/integration/notification-flood-burst-invariant.test.ts`.
+- The pre-existing outbound-guard route suites (`post-update-gate-budget-route`,
+  `localhost-link-guard-route`, `outbound-content-dedup-route`, `outbound-gate-budget`) pass
+  unchanged — the `evaluateOutbound` extraction is behavior-preserving.
+- Side-effects review: `upgrades/side-effects/proactive-growth-digest-publisher-slice2.md`.
+- Spec: `docs/specs/PROACTIVE-GROWTH-DIGEST-PUBLISHER-SLICE2-SPEC.md` (converged + approved).

package/upgrades/1.3.476.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a standalone test utility — `scripts/throwaway-identity.mjs` (+ `scripts/lib/`) — that
+mints genuinely-distinct, readable throwaway email inboxes via the mail.tm public
+disposable-mailbox API and extracts verification codes/links from them. It's the autonomous
+half of provisioning distinct test identities for the Live Integration Security-Test Harness
+(Slack today, any integration later): N distinct inboxes → N genuinely-distinct principals,
+zero real accounts. No runtime code, gate, or config is touched.
+
+## What to Tell Your User
+
+Nothing changes in how the agent runs. This is a developer/test tool. It lets the agent set
+up several genuinely-different throwaway test users (and read their email) on its own, so a
+live integration test can use real distinct identities without anyone hand-creating email
+accounts. The only step it intentionally leaves to a human is passing an anti-bot CAPTCHA at
+workspace creation.
+
+## Summary of New Capabilities
+
+- `scripts/throwaway-identity.mjs mint` — create a fresh readable throwaway inbox.
+- `scripts/throwaway-identity.mjs wait <token>` — await an email and extract its code/link.
+- `scripts/lib/throwaway-identity.mjs` — importable helper (HTTP injectable for hermetic tests).
+
+## Evidence
+
+- 15 hermetic unit tests (`tests/unit/throwaway-identity.test.ts`) — pure extractors + the
+  mint / poll-until-match / timeout flow, with fetch + clock injected (no network).
+- Live CLI smoke minted a real inbox + token. `tsc --noEmit` clean.

package/upgrades/side-effects/proactive-growth-digest-publisher-slice2.md

@@ -0,0 +1,201 @@
+# Side-Effects Review — Proactive Growth Digest Publisher (Slice 2)
+
+**Version / slug:** `proactive-growth-digest-publisher-slice2`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (Tier 2 — converged + approved spec, 8-reviewer panel, 3 iterations)`
+
+## Summary of the change
+
+Adds `GrowthDigestPublisher` (`src/monitoring/GrowthDigestPublisher.ts`): an in-process
+component that consumes the existing `monitoring.growthAnalyst.digestCron` and, on that
+cadence, formats ONE consolidated "growth check-in" from the already-computed
+`GrowthMilestoneAnalyst.buildDigest()` and routes it through the existing flood-guarded
+post-update path. It is the cadence + delivery half (Slice 2) of the growth analyst;
+Slice 1 (compute + read routes) already shipped. To give the publisher a delivery path
+that provably cannot bypass the dedup/budget/tone guards, the change carves a pure,
+`res`-free `evaluateOutbound` funnel out of `checkOutboundMessage` in
+`src/server/routes.ts` and adds a `postToUpdatesTopic` helper both the route and the
+publisher share. New config keys (`digestDelivery`, `digestTimezone`,
+`digestSendOnCalmWeeks`) land in `ConfigDefaults.ts` + `types.ts`; wiring + teardown in
+`AgentServer.ts`. Ships dark (`digestDelivery: 'off'` by default, even on a dev agent).
+
+## Decision-point inventory
+
+- `evaluateOutbound` (`src/server/routes.ts`) — **add** — pure res-free extraction of the
+  localhost-link guard + tone-gate decision out of `checkOutboundMessage`. Both the route
+  adapter and the publisher's `postToUpdatesTopic` call this single function.
+- `checkOutboundMessage` (`src/server/routes.ts`) — **modify** — now a thin route adapter:
+  fires the two observe-only observers (route-side) + delegates the decision to
+  `evaluateOutbound` + maps the decision to res. Behavior byte-identical for callers.
+- `postToUpdatesTopic` (`src/server/routes.ts`) — **add** — the publisher's guarded sender:
+  resolve Updates topic → `evaluateOutbound` → `sendToTopic`. Returns a flat DeliveryResult.
+- `GrowthDigestPublisher.publishOnce` — **add** — the lease-gate → mode → in-flight →
+  calm → format → deliver decision chain. The publisher holds NO authority: it only sends
+  a message or stays quiet; a guard block is a normal, non-error outcome it never re-acts on.
+- `digestDelivery` / `digestSendOnCalmWeeks` / `digestTimezone` config — **add** — the
+  rollout + cadence dials under `monitoring.growthAnalyst`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The `evaluateOutbound` extraction preserves the EXACT block/allow logic of the prior
+`checkOutboundMessage` (localhost-link guard + tone gate). No new block surface is added;
+the decision function returns the same 422 bodies for the same inputs (verified by the
+existing `post-update-gate-budget-route`, `localhost-link-guard-route`, and
+`outbound-content-dedup-route` suites — all 20 tests pass unchanged). The publisher itself
+adds no block/allow surface — it is a sender, not a gate. Over-block: not applicable to the
+new code; preserved for the refactored code.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The publisher's bounded multi-machine handoff edge (§3.7): if a lease handoff falls between
+a window's fire time and the newly-awake machine's `.start()`/catch-up, that one window can
+be re-sent once (the per-machine audit log has no record of the old machine's send). This is
+a deliberately-accepted under-guard in the SAFE direction — a single bounded re-send through
+the same aggregating/budgeted/deduped funnel, biased toward "the check-in arrives" over
+"silently dropped," which is the slice's entire reason to exist. The near-simultaneous case
+is absorbed by the shared `evaluateOutbound` dedup. No new under-block in the message-gate
+logic (the refactor is behavior-preserving).
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Correct layers. The publisher is a thin cadence/delivery wrapper (low-level orchestration)
+that DELEGATES the block/allow decision to the existing smart gate via the shared
+`evaluateOutbound` — it does not re-implement guarding. The formatter is a pure render with
+no decision authority (the analyst already decided what crosses a rule). The funnel
+extraction is specifically a level-of-abstraction fix: it ensures the publisher FEEDS the
+existing chokepoint rather than running a parallel un-guarded `sendToTopic`. The two
+observe-only observers (`observeSelfViolation`, `observePrincipalCoherence`) deliberately
+stay route-side, not in `evaluateOutbound` — they have nothing to catch on a proactive
+digest (it credits no operator role and is authored by no principal), so keeping them out
+of the shared funnel both preserves byte-identical caller behavior and avoids meaningless
+telemetry.
+
+---
+
+## 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 (the publisher is a sender; the
+  refactored `evaluateOutbound` keeps the SAME smart gate — `messagingToneGate`, an
+  LLM-backed authority with recent conversational context — as the sole decider).
+
+The publisher produces a message or stays silent; it never blocks, delays, or rewrites
+anything. The §3.5 superseded-job belt is a SIGNAL (an audit line), never a cross-component
+mutation — the publisher never disables another component's job. The funnel extraction
+keeps the single smart authority (`messagingToneGate`) and merely makes the publisher route
+through it rather than around it. No brittle detector gains block authority.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** `evaluateOutbound` runs the same localhost-guard-then-tone-gate order as
+  before; `checkOutboundMessage` still fires the two observers FIRST (route-side), so no
+  existing route caller's observation is shadowed. The publisher path intentionally does NOT
+  fire those observers (nothing to catch) — confirmed not relied on for the digest path.
+- **Double-fire:** the in-process cron runs on BOTH the awake and standby machine → the
+  lease gate (`isAwake`) ensures only the awake machine sends (mirrors the
+  scheduler/ActivitySentinel precedent the superseded `initiative-digest-review` relied on).
+  The superseded job + the publisher both fire `0 11 * * 1` — handled by §3.5 (durable
+  source-template disable at the live-flip, NOT at this dark merge; while `digestDelivery`
+  is `off`/`dry-run` the publisher doesn't send, so the job stays the sole voice).
+- **Races:** the in-flight guard + croner `protect:true` prevent overlapping `publishOnce`
+  passes. The audit log is the single shared state; window-key idempotency is recorded only
+  on a real post-lease decision.
+- **Feedback loops:** none — the digest reads analyst state and emits one message; it feeds
+  no system that feeds back into the analyst.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** none — internal component, no shared external state.
+- **Install base:** none at merge — ships `digestDelivery: 'off'`; existing agents get the
+  three new config defaults via `applyDefaults` add-missing-only deep-merge (no migrateConfig
+  needed, matching the rest of the `growthAnalyst` block). No CLAUDE.md template change at
+  this dark merge (it rides the live-flip per the Agent Awareness Standard, parent §9).
+- **External systems (Telegram):** only when an operator flips `digestDelivery` to
+  `dry-run`/`live` — and then it sends ONE message into the EXISTING Agent Updates topic via
+  the same guarded path as `/telegram/post-update`. Never a new topic, never per-finding.
+- **Persistent state:** a new append-only audit log at `logs/growth-digest.jsonl`
+  (best-effort, never throws). No DB, no schema change.
+- **Timing:** the weekly cron + a 60s settle-delayed catch-up; the cadence sanity-floor
+  refuses a sub-hourly `digestCron`.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change shipping dark — revert and ship a patch. No persistent state needs cleanup
+(`logs/growth-digest.jsonl` is an inert append-only log; leaving it is harmless). No agent
+state repair (the publisher is simply not constructed when `digestDelivery: 'off'`). No
+user-visible regression during the rollback window, because at merge nothing is sent
+(default off). The `evaluateOutbound` extraction is behavior-preserving and covered by the
+pre-existing route suites, so reverting it carries no caller-facing risk either.
+
+---
+
+## Conclusion
+
+This review found no new block/allow surface and no signal-vs-authority violation: the
+publisher is a sender that delegates every guard decision to the existing smart gate via a
+deliberately-extracted single funnel, closing off the "second un-guarded send path" the
+review flagged in the draft. The multi-machine double-send (the one SERIOUS finding from
+convergence) is fixed by the lease gate; the bounded handoff re-send is an accepted,
+SAFE-direction tradeoff. The change ships dark with zero user-facing surface at merge, so
+rollback is a plain revert. Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+
+The change carries a converged + approved Tier-2 spec
+(`docs/specs/PROACTIVE-GROWTH-DIGEST-PUBLISHER-SLICE2-SPEC.md`) reviewed by an 8-reviewer
+panel (security, scalability, adversarial, integration, lessons-aware + gemini) over 3
+iterations; the convergence report is the independent-read record.
+
+---
+
+## Evidence pointers
+
+- `src/monitoring/GrowthDigestPublisher.ts` — the publisher + pure `formatDigest` +
+  `createGrowthDigestAuditSink`.
+- `src/server/routes.ts` — `evaluateOutbound` (pure funnel), `checkOutboundMessage`
+  (thin adapter), `postToUpdatesTopic` (publisher sender), `attachSender` hookup.
+- `src/server/AgentServer.ts` — construction gate (`analyst && digestDelivery !== 'off'`),
+  lease gate (`isAwake`), `.stop()` teardown.
+- `tests/unit/GrowthDigestPublisher.test.ts` — 21 tests (publishOnce matrix, lease gate,
+  in-flight guard, missed-run catch-up idempotency, sanity-floor, formatter guarantees).
+- `tests/integration/growth-digest-publisher.test.ts` +
+  `tests/integration/growth-digest-publisher-wiring.test.ts` — guarded delivery + single-
+  funnel + sender-not-a-no-op + lease-gate wiring (10 tests).
+- `tests/e2e/growth-digest-publisher-lifecycle.test.ts` — boots the real AgentServer:
+  LIVE lands one check-in in the Updates topic; OFF / no-analyst → publisher null (3 tests).
+- `tests/integration/notification-flood-burst-invariant.test.ts` — 500-finding burst → one
+  bounded message, high-priority finding rendered in full.
+- `npm run lint` clean (incl. dev-agent-dark-gate); analyst + ConfigDefaults regression
+  suites green (80 tests).

package/upgrades/side-effects/throwaway-identity-helper.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — throwaway-identity helper
+
+**Version / slug:** `throwaway-identity-helper`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Tier:** `1` (standalone test-tooling script + lib + hermetic test; no runtime/gate/config wiring)
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds `scripts/lib/throwaway-identity.mjs` (importable) + `scripts/throwaway-identity.mjs`
+(CLI) — mints genuinely-distinct, readable throwaway email inboxes via the mail.tm public
+disposable-mailbox API, and polls/extracts codes+links from them. The autonomous half of
+test-identity provisioning for live-integration test harnesses (Slack/Discord/…). + a fully
+hermetic unit test (injected fetch + clock, no network) and an ELI16.
+
+## Decision-point inventory
+
+None in runtime — it's standalone tooling, never imported by `src/` or wired into a gate.
+Internal branch points (domain selection, message-match filter, timeout) are pure functions
+covered by the test.
+
+## 1. Over-block
+
+Nothing is rejected at runtime. The tool only calls a public disposable-mail API and reads
+inboxes it just created. It is not on any agent code path.
+
+## 2. Under-block
+
+It deliberately does NOT cover the anti-bot signup CAPTCHA at workspace/account creation —
+that is a human-verification control and remains a ~30s human handoff (documented in the
+live-run runbook). It is the email half only.
+
+## 3. Level-of-abstraction fit
+
+Right layer: a `scripts/` + `scripts/lib/` test utility beside the other dev/test scripts,
+with the HTTP injected so the test is hermetic. Reusable by any integration's live harness,
+not coupled to the permission gate.
+
+## Migration / rollback
+
+No migration (standalone tooling). Rollback = delete the two scripts + the test.
+
+## Testing-integrity note
+
+15 hermetic unit tests (pure extractors + the full mint / poll-until-match / timeout flow,
+HTTP + clock injected). A separate live CLI smoke confirmed it mints a real inbox
+(`echo-…@web-library.net` + token). `tsc --noEmit` clean.