instar 0.28.118 → 0.28.120

package/dist/monitoring/FrameworkParitySentinel.d.ts

@@ -0,0 +1,91 @@
+/**
+ * FrameworkParitySentinel — consumer of the Layer-3 parity rules registry.
+ *
+ * Spec: specs/instar-foundations/framework-parity-sentinel.md
+ *
+ * Walks the registry on its scan cadence (and on triggers), calls each rule's
+ * verify() per instance, surfaces drift via events + degradation reports, and
+ * (per rule's remediationPolicy) optionally calls remediate() to re-render
+ * canonical into the framework-native shape.
+ *
+ * v0.1 scope:
+ *   - Registry walker (consume listParityRules → iterate → collect verify).
+ *   - State file persistence (.instar/state/framework-parity-sentinel.json).
+ *   - Interval trigger (single setInterval; no chokidar watcher yet).
+ *   - EventEmitter wiring (5 events: gap-found, remediated, remediation-refused,
+ *     orphan-found, scan-complete).
+ *   - Degradation reporter on persistent unresolved gaps.
+ *
+ * v0.2 deferred: chokidar source-change watcher, per-instance remediate HTTP
+ * route, trust-level integration for mirror-trust gating, backfill migration.
+ */
+import { EventEmitter } from 'node:events';
+import { getParityRule } from '../providers/parity/registry.js';
+import type { IntelligenceFramework } from '../core/intelligenceProviderFactory.js';
+export interface FrameworkParitySentinelConfig {
+    /** Project root (passed to each rule's verify/remediate). */
+    projectRoot: string;
+    /** State directory (typically `.instar`). */
+    stateDir: string;
+    /** Which frameworks are currently enabled for this agent. */
+    enabledFrameworks: ReadonlyArray<IntelligenceFramework>;
+    /** Scan interval in ms. Default: 1_800_000 (30 min). */
+    scanIntervalMs?: number;
+    /** Initial scan delay in ms. Default: 60_000 (1 min after start). */
+    initialScanDelayMs?: number;
+    /** If true, mirror-trust rules call remediate(); if false, all rules are flag-only. */
+    remediationEnabled?: boolean;
+}
+interface PerInstanceCursor {
+    lastScanAt: string;
+    lastResult: 'ok' | 'drift' | 'conflict' | 'error';
+    lastDetail?: string;
+    /** Number of consecutive scans with unresolved drift — used for degradation reporting. */
+    unresolvedCount: number;
+}
+export interface ParityScanReport {
+    scannedAt: string;
+    rulesWalked: number;
+    instancesChecked: number;
+    gapsFound: number;
+    remediated: number;
+    remediationRefused: number;
+    orphansFound: number;
+}
+export declare class FrameworkParitySentinel extends EventEmitter {
+    private config;
+    private state;
+    private statePath;
+    private interval;
+    private initialTimeout;
+    private isScanning;
+    constructor(config: FrameworkParitySentinelConfig);
+    start(): void;
+    stop(): void;
+    /**
+     * Run a full scan immediately. Returns a structured report. Safe to call
+     * concurrently — overlapping calls are short-circuited.
+     */
+    scan(): Promise<ParityScanReport>;
+    /**
+     * Returns the current scan state — used by the HTTP /api/framework-parity/status route.
+     */
+    getStatus(): {
+        lastScanAt: string | null;
+        cursors: Record<string, PerInstanceCursor>;
+    };
+    private scanRule;
+    private attemptRemediate;
+    private shouldRemediate;
+    private recordRuleError;
+    private loadState;
+    private saveState;
+}
+/**
+ * Lookup a single rule by primitive. Re-exported here so the sentinel's
+ * tests and the HTTP routes have a single import surface.
+ * @internal
+ */
+export declare const _getParityRuleForTest: typeof getParityRule;
+export {};
+//# sourceMappingURL=FrameworkParitySentinel.d.ts.map

