@brunosps00/dev-workflow 2.5.0 → 2.7.0

package/scaffold/pt-br/commands/dw-update.md

@@ -24,15 +24,16 @@ Antes de sobrescrever arquivos gerenciados, crie um snapshot:
 ```bash
 SNAPSHOT_DIR=".dw/.backup/$(date -u +%Y%m%dT%H%M%SZ)"
 mkdir -p "$SNAPSHOT_DIR"
-cp -r .dw/commands .dw/templates .dw/references .dw/scripts "$SNAPSHOT_DIR/" 2>/dev/null
+cp -r .dw/commands .dw/templates .dw/references .dw/scripts .dw/skills "$SNAPSHOT_DIR/" 2>/dev/null
 # agents/skills (bundled) tambem fazem parte do update
 [ -d .agents/skills ] && cp -r .agents/skills "$SNAPSHOT_DIR/agents-skills" 2>/dev/null
 # .claude/settings.json agora e mutado pelo update (MCPs + hooks + statusLine)
 [ -f .claude/settings.json ] && mkdir -p "$SNAPSHOT_DIR/claude" && cp .claude/settings.json "$SNAPSHOT_DIR/claude/settings.json" 2>/dev/null
+[ -f .dw/install-state.json ] && cp .dw/install-state.json "$SNAPSHOT_DIR/install-state.json" 2>/dev/null
 echo "Snapshot salvo em $SNAPSHOT_DIR"
 ```
 
-Manter apenas os 3 snapshots mais recentes (remover os mais antigos) para evitar acumulo.
+Manter apenas os 3 snapshots mais recentes em `.dw/.backup/` (remover os mais antigos) para evitar acumulo. `.dw/.migrated/` não é snapshot: nunca remova.
 
 ### 1. Registrar Versão Atual (Obrigatório)
 
@@ -86,7 +87,13 @@ O comando `update` sobrescreve arquivos gerenciados e PRESERVA:
 
 O comando `update` também roda o passo de migração GSD automaticamente — se o projeto tem `.planning/` legado (de uso prévio do GSD), o conteúdo é migrado para `.dw/intel/`, `.dw/spec/active-session.md`, `.dw/spec/quick/`, etc., e `.planning/` é renomeado para `.planning.gsd-archive-<DATA>/` para inspeção. Os arquivos `.claude/commands/gsd/`, `.claude/agents/gsd-*.md`, `.claude/hooks/gsd-*.js` e `.claude/gsd-file-manifest.json` são removidos durante a migração.
 
-Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o erro ao usuário e PARE. NÃO tente workarounds manuais como copiar arquivos.
+O CLI nunca apaga o que aposenta: move para `.dw/.migrated/<timestamp>/`, mantendo o caminho relativo, e imprime o destino. Isso acontece só depois que as skills novas estão em `.dw/skills/`, então um update interrompido deixa as cópias antigas no lugar. O que ele aposenta, e como decide:
+
+- **Cópias legadas de skills bundled** em `.agents/skills/` (`[moved]`): só quando a cópia é do dev-workflow. Skill homônima que não é sai como `[kept]` e fica intocada.
+- **Skills removidas em releases anteriores** (`[v<N>]`) e **fontes de comandos removidos** (`[legacy]`): casadas por nome, então uma skill homônima de outra origem também é movida — é o move que torna isso recuperável.
+- **Wrappers `dw-*` órfãos** (`[orphan]`): `dw-` é o namespace deste pacote; uma skill do usuário chamada `dw-*` é movida, não perdida.
+
+Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o erro ao usuário e PARE. NÃO tente workarounds manuais como copiar arquivos. Passe ao usuário o caminho do snapshot do passo 0 e as duas saídas: rodar o update de novo depois de resolver a causa (ele é idempotente), ou `/dw-update --rollback`.
 
 ### 4. Capturar Nova Versão
 
@@ -96,7 +103,7 @@ node -e 'const s = JSON.parse(require("node:fs").readFileSync(".dw/install-state
 
 ### Checks de compatibilidade do upgrade
 
