@cairnkeep/cli 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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
@@ -232,7 +252,8 @@ 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.7.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

package/README.md

@@ -84,6 +84,9 @@ 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;
@@ -391,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`,
@@ -460,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

@@ -59,6 +59,9 @@ 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.
@@ -116,6 +119,9 @@ 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" "$@"
     ;;

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/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.7.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
 
@@ -77,7 +81,8 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn capabilities` | L15 |
 | `cairn notes` | L13 |
 | `cairn eval` | L16 |
-| `cairn graph` | L05-L06 |
+| `cairn skill` | L19 |
+| `cairn graph` | L18 |
 | `cairn memory` | L07-L08 |
 | `cairn audit-timer` | L05 and L13 |
 | `cairn uninstall` | L02 and L11-L12 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.7.0
+**Baseline:** Cairnkeep 2.8.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -32,8 +32,9 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 5 | Trajectories, notes, compaction, artifacts | Local session evidence has an explicit retention purpose |
 | 6 | Typed nodes and capability governance | Filtering and centrally inspectable feature state are needed |
 | 7 | Evaluation and ablation | A concrete change needs bounded measurement |
+| 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
 
-Every stage is independently useful. Stages 4-7 are opt-in and are not
+Every stage is independently useful. Stages 4-8 are opt-in and are not
 prerequisites for ordinary memory.
 
 ## Core and derived knowledge
@@ -43,7 +44,7 @@ prerequisites for ordinary memory.
 | Scoped memory | `/remember`, `/recall`, MCP memory tools | Available after MCP registration; named/global DBs under `CAIRN_AGENTFS_BASE_DIR`, project DB under `<server-cwd>/.agentfs/` | Recall in a new session; use reviewed delete/supersession rather than filesystem removal | `course-02-memory` |
 | Memory lifecycle | `/memory-review`, `memory_supersede`, `memory_history`, reviewed apply/invalidate tools | Durable history; no automatic promotion | Inspect key history and provenance | `course-02-memory` |
 | Wiki and alignment | `/wiki-ingest`, `/wiki-query`, `/wiki-lint`, alignment files | Written only when invoked; reviewable `.planning/` artifacts | Re-run lint, inspect source citations, revert tracked changes normally | `course-02-memory` |
-| Knowledge graph | `/graphify` and graph tools | Disabled until configured/invoked; derived graph files | Rebuild from canonical sources; never treat the graph as canonical | `course-02-memory` |
+| Local code graph | `cairn graph build|query|status|diff|explain|path`; `/graphify` delegates | Default off; optional isolated `graphify` executable; incremental work under `graphify-out/`, published view under `.planning/graphs/` | Ignore both derived locations; check status and source before trusting a result; use `--force` only after intentional deletion; uninstall adapters separately | `course-08-graph` |
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
 
 ## Storage and optional topology
@@ -70,7 +71,8 @@ prerequisites for ordinary memory.
 | Typed nodes/import | `CAIRN_TYPED_MEMORY_NODES=1` | Restart MCP server; tool schema changes | Hard-filter search; dry-run, replay-safe import; `cairn doctor --repair` only for derived state | `course-05-evidence` |
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
-| Meta-agent loop | Not shipped | Not applicable | Design contract only; never advertise as an available command | `course-07-evaluation` |
+| Validated skill improvement | Reviewed recurring hindsight; proposal adapter; `CAIRN_EVAL=1` for evaluation | No server restart; explicit subprocesses only | `cairn skill list|show`; exact-digest apply; concurrent-edit-safe rollback | Planned: `course-09-skill` |
+| General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `course-07-evaluation` |
 
 ## Harness and maintenance checks
 

package/docs/learning/README.md

@@ -48,6 +48,8 @@ expanded only after their labs are executable.
 | L15 | [Capability governance](lessons/L15-capability-governance.md) | Brief | 35 min |
 | L16 | [Evaluation and ablation](lessons/L16-evaluation.md) | Brief | 50 min |
 | L17 | [The agent boundary](lessons/L17-agent-boundary.md) | Brief | 25 min |
+| L18 | [Local code graph](lessons/L18-local-code-graph.md) | Brief | 35 min |
+| L19 | [Validated skill improvement](lessons/L19-validated-skill-improvement.md) | Brief | 50 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work
@@ -65,8 +67,8 @@ Every complete lesson contains:
 6. Release compatibility metadata for completed exercises.
 
 The learner should never need optional infrastructure to complete L00-L06.
