@polymorphism-tech/morph-spec 10.5.4 → 10.6.0

package/CLAUDE.md

@@ -21,6 +21,7 @@ cd src/dashboard && npm install
 npm run test:changed              # add -- --list to see the selection and why
 
 # Run all tests (files in parallel, cpus-1 at a time; ~6 min on a 16-core Windows box, bound by process/git contention)
+# Not a step before a PR or release: the PR runs test:changed and the tag runs the whole wall before publishing
 npm test
 
 # A subtree or file (still parallel); --test-concurrency=1 to debug serially

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 10.5.4  
+**Version:** 10.6.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -376,4 +376,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v10.5.4 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v10.6.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "10.5.4",
+  "version": "10.6.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -174,4 +174,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v10.5.4 by Polymorphism Tech*
+*morph-spec v10.6.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -89,4 +89,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v10.5.4 by Polymorphism Tech*
+*morph-spec v10.6.0 by Polymorphism Tech*

package/framework/docs/CLI.md

@@ -127,6 +127,8 @@ Feature sem `workType` (pré-v8) é tratada como `feature`.
 
 **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum; a sessão escolhe por `finish.mode` do `config.json`, padrão `pr`): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — depois integra: `--merge` na hora; `--pr` só abre o PR, sem integrar. **O payload distingue os dois** — `--merge` sai com `integrated: true`; `--pr` sai com `integrated: false`, `awaiting: "merge"`, `pr: {number, url}` e um `nextStep` apontando para o merge. **`finished: true` sai nos dois casos e marca só o comando ter terminado, nunca a integração** — `--pr` não encerra a feature, quem encerra é o merge do PR; até lá ela aparece em `morph-spec list`/`fleet` como `aguardando-merge`, sem cópia local (ver `list` acima e `doctor` abaixo).
 
+**Stamp com `pendingPr`** (`verify --ci` sob `project.prChecks`): o `--pr` espera os checks declarados no commit do archive, antes do desmonte, porque é esse o run que o merge reaproveita; provar antes do archive pagaria o CI duas vezes. Rode em `run_in_background`. `pass` → `checks: { status: "pass" }`. Check vermelho → `error: "pr-checks-fail"`: desfaz o archive com `git revert`, reabre o Gate 3, carimba `status: "fail"`, `source: "pr"`, devolve a PR a rascunho (o revert fica local, e rascunho não mergeia) e sai 1. Check que morreu em menos de 30 s (cota do Actions), cancelado, ou nenhum check no commit em 90 s → `error: "pr-checks-no-verdict"`: desfaz igual, apaga o stamp, e a saída é a completa local, `verify {f}` sem `--ci`. O próximo `finish` reaproveita a PR aberta. Sem resposta em 50 min: `finished: true`, `checks: { status: "pending" }`, sem desfazer nada. Processo morto na espera: o mesmo `finish --pr` retoma. `--merge` recusa esse stamp (`pr-proof-pending`).
+
 **Índice de ADRs:** no mesmo commit do archive, o `finish` lê o `2-plan/plan.md` da feature: os ADRs de `## Decisões` com `**Alcance:** projeto` entram em `.morph/specs/adrs/` (um arquivo por ADR, `{feature}--ADR-{nnn}.md` — features paralelas nunca tocam o mesmo arquivo), e a tabela `ADR | Mudança | Escopo` de `### Conflitos com o acervo` retira (total, o arquivo sai) ou estreita (parcial, `scope:` no arquivo) os ADRs revogados — forma em `morph-spec plan-check --help`; o `plan-check` avisa, enquanto o plano ainda muda, a linha que o `finish` não aplicaria. O payload traz `adrIndex: {added, revoked, narrowed}` e `revocationProblems: [{id, reason, message}]` (linha malformada ou ambígua, ADR fora do índice) — cada chave só aparece com conteúdo, e nenhum problema recusa o `finish`.
 
 `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Saída de teste não rastreada (`test-results/`, `TestResults/`, `playwright-report/`, `blob-report/`) não conta como árvore suja: na raiz só é tolerada, na worktree sai junto com o desmonte; qualquer outro arquivo não commitado recusa. Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; derruba a stack e2e com `down --remove-orphans --rmi local -v` (`--keep-volumes` tira o `-v`) e os `e2e.hostServices` — `--rmi local` leva só as imagens que o compose construiu, nunca a puxada (`postgres`), que a próxima feature baixaria de novo; `docker builder prune` nunca roda (o cache é global da máquina). No `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`.
@@ -347,6 +349,8 @@ Código não commitado é **erro de uso (exit 2)**: o CI só vê commits. CI rod
 
 **Por quê.** Só o **artefato** vira prova, nunca o "verde" do run: workflow de lint, deploy ou de terceiro não compra o Gate 3.
 
+**Prova na PR (`project.prChecks`):** projeto cujo CI de PR já roda a suíte declara `"prChecks": { "workflows": ["Backend", "Frontend"], "covers": ["dotnet", "vitest"] }`, e o `--ci` não cria `morph-verify.yml` nem paga a suíte duas vezes: roda local só o que a PR não prova (build, validadores, e2e aplicável, nós fora de `covers`) e carimba com `pendingPr`. Quem espera é o `finish --pr` (`### finish`). `workflows` é o `name:` do workflow; workflow fora da lista não prova nada. `covers` vale pelo que o workflow roda de fato: Vitest só com `--changed` na PR é cobertura menor aceita pelo projeto. Roda a completa local, com a razão, o que a rodada afetada subiria (migration, contrato, arquivo que alcança o projeto inteiro, código compartilhado) e o que não alcança o CI (`ciAvailability`). Ignorado com `project.ci: false` ou `finish.mode: "merge"`.
+
 ### Validador code-budget
 
 **Validador `code-budget` (nó `validators` do `verify`)** — mede o que a árvore **adicionou** contra a branch default: `git diff -U0` a partir do merge-base com `origin/{default}` (ou `{default}` local), arquivo novo não rastreado conta inteiro e arquivo movido sem edição não conta. Lê `.cs`/`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`, fora de `.d.ts`, de `node_modules`/`bin`/`obj`/`dist`/`.morph` e de código gerado (`*.Designer.cs`, `*.g.cs`, `*ModelSnapshot.cs`).
