instar 1.3.206 → 1.3.207

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-02T20:50:08.043Z",
-  "instarVersion": "1.3.206",
+  "generatedAt": "2026-06-02T21:28:59.172Z",
+  "instarVersion": "1.3.207",
   "entryCount": 195,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1490,7 +1490,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/AutoUpdater.ts",
-      "contentHash": "9a679f1b322237ea5022657900d1f07cd3c201cd458baa89090c696042b6c1d3",
+      "contentHash": "60802cc5aad744cad139c5f5c0b1e4b27468c0a27b38384804ed09a6aa4e081c",
       "since": "2025-01-01"
     },
     "subsystem:auto-dispatcher": {
@@ -1506,7 +1506,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "90bfb6c540825ac2bf3393e22c4b7ae324159407acaac58b2c464762ef69901a",
+      "contentHash": "797a5827842944d872077473dc0d87a1f99601f33d5f262e272748731d68250b",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates.ts

@@ -466,6 +466,7 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - The endpoint resolves the Updates topic from state server-side; you cannot specify a topic and you should not try to.
 - If Updates is not configured, the endpoint returns 400 — do NOT fall back to sending in the active topic. Update-class messages belong in Updates or they don't go out at all.
 - **When to use** (PROACTIVE — this is the trigger): the moment I am about to author a conversational message whose subject is *me* shipping, updating, or restarting — including post-restart "I'm back" confirmations — I use this endpoint. Authoring such a message via the standard Telegram reply path puts release chatter into whatever conversation the user was last in, which is the bug this routing closes.
+- **Maturity honesty (silent-by-default user announcements)**: user-facing update announcements are *opt-in and maturity-tagged*, authored in the release's upgrade guide (\`user_announcement\` front-matter: each change is \`audience: user|agent-only\` + \`maturity: experimental|preview|stable\`). The post-update notifier stays SILENT unless a change was explicitly promoted to \`audience: user\`, and experimental/preview features are announced as such (⚗️ Experimental / 🧪 Preview) — never implied to be finished. When I narrate my own ship here, I mirror that honesty: I do NOT announce a feature that ships dark/disabled as if it works, and I don't dress up an infra change as a finished capability. Patch-level "restarting…" notices are suppressed (only deferral warnings — "your work is holding a restart" — still surface).
 
 **Secret Drop** — Securely collect secrets (API keys, passwords, tokens) from users without exposing them in chat history.
 - Request a secret: \`curl -X POST -H "Authorization: Bearer $AUTH" http://localhost:${port}/secrets/request -H 'Content-Type: application/json' -d '{"label":"OpenAI API Key","description":"Needed for GPT integration","topicId":TOPIC_ID}'\`

package/upgrades/1.3.207.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+User-facing update announcements are now **opt-in and maturity-tagged**. A new
+pure helper (`src/core/upgradeAnnouncement.ts`) parses a `user_announcement`
+front-matter block in the release upgrade guide — each notable change carries an
+`audience` (`user` or `agent-only`) and a `maturity` (`experimental` / `preview`
+/ `stable`).
+
+- **UpgradeNotifyManager** is now silent-by-default: with no `audience: user`
+  entry it skips the user message entirely (still updating MEMORY.md and
+  acknowledging), and with entries it composes only from them using honest
+  maturity framing + badges (⚗️ Experimental / 🧪 Preview). The old "lead with
+  the biggest user-visible feature" instruction is gone.
+- **UpgradeGuideProcessor** hoists and merges each guide's `user_announcement`
+  block to the top of the concatenated pending guide, so the decision survives
+  multi-guide batches (a no-op when no guide carries a block).
+- **AutoUpdater + the restart handshake** suppress the bare patch-level "Just
+  updated… restarting" narration while keeping the restart-hold warnings;
+  restart verification is preserved via an empty deferred notification.
+- **analyze-release.js** scaffolds the block (defaulting every entry to
+  `agent-only`) on `--draft-guide`, and warns at authoring time when a
+  user-relevant release carries no block at all.
+- Existing agents receive the maturity-honesty guidance through a
+  `PostUpdateMigrator` CLAUDE.md migration (new agents get it from the template).
+
+Parent principle: **Near-Silent Notifications**. Spec:
+`docs/specs/mature-update-announcements.md`.
+
+## What to Tell Your User
+
+- **Quieter, more honest updates**: "I'll only message you about an update when
+  it's genuinely relevant and ready for you, and I'll be upfront when something
+  is still experimental instead of making it sound finished. You'll get fewer
+  pings and clearer ones."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Maturity-tagged, opt-in update announcements | Authored in the release upgrade guide's `user_announcement` front-matter; the notifier stays silent unless a change is promoted to the user |
+| Honest maturity framing | Experimental and preview features are labeled as such, never narrated as finished |
+| Quieter restarts | Patch-level "restarting" notices are suppressed; restart-hold warnings still surface |

package/upgrades/side-effects/mature-update-announcements.md

@@ -0,0 +1,149 @@
+# Side-Effects Review — Maturity-aware, silent-by-default user update announcements
+
+**Version / slug:** `mature-update-announcements`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Second-pass reviewer:** `3 independent adversarial reviewers (design / correctness / integration) — internal convergence`
+
+## Summary of the change
+
+Stops the post-update notifier from overselling unfinished features (the trigger:
+infancy-stage Gemini CLI support narrated as "just got more reliable"). User-facing
+update announcements become OPT-IN + maturity-tagged, authored in the release's
+upgrade guide (`user_announcement` front-matter). Touches: `src/core/upgradeAnnouncement.ts`
+(new pure helper), `src/core/UpgradeNotifyManager.ts` (silent-by-default compose),
+`src/core/UpgradeGuideProcessor.ts` (hoist/merge blocks to byte 0), `src/core/AutoUpdater.ts`
++ `src/commands/server.ts` (Fork 3: suppress patch-level restart narration, preserve
+handshake verification), `scripts/analyze-release.js` (draft block + forgot-block advisory),
+`src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` (agent-awareness guidance).
+Decision points touched: the post-update *announce/skip* decision and the *restart-narrate/suppress*
+decision.
+
+## Decision-point inventory
+
+- `UpgradeNotifyManager.buildPrompt announce-vs-skip` — **modify** — was "always compose, lead with the biggest feature"; now composes only from `audience: user` entries, skips entirely when there are none.
+- `AutoUpdater restart-narration` — **modify** — was "narrate on every active-session restart"; now suppresses the bare narration for patch-only bumps (deferral warnings unchanged).
+- `analyze-release forgot-block advisory` — **add** — a non-blocking author-facing warning when a user-relevant release carries no announcement block.
+- `UpgradeGuideProcessor block hoist` — **add** — assembles a merged front-matter block at byte 0 (no decision authority; pure data-flow plumbing).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The "block" surface here is the announce/skip decision. Silent-by-default means a
+*genuinely user-ready* feature is "over-blocked" (not announced) if the release author
+forgets to add a `user_announcement` block. This is the one real over-block risk and was
+raised by the design reviewer. Mitigations: (a) `analyze-release --draft-guide` scaffolds
+the block for every feature/enhancement, so the author is structurally prompted to promote
+the user-facing ones; (b) the main-path forgot-block advisory fires when a user-relevant
+release has no block at all. The fail-safe direction is deliberate: silence (recoverable
+with a follow-up note) is preferable to today's failure of a misleading announcement.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+An author can still *mislabel* maturity — mark an experimental feature `stable, audience: user` —
+and the system will compose a confident message. The forgot-block advisory only catches total
+absence of the block, not a wrong maturity inside it. This is accepted: maturity is a human
+judgment authored with the release notes (the Body-and-Mind "author decides" layer); we
+deliberately did NOT add a brittle headline→rollout-stage map in CI to police it (it would be
+fragile and is the wrong layer). The restart-suppression "under-block": a patch bump that is
+secretly disruptive gets no narration — but the deferral warnings and the failed-restart
+escalation still fire, so a genuinely stuck restart is still surfaced.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The announce decision is authored at release time (in the upgrade guide), not improvised
+by a throwaway notify session — that was the core design move. The notify-side helper
+(`upgradeAnnouncement.ts`) is a pure renderer/parser (a low-level primitive). The forgot-block
+guard lives in the release analyzer (the only layer with the "brand-new feature" signal and the
+author's attention) — during convergence we *moved* the coherence check there and removed an
+orphaned TS function that would have been a parallel implementation. The hoist lives in the
+processor (the layer that already assembles the pending guide). No re-implementation of an
+existing primitive; no gate running parallel to a smarter one.
+
+## 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 — the brittle pieces are signals; the only authorities are deterministic, fully-enumerable policy.
+
+The forgot-block advisory is a **signal** (a non-blocking `log()` line; the author decides). The
+announce/skip decision is a deterministic policy over a fully-enumerable input ("are there
+`audience: user` entries?") — not brittle pattern-matching. The restart-suppression decision is
+deterministic over `crossesBreaking(prev, next)` (a pure semver observation that fails safe to
+"narrate" on malformed input). No LLM-free brittle check holds blocking authority. All three
+adversarial reviewers independently affirmed signal-vs-authority compliance.
+
+## 5. Interactions
+
+- **Shadowing:** the announcement front-matter is hoisted to byte 0 *above* the existing
+  `# Instar Upgrade Guide` header and `<!-- bump: -->` marker. Verified the bump-marker regex,
+  the publish-gate validator (`validateGuideContent` uses `includes`, no first-line requirement),
+  `assemble-next-md.mjs`, and `check-upgrade-guide.js` all tolerate leading front-matter.
+- **Double-fire:** the notify session's Step-1 send and the AutoUpdater restart narration are
+  distinct topics/paths; no overlap. The handshake is written once per version (existing dedup
+  guard unchanged).
+- **Races:** none introduced — the processor assembly is single-pass synchronous; no shared
+  mutable state added.
+- **Feedback loops:** none.
+
+## 6. External surfaces
+
+- **Other agents:** the CLAUDE.md template + `migrateClaudeMd` change is the only agent-visible
+  surface; it adds guidance, removes nothing.
+- **Users:** fewer/quieter update messages (the intended UX change). Patch-level "restarting…"
+  messages disappear; deferral warnings remain.
+- **External systems (Telegram):** the post-update topic receives fewer messages; format of any
+  message that DOES send is unchanged except for the experimental/preview badges.
+- **Persistent state:** none. No new files/columns/ledgers. The handshake file is written exactly
+  as before (only its `deferredNotification` may now be empty for patch bumps; the server skips
+  empty emits and still clears the file).
+- **Timing:** none beyond the existing restart timing.
+
+## 7. Rollback cost
+
+**Pure code change — revert the commit, ship as next patch.** No persistent state, no data
+migration, no agent-state repair. The `migrateClaudeMd` addition is idempotent and additive
+(reverting simply stops adding the section to new updates; already-patched CLAUDE.md files keep a
+harmless guidance paragraph). No user-visible regression during the rollback window — worst case
+reverts to the prior (louder, less honest) announcement behavior.
+
+## Conclusion
+
+The review (three independent adversarial passes — design, correctness, integration) returned a
+unanimous SHIP-WITH-MINOR-FIXES with no blockers. Three findings were acted on before commit:
+(1) added the required `migrateClaudeMd` migration parity for the maturity-honesty guidance;
+(2) added the author-facing forgot-block advisory to mitigate the silent-by-default over-block
+risk; (3) removed the orphaned `announcementCoherenceWarnings` TS helper (un-wired dead code) and
+relocated the coherence concern to the release analyzer where the signal actually exists — keeping
+`upgradeAnnouncement.ts` focused on the notify path. A correctness reviewer's serialize↔parse
+round-trip gap was closed with an explicit unit test. The change is clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** internal multi-reviewer convergence (design / correctness / integration)
+**Independent read of the artifact: concur**
+
+All three reviewers concurred the design is sound (signal-vs-authority + Body-and-Mind compliant,
+correct level of abstraction) and the implementation is correct and alive end-to-end. The minor
+fixes they raised are incorporated above; no residual concerns block the ship.
+
+---
+
+## Evidence pointers
+
+- Affected-set test run: 11 files / 134 tests green (unit helper, compose branches, processor
+  hoist + no-op, analyze-release round-trip + forgot-block advisory, migration parity, AutoUpdater
+  Fork-3 patch-suppression + minor-narrates, e2e upgrade-guide lifecycle).
+- Spec: `docs/specs/mature-update-announcements.md` (`review-convergence: internal-multi-reviewer-2026-06-02`, `approved: true`).
+- ELI16: `docs/specs/mature-update-announcements.eli16.md`.