@seanyao/roll 4.703.2 → 4.706.1

package/docs/verification.md

@@ -73,6 +73,26 @@ diff <(v2.0-bash <cmd>) <(v3-ts <cmd>)
 - **回收**：`roll loop gc` 按阈值清理陈旧 run（保最近 N 次 + M 天内，二者满足其一即留；只删「又旧又超额」的尾部）。阈值 `--keep-latest`（默认 10）/`--keep-days`（默认 30），`--dry-run` 预演。
 - **读取兼容**：迁移窗口内旧布局 `.roll/verification/<ID>/` 仍可读（attest gate、ac-map、报告解析都先查卡夹再回落旧树）；存量迁移与兼容代码移除由 US-META-002 收尾。
 
+## 证据可见性模型（US-PHYSICAL-008）
+
+截图/图片类证据涉及隐私，因此在 `git add` 之前必须确认目标仓库的远程可见性：
+
+| 布局 | 目标仓库 | 判定策略 | 图片证据 |
+|------|----------|----------|----------|
+| 独立 roll-meta | `.roll` 自身所在的私有仓 | `gh api repos/<slug>` 或 `git ls-remote`；判定为 private 则放行 | 私有仓放行 |
+| 公开产品仓 + 独立 roll-meta | 产品仓本身不接收 `.roll` 证据；证据进私有 roll-meta | 同 roll-meta | 私有仓放行 |
+| in-repo `.roll` | 产品主仓（`.roll` 随代码一起 tracked） | 检查主仓 remote 可见性 | public / 未知 一律拒绝 |
+
+保守规则：判定失败（无 remote、`gh` 不可用、API 失败、非 GitHub 且无法推断可见性）一律按 **public** 处理，拒绝图片证据并触发 ALERT。
+
+逃生口：owner 可在 `.roll/local.yaml` 中显式声明
+
+```yaml
+evidence_public_waiver: true
+```
+
+放行公开仓的图片证据，同时留下审计痕迹。in-repo 项目首次成功判定后会把 `evidence_visibility` + `evidence_remote` 写入同一文件；remote URL 变化时自动重判。
+
 ## 门
 
 | 门 | 条件 | 频率 |

package/guide/en/acceptance-evidence.md

@@ -107,6 +107,11 @@ down to 🟧 Claimed and lists it under **Discrepancies**. Verbal completion
 
 `roll story validate` checks, at design time, that a spec is *born* with a
 visual-evidence AC (and, for a web surface, a declared product page to capture).
+If the spec has a visual-evidence AC but no declared surface
+(`deliverable_url`, `deliverable_cmd`, `physical_terminal`, or
+`screenshot_exempt`), validation prints a soft must-declare warning and still
+exits 0. Runtime gates carry the same must-declare signal as a diagnostic only;
+they do not block or mark the delivery skipped for that reason alone.
 Two rules decide what the validator recognises:
 
 - **The `[visual-evidence]` marker is authoritative.** An AC item that opens with
@@ -179,6 +184,19 @@ at startup:
   screenshot requests. If readiness is unavailable, `roll attest` records an
   honest skip with the setup reason instead of blocking report generation; if
   the provider times out, the report surfaces timeout as its own failure reason.
+  On macOS npm installs, Roll tries to install the app from the latest
+  `seanyao/roll-capture` Release into `~/Applications`; `roll setup` can retry
+  that repair unless `--no-capture-install` is set.
+
+  **Capture default strategy (US-PHYSICAL-006):** Physical screenshot requests
+  default to **window-level** capture — they only capture the tested application's
+  window (Terminal.app for terminal/CLI evidence, Google Chrome for web evidence),
+  not the full screen. Full-screen capture requires an explicit
+  `capture_fullscreen: true` frontmatter declaration in the card spec. This
+  privacy-first design prevents evidence chains from including irrelevant on-screen
+  content (chat, email, other projects). If the target window is not found, Roll
+  Capture.app returns a documented fallback with the reason recorded in the
+  response and evidence ledger — no silent expansion of capture scope.
 - `Playwright Chromium` — optional headless web capture for `roll attest` and
   archive screenshots. Install with `npx playwright install chromium`.
 

package/guide/en/configuration.md