@@ -746,6 +750,7 @@ nomeia o nó que impediu. **Apagar teste é legítimo:** a única cor vermelha q
 | Sessão que implementa | à vontade — filtro ou suíte —, pela fila `heavy` (`heavy.gateBash` ligado por padrão) | Implementar e conferir é dela; a prova do gate continua sendo o `verify` sem filtro |
 | Gate 3 | `verify {f} --ci --json` (sem filtro; sem CI disponível, roda local) | A prova tem de cobrir **todos** os nós; no CI ela não ocupa a máquina e roda em paralelo com o avaliador |
 | CI | a suíte inteira, todos os nós (`morph-verify.yml` roda o mesmo `verify {f}`) | idem — e o artefato dele é o stamp do Gate 3 |
+| PR, com `project.prChecks` | os workflows do projeto, esperados pelo `finish --pr` | a suíte que a PR já paga não roda de novo na máquina nem no `morph-verify.yml` |
 | Evidência de eval (cenário `Cn` com `prova: eval`) | `verify {f} --filter {id-do-nó-evals} --skip-e2e --no-persist` | Só o nó `evals`, sem stack e sem carimbo — é a evidência de runtime do cenário, não a verificação da feature |
 
 > **Nenhum relógio do `verify` é de 600 s.** Os 600 s que existem são a espera da fila

package/framework/schemas/config.schema.json

@@ -25,6 +25,16 @@
           "type": "boolean",
           "description": "false turns `verify {f} --ci` into the local verify (with the reason printed). Absent or true: the Gate 3 proof comes from the GitHub Actions workflow that runs `morph-spec verify` (created on first use), whenever origin is GitHub and gh is authenticated."
         },
