instar 0.28.118 → 0.28.119

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.118",
+  "version": "0.28.119",
   "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-19T02:38:16.455Z",
+  "instarVersion": "0.28.119",
   "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/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).