@seanyao/roll 2.604.2 → 3.606.1

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## v3.606.1
+
+### 新功能
+
+- **`roll attest` 验收证据链上线** — 每个交付的 story 可生成单文件验收报告：逐条 AC 判定（五档徽章）、证据卡片（截图 / 可搜索的 CLI 文本 / commit·CI·部署链接）、零证据强制降级红线 + 缺口附录；离线可开、可打印 PDF。web/iOS/Android 三端截屏各带前置自动跳过；同 story 自评条目折叠展示
+- **发版一致性闸** — 每个 v* tag 在创建 Release 前先过 `roll consistency check`：任一维度对不上即中止发版，差异清单见 job 日志
+- **loop 调度面 TS 化** — `loop on/off/pause/resume/now` 原生实现；`loop on` 生成自包含 v3 runner（周期心脏 = `loop run-once`）；`loop now` 检测旧版模板自动再生成后再跑（根治 command not found）
+
+### 稳定性
+
+- **backlog 状态端到端确定性** — 取卡即标 🔨 进行中、交付完成确定性翻 ✅ Done、崩溃残留的认领自动回收；普通项目（.roll 被 gitignore）布局下状态不再悬空
+- **changelog 不再漏卡** — 裸 ID（非链接形）的 Done 行正确入草稿；空草稿时 `--write` 不写占位句
+- **peer 硬触发留痕** — 高复杂度交付未经评审会在事件流与 ALERT 留下可审计记录
+
+### 精简
+
+- **tart 隔离 lane 移除** — `test_isolation.type` 只留 `none`；残留 tart 配置显式报错退出，绝不静默回落宿主
+- **bats 测试套件退役** — 51k 行 bash 测试由 TS diff-test 体系接管（对使用者无感；v2 分支保留全量历史）
+
+### 文档
+
+- **架构与理念文档归仓** — `docs/architecture.md`（分层 / 领域 / 12 条不变量）、`docs/verification.md`、`docs/manifesto.md`
+- **双语新章** — 验收证据指南、一致性与发版闸指南、README 仓库结构章节与环境要求修正
+
+
+## v3.0.0
+
+### TypeScript 重写
+
+- **引擎从 bash 换成 TypeScript** — roll 的核心重写为 pnpm monorepo（`packages/`：spec/core/infra/cli/web 分层）。这是一次引擎替换，不是功能改版
+- **命令一个不变** — `roll init` / `loop` / `status` / `backlog` / `prices` / `slides` 等全部子命令的入参、输出、副作用、退出码保持原样；升级后照旧用
+- **逐层对拍迁移** — 地基、CLI、领域服务、infra、loop 各层逐条移植，每条命令写 diff-test 断言「TS 输出 == 原 bash 输出」，逐字节对齐冻结的 v2 oracle
+- **1031 项 TS 测试全绿** — 单测覆盖每个公共入口 + 跨层 diff-test；`npm i -g @seanyao/roll` 装的就是这套 TS-first CLI
+
+### 兼容与回滚
+
+- **bash 实现留作回落 + oracle** — `bin/roll` 随包一起发布：TS 层尚未接管的命令自动透传 bash，行为零差异；同一份 bash 也是测试套件的标准答案
+- **v2 归档在 `v2` 分支** — 锚点 tag `v2-freeze-2026-06-04`，需要时一键回滚
+
 ## v2.604.2
 
 ### 精简

package/README.md

@@ -26,7 +26,7 @@ curl -fsSL https://seanyao.github.io/roll/install | bash
 npm install -g @seanyao/roll
 ```
 
-Requirements: bash 3.2+. npm/Node.js not required — curl install is self-contained.
+Requirements: Node.js ≥ 22 (the CLI entry runs on node). bash 3.2+ for the bundled fallback engine.
 
 ## Use
 
@@ -53,7 +53,7 @@ roll loop on        # let AI work through the backlog (optional)
 | `roll status` | Show current state and drift |
 | `roll agent [use <name>]` | Per-project agent selection |
 | `roll ci [--wait]` | Show or wait for current commit's CI status |
-| `roll test [--where] [--reset]` | Run the test suite (routes through isolation adapter; Tart VM on Apple Silicon) |
+| `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |
 | `roll release` | Run the release script (human-only) |
 | `roll review-pr <number>` | AI-powered code review for a PR |
 | **Machine · global** | |
@@ -61,6 +61,23 @@ roll loop on        # let AI work through the backlog (optional)
 | `roll update` | Upgrade to latest + re-sync |
 | `roll version` | Print installed roll version |
 
