@cairnkeep/cli 2.15.2 → 2.15.4

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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
+
+- 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,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.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.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,12 @@ 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 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.
 
 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,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.15.2
-**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.2
+**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,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.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.2
+**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.2
+**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.2 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.2
+**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.2
+**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.2 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.2 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.2, 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.2; 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.2 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.2 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.4 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 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
+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 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
    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,13 @@ 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` 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.
 
 ```bash
 cairn playbook list
@@ -873,12 +875,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

@@ -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`.
@@ -93,6 +94,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.4","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,20 @@ async function main() {
         process.stdout.write(usage());
         return;
     }
+    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);
     if (command === "list") {
         ensureAllowed(parsed, [], ["--json"]);

package/package.json

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

@@ -28,6 +28,18 @@ 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 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"
+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' \
+  'as the first tool or command' \
   '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 '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"
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"

package/scripts/test-playbook-instructions.sh

@@ -14,8 +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 '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,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"), /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

@@ -1,12 +1,15 @@
 <!-- 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,
+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.
+  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
@@ -20,11 +23,11 @@ prior work:
 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.
-- 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 -->