@@ -21,6 +21,7 @@ shared conventions.
 | `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | Override the GC retention period for `roll loop gc`. Takes precedence over `loop_gc.retention_days` in `.roll/local.yaml`. |
 | `ROLL_FEED_BUDGET_BYTES` | `16384` | Byte budget for the context feed handed to the inner agent each cycle. Set it to a positive integer to dial the feed to the inner agent's capacity; non-numeric or non-positive values fall back to the default. |
 | `ROLL_AGENT_NUDGE` | `1` (on) | Compatibility agent preference switch. The scoped role binding is the primary selector; set this to `0` (or `off`/`false`/`no`) to disable legacy history preference. |
+| `ROLL_SKIP_CAPTURE_INSTALL` | unset | Set to `1` to skip the best-effort macOS `Roll Capture.app` install during npm postinstall and setup repair. |
 | `ROLL_RUN_DIR` | unset | Canonical acceptance-evidence run directory. The loop runner sets it before agent spawn; `roll attest --run-dir` and standalone `roll attest` can also consume it. |
 | `ROLL_EVIDENCE_DIR` | derived from `ROLL_RUN_DIR` | Directory for raw command/test artifacts inside the open evidence frame. Normally set by the runner or `roll test`, not by hand. |
 | `ROLL_SCREENSHOTS_DIR` | derived from `ROLL_RUN_DIR` | Directory for visual proof inside the open evidence frame. Normally set by the runner or capture lane, not by hand. |

package/guide/en/installation.md

@@ -22,7 +22,18 @@ curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
 npm install -g @seanyao/roll
 ```
 
-Requires Node.js 16+.
+Requires Node.js 22+.
+
+On macOS, the npm package runs a best-effort postinstall that downloads
+`Roll-Capture.app.zip` from the latest `seanyao/roll-capture` GitHub Release,
+validates the asset, and installs `Roll Capture.app` into `~/Applications`.
+Open the app once and grant Screen Recording permission before relying on
+physical screenshots. CI, headless sessions, non-macOS hosts, offline failures,
+sudo/root shells, and `ROLL_SKIP_CAPTURE_INSTALL=1` skip the app install without
+failing npm. If npm ran under sudo/root, run `roll setup` again as a regular user
+so Roll installs the app into that user's `~/Applications`, not `/var/root`.
+GitHub download requests respect `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` when the
+current Node runtime exposes the matching fetch dispatcher.
 
 After installation via either method, run setup to sync conventions and skills into your AI tools:
 
@@ -30,6 +41,10 @@ After installation via either method, run setup to sync conventions and skills i
 roll setup
 ```
 
+`roll setup --no-capture-install` keeps setup from attempting the same Roll
+Capture.app repair. `roll doctor tools` reports whether the app, permission
+proxy, and inbox are ready.
+
 ## Verify
 
 ```bash

package/guide/zh/acceptance-evidence.md

@@ -93,7 +93,11 @@ roll attest audit --json
 ## 设计期声明可视证据
 
 `roll story validate` 在设计期就检查一张卡是否**生而诚实**——带可视证据 AC，
-且 web 面要声明可截的产品页。校验器靠两条规则识别：
+且 web 面要声明可截的产品页。若卡有可视证据 AC，但没有声明任何交付面
+（`deliverable_url`、`deliverable_cmd`、`physical_terminal` 或
+`screenshot_exempt`），validate 只打印 must-declare 软警告，仍以 0 退出。
+运行时 gate 也只把同一信号作为诊断携带，不会仅因此阻断或把交付标成 skipped。
+校验器靠两条规则识别：
 
 - **`[visual-evidence]` 标记即定论。** 以字面 `[visual-evidence]` 标记开头的 AC
   条目**本身**就是可视证据 AC，无论后面写什么词——不必再额外写"截图 / screenshot"：
@@ -153,6 +157,15 @@ evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录
 - `Roll Capture.app` / `physical.screenshot` —— 物理截图请求的 provider 通道。
   就绪度不可用时，`roll attest` 记录带设置原因的 honest skip，不阻断报告生成；
   provider 超时时，报告把 timeout 作为独立失败原因展示。
+  macOS npm 安装会尝试从 `seanyao/roll-capture` 最新 Release 安装 app 到
+  `~/Applications`；`roll setup` 可重试这条修复路径，除非传入
+  `--no-capture-install`。
+
+  **截图默认策略 (US-PHYSICAL-006)：** 物理截图请求默认使用**窗口级**截取——
+  只截被测应用的窗口（终端/CLI 证据截 Terminal.app，网页证据截 Google Chrome），
+  不再默认全屏。全屏截图必须在卡片 spec 中显式声明 `capture_fullscreen: true`。
+  这个隐私优先的设计防止证据链夹带屏幕上无关的隐私内容（聊天记录、邮件、其他项目）。
+  如果目标窗口找不到，Roll Capture.app 会返回带有原因的降级记录——不允许静默扩大截取范围。
 - `Playwright Chromium` —— 可选的 headless web 截图工具，用于 `roll attest`
   和归档截图。安装命令是 `npx playwright install chromium`。
 

package/guide/zh/configuration.md

