claude-dev-env 2.4.0 → 2.5.0

package/skills/issue-tracker/reference/operation-matrix.md

@@ -0,0 +1,41 @@
+# Operation matrix
+
+Each issue op maps to a GitHub MCP tool and a `gh` fallback that reaches the same REST endpoint. Prefer the MCP tool; fall back to `gh` when the MCP server is unreachable. The REST endpoint column names the authoritative contract both surfaces call, so a session with neither surface can still drive the raw API.
+
+The MCP tool names below match the connected GitHub MCP server's issue toolset. When a server exposes a tool under a different name, pick the tool by what the row describes, and the REST endpoint tells you what it must call.
+
+| Operation | GitHub MCP tool | REST endpoint | `gh` fallback |
+|-----------|-----------------|---------------|---------------|
+| Search open + closed | `mcp__github__search_issues` | `GET /search/issues?q=<terms>+repo:{owner}/{repo}` | `gh issue list --search "<terms>" --state all` |
+| Create epic / sub-issue | `mcp__github__issue_write` (create) | `POST /repos/{owner}/{repo}/issues` | `gh issue create --title "<t>" --body-file <path> --label <label>` |
+| Read issue body | `mcp__github__issue_read` | `GET /repos/{owner}/{repo}/issues/{number}` | `gh issue view <number> --json body` |
+| Update body / labels | `mcp__github__issue_write` (update) | `PATCH /repos/{owner}/{repo}/issues/{number}` | `gh issue edit <number> --body-file <path> --add-label <label>` |
+| Attach native sub-issue | `mcp__github__sub_issue_write` | `POST /repos/{owner}/{repo}/issues/{number}/sub_issues` | `gh api repos/{owner}/{repo}/issues/{number}/sub_issues -F sub_issue_id=<int>` |
+| Add cross-reference comment | `mcp__github__add_issue_comment` | `POST /repos/{owner}/{repo}/issues/{number}/comments` | `gh issue comment <number> --body-file <path>` |
+| Create label | `mcp__github__` label-create tool | `POST /repos/{owner}/{repo}/labels` | `gh label create <name> --color <hex> --description "<text>"` |
+
+## The sub-issue `.id` rule (read this before every attach)
+
+The sub-issues endpoint identifies the child by its REST **database `.id`** — a large integer such as `2138472019` — not by its display number (`#42`). The two are different values. Passing the display number attaches nothing.
+
+Read the child's `.id` from the create op's response, or fetch it:
+
+```
+gh api repos/{owner}/{repo}/issues/{number} --jq .id
+```
+
+`gh issue view <number> --json id` returns the GraphQL node id, a base64 string — the wrong value for this endpoint. Use `gh api ... --jq .id` for the REST database id.
+
+The gh attach uses `-F` (typed field), which sends the id as a JSON integer. `-f` sends a string, and the endpoint rejects a string sub-issue id.
+
+```
+gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -F sub_issue_id=2138472019
+```
+
+## Body content through `--body-file`
+
+Every `gh issue create`, `gh issue edit`, and `gh issue comment` passes body content with `--body-file <path>`, never `--body "<text>"`. A `--body` string mangles backticks on GitHub — they land as literal `\``. Write the body to a temp file and point `--body-file` at it.
+
+## Paginated reads
+
+`gh issue list` needs no pagination flags. For a `gh api` read of a paginated list endpoint (an issue's comments, a repository's issues), pass `--paginate --slurp` and pipe to external `jq` — `gh`'s built-in `--jq` runs per page and gives wrong cross-page results.

package/skills/orchestrator/SKILL.md

@@ -30,15 +30,87 @@ The moment it edits a file or runs a test itself, the pairing breaks —
 its own tool use stays orchestration, run-artifact writes, and light
 verification reads.
 
