diff --git a/README.md b/README.md index 75025d3..b337ebf 100644 --- a/README.md +++ b/README.md @@ -2,633 +2,328 @@ English | [简体中文](README.zh-CN.md) -Cambium is a governance standard and reference toolset for knowledge corpora -maintained with LLM agents. It defines how an agent loads rules, scopes work, -preserves canonical ownership, incorporates sources, manages long-running -changes, and produces auditable evidence before claiming completion. +Cambium is a governance standard and reference toolset for knowledge +repositories maintained with LLM agents. -Cambium does not provide a knowledge corpus, a RAG engine, or a default domain -policy. It governs how an operator and an agent maintain a corpus over time. +It helps an operator answer five practical questions: -## Architecture +1. What rules apply to this repository? +2. What work is required, and who may change shared state? +3. What evidence must exist before work can close? +4. How can an interrupted task resume without guessing? +5. Which decisions belong to the operator rather than the agent? + +Cambium is not a knowledge base, a RAG engine, an agent scheduler, or a default +domain policy. It governs work; it does not supply the corpus or decide its +meaning. + +## Start Here + +- To understand the model, read [The Mental Model](#the-mental-model). +- To adopt Cambium for a repository, follow [Adopt Cambium](#adopt-cambium). +- To resume existing work, run the command in + [Start Or Resume A Task](#start-or-resume-a-task) before writing anything. +- To connect an agent host, see + [Use Cambium From An Agent Host](#use-cambium-from-an-agent-host). +- For every tool and its exact arguments, see [Tools/README.md](Tools/README.md). +- For what is complete, in progress, or only conditional, see + [ROADMAP.md](ROADMAP.md). + +## The Mental Model ```text -effective standard = domain-neutral kernel + exactly one selected profile +effective governance + = Cambium kernel + + exactly one selected profile + + adopter-owned runtime state ``` -The kernel owns the cross-domain rules. A profile supplies one corpus's -concrete scope, language, architecture, corpus-planning bindings and scale, -priorities, sources, roles, expression artifacts, audit bindings, scans, and -supplemental gates. A profile may extend defined interfaces, but it cannot -replace, disable, or weaken the kernel. - -| Component | Responsibility | -|---|---| -| Kernel modules (`K00`-`K13`) | Normative, cross-domain rule text | -| Runtime routes (`R01`-`R13`) | Task-specific loading and execution paths; `Kxx` and `Rxx` are independent namespaces | -| Read Sets | Route-specific source-loading boundary used when a Runtime Card requires read-back | -| Runtime Cards | Kernel-owned, compiled shortcuts for routine agent execution; never a second source of rules | -| Selected profile | The adopter's concrete answers to the profile interface | -| Adopter runtime namespace (`.cambium/`) | Coverage object state, the canonical Required Queue, task-level Progress, hash-bound complex-batch Work Specs, controlled plans including active-task Standards adoption, deltas, receipts, and derived reports | -| Tools | Deterministic checks, controlled state writers, schemas, receipts, and derived/compiled-artifact generators; not final semantic judgment | - -Within the kernel module namespace, [K02 Knowledge Work Construction]() -owns knowledge-object inventory, Coverage semantics, Corpus Planning, -architecture and dependency planning, knowledge-batch production, and -migration safety. [K13 Task Runtime -and Execution Control]() -owns the persistent runtime namespace, Task Contract and task state, -Guidance/Amendments, Progress Ledger, Required Queue, batch transitions, -hash-bound batch Work Specs, controlled active-task Standards-adoption state -writes, completion bindings, handoff, and interruption recovery. K12 remains -the sole owner of which changed Standards predicates affect a live task and -which gates must rerun. This boundary keeps -knowledge-object disposition separate from batch/work-unit lifecycle while -requiring the two state layers to reconcile. - -Routine work starts from Runtime Cards. When a Card is incomplete, disputed, -or insufficient for an exception, the agent reads back its Read Set and the -referenced kernel modules. Normative source text always wins. - -This repository is intentionally uninstantiated. The adopter-specific active -state in -[`K00/03 Standards Governance`]() -still contains placeholders and no profile is selected. It therefore defines -no active standard for a particular knowledge corpus and distributes no -profile-specific `Tools/vocab.yaml` or fabricated `.cambium/state/`. - -## Execution Model - -Cambium separates durable work units from execution contexts. - -- A **batch** is an independently accepted unit of work with its own manifest, - dependencies, receipts, delta, and lifecycle. -- The **Required Queue** is the model-neutral, persistent owner of those batch - manifests, their deterministic order, dependencies, holds, and lifecycle. -- An **agent** is an execution context assigned to work. One agent may execute - several batches sequentially, while isolated agents may execute disjoint - batches concurrently. -- A **subagent** is a child execution context created by a runtime. It is not a - separate Cambium work unit or authority class and may act as a worker, - researcher, or independent reviewer. Acting as the independent reviewer is - the narrowest of those roles: [`K12/12 Substantive Correctness - Review`]() - requires a subagent started with a clean context and carrying no author - context, whose input is only the note body and its Sources. An ordinary child - context that inherits the author's context does not satisfy it. -- A logical **integrator** exclusively controls the shared state named in - [`K13/10 Batch Admission Transitions and Serial Integration`](): - guidance disposition, Queue structural revision, Queue state transition, - contract changes, Standards adoption, batch activation, and merging. That - module states the enumeration; this list is a reader's summary of it. - -The active-batch concurrency limit is not an agent-count limit. Concurrent -workers produce isolated batch outputs; the integrator merges those outputs -one at a time and runs the global checks after each merge. - -Three machine-readable control objects deliberately have different jobs: - -| State object | Owns | +| Layer | What it owns | |---|---| -| Coverage Ledger | Knowledge objects, dispositions, canonical owners, and object-side batch assignment | -| Required Queue | Batch/work-unit manifests, order, dependencies, lifecycle, holds, and transition evidence | -| Progress Ledger | Task Contract, whole-task state, Guidance/Amendments, checkpoints, and the accepted Queue fingerprint | +| `kernel/` | Cross-domain rules, gates, routes, Read Sets, and Runtime Cards | +| Selected profile | One repository's scope, language, architecture, sources, priorities, roles, scans, and allowed extensions | +| `.cambium/` | The adopter's current governance identity, task state, Queue, plans, deltas, receipts, and recovery evidence | +| `Tools/` | Deterministic checks, controlled writers, schemas, and generated projections | + +The kernel is normative. A profile can fill or tighten an extension point, but +cannot disable a kernel rule. Tools execute declared rules; they do not make +the final semantic judgment. + +Runtime Cards are short execution routes, not a second copy of the standard. +When a Card is insufficient or disputed, its Read Set leads back to the +normative kernel text. + +This repository is intentionally uninstantiated. It contains templates and +examples, but selects no adopter profile and creates no fabricated task state. + +## What Ships Today + +Cambium currently provides: + +- a single pre-closed profile template, a safe scaffolder, a machine-readable + adoption interview, a read-only onboarding status view, and profile checks; +- persistent Coverage, Required Queue, and Progress state for resumable work; +- deterministic task and batch transitions, controlled Amendments, active-task + Standards adoption, interruption recovery, and build or maintenance closure; +- append-only receipts and Terminal Proof bindings; +- explicit Global Map, Capability Matrix, and Gap Register validation; +- deterministic page, structure, vocabulary, link, boundary, freshness, and + residual-content checks; +- a generated host-neutral interface: each tool's own CLI declaration compiles + into the agent-facing MCP projection and per-host configuration; +- Card-first activation and progressive Read Set delivery primitives. + +The generated MCP surface is a call surface, not an orchestrator. The tools +still decide whether an operation is valid and whether its evidence counts. + +## What Does Not Ship Yet -They are reconciled rather than treated as interchangeable task lists. +Cambium does not currently bundle: -## Repository Layout +- agent dispatch or scheduling; +- isolated worker workspaces; +- a complete single-writer integrator loop; +- durable Assignment lifecycle management; +- authenticated actor or reviewer identity; +- automatic corpus-wide dependency propagation; +- an independent evaluator that re-derives the complete expected corpus; +- an installable OpenAI Plugin package, Hooks, UI, or marketplace entry. -| Path | Contents | +These boundaries are intentional. A host may add capabilities, but it must not +claim evidence for a capability it cannot prove. See [ROADMAP.md](ROADMAP.md) +for the delivery order. + +## The Three Runtime Ledgers + +Long-running work uses three state objects with different owners: + +| State object | What it answers | |---|---| -| [`kernel/`](kernel/) | Cross-domain standards, Read Sets, and compiled Runtime Cards | -| [`profiles/README.md`](profiles/README.md) | The authoritative profile-slot interface and filling rules | -| [`profiles/_template/`](profiles/_template/) | A domain-neutral form to copy and fill; not a runnable or default profile | -| [`profiles/examples/`](profiles/examples/) | Non-normative completed references; examples are not adoption starting points and cannot be selected in place | -| [`Tools/`](Tools/) | Standard-library Python checks, schemas, receipts, and compiled-artifact generators | -| [`Tools/compiled/`](Tools/compiled/) | Generated artifacts: the CLI invocation contract, its agent-facing MCP projection, and one registration file per supported host. Never hand-edited; `--check` recomputes and compares | -| [`ROADMAP.md`](ROADMAP.md) | Non-normative implementation directions; not a statement of current capability | - -The included -[`Agent Systems Atlas`](profiles/examples/agent-atlas/README.md) profile is an -example of answer shape and specificity. It is not Cambium's default -configuration and does not contain the Atlas knowledge corpus. - -## Adopter Runtime State - -Long-running, resumable, or multi-batch work uses one fixed task namespace in -the adopting repository. Every task first checks whether `.cambium/state/` -already exists, because a seemingly bounded new request may enter a repository -whose earlier persistent task was interrupted. Governance may already exist -without a task runtime: +| Coverage Ledger | Which knowledge objects exist, what disposition they have, and which batch currently owns unfinished work? | +| Required Queue | Which batches exist, what are their manifests and dependencies, and what lifecycle state is each batch in? | +| Progress Ledger | What is the task contract, whole-task state, checkpoint, Standards identity, and accepted Queue fingerprint? | + +They must agree, but they are not interchangeable task lists. + +The adopter-owned namespace is: ```text .cambium/ -├── governance/ # canonical current Standards/Profile identity +├── governance/ # current Standards and selected-profile identity ├── state/ # Coverage, Required Queue, and Progress -├── work_specs/ # immutable restricted-YAML contracts for complex batches -├── deltas/ # worker deltas and restricted-YAML controlled-operation plans -├── receipts/ # deterministic and transition evidence -├── reports/ # derived human-readable views -└── tmp/ # recovery locks and incomplete-write metadata +├── work_specs/ # immutable contracts for complex batches +├── deltas/ # proposed and batch-local changes +├── receipts/ # evidence and transition history +├── reports/ # derived views; never authority +└── tmp/ # locks and interrupted-write recovery evidence ``` -`state/`, `work_specs/`, `deltas/`, and `receipts/` are durable. Reports are -projections, not tool inputs, and `tmp/` is ignored by Git; a surviving writer -lock remains recovery evidence until its operation is reconciled. Cambium -publishes the schemas under `Tools/schemas/`; a conformance fixture suite is -planned rather than shipped, and this repository carries none today (see -[`ROADMAP.md`](ROADMAP.md) `Observability And Conformance`). An adopter creates -its own runtime state with `Tools/init_state.py` after selecting a profile and -defining a task. The tool -requires an explicit objective and exclusions, does not invent Required work, -and does not overwrite any existing `.cambium/state/` task runtime; a valid -governance/history namespace is preserved. -If task state already exists, a restarted or newly assigned Agent first -runs `Tools/check_queue.py . --resume-status` to discover the recorded task, -its `build` or `maintenance` completion semantics, checkpoint binding, latest -task transition, in-flight batches, pending control inputs/deltas, the -applicable completion block, maintenance candidate SHA/partition and prior -completion anchor, holds, writer-lock evidence, and the exact -machine-readable `next_action`. A complete open-batch handoff is reported as -`admit-delta`; a merge-ready batch without an apply receipt becomes -`apply-delta`, and an applied batch without a current close bundle becomes -`run-batch-close-gate`. Only a current bundle authorizes the four-ID -`close-applied-batch` action and its exact copyable close command. This prevents -a fresh Agent context from mistaking an interrupted repository for an unused -one. - -## Current Implementation Boundaries - -The kernel and tools now provide persistent task and Required Queue state, -optional hash-bound complex-batch Work Specs, explicit Global Map / Capability -Matrix / Gap Register validation, and deterministic initialization, -compilation, validation, task/batch transitions, active-task Standards/Profile -adoption, interruption recovery, build Terminal closure, bounded maintenance -closure, and derived report generation. The page-level contract family is also -deterministic: the composed frontmatter page contract (K08/06-08, advisory -`page-contract` gate), the Structure Registry resolution (K01/05-06, -`structure-registry` gate) with its marker-block coverage projections, and the -page boundary contract (K08/09, advisory `boundary-contract` gate) with its -tool-owned boundary projection blocks. -They do not dispatch agents. Worker dispatch, workspace isolation, lifecycle -event delivery beyond the Card/read-back tool result, and the integrator loop -must still be supplied by the adopting runtime or a human operator. - -Those operations are now callable from an agent host without host-specific -code. A compiled CLI invocation contract is derived by introspecting each -tool's own parser rather than being maintained by hand; an agent-facing MCP -projection is generated from that contract; a stdio server serves the -projection; and one registration file per host is rendered from a single server -definition. Every one of those artifacts is generated at build time, written -into the repository, and guarded by `--check` recompute-and-compare, exactly as -Runtime Cards and the composed vocabulary already are. - -Queue admission is Card-first on that interface. A successful -`check_queue --require-ready` result carries a content-addressed Bundle with -R01, every selected task Card, startup read-backs, and the remaining Addendum -plan. The stdio MCP server gives each session an execution-context identity; -the opening transition accepts a machine-delivered admission only in that same -session and preserves the Bundle binding. A direct CLI invocation returns the -same bytes but declares degraded assurance because no host context can be -proved. `check_queue --deliver-readback --readback-rule ` adds -one registered conditional source without loading the whole Kernel. - -That interface layer is deliberately thin, and the boundary is held -mechanically rather than by convention. It does not decide whether an operation -may run, whether a result counts, or whether evidence is kept — those remain -kernel questions answered by the tools themselves. It must not re-implement any -kernel rule, and a test asserts that the server imports only the standard -library, so no judgment module can be reached from it. A kernel refusal reaches -the caller unchanged: the layer never rewrites a refusal into an error, never -presents a failure as a refusal, and reports a result it cannot parse as -unparseable rather than inventing a verdict. - -The shipped Amendment interface first registers an approved operational -decision against the exact current state, then consumes that authorization in -a scope/disposition replan or batch-cancellation transaction. Pending -registration receipts authorize current execution; after verified write-back -they prove history only. A separate Standards-adoption transaction synchronizes -only the three Standards/Profile identities, the Progress load set, and the -structural Queue revision while preserving the task and every batch -lifecycle/hold. After -Queue materialization, a change to any other Task Contract field is rejected -unless a host supplies an equivalent controlled writer; the -baseline recovery path is to pause or cancel the current task, preserve its -runtime, and begin a successor task. One non-scope contract field has its -guarded writer today: `apply_contract_amendment.py` amends the contract's -`policy_exceptions` register of bounded K00/07 policy exceptions in a single -anchored transaction. A generic writer for the remaining non-scope fields -(objective, acceptance, timing) remains roadmap work. - -These writers accept only the current public schema and receipt protocols. An -existing adopter runtime with older or unregistered operational Amendment -state must be converted outside the public execution path before it is loaded; -Standards adoption does not guess or silently upgrade that state. - -Profile setup is agent-conducted over explicit contracts: `scaffold_profile.py` -creates the candidate package from the version-controlled whitelist, the -machine-readable interview contract (`profiles/interview.yaml`) carries the -questions any assisting agent asks and projects the operator's confirmed -answers, and `check_profile.py` validates the result. Filling in a text editor -against the same contracts remains the no-agent fallback. This release does not -bundle an automated interview runner; whatever conducts the interview produces -only a candidate and never invents domain policy, approves a profile, or -selects one for use. Planned convenience and runtime layers are described in -[`ROADMAP.md`](ROADMAP.md). - -Cambium's receipts and Terminal Proof operate inside the adopting repository's -local trust boundary. The shipped checks can validate receipt structure, -declared producer and version labels, exact SHA-256 bindings to current state -and content, transition-chain agreement, and whether evidence is stale. Those -hashes are integrity bindings, not signatures: without an external signing or -controlled-execution system, Cambium does not authenticate which executable -ran, which operating-system account supplied an actor label, or whether the -recorded reviewer was a different person or process. An adversary who may -rewrite the repository, its tools, and its evidence can construct an -internally consistent history. The baseline therefore detects accidental -drift, incomplete transitions, and stale or inconsistent evidence; stronger -provenance requires controls outside this repository. +Do not edit canonical state by hand. Use the owning writer so revisions, +hashes, receipts, and recovery evidence move together. ## Adopt Cambium -Profile adoption follows one process whether the target corpus already exists -or will be built from zero, and Cambium never creates the corpus during setup. -The two differ in exactly one place, described under **Adopting into an empty -corpus** below: a corpus with pages is described from what it contains, and a -corpus without them is described from what bounded founding will create. Start -by confirming the corpus location and profile ID, then scaffold a candidate -profile for that corpus. Do not edit the shared template in place and do not -copy an example as the starting point. +Adoption creates and approves one profile for one repository. Copying a +template or example does not select it. + +### 1. Create a candidate profile ```text -python3 Tools/scaffold_profile.py . --profile-id my-profile # dry-run +python3 Tools/scaffold_profile.py . --profile-id my-profile python3 Tools/scaffold_profile.py . --profile-id my-profile --apply ``` -The scaffolder copies exactly the whitelist in -[`profiles/template-files.yaml`](profiles/template-files.yaml), derives the -mechanical identity and self-path cells, and refuses an existing target; a -manual whitelist copy is the no-agent fallback. - -The template ships pre-closed: every slot switch with a legal exit state is -already in it, operational answers are pre-filled for confirmation, and only -the decisions no template can make remain open. To answer every switch now -instead, the adoption interview walks the closed ones in the same sitting. -Either route produces a fully conformant profile; the fill-depth contract is -in [`profiles/README.md`](profiles/README.md). - -1. Answer the remaining `TODO(profile)` decisions in `profiles/my-profile/` — - by the [adoption interview](profiles/interview.yaml) or by hand. Keep - `profile_id` equal to the directory name and use - [`profiles/README.md`](profiles/README.md) as the interface authority. -2. Validate the filled copy: - - ```text - python3 Tools/check_profile.py profiles/my-profile - ``` - -3. Perform initial adoption through the full - [`R09 Standards Governance Read Set`](). - Prepare a restricted-YAML adoption plan from - [`Tools/schemas/profile_adoption_plan.template.yaml`](Tools/schemas/profile_adoption_plan.template.yaml) — - it binds the adopter's Standards version, status `approved`, effective - date, the exact `profiles/my-profile/profile.md` path, and the candidate's - exact `profile-load` fingerprints. Directory presence, profile discovery, - an example, or a generated file never selects a profile. -4. With the user's explicit authorization, run the no-runtime adoption - transaction. Dry-run first; `--apply` executes prepare/commit/abort with - full restoration on any failure: - - ```text - python3 Tools/apply_profile_adoption.py . --plan .yaml - python3 Tools/apply_profile_adoption.py . --plan .yaml --apply - ``` - - The transaction creates the canonical adopter Standards state, appends the - first immutable adoption receipts, composes the Profile vocabulary and the - frontmatter page contract, stamps the Runtime Cards for the adopted version, and - re-verifies the gates; a failure at any step restores the previous control - plane rather than leaving a partial adoption. The same steps remain - runnable by hand (`compose_vocab.py`, `compose_page_contract.py`, - `stamp_cards.py --set-version` / `--check`) as the no-agent fallback. An - existing `.cambium/state/` task runtime is refused here: an active task adopts through - `adopt_standards.py` (next section). -5. Complete the R09 governance gates before beginning corpus-content work. - [`Tools/README.md`](Tools/README.md) documents the individual commands, - receipts, and exit semantics; tool success alone is not proof that the - complete governance gate passed. - -### Adopting into an empty corpus - -Some of the profile's answers describe a corpus, and a corpus with no pages -cannot yet supply them. None of it needs a relaxed contract or a mechanism that -does not exist; what an empty corpus needs is to be founded first, which is -ordinary authoring work. - -- **The residual scan.** Its matchers normally come from strings real pages - carry. With no pages, declare the structure class you will use, and have - bounded founding create one page under the accepted root that carries it — - the residual witness, authored before any batch or runtime state exists. The - production scan refuses a configuration that recognises nothing in the - repository, so a declared class must be materialized; the positive control - proves only that matchers and `mandated_headings` agree and passes on an - empty repository. -- **Coverage.** Knowledge objects that do not exist yet still get records, so - the first Queue is compiled from pages you intend rather than pages you - have. Those intended pages enter Coverage through the user-confirmed Task - Plan of the large-scale task; the profile never generates Coverage. -- **Corpus Planning** stays `not-applicable` at initial adoption, with a - reason that authorizes bounded founding and defers — not forbids — - large-scale work. The Global Map names existing canonical owners, so the - plan becomes provable once founding creates some, through a second R09 - revision, and - [`K00/13`]() - admits large-scale work only against a proved one. That is the sequence - below, not an obstruction. (A corpus that already has pages skips this: its - owners exist, so the initial adoption can configure the slot directly.) - -### Founding a corpus, then building it - -Creating the first pages of an empty corpus is bounded authoring work. It is -not the large-scale creation `K00/13` admits, so it selects neither R11 nor -Corpus Planning, and — being bounded — it initializes no `.cambium/state/` task runtime -state at all. - -1. Adopt the profile through R09. -2. Author one canonical owner per `Profile Scope` layer, plus the residual - witness declared during the interview (one page may serve as both owner and - witness when that is semantically natural, never merged only to save - files). Ordinary single-note and module routes; no Queue, no Coverage, no - admission gate. -3. With owners on disk, a second R09 revision configures the Corpus Planning - slot: R13 prepares the Global Map, Capability Matrix, and Gap Register - inside that open revision against the `configured` after Profile - ([`K02/03`]() - candidate preparation), validated with `check_profile.py` and - `check_corpus_plan.py --profile `; the revision closes - through the same `apply_profile_adoption.py` transaction (its - `profile-revision` branch), and the artifacts become authoritative then. -4. The large-scale build is the task that follows: initialize runtime state, - pass the `K00/13` admission conditions, compile the Queue, run batches. - -The founding pages are ordinary Required objects from step 4 onward and enter -batches for review like any other page. Nothing is built twice; the sequence -costs one task boundary and the R09 that configures the slot. - -Copying, filling, validating, or recording a manifest path does not activate a -profile by itself. The manifest becomes the selected profile for content work -only when the complete R09 initial-adoption change closes. Validate the filled -copy, not `_template`; the composed vocabulary does not exist before adoption. - -## Call Cambium From An Agent Host - -Cambium's operations are reachable from Claude Code, Codex, Kimi Code, and dsh -without writing host-specific code. What each host reads is a generated file, -never a hand-written one. - -Render the registration for your corpus. Both roots are absolute paths; leave -either out and its placeholder stays in the product: +The first command is a dry run. The second copies only the version-controlled +whitelist and refuses to overwrite an existing candidate. -```bash -python3 Tools/render_host_configs.py . \ - --distribution-root /absolute/path/to/corpus \ - --workspace-root /absolute/path/to/corpus -``` +### 2. Answer the open decisions and validate -The products land in `Tools/compiled/host-configs/`. Install the one your host -reads: - -| Host | Destination | Carries | -|---|---|---| -| Claude Code | `/.mcp.json` | registration + binding | -| Kimi Code | `/.kimi-code/mcp.json` | registration + binding | -| Codex | `/.codex/config.toml` | registration + binding | -| dsh | `/.env` | binding only | -| dsh | `$DSH_HOME/profiles//cordis.patch.yml`, or `dsh --patch ` | registration only, once per machine | - -Registration and binding are two different questions — where the server is, and -which corpus this session governs. Three hosts happen to answer both in one -file; dsh separates them, which is what makes the distinction visible. The -binding travels as `CAMBIUM_WORKSPACE_ROOT`, set by the host and read from the -environment only. It is never inferred from an inherited working directory: -every host starts a stdio server in the session's own directory, but none of -them documents that behaviour, and an undocumented default is not something a -governance binding may rest on. - -**First contact is manual on three of the four hosts.** Claude Code asks a -person to trust the workspace before it loads a project-level `.mcp.json`; -Codex reads a project-level `.codex/config.toml` only while the project is -trusted; Kimi loads project-level MCP config only after the workspace is marked -trusted. A repository that was just cloned cannot approve itself, and that is -the point. Each approval is one time per corpus. dsh needs no approval because -its registration lives in the operator's own profile rather than in the -repository. - -Verify a rendered product before or after installing it: +Use [profiles/interview.yaml](profiles/interview.yaml) with an assisting agent, +or fill the same contract by hand. The authoritative slot guide is +[profiles/README.md](profiles/README.md). -```bash -python3 Tools/render_host_configs.py . --check +```text +python3 Tools/profile_onboarding_status.py . --profile-id my-profile --json +python3 Tools/check_profile.py profiles/my-profile ``` -The server exposes exactly the operations the compiled projection declares. It -decides nothing: it reads exit codes and receipts, passes a kernel refusal -through unchanged, and reports an unparseable result as unparseable rather than -guessing a verdict. +The template pre-closes choices that have a safe legal default. The remaining +questions require operator-confirmed repository decisions. An agent may prepare +a candidate, but may not approve it or invent domain policy. -## Adopt A New Standards Version Into An Active Task +### 3. Approve the profile through R09 -R09 governs the Standards revision and records its exact changed predicates. -When an existing `.cambium/state/` task still freezes the prior Standards/Profile -identity, R09 produces one restricted-YAML plan using -[`Tools/schemas/standards_adoption_plan.template.yaml`](Tools/schemas/standards_adoption_plan.template.yaml): +Prepare a plan from +[Tools/schemas/profile_adoption_plan.template.yaml](Tools/schemas/profile_adoption_plan.template.yaml), +then dry-run and apply it: ```text -.cambium/deltas/standards-adoptions/.yaml +python3 Tools/apply_profile_adoption.py . --plan .yaml +python3 Tools/apply_profile_adoption.py . --plan .yaml --apply ``` -That plan is the task's canonical machine revision record. It binds the -complete approved K00/03 rule bytes, the exact canonical adopter-state -before-image, deterministic after snapshots of `kernel/` and -the selected Profile directory, and the exact changed-predicate, -invalidated-evidence dimension/boundary, and rerun scope. There is no second -revision YAML or prose adoption copy. - -R07 executes or resumes that plan. Dry-run first; only the integrator writes: +The transaction binds the approved Standards version, selected profile, +generated contracts, Runtime Cards, and adoption receipts. It restores the +previous control plane if any step fails. -```text -python3 Tools/adopt_standards.py . \ - --plan .cambium/deltas/standards-adoptions/SA-001.yaml +An empty corpus follows the same adoption contract. First perform bounded +founding work to create real canonical owners and the residual-scan witness; +then adopt a Profile revision that configures Corpus Planning before starting +large-scale work. The exact sequence is documented in +[profiles/README.md](profiles/README.md#adoption-flow). -python3 Tools/adopt_standards.py . \ - --plan .cambium/deltas/standards-adoptions/SA-001.yaml \ - --apply --actor-role integrator -``` +## Start Or Resume A Task -The writer accepts only an `active` or `paused` task. If a build task is already -`completion-candidate`, first use the legal Task transition to return it to -`paused` or `active`; if the new Standards cannot validate a bound Work Spec, -upgrade that specification through its owning process before adoption. The -same preparation formally rolls back any affected `merge-ready` batch and -places every affected `open` batch under `revalidation-required`; the writer -verifies but does not create lifecycle/hold changes. The -transaction then preserves that Task state and every batch state/hold, keeps -Queue membership/order fixed, increments the structural `queue_revision`, -updates the synchronized Contract/Standards/Profile/load set, and appends -recoverable evidence. Historical receipt bytes remain unchanged. - -Every adoption consumes immediate Queue consistency on staged after bytes. -Changed predicates select any additional deferred evidence boundaries: a -batch-close or Terminal gate reruns only when that boundary is reached and does -not block unrelated earlier work. Historical closed transitions continue to -verify under the identity that produced them; declared invalidated evidence cannot -be reused as current evidence under the new predicate. Current-use receipt -catalogs exclude every invalidated-evidence receipt ID accumulated by committed -adoptions. - -The plan and append-only receipts are the Agent interface. Cambium does not -create or consume a persistent Markdown adoption report. - -## Start A Governed Task - -After initial adoption: +Always check for existing runtime state before writing: ```text -Standards Overview - -> Card Index - -> R01 Core Bootstrap Card + the task-specific Runtime Card - -> selected-profile bindings - -> Read Set and kernel source read-back when required - -> applicable gates, deterministic checks, and receipts +python3 Tools/check_queue.py . --resume-status ``` -Begin with the -[`Standards Overview`]() and -[`Kernel Runtime Card Index`](). Load only the -route, profile bindings, and source modules required by the current task. -Combine additional routes only when their Card Index triggers apply; they do -not replace the route for the work itself. - -For every task, first inspect the target repository for `.cambium/state/`. If -it exists, do not write content or task state and do not initialize or -overwrite it: inspect and reconcile its current task first. If task state is -absent, only a long-running, resumable, or multi-batch task initializes it; -bounded work continues without creating empty task state. A valid -`.cambium/governance/` and adoption history may already exist and are -preserved. +If `.cambium/state/` exists, this command reports the recorded task, locks, +holds, in-flight batches, recovery state, and exact `next_action`. Do not +initialize over it. -```text -# Existing runtime state: always inspect before writing. -python3 Tools/check_queue.py . --resume-status +Bounded work does not need empty persistent state. For long-running, resumable, +or multi-batch work, initialize once after profile adoption: -# No .cambium/state/ exists and persistent state applies: initialize once. +```text python3 Tools/init_state.py . \ --task-id YOUR_TASK \ - --objective "State the concrete outcome this task must achieve" \ - --exclude "State one explicit out-of-scope boundary" \ + --objective "State the concrete outcome" \ + --exclude "State one explicit boundary" \ --completion-semantics build \ --scope-version s1 \ --standards-version YOUR_VERSION \ - --profile-manifest profiles/my-profile/profile.md \ - --apply + --profile-manifest profiles/my-profile/profile.md ``` -Choose `build` for corpus-building work that closes through -`completion-candidate`, R08, and Terminal Proof. Choose `maintenance` for an -R10 budget-envelope run that closes through the maintenance completion gate -without entering `completion-candidate`. The choice is required and frozen in -the Task Contract; initialization never guesses it. A bounded single-note task -does not initialize `.cambium/` merely to record this choice. - -A reported writer lock may belong to a live writer or an interrupted write. -Do not delete it until no writer remains and the state files, receipts, -revisions/fingerprint, pending deltas, and any recorded archive move have been -reconciled. JSONL receipts are append-only; an uncertain receipt append keeps -the lock instead of deleting or rewriting evidence. A new task does -not reuse an old namespace, even when the old task is complete or cancelled; -an explicit archive/rollover process must handle that history. Within one -task, `Tools/seal_receipts.py` is that process for verified frozen history: -it moves already-revalidated rows of closed batches into the cold chain -(`.cambium/receipts/cold/`, K12/07), so hot registers stop growing with -every close while every byte and receipt ID stays resolvable. Cross-task -namespace rollover remains manual. - -Once the current task is known and valid, inventory Required objects into -Coverage, declare explicit `batch_specs`, compile the Queue, and run -`check_queue.py` before activating a batch. Simple single-note work does not -need an empty Queue merely to satisfy a formality. The initial compile stores -an immutable origin receipt in Progress; later same-scope replans use a staged -Coverage proposal, register its approved exact diff, and never require editing -canonical Coverage in advance. - -Large-scale construction, migration, or persistent multi-batch corpus work -also configures the selected Profile's `Corpus Planning` slot. Maintain its -restricted-YAML Global Map, Capability Matrix, and Gap Register through R13, -then run `check_corpus_plan.py`. Agents consume its deterministic JSON -projection and the separate semantic-acceptance status instead of storing a -copied report. A Profile-bound authority records accepted/rejected Capability -decisions from restricted YAML with `record_corpus_acceptance.py`; evidence is -append-only JSONL. These artifacts supply explicit topology, capability, -priority, evidence, and gap-handoff inputs. They do not schedule Queue work or -replace Coverage. - -A simple batch records `work_spec_path: null` and `work_spec_sha256: null`. -Only a complex batch creates a restricted-YAML contract directly under -`.cambium/work_specs/` from `Tools/schemas/batch_work_spec.template.yaml`, then -binds that exact path and SHA-256 in Coverage `batch_specs` before Queue -compilation. The Work Spec carries batch-specific outcome, instructions, -acceptance conditions, and constraints; Queue order, lifecycle, holds, and -receipts remain in the Required Queue. - -`init_state.py` infers nothing, so the Task Contract's five selection fields -and the Coverage Ledger come up empty. Do not fill them by hand. Write one plan -from `Tools/schemas/task_plan.template.yaml`, get it confirmed, and apply it: -the transaction is the record of what was agreed, and hand-edited state is not. -Objects not yet created belong in the plan too — the Queue is compiled from -what the task intends to build, not only from what the file system holds. - -The plan names routes, not paths. `selected_card_paths`, `selected_read_sets`, -and `loaded_module_paths` are resolved from `selected_route_ids` through the -canonical indexes and the transitive loading-boundary closure; selecting R01 -alone reaches every other route and well over a hundred modules. List a path -only to add a profile supplemental Read Set, which has no registry to resolve -it from. +Review the dry run, then repeat the command with `--apply`. + +`init_state.py` deliberately leaves work selection empty. Put the confirmed +Task Contract and Coverage choices in one task plan, then materialize the Queue: ```text -# One confirmed plan fills the Task Contract and Coverage (K13/18). cp Tools/schemas/task_plan.template.yaml \ .cambium/deltas/task-plans/TP-001.yaml -# Edit it, replace every TODO(plan), then dry-run and apply: -python3 Tools/apply_task_plan.py . --plan .cambium/deltas/task-plans/TP-001.yaml -python3 Tools/apply_task_plan.py . --plan .cambium/deltas/task-plans/TP-001.yaml --apply -# It prints the next command, with the Queue revision and SHA already filled in: + +python3 Tools/apply_task_plan.py . \ + --plan .cambium/deltas/task-plans/TP-001.yaml + +python3 Tools/apply_task_plan.py . \ + --plan .cambium/deltas/task-plans/TP-001.yaml --apply + +# Use the revision and SHA printed by apply_task_plan.py. python3 Tools/compile_queue.py . --apply --actor-role integrator \ - --expected-queue-revision 1 \ - --expected-sha256 SHA_PRINTED_BY_APPLY_TASK_PLAN + --expected-queue-revision REVISION \ + --expected-sha256 SHA256 + python3 Tools/check_queue.py . python3 Tools/render_queue.py . ``` -Lifecycle writes are dry runs unless `--apply` is supplied, and an apply also -requires the current revision/fingerprint printed by the state tools. See -[`Tools/README.md`](Tools/README.md) for transition commands, exit code 2 -holds, receipts, Amendment registration and execution (including the -contract-amendment writer for bounded K00/07 policy exceptions), interruption -recovery, and both completion paths. +Use `build` when the task closes through Terminal Proof. Use `maintenance` +when it closes through the bounded maintenance gate. The choice is frozen in +the Task Contract. + +## Controlled Changes + +After the Queue exists, shared state changes go through a controlled writer: + +- `register_amendment.py` and `apply_amendment.py` handle approved operational + replans such as bounded scope/disposition changes and batch cancellation; +- `apply_contract_amendment.py` handles the two supported Task Contract fields: + `policy_exceptions` and `amendment_authority`; +- `adopt_standards.py` moves an active task to an approved Standards/Profile + revision without rewriting its lifecycle history; +- `apply_delta.py`, `update_queue.py`, and `update_task.py` own batch and task + progression. + +Writers are dry runs unless `--apply` is present. Shared-state writes are +integrator-only and require current revisions or hashes where the tool asks for +them. Exact commands, schemas, and recovery procedures are in +[Tools/README.md](Tools/README.md). + +## Use Cambium From An Agent Host + +Cambium renders registration and corpus binding for Claude Code, Codex, Kimi +Code, and dsh from one canonical server definition: + +```bash +python3 Tools/render_host_configs.py . \ + --distribution-root /absolute/path/to/cambium \ + --workspace-root /absolute/path/to/corpus + +python3 Tools/render_host_configs.py . \ + --distribution-root /absolute/path/to/cambium \ + --workspace-root /absolute/path/to/corpus \ + --check +``` + +Generated files land under `Tools/compiled/host-configs/`. + +| Host | Install the generated configuration at | +|---|---| +| Claude Code | `/.mcp.json` | +| Codex | `/.codex/config.toml` | +| Kimi Code | `/.kimi-code/mcp.json` | +| dsh | the operator profile for registration and `/.env` for binding | + +Registration answers “where is the server?” Corpus binding answers “which +repository does this session govern?” They are separate capabilities. + +Installing a host configuration is not Cambium adoption. It does not approve a +profile, create task state, or migrate Standards. The MCP server exposes the +generated CLI projection and passes tool verdicts through; it does not create a +second policy engine. + +Card delivery also has a strict evidence boundary. A server can prove what it +sent, but not by itself what a host placed in the model context or what an agent +read. Machine-enforced Assignment delivery remains an in-progress roadmap +capability; until its gate is complete, do not turn transport metadata into a +claim of cognition or independent execution. + +## Safety And Trust Boundary + +- A surviving writer lock is recovery evidence. Do not delete it until the + writer, state files, receipts, pending deltas, and archive moves are + reconciled. +- JSONL receipts are append-only. An uncertain append keeps the lock rather + than guessing whether the receipt landed. +- Exit code `2` is a hold, not success and not an ordinary failure. +- Reports and generated projections are views, never canonical input. +- Repository-provided verifier code is not run automatically; its source and + effects require explicit authorization. + +SHA-256 bindings detect drift and inconsistent history inside the adopter's +local trust domain. They are not signatures. Without a protected runner or +external attestation, Cambium does not authenticate actor labels, reviewer +labels, operating-system identities, or workspace isolation. A party that can +rewrite the repository, tools, and evidence can construct a new internally +consistent history. + +## Repository Map + +| Path | Purpose | +|---|---| +| [`kernel/`](kernel/) | Normative standards, Read Sets, and Runtime Cards | +| [`profiles/`](profiles/) | Profile interface, template, interview, and examples | +| [`Tools/`](Tools/) | Checks, writers, schemas, receipts, and generators | +| [`Tools/compiled/`](Tools/compiled/) | Generated CLI, MCP, metadata, and host projections | +| [`ROADMAP.md`](ROADMAP.md) | Status-based implementation roadmap | + +Examples show answer shape; they are not defaults and must not be selected in +place of an adopter-owned profile. ## License -Cambium assigns licenses by path to its maintained, tracked release files: +Cambium uses path-based licensing: -- Software and implementation materials under [`Tools/`](Tools/) are licensed - under the Apache License 2.0. -- The standards, profile materials, and project documentation under - [`kernel/`](kernel/), [`profiles/`](profiles/), this README, and - [`ROADMAP.md`](ROADMAP.md) are licensed under CC BY 4.0. +- software and implementation material under `Tools/` uses Apache-2.0; +- standards, profiles, README files, and roadmap documentation use CC BY 4.0. -See [`LICENSE.md`](LICENSE.md) for the authoritative scope, -[`ATTRIBUTION.md`](ATTRIBUTION.md) for attribution guidance, and -[`LICENSES/`](LICENSES/) for the complete license texts. +See [LICENSE.md](LICENSE.md), [ATTRIBUTION.md](ATTRIBUTION.md), and +[LICENSES/](LICENSES/) for the authoritative terms and notices. -Adopter-generated profiles, vocabularies, receipts, and runtime evidence do -not acquire a Cambium license merely because they are stored inside these -directories. +Adopter-generated profiles, state, receipts, and evidence do not acquire a +Cambium license merely because Cambium tools manage them. diff --git a/README.zh-CN.md b/README.zh-CN.md index df9e1e2..2611393 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,516 +2,310 @@ [English](README.md) | 简体中文 -Cambium 是一套面向由 LLM Agent 维护的知识语料库的治理标准和参考工具集。 -它定义了 Agent 如何加载规则、限定工作范围、维护权威归属、吸收来源、 -管理长期变更，以及在宣称完成之前生成可审计的证据。 +Cambium 是一套治理标准和参考工具，适用于由 LLM Agent 参与维护的知识仓库。 -Cambium 不提供知识语料库、RAG 引擎或默认的领域策略。它治理的是操作方和 -Agent 如何持续维护一个语料库。 +它主要帮助操作者回答五个实际问题： -## 架构 +1. 这个仓库要遵守哪些规则？ +2. 当前必须做什么，谁可以修改共享状态？ +3. 一项工作结束前，必须留下哪些证据？ +4. 任务中断后，新的 Agent 如何在不猜测的情况下继续？ +5. 哪些决定必须由操作者做，不能交给 Agent 自行判断？ + +Cambium 不是知识库、RAG 引擎、Agent 调度器，也不提供默认的领域政策。它治理 +工作过程，但不提供知识内容，也不替操作者决定内容含义。 + +## 建议从这里开始 + +- 想先理解 Cambium：阅读[理解 Cambium](#理解-cambium)。 +- 想在一个仓库中采用 Cambium：按照[采用 Cambium](#采用-cambium)操作。 +- 想继续一项已有任务：写入任何内容前，先运行 + [开始或恢复任务](#开始或恢复任务)中的检查命令。 +- 想从 Agent 宿主调用 Cambium：阅读 + [从 Agent 宿主调用 Cambium](#从-agent-宿主调用-cambium)。 +- 想查看所有工具及其准确参数：阅读 [Tools/README.md](Tools/README.md)。 +- 想了解哪些能力已经完成、正在开发或有条件可用：阅读 + [ROADMAP.md](ROADMAP.md)。 + +## 理解 Cambium + +Cambium 的有效治理由三部分组成： ```text -effective standard = domain-neutral kernel + exactly one selected profile +有效治理 + = Cambium 内核 + + 唯一一个已选定的 Profile + + 采用方自己拥有的运行时状态 ``` -内核负责跨领域规则。Profile 为一个具体语料库提供明确的范围、语言、架构、 -语料库规划绑定与规模、优先级、来源、角色、表达产物、审计绑定、扫描项及 -补充门禁。Profile 可以扩展已定义的接口，但不能替换、禁用或削弱内核。 - -| 组件 | 职责 | -|---|---| -| 内核模块（`K00`-`K13`） | 规范性的跨领域规则文本 | -| 运行时路由（`R01`-`R13`） | 针对具体任务的加载与执行路径；`Kxx` 与 `Rxx` 是彼此独立的命名空间 | -| Read Sets | 当 Runtime Card 要求回读时使用的、特定于路由的来源加载边界 | -| Runtime Cards | 由内核拥有、为日常 Agent 执行编译的快捷入口；绝不是第二套规则来源 | -| 选定的 Profile | 采用方针对 Profile 接口给出的具体答案 | -| 采用方运行时命名空间（`.cambium/`） | Coverage 对象状态、权威的 Required Queue、任务级 Progress、以哈希绑定的复杂批次 Work Specs、包括活动任务 Standards 采用在内的受控计划、delta、receipt 和派生报告 | -| 工具 | 确定性检查、受控状态写入器、schema、receipt 及派生/编译产物生成器；不负责最终的语义判断 | - -在内核模块命名空间中，[K02 知识工作构建]() -负责知识对象清单、Coverage 语义、Corpus Planning、架构与依赖规划、 -知识批次生产及迁移安全。[K13 任务运行时与执行控制]() -负责持久运行时命名空间、Task Contract 与任务状态、Guidance/Amendments、 -Progress Ledger、Required Queue、批次转换、以哈希绑定的批次 Work Specs、 -受控的活动任务 Standards 采用状态写入、完成绑定、交接及中断恢复。K12 仍是 -唯一负责判定哪些已变更 Standards 谓词会影响活动任务、以及哪些门禁必须重跑 -的模块。这一边界将知识对象的处置与批次/工作单元生命周期分离，同时要求两个 -状态层相互核对一致。 - -日常工作从 Runtime Cards 开始。当某张 Card 不完整、有争议，或不足以处理 -例外时，Agent 回读它的 Read Set 以及其中引用的内核模块。规范性来源文本 -始终优先。 - -本仓库有意保持未实例化状态。采用方特定的活动状态位于 -[`K00/03 Standards Governance`]()， -其中仍含占位符，并且尚未选定任何 Profile。因此，本仓库没有为某个特定知识 -语料库定义活动标准，也不分发特定于 Profile 的 `Tools/vocab.yaml` 或虚构的 -`.cambium/state/`。 - -## 执行模型 - -Cambium 将持久工作单元与执行上下文分离。 - -- **批次（batch）** 是一个独立验收的工作单元，拥有自己的 manifest、依赖、 - receipt、delta 和生命周期。 -- **Required Queue** 是与模型无关的持久所有者，负责这些批次 manifest、 - 它们的确定性顺序、依赖、hold 和生命周期。 -- **Agent** 是被分配执行工作的上下文。一个 Agent 可以依次执行多个批次， - 而相互隔离的 Agent 可以并发执行互不相交的批次。 -- **subagent** 是由运行时创建的子执行上下文。它不是独立的 Cambium 工作单元 - 或权限类别，可以担任执行者、研究者或独立审阅者。担任独立审阅者是这些角色 - 中边界最窄的一种：[`K12/12 Substantive Correctness - Review`]() - 要求 subagent 以干净上下文启动，不携带作者上下文，其输入只能是笔记正文及其 - Sources。继承作者上下文的普通子上下文不满足该要求。 -- 一个逻辑上的 **integrator** 独占控制 - [`K13/10 Batch Admission Transitions and Serial Integration`]() - 中指定的共享状态：Guidance 处置、Queue 结构修订、Queue 状态转换、Contract - 变更、Standards 采用、批次激活及合并。该模块给出完整枚举；这里的列表只是 - 面向读者的摘要。 - -活动批次的并发上限不是 Agent 数量上限。并发执行者生成隔离的批次输出； -integrator 逐个合并这些输出，并在每次合并后运行全局检查。 - -三个机器可读的控制对象被刻意赋予不同职责： - -| 状态对象 | 负责内容 | +| 层 | 负责什么 | |---|---| -| Coverage Ledger | 知识对象、处置、权威所有者和对象侧的批次分配 | -| Required Queue | 批次/工作单元 manifest、顺序、依赖、生命周期、hold 和转换证据 | -| Progress Ledger | Task Contract、整体任务状态、Guidance/Amendments、检查点和已接受的 Queue 指纹 | +| `kernel/` | 跨领域规则、门禁、执行路线、Read Sets 和 Runtime Cards | +| 已选定的 Profile | 一个仓库自己的范围、语言、架构、来源、优先级、角色、扫描规则和允许的扩展 | +| `.cambium/` | 采用方当前的治理身份、任务状态、Queue、计划、变更、receipt 和恢复证据 | +| `Tools/` | 确定性检查、受控写入器、schema 和生成产物 | -它们需要相互核对一致，而不能被当作可互换的任务列表。 +内核是规范性来源。Profile 可以填写或收紧内核预留的扩展点，但不能关闭内核规则。 +工具按照已声明的规则执行检查和写入，但不替操作者做最终的语义判断。 -## 仓库结构 +Runtime Card 是一条简短的执行路线，不是另一份标准。当 Card 的信息不够，或其中 +的要求存在争议时，Agent 应沿着 Read Set 回读内核中的规范文本。 -| 路径 | 内容 | -|---|---| -| [`kernel/`](kernel/) | 跨领域标准、Read Sets 和编译后的 Runtime Cards | -| [`profiles/README.md`](profiles/README.md) | 权威的 Profile 槽位接口与填写规则 | -| [`profiles/_template/`](profiles/_template/) | 可复制并填写的领域中立表单；不是可运行或默认的 Profile | -| [`profiles/examples/`](profiles/examples/) | 非规范性的完整参考；示例不是采用起点，也不能被直接选用 | -| [`Tools/`](Tools/) | 标准库 Python 检查、schema、receipt 和编译产物生成器 | -| [`Tools/compiled/`](Tools/compiled/) | 生成产物：CLI 调用契约、面向 Agent 的 MCP 投影，以及每家宿主一份的注册文件。禁止手改；`--check` 重算并比对 | -| [`ROADMAP.md`](ROADMAP.md) | 非规范性的实现方向；不代表当前能力 | +本仓库有意保持“尚未采用”的状态：它提供模板和示例，但没有替任何采用方选择 +Profile，也没有伪造任务状态。 -内含的 [`Agent Systems Atlas`](profiles/examples/agent-atlas/README.md) -Profile 是答案形式和具体程度的示例。它不是 Cambium 的默认配置，也不包含 -Atlas 知识语料库。 +## 目前已经提供的能力 -## 采用方运行时状态 +Cambium 当前提供： -长期、可恢复或多批次工作在采用方仓库中使用一个固定命名空间。每项任务首先 -检查该命名空间是否已经存在，因为一个看似有界的新请求可能进入了此前持久任务 -被中断的仓库： +- 一份默认关闭可选项的 Profile 模板、安全的 Profile 脚手架、机器可读的采用访谈、 + 只读的入门状态检查和 Profile 校验； +- 可持久保存的 Coverage、Required Queue 和 Progress 状态，使长期任务能够恢复； +- 确定性的任务与批次状态转换、受控 Amendment、活动任务的 Standards 采用、 + 中断恢复，以及 build 或 maintenance 两种完成路径； +- 只追加的 receipt 和 Terminal Proof 绑定； +- 对 Global Map、Capability Matrix 和 Gap Register 的显式校验； +- 确定性的页面、结构、词汇、链接、边界、新鲜度和残留内容检查； +- 宿主无关的生成接口：每个工具自己的 CLI 声明会编译成面向 Agent 的 MCP 接口， + 并生成各宿主所需的配置； +- Card-first activation，以及逐步交付 Read Set 的基础能力。 -```text -.cambium/ -├── state/ # Coverage, Required Queue, and Progress -├── work_specs/ # immutable restricted-YAML contracts for complex batches -├── deltas/ # worker deltas and restricted-YAML controlled-operation plans -├── receipts/ # deterministic and transition evidence -├── reports/ # derived human-readable views -└── tmp/ # recovery locks and incomplete-write metadata -``` +生成的 MCP 接口只是调用入口，不是任务编排器。一次操作是否有效、它的证据是否 +成立，仍由工具判断。 -`state/`、`work_specs/`、`deltas/` 和 `receipts/` 是持久的。报告是投影， -而不是工具输入；`tmp/` 被 Git 忽略，残留的写入器锁在其操作完成核对之前仍是 -恢复证据。Cambium 在 `Tools/schemas/` 下发布 schema；一致性 fixture 套件仍处于 -规划中而尚未随项目发布，当前仓库也不包含这类套件（参见 -[`ROADMAP.md`](ROADMAP.md) 中的 `Observability And Conformance`）。采用方在 -选定 Profile 并定义任务后，使用 `Tools/init_state.py` 创建自己的运行时状态。该工具 -要求显式提供 objective 与 exclusions，不会凭空编造 Required 工作，也不会覆盖任何 -已有的 `.cambium/` 命名空间。 -如果该命名空间已存在，重启或新分配的 Agent 会先运行 -`Tools/check_queue.py . --resume-status`，以发现已记录的任务、它的 `build` 或 -`maintenance` 完成语义、检查点绑定、最新任务转换、进行中的批次、待处理的 -控制输入/delta、适用的完成区块、maintenance candidate SHA/partition 及先前的 -完成锚点、hold、写入器锁证据和准确的机器可读 `next_action`。完整的开放批次 -交接会报告为 `admit-delta`；没有 apply receipt 的 merge-ready 批次会变为 -`apply-delta`；已应用但没有当前 close bundle 的批次会变为 -`run-batch-close-gate`。只有当前 bundle 才授权四 ID 的 -`close-applied-batch` 操作及其可精确复制的关闭命令。这可以防止新的 Agent -上下文误把中断的仓库当成尚未使用的仓库。 - -## 当前实现边界 - -内核和工具现在提供持久的任务及 Required Queue 状态、可选的以哈希绑定的复杂 -批次 Work Specs、显式的 Global Map / Capability Matrix / Gap Register 验证， -以及确定性的初始化、编译、验证、任务/批次转换、活动任务 Standards/Profile -采用、中断恢复、build Terminal 闭合、有界 maintenance 闭合和派生报告 -生成。页面级契约族同样具有确定性：组合后的 frontmatter 页面契约 -（K08/06-08，建议性的 `page-contract` 门禁）、Structure Registry 解析 -（K01/05-06，`structure-registry` 门禁）及其 marker-block coverage 投影， -以及页面边界契约（K08/09，建议性的 `boundary-contract` 门禁）及其由工具 -拥有的边界投影区块。 -它们不会调度 Agent。执行者调度、工作区隔离、事件投递和 integrator 循环仍须 -由采用方运行时或人工操作方提供。 - -这些操作现在可以从 Agent 宿主直接调用，不需要为任何一家写专门的代码。CLI -调用契约由内省每个工具自己的解析器推导得出，而不是人工维护；面向 Agent 的 -MCP 投影由该契约生成；一个 stdio server 提供这份投影；每家宿主一份的注册 -文件由同一份 server 定义渲染。以上每一件都在构建期生成、写进仓库，并由 -`--check` 重算比对守护——与 Runtime Cards 和组合后的词表完全同一套机制。 - -该接口层刻意做得很薄，且这条边界由机械检查守住，而不是靠自觉。它不决定一个 -操作能不能跑、结果算不算成功、要不要留证据——这些仍是内核的问题，由工具自身 -回答。它不得重新实现任何内核规则；有一条测试断言该 server 只 import 标准库， -因此任何判定模块都无法从它到达。内核的拒绝原样到达调用方：该层绝不把拒绝改写 -成错误，绝不把故障伪装成拒绝，读不懂的结果如实上报读不懂，而不是猜一个结论 -出来。 - -随项目提供的 Amendment 接口首先针对准确的当前状态登记一项已批准的操作决策， -随后在范围/处置重新规划或批次取消事务中使用该授权。待处理的 registration -receipt 授权当前执行；在写回验证完成后，它们只用于证明历史。另一个独立的 -Standards 采用事务仅同步三项 Standards/Profile 标识、Progress load set 及结构性 -Queue 修订，同时保留任务以及每个批次的生命周期/hold。Queue 实体化后，若主机 -没有提供等价的受控写入器，则对其他任何 Task Contract 字段的变更都会被拒绝； -基线恢复路径是暂停或取消当前任务、保留其运行时，并启动一个后继任务。目前有 -一个非范围 Contract 字段拥有受控写入器：`apply_contract_amendment.py` 在单一 -锚定事务中修订 Contract 的 `policy_exceptions`（K00/07 有界政策豁免登记）。 -覆盖其余非范围字段（objective、acceptance、timing）的通用写入器仍属于路线图 -工作。 - -这些写入器只接受当前公开的 schema 和 receipt 协议。采用方已有的运行时如果 -包含旧版或未登记的操作性 Amendment 状态，必须在公共执行路径之外完成转换后 -才能加载；Standards 采用不会猜测或静默升级这些状态。 - -Profile 设置由 Agent 基于显式契约主导：`scaffold_profile.py` 按受版本控制的 -白名单创建候选包，机器可读的访谈契约（`profiles/interview.yaml`）承载任何 -协助 Agent 要提出的问题并把操作者确认的答案投影进对应文件，`check_profile.py` -验证结果。在文本编辑器里按同一套契约手工填写仍是无 Agent 的后备路径。此版本 -不捆绑自动化的访谈 runner；无论由谁主持访谈，产出都只是候选——不发明领域 -政策、不批准 Profile、也不选定它。规划中的便捷层与运行时层见 -[`ROADMAP.md`](ROADMAP.md)。 - -Cambium 的 receipt 与 Terminal Proof 在采用方仓库的本地信任边界内运作。 -随项目提供的检查可以验证 receipt 结构、声明的 producer 与版本标签、与当前 -状态和内容准确绑定的 SHA-256、转换链一致性，以及证据是否过期。这些哈希是 -完整性绑定，而不是签名：如果没有外部签名或受控执行系统，Cambium 无法认证 -究竟运行了哪个可执行文件、哪个操作系统账户提供了 actor 标签，或记录的 -审阅者是否确实是另一个人或进程。能够重写仓库、工具和证据的攻击者可以构造 -一套内部一致的历史。因此，基线可以检测意外漂移、不完整转换及过期或不一致 -的证据；更强的来源可追溯性需要本仓库之外的控制措施。 +## 目前还没有提供的能力 -## 采用 Cambium +Cambium 当前不包含： -无论目标语料库已经存在还是将从零开始构建，Profile 采用都遵循同一套流程， -Cambium 在设置期间也从不创建语料库。两者只有一处不同，见下面的**采用进空 -语料库**：已有页面的语料库按它**包含什么**来描述，还没有页面的语料库按有界 -founding **将要创建什么**来描述。首先确认语料库位置与 Profile ID，然后为该 -语料库 scaffold 一个候选 Profile。不要直接编辑共享模板，也不要复制示例作为 -起点。 +- Agent 派发或调度； +- 隔离的执行者工作区； +- 完整的 single-writer integrator 循环； +- 持久、完整的 Assignment 生命周期管理； +- 经过认证的操作者或审阅者身份； +- 自动的全语料库依赖传播； +- 能独立重新推导完整预期语料库的评估器； +- 可安装的 OpenAI Plugin 包、Hooks、UI 或应用市场条目。 -```text -python3 Tools/scaffold_profile.py . --profile-id my-profile # dry-run -python3 Tools/scaffold_profile.py . --profile-id my-profile --apply -``` +这些边界是有意保留的。宿主可以补充额外能力，但不能为自己无法证明的能力声明 +证据。具体交付顺序见 [ROADMAP.md](ROADMAP.md)。 -scaffolder 精确复制 [`profiles/template-files.yaml`](profiles/template-files.yaml) -中的白名单、派生机械的身份与自路径单元格，并拒绝已存在的目标；手工按白名单 -复制是无 Agent 的后备路径。 - -模板出厂即预关闭：所有具备合法退出态的槽位开关已处于关闭态，运营性答案预填待 -确认，只保留模板无法替你回答的决策。若想现在就逐一回答全部开关，采纳面试会在 -同一次填充中走完这些关闭项。两条路径产出的 Profile 同等合规；填充深度契约见 -[`profiles/README.md`](profiles/README.md)。 - -1. 回答 `profiles/my-profile/` 中剩余的 `TODO(profile)` 决策——通过 - [采纳访谈](profiles/interview.yaml) 或手工填写。保持 `profile_id` - 与目录名相同，并以 [`profiles/README.md`](profiles/README.md) 作为接口权威。 -2. 验证填写后的副本： - - ```text - python3 Tools/check_profile.py profiles/my-profile - ``` - -3. 通过完整的 [`R09 Standards Governance Read Set`]() - 执行初始采用。从 - [`Tools/schemas/profile_adoption_plan.template.yaml`](Tools/schemas/profile_adoption_plan.template.yaml) - 准备一份 restricted-YAML 采用计划——它绑定采用方的 Standards version、状态 - `approved`、effective date、准确的 `profiles/my-profile/profile.md` 路径， - 以及候选的精确 `profile-load` 指纹。目录存在、Profile discovery、示例或 - 生成的文件都不能选定 Profile。 -4. 在用户明确授权后，运行无运行时的采用事务。先 dry-run；`--apply` 执行 - prepare/commit/abort，任何一步失败都完整恢复： - - ```text - python3 Tools/apply_profile_adoption.py . --plan .yaml - python3 Tools/apply_profile_adoption.py . --plan .yaml --apply - ``` - - 该事务实例化 K00/03 的四个值、创建首条 Change Summary、组合 Profile - vocabulary 与 frontmatter 页面契约、为已采用版本 stamp Runtime Cards，并 - 复验各门禁；任何一步失败都会恢复此前的控制面，不会留下部分采用。同样的 - 步骤仍可手工执行（`compose_vocab.py`、`compose_page_contract.py`、 - `stamp_cards.py --set-version` / `--check`），作为无 Agent 的后备路径。 - 存在 `.cambium/` 运行时会被拒绝：活动任务通过 `adopt_standards.py` 采用 - （见下一节）。 -5. 在开始语料库内容工作前完成 R09 治理门禁。[`Tools/README.md`](Tools/README.md) - 记录了各项命令、receipt 和退出语义；工具成功本身不能证明完整的治理门禁已经通过。 - -### 采用进空语料库 - -Profile 里有几项答案是在描述语料库，而没有页面的语料库还给不出它们。这不需要 -放宽任何合同，也不需要任何尚不存在的机制——空语料库需要的是先被**建立起来**， -而建立它是普通的创作工作。 - -- **残留扫描**。它的 matcher 通常取自真实页面携带的字符串。没有页面时，就 - **声明**你将使用的结构类，并由有界 founding 在接受根下创建一个携带它的 - 页面——残留见证页，在任何批次或运行时状态存在之前写成。生产扫描 - 会拒绝一个在仓库里认不出任何文件的配置，所以声明的结构类必须被物化；正对照 - 只证明 matcher 与 `mandated_headings` 自洽，在空仓库上照样通过。 -- **Coverage**。尚未创建的知识对象同样有记录，所以第一份 Queue 是从你**打算 - 建**的页面编译出来的，而不是从你**已经有**的页面。这些计划中的页面通过 - 大规模任务里由用户确认的 Task Plan 进入 Coverage；Profile 永远不生成 - Coverage。 -- **Corpus Planning** 在初始采用时保持 `not-applicable`，其理由授权有界 - founding，并**推迟**而非禁止大规模工作。Global Map 点名的是已存在 - 的 canonical owner，所以 founding 创建出属主之后，这份规划才通过第二次 - R09 修订变得可证明；而 - [`K00/13`]() - 只在规划已证明的前提下准入大规模工作。这是下面那条顺序，不是阻碍。 - （已有页面的语料库跳过这一步：属主已存在，初始采用即可直接配置该槽。） - -### 先建立语料库，再构建它 - -创建一个空语料库的头几页是**有界创作工作**。它不是 `K00/13` 所准入的大规模 -创建，因此既不选 R11 也不需要 Corpus Planning；而且既然有界，它根本不初始化 -`.cambium/` 运行时状态。 - -1. 通过 R09 采用 Profile。 -2. 为 `Profile Scope` 的每一层各写出至少一个 canonical owner，加上面试中声明的 - 残留见证页（语义自然兼容时，一个页面可以同时承担 owner 与 witness；不能 - 为了少建文件而强行合并）。普通的单页与模块路线；没有 Queue、没有 - Coverage、没有准入门禁。 -3. 属主落盘之后，由第二次 R09 修订配置 Corpus Planning 槽：R13 在该开放修订 - 内，针对 `configured` 的 after Profile 准备 Global Map、Capability Matrix - 与 Gap Register - （[`K02/03`]() - 的 candidate preparation），用 `check_profile.py` 与 - `check_corpus_plan.py --profile <候选 manifest>` 验证；修订通过同一个 - `apply_profile_adoption.py` 事务（其 `profile-revision` 分支）闭合， - 届时这些制品才成为权威。 -4. 大规模构建是随后的那个任务：初始化运行时状态、过 `K00/13` 的准入条件、编译 - Queue、跑批次。 - -从第 4 步起，那几页就是普通的 Required 对象，与其余页一样进批次复查。没有任何 -内容被建两遍；这条顺序的代价是一个任务边界，加上把槽配置成 `configured` 的那 -一次 R09。 - -复制、填写、验证 Profile 或记录 manifest 路径本身都不会激活它。只有完整的 -R09 初始采用变更闭合后，该 manifest 才会成为内容工作的选定 Profile。应验证 -填写后的副本，而不是 `_template`；组合后的 vocabulary 在采用前并不存在。 +## 三本运行时台账 -## 从 Agent 宿主调用 Cambium +长期任务使用三个职责不同的状态对象： -Cambium 的操作可以从 Claude Code、Codex、Kimi Code 和 dsh 直接调用，不需要为 -任何一家写代码。每家宿主读到的都是生成文件，绝不是手写的。 +| 状态对象 | 它回答的问题 | +|---|---| +| Coverage Ledger | 有哪些知识对象？它们如何处置？未完成工作当前由哪个批次负责？ | +| Required Queue | 有哪些批次？每个批次的清单、依赖和生命周期状态是什么？ | +| Progress Ledger | 任务合同、整体状态、检查点、Standards 身份和已接受的 Queue 指纹是什么？ | -为你的语料库渲染注册文件。两个根都是绝对路径；任一不给，其占位符就留在产物里： +三者必须相互一致，但不能把它们当成三份可以互换的任务列表。 -```bash -python3 Tools/render_host_configs.py . \ - --distribution-root /语料库的绝对路径 \ - --workspace-root /语料库的绝对路径 -``` +采用方拥有的运行时目录结构如下： -产物落在 `Tools/compiled/host-configs/`。把你这家宿主读的那份装上： +```text +.cambium/ +├── governance/ # 当前 Standards 和已选 Profile 的身份 +├── state/ # Coverage、Required Queue 和 Progress +├── work_specs/ # 复杂批次的不可变合同 +├── deltas/ # 提议中的变更和批次内变更 +├── receipts/ # 证据和状态转换历史 +├── reports/ # 派生视图，不是权威输入 +└── tmp/ # 锁和写入中断后的恢复证据 +``` -| 宿主 | 落点 | 承载 | -|---|---|---| -| Claude Code | `<语料库>/.mcp.json` | 注册 + 绑定 | -| Kimi Code | `<语料库>/.kimi-code/mcp.json` | 注册 + 绑定 | -| Codex | `<语料库>/.codex/config.toml` | 注册 + 绑定 | -| dsh | `<语料库>/.env` | 仅绑定 | -| dsh | `$DSH_HOME/profiles/<名>/cordis.patch.yml`，或 `dsh --patch <路径>` | 仅注册，每台机器一次 | +不要手工修改权威状态。应使用拥有该状态的写入器，让 revision、hash、receipt 和 +恢复证据一起更新。 -注册和绑定是两个不同的问题——server 在哪，以及这次会话治哪个语料库。三家宿主 -恰好把两者写进同一个文件；dsh 把它们强行分开，反而让这个区别显形。绑定以 -`CAMBIUM_WORKSPACE_ROOT` 传递，由宿主设置且只从环境变量读取。它绝不从继承来的 -工作目录推断：四家宿主确实都在会话自身的目录里启动 stdio server，但没有一家把 -这个行为写进文档，而未文档化的默认行为不能作为治理绑定的地基。 +## 采用 Cambium -**四家里有三家的首次接入需要人工一步。** Claude Code 在加载项目级 `.mcp.json` -前会请人信任该工作区；Codex 只在项目被信任时才读项目级 `.codex/config.toml`； -Kimi 只在工作区被标记为信任后才加载项目级 MCP 配置。一个刚克隆下来的仓库不能 -自我批准，这正是这道门的意义。每个语料库只需批准一次。dsh 不需要批准，因为它的 -注册放在操作者自己的 profile 里，而不在仓库中。 +采用过程的目标，是为一个仓库创建并批准唯一一个 Profile。复制模板或示例并不 +等于选定 Profile。 -装之前或装之后都可以校验产物： +### 1. 创建候选 Profile -```bash -python3 Tools/render_host_configs.py . --check +```text +python3 Tools/scaffold_profile.py . --profile-id my-profile +python3 Tools/scaffold_profile.py . --profile-id my-profile --apply ``` -该 server 只暴露编译投影所声明的那些操作。它不做任何判定：读退出码和 receipt， -把内核的拒绝原样传出，读不懂的结果如实上报读不懂，而不是猜一个结论。 +第一条命令只预览，不写文件。第二条命令只复制版本控制白名单中的文件；如果目标 +已经存在，它会拒绝覆盖。 -## 将新的 Standards 版本采用到活动任务中 +### 2. 回答开放问题并校验 -R09 治理 Standards 修订，并记录其准确的 changed predicates。当现有 -`.cambium/` 任务仍冻结在此前的 Standards/Profile 标识上时，R09 使用 -[`Tools/schemas/standards_adoption_plan.template.yaml`](Tools/schemas/standards_adoption_plan.template.yaml) -生成一个 restricted-YAML 计划： +可以让 Agent 按 [profiles/interview.yaml](profiles/interview.yaml) 协助访谈， +也可以手工填写同一份合同。各字段的权威说明在 +[profiles/README.md](profiles/README.md)。 ```text -.cambium/deltas/standards-adoptions/.yaml +python3 Tools/profile_onboarding_status.py . --profile-id my-profile --json +python3 Tools/check_profile.py profiles/my-profile ``` -该计划是任务的权威机器修订记录。它绑定完整且已批准的 K00/03 字节、`kernel/` -与选定 Profile 目录在变更后的确定性快照，以及准确的 changed-predicate、 -invalidated-evidence dimension/boundary 与 rerun scope。不存在第二份修订 YAML -或散文式采用副本。 +模板已经预先关闭有安全默认值的选项。剩余问题都需要操作者确认仓库的真实情况。 +Agent 可以准备候选答案，但不能批准 Profile，也不能自行发明领域政策。 -R07 执行或恢复该计划。先进行 dry-run；只有 integrator 可以写入： +### 3. 通过 R09 批准 Profile -```text -python3 Tools/adopt_standards.py . \ - --plan .cambium/deltas/standards-adoptions/SA-001.yaml +以 +[Tools/schemas/profile_adoption_plan.template.yaml](Tools/schemas/profile_adoption_plan.template.yaml) +为模板准备采用计划，然后先预览，再正式应用： -python3 Tools/adopt_standards.py . \ - --plan .cambium/deltas/standards-adoptions/SA-001.yaml \ - --apply --actor-role integrator +```text +python3 Tools/apply_profile_adoption.py . --plan .yaml +python3 Tools/apply_profile_adoption.py . --plan .yaml --apply ``` -写入器只接受 `active` 或 `paused` 任务。如果一个 build 任务已处于 -`completion-candidate`，先使用合法的 Task 转换使其回到 `paused` 或 -`active`；如果新的 Standards 无法验证已绑定的 Work Spec，则在采用前通过其 -归属流程升级该 specification。相同的准备工作会正式回滚任何受影响的 -`merge-ready` 批次，并将每个受影响的 `open` 批次置于 -`revalidation-required` 下；写入器会验证生命周期/hold 变更，但不会创建它们。 -随后，该事务保留 Task 状态以及每个批次的状态/hold，保持 Queue 成员及顺序不变， -递增结构性 `queue_revision`，更新同步的 Contract/Standards/Profile/load set， -并追加可恢复证据。历史 receipt 的字节保持不变。 - -每次采用都要求 staged after bytes 立即满足 Queue 一致性。Changed predicates -会选择任何额外的延迟证据边界：batch-close 或 Terminal 门禁仅在到达该边界时 -重跑，不会阻塞此前不相关的工作。历史上已关闭的转换仍按生成它们时的标识进行 -验证；已声明失效的证据不能在新谓词下被重新用作当前证据。当前使用的 receipt -catalog 会排除已提交采用所累计的每一个 invalidated-evidence receipt ID。 +这个事务会把已批准的 Standards 版本、所选 Profile、生成合同、Runtime Cards 和 +采用 receipt 绑定在一起。任何一步失败，工具都会恢复之前的控制面。 -该计划和仅追加的 receipt 是 Agent 接口。Cambium 不创建或使用持久的 Markdown -采用报告。 +空语料库也使用同一份采用合同。先进行有界的 founding 工作，创建真实的 +canonical owner 和残留扫描见证；然后再次修订 Profile，配置 Corpus Planning， +之后才能开始大规模工作。完整顺序见 +[profiles/README.md](profiles/README.md#adoption-flow)。 -## 启动受治理任务 +## 开始或恢复任务 -初始采用完成后： +写入任何内容前，先检查仓库是否已经存在运行时状态： ```text -Standards Overview - -> Card Index - -> R01 Core Bootstrap Card + the task-specific Runtime Card - -> selected-profile bindings - -> Read Set and kernel source read-back when required - -> applicable gates, deterministic checks, and receipts +python3 Tools/check_queue.py . --resume-status ``` -从 [`Standards Overview`]() 和 -[`Kernel Runtime Card Index`]() 开始。只加载当前 -任务所需的路由、Profile bindings 和来源模块。仅当 Card Index 的触发条件适用时 -组合其他路由；它们不会替代工作本身对应的路由。 +如果 `.cambium/state/` 已经存在，这条命令会报告已记录的任务、锁、hold、正在执行 +的批次、恢复状态和准确的 `next_action`。不要在已有状态之上重新初始化。 -对每项任务，先检查目标仓库中是否存在 `.cambium/`。如果存在，不要写入内容 -或状态，也不要初始化或覆盖它：先检查并核对其中的当前任务。如果不存在，则只有 -长期、可恢复或多批次任务才初始化它；有界工作继续执行而不创建空的运行时状态。 +有界工作不要求创建空的持久状态。长期、可恢复或多批次任务，应在 Profile 采用后 +只初始化一次： ```text -# Existing runtime state: always inspect before writing. -python3 Tools/check_queue.py . --resume-status - -# No .cambium/ exists and persistent state applies: initialize once. python3 Tools/init_state.py . \ --task-id YOUR_TASK \ - --objective "State the concrete outcome this task must achieve" \ - --exclude "State one explicit out-of-scope boundary" \ + --objective "写明要得到的具体结果" \ + --exclude "写明至少一项明确边界" \ --completion-semantics build \ --scope-version s1 \ --standards-version YOUR_VERSION \ - --profile-manifest profiles/my-profile/profile.md \ - --apply + --profile-manifest profiles/my-profile/profile.md ``` -对于语料库构建工作，选择 `build`；此类工作通过 `completion-candidate`、R08 -和 Terminal Proof 闭合。对于 R10 budget-envelope 运行，选择 `maintenance`； -此类工作通过 maintenance completion gate 闭合，而不进入 `completion-candidate`。该选择是 -必填项，并被冻结在 Task Contract 中；初始化从不猜测它。一个有界的单笔记任务 -不会仅为记录此选择而初始化 `.cambium/`。 - -报告的写入器锁可能属于仍在运行的写入器，也可能来自中断的写入。在确认没有 -写入器残留，并对状态文件、receipt、revision/fingerprint、待处理 delta 及任何 -已记录的 archive move 完成核对前，不要删除它。JSONL receipt 仅可追加；不确定的 -receipt append 会保留锁，而不是删除或重写证据。新任务不会复用旧命名空间， -即使旧任务已完成或已取消；必须通过显式的 archive/rollover 流程处理该历史。在 -同一任务内部，`Tools/seal_receipts.py` 就是已验证冻结历史的那个流程：它把已 -关闭批次的、经过完整复验的收据行移入冷链（`.cambium/receipts/cold/`，见 -K12/07），热账本不再随每次关批增长，而每一个字节与收据 ID 永久可解析。跨任务 -的命名空间滚转仍需人工处理。 - -确认当前任务已知且有效后，将 Required 对象清点到 Coverage 中，声明显式的 -`batch_specs`，编译 Queue，并在激活批次前运行 `check_queue.py`。简单的 -单笔记工作无需仅为满足形式要求而创建空 Queue。初次编译在 Progress 中存储一份 -不可变的 origin receipt；后续同范围重新规划使用 staged Coverage proposal， -登记其已批准的准确 diff，并且绝不要求预先编辑权威 Coverage。 - -大规模构建、迁移或持久多批次语料库工作还需要配置选定 Profile 的 -`Corpus Planning` 槽位。通过 R13 维护其 restricted-YAML Global Map、 -Capability Matrix 和 Gap Register，然后运行 `check_corpus_plan.py`。Agent 使用其 -确定性 JSON 投影和独立的 semantic-acceptance 状态，而不是存储复制的报告。 -一个受 Profile 绑定的权威角色使用 `record_corpus_acceptance.py`，从 -restricted YAML 记录已接受/已拒绝的 Capability 决策；证据采用仅追加 JSONL。 -这些产物提供显式的 topology、capability、priority、evidence 和 gap-handoff -输入。它们不调度 Queue 工作，也不替代 Coverage。 - -简单批次记录 `work_spec_path: null` 和 `work_spec_sha256: null`。 -只有复杂批次才会直接在 `.cambium/work_specs/` 下，根据 -`Tools/schemas/batch_work_spec.template.yaml` 创建 restricted-YAML 契约，然后在 Queue 编译前将该 -准确路径和 SHA-256 绑定到 Coverage 的 `batch_specs` 中。Work Spec 承载批次 -特定的 outcome、instructions、acceptance conditions 和 constraints；Queue 顺序、 -生命周期、hold 及 receipt 仍保留在 Required Queue 中。 - -`init_state.py` 不推断任何内容，因此任务合同的五个选择字段与 Coverage Ledger -建出来都是空的。**不要手工填写它们。** 依据 -`Tools/schemas/task_plan.template.yaml` 写一份计划，确认之后再应用：这份事务 -本身就是「当时确认了什么」的记录，手改的状态不是。尚未创建的对象同样要写进 -计划——Queue 是从任务打算构建的内容编译出来的，不只是文件系统已有的内容。 - -计划里写的是路由，不是路径。`selected_card_paths`、`selected_read_sets` 与 -`loaded_module_paths` 由 `selected_route_ids` 经规范索引与加载边界的传递闭包 -解析得到；只选 R01 一条就会闭合到其余全部路由与一百多个模块。只有在需要加入 -profile 补充 Read Set（它没有可解析的注册表）时，才手写路径。 +先检查预览结果，再加上 `--apply` 重复运行。 + +`init_state.py` 不会替你选择工作。把已确认的 Task Contract 和 Coverage 选择写入 +同一份任务计划，再生成 Queue： ```text -# 一份已确认的计划填入任务合同与 Coverage（K13/18）。 cp Tools/schemas/task_plan.template.yaml \ .cambium/deltas/task-plans/TP-001.yaml -# 编辑它，替换掉每一处 TODO(plan)，然后先 dry-run 再 apply： -python3 Tools/apply_task_plan.py . --plan .cambium/deltas/task-plans/TP-001.yaml -python3 Tools/apply_task_plan.py . --plan .cambium/deltas/task-plans/TP-001.yaml --apply -# 它会打印下一条命令，Queue 的 revision 与 SHA 已经填好： + +python3 Tools/apply_task_plan.py . \ + --plan .cambium/deltas/task-plans/TP-001.yaml + +python3 Tools/apply_task_plan.py . \ + --plan .cambium/deltas/task-plans/TP-001.yaml --apply + +# 使用 apply_task_plan.py 输出的 revision 和 SHA。 python3 Tools/compile_queue.py . --apply --actor-role integrator \ - --expected-queue-revision 1 \ - --expected-sha256 SHA_PRINTED_BY_APPLY_TASK_PLAN + --expected-queue-revision REVISION \ + --expected-sha256 SHA256 + python3 Tools/check_queue.py . python3 Tools/render_queue.py . ``` -生命周期写入在未提供 `--apply` 时是 dry run；apply 还要求使用状态工具打印的 -当前 revision/fingerprint。转换命令、退出码 2 的 hold、receipt、Amendment 登记 -与执行、中断恢复及两种完成路径，参见 [`Tools/README.md`](Tools/README.md)。 +需要 Terminal Proof 才能关闭的任务使用 `build`；通过有界 maintenance 门禁关闭 +的任务使用 `maintenance`。这个选择会冻结在 Task Contract 中。 + +## 受控变更 + +Queue 生成后，共享状态必须通过对应的受控写入器修改： + +- `register_amendment.py` 和 `apply_amendment.py`：处理已批准的运营调整，例如有界 + 的范围或处置变化，以及取消批次； +- `apply_contract_amendment.py`：修改目前支持的两个 Task Contract 字段： + `policy_exceptions` 和 `amendment_authority`； +- `adopt_standards.py`：让活动任务采用已批准的新 Standards/Profile 版本，同时 + 保留原有生命周期历史； +- `apply_delta.py`、`update_queue.py` 和 `update_task.py`：负责批次与任务推进。 + +除非带有 `--apply`，这些写入器都只预览。共享状态写入只允许 integrator 执行； +工具要求 revision 或 hash 时，必须提供当前值。准确命令、schema 和恢复步骤见 +[Tools/README.md](Tools/README.md)。 + +## 从 Agent 宿主调用 Cambium + +Cambium 从一份权威 server 定义，为 Claude Code、Codex、Kimi Code 和 dsh 生成 +注册配置和语料库绑定： + +```bash +python3 Tools/render_host_configs.py . \ + --distribution-root /cambium/的绝对路径 \ + --workspace-root /语料库/的绝对路径 + +python3 Tools/render_host_configs.py . \ + --distribution-root /cambium/的绝对路径 \ + --workspace-root /语料库/的绝对路径 \ + --check +``` + +生成文件位于 `Tools/compiled/host-configs/`。 + +| 宿主 | 生成配置应安装到 | +|---|---| +| Claude Code | `/.mcp.json` | +| Codex | `/.codex/config.toml` | +| Kimi Code | `/.kimi-code/mcp.json` | +| dsh | 用操作者 Profile 注册，用 `/.env` 绑定语料库 | + +“注册”回答 server 在哪里；“语料库绑定”回答当前会话治理哪个仓库。它们是两种 +不同的能力。 + +安装宿主配置不等于采用 Cambium：它不会批准 Profile、创建任务状态或迁移 +Standards。MCP server 只暴露生成的 CLI 接口并原样传递工具结论，不会创建第二套 +政策引擎。 + +Card 交付也有严格的证据边界。server 可以证明自己发送了什么，但不能单独证明 +宿主把什么放入模型上下文，也不能证明 Agent 读过什么。机器强制的 Assignment +交付仍是路线图中的开发中能力；完整门禁完成前，不能把传输元数据写成“已经理解” +或“已经独立执行”的证据。 + +## 安全和信任边界 + +- 遗留的写入器锁是恢复证据。在核对写入器、状态文件、receipt、待处理 delta 和 + 归档移动之前，不要删除它。 +- JSONL receipt 只能追加。如果不确定一次追加是否成功，应保留锁，不要猜测。 +- 退出码 `2` 表示 hold，既不是成功，也不是普通失败。 +- report 和生成投影只是视图，不能作为权威输入。 +- 仓库提供的 verifier 代码不会自动运行；运行前必须明确授权并检查其源码和影响。 + +SHA-256 绑定可以在采用方的本地信任域中发现漂移和不一致历史，但它不是数字签名。 +没有受保护 runner 或外部证明时，Cambium 无法认证 actor/reviewer 标签、操作系统 +身份或工作区隔离是否真实。能够同时改写仓库、工具和证据的一方，也能构造一套新 +的、内部自洽的历史。 + +## 仓库结构 + +| 路径 | 用途 | +|---|---| +| [`kernel/`](kernel/) | 规范性标准、Read Sets 和 Runtime Cards | +| [`profiles/`](profiles/) | Profile 接口、模板、访谈和示例 | +| [`Tools/`](Tools/) | 检查、写入器、schema、receipt 和生成器 | +| [`Tools/compiled/`](Tools/compiled/) | 生成的 CLI、MCP、元数据和宿主投影 | +| [`ROADMAP.md`](ROADMAP.md) | 按状态组织的实现路线图 | + +示例只说明答案应写成什么形式，不是默认配置，也不能代替采用方自己拥有的 +Profile。 ## 许可证 -Cambium 按路径为其维护并纳入版本跟踪的发行文件分配许可证： +Cambium 按路径使用不同许可证： -- [`Tools/`](Tools/) 下的软件和实现材料采用 Apache License 2.0。 -- [`kernel/`](kernel/)、[`profiles/`](profiles/)、本 README 及 - [`ROADMAP.md`](ROADMAP.md) 下的标准、Profile 材料和项目文档采用 CC BY 4.0。 +- `Tools/` 下的软件和实现材料使用 Apache-2.0； +- 标准、Profile、README 和路线图文档使用 CC BY 4.0。 -权威的适用范围见 [`LICENSE.md`](LICENSE.md)，署名指南见 -[`ATTRIBUTION.md`](ATTRIBUTION.md)，完整许可证文本见 -[`LICENSES/`](LICENSES/)。 +权威条款和声明见 [LICENSE.md](LICENSE.md)、[ATTRIBUTION.md](ATTRIBUTION.md) +和 [LICENSES/](LICENSES/)。 -采用方生成的 Profile、vocabulary、receipt 和运行时证据不会仅仅因为存储在这些 -目录中就自动适用 Cambium 许可证。 +采用方生成的 Profile、状态、receipt 和证据，不会因为由 Cambium 工具管理而自动 +获得 Cambium 的许可证。 diff --git a/ROADMAP.md b/ROADMAP.md index 65e295b..a885f75 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,1010 +1,518 @@ # Cambium Roadmap -This roadmap is non-normative. It describes product implementation directions, -not kernel rules, profile requirements, current capabilities, or release -commitments. A feature is available only when the repository contains its -implementation and the current documentation says how to use it. +This roadmap describes product direction. It is not a kernel rule, a Profile +requirement, or a release promise. -The kernel and profile interface remain the authority for governed knowledge -work. Future convenience layers may collect, project, and execute decisions; -they may not invent domain policy, approve a profile, weaken a kernel gate, or -bypass R09 adoption. +A capability is available only when its implementation, documentation, and +tests are present in the repository. A roadmap paragraph alone never makes a +feature available. -## Current Baseline +## How To Read This Roadmap -| Area | Current state | +Every item has one of four states: + +| State | Meaning | |---|---| -| Profile setup | `scaffold_profile.py` creates the candidate from the version-controlled whitelist `profiles/template-files.yaml` (16 copied files; the orientation README is never copied) and derives the mechanical identity/self-path cells; the interview contract `profiles/interview.yaml` collects the remaining decisions; `check_profile.py` validates. Manual whitelist copy remains the no-agent fallback | -| Execution | The kernel defines sequential work, concurrent disjoint batches, independent review contexts, and serial integration | -| Persistent work state | `.cambium/` separates object-level Coverage, the canonical Required Queue, task-level Progress, and hash-bound restricted-YAML complex-batch Work Specs; standard-library tools initialize, compile, validate, transition, apply Amendment-bound cross-Ledger changes, recover interrupted-write evidence, and render Queue state | -| Active-task Standards adoption | One restricted-YAML plan binds approved governance bytes, deterministic Kernel/Profile snapshots, old/new Contract/Standards/Profile/load set, changed predicates, and dimension/boundary-specific invalidated evidence. Current admission projects semantic leaf impacts to registered owner Gates: Queue consistency is the only raw immediate receipt, while review/close/completion owners remain mandatory at their native transitions. After required pre-rollbacks/holds, `adopt_standards.py` synchronizes all three runtime identities without changing lifecycle/holds; append-only receipts preserve producer-era history, filter invalidated-evidence receipt IDs from current use, recover interruption, and avoid a prose duplicate | -| Runtime | No bundled orchestrator, scheduler, or workspace manager. The shipped agent interface below is a call surface, not a runtime: it dispatches nothing, schedules nothing, and owns no assignment state | -| Agent interface | Shipped. `compile_cli_contract.py` derives the CLI invocation contract by introspecting each tool's own parser; `render_interface_projection.py` projects it into the agent-facing MCP tool list (40 operations); `mcp_server.py` serves that list over stdio at protocol `2025-11-25` and decides nothing — it reads exit codes and receipts and never infers a verdict; `render_host_configs.py` renders registration and corpus binding for Claude Code, Codex, Kimi Code, and dsh from one canonical server definition. All four artifacts are build-time generated with `--check` recompute-and-compare. Adopting an already-supported host is configuration only; supporting a new host adds one renderer | -| OpenAI Plugin adapter | MCP configuration now ships through the host-neutral agent interface above. No Plugin manifest, Skills, Hooks, or marketplace entry. Measured while building that interface: the Agent Plugins shell cannot determine which corpus a session governs at handshake — it declares no roots, resolves an omitted `cwd` to the plugin root rather than the session workdir, and rejects `env_vars` whitelist forwarding. A per-corpus binding and that shell are not simultaneously available; Codex is therefore registered through its project-level `.codex/config.toml`. The candidate design remains a host-specific adapter over the host-neutral Core, not a replacement for the kernel, selected Profile, or adopter-owned state | -| Corpus planning and impact inputs | A configured Profile explicitly binds restricted-YAML Global Map, Capability Matrix, and Gap Register artifacts; `check_corpus_plan.py` validates structure/reconciliation and emits deterministic JSON, while `record_corpus_acceptance.py` records the distinct Profile-authorized semantic decision as append-only JSONL; no duplicate Markdown report is persisted | -| Automatic dependency propagation | The kernel defines semantic dependency invalidation and downstream `needs_rereview`, but no bundled compiler or change detector yet calculates an affected set from the explicit planning inputs | -| Independent completeness and consistency evaluation | Current gates prove integrity within the declared Coverage, Queue, Delta, receipt, and snapshot boundaries. No bundled independent pass yet re-derives the expected corpus or impact set without trusting those declarations, or evaluates paraphrased cross-document contradictions as a general capability | -| Tools | Deterministic checks, schemas, receipts, vocabulary/Card compilation, Corpus Planning validation/semantic acceptance/on-demand Agent projection, Required Queue and Work Spec control, guarded Amendment and active-task Standards-adoption transactions, single-delta application, and the four agent-interface generators. The 27 receipt-producing tools carry `--json`: the receipt they already build is serialized to stdout while the human summary moves to stderr, and behaviour without the flag is unchanged. A tool that produces no receipt has nothing to serialize and carries no flag | -| Page-level contract family | The composed frontmatter page contract (K08/06-08; `compose_page_contract.py` + advisory `page-contract` gate), Structure Registry resolution (K01/05-06; `structure-registry` gate) with marker-block coverage projections, and the page boundary contract (K08/09; advisory `boundary-contract` gate) with its tool-owned boundary projection — all deterministic, with advisory gates awaiting per-adopter promotion decisions under K12/10 | - -## Profile Adoption Reform And Onboarding - -Reduce profile adoption cost without shrinking the interface. The 14-slot -interface stays; the reform ships one template that pre-closes every switch -with a legal exit state and pre-fills the operational answers that generalize, -and moves fill depth into the adoption interview, which walks those closed -switches on request. Taking a default is full conformance, never a lower -conformance tier. Acceptance target: a real small corpus reaches a checked -candidate profile with at most 15 operator decisions in at most 30 minutes. - -### Pre-closed Template - -One template in which every slot with a legal exit state (`None`, -`Not applicable`, `kernel-defaults`, empty override table) ships already -closed with scenario-accurate reasons, and the shapes for each closed branch -travel as comments in the slot file that closes it. Identity remains -unfilled, so the template is not selectable. An adopter who wants every -switch answered explicitly gets that from the interview's expansion packs, -not from a second directory to keep in step. - -### Pre-filled Defaults, Answer Patterns, And Kernel Absorption - -Operational answers — process and host role bindings, audit starter judgment -items, no-grants priority, language display/naming/length defaults, and a -generic volatility domain — ship pre-filled in the template with -generalized wording and are confirmed or replaced during the interview; the -kernel is not changed for them. Once real adoptions show a pre-filled answer -is stable, it is harvested into a kernel-owned default-declaration state -through ordinary standards work, so later improvements propagate instead of -freezing in copied text. - -Required slots without a legal exit state — Knowledge Spine, Terminology -Structure, Foundation Depth Requirements, and Source Authority — are answered -through lightweight answer patterns rather than new degenerate kernel states: -the interview proposes a shape (one line per pattern — for example, an -own-observation source class recorded with a retrieval date), and the adopter -instantiates it with their own content. Patterns are shapes, never copied -answers, and none reads as an exemption from kernel behavior: a profile with -a minimal source table remains fully bound by K07. Residual-scan -configuration is deliberately excluded from static defaults: the production -scan requires the repository to contain at least one file the matchers -recognise, so scan parameters are derived from corpus inspection — or, on an -empty corpus, declared and then materialized by the first batch — and -confirmed by the operator instead. - -One kernel absorption is already decided: `last_verified` becomes conditional -on `volatility: fast` in the K08 applicability base, promoting a field-proven -adopter tightening into the kernel default. The originating profile removes -its now-redundant difference row when adopting the revised standard. - -### Interview Contract - -Each decision that remains open in the template carries -machine-readable question metadata — question, answer shape, validation, -target slot and field, and trigger — embedded alongside the placeholder. Any -agent can conduct the interview, project confirmed answers into the canonical -profile files, and validate with `check_profile.py`. Questions are layered: a -core pack collected at adoption, whose membership is chosen by change cost -(decisions that are migration-grade to reverse — body language, layer -directories, identity — are always asked and never defaulted), and per-slot -expansion packs opened either electively or when a fail-closed gate names the -slot a task needs. Deepening a profile later flows through ordinary Standards -adoption and does not interrupt an active task. - -An onboarding assistant, where provided, is one execution mode of the -interview contract, not a second profile interface. Whatever conducts the -interview must produce only a candidate: it must not infer unconfirmed domain -policy, copy example answers as defaults, write the active K00 state, approve -the profile, or bypass R09. It should support both an existing corpus and a -corpus built from zero, show the resulting diff and unresolved decisions -before writing, and report structural failures in user-facing terms. - -## Reference Execution Runtime - -Implement the existing batch protocol as a host-neutral reference runtime. -The runtime consumes the existing `.cambium/state/required_queue.yaml`; it does -not create a parallel scheduler-owned batch ledger. - -### Assignment State - -Track the mapping between durable work and temporary execution contexts: - -- `batch_id`; -- `execution_context_id` and optional parent context; -- role (`integrator`, `writer`, `reviewer`, or `researcher`); -- permitted write scope; -- runtime status and handoff checkpoint; -- the Card Activation Bundle and ordered Read-back Addendum delivery chain - injected into that execution context. - -Batch identity must survive an agent interruption or reassignment. Agent and -subagent topology remains runtime metadata rather than profile configuration. -No assignment enters `running` until its host adapter has delivered the exact -Bundle bound by Queue admission. Resume and reassignment inject it again into -the new context; a manual or unbound CLI attestation is degraded and cannot -claim this capability. - -Where the host allows, a role's permitted write scope is enforced -structurally rather than only recorded: each role receives an operation -surface containing only its permitted operations, so a worker's surface has -no integrator transition and a clean-context reviewer's surface exposes only -review inputs and verdict submission. Interface scoping is defence in depth -against misoperation, not authentication; the evidence trust boundary is -unchanged. - -### Integrator Loop - -Implement the single-writer control path before automating parallel workers: - -- admit only dependency-ready batches with disjoint manifests; -- consume Queue readiness, use the integrator-only transition tool for batch - activation, deliver its exact Card Bundle before dispatch, and own guidance - disposition without bypassing canonical state; -- collect each batch's receipts and delta; -- merge one batch at a time and run the global checks after each merge; -- checkpoint, pause, resume, and reassign interrupted work safely. - -### Parallel Workers And Independent Review - -Add isolated worker execution after the integrator loop is reliable: - -- one write owner for each active batch; -- isolated workspaces and batch-private receipt/delta locations; -- parallel research and deterministic checks where they do not create shared - writes; -- clean-context reviewers for L-tier substantive correctness review; -- explicit escalation when dependencies, review rounds, or merge checks do not - converge. - -The active-batch cap remains separate from the number of agent contexts. - -### Host Adapters - -Map the reference runtime onto concrete environments without making any one -host part of the kernel. An adapter may provide agent creation, workspace -isolation, cancellation, event delivery, and context identifiers. It must -declare unsupported capabilities and fall back safely rather than simulating -evidence it cannot produce. - -The bundled stdio MCP interface already supplies the host-neutral primitive: -one session identity, exact Card Bundle tool results, and content-addressed -Read-back Addenda. Adapters reuse that primitive; they do not reparse Card -prose or invent a parallel reading ledger. - -## Operation Capability Registry - -Make the kernel's implicit "which controlled operations are permitted in -which runtime state" knowledge an explicit kernel asset. Today that mapping -exists only as the `next_action` derivation inside -`check_queue.py --resume-status` and as prose distributed across the -standards; no single artifact owns it. - -- A restricted-YAML registry maps each task and batch state to the permitted - controlled operations, the writer tool that owns each operation, its - required parameters, and the receipt or gate evidence it consumes. -- The registry follows the existing compose/check idiom (vocabulary, page - contract, Card stamping): a deterministic checker verifies that the - registry, each tool's declared CLI contract, and the kernel's transition - rules agree, and fails closed on drift. -- The registry is the single generation source for any adapter's closed - operation surface, including the MCP surface below and capability - discovery responses. An adapter must not maintain an independent - hand-written operation list. -- `--resume-status` `next_action` output must agree with the registry; the - registry makes that vocabulary canonical rather than replacing the - derivation. - -This is standards-layer work and precedes the adapter surfaces generated -from it. The kernel leaf that owns the registry passes the normal admission, -size-budget, and Read Set registration requirements, and reaches an active -task only through Standards adoption. - -## OpenAI Plugin Host Adapter - -Implement a single `cambium` OpenAI Plugin as the first concrete Cambium host -adapter and distribution surface. This capability is planned and is not -currently shipped. The Plugin may package Skills, a local MCP adapter, and -generated release resources, but it is not a new normative layer. The kernel, -exactly one selected Profile, and the target repository's `.cambium/` state -remain authoritative. - -The host-neutral half of this capability has since shipped separately, and it -changes what remains here. Cambium is now callable from Claude Code, Codex, -Kimi Code, and dsh through generated per-host configuration; the operation -surface those hosts see is a build-time projection of the compiled CLI -contract, not a hand-listed one. Several boundaries stated below are therefore -already held by that interface rather than pending: the MCP surface is a closed -set of typed operations with no arbitrary command runner and no second -state-writing implementation, and registration is explicitly not adoption. -What a Plugin would still add is packaging and distribution — a manifest, -Skills, Hooks, and a marketplace entry — not the call surface itself. - -One measured constraint belongs on the record. The Agent Plugins shell cannot -determine which corpus a session governs at handshake: it declares no roots, it -resolves an omitted `cwd` to the plugin resource root rather than the session -workdir (the native dialect and `config.toml` resolve to the workdir), and it -rejects `env_vars` whitelist forwarding. All three channels were tested. A -per-corpus binding and that shell are not simultaneously available, so Codex is -registered through its project-level `.codex/config.toml` instead. A Plugin -release that wants per-corpus governance must first close that gap upstream or -carry the binding some other way; it cannot be assumed. - -OpenAI currently documents Plugins as an installable package that may combine -Skills, MCP servers, Hooks, and assets. Its package contract is an evolving -product contract rather than a versioned Cambium dependency. Every Cambium -Plugin release must therefore be checked against the current +| **Complete** | Shipped in the repository and documented for use | +| **In progress** | Active implementation work; not available until the complete change lands | +| **Next** | Intended next capability with a defined boundary and completion test | +| **Conditional** | Built only if its trigger occurs or a separate product decision is made | + +The current user-facing capability summary lives in [README.md](README.md). +This file records what changes next and why. + +## Status At A Glance + +| Capability | State | Short version | +|---|---|---| +| Profile onboarding reform | Complete | One pre-closed template, scaffolder, interview contract, status view, checks, and end-to-end tests ship | +| Persistent task and Queue runtime | Complete | Coverage, Required Queue, Progress, controlled writers, receipts, recovery, and closure paths ship | +| Workflow progression MVP | Complete | Exact candidate carry, bounded delegated Amendments, and routed-gap settlement ship | +| Host-neutral agent interface | Complete | CLI contract, MCP projection, stdio server, and four host renderers ship | +| Activation transport and Assignment delivery | In progress | Replace an unprovable “server sent it” claim with budgeted delivery, host conformance, acknowledgements, and a delivery gate | +| Reference execution runtime | Next | Add durable Assignment state, a single-writer integrator loop, then isolated workers and reviewers | +| State-aware operation discovery | Next | Its scope has changed: the shipped MCP surface comes from tool CLIs, and any future discovery view must not become a second policy engine | +| Typed dependency runtime | Next | Compile explicit corpus relationships and produce bounded change-impact plans | +| Independent completeness and consistency evaluation | Next | Re-derive expected scope without trusting the executor's own Queue or Delta | +| Machine-readable review rulings | Next | Make finding, confirmation, conditional fix, and close-gate evidence one load-bearing chain | +| Receipt ledger integrity chain | Next | Add linked receipt history with an external tail anchor and era-aware replay | +| Observability and broader Contract Amendments | Next | Runtime status and two amendment fields ship; orchestration views and additional contract fields remain | +| OpenAI Plugin packaging | Conditional | Consider only after per-corpus binding and package lifecycle requirements are solved | +| Detached state transactions | Conditional | Needed only when an authoritative writer cannot finish on its normal execution channel | +| Concurrent receipt sealing | Conditional | Needed only if Cambium expands beyond the current single-writer maintenance window | +| Sealed-evidence follow-ups | Next | The reported reachability defect is fixed; protected-set derivation, rehydration, and declared projections remain | + +## Authority Boundaries That Do Not Change + +Every roadmap item must preserve the same control plane: + +```text +authority + = Cambium kernel + + exactly one selected Profile + + adopter-owned .cambium state +``` + +Convenience layers may collect decisions, render views, or call controlled +operations. They may not: + +- invent domain policy or approve a Profile; +- weaken a kernel gate or bypass R09 Standards adoption; +- create a second Queue, Progress ledger, or receipt authority; +- expose an arbitrary shell runner or unrestricted repository paths; +- run adopter-provided verifier code without explicit authorization; +- claim authenticated identity, isolation, independent review, or delivery + without evidence from the host that provides it. + +## Complete Foundations + +These items used to be future roadmap work. They are now part of the current +baseline and remain here only to make the transition visible. + +### Profile Onboarding Reform + +Cambium now ships one template rather than “minimal” and “full” template +families. The template pre-closes switches that have a safe legal exit state +and leaves repository-specific decisions open. + +The shipped flow includes: + +- `profiles/template-files.yaml` as the exact-copy whitelist; +- `Tools/scaffold_profile.py` for safe candidate creation; +- `profiles/interview.yaml` as the machine-readable question contract; +- `Tools/profile_onboarding_status.py` as a read-only state and `next_action` + view; +- `Tools/check_profile.py` for structural and dependency validation; +- end-to-end fixtures for existing and empty corpora. + +An assisting agent may prepare a candidate. It may not approve the Profile, +select it, or infer unconfirmed domain policy. + +The former target of “at most 15 operator decisions in 30 minutes” is now a +product-experience measurement, not an implementation claim. It remains +unproven until measured with real adopters. An automated interview runner is a +possible convenience layer, not a missing governance mechanism. + +### Persistent Runtime And Workflow Progression + +The adopter-owned runtime now separates: + +- object state in Coverage; +- batch state in the Required Queue; +- whole-task state in Progress; +- complex-batch instructions in immutable Work Specs; +- proposed changes in Deltas and controlled plans; +- append-only evidence in receipts. + +Three workflow debts are also closed: + +1. `exact-carry-v1` reuses only the review disposition of an exact unchanged + observation from the immediately previous successful close. +2. `amendment_authority` can delegate only registered bounded operational + change classes; delegation cannot expand itself. +3. Every gap routed to a batch must be settled or rerouted before that batch + reaches `merge-ready`. + +These mechanisms reuse the existing ledgers and writers. They do not create a +parallel control plane. + +### Host-neutral Agent Interface + +The host-neutral interface is complete: + +```text +each tool's argparse declaration + -> Tools/compiled/cli-contract.yaml + -> Tools/compiled/mcp-tools.json + -> Tools/mcp_server.py + -> generated host configuration +``` + +Claude Code, Codex, Kimi Code, and dsh consume generated registration and +workspace binding. The MCP server runs tools as subprocesses and passes their +verdicts through. It does not decide whether an operation is allowed or whether +evidence is sufficient. + +This delivery changed the Plugin plan: Cambium no longer needs an OpenAI Plugin +to obtain a callable agent interface. A Plugin would add packaging and +distribution only. + +### Sealed Evidence Reachability Fix + +Receipt sealing now preserves the evidence a recorded Queue transition +consumed, resolves the required body from verified cold storage, and fails +closed when evidence exists in neither hot nor cold storage. + +That closes the reported defect where sealing could silently reopen an already +discharged obligation. The broader follow-ups are listed under +[Sealed-evidence Hardening](#sealed-evidence-hardening). + +## In Progress + +### Activation Transport And Assignment Delivery + +**State: In progress; not shipped until the complete standards, tools, +generated artifacts, and tests land together.** + +The original activation protocol treated a server result delivered to an MCP +session as proof that the model context received the complete Card bundle. A +real host measurement showed that an oversized result could be externalized +while the receipt still claimed machine delivery. The server could prove what +it sent, but not what the host placed in context. + +The replacement design separates four facts: + +1. Queue admission freezes the exact Card and startup Read Set manifest. +2. Content travels one complete file at a time under a measured result-size + budget. +3. The receiving execution context returns a nonce for each delivered piece. +4. A current Host Adapter conformance record proves that a within-budget result + is delivered inline rather than truncated or externalized. + +An Assignment then moves through: + +```text +pending -> delivering -> delivered -> running +``` + +Only the Assignment delivery gate may authorize `running`. Queue `open` still +means the batch is admitted; it does not mean a worker has received its Cards. + +Delivery evidence is bound to one Assignment, one execution context, one +Bundle, and one attempt. Reassignment or Profile/Bundle change requires +delivery again. Even a valid `delivered` state proves delivery, not that the +agent read, understood, or obeyed the material. + +This item is complete when: + +- the piece budget is derived from reproducible positive and negative host + measurements; +- oversized leaves fail during admission rather than mid-delivery; +- every piece is hash-bound, delivered, and acknowledged in one context; +- a versioned Host Adapter conformance record is current; +- a durable Assignment writer and gate consume the complete acknowledgement + set; +- resume and reassignment invalidate old delivery evidence; +- unsupported hosts fall back to an explicit degraded state; +- the generated CLI/MCP artifacts and negative fixtures agree with the new + protocol. + +## Next Capabilities + +### Reference Execution Runtime + +Cambium defines batch lifecycle and serial integration, but does not yet run +agents. The reference runtime will consume the existing Required Queue rather +than inventing a scheduler-owned ledger. + +Delivery order: + +1. **Durable Assignment state** — map one admitted batch to one temporary + execution context, role, write scope, delivery attempt, and checkpoint. +2. **Single-writer integrator loop** — admit ready disjoint batches, collect + Deltas and receipts, merge one batch at a time, and run global checks after + each merge. +3. **Isolated workers** — one write owner per active batch with batch-private + outputs. +4. **Clean-context reviewers** — receive only the review inputs required by + the governing review contract. +5. **Recovery and observability** — cancellation, interruption, reassignment, + conflict, timeout, and handoff diagnostics. + +The active-batch limit remains separate from the number of agent contexts. +Host adapters must declare unsupported isolation, cancellation, identity, or +filesystem capabilities and fall back safely. + +This capability is complete when parallel disjoint work is replayable, shared +integration remains serial, interrupted work resumes from durable state, and +no actor, reviewer, delivery, or isolation claim exceeds Host evidence. + +### State-aware Operation Discovery + +The earlier roadmap proposed one Operation Capability Registry as the source of +the MCP tool list. Delivery proved that two different questions were being +mixed: + +- **What can this distribution call?** The shipped compiled CLI contract owns + this answer. +- **What may this state do next?** Kernel rules and each controlled tool own + this answer; `check_queue --resume-status` projects `next_action`. + +The existing `Tools/operation-capabilities.yaml` has a narrower job: it binds +metadata fields and transitions to installed writers, consumers, producers, +and receipt schemas. K00/12 separately owns Gate capability and revalidation +mapping. Neither is a universal task-state permission table. + +A future capability-discovery view is justified only if a runtime needs one. +If built, it must compose the compiled CLI contract with current state and +return an explainable permitted-operation set. It must not hand-list tools, +replace a writer's validation, or become a second transition authority. + +This item is no longer a prerequisite for the MCP surface or Plugin packaging. + +### Typed Dependency Runtime + +Cambium already validates explicit Corpus Planning inputs and Profile +dependency closure. The missing capability is a host-independent compiler for +corpus relationships and change impact. + +Eligible inputs include explicit Global Map dependencies, Capability and Gap +links, frontmatter prerequisites, canonical-to-derived bindings, source and +claim bindings, MOC membership, schemas, Profiles, Standards, and registered +relationship extensions. + +The compiler will produce a deterministic graph. Every edge must name: + +- the dependency and dependent object; +- the relationship type and invalidation policy; +- the declaration that authorized the edge. + +A change-impact planner will compare accepted and candidate snapshots, explain +which edge caused each affected object, name the invalidated quality dimension, +and identify the required check or review. + +Raw backlinks and semantic similarity are discovery inputs, not dependency +authority. The runtime must not rewrite content, promote status, perform +unbounded review, or declare completion. + +This capability is complete when identical inputs produce byte-identical +graphs, every declared edge resolves or has an authorized disposition, direct +impact is complete and explainable, ordinary navigation links do not trigger +invalidation, and plain-filesystem and host-backed fixtures produce equivalent +semantics. + +### Independent Completeness And Consistency Evaluation + +Current gates prove that declared Coverage, Queue, Delta, receipt, and snapshot +state agree. They do not independently prove that the declarations cover the +whole expected corpus. + +The new evaluator will first derive the expected set from upstream accepted +inputs such as the Task Contract, Profile scope, Corpus Planning artifacts, +repository snapshots, accepted Amendments, and the typed dependency graph. It +will then compare that set with Coverage, Queue manifests, Deltas, changed +files, invalidations, and receipts. + +It must not use the executor's Queue, Delta, changed-file list, or completion +claim as the authority for what should exist. + +The same read-only boundary will perform bounded cross-document checks for +conflicting definitions, defaults, thresholds, ownership, mechanisms, and +stale downstream conclusions. Deterministic comparisons run first; semantic +review is limited to explicit concept groups and returns the exact passages and +rationale. + +This capability is complete when an internally consistent but incomplete half +of the true expected set fails, missing or ambiguous inputs cannot pass, empty +scope needs an independently verifiable predicate, and the evaluator cannot +modify state or approve its own findings. + +### Machine-readable Review Rulings + +Batch Review Requirements and judgment receipts now provide a machine-readable +batch-level foundation. K12/12 substantive review findings and confirmation +rulings are still prose. + +The load-bearing sequence must be: + +1. A review context writes stable finding IDs, grade, target, and judged bytes. +2. A distinct confirmation context writes one verdict per finding. +3. A conditional-fix writer resolves that verdict, checks the pre-image, applies + the literal bounded patch under lock, and writes a receipt. +4. The batch-close gate refuses an unresolved or unexecuted conditional finding. + +Until the first producer exists, a second-round `not-closed` result escalates. +An executor-created field that no independent producer writes and no close gate +consumes would not solve the problem. + +### Receipt Ledger Integrity Chain + +Receipts are append-only JSONL and many authorizing fields are already +cross-bound to state, plans, or anchors. A remaining structural class has only +one durable carrier and therefore cannot prove its own historical value. + +The planned integrity layer adds: + +- `prev_receipt_sha256` on each receipt in a chained producer era; +- a declared genesis value for the first line; +- an external tail anchor written into the canonical state transaction that + appended the receipt; +- producer-era replay so pre-chain receipts remain valid under their original + rules; +- fail-closed uncertain-tail and broken-suffix recovery. + +A chain without an external anchor is insufficient because a writer could +rebuild the whole file. This feature adds forensic integrity; it does not grant +new authority or defend against an adversary who can rewrite state, tools, +plans, and evidence together. + +### Observability And Contract Amendments + +State-level observability already ships through `check_queue --resume-status` +and derived Queue reports. The reference runtime still needs views for +Assignments, agent contexts, delivery attempts, conflicts, cancellation, +timeouts, and handoffs. + +The guarded Contract Amendment writer currently supports: + +- `policy_exceptions`; +- `amendment_authority`. + +Objective, exclusions, acceptance, timing, and pause policy still require a +successor task. Each field may gain a guarded transaction only with an explicit +authority rule, complete before/after binding, lock-time revalidation, recovery, +and consumer tests. A generic arbitrary Contract diff is not a goal. + +### Sealed-evidence Hardening + +The original hot-to-cold reachability defect is fixed. Three broader debts +remain: + +1. The protected hot-reference set is still enumerated by hand rather than + derived from consumers. +2. No sanctioned rehydration path moves a required cold row back to hot state. +3. The cold projection schema is fixed instead of being declared by consumers. + +These are bounded follow-ups. They must extend the existing verified hot/cold +catalog rather than introduce a second receipt store. + +## Conditional Extensions + +### OpenAI Plugin Packaging + +Cambium already works through generated MCP configuration. An OpenAI Plugin is +therefore an optional packaging and distribution layer, not part of Cambium +Core or the reference runtime. + +The measured Agent Plugins shell cannot currently establish the adopter's +per-corpus workspace binding at handshake: it exposes no roots, an omitted +working directory resolves to the Plugin resource root, and environment +whitelist forwarding is unavailable. Codex therefore uses project-level +`.codex/config.toml` today. + +Plugin work should resume only when that binding is solved upstream or another +explicit, tested carrier exists. If resumed, the first package should contain +one `cambium` Plugin with small `adopt`, `operate`, and `audit` Skills over the +existing host-neutral interface. + +Required boundaries: + +- install, update, downgrade, or removal never changes adopter-owned Standards, + Profile, task state, or receipts; +- Plugin cache stores only disposable preferences, indexes, and caches; +- no arbitrary command runner or unrestricted path access; +- adoption produces a candidate and diff, never automatic approval; +- repository-provided verifiers require disclosed, explicit authorization; +- package contents are generated from canonical sources with correct + per-path licensing and attribution. + +Before any release, validate against the current [OpenAI Plugins documentation](https://developers.openai.com/plugins) and [builder contract](https://developers.openai.com/plugins/build/plugins), then -tested through real installation and ingestion. - -### Architecture And Authority Boundary - -The adapter must preserve these boundaries: - -- Plugin installation or enablement is not Cambium adoption, activation, or - Profile approval. -- Plugin reinstall, upgrade, downgrade, or removal must not migrate, replace, - or delete an adopter's active Standard, selected Profile, task state, or - receipt history. -- Kernel or Profile changes continue through the explicit Standards-adoption - path and may not bypass R09. -- `plugin_resource_root`, `workspace_root`, and `state_root` are distinct - capabilities. Plugin cache or `PLUGIN_DATA` may contain disposable caches, - preferences, and indexes only. -- The adopter repository owns the adopted governance snapshot and canonical - `.cambium/` Coverage, Queue, Progress, Work Specs, receipts, and evidence. -- Skills describe workflows, decision points, and user interaction. They do - not enforce invariants, own normative rules, or prove conformance. -- MCP exposes a closed set of typed, high-level Core operations. It must not - expose an arbitrary command runner, unrestricted path access, or a second - state-writing implementation. -- The adapter consumes the canonical Required Queue. It must not create a - scheduler-owned task or batch ledger in Plugin state. -- A generic adoption mode may inspect a repository and produce a candidate - Profile when no Profile is selected. Runtime operations require exactly one - selected and validated Profile. -- Hooks are optional defence-in-depth interaction controls. They require user - trust and are neither protocol authority nor audit evidence. -- Repository-provided Profile verifiers are not executed automatically. Their - source, requested capability, and effect must be disclosed and explicitly - authorized, with allowlisting or isolation where applicable. -- Host-provided actor names, reviewer labels, or context identifiers do not by - themselves prove authenticated execution or independent review. -- Plugin release artifacts are generated from canonical Core and adapter - sources. Normative files are not maintained as independent manual copies - inside the package. - -An adapter must declare missing filesystem, isolation, cancellation, identity, -or controlled-writer capabilities and fail safely. It must not fabricate the -evidence that an unavailable Host capability would have produced. - -### Initial Package Shape - -The first release candidate should contain one `cambium` Plugin rather than a -suite of interdependent Plugins. Its source and generated artifact should be -separate so that package construction cannot silently fork the Core: +test real installation, new-task loading, upgrade, rollback, and removal. + +Public marketplace distribution, remote MCP, UI, and Workspace sharing remain +later product decisions. They do not define completion of the host-neutral +runtime. + +### Detached State Transactions + +This protocol is needed only if the authoritative execution channel cannot +allow a state writer to finish. + +The safe design is: + +1. `detached prepare` locks the real authoritative namespace and records the + complete before-image, including state files, receipt tails, pending Deltas, + archive moves, and locks. +2. Another environment computes against exactly that before-image. +3. `detached commit` rechecks the full before-image under the still-held real + lock, appends only new receipt bytes, and installs the explicit after-image. +4. Any drift aborts and follows normal recovery. + +Copying state out, computing elsewhere, and copying it back with only three +state-file hashes is not a reusable protocol. It does not protect the +authoritative receipt frontier or concurrent namespace changes. + +### Concurrent Receipt Sealing + +Current receipt sealing deliberately requires a maintenance window with one +writer. The append mutex catches ordinary competing appenders but does not +claim cross-host, adversarial, or fully concurrent exclusion. + +A true concurrent version is required only if Cambium chooses to widen that +boundary. It would need a shared epoch or cutover protocol that every appender +participates in, explicit exclusion invariants, cross-host recovery, and tests +with real racing writers. + +This is not incremental hardening of the current marker. Until the product +boundary changes, the single-writer maintenance window remains the supported +contract. + +## Adjusted Or Retired Directions + +The following older directions should not be revived without a new decision: + +- **Plugin-first delivery.** The host-neutral CLI/MCP interface shipped first; + Plugin work is now optional packaging. +- **One universal Operation Capability Registry as the MCP source.** The CLI + contract owns callable shape; state permission remains with kernel rules and + controlled tools. +- **Two Profile template depths.** One pre-closed template plus interview + expansion packs is the supported design. +- **A scheduler-owned batch ledger.** The Required Queue remains the only + canonical batch lifecycle. +- **Queue admission as proof of worker delivery.** Admission and Assignment + delivery are separate facts. +- **Automatic execution of adopter verifiers.** Verifier code stays disclosed + and explicitly authorized. +- **Prompt behavior as conformance evidence.** Skills and prompts guide use; + gates, writers, receipts, and host evidence carry claims. + +## Delivery Order + +The current critical path is: ```text -adapters/openai-plugin/ # adapter source - mcp_server/ - skills/ - tests/ -packaging/ # reproducible package builder -dist/plugins/cambium/ # generated installable artifact - .codex-plugin/plugin.json - skills/ - .mcp.json - assets/ -.agents/plugins/marketplace.json # repository distribution metadata +activation transport assurance + -> durable Assignment state and delivery gate + -> single-writer integrator loop + -> isolated workers + -> clean-context reviewers + -> cancellation, reassignment, and orchestration observability ``` -New adapter and distribution paths require an explicit licensing and -attribution decision. A Plugin bundle that contains differently licensed -Tools, standards, documentation, or examples must retain the applicable -per-path notices rather than collapsing them into an inaccurate package-wide -claim. - -The initial interaction surface should remain small: - -- `adopt`: inspect the repository, execute the interview contract's question - packs to collect operator-confirmed decisions, produce a candidate Profile - and diff, and run structural validation without selecting or approving the - Profile; -- `operate`: inspect or resume existing state, explain the deterministic next - action, and route any later write through a controlled Core transaction; -- `audit`: inspect receipts, invalidations, batch-close evidence, and Terminal - Proof while distinguishing deterministic results, semantic judgment, - candidate findings, and unavailable evidence. - -The first MCP adapter is local and read-only. Candidate operations include -capability discovery (the state-dependent permitted-operation set generated -from the Operation Capability Registry), workspace inspection, Profile -validation, resume status, Queue validation, receipt inspection, audit -preview, and Terminal Proof verification. UI, remote -repository access, automatic agent dispatch, and public-directory distribution -remain deferred. - -### Phase 0 — Core And Packaging Stabilization - -Prepare Cambium for adapter use without changing kernel or Profile semantics: - -- extract a stable, typed Core API from repository-layout-dependent scripts; -- ship per-tool `--json` output as the first increment of that Core API: - each tool derives its human-readable text and its JSON from one internal - result object, replaces overloaded exit-code meanings with enumerated - error codes, and declares an output schema covered by tests; a second - rendering path is a defect, and receipts remain the evidence of record - while `--json` remains a projection; -- normalize filesystem roots and path aliases across supported platforms; -- separate Plugin resources, target workspace, and canonical state; -- define Plugin, protocol, receipt, and minimum-Core compatibility; -- add platform CI and conformance fixtures for empty scans, path aliases, - symlinks, hardlinks, stale revisions, concurrent writers, and interrupted - writes; -- define generated-package, attribution, upgrade, rollback, and support rules. - -Exit requires the complete supported test matrix and negative fixtures to -pass, a documented compatibility contract, and no critical verifier depending -on an ambiguous repository-relative `Tools/` root. - -### Phase 1 — Read-only Private Alpha - -Validate Plugin discovery and interaction without accepting write risk: - -- package the three Skills and a read-only local MCP adapter; -- support workspace inspection, Profile validation, existing-state resume, - status explanation, and audit explanation; -- distribute through a local or repository marketplace; -- omit Hooks, UI, remote MCP, and automatic agent dispatch. - -Exit requires successful manifest validation, real installation and new-task -loading, positive and negative Skill activation tests, zero target-state -mutation, and proof that reinstall or upgrade leaves canonical state -unchanged. - -### Phase 2 — Guarded Local Beta - -Add writes only through Core transactions: - -- expose explicit dry-run and apply operations; a dry-run response returns - the complete apply envelope, including the exact expected revisions and - SHAs it read, so a caller replays it rather than re-transcribing - parameters; -- require exact workspace roots, expected revisions, locks, receipts, and - interruption recovery; -- support candidate Profile onboarding and the bounded - initialize/compile/transition/apply/close/complete lifecycle; -- preserve single-writer integration and explicit user authority. - -Exit requires successful clean adoption, existing-state resume, interrupted -writer recovery, build and maintenance completion paths, and fail-closed tests -for stale revisions, path escape, prompt injection, unauthorized verifier -execution, and arbitrary-command input. Uninstall or reinstall must not lose -target state. - -### Phase 3 — Codex Execution Adapter - -Implement the execution capabilities defined by the Reference Execution -Runtime, in this order: - -1. durable assignment state; -2. the single-writer integrator loop; -3. isolated workers; -4. clean-context reviewers; -5. cancellation, interruption, reassignment, and observability. - -Exit requires replayable parallel batch work with serial integration, explicit -safe failure for unsupported Host capabilities, and evidence-backed actor and -reviewer claims. An inherited-context agent must not be represented as an -independent reviewer. - -### Phase 4 — Workspace And Ecosystem Distribution - -Only after the Core API, compatibility model, and permission boundary are -stable, evaluate: - -- Workspace sharing; -- host-specific source and event connectors; -- a read-only observer or status UI; -- a public Skills-only educational package that makes no conformance claim; -- remote MCP and Universal Plugin Directory submission. - -A connector may contribute source, event, or authenticated identity evidence. -It must not become Profile authority, dependency policy, semantic ownership, -or completion authority. Public remote MCP remains blocked until the local -repository data path, authorization, retention, and threat model are complete. - -### Release Gates - -- **G0 — Current Plugin contract:** validate against current official - documentation and real ingestion; test manifest, MCP, Hooks, cache, new-task, - upgrade, and rollback behavior; do not claim a frozen Plugin "v1". -- **G1 — Protocol and Core:** all supported tests and negative fixtures pass; - plain-filesystem and Host-adapter fixtures produce equivalent Cambium - semantics. -- **G2 — Plugin archive:** install, reinstall, upgrade, and new-task loading - pass; package resources are complete; Plugin lifecycle cannot migrate active - Cambium state. -- **G3 — Adapter E2E:** adoption, resume, interrupted-write recovery, batch - integration, Terminal Proof, maintenance completion, Standards adoption, and - uninstall/reinstall persistence pass. -- **G4 — Security and trust:** no arbitrary-command surface; exact workspace - capabilities; prompt-injection and path-escape coverage; no credentials in - logs or receipts; accurate tool side-effect annotations; no actor, reviewer, - or isolation claim without Host evidence. -- **G5 — Public distribution:** immutable release, support matrix, changelog, - migration guide, conformance bundle, licensing and attribution review, - security and privacy policies, sufficient positive and negative tool cases, - and a closed local-repository or remote-MCP data architecture. - -### Non-goals - -This roadmap item does not: - -- rewrite Cambium as one large Skill or prompt; -- make Plugin files, cache, or a remote service the owner of the active - Standard or canonical state; -- let Plugin updates silently migrate the kernel, Profile, or an active task; -- claim Cambium conformance from prompt-level behavior; -- provide an arbitrary shell-command MCP tool; -- make UI or Hooks part of the trust boundary; -- auto-execute adopter-controlled verifier code; -- bundle automatic agent dispatch before the Reference Execution Runtime is - implemented; -- claim authenticated actors, independent review, or workspace isolation - without corresponding Host evidence; -- require remote MCP or Universal Directory publication for the local MVP; -- split Cambium into multiple dependent Plugins before the single-adapter API - and upgrade model are stable. - -## Typed Dependency Runtime - -Turn the kernel's existing dependency, invalidation, and downstream re-review -semantics into a host-independent executable projection. This runtime is an -implementation of current governance rules, not a new source of dependency -policy and not a requirement that every knowledge link become an invalidation -edge. - -### Compiled Dependency Model - -Compile explicit relationship sources into a normalized typed dependency -graph. Eligible inputs include: - -- the configured Global Map's explicit typed dependencies; -- the Capability Matrix's explicit capability priorities, canonical paths, - evidence, and Gap IDs; -- the Gap Register's explicit capability links and promoted Coverage paths; -- frontmatter `prerequisites`; -- canonical-to-derived-artifact bindings; -- source and supported-claim bindings; -- registered MOC or collection membership; -- schema, profile, and Standards contract bindings; -- profile-registered relationship extensions that do not redefine kernel - semantics. - -Each normalized edge identifies the dependency, the dependent object, the -relationship type, its invalidation policy, and the declaration from which the -edge was compiled. The generated graph is a deterministic artifact. Knowledge -pages, profiles, registries, and ledgers remain authoritative, and rebuilding -the graph from the same accepted inputs must produce the same result. - -Raw backlinks are discovery input, not dependency authority. A wiki link may -mean prerequisite, ownership, evidence, comparison, alternative, application, -or navigation. Only an explicit kernel relationship or profile-registered -extension participates in automatic semantic propagation. This prevents a -popular navigation target from invalidating every page that merely mentions -it. - -### Change-impact Planning - -Compare the latest accepted snapshot with the current candidate snapshot and -classify changes to content, paths, headings, aliases, governed metadata, -canonical ownership, evidence, schemas, profiles, or Standards contracts. -Resolve the directly affected dependents through the compiled graph and emit -an explainable impact plan containing: - -- the changed object and change kind; -- the dependency edge that caused propagation; -- the affected object; -- the invalidated quality dimension; -- the required deterministic check or semantic review; -- the evidence needed to close or reuse the affected receipt. - -The impact plan must integrate with the existing AuditPlan, Coverage Delta, -`needs_rereview` candidate pool, and AuditReceipt reconciliation contracts. It -discovers and plans affected work; it does not edit knowledge pages or write -the canonical ledgers directly. - -Propagation remains bounded. Direct dependents are the default affected set. -Further expansion requires a registered transitive relationship, an observed -systemic failure, or explicit task authority. A local change must not trigger -an unconditional full-corpus LLM review, while a declared dependency must not -be ignored merely to reduce review cost. - -### Host Independence - -The core compiler and impact planner must operate on ordinary Markdown, YAML -frontmatter, profiles, registries, ledgers, and receipts without requiring -Obsidian or another knowledge host. - -A host adapter may contribute wiki-link extraction, backlinks, rename events, -or host-specific identities. It must normalize them into the same dependency -model and must not make host configuration an authority for semantic edges. -In particular, the runtime must not depend on Obsidian Graph View state or -`.obsidian/graph.json`. A plain filesystem corpus and a host-backed corpus with -equivalent declarations must compile to equivalent normalized relationships. - -### Runtime Boundary - -The Typed Dependency Runtime may compile relationships, detect changes, -validate declared targets, produce affected sets, and emit receipts. It must -not: - -- infer an unconfirmed domain dependency from semantic similarity alone; -- treat every backlink as a dependency; -- rewrite affected content automatically; -- promote authoring, evidence, learning, or expression-readiness status; -- bypass AuditPlan, Coverage Delta, or integrator authority; -- perform unbounded transitive review; -- declare batch or task completion. - -This roadmap item is limited to note- and governed-object-level dependencies. -Inline or block-level dependency markup is outside its scope. - -### Acceptance - -The capability is complete only when: - -1. identical accepted inputs produce a byte-identical normalized graph; -2. every declared dependency resolves or carries an explicit future, deferred, - retired, or otherwise profile-authorized disposition; -3. an upstream change finds every directly affected dependent and explains - each propagation path; -4. ordinary comparison, alternative, and navigation links do not trigger - semantic invalidation; -5. path, heading, alias, content, evidence, and contract changes invalidate - only their applicable dimensions; -6. the output can be consumed by existing AuditPlan and Coverage Delta flows; -7. empty scans, malformed declarations, and missing required inputs fail - closed; -8. the runtime never modifies knowledge content while calculating impact; -9. bounded propagation and receipt reuse remain consistent with the kernel; -10. the conformance suite passes against both a plain Markdown fixture and a - host-adapter fixture without host-specific semantic differences. - -## Independent Completeness And Consistency Evaluation - -Add a read-only evaluation boundary that does not let the execution plan grade -its own completeness. Existing gates remain authoritative for the consistency -of declared Coverage, Queue, Delta, receipt, and snapshot state. This evaluator -addresses the different question of whether those declarations describe the -whole expected scope and impact set. - -### Independent Expected-set Re-derivation - -At initial inventory, applicable batch close, and Terminal Audit, independently -derive the expected set from upstream accepted inputs. Eligible authorities -include the frozen Task Contract, selected Profile Scope and exclusions, -accepted Global Map, Capability Matrix and Gap Register, baseline and candidate -repository snapshots, accepted Guidance and Amendments, and the compiled typed -dependency projection. - -The re-derivation pass must not use the worker's Queue manifest, Delta, changed -file list, completion claim, or self-authored rationale as the authority for -what should be in scope. It may read those artifacts only after deriving the -expected set, in order to compare: - -- the independently discovered in-scope corpus with Coverage inventory records; -- the independently derived affected set with planned Queue manifests; -- the planned manifest with the actual Delta and changed-file set; -- the affected set with current review, invalidation, and receipt coverage. - -The result reports exact missing, unexpected, deferred, excluded, and -unresolved members. Set disagreement cannot be collapsed into a passing count, -and a zero-member result is not a pass unless an independently verifiable empty -scope predicate applies. When the accepted inputs are insufficient to derive a -member or disposition, the evaluator fails closed or raises an explicit -adjudication candidate rather than silently accepting the executor's choice. - -### Cross-document Concept Consistency - -Add a bounded evaluation over documents that explicitly share a canonical -concept, owner, dependency edge, capability, Gap, source-supported claim, or -canonical-to-expression binding. It should detect at least: - -- incompatible definitions or mechanisms attributed to the same concept; -- conflicting defaults, constants, thresholds, state transitions, or exception - conditions; -- a derived or expression artifact contradicting its canonical owner; -- two apparent canonical owners for one responsibility; -- a downstream page that still asserts an invalidated upstream conclusion. - -Deterministic comparisons over registered fields, identifiers, constants, and -relationships run first. A semantic evaluator may review paraphrases only over -the bounded, explainable concept group and must return the compared passages, -canonical owner, finding rationale, and confidence or adjudication status. It -does not acquire authority to invent dependencies, rewrite content, or approve -its own findings. Lexical duplicate detection remains candidate discovery and -does not substitute for contradiction evaluation. - -### Separation And Trust Boundary - -The evaluator is a separate read-only pass with independently constructed -inputs and no authority to modify Coverage, Queue, Progress, content, or its own -acceptance threshold. A clean-context reviewer may satisfy the procedural -separation in a local deployment; stronger deployments may use an isolated -runner, protected baseline, signed receipt, or authenticated reviewer identity -through a host adapter. Actor labels and repository-local hashes alone remain -integrity evidence, not proof of independent execution. - -External evaluation libraries may be optional adapters for semantic metrics, -datasets, and experiment execution. They must not become the owner of Cambium's -scope, dependency, canonical-ownership, or completion semantics, and an adopter -must be able to run the deterministic expected-set checks without a hosted -service. - -### Acceptance - -The capability is complete only when: - -1. a fresh filesystem inventory independently detects an in-scope Markdown - file omitted from Coverage; -2. an independently derived impact set detects an affected object omitted from - the Queue, Delta, review scope, or invalidation set; -3. a negative fixture that updates only half of the true expected set fails - even when its Coverage, Queue, Delta, receipts, and proof are internally - consistent with that incomplete half; -4. paraphrased cross-document contradictions are surfaced without treating - consistent paraphrases as failures; -5. exclusions, deferrals, and not-applicable decisions are explicit, - authority-bound, and independently checkable; -6. empty scans, missing upstream inputs, ambiguous ownership, and unresolved - dependency targets cannot produce a green result; -7. evaluation receipts bind the baseline and candidate snapshots, accepted - upstream authorities, derived expected sets, evaluator version, and exact - findings; -8. the evaluator is read-only and cannot reuse the executor's expected-set - artifact as its own derivation; -9. the deterministic layer works on a plain filesystem corpus without a - particular agent host or external evaluation service; and -10. existing Queue, batch-close, Corpus Planning, and Terminal Proof gates - continue to validate their current ownership boundaries rather than being - duplicated inside the evaluator. - -## Observability And Conformance - -Make orchestration inspectable and testable: - -- batch, agent-context, queue, receipt, and blocker status views; -- conflict, timeout, cancellation, and handoff diagnostics; -- interrupted-run and serial-merge recovery tests; -- equivalence tests between sequential and concurrent execution; -- conformance fixtures for profile generation, independent review, receipts, - delta application, and host-adapter capability claims. - -The local baseline deliberately treats repository/tool/evidence writers as a -trust domain. Deployments that include adversarial writers may add signed -receipts, protected-runner attestations, and authenticated actor/reviewer -identity through a host adapter; those controls must strengthen the existing -byte and state bindings rather than replace them. - -Add a guarded non-scope Task Contract Amendment transaction for objective, -exclusion, acceptance, timing, and pause-policy changes. The -`policy_exceptions` field shipped its writer first -(`Tools/apply_contract_amendment.py`, K13/06 Contract Amendment): one anchored -transaction with resolver-validated policy fingerprints and effective joint -quota bounds, and the pattern the remaining fields' writer extends. The -current baseline still fails closed on direct post-materialization edits of -every other field; until the generic writer exists, such a change rolls into -a preserved successor task rather than mutating live Contract bytes. - -## Receipt Ledger Integrity Chain - -Receipt files are plain append-only JSONL with no integrity structure of -their own. Tamper evidence today is earned field by field through cross -binding: a receipt field is immutable only because a second durable record --- an amendment row, the contract anchor chain, a persisted plan, live state -bytes -- also records it, and replay compares the two. Every field that -AUTHORIZES anything is covered this way. The structural residue is the class -of fields with only one carrier, of which `after_progress_sha256` on the -K13/06 contract-amendment and K13/15 adoption commit receipts is the -canonical example: the durable row lives inside the progress document, so it -cannot record the hash of bytes that contain it, and replay can verify the -field's format but never its historical value. Per-field cross binding can -never close this class, because its members are exactly the fields for which -no second carrier can exist. - -This item closes the class wholesale by giving the canonical receipt ledgers -an integrity structure: - -- Every receipt in a chained ledger carries `prev_receipt_sha256`, the - SHA-256 of the previous line's exact bytes; the first line anchors to a - declared per-file genesis value. Editing any landed line breaks every - subsequent link. -- A self-contained chain is NOT sufficient: whoever can edit the file can - re-derive the whole chain. The chain tail must be pinned outside the file - it protects -- each authoritative writer records the tail hash of every - ledger it appended to in the same state write it already compare-and-swaps - (e.g. a `receipts_tail_sha256` map in the Progress Ledger), so rewriting a - ledger consistently would also have to rewrite state that IS cross-bound. -- Producer-era split, K12/10 discipline: receipts written by pre-chain - producer eras carry no link and replay forever under today's rules; the - chain requirement binds only eras that declare it. No historical ledger is - retro-invalidated for a reason its producer could not have anticipated. -- Recovery semantics extend the existing uncertain-append rule: an uncertain - tail blocks further appends to that ledger and retains the writer lock - until reconciliation decides whether the line landed; a broken link marks - the ledger's suffix suspect as a whole, and distinguishing corruption from - tampering -- and repairing either -- needs its own guarded path, since an - unguarded repair channel would be the new tampering channel. - -Scope, when adopted: the canonical `.cambium/receipts/` ledgers consumed by -runtime validation (task transitions, queue transitions, contract -amendments, adoption, delta application, batch-close bundles). Adoption is a -Standards revision under K12/10 with a coordinated version bump of every -producer, not a tool patch. - -This roadmap item does not: - -- change what any receipt authorizes -- authorization already rests on - double-carrier bindings, and the chain adds forensic integrity, not new - authority; -- defend against an adversary with unrestricted repository write access, - who can alter state, plans, and anchors together; the Evidence trust - boundary is unchanged, and deployments needing that defense layer signed - receipts or host-adapter attestations on top (see Observability And - Conformance); -- replace version-control history where the adopter has it -- a - git-managed corpus already carries file-level tamper evidence the runtime - simply does not consume; -- ship the cheaper partial forms (per-line self-hash without a chain, or a - chain without an external anchor); both detect less than they appear to - and would read as "closed" when the class is not. - -## Detached State Transaction Protocol - -An adopter runtime can live on an execution channel that terminates a -command before a state writer's full validation finishes. During the -incident, the active `device_bash` tool channel exposed `timeout_ms <= -45000` and terminated commands at that limit. This is a property of that -execution channel, not a general device, mount, or bridge guarantee. The -historical 75-second close duration is unverified. The 2026-08-13 -incident: a close transition that could not finish on the device was -executed against a byte-identical replica of the runtime in another -environment and the after-image installed back, verified by before/after -hashes of the three state files and the close gate's repository snapshot -binding. The result was correct and the user ratified it as a one-time -procedural exception — explicitly NOT a reusable precedent, because the -writer lock taken in the replica protects the replica, not the -authoritative namespace, and the state-file hashes do not cover the receipt -append frontier, pending deltas, archive moves, or recovery locks. - -Receipt sealing (K12/07) removed the known unbounded hot-ledger -deserialization cost, but the surviving measurements do not establish that -cost as the incident's proximate cause; the detached-execution class remains. -If detached execution is ever needed again, it must be a protocol, not an -improvisation: - -- `detached prepare`: acquire the REAL writer lock on the authoritative - namespace, record the complete before-image (three state files, every - receipt register tail, pending-delta and lock inventory) in the lock - owner metadata, and export it. -- Compute the transaction elsewhere against exactly that before-image. -- `detached commit`: under the still-held authoritative lock, CAS the full - before-image (not just the three state files), append only new receipt - bytes, install the explicit after-image, and write prepare/commit/abort - receipts exactly as the in-place writers do. -- Any drift between prepare and commit aborts; the lock and the recorded - intent drive the same `--resume-status` recovery every other writer uses. - -Do not ship the shortcut form (copy out, compute, copy back with state-file -hash checks alone); it reads as safe exactly until a concurrent writer, -receipt append, or archive move lands between the copies. - -## Concurrent Sealing Protocol - -Receipt sealing ships with a deliberately narrow operating boundary: a declared -maintenance window with a single writer, stated in K12/07 and enforced socially -rather than mechanically. The receipt append mutex makes the ordinary accident — -a checker or writer running beside a seal — fail loudly instead of dropping a -receipt, and that is all it claims. The following are known and accepted at that -boundary. None of them blocks the current version; each is listed so that a -later version widening the boundary knows what it has to close, and so that -nobody rediscovers them as surprises. - -- **Intra-process concurrency.** Mutex acquisition is re-entrant through a - module-level counter, which is what lets a writer append its own receipts - while holding it. The cost is that threads, and forked children sharing the - interpreter state, are not separated from each other. -- **Bypassing appenders.** The mutex binds only writers that go through - `kblib.write_receipts`. Anything appending bytes to a register directly is - unaffected. The rewrite's tail-preservation is the second line of defence - here, and it is a mitigation, not an exclusion. -- **Marker aliasing.** `receipt-append.free` / `.held` are ordinary paths under - `.cambium/tmp/` and are not themselves checked for symlink or hardlink - aliasing before use. -- **Cross-host writers.** Reclaiming an abandoned mutex rests on the recorded - pid being absent from *this* host. That is sound for a crashed local writer - and says nothing about a writer elsewhere. -- **Cold-path containment is detection, not prevention.** The symlink-component - and hard-link checks over `cold/` are evaluated once per consistency run. - They catch a stale working copy or an ordinary mistake; they do not defend - against a party who can change the filesystem between the check and its use. -- **Coordinated tampering.** The journal binds the pending record by hash and - the cold registers are bound by the seal receipt, so editing any one of them - alone fails closed. An edit to journal and pending together, by someone who - can also write the receipt register, is not defended — consistent with the - standing trust boundary that a party controlling the repository, the tools, - and all evidence can fabricate an internally consistent history. -- **Recovery scope.** `--reconcile` deterministically finishes the publication - paths the sealing writer implements. Other interruptions are required only to - fail closed and preserve recoverable evidence; the operator runbook in - `Tools/README.md` covers them, and restoring the pre-seal `.cambium/` copy is - always a valid answer. - -Widening this boundary means a real concurrent protocol: an epoch or cutover -that appenders participate in rather than a marker they cooperate with, with the -exclusion property stated as an invariant and tested against genuine racing -writers. That is a separate change with its own acceptance criteria, not an -incremental hardening of the above. - -## Sealed Evidence Reachability - -Sealing now keeps the aggregate a recorded Queue transition consumed out of the -cold namespace, gives the consumption replay an explicit sealed branch that -re-proves the record's own hash at the read, and fails a run closed when a -recorded consumption's evidence resolves in neither namespace. That closes the -defect an adopter hit: its transitions stayed hot, what they bind went cold, and -obligations those transitions had discharged silently reopened while every run -reported zero errors. Three things about the shape of that defect are not closed. - -- **The protected set is still enumerated by hand.** `_hot_reference_ids` lists - fields; consumers resolve receipt IDs from wherever they like. The defect was - never one missing field — it was that nothing compared the two sets. The - regression test now asserts that no reachable hot body resolves a sealed - receipt outside a declared sealed-branch field, which catches the whole class, - but only over what a fixture reaches. Deriving the protected set from the - consumers themselves would remove the enumeration rather than guard it. -- **Nothing moves a row back.** `seal_receipts.py` moves rows cold and has no - rehydration path. Body resolution makes an already-sealed archive survivable - for consumers that have a sealed branch; a consumer that genuinely requires a - row hot — because it needs a field no projection carries and no branch exists - — has no sanctioned repair short of restoring a pre-seal copy. -- **The projection schema is fixed and identity-only.** Each new body-level - consumer therefore faces a binary choice: keep its evidence hot, or re-read - the sealed record. A projection whose fields consumers declare against would - let the seal carry what its readers actually need, and would make "this field - is not in the projection" a planning-time answer rather than a runtime one. - -## Workflow Progression MVP Boundaries - -Three workflow debts are closed together because each was making ordinary -batch progress ask for a semantic decision after the relevant decision had -already been made. Their implementations share existing state, receipt, and -writer transactions; none introduces a parallel control plane. - -### Batch-close candidate continuation - -`exact-carry-v1` keeps the complete repository scan on every close and reuses -only the review disposition of an exact unchanged observation. The sole -baseline is the immediately preceding successful close, resolved through the -same verified hot/cold receipt catalog. A row carries only when its prior -disposition was `accept-while-unchanged`, its stable ID, complete observation -hash, and producer version still match, and it is not manifest-local -page-contract debt. A disappearance breaks continuity; legacy evidence grants -no carry; a producer or detail change is fresh; and a type selector expands -only the exact rows present in the current fresh set. Priority quota continues -to use its bounded policy-exception path. - -This is intentionally not scan caching, a global candidate ledger, semantic -equivalence, a time-to-live policy, or revival across a disappearance interval. -Those mechanisms can be proposed later if exact carry proves too conservative; -they are not required to stop stable advisory debt becoming every batch's new -manual ticket. - -### Delegated operational Amendments - -The Task Contract may carry a closed `amendment_authority`. Its safe state is -absent or `user-only`; `delegated-integrator` names only registered bounded -change classes. The registration writer derives the complete impact from the -proposed Coverage and live Queue, binds the exact class set and authority -fingerprint, and every consuming writer derives it again under lock. The first -delegatable set is limited to Required-object addition/promotion/rerouting, -batch addition, and queued-batch update. Unknown effects, removal/demotion, -terminal-history changes, and unsupported metadata changes fail closed or -require an explicit user decision through an implemented writer. - -Delegation never authorizes its own expansion. Changing or revoking the -allowlist remains a confirmed Contract Amendment. This MVP does not infer -semantic scope from prose, create a generic arbitrary-diff capability, or let -an Agent edit Queue/Coverage directly. - -### Routed-gap settlement before freeze - -Every gap routed to a batch is now an explicit obligation before that batch -enters `merge-ready`. A read-only Delta preflight computes the prospective -Coverage after-image; the transition binds the obligation set and proves that -none remains routed to the batch, then apply and close re-prove the same facts. -A newly created gap may target only an existing actionable later batch. An -existing gap reroute uses the controlled Amendment path before freeze. - -The close gate is therefore a verifier, not the first place unfinished routing -is discovered. This MVP does not edit a frozen Delta, treat -`merge-ready -> open` as routine bookkeeping, reopen terminal history, or -invent a successor batch when none exists. - -## Machine-readable Review Rulings - -A K12/12 substantive review currently ends in prose. Its findings, their -grades, and the confirmation round's verdict on each are written for a -person; nothing a gate reads carries them. The 2026-08-13 incident: a -confirmation round ruled one finding not-closed while issuing the exact -five-character fix, the fix was applied correctly by hand, and the receipt -that recorded the batch wrote `result: pass` at top level with the deviation -admitted only in its prose. The machine gates read the field. - -A first attempt at the carrier — a `closed-conditional` ruling executed by a -tool that verifies pre-image, patch uniqueness and post-image — was written -and then withdrawn before release, because it verified a shape no producer -emits: no review tool writes a machine-readable verdict, so the tool's -`review_receipt` field could only ever have been filled in by the same -executor it was meant to constrain, and no gate consumed the resulting -receipt. Shipping it would have repeated the original error one level up: -a rule whose enforcement is prose. - -The order this work has to follow: - -- A review round writes machine-readable findings — stable finding ID, - grade, target page and the bytes judged — into a review register, as a - receipt from the reviewing context. -- The confirmation round writes a verdict per finding against those IDs, - with reviewer identity distinct from the executor's, in the same way - `check_batch_close` already requires distinct integrator and reviewer - labels. -- Only then can a conditional close mean anything: an executor tool - resolves the reviewer's verdict receipt, refuses one it cannot resolve or - that names itself as reviewer, applies the literal patch under the writer - lock with pre-image CAS, and writes a receipt a close gate reads. -- The batch-close gate then refuses to close a batch with an unexecuted - `closed-conditional` finding, which is the consumer that makes the whole - chain load-bearing. - -Until the first step exists, a round-2 not-closed escalates. That is the -current rule and it is not a gap. - -## Implementation Order - -Profile onboarding and typed dependency compilation can progress independently -of agent orchestration. Within the onboarding line, the pre-closed template and -the kernel-default/degenerate-state work precede the interview contract, which -in turn precedes the Plugin `adopt` operation that consumes its question -packs. The persistent Required Queue is already the execution -interface; the future reference runtime consumes it rather than redefining it. -The dependency runtime consumes accepted corpus state and emits plans; the -reference execution runtime may later schedule those plans without owning their -semantic policy. Filesystem-to-Coverage inventory re-derivation can be delivered -before the full typed dependency runtime; impact-set and bounded semantic -consistency evaluation follow the compiled dependency model so they do not -invent a second relationship authority. Within the orchestration line, -assignment state and the deterministic integrator loop precede parallel worker -automation; observability and recovery tests accompany every stage. This order -protects the shared control plane while still making multi-context execution -the intended scaling path. - -The host-neutral agent interface is complete and sits before the Plugin line -rather than inside it: the compiled CLI contract, its projection, the MCP -server, and the per-host configs are all host-neutral, so a Plugin release -consumes them rather than reimplementing them. A new host is adopted by adding -one renderer, which is why the per-host configuration piece is the acceptance -test for the three before it rather than a fourth feature. - -Core stabilization precedes every state-writing Plugin capability. The -Operation Capability Registry is standards-layer work that precedes the -read-only alpha's operation surface, which is generated from the registry -rather than hand-listed. The read-only Plugin alpha may progress alongside -Profile onboarding and typed dependency work because it does not own -canonical state. Guarded writers follow -the stable Core API, while the full Codex execution adapter follows the -single-writer integrator loop. Workspace and public distribution are downstream -delivery choices and do not define completion of the host-neutral Cambium +Two lines can progress in parallel: + +```text +explicit planning inputs + -> typed dependency graph + -> change-impact plans + -> independent expected-set and consistency evaluation + +batch-level review evidence + -> per-finding review rulings + -> conditional fix writer + -> close-gate consumption +``` + +Receipt-chain integrity, Contract Amendment expansion, and sealed-evidence +hardening are independent control-plane improvements, but each must preserve +producer-era replay and existing authority boundaries. + +Plugin packaging, remote MCP, UI, and ecosystem distribution remain downstream +choices. None is a prerequisite for completing the host-neutral Cambium runtime. + +## Definition Of Complete + +No roadmap item is complete merely because its happy path works. Completion +requires: + +- tracked implementation and current user documentation; +- deterministic or explicitly bounded semantic authority; +- negative fixtures for stale state, malformed input, missing evidence, path + escape, interruption, and unsupported Host capabilities where applicable; +- recovery behavior that preserves evidence rather than guessing; +- generated artifacts recomputed and checked; +- no new policy owner, ledger, or trust claim hidden in an adapter or view.