instar 1.2.72 → 1.2.74

package/upgrades/1.2.74.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — one ranked working set across the memory stores
+
+<!-- bump: minor -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+
+## What Changed
+
+**The memory stores now feed one ranked reading list instead of three separate ones.**
+
+Topic-intent (conversation facts + task frame), Playbook (tagged context items),
+and semantic/episodic memory each had their own read path and ranking. This unifies
+the **reading**: the existing working-memory assembler — already a token-budgeted
+multi-source context builder — now also draws from topic-intent and Playbook, and
+ranks everything together by relevance blended with a recency-decay factor (so
+fresher, more-relevant context floats up; stale context sinks but isn't deleted and
+re-warms on reference).
+
+The important design choice (ratified): this unifies the **reading, not the
+storage**. The three stores keep their own backends and write paths; the assembler
+is the single unified read. That makes it additive and reversible — and it's
+guarded by a regression pin: **when the new sources are empty, the assembled
+context is byte-for-byte what it was before.** Playbook is read straight from its
+manifest files (no Python invoked in the hot assembly path), and every new source
+is degrade-safe — a missing or erroring source contributes nothing and never
+breaks assembly.
+
+The result shows up as a "Working Set" section in the assembled context
+(`GET /session/context/:topicId`), drawing from all sources under one budget, with
+per-source contribution visible in the response's `sources`.
+
+**Evidence**: 11 new tests (8 unit — blended ranking, both source adapters,
+degrade-safety, and the regression pin; 3 boot-path route tests confirming the
+unified read path is alive and surfaces topic-intent in a Working Set section, and
+that a ref-less topic is unchanged). The existing 49 assembler + working-memory
+tests stay green (the regression pin, confirmed). `tsc` + lint clean.
+
+Spec: `docs/specs/cwa-unify-stores.md` (approved; Claude-authored + manual review —
+this is the most architectural rung, fuller multi-model review advisable, caveat
+ratified). ELI16: `docs/specs/cwa-unify-stores.eli16.md`. Side-effects:
+`upgrades/side-effects/cwa-unify-stores.md`.
+
+## What to Tell Your User
+
+- **One sorted view of what matters**: "I used to keep 'what's relevant right now'
+  in three separate notebooks that didn't talk to each other. Now they feed one
+  ranked reading list, so when we pick something up I get a single sorted view —
+  freshest and most-relevant first — instead of three half-answers."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Unified working set in assembled context | Automatic — `GET /session/context/:topicId` now includes a "Working Set" section drawing from topic-intent + Playbook + memory |
+| Blended relevance×recency ranking across sources | Automatic (the assembler ranks all sources together) |
+
+## Evidence
+
+Not a bug fix — a new capability over the existing assembler. Verified by 11 new
+tests including 3 that boot the real AgentServer and confirm the assembled-context
+route surfaces a topic-intent ref in a "Working Set" section, plus a regression pin
+(unit + the unchanged existing 49-test suites) proving the assembled output is
+identical when the new sources are empty. `tsc` + lint clean.

package/upgrades/side-effects/cwa-unify-stores.md

