@seanyao/roll 4.707.1 → 4.710.2

package/docs/INDEX.md

@@ -6,6 +6,7 @@
 
 | Path | Title | Category | Description |
 |------|-------|----------|-------------|
+| `docs/acceptance-contract.md` | 验收契约权属 / Acceptance Contract Ownership | process | 契约是设计层拥有的冻结产物(cycle 起始快照+漂移检测)、证据分类(web/cmd/roll-capture/named-tests)、能力天花板(存在性/绑定/权属 vs evaluator 判内容) |
 | `docs/architecture.md` | 系统设计 / System Architecture | architecture | 产品定位、设计原则、系统架构、领域模型、行为合同、事实来源 (US-TRUTH)、结构化交付真相、唯一查询入口、存储裁定、消费者契约 |
 | `docs/difftest-freeze-paradigm.md` | 快照冻结测试范式 | testing | CLI 命令输出用 Vitest 快照冻结的行为契约测试范式与可移植性陷阱 |
 | `docs/live-console.md` | 实时控制台指南 / Live Console Guide | guide | CLI-first 实时可观测指南：`roll loop cycle watch` 用法、三流契约、静态导出 vs 实时服务、证据按构造 |
@@ -15,8 +16,8 @@
 
 ## Coverage Summary
 
-- Total docs indexed: 6
-- By category: architecture (1) / guide (1) / migration (1) / testing (1) / product (1) / process (1)
+- Total docs indexed: 7
+- By category: architecture (1) / guide (1) / migration (1) / testing (1) / product (1) / process (2)
 
 ## Key Architecture Chapters (US-TRUTH epic)
 

package/docs/acceptance-contract.md