-Leia o `.dw/commands/dw-update.md` atualizado após o CLI terminar. Use `.dw/install-state.json` e o output `Installed version` do CLI para a diferença de versões: um pacote executado por `npx` não precisa ser resolvível pelo `node_modules` do consumidor. Estado novo ausente ou inválido é falha de verificação; não declare sucesso do update.
+Leia o `.dw/commands/dw-update.md` atualizado após o CLI terminar. Use `.dw/install-state.json` e o output `Installed version` do CLI para a diferença de versões: um pacote executado por `npx` não precisa ser resolvível pelo `node_modules` do consumidor. Estado novo ausente ou inválido é falha de verificação; não declare sucesso do update. A versão lida no passo 4 tem de ser igual ao lado direito da linha `Installed version: <antiga> -> <nova>` do CLI; se essa linha faltar, ou as versões diferirem, o CLI não terminou e o update falhou.
 
 Em um upgrade de versão anterior à 2.3.0 (ou versão legada desconhecida):
 
@@ -116,6 +123,7 @@ Apresente ao usuário:
 - Resumo do que o output do `update` mostrou (arquivos copiados, wrappers gerados, MCPs configurados)
 - As `Post-update agent actions` impressas pelo CLI
 - Quaisquer avisos ou erros
+- Toda linha `[moved]`, `[v<N>]`, `[orphan]`, `[legacy]` ou `[kept]` do `Skill migration`, o caminho `.dw/.migrated/<timestamp>/` e todo arquivo marcado `was not installed by dev-workflow` (adição do próprio time: ofereça trazê-lo de volta numa skill do time, nunca em `.dw/skills/`, que o update sobrescreve)
 
 ### 6. Executar Ações de Agente Pós-Update (Obrigatório)
 
@@ -144,19 +152,28 @@ Se invocado com `--rollback`:
 1. Listar snapshots em `.dw/.backup/`
 2. Se nenhum existir: PARAR e reportar "Nenhum snapshot disponível"
 3. Se mais de um existir: perguntar ao usuário qual restaurar (padrão: mais recente)
-4. Confirmar com o usuário: "Restaurar snapshot `<path>`? Isso SOBRESCREVE `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/`, `.agents/skills/` e `.claude/settings.json`. Prosseguir? [s/N]"
+4. Confirmar com o usuário: "Restaurar snapshot `<path>`? Isso SUBSTITUI `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/` e `.dw/skills/` pelas cópias do snapshot (quando ele as tem), copia o `.agents/skills/` do snapshot por cima do atual sem remover outras entradas, e restaura `.claude/settings.json` e `.dw/install-state.json`. `.dw/templates/overrides/` nunca é tocado. Prosseguir? [s/N]"
 5. Somente após `s`: copiar de volta
 
 ```bash
-cp -r "$SNAPSHOT_DIR/commands"   .dw/
-cp -r "$SNAPSHOT_DIR/templates"  .dw/
-cp -r "$SNAPSHOT_DIR/references" .dw/ 2>/dev/null
-cp -r "$SNAPSHOT_DIR/scripts"    .dw/ 2>/dev/null
-[ -d "$SNAPSHOT_DIR/agents-skills" ] && cp -r "$SNAPSHOT_DIR/agents-skills" .agents/skills 2>/dev/null
+SNAPSHOT_DIR=".dw/.backup/<timestamp-escolhido>"   # o snapshot confirmado no passo 4
+[ -d "$SNAPSHOT_DIR" ] || { echo "Snapshot não encontrado: $SNAPSHOT_DIR"; exit 1; }
+# Pastas gerenciadas de .dw são substituídas, para não sobrar arquivo da release mais nova.
+for d in commands references scripts skills; do
+  [ -d "$SNAPSHOT_DIR/$d" ] && rm -rf ".dw/$d" && cp -r "$SNAPSHOT_DIR/$d" .dw/
+done
+# .dw/templates/overrides/ é do dono: restaure os templates gerenciados em volta dele, nunca o remova.
+if [ -d "$SNAPSHOT_DIR/templates" ]; then
+  find .dw/templates -mindepth 1 -maxdepth 1 ! -name overrides -exec rm -rf {} +
+  for f in "$SNAPSHOT_DIR/templates"/*; do [ "$(basename "$f")" = overrides ] || cp -r "$f" .dw/templates/; done
+fi
+# .agents/skills é compartilhada com as skills do próprio usuário: mescla, nunca substitui.
+[ -d "$SNAPSHOT_DIR/agents-skills" ] && mkdir -p .agents/skills && cp -r "$SNAPSHOT_DIR/agents-skills/." .agents/skills/ 2>/dev/null
 [ -f "$SNAPSHOT_DIR/claude/settings.json" ] && cp "$SNAPSHOT_DIR/claude/settings.json" .claude/settings.json 2>/dev/null
+[ -f "$SNAPSHOT_DIR/install-state.json" ] && cp "$SNAPSHOT_DIR/install-state.json" .dw/install-state.json 2>/dev/null
 ```
 
