@brunosps00/dev-workflow 1.3.0 → 1.5.0

package/scaffold/rules/python.md

@@ -0,0 +1,18 @@
+# Baseline rules — Python (extends common)
+
+## Style
+- Type hints on public functions; run mypy/pyright in CI. `@dataclass(frozen=True)` for value types.
+- Follow PEP 8; format with black/ruff. Explicit over implicit.
+- Context managers (`with`) for every resource (files, connections, locks).
+
+## Errors
+- Catch the narrowest exception; never bare `except:`. Re-raise with context (`raise ... from e`).
+- Don't return `None` to signal failure where an exception or a typed result is clearer.
+
+## Testing
+- pytest; fixtures over setup/teardown boilerplate. Parametrize input variations.
+- Test behavior; avoid asserting internal call counts unless the calls ARE the contract.
+
+## Security
+- Parameterized queries only — never f-string/format SQL. Normalize/validate input at the edge.
+- `secrets` for tokens, not `random`. Never log credentials or PII.

package/scaffold/rules/react.md

@@ -0,0 +1,18 @@
+# Baseline rules — React (extends common + typescript)
+
+## Components
+- Function components + hooks only. Keep components small; lift state only as far as it's shared.
+- Derive, don't duplicate, state. Compute during render instead of syncing via effects.
+- List keys are stable ids, never the array index for dynamic lists.
+
+## Effects & data
+- `useEffect` synchronizes with external systems — not for deriving values or handling events.
+- Data fetching via a library (React Query / RTK Query / route loader) over ad-hoc effects; handle loading/error/empty.
+
+## Rendering
+- Every list/screen designs its empty, loading, and error states (see `dw-ui-discipline`).
+- Memoize (`useMemo`/`useCallback`/`memo`) only after measuring a real cost — not by default.
+
+## Security & a11y
+- Never `dangerouslySetInnerHTML` with unsanitized input; escape user content.
+- Semantic HTML + WCAG 2.2 AA floor: labels, focus-visible, keyboard nav, contrast (see `dw-ui-discipline`).

package/scaffold/rules/rust.md

@@ -0,0 +1,18 @@
+# Baseline rules — Rust (extends common)
+
+## Style
+- `Result<T, E>` for fallible ops; reserve `panic!`/`unwrap`/`expect` for truly unrecoverable code or tests.
+- Prefer borrowing over cloning; clone deliberately, not to silence the borrow checker.
+- Model the domain with enums + exhaustive `match`; make illegal states unrepresentable.
+
+## Errors
+- Propagate with `?`; enrich context (`thiserror` for libs, `anyhow` for apps) at boundaries.
+- No silent `let _ =` on a real error.
+
+## Testing
+- `#[cfg(test)]` unit tests near code; integration tests in `tests/`. Test the public API.
+- Meaningful `assert_eq!` messages; property tests (proptest) for invariants.
+
+## Security
+- Avoid `unsafe`; when unavoidable, encapsulate it and comment the invariants it upholds.
+- Don't `unwrap` on data you don't control; validate external input.

package/scaffold/rules/typescript.md

@@ -0,0 +1,23 @@
+# Baseline rules — TypeScript (extends common)
+
+## Types
+- `strict: true`. No `any` — use `unknown` + narrowing, generics, or a precise type. `as` casts are a smell.
+- Make illegal states unrepresentable: discriminated unions over boolean flags; `readonly` for immutability.
+- Export the narrowest surface; keep public types precise at boundaries.
+
+## Style
+- `const` by default; `let` only when reassigned; never `var`.
+- `async`/`await` over raw promise chains; always handle rejection.
+- Immutability via spread / `Readonly<T>`; avoid in-place array/object mutation.
+
+## Errors
+- Model expected failures as values (`Result`/union) where it aids callers; throw for truly exceptional.
+- Never `catch (e) {}` — at minimum log with context and rethrow or handle.
+
+## Testing
+- Vitest/Jest; type-level tests where a public generic contract matters.
+- Assert exported behavior, not private internals.
+
+## Security
+- Validate external input with a schema (zod/valibot) at the boundary; `as` does not enforce shape at runtime.
+- No `eval`/`Function` on user input; sanitize before `innerHTML`.

