@brunosps00/dev-workflow 2.1.0 → 2.3.0

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

@@ -1,72 +1,52 @@
 ---
 type: task
-schema_version: "1.0"
+schema_version: "1.1"
 status: pending
 ---
 
 # Tarefa X.0: [Título da Tarefa Principal]
 
-<critical>Ler os arquivos de prd.md e techspec.md desta pasta, se você não ler esses arquivos sua tarefa será invalidada</critical>
+Leia as seções relevantes do PRD/TechSpec e as restrições da task; use os links abaixo.
 
 ## Visão Geral
 
 [Breve descrição da tarefa]
 
-**Requisitos Funcionais cobertos**: RF-X.Y, RF-X.Z (máximo 2 por task)
+**Requisitos Funcionais cobertos**: RF-X.Y, RF-X.Z
 Depends on: none
 
 <requirements>
 [Lista de requisitos obrigatórios]
 </requirements>
 
-## Subtarefas
+## Escolha de execução
 
-### Implementação
-- [ ] X.1 [Descrição da subtarefa]
-- [ ] X.2 [Descrição da subtarefa]
+Espelhe a entrada aprovada desta task em `execution-plan.json` (veja `.dw/references/execution-contract.md`).
 
-### Testes Unitários (Obrigatório para Backend)
-- [ ] X.3 Criar testes para [service/use-case]
-- [ ] X.4 Criar testes para [controller/adapter]
+| Complexidade + justificativa | Ferramenta | Modelo / esforço | Agentes | Fallbacks aprovados |
+|---|---|---|---|---|
+| standard — [motivo] | local | inherit / inherit | nenhum | nenhum |
 
-## Testes Unitários
+## Implementação
 
-### Casos a Testar
+- [ ] [Comportamento a entregar]
+- [ ] [Verificações relevantes e critérios de aceitação]
 
-| Método | Casos |
-|--------|-------|
-| `[método1]` | Happy path, edge case, erro |
-| `[método2]` | Happy path, not found |
+## Verificação e critérios de sucesso
 
-### Mocks Necessários
-- `[repositório/service]` - mockado via mock function
+| Comportamento / risco | Suíte existente ou novo teste | Comando / evidência observável |
+|---|---|---|
+| [Resultado exigido] | [Menor camada eficaz; teste novo só se necessário] | [Comando do projeto ou inspeção] |
 
-## Detalhes de Implementação
+Use a estratégia de testes do projeto. Defina mocks só em fronteiras justificadas; não imponha percentuais de cobertura nem teste novo para toda edição. Inclua falhas relevantes quando aplicável.
 
-[Seções relevantes da spec técnica - referencie a techspec.md ao invés de duplicar conteúdo]
+## Arquivos e decisões relevantes
 
-## Critérios de Sucesso
+[Caminhos de código e seções relevantes do TechSpec/ADR; não duplique documentos inteiros.]
 
-- [Resultados mensuráveis]
-- [Requisitos de qualidade]
-- **Testes unitários passando**
-- **Cobertura mínima 80%** em services/use-cases
+## Commit ao concluir
 
-## Arquivos Relevantes
-- [Arquivos relevantes desta tarefa]
-- [Arquivo].spec.ts - Testes unitários
-
-## Commit ao Final
-
-Ao completar esta task, fazer commit:
-```bash
-git add .
-git commit -m "feat([modulo]): [descrição]
-
-- [item 1]
-- [item 2]
-- Add unit tests"
-```
+Use o protocolo de commit atômico com escopo do `/dw-run`. Faça stage apenas dos arquivos desta task, preserve IDs de requisitos, registre o SHA resultante em tasks.md/run-log e inclua os registros finais antes da entrega. Não implica push nem merge.
 
 ## Related ADRs
 

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

@@ -1,6 +1,6 @@
 ---
 type: tasks-index
-schema_version: "1.0"
+schema_version: "1.1"
 status: draft
 ---
 
@@ -34,10 +34,13 @@ feat/prd-[nome-funcionalidade]
 - [ ] 2.0 Título da Tarefa Principal        Depends on: 1.0
 - [ ] 3.0 Título da Tarefa Principal        Depends on: 1.0, 2.0
 
+## Plano de execução
+
+Proponha desenvolvimento local ou cruzado por task na quebra. Resuma complexidade/justificativa, ferramenta, modelo/esforço, agentes, dependências e verificação. Salve escolhas validadas e fallbacks aprovados em `execution-plan.json`; use `.dw/references/execution-contract.md`. Registre aprovação da mesma matriz antes de executar.
+
 ## Workflow
 
-Cada task segue o fluxo:
-1. `/dw-run [N]_task.md` - Implementa a task
-2. Testes unitários incluídos na implementação
-3. Commit ao final da task (sem push)
-4. Próxima task ou `/dw-generate-pr [branch-alvo]` quando todas concluídas
+1. `/dw-run` consome escolhas aprovadas em ordem de dependências.
+2. Cada task implementa, verifica e commita mudanças no escopo; o parent revisa handoffs externos e encaminha correções.
+3. Continue implementação aprovada até review final e QA aplicável. Pedido somente de planejamento termina no plano.
+4. Prepare entrega validada; integre/envie/publique só dentro da autorização existente.

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

@@ -78,6 +78,10 @@ type NomeServico interface {
 
 ## Sequenciamento de Desenvolvimento
 
+### Qualidade do Frontend (quando aplicável)
+
+[Leia a baseline de qualidade existente do módulo. Use linhas relevantes de `.dw/templates/frontend-quality-template.md` para contratos de API, tipos, limites de imports ou ferramentas de qualidade alterados. Registre fontes autoritativas, checks exatos, política atual, adoção proposta e evidência comportamental. Separe diagnósticos consultivos de gates obrigatórios; não transforme uma funcionalidade de UI em migração de ferramentas do repositório inteiro.]
+
 ### Ordem de Construção
 
 [Defina sequência de implementação:

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

@@ -23,6 +23,7 @@ export const DANGEROUS = [
   { re: /\bgit\s+reset\b[^\n|&;]*--hard\b/, why: 'hard reset discards uncommitted work and rewrites the branch' },
   { re: /\bgit\s+clean\b[^\n|&;]*-[a-z]*f/, why: 'git clean -f permanently deletes untracked files' },
   { re: /\bgit\s+branch\b[^\n|&;]*\s-D\b/, why: 'force-deletes a branch that may be unmerged' },
+  { re: /\bgit\s+worktree\s+remove\b[^\n|&;]*(--force\b|\s-f\b)/, why: 'force-removes a worktree that may hold uncommitted work — commit first or use /dw-worktree clean (never --force)' },
   { re: /\bgit\s+checkout\b[^\n|&;]*\s(--\s+\.|\.\s*$)/, why: 'discards all local changes in the working tree' },
   { re: /\bgit\s+restore\b[^\n|&;]*\s(--\s+)?\.(?=\s*(?:$|[|&;]))/, why: 'discards all local changes in the working tree' },
 ];

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

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