#!/usr/bin/env python3
"""Argparse surface for the Yao CLI."""

import argparse
from collections.abc import Callable

from yao_cli_parser_evidence import add_evidence_commands
from yao_cli_parser_operator import add_operator_commands
from yao_cli_parser_operations import add_operating_loop_commands


SCRIPT_INTERFACE = "internal-module"
SCRIPT_INTERFACE_REASON = "Imported by yao.py to keep CLI parser declarations separate from command orchestration."


def _handler(command_handlers: dict[str, Callable[[argparse.Namespace], int]], name: str) -> Callable[[argparse.Namespace], int]:
    if name not in command_handlers:
        raise KeyError(f"Missing CLI command handler: {name}")
    return command_handlers[name]


def build_parser(command_handlers: dict[str, Callable[[argparse.Namespace], int]]) -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Unified authoring CLI for yao-meta-skill.")
    subparsers = parser.add_subparsers(dest="command", required=True)

    init_cmd = subparsers.add_parser("init", help="Initialize a minimal skill package.")
    init_cmd.add_argument("name")
    init_cmd.add_argument("--description", default="Describe what the skill does and when to use it.")
    init_cmd.add_argument("--title")
    init_cmd.add_argument("--output-dir", default=".")
    init_cmd.add_argument("--mode", choices=["scaffold", "production", "library", "governed"], default="scaffold")
    init_cmd.add_argument("--archetype", choices=["scaffold", "production", "library", "governed"], default="scaffold")
    init_cmd.add_argument("--external-reference", action="append", default=[])
    init_cmd.add_argument("--user-reference", action="append", default=[])
    init_cmd.add_argument("--local-constraint", action="append", default=[])
    init_cmd.add_argument("--github-query")
    init_cmd.add_argument("--github-top-n", type=int, default=3)
    init_cmd.add_argument("--github-fixture-dir")
    init_cmd.add_argument("--intent-job")
    init_cmd.add_argument("--intent-real-input", action="append", default=[])
    init_cmd.add_argument("--intent-primary-output")
    init_cmd.add_argument("--intent-exclusion", action="append", default=[])
    init_cmd.add_argument("--intent-constraint", action="append", default=[])
    init_cmd.add_argument("--intent-standard", action="append", default=[])
    init_cmd.add_argument("--intent-correction")
    init_cmd.set_defaults(func=_handler(command_handlers, "command_init"))

    quickstart_cmd = subparsers.add_parser(
        "quickstart",
        help="Interactive fast path for creating a scaffold-first skill package.",
    )
    quickstart_cmd.add_argument("--name")
    quickstart_cmd.add_argument("--job")
    quickstart_cmd.add_argument("--real-input", action="append", default=[])
    quickstart_cmd.add_argument("--primary-output")
    quickstart_cmd.add_argument("--description")
    quickstart_cmd.add_argument("--title")
    quickstart_cmd.add_argument("--output-dir", default=".")
    quickstart_cmd.add_argument("--mode", choices=["scaffold", "production", "library", "governed"])
    quickstart_cmd.add_argument("--archetype", choices=["scaffold", "production", "library", "governed"])
    quickstart_cmd.add_argument("--external-reference", action="append", default=[])
    quickstart_cmd.add_argument("--user-reference", action="append", default=[])
    quickstart_cmd.add_argument("--local-constraint", action="append", default=[])
    quickstart_cmd.add_argument("--constraint", action="append", default=[])
    quickstart_cmd.add_argument("--github-query")
    quickstart_cmd.add_argument("--github-top-n", type=int, default=3)
    quickstart_cmd.add_argument("--github-fixture-dir")
    quickstart_cmd.add_argument("--no-update-check", action="store_true")
    quickstart_cmd.set_defaults(func=_handler(command_handlers, "command_quickstart"))

    validate_cmd = subparsers.add_parser("validate", help="Run validate, lint, governance, and resource checks.")
    validate_cmd.add_argument("skill_dir", nargs="?", default=".")
    validate_cmd.add_argument("--require-manifest", action="store_true")
    validate_cmd.set_defaults(func=_handler(command_handlers, "command_validate"))

    optimize_cmd = subparsers.add_parser("optimize-description", help="Optimize description candidates for a target.")
    optimize_cmd.add_argument(
        "--target",
        choices=["root", "team-frontend-review", "governed-incident-command", "all"],
        default="root",
    )
    optimize_cmd.add_argument("--write", action="store_true", help="Write default report artifacts for the target.")
    optimize_cmd.set_defaults(func=_handler(command_handlers, "command_optimize_description"))

    promote_cmd = subparsers.add_parser("promote-check", help="Apply promotion policy and build iteration bundles.")
    promote_cmd.set_defaults(func=_handler(command_handlers, "command_promote_check"))

    python_compat_cmd = subparsers.add_parser(
        "python-compat",
        help="Check Python source compatibility for the supported CI/runtime interpreter.",
    )
    python_compat_cmd.add_argument("skill_dir", nargs="?", default=".")
    python_compat_cmd.add_argument("--path", action="append", default=[])
    python_compat_cmd.add_argument("--target-python", default="3.11")
    python_compat_cmd.add_argument("--output-json")
    python_compat_cmd.add_argument("--output-md")
    python_compat_cmd.add_argument("--generated-at")
    python_compat_cmd.set_defaults(func=_handler(command_handlers, "command_python_compat"))

    architecture_audit_cmd = subparsers.add_parser(
        "architecture-audit",
        help="Render maintainability evidence for large Python files and CLI command surface.",
    )
    architecture_audit_cmd.add_argument("skill_dir", nargs="?", default=".")
    architecture_audit_cmd.add_argument("--output-json")
    architecture_audit_cmd.add_argument("--output-md")
    architecture_audit_cmd.add_argument("--warn-lines", type=int, default=900)
    architecture_audit_cmd.add_argument("--block-lines", type=int, default=1500)
    architecture_audit_cmd.add_argument("--generated-at")
    architecture_audit_cmd.set_defaults(func=_handler(command_handlers, "command_architecture_audit"))

    review_cmd = subparsers.add_parser("review", help="Locate the current bundle and human review stub for a target.")
    review_cmd.add_argument(
        "--target",
        choices=["root", "team-frontend-review", "governed-incident-command"],
        default="root",
    )
    review_cmd.set_defaults(func=_handler(command_handlers, "command_review"))

    snapshot_cmd = subparsers.add_parser("release-snapshot", help="Create a versioned snapshot from current promotion outputs.")
    snapshot_cmd.add_argument(
        "--target",
        choices=["root", "team-frontend-review", "governed-incident-command"],
        default="root",
    )
    snapshot_cmd.add_argument("--label", default="manual")
    snapshot_cmd.set_defaults(func=_handler(command_handlers, "command_release_snapshot"))

    flow_cmd = subparsers.add_parser(
        "workspace-flow",
        help="Run optimize, promotion, review refresh, and release snapshots as one authoring flow.",
    )
    flow_cmd.add_argument(
        "--target",
        choices=["root", "team-frontend-review", "governed-incident-command", "all"],
        default="root",
    )
    flow_cmd.add_argument("--label", default="manual")
    flow_cmd.set_defaults(func=_handler(command_handlers, "command_workspace_flow"))

    report_cmd = subparsers.add_parser("report", help="Render route, iteration, regression, and context reports.")
    report_cmd.add_argument("--refresh-optimization", action="store_true")
    report_cmd.set_defaults(func=_handler(command_handlers, "command_report"))

    skill_report_cmd = subparsers.add_parser("skill-report", help="Render the HTML skill report for a skill package.")
    skill_report_cmd.add_argument("skill_dir", nargs="?", default=".")
    skill_report_cmd.add_argument("--output-html")
    skill_report_cmd.add_argument("--output-json")
    skill_report_cmd.set_defaults(func=_handler(command_handlers, "command_skill_report"))

    skill_interpretation_cmd = subparsers.add_parser(
        "skill-interpretation",
        help="Render the first-class skill interpretation report for a skill package.",
    )
    skill_interpretation_cmd.add_argument("skill_dir", nargs="?", default=".")
    skill_interpretation_cmd.add_argument("--output-html")
    skill_interpretation_cmd.add_argument("--output-json")
    skill_interpretation_cmd.set_defaults(func=_handler(command_handlers, "command_skill_interpretation"))

    review_viewer_cmd = subparsers.add_parser("review-viewer", help="Render a compact HTML review page for a skill package.")
    review_viewer_cmd.add_argument("skill_dir", nargs="?", default=".")
    review_viewer_cmd.add_argument("--output-html")
    review_viewer_cmd.add_argument("--output-json")
    review_viewer_cmd.set_defaults(func=_handler(command_handlers, "command_review_viewer"))

    review_studio_cmd = subparsers.add_parser("review-studio", help="Render Review Studio 2.0 for a skill package.")
    review_studio_cmd.add_argument("skill_dir", nargs="?", default=".")
    review_studio_cmd.add_argument("--output-html")
    review_studio_cmd.add_argument("--output-json")
    review_studio_cmd.set_defaults(func=_handler(command_handlers, "command_review_studio"))

    skill_os2_audit_cmd = subparsers.add_parser(
        "skill-os2-audit",
        help="Render a requirement-by-requirement Skill OS 2.0 completion audit.",
    )
    skill_os2_audit_cmd.add_argument("skill_dir", nargs="?", default=".")
    skill_os2_audit_cmd.add_argument("--output-json")
    skill_os2_audit_cmd.add_argument("--output-md")
    skill_os2_audit_cmd.add_argument("--generated-at")
    skill_os2_audit_cmd.set_defaults(func=_handler(command_handlers, "command_skill_os2_audit"))

    skill_os2_coverage_cmd = subparsers.add_parser(
        "skill-os2-coverage",
        help="Render Skill OS 2.0 blueprint-to-evidence coverage.",
    )
    skill_os2_coverage_cmd.add_argument("skill_dir", nargs="?", default=".")
    skill_os2_coverage_cmd.add_argument("--output-json")
    skill_os2_coverage_cmd.add_argument("--output-md")
    skill_os2_coverage_cmd.add_argument("--generated-at")
    skill_os2_coverage_cmd.set_defaults(func=_handler(command_handlers, "command_skill_os2_coverage"))

    add_evidence_commands(subparsers, command_handlers)

    reference_scan_cmd = subparsers.add_parser(
        "reference-scan",
        help="Render a controlled benchmark scan report for a skill package.",
    )
    reference_scan_cmd.add_argument("skill_dir", nargs="?", default=".")
    reference_scan_cmd.add_argument("--reference", action="append", default=[])
    reference_scan_cmd.add_argument("--external-reference", action="append", default=[])
    reference_scan_cmd.add_argument("--user-reference", action="append", default=[])
    reference_scan_cmd.add_argument("--local-constraint", action="append", default=[])
    reference_scan_cmd.add_argument("--output-md")
    reference_scan_cmd.add_argument("--output-json")
    reference_scan_cmd.set_defaults(func=_handler(command_handlers, "command_reference_scan"))

    github_scan_cmd = subparsers.add_parser(
        "github-benchmark-scan",
        help="Search top public GitHub repositories and extract borrow or avoid patterns for a skill.",
    )
    github_scan_cmd.add_argument("skill_dir", nargs="?", default=".")
    github_scan_cmd.add_argument("--query", required=True)
    github_scan_cmd.add_argument("--top-n", type=int, default=3)
    github_scan_cmd.add_argument("--fixture-dir")
    github_scan_cmd.add_argument("--output-md")
    github_scan_cmd.add_argument("--output-json")
    github_scan_cmd.set_defaults(func=_handler(command_handlers, "command_github_benchmark_scan"))

    intent_confidence_cmd = subparsers.add_parser(
        "intent-confidence",
        help="Render a confidence report for how well the real job, inputs, outputs, and exclusions are understood.",
    )
    intent_confidence_cmd.add_argument("skill_dir", nargs="?", default=".")
    intent_confidence_cmd.add_argument("--context-json")
    intent_confidence_cmd.add_argument("--output-md")
    intent_confidence_cmd.add_argument("--output-json")
    intent_confidence_cmd.set_defaults(func=_handler(command_handlers, "command_intent_confidence"))

    intent_dialogue_cmd = subparsers.add_parser(
        "intent-dialogue",
        help="Render a front-loaded intent dialogue guide for a skill package.",
    )
    intent_dialogue_cmd.add_argument("skill_dir", nargs="?", default=".")
    intent_dialogue_cmd.add_argument("--output-md")
    intent_dialogue_cmd.add_argument("--output-json")
    intent_dialogue_cmd.set_defaults(func=_handler(command_handlers, "command_intent_dialogue"))

    reference_synthesis_cmd = subparsers.add_parser(
        "reference-synthesis",
        help="Render a multi-source reference synthesis report for a skill package.",
    )
    reference_synthesis_cmd.add_argument("skill_dir", nargs="?", default=".")
    reference_synthesis_cmd.add_argument("--output-md")
    reference_synthesis_cmd.add_argument("--output-json")
    reference_synthesis_cmd.set_defaults(func=_handler(command_handlers, "command_reference_synthesis"))

    output_risk_cmd = subparsers.add_parser(
        "output-risk-profile",
        help="Render predicted output failure modes and self-repair checks for a skill package.",
    )
    output_risk_cmd.add_argument("skill_dir", nargs="?", default=".")
    output_risk_cmd.add_argument("--output-md")
    output_risk_cmd.add_argument("--output-json")
    output_risk_cmd.set_defaults(func=_handler(command_handlers, "command_output_risk_profile"))

    artifact_design_cmd = subparsers.add_parser(
        "artifact-design-profile",
        help="Render artifact design direction and visual quality gates for a skill package.",
    )
    artifact_design_cmd.add_argument("skill_dir", nargs="?", default=".")
    artifact_design_cmd.add_argument("--output-md")
    artifact_design_cmd.add_argument("--output-json")
    artifact_design_cmd.set_defaults(func=_handler(command_handlers, "command_artifact_design_profile"))

    prompt_quality_cmd = subparsers.add_parser(
        "prompt-quality-profile",
        help="Render prompt-facing need model, RTF mapping, complexity, and quality checks for a skill package.",
    )
    prompt_quality_cmd.add_argument("skill_dir", nargs="?", default=".")
    prompt_quality_cmd.add_argument("--output-md")
    prompt_quality_cmd.add_argument("--output-json")
    prompt_quality_cmd.set_defaults(func=_handler(command_handlers, "command_prompt_quality_profile"))

    system_model_cmd = subparsers.add_parser(
        "system-model",
        help="Render a systems-thinking model for boundaries, feedback loops, drift, and leverage points.",
    )
    system_model_cmd.add_argument("skill_dir", nargs="?", default=".")
    system_model_cmd.add_argument("--output-md")
    system_model_cmd.add_argument("--output-json")
    system_model_cmd.set_defaults(func=_handler(command_handlers, "command_system_model"))

    iteration_directions_cmd = subparsers.add_parser(
        "iteration-directions",
        help="Render the top three next iteration directions for a skill package.",
    )
    iteration_directions_cmd.add_argument("skill_dir", nargs="?", default=".")
    iteration_directions_cmd.add_argument("--output-md")
    iteration_directions_cmd.add_argument("--output-json")
    iteration_directions_cmd.set_defaults(func=_handler(command_handlers, "command_iteration_directions"))

    feedback_cmd = subparsers.add_parser(
        "feedback",
        help="Capture lightweight reviewer feedback without running the full promotion flow.",
    )
    feedback_cmd.add_argument("skill_dir", nargs="?", default=".")
    feedback_cmd.add_argument("--note")
    feedback_cmd.add_argument("--rating", type=int, default=3)
    feedback_cmd.add_argument("--category", default="general")
    feedback_cmd.add_argument("--recommended-action", default="review")
    feedback_cmd.set_defaults(func=_handler(command_handlers, "command_feedback"))

    add_operator_commands(subparsers, command_handlers)
    add_operating_loop_commands(subparsers, command_handlers)

    baseline_compare_cmd = subparsers.add_parser(
        "baseline-compare",
        help="Render a lightweight with-skill vs baseline comparison across tracked targets.",
    )
    baseline_compare_cmd.set_defaults(func=_handler(command_handlers, "command_baseline_compare"))

    skill_ir_cmd = subparsers.add_parser("skill-ir", help="Export platform-neutral Skill IR for a skill package.")
    skill_ir_cmd.add_argument("skill_dir", nargs="?", default=".")
    skill_ir_cmd.add_argument("--output-json")
    skill_ir_cmd.add_argument("--validate-only", action="store_true")
    skill_ir_cmd.set_defaults(func=_handler(command_handlers, "command_skill_ir"))

    compile_skill_cmd = subparsers.add_parser(
        "compile-skill",
        help="Compile Skill IR into target-specific semantic contracts.",
    )
    compile_skill_cmd.add_argument("skill_dir", nargs="?", default=".")
    compile_skill_cmd.add_argument("--target", action="append")
    compile_skill_cmd.add_argument("--output-json")
    compile_skill_cmd.add_argument("--output-md")
    compile_skill_cmd.add_argument("--generated-at")
    compile_skill_cmd.set_defaults(func=_handler(command_handlers, "command_compile_skill"))

    output_eval_cmd = subparsers.add_parser("output-eval", help="Run Output Eval Lab assertion grading.")
    output_eval_cmd.add_argument("--cases")
    output_eval_cmd.add_argument("--output-json")
    output_eval_cmd.add_argument("--output-md")
    output_eval_cmd.add_argument("--blind-pack-json")
    output_eval_cmd.add_argument("--blind-pack-md")
    output_eval_cmd.add_argument("--blind-answer-key-json")
    output_eval_cmd.set_defaults(func=_handler(command_handlers, "command_output_eval"))

    output_review_kit_cmd = subparsers.add_parser(
        "output-review-kit",
        help="Prepare a reviewer-facing blind A/B output review kit without exposing the answer key.",
    )
    output_review_kit_cmd.add_argument("--blind-pack-json")
    output_review_kit_cmd.add_argument("--blind-pack-md")
    output_review_kit_cmd.add_argument("--decisions")
    output_review_kit_cmd.add_argument("--output-json")
    output_review_kit_cmd.add_argument("--output-md")
    output_review_kit_cmd.add_argument("--output-html")
    output_review_kit_cmd.add_argument("--write-template", action="store_true")
    output_review_kit_cmd.set_defaults(func=_handler(command_handlers, "command_output_review_kit"))

    output_execution_cmd = subparsers.add_parser(
        "output-exec",
        help="Record output-eval execution evidence, timing, and token usage.",
    )
    output_execution_cmd.add_argument("--cases")
    output_execution_cmd.add_argument("--output-json")
    output_execution_cmd.add_argument("--output-md")
    output_execution_cmd.add_argument("--runner-command")
    output_execution_cmd.add_argument(
        "--provider-runner",
        choices=["openai", "deepseek"],
        help="Use the bundled provider-backed runner instead of a custom runner command.",
    )
    output_execution_cmd.add_argument("--provider-model", help="Model for --provider-runner; otherwise use YAO_OUTPUT_EVAL_MODEL.")
    output_execution_cmd.add_argument("--provider-base-url", help="Override provider endpoint for compatible APIs.")
    output_execution_cmd.add_argument(
        "--provider-api-format",
        choices=["responses", "chat-completions"],
        help="Provider API shape used by the bundled provider runner. Defaults are selected from --provider-runner.",
    )
    output_execution_cmd.add_argument(
        "--provider-thinking",
        choices=["enabled", "disabled"],
        help="Optional thinking mode override for chat-completions providers that support it.",
    )
    output_execution_cmd.add_argument(
        "--provider-temperature",
        type=float,
        help="Sampling temperature for the bundled provider runner. Defaults to 0 for reproducibility.",
    )
    output_execution_cmd.add_argument("--api-key-env")
    output_execution_cmd.add_argument("--allow-insecure-localhost", action="store_true")
    output_execution_cmd.add_argument("--allow-custom-base-url", action="store_true")
    output_execution_cmd.add_argument("--timeout-seconds", type=float)
    output_execution_cmd.set_defaults(func=_handler(command_handlers, "command_output_execution"))

    output_review_cmd = subparsers.add_parser(
        "output-review",
        help="Adjudicate blind A/B output review decisions against the answer key.",
    )
    output_review_cmd.add_argument("--blind-pack")
    output_review_cmd.add_argument("--answer-key")
    output_review_cmd.add_argument("--decisions")
    output_review_cmd.add_argument("--output-json")
    output_review_cmd.add_argument("--output-md")
    output_review_cmd.add_argument("--write-template", action="store_true")
    output_review_cmd.set_defaults(func=_handler(command_handlers, "command_output_review"))

    output_review_import_cmd = subparsers.add_parser(
        "output-review-import",
        help="Import human blind A/B reviewer decisions into the canonical decision file.",
    )
    output_review_import_cmd.add_argument("--input", required=True)
    output_review_import_cmd.add_argument("--format", choices=["auto", "json", "jsonl", "csv"], default="auto")
    output_review_import_cmd.add_argument("--blind-pack")
    output_review_import_cmd.add_argument("--output-json")
    output_review_import_cmd.add_argument("--reviewer")
    output_review_import_cmd.add_argument("--reviewed-at")
    output_review_import_cmd.add_argument("--blind-review-attested", action="store_true")
    output_review_import_cmd.add_argument("--run-adjudication", action="store_true")
    output_review_import_cmd.add_argument("--answer-key")
    output_review_import_cmd.add_argument("--adjudication-json")
    output_review_import_cmd.add_argument("--adjudication-md")
    output_review_import_cmd.set_defaults(func=_handler(command_handlers, "command_output_review_import"))

    conformance_cmd = subparsers.add_parser("conformance", help="Run runtime conformance checks for Skill OS targets.")
    conformance_cmd.add_argument("skill_dir", nargs="?", default=".")
    conformance_cmd.add_argument("--target", action="append", choices=["openai", "claude", "agent-skills", "vscode", "generic"])
    conformance_cmd.add_argument("--output-json")
    conformance_cmd.add_argument("--output-md")
    conformance_cmd.set_defaults(func=_handler(command_handlers, "command_conformance"))

    runtime_permissions_cmd = subparsers.add_parser(
        "runtime-permissions",
        help="Probe generated target adapters for runtime permission enforcement metadata.",
    )
    runtime_permissions_cmd.add_argument("skill_dir", nargs="?", default=".")
    runtime_permissions_cmd.add_argument("--package-dir", default="dist")
    runtime_permissions_cmd.add_argument("--target", action="append", choices=["openai", "claude", "generic", "vscode"])
    runtime_permissions_cmd.add_argument("--install-simulation-json")
    runtime_permissions_cmd.add_argument("--output-json")
    runtime_permissions_cmd.add_argument("--output-md")
    runtime_permissions_cmd.set_defaults(func=_handler(command_handlers, "command_runtime_permissions"))

    trust_cmd = subparsers.add_parser("trust", help="Run trust and security checks for a skill package.")
    trust_cmd.add_argument("skill_dir", nargs="?", default=".")
    trust_cmd.add_argument("--output-json")
    trust_cmd.add_argument("--output-md")
    trust_cmd.set_defaults(func=_handler(command_handlers, "command_trust"))

    skill_atlas_cmd = subparsers.add_parser("skill-atlas", help="Build a portfolio-level Skill Atlas for a workspace.")
    skill_atlas_cmd.add_argument("--workspace-root", default=".")
    skill_atlas_cmd.add_argument("--output-dir")
    skill_atlas_cmd.add_argument("--report-html")
    skill_atlas_cmd.add_argument("--report-json")
    skill_atlas_cmd.add_argument("--overlap-threshold", type=float)
    skill_atlas_cmd.add_argument("--today")
    skill_atlas_cmd.set_defaults(func=_handler(command_handlers, "command_skill_atlas"))

    registry_audit_cmd = subparsers.add_parser("registry-audit", help="Build and audit Skill OS registry package metadata.")
    registry_audit_cmd.add_argument("skill_dir", nargs="?", default=".")
    registry_audit_cmd.add_argument("--registry-dir")
    registry_audit_cmd.add_argument("--output-json")
    registry_audit_cmd.add_argument("--output-md")
    registry_audit_cmd.add_argument("--generated-at")
    registry_audit_cmd.set_defaults(func=_handler(command_handlers, "command_registry_audit"))

    package_cmd = subparsers.add_parser("package", help="Export compatibility artifacts for selected targets.")
    package_cmd.add_argument("skill_dir", nargs="?", default=".")
    package_cmd.add_argument("--platform", action="append")
    package_cmd.add_argument("--output-dir", default="dist")
    package_cmd.add_argument("--expectations")
    package_cmd.add_argument("--zip", action="store_true")
    package_cmd.set_defaults(func=_handler(command_handlers, "command_package"))

    package_verify_cmd = subparsers.add_parser("package-verify", help="Verify generated package artifacts, archive safety, and registry parity.")
    package_verify_cmd.add_argument("skill_dir", nargs="?", default=".")
    package_verify_cmd.add_argument("--package-dir", default="dist")
    package_verify_cmd.add_argument("--expectations", default="evals/packaging_expectations.json")
    package_verify_cmd.add_argument("--registry-json", default="reports/registry_audit.json")
    package_verify_cmd.add_argument("--output-json")
    package_verify_cmd.add_argument("--output-md")
    package_verify_cmd.add_argument("--require-zip", action="store_true")
    package_verify_cmd.add_argument("--generated-at")
    package_verify_cmd.set_defaults(func=_handler(command_handlers, "command_package_verify"))

    install_simulate_cmd = subparsers.add_parser("install-simulate", help="Simulate installing a generated package into a temporary local skill root.")
    install_simulate_cmd.add_argument("skill_dir", nargs="?", default=".")
    install_simulate_cmd.add_argument("--package-dir", default="dist")
    install_simulate_cmd.add_argument("--install-root")
    install_simulate_cmd.add_argument("--output-json")
    install_simulate_cmd.add_argument("--output-md")
    install_simulate_cmd.add_argument("--generated-at")
    install_simulate_cmd.set_defaults(func=_handler(command_handlers, "command_install_simulate"))

    upgrade_check_cmd = subparsers.add_parser("upgrade-check", help="Compare current and previous registry package metadata for upgrade readiness.")
    upgrade_check_cmd.add_argument("skill_dir", nargs="?", default=".")
    upgrade_check_cmd.add_argument("--previous-package-json", required=True)
    upgrade_check_cmd.add_argument("--current-package-json", default="reports/registry_audit.json")
    upgrade_check_cmd.add_argument("--output-json")
    upgrade_check_cmd.add_argument("--output-md")
    upgrade_check_cmd.add_argument("--generated-at")
    upgrade_check_cmd.set_defaults(func=_handler(command_handlers, "command_upgrade_check"))

    test_cmd = subparsers.add_parser("test", help="Run a Makefile test target.")
    test_cmd.add_argument("--target", default="test")
    test_cmd.set_defaults(func=_handler(command_handlers, "command_test"))

    update_cmd = subparsers.add_parser("check-update", help="Check whether a newer yao-meta-skill version is available.")
    update_cmd.add_argument("--force", action="store_true")
    update_cmd.add_argument("--no-cache", action="store_true")
    update_cmd.add_argument("--version-url")
    update_cmd.add_argument("--manifest-url")
    update_cmd.add_argument("--timeout", type=float, default=3.0)
    update_cmd.add_argument("--allow-custom-update-url", action="store_true")
    update_cmd.set_defaults(func=_handler(command_handlers, "command_check_update"))

    return parser