package/dist/monitoring/FrameworkParitySentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrameworkParitySentinel.d.ts","sourceRoot":"","sources":["../../src/monitoring/FrameworkParitySentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAEL,aAAa,EACd,MAAM,iCAAiC,CAAC;AAMzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAKpF,MAAM,WAAW,6BAA6B;IAC5C,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,iBAAiB,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACxD,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,UAAU,iBAAiB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,IAAI,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,CAAC;CACzB;AASD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAUD,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,6BAA6B;IASjD,KAAK,IAAI,IAAI;IAsBb,IAAI,IAAI,IAAI;IAaZ;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAkDvC;;OAEG;IACH,SAAS,IAAI;QAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;KAAE;YASxE,QAAQ;YAiFR,gBAAgB;IA4B9B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,SAAS;CAWlB;AAID;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,sBAAgB,CAAC"}

package/dist/monitoring/FrameworkParitySentinel.js

@@ -0,0 +1,286 @@
+/**
+ * FrameworkParitySentinel — consumer of the Layer-3 parity rules registry.
+ *
+ * Spec: specs/instar-foundations/framework-parity-sentinel.md
+ *
+ * Walks the registry on its scan cadence (and on triggers), calls each rule's
+ * verify() per instance, surfaces drift via events + degradation reports, and
+ * (per rule's remediationPolicy) optionally calls remediate() to re-render
+ * canonical into the framework-native shape.
+ *
+ * v0.1 scope:
+ *   - Registry walker (consume listParityRules → iterate → collect verify).
+ *   - State file persistence (.instar/state/framework-parity-sentinel.json).
+ *   - Interval trigger (single setInterval; no chokidar watcher yet).
+ *   - EventEmitter wiring (5 events: gap-found, remediated, remediation-refused,
+ *     orphan-found, scan-complete).
+ *   - Degradation reporter on persistent unresolved gaps.
+ *
+ * v0.2 deferred: chokidar source-change watcher, per-instance remediate HTTP
+ * route, trust-level integration for mirror-trust gating, backfill migration.
+ */
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import path from 'node:path';
+import { listParityRules, getParityRule, } from '../providers/parity/registry.js';
+import { DegradationReporter } from './DegradationReporter.js';
+// ── Helpers ───────────────────────────────────────────────────────
+function cursorKey(primitive, instance) {
+    return `${primitive}::${instance}`;
+}
+// ── Implementation ────────────────────────────────────────────────
+export class FrameworkParitySentinel extends EventEmitter {
+    config;
+    state;
+    statePath;
+    interval = null;
+    initialTimeout = null;
+    isScanning = false;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.statePath = path.join(config.stateDir, 'state', 'framework-parity-sentinel.json');
+        this.state = this.loadState();
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────
+    start() {
+        if (this.interval)
+            return;
+        const intervalMs = this.config.scanIntervalMs ?? 1_800_000;
+        const initialDelay = this.config.initialScanDelayMs ?? 60_000;
+        this.initialTimeout = setTimeout(() => {
+            void this.scan();
+        }, initialDelay);
+        this.initialTimeout.unref?.();
+        this.interval = setInterval(() => {
+            void this.scan();
+        }, intervalMs);
+        this.interval.unref?.();
+        console.log(`[FrameworkParitySentinel] started — interval ${Math.round(intervalMs / 60_000)}m, ` +
+            `first scan in ${Math.round(initialDelay / 1000)}s`);
+    }
+    stop() {
+        if (this.initialTimeout) {
+            clearTimeout(this.initialTimeout);
+            this.initialTimeout = null;
+        }
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    // ── Public API ─────────────────────────────────────────────────
+    /**
+     * Run a full scan immediately. Returns a structured report. Safe to call
+     * concurrently — overlapping calls are short-circuited.
+     */
+    async scan() {
+        if (this.isScanning) {
+            return {
+                scannedAt: new Date().toISOString(),
+                rulesWalked: 0,
+                instancesChecked: 0,
+                gapsFound: 0,
+                remediated: 0,
+                remediationRefused: 0,
+                orphansFound: 0,
+            };
+        }
+        this.isScanning = true;
+        const scannedAt = new Date().toISOString();
+        const report = {
+            scannedAt,
+            rulesWalked: 0,
+            instancesChecked: 0,
+            gapsFound: 0,
+            remediated: 0,
+            remediationRefused: 0,
+            orphansFound: 0,
+        };
+        try {
+            const rules = listParityRules();
+            for (const rule of rules) {
+                report.rulesWalked += 1;
+                await this.scanRule(rule, report);
+            }
+            this.state.lastScanAt = scannedAt;
+            this.saveState();
+            this.emit('parity:scan-complete', report);
+            return report;
+        }
+        catch (err) {
+            DegradationReporter.getInstance().report({
+                feature: 'FrameworkParitySentinel.scan',
+                primary: 'Walk parity rules registry + verify',
+                fallback: 'Scan aborted; cursors not advanced',
+                reason: `Scan error: ${err instanceof Error ? err.message : String(err)}`,
+                impact: 'Cross-framework drift may go undetected until next successful scan',
+            });
+            console.error('[FrameworkParitySentinel] scan error:', err);
+            return report;
+        }
+        finally {
+            this.isScanning = false;
+        }
+    }
+    /**
+     * Returns the current scan state — used by the HTTP /api/framework-parity/status route.
+     */
+    getStatus() {
+        return {
+            lastScanAt: this.state.lastScanAt,
+            cursors: { ...this.state.cursors },
+        };
+    }
+    // ── Scan implementation ────────────────────────────────────────
+    async scanRule(rule, report) {
+        let instances;
+        try {
+            instances = await rule.listInstances(this.config.projectRoot);
+        }
+        catch (err) {
+            this.recordRuleError(rule, err);
+            return;
+        }
+        for (const instance of instances) {
+            report.instancesChecked += 1;
+            const key = cursorKey(rule.primitive, instance);
+            let result = 'ok';
+            let detail;
+            try {
+                const verifyResult = await rule.verify(this.config.projectRoot, instance);
+                if (!verifyResult.ok) {
+                    report.gapsFound += verifyResult.mismatches.length;
+                    const hasConflict = verifyResult.mismatches.some((m) => m.reasonCode === 'user-edit-conflict');
+                    result = hasConflict ? 'conflict' : 'drift';
+                    detail = verifyResult.mismatches.map((m) => `${m.framework}: ${m.detail}`).join('; ');
+                    for (const m of verifyResult.mismatches) {
+                        this.emit('parity:gap-found', m);
+                    }
+                    if (result === 'drift' && this.shouldRemediate(rule)) {
+                        for (const m of verifyResult.mismatches) {
+                            if (m.framework === 'canonical')
+                                continue; // can't remediate canonical drift
+                            await this.attemptRemediate(rule, instance, m.framework, report);
+                        }
+                    }
+                    else if (result === 'conflict') {
+                        for (const m of verifyResult.mismatches) {
+                            this.emit('parity:remediation-refused', m);
+                            report.remediationRefused += 1;
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                result = 'error';
+                detail = err instanceof Error ? err.message : String(err);
+            }
+            const prior = this.state.cursors[key];
+            const unresolvedCount = result === 'ok'
+                ? 0
+                : (prior?.unresolvedCount ?? 0) + 1;
+            this.state.cursors[key] = {
+                lastScanAt: report.scannedAt,
+                lastResult: result,
+                lastDetail: detail,
+                unresolvedCount,
+            };
+            if (unresolvedCount >= 3 && result !== 'ok') {
+                DegradationReporter.getInstance().report({
+                    feature: `parity:${rule.primitive}:${instance}`,
+                    primary: 'Cross-framework parity for this instance',
+                    fallback: 'Drift persists across multiple scans',
+                    reason: detail ?? 'unknown',
+                    impact: `Drift unresolved for ${unresolvedCount} consecutive scans`,
+                });
+            }
+        }
+        // Orphan detection (per rule)
+        try {
+            const orphans = await rule.listOrphans(this.config.projectRoot);
+            for (const o of orphans) {
+                report.orphansFound += 1;
+                this.emit('parity:orphan-found', o);
+            }
+        }
+        catch (err) {
+            this.recordRuleError(rule, err);
+        }
+    }
+    async attemptRemediate(rule, instance, framework, report) {
+        if (framework === 'canonical')
+            return;
+        if (!this.config.enabledFrameworks.includes(framework))
+            return;
+        try {
+            await rule.remediate(this.config.projectRoot, instance, framework);
+            report.remediated += 1;
+            this.emit('parity:remediated', {
+                primitive: rule.primitive,
+                instance,
+                framework,
+            });
+        }
+        catch (err) {
+            report.remediationRefused += 1;
+            this.emit('parity:remediation-refused', {
+                primitive: rule.primitive,
+                instanceName: instance,
+                framework,
+                reasonCode: 'user-edit-conflict',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    shouldRemediate(rule) {
+        if (rule.remediationPolicy === 'flag-only')
+            return false;
+        if (this.config.remediationEnabled === false)
+            return false;
+        return true;
+    }
+    recordRuleError(rule, err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error(`[FrameworkParitySentinel] rule ${rule.primitive} error: ${detail}`);
+        DegradationReporter.getInstance().report({
+            feature: `parity:${rule.primitive}`,
+            primary: 'Walk this primitive\'s parity rule',
+            fallback: 'Skip this rule for this scan; other rules unaffected',
+            reason: detail,
+            impact: `Drift detection for ${rule.primitive} primitive paused until next successful scan`,
+        });
+    }
+    // ── Persistence ────────────────────────────────────────────────
+    loadState() {
+        try {
+            if (fs.existsSync(this.statePath)) {
+                return JSON.parse(fs.readFileSync(this.statePath, 'utf-8'));
+            }
+        }
+        catch {
+            /* start fresh */
+        }
+        return { cursors: {}, lastScanAt: null };
+    }
+    saveState() {
+        try {
+            const dir = path.dirname(this.statePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.statePath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify(this.state, null, 2));
+            fs.renameSync(tmpPath, this.statePath);
+        }
+        catch {
+            // @silent-fallback-ok — state loss just re-scans on next pass
+        }
+    }
+}
+// ── Test seam ─────────────────────────────────────────────────────
+/**
+ * Lookup a single rule by primitive. Re-exported here so the sentinel's
+ * tests and the HTTP routes have a single import surface.
+ * @internal
+ */
+export const _getParityRuleForTest = getParityRule;
+//# sourceMappingURL=FrameworkParitySentinel.js.map

package/dist/monitoring/FrameworkParitySentinel.js.map

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

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.118",
+  "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:06:04.451Z",
-  "instarVersion": "0.28.118",
+  "generatedAt": "2026-05-19T04:26:32.444Z",
+  "instarVersion": "0.28.120",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.119.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — v1.0.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+Lands the FrameworkParitySentinel — the class that walks the Layer-3 parity rules registry (Skill / Hook / Memory), runs each rule's verify() per instance, and routes drift to events (or to remediation, per the rule's declared policy).
+
+v0.1 ships the sentinel as a building block — class + 12 unit tests. HTTP routes (GET /api/framework-parity/status, POST /api/framework-parity/scan) and server.ts boot integration are deferred to a focused follow-up PR. This matches the precedent set by Skill / Hook / Memory parity rules: each shipped as a registry building block first, with operational wiring as a separate step.
+
+Key safety locks: per-rule remediationPolicy is the authority (flag-only never auto-remediates; mirror-trust does); the sentinel-level remediationEnabled config can DOWNGRADE mirror-trust to flag-only but never UPGRADE flag-only. Memory's sacrosanct status is preserved unconditionally. Concurrent scan calls short-circuit to prevent pileup. User-edit-conflict refuses remediation and emits a structured event.
+
+Five new events: parity:gap-found, parity:remediated, parity:remediation-refused, parity:orphan-found, parity:scan-complete. Persistent state at .instar/state/framework-parity-sentinel.json with per (primitive × instance) cursors.
+
+Spec at specs/instar-foundations/framework-parity-sentinel.md (converged + approved). ELI16 companion + convergence report alongside. Original 2026-05-18 proposal at specs/provider-portability/13-framework-parity-sentinel.md is now superseded — left in place for historical reference, frontmatter unchanged.
+
+## What to Tell Your User
+
+- "The piece that runs the cross-framework drift checks is now built. It walks the parity rules every 30 minutes (when wired into the server, coming next), spots when your canonical files have drifted from their rendered forms on Claude or Codex, and either re-renders or flags the drift for you — based on the rule's safety policy."
+- "Memory stays sacrosanct: the sentinel will never auto-regenerate your AGENT.md, USER.md, or MEMORY.md. If they're corrupted, you get a structured alert pointing at the repair procedure."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| FrameworkParitySentinel class | Import from src/monitoring/FrameworkParitySentinel.js. Construct with projectRoot + stateDir + enabledFrameworks. Call scan() for one pass or start() for interval mode. |
+| Per-instance scan cursors | sentinel.getStatus() returns the per (primitive × instance) cursor state — used by the upcoming HTTP route. |
+| Five EventEmitter events | parity:gap-found, parity:remediated, parity:remediation-refused, parity:orphan-found, parity:scan-complete. |
+
+## Deferred (Tracked Follow-ups)
+
+- HTTP routes (GET /api/framework-parity/status, POST /api/framework-parity/scan).
+- server.ts boot integration (construction + start + RouteContext wiring).
+- Integration + E2E tests (land with the HTTP wiring).
+- chokidar source-change watcher (v0.2).
+- Per-instance POST /api/framework-parity/remediate route (v0.2 — pending trust integration).
+- Conversational-action layer wiring (Step 6 of the rollout).

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.

package/upgrades/side-effects/feat-framework-parity-sentinel.md

@@ -0,0 +1,94 @@
+# Side-Effects Review — FrameworkParitySentinel v0.1 (building block)
+
+**Version / slug:** `feat-framework-parity-sentinel`
+**Date:** 2026-05-19
+**Author:** Echo (autonomous mode, hybrid C)
+
+## Summary of the change
+
+Lands the FrameworkParitySentinel as a **building block** — the class that walks the Layer-3 parity rules registry, calls each rule's `verify()` per instance, surfaces drift via events, and (per rule's `remediationPolicy`) optionally calls `remediate()`. Ships with unit tests and structured spec docs.
+
+**Deliberately scoped narrow:** HTTP routes (`GET /api/framework-parity/status`, `POST /api/framework-parity/scan`) and server.ts boot integration are deferred to a follow-up PR. This matches the precedent set by Skill/Hook/Memory parity rules in PRs #252/#253/#254 — each shipped as a building block via the parity registry, with boot integration as a separate step. Shipping the sentinel class now unblocks the registry consumer side; the follow-up wires it into the server lifecycle.
+
+**Files changed (specs):**
+- specs/instar-foundations/framework-parity-sentinel.md (new, converged + approved per pre-auth)
+- specs/instar-foundations/framework-parity-sentinel.eli16.md (new)
+- docs/specs/reports/framework-parity-sentinel-convergence.md (new)
+
+**Files changed (source):**
+- src/monitoring/FrameworkParitySentinel.ts (new — class + lifecycle + scan + state I/O + EventEmitter)
+
+**Files changed (tests):**
+- tests/unit/monitoring/FrameworkParitySentinel.test.ts (new — 12 tests)
+
+**Files changed (release notes):**
+- upgrades/NEXT.md (new)
+- package.json (version bump)
+
+## Decision-point inventory
+
+- **Building-block scope**: ships the class + unit tests; HTTP routes + boot wiring as a follow-up. Matches PR #252/#253/#254 precedent.
+- **Scan cadence default**: 30 min (1_800_000 ms). Configurable.
+- **Initial scan delay**: 60s (allows server to settle before first pass).
+- **Concurrent-scan short-circuit**: second concurrent `scan()` call returns an empty report; prevents pileup on slow rules.
+- **Remediation gating**: per-rule `remediationPolicy` is the authority. Sentinel-level `remediationEnabled` config can DOWNGRADE mirror-trust to flag-only but never UPGRADE flag-only to mirror-trust.
+- **State schema**: `cursors[primitive::instance]` with `lastScanAt`, `lastResult`, `lastDetail`, `unresolvedCount`. Atomic writes via tempfile+rename.
+- **Degradation threshold**: 3 consecutive scans with unresolved drift trips a `DegradationReporter.report()`.
+- **Canonical-side mismatches are signal-only**: when `verify()` returns `framework: 'canonical'` (e.g. missing AGENT.md), the sentinel emits `parity:gap-found` but does NOT call `remediate()` — only the rule can mutate canonical, and Memory's rule throws by design.
+- **Event vocabulary**: `parity:gap-found`, `parity:remediated`, `parity:remediation-refused`, `parity:orphan-found`, `parity:scan-complete`.
+- **Orphan removal is opt-in**: `listOrphans()` always runs; `removeOrphans()` requires explicit operator action (no auto-fire in v0.1).
+
+## Over-block / under-block analysis
+
+**Over-block risk:** the sentinel never blocks operations — it scans + emits + (optionally) re-renders. Worst case is a noisy event stream, filterable at the EventEmitter consumer.
+
+**Under-block risk:** if a rule's `verify()` throws, the sentinel marks that rule failed (via DegradationReporter) and continues with other rules. The failed rule's instances stay at their prior cursor state — drift may persist longer than 30 min until the rule's verify recovers. Mitigated by Degradation reporting (3-consecutive-failure trip) so operators are notified.
+
+**Under-block risk (concurrent scan):** the short-circuit returns an empty report. If a user POSTs `/scan` while an interval scan is in flight (when routes ship), they get back empty + the interval scan continues. Acceptable for v0.1 — adding queue/wait complicates state.
+
+## Level-of-abstraction fit
+
+- Sentinel is the orchestrator. It owns scan timing, state, event emission. Routes/wiring are NOT in v0.1.
+- Rules own canonical definitions, rendering, verification, remediation.
+- Boundary is clean — sentinel never reads canonical formats directly, never knows what a "skill" or "hook" is. Just the registry interface.
+
+## Signal-vs-authority compliance
+
+- Sentinel emits signals (`parity:gap-found`). Rules' `remediationPolicy` and sentinel's `remediationEnabled` are the layered authority.
+- Sentinel never overrides a rule's `flag-only` policy (cannot upgrade).
+- Sentinel respects `user-edit-conflict` by short-circuiting remediation and emitting `parity:remediation-refused`.
+
+## Interaction surface
+
+- Adds one new class under `src/monitoring/`. No HTTP routes, no server.ts wiring, no config additions in v0.1.
+- Optional state file at `.instar/state/framework-parity-sentinel.json` — only written when `scan()` is called. Cold-start safe.
+- No changes to existing rules, registries, or per-primitive infrastructure.
+- No migrations needed (cold-start is a no-op until the follow-up wires it in).
+
+## Rollback cost
+
+- Pure-add. Revert removes the sentinel + tests + spec + state file. No data migrations.
+- Worst-case bug: spurious remediation on healthy artifacts when the follow-up wires it. Mitigated by user-edit-conflict short-circuit + per-rule policy + future `remediationEnabled` kill-switch.
+- Operator emergency (post-follow-up): set `frameworkParity.remediationEnabled: false` in `.instar/config.json` and restart — sentinel becomes signal-only.
+
+## Test coverage
+
+- Unit: 12 tests covering rule walking, event emission for all 5 events, remediation policy routing (mirror-trust + flag-only + user-edit-conflict + config override), concurrent-scan short-circuit, state persistence round-trip, start/stop lifecycle idempotency.
+- Integration + E2E: deferred to the follow-up PR that wires HTTP routes — matches PR #252/#253/#254 precedent (the parity rules in those PRs also shipped unit-tests-only as building blocks).
+
+## Documentation
+
+- Concept spec + ELI16 at `specs/instar-foundations/`.
+- Convergence report at `docs/specs/reports/`.
+- NEXT.md with "What to Tell Your User" entries.
+
+## Deferred (tracked, not silent)
+
+- **HTTP routes** (`GET /api/framework-parity/status`, `POST /api/framework-parity/scan`) — follow-up PR.
+- **server.ts boot integration** (construction + start + RouteContext wiring) — follow-up PR.
+- **Integration + E2E tests** — land with the HTTP wiring.
+- **chokidar source-change watcher** — v0.2.
+- **POST /api/framework-parity/remediate per-instance route** — v0.2 (pending trust integration).
+- **Trust-level integration** for mirror-trust gating (v0.2 — hardcodes allow for v0.1).
+- **Backfill migration** of existing-agent installed base (separate one-shot tool).
+- **Conversational-action layer** (Step 6 of the rollout).