@brunosps00/dev-workflow 1.4.0 → 1.6.0

package/scaffold/pt-br/templates/adr-template.md

@@ -3,8 +3,9 @@ id: NNN
 status: Proposed
 title: [Título imperativo curto da decisão]
 date: YYYY-MM-DD
-prd: [slug do PRD, ex: prd-user-auth]
-schema_version: "1.0"
+scope: repo | prd
+prd: [slug do PRD para scope=prd, ex: prd-user-auth; "n/a" para scope=repo]
+schema_version: "1.1"
 supersedes: null
 superseded_by: null
 ---
@@ -46,8 +47,11 @@ Proposed | Accepted | Deprecated | Superseded by ADR-XXX
 
 ## Related
 
-- PRD: `.dw/spec/[prd-slug]/prd.md`
-- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável)
+<!-- scope=prd: linke o PRD/TechSpec dono. scope=repo: sem PRD dono — omita as linhas de PRD/TechSpec
+     (ou escreva "n/a") e linke `.dw/constitution.md` / `.dw/rules/` só quando genuinamente aplicáveis. -->
+
+- PRD: `.dw/spec/[prd-slug]/prd.md` (só scope=prd; "n/a" para scope=repo)
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável; só scope=prd)
 - Tasks afetadas: [lista de tasks, se aplicável]
 - ADRs relacionadas: [lista, se aplicável]
 

package/scaffold/pt-br/templates/idea-onepager.md

@@ -1,11 +1,19 @@
 ---
 type: idea-onepager
-schema_version: "1.0"
-status: draft
+schema_version: "1.1"
+status: draft | paused | aligned
 date: YYYY-MM-DD
 classification: improves | consolidates | new
+alignment:
+  confirmed_by_user: false   # true SOMENTE quando o usuário confirma explicitamente o shared understanding
+  confirmed_on: null         # data ISO dessa confirmação
 ---
 
+> **Schema 1.1.** O bloco `## Grill Alignment` abaixo é preenchido por uma sessão de grill do `/dw-brainstorm`. Sem
+> Grill, deixe esse bloco vazio e mantenha `status: draft`. `status: aligned` é permitido SOMENTE quando cada branch
+> de dependência está resolvida, contradições glossário/código estão fechadas, nenhuma decisão bloqueante resta, e o
+> usuário confirmou explicitamente o shared understanding — senão use `draft` ou `paused`.
+
 # Ideia: [Título curto e imperativo]
 
 ## Problem Statement
@@ -81,6 +89,40 @@ Idealmente 2-4 stories. Se são mais de 5, provavelmente não é MVP.]
 - [Pergunta 1 que afeta escopo]
 - [Pergunta 2 que afeta prioridade]
 
+## Grill Alignment
+
+_(schema 1.1 — preenchido por uma sessão de grill do `/dw-brainstorm`; consumido pelo `/dw-plan`, que NÃO re-pergunta decisões resolvidas. Deixe vazio para um one-pager sem grill.)_
+
+### Resolved Decisions
+
+| Decisão | Recomendado | Escolhido | Alternativa rejeitada | Evidência |
+|---------|-------------|-----------|-----------------------|-----------|
+| [a decisão] | [o que o Grill recomendou] | [o que o usuário escolheu] | [a opção rejeitada + seu trade-off] | [fonte no one-pager/repo] |
+
+### Evidence
+
+[Fatos descobertos durante o Grill no repo/rules/intel/docs — cada um com sua fonte (`path:line`, doc, ou query de intel) — usados em vez de perguntar ao usuário.]
+
+- **[fato]** — fonte: `[path:line ou doc]`
+
+### Canonical Vocabulary
+
+[Links para `.dw/domain/**` dos termos de que esta ideia depende. Não repita definições aqui — aponte para o glossário.]
+
+- **[Termo]** → `.dw/domain/glossary.md#termo` (ou `.dw/domain/contexts/<slug>.md#termo` num projeto multi-contexto)
+
+### Remaining Decisions
+
+[Decisões não-bloqueantes ainda abertas após o alinhamento, com seu dono. Uma decisão bloqueante significa que o one-pager NÃO está `aligned`.]
+
+- **[decisão aberta]** — dono: [quem] — bloqueante? [não]
+
+### Alignment State
+
+- **State:** `draft` | `paused` | `aligned`
+- **Shared understanding confirmado pelo usuário:** [sim/não — `aligned` exige um sim explícito]
+- **Por que não alinhado (se draft/paused):** [o nó bloqueante ou contradição não fechada que parou o alinhamento]
+
 ## Next Step
 
 Escolha UM:

package/scaffold/rules/README.md

@@ -0,0 +1,22 @@
+# Rules library — curated declarative baseline
+
+Curated "what good code SHOULD look like" per stack, installed to `.dw/rules-library/`. This is the third
+leg of the rules model:
+
+| Source | Type | Answers | Authored by |
+|---|---|---|---|
+| `.dw/rules-library/` | Curated baseline (this) | what good code looks like in `<stack>` | dev-workflow (shipped) |
+| `.dw/rules/` | Analytical | what THIS code **is** (observed patterns) | `/dw-analyze-project` |
+| `.dw/constitution.md` | Declarative, committed | what THIS project **commits to** | `/dw-analyze-project` (Step 8) |
+
+## Precedence
+
+A language file overrides `common` where idioms differ. The project's own `.dw/rules/` and
+`.dw/constitution.md` override the library — they describe THIS project; the library is only the default a
+project starts from.
+
+## Loading (lazy — protect the context budget)
+
+Commands load ONLY the files for the **active stack**, resolved via `.dw/config/stack-mappings.json`
+(`common.md` + `<stack>.md`). Never load the whole library. `/dw-analyze-project` uses it to seed
+constitution proposals; `/dw-review` reads the active stack's baseline as the declarative bar.

