@cairnkeep/cli 2.14.0 → 2.15.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.15.1] - 2026-08-17
+
+### Fixed
+
+- Make concurrent playbook policy updates tolerate lock handoff races,
+  including transient Windows directory-removal errors, while retaining
+  fail-closed validation for unsafe lock objects.
+- Strengthen the playbook concurrency regression with repeated mixed profile
+  and reset operations across the supported Node and Windows CI matrix.
+
+## [2.15.0] - 2026-08-17
+
+### Added
+
+- Add strict local project playbooks with `minimal`, `balanced`, and `strict`
+  profiles, bounded canonical action overrides, deterministic start/check/finish
+  decisions, enforcement for missing `must` evidence, and stable policy and
+  decision digests.
+- Add private project-bound outcome receipts with bounded unauthenticated actor
+  provenance, lifecycle inspection, and doctor validation without storing
+  prompts, source bodies, changed paths, diffs, credentials, or command output.
+- Add ownership-safe managed `AGENTS.md` guidance plus thin Claude, OpenCode,
+  Pi, and Kimi `/cairn-work` adapters; Codex and Qwen use the portable project
+  instructions without automatic skill activation.
+- Add an implementation-ready future team-mode contract covering authenticated
+  identity, scopes, ACLs, review queues, audit history, tenant isolation,
+  retention, migration, and release gates while keeping team operation deferred.
+- Add a release-verified playbook lesson, course checkpoint, feature/curriculum
+  coverage, and companion video script.
+
+### Changed
+
+- Guided setup and tracked bootstrap now install the balanced policy and safely
+  reconcile the managed agent-instruction block. Untracked bootstrap leaves
+  shared `AGENTS.md` untouched.
+- Extend completion, native Windows, package, doctor, and backup-first uninstall
+  coverage to the playbook lifecycle and harness adapters.
+
 ## [2.14.0] - 2026-08-17
 
 ### Added