+## Repository layout
+
+Dev side — a pnpm monorepo. Publish side — one npm package.
+
+```
+packages/      TypeScript engine (pnpm workspaces): spec · core · infra · cli · web
+bin/roll       Frozen bash v2 engine — automatic fallback + the diff-test oracle
+lib/           Runtime companions (python/sh) used by the loop & fallback paths
+skills/        Git submodule → seanyao/roll-skills (the agent skill contracts)
+conventions/   Conventions synced into AI clients by `roll setup`
+template/      Project scaffolding installed by `roll init`
+```
+
+The frozen v2 bash lives on the `v2` branch (anchor tag `v2-freeze-2026-06-04`). Build & test: `pnpm install && pnpm -r test`.
+
+Published as a single npm package `@seanyao/roll`: `dist/` (TS bundled by esbuild) + `bin/` + `lib/` + `skills/` + `conventions/` + `template/`.
+
 ## Documentation
 
 | Topic | English | 中文 |
@@ -79,7 +96,13 @@ roll loop on        # let AI work through the backlog (optional)
 | Slides — Layouts reference | [guide/en/slides.md#layouts](guide/en/slides.md#layouts) | [guide/zh/slides.md#layouts布局](guide/zh/slides.md#layouts%E5%B8%83%E5%B1%80) |
 | Feedback (`roll feedback`) | [guide/en/feedback.md](guide/en/feedback.md) | [guide/zh/feedback.md](guide/zh/feedback.md) |
 | Backlog GitHub sync (`roll backlog sync`) | [guide/en/backlog-github-sync.md](guide/en/backlog-github-sync.md) | [guide/zh/backlog-github-sync.md](guide/zh/backlog-github-sync.md) |
-| Test isolation (`roll test` + Tart VM) | [guide/en/test-isolation.md](guide/en/test-isolation.md) | [guide/zh/test-isolation.md](guide/zh/test-isolation.md) |
+| Test isolation (`roll test`) | [guide/en/test-isolation.md](guide/en/test-isolation.md) | [guide/zh/test-isolation.md](guide/zh/test-isolation.md) |
+| Acceptance evidence (`roll attest`) | [guide/en/acceptance-evidence.md](guide/en/acceptance-evidence.md) | [guide/zh/acceptance-evidence.md](guide/zh/acceptance-evidence.md) |
+| Consistency & release gate | [guide/en/consistency.md](guide/en/consistency.md) | [guide/zh/consistency.md](guide/zh/consistency.md) |
+| Architecture (layers · domain · invariants) | [docs/architecture.md](docs/architecture.md) | — |
+| Verification system | [docs/verification.md](docs/verification.md) | — |
+| Manifesto · 理念 | [docs/manifesto.md](docs/manifesto.md) | — |
+| Acceptance evidence (`roll attest`) | [guide/en/acceptance-evidence.md](guide/en/acceptance-evidence.md) | [guide/zh/acceptance-evidence.md](guide/zh/acceptance-evidence.md) |
 | Cross-machine sync | [guide/en/loop.md#cross-machine-sync](guide/en/loop.md#cross-machine-sync) | [guide/zh/loop.md#跨机器同步](guide/zh/loop.md#%E8%B7%A8%E6%9C%BA%E5%99%A8%E5%90%8C%E6%AD%A5) |
 | Remote monitoring (watch loop from a phone via `remote-watch`) | [guide/en/loop.md#remote-monitoring](guide/en/loop.md#remote-monitoring) | [guide/zh/loop.md#远程监控remote-monitoring](guide/zh/loop.md#%E8%BF%9C%E7%A8%8B%E7%9B%91%E6%8E%A7remote-monitoring) |
 | Cycle result eval (`roll loop eval`) | [guide/en/loop.md#cycle-result-eval](guide/en/loop.md#cycle-result-eval) | [guide/zh/loop.md#cycle-结果评分result-eval](guide/zh/loop.md#cycle-%E7%BB%93%E6%9E%9C%E8%AF%84%E5%88%86result-eval) |

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2.604.2"
+VERSION="3.0.0"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1416,6 +1416,13 @@ cmd_setup() {
     esac
   done
 
+  # P1-3.4 (v3 branch): skills/ is a git submodule — populate it for git clones
+  # whose skills/ is still empty. No-op for npm/curl installs (no .gitmodules).
+  if [[ -d "$ROLL_PKG_DIR/.git" ]] && [[ -f "$ROLL_PKG_DIR/.gitmodules" ]] \
+     && [[ -z "$(ls -A "$ROLL_PKG_DIR/skills" 2>/dev/null)" ]]; then
+    ( cd "$ROLL_PKG_DIR" && git submodule update --init --recursive --quiet ) || true
+  fi
+
   # Capture per-step outcomes for the v2 UI render at the end.
   local steps_buf=()
   _record() { steps_buf+=("$1|$2"); }