agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/cli/parsers.py

@@ -0,0 +1,618 @@
+"""Argparse construction for the root CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+from agent_lifecycle.cli.adapter import add_adapter_parser
+from agent_lifecycle.cli.followup import add_followup_parser
+from agent_lifecycle.cli.metrics_parser import add_metrics_parser
+from agent_lifecycle.cli.policy import add_policy_parser
+from agent_lifecycle.cli.progress_hooks import add_progress_hook_args
+from agent_lifecycle.cli.worktree import add_worktree_parser
+from agent_lifecycle.contracts.review_mesh_schemas import REVIEW_MESH_MODE_IDS
+from agent_lifecycle.review_mesh.operator_templates import REVIEW_MESH_OPERATOR_TEMPLATE_IDS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agent-lifecycle")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("version", help="print package version as compact JSON")
+    _add_diagnose_parser(subparsers)
+    _add_diagnostics_parser(subparsers)
+    _add_schema_parser(subparsers)
+    _add_contract_parser(subparsers)
+    subparsers.add_parser("neutrality", help="run neutrality subcommands")
+    _add_evidence_parser(subparsers)
+    _add_import_parser(subparsers)
+    _add_quality_parser(subparsers)
+    _add_review_mesh_parser(subparsers)
+    _add_report_parser(subparsers)
+    add_policy_parser(subparsers)
+    _add_workflow_parser(subparsers)
+    _add_audit_parser(subparsers)
+    _add_context_parser(subparsers)
+    _add_goal_parser(subparsers)
+    add_followup_parser(subparsers)
+    add_worktree_parser(subparsers)
+    _add_model_parser(subparsers)
+    add_metrics_parser(subparsers)
+    _add_runner_parser(subparsers)
+    _add_tier_parser(subparsers)
+    _add_specification_parser(subparsers)
+    _add_plan_parser(subparsers)
+    _add_task_parser(subparsers)
+    add_adapter_parser(subparsers)
+    subparsers.add_parser("conformance", help="conformance commands")
+    return parser
+
+
+def _add_diagnose_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    diagnose = subparsers.add_parser("diagnose", help="build a redacted readiness report")
+    diagnose.add_argument("--project-root", default=".")
+    diagnose.add_argument("--adapter", action="append", default=[])
+    diagnose.add_argument("--context-profile")
+    diagnose.add_argument("--model-profile")
+    diagnose.add_argument("--adapter-baseline")
+    diagnose.add_argument("--no-install-plans", action="store_true")
+    diagnose.add_argument("--include-host-probes", action="store_true")
+    diagnose.add_argument("--timeout-seconds", type=float, default=5.0)
+    diagnose.add_argument("--max-host-probes", type=int, default=1)
+
+
+def _add_diagnostics_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    diagnostics = subparsers.add_parser("diagnostics", help="optional diagnostics commands")
+    diagnostics_sub = diagnostics.add_subparsers(dest="diagnostics_command", required=True)
+    bundle = diagnostics_sub.add_parser("bundle")
+    bundle.add_argument("--project-root", default=".")
+    bundle.add_argument("--artifact", action="append", default=[])
+    bundle.add_argument("--max-artifacts", type=int, default=8)
+    bundle.add_argument("--max-input-bytes", type=int, default=20000)
+    bundle.add_argument("--out")
+
+
+def _add_schema_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    schema = subparsers.add_parser("schema", help="inspect bundled JSON schemas")
+    schema_sub = schema.add_subparsers(dest="schema_command", required=True)
+    schema_sub.add_parser("list")
+    show = schema_sub.add_parser("show")
+    show.add_argument("schema_id")
+
+
+def _add_contract_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    contract = subparsers.add_parser("contract", help="public contract commands")
+    contract_sub = contract.add_subparsers(dest="contract_command", required=True)
+    policy = contract_sub.add_parser("policy")
+    policy.add_argument("--out")
+    check = contract_sub.add_parser("check")
+    check.add_argument("--policy")
+
+
+def _add_evidence_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    evidence = subparsers.add_parser("evidence", help="optional evidence index commands")
+    evidence_sub = evidence.add_subparsers(dest="evidence_command", required=True)
+    index = evidence_sub.add_parser("index")
+    index.add_argument("--project-root", default=".")
+    index.add_argument("--artifact", action="append", default=[])
+    index.add_argument("--max-artifacts", type=int, default=64)
+    index.add_argument("--max-input-bytes", type=int, default=65536)
+    index.add_argument("--target-tokens", type=int, default=2048)
+    index.add_argument("--out")
+    search = evidence_sub.add_parser("search")
+    search.add_argument("--index", required=True)
+    search.add_argument("--query", default="")
+    search.add_argument("--max-results", type=int, default=8)
+    search.add_argument("--target-tokens", type=int, default=2048)
+    search.add_argument("--out")
+
+
+def _add_import_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    imports = subparsers.add_parser("import", help="optional import commands for untrusted planning inputs")
+    import_sub = imports.add_subparsers(dest="import_command", required=True)
+    profile_list = import_sub.add_parser("profile-list")
+    profile_list.add_argument("--out")
+    plan = import_sub.add_parser("plan")
+    plan.add_argument("--source", required=True)
+    plan.add_argument("--dialect", choices=["openspec", "spec-kit", "bmad", "spec-kitty"])
+    plan.add_argument("--package-id", default="imported-plan")
+    plan.add_argument("--max-input-bytes", type=int, default=32768)
+    plan.add_argument("--max-files", type=int, default=32)
+    plan.add_argument("--target-tokens", type=int, default=4096)
+    plan.add_argument("--out")
+    external = import_sub.add_parser("external")
+    external.add_argument("--source", required=True)
+    external.add_argument("--family", choices=["workflow", "agent"], required=True)
+    external.add_argument("--profile", default="generic")
+    external.add_argument("--package-id", default="external-dialect-import")
+    external.add_argument("--max-input-bytes", type=int, default=32768)
+    external.add_argument("--target-tokens", type=int, default=4096)
+    external.add_argument("--out")
+    check = import_sub.add_parser("check")
+    check.add_argument("--candidate", required=True)
+    external_check = import_sub.add_parser("external-check")
+    external_check.add_argument("--candidate", required=True)
+    proposal_check = import_sub.add_parser("proposal-check")
+    proposal_check.add_argument("--proposal", required=True)
+
+
+def _add_quality_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    quality = subparsers.add_parser("quality", help="optional quality commands")
+    quality_sub = quality.add_subparsers(dest="quality_command", required=True)
+    pack_check = quality_sub.add_parser("pack-check")
+    pack_check.add_argument("--manifest")
+    behavior_check = quality_sub.add_parser("behavior-check")
+    behavior_check.add_argument("--manifest")
+    behavior_check.add_argument("--fixture", action="append", default=[])
+    template_list = quality_sub.add_parser("template-list")
+    template_list.add_argument("--out")
+    template_check = quality_sub.add_parser("template-check")
+    template_check.add_argument("--project-root", default=".")
+    template_check.add_argument("--template-id")
+    template_check.add_argument("--out")
+    bug_recipe_list = quality_sub.add_parser("bug-recipe-list")
+    bug_recipe_list.add_argument("--out")
+    bug_recipe_check = quality_sub.add_parser("bug-recipe-check")
+    bug_recipe_check.add_argument("--recipe-id")
+    bug_recipe_check.add_argument("--out")
+
+
+def _add_review_mesh_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    review_mesh = subparsers.add_parser("review-mesh", help="optional Review Mesh commands")
+    review_mesh_sub = review_mesh.add_subparsers(dest="review_mesh_command", required=True)
+    template_list = review_mesh_sub.add_parser("template-list")
+    template_list.add_argument("--out")
+    profile = review_mesh_sub.add_parser("profile")
+    profile.add_argument("--profile-id", default="optional-review-mesh")
+    profile.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS), action="append", default=[])
+    profile.add_argument("--default-mode", choices=list(REVIEW_MESH_MODE_IDS), default="leader-draft-multi-review")
+    profile.add_argument("--reviewer-model-class", action="append", default=[])
+    profile.add_argument("--require-independence", action="store_true")
+    profile.add_argument("--independence-dimension", choices=["host", "model"], action="append", default=[])
+    profile.add_argument("--allow-live-calls", action="store_true")
+    profile.add_argument("--max-invocations", type=int)
+    profile.add_argument("--max-input-tokens", type=int)
+    profile.add_argument("--max-output-tokens", type=int)
+    profile.add_argument("--max-wall-seconds", type=int)
+    profile.add_argument("--out")
+    recommend = review_mesh_sub.add_parser("recommend")
+    source = recommend.add_mutually_exclusive_group(required=True)
+    source.add_argument("--text")
+    source.add_argument("--file")
+    source.add_argument("--intake")
+    source.add_argument("--manifest")
+    recommend.add_argument("--sdd-tier", choices=["S0", "S1", "S2"])
+    recommend.add_argument("--risk-flag", action="append", default=[])
+    recommend.add_argument("--out")
+    prepare = review_mesh_sub.add_parser("prepare")
+    prepare_source = prepare.add_mutually_exclusive_group(required=True)
+    prepare_source.add_argument("--manifest")
+    prepare_source.add_argument("--intake")
+    prepare_source.add_argument("--handoff")
+    prepare.add_argument("--template", choices=list(REVIEW_MESH_OPERATOR_TEMPLATE_IDS), default="leader-draft-review")
+    prepare.add_argument("--profile-id")
+    prepare.add_argument("--phase")
+    prepare.add_argument("--reviewer", action="append", default=[])
+    prepare.add_argument("--blocking", action="store_true")
+    prepare.add_argument("--evidence-id", action="append", default=[])
+    prepare.add_argument("--out-dir")
+    prepare.add_argument("--out")
+    assign = review_mesh_sub.add_parser("assign")
+    assign_source = assign.add_mutually_exclusive_group(required=True)
+    assign_source.add_argument("--manifest")
+    assign_source.add_argument("--intake")
+    assign_source.add_argument("--handoff")
+    assign.add_argument("--profile")
+    assign.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS), required=True)
+    assign.add_argument("--phase", required=True)
+    assign.add_argument("--assignment-id", required=True)
+    assign.add_argument("--reviewer-id", required=True)
+    assign.add_argument("--reviewer-role", default="reviewer")
+    assign.add_argument("--reviewer-model-class", default="strong-reasoning")
+    assign.add_argument("--reviewer-host-identity-hash")
+    assign.add_argument("--reviewer-model-identity-hash")
+    assign.add_argument("--blocking", action="store_true")
+    assign.add_argument("--evidence-id", action="append", default=[])
+    assign.add_argument("--out")
+    import_result = review_mesh_sub.add_parser("import-result")
+    import_result.add_argument("--profile", required=True)
+    import_result.add_argument("--assignment", required=True)
+    import_result.add_argument("--reviewer-output", required=True)
+    import_result.add_argument("--allow-local-evidence-ref", action="store_true")
+    import_result.add_argument("--out")
+    synthesize = review_mesh_sub.add_parser("synthesize")
+    synthesize.add_argument("--profile", required=True)
+    synthesize.add_argument("--result", action="append", required=True)
+    synthesize.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS))
+    synthesize.add_argument("--accepted-finding-id", action="append", default=[])
+    synthesize.add_argument("--rejected-finding-id", action="append", default=[])
+    synthesize.add_argument("--out")
+    quorum = review_mesh_sub.add_parser("quorum")
+    quorum.add_argument("--profile", required=True)
+    quorum.add_argument("--synthesis", required=True)
+    quorum.add_argument("--min-reviewers", type=int, required=True)
+    quorum.add_argument("--required-role", action="append", default=[])
+    quorum.add_argument("--reviewer-role", action="append", default=[])
+    quorum.add_argument("--out")
+
+
+def _add_report_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    report = subparsers.add_parser("report", help="read-only report commands")
+    report_sub = report.add_subparsers(dest="report_command", required=True)
+    status_view = report_sub.add_parser("status-view")
+    status_view.add_argument("--project-root", default=".")
+    status_view.add_argument("--artifact", action="append", default=[])
+    status_view.add_argument("--max-items", type=int, default=12)
+    status_view.add_argument("--target-window", default="8k")
+    status_view.add_argument("--out")
+    event_feed = report_sub.add_parser("event-feed")
+    event_feed.add_argument("--state", required=True)
+    event_feed.add_argument("--out")
+    progress = report_sub.add_parser("progress")
+    progress.add_argument("--state", required=True)
+    progress.add_argument("--usage-receipt", action="append", default=[])
+    progress.add_argument("--change-summary")
+    progress.add_argument("--watch", action="store_true")
+    progress.add_argument("--watch-iterations", type=int, default=5)
+    progress.add_argument("--watch-interval", type=float, default=1.0)
+    progress.add_argument("--terminal", action="store_true")
+    progress.add_argument("--out")
+    progress_bridge = report_sub.add_parser("progress-bridge")
+    progress_bridge.add_argument("--adapter", required=True)
+    progress_bridge.add_argument("--support-level", choices=["AUTO", "WATCH", "MANUAL", "UNSUPPORTED"], required=True)
+    progress_bridge.add_argument(
+        "--hook-point",
+        choices=[
+            "after-workflow-run",
+            "after-task-result",
+            "after-task-accept",
+            "after-finalize",
+            "side-terminal-watch",
+            "manual",
+        ],
+        required=True,
+    )
+    progress_bridge.add_argument("--state", required=True)
+    progress_bridge.add_argument("--usage-receipt", action="append", default=[])
+    progress_bridge.add_argument("--change-summary")
+    progress_bridge.add_argument("--display-mode", choices=["terminal", "json"], default="terminal")
+    progress_bridge.add_argument("--watch", action="store_true")
+    progress_bridge.add_argument("--watch-iterations", type=int, default=1)
+    progress_bridge.add_argument("--watch-interval", type=float, default=0.0)
+    progress_bridge.add_argument("--terminal", action="store_true")
+    progress_bridge.add_argument("--out")
+    change_summary = report_sub.add_parser("change-summary")
+    change_summary.add_argument("--project-root", default=".")
+    change_summary.add_argument("--base")
+    change_summary.add_argument("--head")
+    change_summary.add_argument("--staged", action="store_true")
+    change_summary.add_argument("--path", action="append", default=[])
+    change_summary.add_argument("--out")
+
+
+def _add_workflow_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    workflow = subparsers.add_parser("workflow", help="workflow commands")
+    workflow_sub = workflow.add_subparsers(dest="workflow_command", required=True)
+    workflow_status = workflow_sub.add_parser("status")
+    workflow_status.add_argument("--state", required=True)
+    workflow_status.add_argument("--full", action="store_true")
+    workflow_next = workflow_sub.add_parser("next")
+    workflow_next.add_argument("--state", required=True)
+    workflow_run = workflow_sub.add_parser("run")
+    workflow_run.add_argument("--state", required=True)
+    workflow_run.add_argument("--manifest", required=True)
+    workflow_run.add_argument("--lock")
+    workflow_run.add_argument("--operation-id", required=True)
+    workflow_run.add_argument("--expected-revision", required=True, type=int)
+    workflow_run.add_argument("--source-revision", required=True)
+    workflow_run.add_argument("--reason")
+    workflow_run.add_argument("--out")
+    add_progress_hook_args(workflow_run)
+    workflow_adopt = workflow_sub.add_parser("adopt-plan")
+    workflow_adopt.add_argument("--state", required=True)
+    workflow_adopt.add_argument("--manifest", required=True)
+    workflow_adopt.add_argument("--operation-id", required=True)
+    workflow_adopt.add_argument("--expected-revision", required=True, type=int)
+    workflow_adopt.add_argument("--source-revision", required=True)
+    workflow_adopt.add_argument("--reset-tasks", action="store_true")
+    workflow_adopt.add_argument("--preserve-accepted-compatible", action="store_true")
+    workflow_adopt.add_argument(
+        "--start-mode",
+        choices=["approval-required", "auto-after-freeze", "plan-only"],
+        default="approval-required",
+    )
+    workflow_adopt.add_argument("--authorized-by")
+    workflow_run_start = workflow_sub.add_parser("run-start")
+    workflow_run_start.add_argument("--state", required=True)
+    workflow_run_start.add_argument("--operation-id", required=True)
+    workflow_run_start.add_argument("--expected-revision", required=True, type=int)
+    workflow_run_start.add_argument("--source-revision", required=True)
+    workflow_run_start.add_argument("--reason", required=True)
+    workflow_block = workflow_sub.add_parser("block")
+    workflow_block.add_argument("--state", required=True)
+    workflow_block.add_argument("--operation-id", required=True)
+    workflow_block.add_argument("--expected-revision", required=True, type=int)
+    workflow_block.add_argument("--blocker-code", required=True)
+    workflow_block.add_argument("--reason", required=True)
+    workflow_resolve = workflow_sub.add_parser("resolve")
+    workflow_resolve.add_argument("--state", required=True)
+    workflow_resolve.add_argument("--operation-id", required=True)
+    workflow_resolve.add_argument("--expected-revision", required=True, type=int)
+    workflow_resolve.add_argument("--reason", required=True)
+    workflow_task = workflow_sub.add_parser("task-start")
+    workflow_task.add_argument("--state", required=True)
+    workflow_task.add_argument("--task", required=True)
+    workflow_task.add_argument("--operation-id", required=True)
+    workflow_task.add_argument("--expected-revision", required=True, type=int)
+    workflow_task.add_argument("--source-revision", required=True)
+    workflow_task.add_argument("--reason", required=True)
+    workflow_result = workflow_sub.add_parser("task-result")
+    workflow_result.add_argument("--state", required=True)
+    workflow_result.add_argument("--task", required=True)
+    workflow_result.add_argument("--operation-id", required=True)
+    workflow_result.add_argument("--expected-revision", required=True, type=int)
+    workflow_result.add_argument("--source-revision", required=True)
+    workflow_result.add_argument("--result", required=True)
+    workflow_result.add_argument("--model-usage-receipt")
+    workflow_result.add_argument("--budget-targets")
+    workflow_result.add_argument("--reason", required=True)
+    add_progress_hook_args(workflow_result)
+    workflow_budget = workflow_sub.add_parser("budget-decision")
+    workflow_budget.add_argument("--state", required=True)
+    workflow_budget.add_argument("--task", required=True)
+    workflow_budget.add_argument("--operation-id", required=True)
+    workflow_budget.add_argument("--expected-revision", required=True, type=int)
+    workflow_budget.add_argument("--source-revision", required=True)
+    workflow_budget.add_argument("--model-usage-receipt")
+    workflow_budget.add_argument("--budget-policy")
+    workflow_budget.add_argument("--receipt", required=True)
+    workflow_budget.add_argument(
+        "--action",
+        choices=["continue-same-route", "reroute-cheaper", "reroute-stronger", "split-task", "abort"],
+    )
+    workflow_budget.add_argument("--decision-receipt")
+    workflow_budget.add_argument("--route-decision")
+    workflow_budget.add_argument("--split-packet")
+    workflow_budget.add_argument("--cap-deltas")
+    workflow_budget.add_argument("--operator-identity-hash")
+    workflow_budget.add_argument("--reason", required=True)
+    workflow_budget_policy = workflow_sub.add_parser("budget-policy-check")
+    workflow_budget_policy.add_argument("--policy", required=True)
+    workflow_accept = workflow_sub.add_parser("task-accept")
+    workflow_accept.add_argument("--state", required=True)
+    workflow_accept.add_argument("--task", required=True)
+    workflow_accept.add_argument("--operation-id", required=True)
+    workflow_accept.add_argument("--expected-revision", required=True, type=int)
+    workflow_accept.add_argument("--review", required=True)
+    workflow_accept.add_argument("--implementation-audit")
+    workflow_accept.add_argument("--reason", required=True)
+    add_progress_hook_args(workflow_accept)
+    workflow_finalize = workflow_sub.add_parser("finalize")
+    workflow_finalize.add_argument("--state", required=True)
+    workflow_finalize.add_argument("--operation-id", required=True)
+    workflow_finalize.add_argument("--expected-revision", required=True, type=int)
+    workflow_finalize.add_argument("--source-revision", required=True)
+    workflow_finalize.add_argument("--final-audit", required=True)
+    workflow_finalize.add_argument("--proof", required=True)
+    workflow_finalize.add_argument("--proof-integrity")
+    workflow_finalize.add_argument("--goal-record")
+    workflow_finalize.add_argument("--follow-up-register")
+    workflow_finalize.add_argument("--completion-gate-receipt")
+    workflow_finalize.add_argument("--final-implementation-audit")
+    workflow_finalize.add_argument("--review-mesh-quorum", action="append", default=[])
+    workflow_finalize.add_argument("--reason", required=True)
+    add_progress_hook_args(workflow_finalize)
+
+
+def _add_audit_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    audit = subparsers.add_parser("audit", help="audit commands")
+    audit_sub = audit.add_subparsers(dest="audit_command", required=True)
+    ownership = audit_sub.add_parser("ownership")
+    ownership.add_argument("--manifest", required=True)
+    ownership.add_argument("--base", required=False)
+    ownership.add_argument("--path", action="append", default=[])
+    ownership.add_argument("--fail-on-unowned", action="store_true")
+    ownership.add_argument("--fail-on-forbidden", action="store_true")
+    review_check = audit_sub.add_parser("review-check")
+    review_check.add_argument("--review", required=True)
+    implementation = audit_sub.add_parser("implementation")
+    implementation.add_argument("--manifest", required=True)
+    implementation.add_argument("--state", required=True)
+    implementation.add_argument("--task", required=True)
+    implementation.add_argument("--result", required=True)
+    implementation.add_argument("--review", required=True)
+    implementation.add_argument("--evidence", action="append", default=[])
+    implementation.add_argument("--sandbox-receipt", action="append", default=[])
+    implementation.add_argument("--review-mesh-quorum", action="append", default=[])
+    implementation.add_argument("--path", action="append", default=[])
+    implementation.add_argument("--base")
+    implementation.add_argument("--expected-revision", type=int)
+    implementation.add_argument("--auditor-id", default="implementation-auditor")
+    implementation.add_argument("--auditor-surface", default="cli")
+    implementation.add_argument("--out")
+    final_implementation = audit_sub.add_parser("final-implementation")
+    final_implementation.add_argument("--manifest", required=True)
+    final_implementation.add_argument("--state", required=True)
+    final_implementation.add_argument("--report", action="append", required=True)
+    final_implementation.add_argument("--auditor-id", default="final-implementation-auditor")
+    final_implementation.add_argument("--auditor-surface", default="cli")
+    final_implementation.add_argument("--out")
+
+
+def _add_context_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    context = subparsers.add_parser("context", help="compact context commands")
+    context_sub = context.add_subparsers(dest="context_command", required=True)
+    profile_check = context_sub.add_parser("profile-check")
+    profile_check.add_argument("--profile", required=True)
+    context_check = context_sub.add_parser("check")
+    context_check.add_argument("--profile", required=True)
+    context_check.add_argument("--task-packet", required=True)
+    context_check.add_argument("--summary", required=True)
+    context_check.add_argument("--target-window")
+    context_check.add_argument("--latest-user", default="")
+    context_render = context_sub.add_parser("render")
+    context_render.add_argument("--profile", required=True)
+    context_render.add_argument("--task-packet", required=True)
+    context_render.add_argument("--summary", required=True)
+    context_render.add_argument("--target-window")
+    context_render.add_argument("--latest-user", default="")
+    external_import = context_sub.add_parser("external-import")
+    external_import.add_argument("--source", required=True)
+    external_import.add_argument("--citation")
+    external_import.add_argument("--source-id")
+    external_import.add_argument("--max-input-bytes", type=int, default=32768)
+    external_import.add_argument("--target-tokens", type=int, default=2048)
+    external_import.add_argument("--out")
+    episode_retrieve = context_sub.add_parser("episode-retrieve")
+    episode_retrieve.add_argument("--project-root", default=".")
+    episode_retrieve.add_argument("--artifact", action="append", required=True)
+    episode_retrieve.add_argument("--external-context", action="append", default=[])
+    episode_retrieve.add_argument("--query", default="")
+    episode_retrieve.add_argument("--max-results", type=int, default=8)
+    episode_retrieve.add_argument("--max-external-context-hints", type=int, default=4)
+    episode_retrieve.add_argument("--target-tokens", type=int, default=2048)
+    episode_retrieve.add_argument("--out")
+
+
+def _add_goal_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    goal = subparsers.add_parser("goal", help="goal continuity commands")
+    goal_sub = goal.add_subparsers(dest="goal_command", required=True)
+    goal_check = goal_sub.add_parser("check")
+    goal_check.add_argument("--record", required=True)
+    goal_check.add_argument("--state")
+    goal_check.add_argument("--current", action="store_true")
+    goal_summarize = goal_sub.add_parser("summarize")
+    goal_summarize.add_argument("--record", required=True)
+    goal_summarize.add_argument("--state", required=True)
+    goal_summarize.add_argument("--profile")
+    goal_summarize.add_argument("--target-window")
+    goal_view = goal_sub.add_parser("view")
+    goal_view.add_argument("--record", required=True)
+    goal_view.add_argument("--state", required=True)
+    goal_view.add_argument("--usage-receipt", action="append", default=[])
+    goal_view.add_argument("--change-summary")
+    goal_view.add_argument("--allow-stale-goal", action="store_true")
+    goal_view.add_argument("--terminal", action="store_true")
+    goal_view.add_argument("--out")
+    goal_update = goal_sub.add_parser("update")
+    goal_update.add_argument("--record", required=True)
+    goal_update.add_argument("--state", required=True)
+    goal_update.add_argument("--reason", required=True)
+    goal_update.add_argument("--status", choices=["ACTIVE", "BLOCKED", "READY_FOR_FINALIZATION", "COMPLETE"])
+    goal_update.add_argument("--evidence-id", action="append", default=[])
+    goal_update.add_argument("--out")
+
+
+def _add_model_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    model = subparsers.add_parser("model", help="model routing commands")
+    model_sub = model.add_subparsers(dest="model_command", required=True)
+    model_route = model_sub.add_parser("route")
+    model_route.add_argument("--request", required=True)
+    model_route.add_argument("--profile", default="profiles/model-routing-profile.v1.json")
+    model_route.add_argument("--host-profile")
+    model_profile_check = model_sub.add_parser("profile-check")
+    model_profile_check.add_argument("--profile", required=True)
+    model_profile_check.add_argument("--type", choices=["auto", "routing", "host"], default="auto")
+    model_usage_check = model_sub.add_parser("usage-check")
+    model_usage_check.add_argument("--receipt", required=True)
+    model_usage_check.add_argument("--route-decision")
+    model_usage_check.add_argument("--budget-targets")
+
+
+def _add_runner_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    runner = subparsers.add_parser("runner", help="controlled execution-loop commands")
+    runner_sub = runner.add_subparsers(dest="runner_command", required=True)
+    runner_start = runner_sub.add_parser("start")
+    runner_start.add_argument("--state", required=True)
+    runner_start.add_argument("--runner", required=True)
+    runner_start.add_argument("--policy")
+    runner_start.add_argument("--operation-id", required=True)
+    runner_start.add_argument("--reason", required=True)
+    runner_status = runner_sub.add_parser("status")
+    runner_status.add_argument("--runner", required=True)
+    runner_status.add_argument("--state")
+    runner_status.add_argument("--profile")
+    runner_status.add_argument("--target-window")
+    runner_transition = runner_sub.add_parser("transition")
+    runner_transition.add_argument("--runner", required=True)
+    runner_transition.add_argument("--state", required=True)
+    runner_transition.add_argument("--request", required=True)
+    runner_stop = runner_sub.add_parser("stop")
+    runner_stop.add_argument("--runner", required=True)
+    runner_stop.add_argument("--state", required=True)
+    runner_stop.add_argument("--operation-id", required=True)
+    runner_stop.add_argument("--expected-runner-revision", required=True, type=int)
+    runner_stop.add_argument("--reason", required=True)
+    runner_resume = runner_sub.add_parser("resume")
+    runner_resume.add_argument("--runner", required=True)
+    runner_resume.add_argument("--state", required=True)
+    runner_resume.add_argument("--operation-id", required=True)
+    runner_resume.add_argument("--expected-runner-revision", required=True, type=int)
+    runner_resume.add_argument("--reason", required=True)
+
+
+def _add_tier_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    tier = subparsers.add_parser("tier", help="SDD tier commands")
+    tier_sub = tier.add_subparsers(dest="tier_command", required=True)
+    tier_resolve = tier_sub.add_parser("resolve")
+    tier_resolve.add_argument("--request", required=True)
+
+
+def _add_specification_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    specification = subparsers.add_parser("specification", help="specification commands")
+    specification_sub = specification.add_subparsers(dest="specification_command", required=True)
+    specification_check = specification_sub.add_parser("check")
+    specification_check.add_argument("--specification", required=True)
+    completion_gate = specification_sub.add_parser("completion-gate")
+    completion_gate.add_argument("--state", required=True)
+    completion_gate.add_argument("--final-audit")
+    completion_gate.add_argument("--follow-up-register")
+    completion_gate.add_argument("--input")
+    completion_gate.add_argument("--verifier", default="completion-gate")
+    completion_gate.add_argument("--out")
+
+
+def _add_plan_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    plan = subparsers.add_parser("plan", help="plan commands")
+    plan_sub = plan.add_subparsers(dest="plan_command", required=True)
+    plan_check = plan_sub.add_parser("check")
+    plan_check.add_argument("--manifest", required=True)
+    plan_check.add_argument("--lock")
+    plan_check.add_argument("--require-completeness", action="store_true")
+    plan_check.add_argument("--completeness-profile")
+    completeness_check = plan_sub.add_parser("completeness-check")
+    completeness_check.add_argument("--manifest", required=True)
+    completeness_check.add_argument("--profile")
+    completeness_check.add_argument("--out")
+    acceptance_check = plan_sub.add_parser("acceptance-check")
+    acceptance_check.add_argument("--manifest", required=True)
+    acceptance_check.add_argument("--acceptance", required=True)
+    refs_check = plan_sub.add_parser("refs-check")
+    refs_check.add_argument("--manifest", required=True)
+    snapshot = plan_sub.add_parser("snapshot")
+    snapshot.add_argument("--manifest", required=True)
+    snapshot.add_argument("--out")
+    reconcile = plan_sub.add_parser("reconcile")
+    reconcile.add_argument("--manifest", required=True)
+    reconcile.add_argument("--snapshot", required=True)
+    handoff = plan_sub.add_parser("handoff")
+    handoff.add_argument("--manifest", required=True)
+    handoff.add_argument("--snapshot")
+    handoff.add_argument("--max-workstreams", type=int, default=12)
+    handoff.add_argument("--target-tokens", type=int, default=4096)
+    handoff.add_argument("--out")
+
+
+def _add_task_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    task = subparsers.add_parser("task", help="task commands")
+    task_sub = task.add_subparsers(dest="task_command", required=True)
+    task_compile = task_sub.add_parser("compile")
+    task_compile.add_argument("--manifest", required=True)
+    task_compile.add_argument("--out-dir")
+    task_compile.add_argument("--write", action="store_true")
+    small_compile = task_sub.add_parser("compile-small")
+    small_compile.add_argument("--manifest", required=True)
+    small_compile.add_argument("--context-profile", default="profiles/small-context-profile.v1.json")
+    small_compile.add_argument("--target-window", default="4k-strict")
+    small_compile.add_argument("--adaptive-decision")
+    small_compile.add_argument("--out-dir")
+    small_compile.add_argument("--write", action="store_true")