@@ -370,7 +408,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.14.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.15.1...HEAD
+[2.15.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.15.0...v2.15.1
+[2.15.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.14.0...v2.15.0
 [2.14.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.1...v2.14.0
 [2.13.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.0...v2.13.1
 [2.13.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.12.0...v2.13.0

package/README.md

@@ -32,11 +32,11 @@ verification, and the first remember/recall cycle.
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`setup`, `bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
-`doctor`, `trajectory`, `artifact`, `evidence`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
+`doctor`, `playbook`, `trajectory`, `artifact`, `evidence`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
 agents, hooks) installed on Claude Code and OpenCode, plus the native Pi
-trajectory extension and thin Pi/Kimi graph adapters. The generic launchers
+trajectory extension and thin Pi/Kimi graph and playbook adapters. The generic launchers
 expose wrapper seams (`.ai/pre-launch.sh`/`.ai/pre-launch.ps1`,
 `CAIRN_EXTRA_SETTINGS`, `.ai/post-exit.sh`/`.ai/post-exit.ps1`) so an enterprise wrapper can add provider/credential setup
 without forking them. Also shipped: context exploration (`/context-explore`) and
@@ -48,6 +48,9 @@ Version 2.12 adds a declarative harness registry, first-class Codex project
 setup, and a shorter path from installation to verified recall.
 Version 2.13 adds opt-in local Git-linked work evidence around generated harness
 launchers, including native Windows, without capturing prompts or replacing Git.
+Version 2.15 adds bounded project playbooks that help agents select existing
+recall, planning, verification, review, security, documentation, and learning
+steps without becoming an agent runtime or granting approval.
 
 ## Compatibility
 
@@ -199,6 +202,19 @@ patterns/transactional-migrations: Use transactional migrations for schema chang
 The exact command rendering depends on the client. Any MCP client can call
 `memory_write` and `memory_search` directly.
 
+Setup also installs a balanced `.ai/playbooks.json` policy and an ownership-safe
+managed block in `AGENTS.md`. Agents can evaluate it at task boundaries:
+
+```bash
+cairn playbook check start --complexity standard --familiarity mixed
+cairn playbook check finish --changed src/example.ts --completed verify.tests --enforce
+```
+
+The result selects only existing Cairnkeep actions. It never runs them, enables
+a disabled capability, grants approval, or promotes memory automatically. Use
+`cairn playbook status`, `set minimal|balanced|strict`, and `enable|disable` to
+inspect or customize the project policy.
+
 For Codex CLI, `cairn setup --harness codex --memory local` writes the
 project-scoped `.codex/config.toml` entry and both POSIX and native Windows
 launchers. Review the configuration and trust the project before launching.
@@ -325,6 +341,10 @@ search):
 | `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read/related tools (default off) |
 | `CAIRN_CONTEXT_PACK_HTTP` | Separately consent to context-pack tools over authenticated HTTP (default off) |
 | `CAIRN_PACK_BASE_DIR` | Immutable pack objects, source records, pointers, and retrieval cache (default `~/.cairnkeep/packs`) |
+| `CAIRN_PLAYBOOK_PROFILE` | Process-only playbook profile override: `minimal`, `balanced`, or `strict` (project default: `balanced`) |
+| `CAIRN_PLAYBOOK_ACTOR` | Optional local receipt label; caller-supplied and unauthenticated in v2.15 |
+| `CAIRN_PLAYBOOK_ACTOR_KIND` | Optional local actor kind: `user`, `agent`, or `service` |
+| `CAIRN_PLAYBOOK_SESSION` | Optional bounded session label used by playbook decisions and receipts |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
 | `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |

package/claude/commands/cairn-work.md

@@ -0,0 +1,19 @@
+---
+description: Evaluate Cairnkeep's project playbook at task start, scope changes, or finish
+argument-hint: "start|check|finish [cairn playbook check options]"
+allowed-tools: Bash
+---
+
+<!-- managed-by:cairnkeep -->
+# Cairnkeep playbook check
+
+Run exactly one local command:
+
+```text
+cairn playbook check $ARGUMENTS
+```
+
+Accept `start`, `check`, or `finish` followed only by check options documented by
+`cairn playbook --help`. Safely quote every argument. Return the decision
+and explain which `must`, `should`, and `may` actions you will follow. Never
+claim that this command executed an action or granted approval.

package/docs/design/team-mode.md

@@ -0,0 +1,145 @@
+# Team mode design contract
+
+**Status:** design only; not shipped in Cairnkeep 2.15
+
+Cairnkeep 2.15 remains a local, single-operator product. Its playbook receipts
+carry provider-neutral project and actor fields so a future authenticated team
+service can preserve provenance, but those fields are caller assertions and
+must not be used for authorization. This document defines the boundary a team
+implementation must satisfy before that statement can change.
+
+## Goal and non-goals
+
+Team mode would let an organization share reviewed memory, context packs,
+policies, decisions, and workflow evidence without turning private local
+stores into a common bucket. It must retain local-first operation and explicit
+promotion. It is not collaborative editing, an agent runtime, employee
+monitoring, automatic message ingestion, or an implicit channel for prompts,
+credentials, source trees, or session transcripts.
+
+## Identity and project scope
+
+The service must authenticate a human or workload before accepting a team
+operation. Stable internal subject IDs, organization IDs, and canonical project
+IDs are authoritative; display names, email addresses, Git usernames, and the
+current 2.15 `--actor` value are labels only. Authentication adapters may use
+OIDC/OAuth, mTLS workload identity, or a locally administered service token,
+but normalized claims must include issuer, subject, audience, authentication
+time, and credential class. Tokens and raw identity claims never enter memory
+or receipts.
+
+Every object has exactly one scope:
+
+| Scope | Owner | Default visibility | Promotion |
+|---|---|---|---|
+| personal | authenticated subject | that subject | explicit review request |
+| project | canonical project | authorized project members | project review policy |
+| team | organization collection | named collection members | collection review policy |
+
+Reads never fall through from one project or organization to another. A
+personal object is not discoverable through project search until its selected,
+redacted form has been approved and copied as a new immutable project object.
+
+## Authorization
+
+Authorization must be deny-by-default and evaluated server-side after
+authentication. Minimum roles are `reader`, `contributor`, `reviewer`,
+`maintainer`, and `auditor`. Roles map to explicit operations rather than broad
+administrator shortcuts:
+
+- readers may list and read approved project objects;
+- contributors may create private proposals and submit review requests;
+- reviewers may approve or reject proposals but cannot alter their bytes;
+- maintainers may manage membership, retention, and project policy but cannot
+  approve their own content unless an explicit small-team exception is enabled
+  and audited;
+- auditors may read append-only audit records, not content by default.
+
+Capability contracts and MCP profiles remain an additional intersection. An
+ACL cannot enable a disabled capability, broaden a tool profile, satisfy a
+human confirmation, or make a destructive operation read-only.
+
+## Review and conflict model
+
+Shared durable memory and policies use immutable proposals. A proposal binds
+the source scope, source object digest, redacted candidate bytes, base revision,
+target scope, submitter identity, policy digest, and expiry. Approval creates a
+new immutable revision and an audit event; it never mutates the proposal.
+
+Concurrent proposals against the same base remain separate. The service may
+compute a deterministic conflict report but must not select or merge a winner.
+A reviewer resolves the conflict by accepting one proposal or submitting new
+combined bytes. Playbook distribution follows the same review path and may not
+silently replace a project override.
+
+## Audit and receipts
+
+Accepted operations append a canonical event containing organization,
+project, subject, credential class, operation, object identity and digests,
+authorization decision, policy revision, request ID, server time, and result.
+Rejected privileged operations append a value-free denial event. Audit records
+exclude prompt bodies, source content, secrets, tokens, full environment
+snapshots, and unredacted personal data.
+
+Audit history is append-only, hash-linked, bounded by an explicit retention
+class, exportable by auditors, and covered by backup/restore verification.
+Corrections append superseding events; they never rewrite history. A team
+playbook receipt must distinguish the authenticated server subject from any
+agent label supplied by a harness.
+
+## Tenant isolation and storage
+
+Organization and project identity must be part of every storage key and every
+cache key. Database row policies or physically separate stores must be tested
+with cross-tenant negative cases. Context-pack objects may be content-addressed
+globally only when existence, metadata, timing, and deduplication cannot leak
+across tenants; otherwise storage is tenant-local. Encryption keys, backup
+namespaces, search indexes, embedding caches, temporary files, logs, and rate
+limits observe the same boundary.
+
+The HTTP deployment must retain authentication, Host and CORS validation,
+request-size limits, timeouts, and explicit feature consent. No unauthenticated
+compatibility mode may expose team data.
+
+## Retention, deletion, and portability
+
+Each scope declares retention for content, proposals, receipts, audit events,
+indexes, and backups. Legal hold is an explicit audited state. Deletion first
+revokes visibility, then schedules content and derived indexes for removal;
+immutable audit tombstones retain only the minimum identifiers required by the
+declared policy. An organization export uses open, versioned schemas with
+digests and includes neither credentials nor another tenant's deduplicated
+metadata.
+
+## Migration and compatibility
+
+Enabling team mode is an explicit deployment and project decision. Existing
+local memory, packs, policies, and receipts remain local until individually
+selected for a previewable import. The importer validates schemas and digests,
+shows destination scope and redactions, and requires confirmation. There is no
+automatic upload, background synchronization, or inference from local paths.
+
+Offline local commands keep working when a team service is unavailable. Local
+and server configuration use separate names and provenance so failover cannot
+mistake an unverified local actor for an authenticated subject. Downgrade and
+export paths must be documented before general availability.
+
+## Admission gates
+
+Team mode is not releasable until all of the following have evidence:
+
+1. Threat model and independent security review covering authentication,
+   authorization, confused-deputy attacks, tenant isolation, and audit integrity.
+2. Cross-tenant tests for every read, search, cache, export, backup, and error
+   path, plus concurrent proposal and stale-policy tests.
+3. A privacy review with data inventory, retention/deletion exercises, and
+   proof that local projects never upload implicitly.
+4. Restore and disaster-recovery rehearsal preserving scope, audit links, and
+   revision digests.
+5. A migration pilot using synthetic data, followed by an explicitly approved
+   limited real-world pilot with rollback.
+6. Operational ownership for identity-provider failures, revocation latency,
+   incident response, audit export, and key rotation.
+
+Until these gates pass, Cairnkeep documentation and output must describe actor
+identity as unverified and team support as deferred.

package/docs/harness-compatibility.md

@@ -14,20 +14,21 @@ Cairnkeep commands, hooks or native trajectory capture.
 
 | Harness | Supported surface | Runtime status |
 |---|---|---|
-| Claude Code | Memory MCP, commands, agents, hooks, launcher | Exercised by Cairnkeep tests |
-| OpenCode | Memory MCP, commands, workflows, plugins, launcher | Exercised by Cairnkeep tests |
-| Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph Skill | Launcher tested; remote MCP tested with Kimi Code 0.30.0; graph Skill contract-tested |
-| Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
-| Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, and graph prompt | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
-| Codex CLI | Project-scoped memory MCP and launcher | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
+| Claude Code | Memory MCP, commands (including `/cairn-work`), agents, hooks, launcher | Exercised by Cairnkeep tests |
+| OpenCode | Memory MCP, commands (including `/cairn-work`), workflows, plugins, launcher | Exercised by Cairnkeep tests |
+| Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph and cairn-work Skills | Launcher tested; remote MCP tested with Kimi Code 0.30.0; Skills contract-tested |
+| Qwen Code | Memory MCP, launcher, project `AGENTS.md` playbook guidance | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
+| Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, graph and cairn-work prompts | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
+| Codex CLI | Project-scoped memory MCP, launcher, and project `AGENTS.md` playbook guidance | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
-Kimi receives one narrow graph Skill, while Pi receives one narrow graph prompt;
+Kimi receives narrow graph and playbook Skills, while Pi receives matching narrow prompts;
 neither is equivalent to the full commands, agents, hooks, and plugins surface.
 Qwen skills and hooks still require harness-specific adaptation and validation.
-Codex receives a project-local MCP entry and launcher, but not Cairnkeep-specific
-commands, hooks, agents, or automatic skill activation.
+Codex receives a project-local MCP entry, launcher, and portable playbook
+instructions, but not Cairnkeep-specific commands, hooks, agents, or automatic
+skill activation.
 
 Every MCP client receives complete tool annotations and may use a Cairnkeep
 least-authority profile independent of harness assets. Context-pack tools are
@@ -48,7 +49,7 @@ extension; it does not expand the other support levels.
 
 Run `cairn sync-pi --apply` explicitly to install
 `extensions/cairnkeep-memory.ts`, `extensions/cairnkeep-trajectory.ts`, and
-`prompts/graphify.md` under the Pi agent root. Use `--check` for drift and
+`prompts/graphify.md`, and `prompts/cairn-work.md` under the Pi agent root. Use `--check` for drift and
 `cairn doctor` from a project that selected Pi for setup-aware diagnosis. Setup
 reports this machine command but never runs it automatically. Uninstall removes
 only those owned paths, backup-first.

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.14.0
+**Baseline:** Cairnkeep 2.15.1
 **Last reviewed:** 2026-08-17
 
 This map prevents the course from drifting behind the product. It assigns each
@@ -40,6 +40,7 @@ been rehearsed.
 | Guided project setup, selected harness state, and Git-less limitations | L03 | L03 and L23 | Ready |
 | Pi local stdio memory bridge, trusted annotation details, and explicit lifecycle | L23 | L23 | Ready; Pi 0.84.1 validated minimum |
 | OKF 0.1/0.2 validation/import, provenance, links, regressions, and reviewed 0.2 export | L24 | L24 | Ready; local/offline by default |
+| Bounded project playbooks, managed agent guidance, enforcement, and private receipts | L25 | L25 | Ready; balanced/local by default; actor identity unverified |
 
 ## Release Review
 
@@ -73,6 +74,7 @@ repository remains the canonical source for explanations and scripts.
 | `course-10-trust-context` | L20-L21 and L24 | MCP authority profiles, offline context-pack lifecycle, and reviewed OKF exchange |
 | `course-11-windows` | L22 | Native PowerShell lifecycle, ACL inspection, and reversible uninstall |
 | `course-12-guided-setup` | L23 | Deterministic setup, Pi local stdio, recovery, and backup-first uninstall |
+| `course-13-playbooks` | L25 | Policy profiles, lifecycle decisions, enforcement, receipts, and ownership-safe instructions |
 
 ## Command Ownership
 
@@ -88,6 +90,7 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn sync-pi` | L13 and L23 |
 | `cairn sync-kimi` | L02 |
 | `cairn doctor` | L03; advanced repair in L13-L14 |
+| `cairn playbook` | L25 |
 | `cairn trajectory` | L13 |
 | `cairn artifact` | L13 |
 | `cairn evidence` | L13 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.14.0
+**Baseline:** Cairnkeep 2.15.1
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -18,6 +18,8 @@ retention contract.
 Version 2.14 adds OKF 0.1/0.2 import, structured provenance,
 deterministic links, and reviewed OKF 0.2 export; see
 [L24](lessons/L24-okf-exchange.md).
+Version 2.15 adds local bounded playbooks and private outcome receipts; see
+[L25](lessons/L25-playbooks.md).
 
 ## The three-layer model
 
@@ -47,6 +49,7 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
 | 9 | Least-authority MCP profiles | A client should receive fewer tools than the default catalog |
 | 10 | Immutable context packs and OKF exchange | Reviewed external context should be pinned or exchanged without becoming memory |
+| 11 | Bounded project playbooks | Agents should select proportional workflow checks under inspectable local policy |
 
 Every stage is independently useful. Stages 4-8 are opt-in and are not
 prerequisites for ordinary memory.
@@ -62,6 +65,7 @@ prerequisites for ordinary memory.
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
 | Guided project setup | `cairn setup PATH --git init\|existing\|none --harness LIST --memory local\|none --yes` | Reconciles only selected project assets from one harness registry; private `.ai/cairnkeep.json`; machine sync is never automatic | Repeat deterministically, run doctor, or replay its recovery command; Git-less mode remains limited | `course-12-guided-setup` |
 | Codex project memory | Select `--harness codex --memory local` | Writes `.codex/config.toml` plus POSIX/native Windows launchers; local stdio; user-wide configuration and trust remain untouched | Review the MCP table, accept Codex project trust, run doctor, and relaunch; uninstall is backup-first | `course-01-bootstrap` |
+| Workflow playbooks | `cairn playbook check start|check|finish`; project `minimal`, `balanced`, or `strict` policy | Balanced by default; private `.ai/playbooks.json`; optional receipts in `.agentfs/playbooks/`; checks are offline and execute nothing | Inspect status/digests, enforce truthful `must` evidence, inspect receipts, reset overrides, remove only the managed `AGENTS.md` block | `course-13-playbooks` |
 
 ## Storage and optional topology
 
@@ -93,7 +97,7 @@ prerequisites for ordinary memory.
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
 | Validated skill improvement | Reviewed recurring hindsight; proposal adapter; `CAIRN_EVAL=1` for evaluation | No server restart; explicit subprocesses only | `cairn skill list|show`; exact-digest apply; concurrent-edit-safe rollback | `course-09-skill` |
-| General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `course-07-evaluation` |
+| General meta-agent loop | Not shipped | Not applicable | Playbooks select bounded existing actions; no generic configuration loop, command language, or scheduler | `course-07-evaluation` |
 | Pack retrieval and skills | `CAIRN_CONTEXT_PACKS=1`; HTTP needs separate consent; skills need exact-digest approval | Restart MCP server | `cairn pack skills`; revoke approval or disable pack; no automatic execution | `course-10-trust-context` |
 
 ## Harness and maintenance checks
@@ -102,8 +106,8 @@ prerequisites for ordinary memory.
 - For Codex, review `.codex/config.toml` and accept project trust; no machine
   sync is required for the memory-only integration.
 - Run `cairn sync --check` after every core upgrade; apply only reported drift.
-- Run `cairn sync-pi --check` when the Pi memory/trajectory/graph assets are installed.
-- Run `cairn sync-kimi --check` when the optional Kimi graph Skill is installed.
+- Run `cairn sync-pi --check` when the Pi memory/trajectory/graph/playbook assets are installed.
+- Run `cairn sync-kimi --check` when the optional Kimi graph/playbook Skills are installed.
 - Use `cairn doctor --repair` only after preserving the affected store and only
   for repairable derived indexes/metadata.
 - Use `cairn uninstall --dry-run` before uninstall; durable memory is retained

package/docs/learning/README.md

@@ -56,6 +56,7 @@ expanded only after their labs are executable.
 | L22 | [Operate Cairnkeep on native Windows](lessons/L22-native-windows.md) | Ready | 30 min |
 | L23 | [Guided setup and Pi memory](lessons/L23-guided-setup.md) | Ready | 35 min |
 | L24 | [Reviewed knowledge exchange](lessons/L24-okf-exchange.md) | Ready | 35 min |
+| L25 | [Bounded workflow playbooks](lessons/L25-playbooks.md) | Ready | 35 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work
@@ -74,7 +75,7 @@ Every complete lesson contains:
 
 The learner should never need optional infrastructure to complete L00-L06.
 Remote memory, RAG, routing, containers, graph indexing, structured capture,
-typed nodes, capability governance, evaluation, context packs, and OKF exchange are separate
+typed nodes, capability governance, evaluation, context packs, OKF exchange, and playbooks are separate
 opt-in modules. MCP profiles are restrictive and never activate an optional
 feature.
 

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.14.0
+**Tested with:** Cairnkeep 2.15.1
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.14.0
+**Tested with:** Cairnkeep 2.15.1
 
 ## Outcome
 

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.14.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.14.0
+**Tested with:** Cairnkeep 2.15.1
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.14.0
+**Tested with:** Cairnkeep 2.15.1
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.14.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.14.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.14.0, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.1, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.14.0; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.15.1; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 

package/docs/learning/lessons/L24-okf-exchange.md

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.14.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/learning/lessons/L25-playbooks.md

@@ -0,0 +1,114 @@
+# L25 - Bounded workflow playbooks
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
+**Time:** 35 minutes
+
+## Outcome
+
+Configure a project playbook, evaluate it at start and finish, satisfy a
+deterministic `must` gate with honest evidence, and inspect one private receipt
+without mistaking agent self-selection for authorization or execution.
+
+## Exercise
+
+Create a disposable project and a strict policy:
+
+```bash
+lab=$(mktemp -d)
+mkdir -p "$lab/project/.ai"
+cd "$lab/project"
+cairn playbook init strict
+cairn playbook status
+cairn playbook check start --session course-playbook \
+  --complexity complex --familiarity unfamiliar
+```
+
+The start decision should select recall, focused exploration, and a bounded
+plan. It displays existing Cairnkeep actions; it does not run them. In a real
+task, perform the applicable actions through the harness and retain truthful
+evidence.
+
+Now model a security-sensitive public code-and-documentation change. First
+observe the enforcement failure:
+
+```bash
+set +e
+cairn playbook check finish --session course-playbook \
+  --changed src/auth.ts docs/security.md --risk security --public-change \
+  --enforce --json >"$lab/missing.json"
+test "$?" -eq 3
+set -e
+```
+
+Inspect `blocking_actions`; do not merely label them complete. After running
+the relevant tests, repository review, security audit, and documentation
+checks, provide the resulting evidence:
+
+```bash
+cairn playbook check finish --session course-playbook \
+  --changed src/auth.ts docs/security.md --risk security --public-change \
+  --completed verify.tests review.repository review.security docs.update \
+  --skipped learning.capture='no stable reusable learning' \
+  --enforce --json >"$lab/decision.json"
+```
+
+Record one material result with the exact returned digests:
+
+```bash
+policy=$(node -p "require('$lab/decision.json').policy_digest")
+decision=$(node -p "require('$lab/decision.json').decision_digest")
+cairn playbook record --policy "$policy" --decision "$decision" \
+  --event finish --action verify.tests --outcome completed \
+  --session course-playbook --reason 'targeted synthetic tests passed'
+cairn playbook receipts list
+cairn playbook doctor
+```
+
+Try a bounded customization, then restore the profile behavior:
+
+```bash
+cairn playbook disable learning.capture
+cairn playbook reset learning.capture
+cairn playbook set balanced
+```
+
+## Common failures
+
+- Exit 3 is missing required evidence, not a request to weaken the policy.
+- `--skipped` and `--failed` require `ACTION=REASON`; they do not satisfy a
+  `must` action.
+- Unknown actions, fields, modes, commands, URLs, path traversal, symlinks,
+  unsafe permissions, and oversized policy files fail closed.
+- A changed policy makes an old policy digest stale for new receipts.
+- `CAIRN_PLAYBOOK_PROFILE` overrides the project profile for that process; use
+  `cairn playbook status` to see the effective source.
+
+## Privacy and trust boundary
+
+Checks are offline and store nothing. Explicit receipts contain bounded
+identifiers, digests, event/action/outcome/reason, and a timestamp, but no
+prompt, file body, diff, command output, credential, or environment snapshot.
+Changed-path labels affect the decision but are not stored in the receipt.
+
+The v2.15 actor field is caller-supplied and unauthenticated. It is useful for
+local provenance, not access control, employee monitoring, or non-repudiation.
+Playbooks cannot enable capabilities, grant mutation approval, execute harness
+commands, or promote a learning into durable memory. Team authentication,
+ACLs, tenant isolation, and shared review queues remain design-only.
+
+## Recovery and acceptance
+
+```bash
+cairn playbook instructions remove --project "$lab/project"
+cd /
+rm -rf "$lab"
+```
+
+- Identical policy, signals, event, and evidence produce the same decision
+  digest.
+- Missing applicable `must` evidence exits 3 under `--enforce`; completed
+  evidence clears the relevant block.
+- The receipt is private, project-bound, bounded, and visible to `doctor`.
+- Removing managed instructions preserves all surrounding `AGENTS.md` content.
+- No check executes an action, contacts a network service, or grants approval.