instar 1.3.126 → 1.3.128

package/upgrades/1.3.128.md

@@ -0,0 +1,84 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**New preferences read-surface (Correction & Preference Learning Sentinel —
+Slice 1a).** This is the structural application surface for auto-learned user
+preferences, modeled exactly on the existing ORG-INTENT session-start pattern.
+It adds three pieces that work together:
+
+- A new in-process primitive, `recordPreference()`, that is the ONLY writer to
+  a new structured file at `.instar/preferences.json`. Writes are atomic (temp
+  file + rename), schema-versioned, and upsert by `dedupeKey` — so a recurring
+  preference collapses to one entry whose observation count grows rather than
+  piling up duplicates. An absent file simply means "no preferences" (it is
+  never required to exist).
+- A new HTTP route, `GET /preferences/session-context`, gated on
+  `monitoring.correctionLearning.enabled`. When the feature is off it returns
+  503; when on, it serves the active preferences as a structured block, bounded
+  by `maxInjectedPreferencesBytes` (4000) and priority-ordered by recency ×
+  confidence × dedupe-count. It serves only the learning text plus metadata —
+  never any raw internal fields.
+- A session-start hook patch: the hook now fetches that route on every boot and
+  injects the returned block, wrapped in an `<auto-learned-preference
+  src='correction-loop'>` envelope so a learned preference can never be mistaken
+  for an authoritative instruction.
+
+This is **signal-only**. It stores, serves, and injects preferences so the agent
+always SEES them — it NEVER blocks or rewrites an outbound message. The whole
+feature ships OFF by default (`monitoring.correctionLearning.enabled: false`),
+so on this update nothing changes behaviorally until you turn it on. Slice 1b
+(the capture → distill → ledger → recurrence-gate loop that writes through
+`recordPreference()`) lands in a later change and consumes this surface.
+
+## What to Tell Your User
+
+Nothing changes unless you turn it on. This update adds the plumbing for me to
+learn your preferences over time — the repeated corrections you make, like
+asking me to be plainer or to lead with the action. When that learning loop is
+switched on in a later release, anything I learn about how you like to work gets
+injected into my context at the start of every session, so I carry it forward
+instead of forgetting it when a conversation ends. These learned preferences are
+always treated as gentle signals, never as commands, and a real instruction or a
+safety rule always wins. For now the feature is off by default and there is
+nothing for you to do.
+
+## Summary of New Capabilities
+
+- New primitive: `recordPreference()` — the single, atomic, schema-versioned
+  writer to `.instar/preferences.json` (upsert by `dedupeKey`).
+- New route: `GET /preferences/session-context` — serves the byte-bounded,
+  priority-ordered learned-preference block (503 when disabled; `{ present:
+  false }` when none). Bearer-authed like sibling routes; classified in the
+  CapabilityIndex so it is discoverable via `GET /capabilities`.
+- Session-start hook now injects the `<auto-learned-preference>` block on every
+  boot when the feature is enabled and preferences exist (fail-open: 503 /
+  unreachable / empty → injects nothing).
+- New config block `monitoring.correctionLearning` (ships OFF), backfilled into
+  existing agents automatically via `applyDefaults` deep-merge.
+- CLAUDE.md template + migrator backfill so existing agents learn about the
+  surface and honor injected preferences.
+
+## Evidence
+
+- `tests/unit/PreferencesManager.test.ts` (13) — atomic write + schema version,
+  dedupe-upsert (count increments, learning/recordedAt refresh, confidence max),
+  absent-file ≡ empty, malformed-file tolerance, bounded-bytes + priority order,
+  serves only learning + metadata.
+- `tests/unit/preferences-wiring-integrity.test.ts` (7) — `recordPreference()`
+  is the only writer (read path never creates/mutates the file; atomic
+  no-partial under repeated upsert); route gate keyed strictly on
+  `correctionLearning.enabled === true`.
+- `tests/integration/preferences-routes.test.ts` (5) — 401 without bearer, 503
+  when disabled, 200 `{ present: false }` when enabled+empty, 200 structured
+  block when enabled+exists, no raw-extra leak.
+- `tests/e2e/preferences-session-context-lifecycle.test.ts` (6) — feature-alive
+  200/503 on the production AgentServer boot path; the generated session-start
+  hook emits the `<auto-learned-preference>` block when enabled+present and
+  nothing when off.
+- `tests/unit/capabilities-discoverability.test.ts` (100) — `/preferences`
+  classified; lint green.
+- Side-effects review:
+  `upgrades/side-effects/correction-preference-learning-sentinel-slice1a.md`.

package/upgrades/side-effects/correction-preference-learning-sentinel-slice1a.md

