DOCSEARCHbyAlgolia
Submit Docs

Decapod Governance Runtime

repository·master·Indexed 42 days ago

https://github.com/decapodlabs/decapod

A Rust-built, repo-native governance kernel for AI agents that ensures agent-generated code adheres to human intent through enforced workflows, proof gates, and safe coordination. Decapod acts as a daemonless layer between AI models and execution, providing bounded and provable delivery via a structured directory system and a CLI for task management, validation, and workspace isolation. Version 0.102.0.

Tokens
48.4K
Snippets
135
Records
248
Agent score
53%

What's inside Decapod

  1. What is Epistemic Custody?

    master

    Epistemic Custody is the concept of maintaining a preserved, auditable chain of reasoning and evidence. Decapod ensures there is a traceable link between:

    • The initial human intent.
    • The context provided to the AI model.
    • The assumptions made during implementation.
    • The final proof of completion.

    By keeping this chain in the governed repository state, agent work becomes fully falsifiable and transparent, even after the original execution session has ended.

  2. What is Decapod and how does it work?

    master

    Decapod is a daemonless, repo-native governance kernel designed for AI coding agents. It acts as a layer between human intent and agent execution to ensure reliability and trust.

    Instead of relying on ephemeral chat transcripts or tool logs, Decapod uses a project-local state layer located in .decapod/. This directory stores intent, selected context, workspace custody, protected boundaries, validation evidence, and completion status. This makes agent work bounded, attributable, resumable, and provable, even if the original agent or conversation is lost.

    Decapod achieves 'convergence' (reliable execution) through four primary mechanisms:

    1. Repo-Native State: Storing execution state (tasks, specs, proof artifacts) in .decapod/.
    2. Isolated Execution: Automating the creation of isolated git worktrees and (optionally) Docker containers for every task to prevent environment corruption.
    3. Explicit Intent: Requiring agents to record interpretations in versioned plans, todos, and living specifications before implementation.
    4. Proof-Backed Completion: Requiring validation gates and evidence to pass before work is considered 'done'.

  3. Understand the Decapod artifact structure

    master

    Decapod organizes state into two distinct classes of artifacts within the .decapod/ directory: Authored and managed state and Generated evidence and projections.

    • Authored and managed state: Files that represent the project's intent, design, and contracts. These are maintained by the acting agent and validated by Decapod.
    • Generated evidence and projections: Consumable views produced by Decapod (such as context capsules or provenance records) derived from governed inputs. These are not independent authorities and cannot replace their source material.

  4. Understand identity assertions in handshake records

    master

    Handshake records expose identity-adjacent values through identity_assertions. Each assertion is a self-contained object that includes:

    • claim_kind
    • subject_type
    • asserted_value
    • evidence_class
    • scope
    • lifecycle fields
    • authority/verifier slots
    • verification_method
    • claim-specific result

  5. Understand the v2 Interface Contract Model

    master

    Decapod is migrating to a versioned, typed, envelope-first interface model. This model replaces various incompatible response shapes (RPC, Internalization, Constitution, etc.) with a single, strict, machine-readable contract boundary.

    Every cross-boundary operation must now identify its:

    • Producer & Consumer: The components involved and their roles.
    • Contract Version: The semantic version of the contract being used.
    • Lifecycle State: The current state and transition evidence.
    • Scope: The context of the operation (e.g., repo_id, session_id).
    • Outcome: A structured result or error (never free-form strings).
    • Proof: Hashes and evidence verifying the operation.

    This model ensures that all interactions—whether via Rust code, CLI, or RPC—follow a predictable, observable, and verifiable structure.

  6. Understand Proof-backed Completion vs. Completion Claims

    master

    In Decapod, there is a critical distinction between an agent's completion claim and proof-backed completion:

    • Completion Claim: A simple report of what the agent believes it has accomplished.
    • Proof-backed Completion: A verified state establishing that specific Verification Gates were run against a known repository state, produced evidence, and permitted the governed publication transition.

    To achieve proof-backed completion, an agent must satisfy the requirements of the Evidence Ledger, ensuring epistemic custody—a reviewable chain linking intent, assumptions, specific checks, and the measured repository state.

  7. Requirements for Deterministic Proof

    master
    Decapod requires deterministic proof. A proof is only considered valid if it can be re-run or re-verified by a different agent or a human at a later date. This requirement ensures that repository integrity is not tied to an agent's transient state, but is instead anchored to verifiable, repeatable evidence.

  8. Adhere to the Agentic Protocol for reliable execution

    master

    When operating with Decapod, follow these core principles to maintain state and recover from failures:

    • Orientation First: Always start with a claimed task and an isolated workspace.
    • Follow the Errors: Decapod error messages provide deterministic recovery instructions. Do not guess; follow the guidance provided in the error.
    • Respect the Schema: Check Decapod configuration to understand current repository policies (e.g., container isolation requirements).
    • Maintain Custody: If research reveals that the original task intent needs refinement, update specs/INTENT.md.
    • Preserve State: Do not rely on chat history. Use Decapod todos, workspaces, specs, context capsules, validation, and proof artifacts to ensure work is recoverable from the repository.
    • Handle Recoverable Failures: If validation fails, identify the violated invariant, perform the sanctioned remediation, update the affected artifact, and re-run validation. Stop only if remediation is unsupported or human judgment is required.

  9. Configure the Constitution and Overrides

    master

    The Constitution defines the rules of the repository. It consists of immutable Global rules and mutable Local overrides.

    Local Overrides (OVERRIDE.md)

    Humans can override specific directives by using four-backtick source blocks. Decapod derives the structure, hashes, and precedence from these blocks.

    Authoring Rules:

    • Replace the visible instruction inside the four-backtick block with your own Markdown/documentation.
    • Do not attempt to recreate the outer OVERRIDE.md structure manually; Decapod manages the structure.
    • Validation: The repository overlay becomes invalid if you have duplicate exact registered directives, unclosed wrappers, or non-empty unknown IDs in Decapod namespaces.
    • Compatibility: Empty retired generated sections are ignored to maintain upgrade compatibility.

  10. Identify and use Verification Gates

    master

    A Gate is a discrete check required for a task to be considered valid within Decapod. Gates are categorized by their purpose:

    • Compliance Gates: Validated using the decapod validate CLI command.
    • Quality Gates: Includes unit tests, linting, and type-checking.
    • Security Gates: Includes secret scanning and dependency audits.
    • Human Gates: Requires explicit manual approval, typically for high-risk changes.

    For a task to move toward publication, it must pass the gates defined by its governing policy.

  11. Handling ambiguity with Intent Pressure

    master

    When an agent encounters ambiguity, it should apply the principle of Intent Pressure: uncertainty must be preserved, not compressed.

    If an agent is not 100% certain of a requirement (e.g., it is only 70% sure), it is strictly forbidden from guessing the remaining 30%. Instead, the agent must:

    1. Record the specific ambiguity in the task's metadata.
    2. Document the uncertainty in the specs/INTENT.md file.
    3. Request human clarification to resolve the ambiguity before proceeding with implementation.

  12. How Intent drives the Decapod development lifecycle

    master

    In Decapod, Intent is the human-originated "Why" that drives the entire development process. To prevent agents from implementing incorrect solutions due to ambiguity, Decapod enforces a Spec-First Mandate. This lifecycle follows three mandatory stages:

    1. Capture: Convert vague human requests into explicit tasks using the decapod todo add CLI command.
    2. Formalize: Agents must update or verify the specs/INTENT.md document located in the repository to ensure the goal is clearly defined.
    3. Validate: The final implementation is checked against the recorded intent. If the implementation deviates from the specs/INTENT.md specification, validation fails.

    By treating intent as a versioned artifact in the repository, Decapod ensures an auditable link between requirements and code, facilitating long-term maintenance and multi-agent handovers.

    # Example: Capturing a vague request as an explicit task
decapod todo add "Implement user authentication"