Skip to content

richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane

running-control-plane

Flagged

CRITICAL INTAKE GATEWAY: use at the start of any non-trivial engineering task, feature, refactor, multi-file bugfix, work package or new idea, including requests to explore, brainstorm, build, fix or change something, before planning or code changes. Enforces read-only discovery, 1-3 structured questions with defaults, control-plane registration and the immutable four-pillar TASK_SPEC.md. Also runs the rest of the control plane: health ("run health check", "check os metrics", "system monitor", event bus, locks, memory, "is my signing identity ready" status check), transition simulation ("dry run transition", "simulate transition", "check edge X -> Y"), worktree selection, and gating on/off ("disable the control plane", "turn off the push guard", "stop gating my commits"). Not for project setup or key creation (use setting-up-agentic-os) or improving skills (use improving-skills-in-lab).

FileKindSize
SKILL.mdskill md5.4 KB
evals/evals.jsonconfig8.3 KB
references/acceptance-criteria.mdmarkdown4.0 KB
references/agentic-os-skill-map.mdmarkdown2.3 KB
references/architecture/architecture.mdmarkdown2.4 KB
references/architecture/context-folder-patterns.mdmarkdown3.3 KB
references/architecture/vision.mdmarkdown56.6 KB
references/cheap-agent-transition-simulation.mdmarkdown6.1 KB
references/control-plane-architecture.mdmarkdown9.0 KB
references/control-plane-rebuild-recovery.mdmarkdown6.2 KB
references/control-plane-simulation-protocol.mdmarkdown5.7 KB
references/diagrams/agentic-os-memory-subsystem.mmdother1.4 KB
references/diagrams/architecture-overview.mmdother3.1 KB
references/diagrams/control-plane-architecture.mermaidother6.3 KB
references/diagrams/control-plane-lifecycle-hardened-with-ciba-rar.mermaidother4.5 KB
references/diagrams/control-plane-pipeline-happy-path.mermaidother5.0 KB
references/diagrams/control-plane-pipeline.mermaidother9.3 KB
references/diagrams/event-bus-architecture.mmdother2.4 KB
references/diagrams/increment-b-human-only-transition-ssh-signing.mermaidother5.3 KB
references/edge-matrix.mdmarkdown13.3 KB
references/fallback-tree.mdmarkdown2.9 KB
references/health-detailed-reference.mdmarkdown7.1 KB
references/healthy-transcript.mdmarkdown3.8 KB
references/implementation-ledger-contract.mdmarkdown851 B
references/intake-detailed-reference.mdmarkdown3.1 KB
references/modes/health.mdmarkdown3.4 KB
references/modes/intake.mdmarkdown3.8 KB
references/modes/mode.mdmarkdown5.8 KB
references/modes/simulator.mdmarkdown6.2 KB
references/modes/worktree.mdmarkdown2.9 KB
references/multi-round-external-review-protocol.mdmarkdown2.6 KB
references/worktree-reconciliation-and-multi-worktree-practices.mdmarkdown5.8 KB
requirements-dev.inother741 B
requirements-dev.txtmarkdown603 B
requirements.inother196 B
requirements.txtmanifest202 B
scripts/agent_control.pyscript97.7 KB
scripts/audit_map_debt.pyscript6.1 KB
scripts/capability_probe.pyscript6.4 KB
scripts/check_plan_links.pyscript1.8 KB
scripts/control_plane/__init__.pyscript842 B
scripts/control_plane/adapters.pyscript144.9 KB
scripts/control_plane/approver_policy.pyscript20.0 KB
scripts/control_plane/baseline_transition_report.pyscript4.0 KB
scripts/control_plane/constants.pyscript13.5 KB
scripts/control_plane/coordinator.pyscript57.3 KB
scripts/control_plane/edge_matrix.pyscript3.1 KB
scripts/control_plane/gate1_approval.pyscript10.7 KB
scripts/control_plane/gate_evidence.pyscript9.9 KB
scripts/control_plane/identity_layout.pyscript2.9 KB
scripts/control_plane/identity_setup.pyscript11.0 KB
scripts/control_plane/implementation.pyscript3.7 KB
scripts/control_plane/implementation_loop.pyscript11.3 KB
scripts/control_plane/inspection.pyscript3.9 KB
scripts/control_plane/installation_probe.pyscript5.7 KB
scripts/control_plane/isolation_check.pyscript14.0 KB
scripts/control_plane/measurement.pyscript39.1 KB
scripts/control_plane/pipeline_simulator.pyscript30.0 KB
scripts/control_plane/policy.pyscript32.5 KB
scripts/control_plane/ports.pyscript20.3 KB
scripts/control_plane/proof_edges.pyscript4.6 KB
scripts/control_plane/proof_policy.pyscript2.2 KB
scripts/control_plane/receipt_provenance.pyscript4.7 KB
scripts/control_plane/registry.pyscript32.9 KB
scripts/control_plane/review_options.pyscript8.2 KB
scripts/control_plane/review_selection.pyscript3.2 KB
scripts/control_plane/run_transition_simulation.pyscript12.0 KB
scripts/control_plane/signing_selftest.pyscript6.8 KB
scripts/control_plane/simulation_identity.pyscript10.4 KB
scripts/control_plane/snapshot.pyscript10.8 KB
scripts/control_plane/ssh_signing.pyscript21.8 KB
scripts/control_plane/state_machine.pyscript5.8 KB
scripts/control_plane/transition_request.pyscript19.5 KB
scripts/control_plane/transition_simulation_cases.pyscript24.6 KB
scripts/control_plane/transition_templates.yamlconfig159.1 KB
scripts/control_plane/tty_signer.pyscript3.0 KB
scripts/control_plane/wrappers/__init__.pyscript24 B
scripts/control_plane/wrappers/record_interview_question.pyscript8.0 KB
scripts/control_plane/wrappers/record_retrospective.pyscript2.3 KB
scripts/control_plane/wrappers/run_exit_verification.pyscript6.4 KB
scripts/control_plane/wrappers/run_verify_exit_bundle.pyscript5.4 KB
scripts/control_plane/wrappers/write_plan_document.pyscript9.6 KB
scripts/control_plane_hooks.pyscript10.5 KB
scripts/control_plane_mode.pyscript12.0 KB
scripts/distill_playbook.pyexecutablescript9.9 KB
scripts/evolution_state.pyscript29.4 KB
scripts/export_upstream_pr.pyscript4.4 KB
scripts/interview_spec_engine.pyscript9.1 KB
scripts/kernel.pyscript14.6 KB
scripts/pre-commit-evolution-guardexecutablescript3.7 KB
scripts/pre-commit-pipeline-guardexecutablescript13.6 KB
scripts/pre-push-review-guardexecutablescript10.5 KB
scripts/record_trace.pyscript7.2 KB
scripts/smoke_test.pyexecutablescript22.6 KB
scripts/test_capability_probe.pyscript3.9 KB
scripts/test_worktree_manager.pyscript2.8 KB
scripts/verify_evolution_receipt.pyscript7.5 KB
scripts/verify_gate_evidence.pyscript1.6 KB
scripts/worktree_manager.pyscript3.0 KB
tests/conftest.pyscript7.7 KB
tests/helpers/__init__.pyscript0 B
tests/helpers/control_plane_fixtures.pyscript2.6 KB
tests/helpers/control_plane_repo.pyscript4.0 KB
tests/helpers/gate1_fixtures.pyscript5.8 KB
tests/helpers/human_signer.pyscript7.3 KB
tests/helpers/implementation_ledger.pyscript1.1 KB
tests/interview_helpers.pyscript5.2 KB
tests/test_actionable_rollback.pyscript2.2 KB
tests/test_agent_control.pyscript190.6 KB
tests/test_agent_control_gate_characterization.pyscript14.7 KB
tests/test_approve_transition.pyscript10.5 KB
tests/test_approver_identity_guidance.pyscript3.4 KB
tests/test_approver_isolation.pyscript12.3 KB
tests/test_audit_map_debt.pyscript4.7 KB
tests/test_authorized_actor_enforcement.pyscript22.9 KB
tests/test_background_document_priority.pyscript924 B
tests/test_check_plan_links.pyscript1.1 KB
tests/test_content_snapshot.pyscript11.8 KB
tests/test_control_plane_architecture_diagram_contract.pyscript9.0 KB
tests/test_control_plane_architecture_overview_contract.pyscript2.1 KB
tests/test_control_plane_critic_review.pyscript3.1 KB
tests/test_control_plane_crypto_adapter.pyscript5.0 KB
tests/test_control_plane_delegation_contract.pyscript5.7 KB
tests/test_control_plane_facade_composition.pyscript15.9 KB
tests/test_control_plane_filesystem_adapter.pyscript4.9 KB
tests/test_control_plane_hooks.pyscript7.3 KB
tests/test_control_plane_interview_guidance.pyscript3.8 KB
tests/test_control_plane_measurement_contract.pyscript28.0 KB
tests/test_control_plane_mode.pyscript7.5 KB
tests/test_control_plane_mode_guards.pyscript3.5 KB
tests/test_control_plane_model_catalog_adapter.pyscript9.2 KB
tests/test_control_plane_pipeline_diagram_contract.pyscript2.3 KB
tests/test_control_plane_pipeline_simulator.pyscript7.5 KB
tests/test_control_plane_policy.pyscript13.0 KB
tests/test_control_plane_ports.pyscript3.2 KB
tests/test_control_plane_reset_transition.pyscript13.6 KB
tests/test_control_plane_schema_rebuild_atomicity.pyscript20.0 KB
tests/test_control_plane_simulation_protocol_contract.pyscript959 B
tests/test_control_plane_sqlite_persistence_adapter.pyscript5.5 KB
tests/test_control_plane_state_machine.pyscript15.2 KB
tests/test_control_plane_trigger_enforcement.pyscript14.6 KB
tests/test_control_plane_worktree_sharing.pyscript4.5 KB
tests/test_domain_namespaces.pyscript6.7 KB
tests/test_done_closure_proof.pyscript6.9 KB
tests/test_draft_plan_interactive_outline_gap.pyscript2.2 KB
tests/test_dual_identity_onboarding.pyscript7.3 KB
tests/test_edge_matrix.pyscript3.2 KB
tests/test_ensure_schema_fastpath.pyscript4.4 KB
tests/test_evolution_guards.pyscript14.9 KB
tests/test_evolution_scripts.pyscript55.3 KB
tests/test_gate1_guidance.pyscript1.8 KB
tests/test_gate3_code_acceptance.pyscript13.5 KB
tests/test_graph_state_machine.pyscript16.0 KB
tests/test_guidance_readiness.pyscript2.2 KB
tests/test_health_check_signing_status.pyscript3.5 KB
tests/test_human_decision_trigger_enforcement.pyscript37.3 KB
tests/test_human_only_wiring.pyscript22.3 KB
tests/test_human_signer_isolation.pyscript4.0 KB
tests/test_identity_verification_readiness.pyscript5.8 KB
tests/test_implementation_ledger.pyscript3.4 KB
tests/test_implementation_loop.pyscript6.9 KB
tests/test_implementation_runtime_bridge.pyscript2.6 KB
tests/test_init_agentic_os_scaffolding.pyscript10.0 KB
tests/test_init_respects_control_plane_mode.pyscript4.3 KB
tests/test_inspect_verbs.pyscript3.6 KB
tests/test_installation_probe.pyscript3.1 KB
tests/test_intake_scenarios.pyscript7.2 KB
tests/test_interview_plan_outline.pyscript2.8 KB
tests/test_isolation_check.pyscript12.5 KB
tests/test_isolation_setup_docs.pyscript2.7 KB
tests/test_kernel_security.pyscript4.0 KB
tests/test_legacy_input_fallback.pyscript6.0 KB
tests/test_list_review_options.pyscript3.1 KB
tests/test_multi_agent_bundle_gate.pyscript5.5 KB
tests/test_one_approver_per_pipeline.pyscript15.8 KB
tests/test_os_init_dual_identity.pyscript3.9 KB
tests/test_os_init_identity_bootstrap.pyscript8.8 KB
tests/test_os_init_identity_status.pyscript3.9 KB
tests/test_os_init_single_instruction_file.pyscript7.3 KB
tests/test_p00_live_baseline.pyscript10.2 KB
tests/test_p01_intake_persistence.pyscript6.7 KB
tests/test_post_run_metrics_protocol.pyscript3.3 KB
tests/test_pre_commit_pipeline_guard.pyscript29.1 KB
tests/test_pre_push_review_guard.pyscript5.7 KB
tests/test_receipt_provenance.pyscript6.6 KB
tests/test_retrospective_pipeline.pyscript5.3 KB
tests/test_review_option_menus.pyscript6.6 KB
tests/test_review_selection.pyscript8.2 KB
tests/test_round3_fixes.pyscript8.3 KB
tests/test_rules_compliance.pyscript1.3 KB
tests/test_run_transition_simulation_formatting.pyscript1.7 KB
tests/test_run_verify_exit_bundle.pyscript10.2 KB
tests/test_setup_ciba_identity.pyscript11.2 KB
tests/test_signed_approval_human_receipt.pyscript3.9 KB
tests/test_signing_mechanics_selftest.pyscript6.9 KB
tests/test_signing_skill_selfcontained.pyscript3.4 KB
tests/test_skip_receipt_guidance.pyscript2.7 KB
tests/test_ssh_signing.pyscript23.9 KB
tests/test_strategy_artifacts.pyscript21.8 KB
tests/test_transition_answer_normalization.pyscript1.1 KB

