@polymorphism-tech/morph-spec 8.24.3 → 8.26.0

package/framework/templates/examples/spec-examples.md

@@ -2,7 +2,8 @@
 
 > **Layer:** 3 | **Load:** on-demand | **Keywords:** spec, specification, template
 
-**Use the stack's `.morph/framework/templates/spec.md` as the canonical template.**
+**The canonical template is `docs/spec.md` of the template system** (REGISTRY id `spec`),
+resolved from the installed package — see `framework/templates/README.md`.
 
 This file contains extended examples for each spec section.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.24.3",
+  "version": "8.26.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/claim.js

@@ -132,7 +132,17 @@ export function claimCommand(feature, options = {}) {
 
   // No feature (or explicit --list): the read-only board, whole or filtered.
   const all = listClaims(gitCommonDir);
-  const rows = feature ? all.filter((c) => c.feature === feature) : all;
+  const scoped = feature ? all.filter((c) => c.feature === feature) : all;
+
+  // Um claim morto NÃO é limpo do registro — ele só para de avisar (o TTL de
+  // 30 min o mata, `live` é computado na leitura). O efeito colateral é que o
+  // board acumula: features encerradas há 20h e 73h apareciam no `--list` como
+  // se fossem informação. Um quadro de avisos onde quase nada é aviso ensina a
+  // não olhar o quadro. Por padrão mostramos só o que ainda avisa; `--all`
+  // devolve o registro inteiro, e o rodapé conta o que ficou de fora para a
+  // omissão nunca ser silenciosa.
+  const rows = options.all ? scoped : scoped.filter((c) => c.live);
+  const hidden = scoped.length - rows.length;
 
   if (options.json) {
     console.log(JSON.stringify(rows));
@@ -141,8 +151,11 @@ export function claimCommand(feature, options = {}) {
 
   if (!rows.length) {
     console.log(chalk.gray(feature
-      ? `Nenhum claim para "${feature}".`
-      : 'Nenhuma feature reclamada — nenhuma sessão registrada.'));
+      ? `Nenhum claim vivo para "${feature}".`
+      : 'Nenhuma feature reclamada — nenhuma sessão viva registrada.'));
+    if (hidden > 0) {
+      console.log(chalk.gray(`(${hidden} claim(s) morto(s) omitido(s) — \`--all\` para ver, \`--release\` para limpar)`));
+    }
     process.exit(0);
   }
 
@@ -155,6 +168,9 @@ export function claimCommand(feature, options = {}) {
       + col(claimAge(c), 12) + col(c.pid, 9) + (c.path || '-'),
     );
   }
+  if (hidden > 0) {
+    console.log(chalk.gray(`\n${hidden} claim(s) morto(s) omitido(s) — \`--all\` para ver.`));
+  }
   console.log(chalk.gray('\nClaims são AVISOS, nunca bloqueios. Claim órfão: `morph-spec claim <f> --release`'));
   process.exit(0);
 }

package/src/commands/state/approve.js

