@cairnkeep/cli 2.13.1 → 2.15.0

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

@@ -0,0 +1,383 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants, existsSync } from "node:fs";
+import { lstat, mkdir, open, realpath, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { atomicReplace, hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
+import { PLAYBOOK_ACTION_IDS, PLAYBOOK_CHANGE_TYPES, PLAYBOOK_PROFILES, PLAYBOOK_SCHEMA_VERSION, playbookActorSchema, playbookConfigSchema, playbookEvidenceSchema, playbookSignalsSchema, } from "./playbook-schema.js";
+const MAX_CONFIG_BYTES = 64 * 1024;
+const LOCK_ATTEMPTS = 200;
+const LOCK_WAIT_MS = 10;
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export const PLAYBOOK_ACTIONS = Object.freeze([
+    { id: "context.recall", title: "Recall durable context", command: "/recall <task topic>", description: "Read accepted project memory and derived knowledge before committing to an approach." },
+    { id: "context.explore", title: "Explore focused code context", command: "/context-explore <question>", description: "Collect compact citations when the relevant code is unfamiliar or structurally complex." },
+    { id: "work.plan", title: "Write a bounded plan", command: "Write and track a concise implementation plan.", description: "Plan non-trivial work before editing and keep the plan proportional to the task." },
+    { id: "verify.tests", title: "Run relevant verification", command: "Run the smallest sufficient tests, then broader gates when risk warrants.", description: "Verify changed behavior before claiming completion." },
+    { id: "review.repository", title: "Review the repository change", command: "/repo-review", description: "Review bugs, security, and maintainability after material code changes." },
+    { id: "review.security", title: "Run the governed security audit", command: "/security-audit", description: "Audit security-sensitive changes through the existing governed workflow." },
+    { id: "docs.update", title: "Align documentation", command: "Update and verify affected operating, API, compatibility, and learning documentation.", description: "Keep public behavior and operator guidance synchronized with the implementation." },
+    { id: "learning.capture", title: "Capture reviewed learnings", command: "/remember or stage a candidate for /memory-review", description: "Propose stable decisions, pitfalls, and patterns without automatically promoting them." },
+]);
+const PROFILE_MODES = Object.freeze({
+    minimal: Object.freeze({
+        "context.recall": "may",
+        "context.explore": "may",
+        "work.plan": "may",
+        "verify.tests": "must",
+        "review.repository": "may",
+        "review.security": "should",
+        "docs.update": "should",
+        "learning.capture": "may",
+    }),
+    balanced: Object.freeze({
+        "context.recall": "should",
+        "context.explore": "should",
+        "work.plan": "should",
+        "verify.tests": "must",
+        "review.repository": "should",
+        "review.security": "must",
+        "docs.update": "should",
+        "learning.capture": "should",
+    }),
+    strict: Object.freeze({
+        "context.recall": "must",
+        "context.explore": "must",
+        "work.plan": "must",
+        "verify.tests": "must",
+        "review.repository": "must",
+        "review.security": "must",
+        "docs.update": "must",
+        "learning.capture": "should",
+    }),
+});
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+async function canonicalRoot(projectRoot) {
+    const root = resolve(projectRoot);
+    const canonical = await realpath(root);
+    const info = await stat(canonical);
+    if (!info.isDirectory())
+        throw new Error("Playbook project root is not a directory.");
+    return canonical;
+}
+export async function playbookProjectIdentity(projectRoot = process.cwd()) {
+    const root = await canonicalRoot(projectRoot);
+    const info = await stat(root);
+    return sha256(`cairn:playbook-project:v1\0${root}\0${String(info.dev)}\0${String(info.ino)}`);
+}
+async function paths(projectRoot) {
+    const root = await canonicalRoot(projectRoot);
+    const directory = join(root, ".ai");
+    const config = join(directory, "playbooks.json");
+    const lock = join(directory, ".playbooks.lock");
+    if (dirname(directory) !== root || dirname(config) !== directory || dirname(lock) !== directory) {
+        throw new Error("Playbook configuration path is outside the project root.");
+    }
+    return { root, directory, config, lock };
+}
+async function safeDirectory(directory, create) {
+    try {
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("Playbook configuration directory is unsafe.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if (!create)
+            return;
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("Playbook configuration directory is unsafe.");
+    }
+}
+async function readBounded(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > MAX_CONFIG_BYTES)
+            throw new Error("Playbook configuration is invalid.");
+        const bytes = await handle.readFile();
+        if (bytes.byteLength > MAX_CONFIG_BYTES)
+            throw new Error("Playbook configuration is invalid.");
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readProjectConfig(projectRoot) {
+    const { directory, config } = await paths(projectRoot);
+    try {
+        await safeDirectory(directory, false);
+        if (!existsSync(config))
+            return { exists: false, issues: [] };
+        const info = await lstat(config);
+        if (!info.isFile() || info.isSymbolicLink() || !privatePathIsSafe(config)) {
+            return { exists: true, issues: ["unsafe-config"] };
+        }
+        const bytes = await readBounded(config);
+        if (!bytes)
+            return { exists: false, issues: [] };
+        return { config: playbookConfigSchema.parse(JSON.parse(bytes.toString("utf8"))), exists: true, issues: [] };
+    }
+    catch {
+        return { exists: existsSync(config), issues: ["invalid-config"] };
+    }
+}
+function orderedOverrides(overrides) {
+    const result = {};
+    for (const id of PLAYBOOK_ACTION_IDS)
+        if (overrides[id] !== undefined)
+            result[id] = overrides[id];
+    return result;
+}
+function orderedConfig(profile, overrides) {
+    return playbookConfigSchema.parse({ schema_version: PLAYBOOK_SCHEMA_VERSION, profile, overrides: orderedOverrides(overrides) });
+}
+export async function resolvePlaybookStatus(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const env = options.env ?? process.env;
+    const stored = await readProjectConfig(projectRoot);
+    const issues = [...stored.issues];
+    let profile = stored.config?.profile ?? "balanced";
+    let source = stored.config ? "project" : "default";
+    const rawEnvironmentProfile = env.CAIRN_PLAYBOOK_PROFILE?.trim();
+    if (rawEnvironmentProfile) {
+        if (PLAYBOOK_PROFILES.includes(rawEnvironmentProfile)) {
+            profile = rawEnvironmentProfile;
+            source = "environment";
+        }
+        else
+            issues.push("invalid-environment-profile");
+    }
+    const overrides = orderedOverrides(stored.config?.overrides ?? {});
+    const modes = {};
+    for (const id of PLAYBOOK_ACTION_IDS)
+        modes[id] = overrides[id] ?? PROFILE_MODES[profile][id];
+    const policyDigest = sha256(JSON.stringify({ schema_version: PLAYBOOK_SCHEMA_VERSION, profile, modes: PLAYBOOK_ACTION_IDS.map((id) => [id, modes[id]]) }));
+    return {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        profile,
+        source,
+        overrides,
+        modes,
+        policy_digest: policyDigest,
+        config_exists: stored.exists,
+        issues,
+    };
+}
+async function acquireLock(lock) {
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
+        try {
+            await mkdir(lock, { mode: 0o700 });
+            return () => rm(lock, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const info = await lstat(lock);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Playbook configuration lock is unsafe.");
+            await delay(LOCK_WAIT_MS);
+        }
+    }
+    throw new Error("Playbook configuration is locked; retry after the active update finishes.");
+}
+async function atomicConfigWrite(path, value) {
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    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);
+        await atomicReplace(temporary, path);
+        hardenPrivatePath(path);
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+    }
+}
+async function mutatePolicy(projectRoot, mutation, requireMissing = false) {
+    const target = await paths(projectRoot);
+    await safeDirectory(target.directory, true);
+    const release = await acquireLock(target.lock);
+    try {
+        const read = await readProjectConfig(target.root);
+        if (read.issues.length)
+            throw new Error("Existing playbook configuration is invalid or unsafe.");
+        if (requireMissing && read.config)
+            throw new Error("Playbook configuration already exists.");
+        await atomicConfigWrite(target.config, mutation(read.config));
+    }
+    finally {
+        await release();
+    }
+    return resolvePlaybookStatus({ projectRoot: target.root, env: {} });
+}
+export async function initializePlaybook(projectRoot, profile) {
+    return mutatePolicy(projectRoot, () => orderedConfig(profile, {}), true);
+}
+export async function setPlaybookProfile(projectRoot, profile) {
+    return mutatePolicy(projectRoot, (current) => orderedConfig(profile, current?.overrides ?? {}));
+}
+export async function setPlaybookOverride(projectRoot, action, mode) {
+    return mutatePolicy(projectRoot, (current) => orderedConfig(current?.profile ?? "balanced", { ...(current?.overrides ?? {}), [action]: mode }));
+}
+export async function resetPlaybookOverride(projectRoot, action) {
+    return mutatePolicy(projectRoot, (current) => {
+        const overrides = { ...(current?.overrides ?? {}) };
+        delete overrides[action];
+        return orderedConfig(current?.profile ?? "balanced", overrides);
+    });
+}
+export async function resetPlaybook(projectRoot) {
+    const target = await paths(projectRoot);
+    await safeDirectory(target.directory, false);
+    if (!existsSync(target.directory))
+        return resolvePlaybookStatus({ projectRoot: target.root, env: {} });
+    const release = await acquireLock(target.lock);
+    try {
+        if (!existsSync(target.config))
+            return resolvePlaybookStatus({ projectRoot: target.root, env: {} });
+        const info = await lstat(target.config);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error("Playbook configuration is unsafe.");
+        await rm(target.config);
+    }
+    finally {
+        await release();
+    }
+    return resolvePlaybookStatus({ projectRoot: target.root, env: {} });
+}
+export function normalizeChangedPaths(values) {
+    if (values.length > 256)
+        throw new Error("Too many changed paths.");
+    return [...new Set(values.map((raw) => {
+            const value = raw.replaceAll("\\", "/").replace(/^\.\//, "");
+            if (!value || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value) || isAbsolute(value)
+                || /^[A-Za-z]:\//.test(value) || value.split("/").some((part) => part === ".." || part === "")) {
+                throw new Error("Changed paths must be safe project-relative paths.");
+            }
+            return value;
+        }))].sort();
+}
+export function inferChangeTypes(paths, explicit = []) {
+    const result = new Set(explicit);
+    for (const path of normalizeChangedPaths(paths)) {
+        const lower = path.toLowerCase();
+        const testFile = /(^|\/)(test|tests|spec|specs|__tests__)(\/|$)|\.(test|spec)\./.test(lower);
+        if (testFile)
+            result.add("tests");
+        if (/(^|\/)(docs?|readme|changelog|license)(\/|\.|$)|\.md$/.test(lower))
+            result.add("docs");
+        if (/(^|\/)(package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|requirements[^/]*\.txt|cargo\.lock|go\.(mod|sum))$/.test(lower))
+            result.add("dependencies");
+        if (/(^|\/)(auth|security|crypto|permission|permissions|acl|secret|secrets|token|tokens|network|http|cors)(\/|\.|-|_)/.test(lower))
+            result.add("security");
+        if (/\.(json|ya?ml|toml|ini|conf|config)$|(^|\/)(dockerfile|\.github|\.gitlab-ci\.yml)(\/|$)/.test(lower))
+            result.add("config");
+        if (!testFile && /\.(c|cc|cpp|cs|go|java|js|jsx|kt|mjs|py|rb|rs|sh|swift|ts|tsx)$/.test(lower))
+            result.add("code");
+    }
+    return PLAYBOOK_CHANGE_TYPES.filter((value) => result.has(value));
+}
+function applicability(id, event, signals) {
+    const types = new Set(signals.change_types);
+    const materialCode = types.has("code") || types.has("dependencies") || types.has("security");
+    switch (id) {
+        case "context.recall": return event === "start" ? "Task start benefits from durable project context." : null;
+        case "context.explore": return event !== "finish" && (signals.familiarity !== "known" || signals.complexity === "complex")
+            ? "Focused exploration applies because the context is not fully known or the task is complex." : null;
+        case "work.plan": return event !== "finish" && signals.complexity !== "trivial"
+            ? "A bounded plan applies to standard or complex work." : null;
+        case "verify.tests": return event === "finish" && materialCode
+            ? "Behavior-affecting files changed and require verification." : null;
+        case "review.repository": return event === "finish" && materialCode
+            ? "Material code, dependency, or security changes warrant repository review." : null;
+        case "review.security": return event === "finish" && (types.has("security") || types.has("dependencies") || signals.risk === "security" || signals.risk === "high")
+            ? "Security-sensitive paths, dependencies, or elevated risk trigger the governed audit." : null;
+        case "docs.update": return event === "finish" && (signals.public_change || types.has("config") || types.has("dependencies"))
+            ? "Public behavior, configuration, or dependency behavior may require documentation alignment." : null;
+        case "learning.capture": return event === "finish" && (materialCode || signals.complexity !== "trivial")
+            ? "Material work should offer stable learnings to the reviewed memory gate." : null;
+    }
+}
+function evidenceMap(evidence) {
+    const result = new Map();
+    for (const entry of evidence) {
+        const parsed = playbookEvidenceSchema.parse(entry);
+        if (result.has(parsed.action))
+            throw new Error(`Duplicate evidence for ${parsed.action}.`);
+        result.set(parsed.action, parsed);
+    }
+    return result;
+}
+export async function evaluatePlaybook(options) {
+    if (!SESSION_PATTERN.test(options.sessionId))
+        throw new Error("Invalid playbook session ID.");
+    const actor = playbookActorSchema.parse(options.actor);
+    const signals = playbookSignalsSchema.parse({
+        ...options.signals,
+        changed_paths: normalizeChangedPaths(options.signals.changed_paths),
+        change_types: PLAYBOOK_CHANGE_TYPES.filter((value) => options.signals.change_types.includes(value)),
+    });
+    const status = await resolvePlaybookStatus({ projectRoot: options.projectRoot, env: options.env });
+    const evidence = evidenceMap(options.evidence ?? []);
+    const actions = [];
+    for (const definition of PLAYBOOK_ACTIONS) {
+        const rationale = applicability(definition.id, options.event, signals);
+        const mode = status.modes[definition.id];
+        if (!rationale || mode === "off")
+            continue;
+        const observed = evidence.get(definition.id);
+        const outcome = observed?.outcome ?? "pending";
+        const blocking = mode === "must" && outcome !== "completed";
+        actions.push({ ...definition, mode, rationale, outcome, reason: observed?.reason ?? "", blocking });
+    }
+    const projectIdentity = await playbookProjectIdentity(options.projectRoot);
+    const digestInput = {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        event: options.event,
+        project_identity: projectIdentity,
+        profile: status.profile,
+        policy_digest: status.policy_digest,
+        signals,
+        actions: actions.map(({ id, mode, outcome, reason }) => ({ id, mode, outcome, reason })),
+    };
+    const decisionDigest = sha256(JSON.stringify(digestInput));
+    return {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        event: options.event,
+        project_identity: projectIdentity,
+        actor,
+        session_id: options.sessionId,
+        profile: status.profile,
+        policy_digest: status.policy_digest,
+        decision_digest: decisionDigest,
+        signals,
+        actions,
+        blocking_actions: actions.filter(({ blocking }) => blocking).map(({ id }) => id),
+        advisory_actions: actions.filter(({ mode, outcome }) => mode !== "must" && outcome === "pending").map(({ id }) => id),
+        issues: status.issues,
+    };
+}

package/mcp-memory-server/package.json

@@ -50,9 +50,11 @@
         "check:pi-mcp-bridge": "node scripts/smoke-pi-mcp-bridge.mjs",
         "check:context-pack": "node scripts/smoke-context-pack.mjs",
         "check:work-evidence": "node scripts/smoke-work-evidence.mjs",
+        "check:okf": "node scripts/smoke-okf.mjs",
+        "check:playbook": "node scripts/smoke-playbook.mjs",
         "check:notes": "npm run build && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack && npm run check:work-evidence",
+        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack && npm run check:work-evidence && npm run check:okf && npm run check:playbook",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
         "test:all": "npm run test:memory"
@@ -60,6 +62,7 @@
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",
         "agentfs-sdk": "^0.6.4",
+        "yaml": "2.9.0",
         "zod": "^4.4.3"
     },
     "devDependencies": {

package/opencode/command/cairn-work.md

@@ -0,0 +1,13 @@
+---
+description: Evaluate Cairnkeep's project playbook at task start, scope changes, or finish
+---
+
+<!-- managed-by:cairnkeep -->
+# Cairnkeep playbook check
+
+Run exactly one local command: `cairn playbook check $ARGUMENTS`.
+
+Accept `start`, `check`, or `finish` followed only by documented check options.
+Safely quote every argument. Return the decision and explain which `must`,
+`should`, and `may` actions you will follow. This is policy evaluation only: it
+does not execute an action or grant approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.13.1",
+  "version": "2.15.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,6 +39,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "agentfs-sdk": "^0.6.4",
+    "yaml": "2.9.0",
     "zod": "^4.4.3"
   },
   "scripts": {

package/pi/prompts/cairn-work.md

@@ -0,0 +1,12 @@
+---
+description: Evaluate Cairnkeep's bounded workflow playbook
+argument-hint: "start|check|finish [cairn playbook check options]"
+---
+
+<!-- managed-by:cairnkeep -->
+# Cairnkeep playbook check
+
+Invoke the shell tool exactly once with `cairn playbook check $ARGUMENTS`.
+Accept only `start`, `check`, or `finish` plus documented check options. Return
+the decision verbatim, then state how you will handle its `must`, `should`, and
+`may` actions. Do not treat the decision as execution or approval.

package/schemas/context-pack.schema.json

@@ -12,6 +12,15 @@
     "title": { "type": "string", "minLength": 1, "maxLength": 256 },
     "description": { "type": "string", "minLength": 1, "maxLength": 2048 },
     "license": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "source_format": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "okf" },
