scripts/submission_bundle.py

#!/usr/bin/env python3
"""Build a safe, judge-facing evidence bundle manifest for Devpost submission."""

from __future__ import annotations

import argparse
import hashlib
import json
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from zipfile import ZIP_DEFLATED, ZipFile

from proofframe.submission_gate import build_submission_gate


ROOT = Path(__file__).resolve().parents[1]
DEFAULT_JSON = ROOT / "docs" / "assets" / "submission-bundle-manifest.json"
DEFAULT_MD = ROOT / "docs" / "assets" / "submission-bundle-manifest.md"
CLOSEOUT_REPORTS = [
    {
        "id": "secret_scan_after_receipt",
        "path": "docs/assets/secret-scan-report.json",
        "schema": "proofframe.secret_scan.v1",
        "ready_fields": {"ok": True, "mode": "clear"},
    },
    {
        "id": "final_submission_control_after_receipt",
        "path": "docs/assets/final-submission-control.json",
        "schema": "proofframe.final_submission_control.v1",
        "ready_fields": {"safe_to_submit": True, "mode": "final_submit_ready"},
    },
    {
        "id": "final_closeout_status_after_receipt",
        "path": "docs/assets/final-closeout-status.json",
        "schema": "proofframe.final_closeout_status.v1",
        "ready_fields": {"ok": True, "safe_to_submit": True, "mode": "final_closeout_ready"},
    },
    {
        "id": "final_video_publish_kit_after_receipt",
        "path": "docs/assets/final-video-publish-kit.json",
        "schema": "proofframe.final_video_publish_kit.v1",
        "ready_fields": {"ok": True, "safe_to_submit": True, "mode": "public_video_ready"},
    },
    {
        "id": "final_launch_plan_after_receipt",
        "path": "docs/assets/final-launch-plan.json",
        "schema": "proofframe.final_launch_plan.v1",
        "ready_fields": {"ok": True, "mode": "submitted"},
    },
    {
        "id": "devpost_preview_after_receipt",
        "path": "docs/assets/devpost-submission-preview.json",
        "schema": "proofframe.devpost_submission_preview.v1",
        "ready_fields": {"safe_to_submit": True, "mode": "final_preview_ready"},
    },
    {
        "id": "judge_decision_brief_after_receipt",
        "path": "docs/assets/judge-decision-brief.json",
        "schema": "proofframe.judge_decision_brief.v1",
        "ready_fields": {"ok": True, "safe_to_submit": True, "mode": "final_decision_ready"},
    },
]