scripts/evolution_state.py

View on GitHub
#!/usr/bin/env python
"""
evolution_state.py — Deterministic Controller for Graph-Planned Evolution
========================================================================

Purpose:
    Single authorized controller and state manager for autonomous self-evolution
    cycles in the Agentic OS. Enforces the 6-Node Graph State Machine DAG,
    advisory directory spinlocks, verifier sovereignty guards, pre-commit receipt
    gating, and Layer 2 asymmetric persistence worktree transfers.

Layer: OS Kernel / Evolution Controller

CLI Subcommands:
    init, plan, authorize, transition, record-verification, set-receipt,
    export-layer2, recover, status

Key Input Dependencies:
    - context/.evolution/<cycle-id>/state.json (per-cycle state file)
    - context/.locks/ (advisory spinlock directory)
"""

import argparse
import hashlib
import json
import os
import shutil
import subprocess
import sys
import tempfile
import time
from datetime import datetime, timezone
from pathlib import Path

SCHEMA_VERSION = "1.1.0"
MAX_ATTEMPTS = 3

DEFAULT_PROTECTED_SET = [
    "evaluate.py",
    "eval_runner.py",
    "plugins/agent-agentic-os/skills/improving-skills-in-lab/scripts/evaluate.py",
    "plugins/agent-agentic-os/skills/improving-skills-in-lab/scripts/eval_runner.py",
    ".agent/rules/self-evolution-policy.md",
    ".agent/rules/engineering-lifecycle-policy.md",
    "plugins/agent-agentic-os/rules/self-evolution-policy.md",
    "plugins/agent-agentic-os/rules/engineering-lifecycle-policy.md",
]