-6. Reportar: snapshot restaurado, versão provavelmente recuperada (ler de `.dw/commands/dw-help.md` ou metadata se houver)
+6. Reportar: snapshot restaurado, e a versão do `.dw/install-state.json` restaurado (ou "unknown" quando o snapshot é anterior a ele). Snapshot de antes da 2.7.0 não tem `skills/`: `.dw/skills/` fica como estava, o que é inofensivo (comandos antigos leem `.agents/skills/`), e o próximo update aposenta de novo as cópias restauradas em `.agents/skills/`.
 
 ## Opções Avançadas
 

package/scaffold/pt-br/references/invariants.md

@@ -49,8 +49,9 @@ funcionando. Um agente que não consegue destruir trabalho não pode ser convenc
 
 **Como isso é verificado:** em parte pelo `.dw/scripts/hooks/git-guardrails.mjs`, um hook `PreToolUse` que
 nega esses padrões no Bash. O hook é **uma implementação, não a fonte da regra**, e tem dois limites
-conhecidos: só cobre Bash no Claude Code, e **falha aberto** — erro de parse ou exceção em runtime deixa o
-comando passar. Então a regra obriga mesmo onde o hook não roda.
+conhecidos: só cobre Bash no Claude Code e no Codex (o Codex só o roda depois que o projeto e o hook são
+marcados como confiáveis), e **falha aberto** — erro de parse ou exceção em runtime deixa o comando passar.
+Então a regra obriga mesmo onde o hook não roda.
 
 Duas operações ficam de fora do hook de propósito e vivem só aqui: `rebase` e `commit --amend`. As duas são
 rotina em trabalho não pushado, e uma linha de comando não distingue pushado de não pushado. Negá-las
@@ -80,6 +81,11 @@ Este piso é estreito de propósito. Algo genuinamente destrutivo que não estej
 isso — aplique o mesmo critério: se a ação destrói trabalho sem segunda cópia, reescreve história
 compartilhada ou move uma credencial, pare e pergunte. Uma confirmação a mais custa uma mensagem.
 
+O mesmo vale para as pastas de skills que os agentes compartilham — `.agents/skills/`, `.claude/skills/`,
+`.codex/skills/`: elas guardam também skills do usuário e de outras ferramentas. Fora do `update`/`uninstall`
+do próprio CLI, liste o que removeria e pergunte por entrada; mova o aprovado para `.dw/.migrated/<timestamp>/`,
+nunca `rm`.
+
 ## Atribuição
 
 O modelo de duas camadas — um piso que regra de projeto só pode apertar, nunca afrouxar — foi adaptado do

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

@@ -80,7 +80,7 @@ services: []
 │   └── api/                      (criado por `pnpm dlx @nestjs/cli` ou scaffold escolhido)
 ├── packages/
 │   └── shared/                   (criado pelo /dw-new-project)
-├── docker-compose.dev.yml        (composto a partir de .agents/skills/docker-compose-recipes/)
+├── docker-compose.dev.yml        (composto a partir de .dw/skills/docker-compose-recipes/)
 ├── .env.example                  (consolidado dos servicos selecionados)
 ├── .gitignore                    (por stack)
 ├── .dockerignore                 (por stack)

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * dev-workflow git guardrails — Claude Code PreToolUse hook (matcher: Bash).
+ * dev-workflow git guardrails — PreToolUse hook (matcher: Bash) for Claude Code
+ * (.claude/settings.json) and Codex (.codex/hooks.json); both send the same payload.
  *
  * Blocks irreversible git commands (force push, hard reset, clean -f, branch
  * deletion, remote branch deletion). Everything else is allowed.
@@ -76,7 +77,7 @@ export function evaluatePayload(input) {
           permissionDecision: 'deny',
           permissionDecisionReason:
             `Blocked by dev-workflow git guardrails: ${rule.why}. ` +
-            `If this is intentional, run it yourself outside the agent, or adjust .claude/settings.json hooks.`,
+            `If this is intentional, run it yourself outside the agent, or adjust the hook in .claude/settings.json or .codex/hooks.json.`,
         },
       };
     }

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

