code/self_healing_finetuning/n21/cli.py

from __future__ import annotations

import argparse
import json
from pathlib import Path

from approvals.promotion import plan_promotion
from bootstrap.hf_model_setup import bootstrap_hf_model
from data_pipeline.ingest import ingest_dataset
from data_pipeline.all_role_defect_repair import build_all_role_defect_repair
from data_pipeline.learning_pdf_to_jsonl import build_training_jsonl_from_learning, convert_learning_role, convert_learning_tree
from data_pipeline.nonrepair_balance import generate_nonrepair_balance_data
from data_pipeline.paired_eval_failure_repair import build_paired_eval_failure_repair, build_release_paired_eval_failure_repair
from data_pipeline.paired_eval_diagnostics import build_paired_eval_diagnostics
from data_pipeline.pairwise_preference_memory import build_pairwise_preference_data
from data_pipeline.repair_dataset import build_repair_dataset
from data_pipeline.reasoning_data_generation import generate_grounded_reasoning_examples
from data_pipeline.repair_acceptance_gate import run_repair_acceptance_gate
from data_pipeline.repair_coverage import evaluate_repair_coverage
from data_pipeline.seed_expander import expand_seed_data
from data_pipeline.source_intake import intake_public_sources
from data_pipeline.training_data_validation import validate_training_data
from eval.baseline import record_baseline
from eval.a_plus_report import build_a_plus_report
from eval.best_run_tracker import update_best_run
from eval.certification import certify
from eval.evidence_producers import produce_required_eval_evidence
from eval.frozen_suite import validate_frozen_suite
from eval.model_quality_gate import evaluate_model_quality_gate
from eval.paired_eval_defect_ranker import rank_all_role_defects
from inference.deploy import deploy as deploy_run
from model_policy.selector import select_model
from model_policy.profiles import apply_provider_profile, resolve_model_profile
from monitoring.canary import run_canary_monitor
from n21.config import load_structured, write_json
from n21.settings import CONFIG_ROOT, DEFAULT_MODEL_ID, REPO_ROOT, SHFT_WORKSPACE_ROOT, ensure_workspace
from observability.audit_log import utc_now
from orchestrator.cycle_controller import run_self_healing_cycles
from orchestrator.continuous_status import write_continuous_status
from orchestrator.human_owner_decision import request_human_owner_instruction
from orchestrator.dataset_provenance import check_resume_provenance
from orchestrator.lifecycle_proof import run_lifecycle_proof
from orchestrator.provider_routing import get_provider, validate_route
from orchestrator.promotion_blocker_controller import build_controller_decision
from orchestrator.stall_breakout import run_stall_breakout
from release_packaging.release import DEFAULT_SOURCE_RUN_ID, export_release, validate_release
from providers.hf_staging import stage_hf_artifact_bucket, stage_hf_code, stage_hf_dataset
from repair.diagnose import diagnose as diagnose_error
from repair.evidence_report import write_repair_evidence
from rollback.anchor import load_last_good_anchor, validate_rollback_anchor
from security.secret_scan import scan_tree
from training.launch import run_training
from training.hf_preference_train import run_preference_training


def new_run_id() -> str:
    stamp = utc_now().replace("-", "").replace(":", "").replace("T", "_").replace("Z", "")
    return f"run_{stamp}"


def run_dir(run_id: str) -> Path:
    return SHFT_WORKSPACE_ROOT / "runs" / run_id


def command_validate_config(args: argparse.Namespace) -> int:
    ensure_workspace()
    provider = get_provider(args.provider)
    config_path = CONFIG_ROOT / "providers" / f"{args.provider}.yaml"
    config = load_structured(config_path)
    profile = resolve_model_profile(args.model_profile, model_candidate=args.model_candidate, base_model_id=args.base_model_id)
    config = apply_provider_profile(config, profile)
    result = provider.validate_config(config, live=args.live)
    route_errors = validate_route(args.provider, args.infer_provider or args.provider)
    secret_findings = scan_tree(REPO_ROOT)
    if route_errors:
        result["errors"].extend(route_errors)
    if secret_findings:
        result["warnings"].append(f"secret scan findings require review: {len(secret_findings)} files")
    result["ok"] = not result["errors"]
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 2


def command_select_model(args: argparse.Namespace) -> int:
    ensure_workspace()
    record = select_model(args.task, args.env, strategy=args.strategy, model_profile=args.model_profile, model_candidate=args.model_candidate)
    out = SHFT_WORKSPACE_ROOT / "current" / args.env / "model_selection.json"
    write_json(out, record)
    print(json.dumps(record, indent=2))
    print(f"wrote {out}")
    return 0


def command_bootstrap_model(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = bootstrap_hf_model(Path(args.config), live=args.live)
    print(json.dumps(result, indent=2))
    return 0 if result["status"] in {"planned", "completed"} else 5


def command_ingest(args: argparse.Namespace) -> int:
    ensure_workspace()
    rid = args.run_id or new_run_id()
    out = run_dir(rid) / "dataset_snapshot"
    dataset_path = Path(args.dataset_path) if args.dataset_path else None
    try:
        manifest = ingest_dataset(out, dataset_path=dataset_path)
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc), "run_id": rid}, indent=2))
        return 2
    write_json(run_dir(rid) / "manifests" / "dataset_manifest.json", manifest)
    print(json.dumps({"run_id": rid, "dataset_manifest": manifest}, indent=2))
    return 0


