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/control_plane/registry.py

View on GitHub
"""
control_plane/registry.py — TransitionRegistry Domain Component (issue-529 Slice 1)
=====================================================================================

Purpose:
    Loads, schema-validates, and serves the single authoritative transition registry
    (), enforcing 1:1 bidirectional parity with
    state_machine.ALLOWED_TRANSITIONS (edge count derived from that table at
    runtime, not a fixed literal — see test_registry_covers_every_allowed_edge).

Layer:
    OS Kernel / Execution Control Plane Substrate — Registry (domain layer)

Key Input Dependencies:
    - control_plane/transition_templates.yaml (the single authoritative registry
      loaded by load_default()/load_from_file()) — each entry's field set is
      validated against REQUIRED_TEMPLATE_FIELDS.
    - control_plane/state_machine.py's ALLOWED_TRANSITIONS/CANONICAL_STATES — every
      loaded template must have exactly one matching (from_state, to_state) edge.

Key Functions:
    - TransitionRegistryError — raised on a missing/malformed/schema-violating YAML.
    - REQUIRED_TEMPLATE_FIELDS — the field set every template entry must declare.
    - TransitionTemplate — dataclass for one validated transition's full template.
    - TransitionRegistry — loads and serves the registry:
        - get_template()/get_template_by_id() — look up one template.
        - get_all_templates()/get_all_edges()/get_all_declared_check_ids() —
          registry-wide views.
        - get_edges_releasing_capability()/get_legal_next_states() — capability and
          adjacency queries.
        - get_transition_guidance() — builds the human-readable advisory guidance
          block for one edge (purpose, checklist, next steps).
        - get_stage_contract()/get_stage_question() — per-state question contracts.
        - load_from_file()/load_default() — construct a validated registry from a
          given YAML path, or the canonical transition_templates.yaml.
"""

import hashlib
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Dict, List, Optional, Set, Tuple
import yaml

from control_plane.state_machine import ALLOWED_TRANSITIONS, CANONICAL_STATES
from control_plane.constants import AGENT_CONTROL_CMD, CONTROL_SCRIPTS_DIR, AUTHORIZED_ACTOR_HUMAN_ONLY, AUTHORIZED_ACTOR_AGENT_OR_HUMAN

# load_default() memo: {sha256 of the YAML bytes: parsed registry}; see TransitionRegistry.load_default().
_DEFAULT_REGISTRY_CACHE: Dict[str, "TransitionRegistry"] = {}


class TransitionRegistryError(Exception):
    """Raised when transition_templates.yaml is missing, malformed, or violates schema."""
    pass


REQUIRED_TEMPLATE_FIELDS = [
    "transition_id",
    "from_state",
    "to_state",
    "purpose",
    "checklist",
    "required_artifacts",
    "deterministic_checks",
    "human_questions",
    "approval",
    "skip",
    "authority",
    "capabilities_released",
    "capabilities_prohibited",
    "denial_message",
    "next_steps_hint",
]

TRANSITION_GUIDANCE_SCHEMA_VERSION = "transition-guidance-v1"
EXECUTION_GUIDANCE_UNITS = (
    "work_package",
    "task",
    "slice",
    "transition",
    "execution_step",
)
EXECUTION_GUIDANCE_FIELDS = (
    "objective",
    "scope_boundary",
    "prerequisites",
    "authority",
    "expected_artifacts",
    "validation_command",
    "completion_evidence",
    "handoff_condition",
    "failure_recovery",
)