CANONICAL_NODES = [
    "TRIAGE", "PLAN", "AWAITING_APPROVAL", "AUTHORIZED", "CREATE_WORKTREE",
    "EXECUTE", "VERIFY_GATE", "PRE_COMMIT_RECEIPT", "COMMIT", "ROLLBACK",
    "FINAL_RECEIPT", "COMPLETED", "ESCALATED", "RECOVERY_REQUIRED"
]

STATUS_ENUMS = [
    "IN_PROGRESS", "AWAITING_APPROVAL", "COMMITTED", "ROLLED_BACK",
    "ESCALATED", "RECOVERY_REQUIRED"
]

VALID_DAG = {
    "TRIAGE": ["PLAN", "ESCALATED"],
    "PLAN": ["AWAITING_APPROVAL", "ESCALATED"],
    "AWAITING_APPROVAL": ["AUTHORIZED", "ESCALATED"],
    "AUTHORIZED": ["CREATE_WORKTREE", "ESCALATED"],
    "CREATE_WORKTREE": ["EXECUTE", "ESCALATED"],
    "EXECUTE": ["VERIFY_GATE", "ESCALATED"],
    "VERIFY_GATE": ["PRE_COMMIT_RECEIPT", "PLAN", "ROLLBACK", "ESCALATED"],
    "PRE_COMMIT_RECEIPT": ["COMMIT", "ESCALATED"],
    "COMMIT": ["FINAL_RECEIPT", "ESCALATED"],
    "ROLLBACK": ["FINAL_RECEIPT", "ESCALATED"],
    "FINAL_RECEIPT": ["COMPLETED", "ESCALATED"],
    "COMPLETED": [],
    "ESCALATED": [],
    "RECOVERY_REQUIRED": ["TRIAGE"]
}


