@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/P-prototype/generate-design-package.md

@@ -1,50 +0,0 @@
-# Generate Design Package
-
-在候选已形成后使用。设计系统主文档是源；HTML/CSS/JS 是可运行投影，不能成为第二套未记录规则。
-
-## 1. 生成候选页面
-
-为每个候选创建 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/variants/{style-id}.html</Path>`。每页使用相同真实任务、数据和状态，差异集中在 shell、信息层级、操作入口、密度、token 与跨端策略。页面必须离线运行，不引用 CDN、远程字体或远程图片；可从 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/assets/</Path>` 复制已归属的本地资产。
-
-每页至少展示默认、hover/focus、selected、loading、empty/error 中与任务相关的状态，并包含浅/深主题或明确说明为何只有单主题。图标按钮使用项目已有图标库；新项目可复制 design library 内的 Lucide 资产。
-
-**完成标准**：2-4 个候选各有独立 HTML，使用同一任务语义，页面差异不只是颜色。
-
-## 2. 生成 comparison 索引
-
-`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/index.html</Path>` 提供候选名称、适合原因、关键 token、迁移成本、拒绝风险和打开入口。桌面并排或分栏比较；窄屏改为顺序浏览，不把预览压成不可读小窗。索引只帮助比较，不在用户选择前偷偷设置赢家。
-
-**完成标准**：所有候选均可从索引到达，返回路径明确，键盘可操作，390px 与 1440px 均无意外溢出。
-
-## 3. 写入最终源码
-
-用户确认后，在设计系统主文档的 `Prototype Sources` 中写入且只写入以下具名块：
-
-````text
-<!-- PROTOTYPE-FILE: final/index.html -->
-```html
-...
-```
-<!-- /PROTOTYPE-FILE -->
-````
-
-CSS 与 JS 分别使用约定的 final 目标。源码不得包含占位符、生产 secret、生产写操作或无法离线取得的依赖。HTML 必须使用相对引用连接物化后的 CSS 与 JS。
-
-**完成标准**：三个块路径唯一、语言正确、代码完整，Markdown 单独阅读即可理解全部实现。
-
-## 4. 物化与校验
-
-运行：
-
-```bash
-node <Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> \
-  <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>
-
-node <Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> \
-  --check \
-  <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>
-```
-
-随后运行局部 validator、项目可用的 HTML/CSS/JS 检查和浏览器视口检查，把命令、退出码、关键输出与截图相对路径写入 `Validation and Handoff`。
-
-**完成标准**：物化二次运行无 diff；最终页面离线可用；所有验收项有证据而不是口头断言。

package/template/workflows/specdev/P-prototype/logic-protocol.md

@@ -1,11 +0,0 @@
-# 逻辑原型
-
-用于验证状态、算法、规则和交互因果。先读取 <Path>{roots.workflows}/specdev/P-prototype/logic-template.md</Path>。P 拥有 <Path>{roots.state}/specdev/changes/{change}/prototypes/LOGIC-NNN/</Path>，ID 最小未用；不修改生产代码或创建 branch/worktree。
-
-1. 选择当前问题的最小纯逻辑，明确初始状态、输入、状态转换、不变量、非法输入及希望验证的决定；有缺口先返回 G。
-2. 写 logic.md 作为决定和证据记录；生成 index.html，所有 CSS/JS 内联，无远程字体、CDN、网络调用或外部文件依赖。使用内存状态，reset 回到同一初始状态。
-3. 提供可见状态、自由操作、带解释的引导场景与 reset；场景包括正常、边界和非法输入。不要用动画或精美 UI 替代规则反馈。
-4. 在实际浏览器离线验证上述场景，记录观察和失败；静态脚本校验不能冒充浏览器观察。通过后 status=ready、verification=passed，保存 SHA-256 摘要。
-5. 运行 SpecDev --stage prototype，返回产物与已确认/未确认决定，路由 G/S/T。网页只是原型，不能自动复制为生产实现或把模拟结果当作后端真实行为。
-
-记录按 <Path>{roots.workflows}/specdev/common/schemas/logic-prototype.schema.json</Path> 校验。不能运行浏览器时保持 draft/blocked，报告可运行文件与未验证项。