+## status_gate (deterministic — not optional)
+
+**Prose does not keep the loop alive.** Re-arm and terminate are gated by
+`scripts/status_gate.py` (and, on Claude, the PreToolUse hook
+`orchestrator_refresh_reschedule_gate`). The gate is host-agnostic: a
+single pending re-arm latch in the status file, not host product names.
+
+```
+python scripts/status_gate.py set --status active|done [--run-slug SLUG] [--status-file PATH]
+python scripts/status_gate.py begin-firing [--run-slug SLUG] [--status-file PATH]
+python scripts/status_gate.py should-reschedule [--run-slug SLUG] [--status-file PATH]
+python scripts/status_gate.py claim-rearm [--run-slug SLUG] [--status-file PATH]
+python scripts/status_gate.py release-rearm [--run-slug SLUG] [--status-file PATH]
+```
+
+| Exit / output | Meaning |
+|---|---|
+| `set` → 0 | Status written (`active`/`done`); `done` clears latch; re-asserting `active` preserves it |
+| `begin-firing` → 0 | Active; clears `rearm_pending` (start of a refresh firing) |
+| `begin-firing` → 1 | Stop — missing/invalid/done (fail closed) |
+| `should-reschedule` → 0 | Active and `rearm_pending` is false (read-only) |
+| `should-reschedule` → 1 | Stop — inactive, missing, invalid, or slot already pending |
+| `claim-rearm` → 0 | Slot latched (`rearm_pending` true) after a successful create |
+| `claim-rearm` → 1 | Slot already pending or inactive — cancel any just-created schedule |
+| `release-rearm` → 0 | Cleared pending (recovery if a latch stuck after create) |
+| `release-rearm` → 1 | Stop — missing/invalid/done; nothing to release |
+
+Default status path: `.orchestrator-run-status.json` under the repo plans
+directory, or `$ORCHESTRATOR_RUN_STATUS_FILE`. With `--run-slug SLUG`,
+under the slug plans subdirectory. When using a slug, every refresh
+schedule prompt must carry it: `/orchestrator-refresh --run-slug SLUG`.
+
+### Single-pending re-arm protocol (all hosts)
+
+Exactly one delayed refresh may be outstanding. **Create then claim**
+(order matters on Claude: PreToolUse denies `ScheduleWakeup` when the
+slot is already pending).
+
+1. **Cancel matching schedules** only when the host can list and cancel
+   schedules by prompt. Drop every schedule whose prompt targets
+   `/orchestrator-refresh` (and the same `--run-slug` when used).
+   Replace, never stack. On Claude, there is no selective cancel for a
+   sibling `ScheduleWakeup` — the status-file latch
+   (`should-reschedule` / `claim-rearm`) is the sole stacking
+   enforcement there.
+2. **`should-reschedule`** (same path args as activate). Exit 1 → stop;
+   do not create. Exit 0 → continue.
+3. **Create exactly one non-recurring delayed wake** (~1200–2700s) with
+   prompt `/orchestrator-refresh` (plus `--run-slug` when used). Use the
+   host's one-shot delayed schedule tool (on Claude: `ScheduleWakeup`).
+   Never recurring, never cadence, never a second create in the same
+   firing.
+4. **`claim-rearm`** immediately after a successful create. Exit 0 →
+   done. Exit 1 → cancel the schedule just created and stop (race /
+   already latched).
+5. **On create failure:** do not claim; stop or retry once from step 1.
+
+On Claude, the PreToolUse hook also denies when inactive, already
+pending, or when the tool is `CronCreate`.
+
+**Rules:**
+
+- **Activate only with open work.** After the first ledger task exists,
+  `set --status active` (same `--run-slug` for the whole run if used).
+- **Done is a script.** When every ledger task is completed/cancelled and
+  no executor is running: `set --status done`, cancel matching host
+  schedules, stop. Do not re-arm.
+- **Invocation guard.** If `should-reschedule` is already exit 1 for
+  `rearm_already_pending`, a refresh is already queued — do not arm again.
+
 ## Process
 
-1. **Invocation guard.** One `/orchestrator` per session. When the
-   refresh loop is already running, do not schedule a second one; reuse
-   the live advisor bind and go to step 4.
-2. **Register the discipline reminder.** Schedule it with
-   `ScheduleWakeup` at `delaySeconds: 2700`, prompt
-   `/orchestrator-refresh`, where each refresh re-schedules the next one.
-3. **Bind the shared advisor before any executor.** Follow
+1. **Invocation guard.** One `/orchestrator` per session. When a refresh
+   one-shot is already queued (`should-reschedule` exits 1 with
+   `rearm_already_pending`), do not stack a second: reuse the live
+   advisor bind and go to step 6 (Orchestrate). Skip steps 4–5 — status
+   is already active and a re-arm is already latched; re-registering
+   would attempt a redundant host schedule. (Re-asserting
+   `set --status active` preserves `rearm_pending` when already active,
+   but still do not run step 5.)
+2. **Bind the shared advisor before any executor.** Follow
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
    end to end: detect the host profile, compute the floor from the
    orchestrator consumer set — this session plus every tier in the