@@ -12,9 +12,12 @@
  * USD is a best-effort ESTIMATE from a local price table — tokens are exact.
  *
  * The same pass also counts which skills the session's tool calls referenced,
- * emitted as `skills` on the row. `/dw-skill-health` reads it as usage evidence.
- * An absent `skills` key means the row predates this instrumentation; `{}` means
- * the session was observed and nothing fired — those are different facts.
+ * emitted as `skills` on the row, and which dev-workflow commands it loaded
+ * (a read of `.dw/commands/<name>.md`, which every command wrapper performs, or a
+ * Skill-tool call naming a command), emitted as `commands`. `/dw-skill-health`
+ * reads both as usage evidence. An absent key means the row predates that
+ * instrumentation; `{}` means the session was observed and nothing fired —
+ * those are different facts.
  *
  * 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.
@@ -70,7 +73,7 @@ function knownSkills() {
       return false;
     }
   };
-  for (const base of ['.agents/skills', '.claude/skills']) {
+  for (const base of ['.dw/skills', '.agents/skills', '.claude/skills']) {
     const root = join(PROJECT_ROOT, base);
     if (!isDir(root)) continue;
     let top;
@@ -103,8 +106,29 @@ function knownSkills() {
 }
 
 // Matches a skills/ path inside a tool call's input, capturing at most two
-// segments so a grouped `group/skill` is preserved.
-const SKILL_PATH = /(?:\.agents|\.claude)\/skills\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?)\//g;
+// segments so a grouped `group/skill` is preserved. `.dw/skills/` is where the
+// bundled skills live; `.agents/` and `.claude/` hold wrappers, external and
+// legacy copies.
+const SKILL_PATH = /(?:\.dw|\.agents|\.claude)\/skills\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?)\//g;
+
+// Matches the canonical command file every wrapper tells the agent to read.
+const COMMAND_PATH = /\.dw\/commands\/([A-Za-z0-9._-]+)\.md/g;
+
+// Commands this project has installed: the names usage counting may emit under
+// `commands`. Their wrappers also sit under `.claude/skills/` and
+// `.agents/skills/`, so knownSkills() sees the same names; a command name is
+// always counted as a command, never as a skill.
+function knownCommands() {
+  const names = new Set();
+  try {
+    for (const file of readdirSync(join(DW_DIR, 'commands'))) {
+      if (file.endsWith('.md')) names.add(file.slice(0, -3));
+    }
+  } catch {
+    /* no installed commands — nothing to count */
+  }
+  return names;
+}
 
 // Count skill references in ONE assistant message.
 //