package/template/workflows/specdev/P-prototype/project-preview-protocol.md

@@ -1,9 +0,0 @@
-# 显式项目内 UI 预览
-
-仅在用户明确要求项目内预览时加载；默认仍是离线持久化 UI 包，候选默认 3、最多 4，不改变 design-system.md 权威。
-
-记录项目路由/启动命令、允许的临时文件写集、现有未提交改动和清理方案。用当前项目真实组件与布局环境，加隔离 mock/stub 阻断生产写入；不连接真实付款、发信或数据变更服务。使用 ?variant= 或项目等价参数切换方案，可加底部切换器；快捷键不能劫持输入框、编辑区或浏览器功能。
-
-每个候选决定与项目相对证据回写 design-system.md。验证相同任务、viewport、状态与交互，用户选定后仍生成离线 comparison/final 并通过原有两个局部校验器。临时预览不是另一权威源。
-
-只清理本次明确拥有且内容未漂移的临时修改，保留原有用户内容；发现 owner/内容冲突时停止该清理并记录剩余写集。清理完成或明确 handoff 后才能把项目预览分支标完成。不自动创建分支、提交、推送或删除 worktree。

package/template/workflows/specdev/P-prototype/style-selection-protocol.md

@@ -1,41 +0,0 @@
-# Style Selection Protocol
-
-在检测完成并已生成 2-4 个功能候选后使用。每轮只关闭一个决策层，每次回答立即写入设计系统主文档；已确认内容不重复询问。
-
-## 决策顺序
-
-1. **产品与平台**：确认主用户、最高频任务、桌面/Web/移动优先级及是否真正跨端。
-2. **信息架构**：从全局侧栏、双层导航、列表-详情、画布/检查器、仪表盘网格、内容中心中选择 shell 或明确组合。
-3. **密度与排版**：选择 Compact、Default、Comfortable 或 Touch，并确认 UI/正文/代码字体角色。
-4. **色调与主题**：选择暖中性、冷中性、单色、品牌强调或媒体深色；确认 light、dark、system 或 both。
-5. **形状与层级**：确认主圆角组、边框/表面/阴影职责、常驻区与浮层差异。
-6. **交互与运动**：确认点击、异步、危险操作、拖动、键盘、触屏和 reduced-motion 行为。
-7. **跨端重排**：确认侧栏、检查器、表格、工具栏、hover 工具在窄屏的任务级替代。
-8. **可视收束**：打开 comparison，选择一个候选、拒绝其余候选，或明确哪些区域组合；不得只说“更现代”。
-
-## 候选说明合同
-
-每个候选必须包含：风格 id、适用任务、布局变化、token 摘要、三项关键交互、平台策略、现有 UI 的保留/调整/替换项、研究项目、迁移成本和不适用风险。候选必须在信息层级或操作入口上有结构差异，不能只是颜色与文案变化。
-
-候选数读取 `<Path>{roots.state}/specdev/config.json</Path>` 的 `planning.ui_design_default_candidates` 与 `planning.ui_design_max_candidates`，两者必须落在 2-4。事实只支持两个方向时可以少于默认值；达到配置上限前也不得为了凑数引入不适合产品的风格。
-
-## 八种风格路由
-
-| 风格 | 首选任务 | 避免场景 |
-|---|---|---|
-| dense-ide | 数据库、API、日志、专业开发工具 | 低频消费级表单 |
-| monochrome-console | Agent 管理、本地控制台、运行监控 | 品牌内容与媒体浏览 |
-| soft-personal-ai | 个人 AI、轻量桌面助手 | 极端数据密度和大表格 |
-| responsive-web | 自托管 Web、PWA、多设备访问 | 强原生手势为核心的移动产品 |
-| mobile-supervisor | 审批、通知、远程监督 | 手机内完整复刻 IDE |
-| cross-platform-workspace | 桌面/Web/移动 Agent 工作区 | 只需单页面内容展示 |
-| local-first-content | 笔记、知识库、长内容 | 监控大盘和媒体墙 |
-| media-first | 相册、视频、资产库 | 长表单和密集代码任务 |
-
-需要 CRM、仪表盘、画布、客服、通信或 API 分窗时，读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/product-pattern-index.md</Path>`，将产品布局模式与最接近的视觉风格组合，并记录组合边界。
-
-## 持久化与阻塞
-
-每轮更新 frontmatter、`Style Decision` 中的选择表和拒绝理由，再原子重读。用户尚未看到候选 HTML、回答含糊或多个方向仍会改变核心布局时保持 `status: selecting`。用户不在线时可以继续补充可发现证据和生成候选，但不得替用户选择最终风格。
-
-**完成标准**：八层决策均为 confirmed 或明确 not-applicable；被拒绝候选有原因，组合候选有逐区域边界，最终方向能直接生成 token 与页面。

package/template/workflows/specdev/P-prototype/tools/validate-design-package.mjs

@@ -1,155 +0,0 @@
-#!/usr/bin/env node
-
-import { lstat, readdir, readFile, stat } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import { extractPrototypeSources, materialize } from "./materialize-prototype.mjs";
-
-const REQUIRED_HEADINGS = [
-  "## Project Evidence",
-  "## Style Decision",
-  "## Foundation Tokens",
-  "## Component and State Contract",
-  "## Interaction Contract",
-  "## Responsive Contract",
-  "## Prototype Sources",
-  "## Validation and Handoff",
-];
-
-function frontmatterValue(header, key) {
-  const match = header.match(new RegExp(`^${key}:\\s*(.*?)\\s*$`, "m"));
-  if (!match) return undefined;
-  const value = match[1].trim();
-  if (value === "null") return null;
-  if (/^\d+$/.test(value)) return Number(value);
-  return value.replace(/^['"]|['"]$/g, "");
-}
-
-function frontmatterArray(header, key) {
-  const value = frontmatterValue(header, key);
-  if (typeof value !== "string" || !value.startsWith("[") || !value.endsWith("]")) return [];
-  return value.slice(1, -1).split(",").map((item) => item.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
-}
-
-async function isFile(path) {
-  try {
-    return (await stat(path)).isFile();
-  } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-async function isSymlink(path) {
-  try {
-    return (await lstat(path)).isSymbolicLink();
-  } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-async function validate(path, { allowDraft = false } = {}) {
-  const designPath = resolve(path);
-  if (await isSymlink(designPath)) throw new Error("design-system.md must not be a symlink");
-  const markdown = await readFile(designPath, "utf8");
-  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-  const errors = [];
-  if (!match) throw new Error("design-system.md requires YAML frontmatter");
-  const [, header, body] = match;
-  const meta = {
-    schemaVersion: frontmatterValue(header, "schema_version"),
-    artifact: frontmatterValue(header, "artifact"),
-    change: frontmatterValue(header, "change"),
-    designId: frontmatterValue(header, "design_id"),
-    status: frontmatterValue(header, "status"),
-    projectKind: frontmatterValue(header, "project_kind"),
-    platforms: frontmatterArray(header, "platforms"),
-    candidates: frontmatterArray(header, "style_candidates"),
-    selectedStyle: frontmatterValue(header, "selected_style"),
-    density: frontmatterValue(header, "density"),
-    colorMode: frontmatterValue(header, "color_mode"),
-    researchSnapshot: frontmatterValue(header, "research_snapshot"),
-    prototypeFiles: frontmatterArray(header, "prototype_files"),
-    updatedAt: frontmatterValue(header, "updated_at"),
-  };
-
-  const designRoot = dirname(designPath);
-  const expectedDesignId = basename(designRoot);
-  const expectedChange = basename(dirname(dirname(designRoot)));
-  if (meta.schemaVersion !== 2 || meta.artifact !== "ui-design-system") errors.push("artifact/schema_version must be ui-design-system/2");
-  if (!/^UI-\d{3,}$/.test(String(meta.designId ?? "")) || meta.designId !== expectedDesignId) errors.push("design_id must match the UI-NNN directory");
-  if (meta.change !== expectedChange) errors.push("change must match the owning change directory");
-  if (!new Set(["detecting", "selecting", "ready", "blocked"]).has(meta.status)) errors.push("invalid design status");
-  if (!new Set(["existing", "new"]).has(meta.projectKind)) errors.push("project_kind must be existing or new");
-  if (!meta.platforms.length || meta.platforms.some((value) => !new Set(["desktop", "web", "mobile"]).has(value))) errors.push("platforms must contain desktop, web, or mobile");
-  if (meta.candidates.length < 2 || meta.candidates.length > 4 || new Set(meta.candidates).size !== meta.candidates.length) errors.push("style_candidates must contain 2-4 unique values");
-  if (meta.researchSnapshot !== "49b5659") errors.push("research_snapshot must equal 49b5659");
-  for (const required of ["final/index.html", "final/styles.css", "final/app.js"]) {
-    if (!meta.prototypeFiles.includes(required)) errors.push(`prototype_files must include ${required}`);
-  }
-  if (typeof meta.updatedAt !== "string" || Number.isNaN(Date.parse(meta.updatedAt))) errors.push("updated_at must be ISO-8601");
-  for (const heading of REQUIRED_HEADINGS) if (!body.includes(heading)) errors.push(`missing '${heading}'`);
-  if (/(?:[A-Za-z]:[\\/]|\/(?:Users|home|tmp)\/)/.test(markdown)) errors.push("design package contains a machine-specific absolute path");
-
-  let sources;
-  try {
-    sources = extractPrototypeSources(markdown);
-  } catch (error) {
-    errors.push(error.message);
-  }
-
-  if (meta.status === "ready" && !allowDraft) {
-    if (!meta.selectedStyle || !meta.candidates.includes(meta.selectedStyle)) errors.push("ready design requires selected_style from style_candidates");
-    if (!new Set(["compact", "default", "comfortable", "touch"]).has(meta.density)) errors.push("ready design requires a density");
-    if (!new Set(["light", "dark", "system", "both"]).has(meta.colorMode)) errors.push("ready design requires a color_mode");
-    const comparisonIndex = join(designRoot, "comparison", "index.html");
-    const variantsRoot = join(designRoot, "comparison", "variants");
-    if (!(await isFile(comparisonIndex))) errors.push("ready design requires comparison/index.html");
-    if (await isSymlink(comparisonIndex)) errors.push("comparison/index.html must not be a symlink");
-    if (await isSymlink(join(designRoot, "comparison")) || await isSymlink(variantsRoot)) errors.push("comparison directories must not be symlinks");
-    let variants = [];
-    try {
-      variants = (await readdir(variantsRoot)).filter((entry) => entry.endsWith(".html"));
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    if (variants.length < 2 || variants.length > 4) errors.push("ready design requires 2-4 comparison variant HTML files");
-    for (const variant of variants) {
-      if (await isSymlink(join(variantsRoot, variant))) errors.push(`comparison variant must not be a symlink: ${variant}`);
-    }
-    if (await isSymlink(join(designRoot, "final"))) errors.push("final directory must not be a symlink");
-    if (sources) {
-      try {
-        await materialize(designPath, { check: true });
-      } catch (error) {
-        errors.push(error.message);
-      }
-      const html = sources.get("final/index.html") ?? "";
-      const css = sources.get("final/styles.css") ?? "";
-      const js = sources.get("final/app.js") ?? "";
-      if (!/href=["']styles\.css["']/.test(html) || !/src=["']app\.js["']/.test(html)) errors.push("final HTML must reference relative styles.css and app.js");
-      if (/<(?:script|link)[^>]+(?:src|href)=["']https?:/i.test(html)) errors.push("final HTML must not load remote scripts or styles");
-      if (!css.includes(":focus-visible")) errors.push("final CSS must define :focus-visible");
-      if (!css.includes("prefers-reduced-motion")) errors.push("final CSS must handle prefers-reduced-motion");
-      if (!js.includes("addEventListener")) errors.push("final JS must implement an explicit interaction");
-    }
-  }
-
-  if (errors.length) throw new Error(errors.join("\n"));
-  return meta;
-}
-
-const args = process.argv.slice(2);
-const allowDraft = args.includes("--allow-draft");
-const paths = args.filter((arg) => arg !== "--allow-draft");
-if (paths.length !== 1) {
-  console.error("usage: validate-design-package.mjs [--allow-draft] <design-system.md>");
-  process.exitCode = 1;
-} else {
-  validate(paths[0], { allowDraft })
-    .then((meta) => console.log(`valid ${meta.designId} (${meta.status})`))
-    .catch((error) => {
-      console.error(error.message);
-      process.exitCode = 1;
-    });
-}

package/template/workflows/specdev/R-retro/R-retro.md

@@ -1,26 +0,0 @@
----
-id: specdev/retro
-type: workflow-entry
-workflow: specdev
-name: 开发复盘
-description: 对指定开发活动、环境或协作流程的已观察摩擦做证据化复盘，形成根因、改进 owner 与可检验提案；代码讲解使用 L-learn-change，Speculo 产品反馈使用 retro 命令。
-keywords: [retro, retrospective, 复盘, 环境, 反馈, 改进]
----
-
-# 开发复盘
-
-先读 <Path>{roots.workflows}/specdev/README.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>。本 Work 不自动修代码、提 Issue 或改永久知识。
-
-## 流程
-
-1. 固定本次会话/活动范围，按来源 ID 定位 change、测试、CI、交接和失败证据，不全读历史。缺失资料列 unknown；范围清楚且证据可定位才开始分析。
-2. 未归档且尚未 completed 的当前 change 使用其 retro 目录。completed 或 archived 来源以及独立复盘建立非实现 review change，引用原 locator；不重开来源状态或改写归档。按 <Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path> 初始化/恢复；他项占用 current_work 时先 handoff。
-3. 调用 <Path>{roots.skills}/retrospective/SKILL.md</Path>，检查约束是否缺失、已有检查是否失效或未接入；区分环境事实、机械检查和判断规则。每个发现有因果证据或明确假设，建议有 owner、正反验收与路由。
-4. 按 <Path>{roots.workflows}/specdev/R-retro/retro-template.md</Path> 创建 <Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path>，选择最小未占用 ID。原子保存并重读，运行 SpecDev --stage retro；修订保留来源与被替代结论。
-5. 验证通过后追加 works_run=specdev/retro 并清空 current_work；证据不足可完成一份 outcome=insufficient-evidence 的诚实报告，不冒充解决问题。只读复盘不创建 Spec/Ticket 或 implementation Evidence。review-only change 按专用完成门关闭。
-
-## 结果与路由
-
-合法 outcome：findings、no-findings、insufficient-evidence。发现的 disposition 为 file-issue / lesson-only / discard / duplicate；每项记录理由，允许没有发现。
-
-代码问题交 <Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>，计划改进交 <Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>，远程反馈交 <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>；永久知识交 <Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>。返回完整报告、已验证与未验证项、下一入口；不自动推进这些后续副作用。

package/template/workflows/specdev/R-retro/retro-template.md

@@ -1,27 +0,0 @@
----
-schema_version: 1
-artifact: retrospective
-change: <YYYY-MM-DD-topic>
-id: RETRO-001
-status: completed
-outcome: findings
-sources: []
-updated_at: <ISO-8601>
----
-
-# 开发复盘
-
-## Scope
-本次活动、会话、change 与来源 locator。扩大范围必须有来源。
-
-## Evidence
-原始现象、证据与未知项；已归档来源只引用不修改。
-
-## Findings
-逐项：ID、根因/假设、影响和频率、已有约束是否失效/未接入、remediation_axis、owner、disposition、合并/重复关系。没有发现明确写 none；不能强造 Issue。
-
-## Acceptance
-每项建议的正反样例、验证命令/方法与完成条件；区分机械检查和人的判断。
-
-## Routes
-下一入口、所需授权、未完成项及恢复条件；无后续动作注明原因。

package/template/workflows/specdev/R-review-architecture/R-review-architecture.md

@@ -1,93 +0,0 @@
----
-id: specdev/review-architecture
-type: workflow-entry
-workflow: specdev
-name: 架构审查
-description: 从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险，以中文 Markdown 记录高置信候选，并对用户选择的一个方案运行设计树访谈。
-keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接缝, code-judo]
----
-
-# 架构审查
-
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
-
-本 work 根据可定位的代码压力审查当前范围：先找会让 module 变浅的结构性坏味道，再找能删掉复杂性的 `code-judo` 机会，再找真正值得深化的 seam。行为正确不构成通过；如果存在更简单的路径，就优先把复杂性删掉，而不是搬家。
-
-本 work 只审查、呈现和访谈，不直接修改产品代码。报告阶段只产出 Markdown 决策记录，不生成 HTML。
-
-本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。沿用 CONTEXT 与共享设计词汇（module、interface、depth、seam、adapter、leverage、locality）准确表达含义，不为机械出现英文而牺牲理解。
-
-激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
-
-## 输入与产物
-
-按存在情况读取：
-
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
-- `<Path>{roots.state}/specdev/adr/</Path>`
-- `<Path>{roots.state}/specdev/context/</Path>`
-- 当前代码、测试、依赖和 Git 历史。
-
-产物：
-
-- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
-
-每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
-
-## 选择交付分支
-
-- `report`（默认）：用户只请求 review/扫描时完成下方探索与报告，候选保持 `unselected`；没有候选是有效结果，不要求用户先选方案才完成报告。
-- `selected-design`：只有用户已经选择一个候选并请求深入设计，才加载 `<Path>{roots.workflows}/specdev/R-review-architecture/references/selected-design.md</Path>`。输入是可回读报告和所选候选；来源漂移先核对影响，不用旧结论代替当前代码。
-
-两分支均不修改生产代码，报告不授权访谈、建票或实施。
-
-## Report 流程
-
-### 1. 探索
-
-**先找结构压力，再找方案。** YAGNI 仍然成立，但只有真正的代码压力才值得写入报告。
-
-- 用户指明 module、子系统或痛点时直接采用，跳过热点推断；
-- 否则翻阅足够长的 `git log --oneline`，找出反复出现的 files、call sites 和 test surfaces；
-- 变更散落、没有明确热点时才扩大搜索范围；
-- 只接受能通过删除测试的候选：删掉该 module 后，复杂性应集中或消失，而不是换一个地方继续蔓延；
-- 逐项应用 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>` 的结构压力、删除测试与排序规则；
-- 先读取项目领域词汇及当前区域 ADR；探索真实调用和测试表面，过滤仅 rearrange complexity 的提案。
-
-对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。若没有任何候选通过这条线，明确写出“没有高置信候选”，不要为了填表而硬造一个。
-
-**完成标准**：审查范围、排除范围、领域/ADR 输入和每个候选的 code pressure 均可追踪；没有把行为正确但结构平庸的地方当成通过。
-
-### 2. 生成 Markdown 报告
-
-使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>` 写入 Markdown 决策记录。
-
-每个候选以高置信 finding 的顺序展示，而不是按文件顺序排列。每个候选包含：
-
-- **文件**——涉及的 files 和 modules；
-- **问题**——当前架构造成的摩擦；
-- **代码 judo**——保留行为但删掉什么复杂性；
-- **收益**——用 locality、leverage、depth 和测试改善解释；
-- **删除测试**——删掉这个 module 后复杂性是否真的消失；
-- **前后对比**——用文本图示或 Mermaid 记录 shallow 与 deep；
-- **建议强度**——`Strong | Worth exploring | Speculative`；
-- **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`；
-- **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
-
-报告以“最佳推荐”结束；若没有高置信候选，就明确写 `无高置信候选`。报告阶段**不提出 interface**；返回候选和证据即可，不强制追加选择问题。
-
-**完成标准**：每个候选字段完整、最佳推荐唯一或明确为空，Markdown 已原子写入并重读。
-
-## 分支完成、状态与返回
-
-`report` 完成条件：范围有依据；高置信候选满足删除测试且每项有当前文件/调用/测试证据、前后对比、收益、强度和 ADR 冲突处理；最佳推荐唯一或明确为“无高置信候选”；Markdown 已原子写入并回读。未选择或拒绝的候选不变成 Ticket。
-
-`selected-design` 完成条件：用户选定的一个候选完成参考中的完整 frontier 访谈，或明确 blocked/rejected；只有接受且达成共识的方案才按原 Ticket 治理交接。其他候选保持未选择，不批量要求决定。
-
-按本分支真实结果更新 Work 状态：成功才把本 Work 去重加入 `works_run` 并清空 `current_work`，blocked 保留恢复键和原因。报告完成不是产品交付；只有请求本来以非实现审查为终点且满足 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，该终点 owner 才可关闭 change。
-
-返回分支、报告完整路径、审查范围/排除范围、代码证据、候选结论、实际验证与未验证项；有选择时再返回相应设计树/下一 Work。结构检查不证明设计判断正确，不能把弱候选包装成最佳推荐。

