@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/common/neat-freak/references/verification.md

@@ -1,92 +0,0 @@
-# 证据层级与发布终态
-
-## 风险决定证据深度
-
-| 结论 | 最低证据 |
-|---|---|
-| “文档链接有效” | 项目自己的 doc-link/index check 或逐链接存在性 |
-| “规则已同源” | realpath/readlink/import + 平台实际加载顺序 |
-| “代码实现是 X” | 当前目标分支代码、schema、配置与相关测试 |
-| “PR 已完成” | PR state=merged + merge commit；不能推导已部署 |
-| “已部署” | deploy marker/release 指向目标 commit + 服务 active |
-| “用户已看到新版本” | canonical 用户 URL/API 的真实响应，必要时同时比 origin/cache |
-| “可安全清场” | merged + production contains change + knowledge receipt + lane clean + 无唯一未集成文件 |
-| “已获准清场” | 完整结果已向用户汇报 + 用户在该汇报后明确确认可以清场 + 现场要求的确认凭证 |
-| “整个项目干净” | 项目内所有适用事实面 verified；warning、pending 和 out-of-scope 单列 |
-
-代码直觉、旧 memory、commit message 和 cache-buster URL 都只能当线索，不能单独证明生产终态。
-
-## 真相矩阵
-
-对每个发现至少记录：
-
-```text
-topic: <事实主题>
-authority: <当前权威来源>
-code: verified-current | stale | n/a
-runtime: verified-current | stale | unverified | n/a
-docs: verified-current | stale | changed
-rules: verified-current | stale | changed | n/a
-memory: verified-current | stale | generated-read-only | changed | n/a
-action: <做了什么或为什么没做>
-verification: <命令、页面或门禁>
-```
-
-用户不需要看到完整矩阵，但最终摘要必须保留未闭合状态。
-
-## 发布状态机
-
-```text
-implemented
-  -> locally verified
-  -> pushed / PR opened
-  -> CI + required backtest/visual review passed
-  -> merged
-  -> deployed
-  -> live verified
-  -> knowledge closed + receipt recorded
-  -> full result reported while evidence is preserved
-  -> user explicitly approved cleanup after the report
-  -> workspace cleaned
-  -> post-cleanup audit passed
-  -> cleanup result appended
-```
-
-跳过的状态必须有项目规则允许的原因。失败停在哪一格，就按那一格汇报，不能用“基本完成”覆盖。
-
-## 缓存和多表面产品
-
-当用户可见内容经过 CDN、边缘缓存、搜索索引、异步 worker 或多客户端时，至少识别：
-
-- origin 是否为新内容；
-- canonical URL 是否仍为旧缓存；
-- API/页面/通知/RSS 是否共享同一数据出口；
-- deploy marker 是否在所有异步进程真正切换之后才写；
-- cache-buster 是否只是诊断，而非真实用户验收。
-
-只验证其中一个表面时，在结论里明确限制范围。
-
-## 清场前 gate
-
-清场会销毁复盘和用户复核证据，因此顺序固定为：
-
-1. 验证目标工作已集成并上线；
-2. 同步 docs/rules/获准记忆；
-3. 记录项目要求的 knowledge closeout receipt；
-4. 预览待删除 worktree/branch/db/artifact；
-5. 检查 dirty 文件和 patch equivalence；
-6. 向用户完整汇报结果并保留上述现场；
-7. 等待用户在看完汇报后明确确认可以清场；
-8. 记录项目要求的用户确认凭证并执行授权的清理；
-9. 重新运行 workspace audit，补充汇报清场结果。
-
-用户最初任务中的“收尾并清理”“做完删掉”等预授权不替代第 7 步；确认必须发生在完整汇报之后，因为用户要先看到结果才能判断是否需要保留现场继续复核。
-
-目录名、分支年龄和 agent 会话是否关闭都不能证明可删除。
-
-## 验证失败时
-
-- 同一失败第二次出现，停止盲重试，重新检查假设、环境和命令名。
-- 门禁要求机器可读 metadata 时，补正确留痕并触发新事件；不要用人工确认绕过可修复的格式问题。
-- 失败发生在生产写入前，明确说“尚未影响生产”；发生在切流后，先确认当前 active release 和回滚边界。
-- 任何未验证项保持 `pending`，不要为了摘要好看把它降格成 warning。

