@cairnkeep/cli 2.15.1 → 2.15.3

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.15.3] - 2026-08-18
+
+### Changed
+
+- Require the generic managed memory step before repository inventory or
+  search commands, with task-derived query guidance that does not need an
+  exploratory file read first.
+- Make the managed playbook receipt guidance directly executable, including
+  the lifecycle event, action, outcome, session, optional reason, and one-call
+  per-action boundary.
+
+### Fixed
+
+- Add successful command-scoped help for `cairn playbook check --help` and
+  `cairn playbook record --help`, including the bounded event, outcome,
+  identity, project, and output options agents need to avoid CLI probing.
+
+## [2.15.2] - 2026-08-18
+
+### Added
+
+- Add a generic, ownership-safe durable-context protocol to the managed project
+  `AGENTS.md` block. Compatible agents derive one short project-memory query
+  before broad exploration when prior decisions or conventions may matter,
+  verify referenced repository sources, fall back cleanly when retrieval is
+  unavailable, and never promote memory automatically.
+- Extend setup, bootstrap, installed-package, native Windows, uninstall, and
+  documentation coverage for the managed retrieval guidance.
+
+### Fixed
+
+- Serialize same-process playbook configuration mutations before taking the
+  filesystem lock, avoiding Windows CI lock starvation under concurrent
+  profile and reset operations while preserving cross-process exclusion.
+
 ## [2.15.1] - 2026-08-17
 
 ### Fixed

package/README.md

@@ -51,6 +51,10 @@ 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.
+Version 2.15.3 tightens the generic durable-context protocol so compatible
+agents derive one project-memory query before repository inventory or search,
+verify its repository provenance, and receive executable playbook receipt
+syntax with command-scoped help.
 
 ## Compatibility
 
@@ -203,7 +207,11 @@ 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:
+managed block in `AGENTS.md`. The block directs compatible agents to make one
+task-derived, project-scoped memory search for nontrivial work involving prior
+decisions, conventions, constraints, or failures. Results are locators, not
+authority; referenced repository sources must be verified, and memory is never
+promoted automatically. Agents can evaluate the playbook at task boundaries:
 
 ```bash
 cairn playbook check start --complexity standard --familiarity mixed

package/docs/harness-compatibility.md

@@ -17,18 +17,22 @@ Cairnkeep commands, hooks or native trajectory capture.
 | 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 |
+| Qwen Code | Memory MCP, launcher, project `AGENTS.md` durable-context and 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 |
+| Codex CLI | Project-scoped memory MCP, launcher, and project `AGENTS.md` durable-context and 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 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, launcher, and portable playbook
-instructions, but not Cairnkeep-specific commands, hooks, agents, or automatic
-skill activation.
+Codex receives a project-local MCP entry, launcher, and portable durable-context
+and playbook instructions, but not Cairnkeep-specific commands, hooks, agents,
+or automatic skill activation. The durable-context protocol places its
+task-derived search before repository inventory or search, and the playbook
+instructions provide executable receipt syntax plus command-scoped help.
+Harness behavior remains probabilistic; instruction presence must not be
+reported as a tool invocation without runtime evidence.
 
 Every MCP client receives complete tool annotations and may use a Cairnkeep
 least-authority profile independent of harness assets. Context-pack tools are
@@ -240,6 +244,26 @@ The launcher loads `.ai/.env`, runs optional pre/post hooks, changes to the
 project root, and passes all arguments to `codex`. It does not install native
 Codex Skills or instructions and does not activate approved context-pack skills.
 
+Codex uses MCP annotations when deciding whether a tool needs approval. In
+non-interactive `codex exec`, an unapproved mutating call is cancelled rather
+than silently executed. Cairnkeep intentionally does not autoapprove memory
+writes during setup. An operator who has explicitly authorized a bounded,
+unattended workflow may add narrow per-tool policy to the isolated Codex config:
+
+```toml
+[mcp_servers.cairn-memory.tools.memory_write]
+approval_mode = "approve"
+
+[mcp_servers.cairn-memory.tools.memory_supersede]
+approval_mode = "approve"
+```
+
+Do not add this to shared or ordinary interactive configuration merely to avoid
+prompts. Keep the allowlist limited to the authorized tools and continue to use
+Cairn MCP profiles and project isolation. See the
+[official Codex MCP configuration reference](https://developers.openai.com/codex/mcp)
+for approval-mode semantics.
+
 ## Candidate memory clients
 
 The following clients have documented MCP support and are reasonable adapter

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.15.1
-**Last reviewed:** 2026-08-17
+**Baseline:** Cairnkeep 2.15.3
+**Last reviewed:** 2026-08-18
 
 This map prevents the course from drifting behind the product. It assigns each
 user-facing surface to a lesson and records whether the lesson is complete or
@@ -40,7 +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 |
+| Bounded project playbooks, generic memory retrieval guidance, enforcement, and private receipts | L25 | L25 | Ready; balanced/local by default; invocation requires runtime evidence; actor identity unverified |
 
 ## Release Review
 

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.15.1
+**Baseline:** Cairnkeep 2.15.3
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -20,6 +20,10 @@ 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).
+Version 2.15.3 makes generic task-derived, project-scoped retrieval precede
+repository inventory or search and adds executable playbook receipt guidance
+with command-scoped help. Retrieval remains a locator and actual tool
+invocation must be verified from runtime evidence.
 
 ## The three-layer model
 
@@ -65,7 +69,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` |
+| Workflow playbooks and durable-context guidance | `cairn playbook check start|check|finish`; project `minimal`, `balanced`, or `strict` policy; managed `AGENTS.md` retrieval protocol | Balanced by default; private `.ai/playbooks.json`; one task-derived project search when applicable; optional receipts in `.agentfs/playbooks/`; checks are offline and execute nothing | Verify the actual memory tool event and maintained source, 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
 

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

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

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

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

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3 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.15.1
+**Tested with:** Cairnkeep 2.15.3
 
 ## 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.15.1
