@namewta/speculo 0.4.0 → 0.5.0

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

@@ -3,13 +3,20 @@ id: specdev/review-architecture
 type: workflow-entry
 workflow: specdev
 name: 架构审查
-description: 扫描与目标相关的代码区域，识别浅模块、接缝泄漏和局部性问题，以可视化报告呈现候选方案，并通过逐项访谈转化为可执行决策。
-keywords: [architecture, review, module depth, seams, locality, HTML, refactor]
+description: 从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
+keywords: [architecture, review, module, interface, depth, seam, adapter, leverage, locality, HTML]
 ---
 
-# 架构审查
+# 改善代码库架构
 
-本 work 保留并强化三项核心能力：从真实代码压力识别深层化机会、输出可视化 HTML 审查报告、与用户逐项访谈候选方案。它不以“更优雅”为由制造无目标重构，也不直接修改产品代码。
+揭示架构摩擦，提出**深化机会**——将 shallow module 转变为 deep module 的重构。目标是可测试性和 AI 可导航性。
+
+本 work 基于项目领域模型，并建立在共享设计词汇之上：
+
+- 读取 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，在每个建议中严格使用 module、interface、depth、seam、adapter、leverage、locality，不滑向含义更松散的替代词。
+- 当前 change 与永久 CONTEXT 中的领域语言为好的 seam 提供名称；ADR 记录本 work 不应重新争论的决定。
+
+本 work 只审查、呈现和访谈，不直接修改产品代码。
 
 ## 输入与产物
 
@@ -22,119 +29,99 @@ keywords: [architecture, review, module depth, seams, locality, HTML, refactor]
 - `<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>`
-- 可视化报告：`<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
-
-模板：
-
-- `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
-- `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
+- 系统临时目录中名称为 architecture-review-&lt;timestamp&gt;.html 的打开副本。
 
 ## 流程
 
-### 1. 明确审查压力与范围
-
-记录触发审查的业务目标、近期变更、缺陷、维护成本、性能或风险，不做无边界全仓巡检。明确：审查入口、相关调用路径、不审查范围和成功标准。
-
-用户明确要求全仓架构扫描时，可以扩展范围，但仍按领域、模块或调用链分批，避免在单次上下文中生成无证据的泛化结论。
-
-### 2. 建立当前结构地图
+### 1. 探索
 
-只读探索目标区域：
+**扫描前先划定范围——YAGNI。** 深化一个模块的价值在于让未来变更更容易，因此特别关注近期发生过变更的部分。
 
-- 模块及其公共接口；
-- 信息隐藏与调用者负担；
-- 接缝、适配器和依赖类别；
-- 数据、控制和错误流；
-- 时间耦合、共享状态和跨目录跳转；
-- 测试接缝与变更热点；
-- 近期缺陷、重复 workaround 和高频共同修改路径。
+- 用户指明模块、子系统或痛点时直接采用，跳过热点推断；
+- 否则翻阅足够长的 `git log --oneline`，找出反复出现的文件和位置；
+- 变更散落、没有明确热点时才扩大搜索范围。
 
-使用：
+首先阅读项目领域词汇和接触区域的 ADR。然后有机探索代码库，注意在哪里遇到摩擦：
 
-- `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
+- 理解一个概念是否需要在多个小模块间反复跳跃；
+- 哪些模块是 shallow，interface 几乎与实现一样复杂；
+- 哪些纯函数仅为可测试性抽出，bug 却藏在缺少 locality 的调用方式中；
+- 哪些紧密耦合模块在 seam 泄漏；
+- 哪些区域未经测试，或难以通过当前 interface 测试。
 
-外部技术或模式不清楚时使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
+对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。
 
-### 3. 识别候选深层化机会
+**完成标准**：审查范围、排除范围、领域/ADR 输入和每个候选的代码压力均可追踪。
 
-候选至少属于一种机制：
+### 2. 生成 Markdown 与 HTML 报告
 