+        "version": { "type": "string", "minLength": 1, "maxLength": 32 }
+      }
+    },
     "files": {
       "type": "array",
       "maxItems": 1024,

package/schemas/playbook.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/playbook.schema.json",
+  "title": "Cairnkeep playbook policy v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "profile", "overrides"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "profile": { "enum": ["minimal", "balanced", "strict"] },
+    "overrides": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "context.recall": { "$ref": "#/$defs/mode" },
+        "context.explore": { "$ref": "#/$defs/mode" },
+        "work.plan": { "$ref": "#/$defs/mode" },
+        "verify.tests": { "$ref": "#/$defs/mode" },
+        "review.repository": { "$ref": "#/$defs/mode" },
+        "review.security": { "$ref": "#/$defs/mode" },
+        "docs.update": { "$ref": "#/$defs/mode" },
+        "learning.capture": { "$ref": "#/$defs/mode" }
+      }
+    }
+  },
+  "$defs": {
+    "mode": { "enum": ["must", "should", "may", "off"] }
+  }
+}

package/scripts/bootstrap.sh

@@ -40,6 +40,18 @@ if [[ $untracked -eq 1 ]]; then
   exclude_prefix=$(cd "$target" && git rev-parse --show-prefix)
 fi
 
+if [[ $untracked -eq 0 ]]; then
+  set +e
+  node "$CAIRN_ROOT/scripts/playbook-instructions.mjs" "$target" --check >/dev/null 2>&1
+  instructions_check=$?
+  set -e
+  if [[ $instructions_check -gt 1 ]]; then
+    echo "Cannot safely reconcile Cairnkeep playbook instructions in $target/AGENTS.md" >&2
+    echo "Resolve the managed markers, then retry bootstrap." >&2
+    exit 1
+  fi
+fi
+
 install_file() {
   local src="$1" dest="$2" mode="$3"
   if [[ -e "$dest" ]]; then
@@ -59,6 +71,11 @@ done < <(node "$CAIRN_ROOT/scripts/harness-registry.mjs" bootstrap-assets)
 install_file "$TPL/env.example.template"       "$target/.ai/env.example"       0644
 install_file "$TPL/trajectory-redaction.json.template" "$target/.ai/trajectory-redaction.json" 0644
 install_file "$TPL/capabilities.json.template" "$target/.ai/capabilities.json" 0600
+install_file "$TPL/playbooks.json.template" "$target/.ai/playbooks.json" 0600
+
+if [[ $untracked -eq 0 ]]; then
+  node "$CAIRN_ROOT/scripts/playbook-instructions.mjs" "$target" >/dev/null
+fi
 
 # Project-scope memory is private runtime data. Keep it out of version control
 # even before the first .agentfs/project.db is created.

package/scripts/cairn-cli.mjs

@@ -18,6 +18,7 @@ const NODE_COMMANDS = new Map([
   ["skill", "skill-cli.js"],
   ["graph", "graph-cli.js"],
   ["evidence", "work-evidence-cli.js"],
+  ["playbook", "playbook-cli.js"],
 ]);
 
 const POSIX_COMMANDS = new Map([
@@ -52,6 +53,7 @@ Usage:
   cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
   cairn graph <build|query|status|diff|explain|path>
   cairn evidence <list|show|delete|prune|doctor>
+  cairn playbook <list|status|init|set|enable|disable|reset|check|record|receipts|instructions|doctor>
   cairn memory <path|export|import>
   cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
   cairn uninstall [--dry-run] [--yes] [--purge-memory] [--purge-packs] [PROJECT ...]

package/scripts/completion.sh

@@ -13,7 +13,7 @@ _cairn_complete() {
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
+  commands="bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
@@ -28,6 +28,7 @@ _cairn_complete() {
     trajectory) COMPREPLY=( $(compgen -W "list show prune --json --dry-run" -- "$current") ) ;;
     artifact) COMPREPLY=( $(compgen -W "list show delete prune --kind --session --json --dry-run --include-protected" -- "$current") ) ;;
     evidence) COMPREPLY=( $(compgen -W "list show delete prune doctor --status --json --dry-run --repair" -- "$current") ) ;;
+    playbook) COMPREPLY=( $(compgen -W "list status init set enable disable reset check record receipts instructions doctor minimal balanced strict must should may off start finish install remove context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture --project --json --enforce --complexity --familiarity --risk --public-change --changed --change-type --completed --skipped --failed --actor --actor-kind --session --policy --decision --event --action --outcome --reason" -- "$current") ) ;;
     capabilities)
       case "${COMP_WORDS[2]:-}" in
         enable|disable)
