alexhraber · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/.decapod/OVERRIDE.md b/.decapod/OVERRIDE.md
diff --git a/.decapod/README.md b/.decapod/README.md
@@ -1,60 +1,77 @@
-# .decapod - Decapod Project Metadata 🦀✨
+# .decapod - Decapod Control Plane
 
-Welcome to the control-plane directory for this repo.
+Decapod is the daemonless, local-first governance kernel behind AI coding agents. Agents call it on demand to turn intent into context, then context into explicit specifications before inference, enforce boundaries, and deliver proof-backed completion across concurrent multi-agent work.
 
-## Quick Start
+GitHub: https://github.com/DecapodLabs/decapod
+Canonical Contract: `assets/constitution.json` section `core/DECAPOD`
 
-1. **Initialize**: Run `decapod init` to set up your project
-2. **Configure overrides**: Edit `.decapod/OVERRIDE.md` to customize behavior
-3. **Read docs**: Use `decapod docs show <path>` to read constitution docs
+## What This Directory Is
 
-## Summary
+This `.decapod/` directory is the local control plane for this repository.
+It keeps Decapod-owned state, generated artifacts, and isolated workspaces separate from your product source tree.
 
-The `.decapod/OVERRIDES.md` file is your project-local override layer for Decapod's embedded constitution.
+`OVERRIDE.md` and `README.md` intentionally stay at this top level.
 
-The embedded constitution (shipped with Decapod) is read-only baseline policy.
-`.decapod/OVERRIDE.md` is where you add project-specific behavior without forking Decapod.
+## Quick Start
 
-Keep overrides in the correct section, minimal and explicit.
+1. `decapod init --proof`
+2. `decapod validate`
+3. `decapod constitution get core/DECAPOD`
+4. `decapod session acquire`
+5. `decapod rpc --op agent.init`
+6. `decapod workspace status`
+7. `decapod todo add \"<task>\" && decapod todo claim --id <task-id>`
+8. `decapod workspace ensure`
 
-## How to Use Overrides
+## Migrating Custom Agent Files
 
-The embedded constitution (read-only, shipped with Decapod) provides the base methodology. The `.decapod/OVERRIDE.md` file lets you customize behavior without forking Decapod.
+If you have existing files like `SOUL.md` or `MEMORY.md` that were used for agent instructions, you can migrate them into the Decapod governance layer.
 
-**To add an override:**
+After running `decapod init`, simply ask your agent to **"consolidate my [FILE.md] content into the .decapod/OVERRIDE.md substrate"**. This ensures your project-specific intent is merged into the correct constitutional sections while allowing Decapod to manage the primary entrypoints.
 
-1. Find the component section in `OVERRIDE.md` (Core, Specs, Interfaces, Methodology, Architecture, or Plugins)
-2. Scroll to the specific component you want to override (e.g., `### plugins/TODO.md`)
-3. Write your override content under that heading
-4. Use markdown formatting for your overrides
-5. Commit this file to version control
+## Aptitude Memory
 
-**Example override:**
+Decapod aptitude remains for preferences and behavior recall:
 
-```markdown
-### plugins/TODO.md
+```bash
+# Record a preference
+decapod data aptitude add --category git --key branch_prefix --value "feature/" --confidence 90
 
-## Priority Levels (Project Override)
+# Get contextual prompts
+decapod data aptitude prompt --query "commit"
 