+        "prChecks": {
+          "type": "object",
+          "description": "The project's own PR workflows as the proof of suites they already run. With it, `verify {f} --ci` leaves the `covers` nodes out of the local run, and `finish --pr` waits for the `workflows` checks of the PR commit; red or unjudged, it undoes the archive and reopens Gate 3. Ignored with project.ci: false or finish.mode: merge, and by a change the affected run would escalate to the complete one.",
+          "required": ["workflows", "covers"],
+          "additionalProperties": false,
+          "properties": {
+            "workflows": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Workflow `name:` values whose checks count. Any other workflow proves nothing." },
+            "covers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "project.tests[].id of the nodes these workflows prove. A node left out (e2e, evals, what the PR does not run) still runs locally." }
+          }
+        },
         "tests": {
           "type": "array",
           "description": "One entry per test suite. Absent (not empty) means the four-step fallback of resolveTestPlan() decides — every project created before this key existed keeps working. An empty array is an explicit declaration of 'no test suites'.",

package/framework/schemas/feature.schema.json

@@ -149,8 +149,18 @@
         "e2eReason": { "type": ["string", "null"], "description": "The LITERAL reason the e2e node skipped (e2e-check.js's own wording), or null when it did not skip. risk-detector.js's classifyE2eSkip() reads it: 'project does not containerize' / 'does not touch runtime' are legitimate dispensations and pass; 'docker is not available' / 'requested' (--skip-e2e) / anything unclassifiable — null included — are an absence of proof and pause Gate 3. A skip recorded WITHOUT a reason is refused on purpose: a nameless dispensation is a silent no-op." },
         "sha": { "type": ["string", "null"], "description": "HEAD commit SHA at verify time (git rev-parse HEAD); null when not in a git repo or no commits yet." },
         "ts": { "type": "string", "format": "date-time", "description": "Server-side timestamp, same instant as the corresponding verifications entry's updatedAt." },
-        "source": { "type": "string", "enum": ["ci"], "description": "Present only when the stamp came from `verify --ci`: the verify --json the project CI uploaded for the pushed commit, judged by the same rules as a local run. Absent = local run." },
-        "ciRun": { "type": "string", "description": "URL of the CI run whose artifact wrote this stamp (with source: ci). `sha` is that run's headSha, so verificationStale compares the code CI saw with HEAD." }
+        "source": { "type": "string", "enum": ["ci", "pr"], "description": "`ci`: the stamp came from `verify --ci`, the verify --json the project CI uploaded for the pushed commit, judged by the same rules as a local run. `pr`: `finish --pr` wrote it when a project.prChecks workflow came back red. Absent = local run." },
+        "ciRun": { "type": "string", "description": "URL of the CI run whose artifact wrote this stamp (with source: ci). `sha` is that run's headSha, so verificationStale compares the code CI saw with HEAD." },
+        "pendingPr": {
+          "type": "object",
+          "description": "Local run of `verify --ci` under project.prChecks: the `covers` nodes were left out and `finish --pr` waits for the `workflows` checks. Refused by `finish --merge`.",
+          "required": ["workflows", "covers"],
+          "additionalProperties": false,
+          "properties": {
+            "workflows": { "type": "array", "items": { "type": "string" } },
+            "covers": { "type": "array", "items": { "type": "string" } }
+          }
+        }
       },
       "additionalProperties": false
     },

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when_to_use: Use quando for iniciar um novo projeto de LP com o template Umbraco genérico
 user-invocable: true
-cliVersion: "10.5.4"
+cliVersion: "10.6.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when_to_use: Use quando o usuário pedir "use /migrate-lp-to-umbraco {projeto}" ou descrever a necessidade de migrar uma LP para Umbraco
 user-invocable: true
-cliVersion: "10.5.4"
+cliVersion: "10.6.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Implementa o plano aprovado de uma feature morph-spec inteiro nesta
 version: core
 when_to_use: Use com o gate do plano aprovado ("/morph-apply {feature}", "implementar feature"), em "/morph-review {feature}" (entra no §5), em "/morph-hotfix {feature}" ou incidente de produção (references/hotfix.md), ou quando `morph-spec next` mandar implement, verify, fix, review ou finish
 user-invocable: true
-cliVersion: "10.5.4"
+cliVersion: "10.6.0"
 ---
 
 # morph-apply
@@ -58,7 +58,7 @@ Verify verde: siga `references/review.md` — foto `--before-eval`, verificador
 
 ## 6. Fechar
 
-`morph-spec context refresh` (regera o inventário em `.morph/context/README.md`; `design-system.md` você atualiza só se mudou token) e commite o que faltar (relatórios do review): o `finish` exige árvore limpa. Modo: `finish.mode` do config do projeto, padrão `pr`, sem perguntar: `morph-spec finish {feature} --pr|--merge`. `--pr` não integra: a feature fica `aguardando-merge` até o merge. O `finish` arquiva o `feature.json`, o `plan.md` e o recap; o report e a review ficam no histórico do git. Encerrado, aponte o recap ao usuário (`.morph/archive/{feature}/recap.html`, abra no navegador; `morph-spec recap {feature} --piper` narra com o Piper local).
+`morph-spec context refresh` (regera o inventário em `.morph/context/README.md`; `design-system.md` você atualiza só se mudou token) e commite o que faltar (relatórios do review): o `finish` exige árvore limpa. Modo: `finish.mode` do config do projeto, padrão `pr`, sem perguntar: `morph-spec finish {feature} --pr|--merge`. `--pr` não integra: a feature fica `aguardando-merge` até o merge. Stamp com `pendingPr`: `--pr` em `run_in_background`, porque ele espera os checks da PR; `pr-checks-fail` ou `pr-checks-no-verdict` desfaz o archive e reabre o Gate 3: siga o `hint`. O `finish` arquiva o `feature.json`, o `plan.md` e o recap; o report e a review ficam no histórico do git. Encerrado, aponte o recap ao usuário (`.morph/archive/{feature}/recap.html`, abra no navegador; `morph-spec recap {feature} --piper` narra com o Piper local).
 
 ## Arquivo de teste
 

package/framework/skills/core/morph-apply/references/review.md