-- 浅模块把复杂性推给调用者；
-- 接缝泄漏导致多处了解同一协议或状态；
-- 局部性差导致一个行为修改跨越过多路径；
-- 依赖方向或生命周期不清导致测试与替换困难；
-- 时间耦合、共享状态或错误语义造成事故半径；
-- 缺少真正适配器导致 Mock 代替设计；
-- 宽重构压力需要 expand-contract。
+使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>` 写入 Markdown 决策记录。
 
-每个候选必须有项目路径、调用或测试证据，并说明“不做”的实际后果。没有用户或工程收益、近期变化压力或风险降低的候选直接过滤。
+加载 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-report-contract.md</Path>` 和 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>`，写入持久化 HTML。报告使用 Tailwind CDN 布局、Mermaid CDN 表达调用/依赖/序列，并混合手写 CSS/SVG 呈现质量图、横截面和调用图坍缩。
 
-### 4. 设计替代方案
+每个候选包含：
 
-每个保留候选至少比较：
+- **文件**——涉及的文件和 modules；
+- **问题**——当前架构造成的摩擦；
+- **解决方案**——简明描述会发生什么；
+- **收益**——用 locality、leverage 和测试改善解释；
+- **前后对比图**——并排展示 shallow 与 deep；
+- **建议强度**——`Strong | Worth exploring | Speculative`；
+- **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`；
+- **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
 
-- 保持现状；
-- 最小深层化方案；
-- 一个具有实质差异的替代方案。
+报告以“最佳推荐”结束。此时**不提出 interface**，只询问用户想探索哪一个候选。
 
-比较调用者复杂度、接口稳定性、迁移、兼容、测试、回滚、路径影响和事故半径。局部接口存在多个可行设计时，可使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
+**完成标准**：每个候选字段完整、图表承担主要关系、最佳推荐唯一，Markdown 与 HTML 已原子写入并重读。
 
-### 5. 生成 Markdown 与 HTML 报告
+### 3. 持久化并打开报告
 
-使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`。
+从 `$TMPDIR` 解析临时目录，回退 `/tmp`，Windows 使用 `%TEMP%`。把持久化 HTML 复制到全新的 architecture-review-&lt;timestamp&gt;.html，再用平台命令打开：Linux `xdg-open`、macOS `open`、Windows `start`。
 
-使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`。HTML 应包含：
+打开失败不删除任一文件；向用户返回 state 主件和临时副本的绝对路径，以及失败命令。敏感值和机器路径不写回持久化报告。
 
-- 审查范围与结构地图；
-- 候选卡片和严重度；
-- 证据路径；
-- 方案对比；
-- 影响与迁移图；
-- 接受、延后、拒绝状态；
-- 指向 Markdown 决策记录的完整状态路径文本。
+**完成标准**：持久化主件可重读；临时副本名称唯一；打开成功或失败证据已报告。
 
-不得依赖外部 CDN；报告应可作为单文件本地打开。
+### 4. 访谈用户选择的一个候选
 
-### 6. 逐项访谈候选
+用户选择候选后，调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
 
-按价值与风险排序，一次只讨论一个候选：
+决策结晶时保持领域模型同步：
 
-1. 说明证据和问题机制；
-2. 给出推荐方案与理由；
-3. 展示至少一个替代方案和保持现状的后果；
-4. 询问用户接受、调整、延后或拒绝；
-5. 将结论写回 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`；
-6. 架构级决定同步到 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`，讨论轨迹同步到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
+- 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
+- 模糊术语当场精炼；
+- 用户以长期有效理由拒绝候选时，询问是否记录 ADR，暂时性或自明理由不制造 ADR；
+- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
 
-不得一次抛出所有问题要求用户批量选择。
+将选择、访谈状态与结论同步到 Markdown/HTML；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
 
-### 7. 转化为执行工作
+**完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
 
-只有被接受且有具体变更压力的提案才进入执行。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`：
+### 5. 转化为执行工作
 
-- 可独立降低后续实现难度的改进生成 Prefactor Ticket；
-- 常规垂直迁移生成 Standard Ticket；
-- 公共契约、数据、宽迁移或高风险改动生成 Deep Ticket 与 expand-contract；
-- 进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 完成正式拆分和 Ready 门禁。
+只有被接受且有具体变更压力的提案进入 `<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 治理。
 
 ## 完成标准
 