package/template/workflows/specdev/common/neat-freak/scripts/audit-inventory.sh

@@ -1,106 +0,0 @@
-#!/usr/bin/env bash
-# Read-only inventory for neat-freak. Prints metadata and paths only; never reads file contents.
-
-set -euo pipefail
-
-usage() {
-  echo "usage: $0 <project-root>" >&2
-  exit 64
-}
-
-[[ $# -eq 1 ]] || usage
-[[ -d "$1" ]] || { echo "[ERR] project root is not a directory: $1" >&2; exit 66; }
-
-PROJECT_ROOT="$(cd "$1" && pwd -P)"
-SEEN_RULE_FILES=$'\n'
-
-section() {
-  printf '\n## %s\n' "$1"
-}
-
-file_size() {
-  local file="$1"
-  local lines bytes
-  lines="$(wc -l < "$file" | tr -d ' ')"
-  bytes="$(wc -c < "$file" | tr -d ' ')"
-  printf '%s\tlines=%s\tbytes=%s\n' "$file" "$lines" "$bytes"
-}
-
-describe_rule_file() {
-  local file="$1"
-  case "$SEEN_RULE_FILES" in
-    *$'\n'"$file"$'\n'*) return ;;
-  esac
-  SEEN_RULE_FILES+="$file"$'\n'
-  if [[ -L "$file" ]]; then
-    local target state
-    target="$(readlink "$file")"
-    if [[ -e "$file" ]]; then state="valid"; else state="broken"; fi
-    printf '%s\tsymlink=%s\tstate=%s\n' "$file" "$target" "$state"
-  elif [[ -f "$file" ]]; then
-    file_size "$file"
-  fi
-}
-
-printf '# neat-freak inventory v2\n'
-printf 'project_root=%s\n' "$PROJECT_ROOT"
-printf 'generated_at=%s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
-
-section "platform-directories"
-# Common agent home dirs; nonexistent ones are skipped silently.
-for dir in "$HOME/.claude" "$HOME/.codex" "$HOME/.cursor" "$HOME/.gemini" \
-  "$HOME/.qoder" "$HOME/.trae" "$HOME/.iflow" "$HOME/.codebuddy"; do
-  [[ -d "$dir" ]] && printf '%s\n' "$dir"
-done
-
-section "other-agent-rule-artifacts"
-# Platform-specific rule forms at the project root (existence only).
-for rel in .cursorrules .windsurfrules .cursor/rules .qoder .trae .iflow; do
-  [[ -e "$PROJECT_ROOT/$rel" ]] && printf '%s\n' "$PROJECT_ROOT/$rel"
-done
-true
-
-section "git"
-if git -C "$PROJECT_ROOT" rev-parse --show-toplevel >/dev/null 2>&1; then
-  GIT_ROOT="$(git -C "$PROJECT_ROOT" rev-parse --show-toplevel)"
-  printf 'git_root=%s\n' "$GIT_ROOT"
-  printf 'branch=%s\n' "$(git -C "$PROJECT_ROOT" branch --show-current 2>/dev/null || true)"
-  printf 'head=%s\n' "$(git -C "$PROJECT_ROOT" rev-parse HEAD)"
-  printf 'status_entries=%s\n' "$(git -C "$PROJECT_ROOT" status --porcelain=v1 | wc -l | tr -d ' ')"
-  printf 'worktrees=%s\n' "$(git -C "$PROJECT_ROOT" worktree list --porcelain | awk '$1 == "worktree" {n++} END {print n+0}')"
-else
-  printf 'git_root=none\n'
-fi
-
-section "rule-chain-candidates"
-cursor="$PROJECT_ROOT"
-while :; do
-  for rel in AGENTS.override.md AGENTS.md CLAUDE.md CLAUDE.local.md .claude/CLAUDE.md; do
-    describe_rule_file "$cursor/$rel"
-  done
-  [[ "$cursor" == "/" ]] && break
-  parent="$(dirname "$cursor")"
-  [[ "$parent" == "$cursor" ]] && break
-  cursor="$parent"
-done
-for file in \
-  "$HOME/.codex/AGENTS.override.md" \
-  "$HOME/.codex/AGENTS.md" \
-  "$HOME/.claude/CLAUDE.md"; do
-  describe_rule_file "$file"
-done
-
-section "project-markdown"
-find "$PROJECT_ROOT" \
-  \( -name .git -o -name node_modules -o -name .next -o -name dist -o -name build -o -name .venv -o -name venv -o -name __pycache__ -o -name target -o -name vendor -o -name .turbo -o -name .cache \) -prune \
-  -o -type f \( -name '*.md' -o -name '*.mdx' \) -print \
-  | LC_ALL=C sort
-
-section "project-markdown-count"
-find "$PROJECT_ROOT" \
-  \( -name .git -o -name node_modules -o -name .next -o -name dist -o -name build -o -name .venv -o -name venv -o -name __pycache__ -o -name target -o -name vendor -o -name .turbo -o -name .cache \) -prune \
-  -o -type f \( -name '*.md' -o -name '*.mdx' \) -print \
-  | awk 'END {print NR+0}'
-
-section "root-entries"
-find "$PROJECT_ROOT" -mindepth 1 -maxdepth 1 -print | LC_ALL=C sort

package/template/workflows/specdev/common/prototype/LOGIC.md

@@ -1,89 +0,0 @@
-# 逻辑原型
-
-构建一个微小的交互式终端应用，让用户手动驱动状态模型。当问题涉及**业务逻辑、状态转换或数据形态**时使用——这类问题在纸面上看起来合理，但只有推进真实用例后才会暴露出不对劲的地方。
-
-## 适用场景
-
-- "我不确定这个状态机能否处理先 X 后 Y 的边界情况。"
-- "这个数据模型真的能表示那种情况吗……"
-- "我想在写之前先感受一下 API 应该长什么样。"
-- 任何用户想要**按按钮、观察状态变化**的场景。
-
-如果问题是"这个应该长什么样"——选错了分支。用 [UI.md](UI.md)。
-
-## 流程
-
-### 1. 陈述问题
-
-在写代码之前，写下你正在为哪个状态模型和哪个问题做原型。一段话即可，放在原型的 README 或文件顶部的注释中。回答了错误问题的逻辑原型是纯粹浪费——让问题显式化，这样之后可以核查，无论用户是现在看着还是稍后 AFK 回来再看。
-
-### 2. 选择语言
-
-使用宿主项目所用的语言。如果项目没有明显的运行时（如文档仓库），则询问。
-
-遵循项目已有的工具链约定——不要仅为原型引入新的包管理器或运行时。
-
-### 3. 将逻辑隔离到一个可移植模块中
-
-将实际逻辑——回答问题的部分——放在一个小巧、纯净的接口后面，使其之后可以被提取并放入正式代码库。围绕它的 TUI 是一次性的；逻辑模块不应该是一次性的。
-
-正确的形态取决于问题：
-
-- **纯 reducer**——`(state, action) => state`。适用于动作为离散事件且状态为单一值的场景。
-- **状态机**——显式的状态和转换。适用于"当前哪些操作是合法的"本身就是问题的一部分。
-- **一组纯函数**操作一个纯数据类型。适用于没有隐式当前状态、只有转换的场景。
-- **类或模块**——具有清晰方法接口，当逻辑确实拥有持续性内部状态时使用。
-
-选择最适合所问问题的形态，而*不是*最容易接入 TUI 的形态。保持纯净：无 I/O、无终端代码、无用于控制流的 `console.log`。TUI 导入它并调用它；反向不传递任何内容。
-
-这就是让原型在自身生命周期之后仍有价值的关键：当问题得到回答后，验证通过的 reducer / 状态机 / 函数集可以被单独提升到正式模块中。
-
-### 4. 构建最小的 TUI 来暴露状态
-
-将其构建为**轻量 TUI**——每次 tick 清屏（`console.clear()` / `print("\033[2J\033[H")` / 等价方式）并重新渲染整个帧。用户应始终看到一个稳定视图，而非不断增长的滚动回溯。
-
-每帧包含两部分，顺序如下：
-
-1. **当前状态**，pretty-print 且 diff 友好（每行一个字段，或格式化 JSON）。使用**粗体**标注字段名或节标题，**暗色**标注次要上下文（时间戳、ID、派生值）。原生 ANSI 转义码即可——`\x1b[1m` 粗体、`\x1b[2m` 暗色、`\x1b[0m` 重置。无需引入样式库，除非项目中已经存在。
-2. **键盘快捷键**，列在底部：`[a] 添加用户  [d] 删除用户  [t] 推动时钟  [q] 退出`。粗体标键、暗色标描述，或反过来——怎么读起来清晰怎么来。
-
-行为：
-
-1. **初始化状态**——单个内存中的对象/结构体。启动时渲染第一帧。
-2. **每次读取一次按键（或一行）**，分发到修改状态的处理器。
-3. **每次操作后重新渲染**完整帧——不追加，而是替换。
-4. **循环直到退出。**
-
-整个帧应适配一屏。
-
-### 5. 一条命令即可运行
-
-向项目已有任务运行器添加一条脚本（`package.json` scripts、`Makefile`、`justfile`、`pyproject.toml`）。用户应运行 `pnpm run <原型名称>` 或等价命令——永远不需要记住路径。
-
-如果宿主项目没有任务运行器，直接把命令写在原型 README 的顶部。
-
-### 6. 交付
-
-给用户运行命令。他们会自己驱动它；有趣的时刻是他们说"等等，那不应该可能"或"嗯，我以为 X 会不一样"——那些是_想法_中的 bug，这正是整个原型的目的。如果他们想添加新操作，就添加。原型会演化。
-
-### 7. 捕获答案并持久化
-
-原型回答问题后，按 [SKILL](SKILL.md) 中持久化约定的方式捕获答案：
-
-1. **提升验证过的逻辑**：将验证通过的 reducer / 状态机 / 函数集提升到正式模块中（决策已被吸收）。
-2. **持久化答案记录**：在 `<Path>{roots.state}/<workflow>/changes/{change}/prototype/logic-<topic>.md</Path>` 创建答案文件，记录：
-   - 所回答的问题
-   - 结论——什么可行、什么不可行
-   - 被验证的逻辑模块的描述
-   - throwaway 分支指针（TUI 外壳代码所在位置）
-3. **更新索引**：将新答案追加到 `prototype/index.md` 表格中。
-
-TUI 外壳代码仍提交到 throwaway 分支——它是一次性的交互壳，真正有价值的部分（逻辑模块）已经提升到正式代码中。
-
-## 反模式
-
-- **不要加测试。** 需要测试的原型不再是原型。
-- **不要接入真实数据库。** 使用内存存储，除非问题本身就是关于持久化的。
-- **不要泛化。** 不要"如果我们以后想支持 X 呢"。原型只回答一个问题。
-- **不要把逻辑和 TUI 混在一起。** 如果 reducer / 状态机引用了 `console.log`、提示符或终端转义码，它就不可移植了。让 TUI 成为纯模块外面的薄壳。
-- **不要把 TUI 外壳发布到生产环境。** 外壳是为在终端中手动驱动而优化的。背后的逻辑模块才是值得保留的部分。

package/template/workflows/specdev/common/prototype/SKILL.md

@@ -1,78 +0,0 @@
----
-name: prototype
-description: 构建一个一次性原型来回答设计问题。当用户想要快速验证某个状态模型或逻辑是否正确，或探索 UI 应该长什么样时使用。
----
-
-# 原型
-
-原型是**回答问题的 disposable 代码**。问题决定形态。
-
-## 选择分支
-
-确定正在回答哪个问题——从用户的提示、周围代码中推断，或用户在场时直接询问：
-
-- **"这个逻辑 / 状态模型对吗？"** → [LOGIC.md](LOGIC.md)。构建一个微小的交互式终端应用，推动状态机经过那些在纸面上难以推理的用例。
-- **"这个应该长什么样？"** → [UI.md](UI.md)。在单个路由上生成几个截然不同的 UI 变体，通过 URL 查询参数和底部浮动栏切换。
-
-两条分支产生的产物截然不同——选错会浪费整个原型。如果问题确实模糊且无法联系用户，默认选择与周围代码更匹配的分支（后端模块 → logic；页面或组件 → UI），并在原型顶部声明假设。
-
-## 通用规则
-
-1. **从第一天起就是 disposable，并明确标注。** 将原型代码放在离实际使用位置近的地方（紧邻它正在为哪个模块或页面做原型），这样上下文一目了然——但命名要让随便一个读者都能看出这是原型而非生产代码。对于 disposable UI 路由，遵循项目已有的路由约定，不要发明新的顶层结构。
-2. **一条命令即可运行。** 使用项目已有任务运行器支持的方式——`pnpm <名称>`、`python <路径>`、`bun <路径>` 等。用户必须能不加思考就启动它。
-3. **默认无持久化。** 状态存在于内存中。持久化是原型正在_检查_的东西，而非原型应该依赖的东西。如果问题明确涉及数据库，用一个临时库或本地文件，名称要清楚标注"PROTOTYPE — 可随时清除"。
-4. **跳过打磨。** 不写测试，不做超出让原型_可运行_范围的错误处理，不建抽象。目的是快速学习。
-5. **展示状态。** 每次操作后（logic）或每次变体切换时（UI），打印或渲染完整的相关状态，让用户能看到什么发生了变化。
-6. **完成后捕获结论。** 将验证通过的决策融入正式代码。然后将答案和结论持久化到变更目录：
-   - 在 `<Path>{roots.state}/<workflow>/changes/{change}/prototype/</Path>` 下创建答案文件
-   - 维护 `prototype/index.md` 索引表
-   - 原型代码本身仍为一次性代码：提交到 throwaway 分支，保持脱离主分支。答案文件中记录该分支的引用指针
-   - 具体持久化规范见下方「持久化约定」章节
-
-## 持久化约定
-
-### 产物位置
-
-原型答案写入当前 change 目录下的 `prototype/` 子目录：
-
-```
-<Path>{roots.state}/<workflow>/changes/{change}/prototype/<type>-<topic>.md</Path>
-```
-
-- `<type>` 为 `logic` 或 `ui`，对应原型分支类型
-- `<topic>` 为 kebab-case 主题名，概括原型所回答的问题，如 `auth-state-machine.md`、`settings-page-layout.md`
-- `<workflow>` 为当前 workflow 目录名（如 `specdev`）
-- `<change>` 为当前活跃变更目录名（格式 `<YYYY-MM-DD>-<topic>`，从 `<Path>{roots.state}/<workflow>/status.json</Path>` 的 `active` 数组中获取）
-
-### 答案文件内容
-
-每个答案文件包含以下信息：
-
-- **问题**：原型所回答的具体问题
-- **结论**：验证后的结论——什么可行、什么不可行、为什么
-- **验证内容**（仅 logic 原型）：被验证的 reducer / 状态机 / 函数集的描述
-- **UI 评估记录**（仅 UI 原型）：哪个变体胜出及原因、各变体的结构差异分析、从落选变体中提取的有价值元素
-- **原型代码引用**：throwaway 分支名称，指向原型代码所在的 git 分支
-
-### 维护 prototype/index.md
-
-在 `prototype/` 目录下维护一个索引文件 `<Path>{roots.state}/<workflow>/changes/{change}/prototype/index.md</Path>`，仅包含一张表格：
-
-| 类型 | 文件 | 问题概述 | 结论摘要 |
-|------|------|---------|---------|
-| logic | `auth-state-machine.md` | 认证状态机能否正确处理 token 过期 + 并发刷新 | 可行；需增加 TOKEN_EXPIRED 中间态 |
-| ui | `settings-layout.md` | 设置页三种布局方案对比 | B 方案（侧边栏布局）胜出；吸收 C 的面包屑导航 |
-
-- 表格四列：类型（`logic` / `ui`）、文件（`prototype/` 下的相对路径）、问题概述（一句话概括）、结论摘要（一句话概括结论）
-- 每次新增答案文件后，向表格追加一行
-- `index.md` 除表格外无需其它内容
-
-### 去重与增量更新
-
-在开始新原型之前：
-
-1. 先读取 `<Path>{roots.state}/<workflow>/changes/{change}/prototype/index.md</Path>`，检查是否已有同名或高度相关的原型记录
-2. 如已存在对应 `.md` 文件，先读取其完整内容
-3. 如现有结论已覆盖当前问题，直接引用，无需重复原型
-4. 如需更新（新发现补充、结论修正），在原文件基础上增删改，并同步更新 `index.md` 中对应行的概述
-5. 如需回答全新问题，创建新文件并追加到 `index.md` 表格

package/template/workflows/specdev/common/prototype/UI.md

@@ -1,120 +0,0 @@
-# UI 原型
-
-在单个路由上生成**几个截然不同的 UI 变体**，通过底部浮动栏切换。用户在浏览器中翻看变体，选一个（或从每个中偷一些元素），然后丢弃其余。
-
-如果问题是关于逻辑/状态而非界面外观——选错了分支。用 [LOGIC.md](LOGIC.md)。
-
-## 适用场景
-
-- "这个页面应该长什么样？"
-- "我想在提交之前看几个仪表盘方案。"
-- "给设置页试一种不同的布局。"
-- 任何用户本来会在脑子里花一天时间在三个模糊线框图之间犹豫不决的场景。
-
-## 两种子形态 —— 强烈偏好子形态 A
-
-UI 原型在**与应用的其余部分产生摩擦**时才最容易评判——真实的 header、真实的 sidebar、真实的数据、真实的信息密度。单独的一次性路由是真空：每个变体在隔离状态下看起来都不错。只要有合理的现有页面可以承载变体，就默认使用子形态 A。只有当原型确实没有邻近的宿主时才使用子形态 B。
-
-### 子形态 A — 调整现有页面（首选）
-
-路由已存在。变体在**同一路由**上渲染，通过 `?variant=` URL 查询参数控制。现有的数据获取、参数和认证全部保留——只替换渲染部分。这是默认选项；除非有明确的理由不这样做，否则选它。
-
-如果原型针对的东西还没有页面，但*自然地应该存在于某个页面内部*（仪表盘的新区域、设置页的新卡片、现有流程中的新步骤）——这仍然是子形态 A。将变体挂载在宿主页面内部。
-
-### 子形态 B — 新建页面（最后手段）
-
-仅当被原型化的事物确实没有现成页面可以嵌入时使用——例如一个全新的顶层界面，或一个无法合理嵌入任何地方的流程。
-
-按照项目已有的路由约定创建一个**一次性路由**——不要发明新的顶层结构。命名要让人一眼看出是原型（例如在路径或文件名中包含 `prototype` 字样）。同样使用 `?variant=` 模式。
-
-在提交子形态 B 之前，做一个合理性检查：真的没有现成页面可以嵌入吗？空路由会隐藏有内容的页面能够暴露的设计问题。
-
-两种子形态下，底部浮动栏完全相同。
-
-## 流程
-
-### 1. 陈述问题并确定变体数量 N
-
-默认 **3 个变体**。超过 5 个就不再是截然不同，而是噪音——以此为上限。
-
-将计划写在一行内，放在原型所在位置或文件顶部注释中：
-
-> "设置页的三个变体，通过 `?variant=` 切换，在现有 `/settings` 路由上。"
-
-无论用户是否在场反对，这都能成立。
-
-### 2. 生成截然不同的变体
-
-起草每个变体。每个变体必须满足：
-
-- 页面的目的和它能访问的数据。
-- 项目的组件库 / 样式系统（TailwindCSS、shadcn、MUI、纯 CSS，等等）。
-- 清晰的导出组件名，例如 `VariantA`、`VariantB`、`VariantC`。
-
-变体必须在**结构上不同**——不同的布局、不同的信息层次、不同的主要操作入口，而不仅仅是不同的颜色。三个微调过的卡片网格不是 UI 原型，是壁纸。如果两份草稿太相似，用明确的"不要用卡片网格"指引重做其中一个。
-
-### 3. 将它们串接起来
-
-在路由上创建一个单一的切换器组件：
-
-```tsx
-// 伪代码 —— 根据项目框架调整
-const variant = searchParams.get('variant') ?? 'A';
-return (
-  <>
-    {variant === 'A' && <VariantA {...data} />}
-    {variant === 'B' && <VariantB {...data} />}
-    {variant === 'C' && <VariantC {...data} />}
-    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
-  </>
-);
-```
-
-对于子形态 A（现有页面）：将现有数据获取保持在切换器上方；每个变体只替换渲染的子树。
-
-对于子形态 B（新建页面）：`/prototype/<名称>` 下的一次性路由挂载同一个切换器。
-
-### 4. 构建浮动切换器
-
-一个位于屏幕底部中央的固定定位小栏，包含三个元素：
-
-- **左箭头**——切换到上一个变体（循环）。
-- **变体标签**——显示当前变体标识，如果变体导出了名称，也显示名称。例如 `B — 侧边栏布局`。
-- **右箭头**——切换到下一个（循环）。
-
-行为：
-
-- 点击箭头更新 URL 查询参数（使用框架的路由器——Next 上用 `router.replace`、React Router 上用 `navigate`，等等），使变体可分享且在刷新后保持。
-- 键盘：`←` 和 `→` 方向键也可切换。当 `<input>`、`<textarea>` 或 `[contenteditable]` 元素聚焦时不要拦截方向键。
-- 在视觉上与页面区分（如高对比度胶囊形、微妙阴影），使其明显不是被评估的设计的一部分。
-- 在生产构建中隐藏——通过 `process.env.NODE_ENV !== 'production'` 或等价检查进行门控，这样即使原型不小心合入也不会把切换器发布给用户。
-
-将切换器放在一个共享组件中，供两种子形态复用。放置在项目中共享 UI 组件的通常位置。
-
-### 5. 交付
-
-给出 URL（以及 `?variant=` 的各个键值）。用户会在有空时翻看。最有趣的反馈通常是**"我想要 B 方案的头和 C 方案的侧边栏"**——那才是他们真正想要的设计。
-
-### 6. 捕获答案并清理
-
-一旦某个变体胜出，按 [SKILL](SKILL.md) 中持久化约定的方式捕获答案：
-
-1. **融入正式代码**：
-   - **子形态 A** — 将胜出变体融入现有页面；从主分支移除落选变体和切换器。
-   - **子形态 B** — 将胜出变体提升为正式路由；从主分支移除一次性路由和切换器。
-2. **持久化评估记录**：在 `<Path>{roots.state}/<workflow>/changes/{change}/prototype/ui-<topic>.md</Path>` 创建答案文件，记录：
-   - 所回答的 UI 问题
-   - 哪个变体胜出及原因——完整的评估推理
-   - 各变体的结构差异分析
-   - 从落选变体中提取的有价值元素（如果适用）
-   - throwaway 分支指针
-3. **UI 规范沉淀**：将评估过程中产生的 UI 规范洞察（如布局原则、信息层次、交互模式选择理由）写入答案文件，供后续 spec 编写引用。
-4. **清理原型代码**：将完整变体集（包括落选变体和切换器）提交到 throwaway 分支，不进入主分支。变体组件和切换器留在主分支会快速腐烂并误导后续读者。
-5. **更新索引**：将新答案追加到 `prototype/index.md` 表格中。
-
-## 反模式
-
-- **变体仅颜色或文案不同。** 那是微调，不是原型。真正的变体在结构上存在分歧。
-- **变体之间共享过多代码。** 共享一个 `<Header>` 没问题；共享一个 `<Layout>` 就失去了意义。每个变体应该能够自由地抛弃布局。
-- **将变体接入真实的数据变更。** 只读原型完全没问题。如果变体需要变更数据，将其指向一个桩——问题是"这个应该长什么样"，不是"后端是否正常工作"。
-- **将原型直接提升到生产环境。** 变体代码是在原型约束下编写的（无测试、最小错误处理）。融入时要正确重写。

package/template/workflows/specdev/common/research/SKILL.md

@@ -1,54 +0,0 @@
----
-name: research
-description: "针对高可信度一手来源调查问题，并将发现结果以 Markdown 文件持久化到变更目录的 research/ 子目录中。适用于需要研究某个主题、收集文档或 API 信息、或委托阅读工作给后台 Agent 的场景。"
----
-
-启动一个**后台 Agent** 来进行研究，这样你可以在它阅读时继续工作。
-
-其工作内容：
-
-1. 针对**一手来源**调查问题 —— 官方文档、源代码、规范、第一方 API —— 而不是基于这些来源的二次编写材料。将每个声明追溯到拥有该声明的来源。
-2. 将发现结果写入单个 Markdown 文件，为每个声明标注来源。
-3. 将文件持久化到当前变更目录的 `research/` 子目录中，并维护同目录下的 `index.md` 索引。
-
-## 持久化约定
-
-### 产物位置
-
-研究产物写入当前 change 目录下的 `research/` 子目录：
-
-```
-<Path>{roots.state}/<workflow>/changes/{change}/research/<research_topic_name>.md</Path>
-```
-
-- `<research_topic_name>` 为 kebab-case，如 `react-19-upgrade-guide.md`、`prisma-v6-migration.md`
-- `<workflow>` 为当前 workflow 目录名（如 `specdev`）
-- `<change>` 为当前活跃变更目录名（格式 `<YYYY-MM-DD>-<topic>`，从 `<Path>{roots.state}/<workflow>/status.json</Path>` 的 `active` 数组中获取）
-
-### 维护 research/index.md
-
-在 `research/` 目录下维护一个索引文件 `<Path>{roots.state}/<workflow>/changes/{change}/research/index.md</Path>`，仅包含一张表格：
-
-| 文件 | 概述 |
-|------|------|
-| `react-19-upgrade-guide.md` | React 19 升级要点、breaking changes、迁移路径 |
-| `prisma-v6-changes.md` | Prisma v6 新增 API、废弃项、性能改进 |
-
-- 表格两列：文件（`research/` 下的相对路径）、概述（一句话概括研究主题和关键发现）
-- 每次新增 research 文件后，向表格追加一行
-- 每次修改 research 文件后，检查对应概述是否仍准确，必要时更新
-- `index.md` 除表格外无需其它内容
-
-### 去重与增量更新
-
-在开始新研究之前：
-
-1. 先读取 `<Path>{roots.state}/<workflow>/changes/{change}/research/index.md</Path>`，检查是否已有同名或高度相关的 research topic
-2. 如已存在对应 `.md` 文件，先读取其完整内容
-3. 如现有内容已满足当前需求，直接引用，无需重新研究
-4. 如现有内容不满足需求（信息过时、覆盖不全、结论有误），在原文件基础上进行增删改：
-   - **增**：补充新的发现、新增来源、追加未覆盖的子主题
-   - **删**：删除已被证伪的结论、过时的信息
-   - **改**：修正错误结论、更新版本号/API 签名
-   - 修改后同步更新 `index.md` 中对应行的概述
-5. 如需研究的是全新 topic，创建新文件并追加到 `index.md` 表格

package/template/workflows/specdev/common/resolving-merge-conflicts/SKILL.md

@@ -1,14 +0,0 @@
----
-name: resolving-merge-conflicts
-description: "用于解决进行中的 git merge/rebase 冲突。"
----
-
-1. **查看 merge/rebase 的当前状态**。检查 git 历史记录和冲突文件。
-
-2. **查找每个冲突的一手来源**。深入理解每个更改的原因以及原始意图。阅读 commit 消息、检查 PR、查看原始 issue/ticket。
-
-3. **解决每个冲突块。** 尽可能保留双方的意图。当不兼容时，选择与合并既定目标一致的一方，并注明权衡。**不要**发明新行为。务必解决；绝不执行 `--abort`。
-
-4. 查找项目的**自动化检查**并运行它们 —— 通常按类型检查、测试、格式化的顺序。修复合并破坏的任何内容。
-
-5. **完成 merge/rebase。** 暂存所有内容并提交。如果是 rebase，继续 rebase 过程直到所有 commits 都已 rebase。

package/template/workflows/specdev/common/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# 人在回路（Human-in-the-loop）重现循环。
-# 复制此文件，编辑下面的步骤，然后运行它。
-# Agent 运行脚本；用户在其终端中按照提示操作。
-#
-# 用法：
-#   bash hitl-loop.template.sh
-#
-# 两个辅助函数：
-#   step "<指令>"          → 显示指令，等待按 Enter
-#   capture VAR "<问题>"   → 显示问题，读取响应到 VAR
-#
-# 结束时，捕获的值以 KEY=VALUE 格式打印，供 agent 解析。
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- 在下方编辑 ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- 在上方编辑 ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"