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/ports.py

View on GitHub
"""
control_plane/ports.py — Port Interfaces for the ControlPlane Decomposition (issue-524)
=========================================================================================

Purpose:
    Declares the abstract seams that domain and policy code depend on instead of concrete
    infrastructure (sqlite3, subprocess, hashlib, filesystem, model-catalog JSON storage).
    Dependency-direction invariant (docs/plans/issue-524-spec.md, DoD item 5): domain/policy
    modules import ONLY from this file (and stdlib `abc`/`typing`) — never sqlite3, subprocess,
    hashlib, time-based I/O, or concrete filesystem/model-catalog storage. Adapters (added in
    later steps) implement these interfaces against real infrastructure; the application layer
    composes policy with adapters via these ports.

Layer:
    OS Kernel / Execution Control Plane Substrate — Ports (hexagonal boundary)

Key Input Dependencies:
    None — pure interface definitions, no I/O.

Key Functions:
    - ClockPort — current_time() -> float, strftime(fmt) -> str
    - FilesystemPort — append_text(), read_text(), exists()
    - CryptoPort — sha256_file(), sha256_hex()
    - ModelCatalogPort — load_catalog(), load_cheapest()
    - PersistencePort — task/transition/receipt/review/log/baseline CRUD, all keyed by task_id.
      Fully implemented by control_plane.adapters.SqlitePersistenceAdapter (issue-524 Step 5
      revision) — every method here has a concrete SQLite-backed implementation; ControlPlane
      composes this port rather than issuing SQL itself.
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple

from control_plane.snapshot import SnapshotEntry


class PersistenceInvariantViolation(Exception):
    """Raised when evolution integrity, database trigger enforcement, or asymmetric persistence invariants are violated."""
    pass


@dataclass(frozen=True)
class TransitionRecord:
    transition_id: int
    task_id: str
    from_state: str
    to_state: str
    actor: str
    reason: Optional[str]
    timestamp: str


@dataclass(frozen=True)
class TransitionDecision:
    task_id: str
    source_occupancy_transition_id: int
    from_state: str
    to_state: str
    question_id: str
    answer: str
    decision_type: str
    actor: str
    recorded_at: float
    # Optional provenance from control_plane.transition_request's stub-JWT mechanics
    # (T3): populated only when this decision was authorized by consuming a signed
    # transition_request token; absent for every other decision path.
    token_jti: Optional[str] = None
    token_consumed_at: Optional[float] = None


@dataclass(frozen=True)
class InterviewAnswerRecord:
    """Identifiers returned by the atomic answer-and-outline persistence operation."""

    decision_id: int
    outline_revision: int


@dataclass(frozen=True)
class AuthorizationProof:
    """Proof that a human authorized a proof-required edge (Gate 1), verified INSIDE the
    commit transaction by the persistence adapter (auth-ciba-increment-b T4).

    kind: only "sshsig" is accepted (the audited legacy_input fallback was removed on 2026-09-20).
    signature: the raw armored SSHSIG bytes, read once by the caller.
    allowed_signers / principal: the production trust anchor (namespace control-plane@agentic-os.local).
    live_snapshot_fn: called inside the transaction to read the live reviewed files."""

    kind: str
    request_id: int
    signature: bytes = b""
    allowed_signers: Optional[Path] = None
    principal: Optional[str] = None
    require_uv: bool = True
    live_snapshot_fn: Optional[Callable[[], Sequence[SnapshotEntry]]] = None
    binary: str = "ssh-keygen"
    timeout: float = 10.0


@dataclass(frozen=True)
class TransitionCommitRequest:
    task_id: str
    expected_from_state: str
    to_state: str
    source_occupancy_transition_id: int
    template_id: str
    actor: str
    reason: str
    staged_decisions: List[TransitionDecision]
    staged_receipts: List[Dict[str, Any]]
    interactive_human_authorization: bool = False
    # Verified inside the commit transaction for edges declaring requires_cryptographic_proof.
    proof: Optional[AuthorizationProof] = None


@dataclass(frozen=True)
class PhaseCapability:
    task_id: str
    action_identity: str
    current_state: str
    releasing_edge: Tuple[str, str]
    transition_id: int
    # authorized_actor classification (T1) of releasing_edge, carried here so
    # callers don't need a second registry lookup keyed on the same edge.
    authorized_actor: str = "agent_or_human"


class ClockPort(ABC):

    """Abstracts wall-clock time so domain/policy code never imports `time` directly."""

    @abstractmethod
    def current_time(self) -> float:
        """Returns the current time as a float (seconds since epoch, or equivalent)."""
        raise NotImplementedError

    @abstractmethod
    def strftime(self, fmt: str) -> str:
        """Returns the current time formatted per `fmt` (strftime-style), for human-readable
        timestamps in generated text (e.g. map-debt entries)."""
        raise NotImplementedError


class FilesystemPort(ABC):
    """Abstracts filesystem side-effects (e.g. appending to references/map-debt.md)."""

    @abstractmethod
    def append_text(self, path: Path, content: str) -> None:
        """Appends text content to the file at `path`, creating it if absent is NOT implied —
        callers must check `exists()` first if creation-on-missing is not desired."""
        raise NotImplementedError

    @abstractmethod
    def read_text(self, path: Path) -> str:
        """Reads and returns the full text content of the file at `path`."""
        raise NotImplementedError

    @abstractmethod
    def exists(self, path: Path) -> bool:
        """Returns whether a file exists at `path`."""
        raise NotImplementedError


class CryptoPort(ABC):
    """Abstracts cryptographic hashing (verifier sovereignty, receipt tokens)."""

    @abstractmethod
    def sha256_file(self, path: Path) -> str:
        """Returns the SHA256 hex digest of the file at `path`."""
        raise NotImplementedError

    @abstractmethod
    def sha256_hex(self, raw: str) -> str:
        """Returns the SHA256 hex digest of the given string."""
        raise NotImplementedError


class ModelCatalogPort(ABC):
    """Abstracts model-catalog resolution — both the JSON file reads AND the tier-selection/
    strategy logic (issue-524, post-round-2-review correction: the original version only
    declared the file-read methods, leaving resolve_recommended_model()'s tool-alias
    resolution, tier strategy, and fallback logic still embedded in ControlPlane — an
    incomplete separation of the model-catalog responsibility)."""

    @abstractmethod
    def resolve_recommended_model(self, runtime_tool: str, tier: str = "low") -> Dict[str, str]:
        """Resolves a full model recommendation for `runtime_tool`/`tier`: tool-alias
        resolution, catalog file lookup, tier-strategy selection, and fallback — the complete
        behavior formerly split between ControlPlane.resolve_recommended_model() and this
        port's file-read-only methods. Returns {"runtime_tool", "tier", "model_id"}."""
        raise NotImplementedError

    @abstractmethod
    def load_catalog(self, catalog_path: Path) -> Optional[Dict[str, Any]]:
        """Loads and returns a parsed model-catalog JSON file, or None if unavailable/unparsable."""
        raise NotImplementedError

    @abstractmethod
    def load_cheapest(self, cheapest_path: Path, tool_key: str) -> Optional[str]:
        """Loads cheapest_models.json and returns the cheapest model id for `tool_key`, or None."""
        raise NotImplementedError


