instar 0.28.124 → 1.0.8

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-19T17:11:01.459Z",
-  "instarVersion": "0.28.124",
+  "generatedAt": "2026-05-19T19:32:42.283Z",
+  "instarVersion": "1.0.8",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "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": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "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": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "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": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "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": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "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": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1456,7 +1456,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "47337f719ab5f0f928b0cd90e2b89e478379ddf52f6d35c6ff261b0e0b5ecaaf",
+      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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/1.0.8.md

@@ -1,40 +1,93 @@
-# Upgrade Guide — v1.0.8
+# Upgrade Guide — v1.0.8 (the v1.0 milestone)
 
 <!-- bump: patch -->
 
 ## What Changed
 
-Restores Migration Parity §4 conformance for canonical (built-in) hooks. The Hook primitive shipped in PR #253 with a stamp-and-refuse-on-conflict pattern that resurrected the install-if-missing wedge §4 was written to prevent. This release inverts the policy so that built-in hooks are once again always overwritten on every migration run.
-
-Three small code changes:
-
-- The ParityRule interface gained an optional alwaysOverwrite field.
-- hookParityRule sets alwaysOverwrite to true.
-- FrameworkParitySentinel honors alwaysOverwrite and emits a new parity:user-edit-overwritten audit event when overwriting a user-edited rendering.
-
-The user-edit detection stays as a signal in verify output; only the blocking authority moves from the rule to the higher-context Migration Parity policy. skillParityRule does NOT opt in because Migration Parity §5 explicitly carves out skills as refuse-on-conflict with PostUpdateMigrator override.
+This is the official v1.0 milestone release. Two things land together because
+they are causally linked:
+
+1. **Versioning is now truthful.** The release workflow honors the version in
+   `package.json` as the operator's authority for an intended release. It used
+   to derive the next version solely from the npm registry and ignore
+   `package.json`, which made a deliberate major/minor release structurally
+   impossible. That gap is the documented root cause of the 2026-05-19
+   deployment misalignment, where v1.0 framework-parity work shipped to npm
+   under v0.28.x patch numbers. The release that makes truthful versioning
+   possible is, fittingly, the release that stamps v1.0.
+
+2. **The v1.0 milestone is the framework-portability architecture.** Instar is
+   no longer tied to Claude Code as a runtime. The eleven Layer-3 primitives
+   (skill, hook, agent, tool, memory, instruction-file, session-resume,
+   slash-command, outbound-relay, conversational-action, MCP-server) are
+   abstracted behind a parity-rule registry. Identity renders per framework
+   (Claude Code, Codex, Gemini) from a single canonical source. Session-launch
+   builders, the intelligence-provider factory, and the post-update migrator
+   are all framework-aware.
+
+The version-resolution policy was extracted from inline workflow scripting
+into `scripts/resolve-publish-version.mjs` so it is unit-tested.
 
 ## Evidence
 
-Reproduction prior to this release: render a canonical hook to .claude/hooks/session-start/inject.sh, append a user edit (e.g. echo "user added"), then run the parity scan. The verify pass reports user-edit-conflict, and the sentinel skips remediation. On the next instar update where the canonical hook source changes (the typical fix-broken-template scenario), the agent stays stuck on the user-edited stale rendering.
+Reproduction prior to this change: set `package.json` to a higher version
+while npm is behind, merge to main. The workflow published the npm-derived
+patch and silently discarded the intended version. This is the documented
+root cause in `docs/incidents/2026-05-19-v1-deployment-misalignment.md`.
 
-Observed after this release: same setup, same parity scan, the sentinel now calls remediate, the rendering is overwritten with the new canonical body, and the operator sees parity:user-edit-overwritten in the audit stream. Recovery of the user edit is available via git history if needed.
+Observed after this change: a higher `package.json` version than npm publishes
+at the intended version (this is how v1.0.8 itself ships). A routine PR that
+does not touch `package.json` still resolves to the next patch. A stale lower
+`package.json` resolves to npm patch-plus-one, never a downgrade.
 
-Unit-test verification: tests/unit/providers/parity/hookParityRule.test.ts now asserts remediate ALWAYS OVERWRITES user-edits per Migration Parity §4. tests/unit/monitoring/FrameworkParitySentinel.test.ts asserts the new audit event fires for alwaysOverwrite rules.
+Unit verification: `tests/unit/resolve-publish-version.test.ts` — nine cases
+covering greater-than, equal, and less-than across each semver field,
+operator-intended major and minor bumps, routine patch, stale no-downgrade,
+unpublished-package, and a regression replaying the exact 2026-05-19 incident
+input and asserting it now resolves to the intended version.
 
 ## What to Tell Your User
 
