@cairnkeep/cli 2.15.3 → 2.16.0

package/scripts/test-release-sbom.sh

@@ -2,7 +2,8 @@
 set -euo pipefail
 
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
-WORKFLOW="$ROOT/.github/workflows/publish.yml"
+CANDIDATE_WORKFLOW="$ROOT/.github/workflows/ci.yml"
+PUBLISH_WORKFLOW="$ROOT/.github/workflows/publish.yml"
 TEMP_DIR=$(mktemp -d)
 trap 'rm -f "$TEMP_DIR/cairnkeep.cdx.json"; rmdir "$TEMP_DIR"' EXIT
 
@@ -11,12 +12,13 @@ fail() {
   exit 1
 }
 
-node - "$ROOT/package.json" "$ROOT/package-lock.json" "$WORKFLOW" <<'NODE'
+node - "$ROOT/package.json" "$ROOT/package-lock.json" "$CANDIDATE_WORKFLOW" "$PUBLISH_WORKFLOW" <<'NODE'
 const fs = require("node:fs");
 
 const manifest = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
 const lock = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
-const workflow = fs.readFileSync(process.argv[4], "utf8");
+const candidateWorkflow = fs.readFileSync(process.argv[4], "utf8");
+const publishWorkflow = fs.readFileSync(process.argv[5], "utf8");
 const expected = "6.0.0";
 
 if (manifest.devDependencies?.["@cyclonedx/cyclonedx-npm"] !== expected) {
@@ -29,24 +31,47 @@ if (lock.packages?.["node_modules/@cyclonedx/cyclonedx-npm"]?.version !== expect
   throw new Error(`package-lock.json must resolve @cyclonedx/cyclonedx-npm ${expected}`);
 }
 
-const artifactStep = workflow.indexOf("- name: Build and validate release artifacts");
-const publishStep = workflow.indexOf("- name: Publish to npm with provenance");
-const attachStep = workflow.indexOf("- name: Attach package and SBOM to GitHub release");
-if (artifactStep < 0 || publishStep < 0 || attachStep < 0 || !(artifactStep < publishStep && publishStep < attachStep)) {
-  throw new Error("release artifacts must validate before npm publication and attach only after publication");
+if (!candidateWorkflow.includes("release-candidate:")
+  || !candidateWorkflow.includes("- name: Build release candidate")
+  || !candidateWorkflow.includes("name: release-candidate-${{ steps.candidate.outputs.tree }}")) {
+  throw new Error("CI must build and upload a tree-addressed release candidate after its required jobs");
+}
+if (!publishWorkflow.includes("- name: Download the CI-verified release candidate")
+  || !publishWorkflow.includes("jq -r '.conclusion'")
+  || !publishWorkflow.includes("== success")
+  || !publishWorkflow.includes("sha256sum --check SHA256SUMS")
+  || !publishWorkflow.includes("candidate.tree !== tree")) {
+  throw new Error("release publication must verify the successful CI run, checksums, version, and exact tree");
+}
+const publishStep = publishWorkflow.indexOf("- name: Publish to npm with provenance");
+const attachStep = publishWorkflow.indexOf("- name: Attach package and SBOM to GitHub release");
+if (publishStep < 0 || attachStep < 0 || publishStep >= attachStep) {
+  throw new Error("verified artifacts must publish to npm before release attachment");
+}
+if (!publishWorkflow.includes('npm publish "./artifacts/cairnkeep-cli-$VERSION.tgz"')) {
+  throw new Error("npm publication must use an explicit relative tarball path");
+}
+if (publishWorkflow.includes("check:public")) {
+  throw new Error("release workflow must promote the verified candidate without repeating the public suite");
+}
+if (!publishWorkflow.includes("name: containers (${{ matrix.target }})")
+  || !publishWorkflow.includes("- target: server")
+  || !publishWorkflow.includes("- target: workspace")
+  || !publishWorkflow.includes("needs: prepare")) {
+  throw new Error("npm and both container targets must fan out after candidate preparation");
 }
 NODE
 
-grep -Fq './node_modules/.bin/cyclonedx-npm' "$WORKFLOW" || fail "release workflow does not use the locked CycloneDX generator"
-grep -Fq -- '--package-lock-only' "$WORKFLOW" || fail "release workflow does not use the package lock"
-grep -Fq -- '--omit dev' "$WORKFLOW" || fail "release workflow does not omit development dependencies"
-grep -Fq -- '--output-reproducible' "$WORKFLOW" || fail "release workflow does not request reproducible output"
-grep -Fq -- '--spec-version 1.6' "$WORKFLOW" || fail "release workflow does not emit CycloneDX 1.6"
-grep -Fq -- '--validate' "$WORKFLOW" || fail "release workflow does not validate the generated SBOM"
-if grep -Fq 'npm sbom' "$WORKFLOW"; then
+grep -Fq './node_modules/.bin/cyclonedx-npm' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not use the locked CycloneDX generator"
+grep -Fq -- '--package-lock-only' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not use the package lock"
+grep -Fq -- '--omit dev' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not omit development dependencies"
+grep -Fq -- '--output-reproducible' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not request reproducible output"
+grep -Fq -- '--spec-version 1.6' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not emit CycloneDX 1.6"
+grep -Fq -- '--validate' "$CANDIDATE_WORKFLOW" || fail "candidate workflow does not validate the generated SBOM"
+if grep -Fq 'npm sbom' "$CANDIDATE_WORKFLOW" "$PUBLISH_WORKFLOW"; then
   fail "release workflow still uses npm sbom"
 fi
-if grep -Fqi 'sbomsmith' "$WORKFLOW"; then
+if grep -Fqi 'sbomsmith' "$CANDIDATE_WORKFLOW" "$PUBLISH_WORKFLOW"; then
   fail "release workflow must not depend on an external converter"
 fi
 

package/scripts/test-setup-preflight.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
 import {
   existsSync,
   lstatSync,
@@ -20,6 +21,7 @@ const RED_MARKER = "PHASE26_RED:SETUP_CORE_MISSING";
 const here = dirname(fileURLToPath(import.meta.url));
 const setupCorePath = join(here, "setup-core.mjs");
 const setupPath = join(here, "setup.mjs");
+const terminalPromptsPath = join(here, "terminal-prompts.mjs");
 const MANAGED_PATHS = [".ai", ".planning", ".agentfs"];
 
 function assertNoManagedPaths(target, label) {
@@ -81,6 +83,10 @@ async function loadSetup() {
   return import(pathToFileURL(setupPath).href);
 }
 
+async function loadTerminalPrompts() {
+  return import(pathToFileURL(terminalPromptsPath).href);
+}
+
 function assertExports(core) {
   for (const name of [
     "parseSetupArgs",
@@ -225,6 +231,126 @@ async function runInteractive(setup, args, responses) {
   return { status, prompts, output: output.read(), error: error.read() };
 }
 
+class FakeTTY extends EventEmitter {
+  constructor() {
+    super();
+    this.isTTY = true;
+    this.isRaw = false;
+    this.paused = true;
+  }
+
+  setRawMode(value) { this.isRaw = value; }
+  isPaused() { return this.paused; }
+  resume() { this.paused = false; }
+  pause() { this.paused = true; }
+}
+
+async function testTerminalSelectors(prompts) {
+  const input = new FakeTTY();
+  const output = captureStream();
+  output.stream.isTTY = true;
+  assert.equal(prompts.supportsTerminalPrompts(input, output.stream, { TERM: "xterm-256color" }), true);
+  assert.equal(prompts.supportsTerminalPrompts(input, output.stream, { TERM: "dumb" }), false);
+
+  const multi = prompts.selectManyPrompt({
+    message: "Coding harnesses",
+    choices: [
+      { value: "claude", label: "Claude Code" },
+      { value: "codex", label: "Codex CLI" },
+    ],
+    input,
+    output: output.stream,
+  });
+  setImmediate(() => {
+    input.emit("keypress", " ", { name: "space" });
+    input.emit("keypress", "", { name: "down" });
+    input.emit("keypress", " ", { name: "space" });
+    input.emit("keypress", "", { name: "return" });
+  });
+  assert.deepEqual(await multi, ["claude", "codex"]);
+  assert.equal(input.isRaw, false);
+  assert.equal(input.isPaused(), true);
+  assert.match(output.read(), /\[x\] Claude Code/);
+  assert.match(output.read(), /Coding harnesses: Claude Code, Codex CLI/);
+
+  const single = prompts.selectOnePrompt({
+    message: "Memory mode",
+    choices: [
+      { value: "local", label: "Local" },
+      { value: "none", label: "None" },
+    ],
+    initialValue: "local",
+    input,
+    output: output.stream,
+  });
+  setImmediate(() => {
+    input.emit("keypress", "", { name: "down" });
+    input.emit("keypress", "", { name: "return" });
+  });
+  assert.equal(await single, "none");
+  assert.match(output.read(), /Memory mode: None/);
+
+  const cancelled = prompts.selectOnePrompt({
+    message: "Cancel me",
+    choices: [{ value: "only", label: "Only choice" }],
+    input,
+    output: output.stream,
+  });
+  setImmediate(() => input.emit("keypress", "", { name: "escape" }));
+  await assert.rejects(cancelled, (error) => error?.status === 130 && /cancelled/i.test(error.message));
+  assert.equal(input.isRaw, false);
+  assert.equal(input.isPaused(), true);
+}
+
+async function testStructuredSetupSelectors(setup, fixture) {
+  const selections = [];
+  const output = captureStream();
+  const error = captureStream();
+  const status = await setup.runSetup([fixture.empty], {
+    isTTY: true,
+    input: { isTTY: true },
+    output: output.stream,
+    error: error.stream,
+    selectOne: async (options) => {
+      selections.push(options);
+      if (options.message === "Git integration") return "init";
+      if (options.message === "Memory mode") return "local";
+      return "no";
+    },
+    selectMany: async (options) => {
+      selections.push(options);
+      return ["codex", "opencode"];
+    },
+  });
+  assert.equal(status, 0);
+  assert.equal(error.read(), "");
+  assert.match(output.read(), /Setup cancelled; no files were changed/);
+  assert.deepEqual(selections.map(({ message }) => message), [
+    "Git integration",
+    "Coding harnesses",
+    "Memory mode",
+    "Apply this setup plan?",
+  ]);
+  const harnessPrompt = selections.find(({ message }) => message === "Coding harnesses");
+  assert.deepEqual(harnessPrompt.choices.map(({ value }) => value), ["claude", "opencode", "pi", "kimi", "qwen", "codex"]);
+  assert.match(harnessPrompt.choices.find(({ value }) => value === "codex").label, /Codex CLI/);
+  assertNoManagedPaths(fixture.empty, "cancelled structured setup");
+}
+
+async function testRedirectedOutputIsNoninteractive(setup, fixture) {
+  const output = captureStream();
+  const error = captureStream();
+  const status = await setup.runSetup([fixture.empty, "--yes"], {
+    input: { isTTY: true },
+    output: output.stream,
+    error: error.stream,
+  });
+  assert.equal(status, 2);
+  assert.equal(output.read(), "");
+  assert.match(error.read(), /git|harness|memory|usage/i);
+  assertNoManagedPaths(fixture.empty, "redirected setup output");
+}
+
 async function testInteractiveGitRecommendation(setup, fixture) {
   const accepted = await runInteractive(setup, [], [fixture.missing, "init", "pi", "local", "yes"]);
   assert.equal(accepted.status, 0);
@@ -271,6 +397,10 @@ async function main() {
     testChoiceContract(core, fixture);
     testPreflightContract(core, fixture);
     const setup = await loadSetup();
+    const terminalPrompts = await loadTerminalPrompts();
+    await testTerminalSelectors(terminalPrompts);
+    await testStructuredSetupSelectors(setup, fixture);
+    await testRedirectedOutputIsNoninteractive(setup, fixture);
     await testInteractiveGitRecommendation(setup, fixture);
     console.log("PASS: setup target, Git, syntax, choice, and no-write preflight contract");
   } finally {

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/scripts/verify-docs-parity.sh

@@ -9,8 +9,8 @@ set -euo pipefail
 #
 #   1. Env-key check: every CAIRN_[A-Z_]+/MCP_HTTP_[A-Z_]+ token read in
 #      mcp-memory-server/src/*.ts (the runtime server config surface --
-#      NOT scripts/ or bin/) must be named somewhere in docs/operating.md
-#      or README.md. `comm -23` on two sorted lists -- code-keys-not-in-
+#      NOT scripts/ or bin/) must be named somewhere in the versioned
+#      top-level docs. `comm -23` on two sorted lists -- code-keys-not-in-
 #      docs -- not a symmetric diff.
 #   2. Command check: every claude/commands/*.md basename must appear in
 #      docs/operating.md.
@@ -27,8 +27,8 @@ Usage: verify-docs-parity.sh
        verify-docs-parity.sh -h|--help
 
 Checks that every CAIRN_*/MCP_HTTP_* env key read by the cairn-memory MCP
-server (mcp-memory-server/src/*.ts) is named in docs/operating.md or
-README.md, and that every claude/commands/*.md command is named in
+server (mcp-memory-server/src/*.ts) is named in the versioned docs, and that
+every claude/commands/*.md command is named in
 docs/operating.md. One-directional: doc-only names are not a failure.
 Prints every missing key/command by name, then exits non-zero on any
 drift, or 0 if the docs are fully in sync with the shipped code.
@@ -264,7 +264,7 @@ check_env_keys() {
   local code_keys doc_keys missing
 
   code_keys=$(grep -ohE "\\b${ENV_KEY_PATTERN}\\b" mcp-memory-server/src/*.ts | grep -v '^CAIRN_TEST_' | sort -u)
-  doc_keys=$(grep -ohE "\\b${ENV_KEY_PATTERN}\\b" docs/operating.md README.md | sort -u)
+  doc_keys=$(grep -ohE "\\b${ENV_KEY_PATTERN}\\b" docs/*.md | sort -u)
 
   missing=$(comm -23 <(printf '%s\n' "$code_keys") <(printf '%s\n' "$doc_keys"))
 
@@ -276,7 +276,7 @@ check_env_keys() {
     return 1
   fi
 
-  echo "[env-keys] OK: every mcp-memory-server/src env key is named in docs/operating.md or README.md"
+  echo "[env-keys] OK: every mcp-memory-server/src env key is named in the versioned docs"
   return 0
 }
 
@@ -316,12 +316,12 @@ check_typed_contract() {
       failed=1
     fi
   done <<'EOF'
-CAIRN_TYPED_MEMORY_NODES|README.md docs/operating.md
-memory_import|README.md docs/operating.md docs/privacy-and-data-flow.md
-address_space|README.md docs/operating.md docs/privacy-and-data-flow.md
-node_types|README.md docs/operating.md
-tags_all|README.md docs/operating.md
-tags_any|README.md docs/operating.md
+CAIRN_TYPED_MEMORY_NODES|docs/operating.md
+memory_import|docs/operating.md docs/privacy-and-data-flow.md
+address_space|docs/operating.md docs/privacy-and-data-flow.md
+node_types|docs/operating.md
+tags_all|docs/operating.md
+tags_any|docs/operating.md
 schemas/memory-node.schema.json|docs/storage.md
 cairn_node_metadata_v1|docs/storage.md
 cairn_node_import_replays_v1|docs/storage.md
@@ -350,11 +350,11 @@ check_artifact_contract() {
       echo "FATAL: artifact default '$key=$value' is missing from env.example" >&2
       failed=1
     }
-    grep -qF "$key" README.md docs/operating.md || {
+    grep -qF "$key" docs/operating.md || {
       echo "FATAL: artifact env key '$key' is missing from public configuration docs" >&2
       failed=1
     }
-    grep -qF "$value" README.md docs/operating.md || {
+    grep -qF "$value" docs/operating.md || {
       echo "FATAL: artifact default '$key=$value' is missing from public configuration docs" >&2
       failed=1
     }
@@ -368,7 +368,7 @@ CAIRN_ARTIFACT_GENERATED_FILE_SNAPSHOT_MAX_BYTES|262144|GENERATED_FILE_MAX_SNAPS
 EOF
 
   for key in CAIRN_COMPACTION_CAPTURE CAIRN_ARTIFACT_STORE CAIRN_ARTIFACT_HTTP; do
-    grep -qF "$key" mcp-memory-server/src/artifact-schema.ts README.md docs/operating.md docs/privacy-and-data-flow.md || {
+    grep -qF "$key" mcp-memory-server/src/artifact-schema.ts docs/operating.md docs/privacy-and-data-flow.md || {
       echo "FATAL: artifact feature flag '$key' is not source/docs complete" >&2
       failed=1
     }
@@ -376,13 +376,13 @@ EOF
 
   for source_term in artifact_write artifact_read artifact_list artifact_delete; do
     grep -qF "\"$source_term\"" mcp-memory-server/src/index.ts || failed=1
-    grep -qF "$source_term" README.md docs/operating.md docs/privacy-and-data-flow.md || failed=1
+    grep -qF "$source_term" docs/operating.md docs/privacy-and-data-flow.md || failed=1
   done
   for source_term in 'list [--kind K] [--session REF] [--json]' 'show <artifact-id-or-prefix> [--json]' 'delete <artifact-id-or-prefix> [--dry-run] [--json]' 'prune [--dry-run] [--include-protected] [--json]'; do
     grep -qF "$source_term" mcp-memory-server/src/artifact-cli.ts || failed=1
   done
   grep -qF '.agentfs/artifacts.db' docs/storage.md docs/privacy-and-data-flow.md || failed=1
-  grep -qF 'CAIRN_ARTIFACT_HTTP' mcp-memory-server/src/index.ts README.md docs/operating.md docs/privacy-and-data-flow.md || failed=1
+  grep -qF 'CAIRN_ARTIFACT_HTTP' mcp-memory-server/src/index.ts docs/operating.md docs/privacy-and-data-flow.md || failed=1
   grep -qE 'redact[^.]{0,180}(before|then)[^.]{0,180}(digest|index|write)' docs/privacy-and-data-flow.md || failed=1
   grep -qE 'default uninstall retains|Default uninstall retains' docs/storage.md docs/privacy-and-data-flow.md || failed=1
   grep -qF -- '--purge-memory PROJECT' docs/storage.md || failed=1
@@ -390,10 +390,10 @@ EOF
 
   for version in 2.1.219 2.1.220; do
     grep -qF "version: \"$version\"" mcp-memory-server/src/compaction-normalize.ts || failed=1
-    grep -qF "$version" README.md docs/operating.md docs/privacy-and-data-flow.md || failed=1
+    grep -qF "$version" docs/operating.md docs/privacy-and-data-flow.md || failed=1
   done
   grep -qF 'version: "1.17.20"' mcp-memory-server/src/compaction-normalize.ts || failed=1
-  grep -qF '1.17.20' README.md docs/operating.md docs/privacy-and-data-flow.md || failed=1
+  grep -qF '1.17.20' docs/operating.md docs/privacy-and-data-flow.md || failed=1
 
   [[ "$failed" -eq 0 ]] && echo "[artifact-contract] OK: artifact flags/defaults/tools/paths/privacy/uninstall/version pins match source"
   return "$failed"
@@ -440,8 +440,8 @@ check_work_evidence_contract() {
     grep -qF "$key" mcp-memory-server/src/work-evidence-schema.ts || failed=1
     grep -qF "$source_term" mcp-memory-server/src/work-evidence-schema.ts || failed=1
     grep -qxF "# $key=$value" templates/env.example.template || failed=1
-    grep -qF "$key" README.md docs/operating.md docs/work-evidence.md || failed=1
-    grep -qF "$value" README.md docs/operating.md docs/work-evidence.md || failed=1
+    grep -qF "$key" docs/operating.md docs/work-evidence.md || failed=1
+    grep -qF "$value" docs/operating.md docs/work-evidence.md || failed=1
   done <<'EOF'
 CAIRN_WORK_EVIDENCE_RETENTION_DAYS|30|WORK_EVIDENCE_DEFAULT_RETENTION_DAYS = 30
 CAIRN_WORK_EVIDENCE_STORE_MAX_BYTES|67108864|WORK_EVIDENCE_DEFAULT_STORE_MAX_BYTES = 64 * 1024 * 1024
@@ -450,11 +450,11 @@ CAIRN_WORK_EVIDENCE_PATCH_MAX_BYTES|1048576|WORK_EVIDENCE_DEFAULT_PATCH_MAX_BYTE
 EOF
 
   for key in CAIRN_WORK_EVIDENCE CAIRN_WORK_EVIDENCE_PATCH; do
-    grep -qF "$key" mcp-memory-server/src/work-evidence-schema.ts templates/env.example.template README.md docs/operating.md docs/privacy-and-data-flow.md || failed=1
+    grep -qF "$key" mcp-memory-server/src/work-evidence-schema.ts templates/env.example.template docs/operating.md docs/privacy-and-data-flow.md || failed=1
   done
   for source_term in work_evidence_list work_evidence_read; do
     grep -qF "\"$source_term\"" mcp-memory-server/src/index.ts || failed=1
-    grep -qF "$source_term" README.md docs/operating.md docs/privacy-and-data-flow.md docs/work-evidence.md || failed=1
+    grep -qF "$source_term" docs/operating.md docs/privacy-and-data-flow.md docs/work-evidence.md || failed=1
   done
   for source_term in 'list [--status pending|complete] [--json]' 'show <evidence-id-or-prefix> [--json]' 'delete <evidence-id-or-prefix> [--dry-run] [--json]' 'prune [--dry-run] [--json]' 'doctor [--repair] [--json]'; do
     grep -qF "$source_term" mcp-memory-server/src/work-evidence-cli.ts || failed=1
@@ -478,7 +478,7 @@ check_capability_contract() {
     mcp-memory-server/src/capability-store.ts \
     mcp-memory-server/src/capability-adapter.ts \
     schemas/capability-callback.schema.json \
-    docs/operating.md docs/storage.md docs/privacy-and-data-flow.md README.md; do
+    docs/operating.md docs/storage.md docs/privacy-and-data-flow.md; do
     if [[ ! -f "$file" ]]; then
       echo "FATAL: capability parity input is missing: $file" >&2
       failed=1
@@ -491,11 +491,11 @@ check_capability_contract() {
       echo "FATAL: canonical capability ID is missing from source: $id" >&2
       failed=1
     }
-    grep -qF "$id" README.md docs/operating.md || {
+    grep -qF "$id" docs/operating.md || {
       echo "FATAL: canonical capability ID is undocumented: $id" >&2
       failed=1
     }
-    grep -qF "$env" README.md docs/operating.md templates/env.example.template || {
+    grep -qF "$env" docs/operating.md templates/env.example.template || {
       echo "FATAL: capability environment key is not source/docs complete: $env" >&2
       failed=1
     }
@@ -511,7 +511,7 @@ context.explore|CAIRN_CAPABILITY_CONTEXT_EXPLORE
 EOF
 
   for term in CAIRN_CAPABILITY_CONTRACT CAIRN_CAPABILITY_LOGGING; do
-    grep -qF "$term" mcp-memory-server/src/capability-config.ts README.md docs/operating.md templates/env.example.template || {
+    grep -qF "$term" mcp-memory-server/src/capability-config.ts docs/operating.md templates/env.example.template || {
       echo "FATAL: capability master/logging flag is not source/docs complete: $term" >&2
       failed=1
     }
@@ -520,7 +520,7 @@ EOF
   while IFS='|' read -r id tool; do
     grep -qF "\"$id\"" mcp-memory-server/src/index.ts || failed=1
     grep -qF "\"$tool\"" mcp-memory-server/src/index.ts || failed=1
-    grep -qF "$tool" README.md docs/operating.md || {
+    grep -qF "$tool" docs/operating.md || {
       echo "FATAL: omitted MCP tool is undocumented: $tool" >&2
       failed=1
     }

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.