@optima-chat/optima-agent 0.8.91 → 0.8.93

package/.claude/skills/video-clone/scripts/_gate.py

@@ -0,0 +1,162 @@
+"""Phase-state machine for the video-clone skill.
+
+Every executable script that spends money or writes durable artifacts calls
+`require_gate()` at startup. If the required gate is not yet confirmed, the
+script exits with code 1 and prints a [HARD-GATE BLOCKED] message describing
+exactly how to unblock it.
+
+State lives in `<project_dir>/.state/phase.json` (one file per project).
+The schema is defined in `assets/phase-state-template.json`.
+
+This module is stdlib-only. Import it from sibling scripts with:
+
+    from _gate import require_gate
+    require_gate(project_dir, "preview_confirmed")
+
+Gates (single):
+    preview_confirmed — user reviewed the preview bundle and confirmed
+                        they want video generation to proceed.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+GATE_NAMES = ("preview_confirmed",)
+STATE_REL = Path(".state") / "phase.json"
+
+
+def _state_path(project_dir: Path | str) -> Path:
+    return Path(project_dir) / STATE_REL
+
+
+def load_state(project_dir: Path | str) -> dict:
+    """Read and parse .state/phase.json for the given project directory."""
+    path = _state_path(project_dir)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"No phase state at {path}. Run init_project.py first."
+        )
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_state(project_dir: Path | str, state: dict) -> None:
+    """Atomically overwrite .state/phase.json."""
+    path = _state_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")
+    tmp.replace(path)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def append_history(state: dict, event: str, **extra) -> None:
+    entry = {"event": event, "at": _now_iso()}
+    entry.update(extra)
+    state.setdefault("history", []).append(entry)
+
+
+def set_gate(
+    project_dir: Path | str,
+    gate_name: str,
+    user_quote: str,
+    *,
+    caller: str,
+) -> None:
+    """Flip a gate from false → true and log the user's confirmation quote.
+
+    Raises ValueError if gate_name is unknown, user_quote is empty, or
+    caller is empty/whitespace. caller is keyword-only and required so
+    bypassing _confirm.run_confirm() either fails or leaves a visible
+    `caller` field in history[].
+    """
+    if gate_name not in GATE_NAMES:
+        raise ValueError(
+            f"unknown gate: {gate_name!r}. valid: {', '.join(GATE_NAMES)}"
+        )
+    if not user_quote or not user_quote.strip():
+        raise ValueError("user_quote is required and must be non-empty")
+    if not caller or not caller.strip():
+        raise ValueError("caller is required and must be non-empty")
+
+    state = load_state(project_dir)
+    if gate_name not in state.get("gates", {}):
+        raise KeyError(
+            f"gate {gate_name!r} not found in state — likely an old "
+            f"3-gate schema. Either complete this project with the "
+            f"previous version of the scripts (PR #65), or start a new "
+            f"project with init_project.py."
+        )
+    now = _now_iso()
+    state["gates"][gate_name] = {
+        "status": True,
+        "confirmed_at": now,
+        "user_quote": user_quote,
+    }
+    append_history(state, gate_name, user_quote=user_quote, caller=caller)
+    save_state(project_dir, state)
+
+
+def require_gate(project_dir: Path | str, gate_name: str) -> None:
+    """Assert the given gate is confirmed. Exits with code 1 on failure.
+
+    This is the mechanical HARD-GATE enforcement. Do not catch SystemExit
+    to "handle" the failure — the entire point is that Claude cannot
+    bypass it.
+    """
+    if gate_name not in GATE_NAMES:
+        _fail(
+            f"require_gate called with unknown gate {gate_name!r}. "
+            f"valid: {', '.join(GATE_NAMES)}"
+        )
+
+    try:
+        state = load_state(project_dir)
+    except FileNotFoundError as e:
+        _fail(str(e))
+
+    gates = state.get("gates", {})
+    if gate_name not in gates:
+        _fail(
+            f"\n[HARD-GATE BLOCKED] {Path(sys.argv[0]).name} expected "
+            f"gate {gate_name!r} but it is not present in {project_dir}/"
+            f".state/phase.json.\n"
+            f"This is most likely an old 3-gate schema project. Either:\n"
+            f"  1. Complete this project with the previous version of "
+            f"the scripts (PR #65), or\n"
+            f"  2. Start a new project with: "
+            f"python scripts/init_project.py --name <new-name> "
+            f"--task-type <video_clone|video_gen>\n"
+        )
+
+    gate = gates.get(gate_name, {})
+    if gate.get("status") is True:
+        return  # gate satisfied, continue
+
+    script_name = Path(sys.argv[0]).name if sys.argv and sys.argv[0] else "<script>"
+    msg = (
+        f"\n[HARD-GATE BLOCKED] {script_name} needs {gate_name}=True\n"
+        f"Current state: {gate_name}={gate.get('status', False)}\n"
+        f"Project: {Path(project_dir).resolve()}\n"
+        f"\n"
+        f"To proceed:\n"
+        f"  1. Show the preview bundle to the user and wait for their confirmation.\n"
+        f"  2. Run: python scripts/confirm.py "
+        f"--project <name> --quote \"<user's actual words>\"\n"
+        f"  3. Retry this command.\n"
+        f"\n"
+        f"Claude: do NOT rationalize past this. The gate exists because "
+        f"text instructions alone did not stop prior bypass attempts. "
+        f"Go get the real user confirmation.\n"
+    )
+    _fail(msg)
+
+
+def _fail(message: str) -> None:
+    print(message, file=sys.stderr)
+    sys.exit(1)

package/.claude/skills/video-clone/scripts/_gate_e2e_test.py

@@ -0,0 +1,226 @@
+"""E2E gate-enforcement tests for single-gate model.
+
+7 cases:
+  1. analyze_source.py runs WITHOUT gate (no gate requirement)
+  2. extract_frames.py runs WITHOUT gate (no gate requirement)
+  3. edit_first_frame.py runs WITHOUT gate (no gate requirement)
+  4. kling_generate.py is BLOCKED by missing preview_confirmed gate
+  5. gen_video.py is BLOCKED by missing preview_confirmed gate
+  6. save_workflow.py is BLOCKED by missing preview_confirmed gate
+  7. Old 3-gate schema is REJECTED by require_gate with informative message
+
+Run: python scripts/_gate_e2e_test.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).parent
+
+
+def _make_project(tmp: Path, gate: bool = False,
+                  old_schema: bool = False) -> Path:
+    proj = tmp / "video-clone" / "e2e-proj"
+    for sub in ("source", "frames", "videos", ".state"):
+        (proj / sub).mkdir(parents=True)
+
+    if old_schema:
+        state = {
+            "schema_version": 0,
+            "project": "e2e-proj",
+            "task_type": "video_clone",
+            "created_at": "2025-01-01T00:00:00Z",
+            "current_phase": 0,
+            "gates": {
+                "plan_confirmed":   {"status": True, "confirmed_at": "x", "user_quote": "y"},
+                "prompt_confirmed": {"status": True, "confirmed_at": "x", "user_quote": "y"},
+                "frame_confirmed":  {"status": True, "confirmed_at": "x", "user_quote": "y"},
+            },
+            "history": [],
+        }
+    else:
+        state = {
+            "schema_version": 1,
+            "project": "e2e-proj",
+            "task_type": "video_clone",
+            "created_at": "2025-01-01T00:00:00Z",
+            "current_phase": 0,
+            "gates": {
+                "preview_confirmed": {
+                    "status": gate,
+                    "confirmed_at": "2025-01-01T00:01:00Z" if gate else None,
+                    "user_quote": "go" if gate else None,
+                }
+            },
+            "history": [],
+        }
+    (proj / ".state" / "phase.json").write_text(
+        json.dumps(state, indent=2), encoding="utf-8"
+    )
+    return proj
+
+
+def _run(tmp: Path, script: str, extra: list[str] | None = None,
+         extra_env: dict | None = None) -> subprocess.CompletedProcess:
+    env = os.environ.copy()
+    env["GEN_OUTPUT_ROOT"] = str(tmp)
+    if extra_env:
+        env.update(extra_env)
+    cmd = [sys.executable, str(SCRIPTS_DIR / script),
+           "--project", "e2e-proj"]
+    if extra:
+        cmd += extra
+    return subprocess.run(cmd, capture_output=True, text=True, env=env)
+
+
+# ------------------------------------------------------------------
+# Case 1: analyze_source.py runs without gate
+# ------------------------------------------------------------------
+def test_analyze_source_runs_without_gate():
+    """analyze_source.py must not call require_gate; a missing source file
+    is the expected failure (not a gate block)."""
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "analyze_source.py", ["--source", "nonexistent.mp4"])
+        assert "HARD-GATE BLOCKED" not in result.stderr, (
+            f"analyze_source must not gate-block. stderr: {result.stderr}"
+        )
+        assert result.returncode != 0  # fails due to missing file, not gate
+    print("PASS test_analyze_source_runs_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 2: extract_frames.py runs without gate
+# ------------------------------------------------------------------
+def test_extract_frames_runs_without_gate():
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "extract_frames.py", ["--source", "nonexistent.mp4"])
+        assert "HARD-GATE BLOCKED" not in result.stderr, (
+            f"extract_frames must not gate-block. stderr: {result.stderr}"
+        )
+    print("PASS test_extract_frames_runs_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 3: edit_first_frame.py runs without gate
+# ------------------------------------------------------------------
+def test_edit_first_frame_runs_without_gate():
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "edit_first_frame.py", ["--image", "nonexistent.png"])
+        assert "HARD-GATE BLOCKED" not in result.stderr, (
+            f"edit_first_frame must not gate-block. stderr: {result.stderr}"
+        )
+    print("PASS test_edit_first_frame_runs_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 4: kling_generate.py is BLOCKED without preview_confirmed
+# ------------------------------------------------------------------
+def test_kling_generate_blocked_without_gate():
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "kling_generate.py",
+                      ["--frame", "frames/frame_v1.png"],
+                      extra_env={"PIAPI_KEY": "dummy"})
+        assert result.returncode == 1, (
+            f"Expected exit 1\nstdout: {result.stdout}\nstderr: {result.stderr}"
+        )
+        assert "HARD-GATE BLOCKED" in result.stderr, (
+            f"Expected HARD-GATE BLOCKED in stderr:\n{result.stderr}"
+        )
+    print("PASS test_kling_generate_blocked_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 5: gen_video.py is BLOCKED without preview_confirmed
+# ------------------------------------------------------------------
+def test_gen_video_blocked_without_gate():
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "gen_video.py", ["--frame", "frames/frame_v1.png"])
+        assert result.returncode == 1, (
+            f"Expected exit 1\nstdout: {result.stdout}\nstderr: {result.stderr}"
+        )
+        assert "HARD-GATE BLOCKED" in result.stderr, (
+            f"Expected HARD-GATE BLOCKED in stderr:\n{result.stderr}"
+        )
+    print("PASS test_gen_video_blocked_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 6: save_workflow.py is BLOCKED without preview_confirmed
+# ------------------------------------------------------------------
+def test_save_workflow_blocked_without_gate():
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, gate=False)
+        result = _run(tmp, "save_workflow.py",
+                      ["--name", "wf1", "--scene", "test",
+                       "--rating", "3", "--strategy", "test strat"])
+        assert result.returncode == 1, (
+            f"Expected exit 1\nstdout: {result.stdout}\nstderr: {result.stderr}"
+        )
+        assert "HARD-GATE BLOCKED" in result.stderr, (
+            f"Expected HARD-GATE BLOCKED in stderr:\n{result.stderr}"
+        )
+    print("PASS test_save_workflow_blocked_without_gate")
+
+
+# ------------------------------------------------------------------
+# Case 7: Old 3-gate schema is REJECTED with informative message
+# ------------------------------------------------------------------
+def test_old_3gate_schema_rejected_at_gate_check():
+    """When any gated script encounters an old 3-gate schema, require_gate
+    must exit 1 with a message mentioning the old schema."""
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td)
+        _make_project(tmp, old_schema=True)
+        result = _run(tmp, "kling_generate.py",
+                      ["--frame", "frames/frame_v1.png"],
+                      extra_env={"PIAPI_KEY": "dummy"})
+        assert result.returncode == 1
+        stderr = result.stderr
+        assert any(kw in stderr for kw in (
+            "old 3-gate", "schema", "plan_confirmed", "HARD-GATE BLOCKED"
+        )), f"Expected old-schema rejection message in stderr:\n{stderr}"
+    print("PASS test_old_3gate_schema_rejected_at_gate_check")
+
+
+TESTS = [
+    ("analyze_source runs without gate", test_analyze_source_runs_without_gate),
+    ("extract_frames runs without gate", test_extract_frames_runs_without_gate),
+    ("edit_first_frame runs without gate", test_edit_first_frame_runs_without_gate),
+    ("kling_generate blocked without gate", test_kling_generate_blocked_without_gate),
+    ("gen_video blocked without gate", test_gen_video_blocked_without_gate),
+    ("save_workflow blocked without gate", test_save_workflow_blocked_without_gate),
+    ("old 3-gate schema rejected", test_old_3gate_schema_rejected_at_gate_check),
+]
+
+
+def main() -> int:
+    failed = 0
+    for name, fn in TESTS:
+        try:
+            fn()
+            print(f"PASS  {name}")
+        except Exception as e:
+            failed += 1
+            print(f"FAIL  {name}: {type(e).__name__}: {e}")
+    print(f"\n{len(TESTS) - failed}/{len(TESTS)} passed")
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/skills/video-clone/scripts/_gate_test.py

