@cairnkeep/cli 2.15.1 → 2.15.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [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,9 @@ 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.2 adds a generic durable-context protocol to the ownership-safe
+managed project instructions so compatible agents can derive one project
+memory query before broad exploration and verify its repository provenance.
 
 ## Compatibility
 
@@ -203,7 +206,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,20 @@ 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. 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 +242,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.2
+**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.2
 
 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,9 @@ 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.2 adds generic task-derived, project-scoped memory guidance to the
+same ownership-safe managed instructions. Retrieval remains a locator and
+actual tool invocation must be verified from runtime evidence.
 
 ## The three-layer model
 
@@ -65,7 +68,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.2
 
 ## 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.2
 
 ## 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.2 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.2
 
 ## 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.2
 
 ## 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.2 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.2 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.2, 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.2; 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.2 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.2 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome
@@ -86,6 +86,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 for a nontrivial task, treat
+memory as a locator, and verify the maintained source. It does not contain a
+task-specific query, force a tool call, 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 +118,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,8 @@
    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, 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.
@@ -23,7 +24,8 @@
    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,15 @@ 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 task query and call `memory_search` with `scope: project` before broad
+exploration. 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 .
@@ -881,8 +890,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`.
 
@@ -94,8 +97,10 @@ cairn playbook check finish --changed README.md --completed docs.update --enforc
 
 `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.2","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

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.2",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/test-package-install.sh

@@ -50,6 +50,8 @@ 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 '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,10 @@ 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 'Treat returned memory as a locator, not authority.' "$project/AGENTS.md"
+grep -qF 'Do not write, supersede, or approve durable memory' "$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 +26,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,8 @@ 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"), /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,20 @@
 <!-- cairnkeep:playbook:v1:start -->
+## Cairnkeep Durable Context
+
+Before broad repository exploration on a nontrivial task that may depend on
+existing project decisions, conventions, constraints, recurring failures, or
+prior work:
+
+- If `memory_search` is available, derive one short query from the task and
+  search `scope: project` once.
+- 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