review-readiness-scan

review-readiness-scan

主動掃描 consumer 端所有 active change 的 ## 人工檢查 區塊，把「已 ready / 尚未 ready」分組寫入 HANDOFF.md，讓使用者能在合適時機批次跑 pnpm review（從 clade home），而不是每條 change 個別開 GUI 才知道沒準備好。

前置：consumer 必須已從 clade 散播到 scripts/review-gui.ts（各 consumer 預設都有；若沒有，跑 pnpm hub:check 確認）。

Step 1 — 跑 headless scan

cd ~/offline/clade
node vendor/scripts/review-gui.ts --scan

預設從 clade home 掃，輸出會聚合 consumers.local 內所有 consumer + worktree。若是 CI / debug 要只掃單一 consumer，才改用 node vendor/scripts/review-gui.ts --repo <consumer-path> --scan。

reviewPort 是 loopback probe port。後續 handoff MUST 原樣複製 entry 的 reviewUrl（永遠 https://review-gui.<maintainer-domain> + reviewPath），不要硬寫 5174，也不要把 probeUrl 交給人。

輸出 JSON（schema: review-readiness-scan/v2）到 stdout，結構：

{
  "schema": "review-readiness-scan/v2",
  "generatedAt": "<ISO8601>",
  "repoRoot": "<abs>",
  "reviewHost": "127.0.0.1",
  "canonicalHost": "review-gui.<maintainer-domain>",
  "reviewPort": 5174,
  "counts": {
    "ready": N,
    "notReady": M,
    "buckets": { "ready": N, "readyForEvidence": N, "applyInProgress": N }
  },
  "ready":    [ { "name": "<change>", "consumerId": "<consumer-a>",
                  "changeKey": "<consumer-a>:<change>",
                  "reviewUrl": "https://review-gui.<maintainer-domain>/review/<consumer-a>:<change>",
                  "probeUrl": "http://127.0.0.1:5174/review/<consumer-a>:<change>",
                  "bucket": "ready", "pending": N, "issued": N, "total": N } ],
  "notReady": [ { "name": "<change>", "consumerId": "<consumer-a>",
                  "changeKey": "<consumer-a>:<change>",
                  "reviewUrl": "https://review-gui.<maintainer-domain>/review/<consumer-a>:<change>",
                  "bucket": "readyForEvidence", "pending": N, "issued": N, "total": N,
                  "readinessHits": N, "malformed": N,
                  "hitsByCode": { "UI_ITEM_NO_URL": 2, "REVIEW_UI_BACKEND_ROUNDTRIP": 1 },
                  // evidenceMissing：item 標了 [verify:e2e/api/ui] 但缺對應 (verified-*:) annotation。
                  // 落 notReady 群的另一條觸發路徑（與 readinessHits / malformed 並列），各 entry 一個 item。
                  "evidenceMissing": [ { "itemId": "#3", "description": "...",
                                          "kinds": ["e2e", "api", "ui"] } ] } ],
  "buckets": {
    "ready": [ /* 可直接開 reviewUrl 給 user 做 GUI review */ ],
    "readyForEvidence": [ /* 實作已接近完成，先跑 Verify Channel Pass 補 evidence */ ],
    "applyInProgress": [ /* implementation 還沒完成，不該補 evidence */ ],
    "applyBlocked": [ /* impl 卡外部 blocker（@apply-blocked marker），交還 user，不要硬推 */ ],
    "healthCheckNeeded": [ /* manual-review pattern hits，先 ingest/fix tasks.md */ ],
    "awaitArchiveWalkthrough": [ /* 只剩 [discuss]，走交付前收尾 walkthrough */ ],
    "awaitingUserDecision": [ /* Claude 已標 (awaiting-user-decision:)，等 user 商業拍板，不要硬推 */ ],
    "feedbackGiven": [ /* user 已標 issue 或 verify pending，交回 Claude 處理 */ ]
  }
}