@cairnkeep/cli 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.8.0] - 2026-08-03
+
+### Added
+
+- Add `cairn skill harvest|list|show|review|propose|evaluate|apply|rollback`
+  for turning recurring hindsight evidence into explicitly reviewed, bounded,
+  independently evaluated, reversible skill-file improvements.
+- Add strict proposal-adapter schemas and environment allowlisting, immutable
+  baseline/candidate worktree overlays, disjoint exploration and confirmation
+  gates, exact-digest application, private backups, and concurrent-edit-safe
+  rollback.
+- Add installed-style CLI and shell-completion coverage, an end-to-end Git
+  worktree evaluation fixture, and documentation for consent, storage,
+  inference ownership, evaluation limits, and recovery.
+
+The lifecycle is local and operator-controlled. It performs no proposal call
+before evidence approval, evaluation remains disabled unless `CAIRN_EVAL=1`,
+and no candidate is applied automatically. Existing MCP tools, memory storage,
+remote HTTP clients, and project launchers are unchanged.
+
+## [2.7.0] - 2026-08-02
+
+### Added
+
+- Add a Cairnkeep-owned `cairn graph build|query|status|diff|explain|path`
+  workflow, matching Claude Code and OpenCode `/graphify` modes, shell
+  completion, local-only code indexing, atomic publication, and snapshot diffs
+  without installing Graphify-owned harness assets or re-indexing generated
+  graph artifacts; add thin Pi prompt and Kimi Skill adapters that expose
+  `/graphify` while delegating exclusively to `cairn graph`, with explicit sync,
+  uninstall, package, and shell-completion coverage.
+
 ## [2.6.0] - 2026-07-29
 
 ### Added
