terra4mice 0.1.0.dev34

State-Driven Development Framework - Terraform for your codebase

terra4mice

State-Driven Development Framework

"Software isn't done when it works. It's done when state converges with spec."

Like Git tracks file changes, terra4mice tracks feature completeness. While Git shows git diff for code, terra4mice shows terra4mice plan for implementation gaps.

The Problem

In livecoding, this happens:

1. You implement A
2. B breaks A
3. You workaround with C
4. D becomes a TODO
5. Someone says "it works"
6. Weeks later: D never existed

The system doesn't know:

• Which parts of the spec are complete
• Which parts are mocked
• Which parts only exist in your head

The Solution

SPEC (desired state)  ->  What SHOULD exist (declarative YAML)
STATE (current state) ->  What DOES exist (inferred/marked)
PLAN (diff)           ->  spec - state = work to do
APPLY (execution)     ->  Cycles until convergence

When NOT to Use terra4mice

❌ Projects <10 resources (GitHub Issues suffice) ❌ Greenfield R&D with changing requirements (overhead not justified) ❌ Teams without spec-first culture (terra4mice forces it) ❌ Pure code quality needs (use SonarQube/linters instead)

When terra4mice Shines

✅ Multi-AI development workflows (Claude Code + Copilot + Cursor) ✅ Livecoding/streaming projects (transparent progress tracking) ✅ Spec drift as chronic problem (incomplete implementations) ✅ Dependency tracking across features

Quick Start

# Install (tree-sitter AST analysis included by default)
pip install terra4mice

# With remote state backend (S3 + DynamoDB locking)
pip install terra4mice[remote]

# All extras
pip install terra4mice[all]

# Initialize in your project
cd my-project
terra4mice init

# See what's missing
terra4mice plan

# Auto-detect codebase state
terra4mice refresh

# List resources in state
terra4mice state list

# Mark something as implemented
terra4mice mark feature.auth_login --files src/auth.py

# CI report (JSON)
terra4mice ci --format json

Commands

terra4mice init

Creates spec and state files:

terra4mice init
# Created: terra4mice.spec.yaml
# Created: terra4mice.state.json

terra4mice plan

Shows what's needed to converge:

$ terra4mice plan

terra4mice will perform the following actions:

  + feature.auth_login
      # Resource declared in spec but not in state
  + feature.auth_refresh
      # Resource declared in spec but not in state
  ~ feature.auth_logout
      # Resource is partially implemented

Plan: 2 to create, 1 to update.

With --verbose, plan shows function-level symbol tracking:

$ terra4mice plan --verbose

  ~ module.inference
      # Resource is partially implemented
      Symbols: 10/12 found
        - format_report (missing)
        - validate_config (missing)

terra4mice refresh

Auto-detects codebase state using multiple strategies:

$ terra4mice refresh

Scanning /my-project for resources...

