@cairnkeep/cli 2.15.2 → 2.15.3

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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

package/README.md

@@ -51,9 +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.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.
+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
 

package/docs/harness-compatibility.md

@@ -28,9 +28,11 @@ 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. Harness behavior remains probabilistic;
-instruction presence must not be reported as a tool invocation without runtime
-evidence.
+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

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.15.2
+**Baseline:** Cairnkeep 2.15.3
 **Last reviewed:** 2026-08-18
 
 This map prevents the course from drifting behind the product. It assigns each

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.15.2
+**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,9 +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.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.
+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
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.15.2
+**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.2
+**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.2 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.2
+**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.2
+**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.2 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.2 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.2, 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.2; 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.2 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.2 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
@@ -87,11 +91,11 @@ 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.
+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

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

@@ -10,7 +10,8 @@
 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, treats memory as a locator, and never writes automatically.
+   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.
@@ -19,9 +20,9 @@
 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. Show one real `memory_search` event so the

package/docs/operating.md

@@ -841,11 +841,12 @@ 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.
+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
@@ -873,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:
 

package/docs/quickstart.md

@@ -93,6 +93,7 @@ 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

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.15.2","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/package.json

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

@@ -51,6 +51,8 @@ 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 '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"

package/scripts/test-playbook-instructions.sh

@@ -14,8 +14,13 @@ 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

package/scripts/test-windows-native.mjs

@@ -41,6 +41,8 @@ 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"), /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

@@ -1,12 +1,14 @@
 <!-- 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:
+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.
+  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
@@ -24,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 -->