-- 审查压力、范围和不审查范围明确；
-- 每个候选有代码事实、行为影响和不做后果；
-- 保留候选有至少两个实质方案与权衡；
-- Markdown 和无外部依赖的 HTML 报告均已生成；
-- 用户已逐项给出接受、调整、延后或拒绝结论；
-- 接受的架构决定已同步到 ADR；
-- 执行建议已转入 Ticket 治理，而不是直接修改代码。
+- 范围来自用户方向或 Git 热点，未进行无边界扫描；
+- 每个候选通过删除测试并有真实代码压力；
+- 领域使用 CONTEXT 词汇，架构严格使用共享词汇；
+- 持久化 Markdown/HTML 与临时打开副本均可定位；
+- 每个候选有 Before/After、强度、收益和 ADR 冲突处理；
+- 报告阶段没有提前设计 interface；
+- 用户选择的一个候选完成完整 frontier 访谈；
+- 接受项进入 Ticket 治理，没有直接修改产品代码。
 
 ## 子文件引用
 
+- 共享设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 - Markdown 模板：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
+- HTML 报告合同：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-report-contract.md</Path>`
 - HTML 模板：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>`
 - 提案转 Ticket：`<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`

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

@@ -0,0 +1,123 @@
+# HTML 报告格式
+
+架构审查渲染为一个独立的 HTML 文件，存放在操作系统临时目录中。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
+
+## 脚手架
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* Tailwind 无法很好覆盖的小型自定义层：
+         虚线接缝线、手绘感箭头等。 */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## 页头
+
+仓库名称、日期和一个紧凑的图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，粗黑框 = 深模块。无介绍段落 — 直接进入候选。
+
+## 候选卡片
+
+图表承担主要分量。文字稀疏、平实，并使用来自 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语，不刻意修饰。
+
+每个候选是一个 `<article>`：
+
+- **标题** — 简短，命名深化方案（例如"Collapse the Order intake pipeline"）。
+- **徽章行** — 推荐强度（`Strong` = 翡翠绿，`Worth exploring` = 琥珀色，`Speculative` = 石板灰），外加一个依赖类别标签（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。
+- **文件** — 等宽字体列表，`font-mono text-sm`。
+- **Before / After 图表** — 核心。两列，并排。参见下方模式。
+- **Problem** — 一句话。痛点是什么。
+- **Solution** — 一句话。改变了什么。
+- **Wins** — 要点，每个不超过 6 个词。例如 "Tests hit one interface"、"Pricing logic stops leaking"、"Delete 4 shallow wrappers"。
+- **ADR 标注**（如适用）— 一行，放在琥珀色调的框中。
+
+无需解释段落。如果图表需要一段文字才能理解，重新画图。
+
+## 图表模式
+
+选择适合候选的模式。混合使用它们。不要让每个图表看起来都一样 — 多样性本身就是目的的一部分。
+
+### Mermaid 图表（依赖/调用流的常用工具）
+
+当重点是"X 调用 Y 调用 Z，看看这有多混乱"时，使用 Mermaid `flowchart` 或 `graph`。用 Tailwind 风格卡片包裹它，这样不会显得突兀。使用 classDef 将泄漏边缘着红色，深模块着深色。序列图适合展示"before：6 个往返；after：1 个"。
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### 手工绘制的框线图（当 Mermaid 的布局难以驾驭时）
+
+模块用带边框和标签的 `<div>` 表示。箭头用绝对定位在相对容器上的内联 SVG `<line>` 或 `<path>` 元素表示。当你希望"after"图表看起来像一个粗边的深模块，内部元素灰显时使用 — Mermaid 不会以合适的权重渲染这种效果。
+
+### 横截面图（适合分层浅度）
+
+堆叠水平条（`h-12 border-l-4`）来展示调用经过的各层。Before：6 个薄层，每个都不做什么。After：一个厚条，标注合并后的职责。
+
+### 质量图（适合"接口与实现一样宽"的场景）
+
+每个模块两个矩形 — 一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅）。After：接口矩形短，实现矩形高（深）。
+
+### 调用图坍缩
+
+Before：嵌套框呈现的函数调用树。After：同一棵树坍缩成一个框，内部调用在其内部以淡化形式显示。
+
+## 样式指导
+
+- 偏向编辑风格，而非企业仪表盘风格。宽松的留白。标题可选择衬线字体（`font-serif` 与 stone/slate 搭配效果很好）。
+- 色彩使用克制：一种强调色（翠绿或靛蓝），加上红色用于泄漏，琥珀色用于警告。
+- 保持图表约 320px 高，使 before/after 能够舒适地并排放置而无需滚动。
+- 使用 `text-xs uppercase tracking-wider` 用于图表内的模块标签 — 它们应读起来像示意图，而非 UI。
+- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。除此之外报告是静态的 — 没有应用代码，除了 Mermaid 自身的渲染之外没有交互。
+
+## 顶部推荐部分
+
+一张更大的卡片。候选名称，一句话说明为什么，指向其卡片的锚链接。这就够了。
+
+## 语气
+
+平实的英语，简洁 — 但架构名词和动词直接来自 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`。简洁不是偏离的借口。
+
+**完全使用：** module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。
+
+**绝不替代：** component、service、unit（代替 module）· API、signature（代替 interface）· boundary（代替 seam）· layer、wrapper（代替 module，当你的意思是 module 时）。
+
+**符合风格的表达方式：**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins 要点**用术语表命名收益：*"locality: bugs concentrate in one module"*、*"leverage: one interface, N call sites"*、*"interface shrinks; implementation absorbs the wrappers"*。不要写 *"easier to maintain"* 或 *"cleaner code"* — 这些术语不在术语表中，不值得留下。
+
+不模糊其词，不清喉咙，不说"值得注意的是……"。如果一句话可以变成一个要点，就变成要点。如果一个要点可以删除，就删除它。如果一个术语不在 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 中，在发明新术语之前先用术语表中已有的。

package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html

@@ -1,58 +1,106 @@
 <!doctype html>
 <html lang="zh-CN">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>SpecDev Architecture Review</title>
-  <style>
-    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
-    body { max-width: 1180px; margin: 0 auto; padding: 32px; line-height: 1.55; }
-    header, section { margin-bottom: 28px; }
-    .meta, .card { border: 1px solid #8886; border-radius: 12px; padding: 16px; }
-    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; }
-    .badge { display: inline-block; border: 1px solid currentColor; border-radius: 999px; padding: 2px 9px; margin-right: 6px; font-size: 0.85rem; }
-    table { width: 100%; border-collapse: collapse; }
-    th, td { border: 1px solid #8886; padding: 8px; text-align: left; vertical-align: top; }
-    code { overflow-wrap: anywhere; }
-    path::before { content: "<Path>"; }
-    path::after { content: "</Path>"; }
-  </style>
-</head>
-<body>
-  <header>
-    <h1>Architecture Review: &lt;范围&gt;</h1>
-    <div class="meta">
-      <p>决策记录：<code><Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path></code></p>
-      <p>本报告：<code><Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path></code></p>
-    </div>
-  </header>
-  <section>
-    <h2>审查压力与结构地图</h2>
-    <p>&lt;填写触发目标、范围、模块、接口、数据流和变化热点。&gt;</p>
-  </section>
-  <section>
-    <h2>候选提案</h2>
-    <div class="grid">
-      <article class="card">
-        <h3>AR-001 · &lt;标题&gt;</h3>
-        <p><span class="badge">severity</span><span class="badge">status</span></p>
-        <p><strong>证据：</strong><code><Path>project/relative/path</Path></code></p>
-        <p><strong>问题机制：</strong>&lt;...&gt;</p>
-        <p><strong>实际影响：</strong>&lt;...&gt;</p>
-        <p><strong>推荐：</strong>&lt;...&gt;</p>
-      </article>
-    </div>
-  </section>
-  <section>
-    <h2>方案对比</h2>
-    <table>
-      <thead><tr><th>维度</th><th>保持现状</th><th>推荐方案</th><th>替代方案</th></tr></thead>
-      <tbody><tr><td>调用者复杂度</td><td></td><td></td><td></td></tr></tbody>
-    </table>
-  </section>
-  <section>
-    <h2>决策与下一步</h2>
-    <p>&lt;逐项记录 accepted / adjusted / deferred / rejected。&gt;</p>
-  </section>
-</body>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Architecture review - {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      * { letter-spacing: 0 !important; }
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .module-label { font-size: 0.72rem; text-transform: uppercase; }
+      .quality-bar { min-height: 2.75rem; }
+      code { overflow-wrap: anywhere; }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="mx-auto max-w-5xl space-y-12 px-4 py-10 sm:px-6 sm:py-12">
+      <header class="space-y-4 border-b border-slate-300 pb-6">
+        <div class="flex flex-col gap-2 sm:flex-row sm:items-end sm:justify-between">
+          <div>
+            <p class="text-sm font-semibold text-emerald-700">{{repo name}} / {{date}}</p>
+            <h1 class="mt-1 font-serif text-3xl font-semibold sm:text-4xl">Architecture review</h1>
+          </div>
+          <p class="text-sm text-slate-600">{{review scope}}</p>
+        </div>
+        <div class="flex flex-wrap gap-x-5 gap-y-2 text-xs text-slate-600" aria-label="图例">
+          <span><span class="mr-1 inline-block h-3 w-5 border border-slate-700 align-middle"></span>module</span>
+          <span><span class="mr-1 inline-block h-3 w-5 border border-dashed border-slate-700 align-middle"></span>seam</span>
+          <span><span class="mr-1 inline-block h-0 w-5 border-t-2 border-red-600 align-middle"></span>leak</span>
+          <span><span class="mr-1 inline-block h-3 w-5 border-4 border-slate-900 align-middle"></span>deep module</span>
+        </div>
+        <p class="text-xs text-slate-500">
+          Decision record: <code><Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path></code>
+        </p>
+      </header>
+
+      <section id="candidates" class="space-y-10">
+        <article id="ar-001" class="rounded-lg border border-slate-300 bg-white p-5 shadow-sm sm:p-7">
+          <div class="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+            <div>
+              <p class="text-sm font-semibold text-emerald-700">AR-001</p>
+              <h2 class="mt-1 font-serif text-2xl font-semibold">Collapse the Order intake pipeline</h2>
+            </div>
+            <div class="flex flex-wrap gap-2 text-xs font-semibold">
+              <span class="rounded border border-emerald-700 bg-emerald-50 px-2 py-1 text-emerald-800">Strong</span>
+              <span class="rounded border border-slate-400 bg-slate-50 px-2 py-1 text-slate-700">in-process</span>
+            </div>
+          </div>
+
+          <div class="mt-5 border-y border-slate-200 py-3">
+            <p class="text-xs font-semibold uppercase text-slate-500">Files</p>
+            <p class="mt-1 font-mono text-sm">src/order/handler.ts · src/order/validator.ts · test/order.test.ts</p>
+          </div>
+
+          <div class="mt-6 grid gap-6 lg:grid-cols-2">
+            <section aria-labelledby="before-title">
+              <h3 id="before-title" class="text-sm font-semibold">Before</h3>
+              <div class="mt-2 min-h-80 rounded-lg border border-slate-200 bg-stone-50 p-4">
+                <pre class="mermaid">
+flowchart LR
+  A[OrderHandler] --> B[OrderValidator]
+  B --> C[OrderRepo]
+  C -. leak .-> D[PricingClient]
+  classDef leaking stroke:#dc2626,stroke-width:2px
+  class C,D leaking
+                </pre>
+              </div>
+            </section>
+            <section aria-labelledby="after-title">
+              <h3 id="after-title" class="text-sm font-semibold">After</h3>
+              <div class="mt-2 flex min-h-80 flex-col justify-center rounded-lg border-4 border-slate-900 bg-white p-5">
+                <p class="module-label font-semibold text-slate-500">Interface</p>
+                <div class="quality-bar mt-2 flex items-center rounded border border-emerald-700 bg-emerald-50 px-4 text-sm font-semibold text-emerald-900">one narrow interface</div>
+                <p class="module-label mt-6 font-semibold text-slate-500">Hidden implementation</p>
+                <div class="mt-2 space-y-2 text-sm text-slate-500">
+                  <div class="rounded border border-slate-200 bg-slate-50 p-3">validation</div>
+                  <div class="rounded border border-slate-200 bg-slate-50 p-3">pricing protocol</div>
+                  <div class="rounded border border-slate-200 bg-slate-50 p-3">persistence</div>
+                </div>
+              </div>
+            </section>
+          </div>
+
+          <dl class="mt-6 grid gap-5 border-t border-slate-200 pt-5 sm:grid-cols-3">
+            <div><dt class="text-xs font-semibold uppercase text-slate-500">Problem</dt><dd class="mt-1 text-sm">Callers coordinate three shallow modules and absorb the failure order.</dd></div>
+            <div><dt class="text-xs font-semibold uppercase text-slate-500">Solution</dt><dd class="mt-1 text-sm">Move the intake policy behind one deep module.</dd></div>
+            <div><dt class="text-xs font-semibold uppercase text-slate-500">Wins</dt><dd class="mt-1 text-sm">One test surface · Local failure policy · Fewer leaking seams</dd></div>
+          </dl>
+
+          <p class="mt-5 rounded border border-amber-500 bg-amber-50 px-4 py-3 text-sm text-amber-950">ADR note: {{none or conflict explanation}}</p>
+        </article>
+      </section>
+
+      <section id="top-recommendation" class="border-t-4 border-emerald-700 pt-6">
+        <p class="text-sm font-semibold text-emerald-700">Best recommendation</p>
+        <h2 class="mt-1 font-serif text-2xl font-semibold"><a class="underline decoration-emerald-600 decoration-2 underline-offset-4" href="#ar-001">Collapse the Order intake pipeline</a></h2>
+        <p class="mt-2 max-w-3xl text-slate-700">It removes the hottest coordination seam while preserving the domain language and existing behavior.</p>
+      </section>
+    </main>
+  </body>
 </html>

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

@@ -16,53 +16,44 @@ status: draft
 - 相关行为或 Ticket：
 - 不审查范围：
 - 成功标准：
+- 热点依据：用户指定 / Git 历史
 
 ## 2. 当前结构地图
 
-### 模块与接口
+### Modules 与 Interfaces
 
-### 数据、控制与错误流
+### 数据、控制与错误流及 Seams
 
-### 变化热点与测试接缝
+### 变化热点、Locality 与测试表面
 
 ## 3. 候选提案
 
 ### AR-001: <标题>
 
-- **机制：** shallow-module / seam-leak / locality / dependency / temporal-coupling / shared-state / migration
-- **严重度：** low / medium / high / critical
-- **证据：** `<Path>project/relative/path</Path>`
-- **问题如何发生：**
-- **用户或工程影响：**
-- **当前 workaround：**
-- **不做后果：**
+- **文件：** `<Path>project/relative/path</Path>`
+- **问题：** 当前架构如何造成摩擦
+- **解决方案：** 将发生什么变化；报告阶段不提出具体 interface
+- **收益：** locality、leverage 与测试改善
+- **建议强度：** Strong / Worth exploring / Speculative
+- **依赖类别：** in-process / local-substitutable / ports & adapters / mock
+- **删除测试：** 删除当前 shallow module 会集中复杂性 / 只移动复杂性
+- **ADR 冲突：** 无 / ADR-###，值得重审因为 ...
 
-#### 方案 A：保持现状
+#### Before / After
 
-#### 方案 B：推荐最小深层化
-
-#### 方案 C：替代方案
-
-| 维度 | A | B | C |
-|---|---|---|---|
-| 调用者复杂度 | | | |
-| 接口稳定性 | | | |
-| 迁移与兼容 | | | |
-| 测试与验证 | | | |
-| 回滚 | | | |
-| 事故半径 | | | |
+- Before：shallow interface、leaking seam 与分散 locality。
+- After：deep module、稳定 interface 与集中测试表面。
 
 - **推荐：**
-- **建议 Planning Depth：** lite / standard / deep
-- **访谈状态：** proposed / accepted / adjusted / deferred / rejected
+- **访谈状态：** unselected / selected / consensus / blocked / rejected
 - **用户结论：**
 - **ADR 影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 中的 ADR-###
 
-## 4. 优先级与依赖
+## 4. 最佳推荐
 
-| Candidate | Value | Risk Reduction | Cost | Dependency | Decision |
-|---|---|---|---|---|---|
+首先探索：AR-###。原因：<一句话>。
 
 ## 5. 下一步
 
-- 接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。
+- 报告生成后询问用户选择一个候选，不批量访谈。
+- 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。