@@ -5,6 +5,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
+import { evaluatorReportState, COMPOSITE_SCORE_TOKEN } from '../../lib/evaluator-report.js';
 
 /**
  * The literal token `review-report.md` carries to declare which tree it
@@ -303,10 +304,23 @@ export async function approveCommand(featureName, gateName, options = {}) {
           process.exit(1);
         }
       } else {
-        const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');
-        if (!existsSync(evaluatorReport)) {
+        // `existsSync` puro não bastava: um evaluator-report SEM o token
+        // `**Composite-Score:**` passava aqui E era descartado pelo gate-check
+        // (que então caía no proxy de taskScores). O resultado era um Gate 3
+        // carimbado `approvedBy: "auto"` sobre a média das auto-avaliações de
+        // quem implementou — precisamente o que MORPH.md §5 proíbe. Arquivo
+        // presente sem veredito legível é relatório OCO, não relatório.
+        const report = evaluatorReportState(process.cwd(), featureName);
+        if (report.status !== 'ok') {
           if (!options.selfAssessed) {
-            console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
+            if (report.status === 'missing') {
+              console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
+            } else {
+              console.error(chalk.red('\n❌ Gate 3: o `4-review/evaluator-report.md` existe mas está OCO —'));
+              console.error(chalk.red(`   falta a linha \`${COMPOSITE_SCORE_TOKEN} {n.n}\`, o veredito legível por máquina.`));
+              console.error(chalk.gray('   Sem ela o gate-check não lê o score real e cai na média das auto-avaliações.'));
+              console.error(chalk.gray('   Peça ao avaliador o relatório completo (morph-review §4) ou complete a linha.'));
+            }
             console.error(chalk.gray('   O score composto da feature vem do avaliador (persona `evaluator`, contexto fresco)'));
             console.error(chalk.gray('   despachado pela morph-review, nunca de auto-avaliação de quem implementou.'));
             console.error(chalk.gray('   Se o dispatch for impossível nesta sessão, aprove com --self-assessed —'));

package/src/commands/state/finish.js

@@ -78,6 +78,14 @@ export function buildPrTitle(feature, fj) {
  * `finished` is the integration (the actual value); `worktreeRemoved` is the
  * best-effort teardown — two independent signals, as before.
  *
+ * RESUMABLE. `merge-conflict`, `checkout-default-failed`, `push-failed` and
+ * `pr-create-failed` all fail AFTER the archive, and legitimately so: the
+ * archive commit is what travels with the branch. Re-running then found no
+ * `features/{f}` and refused from scratch, so every mid-way failure demanded a
+ * hand repair. Now a second run that finds the feature ARCHIVED on its own
+ * branch, not yet merged into the default, picks up at the integration and says
+ * `resumed: true` in its output — see Validation 0c.
+ *
  * @param {string} feature
  * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, force?: boolean,
  *   discardIgnored?: boolean, cwd?: string }} [options]
@@ -98,7 +106,15 @@ export async function finishCommand(feature, options = {}) {
   // containers and their ports when the feature closes. Best-effort by
   // contract — a stack that refuses to come down must never fail a finish that
   // already merged.
+  // Set by Validation 0c when this run picks up an already-archived feature.
+  // Stamped onto EVERY payload emitted from that point on, success or refusal:
+  // a resume merges a branch the user did not archive in this run, and that has
+  // to be visible. Someone who mistypes a name and lands on an archived feature
+  // would otherwise get a silent merge they never asked for.
+  let resumed = false;
+
   const emit = (obj) => {
+    if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
@@ -211,25 +227,128 @@ export async function finishCommand(feature, options = {}) {
     featureCwd = root;
   }
 
-  // Validation 0c: the feature must still BE there. Without this, a missing
-  // feature.json makes the optional chaining below fall through to
-  // `review-not-approved`, which collapses three different situations into one
-  // wrong diagnosis: gate genuinely unapproved, feature already archived, and
-  // feature living on a branch we are not on. The second one is what a user
-  // hits when retrying an interrupted finish, and being told "Gate 3 not
-  // approved" about an approved gate sends them looking in the wrong place.
+  // Validation 0c: the feature must still be in `features/` — or, if it is not,
+  // this run has to decide which of three states it is in before doing anything:
+  // gone entirely, already ARCHIVED and awaiting integration (resume), or
+  // already integrated (nothing to do).
+  //
+  // Originally all three arrived as `review-not-approved`, because a missing
+  // feature.json parses to null and the optional chaining below fell straight
+  // through — being told "Gate 3 not approved" about an approved gate is what
+  // sent the user looking in the wrong place after an interrupted finish.
   //
   // Keyed on the DIRECTORY, not on the parse: readFeatureJson also returns null
   // for malformed JSON, and a legacy feature with a folder but no (or broken)
   // feature.json is a real thing that `--force` is expected to push through.
   if (!existsSync(join(featureCwd, '.morph', 'features', feature))) {
-    emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(featureCwd, root, feature) });
-    process.exit(1);
+    const archivePath = join(featureCwd, '.morph', 'archive', feature);
+    if (!existsSync(archivePath)) {
+      emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(featureCwd, root, feature) });
+      process.exit(1);
+    }
+
+    // ── RESUME ──────────────────────────────────────────────────────────────
+    // Archived HERE, on the branch this finish would merge — every path that
+    // reaches this line has already proved we are standing on `morph/{f}`
+    // (worktree flow: found.branch === expectedBranch; common flow: branchExists
+    // + currentBranch === expectedBranch). So the archive step is done and only
+    // the integration is missing. Which is exactly what a failed merge/push
+    // leaves behind, and what used to require repairing by hand.
+    //
+    // The one thing still to establish is whether the integration ALSO
+    // happened. A branch already contained in the default is a finish that
+    // COMPLETED (`--keep`, or a `--pr` whose PR was merged) — re-merging it is
+    // the hazard this check exists to stop, and it is why resume is keyed on
+    // the branch's relationship to the default rather than on the archive alone.
+    const target = detectDefaultBranch(root);
+    if (!target) {
+      emit({ finished: false, error: 'no-default-branch', hint: 'não foi possível resolver a branch default (origin/HEAD, main ou master)', feature });
+      process.exit(1);
+    }
+    const merged = branchMergedInto(expectedBranch, target, root);
+    if (merged === null) {
+      // PROVE-or-DECLINE, same discipline as the worktree teardown: we could not
+      // establish the branch's state, so we do not act on a guess. Refusing is
+      // recoverable; a duplicate merge is not.
+      emit({
+        finished: false,
+        error: 'resume-undecidable',
+        feature,
+        branch: expectedBranch,
+        base: target,
+        archived: archivePath.replace(/\\/g, '/'),
+        hint: `'${feature}' está arquivada, mas não foi possível comparar ${expectedBranch} com ${target} (ref ausente?) — sem saber se o merge já aconteceu, retomar arriscaria mergear duas vezes. Verifique o estado do git antes de integrar à mão`,
+      });
+      process.exit(1);
+    }
+    if (merged) {
+      emit({
+        finished: false,
+        error: 'already-finished',
+        feature,
+        branch: expectedBranch,
+        base: target,
+        archived: archivePath.replace(/\\/g, '/'),
+        hint: `'${feature}' já foi arquivada E ${expectedBranch} já está contida em ${target} — o finish anterior concluiu. Nada a integrar.`,
+      });
+      process.exit(1);
+    }
+
+    // "Already integrated" is MODE-SPECIFIC, and the ancestor test above only
+    // answers it for `--merge`. A `--pr` that completed leaves its branch
+    // deliberately UNMERGED (that is what the open PR is for), so the ancestor
+    // test says "not merged" and would wave the resume through — straight into
+    // a second `gh pr create` on a head that already has one. The common flow
+    // makes that trivially reachable: integratePr never leaves `morph/{f}`, so
+    // simply re-running the command lands here.
+    //
+    // `gh pr create` refuses a duplicate, so the damage was never two PRs — it
+    // was `pr-create-failed` standing in for "this already finished", which is
+    // the same collapsed diagnosis the `feature-not-found` split removed.
+    if (mode === 'pr') {
+      const openPr = openPrFor(expectedBranch, root);
+      if (openPr === null) {
+        emit({
+          finished: false,
+          error: 'resume-undecidable',
+          feature,
+          branch: expectedBranch,
+          archived: archivePath.replace(/\\/g, '/'),
+          hint: `'${feature}' está arquivada e ${expectedBranch} não foi mergeada, mas não foi possível consultar PRs abertos com \`gh\` — retomar às cegas abriria um PR duplicado. Verifique com \`gh pr list --head ${expectedBranch}\``,
+        });
+        process.exit(1);
+      }
+      if (openPr) {
+        emit({
+          finished: false,
+          error: 'already-finished',
+          feature,
+          branch: expectedBranch,
+          base: target,
+          archived: archivePath.replace(/\\/g, '/'),
+          ...(typeof openPr === 'string' ? { pr: openPr } : {}),
+          hint: `'${feature}' já foi arquivada e ${expectedBranch} já tem PR aberto — o finish anterior concluiu. Falta apenas mergear o PR.`,
+        });
+        process.exit(1);
+      }
+    }
+
+    resumed = true;
   }
 
-  // Validation 1: Gate 3 (review) approved on the feature's own feature.json.
-  const fj = readFeatureJson(featureCwd, feature);
-  if (!options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
+  // Validation 1: Gate 3 (review) approved on the feature's own feature.json —
+  // which on a resume lives in `archive/{f}`, where runArchive moved it.
+  //
+  // NOT re-checked on a resume, deliberately. The archive IS the gate's receipt:
+  // runArchive refuses `review-not-approved` itself, so a feature that reached
+  // `archive/` either passed Gate 3 or was explicitly forced past it. Re-reading
+  // it here would only add a way to fail — an archive whose feature.json is
+  // absent or unparseable (legacy shapes, a forced close) parses to null and
+  // falls straight through to `review-not-approved`, which is the exact
+  // collapsed diagnosis the `feature-not-found` fix removed. Resume integrates
+  // what was already archived; it does not re-litigate why.
+  const fj = readFeatureJson(featureCwd, feature, resumed ? 'archive' : 'features');
+  if (!resumed && !options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
     emit({ finished: false, error: 'review-not-approved', feature });
     process.exit(1);
   }
@@ -399,7 +518,7 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   }
   tryGit(['branch', '-d', expectedBranch], root);
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null, ...ucNote });
+  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
   process.exit(0);
 }
 
@@ -477,6 +596,15 @@ function promotedNote(arch) {
   };
 }
 
+/**
+ * O comando se chama `finish`, e no modo `--merge` ele NÃO publica nada: o
+ * merge é local, o remoto continua sem a feature. Quem lê "finished: true"
+ * conclui o contrário — foi pegadinha repetida em sessões diferentes. O modo
+ * `--pr` empurra e abre o PR; o `--merge` deixa o push para o humano, e é isso
+ * que esta linha diz em voz alta.
+ */
+const MERGE_NEXT_STEP = 'integração LOCAL — nada foi publicado. Rode `git push` para levar ao remoto.';
+
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
   return {
     finished: true,
@@ -484,6 +612,7 @@ function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
     feature,
     merged: branch,
     worktreeRemoved: teardown.worktreeRemoved,
+    nextStep: MERGE_NEXT_STEP,
     ...(shedBackup ? { shedBackup } : {}),
     ...teardownExtras(teardown, worktreePath, branch, true),
   };