+**Tested with:** Cairnkeep 2.15.3
 
 ## 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.15.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3 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.15.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3 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.15.1, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3, 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.15.1; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.15.3; 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.15.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

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

@@ -1,7 +1,7 @@
 # L25 - Bounded workflow playbooks
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.15.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.3 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome
@@ -65,6 +65,10 @@ cairn playbook receipts list
 cairn playbook doctor
 ```
 
+`cairn playbook record --help` prints this command's bounded event, action,
+outcome, identity, session, project, and output options. A receipt records one
+action outcome; use another call only for another material outcome.
+
 Try a bounded customization, then restore the profile behavior:
 
 ```bash
@@ -86,6 +90,13 @@ cairn playbook set balanced
 
 ## Privacy and trust boundary
 
+The managed `AGENTS.md` block also gives compatible agents a bounded durable
+context protocol: derive one short project query before repository inventory or search,
+treat memory as a locator, and verify the maintained source. It does not
+contain a task-specific query or authorize an automatic memory write. When
+evaluating the protocol, inspect the actual `memory_search` event rather than
+assuming the instruction was followed.
+
 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.
@@ -111,4 +122,6 @@ rm -rf "$lab"
   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.
+- The installed memory guidance contains no task-specific query and degrades to
+  ordinary inspection when `memory_search` is unavailable.
 - No check executes an action, contacts a network service, or grants approval.

package/docs/learning/video-scripts/V25-playbooks.md

@@ -9,7 +9,9 @@
    harness remains the agent runtime and every approval remains in force.
 2. Run guided setup in a synthetic project. Show `.ai/playbooks.json` mode and
    the delimited Cairnkeep block inside an `AGENTS.md` that already has user
-   content.
+   content. Point out the generic durable-context protocol: it derives a query
+   from the task before repository inventory or search, treats memory as a
+   locator, and never writes automatically.
 3. Compare `minimal`, `balanced`, and `strict` with `cairn playbook status`.
    Customize one canonical action and show that an arbitrary command or unknown
    field is rejected.
@@ -18,12 +20,13 @@
 5. Run a security-sensitive `check finish --enforce` without evidence and show
    exit 3. Perform synthetic verification, then re-run with completed and
    reasoned skipped evidence.
-6. Record one outcome with exact policy and decision digests. Inspect the
-   private receipt and show that changed paths, prompts, source, and output are
-   absent.
+6. Run `cairn playbook record --help`, then record one outcome with exact
+   policy and decision digests. Inspect the private receipt and show that
+   changed paths, prompts, source, and output are absent.
 7. Show `/cairn-work` in Claude or OpenCode and the portable `AGENTS.md`
    guidance for Codex/Qwen. State that adapters route to the same CLI and do not
-   automatically activate skills.
+   automatically activate skills. Show one real `memory_search` event so the
+   instruction is not mistaken for proof of invocation.
 8. Remove the managed instruction block, prove user instructions remain, and
    close on the design-only team boundary.
 

