@cairnkeep/cli 2.7.0 → 2.8.0

package/schemas/skill-proposal-protocol.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/skill-proposal-protocol.schema.json",
+  "title": "Cairnkeep skill proposal adapter protocol v1",
+  "oneOf": [{ "$ref": "#/$defs/request" }, { "$ref": "#/$defs/response" }],
+  "$defs": {
+    "identifier": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*\\\\)(?!.*//)(?!.*[\\u0000-\\u001f\\u007f])(?:.*\\/)?SKILL\\.md$"
+    },
+    "occurrence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["session_id", "session_digest", "ended_at", "outcome", "evidence"],
+      "properties": {
+        "session_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "session_digest": { "$ref": "#/$defs/digest" },
+        "ended_at": { "$ref": "#/$defs/timestamp" },
+        "outcome": { "enum": ["failure", "resolution", "abandonment"] },
+        "tool_name": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "evidence": { "type": "string", "maxLength": 4096 }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "id", "project_id", "status", "note_id", "source_digest", "title", "description", "failure_family", "failure_count", "resolution_count", "occurrences", "lessons", "caveats", "created_at", "reviewed_at"],
+      "properties": {
+        "schema_version": { "const": 1 },
+        "id": { "$ref": "#/$defs/identifier" },
+        "project_id": { "$ref": "#/$defs/identifier" },
+        "status": { "const": "approved" },
+        "note_id": { "$ref": "#/$defs/identifier" },
+        "source_digest": { "$ref": "#/$defs/digest" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 512 },
+        "description": { "type": "string", "maxLength": 4096 },
+        "failure_family": { "$ref": "#/$defs/identifier" },
+        "failure_count": { "type": "integer", "minimum": 2, "maximum": 1024 },
+        "resolution_count": { "type": "integer", "minimum": 1, "maximum": 1024 },
+        "occurrences": { "type": "array", "minItems": 2, "maxItems": 64, "items": { "$ref": "#/$defs/occurrence" } },
+        "lessons": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 1024 } },
+        "caveats": { "type": "array", "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 1024 } },
+        "created_at": { "$ref": "#/$defs/timestamp" },
+        "reviewed_at": { "$ref": "#/$defs/timestamp" }
+      }
+    },
+    "edit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operation", "anchor", "content", "rationale"],
+      "properties": {
+        "operation": { "enum": ["add", "replace", "delete"] },
+        "anchor": { "oneOf": [{ "type": "string", "minLength": 1, "maxLength": 16384 }, { "type": "null" }] },
+        "content": { "type": "string", "maxLength": 65536 },
+        "rationale": { "type": "string", "minLength": 1, "maxLength": 2048 }
+      }
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "operation", "candidate", "candidate_digest", "target", "edit_budget"],
+      "properties": {
+        "schema_version": { "const": 1 },
+        "operation": { "const": "propose" },
+        "candidate": { "$ref": "#/$defs/candidate" },
+        "candidate_digest": { "$ref": "#/$defs/digest" },
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["path", "baseline_digest", "content"],
+          "properties": {
+            "path": { "$ref": "#/$defs/relativePath" },
+            "baseline_digest": { "$ref": "#/$defs/digest" },
+            "content": { "type": "string", "maxLength": 262144 }
+          }
+        },
+        "edit_budget": { "type": "integer", "minimum": 1, "maximum": 16 }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "status"],
+      "properties": {
+        "schema_version": { "const": 1 },
+        "status": { "enum": ["completed", "adapter_error"] },
+        "error_code": { "$ref": "#/$defs/identifier" },
+        "edits": { "type": "array", "maxItems": 16, "default": [], "items": { "$ref": "#/$defs/edit" } }
+      }
+    }
+  }
+}

package/scripts/completion.sh