@@ -49,7 +49,7 @@ Confirmação = **dispatch novo** só dos papéis em `gate3.redispatch`, com o `
 
 ## 6. Gate 3
 
-**A rodada completa:** com os relatórios sem bloqueador, `morph-spec verify {feature} --ci --json --detach` em `run_in_background` (sem CI, roda local e diz por quê; repetir o comando retoma a rodada). É a única. Sem `--filter`, sempre, e sem `--affected`: verde filtrado é verde sobre código não testado, e é ela que o gate lê. `reason: "stamp-reused"` = nada andou desde o último verde: vale. Saída `CI rodando` → espere a notificação. `fail` → corrija (CI: `gh run view <id> --log-failed`) e siga o §5, porque a correção é código que ninguém revisou. Nó `e2e` em `skip` → o `gate-check` decide se dispensa (`classifyE2eSkip`, em `risk-detector.js`: docker indisponível pausa sozinho).
+**A rodada completa:** com os relatórios sem bloqueador, `morph-spec verify {feature} --ci --json --detach` em `run_in_background` (sem CI, roda local e diz por quê; repetir o comando retoma a rodada). É a única. Sem `--filter`, sempre, e sem `--affected`: verde filtrado é verde sobre código não testado, e é ela que o gate lê. `reason: "stamp-reused"` = nada andou desde o último verde: vale. Saída `CI rodando` → espere a notificação. `fail` → corrija (CI: `gh run view <id> --log-failed`) e siga o §5, porque a correção é código que ninguém revisou. Nó `e2e` em `skip` → o `gate-check` decide se dispensa (`classifyE2eSkip`, em `risk-detector.js`: docker indisponível pausa sozinho). Com `project.prChecks`, o que a PR prova fica de fora e o `finish --pr` espera os checks (`SKILL.md` §6).
 
 `morph-spec gate-check {feature} review [--json]` lê os relatórios, a cobertura dos `Cn` e os demais sinais. Forçar passagem apesar da pausa: `morph-spec gate-decision {feature} review --pause false --reason "…"`.
 

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Leva um pedido ou o link de uma issue ao plano aprovado — roteia
 version: core
 when_to_use: Use quando uma feature, bug ou chore começar ("/morph-plan {feature}", "/morph-plan <link da issue>", "vamos planejar X"), ou ao retomar uma feature cujo gate plan ainda não foi aprovado
 user-invocable: true
-cliVersion: "10.5.4"
+cliVersion: "10.6.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de UI/UX de uma feature com plano aprovado — render
 version: core
 when_to_use: Use quando o ramo de design for tomado (morph-spec advance {feature} --design), antes de /morph-apply
 user-invocable: true
-cliVersion: "10.5.4"
+cliVersion: "10.6.0"
 ---
 
 # morph-uiux

package/package.json

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

package/src/commands/state/finish.js

@@ -24,6 +24,9 @@ import { runArchive } from './archive.js';
 import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
 import { newBackupStamp, enforceBackupRetention, inspectFinishBackups } from '../../lib/worktree/finish-backup.js';
 import { isTestArtifact } from '../../lib/worktree/ignored-triage.js';
+import { waitForPrChecks } from '../../lib/ci/pr-checks.js';
+import { atomicWriteJson } from '../../core/state/state-manager.js';
+import { recordGateEvent } from '../../../framework/hooks/shared/gate-event.js';
 
 const PR_TYPE_BY_WORK_TYPE = { feature: 'feat', bug: 'fix', hotfix: 'fix', chore: 'chore' };
 
@@ -253,7 +256,8 @@ export async function finishCommand(feature, options = {}) {
         });
         process.exit(1);
       }
-      if (openPr) {
+      // A run killed while waiting left the PR open and the proof unread: this run picks the wait up.
+      if (openPr && !readFeatureJson(featureCwd, feature, 'archive')?.verification?.pendingPr) {
         emit({
           finished: false,
           error: 'already-finished',
@@ -278,6 +282,16 @@ export async function finishCommand(feature, options = {}) {
     emit({ finished: false, error: 'review-not-approved', feature });
     process.exit(1);
   }
+  const pendingPr = fj?.verification?.pendingPr ?? null;
+  if (mode === 'merge' && pendingPr && !options.force) {
+    emit({
+      finished: false,
+      error: 'pr-proof-pending',
+      feature,
+      hint: `${pendingPr.covers.join(', ')} só seriam provadas pelo CI da PR, e --merge não abre PR. Rode \`morph-spec verify ${feature}\` (sem --ci), \`gate-check ${feature} review\` e o finish de novo`,
+    });
+    process.exit(1);
+  }
   const prTitle = buildPrTitle(feature, fj);
   const prBody = (fj?.description && String(fj.description).trim())
     ? String(fj.description).trim()
@@ -364,7 +378,7 @@ export async function finishCommand(feature, options = {}) {
   if (mode === 'merge') {
     return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch, backupStamp });
   }
-  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp });
+  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp, pendingPr, featureTree: cleanCwd });
 }
 
 // A junction/symlink in the worktree points at content in the ROOT, and `rm -rf` or