ARTIFACTS = [
    ("repo_readme", "README.md", "Core public project overview"),
    ("dockerfile", "Dockerfile", "Docker deployment image contract"),
    ("dockerignore", ".dockerignore", "Docker build context secret exclusion policy"),
    ("docker_smoke_script", "scripts/docker_smoke.py", "Docker build and API smoke verifier"),
    ("docker_smoke_json", "docs/assets/docker-smoke-report.json", "Machine-readable Docker smoke report"),
    ("docker_smoke_md", "docs/assets/docker-smoke-report.md", "Human-readable Docker smoke report"),
    ("prd", "docs/prd.md", "Product requirements"),
    ("technical_spec", "docs/spec.md", "Implementation specification"),
    ("deployment_runbook", "docs/deployment.md", "Public demo deployment runbook"),
    ("devpost_draft", "docs/devpost_draft.md", "Copy-ready Devpost fields"),
    ("devpost_packet_json", "docs/assets/devpost-submission-packet.json", "Machine-readable Devpost copy"),
    ("devpost_packet_md", "docs/assets/devpost-submission-packet.md", "Human-readable Devpost copy"),
    ("devpost_event_snapshot_script", "scripts/devpost_event_snapshot.py", "Official Devpost event snapshot checker"),
    ("devpost_event_snapshot_json", "docs/assets/devpost-event-snapshot.json", "Machine-readable Devpost event snapshot"),
    ("devpost_event_snapshot_md", "docs/assets/devpost-event-snapshot.md", "Human-readable Devpost event snapshot"),
    ("agent_handoff_script", "scripts/agent_handoff_check.py", "Agent Bus and Codex handoff path checker"),
    ("agent_handoff_json", "docs/assets/agent-handoff-report.json", "Machine-readable Agent handoff report"),
    ("agent_handoff_md", "docs/assets/agent-handoff-report.md", "Human-readable Agent handoff report"),
    ("public_space_sync_script", "scripts/public_space_sync.py", "Public Hugging Face Space sync verifier"),
    ("public_space_sync_json", "docs/assets/public-space-sync-report.json", "Machine-readable public Space sync report"),
    ("public_space_sync_md", "docs/assets/public-space-sync-report.md", "Human-readable public Space sync report"),
    ("public_space_upload_script", "scripts/public_space_upload.py", "No-secret public Hugging Face Space upload helper"),
    ("public_space_upload_json", "docs/assets/public-space-upload-report.json", "Machine-readable public Space upload report"),
    ("public_space_upload_md", "docs/assets/public-space-upload-report.md", "Human-readable public Space upload report"),
    ("public_demo_screenshot_script", "scripts/public_demo_screenshot.py", "Public judge-mode screenshot verifier"),
    ("public_demo_screenshot_json", "docs/assets/public-demo-screenshot-report.json", "Machine-readable public screenshot report"),
    ("public_demo_screenshot_md", "docs/assets/public-demo-screenshot-report.md", "Human-readable public screenshot report"),
    ("devpost_form_kit_script", "scripts/devpost_form_kit.py", "Field-by-field Devpost form kit"),
    ("devpost_form_kit_json", "docs/assets/devpost-form-kit.json", "Machine-readable Devpost form kit"),
    ("devpost_form_kit_md", "docs/assets/devpost-form-kit.md", "Human-readable Devpost form kit"),
    ("devpost_preview_script", "scripts/devpost_submission_preview.py", "One-page claim-safe Devpost preview"),
    ("devpost_preview_json", "docs/assets/devpost-submission-preview.json", "Machine-readable Devpost preview"),
    ("devpost_preview_md", "docs/assets/devpost-submission-preview.md", "Human-readable Devpost preview"),
    ("devpost_submission_checklist_script", "scripts/devpost_submission_checklist.py", "No-secret final Devpost web submission checklist"),
    ("devpost_submission_checklist_json", "docs/assets/devpost-submission-checklist.json", "Machine-readable final Devpost submission checklist"),
    ("devpost_submission_checklist_md", "docs/assets/devpost-submission-checklist.md", "Human-readable final Devpost submission checklist"),
    ("judge_brief_script", "scripts/judge_brief.py", "Public-safe 30-second judge brief"),
    ("judge_brief_json", "docs/assets/judge-brief.json", "Machine-readable judge brief"),
    ("judge_brief_md", "docs/assets/judge-brief.md", "Human-readable judge brief"),
    ("judge_crosswalk_script", "scripts/judge_crosswalk.py", "Official criteria to evidence crosswalk"),
    ("judge_crosswalk_json", "docs/assets/judge-crosswalk.json", "Machine-readable judge crosswalk"),
    ("judge_crosswalk_md", "docs/assets/judge-crosswalk.md", "Human-readable judge crosswalk"),
    ("judge_decision_brief_script", "scripts/judge_decision_brief.py", "Public-safe judge decision brief builder"),
    ("judge_decision_brief_json", "docs/assets/judge-decision-brief.json", "Machine-readable judge decision brief"),
    ("judge_decision_brief_md", "docs/assets/judge-decision-brief.md", "Human-readable judge decision brief"),
    ("judge_evidence_index_script", "scripts/judge_evidence_index.py", "Public-safe judge evidence index builder"),
    ("judge_evidence_index_json", "docs/assets/judge-evidence-index.json", "Machine-readable judge evidence index"),
    ("judge_evidence_index_md", "docs/assets/judge-evidence-index.md", "Human-readable judge evidence index"),
    ("frontend_ui", "apps/web/index.html", "Browser proof ledger UI"),
    ("demo_script", "docs/demo_script.md", "Video shot list and narration"),
    ("demo_storyboard_script", "scripts/demo_storyboard.py", "Machine-checked demo video storyboard"),
    ("demo_storyboard_json", "docs/assets/demo-storyboard.json", "Machine-readable demo storyboard"),
    ("demo_storyboard_md", "docs/assets/demo-storyboard.md", "Human-readable demo storyboard"),
    ("demo_video_draft_script", "scripts/demo_video_draft.py", "Mock demo video draft builder"),
    ("demo_video_draft_json", "docs/assets/demo-video-draft.json", "Machine-readable demo video draft report"),
    ("demo_video_draft_md", "docs/assets/demo-video-draft.md", "Human-readable demo video draft report"),
    ("demo_video_draft_mp4", "docs/assets/proofframe-demo-draft.mp4", "Public-safe mock demo video draft"),
    ("final_video_publish_kit_script", "scripts/final_video_publish_kit.py", "Final public video upload copy and gate kit"),
    ("final_video_publish_kit_json", "docs/assets/final-video-publish-kit.json", "Machine-readable final video publish kit"),
    ("final_video_publish_kit_md", "docs/assets/final-video-publish-kit.md", "Human-readable final video publish kit"),
    ("public_video_check_script", "scripts/public_video_check.py", "Public demo video URL verifier"),
    ("public_video_check_json", "docs/assets/public-video-check.json", "Machine-readable public video check"),
    ("public_video_check_md", "docs/assets/public-video-check.md", "Human-readable public video check"),
    ("sponsor_fit_matrix", "docs/sponsor_fit_matrix.md", "Sponsor judging matrix and claim boundary"),
    ("sponsor_fit_audit_script", "scripts/sponsor_fit_audit.py", "Sponsor-fit clarity audit"),
    ("sponsor_fit_audit_json", "docs/assets/sponsor-fit-audit.json", "Machine-readable sponsor-fit audit"),
    ("sponsor_fit_audit_md", "docs/assets/sponsor-fit-audit.md", "Human-readable sponsor-fit audit"),
    ("award_readiness_script", "scripts/award_readiness.py", "Judge-facing award readiness scorecard"),
    ("award_readiness_json", "docs/assets/award-readiness-report.json", "Machine-readable award readiness report"),
    ("award_readiness_md", "docs/assets/award-readiness-report.md", "Human-readable award readiness report"),
    ("final_submission_control_script", "scripts/final_submission_control.py", "Final submission control tower"),
    ("final_submission_control_json", "docs/assets/final-submission-control.json", "Machine-readable final control report"),
    ("final_submission_control_md", "docs/assets/final-submission-control.md", "Human-readable final control report"),
    ("final_closeout_status_script", "scripts/final_closeout_status.py", "No-secret final closeout status report"),
    ("final_closeout_status_json", "docs/assets/final-closeout-status.json", "Machine-readable final closeout status"),
    ("final_closeout_status_md", "docs/assets/final-closeout-status.md", "Human-readable final closeout status"),
    ("final_operator_brief_script", "scripts/final_operator_brief.py", "No-secret final operator brief"),
    ("final_operator_brief_json", "docs/assets/final-operator-brief.json", "Machine-readable final operator brief"),
    ("final_operator_brief_md", "docs/assets/final-operator-brief.md", "Human-readable final operator brief"),
    ("final_launch_plan_script", "scripts/final_launch_plan.py", "No-secret final launch phase plan"),
    ("final_launch_plan_json", "docs/assets/final-launch-plan.json", "Machine-readable final launch plan"),
    ("final_launch_plan_md", "docs/assets/final-launch-plan.md", "Human-readable final launch plan"),
    ("final_rehearsal_script", "scripts/final_rehearsal.py", "No-secret final submission rehearsal checklist"),
    ("final_rehearsal_json", "docs/assets/final-rehearsal-checklist.json", "Machine-readable final rehearsal checklist"),
    ("final_rehearsal_md", "docs/assets/final-rehearsal-checklist.md", "Human-readable final rehearsal checklist"),
    ("submission_audit_script", "scripts/submission_audit.py", "Pre-submit audit gate"),
    ("submission_audit_json", "docs/assets/submission-audit-report.json", "Machine-readable submission audit report"),
    ("submission_audit_md", "docs/assets/submission-audit-report.md", "Human-readable submission audit report"),
    ("devpost_receipt_script", "scripts/devpost_submission_receipt.py", "Public-safe Devpost submission receipt generator"),
    ("devpost_receipt_json", "docs/assets/devpost-submission-receipt.json", "Machine-readable Devpost submission receipt"),
    ("devpost_receipt_md", "docs/assets/devpost-submission-receipt.md", "Human-readable Devpost submission receipt"),
    ("evidence_package", "docs/evidence_package.md", "Evidence package plan"),
    ("public_claim_freeze", "docs/public_claim_freeze.md", "Verified-claim boundary"),
    ("verification_runbook", "docs/verification.md", "Local, CI, Docker, and live proof runbook"),
    ("final_env_template", ".env.final.example", "Redacted final B2 plus Genblaze env template"),
    ("secret_scan_script", "scripts/secret_scan.py", "Final secret scanner"),
    ("secret_scan_json", "docs/assets/secret-scan-report.json", "Machine-readable secret scan report"),
    ("secret_scan_md", "docs/assets/secret-scan-report.md", "Human-readable secret scan report"),
    ("b2_live_setup_json", "docs/assets/b2-live-setup.json", "Non-secret B2 bucket setup record"),
    ("b2_live_setup_md", "docs/assets/b2-live-setup.md", "Human-readable B2 bucket setup record"),
    ("b2_key_scope_checklist_script", "scripts/b2_key_scope_checklist.py", "No-secret Backblaze B2 application key scope checklist"),
    ("b2_key_scope_checklist_json", "docs/assets/b2-key-scope-checklist.json", "Machine-readable B2 key scope checklist"),
    ("b2_key_scope_checklist_md", "docs/assets/b2-key-scope-checklist.md", "Human-readable B2 key scope checklist"),
    ("genblaze_contract_script", "scripts/genblaze_contract_check.py", "No-secret Genblaze/B2 SDK contract checker"),
    ("genblaze_contract_json", "docs/assets/genblaze-contract-report.json", "Machine-readable Genblaze SDK contract report"),
    ("genblaze_contract_md", "docs/assets/genblaze-contract-report.md", "Human-readable Genblaze SDK contract report"),
    ("b2_live_runner", "scripts/run_b2_live_proof.py", "One-command B2 storage proof runner"),
    ("live_env_handoff_script", "scripts/live_env_handoff.py", "Redacted live credential handoff gate"),
    ("live_env_handoff_json", "docs/assets/live-credential-handoff.json", "Machine-readable live credential handoff"),
    ("live_env_handoff_md", "docs/assets/live-credential-handoff.md", "Human-readable live credential handoff"),
    ("final_env_wizard", "scripts/final_env_wizard.py", "Local final credential env wizard"),
    ("post_credential_live_proof_script", "scripts/post_credential_live_proof.py", "Post-credential live proof sequence runner"),
    ("post_credential_live_proof_json", "docs/assets/post-credential-live-proof-plan.json", "Machine-readable post-credential live proof plan"),
    ("post_credential_live_proof_md", "docs/assets/post-credential-live-proof-plan.md", "Human-readable post-credential live proof plan"),
    ("public_claim_lint", "scripts/claim_lint.py", "Fail-closed public claim lint"),
    ("demo_readiness_script", "scripts/demo_readiness.py", "Demo recording readiness gate"),
    ("demo_readiness_json", "docs/assets/demo-readiness-report.json", "Machine-readable demo readiness report"),
    ("demo_readiness_md", "docs/assets/demo-readiness-report.md", "Human-readable demo readiness report"),
    ("recording_assets_script", "scripts/recording_assets.py", "Public-safe recording asset gate"),
    ("recording_assets_json", "docs/assets/recording-assets.json", "Machine-readable recording asset report"),
    ("recording_assets_md", "docs/assets/recording-assets.md", "Human-readable recording asset report"),
    ("final_live_runner", "scripts/run_final_live_proof.py", "One-command final B2 plus Genblaze proof runner"),
    ("submission_plan", "docs/submission.md", "Registration and submission plan"),
    ("task_ledger", "tasks.json", "Machine-readable task board"),
    ("local_ui_smoke", "docs/assets/proofframe-local-ui-smoke.png", "Local UI screenshot"),
    ("review_console_smoke", "docs/assets/proofframe-review-console-smoke.png", "Review console screenshot"),
    ("public_hf_smoke", "docs/assets/proofframe-hf-public-smoke.png", "Public mock demo screenshot"),
]