@@ -11,7 +11,7 @@ _cairn_complete() {
   COMPREPLY=()
   current=${COMP_WORDS[COMP_CWORD]}
   previous=${COMP_WORDS[COMP_CWORD-1]:-}
-  commands="bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval graph memory audit-timer uninstall completion version help"
+  commands="bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help"
   if (( COMP_CWORD == 1 )); then
     COMPREPLY=( $(compgen -W "$commands" -- "$current") )
     return
@@ -63,6 +63,7 @@ _cairn_complete() {
         *) COMPREPLY=( $(compgen -W "validate run ablate report prune delete" -- "$current") ) ;;
       esac
       ;;
+    skill) COMPREPLY=( $(compgen -W "harvest list show review propose evaluate apply rollback --project --minimum-occurrences --kind --id --candidate --approve --target --adapter --edit-budget --proposal --exploration-task-set --confirmation-task-set --output --repetitions --seed --minimum-improvement --evaluation --application --confirm --yes --json" -- "$current") ) ;;
     graph) COMPREPLY=( $(compgen -W "build query status diff explain path --force" -- "$current") ) ;;
     memory) COMPREPLY=( $(compgen -W "path export import" -- "$current") ) ;;
     audit-timer) COMPREPLY=( $(compgen -W "--on-calendar --para-root --render-only" -- "$current") ) ;;
@@ -90,6 +91,7 @@ _cairn() {
     'capabilities:inspect and manage project capability state'
     'notes:distill and search local hindsight notes'
     'eval:run and inspect default-off local evaluations'
+    'skill:review and evaluate evidence-backed skill improvements'
     'graph:inspect a published Graphify graph'
     'memory:manage the durable memory store'
     'audit-timer:install a memory and wiki audit timer'
@@ -139,6 +141,19 @@ _cairn() {
         *) _values 'eval command' validate run ablate report prune delete ;;
       esac
       ;;
+    skill)
+      case $words[3] in
+        harvest) _arguments '--project[project root]:directory:_files -/' '--minimum-occurrences[minimum recurring failures]:count:' '--json[emit JSON]' ;;
+        list) _arguments '--project[project root]:directory:_files -/' '--kind[artifact kind]:kind:(candidate proposal evaluation application)' '--json[emit JSON]' ;;
+        show) _arguments '--project[project root]:directory:_files -/' '--kind[artifact kind]:kind:(candidate proposal evaluation application)' '--id[artifact ID]:artifact ID:' '--json[emit JSON]' ;;
+        review) _arguments '--project[project root]:directory:_files -/' '--candidate[candidate ID]:candidate ID:' '--approve[approve evidence]' '--json[emit JSON]' ;;
+        propose) _arguments '--project[project root]:directory:_files -/' '--candidate[candidate ID]:candidate ID:' '--target[existing SKILL.md]:file:_files' '--adapter[proposal adapter configuration]:file:_files' '--edit-budget[maximum edits]:count:' '--json[emit JSON]' ;;
+        evaluate) _arguments '--project[project root]:directory:_files -/' '--proposal[proposal ID]:proposal ID:' '--exploration-task-set[exploration task set]:file:_files' '--confirmation-task-set[confirmation task set]:file:_files' '--adapter[evaluation adapter configuration]:file:_files' '--output[report root]:directory:_files -/' '--repetitions[repetition count]:count:' '--seed[deterministic seed]:seed:' '--minimum-improvement[distinct improved tasks]:count:' '--yes[confirm execution]' '--json[emit JSON]' ;;
+        apply) _arguments '--project[project root]:directory:_files -/' '--proposal[proposal ID]:proposal ID:' '--evaluation[evaluation ID]:evaluation ID:' '--confirm[exact proposal digest]:digest:' '--json[emit JSON]' ;;
+        rollback) _arguments '--project[project root]:directory:_files -/' '--application[application ID]:application ID:' '--confirm[confirm rollback]' '--json[emit JSON]' ;;
+        *) _values 'skill command' harvest list show review propose evaluate apply rollback ;;
+      esac
+      ;;
     graph) _values 'graph command' build query status diff explain path '--force[allow a smaller graph after code deletion]' ;;
     memory) _values 'memory command' path export import ;;
     audit-timer) _arguments '--on-calendar[systemd calendar]:calendar:' '--para-root[PARA root]:directory:_files -/' '--render-only[render directory]:directory:_files -/' ;;
@@ -153,8 +168,8 @@ EOF
   fish)
     cat <<'EOF'
 complete -c cairn -f
-for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval graph memory audit-timer uninstall completion version help
-    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval graph memory audit-timer uninstall completion version help" -a $command
+for command in bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help
+    complete -c cairn -n "not __fish_seen_subcommand_from bootstrap memory-server sync sync-pi sync-kimi doctor trajectory artifact capabilities notes eval skill graph memory audit-timer uninstall completion version help" -a $command
 end
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l apply
 complete -c cairn -n "__fish_seen_subcommand_from sync" -l live-root -r
