@tencent-rtc/trtc-agent-skills 0.1.0

package/skills/trtc-topic/tests/test_end_to_end.py

@@ -0,0 +1,305 @@
+"""End-to-end test: run the full slice loop through every component.
+
+Simulates one full slice's lifecycle by exercising the actual CLI scripts
+and gate scripts, not the in-process state_machine module. This catches
+regressions where the moving parts agree on the field shape in unit tests
+but disagree in integration.
+
+Flow:
+
+    init_slice_queue -> next_slice status (cursor at execution step 0)
+        → gate_slice_read (current slice OK, next slice BLOCKED)
+        → next_slice advance mark_slice_read
+        → gate_slice_write (project file ALLOWED)
+        → write code
+        → next_slice advance mark_code_written
+        → stop hook (BLOCKED — apply hasn't run)
+        → apply.py (PASS → state = apply_passed)
+        → stop hook (ALLOWED)
+        → gate_slice_write (BLOCKED — must wait for confirm)
+        → next_slice advance mark_user_confirmed
+        → next_slice status (cursor at slice 1)
+        → gate_slice_read (slice 1 OK, slice 0 BLOCKED)
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+INIT = ROOT / "scripts" / "init_slice_queue.py"
+NEXT = ROOT / "scripts" / "next_slice.py"
+APPLY = ROOT / "scripts" / "apply.py"
+GATE_READ = ROOT / "guardrails" / "gate_slice_read.py"
+GATE_WRITE = ROOT / "guardrails" / "gate_slice_write.py"
+STOP = ROOT / "guardrails" / "stop_require_apply_evidence.py"
+
+
+def _run_cmd(*args, **kwargs) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, *map(str, args)],
+        text=True,
+        capture_output=True,
+        **kwargs,
+    )
+
+
+def _gate(script: Path, payload: dict, session_path: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(script)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        env={"TRTC_SESSION_PATH": str(session_path), "PATH": "/usr/bin:/bin"},
+    )
+
+
+def _stop(session_path: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(STOP)],
+        text=True,
+        capture_output=True,
+        env={"TRTC_SESSION_PATH": str(session_path), "PATH": "/usr/bin:/bin"},
+    )
+
+
+# Same VUE we used in test_apply_cli.py — wires up the login-auth entry
+# (useLoginState), so the entry-symbol gate passes.
+_PASSING_LOGIN_VUE = '''<template><div /></template>
+<script setup lang="ts">
+import { useLoginState, LoginEvent } from "@trtc/tuikit-atomicx-vue3";
+const { login, setSelfInfo, subscribeEvent } = useLoginState();
+await login({ sdkAppId: 0, userId: "u", userSig: "x", scene: 5001 });
+setSelfInfo({ nickName: "Alice" });
+subscribeEvent(LoginEvent.onLoginExpired, () => {});
+subscribeEvent(LoginEvent.onKickedOffline, () => {});
+</script>
+'''
+
+
+def test_full_slice_loop_through_real_scripts(session_factory, project_factory):
+    session = session_factory(
+        confirmed_plan=["conference/login-auth", "conference/room-lifecycle"]
+    )
+    proj = project_factory()
+    target = proj / "src" / "views" / "MeetingRoom.vue"
+
+    # 1. init queue.
+    r = _run_cmd(INIT, "--session", session)
+    assert r.returncode == 0, r.stderr
+    data = yaml.safe_load(session.read_text())
+    assert data["current_execution_index"] == 0
+    assert data["current_execution_state"] == "not_started"
+
+    # 2. status.
+    r = _run_cmd(NEXT, "--session", session, "--json", "status")
+    assert r.returncode == 0
+    st = json.loads(r.stdout)
+    assert st["current_slice_id"] == "conference/login-auth"
+    assert st["state"] == "not_started"
+
+    # 3. read gate: current slice OK.
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/login-auth.md"},
+    }, session)
+    assert r.returncode == 0, r.stderr
+
+    # 3b. read gate: next slice BLOCKED.
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+    }, session)
+    assert r.returncode == 2
+    assert "current slice" in r.stderr.lower() or "login-auth" in r.stderr
+
+    # 4. write gate: not_started → BLOCKED for project files.
+    r = _gate(GATE_WRITE, {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(target)},
+    }, session)
+    assert r.returncode == 2
+
+    # 5. advance mark_slice_read.
+    r = _run_cmd(NEXT, "--session", session, "advance", "mark_slice_read")
+    assert r.returncode == 0, r.stderr
+
+    # 6. write gate: now ALLOWED.
+    r = _gate(GATE_WRITE, {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(target)},
+    }, session)
+    assert r.returncode == 0, r.stderr
+
+    # Actually write the file.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_PASSING_LOGIN_VUE)
+
+    # 7. advance mark_code_written.
+    r = _run_cmd(NEXT, "--session", session, "advance", "mark_code_written")
+    assert r.returncode == 0, r.stderr
+
+    # 8. stop hook: BLOCKED, apply hasn't run.
+    r = _stop(session)
+    assert r.returncode == 2
+    assert "apply" in r.stderr.lower()
+
+    # 9. apply.py: pass.
+    r = _run_cmd(APPLY, "--slice", "conference/login-auth", "--session", session, "--project", proj)
+    assert r.returncode == 0, f"stdout={r.stdout}\nstderr={r.stderr}"
+
+    # State must be apply_passed.
+    data = yaml.safe_load(session.read_text())
+    assert data["current_execution_state"] == "apply_passed"
+
+    # 10. stop hook: ALLOWED now.
+    r = _stop(session)
+    assert r.returncode == 0
+
+    # 11. write gate: apply_passed → BLOCKED (must confirm first).
+    r = _gate(GATE_WRITE, {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(target)},
+    }, session)
+    assert r.returncode == 2
+    assert "apply_passed" in r.stderr or "confirm" in r.stderr.lower()
+
+    # 11b. evidence file is present BEFORE confirmation (apply.py wrote it).
+    ev_dir = session.parent / ".trtc-apply-evidence"
+    ev_files = list(ev_dir.glob("*.json"))
+    assert len(ev_files) == 1
+    ev = json.loads(ev_files[0].read_text())
+    assert ev["status"] == "pass"
+    assert ev["slice_id"] == "conference/login-auth"
+
+    # 12. user confirms.
+    r = _run_cmd(NEXT, "--session", session, "advance", "mark_user_confirmed")
+    assert r.returncode == 0, r.stderr
+
+    # 13. status: cursor advanced to slice 1.
+    r = _run_cmd(NEXT, "--session", session, "--json", "status")
+    st = json.loads(r.stdout)
+    assert st["current_slice_id"] == "conference/room-lifecycle"
+    assert st["state"] == "not_started"
+
+    # 14. read gate: slice 1 now OK, slice 0 now BLOCKED.
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+    }, session)
+    assert r.returncode == 0, r.stderr
+
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/login-auth.md"},
+    }, session)
+    assert r.returncode == 2
+
+    # 15. evidence file was cleaned up by mark_user_confirmed.
+    ev_files = list((session.parent / ".trtc-apply-evidence").glob("*.json"))
+    assert ev_files == [], (
+        "evidence directory should be empty after a clean confirm; "
+        f"found {[f.name for f in ev_files]}"
+    )
+
+
+def test_apply_failure_path(session_factory, project_factory):
+    """Code that never wires up the slice entry → apply_failed → Stop blocked → Edit allowed."""
+    session = session_factory(confirmed_plan=["conference/login-auth"])
+    proj = project_factory()
+    target = proj / "src" / "views" / "MeetingRoom.vue"
+
+    _run_cmd(INIT, "--session", session)
+    _run_cmd(NEXT, "--session", session, "advance", "mark_slice_read")
+
+    # Write real code that never references the login-auth entry (useLoginState).
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        '<template><div /></template>\n<script setup lang="ts">\n'
+        'import { ref } from "vue";\nconst ready = ref(true);\n</script>'
+    )
+
+    _run_cmd(NEXT, "--session", session, "advance", "mark_code_written")
+
+    r = _run_cmd(APPLY, "--slice", "conference/login-auth", "--session", session, "--project", proj)
+    assert r.returncode == 1
+    data = yaml.safe_load(session.read_text())
+    assert data["current_execution_state"] == "apply_failed"
+
+    # Stop blocked.
+    r = _stop(session)
+    assert r.returncode == 2
+
+    # Edit gate ALLOWED in apply_failed (V1 walk-back: no slice-reread gate).
+    r = _gate(GATE_WRITE, {
+        "tool_name": "Edit",
+        "tool_input": {"file_path": str(target)},
+    }, session)
+    assert r.returncode == 0
+
+
+def test_auto_advance_loop_skips_user_confirm(session_factory, project_factory):
+    """With pause_on_failure, apply pass auto-advances cursor to the next slice.
+
+    The AI never has to call mark_user_confirmed for clean slices — apply.py
+    does it. The state machine, gates and evidence file all still operate.
+    """
+    session = session_factory(
+        confirmed_plan=["conference/login-auth", "conference/room-lifecycle"]
+    )
+    proj = project_factory()
+    target = proj / "src" / "views" / "MeetingRoom.vue"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_PASSING_LOGIN_VUE)
+
+    # Set policy on the session.
+    data = yaml.safe_load(session.read_text())
+    data["auto_advance_policy"] = "pause_on_failure"
+    session.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True))
+
+    # init + read + code_written + apply (pass).
+    assert _run_cmd(INIT, "--session", session).returncode == 0
+    assert _run_cmd(NEXT, "--session", session, "advance", "mark_slice_read").returncode == 0
+    assert _run_cmd(NEXT, "--session", session, "advance", "mark_code_written").returncode == 0
+
+    r = _run_cmd(APPLY, "--slice", "conference/login-auth", "--session", session, "--project", proj)
+    assert r.returncode == 0, f"stdout={r.stdout}\nstderr={r.stderr}"
+    assert "auto-advanced" in r.stdout
+
+    # Cursor should be on slice 1, not_started — no user confirm needed.
+    data = yaml.safe_load(session.read_text())
+    assert data["current_execution_index"] == 1
+    assert data["current_execution_state"] == "not_started"
+
+    # Read gate now allows slice 1's file (and blocks slice 0's).
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+    }, session)
+    assert r.returncode == 0
+
+    r = _gate(GATE_READ, {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "knowledge-base/slices/conference/web/login-auth.md"},
+    }, session)
+    assert r.returncode == 2
+
+    # Stop hook: in not_started → allowed.
+    assert _stop(session).returncode == 0
+
+    # Slice 1: write code that never wires up the room-lifecycle entry
+    # (useRoomState); apply must still pause on failure even with auto-advance.
+    target.write_text("<template><div /></template>\n<script setup>\n// no room APIs\n</script>")
+    assert _run_cmd(NEXT, "--session", session, "advance", "mark_slice_read").returncode == 0
+    assert _run_cmd(NEXT, "--session", session, "advance", "mark_code_written").returncode == 0
+    r = _run_cmd(APPLY, "--slice", "conference/room-lifecycle", "--session", session, "--project", proj)
+    assert r.returncode == 1
+    data = yaml.safe_load(session.read_text())
+    assert data["current_execution_state"] == "apply_failed"
+    # Stop is still blocked on apply_failed — the safety net survives.
+    assert _stop(session).returncode == 2

package/skills/trtc-topic/tests/test_finalize_session.py

@@ -0,0 +1,51 @@
+"""Tests for finalize_session.py session normalization."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+
+FINALIZE_SCRIPT = (
+    Path(__file__).resolve().parents[1] / "scripts" / "finalize_session.py"
+)
+
+
+def test_finalize_session_normalizes_completed_topic_session(session_factory):
+    path = session_factory(
+        status="active",
+        current_step="topic-handoff",
+        completed_steps=[
+            "conference/login-auth",
+            "conference/room-lifecycle",
+            "conference/room-lifecycle",
+        ],
+        execution_queue=[
+            {"id": "conference/login-auth", "type": "slice", "slices": ["conference/login-auth"], "status": "done"},
+            {"id": "foundation", "type": "unit", "slices": ["conference/room-lifecycle", "conference/video-layout"], "status": "pending"},
+        ],
+        current_execution_index=2,
+        current_execution_state="all_done",
+    )
+
+    result = subprocess.run(
+        [sys.executable, str(FINALIZE_SCRIPT), "--session", str(path)],
+        text=True,
+        capture_output=True,
+    )
+
+    assert result.returncode == 0, result.stderr
+    data = yaml.safe_load(path.read_text())
+    assert data["status"] == "completed"
+    assert data["current_step"] == "completed"
+    assert data["current_execution_index"] == 2
+    assert data["current_execution_state"] == "all_done"
+    assert data["completed_steps"] == [
+        "conference/login-auth",
+        "conference/room-lifecycle",
+        "conference/video-layout",
+    ]
+    assert [entry["status"] for entry in data["execution_queue"]] == ["done", "done"]
+    assert "last_recap" in data