@@ -20,6 +20,7 @@ Roll 在启动时解析三个环境变量。在运行 `roll` 之前覆盖任意
 | `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | 覆盖 `roll loop gc` 的保留天数。优先级高于 `.roll/local.yaml` 中的 `loop_gc.retention_days`。 |
 | `ROLL_FEED_BUDGET_BYTES` | `16384` | 每个周期交给内层 agent 的上下文 feed 字节预算。设为正整数即可调节容量；非数字或非正数回落默认值。 |
 | `ROLL_AGENT_NUDGE` | `1`（开启） | 兼容期的 agent 偏好开关。新模型优先通过 scoped role binding 选择候选；设为 `0`（或 `off`/`false`/`no`）关闭历史偏好。 |
+| `ROLL_SKIP_CAPTURE_INSTALL` | 未设置 | 设为 `1` 时，跳过 npm postinstall 和 setup 修复里的 macOS `Roll Capture.app` 尽力安装。 |
 | `ROLL_RUN_DIR` | 未设置 | 验收证据 run 目录的标准入口。loop runner 在 agent 启动前设置；`roll attest --run-dir` 与独立 `roll attest` 也会读取它。 |
 | `ROLL_EVIDENCE_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的原始命令/测试产物目录。通常由 runner 或 `roll test` 设置，不需要手写。 |
 | `ROLL_SCREENSHOTS_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的视觉证据目录。通常由 runner 或截图通道设置，不需要手写。 |

package/guide/zh/installation.md

@@ -22,7 +22,16 @@ curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
 npm install -g @seanyao/roll
 ```
 
-需要 Node.js 16+。
+需要 Node.js 22+。
+
+macOS 上，npm 包会在 postinstall 中尽力从 `seanyao/roll-capture` 最新 GitHub
+Release 下载 `Roll-Capture.app.zip`，校验后安装 `Roll Capture.app` 到
+`~/Applications`。使用物理截图前，请打开一次应用并授予 Screen Recording 权限。
+CI、headless、非 macOS、sudo/root shell、离线失败以及
+`ROLL_SKIP_CAPTURE_INSTALL=1` 都会跳过 app 安装，且不会让 npm 安装失败。若 npm
+是在 sudo/root 下运行，请再以普通用户跑 `roll setup` 安装，避免装进
+`/var/root`。当前 Node runtime 暴露对应 fetch dispatcher 时，GitHub 下载请求会遵守
+`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`。
 
 无论哪种方式安装，完成后运行 setup 将约定和技能同步到你的 AI 工具：
 
@@ -30,6 +39,9 @@ npm install -g @seanyao/roll
 roll setup
 ```
 
+`roll setup --no-capture-install` 会禁止 setup 尝试同一套 Roll Capture.app 修复。
+`roll doctor tools` 会报告 app、权限代理和 inbox 是否就绪。
+
 ## 验证
 
 ```bash

package/lib/i18n/init.sh

@@ -46,8 +46,8 @@ _i18n_set en init.plan_validation_failed_see_errors_above "Plan validation faile
 _i18n_set zh init.plan_validation_failed_see_errors_above "校验失败。"
 _i18n_set en init.applying_onboard_plan "Applying onboard plan..."
 _i18n_set zh init.applying_onboard_plan "正在应用 onboard 计划..."
-_i18n_set en init.added_roll_to_gitignore "Added .roll/ to .gitignore"
-_i18n_set zh init.added_roll_to_gitignore "已将 .roll/ 加入 .gitignore"
+_i18n_set en init.added_roll_to_gitignore "Added Roll runtime ignores to .gitignore"
+_i18n_set zh init.added_roll_to_gitignore "已将 Roll 运行时忽略项加入 .gitignore"
 _i18n_set en init.syncing_conventions_to_ai_tools "Syncing conventions to AI tools..."
 _i18n_set zh init.syncing_conventions_to_ai_tools "正在同步约定到 AI 工具..."
 _i18n_set en init.onboard_apply_complete_onboard "Onboard apply complete.  Onboard"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.703.2",
+  "version": "4.706.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {
@@ -10,6 +10,7 @@
     "test:e2e": "pnpm -r build && pnpm --filter @roll/cli exec vitest run test/critical-flows.e2e.test.ts",
     "test:cov": "pnpm -r exec vitest run --coverage.enabled --coverage.provider=v8 --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=text",
     "bundle": "node scripts/bundle.mjs",
+    "postinstall": "node scripts/postinstall-roll-capture.mjs",
     "prepack": "pnpm -r build && pnpm bundle"
   },
   "keywords": [
@@ -35,6 +36,7 @@
     "docs/",
     "guide/",
     "lib/",
+    "scripts/postinstall-roll-capture.mjs",
     "skills/",
     "template/",
     "README.md",

package/scripts/postinstall-roll-capture.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+try {
+  await import("../dist/postinstall.mjs");
+} catch (error) {
+  // The source checkout may not have been bundled yet. Published tarballs carry
+  // dist/postinstall.mjs; either way npm install must never fail here.
+  const reason = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`postinstall skipped: ${reason}\n`);
+}