@@ -627,9 +756,67 @@ function featureElsewhereHint(featureCwd, root, feature) {
   return { hint: `'${feature}' não existe em .morph/features/ nesta árvore. Confira o nome com \`morph-spec list --all\`.` };
 }
 
-function readFeatureJson(cwd, feature) {
+/**
+ * @param {string} cwd
+ * @param {string} feature
+ * @param {'features'|'archive'} [bucket] - `archive` on a resume, where the
+ *   feature.json has already been moved (and stamped `completed`).
+ */
+function readFeatureJson(cwd, feature, bucket = 'features') {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.morph', bucket, feature, 'feature.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is `branch` already contained in `target` — i.e. did an earlier finish get its
+ * merge in?
+ *
+ * Three-valued ON PURPOSE. `git merge-base --is-ancestor` answers by exit code,
+ * and the two failure modes mean opposite things: **1** is a real "no, not
+ * merged", while **128** is "one of these refs does not resolve" and proves
+ * nothing at all. Collapsing them to a boolean would read an unresolvable ref as
+ * "not merged" and let a resume re-merge a completed feature.
+ *
+ * @param {string} branch
+ * @param {string} target
+ * @param {string} cwd
+ * @returns {boolean|null} null when the comparison could not be made
+ */
+export function branchMergedInto(branch, target, cwd) {
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', branch, target], { cwd, stdio: 'pipe' });
+    return true;
+  } catch (err) {
+    return err?.status === 1 ? false : null;
+  }
+}
+
+/**
+ * Does `branch` already have an OPEN pull request? The `--pr` half of
+ * "already integrated" — a completed `--pr` leaves the branch unmerged on
+ * purpose, so `branchMergedInto` cannot see it.
+ *
+ * Three-valued for the same reason: an unanswerable query (no `gh`, no auth, no
+ * network) is not evidence of "no PR", and treating it as such would resume
+ * into a duplicate `gh pr create`.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {string|boolean|null} the PR url, `true` (open PR, url unavailable),
+ *   `false` (none open), or `null` when the question could not be asked
+ */
+function openPrFor(branch, cwd) {
+  const { bin, prefix } = resolveGh();
   try {
-    return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8'));
+    const out = execFileSync(bin, [...prefix, 'pr', 'list', '--head', branch, '--state', 'open', '--json', 'url'], { cwd, stdio: 'pipe' })
+      .toString()
+      .trim();
+    const arr = JSON.parse(out || '[]');
+    if (!Array.isArray(arr) || !arr.length) return false;
+    return typeof arr[0]?.url === 'string' ? arr[0].url : true;
   } catch {
     return null;
   }

package/src/commands/state/gate-check.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { getFeature } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { shouldPauseGate, getRiskSignals } from '../../lib/risk-detector.js';
+import { evaluatorCompositeScore } from '../../lib/evaluator-report.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { detectDefaultBranch, getHeadSha, getDiffStat } from '../../lib/git/default-branch.js';
 
@@ -61,26 +62,6 @@ function compositeEvalScore(feature) {
   return Math.round(avg * 10) / 10;
 }
 
-/**
- * Parse the machine-readable `**Composite-Score:** N.N` token out of
- * evaluator-report.md — the mirror of approve.js's `**Reviewed-SHA:**`
- * pattern. This is the TRUE Gate-3 composite (written by the independent
- * evaluator, per morph-review's dispatch contract), preferred over the
- * taskScores-average proxy whenever present. Returns undefined when the
- * report or the token is absent (legacy report) — the proxy stays the
- * fallback, `--signals evalScore` still overrides both.
- */
-function evaluatorCompositeScore(cwd, featureName) {
-  try {
-    const p = getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
-    if (!existsSync(p)) return undefined;
-    const m = readFileSync(p, 'utf8').match(/\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/);
-    return m ? Number(m[1]) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Collect every signal `shouldPauseGate()` (risk-detector.js) is documented
  * to consume, straight off disk — the deterministic call site risk-detector
@@ -198,6 +179,14 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       for (const key of OVERRIDABLE_SIGNAL_KEYS) {
         if (key in parsed) overrides[key] = parsed[key];
       }
+
+      // Um `evalScore` vindo de --signals substitui o VALOR mas não a
+      // PROCEDÊNCIA: sem isto o merge cego abaixo deixaria `evalScoreSource`
+      // com o que collectSignals escreveu ('taskScores-proxy'), e o sinal de
+      // auditoria passaria a mentir sobre de onde veio o número. `signals-
+      // override` não está em OVERRIDABLE_SIGNAL_KEYS — o caller não pode
+      // forjá-lo, mesmo anti-spoof de `gate`/`workType`.
+      if ('evalScore' in overrides) overrides.evalScoreSource = 'signals-override';
     }
 
     const cwd = process.cwd();

package/src/commands/state/report-check.js

@@ -26,8 +26,9 @@
  */
 
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
+import { readTelemetryEvents } from '../../../framework/hooks/shared/telemetry-logger.js';
 
 /**
  * The four mandatory items of the report contract, as detectable markers.
@@ -54,6 +55,22 @@ function reportPath(cwd, feature, taskId) {
   return join(cwd, '.morph', 'features', feature, '3-implement', 'reports', `${taskId}.md`);
 }
 
+/**
+ * `.morph/logs/task-times.json` — `{ [feature]: { [taskId]: {status,start,end} } }`,
+ * escrito pelo hook `trace-autogen` nas transições de status da task. É a
+ * janela temporal de cada task; sem ela não há como recortar quais writes do
+ * `events.jsonl` pertencem a qual task.
+ */
+function readTaskTimes(cwd) {
+  try {
+    const p = join(cwd, '.morph', 'logs', 'task-times.json');
+    if (!existsSync(p)) return null;
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 function evaluatorPath(cwd, feature) {
   return join(cwd, '.morph', 'features', feature, '4-review', 'evaluator-report.md');
 }
@@ -98,9 +115,140 @@ function outputEvidence(cwd, taskOutputs) {
   return { outputsExpected: expected.length, outputsPresent: present };
 }
 
+/**
+ * Folga entre o `mtime` do relatório e o `ts` do último write observado.
+ *
+ * São DOIS RELÓGIOS: `mtime` vem do filesystem, `ts` vem de
+ * `new Date().toISOString()` dentro do hook de telemetria. O write do próprio
+ * relatório e o evento que o registra caem a milissegundos de distância, com
+ * arredondamentos diferentes — sem folga, um relatório perfeitamente fresco
+ * seria acusado de velho. Dois segundos são muito mais que o skew real e muito
+ * menos que qualquer trabalho de verdade feito depois de relatar.
+ */
+export const STALE_TOLERANCE_MS = 2000;
+
+/**
+ * Traz o target do evento para a MESMA forma que `task.outputs`.
+ *
+ * Os dois lados chegam em convenções diferentes, e cruzá-los crus não casa
+ * nunca: `event.target` é o `file_path` como a ferramenta o recebeu, e
+ * `Write`/`Edit` exigem caminho ABSOLUTO (`telemetry-log.js` só normaliza as
+ * barras, não relativiza); `task.outputs` é relativo à raiz — é assim que
+ * `outputEvidence` o resolve, com `join(cwd, rel)`. Sem este passo,
+ * `undeclared`/`unobserved` listariam TUDO em toda task, e um sinal que sempre
+ * grita é um sinal que se aprende a ignorar.
+ *
+ * Um target que não fica sob a raiz (outra árvore) volta como veio, em vez de
+ * virar `../../..` — fora da árvore ele é evidência legítima de escrita alheia,
+ * não um output que faltou declarar.
+ */
+function toRepoRelative(target, cwd) {
+  const norm = String(target || '').replace(/\\/g, '/');
+  const root = String(cwd || '').replace(/\\/g, '/').replace(/\/+$/, '');
+  if (!root) return norm;
+  // Prefixo comparado sem caixa: no Windows a mesma raiz chega como `R:/repo`
+  // ou `r:/repo` conforme quem chamou o comando.
+  return norm.toLowerCase().startsWith(`${root.toLowerCase()}/`) ? norm.slice(root.length + 1) : norm;
+}
+
+/**
+ * Arquivos que NÃO contam como "trabalho feito depois do relatório".
+ *
+ * Sem este recorte o veredito vira máquina de falso positivo, e um aviso que
+ * dispara à toa é um aviso que se aprende a ignorar:
+ *   - o próprio relatório: gravá-lo É um Write, e ele cai na janela da task por
+ *     construção — todo relatório bem-comportado pareceria stale;
+ *   - qualquer coisa sob `.morph/`: `tasks.json`, `feature.json`, `recap.md`,
+ *     `decisions.md` são escritas do ORQUESTRADOR, depois que o sub-agent
+ *     terminou. São o fluxo normal, não trabalho não relatado.
+ *
+ * `includes` e não `startsWith`, de propósito: o alvo já vem relativizado, mas
+ * um write no `.morph/` de OUTRA árvore não fica sob esta raiz e continua
+ * absoluto — `startsWith('.morph/')` deixaria esse passar como trabalho. Não há
+ * código-fonte sob `.morph/` para o `includes` pegar por engano: a pasta é
+ * estado, por design.
+ */
+function isBookkeepingWrite(target, reportRel) {
+  if (!target) return true;
+  if (target === reportRel) return true;
+  return target.includes('.morph/');
+}
+
+/**
+ * Evidência OBSERVADA: arquivos que a task de fato escreveu, segundo a
+ * telemetria — não segundo o que o agente declarou em `outputs`.
+ *
+ * A distinção é o ponto todo. `outputs` é auto-declarado pelo agente, e
+ * `trace-autogen` lê a MESMA lista — as duas checagens que pareciam
+ * independentes eram a mesma afirmação lida duas vezes. `events.jsonl` registra
+ * cada `Write`/`Edit` no momento em que aconteceu, com `ts`; `task-times.json`
+ * dá a janela `[start, end]` da task. Cruzando os dois sai o que de fato foi
+ * tocado, sem depender da palavra de ninguém.
+ *
+ * Fail-open: sem telemetria (projeto legado, hook desligado) devolve
+ * `{ available: false }` e o comando volta ao comportamento anterior.
+ */
+function observedEvidence(cwd, feature, task) {
+  const times = readTaskTimes(cwd)?.[feature]?.[task.id];
+  if (!times?.start) return { available: false };
+
+  const events = readTelemetryEvents(cwd);
+  if (!events.length) return { available: false };
+
+  const startMs = Date.parse(times.start);
+  // Janela aberta à direita quando a task não fechou: uma task ainda em
+  // andamento tem trabalho observável, e recusar auditá-la esconde exatamente
+  // o caso do relatório escrito cedo demais.
+  const endMs = times.end ? Date.parse(times.end) : Number.POSITIVE_INFINITY;
+  if (!Number.isFinite(startMs)) return { available: false };
+
+  const reportRel = `.morph/features/${feature}/3-implement/reports/${task.id}.md`;
+  const writes = [];
+  for (const e of events) {
+    if (e?.tool !== 'Write' && e?.tool !== 'Edit') continue;
+    const ts = Date.parse(e?.ts ?? '');
+    if (!Number.isFinite(ts) || ts < startMs || ts > endMs) continue;
+    const target = toRepoRelative(e.target, cwd);
+    if (isBookkeepingWrite(target, reportRel)) continue;
+    writes.push({ target, ts });
+  }
+
+  const declared = new Set((Array.isArray(task.outputs) ? task.outputs : [])
+    .map((p) => String(p).replace(/\\/g, '/')));
+  const observed = [...new Set(writes.map((w) => w.target))];
+
+  return {
+    available: true,
+    observed,
+    lastWriteAt: writes.length ? new Date(Math.max(...writes.map((w) => w.ts))).toISOString() : null,
+    undeclared: observed.filter((p) => !declared.has(p)),
+    unobserved: [...declared].filter((p) => !observed.includes(p)),
+  };
+}
+
+/** O relatório é mais velho que o último trabalho observado da própria task? */
+function isReportStale(reportFsPath, observed) {
+  if (!observed?.available || !observed.lastWriteAt) return false;
+  try {
+    const writtenAt = statSync(reportFsPath).mtimeMs;
+    return writtenAt + STALE_TOLERANCE_MS < Date.parse(observed.lastWriteAt);
+  } catch {
+    return false;
+  }
+}
+
 /** Combine report state + evidence into a verdict and the action it implies. */
-function decide(report, evidence) {
-  if (report.exists && report.complete) return { verdict: 'ok', action: 'proceed' };
+function decide(report, evidence, stale) {
+  if (report.exists && report.complete) {
+    // A integridade estrutural (os 4 itens presentes) responde "o relatório
+    // está completo?", nunca "o relatório ainda é verdade?". Caso real: um
+    // sub-agent gravou o esqueleto dizendo "teste ainda não escrito — em
+    // andamento", seguiu trabalhando, escreveu os 9 testes e foi cortado. O
+    // arquivo ficou completo e MENTINDO, e saía `ok` aqui.
+    return stale
+      ? { verdict: 'report-stale', action: 'refresh-from-evidence' }
+      : { verdict: 'ok', action: 'proceed' };
+  }
   if (report.exists) return { verdict: 'report-incomplete', action: 'complete-degraded' };
   if (evidence.outputsExpected === 0) {
     // No declared outputs means no evidence either way. Re-dispatching costs a
@@ -113,13 +261,17 @@ function decide(report, evidence) {
 }
 
 function checkTask(cwd, feature, task) {
-  const report = inspectReport(reportPath(cwd, feature, task.id));
+  const fsPath = reportPath(cwd, feature, task.id);
+  const report = inspectReport(fsPath);
   const evidence = outputEvidence(cwd, task.outputs);
-  return { task: task.id, report, evidence, ...decide(report, evidence) };
+  const observed = observedEvidence(cwd, feature, task);
+  const stale = report.exists && isReportStale(fsPath, observed);
+  return { task: task.id, report, evidence, observed, ...decide(report, evidence, stale) };
 }
 
 const ACTION_HINT = {
   proceed: 'relatório íntegro — siga o fluxo normal.',
+  'refresh-from-evidence': 'o relatório está COMPLETO mas VELHO: a task seguiu escrevendo arquivos depois que ele foi gravado, então ele descreve um estado já ultrapassado. NÃO re-despache e não confie no texto — confira os arquivos em `observed` (evidência real, não auto-declarada) e atualize o relatório a partir deles.',
   'complete-degraded': 'complete os itens faltantes a partir da mensagem de retorno do sub-agent, carimbe o relatório como DEGRADADO e registre a falha de protocolo no recap.',
   'accept-degraded': 'o TRABALHO entrou — não re-despache. Grave você mesmo o relatório canônico a partir da mensagem de retorno, carimbado como DEGRADADO, e registre a falha de protocolo no recap e nas `notes` da task.',
   redispatch: 're-despache a task UMA vez com o mesmo prompt. Segunda ausência sem trabalho entregue = falha real: escale ao humano.',