Inference Report
============================================================
IMPLEMENTED (5 resources)
  module.models
    Confidence: [##########] 100%
    Files: src/models.py
    Evidence: Explicit files found, AST analysis: 100% match
    Symbols: 12/12 (100%)

PARTIAL (1 resources)
  feature.auth
    Confidence: [######----] 60%
    Symbols: 5/8 (62%)
    Missing: validate_token, refresh_session, logout_handler

MISSING (2 resources)
  feature.payments
  feature.notifications

Summary
  Convergence: 68.8%

Inference strategies (in priority order):

1. tree-sitter AST (with [ast]) - verifies functions, classes, exports against spec attributes
2. stdlib ast - basic Python analysis
3. Regex - Solidity, TypeScript/JavaScript patterns
4. Heuristic - config/docs file size

terra4mice state list

Lists all resources in state:

$ terra4mice state list

feature.auth_login
feature.auth_refresh
module.payment_processor

terra4mice state show <address>

Shows resource details including symbol-level tracking:

$ terra4mice state show module.inference

# module.inference
type     = "module"
name     = "inference"
status   = "implemented"
files    = ["src/terra4mice/inference.py"]
symbols  = 12 (10 implemented, 2 missing)
  InferenceEngine                     class      lines 94-686 (src/terra4mice/inference.py)
  InferenceEngine.infer_all           method     lines 154-178 (src/terra4mice/inference.py)
  InferenceEngine.infer_resource      method     lines 180-245 (src/terra4mice/inference.py)
  format_inference_report             function   lines 719-787 (src/terra4mice/inference.py)
  validate_config                     function   [MISSING]

terra4mice mark <address>

Marks a resource with a status:

# Mark as implemented
terra4mice mark feature.auth_login --files src/auth.py

# Mark as partial
terra4mice mark feature.auth_refresh --status partial --reason "Missing token rotation"

# Mark as broken
terra4mice mark feature.auth_logout --status broken --reason "Tests failing"

terra4mice apply

Context-aware apply engine with DAG ordering and multiple execution modes:

# Interactive mode (default) — manual implementation with guidance
terra4mice apply

# Auto mode — AI agent implements resources automatically
terra4mice apply --mode auto --agent claude-code

# Hybrid mode — AI implements, human reviews each change
terra4mice apply --mode hybrid --agent claude-code

# Market mode — post tasks to Execution Market for bounty-based implementation
terra4mice apply --mode market --bounty 50 --market-api-key $KEY

# Parallel execution (any mode) — respects dependency DAG
terra4mice apply --mode auto --max-workers 4

# Dry run — show plan without executing
terra4mice apply --dry-run

# Apply a single resource
terra4mice apply --resource feature.auth_login

# With verification level
terra4mice apply --mode auto --verify-level full

Interactive mode example:

$ terra4mice apply

════════════════════════════════════════════════════════════
 Action 1/3: + create feature.auth_login
════════════════════════════════════════════════════════════

 Resource declared in spec but not in state

 Dependencies:
   (none)

 Attributes:
   - endpoints: ['POST /auth/login']

──────────────────────────────────────────────────────────
 [i]mplement  [p]artial  [s]kip  [a]i-assist  [m]arket  [q]uit
→ i
Files that implement this (comma-separated): src/auth.py
✓ Marked as implemented: feature.auth_login

Apply Modes

Mode	Description
interactive	Manual implementation with dependency status, context, and suggested files
auto	AI agent implements resources — supports Claude Code, Codex, or custom agents
hybrid	AI generates implementation, human reviews and accepts/rejects/edits
market	Posts tasks to Execution Market for bounty-based implementation

Agent Chaining & Fallbacks

Use comma-separated agent names for automatic fallback:

# Try Claude Code first, fall back to Codex if it fails
terra4mice apply --mode auto --agent claude-code,codex

Parallel Execution Engine

The parallel executor respects the dependency DAG — independent resources run concurrently while dependent resources wait:

# 4 workers process independent resources in parallel
terra4mice apply --mode auto --max-workers 4

Verification Levels

Level	Checks
basic	Files exist and are non-empty
git_diff	Basic + git diff shows changes to expected files
full	git_diff + tree-sitter AST verification against spec attributes

terra4mice state pull / push

Sync state between local and remote backends:

# Download remote state to a local file
terra4mice state pull -o local_backup.json

# Upload local state to the remote backend
terra4mice state push -i local_backup.json

terra4mice force-unlock <lock-id>

Force-release a stuck state lock (when a process crashes mid-operation):

terra4mice force-unlock a1b2c3d4-5678-9abc-def0-123456789abc
# Lock forcefully released: a1b2c3d4-...
# WARNING: Releasing a lock held by another process may cause state corruption.

terra4mice init --migrate-state

Migrate local state to a remote backend configured in the spec:

# 1. Add backend: section to terra4mice.spec.yaml
# 2. Run migration
terra4mice init --migrate-state
# State migrated to s3 backend.
#   Resources: 12
#   Serial: 45

terra4mice diff

Compare two state snapshots to see what changed:

$ terra4mice diff --old state.json.bak

terra4mice diff
==================================================
  Old: state.json.bak (serial 5)
  New: terra4mice.state.json (serial 8)

Upgraded (3):
  module.inference: partial -> implemented
  module.analyzers: missing -> implemented
  feature.ci: partial -> implemented

Convergence: 45.0% -> 78.3% (+33.3%)

terra4mice ci

Output for CI/CD pipelines:

# JSON (machine-readable)
terra4mice ci --format json

# Markdown (PR comments)
terra4mice ci --format markdown --comment pr-comment.md

# Fail if convergence < threshold
terra4mice ci --fail-under 80

Spec File Format

# terra4mice.spec.yaml
version: "1"

resources:
  feature:
    auth_login:
      attributes:
        description: "User login"
        endpoints: [POST /auth/login]
      depends_on: []

    auth_refresh:
      attributes:
        description: "Token refresh"
      depends_on:
        - feature.auth_login

  module:
    state_manager:
      attributes:
        class: StateManager
        functions: [load, save, list, mark_created]
      files:
        - src/state_manager.py

  endpoint:
    api_users:
      attributes:
        method: GET
        path: /api/users
      depends_on:
        - feature.auth_login

Spec Attributes for AST Verification

With terra4mice[ast] installed, these attributes are verified against actual code:

attributes:
  class: StateManager              # verified in classes
  functions: [load, save, list]    # verified in defined functions
  entities: [Resource, State]      # verified in classes/interfaces/types/enums
  exports: [WorkerRatingModal]     # verified in exports (TS/JS)
  imports: [useState, useEffect]   # verified in imports
  commands: [init, plan, refresh]  # substring match in functions
  strategies: [explicit_files]     # substring match in functions+classes

Supported languages: Python, TypeScript/TSX, JavaScript, Solidity.

State File Format

{
  "version": "1",
  "serial": 3,
  "last_updated": "2026-01-27T15:30:00",
  "resources": [
    {
      "type": "module",
      "name": "inference",
      "status": "implemented",
      "files": ["src/terra4mice/inference.py"],
      "symbols": {
        "InferenceEngine": {
          "name": "InferenceEngine",
          "kind": "class",
          "status": "implemented",
          "file": "src/terra4mice/inference.py"
        },
        "format_report": {
          "name": "format_report",
          "kind": "function",
          "status": "missing"
        }
      }
    }
  ]
}

Remote State Backend

Store state in S3 with optional DynamoDB locking for team collaboration. Add a backend: section to your spec:

# terra4mice.spec.yaml
version: "1"

backend:
  type: s3
  config:
    bucket: my-terra4mice-state
    key: projects/myapp/terra4mice.state.json
    region: us-east-1
    lock_table: terra4mice-locks    # DynamoDB table (optional)
    profile: my-aws-profile         # AWS profile (optional)
    encrypt: true                   # S3 SSE (optional)

resources:
  # ... your spec unchanged ...

Without backend: or with type: local, behavior is unchanged (local file).

DynamoDB Lock Table Setup

aws dynamodb create-table \
  --table-name terra4mice-locks \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

How Locking Works

When a backend with lock_table is configured, mutating commands (refresh, mark, lock, unlock, state rm, state push) automatically acquire a DynamoDB lock before writing. If another process holds the lock, the command fails with a descriptive error showing who holds it and when it was acquired.

CI/CD Integration

# .github/workflows/terra4mice.yml
name: Check Convergence

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install terra4mice[ast]
      - run: terra4mice plan --detailed-exitcode
        # Returns 2 if there are pending changes

Roadmap

Phase	Status	Description
1 - MVP CLI	✅ DONE	init, plan, refresh, state, mark, apply, ci, diff
2 - tree-sitter AST	✅ DONE	Multi-language deep analysis, spec attribute verification, symbol tracking
3 - Multi-AI Contexts	✅ DONE	Track which AI (Claude, Codex, Kimi) has context on what
4 - CI/CD Integration	✅ DONE	GitHub Action, PR comments, convergence badges
4.5 - Remote State	✅ DONE	S3 backend, DynamoDB locking, state pull/push, migrate-state
5 - Apply Runner	✅ DONE	DAG-ordered execution, Auto/Hybrid/Market modes, parallel engine, verification
5.1 - Agent Dispatch	✅ DONE	Claude Code/Codex backends, agent chaining, fallbacks
5.2 - Parallel Engine	✅ DONE	ThreadPoolExecutor with DAG-aware scheduling, failure cascading
5.3 - Execution Market	✅ DONE	Market mode, bounty tasks, dry-run support
5.4 - E2E Tests & PyPI	✅ DONE	Comprehensive e2e tests, python -m terra4mice, PyPI-ready packaging
6 - Ecosystem Rollout	PLANNED	Deploy across Ultravioleta DAO projects

Multi-Agent Context Tracking

When multiple AIs work on the same project, each carries its own isolated context. The contexts command group provides a context registry to know which AI has context on what resources.

terra4mice contexts list

Shows all agents and their resource contexts:

$ terra4mice contexts list

AGENT          RESOURCE              LAST SEEN    STATUS
claude-code    module.inference      2min ago     active
claude-code    module.analyzers      2min ago     active
codex          feature.auth_login    1hr ago      stale
kimi-2.5       feature.frontend      30min ago    active

Agents: 3 | Active contexts: 4 | Stale: 1

terra4mice contexts show <agent>

Shows detailed context for a specific agent:

$ terra4mice contexts show claude-code

# claude-code
Last active: 2min ago
Status: active

Resources in context:
  module.inference      implemented    2min ago
  module.analyzers      implemented    2min ago
  feature.ci            partial        15min ago

Files touched:
  src/terra4mice/inference.py
  src/terra4mice/analyzers.py

terra4mice contexts sync

Synchronize context between agents:

# Sync all context from one agent to another
terra4mice contexts sync --from=claude-code --to=codex

# Sync specific resources only
terra4mice contexts sync --from=claude-code --to=codex --resources=module.inference,module.analyzers

# Dry run to see what would sync
terra4mice contexts sync --from=claude-code --to=codex --dry-run

terra4mice contexts export / import

Export and import agent contexts for backup or transfer:

# Export an agent's context to a file
terra4mice contexts export claude-code -o claude-context.json

# Import context from a file
terra4mice contexts import codex -i claude-context.json

# Export all agents
terra4mice contexts export --all -o all-contexts.json

terra4mice mark --agent

Mark resources with agent attribution:

# Mark as implemented by a specific agent
terra4mice mark module.auth --status implemented --agent=codex --files src/auth.py

# Mark as partial with agent context
terra4mice mark feature.payments --status partial --agent=claude-code --reason "Missing refund logic"

This automatically updates the context registry so other agents know who worked on what.

Multi-Agent Workflow Examples

Example 1: Handoff Between Agents

When one agent completes work and another takes over:

# Claude finishes working on inference
terra4mice mark module.inference --status implemented --agent=claude-code --files src/inference.py

# Before Codex starts, sync the context
terra4mice contexts sync --from=claude-code --to=codex --resources=module.inference

# Codex can now see what Claude did
terra4mice contexts show codex

Example 2: Parallel Development

Multiple agents working on different features:

# See who's working on what
terra4mice contexts list

# Each agent marks their own work
terra4mice mark feature.auth --agent=claude-code --status implemented
terra4mice mark feature.payments --agent=kimi-2.5 --status partial

# Check for conflicts (same resource, different agents)
terra4mice plan --check-conflicts

Example 3: Context Recovery

When an agent loses context (new session):

# Export context before session ends
terra4mice contexts export claude-code -o session-backup.json

# In new session, restore context
terra4mice contexts import claude-code -i session-backup.json

# Or sync from another agent that has current context
terra4mice contexts sync --from=codex --to=claude-code

Example 4: CI Integration with Multi-Agent

# .github/workflows/terra4mice.yml
- name: Check convergence and contexts
  run: |
    terra4mice plan --detailed-exitcode
    terra4mice contexts list --format json > contexts.json
    # Fail if any contexts are stale > 24h
    terra4mice contexts list --stale-threshold 24h --fail-if-stale

Philosophy

1. State before intention - What exists, not what we want
2. Evidence before perception - Tests, not "I think it works"
3. Convergence before speed - Better slow and correct
4. Clarity before heroism - Visible plan, not magic

Definition of Done

A project is complete when:

$ terra4mice plan

No changes. State matches spec.

Nothing else.

License

MIT - Public good for the developer community.

Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.