@seanyao/roll 4.710.2 → 4.712.1

package/docs/architecture.md

@@ -281,6 +281,8 @@ v4 把"一张 Story 怎么交付"和"项目级怎么协调"分成两层。
 
 剖面在 Cycle 开始时选一次并记入 `execution:profile` 事件。角色之间只通过 artifact（`role-artifacts/designer/design-contract.md` / `execute-evidence` / `eval-report.md` + `artifact-manifest.json`）交接，不共享原始会话；每个角色都是 fresh session。`evaluate` 不是单一 `pass/fail`——blocking review、score、attest 是三个分开的契约。evaluate→execute 的修复回合受硬熔断约束（最大轮数、重复 finding 签名、预算、超时），触界即升级。
 
+**攻防结对（Adversarial pairing，`verified` / `designed` 剖面内的 Builder 步）**：在这两个剖面里，Builder 步不再是单个 agent 同时写测试和实现，而是由**循环引擎真正编排**（US-LOOP-100..106，全在 `@roll/core` + CLI runner）：先 spawn 一个 test_author 写红测试 → 再 spawn 一个**异构**的 implementer 只写实现变绿（不得改测试）→ 绿后进入攻防回合（attacker 补破坏性测试 → implementer 修），直到攻不动。终止由纯函数 `adversarialNextStep` 三重独立判定（按优先级 总超时 → 回合上限 → 连续无洞,任一命中即停）保证**无人值守绝不挂死**；任何攻防异常（无异构伙伴 / agent 不可用 / 单回合挂死）经 `adversarialDegradeDecision` **降级回标准单 builder** 完成本卡并记 `adversarial:degraded` 事件——不静默、不死锁。默认参数：`max_rounds=4`、`dry_rounds_to_stop=2`、`total_timeout_sec=2700`。每卡结果（回合数 / 抓洞数 / 终止原因 / 是否降级）折进 runs 行，`roll loop adversarial` 输出攻防 vs 标准 cohort 的只读影子跑聚合，供 owner 用数据决定是否扩大剖面覆盖（设计 §9）。攻防路径**默认休眠**，仅当项目把 `execution_policy.mode` opt-in 到 verified/designed 才启用；`standard` 剖面零变化。
+
 **Supervisor**：项目级协调者，负责不属于某一张具体 Story 的工作——跨 Story/Epic 上下文、backlog 排序、风险分级、执行剖面建议、路由/Rig 建议、预算、并行、卡住的 cycle、重复失败、文件冲突、合并队列、发布就绪、truth coverage / 显式 release blockers、系统级用户交互（"接下来做什么？""为什么卡住？"）与 owner 升级。
 
 Supervisor **绝不**：实现具体 Story、写 Story 的评估报告、覆盖 Evaluator 裁定、绕过 attest 闸、直接标记 Story 为 Done、用指标静默改写路由/策略。v4.0 的 Supervisor 是 observe/advise（`roll supervisor`）：先用确定性 selector 把事实结构化，再（必要时）让 agent 措辞建议；历史 Done 缺少结构化 DeliveryRecord 只作为 truth coverage/backfill 提醒，发布是否阻塞以显式 release blockers / release consistency 为准；持久化策略变更一律需 owner 确认。安全并行调度（`max_parallel_cycles`、文件冲突串行化、合并队列/预算暂停）的决策逻辑已就位，活体并行交付留待 v4.1。

package/package.json

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

package/skills/roll-build/SKILL.md

@@ -58,3 +58,5 @@ same TCR, evidence, Evaluator, and release gates apply in both modes.
 ## Role in v4 execution profiles
 
 **roll-build is the Builder capability in every execution profile** (`standard` / `verified` / `designed`). Under `designed` it receives the Designer's `design-contract.md` via artifact refs (no shared raw session). Under `verified`/`designed` an independent **Evaluator** (a fresh session) judges the delivery and may open a BOUNDED repair round — you address the blocking findings and write a repair note mapping findings → changes. `standard` is Builder-only. Roles: Supervisor / Designer / Builder / Evaluator.
+
+Under `verified`/`designed` the Builder step itself is the **engine-orchestrated adversarial pair** (US-LOOP-100..106, dormant until `execution_policy.mode` opts in): the loop spawns a heterogeneous test_author ≠ implementer and drives attack rounds, with deterministic never-hang termination, fail-closed degrade to a single builder (`adversarial:degraded`), and a `roll loop adversarial` shadow-run aggregate. See references/full-contract.md § US-SKILL-031.

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

@@ -987,7 +987,9 @@ distilled from the US-EVID-026 delivery retro.
 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:
+co-shaped to be mutually flattering. **This is now orchestrated by the loop engine
+itself** (US-LOOP-100..106), not left to builder self-discipline — the runner
+spawns the roles and drives the rounds:
 
 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;
@@ -995,14 +997,40 @@ co-shaped to be mutually flattering. The loop is:
 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.
+4. The attacker's breaking tests are committed to the branch as real test files,
+   so Phase 6 **Agent 4** audits them as part of the suite — "these failure modes
+   are now pinned" is auditable via the tests themselves. (The engine tracks the
+   attack-test paths in-cycle for the round bookkeeping; it does not forward them
+   as a separate persisted data channel.)
+
+How the engine runs it (all in `@roll/core` + the CLI runner, not a prose
+convention):
+
+- **Sequencing** — the orchestrator's execute phase emits a `spawn_role`
+  subsequence (`test_author → implementer → attack rounds`) instead of a single
+  `spawn_agent`, driven by the pure `adversarialNextStep` termination algorithm
+  (three independent stops, checked in precedence order total-timeout → max-rounds
+  → dry-streak; any one halts the loop, so it can **never hang unattended**).
+  `standard` cycles still emit the single builder,
+  byte-unchanged.
+- **Fail-closed degrade** — any adversarial exception (no heterogeneous partner,
+  an unavailable agent, a hung round) routes through `adversarialDegradeDecision`
+  and falls back to a standard single builder that completes the card, emitting an
+  `adversarial:degraded` event — **never silent, never deadlock**. The role spawns
+  carry the same main-checkout write-protection as the builder.
+- **Observability** — each cycle's outcome (`rounds / holesFound /
+  terminationReason / degraded`) is folded onto the runs row, and
+  `roll loop adversarial` prints the read-only shadow-run aggregate (adversarial
+  vs standard cohort, avg holes, degrade rate) so profile expansion is a
+  data-backed decision (design §9), not a guess.
 
 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.
+The adversarial path is **dormant until a project opts into the verified/designed
+execution profile** (`execution_policy.mode`); a standard-mode project is unaffected.
 
 ### US-SKILL-032 — Independent heterogeneous code review