@@ -0,0 +1,148 @@
+"""Unit tests for _gate.py — single-gate model + caller audit + old-schema rejection."""
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+# Add scripts dir to path so we can import _gate directly.
+SCRIPTS_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import _gate  # noqa: E402
+
+TEMPLATE = json.loads(
+    (SCRIPTS_DIR.parent / "assets" / "phase-state-template.json").read_text(encoding="utf-8")
+)
+
+
+def _fresh_project(tmp: Path, name: str = "p1") -> Path:
+    p = tmp / name
+    (p / ".state").mkdir(parents=True)
+    state = json.loads(json.dumps(TEMPLATE))  # deep copy
+    state["project"] = name
+    state["task_type"] = "video_clone"
+    (p / ".state" / "phase.json").write_text(json.dumps(state), encoding="utf-8")
+    return p
+
+
+def test_set_gate_writes_caller_to_history():
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        _gate.set_gate(p, "preview_confirmed", "OK 开始", caller="confirm.py")
+        state = _gate.load_state(p)
+        history = state["history"]
+        assert len(history) == 1
+        assert history[0]["event"] == "preview_confirmed"
+        assert history[0]["caller"] == "confirm.py"
+        assert history[0]["user_quote"] == "OK 开始"
+        assert state["gates"]["preview_confirmed"]["status"] is True
+    print("PASS test_set_gate_writes_caller_to_history")
+
+
+def test_set_gate_missing_caller_raises_typeerror():
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        try:
+            _gate.set_gate(p, "preview_confirmed", "OK")  # type: ignore[call-arg]
+        except TypeError:
+            print("PASS test_set_gate_missing_caller_raises_typeerror")
+            return
+        raise AssertionError("expected TypeError")
+
+
+def test_set_gate_empty_caller_raises_valueerror():
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        try:
+            _gate.set_gate(p, "preview_confirmed", "OK", caller="   ")
+        except ValueError:
+            print("PASS test_set_gate_empty_caller_raises_valueerror")
+            return
+        raise AssertionError("expected ValueError")
+
+
+def test_set_gate_records_literal_caller_value():
+    """Bypass via 'caller=ad-hoc' is allowed but leaves visible evidence."""
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        _gate.set_gate(p, "preview_confirmed", "ok", caller="ad-hoc")
+        history = _gate.load_state(p)["history"]
+        assert history[0]["caller"] == "ad-hoc"
+    print("PASS test_set_gate_records_literal_caller_value")
+
+
+def test_require_gate_unset_exits_one():
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        try:
+            _gate.require_gate(p, "preview_confirmed")
+        except SystemExit as e:
+            assert e.code == 1
+            print("PASS test_require_gate_unset_exits_one")
+            return
+        raise AssertionError("expected SystemExit(1)")
+
+
+def test_require_gate_set_returns_none():
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        _gate.set_gate(p, "preview_confirmed", "ok", caller="confirm.py")
+        assert _gate.require_gate(p, "preview_confirmed") is None
+    print("PASS test_require_gate_set_returns_none")
+
+
+def test_old_3gate_schema_rejected():
+    """An old PR #65 phase.json should be rejected, not silently mishandled."""
+    with tempfile.TemporaryDirectory() as td:
+        p = Path(td) / "old"
+        (p / ".state").mkdir(parents=True)
+        old_state = {
+            "schema_version": 1,
+            "project": "old",
+            "task_type": "video_clone",
+            "created_at": "2026-01-01T00:00:00Z",
+            "current_phase": 0,
+            "gates": {
+                "plan_confirmed":   {"status": False, "confirmed_at": None, "user_quote": None},
+                "prompt_confirmed": {"status": False, "confirmed_at": None, "user_quote": None},
+                "frame_confirmed":  {"status": False, "confirmed_at": None, "user_quote": None},
+            },
+            "history": [],
+        }
+        (p / ".state" / "phase.json").write_text(json.dumps(old_state), encoding="utf-8")
+        try:
+            _gate.require_gate(p, "preview_confirmed")
+        except SystemExit as e:
+            assert e.code == 1
+            print("PASS test_old_3gate_schema_rejected")
+            return
+        raise AssertionError("expected SystemExit(1)")
+
+
+def test_save_state_atomic():
+    """Verify save_state writes via tmp+replace (no partial-write race)."""
+    with tempfile.TemporaryDirectory() as td:
+        p = _fresh_project(Path(td))
+        state = _gate.load_state(p)
+        state["project"] = "renamed"
+        _gate.save_state(p, state)
+        # Verify no orphan .json.tmp file
+        tmp = (p / ".state" / "phase.json.tmp")
+        assert not tmp.exists()
+        # Verify the new value persisted
+        assert _gate.load_state(p)["project"] == "renamed"
+    print("PASS test_save_state_atomic")
+
+
+if __name__ == "__main__":
+    test_set_gate_writes_caller_to_history()
+    test_set_gate_missing_caller_raises_typeerror()
+    test_set_gate_empty_caller_raises_valueerror()
+    test_set_gate_records_literal_caller_value()
+    test_require_gate_unset_exits_one()
+    test_require_gate_set_returns_none()
+    test_old_3gate_schema_rejected()
+    test_save_state_atomic()
+    print("\nAll 8 _gate tests passed.")