package/scaffold/rules-readme.md

@@ -23,3 +23,11 @@ Run the `/dw-analyze-project` command inside your AI assistant to scan your code
 These rules are automatically read by workflow commands (`create-prd`, `create-techspec`, `run-task`, etc.) to ensure generated artifacts follow your project's conventions.
 
 Re-run `/dw-analyze-project` whenever your stack or conventions change significantly.
+
+## Related: the curated baseline library
+
+This directory (`.dw/rules/`) is **analytical** — what the code IS. It is complemented by
+`.dw/rules-library/` — a **curated declarative baseline** (what good code SHOULD look like) shipped per
+stack, loaded lazily via `.dw/config/stack-mappings.json` — and by `.dw/constitution.md` — the principles
+your team commits to. `/dw-analyze-project` references the library to seed constitution proposals; you don't
+edit the library here. See `.dw/rules-library/README.md`.

package/scaffold/scripts/hooks/git-guardrails.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * dev-workflow git guardrails — Claude Code PreToolUse hook (matcher: Bash).
+ *
+ * Blocks irreversible git commands (force push, hard reset, clean -f, branch
+ * deletion, remote branch deletion). Everything else is allowed.
+ *
+ * Enforces the destructive-command rules from the `dw-git-discipline` skill at
+ * the harness level instead of relying on prose. Inspired by mattpocock/skills
+ * `git-guardrails-claude-code` (MIT).
+ *
+ * Contract: reads the PreToolUse payload as JSON on stdin, emits a
+ * permissionDecision via hookSpecificOutput. Fails OPEN — any parsing/runtime
+ * error allows the command, so a hook bug never blocks the user.
+ */
+
+const DANGEROUS = [
+  { re: /\bgit\s+push\b[^\n|&;]*(--force\b|--force-with-lease\b|\s-f\b)/, why: 'force push rewrites remote history' },
+  { re: /\bgit\s+push\b[^\n|&;]*(--delete\b|\s-d\b|\s:\S)/, why: 'deletes a remote branch' },
+  { re: /\bgit\s+reset\b[^\n|&;]*--hard\b/, why: 'hard reset discards uncommitted work and rewrites the branch' },
+  { re: /\bgit\s+clean\b[^\n|&;]*-[a-z]*f/, why: 'git clean -f permanently deletes untracked files' },
+  { re: /\bgit\s+branch\b[^\n|&;]*\s-D\b/, why: 'force-deletes a branch that may be unmerged' },
+  { re: /\bgit\s+checkout\b[^\n|&;]*\s(--\s+\.|\.\s*$)/, why: 'discards all local changes in the working tree' },
+];
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+function allow() {
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  );
+  process.exit(0);
+}
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    return allow(); // fail open
+  }
+
+  const command = payload && payload.tool_input && typeof payload.tool_input.command === 'string'
+    ? payload.tool_input.command
+    : '';
+  if (!command) return allow();
+
+  for (const rule of DANGEROUS) {
+    if (rule.re.test(command)) {
+      return deny(
+        `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
+          `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
+      );
+    }
+  }
+
+  return allow();
+}
+
+main().catch(() => allow());

