instar 0.28.124 → 0.28.125

package/src/templates/playbook/conversational-catalog-manifest.json

@@ -0,0 +1,43 @@
+{
+  "version": 1,
+  "name": "instar-conversational-catalog",
+  "description": "Conversational-action catalog pointer for Playbook (Instar v1.0 built-in)",
+  "items": [
+    {
+      "id": "/instar/conversational-catalog",
+      "category": "infrastructure",
+      "memory_type": "procedural",
+      "path": ".instar/context/conversational-actions.md",
+      "tags": {
+        "domains": ["conversational-action", "intent-interpretation", "capability"],
+        "qualifiers": ["on-demand", "structural", "bloat-aware"]
+      },
+      "freshness": "2026-05-19T00:00:00Z",
+      "tokens_est": 800,
+      "usefulness": { "helpful": 0, "misleading": 0 },
+      "load_triggers": [
+        "interpreting-user-intent",
+        "matching-to-skill",
+        "translating-conversation-to-action",
+        "user-said-switch-to-X",
+        "user-said-lets-do-Y"
+      ],
+      "dependencies": [],
+      "provenance": [
+        {
+          "source_session": "GENESIS",
+          "created_at": "2026-05-19",
+          "provenance_type": "instar-builtin",
+          "spec": "specs/instar-concepts/conversational-action.md (v0.2)",
+          "context_segment": ".instar/context/conversational-actions.md",
+          "probe_name": "conversational-catalog",
+          "rationale": "On-demand load of the invocable action catalog. Per Instar Design Principle P1 (Structure>Willpower) and the AGENT.md bloat lesson (L1), the catalog is NEVER inlined into AGENT.md. Playbook scoring decides when this pointer is relevant; SelfKnowledgeTree probe materializes the live catalog when fetched."
+        }
+      ],
+      "retirement_policy": "auto",
+      "access_scope": "global",
+      "inheritance_eligible": true,
+      "status": "active"
+    }
+  ]
+}