-Remote memory, RAG, routing, containers, structured capture, typed nodes,
-capability governance, and evaluation are separate opt-in modules.
+Remote memory, RAG, routing, containers, graph indexing, structured capture,
+typed nodes, capability governance, and evaluation are separate opt-in modules.
 
 ## For contributors
 

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.7.0
+**Tested with:** Cairnkeep 2.8.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.7.0
+**Tested with:** Cairnkeep 2.8.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.7.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.8.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.7.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.8.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.7.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.8.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -41,7 +41,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.7.0
+   npm install --global @cairnkeep/cli@2.8.0
    cairn --version
    ```
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.7.0
+**Tested with:** Cairnkeep 2.8.0
 
 ## Outcome
 

package/docs/learning/lessons/L17-agent-boundary.md

@@ -6,23 +6,25 @@
 
 ## Outcome
 
-Separate Cairnkeep's shipped evidence and evaluation substrates from the
-design-only bounded meta-agent proposal, and identify which authority always
-remains with the operator and external harness.
+Separate Cairnkeep's shipped evidence, evaluation, and narrow skill-file
+lifecycle from the design-only general meta-agent proposal, and identify which
+authority always remains with the operator and external harness.
 
 ## Planned lesson
 
 - Current facts: typed capability state, local evidence, immutable evaluation
   inputs, isolated schedules, independent verification, and canonical reports.
-- Design only: natural-language form compilation, candidate generation,
-  candidate injection, comparison, proposal bundles, patch application, and
-  rollback ledgers.
+- Shipped in 2.8.0: reviewed hindsight candidates, bounded edits to one existing
+  `SKILL.md`, isolated baseline/candidate comparison, held-out confirmation,
+  exact-digest application, and rollback ledgers.
+- Design only: general natural-language configuration compilation, arbitrary
+  target types, autonomous scheduling, and an owner inference loop.
 - Cairnkeep coordinates evidence; it does not own a harness inference loop.
 - Natural language is untrusted proposal data, not executable authorization.
 - Separate human gates for form, evaluation, application, confirmation, and
   rollback.
-- Why no CLI command, schema, runtime default, or quality claim ships for the
-  proposed meta-agent loop.
+- Why the shipped `cairn skill` command does not authorize or imply the broader
+  proposed meta-agent loop or a product quality claim.
 
 ## Hands-on lab
 
@@ -36,6 +38,8 @@ be required before any future implementation could act.
 
 - No learner attempts to invoke a meta-agent command or treats an illustrative
   block as a supported schema.
+- The learner can distinguish supported `cairn skill` operations from the
+  broader design-only proposal.
 - Every inference execution remains owned by an operator-configured adapter.
 - A capability digest is not treated as approval, identity proof, or evidence
   of improvement.

package/docs/learning/lessons/L18-local-code-graph.md

@@ -0,0 +1,97 @@
+# L18 - Local code graph
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 35 minutes
+**Introduced in:** Cairnkeep 2.7.0
+
+## Outcome
+
+Build and inspect an optional local structural graph without confusing derived
+graph data with canonical source code or granting an external tool ownership of
+the Cairnkeep operating layer.
+
+## Planned lesson
+
+- When a structural graph answers a code-navigation question better than
+  durable memory, the wiki, or broad text search.
+- Why the graph capability is disabled unless the managed capability contract
+  enables `graph` or the compatibility setting `graphify.enabled` is true.
+- How to install only the isolated `graphify` executable with `uv tool install
+  graphifyy` or `pipx install graphifyy`. Do not run `graphify install` because
+  Cairnkeep owns the harness commands, policies, and lifecycle.
+- How `cairn graph build`, `cairn graph status`, `cairn graph query`,
+  `cairn graph explain`, `cairn graph path`, and `cairn graph diff` share one
+  portable owner across harnesses and the shell.
+- Why builds index local code only, use a reduced subprocess environment, avoid
+  provider credentials and semantic document extraction, and publish validated
+  artifacts atomically under `.planning/graphs/` while Graphify maintains its
+  separate incremental work directory under `graphify-out/`.
+- How the previous successful graph snapshot supports `diff`, and why `--force`
+  is appropriate only when an intentional code deletion reduces the graph.
+- Why exact symbols and narrow terms are more reliable than broad prose, and
+  why every graph result must be checked against canonical source files.
+- How Claude Code and OpenCode receive managed `/graphify` wrappers while
+  `cairn sync-kimi --apply` and `cairn sync-pi --apply` install thin delegates
+  that call only `cairn graph`.
+
+## Hands-on lab
+
+Use the synthetic course repository at checkpoint `course-08-graph` in a
+disposable clone. Confirm that a disabled graph fails before Graphify or graph
+artifacts are accessed. Install only the isolated executable, enable the graph
+through one documented capability path, and then run:
+
+```bash
+cairn graph build
+cairn graph status
+cairn graph query addItem
+cairn graph explain addItem
+cairn graph path addItem writeLedger
+```
+
+Make one reversible change to the synthetic ledger, rebuild, and inspect
+`cairn graph diff`. Revert the source change, rebuild again, and verify the
+status. Inspect `.planning/graphs/` and `graphify-out/` without adding either
+derived location to Git.
+
+## Acceptance criteria
+
+- The disabled-path check creates or changes no graph artifact.
+- `status` identifies whether the published graph is present and current.
+- `query`, `explain`, and `path` return structural discovery evidence that the
+  learner verifies against `src/trail-ledger.mjs`.
+- A second successful build produces a snapshot-backed diff.
+- The learner can explain why `--force` is not a generic retry flag.
+- The repository contains no Graphify-owned harness assets and neither
+  `graphify-out/` nor a published graph artifact is staged for commit.
+- The learner can distinguish graph storage and subprocess data flow from
+  Cairnkeep memory storage and optional embedding traffic.
+
+## Common failures
+
+- If `graphify` is missing, install the isolated CLI and verify it is on
+  `PATH`; do not run its harness installer.
+- If the capability is disabled, enable it through the managed contract or the
+  compatibility setting rather than bypassing the owner.
+- If no previous snapshot exists, make a successful build after a real code
+  change before requesting `diff`.
+- If a path or explanation is empty, retry with exact symbol names and verify
+  the source directly instead of treating a broad query as proof.
+
+## Privacy and trust boundary
+
+The managed build passes the repository path to a local Graphify subprocess and
+publishes a validated view locally. Its reduced environment excludes provider
+credentials, and the managed workflow does not perform semantic document
+extraction. Graphify's incremental `graphify-out/` workspace and Cairnkeep's
+published `.planning/graphs/` view can both contain sensitive structural data.
+Keep both local by default, review ignore rules, and never present the graph as
+canonical evidence.
+
+## Source material
+
+- [Operating guide](../../operating.md#optional-graphify-workflow)
+- [Harness compatibility](../../harness-compatibility.md)
+- [Privacy and data flow](../../privacy-and-data-flow.md)
+- [L15 - Capability governance](L15-capability-governance.md)