Divecha

Divecha is an agent-to-agent skill for turning a build objective into a single-file, behavior-first implementation contract, then letting a coding agent consume that same contract until executable checks pass.

Two rules define it:

1. The spec describes software, not process. A v3 <task>.spec.md is structured data — objective, scope.write/scope.forbid, stateless context facts, exact interfaces, and falsifiable behaviors with concrete input→output examples and executable checks. It is written by one agent for another agent: no narrative sections, no persuasion, no governance fields. The validator rejects unknown top-level keys so process ceremony cannot creep back in.
2. The agent never certifies its own unrun work. The runner computes GREEN mechanically: every behaviors[].check exits 0 from the repo root AND every path the run touched is a subset of scope.write with no scope.forbid match. "Touched" means the working tree (git status --porcelain -uall) plus anything committed since the original persisted baseline — committing or restarting the runner must not launder a change past the check. It prints DIVECHA_GREEN receipt=<path>; prose never counts as proof.

Keep contracts proportional: 1–6 behaviors, small loop bounds, no paperwork gates. Concrete examples are the highest-value lines in a contract — they remove more ambiguity per line than any prose, and the builder turns them directly into test fixtures.

Lifecycle

1. Author Mode: the creator AI writes the smallest useful <task>.spec.md — objective, coarse scope, context facts, interfaces, behaviors with examples — leaving check: TODO and DISCOVER for repo detail it cannot know.
2. Build Mode: Claude Code (Sonnet by default) inspects the real repo, resolves placeholders, turns examples into test fixtures and checks into deterministic commands, and implements to green.
3. Runner Mode: an optional loop runner executes all checks and re-invokes the coding agent with each failing behavior's full spec until GREEN or the loop budget is exhausted (status: stuck).

What It Contains

• divecha/SKILL.md: the Author/Build/Runner skill entrypoint.
• divecha/references/contract_schema.md: the canonical v3 .spec.md schema and enforcement semantics.
• divecha/references/agents_stanza.md: optional repo-level AGENTS.md instructions.
• divecha/references/research_gates.md: deterministic integrity gates for quantitative research.
• divecha/scripts/validate_contract.py: structural contract validator (--mode author|build).
• divecha/scripts/run_divecha_loop.py: the enforcement loop — checks, git scope diff, budget, ledger.
• divecha/scripts/research_vet.py: deterministic source scan for silent exception swallowing.
• divecha/scripts/chain_contracts.py: optional evidence-backed interface ledger for dependent green contracts.
• divecha/requirements.txt: Python dependency list (PyYAML).

Install

Clone the repo and install the Python dependency:

git clone https://github.com/ArjunDivecha/divecha.git
cd divecha
python3 -m pip install -r requirements.txt

Deploy the skill as a symlink so edits in the repo are live immediately:

ln -sfn "$PWD/divecha" "$HOME/.claude/skills/divecha"

Use

Ask the creator AI:

Use $divecha in Author Mode to turn this objective into a behavior-first implementation contract.

Then hand the generated <task>.spec.md to the coding agent:

Use $divecha in Build Mode on <absolute-path-to-task.spec.md>.

Validate a contract:

python3 divecha/scripts/validate_contract.py --mode author <task>.spec.md   # placeholders allowed
python3 divecha/scripts/validate_contract.py --mode build <task>.spec.md    # build-ready, no placeholders

Pre-v3 contracts (schema_version / goal_condition era) are not migrated; they stay readable on disk and new work gets a fresh v3 contract.

Smoke Test

Run the included fixtures without rewriting the contract:

python3 -m py_compile divecha/scripts/validate_contract.py divecha/scripts/run_divecha_loop.py divecha/scripts/chain_contracts.py divecha/scripts/research_vet.py
python3 divecha/scripts/validate_contract.py --mode author tests/fixtures/author.spec.md
python3 divecha/scripts/validate_contract.py --mode build tests/fixtures/build.spec.md
python3 divecha/scripts/run_divecha_loop.py tests/fixtures/build.spec.md --cwd "$PWD" --once --no-ledger --trust

Run the full test suites (rejection corpus + runner enforcement behavior):