@@ -56,7 +57,7 @@ _cairn_complete() {
       esac
       ;;
     mcp-tools) COMPREPLY=( $(compgen -W "list status set reset full read-only custom --tool --project --json" -- "$current") ) ;;
-    pack) COMPREPLY=( $(compgen -W "init lock validate install list show remove enable disable update skills approve-skill revoke-skill --id --version --title --description --license --ref --project --project-id --check --apply --confirm --json" -- "$current") ) ;;
+    pack) COMPREPLY=( $(compgen -W "init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill --id --version --title --description --license --ref --project --project-id --output --file --note --check --apply --confirm --json" -- "$current") ) ;;
     notes) COMPREPLY=( $(compgen -W "distill search-error promote doctor --project --session --all-projects --para-root --text --component --with --confirm --repair --json" -- "$current") ) ;;
     eval)
       case "${COMP_WORDS[2]:-}" in
@@ -96,6 +97,7 @@ _cairn() {
     'trajectory:inspect and prune local session trajectories'
     'artifact:inspect, delete, and prune local artifacts'
     'evidence:inspect and manage local Git-linked work evidence'
+    'playbook:evaluate and record bounded agent workflow policy'
     'capabilities:inspect and manage project capability state'
     'mcp-tools:inspect and restrict MCP tool exposure'
     'pack:manage immutable context packs and skill approvals'
@@ -132,8 +134,9 @@ _cairn() {
       esac
       ;;
     evidence) _values 'work evidence command' list show delete prune doctor '--status[filter records]:status:(pending complete)' '--dry-run[report without mutation]' '--repair[remove safe temporary remnants]' '--json[emit JSON]' ;;
+    playbook) _values 'playbook command' list status init set enable disable reset check record receipts instructions doctor minimal balanced strict must should may off start finish install remove context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture '--project[project root]:directory:_files -/' '--json[emit JSON]' '--enforce[fail when must evidence is missing]' '--changed[changed project path]:file:_files' '--change-type[change type]:type:(code tests docs config dependencies security)' '--complexity[task complexity]:level:(trivial standard complex)' '--familiarity[context familiarity]:level:(known mixed unfamiliar)' '--risk[task risk]:level:(low normal high security)' '--public-change[public behavior changed]' '--completed[completed action]:action:' '--skipped[skipped action and reason]:evidence:' '--failed[failed action and reason]:evidence:' '--actor[local actor label]:actor:' '--actor-kind[local actor kind]:kind:(user agent service)' '--session[session label]:session:' '--policy[policy digest]:digest:' '--decision[decision digest]:digest:' '--event[lifecycle event]:event:(start check finish)' '--action[canonical action]:action:(context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture)' '--outcome[outcome]:outcome:(completed skipped failed)' '--reason[bounded reason]:reason:' ;;
     mcp-tools) _values 'MCP tool profile command' list status set reset full read-only custom '--tool[allow an exact tool]:tool:' '--project[project root]:directory:_files -/' '--json[emit JSON]' ;;
