claude-dev-env 2.0.0 → 2.0.1

package/hooks/blocking/test_verifier_verdict_minter.py

@@ -69,6 +69,36 @@ def _write_sidecar(agent_transcript_file: pathlib.Path, agent_type: str) -> None
     )
 
 
+def _write_verdict_transcript(agent_transcript_file: pathlib.Path, verdict_body: str) -> None:
+    verdict_text = f"ok\n```verdict\n{verdict_body}\n```\n"
+    agent_transcript_file.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {"content": [{"type": "text", "text": verdict_text}]},
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+def _make_repo(tmp_path: pathlib.Path) -> pathlib.Path:
+    repo_root = tmp_path / "repo"
+    repo_root.mkdir()
+    return repo_root
+
+
+def _mint_payload(
+    agent_transcript_file: pathlib.Path, repo_root: pathlib.Path, agent_id: str
+) -> dict[str, str]:
+    return {
+        "agent_transcript_path": str(agent_transcript_file),
+        "cwd": str(repo_root),
+        "agent_id": agent_id,
+    }
+
+
 def test_resolves_subagent_type_from_sidecar(tmp_path: pathlib.Path) -> None:
     agent_transcript = tmp_path / "agent-7.jsonl"
     agent_transcript.write_text("", encoding="utf-8")
@@ -141,7 +171,7 @@ def test_verifier_type_without_a_verdict_mints_nothing(tmp_path: pathlib.Path) -
     assert mint_for_payload(payload) is None
 
 
-def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
+def _init_repo_with_upstream(repo_root: pathlib.Path) -> None:
     subprocess.run(["git", "-C", str(repo_root), "init", "-q"], check=True)
     subprocess.run(
         ["git", "-C", str(repo_root), "config", "user.email", "verifier@test"], check=True
@@ -151,37 +181,20 @@ def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
     subprocess.run(["git", "-C", str(repo_root), "add", "-A"], check=True)
     subprocess.run(["git", "-C", str(repo_root), "commit", "-qm", "init"], check=True)
     subprocess.run(["git", "-C", str(repo_root), "branch", "-f", "origin/main", "HEAD"], check=True)
+
+
+def _init_repo_with_upstream_and_edit(repo_root: pathlib.Path) -> None:
+    _init_repo_with_upstream(repo_root)
     (repo_root / "module.py").write_text("answer = 2\n", encoding="utf-8")
 
 
 def test_clean_verifier_verdict_mints_a_verdict_file(tmp_path: pathlib.Path) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "a02b9583eedc74093",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "a02b9583eedc74093")
     verdict_path = mint_for_payload(payload)
     try:
         assert verdict_path is not None
@@ -199,7 +212,8 @@ def _deny_rules() -> list[str]:
 
 
 def test_settings_deny_verdict_directory_write() -> None:
-    assert "Write($HOME/.claude/verification/**)" in _deny_rules()
+    assert "Edit($HOME/.claude/verification/**)" in _deny_rules()
+    assert "Write($HOME/.claude/verification/**)" not in _deny_rules()
 
 
 def test_settings_deny_verdict_directory_edit() -> None:
