@seanyao/roll 4.712.1 → 4.713.1

package/docs/architecture.md

@@ -77,10 +77,10 @@ web          站点与静态展示（当前不是活体 Supervisor 控制台）
 
 这是系统的引擎。一个 Loop 是一个自治进程，按定时器唤醒，执行一个 Cycle。
 
-**Cycle 生命周期**：选故事 → 路由 agent → 创建隔离工作区 → agent 执行（TCR 循环）→ 送交 PR → 等合并 → 对账 → 收尾。
+**Cycle 生命周期**：选故事（先查租约 `deliveryLease`）→ 路由 agent → 创建隔离工作区 → agent 执行（TCR 循环）→ attest 硬闸 → 送交 PR → AWAITING_MERGE 挂起并释放 loop → pick 下一张卡。交付推进由 Delivery Reconciler 在任意 `roll` 调用时机会性对账完成——不依赖独立 daemon。
 
 **关键约束**：
-- 一 Cycle 只做一个 Story。前一个未交付，不拿下一个。
+- 一 Cycle 只做一个 Story。AWAITING_MERGE 后释放 loop，拿下一个；交付由 Delivery Reconciler 对账推进，不 block loop。
 - 进程可能被 SIGKILL。下次唤醒时，通过锁龄、心跳、PID 判断孤儿态，安全接管或重做。
 - 心跳每 60 秒写入一次。超时无心跳 → 判定死亡并落终态。
 - 退出时无条件写入终态。这是硬约束——trap 兜底。
@@ -89,8 +89,7 @@ web          站点与静态展示（当前不是活体 Supervisor 控制台）
 **Loop 类型**：
 | 类型 | 职责 |
 |------|------|
-| main | 消费待办，执行完整的 pick→TCR→PR→对账 周期 |
-| pr | 监控 open loop PR：CI 挂了自愈，绿了合并 |
+| main | 消费待办，执行完整的 pick→TCR→PR→AWAITING_MERGE→对账 周期（含 Delivery Reconciler 机会性对账） |
 | ci | 监控 CI 状态 |
 | alert | 消费 ALERT 文件，推送到用户 |
 
@@ -139,13 +138,62 @@ cycle 写 `loop:pending`，只做恢复探测，不启动 Builder、不把卡记
 **反规则**：不因历史表现自动改写角色绑定。不做失败后的静默跨 agent 重试。指标可以*建议*
 策略变更，但绝不绕过 human-on-the-loop。
 
-### BC4 · 交付
+### BC4 · 交付（Delivery Reconciler）
 
 每次交付是一个 Pull Request。一个 Story 至多同时有一个 open PR。
 
-**生命周期**：开 PR → CI 通过 → 合并入 main → 删除分支。
+**最后一公里 = 一个 reconcile 闭环，无独立守护进程。**
 
