@cairnkeep/cli 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.9.0] - 2026-08-06
+
+### Added
+
+- Publish complete, centralized MCP tool annotations and add project-scoped
+  `full`, derived `read-only`, and exact custom tool profiles with strict
+  environment precedence and canonical provenance digests.
+- Add immutable context-pack manifests, local and commit-pinned Git installs,
+  atomic project enablement and confirmed updates, retained object storage,
+  integrity diagnostics, and explicit uninstall purge consent.
+- Add read-only context-pack list/search/read tools behind separate local and
+  authenticated-HTTP consent gates. Documents include full provenance; skills
+  remain invisible until their exact project/pack/path/file digest is approved.
+- Add deterministic Markdown chunking, optional embedding-ranked retrieval with
+  offline substring fallback, shell completion, lifecycle tests, operator docs,
+  and learning-path exercises.
+
+Context packs add no runtime dependency, telemetry, background synchronization,
+publisher-authenticity claim, ACL system, automatic skill activation, or
+  provider-specific runtime integration.
+
+## [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 +273,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.7.0...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.9.0...HEAD
+[2.9.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.8.0...v2.9.0
+[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

@@ -15,7 +15,7 @@ Qwen Code, Pi, and other MCP clients).
 ## Status
 
 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
+`doctor`, `trajectory`, `artifact`, `mcp-tools`, `pack`, `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
@@ -41,7 +41,7 @@ and 20 are end-of-life upstream.
 | 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, 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 |
+| Other MCP clients | Memory plus optional domain-knowledge and context-pack 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
@@ -82,8 +82,14 @@ storage paths, secrets, and private derived images, see
   `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
   `cairn trajectory list|show|prune` manages opt-in local session trajectories;
   `cairn artifact list|show|delete|prune` manages opt-in local artifacts;
+  `cairn mcp-tools list|status|set|reset` applies least-authority discovery
+  profiles; `cairn pack` validates, installs, pins, updates, and approves
+  immutable external context;
   `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;
@@ -259,6 +265,11 @@ search):
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
+| `CAIRN_MCP_TOOL_PROFILE` | Process override for MCP exposure: `full`, `read-only`, or `custom` |
+| `CAIRN_MCP_ALLOWED_TOOLS` | Comma-separated exact allowlist required by a custom process profile |
+| `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read tools (default off) |
+| `CAIRN_CONTEXT_PACK_HTTP` | Separately consent to context-pack tools over authenticated HTTP (default off) |
+| `CAIRN_PACK_BASE_DIR` | Immutable pack objects, source records, pointers, and retrieval cache (default `~/.cairnkeep/packs`) |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
 | `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |
@@ -305,6 +316,22 @@ remote memory, and delegated exploration can send content to endpoints you
 configure. Review [Privacy and data flow](docs/privacy-and-data-flow.md) before
 enabling them.
 
+### MCP authority and context packs
+
+Every tool publishes a stable title and all four MCP annotation hints. Use
+`cairn mcp-tools set read-only` for observation-only clients, or an exact custom
+allowlist when a workflow needs fewer tools. Process settings override the
+strict project file; the default remains `full`. Profiles only remove tools and
+cannot bypass capability or feature gates. See
+[MCP tool profiles](docs/mcp-tool-profiles.md).
+
+Context packs are immutable, digest-addressed local document/skill bundles.
+They are installed and project-pinned manually; no background Git sync occurs.
+With `CAIRN_CONTEXT_PACKS=1`, enabled documents are searchable through three
+read-only MCP tools. Skills remain invisible until their exact file digest is
+approved, and are never copied or executed. See
+[Immutable context packs](docs/context-packs.md).
+
 ### Managed capability contract (opt-in)
 
 `CAIRN_CAPABILITY_CONTRACT=1` enables one versioned, typed boundary around the
@@ -391,6 +418,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 +506,9 @@ 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)
+- **MCP tool profiles** — [docs/mcp-tool-profiles.md](docs/mcp-tool-profiles.md)
+- **Immutable context packs** — [docs/context-packs.md](docs/context-packs.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

@@ -52,6 +52,12 @@ Usage:
                            Inspect and manage project capability state. MCP changes
                            require a memory-server restart; operating changes apply
                            on the next invocation.
+  cairn mcp-tools <list|status|set|reset>
+                           Inspect and restrict MCP tool exposure with full,
+                           read-only, or exact custom project profiles.
+  cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>
+                           Build, verify, install, pin, and retrieve immutable
+                           context packs. Packs stay local and disabled by default.
   cairn notes <distill|search-error|promote|doctor>
                            Compile closed trajectories into local hindsight notes,
                            search exact failure signatures, promote corroborated
@@ -59,6 +65,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.
@@ -69,7 +78,7 @@ Usage:
   cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
                            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]
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--purge-packs] [--live-root DIR]
                   [--pi-live-root DIR] [--kimi-live-root DIR] [PROJECT ...]
                            Reverse what cairnkeep installed/modified (operating
                            layer, hook registrations, MCP registration, audit
@@ -110,12 +119,21 @@ case "$cmd" in
   capabilities)
     exec node "$CAIRN_ROOT/mcp-memory-server/dist/capability-cli.js" "$@"
     ;;
+  mcp-tools)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/mcp-tool-cli.js" "$@"
+    ;;
+  pack)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/context-pack-cli.js" "$@"
+    ;;
   notes)
     exec node "$CAIRN_ROOT/mcp-memory-server/dist/note-cli.js" "$@"
     ;;
   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/context-packs.md

@@ -0,0 +1,94 @@
+# Immutable context packs
+
+Context packs provide project-approved reference documents and skills without
+copying them into a harness or promoting them into durable memory. They are
+local, immutable, disabled by default, and never execute instructions.
+
+## Format and identity
+
+The root `context-pack.json` follows
+[`schemas/context-pack.schema.json`](../schemas/context-pack.schema.json). It
+declares a kebab-case ID, semantic version, descriptive metadata, license, and
+an ordered list of UTF-8 `document` or `skill` files with SHA-256 digests.
+
+Validation rejects unknown manifest fields, absolute or traversing paths,
+symlinks, devices, duplicate, missing or undeclared files, invalid UTF-8, and
+digest mismatches. Limits are 1 MiB per file, 1,024 entries, and 64 MiB total.
+The authoritative pack digest covers the exact manifest bytes plus sorted
+path/content bytes. The version label is informative; the digest is identity.
+
+```bash
+cairn pack init ./my-pack --id my-pack --version 1.0.0 \
+  --title "My pack" --description "Reviewed local guidance" --license Apache-2.0
+# Edit metadata/kinds if needed, then refresh file hashes.
+cairn pack lock ./my-pack
+cairn pack validate ./my-pack
+```
+
+## Installation and project pinning
+
+```bash
+cairn pack install ./my-pack
+cairn pack install https://example.invalid/repository.git --ref v1.0.0
+cairn pack list
+cairn pack show PACK-DIGEST
+cairn pack enable PACK-DIGEST --project ./project
+cairn pack disable my-pack --project ./project
+cairn pack remove PACK-DIGEST
+```
+
+Local installation performs no network operation. Git installation requires
+`--ref`, invokes the system `git` executable with an argument array, records
+the exact resolved commit, rejects credentials embedded in URLs, and stores no
+checkout metadata. Immutable objects live under `CAIRN_PACK_BASE_DIR` (default
+`~/.cairnkeep/packs`). Project pointers are atomic and digest-pinned. Remote
+administration may use a validated `--project-id` instead of a local path.
+
+Objects are retained until explicitly removed. Removal is refused while any
+project points to the digest. Ordinary uninstall retains them; use
+`cairn uninstall --purge-packs` only after reviewing the dry run and backup.
+
+Updates never synchronize in the background:
+
+```bash
+cairn pack update my-pack --check --project ./project
+cairn pack update my-pack --apply --confirm CANDIDATE-DIGEST --project ./project
+```
+
+`--check` does not install or switch a project. `--apply` re-inspects the source,
+requires the candidate digest, installs an immutable object, and atomically
+switches only the named project.
+
+## Retrieval and skill approval
+
+Set `CAIRN_CONTEXT_PACKS=1` and restart the memory server to register the three
+read-only, closed-world tools: `context_pack_list`, `context_pack_search`, and
+`context_pack_read`. Every file or search result includes pack ID, version,
+pack digest, path, kind, and file digest. Search uses the existing optional
+embedding configuration and falls back to deterministic substring matching if
+configuration or the endpoint is unavailable. Embedding cache data is stored
+outside immutable objects.
+
+Markdown is split deterministically at headings and paragraphs, with chunks
+bounded to 8 KiB and 512-byte overlap. Only packs enabled for the current
+project are searched.
+
+Skills remain invisible until their exact file digest is approved:
+
+```bash
+cairn pack skills --project ./project
+cairn pack approve-skill PACK-DIGEST path/to/SKILL.md \
+  --confirm FILE-DIGEST --project ./project
+cairn pack revoke-skill PACK-DIGEST path/to/SKILL.md --project ./project
+```
+
+Approval binds the project identity, pack digest, path, and file digest. A pack
+update invalidates approval. Approved skills are only discoverable/readable
+through the context-pack tools; Cairnkeep does not copy, activate, or execute
+them.
+
+Authenticated HTTP deployments need the separate
+`CAIRN_CONTEXT_PACK_HTTP=1` consent flag in addition to
+`CAIRN_CONTEXT_PACKS=1`, the existing bearer token, Host/CORS guards, and a
+project header. Pack digests prove integrity, not publisher authenticity.
+Publisher signatures remain future work.

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

@@ -14,13 +14,19 @@ commands, hooks, plugins, or trajectory adapters.
 | Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
 | 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 |
+| Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
 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.
 
+Every MCP client receives complete tool annotations and may use a Cairnkeep
+least-authority profile independent of harness assets. Context-pack tools are
+ordinary read-only MCP tools and require the pack feature gate; authenticated
+HTTP additionally requires separate pack-HTTP consent. Approved pack skills
+remain context documents, not native harness Skills or automatic instructions.
+
 `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

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.9.0
+**Last reviewed:** 2026-08-06
 
 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,9 @@ 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 | Ready; explicit and default off |
+| Complete MCP annotations and least-authority tool profiles | L20 | L20 | Ready; default profile remains full |
+| Immutable context packs and exact-digest skill approval | L21 | L21 | Ready; default off |
 
 ## Release Review
 
@@ -58,6 +62,9 @@ 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 |
+| `course-09-skill` | L19 | Validated skill improvement in a disposable project |
+| `course-10-trust-context` | L20-L21 | MCP authority profiles and offline context-pack lifecycle |
 
 ## Command Ownership
 
@@ -75,9 +82,12 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn trajectory` | L13 |
 | `cairn artifact` | L13 |
 | `cairn capabilities` | L15 |
+| `cairn mcp-tools` | L20 |
+| `cairn pack` | L21 |
 | `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.9.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,11 @@ 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 |
+| 9 | Least-authority MCP profiles | A client should receive fewer tools than the default catalog |
+| 10 | Immutable context packs | Reviewed external context should be pinned without becoming memory |
 
-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 +46,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
@@ -57,6 +60,8 @@ prerequisites for ordinary memory.
 | Context exploration | Configure an operator-owned exploration binary or route endpoint | Source/context goes only to the selected local or remote component | Check citations/cache; remove variables and relaunch | `course-04-operation` |
 | Containers | Rootless memory or workspace launcher | Named volumes persist; shared checkout mode is read/write, sandbox mode copies into a volume | Inspect mounts/volumes; remove only explicitly named disposable resources | `course-04-operation` |
 | Managed overlays | Separate distribution manifest, wrapper, profile lock, fleet and rollback gates | Policy and secrets belong in the private distribution/machine config, never core | `overlay info`, doctor, fleet dry run/current state, rollback | `course-04-operation` |
+| MCP tool profiles | `cairn mcp-tools set full|read-only|custom` | Strict mode-`0600` project config; process overrides take precedence; profile only removes tools | Inspect catalog/status digest; reset and restart MCP | `course-10-trust-context` |
+| Context packs | Manual local or commit-pinned Git install plus project enablement | Immutable objects and atomic pointers under `CAIRN_PACK_BASE_DIR`; no background sync | Validate, inspect digest, check/apply update, disable/remove | `course-10-trust-context` |
 
 ## Evidence, governance, and measurement
 
@@ -70,7 +75,9 @@ 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 | `course-09-skill` |
+| General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `course-07-evaluation` |
+| Pack retrieval and skills | `CAIRN_CONTEXT_PACKS=1`; HTTP needs separate consent; skills need exact-digest approval | Restart MCP server | `cairn pack skills`; revoke approval or disable pack; no automatic execution | `course-10-trust-context` |
 
 ## Harness and maintenance checks
 

package/docs/learning/README.md

@@ -48,6 +48,10 @@ 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) | Ready | 50 min |
+| L20 | [Least-authority MCP tool profiles](lessons/L20-mcp-tool-profiles.md) | Ready | 25 min |
+| L21 | [Immutable context packs and skill approval](lessons/L21-context-packs.md) | Ready | 40 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 +69,10 @@ 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, evaluation, and context packs are separate
+opt-in modules. MCP profiles are restrictive and never activate an optional
+feature.
 
 ## 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.9.0
 
 ## Outcome