instar 0.28.119 → 0.28.120

package/dist/providers/parity/conversationalActionCatalog.d.ts

@@ -0,0 +1,57 @@
+/**
+ * conversationalActionCatalog — discovery + rendering for the conversational
+ * action catalog (Layer-3 primitive #10, v0.1).
+ *
+ * Spec: specs/instar-concepts/conversational-action.md
+ *
+ * Walks canonical skills under `.instar/skills/<name>/SKILL.md`, generates a
+ * stable markdown block listing each one as a conversational action, and
+ * idempotently inserts/replaces that block in canonical AGENT.md.
+ *
+ * v0.1 scope:
+ *   - Catalog discovery + filtering.
+ *   - Markdown block generation with delimiter comments.
+ *   - Idempotent applyCatalogBlock() — insert or replace cleanly.
+ *
+ * v0.2 deferred:
+ *   - `user-invocable: true` frontmatter filter (pending Skill v0.2 field surface).
+ *   - Authed POST execution endpoints.
+ *   - Per-action JSON Schema / action-shape declarations.
+ *   - Wiring into FrameworkParitySentinel as a parity rule (catalog-drift detection).
+ */
+export interface ConversationalAction {
+    /** Canonical skill name (== slug == slash-command suffix) */
+    name: string;
+    /** Short description used in catalog entry + agent-side intent classification */
+    description: string;
+    /** Framework-agnostic invocation path. v0.1: always `/${name}` */
+    invocation: string;
+}
+declare function parseFrontmatter(raw: string): {
+    fm: Record<string, unknown>;
+    rest: string;
+};
+/**
+ * Walk `.instar/skills/<name>/SKILL.md` under `projectRoot`, return the
+ * discovered conversational actions sorted by name.
+ *
+ * v0.1: enumerates ALL canonical skills (no `user-invocable` filter).
+ */
+export declare function discoverActions(projectRoot: string): Promise<ConversationalAction[]>;
+/**
+ * Render the catalog markdown block (with start/end delimiter comments).
+ *
+ * Stable output — given the same actions list, returns the same string.
+ * Pure function: no I/O. Caller decides where the block lands (typically a
+ * Tier 2 ContextHierarchy segment, a SelfKnowledgeTree probe response, or a
+ * Playbook context item — NOT inlined into AGENT.md, per the bloat-aware
+ * design constraint documented in the concept spec).
+ */
+export declare function renderCatalogBlock(actions: ReadonlyArray<ConversationalAction>): string;
+export declare const _internals: {
+    parseFrontmatter: typeof parseFrontmatter;
+    BLOCK_START: string;
+    BLOCK_END: string;
+};
+export {};
+//# sourceMappingURL=conversationalActionCatalog.d.ts.map

package/dist/providers/parity/conversationalActionCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversationalActionCatalog.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/conversationalActionCatalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAWH,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAkBD,iBAAS,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAiBpF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAoC1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,GAAG,MAAM,CAiBvF;AAgBD,eAAO,MAAM,UAAU;;;;CAA+C,CAAC"}

package/dist/providers/parity/conversationalActionCatalog.js