package/scaffold/rules/common.md

@@ -0,0 +1,29 @@
+# Baseline rules — common (all languages)
+
+Declarative baseline: what code SHOULD be, regardless of stack. Language files override or specialize these
+where idioms differ. Complements `.dw/rules/` (observed) and `.dw/constitution.md` (committed).
+
+## Code style
+- Prefer immutability: return new values, don't mutate inputs. Mutate only in a measured hot path.
+- Name for intent: `overdueInvoices`, not `data`/`tmp`/`x`. A name that needs a comment is the wrong name.
+- Keep functions small and single-purpose; extract when a block needs its own comment to be understood.
+- No magic values: name constants (except self-evident ones like HTTP codes or `0`/`-1` indexes).
+
+## Error handling
+- Never swallow errors. Handle, propagate, or log with context — never an empty catch (see `dw-silent-failure`).
+- Validate untrusted input once, where it enters the system; fail loudly at boundaries.
+- Timeout on every network/IO call; rollback partial transactional work.
+
+## Testing
+- Test behavior, not implementation. A test that breaks on a rename tested the wrong thing.
+- Cover error and edge paths (empty, null, boundary, failure), not just the happy path.
+- New bug → regression test first, then fix (see `dw-testing-discipline`).
+
+## Security
+- No secrets in code or logs. Read from env/secret store; `.env` is gitignored.
+- Validate input at the boundary; encode output at the boundary.
+- Least privilege for every credential, token, and role.
+
+## Git
+- One intent per commit; Conventional Commits subject (see `dw-git-discipline`).
+- Never force-push shared history; rebase only local branches.

package/scaffold/rules/csharp.md

@@ -0,0 +1,18 @@
+# Baseline rules — C# / .NET (extends common)
+
+## Style
+- Nullable reference types enabled; warnings as errors. `record`/`readonly` for value types.
+- `async`/`await` end-to-end; never `.Result`/`.Wait()` (deadlocks). Thread `CancellationToken` through.
+- `using` declarations for `IDisposable`; dependency injection over `new` for services.
+
+## Errors
+- Catch specific exceptions; never empty catch. Don't use exceptions for normal control flow.
+- Validate arguments at public boundaries (`ArgumentNullException.ThrowIfNull`).
+
+## Testing
+- xUnit/NUnit; test public behavior. Mock owned boundaries, not the system under test itself.
+- Arrange-Act-Assert; one behavior per test.
+
+## Security
+- Parameterized queries / EF Core — never concatenate SQL. Validate/encode at boundaries.
+- Secrets via configuration / user-secrets / Key Vault, never in source.

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/skill-registry.json

@@ -35,7 +35,7 @@
       "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.",
       "load_policy": "lazy-references",
-      "context_limit": 18000,
+      "context_limit": 19000,
       "bundled": true
     },
     {
@@ -60,6 +60,30 @@
       "context_limit": 12000,
       "bundled": true
     },
+    {
+      "name": "dw-domain-modeling",
+      "kind": "protocol",
+      "tier": "specialty",
+      "owner": "dw-brainstorm,dw-analyze-project",
+      "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,
+      "exportable": false,
+      "bundled": true
+    },
+    {
+      "name": "dw-grilling",
+      "kind": "protocol",
+      "tier": "specialty",
+      "owner": "dw-brainstorm,dw-plan",
+      "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,
+      "exportable": false,
+      "bundled": true
+    },
     {
       "name": "dw-debug-protocol",
       "kind": "protocol",

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

@@ -125,21 +125,25 @@ 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)
+## Dual evaluation: the CLI auto-gates (max effort) → the parent 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
-**Claude audits independently** and **compares the scores** (catches an inflated self-score).
+**the parent/orchestrator audits independently** and **compares the scores** (catches an inflated self-score). The
+parent is the dispatching session — possibly Claude itself; the re-gate is provider-neutral.
 1. **CLI auto-gate (loop, MAX effort).** The prompt MUST instruct: after implementing, **run the SAME gate** and
    give a **self-score 0–10**; **fix and re-run while the self-score <9 or the gate isn't green**, at max effort.
    Stop at self-score ≥9 + green gate (or report `blockers`). The final report carries the self-score + per
    criterion.
-2. **Claude re-gate (independent).** When the CLI declares pass, the parent **re-runs the SAME gate** (fan-out,
-   prefer Workflow → `/workflows`) and gives its **own 0–10** — without trusting the self-score.
-3. **Compare + decide.** Claude ≥9 and small gap → **PASS** (ready for the owner's merge decision). Claude <9 OR a
+2. **Parent re-gate (independent).** When the CLI declares pass, the parent/orchestrator **re-runs the SAME gate**
+   (fan-out, prefer Workflow → `/workflows`) and gives its **own 0–10** — without trusting the self-score (a worker
+   never signs off on its own exam, even when that worker is Claude).
+3. **Compare + decide.** Parent ≥9 and small gap → **PASS** (ready for the owner's merge decision). Parent <9 OR a
    large gap (CLI overestimated) → re-execute: hand the gaps back via **session resume** (step 5, max effort) and
-   repeat 1→2→3 until it converges. **The score that counts for acceptance is Claude's**; the self-score is signal
-   + an inflation detector. Always record both scores + the gap in the Structured Return.
+   repeat 1→2→3 until it converges. **The score that counts for acceptance is the parent's**; the self-score is
+   signal + an inflation detector. Always record both scores + the gap in the Structured Return.
 
 ## 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
@@ -197,7 +201,7 @@ The stream ends with the adapter's `USAGE` block (token counts). Extract it from
   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:** **Claude's score** (0–10 — counts for acceptance, bar ≥9) + the **CLI self-score** + the **gap**;
+- **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

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.