@brunosps00/dev-workflow 2.2.0 → 2.3.0

package/scaffold/scripts/lib/workflow-contract.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const tools = new Set(['local', 'codex', 'claude', 'copilot']);
+const tiers = new Set(['light', 'standard', 'heavy']);
+
+// A small executable contract for the agent-authored execution-plan.json.
+// This validates assignments, not account access or authorization on its own.
+export function validatePlan(plan) {
+  const issues = [];
+  if (!plan || !['1.0', '1.1'].includes(plan.schema_version)) return ['Unsupported execution plan schema'];
+  if (!Array.isArray(plan.tasks) || !plan.tasks.length) return ['tasks must be a nonempty array'];
+  if (typeof plan.approved !== 'boolean') issues.push('approved must be a boolean');
+  const ids = new Set();
+  for (const task of plan.tasks) {
+    if (!task || typeof task.id !== 'string' || !task.id.trim()) {
+      issues.push('Every task needs a nonempty string id');
+      continue;
+    }
+    if (ids.has(task.id)) issues.push(`Duplicate task ${task.id}`);
+    ids.add(task.id);
+    if (!Array.isArray(task.depends_on) || task.depends_on.some(id => typeof id !== 'string')) issues.push(`${task.id}: depends_on must be a string array`);
+    if (plan.schema_version === '1.1' && !task.execution) issues.push(`${task.id}: missing execution assignment`);
+    if (task.execution) {
+      const e = task.execution;
+      if (typeof e !== 'object' || Array.isArray(e)) { issues.push(`${task.id}: execution must be an object`); continue; }
+      if (!tiers.has(e.complexity)) issues.push(`${task.id}: invalid complexity`);
+      if (typeof e.rationale !== 'string' || !e.rationale.trim()) issues.push(`${task.id}: missing rationale`);
+      if (!Array.isArray(e.agents) || e.agents.some(a => typeof a !== 'string')) issues.push(`${task.id}: agents must be a string array`);
+      for (const assignment of [e, ...(Array.isArray(e.fallbacks) ? e.fallbacks : [])]) {
+        if (!assignment || typeof assignment !== 'object' || Array.isArray(assignment)) { issues.push(`${task.id}: invalid fallback assignment`); continue; }
+        if (!tools.has(assignment.tool)) issues.push(`${task.id}: invalid tool`);
+        if (typeof assignment.model !== 'string' || !assignment.model.trim()) issues.push(`${task.id}: missing model`);
+        if (typeof assignment.effort !== 'string' || !assignment.effort.trim()) issues.push(`${task.id}: missing effort`);
+        if (assignment.tool !== 'local' && [assignment.model, assignment.effort].includes('inherit')) issues.push(`${task.id}: external assignments must resolve model and effort`);
+      }
+      if (e.fallbacks !== undefined && !Array.isArray(e.fallbacks)) issues.push(`${task.id}: fallbacks must be an array`);
+    }
+  }
+  const tasks = new Map(plan.tasks.filter(t => t?.id).map(t => [t.id, t]));
+  const visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) { issues.push(`Dependency cycle at ${id}`); return; }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of tasks.get(id)?.depends_on || []) {
+      if (!ids.has(dep)) issues.push(`${id}: unknown dependency ${dep}`);
+      else visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  }
+  if (!issues.length) for (const id of ids) visit(id);
+  return issues;
+}
+
+export function resolveAssignment(plan, taskId, availableTools) {
+  const issues = validatePlan(plan);
+  if (issues.length) throw new Error(issues.join('; '));
+  if (plan.approved !== true) throw new Error('Execution plan is not approved');
+  const task = plan.tasks.find(t => t.id === taskId);
+  if (!task) throw new Error(`Unknown task ${taskId}`);
+  // Legacy plans never imply permission to start another CLI.
+  const assignment = task.execution || { tool: 'local', model: 'inherit', effort: 'inherit', agents: [] };
+  const candidates = [assignment, ...(assignment.fallbacks || [])];
+  const chosen = candidates.find(c => availableTools.includes(c.tool));
+  if (!chosen) throw new Error(`No approved executor available for ${taskId}`);
+  return { ...chosen, agents: assignment.agents || [], fallback: chosen !== assignment };
+}
+
+export function readyTasks(plan, completedIds) {
+  const issues = validatePlan(plan);
+  if (issues.length) throw new Error(issues.join('; '));
+  const done = new Set(completedIds);
+  return plan.tasks.filter(t => !done.has(t.id) && t.depends_on.every(id => done.has(id))).map(t => t.id);
+}
+
+// Callers fingerprint actual inputs (including relevant untracked files) and
+// environment. Unknown values fail closed. Time/message boundaries are irrelevant.
+export function reusableEvidence(evidence, current) {
+  if (!evidence || evidence.exit_code !== 0 || !current) return false;
+  for (const key of ['command', 'input_fingerprint', 'environment_fingerprint']) {
+    if (typeof current[key] !== 'string' || !current[key] || evidence[key] !== current[key]) return false;
+  }
+  return Array.isArray(current.scope) && current.scope.length > 0 && Array.isArray(evidence.scope)
+    && current.scope.every(item => evidence.scope.includes(item));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [mode, file, taskId, available = 'local'] = process.argv.slice(2);
+    if (!['validate', 'resolve', 'ready'].includes(mode) || !file) throw new Error('Usage: workflow-contract.mjs validate|resolve|ready <plan.json> [task-id|completed-csv] [available-tools-csv]');
+    const plan = JSON.parse(readFileSync(file, 'utf8'));
+    if (mode === 'validate') {
+      const issues = validatePlan(plan);
+      console.log(JSON.stringify({ status: issues.length ? 'BLOCKED' : 'PASS', issues }));
+      if (issues.length) process.exitCode = 1;
+    } else if (mode === 'resolve') console.log(JSON.stringify(resolveAssignment(plan, taskId, available.split(','))));
+    else console.log(JSON.stringify(readyTasks(plan, taskId ? taskId.split(',') : [])));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/scaffold/skill-registry.json

@@ -9,7 +9,7 @@
       "trigger": "API QA, endpoint testing, HTTP recipe generation",
       "expected_output": "A selected API testing recipe and evidence path for the active stack.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true
@@ -22,7 +22,7 @@
       "trigger": "Docker Compose service selection or local infrastructure setup",
       "expected_output": "A selected service recipe and composition guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true
@@ -32,10 +32,10 @@
       "kind": "protocol",
       "tier": "core",
       "owner": "dw-codex-run,dw-claude-run,dw-copilot-run",
-      "trigger": "Fire an AI CLI (Codex/Claude/Copilot) in a dedicated git worktree to implement a prepared prompt; resumable per-task session; STOP for the gate",
-      "expected_output": "Audit-logged run with a 0-10 dual evaluation, a resumable session-id sidecar, and a STOP-for-gate Structured Return.",
+      "trigger": "Execute an approved task through a supported external CLI adapter",
+      "expected_output": "Reviewed task handoff with durable session, acceptance evidence and next task or blocker.",
       "load_policy": "lazy-references",
-      "context_limit": 20500,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -46,7 +46,7 @@
       "trigger": "Codebase indexing or codebase intelligence query",
       "expected_output": ".dw/intel index files or a cited answer from the index.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -57,7 +57,7 @@
       "trigger": "Council mode or high-impact architectural debate",
       "expected_output": "Advisor positions, tension synthesis, and decision recommendation.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -68,7 +68,7 @@
       "trigger": "Native Grill domain vocabulary: challenge fuzzy/overloaded terms, cross-check against code, persist a canonical glossary to .dw/domain",
       "expected_output": "Canonical terms with discouraged synonyms persisted lazily to .dw/domain (single or multi-context), or fuzzy-term findings.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": false,
       "bundled": true
     },
