@tamng0905/builder-essential-skills 0.1.0

package/skills/lead/dispatch.md

@@ -0,0 +1,342 @@
+# Dispatch reference
+
+Dispatch turns a frozen slice into fresh builder, reviewer, or critic work. The
+Lead chooses the job shape, the model tier, the worktree, and the report path;
+the subagent receives a self-contained task and returns raw evidence only.
+
+## Model routing
+
+Every role — `lead`, `builder`, `reviewer`, `researcher`, `scout`, `critic` — is
+an independent slot resolved by `skills/lead/config.py`. The "submodel" of a role
+is its reasoning effort. Do not hand-parse config; run the resolver and use what
+it prints:
+
+```bash
+python skills/lead/config.py            # table of the effective routing
+python skills/lead/config.py --role builder   # one role, with its command
+python skills/lead/config.py --check    # verify each provider CLI is on PATH
+```
+
+Resolution order per role: repo `.lead/config`, then `~/.lead/config`, then the
+shipped defaults in `config.py`. A role value is `<provider>/<model>[:<effort>]`,
+a user-defined `alias`, or the sentinel `inherit-lead`. The provider registry
+(`skills/lead/models.json`, extendable via `.lead/models.json`) maps a provider's
+model aliases to real model ids and prints the exact CLI command — this is the
+single place a model-generation change is reviewed. Full grammar: `MODELS.md`.
+
+Defaults (see `config.py`): `lead = claude/fable:xhigh` (the leading model),
+`reviewer = inherit-lead`, `builder = codex/best:xhigh`, `researcher =
+codex/best:high`, `scout = codex/best:low`, `critic = claude/fable:high`.
+
+Rules that always hold:
+
+- **Tier is fixed at decomposition** by config plus dispatch rules; a job failure
+  never moves it. A failure is a diagnosis task, not a retry-at-a-stronger-model
+  task (see `loop.md` "## Failure ladder").
+- **Codex-first builder fallback.** If the resolved builder's Codex CLI is not on
+  PATH at preflight (`config.py --check` flags this), fall back to
+  `claude/sonnet:high` and write one tracking-issue comment naming requested vs
+  substituted. Never hard-fail on model availability alone.
+- **Dispatch rules** (`when <task-class> -> <spec>`) route recipe-like work to a
+  cheaper tier or ambiguous work to a deeper one; the resolver lists them. A
+  matching rule is a judgment aid — record which rule you used and override with a
+  reason on the issue when needed.
+- **Cross-family review** for high-stakes slices reduces shared blind spots. When
+  both CLIs are installed, prefer the reviewer be a different family than the
+  builder, and record the direction in the verdict comment.
+
+## Per-harness delegation
+
+| | Claude Code | Codex |
+|---|---|---|
+| Builder | Agent tool with `.claude/agents/lead-builder.md`; `disallowedTools` denies git commit/push; `isolation: worktree`; run in background; model passed per invocation from the resolver. Verify `git worktree list` after each spawn; never run two Claude-backend builders concurrently without verified separate worktrees. Never pre-create a worktree for a Claude-backend job. | `codex exec` per the resolver's builder command; the Lead owns worktree creation via git. |
+| Reviewer | Agent tool with `.claude/agents/lead-reviewer.md`; read-only tools plus a shell for check commands; lead tier via `model: inherit` or a per-invocation model. | Fresh `codex exec --sandbox read-only` with the fixed reviewer template. |
+| Watchdog | Background `watchdog.sh` / `watchdog.ps1` whose exit wakes the Lead; the LLM fallback template only when the harness cannot wake on a process exit. | Same script watchdog. |
+| Critic | One fresh read-only subagent over the whole decomposition, pre-freeze. | Same. |
+
+Job and reviewer reports must name which executor (Bash or PowerShell) ran each
+check command; some sandboxes strip one shell.
+
+## Codex backend from a Claude Lead
+
+When the Lead is Claude Code and the builder backend is Codex, write the builder
+block to a file first, then pass it via stdin (`-`) — big prompt blocks contain
+quotes that shells can mangle. Take the exact per-role command from
+`config.py --role builder`; the effort pin is the only thing that changes for a
+tier-down.
+
+Single job in the current checkout:
+
+```bash
+codex exec -C <repo-root> --sandbox workspace-write \
+  -m <model-id> -c model_reasoning_effort="<effort>" \
+  --json -o .lead/last-run.md \
+  - < .lead/dispatch-block.md
+```
+
+For 2–5 jobs, the Lead owns the worktree and runs them in parallel:
+
+```bash
+git -C <repo-root> worktree add .lead/wt/<slice>-<NN> -b job/<slice>-<NN> <freeze-sha>
+
+codex exec -C <repo-root>/.lead/wt/<slice>-<NN> --sandbox workspace-write \
+  -m <model-id> -c model_reasoning_effort="<effort>" \
+  --json -o .lead/wt/<slice>-<NN>.last-run.md \
+  - < .lead/wt/<slice>-<NN>.block.md
+```
+
+A worktree's `.git` is sandbox-protected; builders cannot commit or touch shared
+history from any job.
+
+## Integration commands
+
+Integration is Lead-only, after per-job post-flight passes. For Claude-backend
+jobs, commit inside the harness's auto-created worktree, then merge that branch:
+
+```bash
+git -C <repo-root> checkout -b slice/<name> <freeze-sha>
+git -C <repo-root>/.lead/wt/<slice>-<NN> add -A
+git -C <repo-root>/.lead/wt/<slice>-<NN> commit -m "job <NN>: <what>"
+git -C <repo-root> merge --no-ff job/<slice>-<NN>
+<rerun the check commands>
+git -C <repo-root> worktree remove .lead/wt/<slice>-<NN>
+git -C <repo-root> branch -d job/<slice>-<NN>
+```
+
+A merge conflict means the plan was not disjoint. Kill the conflicting job and
+re-slice; never hand-resolve builder conflicts.
+
+## Reviewer template
+
+Send this as-is except for the placeholders. Add no slice-specific prose,
+encouragement, summaries, or interpretation. Intent context is pointer-only.
+
+<!-- lead-reviewer-template:start -->
+```text
+Frozen check file path: docs/checks/<slice>.md
+Freeze commit SHA: <freeze-sha>
+Branch to review: <branch>
+Spec pointer: <spec path named by the frozen check>
+Job report: docs/jobs/<issue-slug>-01.md
+Rulings file: docs/jobs/<issue-slug>-rulings.md (absent = no post-freeze rulings)
+
+You are a fresh, read-only reviewer. You did not build this job. Flag only gaps
+that affect correctness, the stated requirements, or documented project
+invariants -- cite file:line evidence for every finding. No stylistic preferences.
+
+Tree audit: any tracked-file modification during review discards the verdict as
+INVALID.
+
+Verdict format:
+- Checks integrity: PASS | FAIL | INVALID
+  Raw evidence: git diff <freeze-sha>..HEAD -- docs/checks/
+- Diff vs intent: PASS | FAIL | INVALID
+  Raw evidence: file:line evidence from the diff and the frozen check/spec text
+- Per check:
+  - <check id>: PASS | FAIL | INVALID
+    Command: <exact command from the frozen check>
+    Executor: <Bash | PowerShell>
+    Raw evidence: verbatim stdout/stderr and exit code
+- Slice verdict: PASS | FAIL | INVALID
+  Decisive reason: <one sentence tied to raw evidence>
+```
+<!-- lead-reviewer-template:end -->
+
+Passing checks with wrong code still fails: the diff-vs-intent verdict is not
+optional. INVALID means "not measured the way the check specifies" — unmeasured
+never equals passed.
+
+## Critic template
+
+One pre-freeze pass over the whole decomposition. Send as-is except placeholders.
+
+<!-- lead-critic-template:start -->
+```text
+Draft check file path: docs/checks/<slice>.md
+Branch: <branch>
+Issue bodies: <pasted issue bodies for this plan>
+
+Task: try to falsify this plan. Execute each check command against the current
+tree, verify every referenced path/SHA/pointer resolves, and attack each
+acceptance criterion and issue body for contradictions and non-falsifiability --
+including patterns that collide with repo realities (e.g. a grep pattern matching
+the repo's own name). For every file a job deletes or renames, grep the repo for
+references and confirm the owning job's boundary covers them or a dependency edge
+orders the fix. For every NEW artifact path a job will create, run
+`git check-ignore <path>` and flag the plan if it is ignored.
+
+Defect report format:
+- <check id or clause>: FALSIFIED | HOLDS
+  Evidence: <command run and verbatim output, or file:line>
+- Plan findings: <delete/rename reference and ignored-new-path findings, or none>
+- Assumptions not evidenced in the repo: <list or none>
+```
+<!-- lead-critic-template:end -->
+
+## Issue conventions
+
+Claim is a Lead action, never a builder action: the Lead is the single
+dispatcher and assigns exactly one issue per job immediately before spawning its
+builder. On current backends, builders usually cannot post to issues (Codex has
+no network; a Claude subagent may lose its shell), so `MIRROR: LEAD` is the
+normal mode — the Lead mirrors status at event boundaries it already occupies.
+
+```bash
+gh issue edit <n> --add-assignee "@me"                          # Lead claims, before dispatch
+gh issue comment <n> --body "PHASE 0: <disagreements, or what I checked>"
+gh issue comment <n> --body "BLOCKED: <exact blocker> + <what I tried>"
+gh issue comment <n> --body "STATUS: <the report's exact status line>"
+gh issue comment <n> --body "RULING: <decision> - <one line why>"
+gh issue comment <n> --body "ANSWER: <blocker answer>"
+gh issue comment <n> --body "VERDICT: PASS|FAIL|INVALID - <decisive reason>"
+gh issue comment <tracking-issue-n> --body "DIGEST: <batched escalations + run summary>"
+```
+
+Comments land at least 1 minute apart, each under 65,000 characters, never one
+per commit (GitHub secondary rate limits). A running builder does NOT re-read
+issue comments mid-job — the issue is the durable log, not a channel it polls; an
+answer reaches a builder only through a fresh respawn's spawn context.
+
+## Watchdog dispatch
+
+The Lead writes one watchdog config JSON per wave, then launches the platform
+script as a background process (`watchdog.sh` on POSIX, `watchdog.ps1` on
+Windows):
+
+```json
+{
+  "sweep_sec": 120,
+  "stall_after_min": 10,
+  "jobs": [
+    { "id": "issue-31", "events_file": "<path>", "report_path": "<path>",
+      "worktree": "<path>", "duration_hint_min": 0 }
+  ]
+}
+```
+
+The watchdog detects mechanically and never kills, nudges, or judges. It exits
+with typed evidence; the Lead rules on it:
+
+| Exit | Prefix | Meaning |
+|---|---|---|
+| 0 | `WATCHDOG: ALL_DONE` | every job report exists, with path + byte-size evidence |
+| 2 | `WATCHDOG: INTEGRATED` | a worktree or events file vanished because the Lead integrated it mid-sweep |
+| 3 | `WATCHDOG: STALL` | file growth and process activity both stopped past `stall_after_min` plus any duration hint |
+| 4 | `WATCHDOG: REPEAT` | the last four parsed command events were identical and need an intentional-vs-stuck ruling |
+
+A job is DONE only when its report's final non-blank line starts with `STATUS:`.
+Report existence alone is not done. Liveness is output-file growth plus
+process-tree activity, weighed against any duration hint — never wall-clock alone.
+
+## Monitor fallback template
+
+Use only when the backend cannot wake the Lead from a background process exit; it
+counts against the concurrency cap while running.
+
+<!-- lead-monitor-fallback-template:start -->
+```text
+You are the detection-only fallback monitor for this dispatch wave. You never
+kill, nudge, or decide -- you only observe and report evidence.
+
+In-flight jobs:
+- Issue #<n>, events <path>, report docs/jobs/<issue-slug>-01.md,
+  worktree <path>, duration hint <hint or none>.  (one line per job)
+
+Sweep every ~10 minutes. For each job, check events/report byte growth, process
+activity by command-line/worktree match, and repeated identical commands in the
+tail. A quiet events file on a single sweep is normal model thinking.
+
+Quiet exit is allowed ONLY when, for every job, you list the report path and byte
+size as evidence. If a worktree or events file vanished because the Lead
+integrated the job mid-sweep, exit INTEGRATED and list the vanished path. If you
+cannot verify something from this sandbox, state what you cannot verify rather
+than assuming the job is done. Any stall or repeat concern exits immediately with
+the job id, minutes since last growth, process evidence, and a tail excerpt.
+```
+<!-- lead-monitor-fallback-template:end -->
+
+## Respawn-with-answer template
+
+Respawn-over-resume is the default recovery: a fresh builder spawns into the same
+issue's job. The respawn block is built from four pieces — the original issue
+body (unchanged), the Lead's answer or ruling (posted as an issue comment first,
+copied verbatim into the spawn context), what the previous session completed
+(read from its job report and the worktree's actual `git status`/`git diff`,
+never assumed), and the unchanged boundaries.
+
+```text
+You are resuming issue #<n>. Do not redo completed edits; working-tree edits
+survived unless the command output below proves otherwise.
+
+Previous session completed (from docs/jobs/<issue-slug>-01.md and worktree state):
+<summary of file:line evidence>.
+
+Lead's answer/ruling (also posted on issue #<n>):
+<answer, diagnosis, or rescue root cause>.
+
+Required route-around (sandbox-hang cases only):
+- Run exactly: <command with in-workspace temp/cache paths>.
+- Run check commands sequentially only.
+
+Boundaries remain:
+- MAY TOUCH: <files>
+- MUST NOT TOUCH: <files>
+- Report path: docs/jobs/<issue-slug>-01.md
+- End with exactly one STATUS line.
+```
+
+## Builder block template
+
+```text
+Execute the spec below. Operating rules:
+
+PHASE 0 - Before any code: reply with your plan and EVERY disagreement you have
+with this spec, with reasons, citing real files in this repo. Silent compliance
+is a failure. Silent scope additions are a failure. If you have no disagreements,
+state what you checked before concluding the spec is sound. Verify the named
+APIs/formats/versions against the live dependencies before planning around them.
+
+PHASE 1 - The files under docs/checks/ are read-only at all times; editing them
+fails the slice regardless of results.
+
+PHASE 2 - Build YOUR JOB ONLY: exactly the files listed in BOUNDARIES. Files
+outside your job belong outside your authority - touching them fails your job. No
+placeholder implementations - search the codebase before implementing; full
+implementations only. No silent fallbacks or success-shaped defaults - never
+swallow an error to make output look right. No unrequested backwards-
+compatibility shims. Fail loudly, with context. Exception: fallbacks or compat
+code are allowed only when the spec explicitly requests them. Verify your work by
+running the job's check commands and record the verbatim output. Do NOT commit -
+the Lead commits and merges after verification. Do NOT delete lock files or
+escalate privileges if a git command fails; record the exact error and continue.
+
+SANDBOX POLICY - All temp/basetemp/cache paths MUST be inside the workspace
+(.lead/tmp/<purpose>); never system temp. Run check commands SEQUENTIALLY. The
+spec may declare duration hints for known-long commands; they are context, not
+kill ceilings. If a command appears stalled - no output growth and no process
+activity well past its hint - record the exact command and stop the job; the
+watchdog and Lead own stall handling. A filesystem/sandbox error on a path is
+environmental: record it and route around it - never retry the same path.
+
+When done, write your job report to docs/jobs/<issue-slug>-01.md with RAW results
+only - tables, numbers, command output - no interpretation. Every status claim
+must be backed by a command result from this run. Mirror your final STATUS line
+as a comment on your issue when gh is available; otherwise write "MIRROR: LEAD"
+in the report and continue. End the report with exactly one status line:
+STATUS: COMPLETE | COMPLETE_WITH_CONCERNS (list them) | BLOCKED (exact blocker + what you tried).
+Verdicts belong to the reviewer and the human. Persist until your job is handled
+end to end.
+
+=== OBJECTIVE (and why) ===
+...
+=== OUTPUT FORMAT ===
+...
+=== TOOL GUIDANCE (verification commands; verify-against-reality list) ===
+...
+=== BOUNDARIES (may touch / must not touch / out of scope) ===
+...
+=== DISAGREEMENT RULINGS (from last session) ===
+...
+=== ACCEPTANCE CHECKS (frozen at docs/checks/<slice>.md - read-only) ===
+...
+```