package/upgrades/0.28.125.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — v1.0.13
+
+<!-- bump: patch -->
+
+## What Changed
+
+Wires the v0.1 conversational-action catalog primitives (`discoverActions`, `renderCatalogBlock` from PR #256) through Instar's three pre-built bloat defenses — ContextHierarchy Tier 2 segment, SelfKnowledgeTree probe, and Playbook context item. The v0.1 deliberately shipped the catalog as pure data with no inlining into AGENT.md, because Instar already has structural defenses against AGENT.md bloat. This release wires the consumers.
+
+The catalog content lives in the `conversational-catalog` SelfKnowledgeTree probe — generated fresh on each probe call, never cached. The new ContextHierarchy Tier 2 segment `.instar/context/conversational-actions.md` is the dispatch instruction (when the agent is in an intent-interpretation moment, this segment tells it to fetch the catalog via the probe). The new `conversational-catalog.json` Playbook manifest item is the third on-demand loader — Playbook's scoring engine surfaces the pointer when intent-interpretation triggers fire. All three paths are on-demand by design. The catalog is never inlined into the always-loaded identity prompt.
+
+A semantic correctness test asserts that the Tier 1 loadTier output does not contain the conversational-actions segment content. If a future PR accidentally re-introduces AGENT.md inlining, the test fails.
+
+## Evidence
+
+Reproduction prior to this release: a user says "let's switch to local model" in conversation. The agent has no on-demand path to discover the available conversational actions — `.instar/skills/` exists on disk but the agent has no instruction to consult it for intent interpretation, no probe registered at server boot, and no Playbook item surfaced by the scoring engine. The agent falls back to asking the user for a slash command, breaking the conversation-default promise.
+
+Observed after this release: same setup, three on-demand load paths come alive. The dispatch table for the new Tier 2 segment fires on the `interpreting-user-intent` trigger; the segment instructs the agent to invoke the `conversational-catalog` probe. The probe calls `discoverActions` + `renderCatalogBlock` and returns the live catalog. The agent matches the user's intent against the catalog and routes to the local-model skill. The slash-command surface is never shown.
+
+Unit-test verification: three new ContextHierarchy tests (segment content presence, dispatch table registration, Tier 1 loadTier exclusion) and three new PostUpdateMigrator tests (manifest install when missing, idempotency on second run, refresh on content drift). The existing 19 ContextHierarchy tests continue to pass.
+
+## What to Tell Your User
+
+- "When you say something like 'let's switch to local' or 'send Dawn a message', I now have three independent on-demand paths to discover the right action without you having to know a slash-command name. The catalog is generated live on each lookup, never inlined into my always-loaded identity prompt, and the bloat-aware design is asserted-against in the test suite so a future regression can't sneak it back in."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Conversational-actions ContextHierarchy segment | Automatic. The Tier 2 segment loads on `interpreting-user-intent`, `matching-to-skill`, or `translating-conversation-to-action` triggers. |
+| `conversational-catalog` SelfKnowledgeTree probe | Automatic. Registered at server boot when `selfKnowledgeTree` is enabled. The probe walks `.instar/skills/` and returns the live catalog on each call. |
+| Playbook conversational-catalog manifest | Automatic install via PostUpdateMigrator; mount with `instar playbook mount` (explicit consent per Playbook design). |
+
+## Deferred (Tracked Follow-ups)
+
+- HTTP endpoint `/capabilities/conversational-catalog` is referenced in the segment as a third fallback after the probe; not implemented in this PR. The probe is the canonical access path; the HTTP endpoint is a future convenience.
+- Future v0.3 may add new triggers to the manifest template; PostUpdateMigrator's content-sniff guard will refresh the manifest on update without operator action.

package/upgrades/side-effects/feat-conversational-action-v02.md

@@ -0,0 +1,68 @@
+# Side-effects review — Conversational-action v0.2 (three on-demand loaders)
+
+Per L6 (Side-effects review gate). Seven dimensions.
+
+## 1. Over-block / under-block
+
+**Before this change.** UNDER-blocked: the v0.1 (PR #256) shipped catalog primitives but deliberately omitted any wiring. The catalog existed as pure data; agents had no on-demand load path. The promise "user says intent → agent recognizes via catalog" was a future promise, not an observed behavior.
+
+**After this change.** No over-block risk. All three loaders are on-demand by design. The semantic correctness test asserts the conversational-actions content is NOT in Tier 0 or Tier 1 loads, so the AGENT.md bloat anti-pattern can't sneak back in via accidental regression.
+
+The Playbook integration is opt-in via `instar playbook mount` — operator explicit consent per Playbook design. Operators who don't mount the Playbook manifest still get the other two loaders (segment + probe).
+
+## 2. Level-of-abstraction fit
+
+Each loader lives in its natural home:
+- ContextHierarchy Tier 2 segment → `src/core/ContextHierarchy.ts` DEFAULT_SEGMENTS array
+- SelfKnowledgeTree probe → `src/commands/server.ts` boot path (alongside the existing feature-discovery probe)
+- Playbook manifest → `src/templates/playbook/` (template) + PostUpdateMigrator step (installer)
+
+The probe registration deliberately uses dynamic import (`await import(...)`) so the catalog primitives aren't pulled into the boot graph until the probe is invoked. Lazy load = no startup cost for agents that never trigger the catalog.
+
+The PostUpdateMigrator step uses content-sniff idempotency (skip if existing file matches template byte-for-byte). On every update, the template is re-checked; if it has drifted (e.g., a future v0.3 adds new triggers to the manifest), the file is refreshed.
+
+## 3. Signal vs Authority compliance
+
+The ContextHierarchy Tier 2 segment is the SIGNAL — it tells the agent "you're in an intent-interpretation moment, here's how to fetch the catalog." The SelfKnowledgeTree probe is the AUTHORITY — when invoked, it returns the live catalog. The Playbook item is a complementary RELEVANCE signal — Playbook's scoring engine decides when to surface the pointer based on usefulness history.
+
+Three independent signal/authority paths give the agent multiple on-ramps. No single load path is mandatory; each fills a different role.
+
+## 4. Interactions with adjacent systems
+
+**ContextHierarchy initializer.** The new segment uses the existing template-generator pattern. `generateSegmentTemplate('conversational-actions')` returns a fresh template string; the initializer writes it on first init AND on every update (via the parity-renderings backfill from PR #262, which re-renders all canonical sources).
+
+**SelfKnowledgeTree.** The probe is registered alongside the existing `feature-discovery` probe at server boot. Both probes are conditional on `selfKnowledgeTree` being non-null (matches the existing pattern). No new lifecycle complications.
+
+**Playbook system.** The manifest template lives in `src/templates/playbook/` and is shipped to `.instar/playbook/builtin-manifests/` on update. The actual mount registration is operator-initiated via `instar playbook mount`. No automatic mount — this preserves Playbook's "explicit consent for context items" invariant.
+
+**PostUpdateMigrator backfill (PR #262, now on main).** The parity-renderings backfill re-renders the ContextHierarchy segment on every update, so the conversational-actions segment file stays fresh. The new migrateConversationalCatalogPlaybookManifest step is a sibling — also idempotent, also runs on every update.
+
+**AGENT.md.** Unchanged. The whole point of this PR is to NOT add the catalog to AGENT.md. Asserted structurally by the semantic correctness test.
+
+## 5. Rollback cost
+
+Low. Five files changed (one new template, one new test file, three sibling additions to existing files: ContextHierarchy, server.ts probe registration, PostUpdateMigrator step). Revert is `git revert`. Deployed agents would keep the Playbook manifest file (orphan, harmless — Playbook ignores unmounted manifests); the segment file would remain (still readable but the dispatch table would no longer fire for intent-interpretation triggers). The probe would be unregistered on next server restart.
+
+## 6. Backwards compatibility / drift surface
+
+Backwards-compatible:
+- v0.1 catalog primitives unchanged.
+- Existing ContextHierarchy segments unchanged.
+- Existing SelfKnowledgeTree probes unchanged.
+- Playbook manifest is additive (only writes to builtin-manifests/; never modifies existing mounts).
+
+**Drift surface.** The conversational-actions segment file content is regenerated by ContextHierarchy.initialize() — operators who customize the file would lose customizations on update. This is consistent with all other Tier 0-2 segment files (initialize-only-when-missing protection has been removed in favor of always-overwrite via PR #262's parity-renderings backfill for canonical sources). Operators who want custom intent-dispatch instructions should add a separate custom segment file outside the DEFAULT_SEGMENTS path.
+
+**Playbook manifest format.** The shipped template uses Playbook's documented manifest schema. If Playbook v2 changes the schema, this template would need updating. Documented as a known coupling.
+
+## 7. Authorization / Trust posture
+
+No new authority claims. The probe is read-only (walks `.instar/skills/`, returns a string). The PostUpdateMigrator step writes to `.instar/playbook/builtin-manifests/` (a write surface PostUpdateMigrator already has authority over). The Playbook mount registration is operator-initiated — `instar playbook mount` is a CLI command requiring explicit user invocation.
+
+Trust-floor implications: the conversational-catalog probe is at the same Tier-1 LLM-supervised execution surface as the other knowledge-tree probes. Output is capped at the probe's default `maxOutputChars` (2000 chars). Catalog blocks exceeding this would be truncated; v0.1's renderCatalogBlock produces compact output well within the cap for typical skill counts.
+
+## Outcome
+
+Ship.
+
+The three on-demand loaders are wired structurally. The AGENT.md bloat anti-pattern is asserted-against in the semantic correctness test. The catalog content lives in the probe (dynamic, live) — the segment and Playbook item are pointers, never the content itself. Final v1.0 task closed; the conversational-action layer is structurally complete.