@@ -80,7 +80,7 @@
       "trigger": "Native Grill decision-tree interview: sharpen a plan/PRD to shared understanding, exactly one decision per turn with a recommended answer",
       "expected_output": "A dependency-ordered decision tree, resolved decisions with recommendations, and an explicit shared-understanding gate.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": false,
       "bundled": true
     },
@@ -92,7 +92,7 @@
       "trigger": "Bugfix, QA fix loop, or non-reproducible failure",
       "expected_output": "Six-step triage, root cause, guard, and verification path.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -103,7 +103,7 @@
       "trigger": "Task execution, plan-checking, waves, checkpoint recovery",
       "expected_output": "Plan-check verdict, wave execution report, or checkpoint summary.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -114,7 +114,7 @@
       "trigger": "Commit creation, branch hygiene, PR generation",
       "expected_output": "Atomic commit plan and git hygiene checks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -125,7 +125,7 @@
       "trigger": "Production critical bug, outage, incident, SEV workflow",
       "expected_output": "Incident triage, communication, resolution, and postmortem artifacts.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -136,7 +136,7 @@
       "trigger": "AI, LLM, RAG, classifier, agent, or tool-use feature",
       "expected_output": "Eval strategy, oracle choice, dataset requirements, and result checks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -147,7 +147,7 @@
       "trigger": "Task execution memory, checkpointing, compaction",
       "expected_output": "Updated workflow memory and task-local memory guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -171,7 +171,7 @@
       "trigger": "Code review, implementation review, or review consolidation",
       "expected_output": "Deduplicated findings ordered by defensible severity.",
       "load_policy": "always-small",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -205,7 +205,7 @@
       "trigger": "Refactor analysis, code smells, complexity, or behavior-preserving simplification",
       "expected_output": "Simplification target, risk, behavior-preserving checks, and recommendation.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -217,7 +217,7 @@
       "trigger": "Library/framework/API decision, technical research, dependency audit",
       "expected_output": "Cited source-grounded decision with version and retrieval date.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -228,7 +228,7 @@
       "trigger": "Writing, reviewing, or debugging tests",
       "expected_output": "Test placement, invariant, anti-pattern checks, and verification guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -239,7 +239,7 @@
       "trigger": "UI design, redesign, visual QA, accessibility, or frontend polish",
       "expected_output": "Grounding answers, state matrix, accessibility checks, and visual risks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -250,7 +250,7 @@
       "trigger": "Completion claim, commit, PR generation, or fixed bug status",
       "expected_output": "Fresh verification report with cited command evidence.",
       "load_policy": "always-small",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -288,7 +288,7 @@
       "trigger": "Security review, sensitive code, OWASP checks, auth/payment/input surfaces",
       "expected_output": "High-confidence security findings or explicit pass.",
       "load_policy": "lazy-references",