@@ -48,16 +120,25 @@ verification reads.
    message the warm agent or report here, and an executor that finds the
    advisor unreachable reports that upward — it never spawns a
    replacement itself.
-4. **Write the run artifacts** (next section) before the first spawn.
-5. **Orchestrate.** Hold the plan and the user conversation. Spawn each
+3. **Write the run artifacts** (next section) before the first spawn.
+4. **Activate status_gate** when the first open ledger task exists:
+   `python scripts/status_gate.py set --status active`.
+5. **Register the discipline reminder** via the single-pending re-arm
+   protocol (cancel matching → `should-reschedule` → one non-recurring
+   delayed wake → `claim-rearm`; default delay about 2700s).
+6. **Orchestrate.** Hold the plan and the user conversation. Spawn each
    task with a ticket (Spawn ticket section), keep driving while
    executors work, and keep the ledger reconciled (Task ledger
    discipline).
-6. **Consult the advisor at hard decisions.** The trigger list, consult
+7. **Consult the advisor at hard decisions.** The trigger list, consult
    format, and reply handling live in the protocol's "Consulting the
    warm agent" section; both this session and every executor are
    consumers. Replies open with one of ENDORSE, CORRECTION, PLAN, or
    STOP — `agents/session-advisor.md` defines each signal.
+8. **Terminate when done.** When every ledger task is completed or
+   cancelled and no executor is running: run
+   `set --status done`, cancel matching host schedules, report
+   completion, and stop. Do not re-arm.
 
 ## Run state lives in artifacts
 
@@ -76,6 +157,9 @@ in the repo the run works on (working files, not committed):
   may write — and its reply is thin: status, artifact paths, blockers.
   The orchestrating session records each result into the run's result
   files as it reconciles the ledger.
+- **Run status file** — written only by `status_gate.py`
+  (`active` / `done`, plus `rearm_pending`). Source of truth for
+  reschedule and the single-pending latch.
 
 Correctness never rides on any agent's private context: when an executor
 dies or hangs, point a fresh spawn at the same assignment file plus its
@@ -101,6 +185,18 @@ Return: status, artifact paths, blockers — nothing else.
   fit gets split in the plan — never padded into a longer prompt.
   Explore fan-outs run tiny; a `clean-coder` assignment can carry a
   whole scoped feature.
+- **Focused tickets are the house convention.** One mechanical done-check
+  per ticket; thick context lives in the assignment file, not the ticket
+  prose. The orchestrator owns splitting a big task into tickets and
+  synthesizing the results — an executor never does either. Two
+  anti-patterns to avoid: an epic ticket that bundles several
+  deliverables behind one done-check, and micro-thrash — a run of tickets
+  so thin each spawn pays more in setup than the work itself takes. See
+  Anthropic's coordinator-pattern cookbook:
+  https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_plan_big_execute_small.ipynb.
+- **Resume with a thin next-slice ticket.** A warm agent already holds
+  the assignment's thick context, so its next ticket names only the next
+  slice of work and the done-check — it does not restate the assignment.
 - **Do not restate what the agent definition carries.** The routing
   table picks the definition, and `clean-coder` already holds the code
   discipline. The ticket adds the task, the pointers, and the Advisor
@@ -117,19 +213,38 @@ workflow resume is available.
 
 | Work | Agent type | Model |
 |---|---|---|