-**交付判定**：合并入 main 才算交付。PR 已开、CI 已绿、agent 声称完成都不算——事后对账，只认 main 上真实的 merge commit。
+#### 交付生命周期
+
+```
+building ──attest earned──► publishable ──push+PR──► awaiting_merge ──┐
+   │                                                                  │
+   └─attest MISSING──► blocked_no_evidence (fail-loud，不推分支)        │
+                                                                       ▼
+   awaiting_merge ──L1/L2 强信号命中──► delivered / delivered_external
+   awaiting_merge ──CI 绿未合──► 自驱合并 (gh pr merge --squash) ──► 下轮判 delivered
+   awaiting_merge ──CI 红──► ci_failed ──► fix-forward cycle
+   awaiting_merge ──同卡他 cycle 已 delivered──► superseded（带原因）
+   awaiting_merge ──证据不足──► 留 awaiting_merge（绝不误判）
+```
+
+**交付状态**：
+
+| 状态 | 含义 |
+|------|------|
+| `building` | TCR 进行中 |
+| `blocked_no_evidence` | 过了测试但缺 attest/ac-map → fail-loud，未推分支 |
+| `awaiting_merge` | 分支+PR 已开；挂起，loop 释放并继续下一张卡 |
+| `ci_failed` | PR CI 红 → 需 fix-forward |
+| `delivered` | 合进 main：runner 自驱合并 |
+| `delivered_external` | 合进 main：外部（supervisor / 人手动合 / 其他 cycle）——patch-id / PR-state 反查确认，一等公民 |
+| `superseded` | 同卡另一 cycle 已 delivered |
+| `abandoned` | lease 释放 / 卡撤销 |
+
+#### 分层真相判定（强→弱，任一强信号即 delivered）
+
+| 层 | 信号 | 可靠性 | 何时可用 |
+|---|---|---|---|
+| L1 | **PR 状态**：`gh pr view` → `MERGED` | 最强（权威） | gh 可用且 PR 可解析时 |
+| L2 | **patch-id 等价**：`git patch-id(diff origin/main...branch)` ∈ main 候选 merge commit 的 patch-id 集 | 强（squash/rebase 安全） | 离线也行；不依赖 gh |
+| L3 | **backlog Done + attest 报告存在** | 弱（仅佐证，单独不足） | 兜底交叉验证 |
+
+**判定规则**：`delivered` 需 ≥1 个强信号（L1 或 L2）。L3 单独不足以判 delivered（agent 可能预写 Done）。L1 与 L2 冲突时以 L1 为准并告警。全不命中 → 留 `awaiting_merge`，**绝不误判**。
+
+#### Delivery Reconciler
+
+纯判定 + 薄 IO，在任意 `roll` 调用 / cycle 边界 / `roll loop reconcile` 时机会性运行：
+
+- **触发点**：(a) 每次 `roll loop` cycle 边界；(b) 任意 `roll` 命令的前置机会性 reconcile；(c) 显式 `roll loop reconcile [--json]`；(d) CI 里可选一步
+- **自驱合并**：CI 绿且未合 → `gh pr merge --squash`，不依赖仓库 auto-merge 开关、不依赖 launchd
+- **外部合并反查**：supervisor / 人手动合并被 patch-id / PR-state 自动回填为 `delivered_external`——手动合并是一等支持路径，不是泄漏
+- **幂等 & 崩溃可续**：reconcile 反复跑永远安全，向真相收敛
+- **退役守护进程**：原 `com.roll.pr.<slug>` launchd PR-loop 守护已退役，合并逻辑整体搬进 Delivery Reconciler，不再需要常驻进程
+
+#### 交付判定
+
+合并入 main 才算交付。PR 已开、CI 已绿、agent 声称完成都不算——事后对账，只认 main 上真实的 merge commit。main 是唯一交付真相；reconcile 只把真相投影回 cycle 行。
 
 ### BC5 · 演化
 

package/guide/en/loop.md

@@ -271,6 +271,23 @@ three ranking suggestions and reasons. The ranking is advisory only; Hold, Cut,
 unsatisfied dependencies, skip-list, open PR, merged-delivery, and pending-publish
 gates still decide eligibility.
 
+### One Card, One Lease
+
+By default a card has exactly one delivery lease. Before picking, the picker
+consults the delivery leases derived from the event stream: a card already
+`in_flight`, `awaiting_merge`, `ci_red`, or `delivered` is skipped with a
+`card held: <state> (<cycle>)` reason (event `pick:skipped`, idle reason
+`all_leased`). Same-card parallel builds are off — quality redundancy comes
+from the adversarial pair inside one cycle, not from duplicate builds that only
+one merge can land. A cycle that ended without delivering releases its lease,
+so a legal fix-forward retry of the same card stays pickable.
+
+`roll loop run-once --race` is the explicit opt-in for same-card parallel
+racing (carried to child cycles as `ROLL_LOOP_RACE=1`). On the FIRST merge,
+`roll loop reconcile` atomically supersedes the remaining sibling cycles
+(`delivery:reconciled{superseded}`), so racing costs at most one merge plus
+discarded sibling work — never duplicate deliveries.
+
 ### Goal Mode vs Scheduled Mode
 
 `roll loop go` is a manual goal session, not a launchd scheduler tick. While it

package/guide/zh/loop.md

