Skip to main content

Core Concepts

Rapid OS organizes engineering governance around structured entities, immutable contracts, and SHA-256 cryptographic digests. The system's central concepts are presented below.

1. Project Intelligence (ProjectModel)​

ProjectModel represents the deterministic knowledge Rapid OS holds about a repository. It is generated by rapid scan and contains a collection of normalized facts (ProjectFact).

Each fact includes:

  • Category: language, framework, testing, database, packaging, docker, monorepo, etc.
  • Value and details: exact names and detected versions.
  • Evidence (Evidence): the path of the file that triggered the detection (e.g. pyproject.toml, package.json), the reason, and the assigned confidence.

It is persisted explicitly to .rapid-os/project.json when you use rapid scan --write.

2. Context Compiler (CompiledContext)​

The context compiler (rapid context) extracts and assembles the minimum information strictly necessary for a coding harness to complete a specific task.

Key properties:

  • Task mode: feature, bugfix, refactor, hardening, research, or general.
  • Strict budget (--max-chars): Limits the size of the generated markdown so it does not saturate the LLM's context window.
  • Relevance: Prioritizes project standards, scan facts relevant to the mode, and specifications marked as ready.
  • Traceability (ContextManifest): Emits a record with the SHA-256 digest of each fragment included, so you know exactly what the agent saw.
  • Read-only mode: rapid context never modifies repository files.

3. Specification Registry (SpecRecord and SpecRevision)​

Rapid OS replaces ephemeral notes with a formal specification registry stored in .rapid-os/specs/<spec-id>/.

  • Authoring states:
    • draft: The specification is being written.
    • ready: The specification has been frozen and is ready to be implemented in a run.
    • archived: The specification has been retired or completed.
  • Immutable revisions: Each modification produces a new revision (0001.json, 0002.json, ...) with its own SHA-256 digest (content_digest). A running run is permanently bound to a specific revision; if the specification changes later, the run is not silently altered.

4. Execution Policy (ExecutionPolicy)​

Located at .rapid-os/policy.json, the execution policy defines the team's operating rules:

  • Risk classification: low, medium, high, and critical.
  • Workspace requirements: whether the task can be done in the current workspace (workspace.current) or requires isolation (workspace.isolated).
  • Mandatory gates: checkpoints that must be satisfied before or after implementation (e.g. gate.tests, gate.lint, gate.review).

5. Execution Contract (ExecutionContract)​

The execution contract is the founding document of a run (rapid run create). It immutably freezes:

  • The specification and its exact revision (spec_id, spec_content_digest).
  • The compiled context and its manifest (context_digest).
  • The project snapshot (project_model_digest).
  • The applicable execution policy (policy_digest).
  • The designated harness and the assigned tasks (T001, T002, ...).

The contract digest (contract_digest) is the cryptographic root that governs the entire later lifecycle.

6. Run State Ledger (RunState)​

The state ledger (.rapid-os/runs/<run-id>/states/) works as an append-only ledger. Each transition produces a sequentially numbered file (0001.json, 0002.json, ...).

  • Run states: prepared → active → finished (or failed / cancelled / blocked).
  • Task states: pending → in_progress → done (or skipped / blocked).
  • Gate disposition: pending → acknowledged (declared by the operator) or waived (waived with a recorded justification).

7. Harness Capabilities (HarnessProfile)​

Rapid OS does not grant operating-system permissions; instead, it models the capabilities a harness declares it supports:

  • supported: The harness profile explicitly declares that it supports the operation.
  • unsupported: The profile declares that it does not support the operation.
  • unknown: There is no declaration; Rapid OS does not assume support.

The rapid harness resolve command checks the contract's needs against the profile's capabilities before authorizing the work.

8. Run Evidence (RunEvidence)​

The evidence engine (rapid evidence) ingests physical proof recorded during execution:

  • Command outputs and return codes.
  • Test suite results (TEST_RESULT).
  • Version-control diffs (GIT_RESULT).
  • Generated files, copied to the .rapid-os/evidence/<run-id>/artifacts/ directory with their size and SHA-256 hash.

All evidence is anchored to a state revision (state_revision) and to a specific contract digest.

9. Behavioral Evaluations (EvaluationReport)​

The behavioral evaluator (rapid eval run) is a deterministic engine that runs locally and independently of any LLM:

  • It runs logical rules (BehavioralRuleset v1) over the physical evidence collected.
  • It issues a formal verdict:
    • PASS: All requirements and gates have valid, satisfactory evidence.
    • PASS_WITH_WAIVERS: Requirements met and gates validly waived according to the policy.
    • UNVERIFIED: Evidence is missing to verify tasks or gates.
    • FAIL: A test failed or violated the contract rules.

10. Integrity Validation (rapid validate)​

rapid validate checks the cross-referential and cryptographic integrity of every directory and file in .rapid-os/, making sure there is no manual tampering, schema inconsistency, or break in the SHA-256 provenance chain.

11. Porcelain layer: session, NextAction, playbook, shortcut, producer, and human gate​

On top of the governance engine (the plumbing: specs, runs, evidence, evaluation), Rapid OS offers an intent layer (the porcelain: rapid start, next, check, finish, approve…). Its concepts, with the full design in the orchestration architecture:

  • Session (.rapid-os/session.json): remembers the active run (active_run_id), the mode, the harness, and the state of the repository at the start (start_head). It is local, unversioned state; porcelain verbs use it so they do not ask you for the run id.
  • NextAction: the deterministic answer of rapid next --json. It carries action.kind (author_spec, run_baseline, activate, implement_task, verify, await_human_approval, finish, done, or blocked), the command to run, what is missing, and the progress. It is computed with a pure function over the contract, the state, and the evidence, using the behavioral evaluator as the oracle.
  • Playbook (templates/modes/<mode>.json): a mode's template (feature, bugfix, refactor, hardening, research): the spec_template and the instructions for each action.
  • Shortcut: the file that teaches a harness a mode's loop (/rapid-feature…). It is generated from templates/shortcuts/ with rapid shortcuts install.
  • Porcelain producer: the evidence's producer field indicates who recorded it: rapid:check, rapid:start, rapid:finish, rapid:attach, user, or harness:<id>. Review evidence produced by a harness:* cannot close a human gate.
  • Human gate: gate.peer_review, security_review, migration_review, manual_approval, and final_verification. They are never acknowledged automatically: a person runs rapid approve <gate> in their terminal (with a TTY and no agent as an ancestor). This is a best-effort safeguard; see product limits.