@cairnkeep/cli 2.15.3 → 2.15.4

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.15.4] - 2026-08-19
+
+### Changed
+
+- Make the managed project-memory retrieval contract explicit that retrieval
+  is the first tool or command, including before `pwd`, `ls`, inventory, or
+  search commands.
+- Put the bounded complexity, familiarity, and risk values directly in the
+  managed playbook commands so agents do not need to guess them.
+
+### Fixed
+
+- Support event-scoped playbook help such as
+  `cairn playbook check start --help` while continuing to reject ambiguous or
+  unknown help forms.
+
 ## [2.15.3] - 2026-08-18
 
 ### Changed

package/README.md

@@ -51,10 +51,11 @@ 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.
+Version 2.15.4 makes the generic durable-context retrieval the first tool or
+command for compatible agents, puts bounded playbook signal values inline,
+and supports command- and event-scoped playbook help. Agents still verify
+repository provenance, and instruction presence remains distinct from runtime
+evidence that a tool was called.
 
 ## Compatibility
 

package/docs/harness-compatibility.md

@@ -28,9 +28,10 @@ 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 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.
+or automatic skill activation. The durable-context protocol makes its
+task-derived search the first tool or command, and the playbook instructions
+provide bounded signal values, executable receipt syntax, and command- or
+event-scoped help.
 Harness behavior remains probabilistic; instruction presence must not be
 reported as a tool invocation without runtime evidence.
 

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.15.3
-**Last reviewed:** 2026-08-18
+**Baseline:** Cairnkeep 2.15.4
+**Last reviewed:** 2026-08-19
 
 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

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.15.3
+**Baseline:** Cairnkeep 2.15.4
 
 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,10 +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.
+Version 2.15.4 makes generic task-derived, project-scoped retrieval the first
+tool or command, puts bounded playbook signal values inline, and adds
+event-scoped check help to executable receipt guidance. Retrieval remains a
+locator and actual tool invocation must be verified from runtime evidence.
 
 ## The three-layer model
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.15.3
+**Tested with:** Cairnkeep 2.15.4
 
 ## 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.3
+**Tested with:** Cairnkeep 2.15.4
 
 ## Outcome
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.15.3 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 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.3
+**Tested with:** Cairnkeep 2.15.4
 
 ## 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.3
+**Tested with:** Cairnkeep 2.15.4
 
 ## 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.3 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 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.3 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 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.3, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4, 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.3; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.15.4; 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.3 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 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.3 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome
@@ -91,7 +91,7 @@ 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,
+context protocol: derive one short project query as the first tool or command,
 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

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

@@ -10,7 +10,7 @@
 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. Point out the generic durable-context protocol: it derives a query
-   from the task before repository inventory or search, treats memory as a
+   from the task as the first tool or command, 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

package/docs/operating.md

@@ -842,8 +842,9 @@ 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:
+`scope: project` as their first tool or command, before `pwd`, `ls`, 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.

package/docs/quickstart.md

@@ -72,8 +72,9 @@ result should survive the restart.
 `.planning`, and `.agentfs` scaffold. It also reconciles Cairnkeep's delimited
 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
+task-derived, project-scoped memory search as their first tool or command, 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`.

package/examples/eval/bundled-fake.json

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

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

@@ -245,11 +245,18 @@ 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());
+    if (command === "check" && raw.some((value) => ["--help", "-h"].includes(value))) {
+        const helpArguments = raw.filter((value) => !["--help", "-h"].includes(value));
+        if (raw.length !== helpArguments.length + 1
+            || helpArguments.length > 1
+            || (helpArguments.length === 1 && !["start", "check", "finish"].includes(helpArguments[0]))) {
+            throw new Error("check help accepts at most one event: start, check, or finish.");
+        }
+        process.stdout.write(checkUsage());
+        return;
+    }
+    if (command === "record" && raw.length === 1 && ["--help", "-h"].includes(raw[0])) {
+        process.stdout.write(recordUsage());
         return;
     }
     const parsed = parse(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.15.3",
+  "version": "2.15.4",
   "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

@@ -29,6 +29,10 @@ env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "ca
 "$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 check start --help | grep -q "trivial|standard|complex" || fail "cairn playbook event help"
+if "$cairn" playbook check start finish --help >/dev/null 2>&1; then
+  fail "playbook check help should reject multiple events"
+fi
 "$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"

package/scripts/test-learning-docs.sh

@@ -154,7 +154,7 @@ for phrase in \
   '--enforce' \
   'cairn playbook record' \
   'cairn playbook record --help' \
-  'before repository inventory or search' \
+  'as the first tool or command' \
   'unauthenticated' \
   'does not run'; do
   grep -qF -- "$phrase" "$l25" || {

package/scripts/test-package-install.sh

@@ -51,7 +51,7 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ -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 'make this retrieval the first tool or command' "$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"
 

package/scripts/test-playbook-instructions.sh

@@ -14,13 +14,15 @@ 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 'make this retrieval the first tool or command' "$project/AGENTS.md"
+grep -qF '`pwd`, `ls`, `rg --files`, `find`' "$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"
+grep -qF -- '--complexity trivial|standard|complex --familiarity known|mixed|unfamiliar' "$project/AGENTS.md"
+grep -qF -- '--risk low|normal|high|security' "$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

package/scripts/test-windows-native.mjs

@@ -41,7 +41,7 @@ try {
   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"), /make this retrieval the first tool or command/);
   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\./);

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

@@ -3,8 +3,9 @@
 
 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:
+make this retrieval the first tool or command. Do not run repository location,
+inventory, or search commands such as `pwd`, `ls`, `rg --files`, `find`,
+`tree`, or broad text searches first:
 
 - 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
@@ -22,9 +23,9 @@ commands such as `rg --files`, `find`, `tree`, or broad text searches:
 Use Cairnkeep's bounded playbook policy to select workflow steps. It advises or
 enforces existing capabilities; it does not execute a workflow for you.
 
-- At task start, run `cairn playbook check start --session SESSION --complexity LEVEL --familiarity LEVEL` and follow every applicable `must` action. Apply `should` actions unless there is a concrete reason to skip them; use judgment for `may` actions.
+- At task start, run `cairn playbook check start --session SESSION --complexity trivial|standard|complex --familiarity known|mixed|unfamiliar` with one value from each bounded set, and follow every applicable `must` action. Apply `should` actions unless there is a concrete reason to skip them; use judgment for `may` actions.
 - 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.
+- Before claiming completion, run `cairn playbook check finish --session SESSION --changed PATH... --risk low|normal|high|security --public-change --completed ACTION... --skipped ACTION=REASON... --enforce` with one bounded risk value and 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.
 - 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.