package/.claude/skills/video-clone/scripts/_project.py

@@ -0,0 +1,56 @@
+"""Tiny helper to resolve a project directory under gen-output/video-clone/.
+
+Used by all executor scripts so they share the same GEN_OUTPUT_ROOT convention.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def gen_output_root() -> Path:
+    override = os.environ.get("GEN_OUTPUT_ROOT")
+    if override:
+        return Path(override)
+    return Path.cwd() / "gen-output"
+
+
+def resolve_project(name: str) -> Path:
+    path = gen_output_root() / "video-clone" / name
+    if not path.is_dir():
+        print(
+            f"ERROR: project directory not found at {path}\n"
+            f"Run: python scripts/init_project.py --name {name} --task-type video_clone",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return path
+
+
+def next_version(dir_path: Path, prefix: str, suffix: str) -> Path:
+    """Return dir_path / f'{prefix}v{N}{suffix}' with N = highest existing + 1.
+
+    Example: next_version(frames_dir, 'frame_', '.png') →
+             frames_dir/frame_v3.png  (if v1, v2 already exist)
+    """
+    n = 1
+    while (dir_path / f"{prefix}v{n}{suffix}").exists():
+        n += 1
+    return dir_path / f"{prefix}v{n}{suffix}"
+
+
+def append_log(project_dir: Path, event: str) -> None:
+    """Append one human-readable event line to <project_dir>/log.md.
+
+    Format: 'HH:MM:SS  <event>'. Used by status.py to render the History
+    section. This is the human-readable ledger; phase.json:history[] is the
+    machine-significance audit ledger and stays gate-events-only.
+    """
+    from datetime import datetime, timezone
+    log = project_dir / "log.md"
+    line = f"{datetime.now(timezone.utc).strftime('%H:%M:%S')}  {event}\n"
+    if not log.exists():
+        log.write_text("# Log\n\n", encoding="utf-8")
+    with log.open("a", encoding="utf-8") as f:
+        f.write(line)