terra4mice 0.1.0.dev19

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."

terra4mice applies Terraform's mental model to software development. While Terraform manages infrastructure, terra4mice manages living development.

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

Quick Start

# Install
pip install terra4mice

# With deep AST analysis (optional, Python >=3.10)
pip install terra4mice[ast]

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

# 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

Interactive apply loop:

$ terra4mice apply

============================================================
Next: + feature.auth_login
      Resource declared in spec but not in state

Attributes: {'endpoints': ['POST /auth/login']}

Action: [i]mplement, [p]artial, [s]kip, [q]uit? i
Files that implement this: src/auth.py, src/routes/login.py
Marked as implemented: feature.auth_login

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",
          "line_start": 94,
          "line_end": 686,
          "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	PLANNED	Interactive apply loop, agent integration
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.