@@ -0,0 +1,148 @@
+/**
+ * conversationalActionCatalog — discovery + rendering for the conversational
+ * action catalog (Layer-3 primitive #10, v0.1).
+ *
+ * Spec: specs/instar-concepts/conversational-action.md
+ *
+ * Walks canonical skills under `.instar/skills/<name>/SKILL.md`, generates a
+ * stable markdown block listing each one as a conversational action, and
+ * idempotently inserts/replaces that block in canonical AGENT.md.
+ *
+ * v0.1 scope:
+ *   - Catalog discovery + filtering.
+ *   - Markdown block generation with delimiter comments.
+ *   - Idempotent applyCatalogBlock() — insert or replace cleanly.
+ *
+ * v0.2 deferred:
+ *   - `user-invocable: true` frontmatter filter (pending Skill v0.2 field surface).
+ *   - Authed POST execution endpoints.
+ *   - Per-action JSON Schema / action-shape declarations.
+ *   - Wiring into FrameworkParitySentinel as a parity rule (catalog-drift detection).
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+const CANONICAL_SKILLS_ROOT = '.instar/skills';
+const BLOCK_START = '<!-- instar:conversational-actions:start -->';
+const BLOCK_END = '<!-- instar:conversational-actions:end -->';
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+class CatalogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CatalogError';
+    }
+}
+async function pathExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseFrontmatter(raw) {
+    if (!raw.startsWith('---\n')) {
+        return { fm: {}, rest: raw };
+    }
+    const close = raw.indexOf('\n---', 4);
+    if (close < 0) {
+        throw new CatalogError('skill SKILL.md has unterminated YAML frontmatter');
+    }
+    const fmRaw = raw.slice(4, close);
+    let fm;
+    try {
+        fm = yaml.load(fmRaw, { schema: yaml.FAILSAFE_SCHEMA, json: false });
+    }
+    catch (err) {
+        throw new CatalogError(`skill SKILL.md YAML parse error: ${err.message}`);
+    }
+    const rest = raw.slice(close + 4).replace(/^\n/, '');
+    return { fm: (fm && typeof fm === 'object' ? fm : {}), rest };
+}
+/**
+ * Walk `.instar/skills/<name>/SKILL.md` under `projectRoot`, return the
+ * discovered conversational actions sorted by name.
+ *
+ * v0.1: enumerates ALL canonical skills (no `user-invocable` filter).
+ */
+export async function discoverActions(projectRoot) {
+    const skillsRoot = path.join(projectRoot, CANONICAL_SKILLS_ROOT);
+    if (!(await pathExists(skillsRoot)))
+        return [];
+    const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
+    const actions = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (!SLUG_RE.test(entry.name))
+            continue;
+        const skillMdPath = path.join(skillsRoot, entry.name, 'SKILL.md');
+        if (!(await pathExists(skillMdPath)))
+            continue;
+        let raw;
+        try {
+            raw = await fs.readFile(skillMdPath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseFrontmatter(raw);
+        }
+        catch {
+            // Skip broken skills; the Skill parity rule surfaces them separately.
+            continue;
+        }
+        const name = String(parsed.fm.name ?? entry.name);
+        const description = typeof parsed.fm.description === 'string'
+            ? parsed.fm.description
+            : '(no description)';
+        actions.push({
+            name,
+            description,
+            invocation: `/${name}`,
+        });
+    }
+    actions.sort((a, b) => a.name.localeCompare(b.name));
+    return actions;
+}
+/**
+ * Render the catalog markdown block (with start/end delimiter comments).
+ *
+ * Stable output — given the same actions list, returns the same string.
+ * Pure function: no I/O. Caller decides where the block lands (typically a
+ * Tier 2 ContextHierarchy segment, a SelfKnowledgeTree probe response, or a
+ * Playbook context item — NOT inlined into AGENT.md, per the bloat-aware
+ * design constraint documented in the concept spec).
+ */
+export function renderCatalogBlock(actions) {
+    const lines = [BLOCK_START, '## Conversational Actions', ''];
+    if (actions.length === 0) {
+        lines.push('_No conversational actions installed yet. Install a skill under `.instar/skills/<name>/` to make it available here._');
+    }
+    else {
+        lines.push('When the user expresses intent that maps to one of these, invoke the slash-command (or guide them conversationally to the equivalent action). You do not need to surface the slash-command name to the user — translate intent into invocation.', '');
+        for (const a of actions) {
+            lines.push(`- \`${a.invocation}\` — ${a.description}`);
+        }
+    }
+    lines.push('', BLOCK_END);
+    return lines.join('\n') + '\n';
+}
+/*
+ * NOTE: applyCatalogBlock(...) deliberately NOT exported in v0.1.
+ *
+ * Writing the catalog block directly into AGENT.md (the always-loaded Tier 0
+ * identity file) is the AGENT.md-bloat antipattern Instar built three
+ * defenses against (ContextHierarchy, Playbook, SelfKnowledgeTree). The
+ * catalog block is returned as a string from renderCatalogBlock(); the
+ * caller (a v0.2 ContextHierarchy Tier 2 segment writer, a SelfKnowledgeTree
+ * probe handler, or a Playbook context item) decides where it lands.
+ *
+ * See specs/instar-concepts/conversational-action.md ("Bloat-awareness as a
+ * v0.1 design constraint") for the full rationale.
+ */
+export const _internals = { parseFrontmatter, BLOCK_START, BLOCK_END };
+//# sourceMappingURL=conversationalActionCatalog.js.map