package/skills/lead/loop.md

@@ -0,0 +1,103 @@
+# Factory-loop reference
+
+The loop is one Lead session that runs the factory to completion after approval.
+GitHub issues carry coordination state; git carries specs and frozen checks. The
+Lead dispatches the ready issues, sleeps, and wakes only on an event.
+
+Parallel rules: reviewers dispatch immediately and run concurrently for every
+DONE, never queued behind another review; the ready-issue frontier recomputes on
+every merge, not at wave boundaries; independent bookkeeping batches into
+parallel calls; merges, synthesis, and the critic pass stay serial by design.
+
+## Factory block procedure
+
+1. **Dispatch the ready issues.** Compute the ready set (every issue whose
+   blockers are closed), up to 5 builder jobs plus one watchdog (see `dispatch.md`
+   "## Watchdog dispatch"). Check `docs/STOP` and `docs/PAUSE` before every wave.
+2. **Sleep.** Zero Lead work between dispatch and the next event — no polling.
+3. **Wake on exactly one event:**
+   - **Job DONE.** Send the fixed reviewer template to one fresh reviewer; record
+     the verdict as an issue comment; merge on PASS, diagnose on FAIL.
+   - **Job BLOCKED.** A blocker comment is a completion event. Read it, rule an
+     answer, and respawn a fresh builder with the answer in its spawn context
+     (`dispatch.md` "## Respawn-with-answer template"). A running job never
+     re-reads its own comments — the spawn context is the only delivery channel.
+   - **Watchdog ANOMALY.** Read the evidence and rule one of: healthy-long-run
+     (relaunch the watchdog, sleep again), needs a nudge or answer, or wedged
+     (kill the job, discard its worktree, respawn from the frozen check with a
+     route-around).
+4. **Recompute the ready set.** Closing an issue may unblock others.
+5. **Repeat** until no issues remain open, then post the end-of-run digest.
+
+## Watchdog protocol
+
+Launch the script watchdog at wave dispatch; its typed exit wakes the Lead.
+
+- Exit 0 `ALL_DONE` -> proceed to the review backlog for every report listed by
+  path and byte size.
+- Exit 2 `INTEGRATED` -> benign mid-sweep integration; relaunch if jobs remain.
+- Exit 3 `STALL` -> run the rescue ladder: inspect the named job, kill stuck
+  children if needed, discard a wedged worktree, and respawn from the frozen
+  check with a route-around.
+- Exit 4 `REPEAT` -> rule intentional-vs-stuck before acting; deliberate polling
+  loops are a known false positive.
+
+Backends without background-exit notifications use the LLM fallback template in
+`dispatch.md`; it keeps the same detection-only boundary and per-job evidence.
+
+## Verdict comments
+
+Judgment is recorded on the issue, not in a file. One comment per reviewed job
+carries: per-check PASS/FAIL/INVALID, a checks-integrity verdict, a
+diff-vs-intent verdict, the slice call, and the decisive reason tied to raw
+evidence (exact `gh` command in `dispatch.md` "## Issue conventions"). The
+reviewer's intent context is exactly the frozen check file, the spec, the job
+report, and `docs/jobs/<issue-slug>-rulings.md`. That rulings file is Lead-owned,
+append-only, and committed before reviewer dispatch. No verdict comment on an
+issue means the next block must not build on it as accepted; you may re-run review
+with a fresh reviewer if evidence is missing, but may not fill in a verdict from
+memory. The issue closes on merge.
+
+## Failure ladder
+
+First FAIL on an issue: diagnose from the reviewer's evidence (not the full
+diff), optionally fan out researchers (`research.md`) to inform the diagnosis,
+fix the input — issue text, missing context, or a forbidden-pattern note — and
+respawn a fresh builder at the same tier. Tier is set once, at decomposition, and
+never changes because a job failed. Second FAIL on the same issue after an
+intervention: re-decompose the issue or escalate to the digest. A merge conflict
+is a decomposition failure, not a build failure: kill the conflicting job and
+re-slice; never hand-resolve builder conflicts.
+
+## Escalation digest
+
+Batched on the tracking issue instead of interleaved per-job noise: completed and
+failed jobs with verdicts; open blockers and the answers given; decisions the
+approved spec genuinely does not answer. Ask-the-human items are batched here
+unless a hard stop requires an immediate stop.
+
+## Hard stops
+
+| Situation | Hard stop |
+|---|---|
+| `docs/STOP` exists | Stop before dispatching the next wave. |
+| `docs/PAUSE` exists | Finish in-flight jobs; dispatch nothing new; ask the human. |
+| No verdict comment for completed work | Do not build on it as accepted. |
+| Builder touched `docs/checks/` | Automatic FAIL for that job. |
+| Merge conflict | Decomposition failure: kill the job, re-slice. |
+| Second FAIL on the same issue | Re-decompose or escalate to the digest. |
+| Two consecutive KILLs | Stop the factory and ask the human. |
+| Watchdog reports an anomaly | Rule on it before any further dispatch on that job. |
+| Blocker collides with a recorded assumption | Ask the human; a spec decision surfacing late. |
+| Session context degrades | End the session; the next session grounds from the tracker and git. |
+| Scope grows beyond the approved spec | Stop the factory. |
+| High-stakes issue | Add cross-model review before CONTINUE. |
+
+## Context discipline
+
+- Delegate heavy reading to reviewer, watchdog, or builder subagents; the Lead
+  stays thin and never reads a full diff directly.
+- The tracker and git are the memory: specs, frozen checks, verdict comments, and
+  job reports carry state across sessions, not the conversation.
+- Compact proactively when the harness supports it. Ending a degraded session is
+  free because the tracker and git are the memory.