package/scaffold/scripts/hooks/session-cost.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * dev-workflow session cost tracker — Claude Code SessionEnd hook.
+ *
+ * On session end, parses the session transcript (JSONL at `transcript_path`),
+ * sums token usage per model, estimates USD via ../lib/model-prices.json, and
+ * appends ONE cumulative row to .dw/metrics/costs.jsonl. The statusline and
+ * `/dw-context-budget` (Part B) read that file to report real spend.
+ *
+ * Token counts are what Claude Code records per assistant turn (each turn bills
+ * the full input, mostly cache_read); summing across turns matches billing.
+ * USD is a best-effort ESTIMATE from a local price table — tokens are exact.
+ *
+ * Contract: reads the SessionEnd payload as JSON on stdin. Fails SAFE — any
+ * error exits 0 without writing, so a hook bug never disrupts the session.
+ */
+
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOOK_DIR = dirname(fileURLToPath(import.meta.url)); // <root>/.dw/scripts/hooks
+const DW_DIR = resolve(HOOK_DIR, '..', '..'); // <root>/.dw
+const PRICES_PATH = join(HOOK_DIR, '..', 'lib', 'model-prices.json'); // .dw/scripts/lib/
+
+function readStdin() {
+  return new Promise((resolve_) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve_('');
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve_(data));
+    process.stdin.on('error', () => resolve_(''));
+  });
+}
+
+function loadPrices() {
+  try {
+    return JSON.parse(readFileSync(PRICES_PATH, 'utf-8')).models || {};
+  } catch {
+    return {};
+  }
+}
+
+function priceFor(models, model) {
+  return models[model] || models['_default'] || { input: 3, output: 15, cache_write: 3.75, cache_read: 0.3 };
+}
+
+// Sum per-turn usage from the transcript, grouped by model.
+function tallyTranscript(transcriptPath) {
+  const byModel = {};
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf-8');
+  } catch {
+    return byModel;
+  }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const msg = obj && obj.message;
+    const u = msg && msg.usage;
+    if (!u || obj.type !== 'assistant') continue;
+    const model = (msg && msg.model) || '_unknown';
+    const m = (byModel[model] ||= { input: 0, output: 0, cache_write: 0, cache_read: 0 });
+    m.input += u.input_tokens || 0;
+    m.output += u.output_tokens || 0;
+    m.cache_write += u.cache_creation_input_tokens || 0;
+    m.cache_read += u.cache_read_input_tokens || 0;
+  }
+  return byModel;
+}
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(await readStdin());
+  } catch {
+    return process.exit(0); // fail safe
+  }
+  const transcriptPath = payload && payload.transcript_path;
+  if (!transcriptPath || !existsSync(transcriptPath)) return process.exit(0);
+
+  const byModel = tallyTranscript(transcriptPath);
+  const modelNames = Object.keys(byModel);
+  if (modelNames.length === 0) return process.exit(0); // nothing to record
+
+  const prices = loadPrices();
+  let totalUsd = 0;
+  let totalTokens = 0;
+  const models = {};
+  for (const name of modelNames) {
+    const t = byModel[name];
+    const p = priceFor(prices, name);
+    const usd =
+      (t.input * p.input + t.output * p.output + t.cache_write * p.cache_write + t.cache_read * p.cache_read) / 1e6;
+    totalUsd += usd;
+    totalTokens += t.input + t.output + t.cache_write + t.cache_read;
+    models[name] = { ...t, usd: Number(usd.toFixed(4)) };
+  }
+
+  const row = {
+    ts: new Date().toISOString(),
+    session_id: (payload && payload.session_id) || null,
+    reason: (payload && payload.reason) || null,
+    total_usd: Number(totalUsd.toFixed(4)),
+    total_tokens: totalTokens,
+    models,
+  };
+
+  try {
+    const metricsDir = join(DW_DIR, 'metrics');
+    if (!existsSync(metricsDir)) mkdirSync(metricsDir, { recursive: true });
+    appendFileSync(join(metricsDir, 'costs.jsonl'), JSON.stringify(row) + '\n');
+  } catch {
+    /* fail safe — never disrupt the session */
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scaffold/scripts/hooks/statusline.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * dev-workflow statusline — Claude Code statusLine command.
+ *
+ * Prints one line: git branch · dev-workflow active spec (if any) · minimalism
+ * mode. Reads the session payload (JSON on stdin) for the working dir; falls
+ * back to process.cwd(). Fails SAFE — any error prints a minimal line so the
+ * statusline never breaks the session.
+ *
+ * Minimalism mode is read from .dw/minimalism.json (see the dw-minimalism skill).
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+function gitBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+function minimalismMode(cwd) {
+  try {
+    const file = join(cwd, '.dw', 'minimalism.json');
+    if (!existsSync(file)) return 'full';
+    const mode = JSON.parse(readFileSync(file, 'utf-8')).mode;
+    return typeof mode === 'string' ? mode : 'full';
+  } catch {
+    return 'full';
+  }
+}
+
+function costToday(cwd) {
+  // Sum today's estimated spend from .dw/metrics/costs.jsonl (written by the
+  // session-cost SessionEnd hook). Dedupe by session (latest row wins). Fail SAFE.
+  try {
+    const file = join(cwd, '.dw', 'metrics', 'costs.jsonl');
+    if (!existsSync(file)) return '';
+    const today = new Date().toISOString().slice(0, 10);
+    const bySession = new Map();
+    for (const line of readFileSync(file, 'utf-8').split('\n')) {
+      if (!line.trim()) continue;
+      let r;
+      try {
+        r = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!r || typeof r.total_usd !== 'number' || !r.ts) continue;
+      const key = r.session_id || r.ts;
+      const prev = bySession.get(key);
+      if (!prev || r.ts > prev.ts) bySession.set(key, { ts: r.ts, usd: r.total_usd });
+    }
+    let sum = 0;
+    for (const v of bySession.values()) if (v.ts.slice(0, 10) === today) sum += v.usd;
+    return sum > 0 ? `~$${sum.toFixed(2)}/d` : '';
+  } catch {
+    return '';
+  }
+}
+
+function activeSpec(cwd) {
+  try {
+    const specDir = join(cwd, '.dw', 'spec');
+    if (!existsSync(specDir)) return '';
+    const dirs = readdirSync(specDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+    return dirs.length ? `spec:${dirs.length}` : '';
+  } catch {
+    return '';
+  }
+}
+
+async function main() {
+  let cwd = process.cwd();
+  try {
+    const payload = JSON.parse(await readStdin());
+    cwd =
+      (payload && payload.workspace && payload.workspace.current_dir) ||
+      (payload && payload.cwd) ||
+      cwd;
+  } catch {
+    /* use process.cwd() */
+  }
+
+  const parts = [];
+  const branch = gitBranch(cwd);
+  if (branch) parts.push(`⎇ ${branch}`);
+  const spec = activeSpec(cwd);
+  if (spec) parts.push(spec);
+  parts.push(`min:${minimalismMode(cwd)}`);
+  const cost = costToday(cwd);
+  if (cost) parts.push(cost);
+
+  process.stdout.write(`dw · ${parts.join(' · ')}`);
+}
+
+main().catch(() => process.stdout.write('dw'));

package/scaffold/scripts/lib/model-prices.json

@@ -0,0 +1,12 @@
+{
+  "_note": "USD per 1M tokens. Best-effort estimates for cost display only; token counts are exact. Sync from the claude-api skill when prices change. Unknown models fall back to '_default'. cache_write ~= 1.25x input, cache_read ~= 0.1x input (standard Anthropic caching).",
+  "_updated": "2026-07-01",
+  "models": {
+    "claude-opus-4-8": { "input": 15, "output": 75, "cache_write": 18.75, "cache_read": 1.5 },
+    "claude-opus-4-8[1m]": { "input": 15, "output": 75, "cache_write": 18.75, "cache_read": 1.5 },
+    "claude-sonnet-4-6": { "input": 3, "output": 15, "cache_write": 3.75, "cache_read": 0.3 },
+    "claude-haiku-4-5-20251001": { "input": 1, "output": 5, "cache_write": 1.25, "cache_read": 0.1 },
+    "claude-fable-5": { "input": 3, "output": 15, "cache_write": 3.75, "cache_read": 0.3 },
+    "_default": { "input": 3, "output": 15, "cache_write": 3.75, "cache_read": 0.3 }
+  }
+}

package/scaffold/skill-registry.json

@@ -10,6 +10,8 @@
       "expected_output": "A selected API testing recipe and evidence path for the active stack.",
       "load_policy": "lazy-references",
       "context_limit": 12000,
+      "invocation": "explicit",
+      "exportable": true,
       "bundled": true
     },
     {
@@ -21,6 +23,8 @@
       "expected_output": "A selected service recipe and composition guidance.",
       "load_policy": "lazy-references",
       "context_limit": 12000,
+      "invocation": "explicit",
+      "exportable": true,
       "bundled": true
     },
     {
@@ -122,6 +126,19 @@
       "context_limit": 12000,
       "bundled": true
     },
+    {
+      "name": "dw-minimalism",
+      "kind": "protocol",
+      "tier": "core",
+      "owner": "dw-run,dw-plan,dw-review",
+      "trigger": "Before writing new code, infrastructure, or abstractions: YAGNI decision ladder and lite/full/ultra intensity",
+      "expected_output": "A minimalism verdict (build/reuse/inline/skip) with the ladder rung that justified it.",
+      "load_policy": "always-small",
+      "context_limit": 8000,
+      "invocation": "model",
+      "exportable": true,
+      "bundled": true
+    },
     {
       "name": "dw-review-rigor",
       "kind": "protocol",
@@ -142,6 +159,7 @@
       "expected_output": "Adopt/wrap/compose/build decision with checked search channels.",
       "load_policy": "always-small",
       "context_limit": 6000,
+      "exportable": true,
       "bundled": true
     },
     {
@@ -164,6 +182,7 @@
       "expected_output": "Simplification target, risk, behavior-preserving checks, and recommendation.",
       "load_policy": "lazy-references",
       "context_limit": 12000,
+      "exportable": true,
       "bundled": true
     },
     {
@@ -208,6 +227,7 @@
       "expected_output": "Fresh verification report with cited command evidence.",
       "load_policy": "always-small",
       "context_limit": 12000,
+      "exportable": true,
       "bundled": true
     },
     {
@@ -219,6 +239,8 @@
       "expected_output": "Rewritten prose with AI-writing tells removed and voice preserved.",
       "load_policy": "lazy-references",
       "context_limit": 6000,
+      "invocation": "explicit",
+      "exportable": true,
       "bundled": true
     },
     {
@@ -230,6 +252,8 @@
       "expected_output": "Selected Remotion rule references and implementation guidance.",
       "load_policy": "lazy-references",
       "context_limit": 8000,
+      "invocation": "explicit",
+      "exportable": true,
       "bundled": true
     },
     {
@@ -241,6 +265,7 @@
       "expected_output": "High-confidence security findings or explicit pass.",
       "load_policy": "lazy-references",
       "context_limit": 14000,
+      "exportable": true,
       "bundled": true
     },
     {
@@ -252,6 +277,8 @@
       "expected_output": "Selected performance rule references and metric-driven recommendations.",
       "load_policy": "lazy-references",
       "context_limit": 12000,
+      "invocation": "explicit",
+      "exportable": true,
       "bundled": true
     }
   ]

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

