Rapid OS v3 Governance Loop

Rapid OS v3 governs AI-assisted software engineering through a deterministic, offline, 8-step governance loop. Every artifact is content-addressed with SHA-256 digests and free of wall-clock timestamps, random UUIDs, or host-specific absolute paths.

1. End-to-End Pipeline

Repository
    ↓  rapid scan [--write]
ProjectModel (.rapid-os/project.json)
    ↓  rapid spec create / revise / status ready
SpecRecord + SpecRevision (.rapid-os/specs/<spec-id>/)
    ↓  rapid context compile --spec <spec-id>
CompiledContext + ContextManifest
    ↓  rapid policy show / init
ExecutionPolicy (.rapid-os/policy.json)
    ↓  rapid run create --spec <spec-id> --harness <harness-id>
ExecutionContract + RunRecord + RunState (.rapid-os/runs/<run-id>/)
    ↓  rapid harness resolve --run <run-id> [--locked] [--require-compatible]
CapabilityResolution (.rapid-os/harnesses/ & .rapid-os/capabilities.lock)
    ↓  External Coding Harness Execution + rapid run gate / status / task
Updated RunState Ledger (states/0001.json .. 000N.json)
    ↓  rapid evidence add --run <run-id> --input <evidence.json>
RunEvidence + Copied Artifacts (.rapid-os/evidence/<run-id>/)
    ↓  rapid eval run --run <run-id> [--write] [--require-pass]
EvaluationReport (.rapid-os/evals/<run-id>/reports/000N.json)
    ↓  rapid validate [--strict]
Cross-Phase Integrity Verification

2. Cross-Module Digest & Provenance Chain

Each layer binds cryptographically (via canonical SHA-256 digests) to its upstream inputs:

SpecRevision.content_digest → ExecutionContract.spec_content_digest: Ensures a Run cannot silently drift if a Spec is later revised or tampered with (RAPID1003).
CompiledContext.manifest.content_digest → ExecutionContract.context_digest: Locks the exact compiled Markdown and ContextManifest snapshot (context.md and context-manifest.json) used when the Run was created (RAPID1004).
ProjectModel → ExecutionContract.project_model_digest: Captures the exact repository intelligence snapshot at contract creation.
ExecutionPolicy → ExecutionContract.policy_digest: Binds the policy rules that produced the ExecutionClass, RiskLevel, WorkspaceRequirement, and GateRequirement set.
ExecutionContract.contract_digest → RunRecord & RunState: Every append-only state transition (states/0001.json .. 000N.json) pins contract_digest and is re-verified sequentially from revision 1 (RAPID1012).
ExecutionContract.harness → HarnessProfile → CapabilityResolution: Evaluates whether the selected harness declares support for all capabilities derived from the contract (RAPID1100–RAPID1112).
RunState.content_digest → RunEvidence.state_digest: Every evidence record (E001 .. E00N) pins the exact run_id, contract_digest, state_revision, and historical state_digest at which the observation occurred, along with SHA-256 digests and byte sizes of all copied files in artifacts/E00N/ (RAPID1202–RAPID1205).
RunEvidence[] → evidence_set_digest → EvaluationReport: Every persisted EvaluationReport pins contract_digest, state_revision, state_digest, evidence_set_digest, ruleset_digest, and extra_capability_ids, and undergoes mandatory semantic replay via BehavioralEvaluator whenever loaded or validated (RAPID1223).

Machine gate gate.architecture. In feature, bugfix and refactor runs, when .rapid-os/standards/architecture.json exists the contract includes gate.architecture (required, not waivable). rapid next proposes rapid check --gate gate.architecture -- rapid arch check --new-only; a violation is RAPID1420 and rapid finish does not return PASS until it is satisfied. See Architecture by stack.

Verification integrity. A check bound to a test gate, or to a task of a mode that needs tests, is a test_result with a count whenever its output has a test summary, whatever its argv; one without a readable count is reported as such and a refactor refuses to go on without a baseline that has one. Every check also records a digest of the working tree (tree), and rapid next (before asking for approval), rapid approve and rapid finish require the tree to be the one the last gate.tests check saw: if it changed, they ask for a new check and name the files (RAPID1423). See the CLI reference.

3. Declarations vs. Capabilities vs. Evidence vs. Verdicts

Rapid OS v3 enforces a strict separation between four concepts that are frequently conflated in AI tooling:

