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/transition_templates.yaml

View on GitHub
session_change_control:
  applies_from: task_creation
  owner: controller
  worktree_first_invariant: "From the first task/session mutation, the registered worktree is the authoritative location for all session-owned changes. Do not make direct main-checkout edits after the session baseline unless they are explicitly classified, reconciled, and copied into the worktree."
  session_baseline: "Record the main checkout and registered worktree status before the first mutation, then preserve the baseline reference for the entire task."
  observation_loop:
    trigger: "Any user or agent observation about execution friction, a contract defect, missing evidence, or a pipeline improvement, including observations made before implementation tasks formally begin."
    sequence:
    - record_observation
    - classify_observation
    - decide_immediate_fix_or_defer
    - update_ledger_and_plan_if_in_scope
    - apply_in_registered_worktree
    - run_focused_verification
    - record_evidence_and_resume_current_stage
    classifications:
    - in_scope_immediate_pipeline_fix
    - deferred_map_debt
    - material_scope_expansion
    - blocker
    immediate_fix_rule: "An in-scope, non-destructive pipeline fix may be handled before formal implementation begins, but it must be recorded as a bounded task/plan delta, applied in the registered worktree, focused-tested, and included in the session-wide change inventory."
    approval_boundary: "Material scope expansion, destructive action, authority change, or implementation outside the approved boundary requires human approval before action."
    status_reporting: "Report pre-implementation fixes as pipeline observations handled; do not report implementation as started or complete solely because an observation was addressed."
    failure_recovery: "If the observation cannot be classified or its worktree/ledger/evidence update cannot complete, record the exact blocker and recovery action, preserve the current lifecycle state, and do not silently continue."
  review_gate: "Before any review submission, verify every session-owned change is present and content-matched in the registered worktree; classify generated metadata separately and fail closed on missing, mismatched, or unclassified implementation changes."

strategy_artifacts:
  graph:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>-graph-manifest.json
    required: true
    validator: ["python3", "{validator_script}", "{artifact}"]
    validator_script: "skills/graph-planner/scripts/validate_manifest.py"
  dual-loop:
    artifact: handoffs/task_packet_<task-id>.md
    required: true
    validator: ["python3", "{validator_script}", "packet", "--packet-path", "{artifact}"]
    validator_script: "plugins/agent-orchestration/skills/orchestrating-agent-work/scripts/agent_orchestrator.py"
  agent-swarm:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>.job.md
    required: true
  direct:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>-implementation-plan.md
    required: true
  red-team-review:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>-threat-model.md
    required: false
  learning-loop:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>-eval-brief.md
    required: false
  triple-loop-learning:
    artifact: docs/plans/work-tasks/<task-id>/<task-id>-learning-contract.md
    required: false

review_selection_contract:
  id: review-selection-v1
  applies_to:
  - plan_review_to_multi_agent_review
  - worktree_review_to_multi_agent_code_review
  canonical_profile_path: context/agent-capability-profile.json
  environment_summary_fallback: context/memory/environment.md
  profile_owner: cli-agent
  profile_lifecycle:
    establish: "Run the interactive cli-agent project-setup capability baseline (references/project-setup.md) once during project setup."
    consume: "Pipeline review and implementation stages read the profile and current catalog references; they do not repeat deep environment analysis."
    refresh: "If the profile is missing, partial, invalid, stale, or the user reports an environment change, route back to cli-agent project setup for the provider and model questions."
  availability_rule: "Offer only runtimes and providers whose installation probe succeeds, whose subscription/account/license access is explicitly confirmed by the user, and whose project-use authorization is explicitly confirmed when applicable; never infer availability from the host agent, repository author, or a static option list."
  question_sequence:
  - review_decision
  - review_method
  - internal_runtime_model_effort
  internal_runtime_model_effort:
    applies_when: "The selected review method is single-agent internal or multi-agent internal."
    question_policy: one_at_a_time
    sequence:
    - internal_cli_runtime
    - internal_model
    - internal_effort
    cli_runtime_question: "Which available CLI/runtime should run the internal reviewers?"
    model_question: "Which model should the internal reviewers use?"
    effort_question: "Which effort level should the internal reviewers use?"
    option_resolution:
      cli_runtime: "Render only providers with available=true in context/agent-capability-profile.json; do not infer availability from installed binaries, the host agent, or a static option list."
      model: "After the runtime is selected, render only model IDs and capability tiers from the cli-agent model catalogs for that runtime."
      effort: "Render only effort levels supported by the selected runtime/model and current catalog."
    persistence: "Persist the runtime, model, and effort answers before dispatch; never dispatch an internal reviewer with an inferred or default route."
  user_must_choose_internal_route: true
  human_answer_provenance:
    chat_answer: "A user answer received in chat is a human decision. Persist it through coordinate-transition --interactive so SQLite records actor=human."
    answers_flag: "Do not use --answers to represent a human-gated answer; it records agent provenance and will be rejected by the SQLite human-decision trigger."
    scripted_use: "Use --answers only for non-human scripted tests or explicitly agent-authored decisions on edges that permit them."
  internal_selection_rule: "After the user selects an internal method, inspect the confirmed environment and current catalogs, recommend a proportional runtime/model/effort route, and ask the user to choose or confirm it. Do not dispatch an internal reviewer until that explicit user selection is recorded."
  premium_rule: "A premium model or high-effort route requires explicit user confirmation even when recommended."
  catalog_authority_skill: cli-agent
  catalog_resolution:
    authority: cli-agent
    do_not_duplicate_catalogs: true
    instruction: "Read cli-agent references/model-catalog-maintenance.md for current model IDs, capability tiers, pricing, catalog ownership, and synchronization rules."
    missing_catalog_rule: "If the profile or required catalog cannot be resolved, report the exact missing path and route back to cli-agent project setup for refresh; do not invent model choices or dispatch."
  feedback_handoff:
    applies_to:
    - MULTI_AGENT_REVIEW
    - MULTI_AGENT_CODE_REVIEW
    sequence:
    - collect_each_reviewer_report
    - synthesize_one_canonical_round_brief
    - persist_raw_reports_and_synthesis
    - record_critic_outcome_and_exact_return_edge
    - if_changes_requested_transition_to_worktree_and_pass_revision_brief
    storage:
      raw_reports: "Store each report under the task-scoped temp review directory, with reviewer, runtime, model, effort, and round in the filename or manifest."
      synthesis: "Store one task-scoped synthesis/revision brief beside the raw reports; it is the implementer's only consolidated review input."
      durable_outcome: "Persist the canonical PASS, REVISE, or REVIEW_FAILURE outcome and concise findings through the control-plane critic-review receipt, linked to the review iteration and report manifest."
    synthesis_rule: "The orchestrator, not an individual reviewer, reconciles duplicate findings, preserves dissent, assigns severity, separates in-scope fixes from follow-up debt, and names the exact acceptance checks required before re-review."
    implementation_handoff: "For REVISE or REQUEST_CHANGES, do not ask the reviewer to edit code and do not feed raw reports directly into an unrelated model. Transition to IN_WORKTREE and pass the canonical revision brief to the already-authorized implementation controller as a bounded fix prompt."
    re_review_rule: "After the bounded fix prompt is completed, run focused verification and the session-wide change inventory, return through WORKTREE_REVIEW, and start a new review iteration with the same selection contract unless the user explicitly changes it."
    review_type_isolation:
      plan_review: "MULTI_AGENT_REVIEW receipts concern the draft plan only. They may authorize a return to DRAFT_PLAN, but they never authorize implementation rework, satisfy code_review_or_skip, or count as an implementation-review round."
      implementation_review: "MULTI_AGENT_CODE_REVIEW receipts concern the implementation in the registered worktree only. They may authorize the existing return to IN_WORKTREE for bounded fixes or the exit path after PASS."
      round_numbering: "Maintain separate plan-review and implementation-review iteration counters; do not call an implementation review round 2 merely because plan review reached iteration 2."
      rework_gate: "Do not transition MULTI_AGENT_CODE_REVIEW to IN_WORKTREE without a current implementation-review receipt whose verdict is REQUEST_CHANGES, REVISE, or REVIEW_FAILURE with bounded recovery."
      human_transition_gate: "After the current implementation-review synthesis and revision brief are recorded, ask the human whether to transition back to IN_WORKTREE. Do not begin fixes or treat the rework transition as implicitly approved."