package/docs/operating.md

@@ -838,6 +838,16 @@ project's `AGENTS.md`. `--untracked` bootstrap leaves the shared `AGENTS.md`
 untouched. The policy can select only eight canonical Cairnkeep actions; it
 cannot contain commands, prompts, URLs, or extensions.
 
+The same ownership-safe block contains a generic durable-context protocol. For
+nontrivial work that may depend on existing decisions, conventions,
+constraints, recurring failures, or prior work, compatible agents derive one
+short query directly from the task and call `memory_search` with
+`scope: project` before repository inventory or search commands such as
+`rg --files`, `find`, `tree`, or broad text search. A result is only a locator:
+the maintained repository source must still be read and verified. Missing
+tools and zero results fall back to normal inspection, and the protocol never
+authorizes an automatic memory write, supersede, or approval.
+
 ```bash
 cairn playbook list
 cairn playbook status --project .
@@ -864,12 +874,20 @@ advisory and should carry a concrete `--skipped ACTION=REASON` when omitted.
 Checking never executes the displayed commands, contacts a service, enables a
 capability, or grants approval.
 
-Material outcomes can be stored with `cairn playbook record` using the exact
-policy and decision digests from the check. Inspect them with `cairn playbook
-receipts list|show`; validate state with `cairn playbook doctor`. Actor and
-session options are provenance labels only: v2.15 does not authenticate them
-and does not provide team ACLs. See [team mode](design/team-mode.md) for the
-future admission contract.
+Material outcomes can be stored one action per call using the exact policy and
+decision digests from the check:
+
+```bash
+cairn playbook record --policy POLICY_DIGEST --decision DECISION_DIGEST \
+  --event finish --action verify.tests --outcome completed \
+  --session SESSION --reason 'targeted tests passed'
+cairn playbook record --help
+```
+
+Inspect receipts with `cairn playbook receipts list|show`; validate state with
+`cairn playbook doctor`. Actor and session options are provenance labels only:
+v2.15 does not authenticate them and does not provide team ACLs. See
+[team mode](design/team-mode.md) for the future admission contract.
 
 The managed instruction lifecycle is explicit and ownership-safe:
 
@@ -881,8 +899,10 @@ cairn playbook instructions remove
 
 Claude and OpenCode receive `/cairn-work`; Pi and Kimi receive corresponding
 thin prompt/Skill adapters when their explicit machine sync runs. Codex and
-Qwen follow the project `AGENTS.md` block. These surfaces route to the same CLI
-and do not create a Cairnkeep-owned agent loop.
+Qwen follow the project `AGENTS.md` block. Instruction exposure does not prove
+tool invocation, so evaluations and audits should verify the actual
+`memory_search` event. These surfaces route to the same CLI and do not create a
+Cairnkeep-owned agent loop.
 
 ## The workflow
 

package/docs/quickstart.md

@@ -70,8 +70,11 @@ result should survive the restart.
 
 `cairn setup` creates only the selected harness assets plus the common `.ai`,
 `.planning`, and `.agentfs` scaffold. It also reconciles Cairnkeep's delimited
-playbook block in `AGENTS.md` while preserving every surrounding user byte and
-file mode. It initializes Git only with explicit
+instruction block in `AGENTS.md` while preserving every surrounding user byte
+and file mode. The block tells compatible agents when to make one
+task-derived, project-scoped memory search, to verify maintained repository
+sources, and never to promote memory automatically. It initializes Git only
+with explicit
 `--git init`, preserves unrelated files, does not overwrite modified files it
 does not own, and records managed digests in private `.ai/cairnkeep.json`.
 
@@ -90,12 +93,15 @@ workflow checks apply. Inspect it directly before relying on agent routing:
 cairn playbook status
 cairn playbook check start --complexity standard --familiarity mixed
 cairn playbook check finish --changed README.md --completed docs.update --enforce
+cairn playbook record --help
 ```
 
 `must` can produce a non-zero enforcement result; `should` is advisory with a
 recorded reason when skipped; `may` is optional. A decision executes nothing
-and grants no permission. `cairn playbook instructions remove` removes only the
-managed `AGENTS.md` block.
+and grants no permission. The memory protocol also degrades to ordinary
+repository inspection when the tool is unavailable or returns no relevant
+result. `cairn playbook instructions remove` removes only the managed
+`AGENTS.md` block, including that protocol.
 
 For all harnesses, remote HTTP, storage, profiles, context packs, overlays, and
 recovery details, continue with [Operating Cairnkeep](operating.md) or the

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.15.1","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.15.3","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

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