package/skills/lead/models.json

@@ -0,0 +1,34 @@
+{
+  "//": "Provider registry for techlead-loop model routing. Edit this ONE file when a model generation ships or a CLI flag changes. `.lead/models.json` (repo) or `~/.lead/models.json` (user) can add or override providers without touching the skill.",
+  "providers": {
+    "claude": {
+      "cli": "claude",
+      "kind": "claude",
+      "default_model": "fable",
+      "default_effort": "xhigh",
+      "efforts": ["low", "medium", "high", "xhigh", "max"],
+      "models": {
+        "fable": "claude-fable-5",
+        "opus": "claude-opus-4-8",
+        "sonnet": "claude-sonnet-5",
+        "haiku": "claude-haiku-4-5"
+      },
+      "tier_down": {
+        "fable": "sonnet",
+        "opus": "sonnet",
+        "sonnet": "haiku"
+      }
+    },
+    "codex": {
+      "cli": "codex",
+      "kind": "codex",
+      "default_model": "best",
+      "default_effort": "xhigh",
+      "efforts": ["low", "medium", "high", "xhigh"],
+      "models": {
+        "best": "gpt-5.5"
+      },
+      "tier_down": {}
+    }
+  }
+}

package/skills/lead/research.md

@@ -0,0 +1,76 @@
+# Inline research fan-out (for the build loop)
+
+Read this only when a research trigger fires inside the factory (an oddity, a
+failure diagnosis, a load-bearing fact the spec depends on). The fan-out uses the
+`researcher` role as parallel web-research subagents — read-only, live search, on
+the flat-rate subscription — and the Lead keeps all judgment: it verifies the
+load-bearing claims and writes the spec itself. For discovery-scale research, use
+the separate `/lead-research` skill; this is the slice-scale version.
+
+## Fan out
+
+Resolve the researcher model with `python skills/lead/config.py --role
+researcher`. Decompose the question into 3–5 narrow, NON-OVERLAPPING questions —
+cover different angles, not one angle five times. Typical split: official
+docs/reference; changelog / breaking changes; community failure reports;
+alternatives/comparisons; security/operational constraints.
+
+One fresh researcher per question, all launched in parallel in the background.
+Take the exact command from the resolver; for Codex it looks like:
+
+```bash
+codex exec -C <repo-root> --sandbox read-only -c web_search="live" \
+  -m <model-id> -c model_reasoning_effort="<effort>" \
+  -o .lead/research/<NN>-<topic>.md \
+  - < .lead/research/<NN>-<topic>.prompt.md
+```
+
+Write each research block to a `.prompt.md` file and pass it via stdin (`-`),
+never as a shell argument — quote-mangling shells make the CLI hang on stdin.
+Launch ONE canary researcher and confirm it starts cleanly before fanning out. If
+the resolved researcher is a Claude row or Codex is unavailable, run the fan-out
+as read-only Claude subagents with web search — the block below works verbatim.
+
+- `--sandbox read-only`: researchers never write to the repo.
+- Effort is coverage-tier (`high`, not `xhigh`); synthesis happens on the Lead's
+  side.
+- Scope each researcher to ≤5 subjects and put hard context rules in the block
+  (snippet over page; quote ≤2 sentences; stop the moment you can answer) — a
+  researcher that fills its context window dies without writing its output.
+  Bisect and re-dispatch a dead researcher; do not re-run it as-is.
+
+## Research block template
+
+```text
+You are a web research agent. Answer ONE question. Do not write code, do not make
+recommendations - judgment belongs to the Lead who reads your output.
+
+QUESTION: <one narrow question>
+
+OUTPUT FORMAT - a markdown report, <= ~2,500 tokens total:
+- Findings as bullets. EVERY finding carries: a source tag (e.g. [S3]), source
+  date (if shown), the exact figure or a short direct quote, and a confidence tag
+  (high = primary source / med = reputable secondary / low = single blog or forum).
+- Prefer primary sources (official docs, changelogs, release notes, source code)
+  over blog posts. Record exact version numbers and dates.
+- When sources disagree, report the disagreement - do not resolve it.
+- If you cannot find evidence, write NOT FOUND - never infer or fill gaps from
+  prior knowledge without flagging it.
+- End with a numbered source list - every source URL appears EXACTLY ONCE - then
+  the 2-3 findings most likely to change an implementation decision.
+```
+
+## Gather (Lead — your work, not a subagent's)
+
+1. Read every findings file in `.lead/research/`.
+2. Identify the **load-bearing claims** — the facts the spec will depend on (an
+   API shape, a version constraint, a limit, a deprecation). Adversarially verify
+   each against a second independent source or the live dependency itself.
+   Discard single-source low-confidence claims or mark them as open questions.
+3. Write `docs/spec/<slice>.md`: problem, decision + why, requirements, non-goals,
+   verified facts **with citations**, open questions for the human. You write it;
+   researchers gather, you judge.
+4. Commit the spec. Raw findings stay in `.lead/research/` (gitignored) — only the
+   distilled, cited spec is repo memory.
+5. The slice spec references this spec instead of restating it; the builder's
+   PHASE 0 is expected to challenge the spec's claims.