@dataclass(frozen=True)
class TransitionTemplate:
    transition_id: str
    from_state: str
    to_state: str
    purpose: str
    checklist: List[str]
    required_artifacts: List[str]
    deterministic_checks: List[str]
    human_questions: List[Dict[str, Any]]
    approval: Dict[str, Any]
    skip: Dict[str, Any]
    authority: Dict[str, Any]
    capabilities_released: List[str]
    capabilities_prohibited: List[str]
    denial_message: str
    next_steps_hint: str = ""
    failure_recovery: str = ""
    stage_question_ids: List[str] = None
    stage_route: Optional[Dict[str, Any]] = None
    guidance: Optional[Dict[str, Any]] = None
    # True on every edge into APPROVED, VERIFY_EXIT and DONE: only a verified OpenSSH signature over a
    # content-bound transition_request (consumed in the commit transaction) may commit it.
    requires_cryptographic_proof: bool = False

    @property
    def authorized_actor(self) -> str:
        """Derived, not a hand-maintained parallel field (round-1 review finding,
        auth-ciba-poc-transition-mechanics): 'human_only' iff this edge's own
        approval block requires human approval, otherwise 'agent_or_human'.
        An edge declaring requires_cryptographic_proof is always 'human_only'
        (checked first below): closure edges into DONE take a human signature,
        not a FORCE_CLOSE/FORCE_DONE literal, so they no longer derive as
        'agent_or_human' (changed 2026-09-20)."""
        if self.requires_cryptographic_proof:
            return AUTHORIZED_ACTOR_HUMAN_ONLY
        return (
            AUTHORIZED_ACTOR_HUMAN_ONLY
            if self.approval.get("required") and self.approval.get("approver_role", "human") == "human"
            else AUTHORIZED_ACTOR_AGENT_OR_HUMAN
        )

    def to_dict(self) -> Dict[str, Any]:
        return {
            "transition_id": self.transition_id,
            "from_state": self.from_state,
            "to_state": self.to_state,
            "purpose": self.purpose,
            "checklist": list(self.checklist),
            "required_artifacts": list(self.required_artifacts),
            "deterministic_checks": list(self.deterministic_checks),
            "human_questions": list(self.human_questions),
            "approval": dict(self.approval),
            "skip": dict(self.skip),
            "authority": dict(self.authority),
            "capabilities_released": list(self.capabilities_released),
            "capabilities_prohibited": list(self.capabilities_prohibited),
            "denial_message": self.denial_message,
            "next_steps_hint": self.next_steps_hint,
            "failure_recovery": self.failure_recovery,
            "stage_question_ids": list(self.stage_question_ids or []),
            "stage_route": dict(self.stage_route or {}),
            "guidance": dict(self.guidance or {}),
        }


EXECUTION_CLASS_AGENT = "AGENT"
EXECUTION_CLASS_SOFT = "SOFT"
EXECUTION_CLASS_HARD = "HARD"

EXECUTION_CLASS_INSTRUCTIONS = {
    EXECUTION_CLASS_AGENT: "You (the agent) run this once the human has said go in chat. Put their words in --human-confirmed. There is no question to ask.",
    EXECUTION_CLASS_SOFT: "Ask the human in chat, then you run this. Do not hand the command to the human.",
    EXECUTION_CLASS_HARD: "Only the human can run this. Give them the complete command; you cannot run it.",
}


def classify_edge(template: TransitionTemplate) -> Tuple[str, str, str]:
    """Return (run_by, basis, why) for one registry template.

    Rules, in order: signed edge -> HARD/crypto; human_only -> HARD/policy;
    has human questions -> SOFT; otherwise AGENT.
    """
    if template.requires_cryptographic_proof:
        return EXECUTION_CLASS_HARD, "crypto", "Needs the human's SSH signature (passphrase prompt); no typed word or flag can replace it."
    if template.authorized_actor == AUTHORIZED_ACTOR_HUMAN_ONLY:
        return EXECUTION_CLASS_HARD, "policy", "Repo policy reserves this human-typed decision to the human."
    if template.human_questions:
        return EXECUTION_CLASS_SOFT, "none", "Has a human question: the human answers in chat, then the agent runs the edge."
    return EXECUTION_CLASS_AGENT, "none", "Deterministic checks only; no human decision is needed."