def utc_now() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def load_json(path: Path) -> dict[str, Any] | None:
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (FileNotFoundError, json.JSONDecodeError):
        return None
    return data if isinstance(data, dict) else None


def parse_utc(value: Any) -> datetime | None:
    if not isinstance(value, str) or not value.strip():
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    if parsed.tzinfo is None:
        return None
    return parsed.astimezone(timezone.utc)


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def artifact_record(root: Path, artifact_id: str, relative_path: str, label: str) -> dict[str, Any]:
    path = root / relative_path
    record: dict[str, Any] = {
        "id": artifact_id,
        "path": relative_path,
        "label": label,
        "present": path.exists(),
    }
    if path.exists():
        record.update({"bytes": path.stat().st_size, "sha256": sha256_file(path)})
    return record


def load_packet_summary(root: Path) -> dict[str, Any]:
    packet_path = root / "docs" / "assets" / "devpost-submission-packet.json"
    packet = load_json(packet_path)
    if packet is None:
        return {"present": False, "mode": None, "claim_warning": "Devpost packet missing."}
    return {
        "present": True,
        "mode": packet.get("mode"),
        "project_name": packet.get("project_name"),
        "tagline": packet.get("tagline"),
        "repository_url": packet.get("repository_url"),
        "demo_url": packet.get("demo_url"),
        "claim_warning": packet.get("claim_warning"),
    }