def _now():
    """Return the current UTC time as an ISO-8601 string."""
    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")


def _get_repo_root(repo_dir: Path = None) -> Path:
    """Resolve the repo root, defaulting to the git toplevel of the cwd."""
    if repo_dir:
        return repo_dir.resolve()
    try:
        res = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=True)
        return Path(res.stdout.strip()).resolve()
    except Exception:
        return Path.cwd().resolve()


def _get_git_head(repo_root: Path) -> str:
    """Return the current git HEAD commit SHA for repo_root."""
    try:
        res = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo_root, capture_output=True, text=True, check=True)
        return res.stdout.strip()
    except Exception:
        return "0000000000000000000000000000000000000000"


def _state_file_path(repo_root: Path) -> Path:
    """Return the path to the per-cycle evolution state JSON file."""
    return repo_root / ".agent" / "learning" / "evolution_state.json"


def _lock_dir_path(repo_root: Path) -> Path:
    """Return the path to the advisory lock directory for this repo."""
    return repo_root / ".agent" / "learning" / "evolution.lock"


def _pid_alive(pid: int) -> bool:
    """Return True if a process with the given pid is currently running."""
    try:
        os.kill(int(pid), 0)
        return True
    except (ProcessLookupError, ValueError):
        return False
    except PermissionError:
        return True


def _acquire_lock(repo_root: Path, timeout: int = 2, ttl: int = 1800) -> bool:
    """Acquire the advisory evolution spinlock, waiting up to timeout seconds."""
    lock_dir = _lock_dir_path(repo_root)
    lock_dir.parent.mkdir(parents=True, exist_ok=True)
    deadline = time.time() + timeout

    while time.time() <= deadline:
        try:
            os.mkdir(lock_dir)
            meta = {
                "pid": os.getpid(),
                "acquired_at": _now(),
                "expires_at": time.time() + ttl,
                "ttl": ttl
            }
            (lock_dir / "meta.json").write_text(json.dumps(meta), encoding="utf-8")
            return True
        except FileExistsError:
            # Check staleness
            meta_file = lock_dir / "meta.json"
            is_stale = False
            if meta_file.exists():
                try:
                    meta = json.loads(meta_file.read_text(encoding="utf-8"))
                    if not _pid_alive(meta.get("pid", 0)) or meta.get("expires_at", 0) < time.time():
                        is_stale = True
                except Exception:
                    is_stale = True
            else:
                is_stale = True

            if is_stale:
                try:
                    for item in lock_dir.iterdir():
                        item.unlink()
                    os.rmdir(lock_dir)
                    continue
                except OSError:
                    pass
            time.sleep(0.05)
    return False


def _release_lock(repo_root: Path):
    """Release the advisory evolution spinlock for this repo."""
    lock_dir = _lock_dir_path(repo_root)
    if lock_dir.exists():
        try:
            for item in lock_dir.iterdir():
                item.unlink()
            os.rmdir(lock_dir)
        except OSError:
            pass


def _atomic_write_json(file_path: Path, data: dict):
    """Write data as JSON to file_path atomically (write-then-rename)."""
    file_path.parent.mkdir(parents=True, exist_ok=True)
    with tempfile.NamedTemporaryFile(dir=file_path.parent, delete=False, mode="w", encoding="utf-8") as tf:
        json.dump(data, tf, indent=2)
        tf.flush()
        os.fsync(tf.fileno())
        temp_name = tf.name
    os.replace(temp_name, file_path)


def _load_state(repo_root: Path) -> dict:
    """Load and return the current cycle's state dict from disk."""
    p = _state_file_path(repo_root)
    if not p.exists():
        print(f"Error: Evolution state file not found at {p}", file=sys.stderr)
        sys.exit(1)
    with open(p, "r", encoding="utf-8") as f:
        return json.load(f)


def _file_hash(p: Path) -> str:
    """Return the SHA-256 hex digest of the file at path p."""
    if not p.exists():
        return ""
    h = hashlib.sha256()
    with open(p, "rb") as f:
        while chunk := f.read(65536):
            h.update(chunk)
    return h.hexdigest()


def _check_verifier_sovereignty(repo_root: Path, state: dict):
    """Verify no locked verifier file was modified since the cycle began."""
    # 1. Check default baseline hashes
    default_baseline = state.get("default_baseline_hashes", {})
    for p_str, expected_hash in default_baseline.items():
        curr_hash = _file_hash(repo_root / p_str)
        if expected_hash and curr_hash != expected_hash:
            print(f"SECURITY ALERT: Verifier sovereignty violation! Protected baseline file {p_str} modified.", file=sys.stderr)
            sys.exit(2)

    # 2. Check manifest-declared verifier files
    manifest = state.get("transaction_manifest", {})
    verifier_files = manifest.get("verifier_files", [])
    recorded_hashes = manifest.get("verifier_hashes", {})
    
    for v_rel in verifier_files:
        v_path = repo_root / v_rel
        curr_hash = _file_hash(v_path)
        expected_hash = recorded_hashes.get(v_rel)
        if expected_hash and curr_hash != expected_hash:
            print(f"SECURITY ALERT: Verifier sovereignty violation! {v_rel} modified.", file=sys.stderr)
            sys.exit(2)


