instar 0.28.116 → 0.28.117

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAOlE,wBAAgB,aAAa,CAAC,SAAS,EAAE,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAEpF;AAED,wBAAgB,eAAe,IAAI,aAAa,CAAC,UAAU,CAAC,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,IAAI,CAOtG"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AASlE,wBAAgB,aAAa,CAAC,SAAS,EAAE,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAEpF;AAED,wBAAgB,eAAe,IAAI,aAAa,CAAC,UAAU,CAAC,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,IAAI,CAOtG"}

package/dist/providers/parity/registry.js

@@ -12,8 +12,10 @@
  * rules are code; registration is declarative.
  */
 import { skillParityRule } from './rules/skillParityRule.js';
+import { hookParityRule } from './rules/hookParityRule.js';
 const RULES = new Map([
     [skillParityRule.primitive, skillParityRule],
+    [hookParityRule.primitive, hookParityRule],
 ]);
 export function getParityRule(primitive) {
     return RULES.get(primitive);

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

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/providers/parity/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,MAAM,KAAK,GAAyC,IAAI,GAAG,CAAC;IAC1D,CAAC,eAAe,CAAC,SAAS,EAAE,eAAe,CAAC;CAC7C,CAAC,CAAC;AAEH,MAAM,UAAU,aAAa,CAAC,SAA8B;IAC1D,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAA8B,EAAE,IAAgB;IACxF,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,GAAG,EAAE;QACV,IAAI,KAAK;YAAE,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;;YAClC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/providers/parity/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,MAAM,KAAK,GAAyC,IAAI,GAAG,CAAC;IAC1D,CAAC,eAAe,CAAC,SAAS,EAAE,eAAe,CAAC;IAC5C,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,UAAU,aAAa,CAAC,SAA8B;IAC1D,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAA8B,EAAE,IAAgB;IACxF,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,GAAG,EAAE;QACV,IAAI,KAAK;YAAE,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;;YAClC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC"}

package/dist/providers/parity/rules/hookParityRule.d.ts

@@ -0,0 +1,34 @@
+/**
+ * hookParityRule — parity rule for the Hook functional primitive.
+ *
+ * Specs:
+ *   - specs/instar-concepts/hook.md (canonical shape + event vocabulary)
+ *   - specs/frameworks/claude-code/hooks.md
+ *   - specs/frameworks/codex-cli/hooks.md
+ *
+ * Reads canonical hooks from `.instar/hooks/<event>/<name>.<ext>` and
+ * verifies each framework renders them correctly (script copy + entry in
+ * the framework's settings/config file).
+ *
+ * v0.1 scope: session-start event only. Adding additional events =
+ * extending the EVENT_NAME_MAPPING table at the top of the file.
+ *
+ * Reuses the Skill prototype's hardening patterns:
+ *   - C1: strict slug grammar at every entry point.
+ *   - C5: symmetric verify + orphan detection.
+ *   - C7: x-instar-stamp comment line distinguishes user-edit-conflict
+ *     from canonical drift; remediate refuses to overwrite conflicts.
+ *
+ * Deferred to v0.2 (tracked in concept spec):
+ *   - Events beyond session-start.
+ *   - Executable-bit verification (currently set on render; not verified).
+ *   - hooks.json/settings.json merge semantics for non-Instar entries.
+ *     v0.1 manages only entries whose script paths live under
+ *     `.claude/hooks/<canonical-event>/` or `.agent/openai/hooks/<canonical-event>/`.
+ */
+import type { ParityRule } from '../types.js';
+export declare class CanonicalHookError extends Error {
+    constructor(message: string);
+}
+export declare const hookParityRule: ParityRule;
+//# sourceMappingURL=hookParityRule.d.ts.map

package/dist/providers/parity/rules/hookParityRule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookParityRule.d.ts","sourceRoot":"","sources":["../../../../src/providers/parity/rules/hookParityRule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,KAAK,EACV,UAAU,EAGX,MAAM,aAAa,CAAC;AAkBrB,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAsZD,eAAO,MAAM,cAAc,EAAE,UA6E5B,CAAC"}

package/dist/providers/parity/rules/hookParityRule.js

@@ -0,0 +1,463 @@
+/**
+ * hookParityRule — parity rule for the Hook functional primitive.
+ *
+ * Specs:
+ *   - specs/instar-concepts/hook.md (canonical shape + event vocabulary)
+ *   - specs/frameworks/claude-code/hooks.md
+ *   - specs/frameworks/codex-cli/hooks.md
+ *
+ * Reads canonical hooks from `.instar/hooks/<event>/<name>.<ext>` and
+ * verifies each framework renders them correctly (script copy + entry in
+ * the framework's settings/config file).
+ *
+ * v0.1 scope: session-start event only. Adding additional events =
+ * extending the EVENT_NAME_MAPPING table at the top of the file.
+ *
+ * Reuses the Skill prototype's hardening patterns:
+ *   - C1: strict slug grammar at every entry point.
+ *   - C5: symmetric verify + orphan detection.
+ *   - C7: x-instar-stamp comment line distinguishes user-edit-conflict
+ *     from canonical drift; remediate refuses to overwrite conflicts.
+ *
+ * Deferred to v0.2 (tracked in concept spec):
+ *   - Events beyond session-start.
+ *   - Executable-bit verification (currently set on render; not verified).
+ *   - hooks.json/settings.json merge semantics for non-Instar entries.
+ *     v0.1 manages only entries whose script paths live under
+ *     `.claude/hooks/<canonical-event>/` or `.agent/openai/hooks/<canonical-event>/`.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const CANONICAL_ROOT = '.instar/hooks';
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ALLOWED_EXTS = new Set(['.sh', '.js', '.mjs', '.cjs', '.ts']);
+const STAMP_COMMENT_RE = /^#\s*x-instar-stamp:\s*([a-f0-9]{64})\s*$/m;
+const STAMP_COMMENT_STRIP_RE = /^#\s*x-instar-stamp:\s*[a-f0-9]{64}\s*\r?\n/m;
+const EVENT_NAME_MAPPING = {
+    'session-start': { claude: 'SessionStart', codex: 'session_start' },
+};
+const SUPPORTED_EVENTS = Object.keys(EVENT_NAME_MAPPING);
+export class CanonicalHookError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CanonicalHookError';
+    }
+}
+function validateSlug(value, context) {
+    if (typeof value !== 'string' || !SLUG_RE.test(value)) {
+        throw new CanonicalHookError(`${context}: invalid slug "${value}". Must match ${SLUG_RE.source}.`);
+    }
+}
+function validateExt(ext, context) {
+    if (!ALLOWED_EXTS.has(ext)) {
+        throw new CanonicalHookError(`${context}: invalid extension "${ext}". Allowed: ${[...ALLOWED_EXTS].join(', ')}`);
+    }
+}
+function sha256(s) {
+    return crypto.createHash('sha256').update(s, 'utf-8').digest('hex');
+}
+function parseInstanceName(instanceName) {
+    const slash = instanceName.indexOf('/');
+    if (slash < 0) {
+        throw new CanonicalHookError(`instanceName "${instanceName}" must be in the form "<event>/<name>.<ext>"`);
+    }
+    const event = instanceName.slice(0, slash);
+    const fileName = instanceName.slice(slash + 1);
+    const dot = fileName.lastIndexOf('.');
+    if (dot <= 0) {
+        throw new CanonicalHookError(`instanceName "${instanceName}" must end with an extension (.sh, .js, .mjs, .cjs, .ts)`);
+    }
+    const name = fileName.slice(0, dot);
+    const ext = fileName.slice(dot);
+    return { event, name, ext };
+}
+async function readCanonicalHook(projectRoot, instanceName) {
+    const { event, name, ext } = parseInstanceName(instanceName);
+    validateSlug(event, 'canonical hook event');
+    validateSlug(name, 'canonical hook name');
+    validateExt(ext, 'canonical hook extension');
+    if (!(event in EVENT_NAME_MAPPING)) {
+        throw new CanonicalHookError(`event "${event}" is not in the v0.1 supported set. Supported: ${SUPPORTED_EVENTS.join(', ')}`);
+    }
+    const scriptPath = path.join(projectRoot, CANONICAL_ROOT, event, `${name}${ext}`);
+    let body;
+    try {
+        body = await fs.readFile(scriptPath, 'utf-8');
+    }
+    catch (err) {
+        throw new CanonicalHookError(`canonical hook script missing or unreadable: ${path.relative(projectRoot, scriptPath)} — ${err.message}`);
+    }
+    // Strip a leading stamp comment from body before hashing so the canonical
+    // body hash is stable across rendering cycles.
+    const bodyForHash = body.replace(STAMP_COMMENT_STRIP_RE, '');
+    return {
+        instanceName,
+        event: event,
+        name,
+        ext,
+        body: bodyForHash,
+        bodyHash: sha256(bodyForHash),
+    };
+}
+async function listCanonicalHookInstances(projectRoot) {
+    const root = path.join(projectRoot, CANONICAL_ROOT);
+    const out = [];
+    let eventDirs;
+    try {
+        eventDirs = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && SLUG_RE.test(e.name))
+            .map((e) => e.name);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    for (const event of eventDirs) {
+        if (!(event in EVENT_NAME_MAPPING))
+            continue;
+        const eventDir = path.join(root, event);
+        let files;
+        try {
+            files = (await fs.readdir(eventDir, { withFileTypes: true })).map((e) => ({
+                name: e.name,
+                isFile: e.isFile(),
+            }));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!f.isFile)
+                continue;
+            const dot = f.name.lastIndexOf('.');
+            if (dot <= 0)
+                continue;
+            const baseName = f.name.slice(0, dot);
+            const ext = f.name.slice(dot);
+            if (!SLUG_RE.test(baseName))
+                continue;
+            if (!ALLOWED_EXTS.has(ext))
+                continue;
+            out.push(`${event}/${f.name}`);
+        }
+    }
+    return out.sort();
+}
+function withStamp(body, bodyHash) {
+    const stampLine = `# x-instar-stamp: ${bodyHash}\n`;
+    // Insert stamp right after a shebang if present, else at the top.
+    if (body.startsWith('#!')) {
+        const nl = body.indexOf('\n');
+        if (nl < 0)
+            return body + '\n' + stampLine;
+        return body.slice(0, nl + 1) + stampLine + body.slice(nl + 1);
+    }
+    return stampLine + body;
+}
+function extractStamp(rendered) {
+    const m = rendered.match(STAMP_COMMENT_RE);
+    return m ? m[1] : null;
+}
+function bodyWithoutStamp(rendered) {
+    return rendered.replace(STAMP_COMMENT_STRIP_RE, '');
+}
+function claudeLayout(projectRoot, hook) {
+    return {
+        scriptPath: path.join(projectRoot, '.claude/hooks', hook.event, `${hook.name}${hook.ext}`),
+        configPath: path.join(projectRoot, '.claude/settings.json'),
+    };
+}
+function codexLayout(projectRoot, hook) {
+    return {
+        scriptPath: path.join(projectRoot, '.agent/openai/hooks', hook.event, `${hook.name}${hook.ext}`),
+        configPath: path.join(projectRoot, '.agent/openai/hooks.json'),
+    };
+}
+async function readJsonOrDefault(p, def) {
+    try {
+        const raw = await fs.readFile(p, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return def;
+    }
+}
+function nativeEventForFramework(event, framework) {
+    const m = EVENT_NAME_MAPPING[event];
+    return framework === 'claude-code' ? m.claude : m.codex;
+}
+async function renderClaudeHook(projectRoot, hook) {
+    const layout = claudeLayout(projectRoot, hook);
+    await fs.mkdir(path.dirname(layout.scriptPath), { recursive: true });
+    await fs.writeFile(layout.scriptPath, withStamp(hook.body, hook.bodyHash), 'utf-8');
+    await fs.chmod(layout.scriptPath, 0o755);
+    // Merge settings.json hook entry.
+    const settings = await readJsonOrDefault(layout.configPath, {});
+    const eventKey = nativeEventForFramework(hook.event, 'claude-code');
+    const arr = settings.hooks?.[eventKey] ?? [];
+    const relScriptPath = path.relative(projectRoot, layout.scriptPath);
+    const desiredCommand = `bash ${relScriptPath}`;
+    const existing = arr.find((entry) => entry.hooks?.some((h) => h.command === desiredCommand));
+    if (!existing) {
+        arr.push({
+            matcher: '',
+            hooks: [{ type: 'command', command: desiredCommand, timeout: 10000 }],
+        });
+        settings.hooks = { ...(settings.hooks ?? {}), [eventKey]: arr };
+        await fs.mkdir(path.dirname(layout.configPath), { recursive: true });
+        await fs.writeFile(layout.configPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    }
+}
+async function renderCodexHook(projectRoot, hook) {
+    const layout = codexLayout(projectRoot, hook);
+    await fs.mkdir(path.dirname(layout.scriptPath), { recursive: true });
+    await fs.writeFile(layout.scriptPath, withStamp(hook.body, hook.bodyHash), 'utf-8');
+    await fs.chmod(layout.scriptPath, 0o755);
+    await fs.mkdir(path.dirname(layout.configPath), { recursive: true });
+    const config = await readJsonOrDefault(layout.configPath, { hooks: [] });
+    const eventKey = nativeEventForFramework(hook.event, 'codex-cli');
+    const arr = config.hooks ?? [];
+    const relScriptPath = path.relative(projectRoot, layout.scriptPath);
+    const existing = arr.find((entry) => entry.event === eventKey && entry.script === relScriptPath);
+    if (!existing) {
+        arr.push({ event: eventKey, script: relScriptPath });
+        config.hooks = arr;
+        await fs.writeFile(layout.configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    }
+}
+async function verifyClaudeHook(projectRoot, hook) {
+    const layout = claudeLayout(projectRoot, hook);
+    const issues = [];
+    let rendered = null;
+    try {
+        rendered = await fs.readFile(layout.scriptPath, 'utf-8');
+    }
+    catch {
+        issues.push({
+            reasonCode: 'missing-rendered-file',
+            detail: `expected ${path.relative(projectRoot, layout.scriptPath)} to exist`,
+        });
+        return issues;
+    }
+    const stamp = extractStamp(rendered);
+    const rBody = bodyWithoutStamp(rendered);
+    if (rBody !== hook.body) {
+        if (stamp && stamp === hook.bodyHash) {
+            issues.push({
+                reasonCode: 'user-edit-conflict',
+                detail: `claude hook script body differs from canonical but stamp matches — user edited the rendering`,
+            });
+        }
+        else {
+            issues.push({
+                reasonCode: 'body-content-mismatch',
+                detail: `claude hook script body differs from canonical (stamp ${stamp ? 'stale' : 'missing'})`,
+            });
+        }
+    }
+    // settings.json entry presence
+    const settings = await readJsonOrDefault(layout.configPath, {});
+    const eventKey = nativeEventForFramework(hook.event, 'claude-code');
+    const arr = settings.hooks?.[eventKey] ?? [];
+    const relScriptPath = path.relative(projectRoot, layout.scriptPath);
+    const desiredCommand = `bash ${relScriptPath}`;
+    const hasEntry = arr.some((entry) => entry.hooks?.some((h) => h.command === desiredCommand));
+    if (!hasEntry) {
+        issues.push({
+            reasonCode: 'sibling-artifact-missing',
+            detail: `settings.json missing hook entry for ${eventKey} → ${relScriptPath}`,
+        });
+    }
+    return issues;
+}
+async function verifyCodexHook(projectRoot, hook) {
+    const layout = codexLayout(projectRoot, hook);
+    const issues = [];
+    let rendered = null;
+    try {
+        rendered = await fs.readFile(layout.scriptPath, 'utf-8');
+    }
+    catch {
+        issues.push({
+            reasonCode: 'missing-rendered-file',
+            detail: `expected ${path.relative(projectRoot, layout.scriptPath)} to exist`,
+        });
+        return issues;
+    }
+    const stamp = extractStamp(rendered);
+    const rBody = bodyWithoutStamp(rendered);
+    if (rBody !== hook.body) {
+        if (stamp && stamp === hook.bodyHash) {
+            issues.push({
+                reasonCode: 'user-edit-conflict',
+                detail: `codex hook script body differs from canonical but stamp matches — user edited the rendering`,
+            });
+        }
+        else {
+            issues.push({
+                reasonCode: 'body-content-mismatch',
+                detail: `codex hook script body differs from canonical (stamp ${stamp ? 'stale' : 'missing'})`,
+            });
+        }
+    }
+    const config = await readJsonOrDefault(layout.configPath, {});
+    const eventKey = nativeEventForFramework(hook.event, 'codex-cli');
+    const relScriptPath = path.relative(projectRoot, layout.scriptPath);
+    const hasEntry = (config.hooks ?? []).some((entry) => entry.event === eventKey && entry.script === relScriptPath);
+    if (!hasEntry) {
+        issues.push({
+            reasonCode: 'sibling-artifact-missing',
+            detail: `hooks.json missing entry for ${eventKey} → ${relScriptPath}`,
+        });
+    }
+    return issues;
+}
+// ─── Orphan detection ──────────────────────────────────────────────────
+async function listFrameworkScripts(projectRoot, framework) {
+    const root = framework === 'claude-code'
+        ? path.join(projectRoot, '.claude/hooks')
+        : path.join(projectRoot, '.agent/openai/hooks');
+    let eventDirs;
+    try {
+        eventDirs = (await fs.readdir(root, { withFileTypes: true }))
+            .filter((e) => e.isDirectory() && SLUG_RE.test(e.name))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const event of eventDirs) {
+        let files;
+        try {
+            files = (await fs.readdir(path.join(root, event), { withFileTypes: true })).map((e) => ({
+                name: e.name,
+                isFile: e.isFile(),
+            }));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            if (!f.isFile)
+                continue;
+            const dot = f.name.lastIndexOf('.');
+            if (dot <= 0)
+                continue;
+            const baseName = f.name.slice(0, dot);
+            const ext = f.name.slice(dot);
+            if (!SLUG_RE.test(baseName))
+                continue;
+            if (!ALLOWED_EXTS.has(ext))
+                continue;
+            out.push({ event, name: baseName, ext, fullPath: path.join(root, event, f.name) });
+        }
+    }
+    return out;
+}
+async function findOrphans(projectRoot, framework, canonicalInstances) {
+    const rendered = await listFrameworkScripts(projectRoot, framework);
+    const out = [];
+    for (const r of rendered) {
+        const instanceName = `${r.event}/${r.name}${r.ext}`;
+        if (canonicalInstances.has(instanceName))
+            continue;
+        out.push({
+            primitive: 'hook',
+            instanceName,
+            framework,
+            reasonCode: 'orphan-rendering-found',
+            detail: `rendered hook script has no canonical counterpart: ${path.relative(projectRoot, r.fullPath)}`,
+        });
+    }
+    return out;
+}
+async function removeOrphanScripts(projectRoot, framework, canonicalInstances) {
+    const rendered = await listFrameworkScripts(projectRoot, framework);
+    const removed = [];
+    for (const r of rendered) {
+        const instanceName = `${r.event}/${r.name}${r.ext}`;
+        if (canonicalInstances.has(instanceName))
+            continue;
+        await fs.rm(r.fullPath, { force: true });
+        removed.push(r.fullPath);
+    }
+    return removed;
+}
+// ─── Exported ParityRule ───────────────────────────────────────────────
+export const hookParityRule = {
+    primitive: 'hook',
+    frameworks: ['claude-code', 'codex-cli'],
+    remediationPolicy: 'mirror-trust',
+    async listInstances(projectRoot) {
+        return listCanonicalHookInstances(projectRoot);
+    },
+    async verify(projectRoot, instanceName) {
+        let hook;
+        try {
+            hook = await readCanonicalHook(projectRoot, instanceName);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                mismatches: [
+                    {
+                        primitive: 'hook',
+                        instanceName,
+                        framework: 'canonical',
+                        reasonCode: 'canonical-read-error',
+                        detail: err.message,
+                    },
+                ],
+            };
+        }
+        const mismatches = [];
+        for (const framework of this.frameworks) {
+            const issues = framework === 'claude-code'
+                ? await verifyClaudeHook(projectRoot, hook)
+                : await verifyCodexHook(projectRoot, hook);
+            for (const issue of issues) {
+                mismatches.push({
+                    primitive: 'hook',
+                    instanceName,
+                    framework,
+                    reasonCode: issue.reasonCode,
+                    detail: issue.detail,
+                });
+            }
+        }
+        return { ok: mismatches.length === 0, mismatches };
+    },
+    async remediate(projectRoot, instanceName, framework) {
+        const hook = await readCanonicalHook(projectRoot, instanceName);
+        // Refuse on user-edit-conflict.
+        const issues = framework === 'claude-code'
+            ? await verifyClaudeHook(projectRoot, hook)
+            : await verifyCodexHook(projectRoot, hook);
+        const conflict = issues.find((i) => i.reasonCode === 'user-edit-conflict');
+        if (conflict) {
+            throw new CanonicalHookError(`refused to remediate ${instanceName} on ${framework} due to user-edit-conflict: ${conflict.detail}`);
+        }
+        if (framework === 'claude-code') {
+            await renderClaudeHook(projectRoot, hook);
+        }
+        else {
+            await renderCodexHook(projectRoot, hook);
+        }
+    },
+    async listOrphans(projectRoot) {
+        const canonical = new Set(await listCanonicalHookInstances(projectRoot));
+        const out = [];
+        for (const framework of this.frameworks) {
+            out.push(...(await findOrphans(projectRoot, framework, canonical)));
+        }
+        return out;
+    },
+    async removeOrphans(projectRoot, framework) {
+        const canonical = new Set(await listCanonicalHookInstances(projectRoot));
+        return removeOrphanScripts(projectRoot, framework, canonical);
+    },
+};
+//# sourceMappingURL=hookParityRule.js.map

package/dist/providers/parity/rules/hookParityRule.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.116",
+  "version": "0.28.117",
   "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-19T01:19:09.899Z",
-  "instarVersion": "0.28.116",
+  "generatedAt": "2026-05-19T01:38:36.605Z",
+  "instarVersion": "0.28.117",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {

package/upgrades/0.28.116.md

@@ -1,48 +1,23 @@
-# Upgrade Guide — v1.0.2
+# Upgrade Guide — v1.0.3
 
 <!-- bump: patch -->
 
 ## What Changed
 
-Ships the Skill concept spec, two per-framework rendering specs, and a first concrete parity rule + registry that consumes them. Three categories of work in this release:
-
-**Spec docs (pure docs, no behavior change on their own):**
-- `specs/instar-concepts/skill.md` — formal Layer-3 definition of the Skill primitive, framework-agnostic. Carries `review-convergence` and `approved` frontmatter after a 6-of-7 reviewer convergence round on 2026-05-18 (Grok was not available this session).
-- `specs/instar-concepts/skill.eli16.md` — plain-English companion.
-- `specs/frameworks/claude-code/skills.md` — Claude rendering contract.
-- `specs/frameworks/codex-cli/skills.md` — Codex rendering contract (path + sibling `agents/openai.yaml` shape).
-
-**Parity rule + registry (new code, opt-in — no auto-run yet):**
-- `src/providers/parity/types.ts` — `ParityRule` contract, `ParityMismatch` shape with reason-code enum, framework slot widened to include `'canonical'` for source-layer issues.
-- `src/providers/parity/registry.ts` — minimal `ParityRegistry` holding rules; future `FrameworkParitySentinel` will consume this.
-- `src/providers/parity/rules/skillParityRule.ts` — first concrete rule. Strict slug grammar at every entry point (path-traversal safe), `js-yaml` FAILSAFE parsing (fail-loud on errors and git-merge-conflict markers), symmetric verify (canonical → renderings AND renderings → canonical for orphans), `x-instar-stamp` field on rendered files to distinguish user-edits from canonical drift, description sanitization (control chars stripped, length capped at 256 chars), refuses to auto-remediate `user-edit-conflict` cases.
-
-**Hardening surfaced by the convergence round (already applied):**
-- C1 path traversal via name — strict slug grammar (`^[a-z0-9][a-z0-9-]{0,63}$`) enforced at every entry point.
-- C2 hand-rolled YAML parser — replaced with `js-yaml` (FAILSAFE schema).
-- C5 orphan detection — symmetric verify + `listOrphans()` + `removeOrphans()`.
-- C7 user-edit destruction — `x-instar-stamp` + `user-edit-conflict` distinction; remediate refuses to overwrite.
-- C8 description prompt-injection surface — control-char strip + length cap.
-- H1 dir-name vs frontmatter-name authority — dir name authoritative; mismatch is `canonical-read-error`.
-- H5 canonical-read error tagging — `framework: 'canonical'` slot added.
-
-**Deferred (tracked in spec, NOT in this release):**
-- Backfill migration that scans existing `.claude/skills/` + `.agents/skills/` and populates canonical at `.instar/skills/`. Without this, the parity rule is a structural no-op on existing agents (their canonical dir is empty). The rule works correctly on agents that have canonical content; unit tests synthesize canonical to cover the happy path.
-- `allowed-tools` rendering (Claude frontmatter + Codex `dependencies.tools`) — lands with the Tool primitive.
-- Atomic-write (tempfile + rename) — narrows the race window further; single-machine + single-sentinel-pass makes the current write-pattern safe enough for v0.1.
-- BackupManager default-includes update for `.instar/skills/` — separate PR.
-- CLAUDE.md template update referencing canonical path — separate PR.
+Lands the second Layer-3 functional primitive parity rule: Hook. Follows the Skill prototype's template (canonical-source-of-truth + per-framework rendering + parity rule that keeps them in sync), with hook-specific details (event vocabulary, script executable contract, settings.json/hooks.json merge semantics).
+
+v0.1 covers the `session-start` event only. Remaining events are documented in the canonical vocabulary but not yet rendered; extension is mechanical (one entry in the EVENT_NAME_MAPPING table per event).
+
+Reuses all of the Skill prototype's hardening: strict slug grammar at every entry point, x-instar-stamp distinguishing user-edits from canonical drift, symmetric verify with orphan detection, remediate refuses on user-edit-conflict. Hook-specific additions: leading-comment stamp format (`# x-instar-stamp: <sha256>`), executable-bit on render (chmod +x), settings.json hook-table merge that preserves non-Instar entries, hooks.json hook-array merge with the same property.
+
+Concept spec at `specs/instar-concepts/hook.md` (converged + approved); per-framework specs at `specs/frameworks/claude-code/hooks.md` and `specs/frameworks/codex-cli/hooks.md`.
 
 ## What to Tell Your User
 
-- "We've shipped the first piece of a system that keeps your skills in sync across the agent frameworks we support. Right now it works on new skills you create through the canonical path; existing skills won't be touched until a follow-up backfill migration lands."
-- "No action needed on your end."
+- "Hooks (small scripts that fire automatically on lifecycle events like session-start) now have the same canonical-source-and-rendering pattern that skills do. Currently the parity rule covers session-start; the other events follow the same shape and land mechanically."
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| Skill parity rule (programmatic) | Available via `import { skillParityRule } from 'src/providers/parity/registry'`. No automatic run yet — sentinel that consumes the registry is a separate follow-up. |
-| Strict slug grammar for canonical skills | Enforced automatically; canonical with invalid names rejected at read time. |
-| User-edit-conflict detection | Automatic — rendered SKILL.md carries `x-instar-stamp` and verify distinguishes user-edits from canonical drift. |
-| Orphan rendered-skill cleanup | Programmatic via `skillParityRule.removeOrphans(projectRoot, framework)`. |
+| Hook parity rule (programmatic) | Available via the parity registry — `getParityRule('hook')`. No automatic run yet (sentinel is a separate follow-up). |

package/upgrades/0.28.117.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v1.0.3
+
+<!-- bump: patch -->
+
+## What Changed
+
+Lands the second Layer-3 functional primitive parity rule: Hook. Follows the Skill prototype's template (canonical-source-of-truth + per-framework rendering + parity rule that keeps them in sync), with hook-specific details (event vocabulary, script executable contract, settings.json/hooks.json merge semantics).
+
+v0.1 covers the `session-start` event only. Remaining events are documented in the canonical vocabulary but not yet rendered; extension is mechanical (one entry in the EVENT_NAME_MAPPING table per event).
+
+Reuses all of the Skill prototype's hardening: strict slug grammar at every entry point, x-instar-stamp distinguishing user-edits from canonical drift, symmetric verify with orphan detection, remediate refuses on user-edit-conflict. Hook-specific additions: leading-comment stamp format (`# x-instar-stamp: <sha256>`), executable-bit on render (chmod +x), settings.json hook-table merge that preserves non-Instar entries, hooks.json hook-array merge with the same property.
+
+Concept spec at `specs/instar-concepts/hook.md` (converged + approved); per-framework specs at `specs/frameworks/claude-code/hooks.md` and `specs/frameworks/codex-cli/hooks.md`.
+
+## What to Tell Your User
+
+- "Hooks (small scripts that fire automatically on lifecycle events like session-start) now have the same canonical-source-and-rendering pattern that skills do. Currently the parity rule covers session-start; the other events follow the same shape and land mechanically."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Hook parity rule (programmatic) | Available via the parity registry — `getParityRule('hook')`. No automatic run yet (sentinel is a separate follow-up). |

package/upgrades/side-effects/feat-hook-primitive.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Hook primitive + parity rule
+
+**Version / slug:** `feat-hook-primitive`
+**Date:** 2026-05-19
+**Author:** Echo (autonomous mode, hybrid C)
+
+## Summary of the change
+
+Lands the Hook primitive prototype: concept spec, two framework rendering specs, parity rule registered in the existing registry. v0.1 covers the `session-start` event only; remaining events tracked as mechanical extensions of the EVENT_NAME_MAPPING table.
+
+**Files changed (specs):**
+- specs/instar-concepts/hook.md (new, converged + approved per pre-auth)
+- specs/instar-concepts/hook.eli16.md (new)
+- specs/frameworks/claude-code/hooks.md (new)
+- specs/frameworks/codex-cli/hooks.md (new)
+- docs/specs/reports/hook-concept-convergence.md (new)
+
+**Files changed (source):**
+- src/providers/parity/rules/hookParityRule.ts (new)
+- src/providers/parity/registry.ts (hookParityRule registered)
+
+**Files changed (tests):**
+- tests/unit/providers/parity/hookParityRule.test.ts (new — 22 tests)
+- tests/unit/providers/parity/registry.test.ts (updated for 2-rule registry)
+
+**Files changed (release notes):**
+- upgrades/NEXT.md (new)
+- package.json (version bump)
+
+## Decision-point inventory
+
+- **Canonical path location**: `.instar/hooks/<event>/<name>.<ext>` — mirrors `.instar/skills/<name>/` pattern.
+- **Event vocabulary**: canonical kebab-case (`session-start`, `pre-compact`, ...); per-framework mapping in code.
+- **v0.1 event scope**: session-start only — proves the pattern; extension is mechanical.
+- **Script extension allowlist**: .sh, .js, .mjs, .cjs, .ts.
+- **Stamp format**: leading `# x-instar-stamp: <sha256>` comment line; sha256 of canonical body (with stamp stripped) is the stamp value.
+- **settings.json merge semantics**: only manages entries whose script paths live under `.claude/hooks/<canonical-event>/`. Other user-added hook entries are preserved.
+- **hooks.json merge semantics**: only manages entries whose script paths live under `.agent/openai/hooks/<canonical-event>/`. Other entries preserved.
+- **Migration backfill**: DEFERRED (same shape as Skill backfill; one follow-up PR can cover both primitives).
+
+---
+
+## 1–7. Analysis
+
+### Over-block
+None. Parity rule is opt-in; no auto-run point.
+
+### Under-block
+Same as Skill v0.1: no atomic writes, no executable-bit explicit verification (set on render, presumed to persist), no backfill migration (existing agents' canonical empty). All tracked.
+
+### Level-of-abstraction fit
+Correct. hookParityRule lives alongside skillParityRule in `src/providers/parity/rules/`; shares the same `ParityRule` contract. Event-name mapping is a per-rule concern; types layer doesn't need changes.
+
+### Signal vs authority
+Same as Skill — rule emits signals (mismatches), sentinel (future) is the authority.
+
+### Interactions
+- **`refreshHooksAndSettings()`** — currently installs hooks via `installInstarHooks()`; not touched here. Future migration story covers the canonical-vs-direct-install reconciliation.
+- **`migrateHooks()` in PostUpdateMigrator** — currently always-overwrites built-in hooks under `.claude/hooks/instar/`. This continues to work; the parity rule is opt-in and doesn't conflict.
+
+### External surfaces
+- Public API: new `hookParityRule` export from `src/providers/parity/`.
+- Process surface: only when remediate() invoked explicitly — writes script + chmod + settings/config merge.
+
+### Rollback cost
+Trivial. Revert removes the rule + registry entry; no on-disk state changed by this PR alone.
+
+## Tests
+22 new tests in `hookParityRule.test.ts` covering slug grammar (path traversal, capitals, spaces rejected; only v0.1 events listed), canonical-read errors tagged with framework: 'canonical', remediate (claude script + settings.json entry, codex script + hooks.json entry, executable bit, settings preservation, idempotent), user-edit-conflict via stamp, orphan detection + removal, rule metadata. Plus 4 updated registry tests for 2-rule registry.
+
+Total parity tests: 53/53 passing (27 Skill + 22 Hook + 4 registry). Typecheck clean.
+
+## Evidence
+Abbreviated convergence — see docs/specs/reports/hook-concept-convergence.md. Bug found during test development (stamp-strip regex was leaving trailing whitespace, causing post-render verify to flag user-edit-conflict on freshly-rendered files) — fixed by tightening STAMP_COMMENT_STRIP_RE to consume the trailing newline.