package/skills/trtc-topic/tests/test_gates.py

@@ -0,0 +1,316 @@
+"""Tests for the PreToolUse gates that enforce the slice loop.
+
+Both gates read a JSON object on stdin (Claude Code's PreToolUse contract):
+    {
+      "tool_name": "Read" | "Write" | "Edit" | ...,
+      "tool_input": { "file_path": "...", ... }
+    }
+
+They exit:
+    0 — allow the tool call (out of scope, or in-bounds)
+    2 — block the tool call; stderr explains why
+    other — treated as configuration error; AI sees stderr but Claude Code
+            does not block (we never produce these intentionally).
+
+Out-of-scope cases that MUST exit 0:
+    - session file missing
+    - execution_queue not initialised (topic flow not active)
+    - tool_name doesn't match what the gate guards
+    - file_path falls outside the gate's domain
+      (slice-read gate: only guards knowledge-base/slices/*.md)
+      (slice-write gate: only guards user-project source files)
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+GUARDRAILS_DIR = Path(__file__).resolve().parents[1] / "guardrails"
+GATE_READ = GUARDRAILS_DIR / "gate_slice_read.py"
+GATE_WRITE = GUARDRAILS_DIR / "gate_slice_write.py"
+
+# state_machine helper for advancing test sessions to a specific state
+STATE_MACHINE_DIR = Path(__file__).resolve().parents[1] / "scripts" / "lib"
+sys.path.insert(0, str(STATE_MACHINE_DIR))
+import state_machine  # noqa: E402
+sys.path.pop(0)
+
+
+def _run_gate(script: Path, payload: dict, session_path: Path) -> subprocess.CompletedProcess:
+    """Invoke a gate script with the given JSON stdin payload.
+
+    The session path is passed via TRTC_SESSION_PATH env var so the gate
+    doesn't have to walk the filesystem looking for one. Real hooks use the
+    project's repo root via $CLAUDE_PROJECT_DIR; tests use a tmp_path session.
+    """
+    return subprocess.run(
+        [sys.executable, str(script)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        env={"TRTC_SESSION_PATH": str(session_path), "PATH": "/usr/bin:/bin"},
+    )
+
+
+# ---------- gate_slice_read ------------------------------------------------
+
+class TestGateSliceRead:
+    def test_allows_when_session_missing(self, tmp_path):
+        """No session file → not in topic flow → must allow."""
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": str(tmp_path / "knowledge-base/slices/conference/web/room-chat.md")},
+        }
+        result = _run_gate(GATE_READ, payload, tmp_path / "missing.yaml")
+        assert result.returncode == 0, result.stderr
+
+    def test_allows_when_queue_not_initialised(self, session_factory):
+        """Session exists but no execution_queue -> topic flow not active."""
+        path = session_factory()
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-chat.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_allows_non_read_tool(self, session_factory):
+        """Gate only guards Read; Write should pass through."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Write",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-chat.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0
+
+    def test_allows_non_slice_file(self, session_factory):
+        """Reading a non-slice file (e.g., README) is none of the gate's business."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "README.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0
+
+    def test_allows_current_slice_overview(self, session_factory):
+        """Product-level overview for the current slice is allowed."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/login-auth.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_allows_current_slice_platform_file(self, session_factory):
+        """Platform-specific file for the current slice is allowed."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/login-auth.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_blocks_next_slice_read(self, session_factory):
+        """Reading the SECOND slice while cursor is on the first → exit 2."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 2
+        assert "current slice" in result.stderr.lower() or "login-auth" in result.stderr
+
+    def test_blocks_unrelated_slice(self, session_factory):
+        """Reading a slice not even in the queue → exit 2."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/live/coguest-apply.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 2
+
+    def test_unit_mode_allows_any_slice_in_current_unit(self, session_factory):
+        path = session_factory(
+            execution_granularity="unit",
+            confirmed_plan=[
+                "conference/login-auth",
+                "conference/room-lifecycle",
+                "conference/room-chat",
+            ],
+        )
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_unit_mode_blocks_slice_outside_current_unit(self, session_factory):
+        path = session_factory(
+            execution_granularity="unit",
+            confirmed_plan=[
+                "conference/login-auth",
+                "conference/room-lifecycle",
+                "conference/room-chat",
+            ],
+        )
+        state_machine.init_queue(path)
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-chat.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 2
+        assert "current unit" in result.stderr or "foundation" in result.stderr
+
+    def test_allows_absolute_path_to_current_slice(self, session_factory, tmp_path):
+        """Absolute paths must also be matched, not just relative ones."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        abs_path = tmp_path / "anywhere/knowledge-base/slices/conference/web/login-auth.md"
+        payload = {"tool_name": "Read", "tool_input": {"file_path": str(abs_path)}}
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_advances_to_next_slice_after_confirm(self, session_factory):
+        """After full cycle, the second slice should be readable."""
+        path = session_factory()
+        state_machine.init_queue(path)
+        for transition in [
+            "mark_slice_read",
+            "mark_code_written",
+            "mark_apply_passed",
+            "mark_user_confirmed",
+        ]:
+            state_machine.advance(path, transition)
+        # Now cursor is on conference/room-lifecycle.
+        payload = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/room-lifecycle.md"},
+        }
+        result = _run_gate(GATE_READ, payload, path)
+        assert result.returncode == 0, result.stderr
+
+        # And login-auth (the previous slice) is now blocked, since we've moved on.
+        payload2 = {
+            "tool_name": "Read",
+            "tool_input": {"file_path": "knowledge-base/slices/conference/web/login-auth.md"},
+        }
+        result2 = _run_gate(GATE_READ, payload2, path)
+        assert result2.returncode == 2
+
+
+# ---------- gate_slice_write ------------------------------------------------
+
+class TestGateSliceWrite:
+    def _project_file(self, session_factory) -> tuple[Path, Path]:
+        """Return (session_path, file_path-inside-project-src)."""
+        session_path = session_factory()
+        data = yaml.safe_load(session_path.read_text())
+        proj_root = Path(data["project_state"]["project_root"])
+        proj_root.mkdir(parents=True, exist_ok=True)
+        return session_path, proj_root / "src" / "views" / "MeetingRoom.vue"
+
+    def test_allows_when_session_missing(self, tmp_path):
+        payload = {
+            "tool_name": "Write",
+            "tool_input": {"file_path": str(tmp_path / "user-project/src/foo.vue")},
+        }
+        result = _run_gate(GATE_WRITE, payload, tmp_path / "missing.yaml")
+        assert result.returncode == 0
+
+    def test_allows_when_queue_not_initialised(self, session_factory):
+        path, target = self._project_file(session_factory)
+        payload = {"tool_name": "Write", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0
+
+    def test_allows_non_write_tool(self, session_factory):
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        payload = {"tool_name": "Read", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0
+
+    def test_allows_writes_outside_user_project(self, session_factory, tmp_path):
+        """Writing to .claude/, knowledge-base/, /tmp etc. is not the gate's domain."""
+        path, _target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        # current_execution_state == not_started would block a project write,
+        # but this write is OUTSIDE the project root.
+        outside = tmp_path / "elsewhere" / "scratch.md"
+        payload = {"tool_name": "Write", "tool_input": {"file_path": str(outside)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_blocks_write_when_state_not_started(self, session_factory):
+        """Cursor sits on not_started → AI hasn't read the slice yet → block."""
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        payload = {"tool_name": "Write", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 2
+        assert "not_started" in result.stderr or "read" in result.stderr.lower()
+
+    def test_allows_write_when_state_slice_read(self, session_factory):
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        state_machine.advance(path, "mark_slice_read")
+        payload = {"tool_name": "Write", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_allows_edit_when_state_code_written(self, session_factory):
+        """Edit (during apply retry) is allowed in code_written state."""
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        state_machine.advance(path, "mark_slice_read")
+        state_machine.advance(path, "mark_code_written")
+        payload = {"tool_name": "Edit", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_allows_edit_in_apply_failed(self, session_factory):
+        """apply_failed → Edit is ALLOWED so the AI can retry after a fail.
+
+        We deliberately do NOT enforce a "must re-read the slice first" rule
+        here — the V1 walk-back removed that conditional gate (see
+        docs/apply-skill-long-term-design.md §6.4 'walked back' list).
+        """
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        state_machine.advance(path, "mark_slice_read")
+        state_machine.advance(path, "mark_code_written")
+        state_machine.advance(path, "mark_apply_failed")
+        payload = {"tool_name": "Edit", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 0, result.stderr
+
+    def test_blocks_write_in_apply_passed(self, session_factory):
+        """apply_passed → AI must wait for user confirmation, not keep editing."""
+        path, target = self._project_file(session_factory)
+        state_machine.init_queue(path)
+        state_machine.advance(path, "mark_slice_read")
+        state_machine.advance(path, "mark_code_written")
+        state_machine.advance(path, "mark_apply_passed")
+        payload = {"tool_name": "Write", "tool_input": {"file_path": str(target)}}
+        result = _run_gate(GATE_WRITE, payload, path)
+        assert result.returncode == 2
+        assert "apply_passed" in result.stderr or "confirm" in result.stderr.lower()