-      "context_limit": 14000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -300,7 +300,7 @@
       "trigger": "React/Next.js performance, hydration, data fetching, bundle or render issues",
       "expected_output": "Selected performance rule references and metric-driven recommendations.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true

package/scaffold/skills/dw-cli-run/SKILL.md

@@ -1,234 +1,50 @@
 ---
 name: dw-cli-run
-description: "Shared runner protocol for the dw-*-run commands (dw-codex-run / dw-claude-run / dw-copilot-run). Fires an autonomous AI CLI (Codex / Claude / Copilot) INSIDE a dedicated git worktree to implement a prepared prompt/spec, with streaming captured to a durable audit log, a resumable per-task session, a 0–10 dual evaluation, graded escalation, and a STOP for the human gate. Loaded by those commands — substitute the CLI-specific adapter table they supply. NEVER runs in the main checkout; NEVER auto-merges (the owner decides after the gate)."
+description: Execute an approved task through a Codex, Claude or Copilot CLI adapter, with isolated Git work, durable sessions and a reviewed handoff.
 allowed-tools:
-  - Bash
   - Read
-  - AskUserQuestion
+  - Write
+  - Bash
+  - Grep
+  - Glob
 ---
 
-# dw-cli-run — fire an AI CLI in the right worktree, audit it, keep the session, stop for the gate
-
-CLI-**agnostic** core protocol for the delegation step of `dw-codex-run` / `dw-claude-run` / `dw-copilot-run`: a
-**git worktree** holds a **prompt/spec** already prepared → this protocol fires the autonomous CLI there
-(streaming, non-blocking) → **captures the whole run to a durable audit log** → **keeps a resumable per-task
-session** → **evaluates the delivery 0–10** → escalates on failure → **STOPS for the gate** (merge is the owner's
-call). It exists because running these CLIs by hand is repetitive and risky: wrong worktree, hangs without a TTY,
-lost audit trail, and forgetting to measure quality before merge.
-
-> **Dual-use:** these CLIs perform **autonomous edits with auto-approve**. Confirm the **right worktree** and the
-> **scope** before firing. The isolated worktree is the mitigation that justifies the auto-approve flag.
-
-## The adapter table (supplied by the invoking command)
-The command that loaded you (`dw-codex-run` / `dw-claude-run` / `dw-copilot-run`) provides a **CLI adapter table**
-with these slots. Substitute them into the steps below — everything else is identical across CLIs:
-
-| Slot | Meaning |
-|---|---|
-| `DISPATCH` | first-run command (background, streaming → audit log, `</dev/null`) |
-| `STREAM` | flag(s) that make it emit parseable streaming events (JSON/JSONL) |
-| `MODEL` | flag that selects the model tier for this dispatch |
-| `EFFORT` | flag that selects the reasoning budget for this dispatch |
-| `AUTO` | auto-approve / non-interactive flag for a **WRITE** dispatch (justified by the isolated worktree) |
-| `AUTO_READONLY` | plan/sandbox flag for a **READ-ONLY** dispatch (makes edits impossible; no worktree needed) |
-| `NO_MCP` | flag that starts the CLI with no MCP servers (cold-start trim) |
-| `RESUME <id>` | re-run command that **continues the SAME session/context** by id |
-| `RESUME_LAST` | "resume the last session of this cwd" fallback |
-| `SESSION_ID` | how to obtain/fix the session-id (from the stream, a sidecar, or a flag) |
-| `DONE_SIGNAL` | the stream event that means the turn finished |
-| `USAGE` | where token usage appears in the stream |
-
-If the command did not supply an adapter table, return `BLOCKED` — this skill is not invoked standalone.
-
-## Dispatch modes — WRITE and READ-ONLY
-
-Every dispatch declares its mode up front; it decides isolation, permission flags, and gate. **WRITE** edits and
-commits → worktree mandatory, `AUTO`, one per worktree, full 0–10 gate. **READ-ONLY** reads/reviews/reports → no
-worktree, `AUTO_READONLY`, freely parallel, score the report without a re-run gate. Per-mode detail:
-`references/dispatch-tuning.md`.
-
-<critical>RULE (hard) — a WRITE dispatch runs **only** inside a **dedicated git worktree** (off main). **NEVER** fire a WRITE dispatch in the repo's **main checkout** (the root tree on the primary branch, e.g. `~/code/<project>` on `main`) — the CLI edits autonomously and that would corrupt the owner's active tree. If the target is the main checkout, **ABORT** (`BLOCKED`) and instruct: create/use a worktree first (`git worktree add ../<project>-<slug> -b <branch> main`). Mandatory check before running: `git worktree list` → the target is a secondary worktree (not the one flagged as main) **AND** the CLI's `cwd` is that worktree.</critical>
-
-<critical>A READ-ONLY dispatch MAY run in the main checkout, because the read-only flags make autonomous edits impossible — that is the entire reason the worktree rule exists. This is NOT a relaxation of the WRITE rule: if the dispatch can write, it is a WRITE dispatch and the worktree is mandatory. When in doubt, treat it as WRITE. Never pass an auto-approve flag on a dispatch declared READ-ONLY.</critical>
-
-## Pre-flight (fail early > run in the wrong place)
-1. `<cli> --version` answers (CLI + credentials present). Missing → `BLOCKED`.
-2. **Declare the mode** (WRITE or READ-ONLY) and pick the matching `AUTO`/`AUTO_READONLY` slot.
-3. WRITE only: `git worktree list` — confirm the target worktree and that it is **not** the main checkout. Missing →
-   create it with `/dw-worktree create <slug>` (naming convention + install/build prep), never a bare `git worktree add`.
-4. A **prompt/spec** exists (what the CLI receives). Common conventions: `.dw/spec/<slug>/codex-prompt.md`
-   (dev-workflow), `PROMPT.md`, `TASK.md`, or a path the owner names. **Read it** — it is the scope/fence/gate.
-
-## Cold-start cost
-A spawned CLI does not share the parent session's prompt cache and boots every configured MCP server first — on a
-small task that startup can outweigh the task. **Default: pass the adapter's `NO_MCP` slot on every dispatch whose
-prompt does not name an MCP capability.** Tool restriction, config trimming, and how to bind
-`.dw/config/routing.json` are in `references/dispatch-tuning.md` — read it when a dispatch feels overpriced.
-
-## Where to run — pick the VEHICLE (the main thread NEVER runs inline)
-The main thread **orchestrates**; execution goes to one of these:
-- **Workflow (PREFERRED)** — when there is a pipeline (CLI implements → evaluate 0–10 → **gate fan-out**). One
-  workflow agent runs the CLI (network OK). Shows in `/workflows` + parallelizes. Structure as separate
-  **phases/agents**: `[agent that runs the CLI]` → `[gate agents]`.
-- **Single Agent (subagent)** — one-off dispatch of ONE run, no gate fan-out. Lighter; background; returns the
-  report. Does not show in `/workflows`.
-- **Background Bash** — fallback only (no workflow/agent harness). Needs network → run un-sandboxed so the CLI can
-  reach its API.
-
-> **Nesting:** the agent running the CLI **must not spawn further subagents** (nesting limit; Workflow nests only
-> 1 level). The gate is **another phase/agent** of the workflow — never a sub-spawn from inside the runner agent.
-
-## Progress loop (auto-arm)
-WRITE runs invoke `/dw-report` before dispatch (idempotent while `.dw/reports/.active.json` is live; skipped when
-`DW_REPORT_AUTO=off`; `armed_by: dw-cli-run`). Ticks read the stream for measurable progress (`grep -c
-'"type":"item.completed"'`, last `command_execution`); the gate verdict is `finished` → final report + auto-disarm.
+# CLI task execution
 