package/template/workflows/specdev/R-review-architecture/architecture-review-template.md

@@ -1,69 +0,0 @@
----
-artifact: architecture-review
-change: <YYYY-MM-DD-topic>
-status: draft
----
-
-# 架构审查：<范围>
-
-- **决策记录：** `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
-- **审查准则：** `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`
-
-## 1. 审查压力与范围
-
-- 触发目标：
-- 审查入口：
-- 相关行为或 Ticket：
-- 不审查范围：
-- 成功标准：
-- 热点依据：用户指定 / Git 历史
-- 结构性压力：file-size、spaghetti growth、boundary drift、wrong-layer logic、thin wrapper、sequential orchestration
-
-## 2. 当前结构地图
-
-### 模块与接口
-
-### 数据、控制与错误流及 seam
-
-### 变化热点、locality 与测试表面
-
-### 拆分压力
-
-- 接近或超过 1k lines 的文件：
-- 需要先删除还是先拆分的复杂性：
-
-## 3. 候选提案
-
-### AR-001: <标题>
-
-- **文件：** `<Path>project/relative/path</Path>`
-- **结构类别：** structural blocker / missed simplification / spaghetti growth / boundary drift / file-size pressure / wrong-layer logic
-- **问题：** 当前架构如何造成摩擦
-- **代码 judo：** 保留行为但删掉什么复杂性
-- **删除复杂性：** 会消失的 branch、helper、wrapper、mode、special case
-- **删除测试：** 删除当前 shallow module 会集中复杂性 / 只移动复杂性
-- **收益：** locality、leverage、depth 与测试改善
-- **建议强度：** Strong / Worth exploring / Speculative
-- **依赖类别：** in-process / local-substitutable / ports & adapters / mock
-- **ADR 冲突：** 无 / ADR-###，值得重审因为 ...
-
-#### 前后对比
-
-- Before：shallow interface、leaking seam 与分散 locality。
-- After：deep module、稳定 interface 与集中测试表面。
-
-- **证据：** `CODE:<Path>project/relative/path</Path>`、git log、测试输出
-- **推荐：**
-- **访谈状态：** unselected / selected / consensus / blocked / rejected
-- **用户结论：**
-- **ADR 影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 中的 ADR-###
-
-## 4. 最佳推荐
-
-首先探索：AR-###。原因：<一句话>。若没有高置信候选，明确写 `无高置信候选`。
-
-## 5. 下一步
-
-- 当前请求：report / selected-design。report 到此完成，访谈状态可为 unselected；无高置信候选也可交付。
-- 用户选择原文与候选 ID：仅 selected-design 填写；未选择时不虚构结论、不自动转票。
-- 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。

package/template/workflows/specdev/R-review-architecture/proposal-to-ticket.md

@@ -1,13 +0,0 @@
-# 架构提案转 Ticket
-
-本规则由 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 在候选被用户接受后加载。
-
-- 只有有代码证据、具体收益和用户接受的提案才生成 Ticket。
-- 先确认提案真正在删除复杂性，而不是把复杂性搬家；纯重排、纯改名或 thin wrapper 不进入 Ticket。
-- 前置 Ticket 必须指出解除的后续阻碍、受益 Ticket 或行为，以及独立验证。
-- 修改公共接口、schema、数据或大范围调用方时使用 Deep，并采用 expand → migrate → observe → contract。
-- 架构报告中的项目路径只是审查证据；生成 Ticket 时重新确认当前项目路径和所有权。
-- 不把“清理整个模块”写成单一 Ticket；按可验证安全落点拆分。
-- 如果候选会让文件越过 1k lines、引入更多 special cases，或者只是在已经忙乱的流程里再加一层分支，先继续分解，再考虑 Ticket。
-- 任何会改变外部行为或验收合同的提案先修订 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
-- 任何会改变已接受架构决策的提案先更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。

package/template/workflows/specdev/R-review-architecture/references/selected-design.md

@@ -1,23 +0,0 @@
-# 已选架构候选的设计与转票
-
-用户选定一个候选后读取；保持审查报告和 change 内决策同步，不修改生产代码。
-
-### 3. 访谈用户选择的一个候选
-
-用户选择候选后，调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
-
-决策结晶时保持领域模型同步：
-
-- 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
-- 模糊术语当场精炼；
-- 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时，询问是否记录 ADR；任一条件不满足就留在 LOG/Ticket，不制造 ADR；
-- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`；
-- 如果候选最终只是把复杂性搬家，而不是删掉它，在访谈中直接回退，不把它升级成 Ticket。
-
-将选择、访谈状态与结论同步到 Markdown；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
-
-**完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
-
-### 4. 转化为执行工作
-
-只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`，按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理；只有能删除复杂性的提案才继续，纯重排和 thin wrapper 不进入 Ticket。

package/template/workflows/specdev/R-review-architecture/review-rubric.md

@@ -1,52 +0,0 @@
-# 架构审查准则
-
-本准则只在 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 激活时生效。它把实际维护压力转成候选筛选和排序规则；每个结论都要有路径、调用或测试证据。
-
-使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语：module、interface、depth、seam、adapter、leverage、locality。优先保持项目共享含义；中文解释可与专业词并列，不要求机械复述每个词。
-
-## 重点观察
-
-优先寻找有真实代码压力的候选：
-
-- 结构性回退：module 变浅，interface 正在向 implementation 膨胀；
-- 代码 judo 机会：删掉一个 branch、helper、wrapper、mode 或 special case；
-- spaghetti growth：ad-hoc conditionals、散落例外或一次性 flags；
-- boundary drift：cast、`any`、`unknown` 或 optionality 掩盖真实不变量；
-- 文件大小或拆分压力，尤其是把文件推到 1k lines 以上；
-- wrong-layer logic 泄漏进共享路径或 canonical helper；
-- 重复的 canonical helper、identity abstraction 或 pass-through wrapper；
-- 原本可以更原子化的顺序编排或部分更新；
-- seam 正在把测试、错误或状态处理复杂性泄漏给调用方。
-
-## 删除测试
-
-只有删除当前 module、helper 或 branch 后，复杂性真的消失，或者至少集中到更容易推理的位置，候选才算成立。
-
-拒绝以下候选：
-
-- 只是重新摆放复杂性；
-- 只是改名；
-- 只是把一个 shallow module 换成另一个 shallow module；
-- 只是加一个 thin wrapper、adapter 或 identity abstraction，却没有换来 leverage；
-- 依赖 speculative generality，而不是当前真实压力；
-- 没有文件、调用点或测试证据。
-
-## 排序规则
-
-按严重度和代码压力排序：
-
-1. 结构性阻塞；
-2. 明显的代码 judo；
-3. 重复 special case 和 spaghetti growth；
-4. boundary 与 type contract 漂移；
-5. 文件大小和拆分压力；
-6. wrong-layer logic 和 canonical helper 重复；
-7. 低信号的可读性问题。
-
-## 文件大小规则
-
-不要让一个候选轻易把文件从 1k lines 以下推到 1k lines 以上。默认把它当成拆分压力，而不是通过项。
-
-## 报告门槛
-
-不要把报告写成杂音集合。只保留高置信 finding。若没有候选通过门槛，就直接写 `无高置信候选`，不要硬造一个来填模板。