@@ -0,0 +1,105 @@
+# 验收契约权属 / Acceptance Contract Ownership
+
+> Category: process. The design-owned acceptance contract, the evidence taxonomy,
+> and the honest ceiling of what the harness can guarantee. Companion to
+> `docs/verification.md` (which specifies per-story AC + evidence shape).
+
+## 1. 契约是设计层拥有的冻结产物 / The contract is a design-owned, frozen artifact
+
+A story's **acceptance contract** is the set of things its delivery is judged
+against: its **AC criteria** and its **evidence surface** (`deliverable_url` /
+`deliverable_cmd` / physical screenshot / `screenshot_exempt`). Ownership is
+strict and one-directional:
+
+- **Designer owns it.** The contract is authored with the story and does not
+  change during a build.
+- **Builder only satisfies it.** The builder produces code + evidence to meet
+  the contract; it never authors or edits the contract.
+- **Evaluator only reads and judges it.** Attest reads the contract and decides
+  Done; it never lets the builder's own edits redefine the bar.
+
+**Enforced by topology, not per-agent tool permissions.** Roll runs a
+heterogeneous agent fleet; there is no uniform per-agent write-lock. Instead the
+contract is **frozen at cycle start** into a snapshot (a projection of the
+evidence-surface frontmatter + the set of AC criteria texts, hashed), taken from
+**design truth** — not the builder-writable worktree copy. The attest gate
+judges against that frozen snapshot; a worktree spec whose contract projection
+no longer matches the snapshot is **drift** and is surfaced as an alert. The
+projection deliberately EXCLUDES completion claims (checkbox state, the `✅`
+tick, the `**Status**` line, Delivery/narrative sections) so the ordinary
+stale-claim reset is never mistaken for tampering.
+
+**Ingest is shift-left and soft.** A story with an AC block must declare a
+capture surface OR a `screenshot_exempt` reason. A card that declares neither is
+recorded to a hold list and alerted at authoring time — never a hard block of
+ingestion, and runtime `pick_story` is never blocked (a false positive must not
+stall the loop).
+
+**Exemptions are design-time and audited.** `screenshot_exempt` is part of the
+frozen contract (a builder cannot introduce one that counts). "Exempt from
+screenshot" is not "exempt from evidence": an exempt card still owes another
+capturable evidence form (command output or named tests). The existing
+exemption rate is an observability smell signal (surfaced overall + per epic);
+legacy per-card exemptions and any policy epic-level blanket exempt
+(`acceptance.screenshot_exempt_epics`) are auditable read-only for batch review,
+forward-enforced and never retroactively blocked.
+
+## 2. 证据分类 / Evidence taxonomy
+
+Every AC-bearing story binds **at least one real, gate-resolvable capturable
+evidence**. There is no "give nothing" path. Screenshot is one kind, not the
+only kind:
+
+| Surface | Capture | Bound by |
+|---|---|---|
+| Web page (`deliverable_url`) | headless screenshot | harness |
+| CLI/terminal (`deliverable_cmd`, read-only roll command) | captured terminal output | harness |
+| Physical desktop / real terminal | **roll-capture** (real screen pixels) | harness |
+| Library / pure backend | named test-pass references | builder (non-captured) |
+
+For **captured** artifacts (the first three), the harness — which knows what it
+captured — is the intended owner of the ac-map binding, so the builder does not
+type or confirm those paths; the builder's ac-map covers only **non-captured**
+evidence (named tests, manual verification notes). "No screenshot" therefore
+still requires a declared `deliverable_cmd` or named tests — not silence.
+
+## 3. 能力天花板 / What this guarantees — and what it does not
+
+These mechanisms guarantee, structurally:
+
+- the contract cannot be silently tampered by the builder (frozen snapshot +
+  drift detection);
+- an AC-bearing card cannot enter the backlog with no declared way to produce
+  evidence (shift-left ingest);
+- captured evidence is bound to real on-disk artifacts, not invented paths.
+
+They do **not** guarantee that the evidence CONTENT actually proves the AC. A
+`deliverable_cmd: echo ok` or a vacuous test resolves as "evidence present" yet
+demonstrates nothing. **Judging whether the evidence genuinely satisfies the
+criterion is the Evaluator's semantic job** — read the content, score it — and
+is out of scope for the existence/binding/ownership guarantees above. The
+harness makes tampering hard and evidence necessarily present and correctly
+bound; it does not replace the reviewer reading the proof.
+
+## 4. 现状 / Implementation status (honest, not target-washed)
+
+This model is delivered incrementally; the doc describes the intended contract,
+and this section states what is LIVE vs DESIGNED so nothing above is read as
+more-enforced than it is.
+
+- **Live** (US-EVID-020/021/022): the contract PROJECTION + cycle-start frozen
+  snapshot (`contract-projection.ts`, `contract-snapshot.ts`); the attest gate's
+  worktree-vs-snapshot **drift alert** (`attest-gate.ts`, alert-only); the
+  **shift-left ingest** surface check + hold list (`ingest-gate.ts`), phased and
+  **default observe-only** (`metric`) — `alert`/`block` are opt-in via policy.
+- **Function delivered, surfacing pending** (US-EVID-026/027): the exemption-rate
+  computation (`exemption-stats.ts`) and read-only audit (`exemption-audit.ts`)
+  are implemented and unit-tested, but not yet wired into a board/`roll status`
+  line or a CLI command — they have no production caller yet.
+- **Designed / in progress**: harness-owned binding of captured artifacts into
+  the ac-map (US-EVID-023 — the read primitive exists; the draft-generator
+  wiring + capture-failure surfacing are not yet wired); the confirmed-ac-map
+  dangling-evidence remediation trigger (US-EVID-024); design-time hetero-
+  consensus confirmation of exemptions + the enforced substitute-evidence
+  requirement (US-EVID-025). Until those land, "no give-nothing path" and
+  "harness owns the binding" are the DESIGN intent, not a runtime guarantee.

package/docs/architecture.md

@@ -266,7 +266,7 @@ cycle 写 `loop:pending`，只做恢复探测，不启动 Builder、不把卡记
 Roll 的运行模式只有两个：`guided` 和 `autonomous`。它们不是两套 agent 配置，而是同一套 backlog、truth、route profile、execution profile、attest evidence、Evaluator 和 release gates 之上的两种触发方式。
 
 - `guided`：owner 通过 `roll supervisor status/next/why` 理解状态和下一步，再显式运行 `roll loop go --cards <id>` 等命令。guided 模式不会静默启动长时间 Story 执行。