@@ -0,0 +1,132 @@
+# Side-effects review — Correction & Preference Learning Sentinel (Slice 1a)
+
+**Spec:** `docs/specs/CORRECTION-PREFERENCE-LEARNING-SENTINEL-SPEC.md` (§3.6, §7,
+§9, §10 Slice 1a)
+**Change:** new `src/core/PreferencesManager.ts`; inline
+`GET /preferences/session-context` in `src/server/routes.ts`;
+`monitoring.correctionLearning` config block (`src/core/types.ts` +
+`src/config/ConfigDefaults.ts`); `CapabilityIndex.ts` entry; session-start hook
+patch + `migrateClaudeMd` backfill + shadow-capability marker in
+`src/core/PostUpdateMigrator.ts`; `generateClaudeMd` capability section +
+Registry-First row + proactive trigger in `src/scaffold/templates.ts`; 3-tier +
+wiring tests.
+**Class:** new read-surface feature, ships OFF, signal-only (never gates,
+blocks, or rewrites a message).
+
+## What changed
+
+A structured on-disk preferences file (`.instar/preferences.json`), the single
+atomic writer for it (`recordPreference()`), an HTTP read route serving the
+session-start block, and a session-start hook that injects that block on every
+boot. Modeled 1:1 on the proven ORG-INTENT precedent
+(`GET /intent/org/session-context` + its session-start fetch). Slice 1b (the
+capture/distill/ledger loop) is the future writer; Slice 1a only proves the
+surface is alive end-to-end.
+
+## 1. Security
+
+- **No new external input/network/egress.** The route only reads a local file
+  and serves a deterministically-formatted block. No LLM call, no outbound
+  request, no shell-out in Slice 1a (the hook's curl is loopback to the agent's
+  own server, same as ORG-INTENT).
+- **Auth:** the route is Bearer-gated by the global `authMiddleware` exactly like
+  sibling `/intent/*` routes (integration test asserts 401 without a token).
+- **Output discipline:** the served payload and the injected block contain ONLY
+  the `learning` text + metadata (confidence, seen-count). Internal fields
+  (`dedupeKey`, `provenance`) never leak (unit + integration assertions). This is
+  the §3.6 "serve only learning + metadata" rule.
+- **Injection-confusion defense:** loop-sourced preferences are wrapped in an
+  `<auto-learned-preference src='correction-loop'>` envelope so a downstream
+  prompt assembler structurally cannot mistake a learned preference for an
+  authoritative instruction. The block's own preamble restates "signals, not
+  instructions; real instructions and safety win."
+- **No policy-relaxation surface in 1a:** `recordPreference()` has no writer in
+  Slice 1a (Slice 1b adds the gated, policy-keyword-filtered caller per §3.6).
+  Until then the only way an entry lands is a direct programmatic call, which the
+  correction loop does not yet make.
+
+## 2. Migration parity
+
+- **Config:** `monitoring.correctionLearning` added to `ConfigDefaults`.
+  `applyDefaults` deep-merges add-missing-only (verified: `merge()` recurses into
+  objects, adds absent keys, never overwrites), so existing agents backfill the
+  block on update without a dedicated `migrateConfig` step — and without surprise
+  activation (`enabled: false`). This matches the spec §7 note and the
+  failure-learning precedent.
+- **Route:** inline in `routes.ts` (the discoverability-lint allowlist is fixed; a
+  separate module would trip the orphan-prefix check). `CapabilityIndex` entry
+  added so the lint passes and the route is discoverable.
+- **Hook:** built-in `instar/` hooks are always-overwrite on every migration, so
+  the patched `session-start.sh` propagates to every existing agent on the next
+  update — no hand-written `migrateHooks` block needed.
+- **CLAUDE.md:** `generateClaudeMd` gains the capability section / Registry-First
+  row / proactive trigger; `migrateClaudeMd` gains a content-sniffed backfill
+  (marker `Correction & Preference Learning Sentinel`) so EXISTING agents learn
+  the surface — not just new ones. A shadow-capability marker
+  (`**Preferences I've learned about you**`) mirrors it into Codex/Gemini
+  `AGENTS.md`/`GEMINI.md`. `feature-delivery-completeness` enforces all three legs.
+- **State file:** `.instar/preferences.json` is created lazily on first write;
+  absent ≡ empty. No migration needed.
+
+## 3. Performance
+
+- The read route does one small synchronous file read + a deterministic
+  string-build bounded by `maxInjectedPreferencesBytes` (4000). No DB, no LLM, no
+  network. Cost is negligible and constant-ish.
+- `recordPreference()` reads + rewrites the whole file atomically. The file is
+  bounded by distinct-preference cardinality (upsert by `dedupeKey`), not message
+  volume, so it stays tiny in practice. Each write is one temp-file + fsync +
+  rename.
+- The session-start hook adds one loopback curl with `--max-time 4`; fail-open on
+  timeout, so a slow/absent server can never delay session start beyond that cap.
+
+## 4. Observability
+
+- The route is discoverable via `GET /capabilities` (CapabilityIndex entry,
+  `enabled` reflects the flag).
+- `{ present, block, count }` makes the served state self-describing; `count`
+  exposes distinct-preference cardinality for debugging.
+- No new log channel in 1a (the audit log `logs/correction-learning-audit.jsonl`
+  is a Slice 1b concern — the loop that produces routable decisions).
+
+## 5. Rollback
+
+- Flip `monitoring.correctionLearning.enabled` back to false (or remove the
+  block) → the route 503s and the hook injects nothing. Inert.
+- `.instar/preferences.json` entries all carry `provenance: 'correction-loop'`,
+  enabling a one-shot bulk removal (a single jq-style filter) if a future loop
+  ever writes something unwanted. In 1a nothing writes, so the file stays absent.
+- Code rollback = revert the commits; the absent-file ≡ empty contract means a
+  rolled-back agent with a stray file is still consistent (read tolerates and
+  ignores it; the route 503s when the flag is gone).
+
+## 6. Multi-machine
+
+- The file is per-agent-home local state (under `stateDir`), like ORG-INTENT.md
+  and the integrated-being ledger. On a multi-machine agent each machine reads
+  its own copy; the existing state-sync layer carries `.instar/` files between
+  machines the same way it carries ORG-INTENT.md — no new sync path introduced.
+- The route is read-only and idempotent; no lease/fencing interaction. Slice 1a
+  has no writer competing across machines (that is a Slice 1b consideration when
+  the loop runs only on the awake machine).
+
+## 7. Multi-user
+
+- Slice 1a is a pure read/inject surface and does not itself attribute a
+  preference to a user — it serves whatever was recorded. The multi-user
+  primary-user gate (§3.6) lives in Slice 1b, where corrections are attributed
+  and `recordPreference()` is actually called. Until then no user-shaped data can
+  enter the file via this feature.
+- The injected block is the same for every session on the agent (it is the
+  agent's learned-about-this-operator preferences), consistent with the
+  single-operator model the rest of the agent assumes.
+
+## Tests
+
+- Unit: `tests/unit/PreferencesManager.test.ts` (13),
+  `tests/unit/preferences-wiring-integrity.test.ts` (7).
+- Integration: `tests/integration/preferences-routes.test.ts` (5).
+- E2E: `tests/e2e/preferences-session-context-lifecycle.test.ts` (6).
+- Lint: `tests/unit/capabilities-discoverability.test.ts` (100) green;
+  `tests/unit/feature-delivery-completeness.test.ts` green (parity + shadow
+  marker for the new section).

package/upgrades/side-effects/recurring-warning-cleanup.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — secret-aware Telegram-token readiness
+
+**Version / slug:** `recurring-warning-cleanup`
+**Date:** `2026-05-29`
+**Author:** `echo`
+**Spec:** `docs/specs/recurring-warning-cleanup.md` (+ `.eli16.md`)
+**Convergence:** `docs/specs/reports/recurring-warning-cleanup-convergence.md` (fast-tracked self-review)
+**Second-pass reviewer:** `not required` (see §"Phase 5 trigger check")
+
+## Summary of the change
+
+One self-contained, log-only fix (autonomous-mode work at Justin's request).
+NOT multi-machine.
+
+`CoherenceMonitor.readiness-telegram-token` used a `typeof === 'string'` guard
+that read the post-externalization `{ secret: true }` token placeholder as
+"missing" and false-alarmed 20×/run. Now a token is "configured" if it's a
+non-empty string OR the placeholder, reusing the now-exported `isSecretPlaceholder`
+from `SecretMigrator`.
+
+(The originally-paired RevertDetector fix was dropped — found already fixed on
+main by #552's `sourceTreeReadOk`; see the spec's coordination note.)
+
+## Files touched
+
+- `src/core/SecretMigrator.ts` — export `isSecretPlaceholder` (was module-private; +doc).
+- `src/monitoring/CoherenceMonitor.ts` — import + use it in the token readiness check.
+- `tests/unit/secret-migrator.test.ts` (+`isSecretPlaceholder` cases).
+
+## Decision-point inventory
+
+- **Token present vs missing** — *modify, widening*. Adds the `{secret:true}`
+  placeholder as a "present" case; a genuinely-missing/empty token still fails.
+  Both sides tested. Read-only.
+- **Export of `isSecretPlaceholder`** — *additive*. Was module-private; now
+  exported so the readiness check reuses one definition (no drift). No behavior
+  change to existing callers.
+
+## Blast radius
+
+- No new authority, no gate, no API route, no external surface, no destructive op.
+- The only delta REMOVES a recurring false warning; no real runtime behavior
+  change (a present token now correctly passes; a missing one still fails).
+- No agent-installed files changed → no `PostUpdateMigrator` entry. Pure `src/`.
+- Not multi-machine.
+
+## Phase 5 trigger check (second-pass reviewer)
+
+Second pass **not required**: no new authority, no destructive op, no external
+surface, no migration, not multi-machine. Additive log-noise cleanup with
+both-sides unit coverage.
+
+## Verification
+
+- `tests/unit/secret-migrator.test.ts` (17, incl. `isSecretPlaceholder` cases) pass.
+- `tsc --noEmit` clean.