@brunosps00/dev-workflow 1.4.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/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

@@ -49,6 +49,35 @@ function minimalismMode(cwd) {
   }
 }
 
+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');
@@ -80,6 +109,8 @@ async function main() {
   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(' · ')}`);
 }

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/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
 

package/scaffold/skills/dw-memory/SKILL.md

@@ -52,7 +52,7 @@ Create `MEMORY.md` and `<N>_memory.md` on first use with the template below. Nev
 - Branch: <branch-name>
 
 ## Durable Decisions
-- <decision 1> — <one-line rationale>
+- <decision 1> — <one-line rationale> — [confidence: 0.7; seen in tasks 1,3]
 
 ## Cross-Task Constraints
 - <constraint discovered during implementation that affects multiple tasks>
@@ -124,6 +124,16 @@ Before promoting an item from `<N>_memory.md` to `MEMORY.md`, ask:
 
 All three must be "yes" to promote. If any is "no", the item stays in task memory.
 
+### Confidence signal
+
+Tag each durable decision with a confidence in `[0.3–0.9]` plus the tasks that confirmed it — `… — [confidence: 0.7; seen in tasks 1,3,5]`:
+
+- Confirmed in **≥2 of the last 3 tasks** with no contradiction → **≥0.7** (trust it; safe to act on without re-deriving).
+- Confirmed once, or inferred but not yet reused → **0.3–0.5** (tentative; gather more signal before relying).
+- Contradicted by a later task or the repo → lower it or drop the decision (see Error Handling).
+
+Confidence makes cross-task learning explicit and is the signal `/dw-learn` reads to promote high-confidence decisions into durable instincts, constitution principles, or rules.
+
 ### Belongs in shared memory
 - A discovered constraint affecting multiple tasks ("the Stripe API rate-limits to 100 req/s — batch operations must respect this")
 - A cross-cutting architectural decision made during implementation ("chose React Server Components for data fetching across the whole feature")
@@ -179,6 +189,7 @@ This budget is doctrine, not a hard gate. No command currently rejects work for
 - `/dw-run` — reads memory before coding; updates `<N>_memory.md` during; runs promotion test + updates `MEMORY.md` at the end.
 - `/dw-run` — runs promotion + compaction between tasks, so each task starts with clean shared state.
 - `/dw-autopilot` — threads memory through every phase (brainstorm → PRD → techspec → tasks → execution); on re-invocation reads `MEMORY.md` first to reconstitute cross-session context.
+- `/dw-learn` — synthesizes confidence-tagged decisions here (plus bugfixes, deviations, git history) into atomic **instincts** in `.dw/memory/instincts/`; format, confidence rules, and promotion path in `references/instincts.md`.
 
 Callers should mention this skill in their "Skills Complementares" section.
 

package/scaffold/skills/dw-memory/references/instincts.md

@@ -0,0 +1,45 @@
+# Instincts — promoting durable memory into reusable behavior
+
+An instinct is a small, atomic, confidence-weighted behavior learned from THIS project's work, promotable
+into a constitution principle or rule. Instincts live in `.dw/memory/instincts/*.md` and are proposed and
+curated by `/dw-learn` — never written without explicit approval. There is no always-on observer; instincts
+are synthesized on demand from what the project already recorded (see `/dw-learn` sources).
+
+## File format (`.dw/memory/instincts/<slug>.md`)
+
+```markdown
+---
+id: prefer-result-type-in-services
+trigger: when writing a service method that can fail
+confidence: 0.7          # 0.3 tentative … 0.9 near-certain (same scale as durable decisions)
+domain: error-handling   # code-style | testing | error-handling | git | workflow | security
+scope: project           # project | global
+evidence:
+  - "MEMORY.md decision (seen in tasks 3,5)"
+  - "bugfix 004-null-order — same root cause"
+---
+
+# Prefer Result type in services
+
+## Action
+Return a typed Result/union from fallible service methods instead of throwing across layers.
+
+## Why
+Two bugfixes traced to exceptions swallowed between layers; the confidence-tagged decision in MEMORY.md
+already prefers this.
+```
+
+## Confidence (reuse the promotion signal)
+
+Same scale and rule as durable decisions (see the **Confidence signal** section of this skill): ≥2
+independent confirmations in recent work → ≥0.7. Lower it when a later task contradicts the instinct; drop
+it when it stops being true.
+
+## Promotion path
+
+- **≥0.7, project scope** → propose as a `.dw/constitution.md` principle (via the `/dw-analyze-project`
+  Step 8 flow) or a note on the relevant `.dw/rules-library/<stack>.md`.
+- **Seen across multiple projects** → mark `scope: global` (a candidate for a shipped rule/skill).
+
+High-confidence instincts (≥0.7) whose `trigger` matches the current work are loaded on demand by `/dw-run`
+and `/dw-plan` — the same lazy pattern as `.dw/rules/concerns.md`. Never bulk-load the whole instinct set.

package/scaffold/skills/dw-review-rigor/SKILL.md

@@ -21,6 +21,17 @@ By `/dw-review --code-only`, `/dw-review --coverage-only`, `/dw-refactor`, and `
 - The scope the caller is reviewing (file paths, directories, or PR diff).
 - Optional: prior review reports in `.dw/spec/prd-*/reviews/` — so this round only surfaces NEW findings.
 
+## Pre-Report Gate
+
+Before writing ANY finding, clear four checks — if any is "no"/"unsure", downgrade or drop it (an unactionable finding is noise):
+
+1. **Location** — exact file and line?
+2. **Failure mode** — a concrete input/state and the bad outcome it produces?
+3. **Context** — read the surrounding code (callers, imports, tests), not just the flagged line?
+4. **Severity** — defensible against Rule 2's definitions? (a missing JSDoc is never HIGH)
+
+Report only findings you are **>80% confident** are real. A style preference no rule backs is not a finding. See `references/false-positives.md` for patterns LLM reviewers habitually mis-flag.
+
 ## The Five Rules
 
 ### 1. De-duplicate before writing
@@ -111,6 +122,7 @@ The caller emits:
 2. **Counts** — critical / high / medium / low.
 3. **Findings** — ordered by severity, each in the format above.
 4. **Well-implemented aspects** — short bulleted list, calibrates tone.
+5. **Self-score** — rate the report on the five axes in `references/self-eval-rubric.md`; any axis below top cites the gap, then fix (<30s) or flag.
 
 ## Critical Rules
 

package/scaffold/skills/dw-review-rigor/references/false-positives.md

@@ -0,0 +1,21 @@
+# False Positives — patterns LLM reviewers habitually mis-flag
+
+Loaded on demand by the Pre-Report Gate. Skip these unless you have evidence **specific to this codebase**
+(a failing test, a real caller that doesn't guard, a project rule that forbids it). Flagging them anyway is
+the most common way an AI review drowns real findings in noise.
+
+| Tempting finding | Why it's usually wrong |
+|---|---|
+| "Add error handling here" | The error path is already handled by the caller or the framework — Express/Koa middleware, a React error boundary, a top-level `catch`, or a job runner that retries. Trace one level up before flagging. |
+| "Missing input validation" | The function is internal and every caller already validated at the boundary. Validation belongs at the trust boundary, not on every hop. |
+| "Magic number" | Well-known constants are self-documenting: HTTP codes (200/404/500), `1000`/`60`/`24`/`1024`, array index `0`/`-1`, `100` for percent. Only flag opaque domain numbers with no name. |
+| "Function too long" | Length ≠ complexity. Exhaustive `switch`, config/lookup objects, test tables, and generated code are long *and* simple. Flag high branching/nesting, not line count. |
+| "Missing JSDoc/docstring" | Internal helpers whose name and signature are self-describing don't need docs. Reserve for public API or non-obvious contracts. |
+| "Possible null dereference" | A preceding line already narrowed the type or an `if` guard is in scope. Read the few lines above before asserting. |
+| "Use `const` / style nit" | The linter/formatter already enforces this (Rule 4). It is a linter task, not a review finding. |
+| "This could be a race condition" | Only real if there is actual shared mutable state across concurrent paths. A single-threaded request handler touching a local variable is not a race. |
+| "Add a test for this" | Valid only if the behavior is untested AND load-bearing. Don't demand tests for trivial getters or framework glue. |
+| "Extract this into a helper (DRY)" | Two similar lines are not duplication worth an abstraction. Premature extraction couples unrelated call sites — see `dw-minimalism`. |
+
+**Rule of thumb:** if the "fix" would be rejected by a competent maintainer as busywork, it is a false
+positive. When unsure whether a pattern is intentional, apply Rule 3 (verify intent) before writing it.

package/scaffold/skills/dw-review-rigor/references/self-eval-rubric.md

@@ -0,0 +1,38 @@
+# Self-Evaluation Rubric — five axes, evidence required
+
+A structured way for an agent to rate its own output **before** handing it over, without waiting for user
+feedback. Used by `dw-review-rigor` (score the review itself) and cited by `dw-cli-run` (the 0–10 delivery
+gate applies the same evidence discipline). Adapted from the ECC `agent-self-evaluation` skill.
+
+## The five axes (score each 1–5)
+
+| Axis | Question | What a low score catches |
+|---|---|---|
+| **Accuracy** | Are the facts, claims, and code correct? | Hallucinated APIs, wrong file paths, syntax errors, unverified assertions |
+| **Completeness** | Did it cover everything the request asked? | Missed edge cases, skipped subtasks, unhandled error paths |
+| **Clarity** | Is it understandable and well-structured? | Confusing explanations, jargon, rambling, missing context |
+| **Actionability** | Can the user act on it immediately? | Vague suggestions, missing steps, "you should X" without showing how |
+| **Conciseness** | Is it the minimum needed to be complete? | Redundancy, over-explanation, filler, restating the question |
+
+Scale: **5** = no reasonable improvement · **4** = minor nits · **3** = one notable weakness · **2** = a clear
+gap that hurts usability · **1** = fundamentally misses the request.
+
+## The one hard rule: evidence for every score below 5
+
+A score under 5 **must cite the specific gap** — quote the line, name the missing case, point at the
+redundancy. "Completeness: 3 — doesn't handle the empty-array case in `parse()`" is a real score;
+"Completeness: 3 — could be more thorough" is hand-waving and not allowed.
+
+## What to do with the scores
+
+1. Score each axis independently (don't average away a real weakness).
+2. If any axis is **≤ 3**: fix it now when the fix is under ~30 seconds; otherwise flag it explicitly in the
+   output so the user knows the gap exists.
+3. Keep the self-score short — a few lines, not a second report.
+
+## Anti-patterns
+
+- **"Everything is a 5"** with no evidence — the most common failure; it means you didn't actually evaluate.
+- **Over-penalizing scope** — grade only what was requested, not scope you invented.
+- **Re-litigating decisions** — evaluate execution quality, not whether a settled decision was right.
+- **Personal preference as a gap** — a nit the linter doesn't enforce and no rule backs is not a real deduction.

package/scaffold/skills/dw-silent-failure/SKILL.md

@@ -19,7 +19,8 @@ Use during `/dw-review`, `/dw-bugfix`, and `/dw-qa --fix` when failures may be h
 - Log-only handling where callers need the failure.
 - Generic rethrows that lose stack or input context.
 - Async work launched without awaiting, tracking, or explicit detachment.
-- Network/database/filesystem calls without timeout or rollback where the project requires it.
+- Network/database/filesystem calls without a **timeout** — the call can hang indefinitely and block everything waiting on it.
+- Transactional work (multi-step writes, DB mutations, chained external calls) without **rollback** on partial failure — leaves silently corrupted or half-written state.
 
 ## Reporting Standard
 
@@ -27,7 +28,8 @@ Only flag a finding when you can name:
 
 - the exact location,
 - the trigger,
-- the hidden bad outcome,
+- the severity (critical / high / medium),
+- the hidden bad outcome and its impact (what the user or system experiences when it fires),
 - the minimal fix.
 
 Inspired by ECC's `silent-failure-hunter`; adapted as both a skill and a dispatchable `dw-silent-failure-hunter` agent.

package/scaffold/skills/dw-simplification/SKILL.md

@@ -99,6 +99,18 @@ If a simplification touches >500 lines, **don't do it manually**. Use:
 
 Manual edits across hundreds of lines are how subtle bugs creep in.
 
+## Refactor risk levels
+
+Before removing or restructuring, categorize by blast radius and act in that order — never all at once:
+
+| Risk | Examples | Discipline |
+|------|----------|-----------|
+| **SAFE** | Unused exports, unused deps, unreachable branches | Batch-remove, run the gate after each batch, commit |
+| **CAREFUL** | Consolidate duplicates, extract/inline, rename symbol | One or two per commit; re-read callers first |
+| **RISKY** | Change a public API, alter a data structure, extract a layer | One per commit; regression tests first; pair review / ADR |
+
+Start with SAFE and graduate only after the gate is green. For finding SAFE candidates on JS/TS (and other ecosystems), see `references/dead-code-tools.md`. This composes with Chesterton's Fence (Rule 1) — a tool calling code "unused" still needs the WHY check before deletion (reflection, dynamic imports, and framework entry points are invisible to static analysis).
+
 ## Verification protocol
 
 Before committing the simplification:
@@ -139,6 +151,7 @@ In the formal Level 3 review (post-Level 2 chain from `dw-review-implementation`
 - `references/complexity-metrics.md` — when each metric (cyclomatic, cognitive, depth, fanout) actually matters; how to measure cheaply.
 - `references/behavior-preserving.md` — characterization tests, refactor with test gate, rollback patterns, codemod tooling per language.
 - `references/deep-modules.md` — high-leverage modules behind small interfaces; deletion test, locality, leverage, seam, adapter diagnostic; anti-patterns (shallow wrapper, god-module). Invoked by `/dw-refactor` and `/dw-brainstorm` refactor-audit mode.
+- `references/dead-code-tools.md` — per-ecosystem tools that surface SAFE-tier dead-code candidates (knip/depcheck/ts-prune for JS/TS; vulture/ruff for Python; deadcode/staticcheck for Go; cargo-udeps for Rust). Candidates still pass Chesterton's Fence before deletion.
 
 ## Inspired by