@@ -0,0 +1,83 @@
+# Side-effects review — unify the working-awareness stores (rung 2)
+
+**Scope**: Give the working-awareness stores one ranked read path. Per the
+ratified spec (`docs/specs/cwa-unify-stores.md`), this unifies the READ — extends
+the existing `WorkingMemoryAssembler` to draw topic-intent refs + Playbook
+manifest items into one ranked working-set section — NOT a physical store
+migration. Additive, reversible, regression-pinned.
+
+**Files touched**:
+- `src/memory/WorkingSet.ts` — NEW. The `WorkingSetItem` lingua franca +
+  `blendedScore`/`rankWorkingSet` (relevance × recency-decay) + two read-only,
+  degrade-safe source adapters: `topicIntentToWorkingSet` (refs at/above tentative
+  → items; relevance = confidence, recency = lastReinforcedAt) and
+  `playbookManifestToWorkingSet` (scans `{stateDir}/playbook/**.json` manifests,
+  trigger/tag-gated by the query, relevance = match + usefulness, recency =
+  freshness — **never invokes the Python scripts**).
+- `src/memory/WorkingMemoryAssembler.ts` — optional `topicIntentStore` + `stateDir`
+  config; `workingSet` token budget (default 500); a new "Working Set" section
+  appended AFTER the existing knowledge/episodes/relationships sections, gated on
+  the new deps + content; `assembleWorkingSet`/`renderWorkingSet`; section header.
+- `src/commands/server.ts` — pass `topicIntentStore` + `stateDir` to the assembler
+  and broaden its construction gate to include `topicIntentStore` (so the unified
+  read path is available even in minimal setups).
+
+**Under-block**: None. The new section is purely additive context; it gates
+nothing. Each new source is read-only and wrapped so an error/absence contributes
+nothing.
+
+**Over-block**: None. No authority anywhere — the assembler informs context, it
+doesn't decide.
+
+**Level-of-abstraction fit**: The stores keep their backends and write paths; only
+the READ is unified, via the assembler that already does token-budgeted
+multi-source assembly. The new sources speak the same `WorkingSetItem` shape and
+flow through the same budget + render machinery. Playbook is read at the manifest
+level (a stable JSON file), not through its Python CLI — the right seam for a fast,
+degrade-safe assembler.
+
+**Signal vs authority**: N/A — pure read/ranking.
+
+**Interactions**:
+- **REGRESSION PIN (load-bearing):** the working-set section is appended after the
+  existing three and only when `topicIntentStore || stateDir` is configured AND a
+  source returns content. With the new deps absent OR their sources empty, the
+  assembled output is byte-for-byte unchanged — verified by (a) a dedicated unit
+  test, (b) the existing 26 assembler unit tests + 9 working-memory route tests +
+  the assembler-context route tests all still green, (c) a route test asserting a
+  ref-less topic yields no working-set section.
+- The assembler construction gate broadened to include `topicIntentStore` (always
+  present), so the assembler now constructs in more setups. This is additive —
+  callers in minimal setups gain a working-set context they didn't have; existing
+  setups' output is unchanged (pin).
+- The new section draws only from REMAINING token budget after the existing
+  sources, so it cannot starve them.
+- Playbook manifest scan is bounded (depth-limited, per-file try/catch) and
+  trigger-gated (empty query → no Playbook items), so it can't flood or slow
+  assembly.
+
+**External surfaces**: New module `src/memory/WorkingSet.ts` (exports
+`WorkingSetItem`, `blendedScore`, `rankWorkingSet`, the two adapters). New optional
+assembler config fields + a `workingSet` budget. The assembled-context HTTP routes
+now MAY include a "Working Set" section. No new endpoint, no config-shape change
+for users (the assembler deps are wired server-side).
+
+**Deferred (tracked)**: deeper cross-source blended re-ranking of the existing
+sources (`cwa-physical-store-merge` rejected; cross-blend is implicit future work),
+the Usher / mid-task re-surfacing (`cwa-usher`), capability+standards descriptors
+as sources (`cwa-capability-index-context`). All in the spec's non-goals.
+
+**Rollback cost**: Low. Drop the working-set section + the two adapter calls (or
+just don't pass `topicIntentStore`/`stateDir`); the assembler returns to its
+current three sources. No data migration. The regression pin guarantees the
+revert is a no-op for existing output.
+
+**Migration parity**: Additive assembler sources + budget default + the broadened
+construction gate — all server-side (every agent gets it on update). No store
+schema change, no hook/template/skill change, no user config change required.
+
+**Convergence honesty**: Claude-authored + manual review; full multi-model
+convergence tooling absent on host. This is the most architectural rung (touches
+the shared assembler), so the regression pin is the primary safety and a fuller
+multi-model review remains advisable — but the pin + the unchanged existing suites
+bound the risk tightly.

package/upgrades/side-effects/never-a-false-blocker-standard.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — Never a False Blocker (B17_FALSE_BLOCKER)
+
+**Slug:** `never-a-false-blocker-standard`
+**Date:** 2026-05-24
+**Author:** echo
+**Second-pass reviewer:** internal adversarial convergence (two reviewers) + real-LLM test-as-self
+
+## Summary of the change
+
+Adds the constitution standard "Never a False Blocker" to `docs/STANDARDS-REGISTRY.md` and its structural enforcement: a new always-evaluated rule **B17_FALSE_BLOCKER** in `MessagingToneGate` (the outbound-message authority that hosts B15/B16). B17 holds an outbound message that defers a doable task to a person — "needs a human / I can't / second opinion / reverse-engineering" — when the message names no genuinely-human-only item and shows no inventory of the agent's own means (computer use, terminal, send-keys, MCP). The `deferral-detector` PreToolUse hook is extended (signal-only) to prime the inventory checklist for the new excuse-shapes. Registers the standard in `docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md` (P12). The sibling of B16 — feasibility-surrender (B16) vs human-deference (B17).
+
+## Decision-point inventory
+
+- `VALID_RULES` set — **add** `'B17_FALSE_BLOCKER'`. Without this the gate's drift-detection fails-open on a legitimate B17 citation (verified: a real-LLM B17 citation is accepted, `failedOpen=false`).
+- `buildPrompt()` rule section — **add** the B17 definition after B16 (always-evaluated, no precondition), including the B16/B17 de-confliction + straddle handling + citation precedence (B15>B16>B17) + the UI-interaction clarification + a worked block example.
+- Response-format enumeration + two doc comments (`B1..B16`→`B1..B17`) — **modify**.
+- `deferral-detector` template (`PostUpdateMigrator.getDeferralDetectorHook`) + the deployed copy — **add** `needs_human_to` / `needs_reverse_engineering` patterns and a guarded `wants_second_opinion` (suppressed when a model/agent is named, so self-fetched cross-model review is not flagged). Checklist text updated to name the agent's own means + the tiny human-only set.
+- No route changes: `checkOutboundMessage` → 422 is rule-agnostic; B17 rides the existing outbound paths.
+
+## 1. Over-block
+
+Principal risk: blocking legitimate escalations. Mitigated — severity favors false-negatives, and the allowlist explicitly passes: a password/secret only the user holds, CAPTCHA, legal/billing/payment authorization, **required approvals** (side-effects/policy-gated), **account/access grants**, **external rate-limit/quota waits**, genuine value judgments, deferrals after a named-outcome inventory, self-fetched cross-model review, and rule-discussion. Real-LLM test-as-self confirmed password escalation, value-judgment, and required-approval all PASS while the founding false-blocker BLOCKS — no false-positive introduced by the precision-tightening.
+
+## 2. Under-block (a real false blocker slipping through)
+
+Two known holes, both accepted by design:
+- The gate sees only message text, so a **fabricated inventory** ("I tried everything, your call") can pass — same limit as B16, stated honestly in the rule. Mitigated by requiring *named outcomes* (not bare tool names); the hollow-inventory case is a unit assertion.
+- Borderline misses are acceptable per the false-negative-favoring posture. Test-as-self caught the founding case passing initially and the prompt was tightened (UI-interaction clarification + worked example) until real Haiku blocked it.
+
+## 3. Level-of-abstraction fit
+
+Correct: the block authority lives inside the single outbound authority (where B15/B16 live), not in the detector. The `deferral-detector` extension is signal-only (injects `additionalContext`, never blocks). Signal-vs-authority compliant.
+
+## 4. Blocking authority
+
+No new brittle authority. B17 is one more rule the existing authority may cite; the 422 plumbing and fail-open behavior are inherited unchanged.
+
+## 5. Interactions
+
+B17 is always evaluated alongside B15/B16 in one LLM call — no extra calls, marginally longer prompt. De-conflicted from B16 (missing mechanism → B16; person required → B17; the straddle → B17) with explicit citation precedence B15>B16>B17 so telemetry is deterministic. Drift-detection unaffected (an invented rule id still fails open — regression test included). The detector's orphan-TODO patterns are preserved (the regenerated deployed copy carries them, so migration does not regress that prior improvement).
+
+## 6. External surfaces
+
+None. No new endpoints, credentials, or network calls.
+
+## 7. Rollback cost
+
+Low. Reverting removes the rule from the set + prompt, the detector patterns, and the doc entries; no state, no migration, no schema. An older server simply lacks the rule.
+
+## 8. Test evidence
+
+- Unit (`messaging-tone-gate-b17.test.ts`, 13 tests) + integration (`telegram-reply-b17-false-blocker.test.ts`, 2 tests) green; tsc clean; smoke suite (62 files / 2371 tests) green.
+- Detector behaviorally exercised: false-blocker and reverse-engineering payloads flag; self-fetched cross-model review and clean status messages do not.
+- **Real-LLM test-as-self** (real `ClaudeCliIntelligenceProvider` → Haiku, in-process against the built rule, production server untouched): founding codex-trust message + the fused straddle both BLOCK with B17; password escalation, value judgment, required approval, self-fetched second opinion, and post-inventory deferral all PASS.