atlas-workflow 0.9.0 → 0.9.2

package/plugins/atlas-workflow-orchestrator/packages/skills/atlas-slice-review/scripts/classify_findings.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+export const SEVERITY_ORDER = Object.freeze({ P0: 0, P1: 1, P2: 2, P3: 3 });
+export const REQUIRED_TEXT_FIELDS = Object.freeze([
+  'task_id', 'title', 'file', 'failure_mode', 'evidence', 'recommendation', 'fix_validation',
+]);
+
+export function normalizeFinding(finding, index) {
+  if (!finding || typeof finding !== 'object' || Array.isArray(finding)) {
+    throw new Error(`Finding ${index} must be a JSON object`);
+  }
+  if (!(finding.severity in SEVERITY_ORDER)) {
+    throw new Error(`Finding ${index} has invalid severity: ${JSON.stringify(finding.severity)}`);
+  }
+  const missing = REQUIRED_TEXT_FIELDS.filter(
+    (field) => typeof finding[field] !== 'string' || !finding[field].trim(),
+  );
+  if (missing.length) throw new Error(`Finding ${index} missing required fields: ${missing.join(', ')}`);
+  if (!Number.isInteger(finding.line) || finding.line < 1) {
+    throw new Error(`Finding ${index} has invalid line: ${JSON.stringify(finding.line)}`);
+  }
+  return {
+    severity: finding.severity,
+    task_id: finding.task_id,
+    title: finding.title,
+    file: finding.file,
+    line: finding.line,
+    summary: typeof finding.summary === 'string' ? finding.summary : '',
+    failure_mode: finding.failure_mode,
+    evidence: finding.evidence,
+    recommendation: finding.recommendation,
+    fix_validation: finding.fix_validation,
+    diff_attributed: finding.diff_attributed !== false,
+  };
+}
+
+export function classifyFindings(payload) {
+  if (!Array.isArray(payload)) throw new Error('Findings input must be a JSON array');
+  return payload.map(normalizeFinding).sort((a, b) => (
+    SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]
+      || a.task_id.localeCompare(b.task_id)
+      || a.file.localeCompare(b.file)
+      || a.line - b.line
+  ));
+}
+
+export function run(argv = process.argv.slice(2)) {
+  if (argv.length !== 1) throw new Error('Usage: node classify_findings.mjs <findings.json>');
+  const payload = JSON.parse(fs.readFileSync(argv[0], 'utf8'));
+  process.stdout.write(`${JSON.stringify(classifyFindings(payload), null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  try { run(); } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/plugins/atlas-workflow-orchestrator/packages/skills/atlas-slice-review/scripts/classify_findings.py

@@ -1,56 +1,24 @@
 #!/usr/bin/env python3
-"""Normalize raw findings into a severity-oriented review structure."""
+"""Wrapper legado: delega ao gate Node canônico por uma release."""
 
 from __future__ import annotations
 
-import argparse
-import json
 import pathlib
+import subprocess
 import sys
-from typing import Any
-
-SEVERITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
-
-
-def load_findings(path: pathlib.Path) -> list[dict[str, Any]]:
-    payload = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(payload, list):
-        raise ValueError("Findings input must be a JSON array")
-    return payload
-
-
-def normalize_finding(finding: dict[str, Any]) -> dict[str, Any]:
-    severity = finding.get("severity", "P2")
-    if severity not in SEVERITY_ORDER:
-        severity = "P2"
-    return {
-        "severity": severity,
-        "task_id": finding.get("task_id", ""),
-        "title": finding.get("title", ""),
-        "file": finding.get("file", ""),
-        "line": finding.get("line"),
-        "summary": finding.get("summary", ""),
-        "evidence": finding.get("evidence", ""),
-        "diff_attributed": bool(finding.get("diff_attributed", True)),
-    }
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("findings_json", help="Path to a JSON array of findings")
-    args = parser.parse_args()
-
+    if len(sys.argv) != 2:
+        sys.stderr.write("Usage: python classify_findings.py <findings.json>\n")
+        return 1
+    script = pathlib.Path(__file__).with_name("classify_findings.mjs")
     try:
-        normalized = [normalize_finding(item) for item in load_findings(pathlib.Path(args.findings_json))]
-    except (FileNotFoundError, ValueError, json.JSONDecodeError) as exc:
-        sys.stderr.write(f"{exc}\n")
+        return subprocess.run(["node", str(script), sys.argv[1]], check=False).returncode
+    except FileNotFoundError:
+        sys.stderr.write("Node.js ausente: requisito runtime do Atlas\n")
         return 1
 
-    normalized.sort(key=lambda item: (SEVERITY_ORDER[item["severity"]], item["task_id"], item["file"], item["line"] or 0))
-    json.dump(normalized, sys.stdout, indent=2)
-    sys.stdout.write("\n")
-    return 0
-
 
 if __name__ == "__main__":
     raise SystemExit(main())

package/plugins/atlas-workflow-orchestrator/packages/skills/atlas-sprint-prd-generator/SKILL.md

@@ -16,6 +16,7 @@ Todo PRD gerado por esta skill deve declarar explicitamente a cadeia de execuç
 * Sprint ID: `S<NN>` (`S01`, `S02`, etc.).
 * Opcional: app/projeto alvo quando houver mais de uma fonte de backlog/roadmap.
 * Opcional: path de saída.
+* Opcional: path explícito do backlog autoritativo. Quando fornecido, vence qualquer descoberta.
 
 *Se faltar o Sprint ID, peça antes de gerar.*
 
@@ -23,10 +24,11 @@ Todo PRD gerado por esta skill deve declarar explicitamente a cadeia de execuç
 
 ## Workflow Obrigatório
 
-1. **Localizar Insumos:** Descubra a raiz do repo com `git rev-parse --show-toplevel`. Localize o template canônico em `<raiz-do-plugin>/packages/templates/PRD_TEMPLATE.md`. Localize backlog/roadmap no repo ativo (`**/BACKLOG_MESTRE*.md`).
-2. **Extração da Sprint:** Leia a fonte de backlog/roadmap. Localize a sprint, extraindo fase-fonte, objetivo, dependências e filename do PRD.
-3. **Inspecionar Código:** Busque no codebase por classes, tabelas, RPCs, mappers e rotas existentes que influenciam a feature.
-4. **Redação do PRD:** Siga estritamente o layout enxuto e focado do `PRD_TEMPLATE.md` (teto orientativo de ~180-220 linhas), separando dores e regras de negócio de implementações de código.
+1. **Localizar Insumos:** Descubra a raiz do repo com `git rev-parse --show-toplevel`. Localize o template canônico em `<raiz-do-plugin>/packages/templates/PRD_TEMPLATE.md`. Localize backlogs candidatos (`**/BACKLOG_MESTRE*.md`) sem escolher por heurística silenciosa.
+2. **Fechar autoridade:** use `../_shared/scripts/document_quality.mjs#resolveSprintAuthority` com precedência fixa: path explícito → backlog canônico referenciado pelo artefato/input → único candidato contendo o Sprint ID. Zero match bloqueia. Múltiplos matches sem autoridade, mesmo com conteúdo parecido, bloqueiam com paths conflitantes e `next_action` para informar o path.
+3. **Extração da Sprint:** leia somente a fonte autoritativa. Extraia fase-fonte, objetivo, dependências e filename do PRD; registre no PRD o path + anchor exato da linha/seção do backlog.
+4. **Inspecionar Código:** Busque no codebase por contratos reais que influenciam a feature e registre anchors estáveis (`path:símbolo` ou `path:linha`) nas referências; não copie implementação para o PRD.
+5. **Redação/atualização:** siga `PRD_TEMPLATE.md`. Ao atualizar, preserve IDs `D*`, decisões fechadas, anchors e histórico; novos IDs são append-only. Mudança deliberada em D* exige decisão explícita e registro histórico.
 
 ### Resolução Canônica de Templates
 
@@ -57,6 +59,7 @@ Todo PRD criado ou atualizado por esta skill deve incluir, perto do topo e sem s
 
 * **Status final:** `Aprovado para implementação`. Setar **automaticamente** ao finalizar a geração — é o status que o gate TC do orquestrador exige (`required_status=Aprovado para implementação`) para o PRD avançar no pipeline. Não deixar `Draft` (trava o gate e força correção manual). O sinal de determinismo que sustenta o avanço é o `atlas_scan_prd` (varredura de ambiguidade) + entrevista quando houver padrões bloqueantes — não o campo Status, que é marcador documental.
 * **Data:** ISO `YYYY-MM-DD` (hoje).
+* **Autoridade:** `Relacionado`/`Referências` inclui backlog autoritativo + anchor da sprint e anchors de código/contrato usados.
 * **Escopo:** Lista fechada de capacidades funcionais.
 * **UX:** Cobrir caminhos de `loading`, `empty`, `error`, `success` e `permission` sob a perspectiva do usuário.
 * **Critérios de Aceite:** Binários e observáveis, divididos conforme `PRD_TEMPLATE.md` em: **Produto**, **UX**, **Dados** e **Regressão de produto**.

package/plugins/atlas-workflow-orchestrator/packages/skills/atlas-task-validator/SKILL.md

@@ -34,9 +34,16 @@ Read the JSON file at `.atlas/state/<run_id>/<slice>.json` using the schema in `
 3. **Executed task ids** — `tasks`.
 4. **Boundary refs** — `boundary_refs`.
 5. **Explicit cold-review note** — you did not observe implementation; read current code only.
+6. **Deterministic boundary** — `base_sha`, `head_sha`, `contract_kind`, and all evidence/probe arrays.
+7. **Working-tree delta** — compare `worktree_baseline`/`worktree_final` and current tree; unchanged preexisting dirt stays outside, later mutations must be evidenced.
+8. **Repair correlation** — on attempt 2, correlate every target finding id with `repair_evidence` in the same state path.
 
 Do not accept inline contract, copied diff, or pasted task lists as the validation boundary. If `state_path` is missing, unreadable, or lacks any required field, return JSON with `verdict: "fail"` and one P1 finding for `Input insuficiente: <missing item>`.
 
+Compatibilidade: state legado mínimo sem `contract_kind` só é aceito quando `executor_skill=atlas-plan-execute`; nesse caso o plano continua autoritativo. State de `atlas-direct-execute` exige extensão completa e `obligations` não vazio.
+
+Antes de validar código, compare `base_sha...head_sha`, `HEAD`, snapshot final atual e delta `worktree_baseline→worktree_final` com `files_changed`/evidências. Não infira base pelo nome da branch. Divergência gera `boundary_violations` e finding P1 estruturado.
+
 ---
 
 ## Resolução Canônica de Templates
@@ -79,23 +86,24 @@ Do not accept inline contract, copied diff, or pasted task lists as the validati
 3. **For each relevant Section 6 Contract:** verify signature, behavior, and returned shape where applicable.
 4. **For each relevant Section 8 checklist item:** mark it pass or fail with evidence.
 5. **Perform cross-task checks** for shared state, missing required args, route order, partial failure handling, and UI/backend permission mismatch.
-6. **Apply universal baseline checks** below. Do not invent new mandatory criteria outside the plan and baseline.
+6. **Aplique baseline + perfis ativos** abaixo. Resolva os perfis por manifests/comandos reais conforme `../_shared/references/stack-profiles.md`; não invente critérios fora do plano, baseline e perfis ativos.
 7. **Do not patch files or propose diffs.** Suggested fix must fit in 1-2 lines of text.
 
 ---
 
-## Universal Baseline
+## Baseline universal + perfis
+
+Fonte compartilhada: `../_shared/references/stack-profiles.md`. Execute `detectStackProfiles(project_root, declared_commands, boundary_paths)` de `../_shared/scripts/document_quality.mjs`; aplique cada entrada de `boundaries` somente aos arquivos daquele package.
+
+Sempre aplique baseline universal: segurança/permissões, boundary/contratos, erros/falhas parciais, concorrência/reentrada, cleanup/estado stale, integridade de dados/input e checks realmente declarados.
+
+Ative regras específicas somente quando o perfil retornar `true`:
 
-Always apply these checks:
-* **Naming cross-layer:** New read methods use `get*` prefix. Mutation uses explicit verbs (`create`, `update`, `delete`, `add`, `remove`). Concepts keep consistent root names across layers.
-* **State lifecycle:** Shared stores or controllers reused across modes or routes must reset previous mode state in `init()` or transition.
-* **Navigation args:** Argument resolvers validate required fields; navigation passes all required ids (no empty placeholder `''`).
-* **Partial failure paths:** Multi-step mutations surface partial persistence clearly if a later step fails.
-* **Backend and UI gate match:** Sensitive mutations require server-side enforcement. UI gating alone is insufficient (Page reads `canManage` from Store).
-* **Route registration:** Literal routes are registered before parameterized routes (`/:id`, `/:id/edit`) under the same prefix.
-* **Localization:** New localization keys must exist in every required locale file; generated l10n is clean.
-* **Analyzer:** `flutter analyze` (or stack equivalent) returns zero issues for touched files in boundary.
-* **Casts and nullability:** Remote payload casts use safe defensive patterns; nulos in collections treated with `?? []`.
+- `flutter_dart`: lifecycle Flutter, rotas/args, null-safety/casts, l10n, analyze/test; GetX somente se dependência/import/regra real confirmar GetX.
+- `node_typescript`: handles/promises, validação runtime, ESM/CJS/exports/tipos e scripts Node reais.
+- `python`: context managers/cleanup, exceções/async, typing/parsing e ferramentas Python declaradas.
+
+Monorepo pode ativar múltiplos perfis, sempre restritos ao boundary correspondente. Fixture Node sem sinal Flutter não recebe regra Flutter/GetX.
 
 ---
 
@@ -110,10 +118,15 @@ Return strict JSON as the final output. Do not wrap it in Markdown and do not pr
   "verdict": "pass | fail | pass_with_observations",
   "findings": [
     {
+      "id": "F-001",
       "severity": "P0|P1|P2|P3",
       "file": "string",
-      "line": 0,
-      "msg": "string"
+      "line": 1,
+      "failure_mode": "string",
+      "evidence": "string",
+      "recommendation": "string",
+      "fix_validation": "string",
+      "msg": "string (deprecated; derivado por uma release)"
     }
   ],
   "observations": [
@@ -134,6 +147,8 @@ Return strict JSON as the final output. Do not wrap it in Markdown and do not pr
 
 `dispatch_token` must equal `validator_recovery.expected_dispatch_token`. `findings`, `observations`, and `boundary_violations` must always be arrays. Use empty arrays when there are no items.
 
+IDs são únicos, obrigatórios no formato `F-NNN` e estáveis nos dois ciclos. Severity é estritamente `P0|P1|P2|P3`. No segundo ciclo, confirme por ID que `repair_evidence` registra arquivos, checks e `status: resolved`; finding não correlacionado permanece P1. O MCP rejeita shape incompleto e `pass`/`pass_with_observations` quando há P0/P1.
+
 **Proof-of-work (`challenge_response`).** If `validator_recovery.challenge` is not `null`, it carries `{ file, algo: "sha256" }` — a boundary file you must have read access to. Compute the sha256 of that file's raw bytes (`shasum -a 256 "<challenge.file>"`) and return the hex (first token) in `challenge_response`. If `challenge` is `null`, return `null`. Never fabricate the hash: the orchestrator recomputes it from disk and blocks the slice (`challenge_failed`) on mismatch. This is a *mechanical* attestation that the verdict touched real boundary bytes — it closes the laziest bypass (claiming `pass` with no read at all); it does **not** by itself prove you read and understood the code (hashing a file does not require loading its content). Reading the boundary remains your obligation. It is not a non-forgeable isolation proof either (the MCP shares one stdio caller). Challenge failures are bounded per attempt: past the cap the slot closes terminally (`challenge_exhausted`), which usually signals path resolution diverging from the consumer root.
 
 ---

package/plugins/atlas-workflow-orchestrator/packages/templates/BACKLOG_MESTRE_TEMPLATE.md

@@ -811,7 +811,17 @@ Ações imediatas:
 
 ---
 
-## 21. Como usar este template
+## 21. Registro de alterações
+
+Registro append-only de atualizações deste backlog. Não substitui decisões da seção 18.
+
+| Data | IDs afetados | Alteração | Motivo / fonte |
+|---|---|---|---|
+| [AAAA-MM-DD] | [SNN/DEC-N/RN] | [resumo objetivo] | [pedido, PRD, contrato ou código] |
+
+---
+
+## 22. Como usar este template
 
 ### Setup inicial
 
@@ -840,5 +850,6 @@ Ações imediatas:
 ### Manter vivo
 
 16. Toda decisão que muda escopo, contrato ou sequência atualiza: fonte canônica → PRD afetado → este backlog.
-17. Registrar decisões na seção 18 e riscos na seção 19.
-18. Manter o registro de sprints (seção 7) e o progresso (seção 8.2) como fonte de estado do projeto.
+17. Em updates, preservar IDs, sprints `done`, decisões fechadas e itens não relacionados; bloquear ciclos, enums inválidos e placeholders acidentais.
+18. Registrar decisões na seção 18, riscos na seção 19 e cada update no registro append-only da seção 21.
+19. Manter o registro de sprints (seção 7) e o progresso (seção 8.2) como fonte de estado do projeto.

package/plugins/atlas-workflow-orchestrator/packages/templates/PRD_TEMPLATE.md

@@ -16,6 +16,7 @@
 | **Data** | <YYYY-MM-DD> |
 | **Dependências de negócio** | <Entregas anteriores necessárias — ex.: “dashboard com lista”> |
 | **Relacionado** | <Regras de negócio, MVP, backlog §X, DEC-*, Q-* — links> |
+| **Fonte da sprint** | <path explícito do backlog autoritativo + anchor único SNN> |
 
 ### Metadados de execução
 
@@ -134,7 +135,7 @@
 
 **Dependências:** <ID entrega — por que bloqueia ou alimenta> · <decisão externa, se houver>
 
-**Referências:** <PRD pai, regras de negócio, backlog — sem listar arquivos de código>
+**Referências:** <PRD pai, regras de negócio, backlog autoritativo + anchor; anchors de contrato/código usados na validação, sem copiar implementação>
 
 **Histórico:** <YYYY-MM-DD — evento>
 

package/plugins/atlas-workflow-orchestrator/packages/templates/STATE_FILE_SCHEMA.md

@@ -8,7 +8,7 @@ Path:
 .atlas/state/<run_id>/<slice>.json
 ```
 
-Schema mínimo:
+Schema legado mínimo (reader compatível):
 
 ```json
 {
@@ -24,9 +24,33 @@ Schema mínimo:
 }
 ```
 
+Extensão determinística (writer atual):
+
+```json
+{
+  "base_sha": "40-char git commit SHA",
+  "head_sha": "40-char git commit SHA",
+  "contract_kind": "plan | direct",
+  "obligations": [{"id": "O1", "requirement": "...", "expected_evidence": ["path/test/check"]}],
+  "invariants": [{"id": "I1", "requirement": "...", "expected_evidence": ["path/check"]}],
+  "scenario_probes": [{"id": "S1", "scenario": "...", "expected": "..."}],
+  "risk_probes": [{"id": "R1", "risk": "...", "probe": "..."}],
+  "validation_map": [{"obligation_ids": ["O1"], "checks": ["node --test ..."], "status": "passed"}],
+  "task_evidence": [{"task": "T01", "files": ["packages/foo.js"], "checks": ["node --test ..."], "result": "passed"}],
+  "repair_evidence": [{"finding_id": "F-001", "files_touched": ["packages/foo.js"], "checks_run": ["node --test ..."], "status": "resolved"}],
+  "worktree_baseline": [{"path": "preexisting.txt", "status": "M", "sha256": "<64 hex>"}],
+  "worktree_final": [{"path": "preexisting.txt", "status": "M", "sha256": "<64 hex>"}]
+}
+```
+
 Regras:
 
 - `run_id`, `slice`, `tasks`, `files_changed`, `diff_stat`, `plan_path`, `boundary_refs`, `executed_at` e `executor_skill` são obrigatórios.
 - `files_changed` contém paths relativos ao repositório consumidor.
 - `boundary_refs` aponta para invariantes, contratos ou tasks do plano que delimitam a validação.
 - O arquivo é uma projeção de boundary para o validator; estado de run continua tendo `atlas_run_state` como fonte primária quando MCP estiver disponível.
+- Writers atuais sempre preenchem a extensão. `contract_kind=direct` exige `obligations` não vazio; `plan` mantém o contrato autoritativo em `plan_path`.
+- Writers capturam `worktree_baseline` antes da primeira mutação e `worktree_final` imediatamente antes do handoff. Ambos usam entradas únicas/ordenadas `{path,status,sha256}`; `status` é `A|M|D|R|C|T|U`, delete usa `sha256:null`, symlink usa SHA-256 do target textual.
+- Readers aceitam temporariamente o schema legado mínimo somente para `atlas-plan-execute` sem `contract_kind`. `atlas-direct-execute` nunca degrada para legado.
+- `base_sha` e `head_sha` são commits explícitos; não inferir base pelo nome da branch. `files_changed` e os arquivos de `task_evidence`/`repair_evidence` devem ser exatamente o diff `base_sha...head_sha` somado ao delta `worktree_baseline→worktree_final`. Dirty preexistente byte/status-idêntico fica fora.
+- `repair_evidence` é aditivo e obrigatório por finding P0/P1 estruturado após repair; o segundo validator correlaciona pelo mesmo `finding_id`.

package/plugins/atlas-workflow-orchestrator/skills/_shared/references/stack-profiles.md

@@ -0,0 +1,36 @@
+# Baseline universal e perfis de stack
+
+Ativação é determinística: inspecione manifests no boundary e comandos realmente declarados no repo/plano. Use `detectStackProfiles(project_root, declared_commands, boundary_paths)`; consuma o array `boundaries` e não deduza stack por extensão isolada.
+
+## Baseline universal — sempre ativo
+
+- segurança, autenticação/autorização e dados sensíveis;
+- boundary real, contratos, schemas e consumidores afetados;
+- erros, falhas parciais, concorrência, idempotência e reentrada;
+- setup/cleanup, recursos, estado stale e persistência;
+- integridade de dados, nulos, enums, validação de input;
+- checks declarados pelo repo/plano, sem inventar ferramenta.
+
+## Flutter/Dart — `pubspec.yaml` ou comando `flutter`/`dart`
+
+- lifecycle de Widget/Controller/Store, dispose/reset e async stale;
+- rotas literais antes de parametrizadas quando o roteador exigir;
+- args obrigatórios, null-safety, casts defensivos, coleções `?? []`;
+- l10n em todos os locales e geração limpa;
+- `flutter analyze`/`flutter test` somente quando declarados/aplicáveis;
+- GetX apenas quando dependência/import/regras reais do repo confirmarem GetX.
+
+## Node/TypeScript — `package.json`, `tsconfig.json` ou comando Node real
+
+- lifecycle de processos/handles, abort/cleanup e promises rejeitadas;
+- validação runtime nas fronteiras JSON/HTTP/MCP;
+- ESM/CJS, exports, tipos e scripts realmente declarados;
+- `node --test`, test runner, lint/typecheck apenas se presentes no repo/plano.
+
+## Python — `pyproject.toml`, `requirements.txt`, `setup.py` ou comando Python real
+
+- context managers, cleanup, exceções e async/cancelamento;
+- parsing/typing nas fronteiras e mutabilidade de defaults;
+- `pytest`, `ruff`, `mypy` ou equivalente apenas se declarados.
+
+Perfis podem coexistir em monorepo. Regra de perfil nunca vira finding fora do boundary onde seu sinal foi ativado.

package/plugins/atlas-workflow-orchestrator/skills/_shared/scripts/document_quality.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const VALID = Object.freeze({
+  moscow: new Set(['Must', 'Should', 'Could', "Won't now"]),
+  gain: new Set(['alto', 'médio', 'baixo']),
+  effort: new Set(['alto', 'médio', 'baixo']),
+  priority: new Set(['P0', 'P1', 'P2', 'P3']),
+  state: new Set(['backlog', 'ready', 'doing', 'review', 'done', 'blocked']),
+});
+
+const STACK_MANIFESTS = ['package.json', 'tsconfig.json', 'pubspec.yaml', 'pyproject.toml', 'requirements.txt', 'setup.py'];
+
+function boundaryRoot(projectRoot, boundary) {
+  const project = path.resolve(projectRoot);
+  let current = path.resolve(project, boundary ?? '.');
+  const relative = path.relative(project, current);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`BOUNDARY_OUTSIDE_PROJECT:${boundary}`);
+  }
+  if (fs.existsSync(current) && fs.statSync(current).isFile()) current = path.dirname(current);
+  while (current === project || current.startsWith(`${project}${path.sep}`)) {
+    if (STACK_MANIFESTS.some((name) => fs.existsSync(path.join(current, name)))) return current;
+    if (current === project) break;
+    current = path.dirname(current);
+  }
+  return path.resolve(project, boundary ?? '.');
+}
+
+function containsGetxImport(root) {
+  const queue = ['lib', 'test'].map((name) => path.join(root, name)).filter((dir) => fs.existsSync(dir));
+  let inspected = 0;
+  while (queue.length > 0 && inspected < 5000) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) queue.push(target);
+      else if (entry.isFile() && entry.name.endsWith('.dart')) {
+        inspected += 1;
+        if (/package:get\/get(?:_core)?\.dart/.test(fs.readFileSync(target, 'utf8'))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function detectBoundaryProfile(root, declaredCommands) {
+  const exists = (name) => fs.existsSync(path.join(root, name));
+  const commands = declaredCommands.filter((v) => typeof v === 'string');
+  let packageJson = null;
+  if (exists('package.json')) {
+    try { packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch {}
+  }
+  let pubspec = '';
+  if (exists('pubspec.yaml')) {
+    try { pubspec = fs.readFileSync(path.join(root, 'pubspec.yaml'), 'utf8'); } catch {}
+  }
+  const packageCommands = Object.values(packageJson?.scripts ?? {}).filter((v) => typeof v === 'string');
+  const allCommands = [...commands, ...packageCommands];
+  const hasCommand = (re) => allCommands.some((command) => re.test(command));
+  return {
+    universal: true,
+    flutter_dart: exists('pubspec.yaml') || hasCommand(/\b(flutter|dart)\b/),
+    node_typescript: exists('package.json') || exists('tsconfig.json') || hasCommand(/\b(node|npm|pnpm|yarn|bun|tsc)\b/),
+    python: exists('pyproject.toml') || exists('requirements.txt') || exists('setup.py') || hasCommand(/\b(python3?|pytest|ruff|mypy)\b/),
+    getx: /^\s{0,4}get\s*:/m.test(pubspec) || containsGetxImport(root),
+  };
+}
+
+export function detectStackProfiles(root, declaredCommands = [], boundaryPaths = ['.']) {
+  const project = path.resolve(root);
+  const requested = boundaryPaths.length > 0 ? boundaryPaths : ['.'];
+  const boundaries = [...new Set(requested.map((boundary) => boundaryRoot(project, boundary)))].map((dir) => ({
+    boundary: path.relative(project, dir).replaceAll('\\', '/') || '.',
+    ...detectBoundaryProfile(dir, declaredCommands),
+  }));
+  return {
+    universal: true,
+    flutter_dart: boundaries.some((profile) => profile.flutter_dart),
+    node_typescript: boundaries.some((profile) => profile.node_typescript),
+    python: boundaries.some((profile) => profile.python),
+    getx: boundaries.some((profile) => profile.getx),
+    boundaries,
+  };
+}
+
+function parseTable(markdown, heading) {
+  const start = markdown.indexOf(heading);
+  if (start < 0) return [];
+  const tail = markdown.slice(start + heading.length);
+  const end = tail.search(/\n##?\s/);
+  return (end < 0 ? tail : tail.slice(0, end)).split('\n')
+    .filter((line) => /^\|.*\|\s*$/.test(line))
+    .map((line) => line.split('|').slice(1, -1).map((cell) => cell.trim()))
+    .filter((cells) => cells.length && !cells.every((cell) => /^-+$/.test(cell)));
+}
+
+export function parseSprintRows(markdown) {
+  const rows = parseTable(markdown, '## 7. Registro de sprints');
+  const header = rows.findIndex((row) => row[0] === 'ID');
+  return rows.slice(header + 1).filter((row) => /^S\d{2}[a-z]?$/.test(row[0])).map((row) => ({
+    id: row[0], name: row[1], phase: row[2], objective: row[3], moscow: row[4], gain: row[5].toLowerCase(),
+    effort: row[6].toLowerCase(), priority: row[7], prd: row[8], dependencies: row[9], state: row[10], gate: row[11], raw: row,
+  }));
+}
+
+export function parseDecisionRows(markdown) {
+  const rows = parseTable(markdown, '### Decisões bloqueantes');
+  const header = rows.findIndex((row) => row[0] === 'ID');
+  return rows.slice(header + 1).filter((row) => /^D\d+$/.test(row[0])).map((row) => ({
+    id: row[0], decision: row[1], blocks: row[2], owner: row[3], status: row[4], raw: row,
+  }));
+}
+
+function dependencyIds(value) {
+  if (!value || value === '—') return [];
+  return [...value.matchAll(/S\d{2}[a-z]?/g)].map((match) => match[0]);
+}
+
+function findCycle(rows) {
+  const graph = new Map(rows.map((row) => [row.id, dependencyIds(row.dependencies)]));
+  const visiting = new Set(); const visited = new Set();
+  const walk = (id, chain = []) => {
+    if (visiting.has(id)) return [...chain.slice(chain.indexOf(id)), id];
+    if (visited.has(id)) return null;
+    visiting.add(id);
+    for (const dep of graph.get(id) ?? []) {
+      const cycle = walk(dep, [...chain, id]);
+      if (cycle) return cycle;
+    }
+    visiting.delete(id); visited.add(id); return null;
+  };
+  for (const id of graph.keys()) { const cycle = walk(id); if (cycle) return cycle; }
+  return null;
+}
+
+function changeLogBody(markdown) {
+  const match = /^##\s+(?:Registro de alterações|Histórico de alterações)\s*$/im.exec(markdown);
+  if (!match) return null;
+  const tail = markdown.slice(match.index + match[0].length);
+  const end = tail.search(/\n##\s+/);
+  return (end < 0 ? tail : tail.slice(0, end)).trim();
+}
+
+export function validateBacklogUpdate(before, after, { authorizedIds = [] } = {}) {
+  const errors = [];
+  const authorized = new Set(authorizedIds);
+  const oldRows = parseSprintRows(before); const newRows = parseSprintRows(after);
+  const oldById = new Map(oldRows.map((row) => [row.id, row]));
+  const newById = new Map(newRows.map((row) => [row.id, row]));
+  if (oldById.size !== oldRows.length) errors.push('DUPLICATE_SPRINT_ID_BEFORE');
+  if (newById.size !== newRows.length) errors.push('DUPLICATE_SPRINT_ID_AFTER');
+  for (const [id, oldRow] of oldById) {
+    const next = newById.get(id);
+    if (!next) errors.push(`SPRINT_REMOVED:${id}`);
+    else if (JSON.stringify(oldRow.raw) !== JSON.stringify(next.raw) && !authorized.has(id)) {
+      errors.push(oldRow.state === 'done' ? `DONE_SPRINT_CHANGED:${id}` : `UNAUTHORIZED_SPRINT_CHANGED:${id}`);
+    }
+  }
+  const oldDecisions = new Map(parseDecisionRows(before).map((row) => [row.id, row]));
+  const newDecisions = new Map(parseDecisionRows(after).map((row) => [row.id, row]));
+  for (const [id, row] of oldDecisions) {
+    const next = newDecisions.get(id);
+    if (!next) errors.push(`DECISION_REMOVED:${id}`);
+    else if (/^(decidido|fechado|aprovado)$/i.test(row.status)
+      && JSON.stringify(row.raw) !== JSON.stringify(next.raw) && !authorized.has(id)) errors.push(`CLOSED_DECISION_CHANGED:${id}`);
+  }
+  for (const row of newRows) {
+    for (const [field, values] of Object.entries(VALID)) if (!values.has(row[field])) errors.push(`INVALID_ENUM:${row.id}:${field}:${row[field]}`);
+    for (const dependency of dependencyIds(row.dependencies)) {
+      if (!newById.has(dependency)) errors.push(`DEPENDENCY_NOT_FOUND:${row.id}:${dependency}`);
+    }
+  }
+  const cycle = findCycle(newRows); if (cycle) errors.push(`DEPENDENCY_CYCLE:${cycle.join('>')}`);
+  if (/\[(?:NOME_|RESULTADO_|observação|decisão|slug|pendente\])/i.test(after)) errors.push('UNRESOLVED_PLACEHOLDER');
+  if (before !== after) {
+    const oldLog = changeLogBody(before);
+    const newLog = changeLogBody(after);
+    if (newLog === null) errors.push('CHANGELOG_REQUIRED');
+    else if (oldLog !== null && !newLog.startsWith(oldLog)) errors.push('CHANGELOG_REWRITTEN');
+    else if (newLog === oldLog) errors.push('CHANGELOG_ENTRY_REQUIRED');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function resolveSprintAuthority({ sprintId, explicitPath, canonicalPath, candidates }) {
+  const normalized = candidates.map((candidate) => ({ ...candidate, path: path.resolve(candidate.path) }));
+  const byPath = (target) => normalized.find((candidate) => candidate.path === path.resolve(target));
+  if (explicitPath) {
+    const match = byPath(explicitPath); if (!match?.sprints.includes(sprintId)) throw new Error(`SPRINT_NOT_FOUND_IN_EXPLICIT_PATH:${sprintId}`); return match;
+  }
+  if (canonicalPath) {
+    const match = byPath(canonicalPath); if (!match?.sprints.includes(sprintId)) throw new Error(`SPRINT_NOT_FOUND_IN_CANONICAL_BACKLOG:${sprintId}`); return match;
+  }
+  const matches = normalized.filter((candidate) => candidate.sprints.includes(sprintId));
+  if (matches.length !== 1) throw new Error(matches.length ? `AMBIGUOUS_BACKLOG_AUTHORITY:${matches.map((m) => m.path).join(',')}` : `SPRINT_NOT_FOUND:${sprintId}`);
+  return matches[0];
+}
+
+export function closedDecisionIds(prd) {
+  return new Set([...prd.matchAll(/^\|\s*(D\d+)\s*\|\s*(?!<|\[)(.+?)\s*\|\s*$/gm)].map((match) => match[1]));
+}
+
+export function pendingInterviewQuestions(prd, questions) {
+  const closed = closedDecisionIds(prd);
+  return questions.filter((question) => !closed.has(question.decision_id));
+}
+
+export function applyInterviewRound(prd, answers, date = new Date().toISOString().slice(0, 10)) {
+  const ids = new Set();
+  for (const answer of answers) {
+    if (!answer || typeof answer.decision_id !== 'string' || !/^D\d+$/.test(answer.decision_id)) throw new Error('INVALID_DECISION_ID');
+    if (ids.has(answer.decision_id)) throw new Error(`DUPLICATE_DECISION_ID:${answer.decision_id}`);
+    if (typeof answer.value !== 'string' || !answer.value.trim()) throw new Error(`EMPTY_DECISION_VALUE:${answer.decision_id}`);
+    ids.add(answer.decision_id);
+  }
+  let updated = prd;
+  for (const answer of answers) {
+    const row = new RegExp(`^\\|\\s*${answer.decision_id}\\s*\\|.*$`, 'm');
+    const replacement = `| ${answer.decision_id} | ${answer.value} |`;
+    updated = row.test(updated) ? updated.replace(row, replacement) : updated.replace(/(\| ID \| Decisão \|\n\|[-| ]+\|)/, `$1\n${replacement}`);
+  }
+  const log = `${date} — entrevista: ${answers.map((answer) => answer.decision_id).join(', ')} persistida(s)`;
+  updated = /\*\*Histórico:\*\*/.test(updated)
+    ? updated.replace(/(\*\*Histórico:\*\*[^\n]*)/, `$1 · ${log}`)
+    : `${updated.trimEnd()}\n\n**Histórico:** ${log}\n`;
+  return updated;
+}
+
+export function persistInterviewRound(prdPath, answers, date = new Date().toISOString().slice(0, 10)) {
+  const absolute = path.resolve(prdPath);
+  const temporary = path.join(path.dirname(absolute), `.${path.basename(absolute)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    const current = fs.readFileSync(absolute, 'utf8');
+    const updated = applyInterviewRound(current, answers, date);
+    const materialized = closedDecisionIds(updated);
+    const missingBeforeWrite = answers.filter((answer) => !materialized.has(answer.decision_id));
+    if (missingBeforeWrite.length > 0) {
+      throw new Error(`DECISION_NOT_MATERIALIZED:${missingBeforeWrite.map((answer) => answer.decision_id).join(',')}`);
+    }
+    const mode = fs.statSync(absolute).mode;
+    fs.writeFileSync(temporary, updated, { encoding: 'utf8', mode });
+    fs.renameSync(temporary, absolute);
+    const readback = fs.readFileSync(absolute, 'utf8');
+    if (readback !== updated) throw new Error('READBACK_DIVERGENT');
+    return readback;
+  } catch (error) {
+    try { fs.rmSync(temporary, { force: true }); } catch {}
+    throw new Error(`INTERVIEW_PERSISTENCE_FAILED:${error.message}`);
+  }
+}