claude-dev-env 2.4.0 → 2.7.0

package/skills/orchestrator/scripts/test_status_gate.py

@@ -0,0 +1,439 @@
+"""Tests for orchestrator status_gate (status file + single-pending re-arm)."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+from status_gate_constants.config.constants import (  # noqa: E402
+    ALL_DEFAULT_STATUS_DIRECTORY_PARTS,
+    EXIT_CODE_STOP,
+    EXIT_CODE_SUCCESS,
+    REARM_PENDING_FIELD_NAME,
+    REASON_ACTIVE,
+    REASON_MISSING_STATUS_FILE,
+    REASON_REARM_ALREADY_PENDING,
+    REASON_STATUS_NOT_ACTIVE,
+    RUN_STATUS_ACTIVE,
+    RUN_STATUS_DONE,
+    STATUS_FIELD_NAME,
+    STATUS_FILE_ENV_VAR,
+    STATUS_FILE_NAME,
+)
+
+
+def load_status_gate_module() -> ModuleType:
+    module_path = SCRIPTS_DIRECTORY / "status_gate.py"
+    spec = importlib.util.spec_from_file_location("status_gate", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    status_gate_module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = status_gate_module
+    spec.loader.exec_module(status_gate_module)
+    return status_gate_module
+
+
+class TestWriteAndDecide:
+    def should_allow_reschedule_when_status_is_active(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "run-status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "", is_rearm_pending=False
+        )
+        is_allowed, reason_code = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is True
+        assert reason_code == REASON_ACTIVE
+
+    def should_stop_when_status_is_done(self, temporary_directory: Path) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "run-status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_DONE, "", is_rearm_pending=False
+        )
+        is_allowed, reason_code = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is False
+        assert reason_code == REASON_STATUS_NOT_ACTIVE
+
+    def should_fail_closed_when_status_file_missing(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "missing.json"
+        is_allowed, reason_code = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is False
+        assert reason_code == REASON_MISSING_STATUS_FILE
+
+    def should_fail_closed_when_status_file_is_invalid_json(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "bad.json"
+        status_file_path.write_text("{not-json", encoding="utf-8")
+        is_allowed, reason_code = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is False
+
+    def should_deny_reschedule_when_rearm_already_pending(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "run-status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "", is_rearm_pending=True
+        )
+        is_allowed, reason_code = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is False
+        assert reason_code == REASON_REARM_ALREADY_PENDING
+
+
+class TestSetPreservesPending:
+    def should_preserve_rearm_pending_when_reasserting_active(
+        self, temporary_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "demo", is_rearm_pending=False
+        )
+        assert status_gate.claim_rearm_slot(status_file_path, "demo")[0] is True
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "set",
+                "--status-file",
+                str(status_file_path),
+                "--status",
+                RUN_STATUS_ACTIVE,
+                "--run-slug",
+                "demo",
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        payload = json.loads(status_file_path.read_text(encoding="utf-8"))
+        assert payload[REARM_PENDING_FIELD_NAME] is True
+        is_allowed, reason_code = status_gate.decide_should_reschedule(
+            status_file_path
+        )
+        assert is_allowed is False
+        assert reason_code == REASON_REARM_ALREADY_PENDING
+
+    def should_clear_rearm_pending_when_setting_done(
+        self, temporary_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "", is_rearm_pending=True
+        )
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "set",
+                "--status-file",
+                str(status_file_path),
+                "--status",
+                RUN_STATUS_DONE,
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        payload = json.loads(status_file_path.read_text(encoding="utf-8"))
+        assert payload[STATUS_FIELD_NAME] == RUN_STATUS_DONE
+        assert payload[REARM_PENDING_FIELD_NAME] is False
+
+
+class TestBeginClaimRelease:
+    def should_claim_rearm_only_once_until_begin_firing(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "run-status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "demo", is_rearm_pending=False
+        )
+        is_claimed, reason_code, payload = status_gate.claim_rearm_slot(
+            status_file_path, "demo"
+        )
+        assert is_claimed is True
+        assert payload is not None
+        assert payload[REARM_PENDING_FIELD_NAME] is True
+
+        is_claimed_again, second_reason, _second_payload = status_gate.claim_rearm_slot(
+            status_file_path, "demo"
+        )
+        assert is_claimed_again is False
+        assert second_reason == REASON_REARM_ALREADY_PENDING
+
+        is_firing, firing_reason, firing_payload = status_gate.begin_firing(
+            status_file_path, "demo"
+        )
+        assert is_firing is True
+        assert firing_payload is not None
+        assert firing_payload[REARM_PENDING_FIELD_NAME] is False
+        assert firing_reason
+
+        is_claimed_after_firing, _claim_reason, after_payload = (
+            status_gate.claim_rearm_slot(status_file_path, "demo")
+        )
+        assert is_claimed_after_firing is True
+        assert after_payload is not None
+        assert after_payload[REARM_PENDING_FIELD_NAME] is True
+
+    def should_release_rearm_after_failed_schedule(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "run-status.json"
+        status_gate.write_status_file(
+            status_file_path, RUN_STATUS_ACTIVE, "", is_rearm_pending=False
+        )
+        assert status_gate.claim_rearm_slot(status_file_path, "")[0] is True
+        is_released, reason_code, payload = status_gate.release_rearm_slot(
+            status_file_path, ""
+        )
+        assert is_released is True
+        assert payload is not None
+        assert payload[REARM_PENDING_FIELD_NAME] is False
+        assert reason_code
+        is_allowed, allow_reason = status_gate.decide_should_reschedule(
+            status_file_path
+        )
+        assert is_allowed is True
+        assert allow_reason == REASON_ACTIVE
+
+
+class TestResolveAndCli:
+    def should_resolve_explicit_status_file_path(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        target_path = temporary_directory / "explicit.json"
+        resolved_path = status_gate.resolve_status_file_path(
+            str(target_path), None, ""
+        )
+        assert resolved_path == target_path.resolve()
+
+    def should_resolve_default_path_under_base_directory(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        resolved_path = status_gate.resolve_status_file_path(
+            None, temporary_directory, ""
+        )
+        expected_path = temporary_directory.joinpath(
+            *ALL_DEFAULT_STATUS_DIRECTORY_PARTS, STATUS_FILE_NAME
+        ).resolve()
+        assert resolved_path == expected_path
+
+    def should_scope_default_path_by_run_slug(
+        self, temporary_directory: Path
+    ) -> None:
+        status_gate = load_status_gate_module()
+        run_slug = "demo-run"
+        resolved_path = status_gate.resolve_status_file_path(
+            None, temporary_directory, run_slug
+        )
+        expected_path = temporary_directory.joinpath(
+            *ALL_DEFAULT_STATUS_DIRECTORY_PARTS, run_slug, STATUS_FILE_NAME
+        ).resolve()
+        assert resolved_path == expected_path
+
+    def should_set_and_gate_via_main(
+        self,
+        temporary_directory: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "status.json"
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "set",
+                "--status-file",
+                str(status_file_path),
+                "--status",
+                RUN_STATUS_ACTIVE,
+                "--run-slug",
+                "demo-run",
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        payload = json.loads(status_file_path.read_text(encoding="utf-8"))
+        assert payload[STATUS_FIELD_NAME] == RUN_STATUS_ACTIVE
+        assert payload[REARM_PENDING_FIELD_NAME] is False
+
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "should-reschedule",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "claim-rearm",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "claim-rearm",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_STOP
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "should-reschedule",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_STOP
+
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "begin-firing",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "should-reschedule",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "set",
+                "--status-file",
+                str(status_file_path),
+                "--status",
+                RUN_STATUS_DONE,
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "should-reschedule",
+                "--status-file",
+                str(status_file_path),
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_STOP
+
+    def should_resolve_status_file_from_environment(
+        self, temporary_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        status_gate = load_status_gate_module()
+        status_file_path = temporary_directory / "env-status.json"
+        monkeypatch.setenv(STATUS_FILE_ENV_VAR, str(status_file_path))
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            ["status_gate.py", "set", "--status", RUN_STATUS_ACTIVE],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        assert status_file_path.is_file()
+        is_allowed, _reason = status_gate.decide_should_reschedule(status_file_path)
+        assert is_allowed is True
+
+    def should_scope_set_and_should_reschedule_with_matching_run_slug(
+        self, temporary_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        status_gate = load_status_gate_module()
+        monkeypatch.chdir(temporary_directory)
+        monkeypatch.delenv(STATUS_FILE_ENV_VAR, raising=False)
+        run_slug = "demo-run"
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "set",
+                "--status",
+                RUN_STATUS_ACTIVE,
+                "--run-slug",
+                run_slug,
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        slug_path = status_gate.resolve_status_file_path(
+            None, temporary_directory, run_slug
+        )
+        default_path = status_gate.resolve_status_file_path(
+            None, temporary_directory, ""
+        )
+        assert slug_path.is_file()
+        assert not default_path.is_file()
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            [
+                "status_gate.py",
+                "should-reschedule",
+                "--run-slug",
+                run_slug,
+            ],
+        )
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+        monkeypatch.setattr(
+            sys,
+            "argv",
+            ["status_gate.py", "should-reschedule"],
+        )
+        assert status_gate.main() == EXIT_CODE_STOP
+
+
+@pytest.fixture
+def temporary_directory(tmp_path: Path) -> Path:
+    return tmp_path

package/skills/orchestrator-refresh/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: orchestrator-refresh
 description: >-
-  Fired by the /orchestrator loop reminder about every 45 minutes to
-  re-assert the advisor discipline mid-run: orchestrate, route hard decisions
-  to the shared advisor (ENDORSE / CORRECTION / PLAN / STOP — SendMessage on
-  Claude, Claude CLI chain on a third-party host), reuse warm agents. Triggers:
-  '/orchestrator-refresh'.
+  Re-assert orchestrator discipline on a one-shot delayed wake: ledger
+  reconcile, advisor routing, warm executor reuse, single-pending re-arm
+  via status_gate. Terminates when the gate says stop. Triggers:
+  '/orchestrator-refresh', orchestrator-refresh, refresh the orchestrator
+  loop, re-arm orchestrator.
 ---
 
 # Orchestrator Refresh
@@ -15,35 +15,129 @@ Detect the host profile first (see Host profiles in
 Re-assert the discipline for that host only — do not invent an Agent-tool
 Claude `session-advisor` spawn on a third-party host.
 
-1. **Reconcile the task ledger first.** Call `TaskList` before anything else
-   this firing. The ledger is stale when any of these holds: a running or
-   finished executor has no `in_progress` task naming it as owner; a finished
-   executor's task is still open (or was closed without its result merged);
-   the next phase you will dispatch has no pending task; a `blockedBy` link
-   contradicts the actual run order. Fix every mismatch with TaskCreate /
-   TaskUpdate in this same firing — never defer reconciliation to "when the
-   agent reports".
-2. **You are the orchestrator.** Orchestrate and hold the user conversation;
-   spawn executor subagents to do all the work — every code edit and build or
-   test run.
+## 0. status_gate first (deterministic)
+
+Script home (prefer install path, else package checkout):
+
+- `%USERPROFILE%/.claude/skills/orchestrator/scripts/status_gate.py`
+- `~/.claude/skills/orchestrator/scripts/status_gate.py`
+- `skills/orchestrator/scripts/status_gate.py`
+
+Pass the same `--run-slug` used at activate, if any.
+
+### 0a. begin-firing (consume prior re-arm)
+
+```
+python <status_gate.py> begin-firing [--run-slug SLUG]
+```
+
+| Exit | Action |
+|---|---|
+| **1** | End the refresh. Cancel matching host schedules for `/orchestrator-refresh` if the host allows. Report inactive/done. **Do not** re-arm. Do not spawn. Any work already in flight keeps running. |
+| **0** | Latch cleared. Continue with steps 1–6. |
+
+### 0b. Done after ledger (step 1)
+
+After ledger reconcile: if every task is completed/cancelled and no
+executor is running:
+
+```
+python <status_gate.py> set --status done [--run-slug SLUG]
+```
+
+Cancel matching host schedules; stop without re-arming.
+
+## The refresh never interrupts the run
+
+A refresh firing reinforces discipline alongside work already in flight.
+It never pauses, cancels, or waits on a running executor. Reconcile the
+ledger, re-assert the routing, re-arm once, and hand control straight back
+to the work in progress.
+
+Inside the re-arm protocol (step 6), every "stop" ends the *re-arm* and
+nothing else. A `should-reschedule` exit 1 means no schedule is created this
+firing, and a `claim-rearm` exit 1 means the schedule just created is
+cancelled; either way the session keeps orchestrating in the same turn.
+
+Two stops end the whole firing, and both leave running executors alone:
+`begin-firing` exit 1 (step 0a) and the done branch (step 0b). Each means the
+run is finished, not active, or has no readable status file, so the refresh
+reports and adds nothing further. A fail-closed advisor bind (step 3) stops
+advisor consultation alone; the firing still reconciles the ledger, re-arms
+once, and reports the unreachable advisor.
+
+## Discipline steps
+
+1. **Reconcile the task ledger first.** Call `TaskList` after the gate.
+   The ledger is stale when any of these holds: a running or finished
+   executor has no `in_progress` task naming it as owner; a finished
+   executor's task is still open (or was closed without its result
+   merged); the next phase you will dispatch has no pending task; a
+   `blockedBy` link contradicts the actual run order. Fix every mismatch
+   with TaskCreate / TaskUpdate in this same firing — never defer.
+2. **You are the orchestrator.** Orchestrate and hold the user
+   conversation; spawn executor subagents for every code edit and build
+   or test run.
+   - **Worker model.** Every coding spawn sets `model: sonnet` on a
+     Claude host, or the resolver-printed sonnet-equivalent id on a
+     third-party host, and fails closed — see Workflow Agent Routing in
+     [`skills/orchestrator/SKILL.md`](../orchestrator/SKILL.md#workflow-agent-routing).
+   - **Focused tickets.** One mechanical done-check per ticket; resume a
+     warm agent with a thin next-slice ticket rather than a fresh cold
+     spawn, and keep thick context in the assignment file.
 3. **Hard decisions go to the shared advisor.**
    - **Claude host:** executors consult the warm `session-advisor` via
-     `SendMessage` and receive one of four signals — ENDORSE, CORRECTION, PLAN,
-     or STOP. The orchestrating session routes its own hard decisions the same
-     way and keeps its tool use to orchestration and light verification reads.
-   - **Third-party host:** the advisor is a max-tier Claude CLI bind owned by this
-     session (`claude_chain_runner.py`, Fable high then Opus max). Do **not**
-     spawn `session-advisor` via Agent and do **not** tell executors to
-     SendMessage a separate advisor agent. Executors report blockers to this
-     session; consult the Claude CLI advisor and relay ENDORSE / CORRECTION /
-     PLAN / STOP. When the CLI bind is unreachable, fail closed and report to
-     the user — do not answer the four signals as this third-party session.
-4. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
-   name or `agentId` to reuse its warm context; prefer that over a cold spawn.
-   (On a third-party host this is executor reuse only — advisor re-bind stays on the CLI
-   chain path in the shared protocol.)
-5. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
-   subagent's context, so a clean context comes from a fresh spawn — never tell
-   an agent to compact.
-5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
-   mechanism needs each firing to queue the following one.
+     `SendMessage` (ENDORSE / CORRECTION / PLAN / STOP). This session
+     routes the same way; keep tool use to orchestration and light
+     verification reads.
+   - **Third-party host:** advisor is a max-tier Claude CLI bind owned
+     by this session (`claude_chain_runner.py`, Fable high then Opus
+     max). Do **not** spawn `session-advisor` via Agent. Executors
+     report blockers here; consult the CLI advisor and relay signals.
+     If the CLI bind is unreachable, fail closed — do not answer the
+     four signals as this third-party session.
+4. **Resume before you spawn.** `SendMessage` an existing *executor* by
+   name or `agentId` before a cold spawn. (Third-party: executor reuse
+   only — advisor stays on the CLI chain.)
+5. **Fresh spawn only for a genuine task switch.** Never tell an agent
+   to compact for a clean context.
+6. **Single-pending re-arm only.** Same protocol as the orchestrator
+   skill (host-agnostic; **create then claim**):
+
+   1. Cancel matching schedules only when the host can list/cancel by
+      prompt (`/orchestrator-refresh` + `--run-slug` if used). On Claude,
+      skip selective cancel — the latch is the sole stacking enforcement.
+   2. `python <status_gate.py> should-reschedule [--run-slug SLUG]`
+      - Exit **1** → stop; do not schedule.
+      - Exit **0** → continue.
+   3. Create **exactly one** non-recurring delayed wake (~1200–2700s)
+      with prompt `/orchestrator-refresh` (plus `--run-slug` when used).
+      Host one-shot tool only (on Claude: `ScheduleWakeup`). Never
+      recurring / never cadence / never a second create this firing.
+   4. `python <status_gate.py> claim-rearm [--run-slug SLUG]` right
+      after a successful create. Exit 1 → cancel that schedule and stop.
+   5. If create fails: do not claim; stop or retry once from cancel.
+
+## Gotchas
+
+- **Stacking loops.** A second schedule create while one is already
+  queued multiplies firings. Cancel → `should-reschedule` → one create
+  → `claim-rearm`. Never claim before create on Claude (PreToolUse
+  denies `ScheduleWakeup` when pending).
+- **Skipping `begin-firing`.** Prior `rearm_pending` stays set; re-arm
+  stays denied. Always run step 0a first.
+- **Create without claim.** Skip claim after create and a second create
+  can stack. Claim immediately after success.
+
+## File Index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Refresh firing steps; points at orchestrator `status_gate.py`. |
+
+## Folder Map
+
+- `SKILL.md` — this skill (thin); gate implementation lives under
+  `skills/orchestrator/scripts/`.
+- Advisor policy:
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).