@@ -220,7 +252,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.6.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.8.0...HEAD
+[2.8.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.7.0...v2.8.0
+[2.7.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.6.0...v2.7.0
 [2.6.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.5.0...v2.6.0
 [2.5.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.1...v2.4.0

package/README.md

@@ -14,12 +14,12 @@ Qwen Code, Pi, and other MCP clients).
 
 ## Status
 
-Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`, `sync-pi`,
+Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
 `doctor`, `trajectory`, `artifact`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
 agents, hooks) installed on Claude Code and OpenCode, plus a native Pi
-trajectory extension. The generic launchers
+trajectory extension and thin Pi/Kimi graph adapters. The generic launchers
 expose wrapper seams (`.ai/pre-launch.sh`, `CAIRN_EXTRA_SETTINGS`,
 `.ai/post-exit.sh`) so an enterprise wrapper can add provider/credential setup
 without forking them. Also shipped: context exploration (`/context-explore`) and
@@ -37,13 +37,18 @@ and 20 are end-of-life upstream.
 |---|---|
 | Claude Code on Linux/macOS | Memory server plus commands, agents, hooks, and launchers |
 | OpenCode on Linux/macOS | Memory server plus commands, plugins, hooks, and launchers |
-| Kimi Code on Linux/macOS | Memory MCP server plus project launcher; no Cairnkeep operating-layer assets yet |
+| Kimi Code on Linux/macOS | Memory MCP server, project launcher, and opt-in `/graphify` Skill |
 | Qwen Code on Linux/macOS | Memory MCP server plus project launcher; no Cairnkeep operating-layer assets yet |
-| Pi on Linux/macOS | Native opt-in trajectory extension and launcher; no bundled MCP bridge |
+| Pi on Linux/macOS | Native opt-in trajectory extension, launcher, and `/graphify` prompt; no bundled MCP bridge |
 | Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
 | Other MCP clients | Memory and optional domain-knowledge MCP tools |
 | Native Windows | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
 
+The `cairn graph` CLI is harness-independent and can be run from a project
+shell used by Kimi Code, Pi, Qwen Code, Codex, or another client. Claude Code,
+OpenCode, Pi, and Kimi can receive thin `/graphify` adapters; those adapters do
+not imply equivalent hooks, agents, or MCP support.
+
 Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
 are exercised in CI.
 
@@ -79,13 +84,20 @@ storage paths, secrets, and private derived images, see
   `cairn artifact list|show|delete|prune` manages opt-in local artifacts;
   `cairn eval validate|run|ablate|report|prune|delete` coordinates explicit
   local two-pass and one-capability-at-a-time measurements;
+  `cairn skill harvest|list|show|review|propose|evaluate|apply|rollback`
+  turns recurring hindsight evidence into reviewed, measured, reversible
+  skill-file improvements;
+  `cairn graph build|query|status|diff|explain|path` owns the local Graphify
+  workflow from any project shell without installing Graphify-owned harness
+  assets; Claude Code, OpenCode, Pi, and Kimi add thin `/graphify` wrappers;
   `cairn notes distill|search-error|promote|doctor` compiles and searches
   default-off local hindsight notes outside the online agent path;
   `cairn memory export|import` relocates the durable store between machines
   (`export` requires the optional `sqlite3` CLI);
   `cairn audit-timer` installs the scheduled memory+wiki audit;
   `cairn completion bash|zsh|fish` generates shell completion definitions; and
-  `cairn sync-pi` installs the native Pi trajectory extension;
+  `cairn sync-pi` installs the native Pi trajectory extension and graph prompt;
+  `cairn sync-kimi` installs the Kimi graph Skill;
   `cairn uninstall` reverses the install (backup-first, revertible).
 - **`templates/`** — project scaffolding (generic launchers, env) plus the
   derived-knowledge layer (wiki, alignment, graph, security, planning).
@@ -160,6 +172,10 @@ configuration requires a literal URL and supports a token reference through
 `bearerTokenEnvVar`; it does not expand `${VAR}` in the URL. See
 [Harness compatibility](docs/harness-compatibility.md#kimi-code).
 
+Install Kimi's thin graph Skill separately with `cairn sync-kimi --apply`.
+It registers `/graphify` (also `/skill:graphify`) and delegates every supported
+operation exclusively to `cairn graph`.
+
 For Qwen Code, use project `.qwen/settings.json`: local stdio launches
 `cairn memory-server`, while remote HTTP uses `httpUrl` and environment-expanded
 headers. Review and approve project MCP configuration with
@@ -174,9 +190,10 @@ cairn bootstrap /path/to/project
 cd /path/to/project && ./.ai/start-pi.sh
 ```
 
-This installs trajectory capture only. Cairnkeep does not bundle or select a Pi
-MCP bridge; configure a user-chosen bridge separately if you also want the MCP
-memory tools inside Pi.
+This installs trajectory capture plus the thin `/graphify` prompt. The prompt
+delegates exclusively to `cairn graph`. Cairnkeep does not bundle or select a
+Pi MCP bridge; configure a user-chosen bridge separately if you also want the
+MCP memory tools inside Pi.
 
 Closed trajectories can be compiled into local hindsight notes without a model
 or embedding service. Capture and distillation are separate opt-ins:
@@ -377,6 +394,25 @@ descendant-process-tree termination is not guaranteed. See the
 [storage contract](docs/storage.md#evaluation-report-and-note-snapshot-storage),
 and [privacy flow](docs/privacy-and-data-flow.md#evaluation-adapter-and-report-flow).
 
+### Validated skill improvement (opt-in)
+
+`cairn skill` promotes repeated, resolved hindsight evidence through a guarded
+lifecycle: local harvest, explicit evidence review, bounded proposal generation,
+separate exploration and confirmation evaluations, exact-digest application,
+and backup-first rollback. Cairnkeep never rewrites a live skill during proposal
+or evaluation, never sends evidence to the proposal adapter before approval,
+and never applies a candidate automatically.
+
+Proposal generation uses an explicit strict adapter configuration with an
+environment allowlist. Evaluation remains disabled unless `CAIRN_EVAL=1`, uses
+the existing isolated worktree runner and independent verifier, and requires
+disjoint committed task sets bound to one immutable source revision. A
+candidate is eligible only when both stages meet the configured improvement
+floor with no regression or unknown pair. See the
+[validated skill guide](docs/skill-improvement.md),
+[storage contract](docs/storage.md#validated-skill-storage), and
+[privacy flow](docs/privacy-and-data-flow.md#validated-skill-improvement-flow).
+
 ### Typed memory nodes and structured import (opt-in)
 
 `CAIRN_TYPED_MEMORY_NODES=1` adds schema-v1 `node_type`, canonical `tags`,
@@ -446,6 +482,7 @@ exposes trajectory data. See the [operating guide](docs/operating.md#compaction-
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
 - **Podman and OCI containers** — [docs/containers.md](docs/containers.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
+- **Validated skill improvement** — [docs/skill-improvement.md](docs/skill-improvement.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)
 - **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md)

package/bin/cairn

@@ -33,8 +33,11 @@ Usage:
                            agents, hooks) into ~/.claude, or into DIR for a single
                            project (--live-root <project>/.claude).
   cairn sync-pi [--apply] [--live-root DIR]
-                           Install/update the Pi trajectory extension into
-                           ~/.pi/agent, or into DIR for an isolated Pi root.
+                           Install/update the Pi trajectory extension and thin
+                           /graphify prompt into ~/.pi/agent or isolated DIR.
+  cairn sync-kimi [--apply] [--live-root DIR]
+                           Install/update the thin Kimi /graphify Skill into
+                           $KIMI_CODE_HOME, ~/.kimi-code, or isolated DIR.
   cairn doctor             Health-check the memory server and configured LLM /
                            embedding endpoints, git provider, and stores.
                            Use --repair for derived trajectory/typed metadata,
@@ -56,6 +59,12 @@ Usage:
   cairn eval <validate|run|ablate|report|prune|delete>
                            Validate or run default-off local evaluations, inspect
                            reports, and manage retained experiment results.
+  cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
+                           Turn recurring hindsight evidence into reviewed,
+                           evaluated, reversible skill-file improvements.
+  cairn graph <build|query|status|diff|explain|path>
+                           Build the local code graph, inspect freshness and
+                           changes, or query exact symbols and paths.
   cairn memory <path|export|import>
                            Relocate global-scope memory. `path` prints its location;
                            `export <file.tgz>` takes a WAL-safe snapshot (requires
@@ -64,7 +73,7 @@ Usage:
                            Install (opt-in) a systemd user timer that runs the
                            memory+wiki audit on a schedule; prints a cron alternative.
   cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR]
-                  [--pi-live-root DIR] [PROJECT ...]
+                  [--pi-live-root DIR] [--kimi-live-root DIR] [PROJECT ...]
                            Reverse what cairnkeep installed/modified (operating
                            layer, hook registrations, MCP registration, audit
                            timer, and any given projects' bootstrap scaffold).
@@ -110,12 +119,21 @@ case "$cmd" in
   eval)
     exec node "$CAIRN_ROOT/mcp-memory-server/dist/eval-cli.js" "$@"
     ;;
+  skill)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/skill-cli.js" "$@"
+    ;;
+  graph)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/graph-cli.js" "$@"
+    ;;
   sync)
     exec "$CAIRN_ROOT/scripts/sync-claude-assets.sh" "$@"
     ;;
   sync-pi)
     exec "$CAIRN_ROOT/scripts/sync-pi-assets.sh" "$@"
     ;;
+  sync-kimi)
+    exec "$CAIRN_ROOT/scripts/sync-kimi-assets.sh" "$@"
+    ;;
   audit-timer)
     exec "$CAIRN_ROOT/scripts/install-audit-timer.sh" "$@"
     ;;

package/claude/commands/graphify.md

@@ -1,12 +1,14 @@
 ---
 description: "Build, rebuild, query, and inspect the project knowledge graph in .planning/graphs/"
-argument-hint: "[build [--force]|query <term>|status|diff]"
+argument-hint: "[build [--force]|query <term>|explain <symbol>|path <from> <to>|status|diff]"
 allowed-tools: Read, Bash
 ---
 
 **STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's command system. Using the Read tool on this file wastes tokens. Begin executing Step 0 immediately.**
 
-**graphify CLI:** the `graphify` subcommand is exposed by `gsd-tools` (on PATH). Invoke as `gsd-tools graphify …` as documented in this command and in `docs/CLI-TOOLS.md`. Other GSD queries use `gsd-tools <subcmd>` where a handler exists.
+**graph workflow:** Cairnkeep owns this surface through `cairn graph`. The
+operator installs only the isolated `graphify` executable; do not invoke
+Graphify's harness installer.
 
 ## Step 0 -- Banner
 
@@ -18,29 +20,13 @@ GRAPHIFY
 
 Then proceed to Step 1.
 
-## Step 1 -- Config Gate
+## Step 1 -- Capability ownership
 
-Check if graphify is enabled by reading `.planning/config.json` directly using the Read tool.
-
-**DO NOT use the gsd-tools config get-value command** -- it hard-exits on missing keys.
-
-1. Read `.planning/config.json` using the Read tool
-2. If the file does not exist: display the disabled message below and **STOP**
-3. Parse the JSON content. Check if `config.graphify && config.graphify.enabled === true`
-4. If `graphify.enabled` is NOT explicitly `true`: display the disabled message below and **STOP**
-5. If `graphify.enabled` is `true`: proceed to Step 2
-
-**Disabled message:**
-
-```
-GRAPHIFY
-
-Knowledge graph is disabled. To activate:
-
-  gsd-tools config-set graphify.enabled true
-
-Then run /graphify build to create the initial graph.
-```
+Do not implement a separate configuration gate in the prompt. Every
+`cairn graph` operation enforces the typed `graph` capability and its legacy
+`graphify.enabled` compatibility default before Graphify or graph-file I/O.
+Proceed directly to Step 2; if the owner reports a disabled capability, display
+its fixed remediation message and **STOP**.
 
 ---
 
@@ -52,6 +38,8 @@ Parse `$ARGUMENTS` to determine the operation mode:
 |----------|--------|
 | `build` or `build --force` | Run inline build (Step 3) |
 | `query <term>` | Run inline query (Step 2a) |
+| `explain <symbol>` | Explain one exact symbol (Step 2d) |
+| `path <from> <to>` | Find the shortest path between two exact symbols (Step 2e) |
 | `status` | Run inline status check (Step 2b) |
 | `diff` | Run inline diff check (Step 2c) |
 | No argument or unknown | Show usage message |
@@ -66,6 +54,8 @@ Usage: /graphify <mode>
 Modes:
   build [--force] Build or rebuild the knowledge graph
   query <term>    Search the graph for a term
+  explain <symbol> Explain one exact symbol and its relationships
+  path <from> <to> Find the shortest path between two exact symbols
   status          Show graph freshness and statistics
   diff            Show changes since last build
 ```
@@ -75,28 +65,39 @@ Modes:
 Run:
 
 ```bash
-gsd-tools graphify query <term>
+cairn graph query <term>
 ```
 
-Parse the JSON output and display results:
-- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
-- If the output contains `"error"` field, display the error message and **STOP**
-- If no nodes found, display: `No graph matches for '<term>'. Try /graphify build to create or rebuild the graph.`
-- Otherwise, display matched nodes grouped by type, with edge relationships and confidence tiers (EXTRACTED/INFERRED/AMBIGUOUS)
+Pass the parsed term as exactly one argument and display the result verbatim.
+On failure, display the error without retrying or changing configuration.
 
 **STOP** after displaying results. Do not spawn an agent.
 
+### Step 2d -- Explain
+
+Run `cairn graph explain <symbol>`, passing the parsed symbol as exactly one
+argument. Display Graphify's explanation verbatim. On failure, display the
+error and suggest `/graphify build` only when the published graph is missing.
+
+**STOP** after displaying the result. Do not spawn an agent.
+
+### Step 2e -- Path
+
+Run `cairn graph path <from> <to>`, passing each parsed symbol as exactly one
+argument. Display Graphify's path result verbatim. On failure, display the
+error and suggest `/graphify build` only when the published graph is missing.
+
+**STOP** after displaying the result. Do not spawn an agent.
+
 ### Step 2b -- Status
 
 Run:
 
 ```bash
-gsd-tools graphify status
+cairn graph status
 ```
 
-Parse the JSON output and display:
-- If `exists: false`, display the message field
-- Otherwise show last build time, node/edge/hyperedge counts, and STALE or FRESH indicator
+Display the local node/edge counts and freshness result verbatim.
 
 **STOP** after displaying status. Do not spawn an agent.
 
@@ -105,14 +106,11 @@ Parse the JSON output and display:
 Run:
 
 ```bash
-gsd-tools graphify diff
+cairn graph diff
 ```
 
-Parse the JSON output and display:
-- If `no_baseline: true`, display the message field
-- Otherwise show node and edge change counts (added/removed/changed)
-
-If no snapshot exists, suggest running `build` twice (first to create, second to generate a diff baseline).
+Display the node and edge change counts verbatim. If no snapshot exists,
+suggest rebuilding after the next code change.
 
 **STOP** after displaying diff. Do not spawn an agent.
 
@@ -123,20 +121,14 @@ If no snapshot exists, suggest running `build` twice (first to create, second to
 Run:
 
 ```bash
-gsd-tools graphify build [--force]
+cairn graph build [--force]
 ```
 
-Parse the JSON output and display:
-- If the output contains `"disabled": true`, display the disabled message from Step 1 and **STOP**
-- If the output contains an `"error"` field, display the error and the `stage` field when present, then **STOP**
-- Otherwise display the build summary using `status.last_build`, `status.node_count`, `status.edge_count`, `status.hyperedge_count`, whether the snapshot was saved, and whether a forced clean rebuild was used
-
-This command now performs the full pipeline directly:
-- runs `graphify update .` with legacy fallback to `graphify . --update`
-- when `--force` is present, clears `graphify-out/`, published graph artifacts, and `.planning/graphs/.last-build-snapshot.json` first
-- validates `graphify-out/graph.json`
-- copies `graph.json`, `graph.html`, and `GRAPH_REPORT.md` into `.planning/graphs/`
-- writes `.planning/graphs/.last-build-snapshot.json`
+Display the build summary verbatim. This managed path runs Graphify's local
+code-only `update`, strips provider credentials from its subprocess
+environment, validates the resulting graph, atomically publishes available
+artifacts into `.planning/graphs/`, and snapshots the previous graph for diff.
+`--force` permits a rebuilt graph with fewer nodes after code deletion.
 
 **STOP** after displaying the build result. Do not spawn an agent.
 
@@ -144,7 +136,6 @@ This command now performs the full pipeline directly:
 
 ## Anti-Patterns
 
-1. DO NOT spawn an agent for graphify operations -- build/query/status/diff are handled directly
+1. DO NOT spawn an agent for graphify operations -- build/query/explain/path/status/diff are handled directly
 2. DO NOT modify graph files directly outside the graphify CLI path
-3. DO NOT skip the config gate check
-4. DO NOT use gsd-tools config get-value for the config gate -- it exits on missing keys
+3. DO NOT duplicate capability parsing in the prompt -- `cairn graph` owns it

package/docs/design/meta-agent.md

@@ -1,17 +1,19 @@
 # Meta-agent design contract
 
-> **Design-only status.** Phase 20 ships this Markdown file only. It ships no
-> executable schema, compiler, generator, controller, adapter change,
-> configuration surface, command-line interface, or runtime default. Phase 18
-> capability state and Phase 19 evaluation behavior described below are current
-> facts. Every meta-agent control, artifact, state, and action described as a
-> requirement is future work that requires separate approval.
+> **General-loop design status.** Cairnkeep 2.8.0 ships a narrower validated
+> lifecycle for one existing `SKILL.md`; see
+> [Validated skill improvement](../skill-improvement.md). It does not ship the
+> general natural-language configuration compiler, autonomous search loop,
+> arbitrary target policy, or capability optimizer specified here. Requirements
+> in this document remain future work except where a paragraph explicitly names
+> the 2.8.0 skill-file lifecycle as current behavior.
 
 ## Status and normative language
 
-This document specifies a future, bounded build-test-improve configuration
-loop. It does not accept input and is not an executable interface. In future
-requirements, **MUST**, **MUST NOT**, **REQUIRED**, and **SHALL** are normative;
+This document specifies a future, general bounded build-test-improve
+configuration loop. It is not the executable interface for `cairn skill`; the
+skill schemas and operating guide are authoritative for that narrower surface.
+In future requirements, **MUST**, **MUST NOT**, **REQUIRED**, and **SHALL** are normative;
 **SHOULD** and **MAY** describe constrained choices. Statements explicitly
 labelled current describe accepted Phase 18 or Phase 19 behavior rather than
 new behavior.
@@ -24,11 +26,12 @@ authority.
 ## Paper concept and Cairnkeep boundary
 
 The paper's build-test-improve concept motivates a future bounded configuration
-loop, but does not redefine Cairnkeep's ownership. Cairnkeep may eventually
-compile an operator objective into a reviewable form, propose bounded candidate
-artifacts, coordinate approved measurement, and prepare a reversible proposal.
-It must not own a harness inference loop. Existing repository contracts remain
-the authority over external design inspiration.
+loop, but does not redefine Cairnkeep's ownership. The shipped skill lifecycle
+can propose one bounded `SKILL.md` candidate through an operator-configured
+adapter. Cairnkeep may eventually compile a broader operator objective into a
+reviewable form and coordinate general candidates. It must not own a harness
+inference loop. Existing repository contracts remain the authority over
+external design inspiration.
 
 Natural-language objectives are untrusted proposal data. They never authorize
 repository reads, writes, commands, network use, evaluation, or application.
@@ -159,9 +162,12 @@ untrusted objective
   -> accept | inconclusive | no_eligible_candidate | rollback
 ```
 
-There is no arrow from a Cairnkeep generator, selector, applier, or rollback
-operation to inference. Phase 19 is the sole Cairnkeep execution and measurement
-seam; the operator-configured external adapter remains the sole inference owner.
+For the future general loop, there is no direct inference edge from a
+Cairnkeep-owned generator, selector, applier, or rollback operation. The shipped
+skill lifecycle has one explicit exception: its operator-configured proposal
+adapter may perform candidate-generation inference through a strict bounded
+process contract. Evaluation still uses the Phase 19 coordinator and external
+adapter; Cairnkeep owns neither inference loop.
 
 | Actor or component | May do | Must not do | Required authority |
 |---|---|---|---|
@@ -189,12 +195,12 @@ diagnostics or model output.
 | Concern | Current accepted Phase 18/19 behavior | Missing future contract; not shipped by Phase 20 |
 |---|---|---|
 | Capability identity | `expected_capability_digest` and `observed_capability_digest` bind the complete Phase 18 effective state. | Candidate-overlay identity and expected/observed candidate digests for arbitrary prompt/config candidates. |
-| Adapter identity | `adapter_config_digest` binds the operator adapter configuration. | It is not a generated-candidate digest and grants no selection or apply authority. |
-| Request surface | Phase 19 sends experiment/task identity, arm, repetition, pass, isolated paths, fixed input, limits, seed, expected capability digest, and output path. | Phase 19 has no arbitrary candidate overlay reference, injection contract, or expected candidate digest. |
+| Adapter identity | `adapter_config_digest` binds the operator adapter configuration. The 2.8.0 skill lifecycle additionally binds proposal and evaluation adapter executable digests. | These identities grant no general selection or apply authority. |
+| Request surface | Phase 19 sends experiment/task identity, arm, repetition, pass, isolated paths, fixed input, limits, seed, expected capability digest, and output path. The skill lifecycle overlays exact baseline/candidate `SKILL.md` bytes before invocation. | Phase 19 has no public arbitrary configuration-overlay protocol or adapter-selected target. |
 | Result surface | Strict results may report bounded metrics, identities, references, and `observed_capability_digest`. | There is no observed candidate-overlay digest, and no candidate pass/approval field. |
 | Ablation | `runCapabilityAblation()` compares an all-enabled baseline with exactly one disabled capability and requires four invocations per task/repetition: two passes in each of two arms. | It is not generic prompt search, arbitrary configuration injection, or a multi-capability candidate arm. |
-| Scheduling | Deterministic, serial, immutable, paired schedules and fresh isolated workspaces are current. | Adaptive generation/selection and separate exploration/held-out campaign control are absent. |
-| Report | Canonical reports preserve observations, aggregates, condition levels, eligible pairs, missingness, warnings, intervals, evidence scope, and provenance. | Reports do not choose winners, authorize application, or provide a proposal/rollback ledger. |
+| Scheduling | Deterministic, serial, immutable, paired schedules and fresh isolated workspaces are current. The skill lifecycle coordinates separate disjoint exploration and confirmation sets. | Adaptive general candidate generation and search remain absent. |
+| Report | Canonical reports preserve observations, aggregates, condition levels, eligible pairs, missingness, warnings, intervals, evidence scope, and provenance. A separate skill evaluation artifact applies the narrow no-regression gate. | Evaluation reports themselves do not authorize application or general configuration selection. |
 
 Exploration and held-out confirmation task sets MUST be separate, committed,
 immutable, non-overlapping, and digest-bound. Exploration results may inform the
@@ -357,14 +363,14 @@ not backlog rows.
 Each row is future work requiring separate approval. The list is exactly nine
 items; Phase 20 delivers none of them.
 
-| # | Exact absent capability | Accepted substrate it may reuse | Delivery status |
+| # | General-loop capability | Accepted substrate it may reuse | Delivery status |
 |---|---|---|---|
 | 1 | Natural-language-to-form compiler and validator | Strict versioning, canonical digests, and path validation patterns | Future work requiring separate approval; not delivered by Phase 20 |
-| 2 | Bounded candidate generator | Phase 18 typed capability identities and retained evidence | Future work requiring separate approval; not delivered by Phase 20 |
-| 3 | Candidate-config injection contract for external adapters | Phase 19 adapter seam and Phase 18 capability digests; Phase 19 currently has no arbitrary overlay identity or observed candidate digest and supports only exactly-one-capability-off ablation | Future work requiring separate approval; not delivered by Phase 20 |
-| 4 | Scoped proposal/artifact schema | Existing strict versioned local artifacts and canonical reports | Future work requiring separate approval; not delivered by Phase 20 |
-| 5 | Backup-first patch applier and rollback ledger | Existing backup-first uninstall/revert and atomic single-file write precedents | Future work requiring separate approval; not delivered by Phase 20 |
-| 6 | Exploration and held-out committed task sets | Current committed task-set schema, exact revisions, and verifier | Future work requiring separate approval; not delivered by Phase 20 |
+| 2 | Bounded candidate generator | Phase 18 typed capability identities and retained evidence | Narrow skill proposer shipped; general objective compiler and candidate search remain future work |
+| 3 | Candidate-config injection contract for external adapters | Phase 19 adapter seam and Phase 18 capability digests | Exact coordinator-owned `SKILL.md` overlays shipped; arbitrary configuration overlays remain future work |
+| 4 | Scoped proposal/artifact schema | Existing strict versioned local artifacts and canonical reports | Narrow candidate/proposal/evaluation/application artifacts shipped; general proposal bundles remain future work |
+| 5 | Backup-first patch applier and rollback ledger | Existing backup-first uninstall/revert and atomic single-file write precedents | One-file exact-digest skill apply/rollback shipped; arbitrary patches remain future work |
+| 6 | Exploration and held-out committed task sets | Current committed task-set schema, exact revisions, and verifier | Shipped for the skill lifecycle; general campaigns remain future work |
 | 7 | Selection policy accounting for uncertainty and repeated comparisons | Phase 19 condition levels, paired estimates, missingness, warnings, and intervals | Future work requiring separate approval; not delivered by Phase 20 |
 | 8 | Sufficient live baseline evidence | Validator-checked evidence scope and exact-source runtime provenance; existing offline evidence is framework-only | Future work requiring separate approval; not delivered by Phase 20 |
 | 9 | Dedicated privacy/security threat review | Current local privacy, bounded storage, secret exclusion, and public hygiene guards | Future work requiring separate approval; not delivered by Phase 20 |
@@ -377,12 +383,10 @@ items; Phase 20 delivers none of them.
 - Architect-style in-loop compression is outside this design and Phase 20.
 - Trace UI is outside this design and Phase 20.
 - Eval UI is outside this design and Phase 20.
-- Phase 20 implements no compiler, generator, selection controller, proposal
-  schema, patch applier, rollback ledger, candidate adapter-protocol change,
-  configuration schema, CLI surface, runtime default, or modification of Phase
-  18 or Phase 19 contracts.
-- Phase 20 adds no symbol, command, flag, package, dependency, test source,
-  executable interface, release, publication, or automatic product claim.
+- Cairnkeep 2.8.0 implements only the reviewed `SKILL.md` lifecycle documented
+  separately. It adds no general objective compiler, autonomous scheduler,
+  capability optimizer, arbitrary patch surface, UI, or automatic product
+  claim.
 
 All excluded implementation work requires a new plan, threat review, approval,
 tests, and evidence. Naming a future contract here does not reserve a public
@@ -394,12 +398,12 @@ interface or represent it as delivered.
 |---|---|---|
 | META-01 | Natural-language specification → strict form | Untrusted prose can become only a complete, versioned, fail-closed future form. |
 | META-02 | Ownership; evaluation; proposal; state machine | Candidates are bounded, measured only through Phase 19/adapters, and separately approved for application. |
-| META-03 | Prerequisites; explicit exclusions | Exactly nine prerequisites remain future work and prohibited ownership/UI/implementation is explicit. |
+| META-03 | Prerequisites; explicit exclusions | Narrow skill delivery is separated from remaining general-loop prerequisites and prohibited ownership/UI behavior. |
 | D-01 | Natural-language specification → strict form | Natural language is untrusted proposal data, never executable control. |
 | D-02 | Required configuration fields | Scope, revisions, paths, resources, safety, capabilities, tasks, evaluation, selection, mutation, and authority are required. |
 | D-03 | Admission is fail closed | Omissions, unknowns, unsafe paths, unresolved revisions, non-finite resources, and inferred defaults invalidate. |
 | D-04 | Admission; privacy invariants | Only value-free operator-owned references are allowed; secret/endpoint/environment values are forbidden. |
-| D-05 | Status and normative language | The artifact is design-only; examples are non-normative; no schema or CLI ships. |
+| D-05 | Status and normative language | The general-loop artifact is design-only; examples are non-normative; the separate narrow skill schema and CLI do not imply broader delivery. |
 | D-06 | Ownership and authority | Phase 19 is the sole execution/measurement seam and the external adapter owns inference. |
 | D-07 | Candidate evaluation | Source, tasks, verifier, adapter identity, schedule, limits, seeds, and digests are frozen and comparable. |
 | D-08 | Candidate evaluation | Canonical terminal/pass states, condition levels, missingness, uncertainty, and evidence scope remain authoritative. |

package/docs/harness-compatibility.md

@@ -10,16 +10,24 @@ commands, hooks, plugins, or trajectory adapters.
 |---|---|---|
 | Claude Code | Memory MCP, commands, agents, hooks, launcher | Exercised by Cairnkeep tests |
 | OpenCode | Memory MCP, commands, workflows, plugins, launcher | Exercised by Cairnkeep tests |
-| Kimi Code | Memory MCP, `AGENTS.md`, launcher | Launcher tested; remote MCP tested with Kimi Code 0.30.0 |
+| Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph Skill | Launcher tested; remote MCP tested with Kimi Code 0.30.0; graph Skill contract-tested |
 | Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
-| Pi | Native opt-in trajectory extension and launcher | Exercised by Cairnkeep tests; no bundled MCP bridge |
+| Pi | Native opt-in trajectory extension, launcher, and graph prompt | Exercised by Cairnkeep tests; no bundled MCP bridge |
 | Codex CLI | Memory MCP | Configuration supported; no Cairnkeep operating-layer assets or launcher |
 | Other MCP clients | Memory and optional domain-knowledge tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
-Kimi and Qwen skills and hooks require harness-specific adaptation and
-validation before they can be presented as equivalent. In either client, call
-MCP tools directly or use ordinary prompts until that work is complete.
+Kimi receives one narrow graph Skill, while Pi receives one narrow graph prompt;
+neither is equivalent to the full commands, agents, hooks, and plugins surface.
+Qwen skills and hooks still require harness-specific adaptation and validation.
+
+`cairn graph` is a separate, harness-independent project-shell CLI. Kimi Code,
+Pi, Qwen Code, Codex, and other shell-capable clients can invoke
+`cairn graph build|query|status|diff|explain|path` when `cairn` and the isolated
+`graphify` executable are on `PATH`. `cairn sync-kimi --apply` registers a Kimi
+Skill as `/graphify` (or `/skill:graphify`), and `cairn sync-pi --apply`
+registers a Pi prompt template as `/graphify`; both delegate exclusively to
+that CLI. Neither adds an MCP bridge to Pi or expands the other support levels.
 
 ## Kimi Code
 

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.6.0
-**Last reviewed:** 2026-07-29
+**Baseline:** Cairnkeep 2.8.0
+**Last reviewed:** 2026-08-03
 
 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
@@ -16,7 +16,8 @@ been rehearsed.
 | Local stdio memory and MCP registration | L00-L02 | L03-L04 | L00-L03 Ready; L04 Brief |
 | Project bootstrap, launchers, and contributor mode | L02-L03 | L05 | L02-L03 Ready; L05 Brief |
 | Memory scopes, keys, search, supersession, and history | L04 | L04-L05 | Brief |
-| Wiki, alignment, graph, and repository quality workflows | L05-L06 | L05-L06 | Brief |
+| Wiki, alignment, and repository quality workflows | L05-L06 | L05-L06 | Brief |
+| Optional local code graph, graph inspection, and harness delegates | L18 | L18 | Brief; default off |
 | Storage placement, export/import, and authenticated remote memory | L07 | L07-L08 | Brief |
 | Document RAG | L00 | L09 | Brief; optional |
 | token-miser exploration and routing | L00 | L10 | Brief; optional |
@@ -30,6 +31,7 @@ been rehearsed.
 | Deterministic two-pass evaluation and one-capability ablation | L16 | L16 | Brief; default off |
 | Shell completion | L02 | L02 | Ready; optional convenience |
 | Bounded meta-agent configuration loop | L17 | None | Design-only; not shipped |
+| Reviewed, evaluated, reversible skill-file improvement | L19 | L19 | Brief; explicit and default off |
 
 ## Release Review
 
@@ -58,6 +60,8 @@ repository remains the canonical source for explanations and scripts.
 | `course-05-evidence` | L13-L14 | Evidence lifecycle and typed memory |
 | `course-06-governance` | L15 | Capability precedence and restart boundaries |
 | `course-07-evaluation` | L16-L17 | Package-owned offline fixture and design boundary |
+| `course-08-graph` | L18 | Optional local structural graph workflow |
+| Planned: `course-09-skill` | L19 | Validated skill improvement after a disposable lab exists |
 
 ## Command Ownership
 
@@ -70,12 +74,15 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn memory-server` | L02 |
 | `cairn sync` | L02 |
 | `cairn sync-pi` | L13 |
+| `cairn sync-kimi` | L02 |
 | `cairn doctor` | L03; advanced repair in L13-L14 |
 | `cairn trajectory` | L13 |
 | `cairn artifact` | L13 |
 | `cairn capabilities` | L15 |
 | `cairn notes` | L13 |
 | `cairn eval` | L16 |
+| `cairn skill` | L19 |
+| `cairn graph` | L18 |
 | `cairn memory` | L07-L08 |
 | `cairn audit-timer` | L05 and L13 |
 | `cairn uninstall` | L02 and L11-L12 |