Local work environment
statecraft-cli
Register projects, inspect configuration and drive governed local work.
Observed 2026-10-03 · Producer spec-spine 0.28.0
0748fc721a5e51baff7c1d137be6e8756f7b9088 ↗34 specifications. Verification and deployment qualification are unknown in this export.
Bootstrap spec system
Foundational contract for this repository: authored truth lives only in markdown (+ YAML frontmatter); machine-consumable truth is compiler-emitted JSON only; every artifact is a deterministic function of (config, file contents); a typed authority graph governs who-owns-what. This repository was born governed: the corpus existed before the first line of product code, and no spec here may claim code that does not exist.
The product boundary, the component owners, and the separation of authority
What this product is, what it is not, and who owns each capability it depends on. Fixes the claim vocabulary (specified / implemented / tested / released), the two interaction modes and which one is built first, the rule that separates an authority change from an implementation change, and the reuse disposition for every shared component this repository would otherwise reimplement. Owns the product half of the constitution and the two founding records under docs/. It owns no code.
Project registration and the Statecraft-managed environment: one global home, one project area, one initialization flow, and where authority comes from
Defines repository registration, initialization, the global and per-project environment, ownership classes, manifests, configuration provenance, upgrade, removal, transfer, and setup-profile rendering. Harness delivery, governance-producer adoption, and managed-session evidence are separated into specs 008, 009, and 015.
Work selection, workspace preparation, the run record, and recovery after interruption
The core loop's semantics. How a unit of work is identified by reading spec-spine's structured report rather than re-deriving it; how an isolated workspace is prepared so the operator's checkout is never edited; the append-only hash-linked run record with intent written before an effect and outcome after it; the closed outcome set (completed, failed, refused, interrupted, cancelled) and the rule that a retry appends an attempt rather than replacing history; supervisor-owned refusal accounting a supervised process cannot erase; and reconciliation of an ambiguous effect before any retry, with no exactly-once promise.
The execution adapter boundary and the first provider: one protocol, declared capabilities, a qualification suite, a constructed child environment, and what a real stream can witness
The single seam through which this product runs an agent, and the first provider behind it. Fixes the three-part protocol (a request the supervisor writes, an event stream it reads, a result it records), the closed capability vocabulary with required tokens refusing before any process starts and preferred tokens degrading visibly, the negative suite that qualifies an adapter binary version, and the constructed rather than filtered child environment whose property is a complete record and explicitly not containment of hostile code. Sections 3.9 to 3.16 name Claude Code as the first provider and fix what its stream can and cannot witness: which capability tokens the manifest may declare, each against a measurement rather than a reading of the flags; the finding that a mid-stream denial notification accompanies the terminal refusal record and that a denied session still classifies itself as a success; which of two denial mechanisms the adapter must use, because they have opposite evidence properties; and what a qualification record binds to.
Independent acceptance, the receipt, the separately reported evidence dimensions, and the envelope two products exchange
How a claim of completion becomes, or fails to become, an acceptance. Fixes the identification of candidate bytes and the trusted base, the authority-set rule that stops a candidate from being judged by rules it wrote, the receipt that binds repository, base, candidate, suite, exit codes and policy digest, the four evidence dimensions reported separately from admission with closed value sets, independently supplied trust roots, the preservation of original bytes and named hash constructions, and the three names for absence, none of which reads as success. It also owns the envelope crate the statecraft platform wrote against these serializations and transferred here, which makes one owner for the reference, the dimensions, admission and the absence words rather than two implementations of one wire format.
The command surface: one binary, every verb the other specs name, and what an exit code means
The binary, and every verb reachable through it. Specs 002 to 005 each describe operator verbs and then own only a library crate, so nothing they specify is runnable. This spec owns crates/statecraft-cli/ and binds those verbs to a process: the command tree, the rule that a command is a thin binding and never a second implementation, the closed exit-code vocabulary that distinguishes a refusal from a failure from a finding, human and --json output as two renderings of one value, and the binary's name being a recorded decision rather than a Cargo default. It also carries the work, run and accept bindings that were specified separately as 009: discovery as a join of two spec-spine reports because one of them does not carry status, inspection as a read-only fold of the run record and nothing else, and the rule that a binding needing a library entry point gets it from the crate that owns the behavior. Section 3.11.1 adds the five verbs 002 sections 3.25 to 3.29 need: inspecting and explicitly upgrading the required harness identity, obtaining the managed-session payload, and recording startup evidence beside submitting qualification evidence for admission.
The family envelope: every --json answer in the exit and JSON contract spec-spine speaks
Amends 006 sections 3.3 and 3.4. Every --json answer this product writes becomes the envelope spec-spine has written since 0.26.0 (its spec 132 section 3.4): schemaVersion, tool, verb, outcome, exitCode, summary, then report for exit 0 or 1 and error for 2, 3 or 4, where error.kind is one of the family's ten tokens. No exit number moves. A usage error under --json is an envelope on stdout. The replacement of 002 section 3.23's check translation, which #118 proposed for the same change, is left to the spec-spine 0.28.0 adoption, which changes the producer answer it would read. Replaces the historical proposal from #118 with the amendment that the current model requires (001 section 5).
Harness delivery, hooks, and skills
Carries the environment adapter, delivered harness, consented settings, required identity, and startup-delivery requirements relocated from spec 002. It keeps repository initialization separate from the harness that a registered adapter delivers.
Governance producer adoption
Carries the governance producer boundary relocated from spec 002: exact released identity, supported APIs, and the rule that Statecraft consumes spec-spine without becoming a second compiler.
Setup profile revision 9: a project decides whether governance refuses an unresolved claim
Amends 002's setup profile. github-actions-rust revision 9 adds one boolean parameter, governance.fail_on_unresolved, default true. True renders what revision 8 renders: gate.sh governance runs index check with --fail-on-unresolved. False omits only that flag: index check still runs, names each unresolved claim and fails a stale or invalid index, and every other governance step is unchanged. It exists for a corpus that approves a spec before building it, where an approved spec's unbuilt claim is unresolved by design. Owner decision of 2026-09-25 ("statecraft-cli switch"), requested by the travel-memory program for Rahi.
Initialization never scaffolds a second 000 spec and never writes an approved one
Amends 002 section 3.15's reconciliation of the contract path <specs_dir>/000-bootstrap/spec.md. When the corpus already has another spec holding the ordinal 000, init does not scaffold the bootstrap spec and drops a stale managed record of one that is not on disk. When init does write the bootstrap spec, it writes it with status draft, because ratification is the owner's act and never a tool's. An existing 000-bootstrap spec is adopted and never rewritten, as before. A defect found by the travel-memory program in hiqlite #47 and rahi #90.
A setup profile declares remote desired state and doctor compares it without writing
Amends 002's setup-profile and remote-doctor contract. A profile renders a versioned desired remote-state document covering required checks, extra jobs, code-owner review, merge queue, the review-exception environment and its reviewers, workflow-token defaults, secret names, repository custom properties, and profile identity. doctor --remote compares every field independently and never writes remote state or reads a secret value.
Supervised adoption of one wire-witness sidecar per attempt
Amends 003 and 004 so Statecraft may adopt wire-witness as an exact linked producer, bracket one sidecar as its own durable effect, supply one per-attempt loopback proxy endpoint to the child, and report confinement and witness posture without treating testimony as authority or creating a general sidecar host.
Admission of wire-exchange evidence
Amends the run record, evidence envelope, and command projection so an exact statecraft/wire-exchange/v1 artifact can be bound to one run attempt and sidecar effect, judged deterministically under explicit policy, and shown without retaining secret values or confusing producer testimony with independent acceptance.
Managed-session evidence and admission
Carries the live-observation, control, startup-record, launch-state, managed-trial, trailer, and confinement requirements relocated from spec 002. It separates runtime evidence from installation and harness delivery.
Active specifications stay bounded and historical journals stay outside the corpus
Amends spec 001's authoring model so an active spec carries current requirements and concise resolved rationale, never an append-only work log. A mechanical gate bounds active files and moves historical journals and handoffs to a nonnormative archive outside the compiler input.
Setup profile revision 10: AI review defaults to a 3000-line diff cap
Amends spec 002's setup profile. github-actions-rust revision 10 raises the inherited AI review diff cap from 2000 to 3000 changed lines so ordinary substantial pull requests remain reviewable. Explicit operator selections remain authoritative and are preserved on upgrade.
Governed inputs for a complete first bootstrap
Amends 002's initialization contract and 009's producer call so a fresh repository can supply setup-profile parameters through one explicit, plan-bound input document, receives the exact governance-producer pin from the producer itself, and remains honestly partial when project-owned prerequisites are absent.
Immutable context-packet consumption across repository snapshots
Amends Statecraft's run, adapter, acceptance, command, and governance-producer contracts so one task may bind immutable spec-spine context packets from several independently identified repository snapshots, record intended and provider-visible delivery separately, and judge packet integrity, closure, freshness, citations, and evidence without reimplementing producer-owned selectors, closures, or digests.
Documentation task and structured result contracts
Amends Statecraft's run, adapter, acceptance, and command contracts with an immutable documentation-task document and a provider-neutral structured documentation result. It separates task authority from provider output, binds every claim to an explicit lifecycle grade and supporting references, preserves omissions and contradictions, and keeps provider completion apart from independent acceptance and publication.
Independent documentation acceptance and review
Amends Statecraft's run, acceptance, and command contracts with an independent documentation-acceptance record. It keeps intended delivery, observed transport, schema validation, citation resolution, semantic review, and acceptance as separate facts; requires claim-grade support, preserved unknowns and contradictions, valid artifacts, and a fresh context manifest; and grants no application or publication authority.
Fixed-export documentation workflow
Amends Statecraft's run, adapter, acceptance, and command contracts with a bounded offline documentation workflow over revision-pinned context exports. It preserves immutable task, delivery, raw result, validation, review, correction, and acceptance records as separate facts; proves the workflow with a deterministic fake adapter; and grants no live provider, repository application, remote export, or publication authority.
Setup profile revision 11: the commit walk runs a contained spec-spine
Amends spec 002's setup profile. github-actions-rust revision 11 copies the spec-spine binary into each temporary commit worktree as a regular file instead of linking it from outside, so spec-spine's containment rule can read every commit's tree. The walk's verdicts are otherwise unchanged.
Setup profile revision 12: a token-budgeted AI review and ratification as a merge condition
Amends spec 002's setup profile and spec 017's review cap. github-actions-rust revision 12 leaves a managed file out of the AI review only when its bytes match the digest its policy records, sends deletions as a list under their own cap, measures the reviewable change in estimated tokens, and reviews a change larger than one call in file groups whose verdicts are merged. It also refuses a merge that changes a path a draft spec owns, unless that pull request ratifies the spec with the owner's exception. An unreadable base now refuses instead of letting the candidate's policy and scripts judge it.
Prompt-injection qualification: untrusted content never expands authority
Amends the adapter negative suite and the documentation lane with a versioned hostile-content corpus and a deterministic product-invariance suite. Every surface that carries repository, packet, citation, provider, wire or tool-facing text is exercised with hostile payloads, and the suite proves by construction that Statecraft's decisions are unchanged: no authority expands, no credential is disclosed, no forbidden capability is invoked, no review or acceptance is bypassed. Provider susceptibility is a separate, later measurement that is recorded as testimony and is never the boundary. Delimiters and detectors are not security controls.
doctor reports a path whose recorded ownership disagrees with the transfer journal or the current rendering
Amends spec 002 section 3.5 with one additive, read-only doctor finding, ownership-disagreement. For each path, doctor compares three facts: the manifest entry's class, the latest transfer-journal record for the path, and the class the current selection's rendering would give it. Each incompatible ownership state defined below is reported with both sources named. doctor repairs nothing, transfers nothing and never treats a rendering it could not compute as agreement. Backlog SC-006.
Observation and proposals: noticing that a repository's governed truth changed, and proposing typed work without acting on it
Adds the transition this product lacks between "spec-spine says the repository means X" and "the operator is offered the work that follows". One observation reads exactly one commit through spec-spine's existing structured reports, reduces the answers to three closed projections, and compares them with the last observation recorded for that repository. Each semantic transition a built-in subscription names becomes a proposal with a deterministic identity, recorded in an append-only chain in the product home. A proposal is never executed by this spec: the operator admits it, admission re-derives its preconditions against the current commit, and an admitted proposal enters spec 003's existing run path with its cause recorded in the attempt's intent. No watcher, no loop, no automatic admission, and no change to spec-spine.
Agent attribution and agent commit identities are refused
Amends spec 001's authored-content rules so agent attribution is suppressed at the project boundary and refused in every text the governance gate reads. The same gate refuses commits whose author or committer uses a known agent address. Display names do not decide identity, and external contributors remain allowed.
One resolved judge: every spec-spine call this product makes runs the executable one resolution selected
Every spec-spine invocation this product makes, in every verb and in every hook it delivers, runs the executable that one resolution selected for that operation, and records which one. No call site names a bare `spec-spine` and lets PATH decide. The resolution's sources are, in order, the supervisor's path in a managed session, an operator override, the project's declared engine as spec-spine's own launcher resolves it when that launcher is present, the repository-local install named by the active setup profile, the repository's own build and then PATH; every candidate except the supervisor's already-resolved path is put to the pin, and each passed over is named. `doctor` reports the resolved executable, never a separate PATH probe. Where the resolved engine carries `check --json`, the check is read from its envelope instead of from its wording. Amends spec 008 section 3.23 contracts 2, 4 and 5.
A governed project needs no provider-specific directory, and this product writes none
Makes the absence of provider-specific project directories (`.claude/`, `.codex/`, `.agents/`, `.agent/` and their equivalents) a supported and tested operating condition. No adapter declares a managed or adopted path inside one. The Claude Code adapter's owned instructions file moves out of `.claude/statecraft/` into content this product already manages, and its pointer, where one is still needed, imports `.statecraft/AGENTS.md` directly. A project that already holds the old file converges through the ordinary upgrade and removal rules. A qualification case starts with every provider directory absent and proves initialization, the governed verbs and context delivery work and recreate none of them. Brings the adapter into line with spec 002 section 3.12 and spec 008 section 3.14, and amends the adapter declaration of spec 004.
Setup profile revision 13: the repository-local engine lives in .bin/
The owner decided that neither spec-spine nor Statecraft uses `.tooling/bin` and that the repository-local spec-spine is `.bin/spec-spine`. Profile github-actions-rust revision 13 installs the pinned engine there, its gate, commit walk, CI cache and policy commands read it there, and its ignore fragment ignores `.bin/`. The resolver's repository-local candidate, the delivered hooks and this repository's own `Makefile` follow. A revision-12 project converges through the ordinary managed upgrade.
Required project-owned code checks under managed governance
Profile revision 14 keeps Rust as its default and admits an explicitly selected external code surface. A contained executable local script and a tracked reusable workflow remain required. Rust prerequisites apply only to the Rust selection. Governance, coupling, AI review, protected owner exceptions and the single required aggregate retain their existing rules.
A reviewed initialization plan may explicitly move the adopted spec-spine pin
Adds an explicit exact --spine request to init plan and init apply. The source and destination pins, producer identity, original configuration digest and minimal authored edit are part of the consented plan identity. Apply changes only the existing required_version value in spec-spine.toml after revalidating the plan, then uses the ordinary managed upgrade rules. No implicit pin move, dependency rewrite, ratification or branch protection change is authorized by initialization.