Skip to content

Run a capsule end-to-end through the 7 phases

This tutorial shows a Capsule flowing through the full Phase 0 → 6 pipeline with all governance layers attached: audit chain, telemetry, persisted checkpoints, and the pause/resume protocol.

It's the canonical "hello world" for Fase B (Pipeline Runtime).

Goal

Run a single synthetic capsule and observe:

  • All 7 phases execute and report success
  • 7 HMAC-signed entries appear in the audit chain
  • 7 metric events emit
  • 2 checkpoints (Phase 4 + Phase 6) land on disk in schema shape
  • The constitutional gates (Rule 35 SDD, Rule 16 budget, Rule 12 cycle cap) all pass

Prerequisites

pip install -e ".[dev,test]"
export AUDIT_HMAC_KEY="some_random_local_value"   # Windows: $env:AUDIT_HMAC_KEY="..."

The full example

Save as examples/first_pipeline_run.py (or run line by line in a REPL):

from datetime import datetime, timedelta, timezone
from pathlib import Path

from src.ai.metrics import AgentMetrics
from src.pipeline import (
    AgentRef, BudgetTracker, Capsule, CheckpointStore, Constraints,
    ContinuationStore, ExpectedOutput, LockManager, PipelineOrchestrator,
    TaskSpec, VerificationAgent,
)
from src.privacy import AuditChain

# 1. Build a Capsule — the unit of work
deadline = (datetime.now(timezone.utc) + timedelta(hours=2)).isoformat()

capsule = Capsule.new(
    from_agent=AgentRef(id="cortex", layer=1),
    to_agent=AgentRef(id="code-writer", layer=5),
    task=TaskSpec(
        story_id="STORY-001",
        description="Implement a sum(a, b) function with tests.",
        intent_class="build_feature",
        acceptance_criteria=[
            "function returns a+b",
            "tests cover positives, negatives, zero",
            "type hints present",
            "module exports the function",
            "passes lint",
        ],
    ),
    constraints=Constraints(
        budget_tokens=50_000,
        budget_dollars=2.0,
        deadline=deadline,
    ),
    expected_output=ExpectedOutput(type="code"),
    metadata={"project_profile": "startup", "model": "claude-haiku-4-5"},
)

# 2. Wire all 4 governance layers
audit = AuditChain(path="_framework/audit/chain.jsonl")
metrics = AgentMetrics(base_dir="_framework/observability")
ckpts = CheckpointStore(base_dir="_framework/checkpoints")
conts = ContinuationStore(base_dir="_framework/continuations")

orch = PipelineOrchestrator(
    budget=BudgetTracker(
        capsule_id=capsule.capsule_id,
        limit_tokens=50_000,
        limit_dollars=2.0,
    ),
    locks=LockManager(),
    verifier=VerificationAgent(),
    audit_chain=audit,
    metrics=metrics,
    checkpoint_store=ckpts,
    continuation_store=conts,
)

# 3. Run
result = orch.run(capsule)

print(f"success={result.success}  cycles={result.cycles_used}")
for phase in result.phases:
    status = "OK" if phase.success else f"HALT={phase.halt_reason}"
    print(f"  {phase.phase.name:18s}  {phase.elapsed_ms:>4}ms  {status}")

print(f"\nFinal checkpoint: {result.final_checkpoint.checkpoint_id}")
print(f"Audit chain valid: {audit.verify()[0]}")

What you should see

success=True  cycles=1
  RECEPTION           0ms   OK
  REALITY_ANCHOR      0ms   OK
  PLANNING            0ms   OK
  AUTOMATED_GATES     1ms   OK
  EXECUTION           2ms   OK
  REVIEW              1ms   OK
  HANDOFF             0ms   OK

Final checkpoint: ckpt_<random12hex>
Audit chain valid: True

What landed on disk

ls _framework/checkpoints/    # 2 JSON files (Phase 4 + Phase 6)
ls _framework/audit/          # chain.jsonl (7 HMAC-signed entries)
ls _framework/observability/  # agent_metrics.jsonl (7 metric events)

Inspect a checkpoint:

cat _framework/checkpoints/ckpt_*.json | python -m json.tool

Validate the audit chain (any tamper breaks it):

from src.privacy import AuditChain
ok, errors = AuditChain(path="_framework/audit/chain.jsonl").verify()
assert ok, errors

Try breaking each gate

What to try Expected halt
acceptance_criteria=[] spec_not_approved (Rule 35 SDD)
deadline= 1h in the past deadline_passed (Phase 0 reception)
budget_tokens=100 budget_exceeded (Rule 16)
Verifier always returns CHANGES_REQUESTED max_cycles_exceeded:3 (Rule 12)
Capsule context contains "cpf: 123.456.789-00" absolute_rules_violated:[21] (PII)

What just happened (mental model)

Capsule  ──▶  Phase 0 Reception        (validates capsule integrity, deadline, locks)
         ──▶  Phase 1 Reality Anchor   (UBT-000: file:// refs exist?)
         ──▶  Phase 2 Planning         (Rule 35: spec approved?)
         ──▶  Phase 3 Automated Gates  (21 absolute constitutional rules)
         ──▶  Phase 4 Execution        (acquire locks → executor → checkpoint)
              ↕  (up to 3 cycles per Rule 12)
         ──▶  Phase 5 Review           (auditor-haiku — reviewer ≠ producer)
         ──▶  Phase 6 Handoff          (final checkpoint + emission)

Each phase emits: - 1 HMAC entry to AuditChain (Rule 11 — auditable trail; Rule 24 — chain inviolable) - 1 MetricEvent to AgentMetrics (Rule 12 — always emit telemetry) - Phase 4 + 6 also persist Checkpoint → _framework/checkpoints/<id>.json

If budget warning (≥80%) fires at Phase 4, the orchestrator emits a Continuation and returns success=True, halt_reason="paused:cont_...". Resume later by passing the checkpoint forward.

Next steps