def closeout_report_record(root: Path, spec: dict[str, Any], receipt_created_at: datetime | None) -> dict[str, Any]:
    data = load_json(root / spec["path"])
    record: dict[str, Any] = {
        "id": spec["id"],
        "path": spec["path"],
        "present": data is not None,
        "schema": data.get("schema") if data else None,
        "schema_ok": bool(data and data.get("schema") == spec["schema"]),
        "created_at": data.get("created_at") if data else None,
        "ready": False,
        "fresh_after_receipt": False,
        "findings": [],
    }
    if data is None:
        record["findings"].append("Report is missing or invalid JSON.")
        return record
    for key, expected in spec["ready_fields"].items():
        actual = data.get(key)
        if actual != expected:
            record["findings"].append(f"Expected {key}={expected!r}, got {actual!r}.")
    report_created_at = parse_utc(data.get("created_at"))
    if report_created_at is None:
        record["findings"].append("created_at is missing or invalid.")
    elif receipt_created_at is None:
        record["findings"].append("Receipt created_at is missing or invalid.")
    else:
        record["fresh_after_receipt"] = report_created_at >= receipt_created_at
        if not record["fresh_after_receipt"]:
            record["findings"].append("Report was generated before the Devpost receipt.")
    record["ready"] = bool(record["schema_ok"] and not record["findings"])
    return record