class TransitionRegistry:
    """Authoritative registry for all transition templates loaded from YAML."""

    def __init__(
        self,
        templates: List[TransitionTemplate],
        stage_contracts: Optional[Dict[str, Dict[str, Any]]] = None,
        execution_guidance: Optional[Dict[str, Dict[str, Any]]] = None,
        model_effort_guidance: Optional[Dict[str, Dict[str, Any]]] = None,
        strategy_artifacts: Optional[Dict[str, Dict[str, Any]]] = None,
    ):
        self._templates_by_edge: Dict[Tuple[str, str], TransitionTemplate] = {}
        self._templates_by_id: Dict[str, TransitionTemplate] = {}
        self._capability_to_edges: Dict[str, List[Tuple[str, str]]] = {}
        self._stage_contracts = dict(stage_contracts or {})
        self._execution_guidance = dict(execution_guidance or {})
        self._model_effort_guidance = dict(model_effort_guidance or {})
        self._strategy_artifacts = dict(strategy_artifacts or {})

        for t in templates:
            edge = (t.from_state, t.to_state)
            if edge in self._templates_by_edge:
                raise TransitionRegistryError(f"Duplicate edge in templates: {edge}")
            if t.transition_id in self._templates_by_id:
                raise TransitionRegistryError(f"Duplicate transition_id: {t.transition_id}")

            self._templates_by_edge[edge] = t
            self._templates_by_id[t.transition_id] = t

            for cap in t.capabilities_released:
                self._capability_to_edges.setdefault(cap, []).append(edge)

    def __len__(self) -> int:
        return len(self._templates_by_edge)

    def get_template(self, from_state: str, to_state: str) -> Optional[TransitionTemplate]:
        return self._templates_by_edge.get((from_state, to_state))

    def get_template_by_id(self, transition_id: str) -> Optional[TransitionTemplate]:
        return self._templates_by_id.get(transition_id)

    def get_all_templates(self) -> List[TransitionTemplate]:
        return list(self._templates_by_edge.values())

    def get_all_edges(self) -> Set[Tuple[str, str]]:
        return set(self._templates_by_edge.keys())

    def get_all_edges_with_proof(self) -> List[Tuple[str, str, str, int]]:
        """(from, to, authorized_actor, requires_proof 0/1) per edge; synced into valid_transitions."""
        return [
            (from_s, to_s, tmpl.authorized_actor, 1 if tmpl.requires_cryptographic_proof else 0)
            for (from_s, to_s), tmpl in self._templates_by_edge.items()
        ]

    def proof_required_edges(self) -> frozenset:
        """The edges whose template declares requires_cryptographic_proof (the single source of truth)."""
        return frozenset(edge for edge, tmpl in self._templates_by_edge.items() if tmpl.requires_cryptographic_proof)

    def get_all_edges_with_actor(self) -> List[Tuple[str, str, str]]:
        """Same edges as get_all_edges(), paired with each template's derived
        authorized_actor. Added for auth-ciba-poc-transition-mechanics (T1);
        kept separate from get_all_edges() to avoid changing that method's
        existing return shape for its one existing caller."""
        return [
            (from_s, to_s, tmpl.authorized_actor)
            for (from_s, to_s), tmpl in self._templates_by_edge.items()
        ]

    def get_all_declared_check_ids(self) -> Set[str]:
        check_ids: Set[str] = set()
        for t in self._templates_by_edge.values():
            for c in t.deterministic_checks:
                check_ids.add(c)
        return check_ids

    @property
    def strategy_artifacts(self) -> Dict[str, Dict[str, Any]]:
        return dict(self._strategy_artifacts)

    def get_strategy_artifact_config(self, strategy: str) -> Optional[Dict[str, Any]]:
        return self._strategy_artifacts.get(strategy)

    def get_edges_releasing_capability(self, capability: str) -> List[Tuple[str, str]]:
        return list(self._capability_to_edges.get(capability, []))

    def get_legal_next_states(self, state: str) -> List[str]:
        """Return legal next states from the canonical state machine.

        This deliberately does not read a YAML-maintained next-state list. Guidance
        may explain an edge, but it must never become a second source of transition
        authority.
        """
        return list(ALLOWED_TRANSITIONS.get(state, []))

    def get_transition_guidance(
        self,
        from_state: str,
        to_state: Optional[str] = None,
        task_id_placeholder: str = "<task-id>",
    ) -> Dict[str, Any]:
        """Build a read-only, advisory snapshot for a state or requested edge."""
        legal_next_states = self.get_legal_next_states(from_state)
        transitions = []
        for next_state in legal_next_states:
            template = self.get_template(from_state, next_state)
            if template is None:
                continue
            transitions.append(self._edge_guidance(template, task_id_placeholder))

        result: Dict[str, Any] = {
            "advisory": True,
            "registry_version": TRANSITION_GUIDANCE_SCHEMA_VERSION,
            "current_state": from_state,
            "stage_contract": self.get_stage_contract(from_state),
            "legal_next_states": legal_next_states,
            "transitions": transitions,
            "execution_guidance": {
                unit: dict(self._execution_guidance[unit])
                for unit in EXECUTION_GUIDANCE_UNITS
            },
            "model_effort_guidance": {
                phase: dict(settings)
                for phase, settings in self._model_effort_guidance.items()
            },
        }
        if to_state is None:
            return result

        if to_state not in legal_next_states:
            result.update({
                "requested_to_state": to_state,
                "legal": False,
                "command": None,
                "denial_guidance": (
                    f"{from_state} -> {to_state} is not a legal transition. "
                    f"Choose one of: {', '.join(legal_next_states) or '(none — terminal state)'}."
                ),
                "recovery_states": legal_next_states,
            })
            return result

        edge = self.get_template(from_state, to_state)
        result.update(self._edge_guidance(edge, task_id_placeholder))
        result["requested_to_state"] = to_state
        result["legal"] = True
        return result

    @staticmethod
    def _edge_guidance(template: TransitionTemplate, task_id_placeholder: str) -> Dict[str, Any]:
        if template.requires_cryptographic_proof:
            command = (
                "" + AGENT_CONTROL_CMD + " "
                f"coordinate-transition --task-id {task_id_placeholder} --to {template.to_state} "
                "--interactive --key <path-to-signing-key>"
            )
        elif template.authorized_actor == AUTHORIZED_ACTOR_HUMAN_ONLY:
            command = (
                "" + AGENT_CONTROL_CMD + " "
                f"coordinate-transition --task-id {task_id_placeholder} --to {template.to_state} --interactive"
            )
        else:
            command = (
                "" + AGENT_CONTROL_CMD + " "
                f"coordinate-transition --task-id {task_id_placeholder} --to {template.to_state} "
                "--human-confirmed 'HUMAN-CONFIRMED: <quote>'"
            )
        configured = dict(template.guidance or {})
        helpers = list(configured.get("helper_commands", []))
        if template.approval.get("required"):
            helpers.append(
                "" + AGENT_CONTROL_CMD + " "
                f"record-human-approval --task-id {task_id_placeholder} --approver <name>"
            )
        run_by, basis, why = classify_edge(template)
        return {
            "from_state": template.from_state,
            "to_state": template.to_state,
            "transition_id": template.transition_id,
            "execution_class": run_by,
            "execution_instruction": EXECUTION_CLASS_INSTRUCTIONS[run_by],
            "command": command,
            "helper_commands": helpers,
            "success_guidance": configured.get("success", template.next_steps_hint),
            "denial_guidance": configured.get("denial", template.denial_message),
            "failure_recovery": template.failure_recovery,
        }

    def get_stage_contract(self, state: str) -> Optional[Dict[str, Any]]:
        """Return the entry-question contract for a lifecycle state."""
        return self._stage_contracts.get(state)

    def get_stage_question(self, state: str, question_id: str) -> Optional[Dict[str, Any]]:
        """Return a baseline or adaptive question by ID from a stage contract."""
        contract = self.get_stage_contract(state)
        if not contract:
            return None
        questions = list(contract.get("entry_questions", []))
        for rule in contract.get("adaptive_follow_up_rules", []):
            questions.extend(rule.get("questions", []))
        return next((q for q in questions if q.get("question_id") == question_id), None)

    @classmethod
    def load_from_file(cls, path: Path) -> "TransitionRegistry":
        if not path.exists():
            raise TransitionRegistryError(f"Transition templates file not found: {path}")
        try:
            with open(path, "r", encoding="utf-8") as f:
                # @AGENT_CONTROL_CMD@ and @CONTROL_SCRIPTS_DIR@ stand for the running install's agent_control.py command and scripts folder
                data = yaml.safe_load(
                    f.read().replace("@AGENT_CONTROL_CMD@", AGENT_CONTROL_CMD).replace("@CONTROL_SCRIPTS_DIR@", str(CONTROL_SCRIPTS_DIR))
                )
        except Exception as e:
            raise TransitionRegistryError(f"Failed to parse YAML from {path}: {e}") from e

        if not isinstance(data, dict) or "templates" not in data:
            raise TransitionRegistryError(f"YAML root must be a dict containing 'templates': {path}")

        raw_templates = data["templates"]
        if not isinstance(raw_templates, list):
            raise TransitionRegistryError(f"'templates' in {path} must be a list")

        raw_stages = data.get("stages", {})
        if not isinstance(raw_stages, dict):
            raise TransitionRegistryError("'stages' in YAML must be a mapping")

        stage_contracts: Dict[str, Dict[str, Any]] = {}
        for state, contract in raw_stages.items():
            if state not in CANONICAL_STATES:
                raise TransitionRegistryError(f"Unknown stage contract state: {state}")
            if not isinstance(contract, dict):
                raise TransitionRegistryError(f"Stage contract for '{state}' must be a mapping")
            for field in ("purpose", "question_policy", "entry_questions", "adaptive_follow_up_rules", "exit_requirements"):
                if field not in contract:
                    raise TransitionRegistryError(f"Stage '{state}' missing required field '{field}'")
            if contract["question_policy"] != "one_at_a_time":
                raise TransitionRegistryError(
                    f"Stage '{state}' must use question_policy 'one_at_a_time'"
                )
            for field in ("entry_questions", "adaptive_follow_up_rules", "exit_requirements"):
                if not isinstance(contract[field], list):
                    raise TransitionRegistryError(f"Stage '{state}' field '{field}' must be a list")
            stage_contracts[state] = contract

        raw_execution_guidance = data.get("execution_guidance")
        if not isinstance(raw_execution_guidance, dict):
            raise TransitionRegistryError("YAML root must contain an 'execution_guidance' mapping")
        execution_guidance: Dict[str, Dict[str, Any]] = {}
        for unit in EXECUTION_GUIDANCE_UNITS:
            contract = raw_execution_guidance.get(unit)
            if not isinstance(contract, dict):
                raise TransitionRegistryError(
                    f"execution_guidance must define mapping for '{unit}'"
                )
            if contract.get("advisory") is not True:
                raise TransitionRegistryError(
                    f"execution_guidance.{unit}.advisory must be true"
                )
            if contract.get("required_fields") != list(EXECUTION_GUIDANCE_FIELDS):
                raise TransitionRegistryError(
                    f"execution_guidance.{unit}.required_fields must match the execution guidance contract"
                )
            if not isinstance(contract.get("instruction"), str) or not contract["instruction"].strip():
                raise TransitionRegistryError(
                    f"execution_guidance.{unit}.instruction must be a non-empty string"
                )
            execution_guidance[unit] = contract

        raw_model_effort_guidance = data.get("model_effort_guidance", {})
        if not isinstance(raw_model_effort_guidance, dict):
            raise TransitionRegistryError("'model_effort_guidance' must be a mapping")
        model_effort_guidance: Dict[str, Dict[str, Any]] = {}
        for phase, settings in raw_model_effort_guidance.items():
            if not isinstance(settings, dict):
                raise TransitionRegistryError(f"model_effort_guidance.{phase} must be a mapping")
            for field in ("recommended_model", "recommended_effort", "reason"):
                if not isinstance(settings.get(field), str) or not settings[field].strip():
                    raise TransitionRegistryError(
                        f"model_effort_guidance.{phase}.{field} must be a non-empty string"
                    )
            if settings.get("requires_confirmation_for_premium") is not True:
                raise TransitionRegistryError(
                    f"model_effort_guidance.{phase}.requires_confirmation_for_premium must be true"
                )
            model_effort_guidance[phase] = settings

        raw_strategy_artifacts = data.get("strategy_artifacts", {})
        if not isinstance(raw_strategy_artifacts, dict):
            raise TransitionRegistryError("'strategy_artifacts' in YAML must be a mapping")
        strategy_artifacts: Dict[str, Dict[str, Any]] = {}
        for strat, cfg in raw_strategy_artifacts.items():
            if not isinstance(cfg, dict):
                raise TransitionRegistryError(f"strategy_artifacts.{strat} must be a mapping")
            strategy_artifacts[strat] = cfg

        parsed: List[TransitionTemplate] = []
        for idx, raw_item in enumerate(raw_templates):
            if not isinstance(raw_item, dict):
                raise TransitionRegistryError(f"Template at index {idx} must be a mapping")

            # Wildcard expansion fans out into one literal template per canonical state.
            # The reset-to-INTAKE wildcard excludes INTAKE's no-op self-loop.
            if raw_item.get("from_state") == "*":
                base_transition_id = raw_item.get("transition_id", f"wildcard_{idx}")
                wildcard_to_state = raw_item.get("to_state")
                existing_edges = {(t.from_state, t.to_state) for t in parsed}
                expanded_items = []
                for state in CANONICAL_STATES:
                    if state == wildcard_to_state:
                        continue
                    if (state, wildcard_to_state) in existing_edges:
                        continue
                    expanded = dict(raw_item)
                    expanded["from_state"] = state
                    expanded["transition_id"] = f"{base_transition_id}__from_{state}"
                    expanded_items.append(expanded)
            else:
                expanded_items = [raw_item]

            for item in expanded_items:
                for field in REQUIRED_TEMPLATE_FIELDS:
                    if field not in item:
                        raise TransitionRegistryError(f"Missing required field '{field}' in template index {idx}")

                if not isinstance(item["checklist"], list) or len(item["checklist"]) == 0:
                    raise TransitionRegistryError(f"Field 'checklist' must be a non-empty list in template '{item.get('transition_id')}'")
                if not isinstance(item["required_artifacts"], list):
                    raise TransitionRegistryError(f"Field 'required_artifacts' must be a list in template '{item.get('transition_id')}'")
                if not isinstance(item["deterministic_checks"], list):
                    raise TransitionRegistryError(f"Field 'deterministic_checks' must be a list in template '{item.get('transition_id')}'")
                if not isinstance(item["human_questions"], list):
                    raise TransitionRegistryError(f"Field 'human_questions' must be a list in template '{item.get('transition_id')}'")
                for question in item["human_questions"]:
                    if not isinstance(question, dict):
                        raise TransitionRegistryError(
                            f"Human question must be a mapping in template '{item.get('transition_id')}'"
                        )
                    asked_when = question.get("asked_when")
                    if asked_when is not None:
                        earlier = [q.get("question_id") for q in item["human_questions"]]
                        if (not isinstance(asked_when, dict) or set(asked_when) != {"question_id", "answer_contains"}
                                or asked_when["question_id"] not in earlier[:earlier.index(question.get("question_id"))]):
                            raise TransitionRegistryError(
                                f"Field 'asked_when' must be {{question_id, answer_contains}} naming an EARLIER question in template '{item.get('transition_id')}'"
                            )
                    choices_from = question.get("choices_from")
                    if choices_from is not None:
                        earlier_ids = [q.get("question_id") for q in item["human_questions"]]
                        runtime_qid = choices_from.get("runtime_question") if isinstance(choices_from, dict) else None
                        if (not isinstance(choices_from, dict) or choices_from.get("kind") not in ("runtime", "model", "effort")
                                or set(choices_from) - {"kind", "runtime_question"}
                                or (choices_from["kind"] != "runtime" and runtime_qid not in earlier_ids[:earlier_ids.index(question.get("question_id"))])):
                            raise TransitionRegistryError(
                                f"Field 'choices_from' must be {{kind: runtime|model|effort[, runtime_question: <earlier question id>]}} in template '{item.get('transition_id')}'"
                            )
                    accepted_answers = question.get("accepted_answers")
                    if accepted_answers is not None:
                        if not isinstance(accepted_answers, list) or not accepted_answers:
                            raise TransitionRegistryError(
                                f"Field 'accepted_answers' must be a non-empty list in template '{item.get('transition_id')}'"
                            )
                        options = question.get("options", [])
                        if not isinstance(options, list) or any(answer not in options for answer in accepted_answers):
                            raise TransitionRegistryError(
                                f"Field 'accepted_answers' must contain only declared options in template '{item.get('transition_id')}'"
                            )
                if not isinstance(item["approval"], dict):
                    raise TransitionRegistryError(f"Field 'approval' must be a dict in template '{item.get('transition_id')}'")
                if not isinstance(item["skip"], dict):
                    raise TransitionRegistryError(f"Field 'skip' must be a dict in template '{item.get('transition_id')}'")
                if not isinstance(item.get("authority"), dict):
                    raise TransitionRegistryError(f"Field 'authority' must be a dict in template '{item.get('transition_id')}'")
                if not isinstance(item["capabilities_released"], list):
                    raise TransitionRegistryError(f"Field 'capabilities_released' must be a list in template '{item.get('transition_id')}'")
                if not isinstance(item["capabilities_prohibited"], list):
                    raise TransitionRegistryError(f"Field 'capabilities_prohibited' must be a list in template '{item.get('transition_id')}'")
                if not isinstance(item["denial_message"], str) or len(item["denial_message"]) == 0:
                    raise TransitionRegistryError(f"Field 'denial_message' must be a non-empty string in template '{item.get('transition_id')}'")
                if not isinstance(item.get("next_steps_hint"), str) or len(item["next_steps_hint"].strip()) == 0:
                    raise TransitionRegistryError(f"Field 'next_steps_hint' must be a non-empty string in template '{item.get('transition_id')}'")
                if not isinstance(item.get("failure_recovery", ""), str):
                    raise TransitionRegistryError(f"Field 'failure_recovery' must be a string in template '{item.get('transition_id')}'")
                if not isinstance(item.get("stage_question_ids", []), list):
                    raise TransitionRegistryError(f"Field 'stage_question_ids' must be a list in template '{item.get('transition_id')}'")
                if item.get("stage_route") is not None and not isinstance(item["stage_route"], dict):
                    raise TransitionRegistryError(f"Field 'stage_route' must be a mapping in template '{item.get('transition_id')}'")
                if item.get("guidance") is not None and not isinstance(item["guidance"], dict):
                    raise TransitionRegistryError(f"Field 'guidance' must be a mapping in template '{item.get('transition_id')}'")
                guidance = item.get("guidance", {})
                if not isinstance(guidance.get("helper_commands", []), list):
                    raise TransitionRegistryError(
                        f"Field 'guidance.helper_commands' must be a list in template '{item.get('transition_id')}'"
                    )
                for guidance_field in ("success", "denial"):
                    if guidance_field in guidance and not isinstance(guidance[guidance_field], str):
                        raise TransitionRegistryError(
                            f"Field 'guidance.{guidance_field}' must be a string in template '{item.get('transition_id')}'"
                        )

                t = TransitionTemplate(
                    transition_id=item["transition_id"],
                    from_state=item["from_state"],
                    to_state=item["to_state"],
                    purpose=item["purpose"],
                    checklist=item["checklist"],
                    required_artifacts=item["required_artifacts"],
                    deterministic_checks=item["deterministic_checks"],
                    human_questions=item["human_questions"],
                    approval=item["approval"],
                    skip=item["skip"],
                    authority=item["authority"],
                    capabilities_released=item["capabilities_released"],
                    capabilities_prohibited=item["capabilities_prohibited"],
                    denial_message=item["denial_message"],
                    next_steps_hint=item.get("next_steps_hint", ""),
                    failure_recovery=item.get("failure_recovery", ""),
                    stage_question_ids=item.get("stage_question_ids", []),
                    stage_route=item.get("stage_route"),
                    guidance=item.get("guidance", {}),
                    requires_cryptographic_proof=bool(item.get("requires_cryptographic_proof", False)),
                )
                if "requires_cryptographic_proof" in item and not isinstance(item["requires_cryptographic_proof"], bool):
                    raise TransitionRegistryError(
                        f"Field 'requires_cryptographic_proof' must be a boolean in template '{item.get('transition_id')}'"
                    )
                parsed.append(t)

        return cls(parsed, stage_contracts, execution_guidance, model_effort_guidance, strategy_artifacts)

    @classmethod
    def default_path(cls) -> Path:
        return Path(__file__).resolve().parent / "transition_templates.yaml"

    @classmethod
    def default_source_digest(cls) -> str:
        """sha256 of the default YAML's bytes: the cache key for load_default() and an input to the
        persistence adapter's schema-sync fingerprint. Cheap (a file read + hash), unlike a parse."""
        try:
            return hashlib.sha256(cls.default_path().read_bytes()).hexdigest()
        except OSError as e:
            raise TransitionRegistryError(f"Transition templates file not found: {cls.default_path()}") from e

    @classmethod
    def load_default(cls) -> "TransitionRegistry":
        """The default registry, parsed at most once per distinct YAML content in this process.

        Parsing the 158KB YAML with the pure-Python loader costs ~0.13s and load_default() sits on every
        persistence call's path, so it is memoized on the file's content hash (an edited YAML is a new key,
        never stale). The returned instance is shared: treat it as read-only -- nothing in the repo mutates
        a loaded registry, and callers needing a variant build one via load_from_file()."""
        key = cls.default_source_digest()
        cached = _DEFAULT_REGISTRY_CACHE.get(key)
        if cached is None:
            cached = cls.load_from_file(cls.default_path())
            _DEFAULT_REGISTRY_CACHE.clear()  # only the current content is ever reachable
            _DEFAULT_REGISTRY_CACHE[key] = cached
        return cached
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