# ============================================================================
# Command Handlers
# ============================================================================

def cmd_init(args):
    """CLI: initialize a new evolution cycle and write its state file."""
    repo_root = _get_repo_root(args.repo_dir)

    # Check if a cycle is already active in evolution_state.json
    state_file = _state_file_path(repo_root)
    if state_file.exists():
        try:
            existing_state = json.loads(state_file.read_text(encoding="utf-8"))
            if existing_state.get("status") == "IN_PROGRESS":
                print(f"Error: An evolution cycle is already in progress (lock held): {existing_state.get('cycle_id')}", file=sys.stderr)
                sys.exit(1)
        except Exception:
            pass

    if not _acquire_lock(repo_root):
        print(f"Error: Could not acquire lock at {_lock_dir_path(repo_root)} (another process active)", file=sys.stderr)
        sys.exit(1)

    initial_head = _get_git_head(repo_root)
    
    # Record baseline hashes for DEFAULT_PROTECTED_SET
    default_baseline = {}
    for p_str in DEFAULT_PROTECTED_SET:
        p = repo_root / p_str
        if p.exists():
            default_baseline[p_str] = _file_hash(p)

    state = {
        "schema_version": SCHEMA_VERSION,
        "cycle_id": args.cycle_id,
        "lock_pid": os.getpid(),
        "current_node": "TRIAGE",
        "status": "IN_PROGRESS",
        "attempt_count": 0,
        "max_attempts": MAX_ATTEMPTS,
        "tier": args.tier,
        "initial_git_head": initial_head,
        "worktree_path": None,
        "authorization": {
            "status": "PENDING",
            "cycle_id": args.cycle_id,
            "plan_hash_sha256": None,
            "transaction_manifest_hash_sha256": None,
            "verifier_identity_sha256": None,
            "authorized_operations": [],
            "authorized_at": None
        },
        "default_baseline_hashes": default_baseline,
        "transaction_manifest": {},
        "baseline_untracked_files": [],
        "owned_tracked_files": [],
        "owned_untracked_files": [],
        "wiki_files": [],
        "event_ids": [],
        "last_verification_exit_code": None,
        "verification_provenance": None,
        "pre_commit_receipt_token": None,
        "final_receipt_token": None
    }
    _atomic_write_json(_state_file_path(repo_root), state)
    print(f"Initialized evolution cycle {args.cycle_id} in TRIAGE mode.")


def cmd_plan(args):
    """CLI: record the read-only proposal plan for the current cycle."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    
    manifest_data = {}
    if args.manifest:
        p = Path(args.manifest).resolve()
        if p.exists():
            manifest_data = json.loads(p.read_text(encoding="utf-8"))
    
    # Calculate verifier hashes (manifest files + default protected files)
    verifier_files = list(manifest_data.get("verifier_files", []))
    for p_str in DEFAULT_PROTECTED_SET:
        if (repo_root / p_str).exists() and p_str not in verifier_files:
            verifier_files.append(p_str)
    manifest_data["verifier_files"] = verifier_files

    verifier_hashes = {}
    for vf in verifier_files:
        v_path = repo_root / vf
        if v_path.exists():
            verifier_hashes[vf] = _file_hash(v_path)
    manifest_data["verifier_hashes"] = verifier_hashes

    # Re-plan invalidates authorization on manifest hash mismatch
    manifest_json = json.dumps(manifest_data, sort_keys=True)
    new_manifest_hash = hashlib.sha256(manifest_json.encode("utf-8")).hexdigest()
    auth = state.get("authorization", {})
    if auth.get("status") == "GRANTED":
        if auth.get("transaction_manifest_hash_sha256") != new_manifest_hash:
            auth["status"] = "INVALIDATED"
            state["authorization"] = auth

    state["transaction_manifest"] = manifest_data
    state["current_node"] = "PLAN"
    _atomic_write_json(_state_file_path(repo_root), state)
    print("Plan and transaction manifest recorded.")


def cmd_authorize(args):
    """CLI: transition the cycle from AWAITING_APPROVAL to AUTHORIZED."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    
    if state["cycle_id"] != args.cycle_id:
        print(f"Error: cycle_id mismatch: expected {state['cycle_id']}, got {args.cycle_id}", file=sys.stderr)
        sys.exit(1)

    ops = [op.strip() for op in args.operations.split(",") if op.strip()]
    state["authorization"] = {
        "status": "GRANTED",
        "cycle_id": args.cycle_id,
        "plan_hash_sha256": args.plan_hash,
        "transaction_manifest_hash_sha256": hashlib.sha256(json.dumps(state.get("transaction_manifest", {}), sort_keys=True).encode("utf-8")).hexdigest(),
        "verifier_identity_sha256": None,
        "authorized_operations": ops,
        "authorized_at": _now()
    }
    state["current_node"] = "AUTHORIZED"
    _atomic_write_json(_state_file_path(repo_root), state)
    print(f"Cycle {args.cycle_id} authorized with operations: {ops}")