package/dist/providers/parity/conversationalActionCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversationalActionCatalog.js","sourceRoot":"","sources":["../../../src/providers/parity/conversationalActionCatalog.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.119",
+  "version": "0.28.120",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-19T02:38:16.455Z",
-  "instarVersion": "0.28.119",
+  "generatedAt": "2026-05-19T04:26:32.444Z",
+  "instarVersion": "0.28.120",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.120.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — v1.0.6
+
+<!-- bump: patch -->
+
+## What Changed
+
+Lands the Conversational-action primitive (Layer-3 required primitive #10) — but **deliberately narrow**: pure-data catalog primitives only, no direct AGENT.md write.
+
+Foundational stance, locked 2026-05-18 per Justin: users should never have to know any Instar internals. Conversational is the default; slash-commands are a backstop. When the user says "let's switch to local" the agent recognizes that intent and either invokes /local-model or guides the user there — without surfacing the slash-command name.
+
+For the agent to translate intent to action, it needs a catalog of what is invocable. The earlier draft of this PR would have written that catalog directly into AGENT.md (the always-loaded identity file). After a scope-coherence pause + Justin's research request, we caught that this contradicts three Instar systems built specifically to prevent AGENT.md bloat: ContextHierarchy (Tier 0/1/2 segments), Playbook (scored decaying items), Self-Knowledge Tree (on-demand probes). So we removed the AGENT.md-writing API from v0.1.
+
+v0.1 ships only the pure-data primitives:
+- discoverActions(projectRoot) walks .instar/skills/ and returns the discovered actions sorted by name
+- renderCatalogBlock(actions) generates a stable markdown block as a string (caller decides where it lands)
+
+v0.1 explicitly does NOT ship:
+- A function that writes the catalog into AGENT.md. v0.2 will route the catalog through ContextHierarchy Tier 2 segments (loaded on demand when the agent is interpreting user intent), a Self-Knowledge Tree probe (queried on demand), and a Playbook item (scored + decaying). All three load conditionally, not always.
+- Authed POST execution endpoints. v0.2 with per-action shape declarations + trust integration.
+- The user-invocable: true frontmatter filter. v0.2 once Skill primitive surfaces that field.
+
+14 unit tests cover discovery and rendering, including a structural assertion that the AGENT.md-writing API is absent from the public surface — the bloat-aware design is enforced at the test layer.
+
+Spec at specs/instar-concepts/conversational-action.md (converged + approved per hybrid-C pre-auth). ELI16 + convergence report alongside. Side-effects review documents the amendment in full.
+
+## What to Tell Your User
+
+- "The first piece of the conversational-action primitive is built — it discovers what is invocable and generates the catalog. The wiring step is held until v0.2 so we can load the catalog only when the agent needs it, instead of inlining it into the always-on identity prompt. That avoids the context-bloat trap we hit three times before."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Conversational action catalog (pure-data) | Import discoverActions and renderCatalogBlock from src/providers/parity/conversationalActionCatalog.js. Walks installed skills, generates the catalog block as a string. |
+| Bloat-aware design enforced at test layer | The applyCatalogBlock API is deliberately absent from the public module exports; a structural test asserts this. |
+
+## Deferred (Tracked Follow-ups)
+
+- v0.2 wiring through ContextHierarchy Tier 2 segment + SelfKnowledgeTree catalog probe + Playbook context item (all three on-demand loaders).
+- v0.2 FrameworkParitySentinel wiring as a catalog-drift parity rule.
+- v0.2 authed POST /api/conversational/execute endpoints with per-action shape declarations + trust integration.
+- v0.2 user-invocable: true frontmatter filter (pending Skill v0.2 field surface).
+- InstructionFile primitive (separate spec, next) — decides what minimal pointer goes into framework-native instruction files.
+- Intent-classification examples in skill frontmatter.

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

@@ -0,0 +1,101 @@
+# Side-Effects Review — Conversational-action primitive v0.1 (bloat-aware catalog primitives)
+
+**Version / slug:** `feat-conversational-action`
+**Date:** 2026-05-19
+**Author:** Echo (autonomous mode, hybrid C, amended after scope-coherence grounding pause)
+
+## Summary of the change
+
+Lands the Conversational-action primitive (Layer-3 required primitive #10) as **bloat-aware pure-data primitives**: `discoverActions` (walks installed canonical skills) + `renderCatalogBlock` (generates the catalog block as a string). 14 unit tests including a structural assertion that `applyCatalogBlock` is deliberately NOT exported.
+
+**Amended scope (post-grounding):** the original draft included `applyCatalogBlock(projectRoot, actions)` that wrote directly into `.instar/AGENT.md`. The scope-coherence hook + Justin's explicit research request surfaced that this contradicts three existing Instar systems built specifically to prevent AGENT.md bloat:
+
+- `ContextHierarchy` (`src/core/ContextHierarchy.ts`) — Tier 0/1/2 segments, "right context at right moment > all context all the time" (born from the Luna incident 2026-02-25)
+- `Playbook` (`docs/PLAYBOOK-GETTING-STARTED.md`) — scored decaying context items
+- `SelfKnowledgeTree` (`src/knowledge/SelfKnowledgeTree.ts`) — on-demand probe queries instead of memorized lists
+- Plus the `Structure > Willpower` principle codified in CLAUDE.md template
+
+`applyCatalogBlock` was removed from v0.1 to prevent baking the wrong placement decision into a primitive's surface. v0.2 wiring goes through the three infrastructures above (Tier 2 segment writer, `catalog` probe, Playbook item) — not direct AGENT.md insert.
+
+**Files changed (specs):**
+- specs/instar-concepts/conversational-action.md (new, converged + approved per pre-auth; includes "Bloat-awareness as a v0.1 design constraint" section)
+- specs/instar-concepts/conversational-action.eli16.md (new)
+- docs/specs/reports/conversational-action-concept-convergence.md (new — records the amended scope as iteration 2 finding)
+
+**Files changed (source):**
+- src/providers/parity/conversationalActionCatalog.ts (new — discoverActions + renderCatalogBlock only; applyCatalogBlock deliberately NOT exported)
+
+**Files changed (tests):**
+- tests/unit/providers/parity/conversationalActionCatalog.test.ts (new — 14 tests; includes structural assertion that applyCatalogBlock is absent from public API)
+
+**Files changed (release notes):**
+- upgrades/NEXT.md (new)
+- package.json (version bump)
+
+## Decision-point inventory
+
+- **Building-block scope, bloat-aware**: ships `discoverActions` + `renderCatalogBlock` only. No direct AGENT.md write. Caller (v0.2 ContextHierarchy / SelfKnowledgeTree / Playbook wiring) decides where the block lands.
+- **`applyCatalogBlock` removal**: structural prevention of AGENT.md bloat. Spec body documents why; one test enforces the public API surface.
+- **Skill discovery enumerates all canonical skills**: `user-invocable: true` filter deferred to v0.2 (Skill v0.1 doesn't surface that field).
+- **Catalog block format**: HTML-comment delimited (`<!-- instar:conversational-actions:start -->` / `:end -->`), stable + machine-readable, idempotent re-renders.
+- **Discovery skip-on-error**: skills with broken YAML frontmatter or invalid slugs are silently skipped (Skill parity rule surfaces them separately as drift). Avoids double-reporting.
+- **No registry entry**: catalog is consumed via direct import (matches Tool primitive precedent). v0.2 sentinel-wired drift detection is the registry consumer.
+- **No I/O writes**: `discoverActions` reads `.instar/skills/`; `renderCatalogBlock` is pure function. Module never writes anywhere.
+
+## Over-block / under-block analysis
+
+**Over-block risk (catalog rendering):** none — block is pure data, never imposed on AGENT.md.
+
+**Under-block risk (broken skills skipped):** a skill with malformed frontmatter is silently absent from the catalog. The Skill parity rule already surfaces this as drift on its own pass; v0.2 sentinel wiring will combine signals.
+
+**Under-block risk (v0.2 not yet wired):** until v0.2 wires the catalog into ContextHierarchy / SelfKnowledgeTree / Playbook, the catalog data exists but nothing reads it. That's intentional — better to ship correct pure-data primitives now than to ship a half-baked wiring that bakes in the bloat path.
+
+## Level-of-abstraction fit
+
+- Catalog primitives are pure data — discovery + rendering. No I/O writes, no LLM calls, no AGENT.md awareness.
+- Boundary clean: catalog OWNS the block format; doesn't OWN where it lands.
+- Pure-function shape: `discoverActions`, `renderCatalogBlock` — composable with any downstream loading vehicle.
+
+## Signal-vs-authority compliance
+
+- Catalog is signal (here's what's invocable + when).
+- Authority over loading placement: the v0.2 ContextHierarchy / SelfKnowledgeTree / Playbook integrations + ultimately the agent's runtime intent classifier.
+- v0.2 authed POST endpoints will gate execution via trust — separate authority layer.
+
+## Interaction surface
+
+- One new file under `src/providers/parity/`. No HTTP routes, no server.ts wiring, no config additions, no AGENT.md writes.
+- Reads `.instar/skills/<name>/SKILL.md`.
+- No changes to existing rules, registries, scaffold, or migration paths.
+- No new dependencies.
+
+## Rollback cost
+
+- Pure-add. Revert removes the module + tests + spec. No data migrations, no AGENT.md state to undo (because no writes).
+- Worst-case bug: `renderCatalogBlock` produces malformed markdown. Mitigated by stability test + delimiter shape test.
+
+## Test coverage
+
+- Unit: 14 tests covering discovery (empty/single/multiple/sort/fallback/slug-filter/broken-YAML-skip/files-vs-dirs), rendering (empty placeholder, bullet shape, stability), end-to-end discover → render, **structural assertion that applyCatalogBlock is NOT in the public API** (enforces the bloat-aware design constraint at the test layer).
+- Integration + E2E: not applicable for pure-data primitives. v0.2 wiring PR will add integration + E2E when HTTP/sentinel/segment-writer surfaces land.
+
+## Documentation
+
+- Concept spec + ELI16 at `specs/instar-concepts/` (both updated to lead with the bloat-awareness design constraint).
+- Convergence report at `docs/specs/reports/` (iteration 2 records the bloat-aware amendment).
+- NEXT.md with "What to Tell Your User" entries explaining the deliberately-narrow v0.1 scope.
+
+## Deferred (tracked, not silent)
+
+- **ContextHierarchy Tier 2 segment writer** that consumes `renderCatalogBlock` output → `.instar/context/conversational-actions.md` with triggers `interpreting-user-intent` / `answering-what-can-you-do` — v0.2.
+- **SelfKnowledgeTree `catalog` probe** that returns matching actions for a query at runtime — v0.2.
+- **Playbook context item** seeded with the catalog discovery pattern + decay configuration — v0.2.
+- **FrameworkParitySentinel wiring** as a catalog-drift parity rule (catalog-out-of-sync detection on scan) — v0.2.
+- **Authed POST /api/conversational/execute endpoints** — v0.2 with per-action shape declarations + trust integration.
+- **`user-invocable: true` filter** — v0.2, pending Skill v0.2 field surface.
+- **InstructionFile primitive** — separate spec, decides what minimal pointer (3 sentences max) goes into framework-native CLAUDE.md / AGENTS.md.
+- **Intent-classification examples in skill frontmatter** — v0.2.
+
+## Why this amendment matters
+
+The pre-amendment v0.1 would have shipped `applyCatalogBlock` as the headline API, with a NEXT.md line saying "v0.2 will fix the bloat concern." That's the "Phase 2" anti-pattern Justin explicitly listed in this autonomous session's stop-hook brief: "every task has a concrete done state. No deferrals disguised as planning." Removing `applyCatalogBlock` makes the v0.1 surface honest — the primitive ships what it can ship correctly, and the wiring decision waits for the right loading vehicle to land.