stages:
  INTERVIEW:
    purpose: Capture the minimum understanding needed before selecting the next lifecycle path.
    question_policy: one_at_a_time
    intent_first: true
    canonical_questions_are_coverage_prompts: true
    adaptation_guidance:
      principle: Understand the desired work; do not conduct a literal questionnaire.
      ask_only_unresolved: true
      allow_combined_answers: true
      allow_rephrased_questions: true
      allow_not_applicable_with_rationale: true
      allow_contextual_follow_ups: true
      preserve_canonical_ids: true
      no_inferred_answers: true
      approval_and_authority_are_always_explicit: true
    approver_identity:
      rule: Before the first interview question, state which identity approves this pipeline and confirm it with the human.
      one_approver_per_pipeline: true
      default: human_operator
      enforced_by: scripts/control_plane/approver_policy.py (by database file; the first signed gate fixes the task's approver key)
      human_operator: Real work lives in the repository's context/control_plane.db and is approved (Gate 1 APPROVED, Gate 3 VERIFY_EXIT, DONE) only with the human operator's own enrolled signing key. The agent's simulation key is refused there under any alias.
      agent_simulation: Simulations run in a separate database file named simulation_control_plane.db. There only the agent's simulation key (enrolled as test-human@local) approves and the human's key is refused. Real-work gates never read that file.
      push_guard: Before a push, the push guard (verify_gate_evidence.py, shipped with the running-control-plane skill) re-verifies every signed gate of the task against context/identity/allowed_signers (human keys only, one key); a simulation database copied or symlinked into context/control_plane.db cannot unlock it.
      never: Never run a simulation against context/control_plane.db, never sign on the human's behalf, and never remove or overwrite either identity in allowed_signers; the two identities coexist.
    plan_outline:
      enabled: true
      purpose: Capture the plan-ready bullets discovered during the interview before drafting the full plan.
      update_after_each_answer: true
      user_visibility: Show a concise outline summary or a link to the current outline; do not make the user reconstruct it from chat.
      artifact_path: docs/plans/work-tasks/<task-id>/<task-id>-plan-outline.md
      link_rule: When the outline artifact exists, provide its repository-relative clickable path in the response.
      bullet_types:
      - purpose
      - desired_user_outcome
      - scope_boundary
      - success_evidence
      - constraint_or_authority
      - risk_or_open_question
      - decision
      outline_is_not_approval: true
      draft_plan_source: The completed outline is the primary interview input for the initial draft plan.
    intent_coverage:
    - intent_id: classification
      canonical_question_id: interview_classification
      purpose: Choose the proportionate lifecycle route.
    - intent_id: problem
      canonical_question_id: interview_summary
      purpose: Understand the desired outcome and why it matters.
    - intent_id: scope
      canonical_question_id: interview_scope
      purpose: Define included behavior, boundaries, and exclusions.
    - intent_id: verification
      canonical_question_id: interview_verification
      purpose: Define observable evidence of correctness.
    - intent_id: acceptance
      canonical_question_id: interview_acceptance_criteria
      purpose: Define constraints and acceptance conditions for standard work.
    progress_display:
      enabled: true
      count_adaptive_questions: true
      format: "Interview question {current} of {total}"
      include_remaining_summary: true
    entry_questions:
    - question_id: interview_classification
      question: "Is this a trivial fix or a standard task? Note: TRIVIAL does NOT skip pipeline stages -- it only lightens evidence at each stage (focused verification, no external reviewers, concise plan). There is no INTAKE/INTERVIEW -> DONE shortcut edge; the only such edges are the human_force_done_* force-close family, requiring live interactive human authorization. If a change is small enough that even the lightened full sequence is disproportionate, the correct choice is to skip this control plane entirely (direct commit/push with the user's explicit authorization), not to answer TRIVIAL expecting a shortcut through it."
      options:
      - TRIVIAL
      - STANDARD
      default: STANDARD
    - question_id: interview_summary
      question: What problem are we solving, in your own words?
      options: []
      default: ''
    - question_id: interview_scope
      question: What files, skills, or behavior are in scope, and what is explicitly out of scope?
      options: []
      default: ''
    - question_id: interview_verification
      question: What observable result will prove the work is correct?
      options: []
      default: ''
    adaptive_follow_up_rules:
    - rule_id: trivial_change_evidence
      when:
        question_id: interview_classification
        equals: TRIVIAL
      questions:
      - question_id: interview_trivial_evidence
        question: What is the smallest change, and what diff or test reference proves it?
        options: []
        default: ''
    - rule_id: standard_acceptance_detail
      when:
        question_id: interview_classification
        equals: STANDARD
      questions:
      - question_id: interview_acceptance_criteria
        question: What acceptance criteria and constraints must the implementation satisfy?
        options: []
        default: ''
      - question_id: interview_planning_model_effort
        question: >-
          For the upcoming planning phase, what model and effort level would you
          like to choose? The interviewer will first classify the planning
          problem as low, medium or high complexity, inspect your available
          tools, recommend a cost/effort route, and explain the tradeoff. You
          may confirm the recommendation or choose another supported option.
        options: []
        default: ''
        selection_mode: confirm_or_change
        recommendation_source: model_effort_guidance
        recommendation_phase: plan
        availability_sources:
        - running-control-plane
        - cli-agent
        complexity_options:
          low:
            recommended_cost_tier: low
            recommended_effort: low
            guidance: Use the cheapest capable available model; premium planning is unnecessary.
          medium:
            recommended_cost_tier: medium
            recommended_effort: medium
            guidance: Use a competent mid-tier model unless ambiguity or risk warrants more.
          high:
            recommended_cost_tier: high
            recommended_effort: medium
            guidance: Prefer a highly capable model such as Astra at medium effort; consider capable alternatives available to the user.
        undersized_choice_guidance: If the user selects a low-tier or low-effort route for a high-complexity plan, advise that it may reduce plan quality and ask whether to continue; defer to the user.
        premium_confirmation_required: true
    exit_requirements:
    - A concise plan outline is persisted and reviewable before the initial draft plan is compiled.
    - Every required intent area has a recorded coverage disposition: direct answer, combined answer, authorized source answer, explicit not-applicable rationale, or focused adaptive follow-up.
    - Canonical question IDs remain traceable in the coverage record; the user is not required to hear redundant literal wording.
    - Every adaptive rule matching the recorded answers has been evaluated.
    - All generated follow-up questions have an answer or an explicit human refusal.
    - The agent has not inferred an answer on the user's behalf.
  PLAN_REVIEW:
    purpose: "The human decides about the authored or revised plan: accept and advance, request revisions, or optionally dispatch an independent review."
    question_policy: one_at_a_time
    entry_questions: []
    adaptive_follow_up_rules: []
    exit_requirements:
    - "The human either accepted the plan (proceed to AWAITING_APPROVAL), requested revisions (return to DRAFT_PLAN), or requested independent review (proceed to MULTI_AGENT_REVIEW)."
    guidance:
      summary: "Agent review is optional. When the human accepts the plan, you run coordinate-transition --to AWAITING_APPROVAL. No review or skip receipt is needed."
      next_steps:
      - Ask the human in chat if they accept the plan, want changes, or want an optional agent review.
      - If accepted, run coordinate-transition --to AWAITING_APPROVAL.
      - If changes requested, run coordinate-transition --to DRAFT_PLAN.
      - If review requested, run coordinate-transition --to MULTI_AGENT_REVIEW.
  MULTI_AGENT_REVIEW:
    purpose: Execute the selected independent review of the current plan before returning to plan acceptance.
    question_policy: one_at_a_time
    entry_questions: []
    adaptive_follow_up_rules: []
    kickoff:
      mandatory_after_entry: true
      do_not_stop_after_transition: true
      runtime_entrypoint: "Use the selected review skill/runtime; for internal multi-agent review, bundle the current artifacts, dispatch the configured reviewer set, collect every report, and record the critic outcome before any return transition."
      internal_multi_agent_reviewer_set:
      - architecture reviewer
      - security auditor
      - TDD contract reviewer
      required_receipt_fields:
      - task_id
      - review_iteration
      - method
      - reviewer
      - runtime
      - model
      - effort
      - report_path_or_external_receipt
      - verdict
      - findings
      outcome_vocabulary:
      - PASS
      - REQUEST_CHANGES
      - REVIEW_FAILURE
      required_sequence:
      - Verify the selected review method and the current plan artifacts.
      - Create the bounded review bundle or load the approved internal review context.
      - Dispatch every selected reviewer with the recorded model, effort, and scope.
      - Collect each reviewer result and preserve its artifact path or external receipt.
      - Synthesize the collected reports into the canonical round brief before choosing the return edge.
      - Record one critic-review outcome linked to the raw-report manifest and synthesis brief.
      - Return to DRAFT_PLAN for requested changes, or return to PLAN_REVIEW for acceptance.
      continuation_rule: After entering MULTI_AGENT_REVIEW, continue through kickoff, dispatch, collection, and outcome recording in the same run; do not wait for another user prompt for routine internal work.
      failure_rule: If dispatch or collection cannot complete, record the exact blocker, affected reviewer or artifact, and the concrete recovery action; do not report the review as complete.
      approval_boundary: Reviewers may critique the plan but may not approve implementation, expand scope, modify production code, create a worktree, or push changes.
    evidence_requirements:
    - The review method and model/effort choice are persisted.
    - Every selected reviewer has a completed result or an explicit failure receipt.
    - Raw reports and one canonical synthesis/revision brief are persisted for the implementer or plan author.
    - A critic-review or review-skip receipt is persisted before leaving this stage.
    exit_requirements:
    - The recorded outcome names the exact return edge and any required plan changes.
    - No implementation capability is released by this review stage.
  IN_WORKTREE:
    purpose: Execute the approved implementation in the registered isolated worktree.
    question_policy: one_at_a_time
    entry_questions: []
    adaptive_follow_up_rules: []
    status_display:
      enabled: true
      lifecycle_states:
      - queued
      - in_progress
      - blocked
      - complete
      format: "Implementation status: {status}; agent: {agent}; model: {model}; effort: {effort}; worktree: {worktree}"
      unknown_value: "unobserved"
      user_summary_rule: Always tell the user whether implementation has started, which agent/runtime/model/effort is active when known, and the next gate; never imply completion from worktree creation alone.
    delegation_display:
      required_after_worktree_entry: true
      fields:
      - agent_count
      - assignments
      - runtime
      - model
      - effort
      - scope
      - status
      - started_at
      user_summary_template: "Implementation delegation: {agent_count} agent(s); assignments: {assignments}; runtime: {runtime}; model: {model}; effort: {effort}; scope: {scope}; status: {status}; started: {started_at}."
      dispatch_truth_rule: Do not report implementation as started until at least one authorized agent dispatch is observed; worktree creation alone is queued preparation.
    implementation_kickoff:
      mandatory_after_entry: true
      runtime_entrypoint: "ControlPlane.create_implementation_controller(...).run()"
      runtime_enforcement: "Use ImplementationController.run_verification() for focused, integration, and final-suite commands; the cadence guard rejects out-of-order or duplicate final-suite runs."
      do_not_wait_for_repeated_user_prompt: true
      ownership: "After APPROVED -> IN_WORKTREE, the implementation controller owns the work package until exit verification or an explicit blocker."
      pipeline_gate_policy: "Do not request lifecycle transitions for internal task dispatch, task review, or bounded fix rounds. Return to the pipeline only for exit verification, retrospective, or a human-authorized abort."
      continuation_loop: "dispatch -> observe -> review -> fix/re-dispatch -> scoped re-review; continue automatically while authorized and within the review bound."
      idle_rule: "Never leave an authorized work package silently idle: dispatch the next legal internal action, or record BLOCKED with the exact blocker and next action."
      authorization_scope: "APPROVED -> IN_WORKTREE authorizes the complete bounded implementation loop, including internal dispatches, reviews, and fix rounds, until exit verification or a genuine blocker. Do not ask the user to re-authorize these internal steps."
      user_prompt_boundary: "Do not pause for routine progress confirmation. Prompt the user only for a new material scope, destructive action, premium-model authorization not already recorded, unresolved blocker, or the post-implementation review/exit gate."
      required_preflight:
      - Probe the active runtime's native planning, worktree, and subagent capabilities; use a native facility only when explicitly reported, otherwise use the portable fallback.
      - Read the approved specification, implementation plan, and task ledger.
      - Verify the registered worktree contains or can safely access the approved artifacts and required source baseline.
      - Create or resume a persistent implementation ledger before dispatch.
      - Select the least costly model and effort that meet each task's complexity and the user's recorded tool availability.
      required_execution:
      - Split the approved ledger into bounded implementation tasks.
      - Dispatch one or more authorized implementer agents when tasks are independently reviewable; otherwise dispatch one integration implementer.
      - Record each dispatch with agent/runtime/model/effort/scope/start time before telling the user implementation is in_progress.
      - Review each completed task before dispatching dependent work; these are internal session events, not lifecycle transitions.
      blocked_behavior: If source baseline, approved artifacts, model authorization, or a security/destructive gate prevents dispatch, report status blocked with the exact blocker and next safe action; do not silently remain queued.
      model_effort_rule: Reuse an explicitly selected implementation model/effort for the same approved scope. Otherwise recommend and select a proportional supported route; seek confirmation only for a premium model, materially broader scope, or a new review round.
      cost_control_rule: "Use the least-cost capable route for each bounded task. Do not interrupt an active high-risk slice solely to change models; at the next verified checkpoint, prefer Luna medium (or the user's equivalent mid-tier tool) for independent review and routine fixes. Reserve premium models for high-complexity planning, architecture, or unresolved correctness risk."
      quota_awareness_rule: "Before dispatch, report the selected model, effort, complexity rationale, and known quota/reset constraint. If the active quota is low, prefer a cheaper capable route or defer non-urgent review until reset; never claim a reset time not observed from the runtime."
      test_cadence_rule: "For each micro-slice, run only focused tests covering the changed contract. Run the subsystem suite at an integration checkpoint and the full plugin suite only once before the P01 acceptance gate or equivalent release checkpoint; do not repeat long full-suite runs after every small edit unless a focused failure requires it."
      subagent_review_test_sequence: "Subagents must follow this order: focused tests for the slice; independent agent review after implementation; bounded fix/re-review rounds for findings; then one final full test and parity check before acceptance. A passing slice test is not an acceptance result, and a full-suite run does not replace independent review."
      simulator_acceptance_rule: "Any new lifecycle or authorization contract must add simulator scenarios before acceptance. The final check must execute the acceptance matrix through production ControlPlane/TransitionCoordinator paths, including every wildcard/override edge, normal-path preservation, authorized success, unauthorized denial, persistence consumption, and error contract; simulator success is required evidence, not optional regression coverage."
      session_continuity_rule: "Keep the implementing agent session alive through bounded review-fix rounds whenever the runtime supports continuation. Relay concrete reviewer findings into that same session immediately; do not close and reopen the implementation context for ordinary corrections. Independent reviews must be narrowly targeted to the changed contract and acceptance matrix."
      user_update_rule: Immediately after entry, report queued preparation. Immediately after the first dispatch, report in_progress with the delegation summary. After each task boundary, report completed/reviewed/blocked work and the next dispatch or gate.
    exit_requirements:
    - Implementation evidence and tests are recorded before reporting complete.
    - The implementation plan contains a fenced JSON Implementation Task Ledger with every in-scope task COMPLETE, evidence, and existing artifact paths before exit verification.
    - Active model and effort are reported from observed runtime metadata, not inferred from task title.
    completion_contract:
      definition: "Implementation is complete when the approved bounded work package is written in the registered worktree, the focused acceptance checks pass, and the implementation ledger records the evidence. This status does not mean committed, pushed, merged, or DONE."
      authority: "The registered worktree is the review source of truth. The main checkout is not an independent implementation authority and may contain pre-existing or mirrored task changes."
      session_change_inventory:
        mandatory: true
        run_on_every_session: true
        run_before_every_review_submission: true
        run_after_every_internal_fix_round: true
        reminder: "At every implementation checkpoint, compare the session-start baseline, main checkout, and registered worktree path by path. Ensure every file created or modified by this session is present with the intended content in the registered worktree before reporting implementation complete or requesting WORKTREE_REVIEW."
        ownership_rule: "A path changed after the session baseline is session-owned unless it is explicitly recorded as pre-existing. A session-owned main-only path is a blocker; it must not be classified as main_only_preexisting."
        required_fields:
        - session_baseline_reference
        - path
        - session_owned
        - main_status
        - worktree_status
        - content_match
        - disposition
        failure_rule: "Do not report completion or enter WORKTREE_REVIEW while any session-owned change is absent or mismatched in the registered worktree."
        recovery: "Synchronize the missing session-owned change into the registered worktree using the approved file/symlink workflow, rerun focused verification, and repeat the inventory until it passes. Preserve unrelated main changes."
        comparison_policy:
          implementation_files: "Require byte-identical intended content between main and the registered worktree."
          generated_metadata: "Allow regenerated installer metadata to differ only in expected timestamps or source-location bookkeeping; verify semantic entries and record the difference."
          missing_or_unclassified: "Always fail closed."
      reconciliation_manifest:
        required_before_integration: true
        purpose: "Reconcile the common base, task baseline, registered worktree, and main checkout before applying any reviewed patch."
        classifications:
        - worktree_only
        - main_only_preexisting
        - shared_task_change
        - generated_metadata
        - untracked
        required_fields:
        - path
        - common_base_blob_or_status
        - task_baseline_status
        - worktree_status
        - main_status
        - classification
        - disposition
      integration_contract:
        review_source: registered_worktree
        apply_reviewed_patch_once: true
        preserve_main_only_preexisting_changes: true
        commit_policy: "After WORKTREE_REVIEW, final verification, and the DONE operation gate, integrate the reviewed worktree patch once into the authorized integration checkout and create one commit. Do not commit both the worktree branch and main independently."
        push_policy: "Push only the verified integration commit after explicit human authorization at the push/DONE boundary; never push from IN_WORKTREE or WORKTREE_REVIEW."
      recovery: "If reconciliation finds conflicting task changes, missing worktree artifacts, or unclassified files, remain in the current gate, record the exact paths and classification failure, and resolve or explicitly exclude them before integration."
  RETROSPECTIVE:
    purpose: Capture the complete pipeline-close survey before allowing DONE.
    question_policy: one_at_a_time
    entry_questions:
    - question_id: retrospective_workflow_complete
      question: Did the run complete the full intended workflow end to end?
      options:
      - Yes
      - No
      default: No
    - question_id: retrospective_human_rescue
      question: Did the run require major human rescue?
      options:
      - Yes
      - No
      default: No
    - question_id: retrospective_uncertainty_count
      question: How many times did the agent not know what to do next?
      options: []
      default: '0'
    - question_id: retrospective_skipped_step_count
      question: How many times did the agent miss or skip a required step?
      options: []
      default: '0'
    - question_id: retrospective_cli_error_count
      question: How many times did the agent use the wrong CLI syntax?
      options: []
      default: '0'
    - question_id: retrospective_redirect_count
      question: How many times was the agent redirected by a human?
      options: []
      default: '0'
    - question_id: retrospective_uncertainty_point
      question: At what point was the agent most uncertain about what to do next?
      options: []
      default: ''
    - question_id: retrospective_ambiguity
      question: Which instruction, rule, or workflow step felt ambiguous or underspecified?
      options: []
      default: ''
    - question_id: retrospective_confusing_tool
      question: Which command, tool, or template was most confusing in practice?
      options: []
      default: ''
    - question_id: retrospective_biggest_friction
      question: What was the single biggest source of friction in this run?
      options: []
      default: ''
    - question_id: retrospective_avoidable_failure
      question: Which failure felt avoidable with a better prompt, skill, or rule?
      options: []
      default: ''
    - question_id: retrospective_smallest_improvement
      question: What smallest workflow change would have improved this run most?
      options: []
      default: ''
    - question_id: retrospective_next_change
      question: What one change should be tested before the next run?
      options: []
      default: ''
    - question_id: retrospective_evidence
      question: What evidence from this run supports that change?
      options: []
      default: ''
    - question_id: retrospective_target
      question: Is the target of that change a skill, prompt, script, or rule?
      options:
      - Skill
      - Prompt
      - Script
      - Rule
      default: Skill
    adaptive_follow_up_rules:
    - rule_id: confirmed_follow_up_issue
      when:
        question_id: retrospective_next_change
        not_empty: true
      questions:
      - question_id: retrospective_issue_worthy
        question: Is this follow-up worthy of a tracked issue?
        options:
        - Yes
        - No
        default: No
    exit_requirements:
    - Every entry question has an answer.
    - Every adaptive rule matching the recorded answers has been evaluated.
    - Issue-worthy follow-ups are confirmed and tracked before DONE.
    - The final complete-or-skip decision is asked only after this survey is complete.
    closeout_change_control:
      mandatory_before_done: true
      classifications:
      - already_resolved_in_current_package
      - bounded_fix_requires_rework_loop
      - larger_follow_up_requires_issue_or_new_work_package
      bounded_fix_rule: A bounded fix is never applied directly from RETROSPECTIVE -- it requires returning through the rework loop (IN_WORKTREE/WORKTREE_REVIEW) like any other implementation change.
      no_legal_return_rule: RETROSPECTIVE has no legal implementation return edge in the canonical DAG -- a genuine bounded fix requires an explicit human-approved recovery re-entry into IN_WORKTREE, not a silent exception.
      larger_follow_up_rule: Before opening a new issue or work package for a larger follow-up, run a duplicate search against existing open issues and map-debt entries covering the same root cause.
      agent_self_assessment:
        mandatory_before_done: true
        question: For each retrospective finding, is this a safe bounded fix now, or does it need a separate follow-up?
        response_policy: Record an explicit classification for every finding before DONE -- do not silently drop a finding without one.
        no_silent_action: true
  DONE:
    purpose: Confirm the human's git-integration intent for the verified worktree before any commit, push, or PR discussion, per worktree-lifecycle-management.md's six-state vocabulary.
    question_policy: one_at_a_time
    entry_questions:
    - question_id: done_git_integration_authorization
      question: Do you want to begin Git integration now (commit on the existing registered feature branch), or leave the verified changes as-is in the current worktree?
      options:
      - Yes, begin Git integration [Recommended]
      - No, leave the verified changes in the current worktree
      default: Yes, begin Git integration [Recommended]
    adaptive_follow_up_rules: []
    exit_requirements:
    - The git-integration authorization question has been answered.
    closeout_contract:
      feature_branch_policy: Reuse the task's existing registered feature branch (worktree_branch) -- never create a new branch at DONE, and never commit directly to main.
      commit_policy: Create exactly one commit for the verified work, with an evolution-check/map-debt reference per the Evolution Integrity Gate, before any push is discussed.
      push_policy: Ask separately, as an explicit isolated instruction, before running git push -- committing and pushing are never bundled into one authorization.
      post_done_protocol:
        overview: "When DONE is signed, the task lifecycle in SQLite is complete. The final repository convergence sequence follows: DONE -> Push Worktree Branch -> PR / Merge to Main -> Sync Main Locally -> Prune Worktree & Branch."
        steps:
        - step: 1
          name: push_worktree_branch
          execution_class: SOFT
          instruction: "Ask the human in chat: 'Task is marked DONE. Would you like me to push <worktree_branch> and create the pull request to main?' Upon confirmation, run `git push origin <worktree_branch>` and update SQLite worktree state to pushed_to_origin via `agent_control.py update-worktree`."
        - step: 2
          name: create_pull_request
          execution_class: SOFT
          instruction: "Open the PR via `gh pr create --base main --head <worktree_branch> ...`. State the PR URL and 'not yet merged', and await the user's review/merge on GitHub."
        - step: 3
          name: sync_local_main
          execution_class: AGENT
          instruction: "Once merged into origin/main, checkout main in the repository root and pull: `cd <repo_root> && git checkout main && git pull origin main`. Update SQLite worktree state to merged_into_origin_main."
        - step: 4
          name: prune_worktree_and_branch
          execution_class: AGENT
          instruction: "Verify clean state on main, then remove the worktree and delete the local task branch: `git worktree remove .worktrees/<task-id> && git branch -d <worktree_branch>`."

intake_guidance:
  source_documents:
    authorization_required: true
    inferred_answers_require_confirmation: true
    documents_cannot_grant_approval: true
    resume_confirmed_answers: true
  review_rounds:
    ceilings_minutes: {QUICK: 5, STANDARD: 15, SIGNIFICANT: 30}
    shared_whole_round_budget: true
    timeout_status: partial_timeout
  precompletion_summary:
    machine_gate:
      audience: internal
      preserve_fields: true
      evaluate_all_checks: true
    user_summary:
      audience: user
      plain_language: true
      hide_machine_gate_details: true
      explain_map_debt_as: "a follow-up the agents recorded for later improvement"
      say_whether_user_action_is_needed: true
      ask_one_question_at_a_time: true
      ask_only_if_human_decision_is_required: true
      user_rule: Tell the user what was checked, whether anything blocks the next step, and the single next question or action in plain language.
    internal_follow_up:
      if_any_check_is_yes: "Handle the result internally as FIX, MAP_DEBT, or ESCALATE; do not turn the machine checklist into a user questionnaire."
human_recovery:
  enabled: true
  source_states: Any canonical state
  target_states: Any different canonical state
  evidence: Requires a consumed, human-authored APPROVAL decision bound to the exact current occupancy transition_id -- this occupancy binding is what distinguishes a genuine human recovery from a replayed or stale approval.
  reentry_rule: Re-entering a state via human recovery restores that state's normal capabilities only -- it does not grant downstream capability that the destination state would not otherwise release, and does not retroactively authorize any transition beyond this one.
  safety_boundary: Recovery targets must be canonical states; unknown states are always rejected regardless of any recorded human approval, since an unknown state has no defined capability or gate contract to enforce.
execution_guidance:
  work_package:
    advisory: true
    required_fields: &execution_guidance_fields
    - objective
    - scope_boundary
    - prerequisites
    - authority
    - expected_artifacts
    - validation_command
    - completion_evidence
    - handoff_condition
    - failure_recovery
    instruction: Define the approved work-package outcome, boundaries, delegated authority, artifacts, validation, handoff, and recovery before executing its tasks.
  task:
    advisory: true
    required_fields: *execution_guidance_fields
    instruction: Execute one bounded task from the work package; preserve its scope, use the approved authority, produce its named artifacts, run its validation, and report completion or recovery evidence.
  slice:
    advisory: true
    required_fields: *execution_guidance_fields
    instruction: Treat each slice as a small independently verifiable increment; state its prerequisites, implement only its boundary, validate it, and hand off only with the required evidence.
  transition:
    advisory: true
    required_fields: *execution_guidance_fields
    instruction: "Before each lifecycle transition, resolve the edge guidance, satisfy its questions and checks through the supported mechanism, and use the success or denial recovery path without treating advisory text as authority. A human answer received in chat must be persisted through --interactive, never --answers, so SQLite records actor=human. After a human answer is accepted, immediately persist the decision, complete the requested transition, load the destination state's stage contract, and ask its next question or execute its deterministic handoff; never stop after merely acknowledging an answer."
  execution_step:
    advisory: true
    required_fields: *execution_guidance_fields
    instruction: Perform the next concrete command or edit only after confirming its prerequisite; record the expected artifact or test evidence and stop for a gate, failure, or scope change.

model_effort_guidance:
  interview:
    recommended_model: current-user-model
    recommended_effort: low
    reason: Intake answers are bounded; reuse authorized source answers and ask only unresolved questions.
    requires_confirmation_for_premium: true
  plan:
    recommended_model: user-selected-planning-model
    recommended_effort: high
    reason: Planning resolves architecture and acceptance evidence; a premium model may be useful but requires explicit confirmation.
    requires_confirmation_for_premium: true
  review:
    recommended_model: user-selected-review-model
    recommended_effort: medium
    reason: Independent review should be proportionate to risk and may use a different model from planning.
    requires_confirmation_for_premium: true
  implementation:
    recommended_model: user-selected-implementation-model
    recommended_effort: medium
    reason: Implementation should use the least costly supported route that meets the evidence contract; after a premium checkpoint, use a mid-tier model such as Luna medium for review and routine fixes when risk permits.
    requires_confirmation_for_premium: true

templates:
- transition_id: intake_to_interview
  from_state: INTAKE
  to_state: INTERVIEW
  purpose: Begin interactive requirements capture and Socratic defaulting with human user.
  next_steps_hint: "First satisfy prior_art_scan; use: log-prior-art --task-id <task-id>. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to INTERVIEW."
  guidance:
    success: "After prior-art evidence is recorded, enter INTERVIEW to collect the user's requirements one question at a time."
    helper_commands:
    - "@AGENT_CONTROL_CMD@ log-prior-art --task-id <task-id> --summary '<summary>'"
  checklist:
  - Current task state is persisted as INTAKE
  - 'Deterministic check satisfied: prior_art_scan'
  required_artifacts: []
  deterministic_checks:
  - prior_art_scan
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - interview_question
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition INTAKE -> INTERVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from INTAKE to INTERVIEW is deterministically governed by automated checks and artifacts.
- transition_id: force_retrospective_from_interview
  from_state: INTERVIEW
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from INTERVIEW, bypassing the normal interview-completeness gate, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as INTERVIEW
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal interview-completeness gate. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition INTERVIEW -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from INTERVIEW, bypassing the normal interview-completeness gate.
- transition_id: intake_to_draft_plan
  from_state: INTAKE
  to_state: DRAFT_PLAN
  purpose: Advance lifecycle state from INTAKE to DRAFT_PLAN upon satisfying phase requirements and verifications.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN."
  checklist:
  - Current task state is persisted as INTAKE
  - Structural DAG transition from INTAKE to DRAFT_PLAN is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition INTAKE -> DRAFT_PLAN denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from INTAKE to DRAFT_PLAN is deterministically governed by automated checks and artifacts.
# Review-state entry edges use a binary submit/revise question: they decide
# whether the current artifacts are ready for that destination. Review-method
# selection and explicit review skips are separate target-specific edges.
- transition_id: intake_to_plan_review
  from_state: INTAKE
  to_state: PLAN_REVIEW
  purpose: Advance lifecycle state from INTAKE to PLAN_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW."
  checklist:
  - Current task state is persisted as INTAKE
  - Structural DAG transition from INTAKE to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_intake_to_plan_review
    question: Submit artifacts for review in PLAN_REVIEW?
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition INTAKE -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into PLAN_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: intake_to_escalated
  from_state: INTAKE
  to_state: ESCALATED
  purpose: Escalate task from INTAKE due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as INTAKE
  - Structural DAG transition from INTAKE to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition INTAKE -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from INTAKE to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: interview_to_draft_plan
  from_state: INTERVIEW
  to_state: DRAFT_PLAN
  purpose: Confirm the interview outline is complete and hand it to DRAFT_PLAN. STANDARD work receives the full plan contract; TRIVIAL work receives a concise implementation plan without the standard-only planning questions.
  next_steps_hint: "Record the applicable interview answers through the supported interview-question mechanism; each answer updates docs/plans/work-tasks/<task-id>/<task-id>-plan-outline.md. For TRIVIAL, capture only intent, smallest scope, verification and trivial-change evidence. For STANDARD, complete the full acceptance and planning-model questions. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN. DRAFT_PLAN compiles the route-appropriate plan using native host plan mode (Claude /plan, Copilot @plan, Antigravity plan mode); for STANDARD tasks, evaluate execution topology via select-loop-strategy among peer patterns."
  checklist:
  - Current task state is persisted as INTERVIEW
  - The route-appropriate interview questions and evidence are complete
  - Interview plan outline is persisted and reviewable
  required_artifacts: []
  deterministic_checks:
  - interview_plan_route_complete
  stage_question_ids:
  - interview_classification
  - interview_summary
  - interview_scope
  - interview_verification
  - interview_trivial_evidence
  - interview_acceptance_criteria
  - interview_planning_model_effort
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - plan_write
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  guidance:
    success: "TRIVIAL uses the short plan route: direct execution, concise plan, skip external reviewers. STANDARD retains the full planning contract: leverage native host plan mode and assess orchestration options via select-loop-strategy before submitting to PLAN_REVIEW."
    denial: "The route-specific interview evidence is incomplete; do not promote TRIVIAL work to implementation until the smallest scope and focused verification are explicit."
  denial_message: 'Transition INTERVIEW -> DRAFT_PLAN denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from INTERVIEW to DRAFT_PLAN is deterministically governed by automated checks and artifacts.
- transition_id: interview_to_plan_review
  from_state: INTERVIEW
  to_state: PLAN_REVIEW
  purpose: Advance lifecycle state from INTERVIEW to PLAN_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. First satisfy plan_mode_or_socratic, interview_standard_complete; use: record-plan-mode-entry or record-socratic-intake; verify-interview-question. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW."
  checklist:
  - Current task state is persisted as INTERVIEW
  - 'Deterministic check satisfied: plan_mode_or_socratic'
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks:
  - plan_mode_or_socratic
  - interview_standard_complete
  stage_question_ids:
  - interview_classification
  - interview_summary
  - interview_scope
  - interview_verification
  - interview_acceptance_criteria
  - interview_planning_model_effort
  stage_route:
    question_id: interview_classification
    equals: STANDARD
  human_questions:
  - question_id: confirm_review_interview_to_plan_review
    question: Submit artifacts for review in PLAN_REVIEW?
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition INTERVIEW -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into PLAN_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: interview_to_escalated
  from_state: INTERVIEW
  to_state: ESCALATED
  purpose: Escalate task from INTERVIEW due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as INTERVIEW
  - Structural DAG transition from INTERVIEW to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition INTERVIEW -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from INTERVIEW to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: draft_plan_to_plan_review
  from_state: DRAFT_PLAN
  to_state: PLAN_REVIEW
  purpose: Submit the authored plan to the PLAN_REVIEW disposition-and-acceptance gate.
  guidance:
    success: "For TRIVIAL work, submit the concise plan for user review and use focused review evidence; skip independent reviewers unless the user requests them or risk warrants escalation. STANDARD work retains the normal review-selection contract and must declare an execution strategy (direct, dual-loop, graph, agent-swarm, red-team-review, learning-loop, or triple-loop-learning) and compile its corresponding plan artifact before submitting to PLAN_REVIEW."
    denial: "Keep the task in DRAFT_PLAN until the route-appropriate plan artifact is complete."
  next_steps_hint: "The plan is drafted. This is a SOFT edge: (1) In chat, ask the human: 'Would you like to submit the drafted plan for review?'. (2) Once the human approves in chat, YOU run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW --human-confirmed 'HUMAN-CONFIRMED: <quote>'. If submitted, PLAN_REVIEW separately asks whether agents should review the draft and, when requested, which supported review method to use. Explicit review skips and plan revisions use their own target-specific transitions. No plan-review choice approves implementation."
  checklist:
  - Current task state is persisted as DRAFT_PLAN
  - Structural DAG transition from DRAFT_PLAN to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_draft_plan_to_plan_review
    question: 'Would you like to submit the drafted plan for review?'
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition DRAFT_PLAN -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into PLAN_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: draft_plan_to_interview
  from_state: DRAFT_PLAN
  to_state: INTERVIEW
  purpose: Advance lifecycle state from DRAFT_PLAN to INTERVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to INTERVIEW."
  checklist:
  - Current task state is persisted as DRAFT_PLAN
  - Structural DAG transition from DRAFT_PLAN to INTERVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition DRAFT_PLAN -> INTERVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from DRAFT_PLAN to INTERVIEW is deterministically governed by automated checks and artifacts.
- transition_id: draft_plan_to_escalated
  from_state: DRAFT_PLAN
  to_state: ESCALATED
  purpose: Escalate task from DRAFT_PLAN due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as DRAFT_PLAN
  - Structural DAG transition from DRAFT_PLAN to ESCALATED is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition DRAFT_PLAN -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from DRAFT_PLAN to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: multi_agent_review_to_draft_plan
  from_state: MULTI_AGENT_REVIEW
  to_state: DRAFT_PLAN
  purpose: Advance lifecycle state from MULTI_AGENT_REVIEW to DRAFT_PLAN upon satisfying phase requirements and verifications.
  next_steps_hint: "Return to DRAFT_PLAN to revise the plan artifacts. A later review submission must have a changed artifact identity or a matching plan_artifact_revision receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN."
  checklist:
  - Current task state is persisted as MULTI_AGENT_REVIEW
  - Structural DAG transition from MULTI_AGENT_REVIEW to DRAFT_PLAN is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - plan_write
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition MULTI_AGENT_REVIEW -> DRAFT_PLAN denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from MULTI_AGENT_REVIEW to DRAFT_PLAN is deterministically governed by automated checks and artifacts.
# Human answer handling: the coordinator canonicalizes unambiguous shorthand (for example,
# "Proceed with review") to the exact registered option below and persists that canonical
# value. Ambiguous answers must be clarified; agents must not guess.
- transition_id: multi_agent_review_to_plan_review
  from_state: MULTI_AGENT_REVIEW
  to_state: PLAN_REVIEW
  purpose: Merge completed independent review outcomes back into PLAN_REVIEW for the plan-acceptance decision.
  next_steps_hint: "Record the passing critic outcome, summarize any revisions, and run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW. The next PLAN_REVIEW -> AWAITING_APPROVAL edge asks whether the plan is accepted or requires further revisions."
  checklist:
  - Current task state is persisted as MULTI_AGENT_REVIEW
  - Structural DAG transition from MULTI_AGENT_REVIEW to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks:
  - critic_review_pass
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition MULTI_AGENT_REVIEW -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: A passing recorded critic outcome deterministically returns the completed review to PLAN_REVIEW for acceptance.
- transition_id: multi_agent_review_to_escalated
  from_state: MULTI_AGENT_REVIEW
  to_state: ESCALATED
  purpose: Escalate task from MULTI_AGENT_REVIEW due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as MULTI_AGENT_REVIEW
  - Structural DAG transition from MULTI_AGENT_REVIEW to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition MULTI_AGENT_REVIEW -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from MULTI_AGENT_REVIEW to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: plan_review_to_multi_agent_review
  from_state: PLAN_REVIEW
  to_state: MULTI_AGENT_REVIEW
  purpose: Select the requested independent review method after the plan was submitted for review.
  next_steps_hint: "PLAN_REVIEW uses review-selection-v1. Ask one question at a time using the same sequence as implementation review: (1) ask whether the user wants agents to review the draft plan; (2) only after Yes, show all four review methods together—single-agent internal, single-agent external bundle, multi-agent internal, and multi-agent external bundle; (3) only for an internal method, ask separately for the CLI/runtime, model, and effort, resolving each from the confirmed profile and cli-agent model catalog. Before asking, run agent_control.py inspect-decisions --task-id <task-id> to re-read what is already recorded instead of relying on memory. If context/agent-capability-profile.json is missing or unreadable, say so and route the human to cli-agent project setup (the init mode of the running-control-plane skill); do not assume any runtime or model. Run agent_control.py list-review-options (read-only) so the human can copy the exact runtime and model identifiers instead of retyping them from memory. For an internal method the coordinator asks the three selections interactively and the human types each one; agents cannot supply them or apply defaults. Do not dispatch an internal reviewer before all three explicit selections are recorded. Persist chat answers through --interactive so SQLite records actor=human. If No, the HUMAN records the skip decision through the interactive command (--interactive); the agent never runs record-review-skip from a chat message or on the human's behalf. Then use PLAN_REVIEW -> AWAITING_APPROVAL. For an accepted review choice, run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to MULTI_AGENT_REVIEW, then immediately execute the MULTI_AGENT_REVIEW.kickoff.required_sequence through outcome recording; do not stop after acknowledging the transition."
  review_selection_contract: review-selection-v1
  review_selection:
    scope: draft_plan
    user_choice_required_for_internal: true
    recommendation_source: model_effort_guidance.review
    catalog_source: review_selection_contract.catalog_resolution
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - Structural DAG transition from PLAN_REVIEW to MULTI_AGENT_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: plan_review_agent_review_decision
    question: 'Would you like agents to review the draft plan?'
    options:
    - Yes — continue to review method selection [Recommended]
    - No — skip agent review and continue to plan acceptance
    accepted_answers:
    - Yes — continue to review method selection [Recommended]
    default: Yes — continue to review method selection [Recommended]
  - question_id: plan_review_method
    question: 'Which review method would you like?'
    options:
    - Single-agent review — internal
    - Single-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    - Multi-agent review — internal [Recommended]
    - Multi-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    accepted_answers:
    - Single-agent review — internal
    - Single-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    - Multi-agent review — internal [Recommended]
    - Multi-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    default: Multi-agent review — internal [Recommended]
  - question_id: plan_review_internal_cli_runtime
    question: 'Which CLI/runtime should run the internal review? Type one that is confirmed available in context/agent-capability-profile.json; do not assume the host agent.'
    options: []
    choices_from:
      kind: runtime
    asked_when:
      question_id: plan_review_method
      answer_contains: '— internal'
  - question_id: plan_review_internal_model
    question: 'Which model should the internal review use? Type one from the current cli-agent model catalog for that runtime; no default is applied.'
    options: []
    choices_from:
      kind: model
      runtime_question: plan_review_internal_cli_runtime
    asked_when:
      question_id: plan_review_method
      answer_contains: '— internal'
  - question_id: plan_review_internal_effort
    question: 'Which reasoning effort should the internal review use? Type the level; no default is applied.'
    options: []
    choices_from:
      kind: effort
      runtime_question: plan_review_internal_cli_runtime
    asked_when:
      question_id: plan_review_method
      answer_contains: '— internal'
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition PLAN_REVIEW -> MULTI_AGENT_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from PLAN_REVIEW to MULTI_AGENT_REVIEW is deterministically governed by automated checks and artifacts.
- transition_id: plan_review_to_awaiting_approval
  from_state: PLAN_REVIEW
  to_state: AWAITING_APPROVAL
  purpose: "Record plan acceptance and move the task to AWAITING_APPROVAL. There the human (not you) signs to approve implementation."
  guidance:
    success: "Agent review is optional. When the human accepts the plan, you (the agent) run this transition. No review or skip receipt is needed."
    denial: "Do not advance without human acceptance of the plan. Return to DRAFT_PLAN for changes or ask the human."
  next_steps_hint: |
    YOU ARE IN PLAN_REVIEW. This is where the HUMAN decides about the plan. Do exactly this:
    1. Ask the human in chat: "Do you accept the plan, or do you want changes, or an agent review?" Ask ONCE. If they already said, do not ask again.
    2. If they ACCEPT: YOU run `@AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to AWAITING_APPROVAL`. Do NOT hand this command to the human. No agent review and no skip is needed. Skipping the review is not a bypass; it is a normal path. (If an agent review was conducted, record with record-critic-review, or if skipped by human decision record-review-skip, but review is strictly optional).
    3. If they want CHANGES: you run `@AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN`.
    4. If they want an AGENT REVIEW (optional): you run `@AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to MULTI_AGENT_REVIEW`.
    WHAT HAPPENS NEXT: in AWAITING_APPROVAL the HUMAN signs with their SSH key (they type their passphrase). You cannot do that step. Give them the complete command then.
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - The human said they ACCEPT the plan (in chat, or by answering confirm_plan_acceptance).
  required_artifacts: []
  deterministic_checks: []
  human_questions:
  - question_id: confirm_plan_acceptance
    question: Do you accept the plan as it is, or do you require further revisions?
    options:
    - Accept plan and proceed to human approval [Recommended]
    - Require further revisions
    accepted_answers:
    - Accept plan and proceed to human approval [Recommended]
    default: Accept plan and proceed to human approval [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: "Denied: the human has not accepted the plan yet. Ask them in chat (step 1), then run this again. You do not need a review or a skip."
  authority:
    type: deterministic
    explanation: Transition from PLAN_REVIEW to AWAITING_APPROVAL is deterministically governed by automated checks and artifacts.
- transition_id: plan_review_to_draft_plan
  from_state: PLAN_REVIEW
  to_state: DRAFT_PLAN
  purpose: Advance lifecycle state from PLAN_REVIEW to DRAFT_PLAN upon satisfying phase requirements and verifications.
  next_steps_hint: "Return to DRAFT_PLAN to revise the plan artifacts. A later review submission must have a changed artifact identity or a matching plan_artifact_revision receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN."
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - Structural DAG transition from PLAN_REVIEW to DRAFT_PLAN is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: confirm_plan_revision
    question: Would you like to make any changes to the plan?
    options:
    - Yes — return to DRAFT_PLAN to make changes [Recommended]
    accepted_answers:
    - Yes — return to DRAFT_PLAN to make changes [Recommended]
    default: Yes — return to DRAFT_PLAN to make changes [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - plan_write
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition PLAN_REVIEW -> DRAFT_PLAN denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from PLAN_REVIEW to DRAFT_PLAN is deterministically governed by automated checks and artifacts.
- transition_id: plan_review_to_interview
  from_state: PLAN_REVIEW
  to_state: INTERVIEW
  purpose: Advance lifecycle state from PLAN_REVIEW to INTERVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to INTERVIEW."
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - Structural DAG transition from PLAN_REVIEW to INTERVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition PLAN_REVIEW -> INTERVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from PLAN_REVIEW to INTERVIEW is deterministically governed by automated checks and artifacts.
- transition_id: plan_review_to_escalated
  from_state: PLAN_REVIEW
  to_state: ESCALATED
  purpose: Escalate task from PLAN_REVIEW due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - Structural DAG transition from PLAN_REVIEW to ESCALATED is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition PLAN_REVIEW -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from PLAN_REVIEW to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: awaiting_approval_to_approved
  from_state: AWAITING_APPROVAL
  to_state: APPROVED
  requires_cryptographic_proof: true
  purpose: Obtain explicit human approval to proceed with task implementation and worktree creation.
  guidance:
    success: "TRIVIAL and STANDARD both require explicit implementation approval here. This is the capability boundary that releases worktree/code access; do not infer it from plan acceptance."
    denial: "Without explicit implementation approval, remain pre-worktree regardless of task size."
  next_steps_hint: "Human-signed gate. Run coordinate-transition --task-id <task-id> --to APPROVED. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, hashes of the reviewed spec and plan, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs agent_control.py show-challenge --request-id N, signs, and runs approve-transition --request-id N. No prompt, typed word, --answers, --human-confirmed or flag can authorize this edge."
  checklist:
  - Current task state is persisted as AWAITING_APPROVAL
  - Structural DAG transition from AWAITING_APPROVAL to APPROVED is legal
  - 'Deterministic check satisfied: main_clean_before_approval'
  required_artifacts: []
  deterministic_checks:
  - main_clean_before_approval
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - push branch to origin
  denial_message: 'Transition AWAITING_APPROVAL -> APPROVED denied: preconditions or required decisions not satisfied.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: awaiting_approval_to_plan_review
  from_state: AWAITING_APPROVAL
  to_state: PLAN_REVIEW
  purpose: Advance lifecycle state from AWAITING_APPROVAL to PLAN_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW."
  checklist:
  - Current task state is persisted as AWAITING_APPROVAL
  - Structural DAG transition from AWAITING_APPROVAL to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_awaiting_approval_to_plan_review
    question: Submit artifacts for review in PLAN_REVIEW?
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition AWAITING_APPROVAL -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into PLAN_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: awaiting_approval_to_draft_plan
  from_state: AWAITING_APPROVAL
  to_state: DRAFT_PLAN
  purpose: Advance lifecycle state from AWAITING_APPROVAL to DRAFT_PLAN upon satisfying phase requirements and verifications.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to DRAFT_PLAN."
  checklist:
  - Current task state is persisted as AWAITING_APPROVAL
  - Structural DAG transition from AWAITING_APPROVAL to DRAFT_PLAN is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - plan_write
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition AWAITING_APPROVAL -> DRAFT_PLAN denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from AWAITING_APPROVAL to DRAFT_PLAN is deterministically governed by automated checks and artifacts.
- transition_id: awaiting_approval_to_escalated
  from_state: AWAITING_APPROVAL
  to_state: ESCALATED
  purpose: Escalate task from AWAITING_APPROVAL due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as AWAITING_APPROVAL
  - Structural DAG transition from AWAITING_APPROVAL to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition AWAITING_APPROVAL -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from AWAITING_APPROVAL to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: approved_to_in_worktree
  from_state: APPROVED
  to_state: IN_WORKTREE
  purpose: Create isolated git worktree and begin test-first implementation.
  guidance:
    success: "TRIVIAL uses one bounded implementation slice and focused verification only. Run the full suite only when the user requests it or the changed surface makes focused verification insufficient. STANDARD follows its approved verification scope."
    denial: "Do not create a worktree or edit production code before the approved boundary and isolation checks pass."
  next_steps_hint: "First record human approval with record-human-approval --task-id <task-id> --approver <approver>. Then create or select an isolated feature worktree and branch, record both with update-worktree, and run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to IN_WORKTREE. The transition itself auto-reconciles any dirty source-checkout changes into the worktree (main_worktree_reconciliation deterministic check) — do not manually claim pre-worktree changes were carried over; the check does this by code and fails closed on any unresolved conflict. After entry, report the required delegation summary: agent count, assignments, runtime, model, effort, scope, status, and start time. State queued until an authorized agent dispatch is observed; then state in_progress. Worktree creation alone is not implementation completion. If the user explicitly authorizes implementation in the existing checkout, record it with record-receipt --gate existing_worktree_exception --cmd approved-existing-checkout:<approver> --exit-code 0 before transitioning."
  checklist:
  - Current task state is persisted as APPROVED
  - 'Deterministic check satisfied: human_approval'
  required_artifacts: []
  deterministic_checks:
  - human_approval
  - worktree_isolation_or_exception
  - main_worktree_reconciliation
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition APPROVED -> IN_WORKTREE denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from APPROVED to IN_WORKTREE is deterministically governed by automated checks and artifacts.
- transition_id: approved_to_retrospective_planning_only
  from_state: APPROVED
  to_state: RETROSPECTIVE
  purpose: Complete a planning-only work package without creating an implementation worktree.
  next_steps_hint: "This is an explicit planning-only completion path with no worktree. Record human approval, verify the plan artifacts, then record a planning_only_completion receipt. Run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE. Implementation, worktree creation, and code claims remain prohibited."
  checklist:
  - Current task state is persisted as APPROVED
  - 'Deterministic check satisfied: human_approval'
  - 'Deterministic check satisfied: planning_only_completion'
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks:
  - human_approval
  - planning_only_completion
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - claim implementation completion
  - push branch to origin
  denial_message: 'Transition APPROVED -> RETROSPECTIVE (planning-only) denied: approval, plan evidence, or planning-only completion receipt is missing.'
  authority:
    type: deterministic
    explanation: Planning-only completion requires explicit human approval and a durable receipt distinguishing plan completion from implementation completion.
- transition_id: approved_to_escalated
  from_state: APPROVED
  to_state: ESCALATED
  purpose: Escalate task from APPROVED due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as APPROVED
  - Structural DAG transition from APPROVED to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition APPROVED -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from APPROVED to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: in_worktree_to_worktree_review
  from_state: IN_WORKTREE
  to_state: WORKTREE_REVIEW
  purpose: "Implementation is complete in the registered worktree; submit the bounded, verified worktree diff to WORKTREE_REVIEW."
  guidance:
    success: "For TRIVIAL work, present the focused diff and focused test result to the user; defer broad/full-suite testing unless requested or required by affected-surface risk. STANDARD retains its approved test-suite contract."
    denial: "Keep implementation bounded and add only the focused evidence needed for the approved change."
  next_steps_hint: "Implementation is complete only after the approved work package is written and focused verification passes; it is not committed, pushed, merged, or DONE. Before every review submission and after every internal fix round, run the session-wide change inventory and ensure every session-owned file is present and content-matched in the registered worktree. The test_suite_or_deferred_to_review deterministic check runs before this edge's own questions are ever presented, so it must be satisfied by a receipt recorded BEFORE calling coordinate-transition, not by answering confirm_test_suite_or_defer in the same call: run @AGENT_CONTROL_CMD@ record-receipt --task-id <task-id> --gate test_suite --cmd '<the pytest command actually run>' --exit-code 0 --human-confirmed 'HUMAN-CONFIRMED: <quote>' if the suite already passed, or the same command with --gate test_suite_deferred_to_review if deferring to the later MULTI_AGENT_CODE_REVIEW/VERIFY_EXIT gate instead. Before integration, create the reconciliation manifest required by the IN_WORKTREE completion contract, classify worktree-only, main-only-preexisting, shared-task, and untracked paths, then apply the reviewed worktree patch once. After review and final verification, run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to WORKTREE_REVIEW."
  checklist:
  - Current task state is persisted as IN_WORKTREE
  - 'Deterministic check satisfied: test_suite_or_deferred_to_review'
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  - .worktrees/<task-id>
  deterministic_checks:
  - test_suite_or_deferred_to_review
  human_questions:
  - question_id: confirm_review_in_worktree_to_worktree_review
    question: Implementation is complete in the registered worktree. Do you wish to proceed to WORKTREE_REVIEW?
    options:
    - Proceed to WORKTREE_REVIEW [Recommended]
    accepted_answers:
    - Proceed to WORKTREE_REVIEW [Recommended]
    default: Proceed to WORKTREE_REVIEW [Recommended]
  - question_id: confirm_test_suite_or_defer
    question: "No test_suite verification receipt is recorded yet. Run tests now, or defer testing to the later MULTI_AGENT_CODE_REVIEW/VERIFY_EXIT gate (which independently re-checks test_suite/full_test_suite)?"
    options:
    - Defer to later review/control step [Recommended]
    - Run tests now instead
    accepted_answers:
    - Defer to later review/control step [Recommended]
    - Run tests now instead
    default: Defer to later review/control step [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition IN_WORKTREE -> WORKTREE_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into WORKTREE_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: in_worktree_to_rolled_back
  from_state: IN_WORKTREE
  to_state: ROLLED_BACK
  purpose: Roll back worktree changes from IN_WORKTREE to clean baseline.
  next_steps_hint: "First satisfy rolled_back_guard; use: record the rollback verification receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ROLLED_BACK."
  checklist:
  - Current task state is persisted as IN_WORKTREE
  - 'Deterministic check satisfied: rolled_back_guard'
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks:
  - rolled_back_guard
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition IN_WORKTREE -> ROLLED_BACK denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from IN_WORKTREE to ROLLED_BACK is deterministically governed by automated checks and artifacts.
- transition_id: in_worktree_to_escalated
  from_state: IN_WORKTREE
  to_state: ESCALATED
  purpose: Escalate task from IN_WORKTREE due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as IN_WORKTREE
  - Structural DAG transition from IN_WORKTREE to ESCALATED is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition IN_WORKTREE -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from IN_WORKTREE to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: worktree_review_to_multi_agent_code_review
  from_state: WORKTREE_REVIEW
  to_state: MULTI_AGENT_CODE_REVIEW
  purpose: Submit worktree code diff for independent multi-agent adversarial code review.
  next_steps_hint: "WORKTREE_REVIEW uses review-selection-v1. Ask one question at a time: (1) ask whether the user wants agents to review the implementation; (2) only after Yes, show all four review methods together—single-agent internal, single-agent external bundle, multi-agent internal, and multi-agent external bundle; (3) only for an internal method, ask separately for the CLI/runtime, model, and effort, resolving each from the confirmed profile and cli-agent model catalog. Before asking, run agent_control.py inspect-decisions --task-id <task-id> to re-read what is already recorded instead of relying on memory. If context/agent-capability-profile.json is missing or unreadable, say so and route the human to cli-agent project setup (the init mode of the running-control-plane skill); do not assume any runtime or model. Run agent_control.py list-review-options (read-only) so the human can copy the exact runtime and model identifiers instead of retyping them from memory. For an internal method the coordinator asks the three selections interactively and the human types each one; agents cannot supply them or apply defaults. Do not dispatch an internal reviewer before all three explicit selections are recorded. Persist chat answers through --interactive so SQLite records actor=human. Then complete this edge's checklist and run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to MULTI_AGENT_CODE_REVIEW."
  review_selection_contract: review-selection-v1
  review_selection:
    scope: implementation
    user_choice_required_for_internal: true
    recommendation_source: model_effort_guidance.review
    catalog_source: review_selection_contract.catalog_resolution
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  - Structural DAG transition from WORKTREE_REVIEW to MULTI_AGENT_CODE_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_worktree_review_to_multi_agent_code_review
    question: 'Would you like agents to review the implementation?'
    options:
    - Yes — continue to review method selection [Recommended]
    - No — skip agent review and continue to exit verification
    accepted_answers:
    - Yes — continue to review method selection [Recommended]
  - question_id: implementation_review_method
    question: 'Which review method would you like?'
    options:
    - Single-agent review — internal
    - Single-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    - Multi-agent review — internal [Recommended]
    - Multi-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    accepted_answers:
    - Single-agent review — internal
    - Single-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    - Multi-agent review — internal [Recommended]
    - Multi-agent review — external bundle (agent generates bundle, waits for you to upload to an independent model and report back)
    default: Multi-agent review — internal [Recommended]
  - question_id: implementation_review_internal_cli_runtime
    question: 'Which CLI/runtime should run the internal review? Type one that is confirmed available in context/agent-capability-profile.json; do not assume the host agent.'
    options: []
    choices_from:
      kind: runtime
    asked_when:
      question_id: implementation_review_method
      answer_contains: '— internal'
  - question_id: implementation_review_internal_model
    question: 'Which model should the internal review use? Type one from the current cli-agent model catalog for that runtime; no default is applied.'
    options: []
    choices_from:
      kind: model
      runtime_question: implementation_review_internal_cli_runtime
    asked_when:
      question_id: implementation_review_method
      answer_contains: '— internal'
  - question_id: implementation_review_internal_effort
    question: 'Which reasoning effort should the internal review use? Type the level; no default is applied.'
    options: []
    choices_from:
      kind: effort
      runtime_question: implementation_review_internal_cli_runtime
    asked_when:
      question_id: implementation_review_method
      answer_contains: '— internal'
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition WORKTREE_REVIEW -> MULTI_AGENT_CODE_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into MULTI_AGENT_CODE_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: worktree_review_to_verify_exit
  from_state: WORKTREE_REVIEW
  to_state: VERIFY_EXIT
  requires_cryptographic_proof: true
  purpose: Advance reviewed code to final exit verification and baseline sovereignty checks.
  guidance:
    success: "TRIVIAL uses the focused verification receipt and does not run the repository-wide suite unless the user asks or approves it. STANDARD uses the full approved verification contract."
    denial: "Do not broaden verification silently; record the focused result or obtain explicit approval for broader testing."
  next_steps_hint: "Human-signed gate. Run coordinate-transition --task-id <task-id> --to VERIFY_EXIT. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, commit SHA, tracked-diff hash, untracked-files hash, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs agent_control.py show-challenge --request-id N, signs, and runs approve-transition --request-id N. If the code changes after the request the approval is refused and a new request is needed. No prompt, typed word, --answers, --human-confirmed or flag can authorize this edge."
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - exit_verification
  capabilities_prohibited: []
  denial_message: 'Transition WORKTREE_REVIEW -> VERIFY_EXIT denied: preconditions or required decisions not satisfied.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: worktree_review_to_in_worktree
  from_state: WORKTREE_REVIEW
  to_state: IN_WORKTREE
  purpose: Advance lifecycle state from WORKTREE_REVIEW to IN_WORKTREE upon satisfying phase requirements and verifications.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to IN_WORKTREE."
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  - Structural DAG transition from WORKTREE_REVIEW to IN_WORKTREE is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition WORKTREE_REVIEW -> IN_WORKTREE denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from WORKTREE_REVIEW to IN_WORKTREE is deterministically governed by automated checks and artifacts.
- transition_id: worktree_review_to_rolled_back
  from_state: WORKTREE_REVIEW
  to_state: ROLLED_BACK
  purpose: Roll back worktree changes from WORKTREE_REVIEW to clean baseline.
  next_steps_hint: "First satisfy rolled_back_guard; use: record the rollback verification receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ROLLED_BACK."
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  - 'Deterministic check satisfied: rolled_back_guard'
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks:
  - rolled_back_guard
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition WORKTREE_REVIEW -> ROLLED_BACK denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from WORKTREE_REVIEW to ROLLED_BACK is deterministically governed by automated checks and artifacts.
- transition_id: worktree_review_to_escalated
  from_state: WORKTREE_REVIEW
  to_state: ESCALATED
  purpose: Escalate task from WORKTREE_REVIEW due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  - Structural DAG transition from WORKTREE_REVIEW to ESCALATED is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition WORKTREE_REVIEW -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from WORKTREE_REVIEW to ESCALATED is deterministically governed by automated checks and artifacts.
# Return-to-review edges also use the binary submit/revise question. Review
# method selection belongs only to the edge that enters the review state, and
# explicit skips use the deterministic exit edge with a recorded skip receipt.
- transition_id: multi_agent_code_review_to_worktree_review
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: WORKTREE_REVIEW
  purpose: Return a completed or re-submitted review package to WORKTREE_REVIEW for artifact and scope confirmation.
  next_steps_hint: "Use this edge only after the review outcome is recorded and the package is ready for artifact review. For a requested change or failed review requiring edits, use MULTI_AGENT_CODE_REVIEW -> IN_WORKTREE instead; do not edit while in the review state. After any bounded fix, rerun focused verification and the session-wide change inventory, then submit through WORKTREE_REVIEW and re-enter MULTI_AGENT_CODE_REVIEW. Answer this edge's human question with --interactive so SQLite records actor=human, complete its checklist, and run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to WORKTREE_REVIEW."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - Structural DAG transition from MULTI_AGENT_CODE_REVIEW to WORKTREE_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_multi_agent_code_review_to_worktree_review
    question: Submit artifacts for review in WORKTREE_REVIEW?
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> WORKTREE_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into WORKTREE_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: multi_agent_code_review_to_verify_exit
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: VERIFY_EXIT
  requires_cryptographic_proof: true
  purpose: Advance lifecycle state from MULTI_AGENT_CODE_REVIEW to VERIFY_EXIT upon satisfying phase requirements and verifications.
  next_steps_hint: "Human-signed gate. Run coordinate-transition --task-id <task-id> --to VERIFY_EXIT. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, commit SHA, tracked-diff hash, untracked-files hash, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs agent_control.py show-challenge --request-id N, signs, and runs approve-transition --request-id N. If the code changes after the request the approval is refused and a new request is needed. No prompt, typed word, --answers, --human-confirmed or flag can authorize this edge."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - Structural DAG transition from MULTI_AGENT_CODE_REVIEW to VERIFY_EXIT is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks:
  - critic_review_pass
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - exit_verification
  capabilities_prohibited: []
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> VERIFY_EXIT denied: preconditions or required decisions not satisfied.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: multi_agent_code_review_to_in_worktree
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: IN_WORKTREE
  purpose: Return a review package requiring bounded changes to the implementation worktree.
  next_steps_hint: "Use this existing rework edge only after the current implementation-review reports have been synthesized, the outcome is REQUEST_CHANGES, REVISE, or REVIEW_FAILURE with bounded recovery, the revision brief is recorded, and the human approves this question. Do not edit in MULTI_AGENT_CODE_REVIEW. After entry, make only the approved bounded fixes in the registered worktree, rerun focused verification and the session-wide change inventory, then submit via IN_WORKTREE -> WORKTREE_REVIEW -> MULTI_AGENT_CODE_REVIEW for another review round. Do not create a new transition type for this loop. Run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to IN_WORKTREE."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - Structural DAG transition from MULTI_AGENT_CODE_REVIEW to IN_WORKTREE is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions:
  - question_id: confirm_rework_multi_agent_code_review_to_in_worktree
    question: "The implementation review identified bounded changes. Do you wish to transition back to IN_WORKTREE so the authorized implementer can apply the revision brief?"
    options:
    - Yes — transition to IN_WORKTREE and begin bounded fixes [Recommended]
    - No — remain in MULTI_AGENT_CODE_REVIEW
    accepted_answers:
    - Yes — transition to IN_WORKTREE and begin bounded fixes [Recommended]
    default: Yes — transition to IN_WORKTREE and begin bounded fixes [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> IN_WORKTREE denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Returning to IN_WORKTREE after implementation review requires the recorded review outcome, bounded revision brief, and explicit human authorization.
- transition_id: multi_agent_code_review_to_rolled_back
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: ROLLED_BACK
  purpose: Roll back worktree changes from MULTI_AGENT_CODE_REVIEW to clean baseline.
  next_steps_hint: "First satisfy rolled_back_guard; use: record the rollback verification receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ROLLED_BACK."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - 'Deterministic check satisfied: rolled_back_guard'
  required_artifacts: []
  deterministic_checks:
  - rolled_back_guard
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> ROLLED_BACK denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from MULTI_AGENT_CODE_REVIEW to ROLLED_BACK is deterministically governed by automated checks
      and artifacts.
- transition_id: multi_agent_code_review_to_escalated
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: ESCALATED
  purpose: Escalate task from MULTI_AGENT_CODE_REVIEW due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - Structural DAG transition from MULTI_AGENT_CODE_REVIEW to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from MULTI_AGENT_CODE_REVIEW to ESCALATED is deterministically governed by automated checks and
      artifacts.
- transition_id: verify_exit_to_retrospective
  from_state: VERIFY_EXIT
  to_state: RETROSPECTIVE
  purpose: Verify clean leak checks and enter the mandatory pipeline-close retrospective gate.
  guidance:
    success: "TRIVIAL may satisfy the test requirement with focused_test_suite plus the existing leak and completeness checks; STANDARD requires full_test_suite."
    denial: "Use the route-appropriate verification contract. A missing focused receipt for TRIVIAL or full-suite receipt for STANDARD blocks closeout."
  next_steps_hint: "STOP: do NOT run `pytest` directly by itself, and do NOT call the individual verifier wrappers one at a time -- a bare pytest run records no receipt, and calling verifiers separately is exactly the slow, error-prone path this hint used to describe (verifier_id=pytest_full_suite, verifier_id=pytest_unit_tests, verifier_id=leak_check, each a separate call). Use the single bundled wrapper instead, which runs all 3 verifiers plus the required asymmetric-persistence log entry in ONE call and fails fast on the first real failure: (1) Confirm docs/plans/work-tasks/<task-id>/<task-id>-implementation-plan.md has a fenced JSON Implementation Task Ledger with every item status=COMPLETE, evidence, and existing artifact paths -- this satisfies implementation_completeness (the bundle does not check this one). (2) Run: python3 @CONTROL_SCRIPTS_DIR@/control_plane/wrappers/run_verify_exit_bundle.py --task-id <task-id> --destination references/map-debt.md --details '<what was logged and why>' -- this alone satisfies full_test_suite, test_suite, leak_check, and done_guard's asymmetric-persistence requirement (default destination is references/map-debt.md; use wiki/decisions/<task-id>.md instead if that's where you logged it). (3) Only after that reports status=COMPLETED: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE --human-confirmed 'HUMAN-CONFIRMED: <what the human actually said>'."
  checklist:
  - Current task state is persisted as VERIFY_EXIT
  - 'Deterministic checks satisfied: full_test_suite, test_suite, leak_check, and asymmetric persistence'
  required_artifacts: []
  deterministic_checks:
  - done_guard
  - implementation_completeness
  - full_test_suite_or_trivial_focused
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited: []
  denial_message: 'Transition VERIFY_EXIT -> RETROSPECTIVE denied: verification or implementation completeness requirements are not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from VERIFY_EXIT to RETROSPECTIVE is governed by the existing exit verification receipts and persistence checks.
- transition_id: retrospective_to_done
  from_state: RETROSPECTIVE
  to_state: DONE
  requires_cryptographic_proof: true
  purpose: Complete the task after a completed retrospective or an explicitly reasoned skip.
  next_steps_hint: "First persist the completed retrospective through the supported record_retrospective wrapper with the required entry fields and resolved follow-ups; do this before requesting DONE. For STANDARD work, run the repository-wide pytest -q suite and record full_test_suite. For TRIVIAL work, record focused_test_suite instead unless the user requests or explicitly approves the full suite. Satisfy retrospective_done_guard (if it denies the request, the denial names the recovery). Then request closure: Human-signed closure. Run coordinate-transition --task-id <task-id> --to DONE. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, worktree commit SHA and diff hashes when a worktree is registered, and for normal completion the recorded retrospective decision and digest, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs show-challenge, signs, and runs approve-transition. There is no force-close word, flag or prompt: closure of any task from any state takes the same signature."
  checklist:
  - Current task state is persisted as RETROSPECTIVE
  - Retrospective survey is complete or explicitly skipped with a reason
  - 'Deterministic check satisfied: full_test_suite'
  required_artifacts: []
  deterministic_checks:
  - retrospective_done_guard
  - full_test_suite_or_trivial_focused
  guidance:
    success: "TRIVIAL closes with focused verification and the retrospective; STANDARD closes only after full-suite verification. Neither route may skip the user review or retrospective evidence."
    denial: "Remain in RETROSPECTIVE until the route-appropriate verification receipt and retrospective decision are recorded."
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition RETROSPECTIVE -> DONE denied: retrospective is incomplete or has unresolved issue follow-ups.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: retrospective_to_escalated
  from_state: RETROSPECTIVE
  to_state: ESCALATED
  purpose: Escalate a retrospective that cannot be completed or whose follow-up issue creation is blocked.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as RETROSPECTIVE
  - Human or agent has documented the blocking reason
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition RETROSPECTIVE -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Escalation preserves the incomplete retrospective for human intervention.
- transition_id: verify_exit_to_in_worktree
  from_state: VERIFY_EXIT
  to_state: IN_WORKTREE
  purpose: Advance lifecycle state from VERIFY_EXIT to IN_WORKTREE upon satisfying phase requirements and verifications.
  next_steps_hint: "Recovery edge: a failed full_test_suite (or other exit verification) receipt routes back here to fix the failure -- do not transition to RETROSPECTIVE or DONE with a failing receipt. Use the existing registered worktree for this task; do not create another worktree. Once fixed, submit through WORKTREE_REVIEW again (do not re-enter VERIFY_EXIT directly) before retrying exit verification. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to IN_WORKTREE."
  failure_recovery: "Do not repeat the failed closeout path -- fix the specific failing verifier or ledger item first, then re-enter WORKTREE_REVIEW rather than retrying VERIFY_EXIT with the same unresolved failure. Do not reset to INTAKE for a verification failure -- that discards all prior progress and is reserved for genuinely desynced control-plane records, not fixable implementation gaps."
  checklist:
  - Current task state is persisted as VERIFY_EXIT
  - Structural DAG transition from VERIFY_EXIT to IN_WORKTREE is legal
  required_artifacts:
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition VERIFY_EXIT -> IN_WORKTREE denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from VERIFY_EXIT to IN_WORKTREE is deterministically governed by automated checks and artifacts.
- transition_id: verify_exit_to_worktree_review
  from_state: VERIFY_EXIT
  to_state: WORKTREE_REVIEW
  purpose: Advance lifecycle state from VERIFY_EXIT to WORKTREE_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to WORKTREE_REVIEW."
  checklist:
  - Current task state is persisted as VERIFY_EXIT
  - Structural DAG transition from VERIFY_EXIT to WORKTREE_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  - .worktrees/<task-id>
  deterministic_checks: []
  human_questions:
  - question_id: confirm_review_verify_exit_to_worktree_review
    question: Submit artifacts for review in WORKTREE_REVIEW?
    options:
    - Proceed with review [Recommended]
    - Continue revising prior stage
    accepted_answers:
    - Proceed with review [Recommended]
    default: Proceed with review [Recommended]
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - push branch to origin without review pass
  - merge into origin/main directly
  denial_message: 'Transition VERIFY_EXIT -> WORKTREE_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_review
    explanation: Entry into WORKTREE_REVIEW requires human confirmation of review scope and artifacts.
- transition_id: verify_exit_to_rolled_back
  from_state: VERIFY_EXIT
  to_state: ROLLED_BACK
  purpose: Roll back worktree changes from VERIFY_EXIT to clean baseline.
  next_steps_hint: "First satisfy rolled_back_guard; use: record the rollback verification receipt. Then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ROLLED_BACK."
  checklist:
  - Current task state is persisted as VERIFY_EXIT
  - 'Deterministic check satisfied: rolled_back_guard'
  required_artifacts: []
  deterministic_checks:
  - rolled_back_guard
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition VERIFY_EXIT -> ROLLED_BACK denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from VERIFY_EXIT to ROLLED_BACK is deterministically governed by automated checks and artifacts.
- transition_id: verify_exit_to_escalated
  from_state: VERIFY_EXIT
  to_state: ESCALATED
  purpose: Escalate task from VERIFY_EXIT due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as VERIFY_EXIT
  - Structural DAG transition from VERIFY_EXIT to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition VERIFY_EXIT -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: deterministic
    explanation: Transition from VERIFY_EXIT to ESCALATED is deterministically governed by automated checks and artifacts.
- transition_id: rolled_back_to_escalated
  from_state: ROLLED_BACK
  to_state: ESCALATED
  purpose: Escalate task from ROLLED_BACK due to blocking failure, unresolvable ambiguity, or user intervention.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to ESCALATED."
  checklist:
  - Current task state is persisted as ROLLED_BACK
  - Structural DAG transition from ROLLED_BACK to ESCALATED is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions:
  - question_id: recovery_approval_rolled_back_to_escalated
    question: Authorize recovery transition from ROLLED_BACK to ESCALATED?
    options:
    - Yes, authorize recovery [Recommended]
    - No, remain in current state
    default: Yes, authorize recovery [Recommended]
  approval:
    required: true
    approver_role: human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Transition ROLLED_BACK -> ESCALATED denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_decision
    explanation: Advancing to ESCALATED requires explicit human review and authorization gate decision.
- transition_id: rolled_back_to_plan_review
  from_state: ROLLED_BACK
  to_state: PLAN_REVIEW
  purpose: Advance lifecycle state from ROLLED_BACK to PLAN_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW."
  checklist:
  - Current task state is persisted as ROLLED_BACK
  - Structural DAG transition from ROLLED_BACK to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: recovery_approval_rolled_back_to_plan_review
    question: Authorize recovery transition from ROLLED_BACK to PLAN_REVIEW?
    options:
    - Yes, authorize recovery [Recommended]
    - No, remain in current state
    default: Yes, authorize recovery [Recommended]
  approval:
    required: true
    approver_role: human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition ROLLED_BACK -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_decision
    explanation: Advancing to PLAN_REVIEW requires explicit human review and authorization gate decision.
- transition_id: escalated_to_intake
  from_state: ESCALATED
  to_state: INTAKE
  purpose: Advance lifecycle state from ESCALATED to INTAKE upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to INTAKE."
  checklist:
  - Current task state is persisted as ESCALATED
  - Structural DAG transition from ESCALATED to INTAKE is legal
  required_artifacts: []
  deterministic_checks: []
  human_questions:
  - question_id: recovery_approval_escalated_to_intake
    question: Authorize recovery transition from ESCALATED to INTAKE?
    options:
    - Yes, authorize recovery [Recommended]
    - No, remain in current state
    default: Yes, authorize recovery [Recommended]
  approval:
    required: true
    approver_role: human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition ESCALATED -> INTAKE denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_decision
    explanation: Advancing to INTAKE requires explicit human review and authorization gate decision.
- transition_id: escalated_to_plan_review
  from_state: ESCALATED
  to_state: PLAN_REVIEW
  purpose: Advance lifecycle state from ESCALATED to PLAN_REVIEW upon satisfying phase requirements and verifications.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to PLAN_REVIEW."
  checklist:
  - Current task state is persisted as ESCALATED
  - Structural DAG transition from ESCALATED to PLAN_REVIEW is legal
  required_artifacts:
  - docs/plans/<task-id>-spec.md
  - docs/plans/<task-id>-implementation-plan.md
  deterministic_checks: []
  human_questions:
  - question_id: recovery_approval_escalated_to_plan_review
    question: Authorize recovery transition from ESCALATED to PLAN_REVIEW?
    options:
    - Yes, authorize recovery [Recommended]
    - No, remain in current state
    default: Yes, authorize recovery [Recommended]
  approval:
    required: true
    approver_role: human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition ESCALATED -> PLAN_REVIEW denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_decision
    explanation: Advancing to PLAN_REVIEW requires explicit human review and authorization gate decision.
- transition_id: human_force_done
  from_state: "*"
  to_state: DONE
  requires_cryptographic_proof: true
  purpose: Allow a human-in-the-loop to terminate any non-DONE task as DONE without claiming implementation occurred.
  next_steps_hint: "Human-signed closure. Run coordinate-transition --task-id <task-id> --to DONE. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, worktree commit SHA and diff hashes when a worktree is registered, and for normal completion the recorded retrospective decision and digest, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs show-challenge, signs, and runs approve-transition. There is no force-close word, flag or prompt: closure of any task from any state takes the same signature."
  checklist:
  - Current task state is not DONE
  - Human confirmation is provided interactively
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - claim implementation completion
  - claim verification completion
  - create implementation worktree
  - push branch to origin
  denial_message: 'Closure denied: a human-signed transition_request (ssh-keygen -Y sign, verified against allowed_signers) is required; no typed word or flag authorizes it.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: reset_to_intake
  from_state: "*"
  to_state: INTAKE
  purpose: Recover a task whose control-plane record has drifted or desynced from reality (e.g. a raw write bypassing the normal transition path) by resetting it to INTAKE for a full re-run through every gate.
  next_steps_hint: "Answer this edge's YAML questions with --interactive or --answers '<json>'. Complete this edge's checklist and required gates, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to INTAKE."
  checklist:
  - Current task state is not INTAKE
  - Human has provided a genuine, interactive justification for the reset
  required_artifacts: []
  deterministic_checks: []
  human_questions:
  - question_id: reset_justification
    question: 'Justify this RESET to INTAKE (e.g. "control-plane record drifted from actual progress after a raw write bypassed the normal transition path; resetting to re-run the full pipeline").'
    options: []
    default: ''
  approval:
    required: true
    approver_role: human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited:
  - modify production code
  - create implementation worktree
  - push branch to origin
  denial_message: 'Transition to INTAKE (reset) denied: preconditions or required decisions not satisfied.'
  authority:
    type: human_decision
    explanation: A human must provide a genuine, interactive justification before a drifted task record can be reset to INTAKE.
- transition_id: force_close_to_done
  from_state: "*"
  to_state: DONE
  requires_cryptographic_proof: true
  purpose: Close a task from any active lifecycle state when a human explicitly authorizes force closure.
  next_steps_hint: "Human-signed closure. Run coordinate-transition --task-id <task-id> --to DONE. In an interactive terminal (--interactive) the CLI prints the exact challenge (task, transition, worktree commit SHA and diff hashes when a worktree is registered, and for normal completion the recorded retrospective decision and digest, nonce, expiry), runs ssh-keygen -Y sign so OpenSSH prompts for your private-key passphrase, verifies the signature against allowed_signers and consumes the request in the commit transaction. Without a terminal it stops with HUMAN_PROOF_REQUIRED and a request_id; the human then runs show-challenge, signs, and runs approve-transition. There is no force-close word, flag or prompt: closure of any task from any state takes the same signature."
  checklist:
  - Current task state is persisted and matches the requested source occupancy
  - A human-signed transition_request for this edge is verified and consumed
  required_artifacts: []
  deterministic_checks: []
  human_questions: []
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released: []
  capabilities_prohibited: []
  denial_message: 'Planning-only close denied: a human-signed transition_request (ssh-keygen -Y sign, verified against allowed_signers) is required; no typed word or flag authorizes it.'
  authority:
    type: cryptographic_proof
    explanation: Only a verified OpenSSH signature over a content-bound transition_request, consumed in the commit transaction, can commit this edge.
- transition_id: force_retrospective_from_intake
  from_state: INTAKE
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from INTAKE, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as INTAKE
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from INTAKE. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition INTAKE -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_draft_plan
  from_state: DRAFT_PLAN
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from DRAFT_PLAN, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as DRAFT_PLAN
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from DRAFT_PLAN. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition DRAFT_PLAN -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_multi_agent_review
  from_state: MULTI_AGENT_REVIEW
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from MULTI_AGENT_REVIEW, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as MULTI_AGENT_REVIEW
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from MULTI_AGENT_REVIEW. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition MULTI_AGENT_REVIEW -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_plan_review
  from_state: PLAN_REVIEW
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from PLAN_REVIEW, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as PLAN_REVIEW
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from PLAN_REVIEW. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition PLAN_REVIEW -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_awaiting_approval
  from_state: AWAITING_APPROVAL
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from AWAITING_APPROVAL, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as AWAITING_APPROVAL
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from AWAITING_APPROVAL. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition AWAITING_APPROVAL -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_rolled_back
  from_state: ROLLED_BACK
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from ROLLED_BACK, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as ROLLED_BACK
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from ROLLED_BACK. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition ROLLED_BACK -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_escalated
  from_state: ESCALATED
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from ESCALATED, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as ESCALATED
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from ESCALATED. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition ESCALATED -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_done
  from_state: DONE
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from DONE, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as DONE
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from DONE. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition DONE -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_in_worktree
  from_state: IN_WORKTREE
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from IN_WORKTREE, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as IN_WORKTREE
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from IN_WORKTREE. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition IN_WORKTREE -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_worktree_review
  from_state: WORKTREE_REVIEW
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from WORKTREE_REVIEW, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as WORKTREE_REVIEW
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from WORKTREE_REVIEW. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition WORKTREE_REVIEW -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.

- transition_id: force_retrospective_from_multi_agent_code_review
  from_state: MULTI_AGENT_CODE_REVIEW
  to_state: RETROSPECTIVE
  purpose: Human-authorized emergency close -- force any in-progress task directly to the mandatory retrospective gate from MULTI_AGENT_CODE_REVIEW, bypassing the normal downstream path, when the session is being ended before natural completion.
  next_steps_hint: "Answer force_retrospective_authorization interactively with the literal value FORCE_RETROSPECTIVE, then run: @AGENT_CONTROL_CMD@ coordinate-transition --task-id <task-id> --to RETROSPECTIVE."
  checklist:
  - Current task state is persisted as MULTI_AGENT_CODE_REVIEW
  - Human has explicitly authorized an emergency close via FORCE_RETROSPECTIVE
  required_artifacts: []
  deterministic_checks: []
  stage_question_ids: []
  human_questions:
  - question_id: force_retrospective_reason_category
    question: Why is this task moving directly to RETROSPECTIVE instead of its normal path?
    options:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
    default: ''
    accepted_answers:
    - Task is effectively complete/trivial -- this is a planned early close, not a failure
    - Ending early due to agent or pipeline failure -- needs follow-up documentation
  - question_id: force_retrospective_authorization
    question: This ends the task early via emergency close, bypassing the normal pipeline from MULTI_AGENT_CODE_REVIEW. Type FORCE_RETROSPECTIVE to confirm.
    options:
    - FORCE_RETROSPECTIVE
    default: ''
    accepted_answers:
    - FORCE_RETROSPECTIVE
  approval:
    required: false
    approver_role: agent_or_human
  skip:
    allowed: false
    requires_justification: false
  capabilities_released:
  - retrospective_capture
  capabilities_prohibited:
  - push branch to origin
  denial_message: 'Transition MULTI_AGENT_CODE_REVIEW -> RETROSPECTIVE (force) denied: explicit FORCE_RETROSPECTIVE authorization not given.'
  authority:
    type: human_decision
    explanation: A human must explicitly type FORCE_RETROSPECTIVE to end a task early from any state, bypassing its normal downstream gates.
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