-## Protocol
-1. **Resolve target.** Worktree + prompt path (from the user or inferred). Derive a `<slug>` (the spec slug or
-   worktree tag) — it keys the durable audit log and the session sidecar.
-2. **Model + effort — routing table first, size only what it misses.** `.dw/config/routing.json` is the default
-   source: commit type → tier (`by_commit_type`), raised if the fence matches `escalate_on_surface`, then tier →
-   `MODEL`/`EFFORT` for the brand. Costs no reasoning, reproducible. Absent, or no declared type? Size it: propose
-   with a one-line rationale (signals: task count, fence breadth, sensitive surface, architectural vs mechanical,
-   E2E/secure-audit in the gate); the owner confirms or overrides. Either way start **one notch below the
-   ceiling**. A tier that keeps escalating is a routing bug — name the entry that mis-sized it.
-3. **Set up the durable audit dir (OUTSIDE the worktree).** `<AUDIT>=<main-repo-or-home>/.dw/cli-run/` — it MUST
-   survive `git worktree remove` (the worktree's `QA/` is wiped on merge). Files: `<AUDIT>/<slug>.log` (stream),
-   `<AUDIT>/<slug>.session` (session-id sidecar), optionally `<AUDIT>/<slug>.last.md` (final message).
-4. **Dispatch (first run) in BACKGROUND with streaming → durable audit log.** Use the adapter's `DISPATCH`:
-   ```bash
-   cd <WORKTREE> && <DISPATCH ... STREAM AUTO ... "$(cat <PROMPT_PATH>)"> </dev/null \
-     > <AUDIT>/<slug>.log 2>&1     # durable streaming audit trail
-   ```
-   - `</dev/null` ALWAYS (no TTY → hang). `STREAM` = parseable events; **don't** swallow everything with
-     `2>/dev/null`.
-   - **The stream log IS the audit trail (always capture).** It records, live and progressively, EVERYTHING the
-     CLI does: each shell `command`, item started/completed, the CLI's `agent_message` (reasoning + answers),
-     tool-calls, and the final `DONE_SIGNAL` (with `USAGE`/tokens). A "last message" capture (`-o` and friends)
-     holds only the **final** message; the stream holds the **whole path**.
-   - **Durability (critical for "audit later"):** write the stream log to a dir **outside** the worktree (step 3).
-     If it lived in the worktree's `QA/`, post-merge cleanup would delete it and the audit would vanish. Audit
-     later: shell commands `grep -oE '"command":"[^"]*"' <log>`; CLI reasoning/answers `grep '"agent_message"'
-     <log>`; tokens via the adapter's `USAGE` field; a readable transcript = `agent_message` + `command` in file
-     order.
-5. **SESSION PER TASK (the heart) — capture on first run, resume by id.**
-   - **First run:** obtain the **session-id** per the adapter's `SESSION_ID` (from the stream, a sidecar, or a
-     fixed flag) and write it to the durable sidecar `<AUDIT>/<slug>.session` (one line: the id). This sidecar
-     lives outside the worktree → it survives `git worktree remove`.
-   - **Resume the SAME context:** read `<AUDIT>/<slug>.session` and re-run the adapter's `RESUME <id>` with the
-     follow-up prompt → the CLI continues the **same session/context** (its reasoning, the files it already
-     touched, the gate state). This is how "come back to the C6 run with full context" works: re-run with the id.
-   - **Fallback:** if the sidecar is missing, the adapter's `RESUME_LAST` resumes the last session of this cwd
-     (worktree = the session's cwd), so context is recoverable as long as you run from the same worktree.
-   - Always record the session-id + sidecar path in the Structured Return (Artifacts) so a later turn can resume.
-6. **Detect "DONE" — by the stream, NEVER by `pgrep` of the worktree path.** The done signal is the adapter's
-   `DONE_SIGNAL` in the stream log **+** the worktree showing a commit/report (`git -C <worktree> log`, last
-   message filled). A `pgrep -f "<worktree-path>"` (or `-f "<...>/last-message"`) **self-matches your own grep
-   command** (the path is in the grep's argv) → false "running" that can hold a **READY** delivery for hours (and
-   a `until ! pgrep ...` waiter with that pattern **never terminates**, since it sees itself alive). In background
-   (`run_in_background`/Workflow), the **completion notification** is the signal. If you truly need pgrep,
-   restrict to `pgrep -af "<cli> "` and filter `/proc/<pid>/cmdline` — never pgrep the raw path.
-7. **Gate needs network?** Auto-approve modes that keep a sandbox **block network** for the CLI's shell commands →
-   `install`/build/test/E2E fail with `EAI_AGAIN`. If the prompt tells the CLI to run the gate, the adapter's
-   `AUTO` flag must be the **network-allowed** variant (full access) so the CLI runs the gate and self-validates.
-   Justified because the **hard RULE** guarantees an isolated worktree. Without network in the gate, the CLI only
-   implements and reports `blockers` (the gate then sits with the parent).
-8. **Read-only / analysis mode:** when only reviewing (no edits), use the adapter's read-only variant and drop the
-   auto-edit flag.
+Use with `dw-codex-run`, `dw-claude-run`, or `dw-copilot-run`. The command supplies the adapter table; without it return `BLOCKED`. Read `.dw/references/execution-contract.md` for task assignments, dependency branches and resume state in an installed workflow. For standalone explicit runner requests, the user's prompt/spec supplies the assignment and authorized scope; do not require an unrelated PRD.
 
-## Mandatory evaluation — 0–10 score (ALWAYS)
-When the run finishes, the parent **evaluates the delivery and gives a 0–10 score** (10 = full conformance +
-complete delivery). Do not skip it — it is the signal that decides gate vs escalation. Score against the prompt:
-- **Scope/fence conformance** (did the ask; stayed inside the allowlist).
-- **Technical gate** (lint/test/build/E2E per the prompt — green?).
-- **Completeness** (every task/item delivered).
-- **Hygiene** (committed, no junk, nothing outside the fence, no forbidden deps).
-- **Quality / no regression.**
-**Acceptance bar: score ≥9** (owner's decision). Bands: **≥9** = acceptable (ready for the human gate); **6–8** =
-`FINDINGS` → **escalate** to reach ≥9; **<6** = failure → **escalate**. `BLOCKED` if the ladder is exhausted
-without reaching 9. Always show the score + a short per-criterion rationale — and for any criterion below its
-ceiling, **cite the specific gap** (the failing test, the file left out of fence), not just a label. Same
-evidence discipline as the five-axis rubric in `dw-review-rigor/references/self-eval-rubric.md`.
+## Adapter slots
 
-## Dual evaluation: the worker auto-gates → the parent re-gates
-A worker **can't grade its own exam alone** — hence two layers. (1) The worker loops at max effort until its own
-score is ≥9 with a green gate. (2) The parent independently re-runs the SAME gate and scores it, without trusting
-the self-score — **a worker never signs off on its own exam, even when that worker is Claude**. (3) The parent's
-score is what counts; a large gap means the worker overestimated → hand the gaps back via session resume and
-repeat. Record both scores and the gap. Prefer a **different brand** for the re-gate when one is installed; with
-only one, re-gate in a separate dispatch at a different tier — never reuse the executing session. Full protocol:
-`references/dispatch-tuning.md`.
+`DISPATCH`, `STREAM`, `MODEL`, `EFFORT`, `AUTO`, `AUTO_READONLY`, `NO_MCP`, `RESUME <id>`, `SESSION_ID`, `DONE_SIGNAL`, `USAGE` describe the provider interface. `AUTO` means the approved non-interactive permission configuration, not blanket permission bypass. Check the installed CLI's help before substituting flags. A CLI version does not prove credentials or model access.
 
-## Graded escalation on failure
-If the score is low / the gate failed / the CLI didn't finish, **re-run the SAME task one notch up** — gradual, no
-giving up on the first stumble, no jumping to the top. **Ladder:** effort first (`low`→`max`), then bump the model
-one tier and reset effort. **Stop** at score ≥9, or `BLOCKED` with evidence when the ceiling is exhausted.
-Announce each notch. Full ladder, continue-vs-restart rules, and how to read escalation as a routing-table signal:
-`references/dispatch-tuning.md`.
+## Isolation and permissions
 
-## Detailed output → direct the next step
-The delivery must be **detailed enough for the parent to decide the next step** — not an opaque "done". When it
-finishes: **read the final message in full** + scan the stream; complement with `git -C <worktree> status` and
-`git diff --stat` to see what truly changed (don't trust only what the CLI said). Then **produce a HANDOFF**: what
-the **gate** should focus on, what to **adjust/redo**, whether to **escalate**, what's **outside the fence /
-uncommitted**, and the **blockers** — record it in the Structured Return (Evidence/Artifacts/Next Step). If the
-report is shallow, treat as `FINDINGS` and ask for detail (resume) or reconstruct it from the diff first.
+- a WRITE dispatch runs **only** inside a **dedicated git worktree**. Create through `/dw-worktree create <slug>` when missing. Check the target is a secondary worktree and the CLI cwd matches it.
+- A READ-ONLY dispatch MAY run in the main checkout when effective tool permissions prevent writes. When in doubt, treat it as WRITE. Never pass an auto-approve flag on a dispatch declared READ-ONLY.
+- Worktrees isolate Git state, not the filesystem, network, credentials or other processes. Preserve platform permissions. Permission bypass is not a default and cannot be justified by a worktree alone.
+- One writer per worktree. Dependent tasks use the same execution branch sequentially; independent branches require a planned integration path.
+- Workers do not merge or push. The parent prepares the reviewed delivery and acts on separate integration/publication authorization.
 
-## Telemetry (tokens + time) — always report
-The stream ends with the adapter's `USAGE` block (token counts). Extract it from the log.
-- **Effective billable ≈ `(input − cached_input) + output`** — input is often ~95%+ cache; reporting only the raw
-  number misleads. Show both (raw + effective).
-- **Wall-clock:** the done event usually carries no duration → measure it yourself: wrap the dispatch with
-  `/usr/bin/time` or `date +%s` before/after. Report in minutes.
-- **Command count:** `grep -c '"command"' <log>` (effort proxy).
-- Record all of it under Structured Return → Telemetry. Useful for cost, escalation, and comparing fan-out phases.
+## Execute and continue
 
-## Discipline (when finishing)
-- **STOP — not merged.** The CLI implemented in the worktree; **run the gate** (tests/lint/build + review; if the
-  project uses dev-workflow: `/dw-review` + `/dw-qa` + `/dw-secure-audit`) **before** any merge.
-- **Merge = the owner's explicit decision.** Never automatic here.
-- **End of life = the same turn as the merge (hard).** When the owner merges: `/dw-worktree merge <slug>` (ff-only from the
-  main checkout → remove → branch delete → prune) or, if merged by other means, `/dw-worktree clean --apply` in that
-  same turn. Never `git worktree remove --force`; KEEP verdicts (dirty/unmerged/in-use) are reported, not forced.
-- Flag **uncommitted** work or edits **outside the fence**.
-- **Stop/abort a running CLI:** use **`TaskStop <task_id>`** (if `run_in_background`/Workflow) OR
-  **`git worktree remove --force <worktree>`** (pulls the rug — the CLI has nowhere to write and dies). Fallback:
-  `kill -9` **only** the PIDs from `pgrep -af "<cli> "` whose `/proc/<pid>/cmdline` matches the worktree tag.
-  **NEVER walk UP the process tree (ppid → ppid…) to kill "the supervisor":** the background CLI is a **child of
-  the Claude session itself** (`<cli> ← claude ← bash ← init`) → killing the ancestors **takes down the session**.
-  Apparent "respawns" are just the node workers of ONE run.
+1. Resolve the assignment from the approved task matrix; `.dw/config/routing.json` only supplies candidates for missing choices. Use current explicit instructions before saved assignments. Do not re-ask approved model/effort choices. An unavailable model uses only an approved fallback, otherwise report the exact blocker.
+2. Read the task prompt, relevant source and constraints. Check dependencies exist on the execution branch. Give the worker acceptance criteria, file scope, verification commands, permission boundaries, and a stopping condition: implemented and verified, or a concrete blocker. No recursive dispatch to another implementation CLI.
+3. Persist assignment, task identity, attempt, worktree/base, prompt and audit paths in `execution-state.json`. Store logs and session sidecars outside disposable worktrees. Capture the stream and final report; never discard error output. Do not claim the stream exposes private reasoning or every internal event.
+4. Run in a background process or bounded agent supported by the host. No mandatory extra agent layer. Read `references/dispatch-tuning.md` only for permission/MCP tuning, diagnostics or escalation.
+5. Persist the exact provider session ID. On resume, verify task/provider/worktree identity from state and audit. Missing sidecar: recover that task's session from its log; if unrecoverable, start a fresh session in the same worktree with the task, diff and checkpoint. Never blindly resume the latest session. Never reset/clean partial work to retry.
+6. Completion requires the terminal event, process outcome, and inspected files/report. A completed turn is not proof of task success. Poll the process handle or task notification; searching for the worktree path with `pgrep` can match the observer itself.
+7. Parent re-gate (independent): the parent re-gates by inspecting diff, acceptance criteria and blocking findings, and validating worker evidence with `dw-verify`. Reuse equivalent evidence rather than mechanically repeating the same suite. Send in-scope corrections to the same worker and continue approved dependent tasks.
+8. Keep model/effort on normal corrections. Escalate only on demonstrated capability limits to a supported, approved alternative. A numeric score is optional diagnostic information, never an acceptance gate. At an impasse preserve work, report the blocker, and continue independent authorized tasks.
 
-## Anti-patterns
-- Running in the main checkout / without confirming the worktree — corrupts the active tree. *(pre-flight 2)*
-- Merging/pushing inside the skill — merge lives outside, after the gate.
-- Skipping the 0–10 score — loses the quality/escalation signal.
-- Suppressing all output (or not capturing the stream to a log) — loses the audit of what the CLI did.
-- **Detecting "done" by `pgrep` of the worktree path** — self-matches your own command → false "running" that
-  holds ready deliveries. Use `DONE_SIGNAL` + worktree. *(step 6)*
-- **Killing the CLI by walking up the PID tree** — takes down the Claude session. Use `TaskStop`/`worktree
-  remove`. *(Discipline)*
-- Losing the session-id — without the sidecar you can't resume the SAME context; capture it on the first run.
+WRITE runs arm `/dw-report` once (`armed_by: dw-cli-run`) (idempotent, skipped when `DW_REPORT_AUTO=off`). On cancellation stop only the recorded task handle/PID, preserve files and logs, and disarm reporting. Never remove a worktree to kill its worker or walk up the process tree. The parent uses `/dw-worktree merge <slug>` for authorized merge and cleanup in the same turn (end-of-life); KEEP worktrees remain intact.
 
 ## Structured Return
-- **Status:** `PASS` · `FINDINGS` · `BLOCKED` · `NOT_APPLICABLE` — `PASS` = ran, score ≥9, stopped clean in the
-  right worktree, ready for the gate; `FINDINGS` = ran, score 6–8 or caveats (uncommitted/out-of-fence/partial);
-  `BLOCKED` = missing CLI/credential/worktree/prompt/adapter table, or escalation exhausted without reaching 9;
-  `NOT_APPLICABLE` = no worktree+prompt → still planning.
-- **Score:** **the parent's score** (0–10 — counts for acceptance, bar ≥9) + the **CLI self-score** + the **gap**;
-  per-criterion rationale (conformance/gate/completeness/hygiene/quality). Large gap = inflated self-score.
-- **Scope:** worktree + branch + prompt used; CLI + model + effort + sandbox/auto mode; escalation notches taken.
-- **Evidence:** path of the durable audit log + final-message file; stream JSONL excerpt; `git status`/diff of the
-  worktree post-run.
-- **Artifacts:** files created/changed (diff summary); **the session-id + sidecar path** (`<AUDIT>/<slug>.session`)
-  so a later turn can resume; the durable audit log path.
-- **Decisions:** model/effort and why; implementation vs read-only; continue (resume) vs reset on retry.
-- **Risks:** out of fence, uncommitted, gate not run, dual-use (autonomous edits).
-- **Telemetry:** tokens from the done event (input/cached/output/reasoning + **effective billable**) + **wall-clock**
-  + command count.
-- **Next Step:** "run the gate in the worktree; merge is the owner's decision" — and the exact resume command
-  (`RESUME <id>`) to continue this session.
 
-## Notes
-The CLI-specific flag names, model list, resume form, and session-id capture live in the **adapter table** of the
-invoking command (`dw-codex-run` / `dw-claude-run` / `dw-copilot-run`). This skill holds the CLI-agnostic protocol
-only; substitute the adapter slots and everything above applies unchanged.
+- **Status:** `PASS` task acceptance and required checks satisfied; `FINDINGS` corrections remain; `BLOCKED` unavailable executor, permissions or unresolved decision; `NOT_APPLICABLE` no CLI execution in scope.
+- **Scope:** task, worktree/branch/base, provider, model, effort, agents and permission mode.
+- **Evidence:** inspected diff, acceptance checks, verification records, process outcome and durable audit path.
+- **Artifacts:** changed files, commits, exact provider session ID and sidecar, execution state, report.
+- **Decisions:** approved assignment/fallback used, corrections, session recovery or new-session reason.
+- **Risks:** outstanding findings, partial work, missing checks or lost conversational context.
+- **Telemetry:** observed tokens, elapsed time and command counts when available; label unavailable fields, never estimate billing from undocumented fields.
+- **Next Step:** parent review/correction/next task, or concrete blocker; merge/push only under applicable authorization.