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

View on GitHub
#!/usr/bin/env python
"""
record_trace.py — Safe Audit Manifest and Telemetry Logger
==========================================================

Purpose:
    Appends safe audit events conforming to Schema v1.1.0 to
    `.agent/learning/traces/cycle_manifests.jsonl` with previous-hash chaining.
    Maintains raw stdout/stderr in gitignored `.agent/learning/traces/raw/<cycle_id>/`
    with defense-in-depth secret scrubbing.

Key Input Dependencies:
    - .agent/learning/traces/cycle_manifests.jsonl (append-only trace log)
"""

import argparse
import hashlib
import json
import os
import re
import subprocess
import sys
import time
import uuid
from datetime import datetime, timezone
from pathlib import Path

SCHEMA_VERSION = "1.1.0"
GENESIS_PREV_HASH = "0" * 64

EVENT_TYPES = [
    "cycle.initialized", "plan.completed", "authorization.granted",
    "worktree.created", "attempt.started", "mutation.completed",
    "verification.completed", "knowledge.persisted", "receipt.precommit.generated",
    "commit.completed", "rollback.completed", "receipt.final.generated",
    "cycle.completed", "cycle.escalated", "recovery.required"
]

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


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 scrub_secrets(text: str) -> str:
    """Redact common secret patterns (tokens, keys) from raw stdout/stderr before persisting."""
    if not text:
        return ""
    # API keys
    text = re.sub(r"(sk-[a-zA-Z0-9_\-]{8,})", "[REDACTED_API_KEY]", text)
    text = re.sub(r"(ghp_[a-zA-Z0-9]{20,})", "[REDACTED_API_KEY]", text)
    # Embedded credentials in URLs
    text = re.sub(r"(https?://)([^:/]+):([^@/]+)@", r"\1[REDACTED_USER]:[REDACTED_PASS]@", text)
    # Secret env lines
    text = re.sub(r"(?i)\b(API_KEY|API_SECRET|SECRET|TOKEN|PASSWORD|ACCESS_TOKEN)=([^\s\n]+)", r"\1=[REDACTED]", text)
    # Long base64-like blobs (>= 32 chars of pure base64 without spaces)
    text = re.sub(r"\b[A-Za-z0-9+/]{32,}={0,2}\b", "[REDACTED_BASE64]", text)
    return text


def _sha256_text(text: str) -> str:
    """Return the SHA-256 hex digest of the given text."""
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def append_event(
    repo_root: Path,
    cycle_id: str,
    node: str,
    event_type: str,
    exit_code: int = 0,
    paths_affected: list = None,
    attempt_id: str = None,
    stdout_text: str = "",
    stderr_text: str = ""
) -> dict:
    """Append one hash-chained trace event to cycle_manifests.jsonl."""
    traces_dir = repo_root / ".agent" / "learning" / "traces"
    manifest_file = traces_dir / "cycle_manifests.jsonl"
    raw_dir = traces_dir / "raw" / cycle_id
    raw_dir.mkdir(parents=True, exist_ok=True)
    manifest_file.parent.mkdir(parents=True, exist_ok=True)

    # Ensure .gitignore in raw/
    gitignore_path = traces_dir / "raw" / ".gitignore"
    if not gitignore_path.exists():
        gitignore_path.write_text("*\n!.gitignore\n", encoding="utf-8")

    event_id = f"evt-{uuid.uuid4().hex[:8]}-{int(time.time())}"

    # Save raw stdout/stderr with scrubbing
    stdout_sha = _sha256_text(stdout_text)
    stderr_sha = _sha256_text(stderr_text)

    if stdout_text:
        scrubbed_out = scrub_secrets(stdout_text)
        (raw_dir / f"{event_id}_stdout.log").write_text(scrubbed_out, encoding="utf-8")

    if stderr_text:
        scrubbed_err = scrub_secrets(stderr_text)
        (raw_dir / f"{event_id}_stderr.log").write_text(scrubbed_err, encoding="utf-8")

    # Read previous events to find seq and previous_event_hash
    event_seq = 1
    previous_event_hash = GENESIS_PREV_HASH

    if manifest_file.exists():
        lines = [l.strip() for l in manifest_file.read_text(encoding="utf-8").split("\n") if l.strip()]
        if lines:
            event_seq = len(lines) + 1
            last_event = json.loads(lines[-1])
            previous_event_hash = last_event.get("event_hash", GENESIS_PREV_HASH)

    event_payload = {
        "schema_version": SCHEMA_VERSION,
        "event_id": event_id,
        "event_seq": event_seq,
        "event_type": event_type,
        "cycle_id": cycle_id,
        "attempt_id": attempt_id,
        "timestamp": _now(),
        "node": node,
        "exit_code": int(exit_code),
        "paths_affected": paths_affected or [],
        "stdout_sha256": stdout_sha,
        "stderr_sha256": stderr_sha,
        "previous_event_hash": previous_event_hash
    }

    # Hash chaining: SHA256(previous_event_hash + canonical_event_json)
    canonical_json = json.dumps(event_payload, sort_keys=True)
    event_hash = hashlib.sha256(f"{previous_event_hash}{canonical_json}".encode("utf-8")).hexdigest()
    event_payload["event_hash"] = event_hash

    # Append to JSONL
    with open(manifest_file, "a", encoding="utf-8") as f:
        f.write(json.dumps(event_payload) + "\n")

    return event_payload


def main():
    """CLI entry point: parse args and append the described trace event."""
    parser = argparse.ArgumentParser(description="Record Evolution Trace Event")
    subparsers = parser.add_subparsers(dest="command", required=True)

    p_app = subparsers.add_parser("append")
    p_app.add_argument("--cycle-id", required=True)
    p_app.add_argument("--node", choices=CANONICAL_NODES, required=True)
    p_app.add_argument("--event-type", choices=EVENT_TYPES, required=True)
    p_app.add_argument("--exit-code", type=int, default=0)
    p_app.add_argument("--paths-affected", default="")
    p_app.add_argument("--attempt-id", default=None)
    p_app.add_argument("--stdout-text", default="")
    p_app.add_argument("--stdout-file", default=None)
    p_app.add_argument("--stderr-text", default="")
    p_app.add_argument("--stderr-file", default=None)
    p_app.add_argument("--repo-dir", type=Path, default=None)

    args = parser.parse_args()

    repo_root = _get_repo_root(args.repo_dir)

    stdout_content = args.stdout_text
    if args.stdout_file:
        f = Path(args.stdout_file)
        if f.exists():
            stdout_content = f.read_text(encoding="utf-8")

    stderr_content = args.stderr_text
    if args.stderr_file:
        f = Path(args.stderr_file)
        if f.exists():
            stderr_content = f.read_text(encoding="utf-8")

    paths = [p.strip() for p in args.paths_affected.split(",") if p.strip()]

    ev = append_event(
        repo_root=repo_root,
        cycle_id=args.cycle_id,
        node=args.node,
        event_type=args.event_type,
        exit_code=args.exit_code,
        paths_affected=paths,
        attempt_id=args.attempt_id,
        stdout_text=stdout_content,
        stderr_text=stderr_content
    )
    print(json.dumps(ev, indent=2))


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