@@ -191,6 +206,29 @@ complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcomma
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from prune" -l older-than-days -r
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from prune delete" -l dry-run
 complete -c cairn -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from validate run ablate report prune delete" -l json
+complete -c cairn -n "__fish_seen_subcommand_from skill; and not __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -a "harvest list show review propose evaluate apply rollback"
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -l project -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from harvest list show review propose evaluate apply rollback" -l json
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from harvest" -l minimum-occurrences -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from list show" -l kind -r -a "candidate proposal evaluation application"
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from show" -l id -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from review propose" -l candidate -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from review" -l approve
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from propose" -l target -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from propose evaluate" -l adapter -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from propose" -l edit-budget -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate apply" -l proposal -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l exploration-task-set -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l confirmation-task-set -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l output -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l repetitions -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l seed -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l minimum-improvement -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from evaluate" -l yes
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from apply" -l evaluation -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from apply" -l confirm -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from rollback" -l application -r
+complete -c cairn -n "__fish_seen_subcommand_from skill; and __fish_seen_subcommand_from rollback" -l confirm
 complete -c cairn -n "__fish_seen_subcommand_from graph" -a "build query status diff explain path"
 complete -c cairn -n "__fish_seen_subcommand_from graph; and __fish_seen_subcommand_from build" -l force
 complete -c cairn -n "__fish_seen_subcommand_from completion" -a "bash zsh fish"

package/scripts/test-completion.sh

@@ -14,6 +14,7 @@ done
 capability_ids='memory.write memory.search notes.distill wiki graph security.audit route.check context.explore'
 eval_commands='validate run ablate report prune delete'
 eval_flags='--task-set --adapter --output --repetitions --seed --json --yes --disable --experiment --older-than-days --dry-run'
+skill_commands='harvest list show review propose evaluate apply rollback'
 for shell in bash zsh fish; do
   grep -q 'capabilities' "$tmp/$shell"
   grep -q 'list.*status.*enable.*disable.*reset.*logging\|list status enable disable reset logging' "$tmp/$shell"
@@ -37,6 +38,11 @@ for shell in bash zsh fish; do
     echo "completion exposed a private eval lifecycle operation for $shell" >&2
     exit 1
   fi
+  grep -q 'skill' "$tmp/$shell"
+  grep -q 'harvest.*list.*show.*review.*propose.*evaluate.*apply.*rollback\|harvest list show review propose evaluate apply rollback' "$tmp/$shell"
+  for skill_flag in --candidate --exploration-task-set --confirmation-task-set --evaluation --application --confirm; do
+    grep -q -- "$skill_flag\|-l ${skill_flag#--}" "$tmp/$shell"
+  done
 done
 
 "$ROOT/bin/cairn" help >"$tmp/root-help"
@@ -52,6 +58,11 @@ if grep -q 'doctor-diagnosis' "$tmp/eval-help"; then
   echo 'eval help exposed a private lifecycle operation' >&2
   exit 1
 fi
+grep -qF 'cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>' "$tmp/root-help"
+node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/skill-help"
+for command in $skill_commands; do
+  grep -q "cairn skill $command" "$tmp/skill-help"
+done
 
 node - "$ROOT/mcp-memory-server/src/capability-registry.ts" "$tmp/bash" "$tmp/zsh" "$tmp/fish" <<'NODE'
 const fs = require("fs");

package/scripts/test-learning-docs.sh

@@ -21,7 +21,7 @@ done
 
 ready=0
 brief=0