@@ -600,7 +614,43 @@ export function prNumberFromUrl(url) {
   return m ? Number(m[1]) : null;
 }
 
-async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp }) {
+// The checks of the archive commit are the proof: a second push of the same code would pay the CI twice,
+// so a red or unjudged run undoes the archive here and the feature goes back to the session.
+function reopenFeature({ tree, feature, check, ciRun, sha }) {
+  const archiveCommit = execFileSync('git', ['log', '-1', '--format=%H', '--fixed-strings', `--grep=chore(morph): archive ${feature}`], { cwd: tree, stdio: 'pipe' }).toString().trim();
+  execFileSync('git', ['revert', '--no-edit', archiveCommit], { cwd: tree, stdio: 'pipe' });
+
+  const path = join(tree, '.morph', 'features', feature, 'feature.json');
+  const fj = JSON.parse(readFileSync(path, 'utf8'));
+  const now = new Date().toISOString();
+  const reason = check.state === 'fail'
+    ? `CI da PR vermelho: ${check.failed.map((c) => c.workflowName).join(', ')}`
+    : `CI da PR sem veredito: ${check.reason}`;
+  fj.approvalGates = { ...fj.approvalGates, review: { approved: false, timestamp: now, approvedBy: null, revokedBy: 'finish', revokedAt: now, reason } };
+  if (check.state === 'fail') {
+    const { pendingPr: _, ...stamp } = fj.verification;
+    fj.verification = { ...stamp, status: 'fail', nodes: { ...stamp.nodes, tests: 'fail' }, sha, ts: now, source: 'pr', ciRun };
+    const entry = fj.verifications?.feature;
+    if (entry) fj.verifications.feature = { ...entry, status: 'fail', failStreak: (entry.failStreak ?? 0) + 1, updatedAt: now };
+  } else {
+    delete fj.verification;
+  }
+  atomicWriteJson(path, fj);
+  recordGateEvent(tree, { feature, gate: 'review', step: 'unapprove', approvedBy: null });
+  commitFeatureState(tree, feature);
+  return reason;
+}
+
+// The revert stays local (a push would pay another CI run), so the reopened PR still holds the archive:
+// as a draft it cannot be merged by accident, on a plan without branch protection.
+function setPrDraft(root, prUrl, draft) {
+  try {
+    const { bin, prefix } = resolveGh();
+    execFileSync(bin, [...prefix, 'pr', 'ready', prUrl, ...(draft ? ['--undo'] : [])], { cwd: root, stdio: 'pipe', timeout: 15000 });
+  } catch { /* gh refuses a PR already in that state */ }
+}
+
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp, pendingPr, featureTree }) {
   try {
     execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
   } catch (err) {
@@ -608,13 +658,48 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     process.exit(1);
   }
 
-  let prUrl = null;
-  try {
-    const { bin, prefix } = resolveGh();
-    prUrl = execFileSync(bin, [...prefix, 'pr', 'create', '--base', defaultBranch, '--head', expectedBranch, '--title', prTitle, '--body', prBody], { cwd: root, stdio: 'pipe' }).toString().trim();
-  } catch (err) {
-    emit({ finished: false, error: 'pr-create-failed', output: gitErr(err), hint: 'a branch foi enviada (push OK); abra o PR manualmente com `gh pr create`', feature, pushed: expectedBranch });
-    process.exit(1);
+  // A feature reopened by a red PR comes back here with that PR still open.
+  const openPr = openPrFor(expectedBranch, root);
+  let prUrl = typeof openPr === 'string' ? openPr : null;
+  if (prUrl) setPrDraft(root, prUrl, false);
+  if (!prUrl) {
+    try {
+      const { bin, prefix } = resolveGh();
+      prUrl = execFileSync(bin, [...prefix, 'pr', 'create', '--base', defaultBranch, '--head', expectedBranch, '--title', prTitle, '--body', prBody], { cwd: root, stdio: 'pipe' }).toString().trim();
+    } catch (err) {
+      emit({ finished: false, error: 'pr-create-failed', output: gitErr(err), hint: 'a branch foi enviada (push OK); abra o PR manualmente com `gh pr create`', feature, pushed: expectedBranch });
+      process.exit(1);
+    }
+  }
+
+  let checks = null;
+  if (pendingPr) {
+    const sha = execFileSync('git', ['rev-parse', expectedBranch], { cwd: root, stdio: 'pipe' }).toString().trim();
+    const check = await waitForPrChecks(root, { branch: expectedBranch, sha, workflows: pendingPr.workflows });
+    if (check.state === 'fail' || check.state === 'no-verdict') {
+      let reason;
+      try {
+        reason = reopenFeature({ tree: featureTree, feature, check, ciRun: check.failed?.[0]?.detailsUrl ?? prUrl, sha });
+      } catch (err) {
+        emit({ finished: false, error: 'reopen-failed', output: gitErr(err), hint: `CI da PR sem verde (${check.state}) e o archive não foi desfeito: não mergeie ${prUrl}; rode \`git revert\` do commit de archive em ${featureTree}`, feature });
+        process.exit(1);
+      }
+      const red = check.state === 'fail';
+      setPrDraft(root, prUrl, true);
+      emit({
+        finished: false,
+        error: red ? 'pr-checks-fail' : 'pr-checks-no-verdict',
+        feature,
+        pr: { number: prNumberFromUrl(prUrl), url: prUrl },
+        reason,
+        ...(red ? { failed: check.failed.map((c) => ({ workflow: c.workflowName, url: c.detailsUrl })) } : {}),
+        hint: red
+          ? 'archive desfeito e Gate 3 reaberto: corrija (`gh run view <id> --log-failed`), commite e siga review.md §5; o finish reaproveita esta PR'
+          : `archive desfeito e Gate 3 reaberto: rode \`morph-spec verify ${feature} --json --detach\` (sem --ci, a completa local), \`gate-check ${feature} review\`, approve e o finish de novo; o finish reaproveita esta PR`,
+      });
+      process.exit(1);
+    }
+    checks = check.state === 'pass' ? { status: 'pass' } : { status: 'pending', reason: check.reason };
   }
 
   // The worktree flow keeps the branch (the open PR needs it); the common flow stays on morph/{f},
@@ -654,7 +739,10 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     pushed: expectedBranch,
     base: defaultBranch,
     pr: { number: prNumber, url: prUrl },
-    nextStep: `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
+    ...(checks ? { checks } : {}),
+    nextStep: checks?.status === 'pending'
+      ? `confira \`gh pr checks ${prNumber ?? expectedBranch}\` antes de mergear ${prLabel}: a suíte ainda não respondeu`
+      : `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
     ...adrIndexNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(e2e ? { e2e } : {}),

package/src/commands/validation/verify.js

@@ -13,7 +13,7 @@ import { HeavyBusyError } from '../../lib/heavy/gate.js';
 import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
 import { memoryBusyHint } from '../../lib/heavy/live-stacks.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
-import { runCiVerify, CiUsageError, reusableLocalStamp } from '../../lib/ci/ci-verify.js';
+import { runCiVerify, CiUsageError, reusableLocalStamp, resolvePrProof } from '../../lib/ci/ci-verify.js';
 import { syncStackRules } from '../../lib/installers/stack-sync.js';
 import {
   DETACH_RUN_ENV, DETACH_STAGE_ENV, DETACH_WORKER_ENV, launchWorker, markWorkerExit, runFilesOf, superviseVerify,
@@ -137,6 +137,7 @@ async function runLocalVerify(featureName, options, fingerprint) {
       fingerprint,
       fresh: options.fresh,
       affected: options.affected,
+      excludeNodes: options.excludeNodes,
       timeout: options.timeout,
       skipTests: options.skipTests,
       skipBuild: options.skipBuild,
@@ -231,14 +232,19 @@ export async function verifyCommand(featureName, options = {}) {
   }
 
   let ci = null;
+  let prProof = null;
   if (options.ci) {
     const fresh = reusableLocalStamp(process.cwd(), feature.verification);
     if (fresh) exitWithReusedStamp(featureName, fresh, 'stamp verde e fresco — o CI não roda de novo', options);
+    prProof = resolvePrProof(process.cwd(), featureName, readMorphConfig(process.cwd()));
+    if (prProof?.local) console.error(chalk.yellow(`\n↪ completa local: ${prProof.local}\n`));
     try {
-      const outcome = await runCiVerify(process.cwd(), featureName, readMorphConfig(process.cwd()), {
+      const outcome = prProof ? null : await runCiVerify(process.cwd(), featureName, readMorphConfig(process.cwd()), {
         log: (line) => console.error(chalk.gray(`   ${line}`)),
       });
-      if (outcome.mode === 'ci') {
+      if (!outcome) {
+        // The PR proof has no run to wait for here: `finish --pr` waits for it.
+      } else if (outcome.mode === 'ci') {
         ci = outcome;
       } else if (outcome.mode === 'pending') {
         if (options.json) console.log(JSON.stringify({ status: 'pending', persisted: false, reason: outcome.reason }, null, 2));
@@ -259,7 +265,8 @@ export async function verifyCommand(featureName, options = {}) {
   // Taken before the run: it is the tree the run is about to read.
   const fingerprint = treeFingerprint(process.cwd());
 
-  const result = ci ? ci.result : await runLocalVerify(featureName, options, fingerprint);
+  const pendingPr = prProof?.covers ? prProof : null;
+  const result = ci ? ci.result : await runLocalVerify(featureName, { ...options, excludeNodes: pendingPr?.covers }, fingerprint);
 
   const cleanup = ci ? { status: 'skipped', reason: 'ci' } : afterHeavyRun({
     projectPath: process.cwd(),
@@ -305,6 +312,7 @@ export async function verifyCommand(featureName, options = {}) {
       ts: now,
       ...(result.flaky?.length ? { flaky: result.flaky } : {}),
       ...(ci ? { source: 'ci', ciRun: ci.run.url } : {}),
+      ...(pendingPr && result.status === 'pass' ? { pendingPr } : {}),
     };
     if (!scopedRun) await updateFeature(featureName, 'verification', stamp);
   }
@@ -334,6 +342,7 @@ export async function verifyCommand(featureName, options = {}) {
       Array.isArray(node.runs) ? { ...withoutOutput(node), runs: node.runs.map(withoutOutput) } : withoutOutput(node)]));
     const output = {
       ...result, nodes, persisted: persist, ...(persist ? {} : { reason }), repeatOf, cleanup,
+      ...(pendingPr ? { pendingPr } : {}),
       ...(ci ? { source: 'ci', ciRun: { id: ci.run.databaseId, url: ci.run.url, sha: ci.run.headSha }, workflowCreated: ci.created } : {}),
     };
     console.log(JSON.stringify(output, null, 2));

package/src/lib/ci/ci-verify.js

@@ -8,7 +8,10 @@ import {
   CI_WORKFLOW_DIR, CI_WORKFLOW_FILE, ciAvailability, downloadResult, findCiWorkflow, pushBranch,
   uncommittedCode, waitForRun, workflowPushProblem,
 } from './github-ci.js';
+import { prProofConfig } from './pr-checks.js';
 import { renderCiWorkflow } from './workflow-scaffold.js';
+import { resolveTestNodes } from '../tasks/test-nodes.js';
+import { selectAffected } from '../verify/affected.js';
 
 export const CI_WAIT_MS = 50 * 60 * 1000;
 const APPEAR_MS = Number(process.env.MORPH_CI_APPEAR_MS ?? 90 * 1000);
@@ -58,6 +61,19 @@ export function reusableLocalStamp(root, stamp) {
   return treeMovedSince(root, stamp.sha, head) ? null : stamp;
 }
 
+/**
+ * `covers` = suites the PR's own checks prove, left out of the local run. `local` = run everything here,
+ * with the reason. Null = the project declared no PR proof. What the affected run would escalate stays local.
+ */
+export function resolvePrProof(root, featureName, config, { select = selectAffected } = {}) {
+  const proof = prProofConfig(config);
+  if (!proof) return null;
+  const avail = ciAvailability(root, featureName, config);
+  if (!avail.ok) return { local: avail.reason };
+  const selection = select({ projectPath: root, nodes: resolveTestNodes(root).nodes });
+  return selection.scope === 'full' ? { local: selection.reason } : proof;
+}
+
 // Every way CI cannot answer is `mode: 'local'` with the reason: no CI is never a pause. Only the
 // uploaded `verify --json` becomes a result, judged by the same stamp and rules as a local run.
 export async function runCiVerify(root, featureName, config, { log = () => {}, waitMs = CI_WAIT_MS, wait = waitForRun } = {}) {

package/src/lib/ci/pr-checks.js

@@ -0,0 +1,76 @@
+import { execFileSync } from 'child_process';
+import { resolveGh } from '../git/gh.js';
+
+const FAILED = new Set(['FAILURE', 'TIMED_OUT']);
+const PASSED = new Set(['SUCCESS', 'SKIPPED', 'NEUTRAL']);
+
+// A job killed by exhausted Actions quota fails within seconds without running a step.
+const MIN_JUDGED_MS = 30 * 1000;
+
+export const PR_WAIT_MS = 50 * 60 * 1000;
+
+/** The PR proof a project declared; null when it closes by merge, opted out of CI or declared nothing. */
+export function prProofConfig(config) {
+  if (config?.project?.ci === false || config?.finish?.mode === 'merge') return null;
+  const { workflows, covers } = config?.project?.prChecks ?? {};
+  const filled = (list) => Array.isArray(list) && list.length > 0;
+  return filled(workflows) && filled(covers) ? { workflows, covers } : null;
+}
+
+function neverRan(check) {
+  const elapsed = Date.parse(check.completedAt) - Date.parse(check.startedAt);
+  return !Number.isFinite(elapsed) || elapsed < MIN_JUDGED_MS;
+}
+
+/** Only a declared workflow counts: a green lint or deploy run says nothing about the suite. */
+export function judgeChecks(rollup, workflows) {
+  const checks = (rollup ?? []).filter((check) => workflows.includes(check.workflowName));
+  if (checks.length === 0) return { state: 'absent' };
+  if (checks.some((check) => check.status !== 'COMPLETED')) return { state: 'running' };
+
+  const failed = checks.filter((check) => FAILED.has(check.conclusion));
+  const real = failed.filter((check) => !neverRan(check));
+  if (real.length > 0) return { state: 'fail', failed: real };
+  if (failed.length > 0) return { state: 'no-verdict', reason: `${failed[0].workflowName} morreu sem rodar (cota do Actions?)` };
+
+  const undecided = checks.find((check) => !PASSED.has(check.conclusion));
+  if (undecided) return { state: 'no-verdict', reason: `${undecided.workflowName}: ${undecided.conclusion}` };
+  if (!checks.some((check) => check.conclusion === 'SUCCESS')) return { state: 'no-verdict', reason: 'nenhum check julgou o código' };
+  return { state: 'pass' };
+}
+
+function readPr(root, branch) {
+  try {
+    const { bin, prefix } = resolveGh();
+    return JSON.parse(execFileSync(bin, [...prefix, 'pr', 'view', branch, '--json', 'headRefOid,statusCheckRollup'], { cwd: root, stdio: 'pipe', timeout: 15000 }).toString());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Waits `appearMs` even when the first workflow already settled: the others may not have been created yet.
+ * @returns {Promise<{ state: 'pass'|'fail'|'no-verdict'|'pending', failed?: object[], reason?: string }>}
+ */
+export async function waitForPrChecks(root, { branch, sha, workflows, timeoutMs = PR_WAIT_MS,
+  appearMs = Number(process.env.MORPH_CI_APPEAR_MS ?? 90 * 1000), pollMs = 15000,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, read = readPr }) {
+  const start = now();
+  let misses = 0;
+  for (;;) {
+    const elapsed = now() - start;
+    const pr = read(root, branch);
+    if (pr === null) {
+      if (++misses >= 3) return { state: 'no-verdict', reason: 'gh pr view não respondeu' };
+    } else {
+      misses = 0;
+      const verdict = pr.headRefOid === sha ? judgeChecks(pr.statusCheckRollup, workflows) : { state: 'absent' };
+      if (elapsed >= appearMs) {
+        if (verdict.state === 'absent') return { state: 'no-verdict', reason: `nenhum check de ${workflows.join(', ')} neste commit` };
+        if (verdict.state !== 'running') return verdict;
+      }
+    }
+    if (elapsed >= timeoutMs) return { state: 'pending', reason: `checks não terminaram em ${Math.round(timeoutMs / 60000)} min` };
+    await sleep(pollMs);
+  }
+}

package/src/lib/validators/verify-runner.js

@@ -105,7 +105,9 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
   // Usage errors are judged before the build: paying for a build to discover a typo
   // is the worst ordering, and a refusal after the cache was touched leaves a half-rewritten tree.
   const resolvedPlan = resolveTestNodes(projectPath);
-  const testPlan = options.selection ? { ...resolvedPlan, nodes: options.selection.nodes } : resolvedPlan;
+  const excluded = new Set(options.excludeNodes ?? []);
+  const scopedNodes = options.selection ? options.selection.nodes : resolvedPlan.nodes;
+  const testPlan = { ...resolvedPlan, nodes: scopedNodes.filter((node) => !excluded.has(node.id)) };
   const filter = parseTestFilter(options.filter);
   if (filter && !testPlan.nodes.some((node) => nodeMatchesFilter(node, filter))) {
     const declared = testPlan.nodes.map((node) => node.id).join(', ') || '(none)';
@@ -150,10 +152,11 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     const kept = options.selection.nodes.map((n) => n.id).join(', ') || 'nenhuma';
     feedback.push(`[verify] rodada afetada, suítes: ${kept}; a completa roda uma vez antes da aprovação`);
   }
+  if (excluded.size > 0) feedback.push(`[verify] provadas pelo CI da PR no finish: ${[...excluded].join(', ')}`);
 
   // Only a complete run feeds or reads the cache: a partial one proves nothing about the nodes it left out.
   const cacheDir = fingerprint && !filter && !skipTests && !skipBuild && !skipE2e && !recordBaseline
-    && !refreshCache && !linux && !freshE2e
+    && !refreshCache && !linux && !freshE2e && excluded.size === 0
     ? resolveGitCommonDir(projectPath)
     : null;
   const reuse = planReuse(cacheDir && !fresh ? readVerifyCache(cacheDir, featureName) : null, fingerprint);
@@ -172,7 +175,7 @@ async function runVerifyGated(projectPath, featureName, options, gate) {
     projectPath,
     testPlan,
     filter,
-    skipTests,
+    skipTests: skipTests || (excluded.size > 0 && testPlan.nodes.length === 0),
     buildNode: nodes.build,
     timeout: explicitTimeout,
     refreshCache,