-    pack) _values 'context pack command' init lock validate install list show remove enable disable update skills approve-skill revoke-skill '--ref[pinned Git ref]:ref:' '--project[project root]:directory:_files -/' '--project-id[remote project ID]:project ID:' '--check[inspect update]' '--apply[apply update]' '--confirm[confirm digest]:digest:' '--json[emit JSON]' ;;
+    pack) _values 'context pack command' init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill '--ref[pinned Git ref]:ref:' '--project[project root]:directory:_files -/' '--project-id[remote project ID]:project ID:' '--output[export output directory]:directory:_files -/' '--file[explicit project Markdown file]:file:_files' '--note[promoted shared note ID]:note ID:' '--check[inspect update or export]' '--apply[apply update or export]' '--confirm[confirm digest]:digest:' '--json[emit JSON]' ;;
     capabilities)
       case $words[3] in
         list|status) _arguments '--json[emit JSON]' ;;
@@ -182,8 +185,8 @@ EOF
   fish)
     sed "s/__CAIRN_HARNESSES__/$harnesses/g" <<'EOF'
 complete -c cairn -f
-for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help
-    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help" -a $command
+for command in bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help
+    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap setup memory-server sync sync-pi sync-kimi doctor trajectory artifact evidence playbook capabilities mcp-tools pack notes eval skill graph memory audit-timer uninstall completion version help" -a $command
 end
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l live-root -r
@@ -212,6 +215,23 @@ complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subc
 complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from list show delete prune doctor" -l json
 complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from delete prune" -l dry-run
 complete -c cairn -n "__fish_seen_subcommand_from evidence; and __fish_seen_subcommand_from doctor" -l repair
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and not __fish_seen_subcommand_from list status init set enable disable reset check record receipts instructions doctor" -a "list status init set enable disable reset check record receipts instructions doctor"
+complete -c cairn -n "__fish_seen_subcommand_from playbook" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from playbook" -l json
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from init set" -a "minimal balanced strict"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -a "start check finish"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l enforce
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l changed -r
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from enable disable reset" -a "context.recall context.explore work.plan verify.tests review.repository review.security docs.update learning.capture"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from enable" -a "must should may"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from instructions" -a "install check remove"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l complexity -r -a "trivial standard complex"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l familiarity -r -a "known mixed unfamiliar"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l risk -r -a "low normal high security"
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l public-change
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l completed -r
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l skipped -r
+complete -c cairn -n "__fish_seen_subcommand_from playbook; and __fish_seen_subcommand_from check" -l failed -r
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and not __fish_seen_subcommand_from list status enable disable reset logging" -a "list status enable disable reset logging"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from enable disable; and not __fish_seen_subcommand_from memory.write memory.search notes.distill wiki graph security.audit route.check context.explore" -a "memory.write memory.search notes.distill wiki graph security.audit route.check context.explore"
 complete -c cairn -n "__fish_seen_subcommand_from capabilities; and __fish_seen_subcommand_from reset; and not __fish_seen_subcommand_from memory.write memory.search notes.distill wiki graph security.audit route.check context.explore" -a "memory.write memory.search notes.distill wiki graph security.audit route.check context.explore"
@@ -223,7 +243,7 @@ complete -c cairn -n "__fish_seen_subcommand_from mcp-tools; and __fish_seen_sub
 complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l project -r
 complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l tool -r
 complete -c cairn -n "__fish_seen_subcommand_from mcp-tools" -l json
-complete -c cairn -n "__fish_seen_subcommand_from pack" -a "init lock validate install list show remove enable disable update skills approve-skill revoke-skill"
+complete -c cairn -n "__fish_seen_subcommand_from pack" -a "init lock validate install import-okf validate-okf export-okf list show remove enable disable update skills approve-skill revoke-skill"
 complete -c cairn -n "__fish_seen_subcommand_from pack" -l project -r
 complete -c cairn -n "__fish_seen_subcommand_from pack" -l project-id -r
 complete -c cairn -n "__fish_seen_subcommand_from pack" -l ref -r