@@ -240,6 +240,19 @@ roll agent list                      # 查看本机已装的 agent
 Hold、Cut、未满足依赖、skip-list、open PR、已合并交付和 pending-publish gate 仍决定
 卡片是否可选。
 
+### 一卡一租约
+
+默认一张卡只有一条交付租约。选卡前 picker 会先咨询由事件流投影出的交付租约：
+卡已处 `in_flight`、`awaiting_merge`、`ci_red` 或 `delivered` 一律 skip，理由形如
+`card held: <state> (<cycle>)`（事件 `pick:skipped`，idle 理由 `all_leased`）。
+同卡并行建造默认关闭——质量冗余由单 cycle 内的攻防结对提供，不靠"只有一份能合入"
+的重复建造。已结束但未交付的 cycle 会释放租约，所以同卡的合法 fix-forward 重试仍可被选。
+
+`roll loop run-once --race` 是同卡并行竞速的显式开关（经 `ROLL_LOOP_RACE=1` 传给
+子 cycle）。首个 merge 发生时，`roll loop reconcile` 原子取消其余 sibling cycle
+（`delivery:reconciled{superseded}`），竞速的代价至多是一份合入加 sibling 废活，
+绝不产生重复交付。
+
 ### Goal Mode 与定时模式
 
 `roll loop go` 是手动 goal session，不是 launchd 定时 tick。运行期间 Roll 会持有

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.712.1",
+  "version": "4.713.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/roll-build/SKILL.md

@@ -43,6 +43,7 @@ same TCR, evidence, Evaluator, and release gates apply in both modes.
 - In the test-gated loop the tests are the weakest link: an isolated Test Adequacy reviewer (Phase 6 Agent 4) audits the tests against the AC, seeing only AC + test files — never the implementation diff or builder reasoning. Self-review of one's own tests (Phase 2) is necessary but not isolation.
 - Self-review, attest, and E2E evidence remain required. The Review Score is produced by the runner's fresh-session peer Reviewer — the agent does NOT self-score.
 - Docs/code/product alignment is a DoD gate: user-visible behavior, command, output-copy, site, or delivery-view changes update the touched README/docs/guide/site/help in the same delivery.
+- Done ≡ merged to `main`. After publish the cycle is `awaiting_merge`; the Delivery Reconciler (no daemon) self-drives the merge and reconciles truth from `main` — manual merges are first-class (`delivered_external`). Never pre-flip a card to Done on an open PR.
 
 ## Gotchas
 

package/skills/roll-build/references/full-contract.md

@@ -750,17 +750,21 @@ story (loop or manual Phase 10.6) and earn the report at delivery time.
 
 **Done ≡ merged (FIX-322/323).** A card is `✅ Done` only once its delivery is
 **merged to `main`** — not when the branch is pushed and not while the PR is
-merely open. `published_pending_merge` (pushed / PR open, awaiting merge) is
-**not** delivered. Consequences you can rely on:
+merely open. `awaiting_merge` (pushed / PR open, awaiting merge) is **not**
+delivered. Consequences you can rely on:
 
-- The picker **skips** any card that already has a merged delivery, so a card
-  reset to 📋 Todo after merge is not re-picked and re-built.
-- Preflight reconciles truth from the PR: a 🔨 In Progress card whose PR has
-  **MERGED** is flipped to ✅ Done automatically (an OPEN PR is left alone).
+- The picker **skips** any card that already has a merged delivery (one card,
+  one `deliveryLease`), so a card reset to 📋 Todo after merge is not re-picked
+  and re-built.
+- Truth reconciles from `main`: the **Delivery Reconciler** (US-DELIV-001..007,
+  no daemon — the `com.roll.pr.<slug>` PR Loop is retired) confirms merges via
+  PR-state (L1) / patch-id (L2) and flips the cycle to `delivered` — manual /
+  external merges included (`delivered_external` is first-class).
 
 So on the manual path, flip the row to Done **after** the PR merges; under
-`roll-loop` the runner waits for green CI, auto-merges, and the flip follows the
-merge — do not pre-flip on a still-open PR.
+`roll-loop` the cycle ends at publish (`awaiting_merge`) and the reconciler
+self-drives the merge (`gh pr merge --squash` on green CI) and flips the row
+once the merge lands on `main` — do not pre-flip on a still-open PR.
 
 Both locations must be updated — neither can be skipped:
 