@@ -113,17 +137,22 @@ const SKILL_PATH = /(?:\.agents|\.claude)\/skills\/([A-Za-z0-9._-]+(?:\/[A-Za-z0
 // `tool_result` that returned the CONTENTS of a SKILL.md (those cite other
 // skills) and a user prompt that merely names one — both would report a skill as
 // fired when it never was. What this measures is loading, not obedience.
-function countSkillUses(msg, known, out) {
+function countSkillUses(msg, known, out, commands = new Set(), commandOut = {}) {
   const content = msg && msg.content;
   if (!Array.isArray(content)) return;
   for (const block of content) {
     if (!block || block.type !== 'tool_use' || !block.input) continue;
-    // One tool call is one reference per skill, however many times its input
-    // names that skill. A grep over three files under the same skill directory
-    // is one load, not three.
+    // One tool call is one reference per skill or command, however many times
+    // its input names it. A grep over three files under the same skill
+    // directory is one load, not three.
     const seen = new Set();
-    if (block.name === 'Skill' && typeof block.input.skill === 'string' && known.has(block.input.skill)) {
-      seen.add(block.input.skill);
+    const seenCommands = new Set();
+    const note = (name) => {
+      if (commands.has(name)) seenCommands.add(name);
+      else if (known.has(name)) seen.add(name);
+    };
+    if (block.name === 'Skill' && typeof block.input.skill === 'string') {
+      note(block.input.skill);
     }
     let serialized;
     try {
@@ -136,24 +165,29 @@ function countSkillUses(msg, known, out) {
       let match;
       while ((match = SKILL_PATH.exec(serialized)) !== null) {
         const full = match[1];
-        const name = known.has(full) ? full : full.split('/')[0];
-        if (known.has(name)) seen.add(name);
+        note(known.has(full) ? full : full.split('/')[0]);
+      }
+      COMMAND_PATH.lastIndex = 0;
+      while ((match = COMMAND_PATH.exec(serialized)) !== null) {
+        if (commands.has(match[1])) seenCommands.add(match[1]);
       }
     }
     for (const name of seen) out[name] = (out[name] || 0) + 1;
+    for (const name of seenCommands) commandOut[name] = (commandOut[name] || 0) + 1;
   }
 }
 
 // Sum per-turn usage from the transcript, grouped by model, and count which
 // skills the session's tool calls referenced.
-function tallyTranscript(transcriptPath, known) {
+function tallyTranscript(transcriptPath, known, commands = new Set()) {
   const byModel = {};
   const skills = {};
+  const commandUses = {};
   let raw;
   try {
     raw = readFileSync(transcriptPath, 'utf-8');
   } catch {
-    return { byModel, skills };
+    return { byModel, skills, commands: commandUses };
   }
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
@@ -166,7 +200,7 @@ function tallyTranscript(transcriptPath, known) {
     if (obj.type !== 'assistant') continue;
     const msg = obj && obj.message;
     try {
-      countSkillUses(msg, known, skills);
+      countSkillUses(msg, known, skills, commands, commandUses);
     } catch {
       /* usage evidence is best-effort — never let it break cost tracking */
     }
@@ -179,7 +213,7 @@ function tallyTranscript(transcriptPath, known) {
     m.cache_write += u.cache_creation_input_tokens || 0;
     m.cache_read += u.cache_read_input_tokens || 0;
   }
-  return { byModel, skills };
+  return { byModel, skills, commands: commandUses };
 }
 
 async function main() {
@@ -198,7 +232,13 @@ async function main() {
   } catch {
     known = new Set();
   }
-  const { byModel, skills } = tallyTranscript(transcriptPath, known);
+  let installedCommands;
+  try {
+    installedCommands = knownCommands();
+  } catch {
+    installedCommands = new Set();
+  }
+  const { byModel, skills, commands } = tallyTranscript(transcriptPath, known, installedCommands);
   const modelNames = Object.keys(byModel);
   if (modelNames.length === 0) return process.exit(0); // nothing to record
 
@@ -223,9 +263,10 @@ async function main() {
     total_usd: Number(totalUsd.toFixed(4)),
     total_tokens: totalTokens,
     models,
-    // Always emitted, even empty: `{}` records an observed session with no skill
-    // reference, while an absent key marks a row written before this existed.
+    // Always emitted, even empty: `{}` records an observed session with no
+    // reference, while an absent key marks a row written before that existed.
     skills,
+    commands,
   };
 
   try {

package/scaffold/scripts/hooks/statusline.mjs

@@ -3,9 +3,11 @@
  * 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.
+ * mode. Reads the session payload (JSON on stdin): the branch comes from the
+ * current dir, the .dw/ state from the project dir, since the shell may sit in a
+ * subdirectory. Falls back to $CLAUDE_PROJECT_DIR, then 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).
  */
@@ -93,23 +95,24 @@ function activeSpec(cwd) {
 
 async function main() {
   let cwd = process.cwd();
+  let root = process.env.CLAUDE_PROJECT_DIR || '';
   try {
     const payload = JSON.parse(await readStdin());
-    cwd =
-      (payload && payload.workspace && payload.workspace.current_dir) ||
-      (payload && payload.cwd) ||
-      cwd;
+    const workspace = (payload && payload.workspace) || {};
+    cwd = workspace.current_dir || (payload && payload.cwd) || cwd;
+    root = workspace.project_dir || root;
   } catch {
-    /* use process.cwd() */
+    /* use $CLAUDE_PROJECT_DIR / process.cwd() */
   }
+  root = root || cwd;
 
   const parts = [];
   const branch = gitBranch(cwd);
   if (branch) parts.push(`⎇ ${branch}`);
-  const spec = activeSpec(cwd);
+  const spec = activeSpec(root);
   if (spec) parts.push(spec);
-  parts.push(`min:${minimalismMode(cwd)}`);
-  const cost = costToday(cwd);
+  parts.push(`min:${minimalismMode(root)}`);
+  const cost = costToday(root);
   if (cost) parts.push(cost);
 
   process.stdout.write(`dw · ${parts.join(' · ')}`);

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -37,7 +37,7 @@ This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalo
 
 ```yaml
 # Generated by /dw-new-project on YYYY-MM-DD
-# Edit freely. Recipes live in .agents/skills/docker-compose-recipes/
+# Edit freely. Recipes live in .dw/skills/docker-compose-recipes/
 
 services:
   # --- storage tier ---

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

@@ -52,7 +52,9 @@ Structure:
 └── runs/<YYYY-MM-DD>.jsonl  # results of each eval run
 ```
 
-See `references/reference-dataset.md` for case-design principles, sampling from production, and when to expand the set.
+Eval-first: run a baseline on the current code before the change; new-behavior cases must fail there. Compare runs case by case: a case that passed and now fails blocks, whatever the average says. Never tune against the `holdout` split.
+
+See `references/reference-dataset.md` for case design, baseline, holdout, per-case drift and when to expand the set.
 
 ## Consistency (run-to-run stability)
 

package/scaffold/skills/dw-llm-eval/references/integration-with-dev-workflow-commands-detail.md

@@ -1,6 +1,6 @@
 ## Integration with dev-workflow commands
 
-- `/dw-plan tasks`: when the PRD has an AI feature requirement, an eval-plan subtask is mandatory. The task references this skill's oracle ladder.
+- `/dw-plan tasks`: when the PRD has an AI feature requirement, an eval-plan subtask is mandatory, ordered before the implementation subtasks: behavior spec, cases, baseline run (`references/reference-dataset.md` "Baseline before the change"). The task references this skill's oracle ladder.
 - `/dw-review --code-only`: AI feature PRs require a reference dataset + ≥2 oracle rungs (lower rungs FIRST). The constitution gate also applies — if the project has principles about AI feature reliability, they're enforced here.
-- `/dw-qa --ai`: new mode (when this skill is bundled) — runs the reference dataset against the current implementation, logs to `QA/logs/ai/<feature>-<date>.jsonl`, computes precision@k / faithfulness / outcome accuracy per the feature type.
+- `/dw-qa --ai`: new mode (when this skill is bundled) — runs the reference dataset against the current implementation, logs to `QA/logs/ai/<feature>-<date>.jsonl`, computes precision@k / faithfulness / outcome accuracy per the feature type, and lists per-case flips against the prior run.
 - `/dw-bugfix` when the bug is an AI failure mode (hallucination, tool misuse, classification error): adds the failing case to the reference dataset BEFORE fixing — the case is now a regression test forever.

package/scaffold/skills/dw-llm-eval/references/reference-dataset.md

@@ -37,6 +37,7 @@ Each case is one line in `cases.jsonl`:
 ```json
 {
   "id": "case-001",
+  "split": "dev",
   "input": {
     "user_message": "I want to cancel my subscription",
     "user_context": { "tier": "premium", "tenure_months": 18 }
@@ -60,6 +61,7 @@ Each case is one line in `cases.jsonl`:
 Fields:
 
 - **`id`** — stable identifier (you'll reference it in regression reports).
+- **`split`** — `dev` (you tune against it) or `holdout` (you never do). See "Held-out split".
 - **`input`** — what the system receives. Match the production input shape exactly.
 - **`expected`** — for rungs 1-3, the deterministic expected output or state change. For rung 4, the rubric-target (what a 5/5 answer would do).
 - **`rubric_criteria`** — which rubric dimensions this case exercises.
@@ -129,18 +131,70 @@ Process:
 4. **Categorize** — difficulty, tags, rubric criteria.
 5. **Promote** to `cases.jsonl` after review.
 
+## Baseline before the change
+
+> Eval-first, from LangChain's [eval-driven development](https://www.langchain.com/blog/what-is-eval-driven-development)
+> post (2026-11-09): the eval is written and run before the change it measures.
+
+When a task adds or changes an AI behavior, the eval exists before the implementation:
+
+1. **Spec the behavior, one at a time.** Four lines, definite enough to score pass/fail: when it should
+   happen, what the system does, what it must not do, and which existing behaviors must keep working.
+   "The answer is helpful" is not a spec.
+2. **Add the cases** for it: the new behavior, its must-not boundary (the near miss that should NOT
+   trigger it), and the existing cases that cover the keep-working list.
+3. **Run the baseline** on the current code, before any change, and save it as
+   `runs/<YYYY-MM-DD>-baseline.jsonl`.
+4. **Read the baseline.** New-behavior cases must fail there. A new case that already passes does not test
+   the change: rewrite it or drop it. Existing cases that pass are the regression set for this change.
+5. Implement, re-run, compare case by case (see "Detecting drift").
+
+Each line of a run file is one case:
+
+```json
+{"id": "case-001", "split": "dev", "pass": true, "score": 4, "commit": "a1b2c3d", "dataset_version": "2.3"}
+```
+
+`pass` is required (the verdict against the case's oracle); `score` only when a rung-4 judge produced one.
+
+## Held-out split
+
+Iterating until every case passes overfits the system to the dataset: the prompt learns the cases, not the
+behavior. Mark about 20% of cases `"split": "holdout"`, spread across difficulty and tags, and:
+
+- iterate against `dev` only — never read a holdout failure to decide the next prompt tweak;
+- run `holdout` before merge to main and before deploy;
+- if `dev` improves and `holdout` stays flat or drops, report overfitting instead of the improvement.
+
+A holdout case that was used to tune is no longer held out: move it to `dev` and add a fresh one.
+
 ## Sampling for regression runs
 
 You don't need to re-run the entire dataset every time. Smart sampling:
 
-- **PR-time:** random sample of 30% + all "high difficulty" cases + any case added in the last 30 days. Fast feedback.
-- **Pre-merge to main:** full dataset.
+- **PR-time:** `dev` split only — random sample of 30% + all "high difficulty" cases + any case added in the last 30 days. Fast feedback.
+- **Pre-merge to main:** full dataset, `holdout` included.
 - **Nightly:** full dataset + judge re-calibration check.
 - **Pre-deploy:** full dataset + manual eyeball on 10 random outputs.
 
 ## Detecting drift
 
-After each run, compare against the prior run on the SAME cases:
+After each run, compare against the prior run on the SAME cases — **case by case first, averages
+second.** An average can rise while a case that used to pass breaks: the change fixed five things and
+overwrote one behavior someone depends on.
+
+```
+Run 2026-05-08 vs 2026-05-01 (dataset 2.3, 24 cases):
+  flipped pass → fail: case-007 (dev), case-019 (holdout)
+  flipped fail → pass: case-021, case-022, case-023
+  unchanged: 19
+```
+
+The gate: **any case that passed in the prior run and fails now blocks**, whatever the average says, until
+it is fixed or accepted in writing (PR or techspec: case id, why the old behavior no longer holds). A
+fail → pass flip on a case nobody was working on is also worth a look: it may be judge drift, not progress.
+
+Then the metric deltas:
 
 ```
 Run 2026-05-08 vs 2026-05-01:

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

@@ -33,12 +33,13 @@ For the four grounding questions, read `references/the-four-grounding-questions-
 | Any UI work (the full version of the grounding) | `references/hard-gate.md` |
 | Reviewing or proposing a design | `references/visual-slop.md` (14 patterns + specific anti-default values) |
 | Designing state coverage | `references/state-matrix.md` |
+| Stress-testing with worst-case data (long names, `1 members`, 1,000 rows, 320px, 200% zoom) | `references/content-stress.md` |
 | Interactive widget (button, form, modal, anything clickable) | `references/accessibility-floor.md` |
 | No design authority exists in the project | `references/curated-defaults.md` (palettes / fonts / scales) |
 | Choosing or reviewing a palette / dark mode | `references/color-oklch.md` (OKLCH, tinted neutrals, contrast) |
 | Fonts, sizing, hierarchy, line length | `references/type-scale.md` (modular scale, pairing, measure) |
-| Adding animation or transitions | `references/motion.md` (easing, duration, reduced-motion) |
-| Cross-device / breakpoints / touch | `references/responsive.md` (mobile-first, container queries) |
+| Adding, reviewing or removing animation | `references/motion.md` (frequency gate, easing, performance, removal, review triggers) |
+| Cross-device / touch / mobile web | `references/responsive.md` (mobile-first, container queries, mobile fixes) |
 | Any user-facing copy (labels, errors, empty states) | `references/ux-writing.md` |
 
 ## The 14 visual-slop patterns (full catalog in `references/visual-slop.md`)
@@ -74,7 +75,8 @@ Before any interactive widget ships:
 - [ ] No keyboard traps.
 - [ ] Touch targets ≥24×24 CSS pixels (≥44×44 recommended on mobile).
 - [ ] Heading hierarchy is semantic (no skipped levels).
-- [ ] `prefers-reduced-motion` honored.
+- [ ] `prefers-reduced-motion` honored (gentler, not zero).
+- [ ] Zoom never disabled (no `user-scalable=no` / `maximum-scale=1`); content survives 200% zoom.
 
 Full verification recipes in `references/accessibility-floor.md`. `/dw-review --code-only` rejects the verdict if any interactive widget ships without these.
 
@@ -90,7 +92,8 @@ In all bend cases, document the bend in the PR (one line). "I skipped the state
 
 - `/dw-redesign-ui` runs the grounding end-to-end. Steps 4 (propose) and 7 (validate) consult this skill explicitly.
 - `/dw-plan techspec` UI sections must answer the 4 grounding questions and reference the state matrix.
-- `/dw-review --code-only` checks UI diffs against the 14 visual-slop patterns and the accessibility floor.
+- `/dw-review --code-only` checks UI diffs against the 14 visual-slop patterns, the accessibility floor, `motion.md` §9 triggers and `content-stress.md` static signals.
+- `/dw-qa` (UI mode) runs the content-stress pass.
 - `/dw-functional-doc` records the surface-job and scene sentences in the overview for each screen.
 
 ## Why this approach
@@ -108,5 +111,5 @@ When invoked directly or by a harness, return or merge this block:
 - **Evidence:** design source read, four grounding answers, states checked, screenshots, and accessibility checks.
 - **Artifacts:** UI proposal, design notes, state matrix, screenshot path, or QA finding.
 - **Decisions:** palette/type/component choices, state handling, and accepted deviations.
-- **Risks:** training-data defaults, missing states, contrast/focus failures, unreadable hierarchy, or mobile overflow.
+- **Risks:** training-data defaults, missing states, contrast/focus failures, unreadable hierarchy, worst-case data breaks, high-frequency motion, or mobile overflow.
 - **Next Step:** exact design/code/QA action or missing input to gather.

package/scaffold/skills/dw-ui-discipline/references/accessibility-floor.md

@@ -152,24 +152,34 @@ Screen readers switch pronunciation based on this.
 
 ### 10. Reduced motion respect
 
-Honor `prefers-reduced-motion`:
+Honor `prefers-reduced-motion`. It means fewer and gentler animations, not zero: drop movement (slide,
+scale, parallax), keep the opacity/color changes that show a state change.
 
 ```css
 @media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    transition-duration: 0.01ms !important;
-  }
+  .drawer { transition: opacity 200ms ease; transform: none; }
 }
 ```
 
 Or in Tailwind:
 ```html
-<div className="transition-all motion-reduce:transition-none">
+<div className="transition-transform motion-reduce:transition-none">
 ```
 
+A global `animation-duration: 0.01ms !important` reset is an acceptable project-wide fallback, as long as
+every state change stays visible. Details in `motion.md` §7.
+
 Vestibular disorders trigger on parallax, large slide-ins, infinite scroll animations.
 
+### 11. Zoom is never disabled
+
+`user-scalable=no` and `maximum-scale=1` in the viewport meta block pinch-zoom for low-vision users (WCAG
+1.4.4 Resize Text). They are usually added to stop iOS zooming into inputs; fix the cause instead —
+inputs at `font-size: 16px` or more (`responsive.md`, "Mobile platform fixes").
+
+Content must also survive **200% browser zoom** without clipping or overlapping: fixed heights on text
+boxes are the usual culprit (`content-stress.md`, Step 4).
+
 ## Verification recipes
 
 ### Automated (CI)
@@ -195,8 +205,9 @@ Run on every PR. Block merge on violations.
 1. Open the changed page.
 2. Tab through with keyboard only. Verify focus visible at every stop.
 3. Run axe DevTools, fix violations.
-4. Toggle prefers-reduced-motion in DevTools rendering panel. Verify animations stop.
-5. Test with screen reader (VoiceOver on Mac, NVDA on Windows) on at least one critical flow.
+4. Toggle prefers-reduced-motion in DevTools rendering panel. Verify movement stops and state changes stay visible.
+5. Zoom the page to 200%. Verify nothing clips, overlaps or becomes unreachable.
+6. Test with screen reader (VoiceOver on Mac, NVDA on Windows) on at least one critical flow.
 
 ### Spot checks
 
@@ -221,5 +232,6 @@ LLM-produced UI commonly fails on:
 - `outline: none` with no replacement focus state.
 - Modals that trap focus only on success path, not on error.
 - Auto-playing carousels with no pause control.
+- `user-scalable=no` / `maximum-scale=1` in the viewport meta.
 
 `/dw-review --code-only` runs axe-style checks on the diff for these.