-for number in $(seq -w 0 17); do
+for number in $(seq -w 0 19); do
   matches=(docs/learning/lessons/L"$number"-*.md)
   [[ ${#matches[@]} -eq 1 && -f ${matches[0]} ]] || {
     echo "learning path must contain exactly one L$number lesson" >&2
@@ -43,7 +43,16 @@ for number in $(seq -w 0 17); do
   fi
 done
 
-[[ $ready -eq 4 && $brief -eq 14 ]] || {
+graph_lesson=docs/learning/lessons/L18-local-code-graph.md
+for mode in build query status diff explain path; do
+  grep -qF "cairn graph $mode" "$graph_lesson"
+done
+grep -qF 'Do not run `graphify install`' "$graph_lesson"
+grep -qF '`cairn sync-kimi --apply`' "$graph_lesson"
+grep -qF '`cairn sync-pi --apply`' "$graph_lesson"
+grep -qF '`graphify-out/`' "$graph_lesson"
+
+[[ $ready -eq 4 && $brief -eq 16 ]] || {
   echo "unexpected learning status totals: ready=$ready brief=$brief" >&2
   exit 1
 }

package/scripts/test-package-install.sh

@@ -19,6 +19,7 @@ server_dev_dependencies_before=$(manifest_field "$ROOT/mcp-memory-server/package
 root_lock_before=$(sha256sum "$ROOT/package-lock.json" | cut -d' ' -f1)
 server_lock_before=$(sha256sum "$ROOT/mcp-memory-server/package-lock.json" | cut -d' ' -f1)
 node "$ROOT/mcp-memory-server/dist/eval-cli.js" --help >"$tmp/source-eval-help"
+node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/source-skill-help"
 env -u CAIRN_EVAL "$ROOT/bin/cairn" eval validate \
   --task-set "$tmp/source-unread-task-set" \
   --adapter "$tmp/source-unread-adapter" \
@@ -52,6 +53,11 @@ env -u CAIRN_NOTE_DISTILLATION cairn notes --help >/dev/null \
   || fail "installed package omitted the notes command"
 
 installed_root="$tmp/prefix/lib/node_modules/@cairnkeep/cli"
+cairn skill --help >"$tmp/installed-skill-help"
+cmp -s "$tmp/source-skill-help" "$tmp/installed-skill-help" || \
+  fail "source and installed skill help differ"
+cairn skill list --project "$tmp/project" --json >"$tmp/installed-skill-list.json" || \
+  fail "installed package skill list failed"
 cairn eval --help >"$tmp/installed-eval-help"
 cmp -s "$tmp/source-eval-help" "$tmp/installed-eval-help" || \
   fail "source and installed eval help differ"
@@ -80,6 +86,18 @@ do
   [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
 done
 
+for required in \
+  schemas/skill-adapter.schema.json \
+  schemas/skill-proposal-protocol.schema.json \
+  mcp-memory-server/dist/skill-schema.js \
+  mcp-memory-server/dist/skill-store.js \
+  mcp-memory-server/dist/skill-evaluation.js \
+  mcp-memory-server/dist/skill-cli.js \
+  docs/skill-improvement.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
+done
+
 for required in \
   schemas/eval-task-set.schema.json \
   schemas/eval-adapter.schema.json \

package/scripts/test-skill-cli.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+node "$ROOT/mcp-memory-server/dist/skill-cli.js" --help >"$tmp/help"
+for operation in harvest list show review propose evaluate apply rollback; do
+  grep -q "$operation" "$tmp/help" || { echo "FAIL: skill help omitted $operation" >&2; exit 1; }
+done
+
+mkdir -p "$tmp/project"
+node "$ROOT/mcp-memory-server/dist/skill-cli.js" list --project "$tmp/project" --json >"$tmp/list.json"
+node -e '
+const value = require(process.argv[1]);
+for (const key of ["candidates", "proposals", "evaluations", "applications"]) {
+  if (!Array.isArray(value[key]) || value[key].length !== 0) process.exit(1);
+}
+' "$tmp/list.json"
+
+if env -u CAIRN_EVAL node "$ROOT/mcp-memory-server/dist/skill-cli.js" evaluate \
+  --project "$tmp/project" --proposal missing --exploration-task-set missing \
+  --confirmation-task-set missing --adapter missing --yes >"$tmp/out" 2>"$tmp/err"; then
+  echo "FAIL: disabled skill evaluation succeeded" >&2
+  exit 1
+fi
+grep -q 'disabled' "$tmp/err" || { echo "FAIL: disabled skill evaluation did not fail closed" >&2; exit 1; }
+
+echo "PASS: installed-style skill CLI discovery and default-off gate"

package/templates/graph-policy.md.template

@@ -26,7 +26,9 @@ This repository uses `.planning/graphs/` as an optional, local, machine-facing d
 
 - Use the graph to compress dependency context for planning, exploration, and impact analysis.
 - Do not use graph outputs as a human-facing substitute for the repo wiki.
-- Do not commit graph build outputs by default; `.planning/graphs/.gitignore` keeps them local unless you intentionally override it.
+- Do not commit graph build outputs by default. `.planning/graphs/.gitignore`
+  covers the published view; also ignore Graphify's root `graphify-out/` work
+  directory through repository policy or the clone-local Git exclude file.
 
 ## Maintenance