From 6773bbb52628bf5efc31fd9fcde66ce51982bd33 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 2 Aug 2026 23:12:52 +0000
Subject: [PATCH] docs(ops): alinhar contrato agent:ready ao
 canPromotePlanIssue

---
 .cursor/skills/plan-issue/SKILL.md            | 2 +-
 docs/plans/plan-issue-lifecycle-ready-impl.md | 2 ++
 scripts/agent-ready.mjs                       | 7 ++++---
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/.cursor/skills/plan-issue/SKILL.md b/.cursor/skills/plan-issue/SKILL.md
index 43d3c845..74f95214 100644
--- a/.cursor/skills/plan-issue/SKILL.md
+++ b/.cursor/skills/plan-issue/SKILL.md
@@ -160,7 +160,7 @@ Sem `--plan`: nasce `ready` (use `--blocked` só se quiser não-claimável sem p
 2. Atualize `Issue: #N` (e status) no plano local.
 3. Commit + **`pnpm push`** + PR **Ready** `--base main` com **`Related #N`** (nunca `Closes #N` em PR só de `docs/plans/` — `plans-only-closes`).
 4. Auto-merge (`gh pr merge --auto --merge`); espere o merge em `main`.
-5. **Promote** com o script (idempotente; só Issues `blocked` + link `docs/plans/`):
+5. **Promote** com o script (idempotente se já `ready`; só Issues `blocked` + link `docs/plans/`, sem gates humanos `needs:*` nem `in-progress`/`done`/`in-prod`):
 
 ```bash
 pnpm agent:ready -- --issue <N[,N…]>
diff --git a/docs/plans/plan-issue-lifecycle-ready-impl.md b/docs/plans/plan-issue-lifecycle-ready-impl.md
index 5a71d974..c89faa38 100644
--- a/docs/plans/plan-issue-lifecycle-ready-impl.md
+++ b/docs/plans/plan-issue-lifecycle-ready-impl.md
@@ -70,6 +70,8 @@ flowchart LR
 - **Label `needs:plan`.**
 - **Reescrever `capture-review-debts` para auto-promote** (só nota + defer para OPS18).
 - **Rename cosmético `canPromotePlanIssue` → `canMarkPlanIssueReady`** — defer; API estável para OPS18 Action.
+- **Hoist `HUMAN_GATE_LABELS` / `issueHasPlanLink` / lista ativa-ou-terminal para módulo neutro** — defer até OPS18 (#296) precisar do mesmo predicado fora de `agent-pool-eligibility` (2 call sites hoje; gatilho = 3º consumidor ou Action dual).
+- **Batch `agent:ready` acumular falhas** — defer; v1 fail-fast no primeiro reject não-skip é ok.
 
 ## Riscos e mitigação
 
diff --git a/scripts/agent-ready.mjs b/scripts/agent-ready.mjs
index 5b50cb85..7640b23f 100644
--- a/scripts/agent-ready.mjs
+++ b/scripts/agent-ready.mjs
@@ -5,9 +5,10 @@
  *   pnpm agent:ready -- --issue 292
  *   pnpm agent:ready -- --issue 292,293
  *
- * Fail-closed: only Issues that are open, labeled `blocked`, and link
- * `docs/plans/` in the body. Does not promote product-blocked Issues without
- * a plan link (those stay for human triage).
+ * Fail-closed via `canPromotePlanIssue`: open + `blocked` + `docs/plans/` link,
+ * and not `needs:consent` / `requirements-changed` / `in-progress`|`done`|`in-prod`.
+ * Idempotent skip when already `ready`. Product-blocked Issues without a plan
+ * link stay for human triage.
  */
 
 import { dieAgent, gh, ghJson, labelNames, parseArgs, setLabels } from './lib/agent-github.mjs'