-- "When Instar ships a built-in hook, the canonical version always wins on the next update. A subtle regression in the Hook primitive was making us refuse to overwrite hooks that anyone had edited locally — which is exactly the pattern that left us stuck on a broken template once before. This release puts the always-overwrite policy back in place, and adds an audit signal so any clobbered edit is visible and recoverable from git."
+- "Instar v1.0 is here. The headline is portability: your agent is no longer locked to one runtime. The same agent identity, skills, hooks, and memory now render correctly whether the runtime is Claude Code, Codex, or another supported framework. This release also fixes the versioning process so the published version always matches what we intend to ship."
+- "If you are updating an existing agent, there is nothing you need to do. The framework-portability code already reached you through earlier patch updates; this release stamps the milestone and corrects the version number. Six narrow hardening improvements ship as quick follow-up patches over the next few releases."
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| ParityRule alwaysOverwrite field | Set alwaysOverwrite to true on rules covered by Migration Parity §4. Defaults to false (refuse-on-conflict for §5 rules like skills). |
-| parity:user-edit-overwritten audit event | Sentinel emits this whenever an alwaysOverwrite rule clobbers a user-edited rendering. Listen via FrameworkParitySentinel events. |
-| Canonical hook always-overwrite restored | No action required; built-in hooks are now once again always overwritten on every migration cycle. Custom hooks in .claude/hooks/custom/ continue to be untouched. |
+| Truthful versioning | Automatic. The release workflow honors the intended version. Routine patches are unchanged. |
+| Framework portability | Automatic. Agent identity and the eleven primitives render per runtime from a single canonical source. |
+| Per-framework identity | Canonical identity lives in one place; the runtime-specific shadow file is regenerated on demand. |
+
+## Agent Migration Notes
+
+For an agent updating from any v0.28.x to v1.0.8:
+
+- **Required actions: none.** The framework-portability code shipped
+  incrementally under v0.28.122–v0.28.125. This release stamps the milestone
+  and corrects the version label. No canonical-file migration is required.
+- **What is new on disk after update:** the post-update migrator continues to
+  refresh framework-rendered copies of canonical primitives. The
+  conversational-action catalog is reachable through its on-demand loaders
+  (context segment, knowledge-tree probe, playbook item). No always-loaded
+  identity-prompt growth.
+- **Verification an agent can run on itself:** confirm the installed version
+  reads 1.0.8 or higher; confirm the canonical identity file is the source of
+  truth and the runtime shadow carries the auto-generated banner.
+- **If an agent runs a non-Claude-Code runtime:** six narrow portability gaps
+  (documented in the v1.0.0 cross-framework audit) ship as v1.0.9–v1.0.14
+  patches immediately after this release. Until then, dual-framework installs
+  are unaffected; the gaps only touch single-runtime non-Claude-Code installs.
 
 ## Deferred (Tracked Follow-ups)
 
-- Wire parity:user-edit-overwritten into a Dashboard view so operators see clobber events without grepping logs.
-- Audit the remaining merged primitive PRs (#254 Agent/Tool/Memory and #255 Sentinel ship-order) using the lessons-aware reviewer; corrective amendments per finding.
+- Six audit-flagged portability hardening gaps ship as v1.0.9–v1.0.14 patches:
+  init routing through the identity renderer, framework-aware connector-server
+  registration, a framework-session-store abstraction, neutral relay-script
+  path, post-update-migrator framework guards, and migrator/identity-renderer
+  unification. Each has a documented fix from the cross-framework audit.
+- The broader deployment-lockdown infrastructure (release-tier config,
+  multi-signature for major bumps, major-work branch isolation, hold-signal,
+  incident-memory injection) is designed separately and tracked in the
+  deployment-lockdown topic. This release is only the version-truth
+  prerequisite plus the milestone stamp.

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.

package/upgrades/side-effects/feat-publish-version-truth.md

@@ -0,0 +1,68 @@
+# Side-effects review — Publish version-truth
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+**Before.** UNDER: the workflow could not express an operator-intended major
+bump at all — every release was a patch. This is the incident root cause.
+
+**After.** No over-block. Routine patch PRs (the overwhelming majority, which
+don't touch package.json) behave identically — LOCAL == NPM → patch+1. The
+only new path is "LOCAL > NPM → honor LOCAL," which is exactly the
+intentional-leap case. The LOCAL < NPM guard prevents an accidental downgrade
+(a queued-run stale-package scenario), so there's no new under-block either.
+
+## 2. Level-of-abstraction fit
+
+The resolution policy lives in `scripts/resolve-publish-version.mjs` — a pure
+function with a CLI shim, unit-tested. The workflow calls it. This is the
+right altitude: decision logic in testable code, orchestration in the
+workflow. No logic buried in inline bash.
+
+## 3. Signal vs Authority compliance
+
+package.json is the SIGNAL of operator intent. The npm registry is the
+AUTHORITY for what shipped. The script reconciles them deterministically with
+a documented precedence. No brittle filter is granted blocking authority; the
+script never *blocks* a publish, it only *resolves the number*. (The loud
+refusal-on-mismatch behavior is part of the separate lockdown spec, not this
+PR.)
+
+## 4. Interactions with adjacent systems
+
+- **Release workflow.** Only the "Determine next version" step changes. The
+  NEXT.md skip-gate, the guide-check, the publish, and the tag/commit steps
+  are untouched.
+- **Routine patch line.** Unchanged. Verified by the `eq` test case.
+- **Queued concurrent runs.** The original concern ("queued runs leave
+  package.json out of sync") is preserved: a queued run that lands after an
+  earlier publish bumped will see LOCAL <= NPM and patch-bump cleanly, not
+  collide.
+- **The v1.0.0 cut.** This is the enabling change — the alignment PR will set
+  package.json to 1.0.0 and the workflow will, for the first time, honor it.
+
+## 5. Rollback cost
+
+Low. Three files (workflow step, new script, new test). `git revert` restores
+the npm-derived behavior. No state migration, no deployed-agent impact (this
+is build-time infra, not shipped runtime code).
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible for the patch line. The only behavioral delta is
+the previously-impossible major/minor leap. No config, no schema, no agent
+files touched. Drift surface: none — the script has no persistent state.
+
+## 7. Authorization / Trust posture
+
+No new authority. The script reads two version strings and prints one. It
+cannot publish, cannot mutate state, cannot escalate. The actual publish
+authority (NPM_TOKEN) is unchanged and still gated by the same CI required
+checks via branch protection.
+
+## Outcome
+
+Ship. Minimal, incident-driven, fully tested, no over-block, trivial
+rollback. Unblocks the v1.0.0 cut without pulling in the broader lockdown
+scope.