python3 tests/run_validator_tests.py   # every tests/fixtures/invalid/* must be rejected for the right reason
python3 tests/run_runner_tests.py      # persisted baseline/state, isolation, receipts, scope, budgets
python3 tests/run_research_vet_tests.py  # deterministic silent-exception research scan
python3 tests/run_chain_tests.py       # deterministic evidence-backed interface handoff

Runner Behavior

The runner refuses to execute anything until --trust is passed because contracts contain arbitrary shell. Without it, the runner lists every command and exits 2. It also refuses to run outside a git repository unless --skip-scope-check is passed, because scope cannot be enforced without git.

A new Git run must start clean. This prevents pre-existing user work inside scope.write from being misattributed to the builder. --worktree creates an isolated detached checkout and leaves it in place for inspection. --allow-dirty is an explicit escape hatch; the receipt marks the proof dirty_start.

Enforcement ownership during a run:

• Enforcement fields, the original baseline, counters, and last observed HEAD are persisted under the worktree-specific Git directory. Mid-run or cross-process edits cannot weaken them; mismatches stop with DIVECHA_STATE_MISMATCH.
• Behavior checks are deterministic and model-free. Validation rejects Codex/GPT, Claude, Opus, Gemini, Fable, OpenAI, Anthropic, and cross-model-vet commands before anything executes. An explicitly requested model review runs outside Divecha after GREEN and is never retried by the runner.
• Turn/failure counters are runner-owned. The budget is enforced even with --no-ledger, and emptying the ledger mid-run cannot extend it.
• The ledger is an append-only list. {turn, agent_note} entries the agent appends mid-run (e.g. to flag a wrong or unsatisfiable check) are preserved across the runner's own appends.
• Checks time out after --timeout seconds (default 600); a timeout counts as a failure with exit code 124.

Use --no-ledger for smoke tests and dry checks. Private state and evidence are still written so the proof boundary survives. Without --no-ledger, the runner updates status and appends ledger entries, then rewrites the YAML frontmatter with yaml.safe_dump — valid YAML, but quoting/indentation may shift. --fresh archives the prior private run state and starts a new proof boundary.

A real run:

python3 divecha/scripts/run_divecha_loop.py <task>.spec.md --cwd <repo-root> --trust

The default agent command runs Claude Code with Sonnet non-interactively:

claude -p --model sonnet --effort medium --permission-mode auto --no-session-persistence

Override it with DIVECHA_AGENT_COMMAND or --agent-command (e.g. to use Opus for a harder build).

For exact path enforcement:

python3 divecha/scripts/run_divecha_loop.py <task>.spec.md --cwd <repo-root> \
  --scope-mode exact --trust

For dependent green contracts. Clean states receive a source_commit; uncommitted states are identified by source_head, source_working_tree_sha256, and source_uncommitted_paths instead:

python3 divecha/scripts/chain_contracts.py T1.spec.md T2.spec.md --output interfaces.json

Sentinels / exit codes: DIVECHA_GREEN 0 · DIVECHA_FAILED / DIVECHA_AGENT_FAILED 1 · DIVECHA_INVALID / DIVECHA_UNTRUSTED / DIVECHA_SCOPE_UNVERIFIABLE / DIVECHA_DIRTY_START / DIVECHA_STATE_MISMATCH 2 · DIVECHA_STUCK 3.

Safety model

Divecha checks are shell commands. Treat a .spec.md received from someone else as code; --trust confirms that you inspected its commands. The validator rejects explicit model/agent calls and checks contract structure and build-readiness. It does not prove that a check really tests the behavior or prevents overfitting; that judgment belongs to the author AI, whose best tool is concrete examples the check must reproduce.

Limitations

• The validator is structural, not semantic.
• A single .spec.md still mixes immutable contract fields with mutable status and ledger presentation state; authoritative frozen runtime state is separate and private.
• Build Mode still needs a competent check-resolution step. Weak checks can make weak implementations look green.
• GREEN proves conformance to the contract, not that the user will like the result; the user judges that by trying it.

License

MIT License. See LICENSE.