loopx 0.4.8__py3-none-any.whl

loopx/cli_commands/todo_argument_validation.py

@@ -0,0 +1,572 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable
+
+from ..control_plane.todos.contract import TODO_CONTINUATION_POLICY_VALUES
+
+TODO_OPTION_FIELDS = (
+    ("--role", "role"),
+    ("--text", "text"),
+    ("--follow-up", "followups"),
+    ("--todo-id", "todo_id"),
+    ("--turn-instance-id", "turn_instance_id"),
+    ("--replan-obligation-id", "replan_obligation_id"),
+    ("--status", "status"),
+    ("--note", "note"),
+    ("--evidence", "evidence"),
+    ("--reason", "reason"),
+    ("--authority-reason", "authority_reason"),
+    ("--task-class", "task_class"),
+    ("--action-kind", "action_kind"),
+    ("--task-domain", "task_domain"),
+    ("--capability-binding-ref", "capability_binding_ref"),
+    ("--task-repository", "task_repository"),
+    ("--continuation-policy", "continuation_policy"),
+    ("--required-write-scope", "required_write_scopes"),
+    ("--required-capability", "required_capabilities"),
+    ("--target-capability", "target_capabilities"),
+    ("--capability-gap-status", "capability_gap_status"),
+    ("--explore-result-node-ref", "explore_result_node_refs"),
+    ("--clear-explore-result-node-refs", "clear_explore_result_node_refs"),
+    ("--decision-scope", "decision_scope"),
+    ("--required-decision-scope", "required_decision_scopes"),
+    ("--decision-outcome", "decision_outcome"),
+    ("--claimed-by", "claimed_by"),
+    ("--task-lease-idempotency-key", "task_lease_idempotency_key"),
+    ("--task-lease-expected-version", "task_lease_expected_version"),
+    ("--bound-agent", "bound_agent"),
+    ("--goal-bound", "goal_bound"),
+    ("--blocks-agent", "blocks_agent"),
+    ("--clear-blocks-agent", "clear_blocks_agent"),
+    ("--excluded-agent", "excluded_agents"),
+    ("--clear-excluded-agents", "clear_excluded_agents"),
+    ("--global-gate", "global_gate"),
+    ("--clear-global-gate", "clear_global_gate"),
+    ("--unblocks-todo-id", "unblocks_todo_id"),
+    ("--successor-todo-id", "successor_todo_ids"),
+    ("--resume-when", "resume_when"),
+    ("--validation-command", "validation_command"),
+    ("--validation-command-json", "validation_command_json"),
+    ("--validation-label", "validation_label"),
+    ("--validation-timeout-seconds", "validation_timeout_seconds"),
+    ("--clear-resume-when", "clear_resume_when"),
+    ("--target-key", "monitor_target_key"),
+    ("--cadence", "cadence"),
+    ("--next-due-at", "next_due_at"),
+    ("--expires-at", "expires_at"),
+    ("--watch-only", "watch_only"),
+    ("--clear-claim", "clear_claim"),
+    ("--no-follow-up", "no_follow_up"),
+    ("--next-agent-todo", "next_agent_todo"),
+    ("--next-user-todo", "next_user_todo"),
+    ("--next-user-task-class", "next_user_task_class"),
+    ("--next-claimed-by", "next_claimed_by"),
+    ("--next-task-class", "next_task_class"),
+    ("--next-action-kind", "next_action_kind"),
+    ("--next-task-repository", "next_task_repository"),
+    ("--next-required-capability", "next_required_capabilities"),
+    ("--next-continuation-policy", "next_continuation_policy"),
+    ("--next-excluded-agent", "next_excluded_agents"),
+    ("--self-merged", "self_merged"),
+    ("--agent-id", "agent_id"),
+    ("--from", "suggestion_sources"),
+    ("--limit", "suggestion_limit"),
+    ("--trigger", "suggestion_trigger"),
+    ("--state-file", "state_file"),
+    ("--execute", "execute"),
+)
+
+_TODO_UPDATE_MUTABLE_FIELDS = (
+    "text", "followups", "status", "note", "evidence", "reason", "task_class",
+    "action_kind", "task_domain", "task_repository", "continuation_policy", "required_write_scopes",
+    "required_capabilities", "target_capabilities", "capability_gap_status",
+    "explore_result_node_refs", "clear_explore_result_node_refs", "decision_scope",
+    "required_decision_scopes", "claimed_by", "bound_agent", "goal_bound",
+    "blocks_agent", "clear_blocks_agent", "excluded_agents", "clear_excluded_agents",
+    "global_gate", "clear_global_gate", "unblocks_todo_id", "successor_todo_ids",
+    "resume_when", "clear_resume_when", "no_follow_up", "monitor_target_key",
+    "cadence", "next_due_at", "expires_at", "watch_only", "clear_claim",
+)
+
+_TODO_UPDATE_UNSUPPORTED_FIELDS = (
+    (
+        "decision_outcome",
+        "todo update does not accept --decision-outcome; use todo complete",
+    ),
+    (
+        "followups",
+        "todo update does not support --follow-up; use `todo capture-followups`",
+    ),
+    ("next_claimed_by", "todo update does not support --next-claimed-by"),
+    (
+        "next_task_repository",
+        "todo update does not support --next-task-repository",
+    ),
+    (
+        "next_required_capabilities",
+        "todo update does not support --next-required-capability",
+    ),
+    (
+        "next_continuation_policy",
+        "todo update does not support --next-continuation-policy",
+    ),
+    ("next_excluded_agents", "todo update does not support --next-excluded-agent"),
+    ("self_merged", "todo update does not support --self-merged"),
+)
+
+_TODO_ADD_INITIAL_RULES = (
+    ("decision_outcome", True, "does not accept --decision-outcome; record it on completion"),
+    ("followups", True, "does not support --follow-up; use `todo capture-followups`"),
+    ("role", False, "requires --role"),
+    ("text", False, "requires --text"),
+    ("clear_claim", True, "accepts --claimed-by but not --clear-claim"),
+    (
+        "clear_explore_result_node_refs",
+        True,
+        "accepts --explore-result-node-ref but not --clear-explore-result-node-refs",
+    ),
+)
+_TODO_ADD_UNSUPPORTED_FIELDS = (
+    "next_claimed_by", "next_task_repository", "next_required_capabilities",
+    "next_continuation_policy", "next_excluded_agents", "clear_excluded_agents",
+    "clear_blocks_agent", "self_merged", "no_follow_up",
+)
+_TODO_OPTION_FLAGS = {field: flag for flag, field in TODO_OPTION_FIELDS}
+
+
+def register_todo_linkage_arguments(
+    todo_parser: argparse.ArgumentParser,
+) -> None:
+    todo_parser.add_argument(
+        "--unblocks-todo-id",
+        help=(
+            "For todo add/update, link this todo to the blocked todo it unblocks, "
+            "for example todo_ab12cd34ef56. Completing an exactly linked user_gate "
+            "also consumes the target required decision scopes covered by that gate."
+        ),
+    )
+    todo_parser.add_argument(
+        "--successor-todo-id",
+        dest="successor_todo_ids",
+        action="append",
+        help=(
+            "For todo update/complete, link an existing successor todo to the "
+            "current todo. Repeat for multiple successors."
+        ),
+    )
+    todo_parser.add_argument(
+        "--resume-when",
+        help=(
+            "For deferred todo add/update, declare a machine-readable resume condition "
+            "such as todo_done:todo_ab12cd34ef56, pr_merged:#532, or "
+            "capacity_available:short_pool. Capacity keys are resolved from quota "
+            "--available-capability declarations."
+        ),
+    )
+    todo_parser.add_argument(
+        "--clear-resume-when",
+        action="store_true",
+        help=(
+            "For todo update, remove the existing resume condition after its "
+            "successor replan has made the todo runnable."
+        ),
+    )
+
+
+def register_todo_successor_creation_arguments(
+    todo_parser: argparse.ArgumentParser,
+) -> None:
+    todo_parser.add_argument(
+        "--next-agent-todo",
+        help="For complete/supersede, atomically add or update the next agent todo.",
+    )
+    todo_parser.add_argument(
+        "--next-user-todo",
+        help="For complete/supersede, atomically add or update the next user todo.",
+    )
+    todo_parser.add_argument(
+        "--next-user-task-class",
+        choices=["user_gate", "user_action"],
+        help=(
+            "Required with --next-user-todo: user_gate for a blocking owner "
+            "decision or user_action for a visible reminder that must not block "
+            "the bound agent lane."
+        ),
+    )
+    todo_parser.add_argument(
+        "--next-claimed-by",
+        help=(
+            "For complete/supersede with --next-agent-todo, soft-claim the successor "
+            "todo for a registered agent. Independent handoffs remain unclaimed unless "
+            "explicitly assigned, while same-agent non-delivery continuations keep the "
+            "current owner. Use --self-merged with --evidence for an eligible same-agent "
+            "delivery."
+        ),
+    )
+    todo_parser.add_argument(
+        "--self-merged",
+        action="store_true",
+        help=(
+            "For todo complete, record that a small validated change was self-merged; "
+            "requires --evidence."
+        ),
+    )
+    todo_parser.add_argument(
+        "--next-task-class",
+        choices=["advancement_task", "continuous_monitor", "blocker"],
+        help="Task class for --next-agent-todo. Defaults to advancement_task.",
+    )
+    todo_parser.add_argument(
+        "--next-action-kind",
+        help="Action kind for --next-agent-todo.",
+    )
+    todo_parser.add_argument(
+        "--next-task-repository",
+        help=(
+            "Credential-free Git repository identity for --next-agent-todo, such as "
+            "git:github.com/owner/repo."
+        ),
+    )
+    todo_parser.add_argument(
+        "--next-required-capability",
+        dest="next_required_capabilities",
+        action="append",
+        help=(
+            "Execution capability required by --next-agent-todo. Repeat for multiple "
+            "capabilities."
+        ),
+    )
+    todo_parser.add_argument(
+        "--next-continuation-policy",
+        choices=sorted(TODO_CONTINUATION_POLICY_VALUES),
+        help="Continuation policy for --next-agent-todo.",
+    )
+    todo_parser.add_argument(
+        "--next-excluded-agent",
+        dest="next_excluded_agents",
+        action="append",
+        help=(
+            "For complete/supersede with --next-agent-todo, exclude one registered "
+            "peer from claiming or executing the successor. Repeat for multiple peers."
+        ),
+    )
+
+
+def unsupported_todo_options(
+    args: argparse.Namespace,
+    *,
+    allowed_fields: Iterable[str],
+) -> list[str]:
+    allowed = set(allowed_fields)
+    return [
+        flag
+        for flag, field in TODO_OPTION_FIELDS
+        if field not in allowed and getattr(args, field, None)
+    ]
+
+
+def _validate_todo_option_subset(args: argparse.Namespace, allowed_fields: Iterable[str], error_prefix: str) -> None:
+    unsupported = unsupported_todo_options(args, allowed_fields=allowed_fields)
+    if unsupported:
+        raise ValueError(error_prefix + ", ".join(unsupported))
+
+
+def validate_todo_list_options(args: argparse.Namespace) -> None:
+    _validate_todo_option_subset(
+        args,
+        {"role", "todo_id", "status", "agent_id", "state_file"},
+        "todo list only accepts --goal-id, optional --role, --status, --todo-id, "
+        "--agent-id, --project, --state-file, --dry-run, and --format; unsupported: ",
+    )
+
+
+def validate_todo_add_options(args: argparse.Namespace) -> None:
+    for field, reject_when_present, message in _TODO_ADD_INITIAL_RULES:
+        if bool(getattr(args, field)) is reject_when_present:
+            raise ValueError(f"todo add {message}")
+    for field in _TODO_ADD_UNSUPPORTED_FIELDS:
+        if getattr(args, field):
+            raise ValueError(f"todo add does not support {_TODO_OPTION_FLAGS[field]}")
+    if args.successor_todo_ids:
+        raise ValueError("todo add does not support --successor-todo-id; use todo update/complete to link existing successor work")
+
+
+def validate_todo_claim_options(args: argparse.Namespace) -> None:
+    if not args.todo_id:
+        raise ValueError("todo claim requires --todo-id")
+    if not args.claimed_by:
+        raise ValueError("todo claim requires --claimed-by")
+    if args.clear_claim:
+        raise ValueError(
+            "todo claim requires --claimed-by and does not support --clear-claim"
+        )
+    _validate_todo_option_subset(
+        args,
+        {"role", "todo_id", "claimed_by", "agent_id", "state_file"},
+        "todo claim only accepts --todo-id, --claimed-by, --agent-id, optional --role, "
+        "--project, --state-file, and --dry-run; unsupported: ",
+    )
+
+
+def validate_todo_update_options(args: argparse.Namespace) -> None:
+    if not args.todo_id:
+        raise ValueError("todo update requires --todo-id")
+    if args.claimed_by and args.clear_claim:
+        raise ValueError(
+            "todo update accepts either --claimed-by or --clear-claim, not both"
+        )
+    if args.explore_result_node_refs and args.clear_explore_result_node_refs:
+        raise ValueError(
+            "todo update accepts either --explore-result-node-ref or "
+            "--clear-explore-result-node-refs, not both"
+        )
+    if not any(getattr(args, field) for field in _TODO_UPDATE_MUTABLE_FIELDS):
+        raise ValueError("todo update requires at least one mutable todo field")
+    if args.no_follow_up and not (args.note or args.reason or args.evidence):
+        raise ValueError("--no-follow-up requires --note, --reason, or --evidence")
+    for field, message in _TODO_UPDATE_UNSUPPORTED_FIELDS:
+        if getattr(args, field):
+            raise ValueError(message)
+
+
+def validate_todo_complete_options(args: argparse.Namespace) -> None:
+    if not args.todo_id:
+        raise ValueError("todo complete requires --todo-id")
+    if args.explore_result_node_refs or args.clear_explore_result_node_refs:
+        raise ValueError("todo complete does not update --explore-result-node-ref; use todo update first")
+    if args.claimed_by and args.clear_claim:
+        raise ValueError("todo complete accepts either --claimed-by or --clear-claim, not both")
+    if args.task_lease_expected_version is not None and not args.task_lease_idempotency_key:
+        raise ValueError(
+            "--task-lease-expected-version requires --task-lease-idempotency-key"
+        )
+    if any(getattr(args, field) for field in ("task_repository", "bound_agent", "goal_bound", "blocks_agent", "clear_blocks_agent", "excluded_agents", "clear_excluded_agents", "global_gate", "clear_global_gate", "unblocks_todo_id", "resume_when")):
+        raise ValueError("todo complete does not update current todo routing metadata; use todo update first")
+    if any(getattr(args, field) for field in ("monitor_target_key", "cadence", "next_due_at", "expires_at")):
+        raise ValueError("todo complete does not update target or monitor schedule metadata; use todo update before completion")
+    if args.no_follow_up and (args.next_agent_todo or args.next_user_todo):
+        raise ValueError("--no-follow-up cannot be combined with successor todos")
+    if args.no_follow_up and args.successor_todo_ids:
+        raise ValueError("--no-follow-up cannot be combined with successor todos")
+    if args.successor_todo_ids and (args.next_agent_todo or args.next_user_todo):
+        raise ValueError("--successor-todo-id links existing work and cannot be combined with --next-agent-todo or --next-user-todo")
+    if args.no_follow_up and not (args.note or args.evidence):
+        raise ValueError("--no-follow-up requires --note or --evidence")
+    if args.followups:
+        raise ValueError("todo complete does not support --follow-up; use `todo capture-followups`")
+    if args.continuation_policy:
+        raise ValueError("todo complete does not update --continuation-policy; use todo update first")
+    validate_successor_routing_options(args)
+
+
+def validate_todo_supersede_options(args: argparse.Namespace) -> None:
+    if not args.todo_id:
+        raise ValueError("todo supersede requires --todo-id")
+    if args.explore_result_node_refs or args.clear_explore_result_node_refs:
+        raise ValueError("todo supersede does not update --explore-result-node-ref; use todo update first")
+    if args.decision_outcome:
+        raise ValueError("todo supersede does not accept --decision-outcome; use todo complete")
+    if args.claimed_by:
+        raise ValueError("todo supersede does not support --claimed-by; use --next-claimed-by to assign the successor, or omit it to inherit the superseded todo owner when present")
+    if args.clear_claim:
+        raise ValueError("todo supersede does not support --clear-claim")
+    if args.self_merged:
+        raise ValueError("todo supersede does not support --self-merged")
+    if args.no_follow_up:
+        raise ValueError("todo supersede does not support --no-follow-up")
+    if args.followups:
+        raise ValueError("todo supersede does not support --follow-up; use `todo capture-followups`")
+    if args.continuation_policy:
+        raise ValueError("todo supersede does not update --continuation-policy; use todo update first")
+    validate_successor_routing_options(args)
+    if any(getattr(args, field) for field in ("blocks_agent", "clear_blocks_agent", "excluded_agents", "clear_excluded_agents", "global_gate", "clear_global_gate", "unblocks_todo_id", "resume_when")):
+        raise ValueError("todo supersede does not update current todo routing metadata; use todo update first")
+    if args.successor_todo_ids:
+        raise ValueError("todo supersede does not support --successor-todo-id; use --next-agent-todo or update the source todo before supersede")
+    if any(getattr(args, field) for field in ("monitor_target_key", "cadence", "next_due_at", "expires_at")):
+        raise ValueError("todo supersede does not update target or monitor schedule metadata; use todo update before supersede")
+
+
+def validate_todo_archive_completed_options(args: argparse.Namespace) -> None:
+    checks = (
+        (args.decision_outcome, "todo archive-completed does not support --decision-outcome"),
+        (args.claimed_by or args.clear_claim, "todo archive-completed does not support --claimed-by or --clear-claim"),
+        (any(getattr(args, field) for field in ("clear_blocks_agent", "excluded_agents", "clear_excluded_agents", "next_excluded_agents")), "todo archive-completed does not support executor exclusions"),
+        (args.next_claimed_by, "todo archive-completed does not support --next-claimed-by"),
+        (args.next_task_repository or args.next_required_capabilities, "todo archive-completed does not support successor routing metadata"),
+        (args.self_merged, "todo archive-completed does not support --self-merged"),
+        (args.no_follow_up, "todo archive-completed does not support --no-follow-up"),
+        (args.followups, "todo archive-completed does not support --follow-up; use `todo capture-followups`"),
+        (args.successor_todo_ids, "todo archive-completed does not support --successor-todo-id"),
+    )
+    for triggered, message in checks:
+        if triggered:
+            raise ValueError(message)
+
+
+def validate_todo_suggest_options(args: argparse.Namespace) -> None:
+    _validate_todo_option_subset(
+        args,
+        {"agent_id", "suggestion_sources", "suggestion_limit", "suggestion_trigger"},
+        "todo suggest only accepts --goal-id, optional --project, --agent-id, "
+        "--from, --limit, --trigger, --dry-run, and --format; unsupported: ",
+    )
+
+
+def validate_todo_capture_followups_options(args: argparse.Namespace) -> None:
+    checks = (
+        (args.role, "todo capture-followups always records agent todos; do not pass --role"),
+        (args.claimed_by, "todo capture-followups writes unclaimed todos; do not pass --claimed-by"),
+    )
+    for triggered, message in checks:
+        if triggered:
+            raise ValueError(message)
+    _validate_todo_option_subset(
+        args,
+        {
+            "text", "followups", "evidence", "task_class", "action_kind",
+            "continuation_policy", "required_write_scopes", "required_capabilities",
+            "target_capabilities", "required_decision_scopes", "state_file",
+        },
+        "todo capture-followups only accepts --goal-id, --follow-up, optional "
+        "--text shorthand, --evidence, routing metadata, --project, --state-file, "
+        "and --dry-run; unsupported: ",
+    )
+
+
+def validate_shared_todo_options(args: argparse.Namespace) -> None:
+    agent_id_allowed_for_user_authoring = (
+        args.todo_command == "add"
+        and args.role == "user"
+        and args.task_class in {"user_gate", "user_action"}
+    )
+    agent_id_allowed_for_read = args.todo_command == "list"
+    agent_id_allowed_for_lifecycle = args.todo_command in {
+        "claim",
+        "update",
+        "complete",
+        "supersede",
+    }
+    global_gate_allowed = args.todo_command in {"add", "update"}
+    clear_global_gate_allowed = args.todo_command == "update"
+    authority_reason_allowed = args.todo_command in {
+        "update",
+        "complete",
+        "supersede",
+    }
+    if getattr(args, "turn_instance_id", None) and args.todo_command != "complete":
+        raise ValueError(
+            "--turn-instance-id is supported only by todo complete settlement"
+        )
+    if (
+        getattr(args, "replan_obligation_id", None)
+        and args.todo_command != "add"
+    ):
+        raise ValueError(
+            "--replan-obligation-id is supported only by todo add"
+        )
+    if (
+        args.todo_command != "complete"
+        and (
+            args.task_lease_idempotency_key
+            or args.task_lease_expected_version is not None
+        )
+    ):
+        raise ValueError(
+            "--task-lease-idempotency-key and --task-lease-expected-version "
+            "are supported only by todo complete"
+        )
+    if args.capability_binding_ref and args.todo_command != "add":
+        raise ValueError(
+            "--capability-binding-ref is immutable and supported only by todo add"
+        )
+    if args.authority_reason and not authority_reason_allowed:
+        raise ValueError(
+            "--authority-reason is supported only by todo update/complete/supersede"
+        )
+    if (
+        args.todo_command not in {"suggest", "capture-followups"}
+        and args.agent_id
+        and not agent_id_allowed_for_user_authoring
+        and not agent_id_allowed_for_read
+        and not agent_id_allowed_for_lifecycle
+    ):
+        if args.todo_command == "add" and args.role == "agent":
+            raise ValueError(
+                "todo add does not support --agent-id for agent todos; omit "
+                "--agent-id and use --claimed-by <registered-agent> only when "
+                "assigning execution, or omit both options to leave the todo "
+                "unclaimed."
+            )
+        raise ValueError(
+            f"todo {args.todo_command} does not support --agent-id; --agent-id "
+            "scopes todo list/suggest, user-todo authoring, and lifecycle actor "
+            "attribution only."
+        )
+    if args.global_gate and not global_gate_allowed:
+        raise ValueError(
+            "--global-gate is supported only by todo add/update for user_gate items"
+        )
+    if args.clear_global_gate and not clear_global_gate_allowed:
+        raise ValueError(
+            "--clear-global-gate is supported only by todo update for user_gate items"
+        )
+    if args.clear_resume_when and args.todo_command != "update":
+        raise ValueError("--clear-resume-when is supported only by todo update")
+    if args.clear_resume_when and args.resume_when:
+        raise ValueError(
+            "todo update accepts either --resume-when or --clear-resume-when, not both"
+        )
+    if (
+        args.todo_command not in {"suggest", "capture-followups"}
+        and (
+            args.suggestion_sources
+            or args.suggestion_limit is not None
+            or args.suggestion_trigger
+        )
+    ):
+        raise ValueError(
+            "--from, --limit, and --trigger are supported only by todo suggest"
+        )
+
+
+def validate_capability_gap_options(args: argparse.Namespace) -> None:
+    if not args.capability_gap_status:
+        return
+    if args.todo_command not in {"add", "update", "complete"}:
+        raise ValueError(
+            "--capability-gap-status is supported only by todo add/update/complete"
+        )
+    if args.role != "agent":
+        raise ValueError("--capability-gap-status requires --role agent")
+    if not args.target_capabilities:
+        raise ValueError(
+            "--capability-gap-status requires at least one --target-capability"
+        )
+    if (
+        args.capability_gap_status in {"fixed", "real_callsite_verified"}
+        and not args.evidence
+    ):
+        raise ValueError(
+            "fixed and real_callsite_verified capability gaps require "
+            "public-safe --evidence"
+        )
+
+
+def validate_successor_routing_options(args: argparse.Namespace) -> None:
+    if args.next_user_task_class and not args.next_user_todo:
+        raise ValueError("--next-user-task-class requires --next-user-todo")
+    if args.next_user_todo and not args.next_user_task_class:
+        raise ValueError(
+            "--next-user-todo requires explicit --next-user-task-class "
+            "user_action|user_gate"
+        )
+    if args.next_continuation_policy and not args.next_agent_todo:
+        raise ValueError("--next-continuation-policy requires --next-agent-todo")
+    if args.next_task_repository and not args.next_agent_todo:
+        raise ValueError("--next-task-repository requires --next-agent-todo")
+    if args.next_required_capabilities and not args.next_agent_todo:
+        raise ValueError("--next-required-capability requires --next-agent-todo")
+    if args.next_excluded_agents and not args.next_agent_todo:
+        raise ValueError("--next-excluded-agent requires --next-agent-todo")