Concept	Layer	Meaning
`GateDisposition.ACKNOWLEDGED`	Phase 4 (`RunState`)	A human or workflow declared that a gate was satisfied. Does not prove work was verified.
`GateDisposition.WAIVED`	Phase 4 (`RunState`) & Phase 6 (`EvaluationReport`)	An explicitly permitted policy exception with a recorded non-empty reason (forbidden at `CRITICAL` risk).
`CompatibilityStatus.COMPATIBLE`	Phase 5 (`CapabilityResolution`)	The selected `HarnessProfile` declares `supported` for all required capabilities. Does not prove the harness exercised them at runtime.
`AssertionOutcome.UNVERIFIED` / `EvaluationVerdict.UNVERIFIED`	Phase 6 (`EvaluationReport`)	A required lifecycle state, task (`DONE`), gate (`ACKNOWLEDGED`), or observable capability lacks qualifying `RunEvidence`. Causes `rapid eval run --require-pass` to fail with `RAPID1225` (exit `1`).
`EvaluationVerdict.PASS`	Phase 6 (`EvaluationReport`)	All required assertions are satisfied by verified `RunEvidence` under `BehavioralRuleset` v1.
`EvaluationVerdict.PASS_WITH_WAIVERS`	Phase 6 (`EvaluationReport`)	All non-waived required assertions pass and at least one required gate was validly `WAIVED`. Satisfies `--require-pass` (exit `0`).
`EvaluationVerdict.FAIL`	Phase 6 (`EvaluationReport`)	At least one required assertion failed (e.g., failed run lifecycle, non-zero test exit code, failed test count `> 0`, or rejected review). Causes `rapid eval run --require-pass` to fail with `RAPID1226` (exit `1`).

4. Explicit Product Boundaries

What Rapid OS v3 Does

Scans repositories deterministically for languages, frameworks, package managers, databases, testing frameworks, Docker, monorepo layouts, and deploy hints with traceable Evidence.
Compiles task-specific, budgeted context (CompiledContext) with conflict detection and provenance (ContextManifest).
Manages multi-spec authoring lifecycles (draft, ready, archived) and immutable revisions (0001, 0002, ...).
Classifies execution risk (low, medium, high, critical) and scope (spike, bounded, architectural) and generates immutable ExecutionContract records.
Tracks append-only RunState transitions (prepared, active, blocked, finished, failed, cancelled) with strict pre/post-execution gate and task phase boundaries.
Resolves declared harness capabilities (HarnessProfile, .rapid-os/capabilities.lock) against contract-derived requirements.
Ingests immutable RunEvidence records (E001, ...), copies supporting artifacts into .rapid-os/evidence/<run-id>/artifacts/, and verifies SHA-256 digests and byte sizes.
Evaluates runs deterministically offline (BehavioralEvaluator → EvaluationReport) with mandatory semantic replay verification.

What Rapid OS v3 Does NOT Do

Does not launch or orchestrate autonomous coding agents or call LLM APIs.
Does not use LLM-as-a-judge (all evaluations are 100% deterministic ruleset checks).
Does not execute anything from the plumbing commands (spec, run, evidence, eval…); the porcelain runs only the test_command of .rapid-os/config.json or the argv given to rapid check, and read-only git commands to record the run's changes.
Does not create Git branches or worktrees except with rapid start --worktree, and never invokes agents or approves human gates.
Does not provide cryptographic hardware/remote attestation of external evidence producers (authenticity is local digest, size, sequence, and contract/state binding verification).
Does not claim that EvaluationVerdict.PASS is a mathematical proof of zero software bugs or complete requirement coverage beyond the recorded evidence rules.

5. Porcelain Verbs → Plumbing Commands

The porcelain verbs drive the loop above for you (see the orchestration architecture and the shortcuts guide). This table replaces the manual plumbing sequence each verb performs; the plumbing commands remain available for CI, debugging and auditing (advanced mode).

Porcelain verb	Plumbing commands it replaces
`rapid start <mode> --spec-file -`	`rapid spec create` + `rapid spec status <spec-id> ready` + `rapid run create --spec <spec-id> --harness <id>`, then the baseline: run the tests, `rapid evidence add` (`test_result`), `rapid run gate <run-id> gate.baseline acknowledged` and `rapid run status <run-id> active`
`rapid next`	Reading `rapid run show` / `rapid run status` and `rapid eval run` by hand to decide what is missing
`rapid check -- <command>`	Running the command, saving its log and `rapid evidence add` (`test_result` or `command_result`, producer `rapid:check`)
`rapid task start\|done\|skip`	`rapid run task <run-id> <task-id> in_progress\|done\|skipped` (`done` also runs the checks)
`rapid attach <path> --label <text>`	`rapid evidence add` with an `artifact` evidence (producer `rapid:attach`)
`rapid finish`	`rapid evidence add` (`file_change`), `rapid run gate <run-id> <gate> acknowledged` for the machine gates the evidence already satisfies, `rapid run status <run-id> finished` and `rapid eval run --run <run-id> --write`
`rapid approve <gate>`	`rapid evidence add` (`review`, producer `user`) + `rapid run gate <run-id> <gate> acknowledged\|waived`; only a person can run it
`rapid status`	`rapid run show` / `rapid run status` + `rapid eval list`
`rapid abort`	`rapid run status <run-id> cancelled`
`rapid shortcuts` / `rapid hook`	Nothing: they generate and enforce the agent-side files (`/rapid-<mode>` skills and Claude Code hooks)

1. End-to-End Pipeline​

2. Cross-Module Digest & Provenance Chain​

3. Declarations vs. Capabilities vs. Evidence vs. Verdicts​

4. Explicit Product Boundaries​

What Rapid OS v3 Does​

What Rapid OS v3 Does NOT Do​

5. Porcelain Verbs → Plumbing Commands​