@cairnkeep/cli 2.13.1 → 2.15.0

package/mcp-memory-server/dist/playbook-cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+import { PLAYBOOK_ACTIONS, evaluatePlaybook, inferChangeTypes, initializePlaybook, resetPlaybook, resetPlaybookOverride, resolvePlaybookStatus, setPlaybookOverride, setPlaybookProfile, } from "./playbook.js";
+import { doctorPlaybooks, listPlaybookReceipts, readPlaybookReceipt, recordPlaybookReceipt } from "./playbook-receipt.js";
+import { PLAYBOOK_ACTION_IDS, PLAYBOOK_CHANGE_TYPES, PLAYBOOK_PROFILES, playbookActionIdSchema, playbookActorKindSchema, playbookComplexitySchema, playbookEventSchema, playbookFamiliaritySchema, playbookModeSchema, playbookOutcomeSchema, playbookProfileSchema, playbookRiskSchema, } from "./playbook-schema.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn playbook — bounded workflow policy for coding agents
+
+Usage:
+  cairn playbook list [--json]
+  cairn playbook status [--project PATH] [--json]
+  cairn playbook init [minimal|balanced|strict] [--project PATH] [--json]
+  cairn playbook set minimal|balanced|strict [--project PATH] [--json]
+  cairn playbook enable ACTION must|should|may [--project PATH] [--json]
+  cairn playbook disable ACTION [--project PATH] [--json]
+  cairn playbook reset [ACTION] [--project PATH] [--json]
+  cairn playbook check start|check|finish [signals] [evidence] [--enforce] [--json]
+  cairn playbook record --policy DIGEST --decision DIGEST --event EVENT --action ACTION --outcome OUTCOME [identity] [--json]
+  cairn playbook receipts list|show [RECEIPT] [--project PATH] [--json]
+  cairn playbook instructions install|check|remove [--project PATH] [--json]
+  cairn playbook doctor [--project PATH] [--json]
+
+Check signals:
+  --complexity trivial|standard|complex   --familiarity known|mixed|unfamiliar
+  --risk low|normal|high|security         --public-change
+  --changed PATH...                       --change-type TYPE...
+  --completed ACTION...                   --skipped ACTION=REASON...
+  --failed ACTION=REASON...               --actor ID --actor-kind user|agent|service --session ID
+
+Policies select only Cairnkeep-owned actions. Checking never executes an action,
+contacts a network service, or grants approval. Actor identity is caller-supplied
+and unauthenticated until a future team deployment binds it to authentication.
+`;
+}
+const VALUE_OPTIONS = new Set([
+    "--project", "--complexity", "--familiarity", "--risk", "--changed", "--change-type",
+    "--completed", "--skipped", "--failed", "--actor", "--actor-kind", "--session",
+    "--policy", "--decision", "--event", "--action", "--outcome", "--reason",
+]);
+const FLAG_OPTIONS = new Set(["--json", "--enforce", "--public-change"]);
+const MULTI_OPTIONS = new Set(["--changed", "--change-type", "--completed", "--skipped", "--failed"]);
+function parse(raw) {
+    const positional = [];
+    const options = new Map();
+    const flags = new Set();
+    for (let index = 0; index < raw.length; index += 1) {
+        const value = raw[index];
+        if (FLAG_OPTIONS.has(value)) {
+            if (flags.has(value))
+                throw new Error(`Duplicate ${value}.`);
+            flags.add(value);
+            continue;
+        }
+        if (VALUE_OPTIONS.has(value)) {
+            const values = options.get(value) ?? [];
+            if (!MULTI_OPTIONS.has(value) && values.length)
+                throw new Error(`Duplicate ${value}.`);
+            let consumed = 0;
+            while (index + 1 < raw.length && !raw[index + 1].startsWith("--")) {
+                values.push(raw[index + 1]);
+                index += 1;
+                consumed += 1;
+                if (!MULTI_OPTIONS.has(value))
+                    break;
+            }
+            if (consumed === 0)
+                throw new Error(`Missing value for ${value}.`);
+            options.set(value, values);
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw new Error(`Unknown option ${value}.`);
+        positional.push(value);
+    }
+    return {
+        positional,
+        options,
+        flags,
+        json: flags.has("--json"),
+        projectRoot: options.get("--project")?.[0] ?? process.cwd(),
+    };
+}
+function one(parsed, name, fallback) {
+    return parsed.options.get(name)?.[0] ?? fallback;
+}
+function many(parsed, name) {
+    return parsed.options.get(name) ?? [];
+}
+function ensureAllowed(parsed, allowedOptions, allowedFlags) {
+    for (const key of parsed.options.keys())
+        if (!allowedOptions.includes(key))
+            throw new Error(`${key} is not valid for this command.`);
+    for (const key of parsed.flags)
+        if (!allowedFlags.includes(key))
+            throw new Error(`${key} is not valid for this command.`);
+}
+function output(value, json, human) {
+    process.stdout.write(`${json ? JSON.stringify(value) : human}\n`);
+}
+function humanStatus(status) {
+    return [
+        `Profile: ${status.profile}`,
+        `Source: ${status.source}`,
+        `Policy digest: ${status.policy_digest}`,
+        `Configuration: ${status.config_exists ? ".ai/playbooks.json" : "built-in balanced default"}`,
+        `Issues: ${status.issues.length ? status.issues.join(", ") : "none"}`,
+        ...PLAYBOOK_ACTION_IDS.map((id) => `${id}\t${status.modes[id]}${status.overrides[id] ? "\toverride" : ""}`),
+    ].join("\n");
+}
+function parseEvidence(values, outcome) {
+    return values.map((value) => {
+        const separator = value.indexOf("=");
+        const action = separator < 0 ? value : value.slice(0, separator);
+        const reason = separator < 0 ? "" : value.slice(separator + 1);
+        playbookActionIdSchema.parse(action);
+        if (outcome !== "completed" && reason.trim().length === 0)
+            throw new Error(`${outcome} evidence requires ACTION=REASON.`);
+        return { action: action, outcome, reason };
+    });
+}
+function actor(parsed) {
+    const id = one(parsed, "--actor", process.env.CAIRN_PLAYBOOK_ACTOR ?? "local-agent");
+    const kind = playbookActorKindSchema.parse(one(parsed, "--actor-kind", process.env.CAIRN_PLAYBOOK_ACTOR_KIND ?? "agent"));
+    return { id, kind, authenticated: false };
+}
+function session(parsed) {
+    return one(parsed, "--session", process.env.CAIRN_PLAYBOOK_SESSION ?? `local-${process.pid}`);
+}
+function humanDecision(value) {
+    const lines = [
+        `Playbook: ${value.profile} (${value.policy_digest})`,
+        `Decision: ${value.decision_digest}`,
+        `Event: ${value.event}`,
+    ];
+    if (value.actions.length === 0)
+        lines.push("Actions: none");
+    else {
+        lines.push("Actions:");
+        for (const row of value.actions) {
+            lines.push(`  [${row.outcome === "completed" ? "x" : " "}] ${row.mode.toUpperCase()} ${row.id} — ${row.title}`);
+            lines.push(`      ${row.rationale}`);
+            lines.push(`      ${row.command}`);
+            if (row.reason)
+                lines.push(`      evidence: ${row.outcome} — ${row.reason}`);
+        }
+    }
+    lines.push(`Blocking: ${value.blocking_actions.length ? value.blocking_actions.join(", ") : "none"}`);
+    lines.push("Actor authentication: unverified local assertion");
+    return lines.join("\n");
+}
+async function check(parsed) {
+    ensureAllowed(parsed, ["--project", "--complexity", "--familiarity", "--risk", "--changed", "--change-type", "--completed", "--skipped", "--failed", "--actor", "--actor-kind", "--session"], ["--json", "--enforce", "--public-change"]);
+    if (parsed.positional.length !== 1)
+        throw new Error("check requires one lifecycle event.");
+    const event = playbookEventSchema.parse(parsed.positional[0]);
+    const explicitTypes = many(parsed, "--change-type").map((value) => {
+        if (!PLAYBOOK_CHANGE_TYPES.includes(value))
+            throw new Error(`Unknown change type ${value}.`);
+        return value;
+    });
+    const changed = many(parsed, "--changed");
+    const evidence = [
+        ...parseEvidence(many(parsed, "--completed"), "completed"),
+        ...parseEvidence(many(parsed, "--skipped"), "skipped"),
+        ...parseEvidence(many(parsed, "--failed"), "failed"),
+    ];
+    const value = await evaluatePlaybook({
+        projectRoot: parsed.projectRoot,
+        event,
+        actor: actor(parsed),
+        sessionId: session(parsed),
+        signals: {
+            complexity: playbookComplexitySchema.parse(one(parsed, "--complexity", "standard")),
+            familiarity: playbookFamiliaritySchema.parse(one(parsed, "--familiarity", "mixed")),
+            risk: playbookRiskSchema.parse(one(parsed, "--risk", "normal")),
+            public_change: parsed.flags.has("--public-change"),
+            changed_paths: changed,
+            change_types: inferChangeTypes(changed, explicitTypes),
+        },
+        evidence,
+    });
+    output(value, parsed.json, humanDecision(value));
+    if (value.issues.length)
+        process.exitCode = 2;
+    else if (parsed.flags.has("--enforce") && value.blocking_actions.length)
+        process.exitCode = 3;
+}
+async function record(parsed) {
+    ensureAllowed(parsed, ["--project", "--policy", "--decision", "--event", "--action", "--outcome", "--reason", "--actor", "--actor-kind", "--session"], ["--json"]);
+    if (parsed.positional.length !== 0)
+        throw new Error("record accepts options only.");
+    const value = await recordPlaybookReceipt({
+        projectRoot: parsed.projectRoot,
+        policyDigest: one(parsed, "--policy") ?? "",
+        decisionDigest: one(parsed, "--decision") ?? "",
+        actor: actor(parsed),
+        sessionId: session(parsed),
+        event: playbookEventSchema.parse(one(parsed, "--event")),
+        action: playbookActionIdSchema.parse(one(parsed, "--action")),
+        outcome: playbookOutcomeSchema.parse(one(parsed, "--outcome")),
+        reason: one(parsed, "--reason", ""),
+    });
+    output(value, parsed.json, `Recorded ${value.receipt_id}: ${value.action} ${value.outcome}.`);
+}
+async function main() {
+    const [command = "help", ...raw] = process.argv.slice(2);
+    if (["help", "--help", "-h"].includes(command)) {
+        if (raw.length)
+            throw new Error("help accepts no arguments.");
+        process.stdout.write(usage());
+        return;
+    }
+    const parsed = parse(raw);
+    if (command === "list") {
+        ensureAllowed(parsed, [], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("list accepts no arguments.");
+        const value = { schema_version: 1, profiles: PLAYBOOK_PROFILES, actions: PLAYBOOK_ACTIONS };
+        output(value, parsed.json, PLAYBOOK_ACTIONS.map(({ id, title, command: actionCommand }) => `${id}\t${title}\t${actionCommand}`).join("\n"));
+        return;
+    }
+    if (command === "status") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("status accepts no positional arguments.");
+        const value = await resolvePlaybookStatus({ projectRoot: parsed.projectRoot });
+        output(value, parsed.json, humanStatus(value));
+        if (value.issues.length)
+            process.exitCode = 2;
+        return;
+    }
+    if (command === "init" || command === "set") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length > 1 || (command === "set" && parsed.positional.length !== 1))
+            throw new Error(`${command} requires one profile.`);
+        const profile = playbookProfileSchema.parse(parsed.positional[0] ?? "balanced");
+        const value = command === "init"
+            ? await initializePlaybook(parsed.projectRoot, profile)
+            : await setPlaybookProfile(parsed.projectRoot, profile);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "enable" || command === "disable") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length !== (command === "enable" ? 2 : 1))
+            throw new Error(`${command} has invalid arguments.`);
+        const action = playbookActionIdSchema.parse(parsed.positional[0]);
+        const mode = command === "disable" ? "off" : playbookModeSchema.parse(parsed.positional[1]);
+        if (mode === "off" && command === "enable")
+            throw new Error("Use disable ACTION to turn an action off.");
+        const value = await setPlaybookOverride(parsed.projectRoot, action, mode);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "reset") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length > 1)
+            throw new Error("reset accepts at most one action.");
+        const value = parsed.positional[0]
+            ? await resetPlaybookOverride(parsed.projectRoot, playbookActionIdSchema.parse(parsed.positional[0]))
+            : await resetPlaybook(parsed.projectRoot);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "check") {
+        await check(parsed);
+        return;
+    }
+    if (command === "record") {
+        await record(parsed);
+        return;
+    }
+    if (command === "receipts") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        const operation = parsed.positional[0] ?? "list";
+        if (operation === "list" && parsed.positional.length === 1) {
+            const value = await listPlaybookReceipts(parsed.projectRoot);
+            output(value, parsed.json, value.receipts.length ? value.receipts.map(({ receipt_id, action, outcome, recorded_at }) => `${receipt_id}\t${outcome}\t${action}\t${recorded_at}`).join("\n") : "No playbook receipts found.");
+            return;
+        }
+        if (operation === "show" && parsed.positional.length === 2) {
+            const value = await readPlaybookReceipt(parsed.positional[1], parsed.projectRoot);
+            output(value, parsed.json, JSON.stringify(value, null, 2));
+            return;
+        }
+        throw new Error("receipts requires list or show RECEIPT.");
+    }
+    if (command === "doctor") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("doctor accepts no positional arguments.");
+        const value = await doctorPlaybooks(parsed.projectRoot);
+        output(value, parsed.json, JSON.stringify(value, null, 2));
+        if (!value.ok)
+            process.exitCode = 2;
+        return;
+    }
+    if (command === "instructions") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length !== 1 || !["install", "check", "remove"].includes(parsed.positional[0]))
+            throw new Error("instructions requires install, check, or remove.");
+        const moduleUrl = new URL("../../scripts/playbook-instructions.mjs", import.meta.url).href;
+        const instructionModule = await import(moduleUrl);
+        const value = parsed.positional[0] === "remove"
+            ? instructionModule.removePlaybookInstructions(parsed.projectRoot, { check: false })
+            : instructionModule.reconcilePlaybookInstructions(parsed.projectRoot, { check: parsed.positional[0] === "check" });
+        output(value, parsed.json, `${value.status}: ${value.path}`);
+        if (parsed.positional[0] === "check" && value.status !== "unchanged")
+            process.exitCode = 1;
+        return;
+    }
+    throw new Error(`unknown playbook command "${command}".`);
+}
+main().catch((error) => {
+    process.stderr.write(`cairn playbook: ${error instanceof Error ? error.message : "invalid command or policy"}\n`);
+    process.exitCode = 2;
+});

package/mcp-memory-server/dist/playbook-receipt.js

@@ -0,0 +1,245 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants, existsSync, readdirSync } from "node:fs";
+import { link, lstat, mkdir, open, realpath, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
+import { playbookProjectIdentity, resolvePlaybookStatus } from "./playbook.js";
+import { PLAYBOOK_SCHEMA_VERSION, playbookActionIdSchema, playbookActorSchema, playbookEventSchema, playbookOutcomeSchema, playbookReasonSchema, } from "./playbook-schema.js";
+const MAX_RECEIPT_BYTES = 8 * 1024;
+const MAX_RECEIPTS = 10_000;
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const RECEIPT_PATTERN = /^pbk_[a-f0-9]{32}$/;
+const receiptSchema = z.strictObject({
+    schema_version: z.literal(PLAYBOOK_SCHEMA_VERSION),
+    receipt_id: z.string().regex(RECEIPT_PATTERN),
+    project_identity: z.string().regex(DIGEST_PATTERN),
+    policy_digest: z.string().regex(DIGEST_PATTERN),
+    decision_digest: z.string().regex(DIGEST_PATTERN),
+    actor: playbookActorSchema,
+    session_id: z.string().regex(SESSION_PATTERN),
+    event: playbookEventSchema,
+    action: playbookActionIdSchema,
+    outcome: playbookOutcomeSchema,
+    reason: playbookReasonSchema,
+    recorded_at: z.string().datetime({ offset: true }),
+});
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+async function layout(projectRoot = process.cwd()) {
+    const root = await realpath(resolve(projectRoot));
+    const agentfs = join(root, ".agentfs");
+    const store = join(agentfs, "playbooks");
+    const receipts = join(store, "receipts");
+    if (dirname(agentfs) !== root || dirname(store) !== agentfs || dirname(receipts) !== store) {
+        throw new Error("Playbook receipt store escapes the project root.");
+    }
+    return { root, agentfs, store, receipts };
+}
+async function ensureDirectory(path, parent) {
+    if (existsSync(path)) {
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(path)) {
+            throw new Error("Playbook receipt storage contains an unsafe path.");
+        }
+        return;
+    }
+    const parentInfo = await lstat(parent);
+    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink())
+        throw new Error("Playbook receipt storage parent is unsafe.");
+    await mkdir(path, { mode: 0o700 });
+    hardenPrivatePath(path);
+}
+async function ensureStore(projectRoot) {
+    const target = await layout(projectRoot);
+    if (!existsSync(target.agentfs))
+        await mkdir(target.agentfs, { mode: 0o700 });
+    const agentInfo = await lstat(target.agentfs);
+    if (!agentInfo.isDirectory() || agentInfo.isSymbolicLink())
+        throw new Error("Project .agentfs path is unsafe.");
+    await ensureDirectory(target.store, target.agentfs);
+    await ensureDirectory(target.receipts, target.store);
+    return target.receipts;
+}
+async function safeRead(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_RECEIPT_BYTES || !privatePathIsSafe(path)) {
+        throw new Error("Unsafe playbook receipt.");
+    }
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.size > MAX_RECEIPT_BYTES || opened.dev !== info.dev || opened.ino !== info.ino) {
+            throw new Error("Playbook receipt changed during validation.");
+        }
+        return receiptSchema.parse(JSON.parse((await handle.readFile()).toString("utf8")));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function atomicReceipt(path, value) {
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    if (bytes.byteLength > MAX_RECEIPT_BYTES)
+        throw new Error("Playbook receipt exceeds its storage limit.");
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        hardenPrivatePath(temporary);
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        hardenPrivatePath(path);
+        return true;
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+    }
+}
+function receiptFiles(directory) {
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory).filter((name) => RECEIPT_PATTERN.test(name.replace(/\.json$/, "")) && name.endsWith(".json")).sort();
+}
+export async function recordPlaybookReceipt(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!DIGEST_PATTERN.test(options.policyDigest) || !DIGEST_PATTERN.test(options.decisionDigest))
+        throw new Error("Invalid playbook digest.");
+    if (!SESSION_PATTERN.test(options.sessionId))
+        throw new Error("Invalid playbook session ID.");
+    const actor = playbookActorSchema.parse(options.actor);
+    const event = playbookEventSchema.parse(options.event);
+    const action = playbookActionIdSchema.parse(options.action);
+    const outcome = playbookOutcomeSchema.parse(options.outcome);
+    const reason = playbookReasonSchema.parse(options.reason ?? "");
+    if ((outcome === "skipped" || outcome === "failed") && reason.trim().length === 0) {
+        throw new Error("Skipped or failed playbook actions require a bounded reason.");
+    }
+    const status = await resolvePlaybookStatus({ projectRoot });
+    if (status.issues.length || status.policy_digest !== options.policyDigest)
+        throw new Error("Playbook policy digest is stale or invalid.");
+    const projectIdentity = await playbookProjectIdentity(projectRoot);
+    const identity = {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        project_identity: projectIdentity,
+        policy_digest: options.policyDigest,
+        decision_digest: options.decisionDigest,
+        actor,
+        session_id: options.sessionId,
+        event,
+        action,
+        outcome,
+        reason,
+    };
+    const receiptId = `pbk_${sha256(JSON.stringify(identity)).slice(0, 32)}`;
+    const directory = await ensureStore(projectRoot);
+    if (receiptFiles(directory).length >= MAX_RECEIPTS)
+        throw new Error("Playbook receipt limit reached; archive or remove old project state.");
+    const path = join(directory, `${receiptId}.json`);
+    if (existsSync(path))
+        return safeRead(path);
+    const receipt = receiptSchema.parse({ ...identity, receipt_id: receiptId, recorded_at: (options.now ?? new Date()).toISOString() });
+    return await atomicReceipt(path, receipt) ? receipt : safeRead(path);
+}
+export async function listPlaybookReceipts(projectRoot = process.cwd()) {
+    const { receipts } = await layout(projectRoot);
+    if (!existsSync(receipts))
+        return { schema_version: PLAYBOOK_SCHEMA_VERSION, receipts: [] };
+    const info = await lstat(receipts);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("Playbook receipt store is unsafe.");
+    const values = [];
+    for (const name of receiptFiles(receipts))
+        values.push(await safeRead(join(receipts, name)));
+    values.sort((left, right) => right.recorded_at.localeCompare(left.recorded_at) || left.receipt_id.localeCompare(right.receipt_id));
+    return { schema_version: PLAYBOOK_SCHEMA_VERSION, receipts: values };
+}
+export async function readPlaybookReceipt(selector, projectRoot = process.cwd()) {
+    if (!/^(?:pbk_)?[a-f0-9]{6,32}$/.test(selector))
+        throw new Error("Invalid playbook receipt selector.");
+    const values = (await listPlaybookReceipts(projectRoot)).receipts.filter(({ receipt_id }) => receipt_id === selector || receipt_id.startsWith(selector.startsWith("pbk_") ? selector : `pbk_${selector}`));
+    if (values.length === 0)
+        throw new Error("Playbook receipt not found.");
+    if (values.length > 1)
+        throw new Error("Playbook receipt selector is ambiguous.");
+    return values[0];
+}
+export async function doctorPlaybooks(projectRoot = process.cwd()) {
+    const status = await resolvePlaybookStatus({ projectRoot });
+    const policyIssues = [...status.issues];
+    const receiptIssues = [];
+    let count = 0;
+    try {
+        const target = await layout(projectRoot);
+        const ai = join(target.root, ".ai");
+        if (existsSync(ai)) {
+            const info = await lstat(ai);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                policyIssues.push("unsafe playbook configuration directory");
+            else {
+                for (const name of readdirSync(ai).sort()) {
+                    if (name === ".playbooks.lock" || /^\.playbooks\.json\..+\.tmp$/.test(name)) {
+                        policyIssues.push(`playbook configuration remnant: ${name}`);
+                    }
+                }
+            }
+        }
+        if (existsSync(target.store)) {
+            const info = await lstat(target.store);
+            if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(target.store)) {
+                receiptIssues.push("unsafe playbook receipt root");
+            }
+            else {
+                for (const name of readdirSync(target.store).sort()) {
+                    if (name !== "receipts")
+                        receiptIssues.push(`unexpected playbook store entry: ${name}`);
+                }
+            }
+        }
+        if (existsSync(target.receipts)) {
+            const info = await lstat(target.receipts);
+            if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(target.receipts))
+                receiptIssues.push("unsafe receipt directory");
+            else {
+                const names = readdirSync(target.receipts).sort();
+                for (const name of names) {
+                    if (!name.endsWith(".json") || !RECEIPT_PATTERN.test(name.slice(0, -5))) {
+                        receiptIssues.push(`unexpected receipt entry: ${name}`);
+                        continue;
+                    }
+                    try {
+                        await safeRead(join(target.receipts, name));
+                        count += 1;
+                    }
+                    catch {
+                        receiptIssues.push(`invalid receipt: ${name}`);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        receiptIssues.push("receipt store diagnostic failed");
+    }
+    return {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        ok: policyIssues.length === 0 && receiptIssues.length === 0,
+        policy: { ok: policyIssues.length === 0, issues: policyIssues },
+        receipts: { ok: receiptIssues.length === 0, count, issues: receiptIssues },
+    };
+}

package/mcp-memory-server/dist/playbook-schema.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export const PLAYBOOK_SCHEMA_VERSION = 1;
+export const PLAYBOOK_PROFILES = ["minimal", "balanced", "strict"];
+export const PLAYBOOK_MODES = ["must", "should", "may", "off"];
+export const PLAYBOOK_EVENTS = ["start", "check", "finish"];
+export const PLAYBOOK_COMPLEXITIES = ["trivial", "standard", "complex"];
+export const PLAYBOOK_FAMILIARITIES = ["known", "mixed", "unfamiliar"];
+export const PLAYBOOK_RISKS = ["low", "normal", "high", "security"];
+export const PLAYBOOK_CHANGE_TYPES = ["code", "tests", "docs", "config", "dependencies", "security"];
+export const PLAYBOOK_OUTCOMES = ["completed", "skipped", "failed"];
+export const PLAYBOOK_ACTOR_KINDS = ["user", "agent", "service"];
+export const PLAYBOOK_ACTION_IDS = [
+    "context.recall",
+    "context.explore",
+    "work.plan",
+    "verify.tests",
+    "review.repository",
+    "review.security",
+    "docs.update",
+    "learning.capture",
+];
+export const playbookProfileSchema = z.enum(PLAYBOOK_PROFILES);
+export const playbookModeSchema = z.enum(PLAYBOOK_MODES);
+export const playbookEventSchema = z.enum(PLAYBOOK_EVENTS);
+export const playbookComplexitySchema = z.enum(PLAYBOOK_COMPLEXITIES);
+export const playbookFamiliaritySchema = z.enum(PLAYBOOK_FAMILIARITIES);
+export const playbookRiskSchema = z.enum(PLAYBOOK_RISKS);
+export const playbookChangeTypeSchema = z.enum(PLAYBOOK_CHANGE_TYPES);
+export const playbookOutcomeSchema = z.enum(PLAYBOOK_OUTCOMES);
+export const playbookActorKindSchema = z.enum(PLAYBOOK_ACTOR_KINDS);
+export const playbookActionIdSchema = z.enum(PLAYBOOK_ACTION_IDS);
+export const playbookOverridesSchema = z.partialRecord(playbookActionIdSchema.or(z.never()), playbookModeSchema);
+export const playbookConfigSchema = z.strictObject({
+    schema_version: z.literal(PLAYBOOK_SCHEMA_VERSION),
+    profile: playbookProfileSchema,
+    overrides: playbookOverridesSchema,
+});
+export const playbookActorSchema = z.strictObject({
+    id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/),
+    kind: playbookActorKindSchema,
+    authenticated: z.literal(false),
+});
+export const playbookReasonSchema = z.string().max(512).refine((value) => !/[\u0000-\u001f\u007f]/.test(value), "Playbook reasons must not contain control characters.");
+export const playbookEvidenceSchema = z.strictObject({
+    action: playbookActionIdSchema,
+    outcome: playbookOutcomeSchema,
+    reason: playbookReasonSchema,
+});
+export const playbookSignalsSchema = z.strictObject({
+    complexity: playbookComplexitySchema,
+    familiarity: playbookFamiliaritySchema,
+    risk: playbookRiskSchema,
+    public_change: z.boolean(),
+    changed_paths: z.array(z.string().min(1).max(512)).max(256),
+    change_types: z.array(playbookChangeTypeSchema).max(PLAYBOOK_CHANGE_TYPES.length),
+});