@seanyao/roll 4.708.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.708.2",
+  "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