def command_expand_seed_data(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = expand_seed_data(train_count=args.train_count, eval_count=args.eval_count)
    print(json.dumps(result, indent=2))
    return 0


def command_build_repair_dataset(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = build_repair_dataset(Path(args.predictions), Path(args.output), max_records=args.max_records)
    print(json.dumps(result, indent=2))
    return 0 if result["status"] == "completed" else 3


def command_build_paired_eval_failure_repair(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_paired_eval_failure_repair(
            predictions_path=Path(args.predictions),
            asset_class=args.asset_class,
            role=args.role,
            output_path=Path(args.output) if args.output else None,
            max_records=args.max_records,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL FAILURE REPAIR DATA] "
        f"RECORDS={result.get('record_count')} "
        f"OUTPUT={result.get('output_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0


def command_build_release_paired_eval_failure_repair(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_release_paired_eval_failure_repair(
            release_id=args.release_id,
            asset_class=args.asset_class,
            role=args.role,
            output_path=Path(args.output) if args.output else None,
            max_records=args.max_records,
            max_records_per_run=args.max_records_per_run,
            allow_empty=args.allow_empty,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL RELEASE FAILURE REPAIR DATA] "
        f"RECORDS={result.get('record_count')} "
        f"SOURCE_RUNS={result.get('source_run_count')} "
        f"OUTPUT={result.get('output_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0


def command_rank_paired_eval_defects(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = rank_all_role_defects(output_path=Path(args.output) if args.output else None)
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    summary = result.get("summary", {})
    counts = summary.get("defect_counts", {})
    print(
        "[SHFT VITAL DEFECT RANKING] "
        f"RANKED_ROLES={summary.get('ranked_role_count')} "
        f"PROOF_MISSING_ROLES={summary.get('proof_missing_role_count')} "
        f"FAILED_PREDICTIONS={summary.get('failed_prediction_count')} "
        f"NUMERIC={counts.get('numeric_reasoning')} "
        f"FACT_INFERENCE={counts.get('fact_inference_separation')} "
        f"ROLE_DISCIPLINE={counts.get('role_discipline')} "
        f"RISK_TRADEOFF={counts.get('risk_tradeoff_framing')} "
        f"UNSUPPORTED={counts.get('hallucination_unsupported_claim')} "
        f"SOURCE_GROUNDING={counts.get('weak_source_grounding')} "
        f"OVERFIT_STYLE={counts.get('overfit_memorized_answer_style')}"
    )
    print(json.dumps(result, indent=2))
    return 0


def command_build_all_role_defect_repair(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_all_role_defect_repair(
            ranking_path=Path(args.ranking) if args.ranking else None,
            output_path=Path(args.output) if args.output else None,
            top_n=args.top_n,
            max_records_per_role=args.max_records_per_role,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    summary = result.get("summary", {})
    counts = summary.get("defect_counts", {})
    print(
        "[SHFT VITAL DEFECT REPAIR] "
        f"OK={result.get('ok')} "
        f"ROLES={summary.get('role_count')} "
        f"ROLES_OK={summary.get('roles_ok')} "
        f"FILES={summary.get('output_file_count')} "
        f"ROWS={summary.get('total_repair_rows')} "
        f"WEAK_SOURCE={counts.get('weak_source_grounding')} "
        f"NUMERIC={counts.get('numeric_reasoning')} "
        f"RISK={counts.get('risk_tradeoff_framing')} "
        f"FACT_INF={counts.get('fact_inference_separation')} "
        f"ROLE_DISCIPLINE={counts.get('role_discipline')} "
        f"OVERFIT={counts.get('overfit_memorized_answer_style')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result.get("ok") else 6


def command_build_pairwise_preference_data(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_pairwise_preference_data(
            run_id=args.run_id,
            asset_class=args.asset_class,
            role=args.role,
            predictions_path=Path(args.predictions) if args.predictions else None,
            output_path=Path(args.output) if args.output else None,
            max_records=args.max_records,
            min_records=args.min_records,
            include_historical=not args.no_historical,
            include_critical_failures=not args.losses_only,
            include_reasoning_chosen=not args.baseline_chosen_only,
            repair_strategy=args.repair_strategy,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    summary = result.get("summary", {})
    print(
        "[SHFT VITAL PREFERENCE MEMORY] "
        f"OK={result.get('ok')} "
        f"PAIRS={summary.get('preference_pair_count')} "
        f"LOSSES={summary.get('pairwise_loss_pair_count')} "
        f"CRITICAL={summary.get('critical_failure_pair_count')} "
        f"OUTPUT={result.get('output_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result.get("ok") else 6


def command_repair_acceptance_gate(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = run_repair_acceptance_gate(
            input_path=Path(args.input),
            output_dir=Path(args.output_dir) if args.output_dir else None,
            require_sections=args.require_sections,
            min_acceptance_rate=args.min_acceptance_rate,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL REPAIR ACCEPTANCE] "
        f"OK={result.get('ok')} "
        f"INPUT={result.get('input_count')} "
        f"ACCEPTED={result.get('accepted_count')} "
        f"REJECTED={result.get('rejected_count')} "
        f"RATE={result.get('acceptance_rate')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result.get("ok") else 6


def command_promotion_blocker_controller(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_controller_decision(
            run_id=args.run_id,
            release_id=args.release_id,
            asset_class=args.asset_class,
            role=args.role,
            max_preference_rounds=args.max_preference_rounds,
            output_path=Path(args.output) if args.output else None,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL STRATEGY CONTROLLER] "
        f"OK={result.get('ok')} "
        f"NEXT={result.get('next_strategy')} "
        f"HOLD={result.get('should_hold')} "
        f"ROUNDS={result.get('preference_round_count')}/{result.get('max_preference_rounds')} "
        f"FAILED={','.join(result.get('failed_promotion_checks') or [])}"
    )
    print(json.dumps(result, indent=2))
    return 0


def command_build_paired_eval_diagnostics(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_paired_eval_diagnostics(
            run_id=args.run_id,
            asset_class=args.asset_class,
            role=args.role,
            predictions_path=Path(args.predictions) if args.predictions else None,
            output_dir=Path(args.output_dir) if args.output_dir else None,
            max_records=args.max_records,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    summary = result.get("summary", {})
    print(
        "[SHFT VITAL PAIRED DIAGNOSTICS] "
        f"OK={result.get('ok')} "
        f"ROWS={summary.get('prediction_count')} "
        f"LOSSES={summary.get('pairwise_loss_count')} "
        f"CRITICAL={summary.get('critical_failure_count')} "
        f"REPAIR_TARGETS={summary.get('accepted_repair_target_count')} "
        f"OUTPUT={result.get('diagnostics_jsonl_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result.get("ok") else 6


def command_convert_learning_pdfs(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = convert_learning_role(
            asset_class=args.asset_class,
            role=args.role,
            chunk_chars=args.chunk_chars,
            min_text_chars=args.min_text_chars,
            skip_existing=not args.force,
        )
    except (FileNotFoundError, ValueError, RuntimeError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["ok"] = result["skipped_pdf_count"] == 0 and result["record_count"] > 0
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 3


def command_convert_learning_sources(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = convert_learning_tree(
            asset_class=args.asset_class,
            role=args.role,
            source_type=args.source_type,
            chunk_chars=args.chunk_chars,
            min_text_chars=args.min_text_chars,
            skip_existing=not args.force,
        )
    except (FileNotFoundError, ValueError, RuntimeError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["ok"] = result["skipped_pdf_count"] == 0 and result["record_count"] > 0
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 3


def command_build_learning_training_jsonl(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = build_training_jsonl_from_learning(
            output_path=Path(args.output),
            source=Path(args.source) if args.source else None,
            asset_class=args.asset_class,
            role=args.role,
            repair_oversample_factor=args.repair_oversample_factor,
            max_repair_selected_ratio=args.max_repair_selected_ratio,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["ok"] = True
    print(json.dumps(result, indent=2))
    return 0


def command_intake_public_sources(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = intake_public_sources(
            asset_class=args.asset_class,
            role=args.role,
            catalog_path=Path(args.catalog) if args.catalog else None,
            policy_path=Path(args.policy) if args.policy else None,
            max_sources=args.max_sources,
            promote_approved=not args.no_promote,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["ok"] = True
    print(json.dumps(result, indent=2))
    return 0


def command_validate_training_data(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = validate_training_data(
            source=Path(args.source),
            output_dir=Path(args.output_dir),
            backup_dir=Path(args.backup_dir) if args.backup_dir else None,
            apply_quarantine=args.apply_quarantine,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 3


def command_generate_reasoning_data(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = generate_grounded_reasoning_examples(
            asset_class=args.asset_class,
            role=args.role,
            source=Path(args.source) if args.source else None,
            output_path=Path(args.output) if args.output else None,
            max_records=args.max_records,
            policy_path=Path(args.policy) if args.policy else None,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL REASONING DATA] "
        f"STATUS={str(result.get('status')).upper()} "
        f"GENERATED={result.get('generated_count')} "
        f"REJECTED={result.get('rejected_count')} "
        f"OUTPUT={result.get('output_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 7


def command_generate_nonrepair_balance_data(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = generate_nonrepair_balance_data(
            asset_class=args.asset_class,
            role=args.role,
            source=Path(args.source) if args.source else None,
            output_path=Path(args.output) if args.output else None,
            min_nonrepair_rows=args.min_nonrepair_rows,
            force=args.force,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL NONREPAIR BALANCE] "
        f"OK={result.get('ok')} "
        f"BEFORE={result.get('current_nonrepair_rows_before_generation')} "
        f"GENERATED={result.get('generated_count')} "
        f"PROJECTED={result.get('projected_nonrepair_rows')} "
        f"OUTPUT={result.get('output_path')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 9


def command_repair_coverage_gate(args: argparse.Namespace) -> int:
    ensure_workspace()
    minimums = {
        "numeric_reasoning": args.min_numeric_reasoning,
        "fact_inference_separation": args.min_fact_inference,
        "neutral_language": args.min_neutral_language,
        "risk_tradeoff": args.min_risk_tradeoff,
        "critical_reasoning": args.min_critical_reasoning,
    }
    try:
        result = evaluate_repair_coverage(
            selected_training=Path(args.selected_training),
            output_path=Path(args.output) if args.output else None,
            minimums=minimums,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    print(
        "[SHFT VITAL REPAIR COVERAGE] "
        f"OK={result.get('ok')} "
        f"REPAIR_ROWS={result.get('repair_row_count')} "
        f"NUMERIC={result.get('counts', {}).get('numeric_reasoning')} "
        f"FACT_INFERENCE={result.get('counts', {}).get('fact_inference_separation')} "
        f"NEUTRAL={result.get('counts', {}).get('neutral_language')} "
        f"RISK_TRADEOFF={result.get('counts', {}).get('risk_tradeoff')} "
        f"CRITICAL={result.get('counts', {}).get('critical_reasoning')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 8


def command_summarize_asset_preflight(args: argparse.Namespace) -> int:
    ensure_workspace()
    roles = args.roles or [
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ]
    preflight_root = Path(args.preflight_root) if args.preflight_root else SHFT_WORKSPACE_ROOT / "preflight" / args.asset_class
    role_reports = []

    for role in roles:
        role_dir = preflight_root / role
        selected_training = role_dir / "selected_training.jsonl"
        selected_manifest = role_dir / "selected_training.manifest.json"
        repair_gate = role_dir / "repair_coverage_gate.json"
        validation_report = role_dir / "training_data_validation" / "training_data_validation_report.json"
        conflict_report = role_dir / "training_data_validation" / "conflict_report.json"
        quarantine_manifest = role_dir / "training_data_validation" / "quarantine_manifest.json"
        train_source = REPO_ROOT / "data" / "learning" / args.asset_class / role

        missing = [
            str(path)
            for path in [
                selected_training,
                selected_manifest,
                repair_gate,
                validation_report,
                conflict_report,
                quarantine_manifest,
            ]
            if not path.exists()
        ]
        manifest = _load_optional_json(selected_manifest)
        repair = _load_optional_json(repair_gate)
        validation = _load_optional_json(validation_report)

        errors = list(missing)
        if not train_source.exists():
            errors.append(f"missing training source: {train_source}")
        if manifest is not None:
            if manifest.get("asset_class") != args.asset_class:
                errors.append(f"manifest asset_class mismatch: {manifest.get('asset_class')} != {args.asset_class}")
            if manifest.get("role") != role:
                errors.append(f"manifest role mismatch: {manifest.get('role')} != {role}")
            if not manifest.get("selected_training_sha256"):
                errors.append("selected_training.manifest.json missing selected_training_sha256")
            if int(manifest.get("record_count") or 0) <= 0:
                errors.append("selected_training.manifest.json record_count must be positive")
            if not manifest.get("required_reasoning_included"):
                errors.append("selected_training.manifest.json required_reasoning_included must be true")
        if repair is not None and repair.get("ok") is not True:
            errors.extend([f"repair coverage: {item}" for item in repair.get("errors", [])])
        if validation is not None and validation.get("ok") is not True:
            errors.extend([f"training validation: {item}" for item in validation.get("schema_errors", [])[:10]])
            errors.extend([f"training conflict: {item}" for item in validation.get("conflicts", [])[:10]])

        selected_count = None if manifest is None else int(manifest.get("record_count") or 0)
        original_count = None if manifest is None else int(manifest.get("original_record_count") or 0)
        repair_count = None if repair is None else int(repair.get("repair_row_count") or 0)
        validation_count = None if validation is None else int(validation.get("record_count") or 0)
        repair_to_selected_ratio = None
        repair_to_original_ratio = None
        if selected_count:
            repair_to_selected_ratio = round(float(repair_count or 0) / float(selected_count), 6)
        if original_count:
            repair_to_original_ratio = round(float(repair_count or 0) / float(original_count), 6)
        corpus_warnings: list[str] = []
        if original_count is not None and original_count < 300:
            corpus_warnings.append(f"data_thin_original_records:{original_count}<300")
        if repair_to_selected_ratio is not None and repair_to_selected_ratio > 0.75:
            corpus_warnings.append(f"repair_heavy_selected_ratio:{repair_to_selected_ratio}>0.75")
        if repair_to_original_ratio is not None and repair_to_original_ratio > 2.0:
            corpus_warnings.append(f"repair_to_original_ratio:{repair_to_original_ratio}>2.0")

        role_reports.append(
            {
                "asset_class": args.asset_class,
                "role": role,
                "release_id": f"linvest21_fingpt_{args.asset_class}_{role}_v1_001",
                "train_source": str(train_source),
                "role_out": str(role_dir),
                "selected_training": str(selected_training),
                "selected_training_sha256": None if manifest is None else manifest.get("selected_training_sha256"),
                "selected_record_count": selected_count,
                "original_record_count": original_count,
                "repair_row_count": repair_count,
                "repair_to_selected_ratio": repair_to_selected_ratio,
                "repair_to_original_ratio": repair_to_original_ratio,
                "corpus_warnings": corpus_warnings,
                "repair_coverage_ok": bool(repair and repair.get("ok") is True),
                "repair_counts": None if repair is None else repair.get("counts"),
                "training_validation_ok": bool(validation and validation.get("ok") is True),
                "training_validation_record_count": validation_count,
                "schema_error_count": None if validation is None else validation.get("schema_error_count"),
                "conflict_count": None if validation is None else validation.get("conflict_count"),
                "paid_training_ready": not errors,
                "errors": errors,
            }
        )

    summary = {
        "schema_version": "shft_asset_all_roles_preflight_summary_v1",
        "asset_class": args.asset_class,
        "role_count": len(role_reports),
        "roles": roles,
        "preflight_root": str(preflight_root),
        "paid_training_submission": "disabled_by_preflight",
        "all_roles_ready": all(report["paid_training_ready"] for report in role_reports),
        "failed_roles": [report["role"] for report in role_reports if not report["paid_training_ready"]],
        "data_thin_roles": [
            report["role"]
            for report in role_reports
            if any(str(item).startswith("data_thin_original_records") for item in report.get("corpus_warnings", []))
        ],
        "repair_heavy_roles": [
            report["role"]
            for report in role_reports
            if any("repair_heavy" in str(item) or "repair_to_original" in str(item) for item in report.get("corpus_warnings", []))
        ],
        "corpus_warning_count": sum(len(report.get("corpus_warnings", [])) for report in role_reports),
        "role_reports": role_reports,
        "created_at": utc_now(),
        "ok": all(report["paid_training_ready"] for report in role_reports),
    }
    output = Path(args.output) if args.output else preflight_root / "all_roles_preflight_summary.json"
    write_json(output, summary)
    print(
        "[SHFT VITAL ASSET PREFLIGHT] "
        f"ASSET={args.asset_class} OK={summary['ok']} "
        f"ROLES={summary['role_count']} FAILED={len(summary['failed_roles'])} "
        f"DATA_THIN={len(summary['data_thin_roles'])} REPAIR_HEAVY={len(summary['repair_heavy_roles'])} "
        f"OUTPUT={output}"
    )
    print(json.dumps(summary, indent=2))
    return 0 if summary["ok"] else 9


def command_check_resume_provenance(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = check_resume_provenance(
        run_dir=run_dir(args.run_id),
        train_source=Path(args.train_source),
    )
    print(
        "[SHFT VITAL RESUME PROVENANCE] "
        f"CAN_RESUME={result['can_resume']} "
        f"STALE={result['stale_training_artifacts']} "
        f"REASON={result['reason']}"
    )
    print(json.dumps(result, indent=2))
    if result["stale_training_artifacts"]:
        return 9
    return 0 if result["can_resume"] else 2


def command_stall_breakout(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = run_stall_breakout(
            run_id=args.run_id,
            asset_class=args.asset_class,
            role=args.role,
            train_source=Path(args.train_source),
            quality_gate_exit_code=args.quality_gate_exit_code,
            catalog_path=Path(args.catalog) if args.catalog else None,
            policy_path=Path(args.policy) if args.policy else None,
            max_sources=args.max_sources,
            apply_quarantine=args.apply_quarantine,
        )
    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["ok"] = result["status"] == "ready_for_next_training_run"
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 7


def command_train(args: argparse.Namespace) -> int:
    ensure_workspace()
    rid = args.run_id or new_run_id()
    rdir = run_dir(rid)
    rdir.mkdir(parents=True, exist_ok=True)
    result = run_training(
        rdir,
        run_id=rid,
        model_candidate=args.model_candidate,
        train_provider=args.train_provider,
        infer_provider=args.infer_provider,
        release_id=args.release_id,
        finetune_start_policy=args.finetune_start_policy,
        model_profile=args.model_profile,
        live=args.live,
    )
    print(json.dumps({"run_id": rid, "result": result}, indent=2))
    return 0


def command_cycle(args: argparse.Namespace) -> int:
    ensure_workspace()
    rid = args.run_id
    rdir = run_dir(rid)
    rdir.mkdir(parents=True, exist_ok=True)
    profile = resolve_model_profile(args.model_profile, model_candidate=args.model_candidate)
    summary = run_self_healing_cycles(
        rdir,
        run_id=rid,
        model_candidate=str(profile["model_candidate"]),
        train_provider=args.train_provider,
        infer_provider=args.infer_provider,
        max_cycles=args.max_cycles,
        stop_on_certified=not args.continue_after_certified,
    )
    print(json.dumps(summary, indent=2))
    return 0


def command_eval(args: argparse.Namespace) -> int:
    ensure_workspace()
    rdir = run_dir(args.run_id)
    profile = resolve_model_profile(args.model_profile, model_candidate=args.model_candidate)
    report = certify(args.env, args.task, model_candidate=str(profile["model_candidate"]))
    write_json(rdir / "eval" / "certification_report.json", report)
    lines = [
        "# Certification Report",
        "",
        f"Run: `{args.run_id}`",
        f"Gate result: `{report['gate_result']}`",
        "",
        "## Rationale",
        "",
    ]
    lines.extend(f"- {item}" for item in report["improvement_report"]["rationale"])
    (rdir / "eval" / "certification_report.md").parent.mkdir(parents=True, exist_ok=True)
    (rdir / "eval" / "certification_report.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
    print(json.dumps(report, indent=2))
    return 0 if report["gate_result"] == "pass" else 3


def command_baseline_eval(args: argparse.Namespace) -> int:
    ensure_workspace()
    rdir = run_dir(args.run_id)
    rdir.mkdir(parents=True, exist_ok=True)
    report = record_baseline(
        rdir,
        run_id=args.run_id,
        model_id=str(resolve_model_profile(args.model_profile, model_candidate=args.model_candidate)["model_candidate"]),
        env=args.env,
        task=args.task,
    )
    print(json.dumps(report, indent=2))
    return 0


def command_validate_eval_suite(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        report = validate_frozen_suite(Path(args.manifest))
    except (FileNotFoundError, ValueError, KeyError, json.JSONDecodeError) as exc:
        print(json.dumps({"ok": False, "error": str(exc), "manifest": args.manifest}, indent=2))
        return 2
    print(json.dumps(report, indent=2))
    return 0 if report["ok"] else 2


def _load_optional_json(path: Path) -> dict | None:
    if not path.exists():
        return None
    return json.loads(path.read_text(encoding="utf-8-sig"))


def _load_dataset_manifest_from_run_chain(run_id: str, training_plan: dict | None) -> dict | None:
    visited: set[str] = set()
    current_run_id: str | None = run_id
    current_training_plan = training_plan

    for _ in range(16):
        if not current_run_id or current_run_id in visited:
            return None
        visited.add(current_run_id)
        current_run_dir = run_dir(current_run_id)
        dataset_manifest = _load_optional_json(current_run_dir / "dataset_snapshot" / "dataset_manifest.json")
        if dataset_manifest is not None:
            return dataset_manifest

        if current_training_plan is None:
            current_training_plan = _load_optional_json(current_run_dir / "remote_artifacts" / "training_plan.json")
        source_run_id = None if current_training_plan is None else current_training_plan.get("source_run_id")
        current_run_id = source_run_id if isinstance(source_run_id, str) and source_run_id else None
        current_training_plan = None

    return None


def _release_certification_guard(source_run_id: str) -> dict[str, object]:
    quality_gate_path = run_dir(source_run_id) / "eval" / "model_quality_gate.json"
    report = _load_optional_json(quality_gate_path)
    ok = bool(report and report.get("ok") is True and report.get("eligible_for_promotion") is True)
    return {
        "ok": ok,
        "source_run_id": source_run_id,
        "quality_gate_path": str(quality_gate_path),
        "required": "eval/model_quality_gate.json with ok=true and eligible_for_promotion=true",
        "quality_signal": None if report is None else report.get("quality_signal"),
        "errors": [] if report is None else (report.get("errors") or []),
    }


def command_quality_gate(args: argparse.Namespace) -> int:
    ensure_workspace()
    rdir = run_dir(args.run_id)
    training_plan = _load_optional_json(rdir / "remote_artifacts" / "training_plan.json")
    dataset_manifest = _load_dataset_manifest_from_run_chain(args.run_id, training_plan)
    report = evaluate_model_quality_gate(
        paired_eval=_load_optional_json(rdir / "eval" / "paired_eval_report.json"),
        training_plan=training_plan,
        training_result=_load_optional_json(rdir / "remote_artifacts" / "training_result.json"),
        trainer_metrics_summary=_load_optional_json(rdir / "remote_artifacts" / "trainer_metrics_summary.json"),
        selected_checkpoint=_load_optional_json(rdir / "remote_artifacts" / "selected_checkpoint.json"),
        dataset_manifest=dataset_manifest,
        model_judge_report=_load_optional_json(rdir / "eval" / "model_judge_report.json"),
        human_review_report=_load_optional_json(rdir / "eval" / "human_spot_check_report.json"),
        baseline_proof_report=_load_optional_json(rdir / "eval" / "baseline_proof_report.json"),
        paired_diagnostics_manifest=_load_optional_json(rdir / "diagnostics" / "paired_eval_diagnostics_manifest.json"),
        preference_manifest=_load_optional_json(rdir / "preference_memory" / "preference_manifest.json"),
    )
    write_json(rdir / "eval" / "model_quality_gate.json", report)
    checks = report.get("checks", {})
    print(
        "[SHFT VITAL MODEL QUALITY] "
        f"CERTIFIED={report.get('ok')} "
        f"QUALITY_SIGNAL={str(report.get('quality_signal', 'unknown')).upper()} "
        f"CANDIDATE_AGGREGATE={checks.get('candidate_aggregate_absolute', {}).get('detail')} "
        f"CRITICAL_PASS={checks.get('critical_pass_absolute', {}).get('detail')} "
        f"WIN_RATE={checks.get('pairwise_win_rate', {}).get('detail')} "
        f"LOSS_RATE={checks.get('pairwise_loss_rate', {}).get('detail')} "
        f"BLOCKERS={len(report.get('errors') or [])}"
    )
    print(json.dumps(report, indent=2))
    return 0 if report["ok"] else 6


def command_train_preference(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = run_preference_training(args)
    print(json.dumps(result, indent=2))
    return 0 if result.get("ok") else 2


def command_a_plus_report(args: argparse.Namespace) -> int:
    ensure_workspace()
    report = build_a_plus_report(run_id=args.run_id, source_run_id=args.source_run_id)
    print(
        "[SHFT A+ REPORT] "
        f"RUN={args.run_id} GRADE={report.get('grade')} "
        f"OK={report.get('ok')} BLOCKERS={len(report.get('blockers') or [])}"
    )
    print(json.dumps(report, indent=2))
    return 0 if report.get("ok") else 7


def command_produce_eval_evidence(args: argparse.Namespace) -> int:
    ensure_workspace()
    rdir = run_dir(args.run_id)
    paired = _load_optional_json(rdir / "eval" / "paired_eval_report.json")
    if paired is None:
        print(json.dumps({"ok": False, "error": "missing eval/paired_eval_report.json", "run_id": args.run_id}, indent=2))
        return 2
    result = produce_required_eval_evidence(
        rdir,
        release_id=args.release_id,
        paired_eval=paired,
        approve_human=args.approve_human,
        request_human_email=args.request_human_email,
        human_email_timeout_seconds=args.human_email_timeout_seconds,
    )
    print(
        "[SHFT VITAL EVAL EVIDENCE] "
        f"BASELINE_PROOF={result['baseline_proof']['proof_mode']} "
        f"MODEL_JUDGE_SCORE={result['model_judge']['mean_score']} "
        f"HUMAN_STATUS={result['human_spot_check']['status']}"
    )
    print(json.dumps(result, indent=2))
    return 0


def command_update_best_run(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = update_best_run(run_id=args.run_id, release_id=args.release_id)
    current = result.get("current_run", {})
    best = result.get("best_run") or {}
    distance = current.get("distance_to_thresholds", {})
    source_batch = result.get("source_batch_acceptance") or {}
    comparison = result.get("previous_best_comparison") or {}
    print(
        "[SHFT VITAL BEST RUN] "
        f"UPDATED={result.get('updated')} "
        f"CURRENT_AGGREGATE={current.get('candidate_aggregate')} "
        f"CURRENT_CRITICAL_PASS={current.get('candidate_critical_pass_rate')} "
        f"BEST_RUN={best.get('run_id')} "
        f"BEST_AGGREGATE={best.get('candidate_aggregate')} "
        f"BEST_CRITICAL_PASS={best.get('candidate_critical_pass_rate')} "
        f"AGGREGATE_GAP={distance.get('candidate_aggregate_gap')} "
        f"CRITICAL_GAP={distance.get('critical_pass_gap')}"
    )
    print(
        "[SHFT VITAL SOURCE BATCH] "
        f"ACCEPTED={source_batch.get('accepted_for_future_training')} "
        f"DECISION={str(source_batch.get('decision')).upper()} "
        f"PREVIOUS_BEST={comparison.get('previous_best_run_id')} "
        f"AGGREGATE_DELTA_VS_PREVIOUS_BEST={comparison.get('aggregate_delta_vs_previous_best')} "
        f"CRITICAL_DELTA_VS_PREVIOUS_BEST={comparison.get('critical_pass_delta_vs_previous_best')}"
    )
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 4


def command_continuous_status(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = write_continuous_status(
        run_id=args.run_id,
        release_id=args.release_id,
        asset_class=args.asset_class,
        role=args.role,
        round_index=args.round_index,
        phase=args.phase,
    )
    current = result.get("current_intelligence", {})
    best = result.get("best_intelligence", {})
    distance = result.get("distance_to_thresholds", {})
    breakout = result.get("breakout", {})
    source_batch = result.get("source_batch_acceptance") or {}
    comparison = result.get("previous_best_comparison") or {}
    convergence = result.get("convergence_control") or {}
    strategy = result.get("next_data_strategy", {})
    print(
        "[SHFT VITAL INTELLIGENCE] "
        f"PHASE={str(result.get('phase')).upper()} ROUND={result.get('round_index')} CERTIFIED={result.get('certified')} "
        f"CURRENT_AGGREGATE={current.get('candidate_aggregate')} "
        f"CURRENT_CRITICAL_PASS={current.get('candidate_critical_pass_rate')} "
        f"WIN_RATE={current.get('pairwise_win_rate')} LOSS_RATE={current.get('pairwise_loss_rate')} "
        f"TRAIN_LOSS={current.get('train_loss')} TRAIN_RECORDS={current.get('train_records')} VALID_RECORDS={current.get('valid_records')}"
    )
    print(
        "[SHFT VITAL DISTANCE TO CERTIFICATION] "
        f"BEST_RUN={best.get('run_id')} BEST_AGGREGATE={best.get('candidate_aggregate')} "
        f"BEST_CRITICAL_PASS={best.get('candidate_critical_pass_rate')} "
        f"AGGREGATE_GAP={distance.get('candidate_aggregate_gap')} CRITICAL_GAP={distance.get('critical_pass_gap')}"
    )
    print(
        "[SHFT VITAL BREAKOUT] "
        f"STATUS={str(breakout.get('status')).upper()} TRAINABLE_NEW_SOURCES={breakout.get('trainable_new_source_count')} "
        f"LIVE_DISCOVERY_ATTEMPTS={breakout.get('live_discovery_attempt_count')} BLOCKERS={len(breakout.get('blockers') or [])}"
    )
    print(
        "[SHFT VITAL SOURCE BATCH] "
        f"ACCEPTED={source_batch.get('accepted_for_future_training')} "
        f"DECISION={str(source_batch.get('decision')).upper()} "
        f"PREVIOUS_BEST={comparison.get('previous_best_run_id')} "
        f"AGGREGATE_DELTA_VS_PREVIOUS_BEST={comparison.get('aggregate_delta_vs_previous_best')} "
        f"CRITICAL_DELTA_VS_PREVIOUS_BEST={comparison.get('critical_pass_delta_vs_previous_best')}"
    )
    print(
        "[SHFT VITAL CONVERGENCE] "
        f"STATE={str(convergence.get('state', 'CONTINUE')).upper()} "
        f"HALT_PAID_RETRAINING={convergence.get('should_halt_paid_retraining')} "
        f"ACTION={str(convergence.get('action', 'continue_measured_loop')).upper()} "
        f"REASONS={len(convergence.get('reasons') or [])}"
    )
    for index, action in enumerate(strategy.get("actions", [])[:5], start=1):
        print(f"[SHFT strategy] {index}. {action}")
    print(f"[SHFT artifacts] continuous_status={result.get('artifacts', {}).get('run_dir')}\\continuous_training_status.json")
    human_decision = None
    if args.enforce_convergence and convergence.get("should_halt_paid_retraining"):
        reason = "; ".join(str(item) for item in (convergence.get("reasons") or [])) or "convergence guard requires owner instruction"
        human_decision = request_human_owner_instruction(
            run_id=args.run_id,
            release_id=args.release_id,
            asset_class=args.asset_class,
            role=args.role,
            reason=reason,
        )
        instruction = (human_decision.get("decision") or {}).get("instruction")
        print(
            "[SHFT VITAL HUMAN OWNER DECISION] "
            f"OWNER={human_decision.get('owner_email')} "
            f"INSTRUCTION={str(instruction).upper()} "
            f"SOURCE={(human_decision.get('decision') or {}).get('source')} "
            f"ARTIFACT={result.get('artifacts', {}).get('run_dir')}\\human_owner_decision.json"
        )
        result["human_owner_decision"] = human_decision
        if instruction == "continue":
            result["convergence_control"]["owner_override"] = "continue"
            result["convergence_control"]["should_halt_paid_retraining"] = False
            result["convergence_control"]["exit_code"] = 0
            result["next_data_strategy"]["owner_instruction"] = "continue"
        elif instruction == "exit":
            result["convergence_control"]["owner_override"] = "exit"
            result["convergence_control"]["exit_code"] = 10
            result["next_data_strategy"]["owner_instruction"] = "exit"
        else:
            result["convergence_control"]["owner_override"] = "pending"
            result["convergence_control"]["exit_code"] = 9
            result["next_data_strategy"]["owner_instruction"] = "pending"
        out_dir = SHFT_WORKSPACE_ROOT / "continuous_training"
        out_dir.mkdir(parents=True, exist_ok=True)
        run_dir = SHFT_WORKSPACE_ROOT / "runs" / args.run_id
        write_json(out_dir / f"{args.release_id}_status.json", result)
        write_json(run_dir / "continuous_training_status.json", result)
        write_json(run_dir / "next_data_strategy.json", result["next_data_strategy"])
    print(json.dumps(result, indent=2))
    final_convergence = result.get("convergence_control") or {}
    if args.enforce_convergence and final_convergence.get("should_halt_paid_retraining"):
        return int(final_convergence.get("exit_code") or 8)
    return 0


def command_stage_hf_dataset(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = stage_hf_dataset(args.run_id, Path(args.dataset_dir), live=args.live)
    except ValueError as exc:
        print(json.dumps({"ok": False, "error": str(exc), "run_id": args.run_id}, indent=2))
        return 2
    print(json.dumps(result, indent=2))
    return 0 if result["status"] in {"planned", "completed"} else 3


def command_stage_hf_bucket(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = stage_hf_artifact_bucket(args.run_id, live=args.live)
    print(json.dumps(result, indent=2))
    return 0 if result["status"] in {"planned", "completed"} else 3


def command_stage_hf_code(args: argparse.Namespace) -> int:
    ensure_workspace()
    try:
        result = stage_hf_code(args.run_id, Path(args.code_dir), live=args.live)
    except ValueError as exc:
        print(json.dumps({"ok": False, "error": str(exc), "run_id": args.run_id}, indent=2))
        return 2
    print(json.dumps(result, indent=2))
    return 0 if result["status"] in {"planned", "completed"} else 3


def command_deploy(args: argparse.Namespace) -> int:
    ensure_workspace()
    manifest = deploy_run(
        run_dir(args.run_id),
        run_id=args.run_id,
        infer_provider=args.infer_provider,
        env=args.env,
        model_candidate=args.model_candidate,
        live=args.live,
    )
    print(json.dumps(manifest, indent=2))
    return 0


def command_promote(args: argparse.Namespace) -> int:
    ensure_workspace()
    rdir = run_dir(args.run_id)
    approvals = {"engineering": args.engineering, "compliance": args.compliance, "product_owner": args.product_owner}
    manifest = plan_promotion(
        implementation_root=SHFT_WORKSPACE_ROOT,
        run_dir=rdir,
        run_id=args.run_id,
        env=args.env,
        approvals=approvals,
        risk_tier=args.risk_tier,
        model_id=DEFAULT_MODEL_ID,
        live=args.live,
    )
    print(json.dumps(manifest, indent=2))
    return 4 if manifest["promotion_errors"] else 0


def command_rollback(args: argparse.Namespace) -> int:
    ensure_workspace()
    rollback_anchor = load_last_good_anchor(SHFT_WORKSPACE_ROOT, env=args.env)
    rollback_errors = ["missing last_good rollback anchor"] if rollback_anchor is None else validate_rollback_anchor(rollback_anchor)
    incident = {
        "run_id": args.run_id,
        "env": args.env,
        "target": args.to,
        "status": "rollback_blocked" if rollback_errors else ("rollback_planned" if not args.live else "rollback_requested"),
        "rollback_anchor": rollback_anchor,
        "rollback_errors": rollback_errors,
        "dry_run": not args.live,
        "created_at": utc_now(),
    }
    out = SHFT_WORKSPACE_ROOT / "rollback" / "incident_archive" / f"{args.run_id}_{args.env}_rollback.json"
    write_json(out, incident)
    print(json.dumps(incident, indent=2))
    return 4 if rollback_errors else 0


def command_monitor(args: argparse.Namespace) -> int:
    ensure_workspace()
    report = run_canary_monitor(run_dir(args.run_id), run_id=args.run_id, env=args.env, mode=args.mode)
    print(json.dumps(report, indent=2))
    return 5 if report["rollback_recommended"] else 0


def command_lifecycle_proof(args: argparse.Namespace) -> int:
    ensure_workspace()
    report = run_lifecycle_proof(
        run_dir(args.run_id),
        run_id=args.run_id,
        env=args.env,
        model_candidate=args.model_candidate,
        train_provider=args.train_provider,
        infer_provider=args.infer_provider,
        max_cycles=args.max_cycles,
        canary_mode=args.canary_mode,
    )
    print(json.dumps(report, indent=2))
    return 5 if report["evidence"]["rollback_recommended"] else 0


def command_diagnose(args: argparse.Namespace) -> int:
    result = diagnose_error(args.error_code)
    print(json.dumps(result, indent=2))
    return 0


def command_repair(args: argparse.Namespace) -> int:
    diagnosis = diagnose_error(args.error_code)
    evidence = write_repair_evidence(
        run_dir(args.run_id) / "repair" / str(diagnosis["playbook"]),
        {"run_id": args.run_id, "diagnosis": diagnosis, "status": "repair_plan_generated"},
    )
    print(json.dumps(evidence, indent=2))
    return 0


def command_export_release(args: argparse.Namespace) -> int:
    ensure_workspace()
    certification_guard = _release_certification_guard(args.source_run_id)
    if not certification_guard["ok"] and not args.allow_uncertified_export:
        print(
            json.dumps(
                {
                    "ok": False,
                    "error": "uncertified_source_run",
                    "certification_guard": certification_guard,
                    "allow_override": "--allow-uncertified-export",
                },
                indent=2,
            )
        )
        return 6
    try:
        result = export_release(
            release_id=args.release_id,
            source_run_id=args.source_run_id,
            export_mode=args.export_mode,
            base_model_id=args.base_model,
            model_id=args.model_id,
            asset_class=args.asset_class,
            role=args.role,
            merged_model_dir=args.merged_model_dir,
            gguf_model_path=args.gguf_model_path,
            zip_release=args.zip,
        )
    except (FileNotFoundError, ValueError) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
        return 2
    result["certification_guard"] = certification_guard
    result["certification_override"] = bool(args.allow_uncertified_export and not certification_guard["ok"])
    print(json.dumps(result, indent=2))
    return 0


def command_validate_release(args: argparse.Namespace) -> int:
    ensure_workspace()
    result = validate_release(args.release_id)
    print(json.dumps(result, indent=2))
    return 0 if result["ok"] else 3


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="n21 shft", description="Linvest21 SHFT dry-run MVP")
    sub = parser.add_subparsers(dest="command", required=True)

    p = sub.add_parser("validate-config")
    p.add_argument("--provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--infer-provider", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.add_argument("--base-model-id")
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_validate_config)

    p = sub.add_parser("select-model")
    p.add_argument("--task", default="finance_qa")
    p.add_argument("--env", default="dev", choices=["dev", "stage", "prod"])
    p.add_argument("--strategy", default="fingpt_first_bootstrap")
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.set_defaults(func=command_select_model)

    p = sub.add_parser("bootstrap-model")
    p.add_argument("--config", default=str(CONFIG_ROOT / "bootstrap" / "linvest21_fingpt_v1_000.yaml"))
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_bootstrap_model)

    p = sub.add_parser("ingest")
    p.add_argument("--run-id")
    p.add_argument("--dataset-path")
    p.set_defaults(func=command_ingest)

    p = sub.add_parser("expand-seed-data")
    p.add_argument("--train-count", type=int, default=120)
    p.add_argument("--eval-count", type=int, default=120)
    p.set_defaults(func=command_expand_seed_data)

    p = sub.add_parser("build-repair-dataset")
    p.add_argument("--predictions", required=True)
    p.add_argument("--output", default=str(REPO_ROOT / "data" / "repair" / "run_step18_eval_loss_repair.jsonl"))
    p.add_argument("--max-records", type=int, default=1500)
    p.set_defaults(func=command_build_repair_dataset)

    p = sub.add_parser("build-paired-eval-failure-repair")
    p.add_argument("--predictions", required=True)
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--output")
    p.add_argument("--max-records", type=int, default=500)
    p.set_defaults(func=command_build_paired_eval_failure_repair)

    p = sub.add_parser("build-release-paired-eval-failure-repair")
    p.add_argument("--release-id", required=True)
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--output")
    p.add_argument("--max-records", type=int, default=1500)
    p.add_argument("--max-records-per-run", type=int, default=120)
    p.add_argument("--allow-empty", action="store_true", help="Write an empty manifest when this release has no paired-failure history yet.")
    p.set_defaults(func=command_build_release_paired_eval_failure_repair)

    p = sub.add_parser("rank-paired-eval-defects")
    p.add_argument(
        "--output",
        default=str(SHFT_WORKSPACE_ROOT / "verification" / "paired_eval_defect_ranking_latest.json"),
        help="JSON report path for all-role paired-eval defect ranking.",
    )
    p.set_defaults(func=command_rank_paired_eval_defects)

    p = sub.add_parser("build-all-role-defect-repair")
    p.add_argument(
        "--ranking",
        default=str(SHFT_WORKSPACE_ROOT / "verification" / "paired_eval_defect_ranking_latest.json"),
        help="All-role paired-eval defect ranking JSON.",
    )
    p.add_argument(
        "--output",
        default=str(SHFT_WORKSPACE_ROOT / "verification" / "all_18_defect_repair_manifest_latest.json"),
        help="All-role defect-led repair manifest JSON.",
    )
    p.add_argument("--top-n", type=int, default=3, help="Number of measured top defects to cover per role.")
    p.add_argument("--max-records-per-role", type=int, default=160, help="Maximum repair rows to emit per role.")
    p.set_defaults(func=command_build_all_role_defect_repair)

    p = sub.add_parser("build-pairwise-preference-data")
    p.add_argument("--run-id", required=True, help="Run id containing eval/paired_predictions.jsonl.")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--predictions", help="Optional paired_predictions.jsonl override.")
    p.add_argument("--output", help="Optional preference_pairs.jsonl output path.")
    p.add_argument("--max-records", type=int, default=500)
    p.add_argument("--min-records", type=int, default=1)
    p.add_argument("--no-historical", action="store_true", help="Do not backfill from historical paired-eval losses.")
    p.add_argument("--losses-only", action="store_true", help="Only convert pairwise losses; skip critical failures that were not losses.")
    p.add_argument("--baseline-chosen-only", action="store_true", help="Use baseline answers only as chosen responses; skip deterministic corrected answers.")
    p.add_argument(
        "--repair-strategy",
        default="generic_loss_targeted",
        choices=[
            "generic_loss_targeted",
            "hard_negative_dpo",
            "critical_safety_repair",
            "human_failure_repair",
            "answer_quality_repair",
        ],
        help="Strategy lane chosen by the promotion-blocker controller.",
    )
    p.set_defaults(func=command_build_pairwise_preference_data)

    p = sub.add_parser("repair-acceptance-gate")
    p.add_argument("--input", required=True, help="Repair targets or preference pairs JSONL to validate before training.")
    p.add_argument("--output-dir")
    p.add_argument("--require-sections", action="store_true")
    p.add_argument("--min-acceptance-rate", type=float, default=0.80)
    p.set_defaults(func=command_repair_acceptance_gate)

    p = sub.add_parser("promotion-blocker-controller")
    p.add_argument("--run-id", required=True)
    p.add_argument("--release-id")
    p.add_argument("--asset-class", required=True)
    p.add_argument("--role", required=True)
    p.add_argument("--max-preference-rounds", type=int, default=5)
    p.add_argument("--output")
    p.set_defaults(func=command_promotion_blocker_controller)

    p = sub.add_parser("build-paired-eval-diagnostics")
    p.add_argument("--run-id", required=True, help="Run id containing eval/paired_predictions.jsonl.")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--predictions", help="Optional paired_predictions.jsonl override.")
    p.add_argument("--output-dir", help="Optional diagnostics output directory.")
    p.add_argument("--max-records", type=int)
    p.set_defaults(func=command_build_paired_eval_diagnostics)

    p = sub.add_parser("convert-learning-pdfs")
    p.add_argument("--asset-class", default="equity", choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", default="researcher", choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--chunk-chars", type=int)
    p.add_argument("--min-text-chars", type=int)
    p.add_argument("--force", action="store_true", help="Regenerate JSONL even when an output file already exists.")
    p.set_defaults(func=command_convert_learning_pdfs)

    p = sub.add_parser("convert-learning-sources")
    p.add_argument("--asset-class", choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--source-type", default="pdf", choices=["pdf"])
    p.add_argument("--chunk-chars", type=int)
    p.add_argument("--min-text-chars", type=int)
    p.add_argument("--force", action="store_true", help="Regenerate JSONL even when an output file already exists.")
    p.set_defaults(func=command_convert_learning_sources)

    p = sub.add_parser("build-learning-training-jsonl")
    p.add_argument("--source", help="JSONL file, role folder, asset folder, or full data/learning tree. Defaults to data/learning.")
    p.add_argument("--output", required=True)
    p.add_argument("--asset-class", choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--repair-oversample-factor", type=int, default=1)
    p.add_argument("--max-repair-selected-ratio", type=float)
    p.add_argument("--role", choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.set_defaults(func=command_build_learning_training_jsonl)

    p = sub.add_parser("intake-public-sources")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--catalog")
    p.add_argument("--policy")
    p.add_argument("--max-sources", type=int)
    p.add_argument("--no-promote", action="store_true", help="Download and manifest only; do not copy approved files into data/learning.")
    p.set_defaults(func=command_intake_public_sources)

    p = sub.add_parser("validate-training-data")
    p.add_argument("--source", required=True)
    p.add_argument("--output-dir", required=True)
    p.add_argument("--backup-dir")
    p.add_argument("--apply-quarantine", action="store_true")
    p.set_defaults(func=command_validate_training_data)

    p = sub.add_parser("generate-reasoning-data")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--source")
    p.add_argument("--output")
    p.add_argument("--max-records", type=int, default=120)
    p.add_argument("--policy")
    p.set_defaults(func=command_generate_reasoning_data)

    p = sub.add_parser("generate-nonrepair-balance-data")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--source")
    p.add_argument("--output")
    p.add_argument("--min-nonrepair-rows", type=int, default=100)
    p.add_argument("--force", action="store_true")
    p.set_defaults(func=command_generate_nonrepair_balance_data)

    p = sub.add_parser("repair-coverage-gate")
    p.add_argument("--selected-training", required=True)
    p.add_argument("--output")
    p.add_argument("--min-numeric-reasoning", type=int, default=300)
    p.add_argument("--min-fact-inference", type=int, default=300)
    p.add_argument("--min-neutral-language", type=int, default=200)
    p.add_argument("--min-risk-tradeoff", type=int, default=200)
    p.add_argument("--min-critical-reasoning", type=int, default=300)
    p.set_defaults(func=command_repair_coverage_gate)

    p = sub.add_parser("summarize-asset-preflight")
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--preflight-root")
    p.add_argument("--output")
    p.add_argument("--roles", nargs="*", choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.set_defaults(func=command_summarize_asset_preflight)

    p = sub.add_parser("check-resume-provenance")
    p.add_argument("--run-id", required=True)
    p.add_argument("--train-source", required=True)
    p.set_defaults(func=command_check_resume_provenance)

    p = sub.add_parser("stall-breakout")
    p.add_argument("--run-id", required=True)
    p.add_argument("--asset-class", required=True, choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", required=True, choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--train-source", required=True)
    p.add_argument("--quality-gate-exit-code", type=int, default=6)
    p.add_argument("--catalog")
    p.add_argument("--policy")
    p.add_argument("--max-sources", type=int)
    p.add_argument("--apply-quarantine", action="store_true")
    p.set_defaults(func=command_stall_breakout)

    p = sub.add_parser("train")
    p.add_argument("--run-id")
    p.add_argument("--train-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--infer-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.add_argument("--release-id")
    p.add_argument("--finetune-start-policy", default="bootstrap", choices=["bootstrap", "continue-best"])
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_train)

    p = sub.add_parser("train-preference")
    p.add_argument("--run-id", required=True)
    p.add_argument("--source-run-id", required=True)
    p.add_argument("--base-model-id", default="Qwen/Qwen3-32B")
    p.add_argument("--start-adapter")
    p.add_argument("--preference-jsonl", required=True)
    p.add_argument("--output-dir", required=True)
    p.add_argument("--max-steps", type=int, default=200)
    p.add_argument("--learning-rate", type=float, default=5e-6)
    p.add_argument("--beta", type=float, default=0.1)
    p.add_argument("--per-device-train-batch-size", type=int, default=1)
    p.add_argument("--gradient-accumulation-steps", type=int, default=8)
    p.add_argument("--max-seq-length", type=int, default=4096)
    p.add_argument("--max-prompt-length", type=int, default=1536)
    p.add_argument("--valid-ratio", type=float, default=0.1)
    p.add_argument("--logging-steps", type=int, default=5)
    p.add_argument("--eval-steps", type=int, default=25)
    p.add_argument("--save-steps", type=int, default=25)
    p.add_argument("--save-total-limit", type=int, default=3)
    p.add_argument("--overfit-tolerance", type=float, default=0.1)
    p.add_argument("--dry-run", action="store_true")
    p.set_defaults(func=command_train_preference)

    p = sub.add_parser("cycle")
    p.add_argument("--run-id", required=True)
    p.add_argument("--train-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--infer-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.add_argument("--max-cycles", type=int, default=3)
    p.add_argument("--continue-after-certified", action="store_true", help="Demo mode: keep running cycles after a candidate certifies.")
    p.set_defaults(func=command_cycle)

    p = sub.add_parser("eval")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="dev", choices=["dev", "stage", "prod"])
    p.add_argument("--task", default="finance_qa")
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.set_defaults(func=command_eval)

    p = sub.add_parser("baseline-eval")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="dev", choices=["dev", "stage", "prod"])
    p.add_argument("--task", default="finance_qa")
    p.add_argument("--model-profile")
    p.add_argument("--model-candidate")
    p.set_defaults(func=command_baseline_eval)

    p = sub.add_parser("validate-eval-suite")
    p.add_argument("--manifest", default=str(REPO_ROOT / "data" / "eval" / "linvest21_frozen_eval_v0_manifest.json"))
    p.set_defaults(func=command_validate_eval_suite)

    p = sub.add_parser("quality-gate")
    p.add_argument("--run-id", required=True)
    p.set_defaults(func=command_quality_gate)

    p = sub.add_parser("a-plus-report")
    p.add_argument("--run-id", required=True)
    p.add_argument("--source-run-id")
    p.set_defaults(func=command_a_plus_report)

    p = sub.add_parser("produce-eval-evidence")
    p.add_argument("--run-id", required=True)
    p.add_argument("--release-id", required=True)
    p.add_argument("--approve-human", action="store_true")
    p.add_argument(
        "--request-human-email",
        action="store_true",
        help="Send a human spot-check approval request and wait for approve/reject before writing the human report.",
    )
    p.add_argument(
        "--human-email-timeout-seconds",
        type=int,
        help="Override SHFT_HUMAN_REVIEW_TIMEOUT_SECONDS for --request-human-email.",
    )
    p.set_defaults(func=command_produce_eval_evidence)

    p = sub.add_parser("update-best-run")
    p.add_argument("--run-id", required=True)
    p.add_argument("--release-id", required=True)
    p.set_defaults(func=command_update_best_run)

    p = sub.add_parser("continuous-status")
    p.add_argument("--run-id", required=True)
    p.add_argument("--release-id", required=True)
    p.add_argument("--asset-class", required=True)
    p.add_argument("--role", required=True)
    p.add_argument("--round-index", type=int, default=0)
    p.add_argument("--phase", default="observe")
    p.add_argument("--enforce-convergence", action="store_true")
    p.set_defaults(func=command_continuous_status)

    p = sub.add_parser("stage-hf-dataset")
    p.add_argument("--run-id", required=True)
    p.add_argument("--dataset-dir", required=True)
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_stage_hf_dataset)

    p = sub.add_parser("stage-hf-bucket")
    p.add_argument("--run-id", required=True)
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_stage_hf_bucket)

    p = sub.add_parser("stage-hf-code")
    p.add_argument("--run-id", required=True)
    p.add_argument("--code-dir", default=str(REPO_ROOT / "impl_codex" / "self_healing_finetuning"))
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_stage_hf_code)

    p = sub.add_parser("deploy")
    p.add_argument("--run-id", required=True)
    p.add_argument("--infer-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--env", default="stage", choices=["dev", "stage", "prod"])
    p.add_argument("--model-candidate", default=DEFAULT_MODEL_ID)
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_deploy)

    p = sub.add_parser("promote")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="stage", choices=["stage", "prod"])
    p.add_argument("--engineering", default="approved")
    p.add_argument("--compliance", default="pending")
    p.add_argument("--product-owner", default="pending")
    p.add_argument("--risk-tier", default="internal_analyst", choices=["internal_dev", "internal_analyst", "regulated_internal", "external_facing"])
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_promote)

    p = sub.add_parser("rollback")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="prod", choices=["stage", "prod"])
    p.add_argument("--to", default="last_good")
    p.add_argument("--live", action="store_true")
    p.set_defaults(func=command_rollback)

    p = sub.add_parser("monitor")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="stage", choices=["stage", "prod"])
    p.add_argument("--mode", default="pass", choices=["pass", "fail"])
    p.set_defaults(func=command_monitor)

    p = sub.add_parser("lifecycle-proof")
    p.add_argument("--run-id", required=True)
    p.add_argument("--env", default="stage", choices=["stage", "prod"])
    p.add_argument("--train-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--infer-provider", default="hf_managed", choices=["hf_managed", "pod_cloud", "local_native"])
    p.add_argument("--model-candidate", default=DEFAULT_MODEL_ID)
    p.add_argument("--max-cycles", type=int, default=1)
    p.add_argument("--canary-mode", default="pass", choices=["pass", "fail"])
    p.set_defaults(func=command_lifecycle_proof)

    p = sub.add_parser("diagnose")
    p.add_argument("--error-code", default="E_EVAL_REGRESSION")
    p.set_defaults(func=command_diagnose)

    p = sub.add_parser("repair")
    p.add_argument("--run-id", required=True)
    p.add_argument("--error-code", default="E_EVAL_REGRESSION")
    p.set_defaults(func=command_repair)

    p = sub.add_parser("export-release")
    p.add_argument("--release-id", required=True)
    p.add_argument("--source-run-id", default=DEFAULT_SOURCE_RUN_ID)
    p.add_argument("--export-mode", default="adapter_only", choices=["adapter_only", "merged_hf", "quantized_gguf"])
    p.add_argument("--base-model", default="meta-llama/Meta-Llama-3-8B")
    p.add_argument("--model-id")
    p.add_argument("--asset-class", choices=["equity", "fixed_income", "multi_asset"])
    p.add_argument("--role", choices=[
        "chief_investment_officer",
        "client_portfolio_manager",
        "performance_manager",
        "portfolio_manager",
        "researcher",
        "risk_manager",
    ])
    p.add_argument("--merged-model-dir")
    p.add_argument("--gguf-model-path")
    p.add_argument("--zip", action="store_true")
    p.add_argument(
        "--allow-uncertified-export",
        action="store_true",
        help="Debug/legacy override. By default export requires a passing measured model-quality gate.",
    )
    p.set_defaults(func=command_export_release)

    p = sub.add_parser("validate-release")
    p.add_argument("--release-id", required=True)
    p.set_defaults(func=command_validate_release)

    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    return args.func(args)


if __name__ == "__main__":
    raise SystemExit(main())