@@ -863,10 +867,11 @@ Before creating any file or directory:
    Work is not complete until it reaches:
    commit → push → CI signal → **PR merged to main** → deploy → online
    verification → backlog update.
-   A pushed branch or an open PR is `published_pending_merge`, NOT delivered;
-   the row flips to `✅ Done` only after the merge. Truth reconciles from the
-   PR: the picker skips already-merged cards and preflight flips a MERGED PR's
-   card to Done.
+   A pushed branch or an open PR is `awaiting_merge`, NOT delivered;
+   the row flips to `✅ Done` only after the merge. Truth reconciles from
+   `main`: the Delivery Reconciler confirms merges via PR-state / patch-id
+   (manual merges included → `delivered_external`) and the picker skips
+   already-merged cards.
 
 2. **TCR for every micro-step**
    - Each behavior change: Test → Green=Commit / Red=Revert

package/skills/roll-loop/SKILL.md

@@ -38,6 +38,14 @@ bypasses pause, budget, route, evidence, Evaluator, or release gates.
 4. Persist events, runs, alerts, and status.
 5. Pause on repeated failure.
 
+## Delivery Lifecycle (US-DELIV-001..007)
+
+最后一公里 = 一个 reconcile 闭环，无独立守护进程（`com.roll.pr.<slug>` PR Loop 已退役）。
+
+- A cycle ends at publish: branch pushed + PR opened → `awaiting_merge`; the loop is released to pick the next card. Nothing blocks on merge.
+- The **Delivery Reconciler** advances delivery opportunistically — cycle boundaries, read paths, and explicit `roll loop reconcile`: CI-green PRs are merged self-drive (`gh pr merge --squash`); merged PRs reconcile from `main` (L1 PR-state / L2 patch-id) to `delivered`; external / manual merges reconcile to `delivered_external` (first-class); insufficient evidence stays `awaiting_merge` — never misjudge.
+- Reconcile is idempotent and crash-safe: any single `roll` invocation can advance the truth.
+
 ## Hard Gates
 
 - Loop never cuts a release autonomously.

package/skills/roll-loop/references/full-contract.md

@@ -301,14 +301,18 @@ After each item completes:
 
    **Path B — heal exhausted (≥`ROLL_LOOP_HEAL_MAX`, default 2) or disabled (`ROLL_LOOP_NO_HEAL=1`) (exit 1):**
 
-   1. Do NOT force ✅ Done here. CI red means the PR will not merge. Under
-      **US-AUTO-044** the main loop no longer waits for merge — it publishes the
-      PR and exits; the dedicated PR Loop (`com.roll.pr.<slug>`, every 5 min)
-      merges / rebases / closes it asynchronously. There is no false-Done risk:
+   1. Do NOT force ✅ Done here. CI red means the PR will not merge. The main
+      loop never waits for merge — it publishes the PR, records
+      `awaiting_merge`, and exits; the **Delivery Reconciler**
+      (US-DELIV-001..007, no daemon — the `com.roll.pr.<slug>` PR Loop is
+      retired) advances it opportunistically on cycle boundaries and on
+      `roll loop reconcile`: self-drive merge (`gh pr merge --squash`) once CI
+      turns green, then reconcile to `delivered` / `delivered_external` from
+      `main` (L1 PR-state / L2 patch-id). There is no false-Done risk:
       with worktree isolation the ✅ Done lives only in the unmerged PR, never on
       the loop's main checkout, and the story is not re-picked meanwhile via the
-      open-PR eligibility gate (FIX-146). The story's
-      ✅ Done lands on main only when the PR Loop actually merges the PR.
+      open-PR eligibility gate (FIX-146) / `deliveryLease`. The story's
+      ✅ Done lands on main only when the reconciler confirms the merge.
    2. Write ALERT to `~/.shared/roll/loop/ALERT-<slug>.md` with:
       - story ID, time, commit SHA
       - heal attempts made (read `heal_count:` from `state-<slug>.yaml`)