loopx/cli_commands/todo_event.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from pathlib import Path
+
+from ..control_plane.todos.contract import decision_scope_metadata_value
+
+
+RolloutEventAppender = Callable[..., dict[str, object]]
+
+TODO_EVENT_KINDS = {
+    "add": "todo_add",
+    "claim": "todo_claim",
+    "update": "todo_update",
+    "complete": "todo_complete",
+    "supersede": "todo_supersede",
+    "archive-completed": "todo_archive_completed",
+    "capture-followups": "todo_capture_followups",
+}
+
+def append_todo_rollout_event(
+    payload: dict[str, object],
+    *,
+    args: argparse.Namespace,
+    registry_path: Path,
+    runtime_root_arg: str | None,
+    append_cli_rollout_event: RolloutEventAppender,
+) -> None:
+    turn_instance_id = getattr(args, "turn_instance_id", None)
+    if (
+        not payload.get("ok")
+        or payload.get("dry_run")
+        or (payload.get("idempotent_replay") and not turn_instance_id)
+    ):
+        return
+    append_cli_rollout_event(
+        payload,
+        registry_path=registry_path,
+        runtime_root_arg=runtime_root_arg,
+        event_kind=TODO_EVENT_KINDS.get(args.todo_command, "todo_update"),
+        agent_id=args.agent_id or args.claimed_by,
+        todo_id=args.todo_id or str(payload.get("todo_id") or "").strip() or None,
+        run_id=turn_instance_id,
+        status=str(payload.get("status") or args.todo_command or "").strip(),
+        summary=(
+            f"todo {args.todo_command} recorded for "
+            f"{payload.get('todo_id') or args.todo_id or 'unstructured todo'}"
+        ),
+        details={
+            "command": "todo",
+            "todo_command": args.todo_command,
+            "role": payload.get("role") or args.role or "",
+            "task_class": (
+                payload.get("task_class")
+                or getattr(args, "task_class", None)
+                or ""
+            ),
+            "decision_scope": decision_scope_metadata_value(
+                payload.get("decision_scope")
+            ),
+            "decision_outcome": payload.get("decision_outcome"),
+            "changed": bool(payload.get("changed")),
+            "added": bool(payload.get("added")),
+            "already_exists": bool(payload.get("already_exists")),
+            "no_followup": bool(getattr(args, "no_follow_up", False)),
+            "mutation_authority": payload.get("mutation_authority"),
+            "replan_transition": payload.get("replan_transition"),
+            "settlement_effect_id": (
+                payload.get("settlement_identity", {}).get("effect_id")
+                if isinstance(payload.get("settlement_identity"), dict)
+                else None
+            ),
+        },
+        idempotency_fields=(
+            ["goal_id", "event_kind", "agent_id", "todo_id", "run_id"]
+            if turn_instance_id
+            else None
+        ),
+    )
+    capability_gap_status = str(
+        getattr(args, "capability_gap_status", None) or ""
+    ).strip()
+    if not capability_gap_status:
+        return
+    gap_payload: dict[str, object] = {
+        "ok": True,
+        "goal_id": payload.get("goal_id"),
+    }
+    append_cli_rollout_event(
+        gap_payload,
+        registry_path=registry_path,
+        runtime_root_arg=runtime_root_arg,
+        event_kind="capability_gap",
+        agent_id=args.agent_id or args.claimed_by,
+        todo_id=args.todo_id or str(payload.get("todo_id") or "").strip() or None,
+        status=capability_gap_status,
+        summary=(
+            f"capability gap {capability_gap_status} for "
+            f"{payload.get('todo_id') or args.todo_id}"
+        ),
+        details={
+            "command": "todo",
+            "todo_command": args.todo_command,
+            "target_capabilities": ",".join(args.target_capabilities or []),
+            "evidence": args.evidence or "not_required_for_found",
+        },
+    )
+    if gap_payload.get("rollout_event"):
+        payload["capability_gap_event"] = gap_payload["rollout_event"]
+    elif gap_payload.get("rollout_event_log_error"):
+        payload["capability_gap_event_error"] = gap_payload[
+            "rollout_event_log_error"
+        ]