-| Feature, bug, and refactor coding | `clean-coder` | `opus` |
-| Verification passes | `code-verifier` | `sonnet` |
-| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` |
+| Feature, bug, and refactor coding | `clean-coder` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| Verification passes | `code-verifier` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
 | PR descriptions | `pr-description-writer` | `haiku`, with file-list grounding check |
 | Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
 
+Every row that edits code, runs a build, or runs a test is a coding row.
+The per-spawn Agent call's `model:` field carries the routing.
+`CLAUDE_CODE_SUBAGENT_MODEL` and other environment variables do not set
+the worker model; the per-spawn `model:` field does.
+
 Routing rules:
 
 - Each row spawns workflow-backed with a ticket; the routing row and the
   ticket together carry the agent type, model, task, and return
-  contract. A task category that maps to `clean-coder` on `opus` is not
-  served by a `general-purpose` Sonnet spawn — the table is the
-  contract, not a cost suggestion.
+  contract. A coding task category is never served by a different tier
+  as a cost call — the table is the contract.
+- **Fail closed on a Claude host.** When `sonnet` cannot be spawned, use
+  the Claude chain failover for `sonnet` when the session has one
+  configured; otherwise stop the coding spawn and report the failure —
+  never fall back in silence to `opus` or the session's own model.
+- **Fail closed on a third-party host.** Before each coding spawn, the
+  orchestrator runs a deterministic worker-model resolver that prints
+  the sonnet-equivalent model id for that host. A non-zero exit stops
+  the coding spawn; the orchestrator reports the failure rather than
+  picking a model itself. This section states the resolver's contract
+  only; a host where no resolver is available fails closed the same
+  way — the coding spawn stops and the orchestrator reports it.
+- Host detection follows
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+  (Host profiles section, `detect_host_profile`) — the sole detection
+  system, with no second one.
 - Resume a warm workflow agent before creating a new workflow run when
   the warm agent holds the relevant context.
 - `clean-coder` owns code edits. `code-verifier` owns verification. The
@@ -175,12 +290,16 @@ the live agents at any moment. Four invariants hold at all times:
    `blockedBy` links, updated the moment the plan changes.
 
 Reconcile on every state change (spawn, completion notification, plan
-change) and on every `/orchestrator-refresh` firing.
+change) and on every `/orchestrator-refresh` firing. After reconcile, if
+no open work remains, run `set --status done` before any re-arm attempt.
 
 ## Constraints
 
 - One `/orchestrator` per session; the invocation guard blocks a second
-  reminder loop.
+  stacked one-shot while one is already queued.
+- Reschedule is mechanical: status file + `claim-rearm` /
+  `should-reschedule` exit codes; never a recurring host schedule; at
+  most one pending re-arm latch.
 - The orchestrating session never edits code or runs a build or test
   itself — executors do that. Its own tool use stays orchestration,
   run-artifact writes, and light verification reads.
@@ -189,14 +308,36 @@ change) and on every `/orchestrator-refresh` firing.
 - One shared advisor per orchestrated session, owned by this session per
   the protocol; executors never spawn, respawn, or shut it down.
 
+## Gotchas
+
+- **Stacking re-arms.** Creating a second delayed wake while one is
+  already queued (or using a recurring host schedule) multiplies loops
+  on each refresh. Always cancel matching → `should-reschedule` → one
+  create → `claim-rearm`. A second create while pending is denied on
+  Claude by PreToolUse; elsewhere `should-reschedule` / `claim-rearm`
+  exit 1 is a hard stop.
+- **Claim before create on Claude.** If you `claim-rearm` first, the
+  PreToolUse hook sees `rearm_pending` and denies `ScheduleWakeup`.
+  Create first, then claim.
+- **Forgetting `begin-firing` on refresh.** The latch stays pending;
+  later re-arms are denied forever until a firing clears it. Refresh
+  must run `begin-firing` first.
+- **Create without claim.** If create succeeds and you skip
+  `claim-rearm`, a second create can stack. Always claim immediately
+  after a successful create.
+
 ## File Index
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Orchestrator strategy: design rule, process, run artifacts, spawn ticket, routing table, reuse rules, ledger invariants, constraints. |
+| `SKILL.md` | Orchestrator strategy; pointers to run-control scripts. |
+| `scripts/status_gate.py` | Status file, latch, and re-arm gate (exit codes). |
+| `scripts/status_gate_constants/config/constants.py` | Named constants for status_gate. |
+| `scripts/test_status_gate.py` | Gate tests. |
 
 ## Folder Map
 
-- `SKILL.md` — complete orchestrator workflow instructions. Advisor
-  policy lives in
+- `SKILL.md` — orchestration process and routing.
+- `scripts/` — deterministic status_gate.
+- Advisor policy:
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).