@@ -209,87 +223,28 @@ def test_settings_deny_verdict_directory_edit() -> None:
 def test_minter_refuses_when_attested_hash_equals_empty_surface_hash(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     attested_empty = empty_surface_hash()
     verdict_fence = json.dumps(
         {"all_pass": True, "findings": [], "manifest_sha256": attested_empty}
     )
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, verdict_fence)
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "empty-surface-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "empty-surface-1")
     assert mint_for_payload(payload) is None
 
 
 def test_minter_refuses_when_recomputed_surface_is_empty(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
-    subprocess.run(["git", "-C", str(repo_root), "init", "-q"], check=True)
-    subprocess.run(
-        ["git", "-C", str(repo_root), "config", "user.email", "verifier@test"],
-        check=True,
-    )
-    subprocess.run(
-        ["git", "-C", str(repo_root), "config", "user.name", "verifier"],
-        check=True,
-    )
-    (repo_root / "module.py").write_text("answer = 1\n", encoding="utf-8")
-    subprocess.run(["git", "-C", str(repo_root), "add", "-A"], check=True)
-    subprocess.run(
-        ["git", "-C", str(repo_root), "commit", "-qm", "init"], check=True
-    )
-    subprocess.run(
-        ["git", "-C", str(repo_root), "branch", "-f", "origin/main", "HEAD"],
-        check=True,
-    )
+    repo_root = _make_repo(tmp_path)
+    _init_repo_with_upstream(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "empty-recompute-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "empty-recompute-1")
     assert mint_for_payload(payload) is None
 
 
@@ -297,23 +252,7 @@ def test_resolves_none_when_sidecar_absent_even_with_verdict_fence(
     tmp_path: pathlib.Path,
 ) -> None:
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
     payload = {"agent_transcript_path": str(agent_transcript)}
     assert resolved_subagent_type(payload) is None
 
@@ -321,67 +260,25 @@ def test_resolves_none_when_sidecar_absent_even_with_verdict_fence(
 def test_does_not_mint_when_sidecar_absent_but_transcript_has_verdict(
     tmp_path: pathlib.Path,
 ) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     agent_transcript = tmp_path / "agent-7.jsonl"
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": 'ok\n```verdict\n{"all_pass": true, "findings": []}\n```\n',
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "no-sidecar-1",
-    }
+    _write_verdict_transcript(agent_transcript, '{"all_pass": true, "findings": []}')
+    payload = _mint_payload(agent_transcript, repo_root, "no-sidecar-1")
     assert mint_for_payload(payload) is None
 
 
 def test_attested_manifest_hash_binds_over_cwd_surface(tmp_path: pathlib.Path) -> None:
-    repo_root = tmp_path / "repo"
-    repo_root.mkdir()
+    repo_root = _make_repo(tmp_path)
     _init_repo_with_upstream_and_edit(repo_root)
     attested_hash = "c" * 64
-    agent_transcript = tmp_path / "agent-7.jsonl"
     verdict_fence = json.dumps(
         {"all_pass": True, "findings": [], "manifest_sha256": attested_hash}
     )
-    agent_transcript.write_text(
-        json.dumps(
-            {
-                "type": "assistant",
-                "message": {
-                    "content": [
-                        {
-                            "type": "text",
-                            "text": f"ok\n```verdict\n{verdict_fence}\n```\n",
-                        }
-                    ]
-                },
-            }
-        )
-        + "\n",
-        encoding="utf-8",
-    )
+    agent_transcript = tmp_path / "agent-7.jsonl"
+    _write_verdict_transcript(agent_transcript, verdict_fence)
     _write_sidecar(agent_transcript, MINTING_AGENT_TYPE)
-    payload = {
-        "agent_transcript_path": str(agent_transcript),
-        "cwd": str(repo_root),
-        "agent_id": "attest-1",
-    }
+    payload = _mint_payload(agent_transcript, repo_root, "attest-1")
     verdict_path = mint_for_payload(payload)
     try:
         assert verdict_path is not None

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/orchestrator/SKILL.md

@@ -21,12 +21,8 @@ delegating to Sonnet-5 workers came out cheaper and faster
 than a solo frontier agent held to the same verification rigor, with
 84-98% of the team's input tokens billed at the worker rate.
 
-Claude Code has no `multiagent` coordinator field or Managed-Agents-style
-`create_agent`/`send_to_agent` primitives; this skill reaches the same
-shape with the tools Claude Code already has. Under this skill the session
-is the orchestrator. In Claude Code the user always talks to the session and never to a
-subagent, so the session is the user's sole interface: all user-facing
-communication flows through it. It spawns and resumes executor subagents
+Under this skill the session
+is the orchestrator. It spawns and resumes executor subagents
 — `clean-coder` and the like — and those executors do every bit of the
 execution: the code edits, the build runs, the test runs. The orchestrating
 session drives the plan and routes hard decisions to the shared advisor
@@ -64,16 +60,11 @@ session drives the plan and routes hard decisions to the shared advisor
    shared advisor bind (Claude warm `session-advisor`, or a third-party host's
    Claude CLI bind — run step 3 only when none exists yet), then skip straight to step 4.
 
-2. **Register the discipline reminder.** By default, schedule it with
-   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/orchestrator-refresh`,
-   where each refresh re-schedules the next one — a 1200-second wakeup costs
-   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
-   mechanism (`/loop 20m /orchestrator-refresh`) is the escape hatch when
-   `ScheduleWakeup` is not available. Either way the reminder is the
-   enforcement surface: each firing re-asserts the discipline while the run is
-   in flight.
+2. **Register the discipline reminder.** schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1800`, prompt `/orchestrator-refresh`,
+   where each refresh re-schedules the next one.
 
-3. **Bind the shared advisor before any executor.** Detect the host profile
+3. **Bind a shared advisor before any executor.** Detect the host profile
    first (see Host profiles in
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
    On a **Claude host**, follow the Warm-up procedure in that doc (Agent spawn
@@ -160,7 +151,7 @@ Routing rules:
 
 ## Agent reuse (non-negotiable)
 
-- **Resume before you spawn, always.** A warm agent carries its context and
+- **Resume before you spawn, always.** A warm agent (active within the past 59 minutes)  carries its context and
   cached tokens; a fresh spawn starts cold and pays to rebuild both.
   Resume the existing workflow agent by name or `agentId` when it holds
   relevant context. Prefer that path every time an existing workflow agent
@@ -170,6 +161,24 @@ Routing rules:
 - **Name the agent to resume.** When a PLAN from the shared advisor fits a warm
   agent, name which agent to resume and where.
 
+## Task ledger discipline
+
+The task list is the run's ledger, and it must be reconcilable against the live
+agents at any moment. Four invariants hold at all times:
+
+1. **No untracked work.** Every unit of delegated work has a task BEFORE its
+   executor spawns — TaskCreate first, then Agent.
+2. **Ownership is live.** At spawn, set the task `in_progress` with `owner` =
+   the executor's agent name. One task, one owner.
+3. **Completion follows evidence.** A task turns `completed` only when the
+   executor's result is back AND merged into run state — never on dispatch,
+   never on a self-report alone (see `workers-done-before-complete`).
+4. **Dependencies mirror the plan.** Phase order is encoded as `blockedBy`
+   links, updated the moment the plan changes.
+
+Reconcile on every state change (spawn, completion notification, plan change)
+and on every `/orchestrator-refresh` firing.
+
 ## Constraints
 
 - One `/orchestrator` per session; the invocation guard blocks a second

package/skills/orchestrator-refresh/SKILL.md

@@ -15,10 +15,18 @@ 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. **You are the orchestrator.** Orchestrate and hold the user conversation;
+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.
-2. **Hard decisions go to the shared advisor.**
+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
@@ -30,11 +38,11 @@ Claude `session-advisor` spawn on a third-party host.
      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.
-3. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
+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.)
-4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
+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