@@ -125,7 +125,9 @@ complete delivery). Do not skip it — it is the signal that decides gate vs esc
 - **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.
+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`.
 
 ## Dual evaluation: the CLI auto-gates (MAX effort) → Claude re-gates (compares scores)
 The CLI **can't grade its own exam alone** — hence two layers. The CLI auto-gates cheaply (close to the work) and

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -80,7 +80,7 @@ For human-readable analysis (architecture overview, module conventions, anti-pat
 3. Search `files.json` for matching exports.
 4. Search `arch.md` (full-text) for the keyword.
 5. Cross-reference with `deps.json` if the query is about a library.
-6. Return a structured answer with file paths cited.
+6. Return a structured answer with file paths cited, each tagged with a `relevance` (0–1, or high/medium/low) and a one-line reason — so the calling command reads the high-relevance files first and skips the rest, instead of loading the whole result set. Ordering by relevance is what keeps intel queries token-lean.
 
 If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded by `/dw-new-project` or `/dw-analyze-project`) and direct grep over the codebase.
 
@@ -105,6 +105,8 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 
 - **Iterative retrieval**: subagents should not load broad file sets blindly. They perform at most three search/evaluate/refine cycles, then read only high-relevance files.
 - **Codemaps**: `.dw/intel/codemaps/*.md` stores short maps optimized for agent context instead of forcing repeated source reads.
+- **Data-flow tracing**: `arch.md` includes at least one end-to-end request lifecycle for a representative feature — entry → validation → auth → service → data → response, with the `file:function` at each hop — so agents learn *how data moves*, not just where files sit. This is the single highest-leverage entry for reducing broad exploratory reads.
+- **Relevance-scored answers**: `/dw-intel` query results are ranked by relevance (see "How `/dw-intel` Reads This", step 6) so callers act on the top hits and skip the tail.
 
 ## Inspired by
 

package/scaffold/skills/dw-debug-protocol/SKILL.md

@@ -70,6 +70,10 @@ Bugs cluster into a small number of categories. Knowing the category narrows whe
 | Configuration | Works dev, fails prod | Env vars, secrets, build flags, infra config |
 | Logic | Branch returns wrong result | Guard conditions, off-by-one, boolean polarity |
 
+## When the agent is the bug (not the code)
+
+Sometimes the failure is in the agent's own run — it loops, drifts off the objective, claims an edit it never made, or its reasoning degraded — not in the code under test. That is a different diagnosis. See `references/agent-degradation.md` for the symptom→cause table and the ordered recovery heuristics (restate objective → verify world state → shrink scope → one discriminating check → retry once).
+
 ## Non-reproducible bugs
 
 Some bugs only happen in production, only on certain users, only at certain times. Don't fix them on intuition. The protocol in `references/non-reproducible-strategy.md` covers:

package/scaffold/skills/dw-debug-protocol/references/agent-degradation.md

@@ -0,0 +1,30 @@
+# Agent Degradation — when the AGENT is the bug, not the code
+
+Use when the failure is in the agent's own run — it loops, drifts off the objective, "did" something it
+didn't, or its reasoning quality collapsed — rather than in the code under test. Complements the six-step
+triage (which assumes a code defect). Condensed from ECC's `agent-architecture-audit` (12-layer stack) and
+`agent-introspection-debugging`. Also referenced by `/dw-harness-audit` for runtime triage.
+
+## Symptom → likely cause → first check
+
+| Symptom | Likely cause | First check |
+|---|---|---|
+| Same command/tool call repeated; hits the tool-call ceiling | Loop / no exit condition | Inspect the last N tool calls for repetition; add a stop condition |
+| Reasoning degrades, requirements dropped mid-run | Context overflow / bloat | Measure active context; drop unrelated loaded files; compact memory |
+| Claims a file was written but it isn't there | Hallucinated execution, wrong cwd, or branch drift | Re-verify path, `pwd`, `git status`, the actual filesystem |
+| "Fixed" but the tests still fail identically | Wrong hypothesis, never re-read production | Isolate the exact failing test; re-read the production code first |
+| Answer contradicts the tool output it just received | Misread / ignored tool result | Add a post-tool validation step; quote the tool output before acting |
+| Objective has quietly shifted from the original ask | Prompt drift across a long session | Restate the original objective in one sentence; compare to the current action |
+| A silent second pass produced a different answer | Hidden repair / fallback loop | Audit for undeclared retry paths; make them explicit |
+| Reuses a stale summary or cached artifact as fact | Distillation / persistence staleness | Check freshness timestamps; refresh the summary before trusting it |
+
+## Recovery heuristics (in order — cheapest and most diagnostic first)
+
+1. **Restate the real objective** in one sentence. Half of agent failures are drift.
+2. **Verify world state** (filesystem, branch, service up) instead of assuming it.
+3. **Shrink the failing scope** to one test / one file / one command.
+4. **Run one discriminating check** that would confirm or kill the current hypothesis.
+5. **Only then retry** — and at most once before escalating.
+
+Never claim auto-healing you can't show. If two recovery attempts don't converge, stop and surface what
+was tried — same as the six-step protocol's "escalate after 60 minutes stuck" rule.

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -94,6 +94,19 @@ Closes RF-XX (partial — see tasks.md).
 
 The commit message format is consistent across waves so `/dw-generate-pr` can build a clean PR body. See `references/atomic-commits.md`.
 
+## De-Sloppify Pass (optional cleanup task)
+
+LLM implementers are thorough but leave slop — tests of framework/language behavior, defensive checks the type system already enforces, leftover `console.log`, over-handled impossible states. Constraining the implementer with "don't over-engineer" degrades its output unpredictably; a **separate cleanup pass in a fresh context** works better. Two focused agents beat one constrained agent.
+
+To request one, a task in `tasks.md` may carry `Cleanup After: <N>` in its frontmatter. The executor runs it as its own task (own commit) right after task N's wave lands, scoped to task N's diff:
+
+- Remove tests that assert language/framework behavior rather than business logic.
+- Remove type checks and guards the type system or a prior validation already guarantees.
+- Remove `console.log`/debug prints and commented-out code.
+- Keep every business-logic test and every real error path — when unsure, keep it.
+
+The cleanup task commits as `refactor(<scope>): de-slop <task N title>` and must leave the gate green (lint + tests + build) — it never changes behavior. Opt-in: no `Cleanup After:` means no cleanup task runs.
+
 ## Checkpoint Protocol
 
 If the executor exhausts its context budget mid-phase OR the user signals stop:

package/scaffold/skills/dw-git-discipline/SKILL.md

@@ -78,6 +78,7 @@ When wired into `/dw-generate-pr`, every PR must:
 | Branch is 5 days old, tons of conflicts | Rebase from main daily; don't let drift compound |
 | PR has 2,000 lines | Split. Identify natural seams: schema, backend, frontend, tests |
 | Stuck mid-merge with conflicts | Resolve, don't `git checkout --theirs` blindly. The conflict is information |
+| Rebase or merge to integrate? | Local-only branch → **rebase** onto `main` (linear history). Shared/pushed branch → **merge** (never rebase history others have pulled) |
 
 ## What this skill does NOT do
 

package/scaffold/skills/dw-llm-eval/SKILL.md

@@ -66,6 +66,17 @@ Structure:
 
 See `references/reference-dataset.md` for case-design principles, sampling from production, and when to expand the set.
 
+## Consistency (run-to-run stability)
+
+The oracle ladder measures whether an output is *correct*; it does not measure whether the feature is *stable*. Because LLMs are non-deterministic, a case that passes once may fail the next run. Measure it:
+
+- Re-run each case **N times** (default 3) against the same code + model + prompt.
+- Record `pass_rate` (e.g. `2/3`) and `consistency` (fraction agreeing with the majority verdict) per case in `runs/<YYYY-MM-DD>.jsonl`.
+- A case with pass_rate strictly between `1/N` and `(N-1)/N` is **flaky** — a signal, not a pass. A 2/3 pass hides a one-in-three production failure; investigate before shipping.
+- Sample at the **temperature the feature uses in production** — consistency measured at temp 0 lies about a temp-0.7 feature.
+
+Deterministic rungs (1–3) are usually stable; consistency matters most for rung 4 (LLM-as-judge) and agent trajectories. Record the run count `N` in the run log so later comparisons are apples-to-apples.
+
 ## RAG evaluation
 
 Three orthogonal metrics — measure all three, not just one:
@@ -120,6 +131,7 @@ See `references/agent-eval.md` for examples and the decision tree.
 - **Synthetic-only dataset.** No traceable production-failure source for any case. REJECTED — confirm at least 20% of cases come from real user inputs.
 - **"Looks good to me" QA.** No reference dataset, no metric, no rubric — just sampling output and calling it good. REJECTED.
 - **Coverage as metric.** Quoting "we tested 50 prompts" without saying what was measured. The number is meaningless without the metric.
+- **Single-run eval on a non-deterministic feature.** Each case run once at production temperature; a lucky pass reported as a pass. REJECTED — report `pass_rate` over N runs (see Consistency).
 
 ## Integration with dev-workflow commands