def build_closeout_gate(root: Path) -> dict[str, Any]:
    receipt_path = "docs/assets/devpost-submission-receipt.json"
    receipt = load_json(root / receipt_path)
    receipt_created_at = parse_utc(receipt.get("created_at") if receipt else None)
    receipt_record = {
        "path": receipt_path,
        "present": receipt is not None,
        "schema": receipt.get("schema") if receipt else None,
        "schema_ok": bool(receipt and receipt.get("schema") == "proofframe.devpost_submission_receipt.v1"),
        "ok": receipt.get("ok") if receipt else None,
        "mode": receipt.get("mode") if receipt else None,
        "created_at": receipt.get("created_at") if receipt else None,
    }
    reports = [closeout_report_record(root, spec, receipt_created_at) for spec in CLOSEOUT_REPORTS]
    receipt_ok = bool(
        receipt_record["present"]
        and receipt_record["schema_ok"]
        and receipt_record["ok"] is True
        and receipt_record["mode"] == "submitted"
        and receipt_created_at is not None
    )
    return {
        "ok": bool(receipt_ok and all(report["ready"] for report in reports)),
        "status": "verified" if receipt_ok and all(report["ready"] for report in reports) else "incomplete",
        "receipt": receipt_record,
        "reports": reports,
    }


def build_manifest(root: Path = ROOT) -> dict[str, Any]:
    root = root.resolve()
    artifacts = [artifact_record(root, *artifact) for artifact in ARTIFACTS]
    missing = [artifact for artifact in artifacts if not artifact["present"]]
    gate = build_submission_gate(root)
    closeout_gate = build_closeout_gate(root)
    return {
        "schema": "proofframe.submission_bundle.v1",
        "created_at": utc_now(),
        "project": "ProofFrame",
        "repository_url": "https://github.com/adjcjh777/backblaze-proofframe",
        "public_demo_url": "https://adjcjh-backblaze-proofframe.hf.space/?judge=1",
        "safe_to_share": not missing,
        "safe_to_submit": bool(gate["ok"] and closeout_gate["ok"]),
        "devpost_packet": load_packet_summary(root),
        "submission_gate": {
            "ok": gate["ok"],
            "mode": gate["mode"],
            "summary": gate["summary"],
            "packet_gate": gate["packet_gate"],
            "evidence_gate": gate["evidence_gate"],
            "report_gate": gate["report_gate"],
            "next_actions": gate["next_actions"],
        },
        "closeout_gate": closeout_gate,
        "artifacts": artifacts,
        "missing_artifacts": [artifact["path"] for artifact in missing],
    }