class PersistencePort(ABC):
    """Abstracts all durable task-lifecycle storage (today: SQLite). Domain and policy code
    depend only on this interface, never on sqlite3 directly."""

    @abstractmethod
    def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
        """Retrieves a task dictionary by task_id, or None if not found."""
        raise NotImplementedError

    @abstractmethod
    def insert_premium_consent(
        self, task_id: str, stage: str, round_id: str, model_id: str, actor: str
    ) -> int:
        """Persist human consent for one exact task/stage/round/model scope."""
        raise NotImplementedError

    @abstractmethod
    def has_premium_consent(self, task_id: str, stage: str, round_id: str, model_id: str) -> bool:
        """Return whether an exact task/stage/round/model consent scope exists."""
        raise NotImplementedError

    @abstractmethod
    def insert_source_assisted_answer_candidate(
        self,
        task_id: str,
        stage: str,
        round_id: str,
        question_id: str,
        answer: str,
        source_path: str,
        source_authorized: bool,
    ) -> int:
        """Persist one source-derived answer candidate and its provenance."""
        raise NotImplementedError

    @abstractmethod
    def confirm_source_assisted_answer_candidate(self, candidate_id: int, actor: str) -> bool:
        """Mark one pending source-derived answer candidate as human-confirmed."""
        raise NotImplementedError

    @abstractmethod
    def has_unconfirmed_source_assisted_answer_candidates(
        self, task_id: str, stage: str, round_id: Optional[str]
    ) -> bool:
        """Return whether the requested scope still has unconfirmed candidates.

        ``round_id=None`` checks every round in the stage, which is used by the
        authoritative lifecycle exit gate.
        """
        raise NotImplementedError

    def upsert_interview_plan_outline(
        self, task_id: str, bullets: List[Dict[str, Any]], artifact_path: str
    ) -> int:
        """Persist the canonical interview outline and return its revision."""
        raise NotImplementedError

    def record_interview_answer(
        self,
        decision: TransitionDecision,
        bullets: List[Dict[str, Any]],
        artifact_path: str,
    ) -> InterviewAnswerRecord:
        """Atomically persist one answer decision and its revisioned outline."""
        raise NotImplementedError

    def get_interview_plan_outline(self, task_id: str) -> Optional[Dict[str, Any]]:
        """Retrieve the canonical interview outline, or None when not yet created."""
        raise NotImplementedError

    def create_delegation_plan(self, task_id: str, contract: Dict[str, Any]) -> int:
        """Persist a governed delegation contract and return its identifier."""
        raise NotImplementedError

    def get_delegation_plan(self, contract_id: int) -> Optional[Dict[str, Any]]:
        """Retrieve a delegation contract by identifier."""
        raise NotImplementedError

    def approve_delegation_plan(self, contract_id: int, actor: str) -> None:
        """Record the human approval for a contract that requires it."""
        raise NotImplementedError

    def count_delegation_receipts(self, contract_id: int) -> int:
        """Count execution attempts against a delegation contract."""
        raise NotImplementedError

    def insert_delegation_receipt(self, contract_id: int, receipt: Dict[str, Any]) -> int:
        """Persist one execution receipt."""
        raise NotImplementedError

    def insert_delegation_verifier_receipt(self, contract_id: int, command: str, exit_code: int) -> None:
        """Persist the verifier receipt required before accepting a result."""
        raise NotImplementedError

    def mark_delegation_status(self, contract_id: int, status: str) -> None:
        """Update the governed contract status."""
        raise NotImplementedError

    def has_delegation_verifier_receipt(self, contract_id: int) -> bool:
        """Return whether a passing verifier receipt exists."""
        raise NotImplementedError

    @abstractmethod
    def insert_task(self, task_id: str, title: str, task_type: str, runtime_tool: str,
                     spec_path: Optional[str], model_tier: Optional[str], model_id: Optional[str]) -> None:
        """Inserts a new task row in INTAKE state and its creation transition, atomically."""
        raise NotImplementedError

    @abstractmethod
    def read_current_state(self, task_id: str) -> Optional[str]:
        """Reads a task's current state value directly, for use immediately before a guarded write."""
        raise NotImplementedError

    @abstractmethod
    def apply_transition(self, task_id: str, from_state: str, to_state: str, actor: str, reason: str) -> bool:
        """Atomically updates task state (guarded by expected from_state) and records the
        transition row. Returns False if the guard predicate did not match (concurrent write)."""
        raise NotImplementedError

    @abstractmethod
    def count_asymmetric_persistence(self, task_id: str, details_like: Optional[str] = None,
                                      destination_like_any: Optional[List[str]] = None) -> int:
        """Counts asymmetric_persistence_log rows for task_id. `details_like` filters on the
        `details` column (single LIKE pattern); `destination_like_any` filters on the
        `destination` column (OR'd across multiple LIKE patterns). At most one of the two
        should be given; neither given returns the unfiltered count for task_id."""
        raise NotImplementedError

    @abstractmethod
    def count_receipts(self, task_id: str, gate_name: str, exit_code: Optional[int] = None) -> int:
        """Counts verification_receipts rows for task_id matching gate_name (and exit_code if given)."""
        raise NotImplementedError

    @abstractmethod
    def count_locked_verifiers(self, task_id: str) -> int:
        """Counts locked_verifier_baselines rows for task_id."""
        raise NotImplementedError

    @abstractmethod
    def get_locked_verifiers(self, task_id: str) -> List[Dict[str, Any]]:
        """Returns locked_verifier_baselines rows (file_path, expected_sha256) for task_id."""
        raise NotImplementedError

    @abstractmethod
    def has_passing_critic_review(self, task_id: str) -> bool:
        """Returns whether any critic_reviews row for task_id has verdict='PASS'."""
        raise NotImplementedError

    @abstractmethod
    def has_receipt(self, task_id: str, gate_name: str) -> bool:
        """Returns whether any verification_receipts row exists for task_id with the given gate_name."""
        raise NotImplementedError

    @abstractmethod
    def insert_verification_receipt(self, task_id: str, gate_name: str, command_executed: str,
                                     exit_code: int, receipt_token: str,
                                     actor: Optional[str] = None, provenance: str = "api") -> None:
        """Inserts a verification_receipts row (with actor/provenance and an append-only audit row)."""
        raise NotImplementedError

    def invalidate_receipt(self, receipt_id: int, actor: str, reason: str) -> None:
        """Marks a receipt invalid and appends an 'invalidated' audit row (T15). Optional capability."""
        raise NotImplementedError

    @abstractmethod
    def insert_critic_review(self, task_id: str, iteration: int, model: str, verdict: str, findings: str) -> None:
        """Inserts a critic_reviews row."""
        raise NotImplementedError

    @abstractmethod
    def insert_locked_verifier(self, task_id: str, file_path: str, expected_sha256: str) -> None:
        """Inserts a locked_verifier_baselines row."""
        raise NotImplementedError

    @abstractmethod
    def insert_asymmetric_persistence(self, task_id: str, destination: str, status: str, details: str) -> None:
        """Inserts an asymmetric_persistence_log row."""
        raise NotImplementedError

    def get_latest_asymmetric_persistence(
        self, task_id: str, destination: Optional[str] = None
    ) -> Optional[Dict[str, Any]]:
        """Retrieves the latest asymmetric_persistence_log row for a task_id and optional destination."""
        return None

    @abstractmethod
    def get_guidance_block_reason(self, task_id: str) -> Optional[str]:
        """Returns the task's guidance_block_reason (None if not blocked)."""
        raise NotImplementedError

    @abstractmethod
    def set_guidance_block(self, task_id: str, reason: str) -> None:
        """Sets guidance_block_reason, refusing all further transitions until cleared."""
        raise NotImplementedError

    @abstractmethod
    def clear_guidance_block(self, task_id: str) -> None:
        """Clears guidance_block_reason."""
        raise NotImplementedError

    @abstractmethod
    def get_verification_receipts(self, task_id: str) -> List[Dict[str, Any]]:
        """Returns all verification_receipts rows for task_id."""
        raise NotImplementedError

    @abstractmethod
    def save_retrospective(self, task_id: str, entry: Dict[str, Any], follow_ups: List[Dict[str, Any]]) -> None:
        """Creates or replaces the single task retrospective and its follow-up rows."""
        raise NotImplementedError

    def get_retrospective_summary(self, task_id: str) -> Optional[Dict[str, Any]]:
        """{decision, digest} of the recorded retrospective, or None (used to bind a human's closure signature)."""
        raise NotImplementedError

    @abstractmethod
    def has_complete_retrospective(self, task_id: str) -> bool:
        """Returns whether the task has a complete or explicitly skipped retrospective."""
        raise NotImplementedError

    @abstractmethod
    def update_worktree_fields(self, task_id: str, worktree_path: str, worktree_branch: str, worktree_state: str) -> None:
        """Updates a task's worktree_path/worktree_branch/worktree_state columns."""
        raise NotImplementedError

    @abstractmethod
    def record_done_closeout_decision(
        self, task_id: str, source_occupancy_transition_id: int, question_id: str,
        answer: str, actor: str, recorded_at: float,
    ) -> int:
        """Persists one human decision made while the task is in DONE closeout."""
        raise NotImplementedError

    @abstractmethod
    def get_done_closeout_decisions(self, task_id: str) -> List[Dict[str, Any]]:
        """Returns persisted DONE closeout decisions for a task."""
        raise NotImplementedError

    @abstractmethod
    def ensure_schema(self) -> None:
        """Ensures the underlying storage schema exists and is at the current version, self-healing if needed."""
        raise NotImplementedError

    @abstractmethod
    def get_last_transition(
        self,
        task_id: str,
        from_state: Optional[str] = None,
        to_state: Optional[str] = None,
    ) -> Optional[TransitionRecord]:
        """Returns the latest TransitionRecord for task_id matching optional from_state/to_state filters."""
        raise NotImplementedError

    @abstractmethod
    def apply_transition_with_receipts(
        self,
        request: TransitionCommitRequest,
    ) -> TransitionRecord:
        """Atomically revalidates authoritative persistable facts in SQLite and applies transition."""
        raise NotImplementedError

    @abstractmethod
    def record_recovery_approval(
        self,
        task_id: str,
        expected_source_state: str,
        destination_state: str,
        source_occupancy_transition_id: int,
        approver: str,
        decision: str,
        reason: str,
    ) -> str:
        """Issues and persists an unconsumed recovery approval decision record bound to the current source occupancy ID."""
        raise NotImplementedError

    @abstractmethod
    def apply_recovery_transition(
        self,
        task_id: str,
        expected_source_state: str,
        destination_state: str,
        source_occupancy_transition_id: int,
        approval_receipt_token: str,
        actor: str,
        reason: str,
    ) -> TransitionRecord:
        """Atomically executes recovery transition using a verified, unconsumed approval record."""
        raise NotImplementedError

    @abstractmethod
    def record_decision(self, decision: TransitionDecision) -> int:
        """Records an occupancy-bound TransitionDecision. Rejects duplicates within same occupancy."""
        raise NotImplementedError

    @abstractmethod
    def get_task_by_worktree_branch(self, branch: str) -> Optional[Dict[str, Any]]:
        """Returns task dict matching worktree_branch, or None."""
        raise NotImplementedError

    @abstractmethod
    def validate_task_pipeline_history(self, task_id: str, task_state: str) -> Optional[str]:
        """Validates transition history and violations for pipeline commit check. Returns error string or None."""
        raise NotImplementedError
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 CodeCodexVerifiedInstall
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