@@ -36,6 +36,37 @@ contacts a network service, or grants approval. Actor identity is caller-supplie
 and unauthenticated until a future team deployment binds it to authentication.
 `;
 }
+function checkUsage() {
+    return `Usage:
+  cairn playbook check start|check|finish [signals] [evidence] [--enforce] [--json]
+
+Signals:
+  --complexity trivial|standard|complex   --familiarity known|mixed|unfamiliar
+  --risk low|normal|high|security         --public-change
+  --changed PATH...                       --change-type TYPE...
+
+Evidence and provenance:
+  --completed ACTION...                   --skipped ACTION=REASON...
+  --failed ACTION=REASON...               --actor ID --actor-kind user|agent|service
+  --session ID
+`;
+}
+function recordUsage() {
+    return `Usage:
+  cairn playbook record --policy DIGEST --decision DIGEST --event start|check|finish \\
+    --action ACTION --outcome completed|skipped|failed [--reason REASON] \\
+    [--actor ID] [--actor-kind user|agent|service] [--session ID] \\
+    [--project PATH] [--json]
+
+Record one material action outcome per call using the exact policy and decision
+digests returned by the corresponding check. Actor identity is caller-supplied
+and unauthenticated in this release.
+
+Actions:
+  context.recall  context.explore  work.plan  verify.tests
+  review.repository  review.security  docs.update  learning.capture
+`;
+}
 const VALUE_OPTIONS = new Set([
     "--project", "--complexity", "--familiarity", "--risk", "--changed", "--change-type",
     "--completed", "--skipped", "--failed", "--actor", "--actor-kind", "--session",
@@ -214,6 +245,13 @@ async function main() {
         process.stdout.write(usage());
         return;
     }
+    if (["check", "record"].includes(command) && raw.length === 1 && ["--help", "-h"].includes(raw[0])) {
+        if (command === "check")
+            process.stdout.write(checkUsage());
+        else
+            process.stdout.write(recordUsage());
+        return;
+    }
     const parsed = parse(raw);
     if (command === "list") {
         ensureAllowed(parsed, [], ["--json"]);

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

@@ -8,6 +8,7 @@ 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}$/;
+const localLockTails = new Map();
 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." },
@@ -180,35 +181,72 @@ export async function resolvePlaybookStatus(options = {}) {
         issues,
     };
 }
+async function acquireLocalLock(lock) {
+    let state = localLockTails.get(lock);
+    if (!state) {
+        state = { tail: Promise.resolve(), users: 0 };
+        localLockTails.set(lock, state);
+    }
+    const predecessor = state.tail;
+    let releaseGate;
+    const gate = new Promise((resolveGate) => { releaseGate = resolveGate; });
+    state.tail = predecessor.then(() => gate);
+    state.users += 1;
+    await predecessor;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        releaseGate();
+        state.users -= 1;
+        if (state.users === 0 && localLockTails.get(lock) === state)
+            localLockTails.delete(lock);
+    };
+}
 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) {
-            const code = error.code;
-            if (code !== "EEXIST" && !(process.platform === "win32" && code === "EPERM"))
-                throw error;
+    const releaseLocal = await acquireLocalLock(lock);
+    try {
+        for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt += 1) {
             try {
-                const info = await lstat(lock);
-                if (!info.isDirectory() || info.isSymbolicLink())
-                    throw new Error("Playbook configuration lock is unsafe.");
+                await mkdir(lock, { mode: 0o700 });
+                return async () => {
+                    try {
+                        await rm(lock, { recursive: true, force: true });
+                    }
+                    finally {
+                        releaseLocal();
+                    }
+                };
             }
-            catch (inspectionError) {
-                const inspectionCode = inspectionError.code;
-                if (inspectionCode === "ENOENT")
-                    continue;
-                if (process.platform === "win32" && (inspectionCode === "EPERM" || inspectionCode === "EBUSY")) {
-                    await delay(LOCK_WAIT_MS);
-                    continue;
+            catch (error) {
+                const code = error.code;
+                if (code !== "EEXIST" && !(process.platform === "win32" && code === "EPERM"))
+                    throw error;
+                try {
+                    const info = await lstat(lock);
+                    if (!info.isDirectory() || info.isSymbolicLink())
+                        throw new Error("Playbook configuration lock is unsafe.");
+                }
+                catch (inspectionError) {
+                    const inspectionCode = inspectionError.code;
+                    if (inspectionCode === "ENOENT")
+                        continue;
+                    if (process.platform === "win32" && (inspectionCode === "EPERM" || inspectionCode === "EBUSY")) {
+                        await delay(LOCK_WAIT_MS);
+                        continue;
+                    }
+                    throw inspectionError;
                 }
-                throw inspectionError;
+                await delay(LOCK_WAIT_MS);
             }
-            await delay(LOCK_WAIT_MS);
         }
+        throw new Error("Playbook configuration is locked; retry after the active update finishes.");
+    }
+    catch (error) {
+        releaseLocal();
+        throw error;
     }
-    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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.15.1",
+  "version": "2.15.3",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/test-cli-dispatch.sh

@@ -28,6 +28,14 @@ env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "ca
 "$cairn" artifact --help | grep -q "cairn artifact list" || fail "cairn artifact dispatch"
 "$cairn" evidence --help | grep -q "cairn evidence list" || fail "cairn evidence dispatch"
 "$cairn" playbook --help | grep -q "cairn playbook list" || fail "cairn playbook dispatch"
+"$cairn" playbook check --help | grep -q "check start|check|finish" || fail "cairn playbook check help"
+"$cairn" playbook record --help >"$tmp/playbook-record-help" || fail "cairn playbook record help"
+grep -qF -- '--event start|check|finish' "$tmp/playbook-record-help" || fail "playbook record help missing events"
+grep -qF -- '--outcome completed|skipped|failed' "$tmp/playbook-record-help" || fail "playbook record help missing outcomes"
+grep -qF 'review.security' "$tmp/playbook-record-help" || fail "playbook record help missing actions"
+if "$cairn" playbook unknown --help >/dev/null 2>&1; then
+  fail "unknown playbook command help should fail"
+fi
 "$cairn" capabilities --help >"$tmp/capabilities-help" 2>/dev/null || fail "cairn capabilities dispatch"
 "$cairn" mcp-tools list --json >"$tmp/mcp-tools.json" || fail "cairn mcp-tools dispatch"
 CAIRN_PACK_BASE_DIR="$tmp/pack-store" "$cairn" pack list --json >"$tmp/packs.json" || fail "cairn pack dispatch"

package/scripts/test-learning-docs.sh

@@ -153,6 +153,8 @@ for phrase in \
   'cairn playbook check finish' \
   '--enforce' \
   'cairn playbook record' \
+  'cairn playbook record --help' \
+  'before repository inventory or search' \
   'unauthenticated' \
   'does not run'; do
   grep -qF -- "$phrase" "$l25" || {

package/scripts/test-package-install.sh

@@ -50,6 +50,10 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ -f "$tmp/project/.planning/config.json" ]] || fail "bootstrap did not install the planning scaffold"
 [[ -f "$tmp/project/.ai/playbooks.json" ]] || fail "bootstrap did not install the playbook policy"
 grep -qF '<!-- cairnkeep:playbook:v1:start -->' "$tmp/project/AGENTS.md" || fail "bootstrap did not install playbook agent guidance"
+grep -qF 'derive one short query from the task' "$tmp/project/AGENTS.md" || fail "bootstrap did not install generic memory retrieval guidance"
+grep -qF 'before running repository inventory or search' "$tmp/project/AGENTS.md" || fail "bootstrap did not install retrieval ordering guidance"
+grep -qF 'cairn playbook record --help' "$tmp/project/AGENTS.md" || fail "bootstrap did not install actionable receipt guidance"
+grep -qF 'Treat returned memory as a locator, not authority.' "$tmp/project/AGENTS.md" || fail "bootstrap did not install memory provenance guidance"
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
 env -u CAIRN_NOTE_DISTILLATION cairn notes --help >/dev/null \

package/scripts/test-playbook-instructions.sh

@@ -12,6 +12,15 @@ chmod 0640 "$project/AGENTS.md"
 node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null
 grep -qF 'Keep this line.' "$project/AGENTS.md"
 [[ $(grep -cF '<!-- cairnkeep:playbook:v1:start -->' "$project/AGENTS.md") -eq 1 ]]
+grep -qF 'derive one short query from the task' "$project/AGENTS.md"
+grep -qF 'search `scope: project` once' "$project/AGENTS.md"
+grep -qF 'before running repository inventory or search' "$project/AGENTS.md"
+grep -qF '`rg --files`, `find`, `tree`' "$project/AGENTS.md"
+grep -qF "do not inspect" "$project/AGENTS.md"
+grep -qF 'Treat returned memory as a locator, not authority.' "$project/AGENTS.md"
+grep -qF 'Do not write, supersede, or approve durable memory' "$project/AGENTS.md"
+grep -qF 'cairn playbook record --policy POLICY_DIGEST --decision DECISION_DIGEST' "$project/AGENTS.md"
+grep -qF 'cairn playbook record --help' "$project/AGENTS.md"
 [[ $(stat -c '%a' "$project/AGENTS.md") == 640 ]]
 before=$(sha256sum "$project/AGENTS.md" | cut -d' ' -f1)
 node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null
@@ -22,6 +31,7 @@ after=$(sha256sum "$project/AGENTS.md" | cut -d' ' -f1)
 node "$ROOT/scripts/playbook-instructions.mjs" "$project" --remove >/dev/null
 grep -qF 'Keep this line.' "$project/AGENTS.md"
 ! grep -qF 'cairnkeep:playbook' "$project/AGENTS.md"
+! grep -qF 'Cairnkeep Durable Context' "$project/AGENTS.md"
 
 printf '%s\n%s\n%s\n' \
   '<!-- cairnkeep:playbook:v1:start -->' \

package/scripts/test-windows-native.mjs

@@ -40,6 +40,10 @@ try {
   assert.match(launcherPowerShell(), /evidence run --harness/);
   assert.match(launcherPowerShell(), /CAIRN_WORK_EVIDENCE/);
   assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /cairnkeep:playbook:v1:start/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /derive one short query from the task/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /before running repository inventory or search/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /cairn playbook record --help/);
+  assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /Treat returned memory as a locator, not authority\./);
   assert.match(readFileSync(join(project, "AGENTS.md"), "utf8"), /Keep this line\./);
 
   const claudeRoot = join(sandbox, "Claude Config");

package/templates/playbook-agent-instructions.md.template

@@ -1,4 +1,22 @@
 <!-- cairnkeep:playbook:v1:start -->
+## Cairnkeep Durable Context
+
+At the start of a nontrivial task that may depend on existing project
+decisions, conventions, constraints, recurring failures, or prior work,
+perform this retrieval step before running repository inventory or search
+commands such as `rg --files`, `find`, `tree`, or broad text searches:
+
+- If `memory_search` is available, derive one short query from the task and
+  search `scope: project` once. Derive it from the user's task; do not inspect
+  the repository first merely to formulate the query.
+- Treat returned memory as a locator, not authority. Read and verify the
+  maintained repository sources it references before implementing a result.
+- If the tool is unavailable or no relevant result exists, continue with
+  ordinary repository inspection. Do not repeat or broaden searches merely to
+  force a result.
+- Do not write, supersede, or approve durable memory unless the user or an
+  applicable reviewed workflow explicitly requests capture.
+
 ## Cairnkeep Playbooks
 
 Use Cairnkeep's bounded playbook policy to select workflow steps. It advises or
@@ -8,7 +26,7 @@ enforces existing capabilities; it does not execute a workflow for you.
 - Re-run `cairn playbook check check` when scope, familiarity, complexity, or risk changes materially.
 - Before claiming completion, run `cairn playbook check finish --session SESSION --changed PATH... --risk LEVEL --public-change --completed ACTION... --skipped ACTION=REASON... --enforce` with accurate signals and evidence.
 - A non-zero enforcement result means applicable `must` evidence is missing. Perform the action and check again; do not relabel a skipped or failed action as completed.
-- Record material outcomes with `cairn playbook record`, using the exact policy and decision digests returned by the check. Actor identity is an unverified local assertion in this release.
+- After a successful finish check, record only material outcomes with `cairn playbook record --policy POLICY_DIGEST --decision DECISION_DIGEST --event finish --action ACTION --outcome OUTCOME --session SESSION [--reason REASON]`, using one call per recorded action and the exact digests returned by the check. Run `cairn playbook record --help` for the bounded values. Actor identity is an unverified local assertion in this release.
 - Existing approval and capability boundaries still apply. A playbook cannot enable a disabled capability, grant approval, write durable memory automatically, run arbitrary commands, or authorize destructive work.
 - If the CLI or an applicable capability is unavailable, state that limitation and follow the policy intent manually; never invent a receipt or successful result.
 <!-- cairnkeep:playbook:v1:end -->