Local context implementation

Boundary

Local context is a file-first subsystem:

• source artifacts are versioned under context/**
• derived search state is generated under .agentplane/context/derived/**
• task context evidence is linked from .agentplane/tasks/<task-id>/**
• ACR records may include the extensions.agentplane.context extension

The shared SQLite projection/cache database is .agentplane/cache.sqlite. It is not the source of truth. Context owns only its projection tables inside that database, and context reindex may rebuild those tables from source artifacts. .agentplane/context/service/** remains a context-owned service workspace for context-only cache directories, embeddings, and remote metadata; it no longer owns the SQLite file.

Owning code paths

Surface	Code path
Command specs	packages/agentplane/src/commands/context/*.spec.ts
CLI handlers	packages/agentplane/src/commands/context/*.ts
Shared parsing and refs	packages/agentplane/src/commands/context/context-utils.ts
SQLite driver/projection	packages/agentplane/src/shared/sqlite-driver.ts, packages/agentplane/src/commands/context/sqlite.ts
ACR context extension	packages/agentplane/src/commands/acr/**
Agent handoff	packages/agentplane/src/commands/context/ingest.ts, packages/agentplane/src/context/harvest-tasks-extraction.ts, .agentplane/tasks/<task-id>/README.md

Task-history extraction

context harvest tasks first produces source-backed, unpublished proposal records for completed task history only when an explicit durable marker is present: ADR/public interface, stable workflow rule, recurring finding, resolved conflict, or recorded decision. It captures exact source lines and available PR, diff, or evaluator evidence; it does not infer facts, graph edges, wiki content, or semantic identity from task text. Before a CURATOR work order is created for exactly one explicit --task selection, CLI writes a task-bound canonical pre-selection check with the current canonical source hashes, addressable lexical candidate refs, and a recorded clear or consolidation_required result. It can require CURATOR semantic reconciliation but cannot decide a canonical identity. The exclusive selection lease records owner and expiry; a stale interrupted lease is atomically recovered, while an active lease prevents a second CURATOR owner. Its context extension names the proposal, task README, ACR file, source digest, allowed outputs, and a replaceable prompt module.

The generated prompt module uses the normal prompt-module schema with a stable address:

framework/template/generated.artifact/context_task_knowledge_proposal/v2

This keeps task-history assimilation improvable through the same module/mutation model as other Agentplane prompts. CURATOR is the semantic execution boundary: it reads the bounded source pack, reconciles the candidate, and returns one SGR. The CLI supervisor remains the mechanical boundary: it validates and materializes an accepted SGR, reindexes, evaluates, records ACR, and writes the apply receipt. A CURATOR task must not edit wiki/facts/graph artifacts or perform lifecycle gates.

Assimilation blueprint contract

context.assimilation is the lifecycle blueprint for source-to-wiki work. The blueprint keeps the wiki layout adaptive, but fixes the execution gates:

1. lock a non-empty source set with hashes
2. search and reconcile existing wiki/facts/graph rows before writing
3. write wiki, derived facts, graph/provenance, and reports as needed
4. run context reindex after the final content change
5. run wiki lint, graph validation, verify-task, doctor, and a smoke search
6. record handoff evidence before another agent resumes stalled or transferred work

context init creates only the root wiki contract files (AGENTS.md and index.md). The first real ingest creates the starter wiki hierarchy when there is source material to assimilate.

Projection contract

context reindex writes context projection rows into .agentplane/cache.sqlite from:

• wiki markdown files, including section-level refs
• fact JSONL rows
• graph JSONL entities and edges
• capability markdown files
• raw text windows from the user-created hierarchy under context/raw/**

Projection rows must carry source refs precise enough for context show to recover the backing material. Markdown sections use #section=<slug>, line ranges use #lines=<start>-<end>, and single-line refs use #line=<line>.

Verification contract

context verify-task <task-id> is an evidence gate, not a formatter. It should reject task context outputs when provenance is missing or structurally inconsistent:

• source-set files missing or lacking sha256: hashes
• wiki changes with no source marker
• facts without source refs, confidence, or status
• graph edges pointing to unknown entities
• provenance rows without source and target
• capability notes without source refs
• completed context tasks without the ACR context extension

For in-progress tasks, missing ACR is allowed because the normal close path runs context validation before acr generate.

Persisted execution receipts are deliberately fail-closed as standalone authentication. A path plus SHA-256 stored in the same repository cannot authenticate an observation against a detached same-UID process that can rewrite both values. context verify-task and the verify step inside context finalize-task therefore return compatibility_unverified when no authenticated observation is supplied. The shared context supervisor passes that observation directly while the process is under its authority; the artifact validator remains independently testable but is not a substitute for that live trust channel.

Release checks

Before a context-bearing release, run:

bun test packages/agentplane/src/commands/context/release-readiness.test.ts
bun run docs:cli:check
bun run package:install-smoke

Add broader gates (typecheck, release parity, docs IA, and packaged smoke) when the change touches shared CLI behavior, generated assets, or release metadata.