Cambium

English | 简体中文

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 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.

Architecture

effective standard = domain-neutral kernel + exactly one selected profile

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.

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:

They are reconciled rather than treated as interchangeable task lists.

Repository Layout

The included
Agent Systems Atlas 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 namespace in the
adopting repository. Every task first checks whether that namespace already
exists, because a seemingly bounded new request may enter a repository whose
earlier persistent task was interrupted:

.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

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 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/ namespace.
If the namespace 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, event
delivery, 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.

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.

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.

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.

python3 Tools/scaffold_profile.py . --profile-id my-profile           # dry-run
python3 Tools/scaffold_profile.py . --profile-id my-profile --apply

The scaffolder copies exactly the whitelist in
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.

1. Answer the remaining TODO(profile) decisions in profiles/my-profile/ —
   by the adoption interview or by hand. Keep
   profile_id equal to the directory name and use
   profiles/README.md as the interface authority.

2. Validate the filled copy:

   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 —
   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:

   python3 Tools/apply_profile_adoption.py . --plan <plan>.yaml
   python3 Tools/apply_profile_adoption.py . --plan <plan>.yaml --apply
   

   The transaction instantiates the four K00/03 values, creates the first
   Change Summary entry, 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/ 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 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/ 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 <candidate manifest>; 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:

python3 Tools/render_host_configs.py . \
  --distribution-root /absolute/path/to/corpus \
  --workspace-root /absolute/path/to/corpus

The products land in Tools/compiled/host-configs/. Install the one your host
reads:

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:

python3 Tools/render_host_configs.py . --check

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.

Adopt A New Standards Version Into An Active Task

R09 governs the Standards revision and records its exact changed predicates.
When an existing .cambium/ task still freezes the prior Standards/Profile
identity, R09 produces one restricted-YAML plan using
Tools/schemas/standards_adoption_plan.template.yaml:

.cambium/deltas/standards-adoptions/<adoption-id>.yaml

That plan is the task's canonical machine revision record. It binds the
complete approved K00/03 bytes, 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:

python3 Tools/adopt_standards.py . \
  --plan .cambium/deltas/standards-adoptions/SA-001.yaml

python3 Tools/adopt_standards.py . \
  --plan .cambium/deltas/standards-adoptions/SA-001.yaml \
  --apply --actor-role integrator

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:

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

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/. If it
exists, do not write content or state and do not initialize or overwrite it:
inspect and reconcile its current task first. If it is absent, only a
long-running, resumable, or multi-batch task initializes it; bounded work
continues without creating empty runtime state.

# 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" \
  --completion-semantics build \
  --scope-version s1 \
  --standards-version YOUR_VERSION \
  --profile-manifest profiles/my-profile/profile.md \
  --apply

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.

# 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/compile_queue.py . --apply --actor-role integrator \
  --expected-queue-revision 1 \
  --expected-sha256 SHA_PRINTED_BY_APPLY_TASK_PLAN
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 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.

License

Cambium assigns licenses by path to its maintained, tracked release files:

• Software and implementation materials under Tools/ are licensed
  under the Apache License 2.0.
• The standards, profile materials, and project documentation under
  kernel/, profiles/, this README, and
  ROADMAP.md are licensed under CC BY 4.0.

See LICENSE.md for the authoritative scope,
ATTRIBUTION.md for attribution guidance, and
LICENSES/ for the complete license texts.

Adopter-generated profiles, vocabularies, receipts, and runtime evidence do
not acquire a Cambium license merely because they are stored inside these
directories.