def cmd_transition(args):
    """CLI: advance the cycle's state machine node, enforcing valid transitions."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    target_node = args.to

    if target_node not in CANONICAL_NODES:
        print(f"Error: Unknown node {target_node}", file=sys.stderr)
        sys.exit(1)

    current_node = state.get("current_node", "TRIAGE")
    valid_targets = VALID_DAG.get(current_node, [])

    if target_node not in valid_targets:
        print(f"Illegal transition from {current_node} to {target_node}", file=sys.stderr)
        sys.exit(1)

    # Machine-enforced attempt ceiling: Cannot loop back to PLAN if attempt_count >= MAX_ATTEMPTS
    if target_node == "PLAN" and current_node == "VERIFY_GATE":
        if state.get("attempt_count", 0) >= MAX_ATTEMPTS:
            print(f"Error: Attempt ceiling reached ({MAX_ATTEMPTS} attempts max). Cannot transition to PLAN; must ROLLBACK.", file=sys.stderr)
            sys.exit(1)

    # Proposal Mode Guard: Cannot transition to CREATE_WORKTREE without GRANTED authorization
    if target_node == "CREATE_WORKTREE":
        if state.get("authorization", {}).get("status") != "GRANTED":
            print(f"Authorization required: Cannot transition to CREATE_WORKTREE without explicit user authorization (status={state.get('authorization', {}).get('status')}).", file=sys.stderr)
            sys.exit(1)
        _check_verifier_sovereignty(repo_root, state)
        # Persist where the caller's `git worktree add` actually put the sandbox, so `verify`
        # (and any future commit step) execute against the mutated copy, not the main checkout.
        # Existence is not required here -- the caller may create the worktree immediately after
        # this transition returns.
        worktree_path = getattr(args, "worktree_path", None)
        if worktree_path is not None:
            state["worktree_path"] = str(Path(worktree_path).resolve())

    # Verifier Sovereignty Guard on EXECUTE
    if target_node == "EXECUTE":
        _check_verifier_sovereignty(repo_root, state)
        state["attempt_count"] = state.get("attempt_count", 0) + 1

    # Transition to PRE_COMMIT_RECEIPT: Must have executed verifier with exit code 0 and controller provenance
    if target_node == "PRE_COMMIT_RECEIPT":
        _check_verifier_sovereignty(repo_root, state)
        prov = state.get("verification_provenance")
        if (not isinstance(prov, dict)
                or prov.get("source") != "controller"
                or prov.get("attempt") != state.get("attempt_count")
                or prov.get("exit_code") != 0):
            print(
                "Verification gate violation: no controller-executed PASS for the current attempt. "
                "Self-reported exit codes cannot drive PRE_COMMIT_RECEIPT.",
                file=sys.stderr,
            )
            sys.exit(1)

    # Pre-Commit Receipt Guard: Cannot transition to COMMIT without token and commit permission
    if target_node == "COMMIT":
        auth_ops = state.get("authorization", {}).get("authorized_operations", [])
        if "commit" not in auth_ops:
            print("Authorization violation: 'commit' is not in authorized_operations.", file=sys.stderr)
            sys.exit(1)
        token = state.get("pre_commit_receipt_token")
        if not token:
            print("Integrity gate violation: pre_commit_receipt_token is required before transition to COMMIT.", file=sys.stderr)
            sys.exit(1)

        # Cryptographic re-verification against git write-tree and event chain.
        # Must recompute the staged tree in the same directory the pre-commit token was
        # generated against (the worktree, when one is recorded) -- otherwise this always
        # mismatches for any cycle that mutates inside an isolated worktree.
        script_dir = Path(__file__).resolve().parent
        if str(script_dir) not in sys.path:
            sys.path.insert(0, str(script_dir))
        try:
            import verify_evolution_receipt
            tree_exec_dir = repo_root
            if state.get("worktree_path") and Path(state["worktree_path"]).exists():
                tree_exec_dir = Path(state["worktree_path"])
            recompute_tree_sha = subprocess.run(
                ["git", "write-tree"], cwd=tree_exec_dir, capture_output=True, text=True
            ).stdout.strip()
            actual = verify_evolution_receipt.compute_receipt(repo_root, state["cycle_id"], tree_sha=recompute_tree_sha)
            if token != actual.get("receipt_token"):
                print(f"Integrity gate violation: pre_commit_receipt_token mismatch! Stored: {token}, Recomputed: {actual.get('receipt_token')}", file=sys.stderr)
                sys.exit(1)
        except Exception as e:
            print(f"Integrity gate violation: Receipt cryptographic verification error: {e}", file=sys.stderr)
            sys.exit(1)

    state["current_node"] = target_node
    if target_node == "AWAITING_APPROVAL":
        state["status"] = "AWAITING_APPROVAL"
    elif target_node == "COMPLETED":
        state["status"] = "COMMITTED"
        _release_lock(repo_root)
    elif target_node == "ESCALATED":
        state["status"] = "ESCALATED"
        _release_lock(repo_root)
    elif target_node == "ROLLBACK":
        state["status"] = "ROLLED_BACK"

    _atomic_write_json(_state_file_path(repo_root), state)
    print(f"Transitioned to node: {target_node}")


def cmd_verify(args):
    """CLI: record the verifier's exit code and outcome for the current cycle."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    _check_verifier_sovereignty(repo_root, state)

    manifest = state.get("transaction_manifest", {})
    verifier_argv = manifest.get("verifier_argv", [])
    if not verifier_argv:
        print("Error: No verifier_argv declared in transaction_manifest", file=sys.stderr)
        sys.exit(1)

    exec_dir = repo_root
    if state.get("worktree_path"):
        wt = Path(state["worktree_path"])
        if not wt.exists():
            print(f"Verify error: worktree_path {wt} does not exist", file=sys.stderr)
            sys.exit(1)
        exec_dir = wt

    print(f"Controller executing verifier: {verifier_argv} in {exec_dir}")
    res = subprocess.run(verifier_argv, cwd=exec_dir, capture_output=True, text=True)
    exit_code = res.returncode
    state["last_verification_exit_code"] = exit_code

    # V1: stamp controller-owned provenance. Only `verify` may write this block.
    state["verification_provenance"] = {
        "source": "controller",
        "attempt": state.get("attempt_count", 0),
        "exit_code": exit_code,
        "verifier_argv_sha256": hashlib.sha256(
            json.dumps(verifier_argv, sort_keys=True).encode("utf-8")
        ).hexdigest(),
        "at": _now(),
    }

    # Check sovereignty after execution
    _check_verifier_sovereignty(repo_root, state)

    _atomic_write_json(_state_file_path(repo_root), state)
    print(f"Controller executed verifier: exit code: {exit_code}")
    if exit_code != 0:
        if res.stdout:
            print(f"Verifier stdout: {res.stdout[:500]}", file=sys.stderr)
        if res.stderr:
            print(f"Verifier stderr: {res.stderr[:500]}", file=sys.stderr)
        sys.exit(exit_code)