def render_markdown(manifest: dict[str, Any]) -> str:
    gate = manifest["submission_gate"]
    packet = manifest["devpost_packet"]
    lines = [
        "# ProofFrame Submission Bundle",
        "",
        f"Created: `{manifest['created_at']}`",
        f"Repository: {manifest['repository_url']}",
        f"Public mock demo: {manifest['public_demo_url']}",
        f"Devpost packet mode: `{packet.get('mode')}`",
        f"Final gate mode: `{gate['mode']}`",
        f"Final gate ready: `{str(gate['ok']).lower()}`",
        "",
        "## Current Gate",
        "",
        (
            f"- Tasks: {gate['summary']['done']} done / {gate['summary']['required']} required; "
            f"{gate['summary']['doing']} doing, {gate['summary']['blocked']} blocked, "
            f"{gate['summary']['todo']} todo."
        ),
        f"- Live evidence: `{gate['evidence_gate']['status']}`",
        f"- Devpost copy packet: `{gate['packet_gate']['status']}`",
        f"- Final reports: `{gate['report_gate']['status']}`",
        f"- Post-Devpost closeout: `{manifest['closeout_gate']['status']}`",
        "",
        "## Next Actions",
        "",
    ]
    if gate["next_actions"]:
        lines.extend(f"- {action}" for action in gate["next_actions"])
    else:
        lines.append("- Ready for final Devpost submit.")

    lines.extend(["", "## Artifacts", ""])
    for artifact in manifest["artifacts"]:
        if artifact["present"]:
            lines.append(
                f"- `{artifact['path']}` ({artifact['bytes']} bytes, sha256 `{artifact['sha256'][:16]}...`) - {artifact['label']}"
            )
        else:
            lines.append(f"- MISSING `{artifact['path']}` - {artifact['label']}")
    lines.append("")
    lines.append("No credentials, browser cookies, signed URLs, or raw provider keys are included.")
    return "\n".join(lines) + "\n"


def write_outputs(
    manifest: dict[str, Any],
    *,
    json_path: Path = DEFAULT_JSON,
    markdown_path: Path = DEFAULT_MD,
    zip_path: Path | None = None,
    root: Path = ROOT,
) -> None:
    json_path.parent.mkdir(parents=True, exist_ok=True)
    markdown_path.parent.mkdir(parents=True, exist_ok=True)
    json_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
    markdown_path.write_text(render_markdown(manifest), encoding="utf-8")
    if zip_path:
        zip_path.parent.mkdir(parents=True, exist_ok=True)
        with ZipFile(zip_path, "w", ZIP_DEFLATED) as archive:
            archive.writestr("submission-bundle-manifest.json", json.dumps(manifest, indent=2) + "\n")
            archive.writestr("submission-bundle-manifest.md", render_markdown(manifest))
            for artifact in manifest["artifacts"]:
                if artifact["present"]:
                    archive.write(root / artifact["path"], artifact["path"])


def cli_summary(manifest: dict[str, Any], args: argparse.Namespace) -> dict[str, Any]:
    return {
        "ok": manifest["safe_to_submit"],
        "mode": manifest["submission_gate"]["mode"],
        "safe_to_share": manifest["safe_to_share"],
        "safe_to_submit": manifest["safe_to_submit"],
        "json": str(args.json_out),
        "markdown": str(args.markdown_out),
        "zip": str(args.zip_out) if args.zip_out else None,
        "missing_artifacts": manifest["missing_artifacts"],
    }


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Build a safe ProofFrame submission bundle manifest.")
    parser.add_argument("--json-out", type=Path, default=DEFAULT_JSON)
    parser.add_argument("--markdown-out", type=Path, default=DEFAULT_MD)
    parser.add_argument("--zip-out", type=Path, help="Optionally write a zip with public artifacts.")
    parser.add_argument("--strict-final", action="store_true", help="Fail unless the final submission gate is ready.")
    return parser


def main() -> None:
    args = build_parser().parse_args()
    manifest = build_manifest(ROOT)
    write_outputs(
        manifest,
        json_path=args.json_out,
        markdown_path=args.markdown_out,
        zip_path=args.zip_out,
        root=ROOT,
    )
    print(json.dumps(cli_summary(manifest, args), indent=2))
    if args.strict_final and not manifest["safe_to_submit"]:
        raise SystemExit(2)


if __name__ == "__main__":
    main()