-- `autonomous`：`roll loop on` 安装 scheduler；scheduler 可以在 pause、budget、route、evidence、Evaluator 和 release gates 内领取合格 Todo。`roll loop pause` / `roll loop off` 回到 guided；`roll loop resume` / `roll loop on` 显式切回 autonomous。
+- `autonomous`：`roll loop on` 安装 scheduler；scheduler 可以在 pause、budget、route、evidence、Evaluator 和 release gates 内领取合格 Todo。`roll loop pause` / `roll loop off` 回到 guided；`roll loop off --all` 是本机所有 `com.roll.*` LaunchAgent 的急停；`roll loop resume` / `roll loop on` 显式切回 autonomous。
 - 持久化来源只使用已有 loop/supervisor 状态：launchd plist、PAUSE/DORMANT marker、events/runs/backlog。不得新增独立 `mode.yaml` 之类的第二真相。
 
 ### BC9 · Supervisor 与执行剖面（v4）

package/guide/en/loop.md

@@ -206,6 +206,7 @@ roll loop on          # Install launchd scheduler (loop + pr + dream)
 roll loop off         # Remove launchd scheduler
 
 roll loop now         # Run one cycle immediately (same as launchd fires)
+roll loop now --cards US-1,FIX-2  # Run one immediate cycle scoped to selected cards
 roll loop test        # Quick smoke test: verify tmux/popup/stream chain works
 
 roll loop status      # Show scheduler state and current loop state
@@ -275,6 +276,8 @@ gates still decide eligibility.
 `roll loop go` is a manual goal session, not a launchd scheduler tick. While it
 runs, Roll holds `.roll/loop/go.lock`; scheduled ticks yield when they see that
 lock, record `goal:tick_skipped`, and do not start another `roll loop run-once`.
+`roll loop now --cards <ids>` uses the same card allow-list for its one-shot
+runner, so a manual tick cannot silently pick a different backlog card.
 
 Goal mode can run when the scheduler is off because it starts its own session
 and does not depend on launchd. For paused projects, run `roll loop resume`
@@ -298,6 +301,12 @@ dirty, the goal pauses with `bootstrap_artifacts_unconfirmed` and prints the
 files to confirm. Commit or clean them, then run `roll loop go` again. This
 preflight does not start a cycle and does not count as no-progress.
 
+For the Roll repository itself, `roll loop go`, `roll loop resume`, and
+`roll loop now` print the runner binary and version before starting autonomous
+work. They fail loud with `runner_stale_for_repo` if the repo-local
+`@seanyao/roll` package version is newer than the running runner; install or
+publish the local build before resuming autonomous work.
+
 `roll loop go` enforces safety only at cycle boundaries. `--budget <usd>` uses
 the effective run cost ledger and moves the goal to `budget_limited` when the
 budget is reached. An idle or aborted cycle that ran no agent counts as a known

package/guide/zh/loop.md

@@ -176,6 +176,7 @@ roll loop on          # 安装 launchd 调度器（loop + pr + dream 三个服
 roll loop off         # 卸载 launchd 调度器
 
 roll loop now         # 立即执行一次循环（与 launchd 触发的流程完全一致）
+roll loop now --cards US-1,FIX-2  # 立即执行一次循环，但只允许指定卡片
 roll loop test        # 快速冒烟测试：验证 tmux/弹窗/流式输出链路是否正常
 
 roll loop status      # 显示调度器状态和当前 loop 状态
@@ -244,6 +245,8 @@ Hold、Cut、未满足依赖、skip-list、open PR、已合并交付和 pending-
 `roll loop go` 是手动 goal session，不是 launchd 定时 tick。运行期间 Roll 会持有
 `.roll/loop/go.lock`；定时 tick 看到该锁就让路，记录 `goal:tick_skipped`，不会再启动
 另一个 `roll loop run-once`。
+`roll loop now --cards <ids>` 对它触发的单次 runner 使用同一份卡片 allow-list，
+所以手动 tick 不能静默改选其他 backlog 卡。
 
 goal mode 在 scheduler off 时也能运行，因为它自己启动会话，不依赖 launchd。loop 处于
 paused 状态时不建议直接启动：`PAUSE-<slug>` 标记仍会在 cycle 边界生效，所以应先执行