def cmd_record_verification(args):
    """CLI: append a verification result entry to the cycle's audit trail."""
    # V1: NON-AUTHORITATIVE. Retained only so old call sites do not hard-crash.
    # It MUST NOT write last_verification_exit_code or verification_provenance.
    # Only `verify` (controller-executed) can drive VERIFY_GATE -> PRE_COMMIT_RECEIPT.
    print(
        "Warning: 'record-verification' is non-authoritative and cannot drive the gate. "
        "Use 'verify' so the controller executes the declared verifier itself.",
        file=sys.stderr,
    )
    sys.exit(0)


def cmd_set_receipt(args):
    """CLI: attach a pre-commit or final receipt hash to the cycle state."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    if args.stage == "pre-commit":
        state["pre_commit_receipt_token"] = args.token
    elif args.stage == "final":
        state["final_receipt_token"] = args.token
    _atomic_write_json(_state_file_path(repo_root), state)
    print(f"Receipt token set for stage '{args.stage}': {args.token}")


def _copy_layer2(from_wt: Path, dest: Path):
    """Copy Layer 2 wiki/debt artifacts from the worktree to the main checkout."""
    # wiki/
    wt_wiki = from_wt / "wiki"
    if wt_wiki.exists():
        dest_wiki = dest / "wiki"
        dest_wiki.mkdir(parents=True, exist_ok=True)
        for root, _, files in os.walk(wt_wiki):
            rel_root = Path(root).relative_to(wt_wiki)
            target_dir = dest_wiki / rel_root
            target_dir.mkdir(parents=True, exist_ok=True)
            for f in files:
                shutil.copy2(Path(root) / f, target_dir / f)
    # map-debt.md and evolution-log.md, wherever they live in the worktree
    for ref_name in ["map-debt.md", "evolution-log.md"]:
        for cand in from_wt.glob(f"**/{ref_name}"):
            rel_path = cand.relative_to(from_wt)
            target_file = dest / rel_path
            target_file.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(cand, target_file)


def cmd_export_layer2(args):
    """CLI: export Layer 2 durable learnings from the worktree before teardown."""
    from_wt = Path(args.from_worktree).resolve()
    to_main = Path(args.to_main).resolve()
    if not from_wt.exists():
        print(f"Error: Worktree path {from_wt} does not exist", file=sys.stderr)
        sys.exit(1)

    if not getattr(args, "commit_knowledge", False):
        # Legacy preview / non-git use: working-tree copy only, no commit.
        _copy_layer2(from_wt, to_main)
        print("Layer 2 artifacts copied to main checkout (working-tree only, no commit).")
        return

    # V2: durable persistence WITHOUT committing to main.
    cycle_id = args.cycle_id
    if not cycle_id:
        state_file = _state_file_path(to_main)
        if state_file.exists():
            try:
                cycle_id = json.loads(state_file.read_text(encoding="utf-8")).get("cycle_id")
            except Exception:
                cycle_id = None
    if not cycle_id:
        print("Error: --cycle-id required for --commit-knowledge", file=sys.stderr)
        sys.exit(1)

    branch = f"knowledge/{cycle_id}"
    kt = to_main.parent / f"knowledge-wt-{cycle_id}"

    # Create a dedicated branch + isolated worktree at current HEAD.
    res = subprocess.run(
        ["git", "worktree", "add", "-b", branch, str(kt), "HEAD"],
        cwd=to_main, capture_output=True, text=True,
    )
    if res.returncode != 0:
        print(f"Error: could not create knowledge worktree/branch: {res.stderr}", file=sys.stderr)
        sys.exit(1)
    try:
        _copy_layer2(from_wt, kt)
        subprocess.run(["git", "add", "-A"], cwd=kt, check=True, capture_output=True)
        st = subprocess.run(["git", "diff", "--cached", "--name-only"], cwd=kt,
                            capture_output=True, text=True)
        if not st.stdout.strip():
            print("Warning: no Layer 2 artifacts to commit.", file=sys.stderr)
        else:
            subprocess.run(
                ["git", "commit", "-m",
                 f"knowledge({cycle_id}): persist Layer 2 evolution insights [skip ci]"],
                cwd=kt, check=True, capture_output=True,
            )
    finally:
        subprocess.run(["git", "worktree", "remove", "--force", str(kt)],
                       cwd=to_main, capture_output=True)
    print(f"Layer 2 committed to branch '{branch}'. Main working tree and HEAD untouched.")


def cmd_recover(args):
    """CLI: attempt to recover a cycle stuck in an inconsistent state."""
    repo_root = _get_repo_root(args.repo_dir)
    state_file = _state_file_path(repo_root)
    if not state_file.exists():
        print("No evolution state to recover.", file=sys.stderr)
        sys.exit(0)

    state = _load_state(repo_root)

    # Check git status for uncommitted/unrecorded changes
    git_status = subprocess.run(["git", "status", "--porcelain"], cwd=repo_root, capture_output=True, text=True)
    dirty_lines = [l.strip() for l in git_status.stdout.split("\n") if l.strip()]

    # Filter out internal .agent/ state files
    untracked_unknown = False
    for l in dirty_lines:
        path_str = l[3:].strip()
        if not (path_str.startswith(".agent/") or path_str == ".agent" or path_str.startswith(".agent")):
            untracked_unknown = True
            break

    if untracked_unknown:
        state["current_node"] = "RECOVERY_REQUIRED"
        state["status"] = "RECOVERY_REQUIRED"
        _atomic_write_json(state_file, state)
        print("Ambiguous or dirty git state detected during recovery: Set to RECOVERY_REQUIRED.")
        return

    # Check traces
    traces_file = repo_root / ".agent" / "learning" / "traces" / "cycle_manifests.jsonl"
    events = []
    if traces_file.exists():
        for l in traces_file.read_text(encoding="utf-8").strip().split("\n"):
            if l.strip():
                try:
                    events.append(json.loads(l))
                except Exception:
                    pass

    event_types = [e.get("event_type") for e in events]
    if "mutation.completed" in event_types:
        state["current_node"] = "VERIFY_GATE"
        state["status"] = "IN_PROGRESS"
        _atomic_write_json(state_file, state)
        print("Recovered to VERIFY_GATE.")
    else:
        state["current_node"] = "TRIAGE"
        state["status"] = "IN_PROGRESS"
        _atomic_write_json(state_file, state)
        print("Recovered cleanly to TRIAGE.")


def cmd_status(args):
    """CLI: print the current cycle's state and node for inspection."""
    repo_root = _get_repo_root(args.repo_dir)
    state = _load_state(repo_root)
    print(json.dumps(state, indent=2))