-For this project, we use a 5-level priority system:
-- **critical**: Production down, blocking release
-- **high**: Sprint commitment, must complete this iteration
-- **medium**: Backlog, next sprint candidate
-- **low**: Nice-to-have, future consideration
-- **idea**: Exploration, needs refinement before actionable
+# Record an observation
+decapod data aptitude observe --category code_style --content "Team prefers async/await over tokio::spawn"
 ```
 
-## Available Override Sections
+## Canonical Layout
+
+- `README.md`: operator onboarding and control-plane map.
+- `OVERRIDE.md`: project-local override layer for embedded constitution directives.
+- `data/`: canonical control-plane state (SQLite + ledgers).
+- `generated/specs/`: living project specs scaffolded by `decapod init`.
+- `generated/context/`: deterministic context capsule artifacts.
+- `generated/artifacts/provenance/`: promotion manifests and convergence checklist.
+- `generated/artifacts/inventory/`: deterministic release inventory artifacts.
+- `generated/artifacts/diagnostics/`: opt-in diagnostics artifacts.
+- `workspaces/`: isolated todo-scoped git worktrees for implementation.
+
+## How It Works
+
+Decapod uses a **JSON-based constitution** to govern agent behavior. Instead of the agent reading full Markdown documents, it uses the Decapod CLI to query specific directives.
+
+1. **Indexing**: Decapod indexes the constitution graph when called.
+2. **Selective Context**: Agents query exact sections (directives) needed for the current task, minimizing context overhead.
+3. **Local Overrides**: You can override any constitution directive in [.decapod/OVERRIDE.md](OVERRIDE.md) using the specific directive ID.
+
+## Why Teams Use This
 
-- **Core**: DECAPOD.md, INTERFACES.md, METHODOLOGY.md, PLUGINS.md, GAPS.md, DEMANDS.md, DEPRECATION.md
-- **Specs**: INTENT.md, SYSTEM.md, AMENDMENTS.md, SECURITY.md, GIT.md
-- **Interfaces**: CLAIMS.md, CONTROL_PLANE.md, DOC_RULES.md, GLOSSARY.md, STORE_MODEL.md
-- **Methodology**: ARCHITECTURE.md, SOUL.md, KNOWLEDGE.md, MEMORY.md
-- **Architecture**: DATA.md, CACHING.md, MEMORY.md, WEB.md, CLOUD.md, FRONTEND.md, ALGORITHMS.md, SECURITY.md, OBSERVABILITY.md, CONCURRENCY.md
-- **Plugins**: TODO.md, MANIFEST.md, EMERGENCY_PROTOCOL.md, DB_BROKER.md, CRON.md, REFLEX.md, HEALTH.md, POLICY.md, WATCHER.md, KNOWLEDGE.md, ARCHIVE.md, FEDERATION.md, FEEDBACK.md, TRUST.md, CONTEXT.md, HEARTBEAT.md, APTITUDE.md, VERIFY.md, DECIDE.md, AUTOUPDATE.md
+- Agent-first interface with explicit governance.
+- Local-first execution without daemon overhead.
+- Integrated TODO, claims, context, validation, and proof in one harness.
+- Cleaner repos: Decapod concerns stay in `.decapod/`.
 
-## Contents
+## Override Workflow
 
-- `OVERRIDE.md`: **Edit this file** to override the embedded decapod constitution for project-specific needs.
-- `data/`: **DO NOT TOUCH**. This is persistent storage (SQLite databases and event logs) used by your agent(s) and decapod.
-- `generated/`: **DO NOT TOUCH**. Artifacts generated by decapod.
+Edit `.decapod/OVERRIDE.md` to add project-specific policy overlays without forking Decapod.
+Keep overrides minimal, explicit, and committed.
diff --git a/.decapod/config.toml b/.decapod/config.toml
@@ -2,7 +2,8 @@ schema_version = "1.0.0"
 
 [init]
 specs = true
-diagram_style = "ascii"
+ci = true
+diagram_style = "mermaid"
 entrypoints = [
     "AGENTS.md",
     "CLAUDE.md",
@@ -12,7 +13,25 @@ entrypoints = [
 
 [repo]
 product_name = "pincher"
-product_summary = "Pincher exists to be the core agent engine that executes and coordinates agent work deterministically across TUI, webapp, and SaaS surfaces, while integrating with Decapod to enforce governance, approvals, and proof-backed quality inside explicitly allowed repos."
-architecture_direction = "Pincher is our Rust-first, highly optimized core agent engine delivered as an embeddable library/module. It is the execution spine that host processes (TUI, webapp, SaaS) integrate to run agent work with consistent behavior and guarantees across every surface. Pincher owns model API orchestration, tool/function calling, patch planning and application, typed state + event emission, deterministic request/retry/idempotency envelopes, and multi-agent concurrency (including spawning and coordinating sub-agents), with a clean backend/plugin architecture so transports and UIs stay thin. The outcome is a single, hardened runtime that turns “agent intent” into reproducible, testable execution—so every product surface ships the same engine, the same safety rails, and the same operational semantics."
+product_summary = "Agent engine. The loop runner. It manages sessions, inference preparation, provider execution, custody, approvals, and runtime control. It ensures Decapod is consulted before inference and before mutation."
+architecture_direction = "library"
 product_type = "service_or_library"
-done_criteria = "Pincher is “done” when a human can submit any supported request through any host surface (TUI, webapp, SaaS) and Pincher deterministically normalizes it into a Decapod-governed intent capsule that expands into an explicit TODO/work-unit graph with clear acceptance criteria, bounded scope, declared constraints, risk classification, required approvals, and named proof surfaces—persisted and addressable as the single source of truth—then executes that plan with multi-agent coordination that is conflict-aware and reproducible, using idempotent request envelopes, bounded retries, and a typed event stream where every model call, tool invocation, and filesystem change is routed as a proposal bound to a specific work unit and governing intent, every risky transition is halted until Decapod records the required approval, and no mutation is permitted unless it is both authorized by the plan and fully traceable, finally driving the plan to closure by running the required proofs, recording outcomes, satisfying Decapod’s promotion gates, and returning a final completion report that is auditable end-to-end—intent → plan → patches → approvals → proofs → promotion—with hard guarantees that nothing changed outside the Decapod-shaped plan and that the delivered result is verifiably compliant with what the human asked for."
+done_criteria = "Done means Pincher provides a Rust-first agent engine that runs governed inference loops inside explicitly allowed repos, with Decapod consulted before context exposure, before agent execution, before repo mutation, and before completion is accepted. Pincher must manage agent/session lifecycle, provider invocation, repo/worktree custody, claimed todos, approval boundaries, context preparation, execution state, validation checkpoints, failure handling, and proof-backed handoff without owning the UI experience directly. A Pincher-managed run is complete only when the intent is bound to Decapod governance, the allowed scope is explicit, the agent operates through that boundary, required approvals are honored, validation has run, proof artifacts are recorded, and the final state can be rendered by Amnion as either ready, blocked, failed-with-cause, or safely handed off."
+base_branch = "main"
+primary_languages = ["Rust"]
+detected_surfaces = [
+    "cargo",
+    "rust",
+]
+external_tracker = false
+container_workspaces = true
+mode = "local"
+declared_capabilities = [
+    "authentication",
+    "background-processing",
+    "event-driven",
+    "external-integrations",
+    "infrastructure-management",
+    "persistent-state",
+    "public-api",
+]
diff --git a/.decapod/generated/Dockerfile b/.decapod/generated/Dockerfile
@@ -1,6 +1,32 @@
 # Generated by decapod container profile
 # Path: .decapod/generated/Dockerfile
-# Regenerate via: decapod auto container run --image-profile alpine
-FROM alpine:3.20
-RUN apk add --no-cache bash ca-certificates curl git openssh-client
+# Managed seed: Decapod maintains the image/version header; agents may
+# mutate project-specific packages and commands in workspace branches.
+ARG DECAPOD_IMAGE=ghcr.io/decapodlabs/decapod:v0.72.16
+FROM $DECAPOD_IMAGE
+ARG DECAPOD_VERSION=0.72.16
+ARG DECAPOD_WORKSPACE_PATH=unknown
+ARG DECAPOD_USE_LOCAL_BINARY=0
+LABEL org.opencontainers.image.base.name="$DECAPOD_IMAGE"
+LABEL org.opencontainers.image.source="https://github.com/DecapodLabs/decapod"
+LABEL org.decapod.managed="workspace"
+LABEL org.decapod.workspace.path="$DECAPOD_WORKSPACE_PATH"
+LABEL org.decapod.version="$DECAPOD_VERSION"
+RUN if command -v apk >/dev/null 2>&1; then \
+apk add --no-cache bash ca-certificates cargo coreutils curl git openssh-client rust sqlite-libs; \
+elif command -v apt-get >/dev/null 2>&1; then \
+apt-get update && \
+apt-get install -y --no-install-recommends bash build-essential ca-certificates cargo coreutils curl git libsqlite3-0 openssh-client rustc && \
+rm -rf /var/lib/apt/lists/*; \
+else \
+echo "No supported package manager found" >&2; exit 1; \
+fi
 RUN update-ca-certificates
+COPY .decapod/generated/decapod /usr/local/bin/decapod.local
+RUN chmod 0755 /usr/local/bin/decapod.local && \
+if [ "$DECAPOD_USE_LOCAL_BINARY" = "1" ]; then \
+cp /usr/local/bin/decapod.local /usr/local/bin/decapod; \
+fi
+RUN if [ "$DECAPOD_USE_LOCAL_BINARY" != "1" ]; then \
+/usr/local/bin/decapod --help >/dev/null; \
+fi
diff --git a/.decapod/generated/policy/context_capsule_policy.json b/.decapod/generated/policy/context_capsule_policy.json
@@ -0,0 +1,41 @@
+{
+  "schema_version": "1.0.0",
+  "policy_version": "jit-capsule-policy-v1",
+  "repo_revision_binding": "HEAD",
+  "default_risk_tier": "medium",
+  "tiers": {
+    "critical": {
+      "allowed_scopes": [
+        "core",
+        "interfaces",
+        "plugins"
+      ],
+      "max_limit": 20,
+      "allow_write": true
+    },
+    "high": {
+      "allowed_scopes": [
+        "core",
+        "interfaces",
+        "plugins"
+      ],
+      "max_limit": 12,
+      "allow_write": true
+    },
+    "low": {
+      "allowed_scopes": [
+        "interfaces"
+      ],
+      "max_limit": 4,
+      "allow_write": false
+    },
+    "medium": {
+      "allowed_scopes": [
+        "core",
+        "interfaces"
+      ],
+      "max_limit": 6,
+      "allow_write": true
+    }
+  }
+}
diff --git a/.decapod/generated/specs/.manifest.json b/.decapod/generated/specs/.manifest.json
@@ -0,0 +1,95 @@
+{
+  "schema_version": "1.1.0",
+  "template_version": "scaffold-v3",
+  "generated_at": "1784668099Z",
+  "repo_signal_fingerprint": "4662065c21bacd9fd48af88524e80aa78796a654d6aa58642b9f7fb3da842383",
+  "declared_capabilities": [
+    "authentication",
+    "background-processing",
+    "event-driven",
+    "external-integrations",
+    "infrastructure-management",
+    "persistent-state",
+    "public-api"
+  ],
+  "capability_definition_version": "1.0.0",
+  "config_input_hash": "307cf907cce89519f092bf94091c88f7215a216e11a5e875f0855985786fd013",
+  "spec_input_hash": "f3989463b175a42d58ebe8e285d96841b1986617f96677ccdd3b9c89526808cf",
+  "decapod_release": "0.72.16",
+  "entrypoints": [
+    {
+      "path": "AGENTS.md",
+      "template_hash": "48fbaa679b3ef6ca712491441e2165ac7a06c279ffd0442ba82bfe8e24c20806",
+      "content_hash": "48fbaa679b3ef6ca712491441e2165ac7a06c279ffd0442ba82bfe8e24c20806",
+      "fingerprint": "5cda5f37f8f0861d4da34116f0977e2568c52a09adeb649e80511408f24f8827"
+    },
+    {
+      "path": "CLAUDE.md",
+      "template_hash": "1a6e8834b3d1fa75f62cba14f7702db9c716faee63e590833116b96ecb1b0fc2",
+      "content_hash": "1a6e8834b3d1fa75f62cba14f7702db9c716faee63e590833116b96ecb1b0fc2",
+      "fingerprint": "1f983c24666a1f41d84a5e5ea3f8b5941981752411ec8fd22dddafbf5b95394e"
+    },
+    {
+      "path": "GEMINI.md",
+      "template_hash": "6a2dde574607f3a59e92f8f8ba2cda53340ed9c0a69cf41d63646a3bf440b72f",
+      "content_hash": "6a2dde574607f3a59e92f8f8ba2cda53340ed9c0a69cf41d63646a3bf440b72f",
+      "fingerprint": "a952a85e11180bbdd9192521932ebf41289187f7a69b17ba5cdb0d33819f3606"
+    },
+    {
+      "path": "CODEX.md",
+      "template_hash": "d133490547ab2fa67e300fdb75dd34b3637505815032e1f9345d703280e581e8",
+      "content_hash": "d133490547ab2fa67e300fdb75dd34b3637505815032e1f9345d703280e581e8",
+      "fingerprint": "4b73d322dddc92be7fd6035430abc84924081bf0de751ecbe76bc3bc5b73b26c"
+    }
+  ],
+  "files": [
+    {
+      "path": ".decapod/generated/specs/README.md",
+      "template_hash": "7a85d851e4e267dd9eec6ae0dee0417fd6ff3dbca435bc92c6e9aa7c26487813",
+      "content_hash": "988a60f85df34c3b76ccbe96aba83742482783ee2aee8a3bca37a7956ad15d20",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/INTENT.md",
+      "template_hash": "e6c06430e23ca87ae33169a6b1f9c70a3fd283655f5b5b29755fb83181f989e9",
+      "content_hash": "bae3c3a2d2972479cd07a627f56472809c657c56eb93ecbea6808dc6fd66049d",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/ARCHITECTURE.md",
+      "template_hash": "f81224214db72e367670029174b0b69cf21ea2240d14ba936257324f2a9449d7",
+      "content_hash": "aeff2deafa28f534f3caacc7c628d0b17c37ba1affc7e5476189ba483ce45a39",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/INTERFACES.md",
+      "template_hash": "15cc8c3bbfe951da695384106eb78a44c7af28ddc002bcc83c8a7770229fe999",
+      "content_hash": "ebb9dc21eca3e544af9852d8ee8cb9e106a287edb9397c9f20a7d2d1649efc32",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/VALIDATION.md",
+      "template_hash": "66c5f8821df14298ff57951351980899465cce41a3e4de98c3893c00116e51fb",
+      "content_hash": "ade44472c239049da87a834b2cd2bf28cd40f0dcf2d91b6e8ddbdfec29050d76",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/SEMANTICS.md",
+      "template_hash": "3a79850c94b81e29c6462a7ea70d45198252e3eeba2132c6e9206f7b4e4a5829",
+      "content_hash": "25dd3472de05e3c34fb3346099224277be69f744db010e7d3d6f78eb421c6580",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/OPERATIONS.md",
+      "template_hash": "54ab819ae22bea9f786793a37196749cbacd72c60f58108898e9db044c534acf",
+      "content_hash": "de3101274209aa41bcd7d42d656a0d9ebfcfc28af7dcab9acf139c257d981a77",
+      "fingerprint": ""
+    },
+    {
+      "path": ".decapod/generated/specs/SECURITY.md",
+      "template_hash": "b283bdc62b7c2fce411becf6b31928d1b3502da28be7ad618531e3e1820fc147",
+      "content_hash": "74e00a43fae4f173695e70e78ba55ccee32389708547b34afa7f4fa0bbd06fba",
+      "fingerprint": ""
+    }
+  ]
+}