@@ -271,6 +274,11 @@ Roll-owned 文件提交并推送；如果历史版本或手工路径仍然只留
 `bootstrap_artifacts_unconfirmed` 暂停，并打印待确认文件。提交或清理后，再重新运行
 `roll loop go`。这个 preflight 不会启动 cycle，也不会累加 no-progress。
 
+在 Roll 仓自身里，`roll loop go`、`roll loop resume` 和 `roll loop now`
+开工前都会打印当前 runner 的 binary 与版本。repo-local `@seanyao/roll`
+包版本高于正在运行的 runner 时，它们会以 `runner_stale_for_repo`
+fail-loud；先安装或发布本地构建，再恢复自治施工。
+
 每次安全闸触发都会记录 `goal:gate_tripped`，`roll loop goal` 会显示最近一次安全闸读数。
 
 ### `roll loop goal` 字段含义

package/package.json

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

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

@@ -975,6 +975,62 @@ or the cap), not in it. A RESIZE is never emitted for a pure quality problem.
 
 ---
 
+## Construction-time independence & shift-left evidence (US-SKILL-031/032/033)
+
+The Review Score (FIX-343) and Phase 6 Agent 4 add independence *downstream* of a
+single builder that wrote BOTH the tests and the implementation. These three
+gates add independence and evidence freshness *during* construction. They were
+distilled from the US-EVID-026 delivery retro.
+
+### US-SKILL-031 — Adversarial pairing mode (verified / designed profiles)
+
+Under the `verified` and `designed` execution profiles, the **test author and the
+implementer are DIFFERENT, heterogeneous agents** — the agent that makes a test
+pass is never the one that wrote it, so tests and implementation cannot be
+co-shaped to be mutually flattering. The loop is:
+
+1. Test author writes a RED test for the next micro-step.
+2. Implementer (a different agent) writes ONLY production code to turn it green;
+   it must not edit the test.
+3. **Attack round** — once green, the test author writes ≥1 *breaking* test
+   targeting an untested failure mode; the implementer fixes; repeat until the
+   attacker is dry (N consecutive rounds surface no new hole).
+4. The attacker's breaking tests are added to the Phase 6 **Agent 4** test-audit
+   input, so "these failure modes are now pinned" is auditable.
+
+Cost: this approximately 2–3× the agent calls, so it is **bound to `verified` /
+`designed`** (high-stakes cards). `standard` keeps the single-builder + downstream
+audit unchanged. The profile choice is recorded (which was picked, and why).
+Independence is by session/context, not vendor (same FIX-343 red line): the
+test-author session must not be the implementer's session or a sub-agent of it.
+
+### US-SKILL-032 — Independent heterogeneous code review
+
+Phase 6's code review is performed by a **randomly-picked independent
+heterogeneous agent** (e.g. pi / kimi), NOT a sub-agent of the builder's session,
+and it emits a **structured verdict** — PASS/FAIL per AC plus a blocking-issue
+list — recorded with `reviewedBy` + session id so independence is verifiable (the
+same `scoredBy` contract as the Review Score). Independence is by session/context,
+not vendor. If no heterogeneous agent is available, fall back to `$roll-.review
+staged`, but **record the independence degradation explicitly** — never silently
+present a self-review as independent. This never becomes a hard block; its output
+feeds the existing fix-and-recheck loop.
+
+### US-SKILL-033 — Shift-left per-AC evidence
+
+Each AC's evidence is captured **at the moment that AC's TCR turns green** — fresh
+and bound to the micro-step — not batched at Phase 11. Phase 11 therefore
+DOWNGRADES from "collect evidence" to "**summarize already-captured evidence +
+generate the ac-map + render the report**"; an AC that reaches Phase 11 with no
+captured evidence is a **red flag** (its TCR never captured), not an invitation to
+now-collect. This is fully consistent with FIX-329 ("attest is earned during
+delivery, never backfilled") — it only moves the earning point earlier, from
+Phase 11 to the per-AC micro-step. Captured-artifact binding stays harness-owned
+(US-EVID-023); this governs the *timing* of non-captured evidence (command output,
+named tests).
+
+---
+
 ## TCR Recovery Patterns
 
 ### Pattern 1: Red After Multiple Attempts