package/skills/lead/status.ps1

@@ -0,0 +1,114 @@
+param([string]$RepoRoot = ".")
+
+# Read-only status tree for a techlead-loop run (Windows). Reads run artifacts
+# plus `gh`; never a new state store. Callers print the output verbatim.
+
+$root = (Resolve-Path -LiteralPath $RepoRoot).Path
+if (-not (Test-Path -LiteralPath $root)) { Write-Output "unreadable repo: $RepoRoot"; exit 1 }
+
+$useColor = ($Host.UI.RawUI -ne $null) -and (-not $env:NO_COLOR)
+function Glyph($ch, $code) { if ($useColor) { "`e[$($code)m$ch`e[0m" } else { $ch } }
+$gMerged   = Glyph ([char]0x2713) 32
+$gReview   = Glyph ([char]0x25D0) 36
+$gBlocked  = Glyph "!" 31
+$gReported = Glyph ([char]0x25A3) 35
+$gBuilding = Glyph ([char]0x25CF) 34
+$gQueued   = Glyph ([char]0x2298) 33
+$gReady    = Glyph ([char]0x25CB) 37
+
+function NewestSpec {
+    $specDir = Join-Path $root "docs/spec"
+    if (-not (Test-Path -LiteralPath $specDir)) { return "unknown" }
+    $newest = Get-ChildItem -LiteralPath $specDir -Filter *.md -File -ErrorAction SilentlyContinue |
+        Sort-Object LastWriteTimeUtc -Descending | Select-Object -First 1
+    if ($newest) { return $newest.Name } else { return "unknown" }
+}
+function TailText($Path) {
+    if (-not (Test-Path -LiteralPath $Path)) { return "" }
+    $bytes = [System.IO.File]::ReadAllBytes($Path)
+    $len = [Math]::Min(4096, $bytes.Length)
+    $tail = $bytes[($bytes.Length - $len)..($bytes.Length - 1)]
+    return [System.Text.Encoding]::UTF8.GetString($tail)
+}
+function StatusLine($Path) {
+    $s = ""
+    foreach ($line in ((TailText $Path) -split "`r?`n")) {
+        if ($line -match '^\xEF\xBB\xBF?STATUS:') { $s = ($line -replace '^\xEF\xBB\xBF?STATUS:\s*', '') }
+        elseif ($line -match '^STATUS:') { $s = ($line -replace '^STATUS:\s*', '') }
+    }
+    return $s
+}
+function Slugify($s) { (($s.ToLower() -replace '[^a-z0-9]', '-') -replace '-+', '-').Trim('-') }
+function ReportPath($slug) {
+    $inWt = Join-Path $root ".lead/wt/$slug-01/docs/jobs/$slug-01.md"
+    if (Test-Path -LiteralPath $inWt) { return $inWt }
+    return (Join-Path $root "docs/jobs/$slug-01.md")
+}
+function Phase($slug, $state, $blockers) {
+    if ($state -eq "CLOSED") { return "$gMerged MERGED" }
+    if ($state -eq "OPEN" -and $blockers) { return "$gQueued QUEUED" }
+    $rep = ReportPath $slug
+    $review = Get-ChildItem -LiteralPath (Join-Path $root ".lead/wt") -Filter "$slug-01.review*.md" -File -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ((Test-Path -LiteralPath $rep) -and $review) { return "$gReview REVIEWING" }
+    if ((StatusLine $rep) -like "BLOCKED*") { return "$gBlocked BLOCKED" }
+    if (Test-Path -LiteralPath $rep) { return "$gReported REPORTED" }
+    if (Test-Path -LiteralPath (Join-Path $root ".lead/wt/$slug-01")) { return "$gBuilding BUILDING" }
+    return "$gReady READY"
+}
+function TrackerLines {
+    $jq = '. as $all | ([ $all[] | select(.parent != null) | .parent.number ] | unique) as $pnums | ([ $all[] | select(.state == "OPEN") | select(.number as $n | $pnums | index($n)) ] | map(.number) | max) as $t | if $t == null then "NOOPENRUN" else ("TRACK\t\($t)", ($all[] | select(.parent != null and .parent.number == $t) | [ "SUB", (.number|tostring), .state, ((.blockedBy.nodes // []) | map(select(.state == "OPEN") | (.number|tostring)) | join(",")), .title ] | @tsv)) end'
+    if ($env:STATUS_GH_STUB -and (Test-Path -LiteralPath $env:STATUS_GH_STUB)) { return Get-Content -LiteralPath $env:STATUS_GH_STUB }
+    if (-not (Get-Command gh -ErrorAction SilentlyContinue)) { return $null }
+    Push-Location $root
+    try { gh issue list --state all --limit 200 --json number,title,state,parent,blockedBy --jq $jq } finally { Pop-Location }
+}
+
+$branch = "unknown"
+if (Test-Path -LiteralPath (Join-Path $root ".git")) {
+    $b = git -C $root branch --show-current 2>$null
+    if ($b) { $branch = $b.Trim() }
+}
+$trackerTsv = TrackerLines
+$tracker = ($null -ne $trackerTsv)
+$tracking = $null
+if ($tracker) {
+    foreach ($row in $trackerTsv) {
+        $cols = $row -split "`t"
+        if ($cols[0] -eq "TRACK") { $tracking = $cols[1] }
+    }
+}
+$slugDirs = Get-ChildItem -LiteralPath (Join-Path $root ".lead/wt") -Directory -Filter "*-01" -ErrorAction SilentlyContinue |
+    ForEach-Object { $_.Name -replace '-01$', '' } | Sort-Object -Unique
+
+if ((-not $tracker -or -not $tracking) -and -not $slugDirs) {
+    Write-Output "NO ACTIVE FACTORY RUN"
+    Write-Output "spec: $(NewestSpec)"
+    exit 0
+}
+Write-Output "STATUS TREE spec: $(NewestSpec) branch: $branch"
+if ($tracker -and $tracking) { Write-Output "tracker: #$tracking" }
+elseif ($tracker) { Write-Output "tracker: no open run" }
+else { Write-Output "tracker: unavailable (local view)" }
+Write-Output "LEAD: local view"
+$cfg = (Get-ChildItem -LiteralPath (Join-Path $root ".lead/tmp") -Filter "wd-*.json" -File -ErrorAction SilentlyContinue | Measure-Object).Count
+$proc = if (Get-CimInstance Win32_Process -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match 'watchdog\.(ps1|sh)' }) { "True" } else { "False" }
+Write-Output "WATCHDOG: process=$proc config=$cfg"
+
+if ($tracker -and $tracking) {
+    foreach ($row in $trackerTsv) {
+        $cols = $row -split "`t"
+        if ($cols[0] -ne "SUB") { continue }
+        $num = $cols[1]; $state = $cols[2]; $blockers = $cols[3]; $title = $cols[4]
+        $slug = Slugify $title
+        $p = (Phase $slug $state $blockers) -split ' ', 2
+        $extra = if ($p[1] -eq "QUEUED") { " blocked-by: $blockers" } else { "" }
+        Write-Output "$($p[0]) #$num $title .lead/wt/$slug-01$extra"
+    }
+} else {
+    foreach ($slug in $slugDirs) {
+        $p = (Phase $slug "" "") -split ' ', 2
+        if ($p[1] -in @("BUILDING", "BLOCKED", "REVIEWING", "REPORTED")) {
+            Write-Output "$($p[0]) $slug .lead/wt/$slug-01"
+        }
+    }
+}