def main():
    """CLI entry point: parse args and dispatch to the matching cmd_* handler."""
    parser = argparse.ArgumentParser(description="Evolution State Controller")
    subparsers = parser.add_subparsers(dest="command", required=True)

    # init
    p_init = subparsers.add_parser("init")
    p_init.add_argument("--cycle-id", required=True)
    p_init.add_argument("--tier", default="Tier 2")
    p_init.add_argument("--repo-dir", type=Path, default=None)

    # plan
    p_plan = subparsers.add_parser("plan")
    p_plan.add_argument("--manifest", default=None)
    p_plan.add_argument("--repo-dir", type=Path, default=None)

    # authorize
    p_auth = subparsers.add_parser("authorize")
    p_auth.add_argument("--cycle-id", required=True)
    p_auth.add_argument("--plan-hash", default=None)
    p_auth.add_argument("--operations", default="create_worktree,mutate,verify,write_layer2,commit")
    p_auth.add_argument("--repo-dir", type=Path, default=None)

    # transition
    p_trans = subparsers.add_parser("transition")
    p_trans.add_argument("--to", required=True)
    p_trans.add_argument("--repo-dir", type=Path, default=None)
    p_trans.add_argument("--worktree-path", type=Path, default=None)

    # verify
    p_ver = subparsers.add_parser("verify")
    p_ver.add_argument("--repo-dir", type=Path, default=None)

    # record-verification
    p_rec = subparsers.add_parser("record-verification")
    p_rec.add_argument("--exit-code", type=int, required=True)
    p_rec.add_argument("--repo-dir", type=Path, default=None)

    # set-receipt
    p_recp = subparsers.add_parser("set-receipt")
    p_recp.add_argument("--stage", choices=["pre-commit", "final"], required=True)
    p_recp.add_argument("--token", required=True)
    p_recp.add_argument("--repo-dir", type=Path, default=None)

    # export-layer2
    p_exp = subparsers.add_parser("export-layer2")
    p_exp.add_argument("--from-worktree", required=True)
    p_exp.add_argument("--to-main", required=True)
    p_exp.add_argument("--cycle-id", default=None)
    p_exp.add_argument("--commit-knowledge", action="store_true", default=False)

    # recover
    p_recov = subparsers.add_parser("recover")
    p_recov.add_argument("--repo-dir", type=Path, default=None)

    # status
    p_stat = subparsers.add_parser("status")
    p_stat.add_argument("--repo-dir", type=Path, default=None)

    args = parser.parse_args()

    dispatch = {
        "init": cmd_init,
        "plan": cmd_plan,
        "authorize": cmd_authorize,
        "transition": cmd_transition,
        "verify": cmd_verify,
        "record-verification": cmd_record_verification,
        "set-receipt": cmd_set_receipt,
        "export-layer2": cmd_export_layer2,
        "recover": cmd_recover,
        "status": cmd_status
    }
    dispatch[args.command](args)


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall