# 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.
