@namewta/speculo 1.0.2 → 1.0.4

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

@@ -3,29 +3,26 @@ id: specdev/review-architecture
 type: workflow-entry
 workflow: specdev
 name: 架构审查
-description: 从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
-keywords: [architecture, review, module, interface, depth, seam, adapter, leverage, locality, HTML]
+description: 从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险，以中文 Markdown 记录高置信候选，并对用户选择的一个方案运行设计树访谈。
+keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接缝, code-judo]
 ---
 
-# 改善代码库架构
+# 架构审查
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
-揭示架构摩擦，提出**深化机会**——将 shallow module 转变为 deep module 的重构。目标是可测试性和 AI 可导航性。
+本 work 以热核级维护性标准审查当前范围：先找会让 module 变浅的结构性坏味道，再找能删掉复杂性的 `code-judo` 机会，再找真正值得深化的 seam。行为正确不构成通过；如果存在更简单的路径，就优先把复杂性删掉，而不是搬家。
 
-本 work 基于项目领域模型，并建立在共享设计词汇之上：
+本 work 只审查、呈现和访谈，不直接修改产品代码。报告阶段只产出 Markdown 决策记录，不生成 HTML。
 
-- 读取 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，在每个建议中严格使用 module、interface、depth、seam、adapter、leverage、locality，不滑向含义更松散的替代词。
-- 当前 change 与永久 CONTEXT 中的领域语言为好的 seam 提供名称；ADR 记录本 work 不应重新争论的决定。
-
-本 work 只审查、呈现和访谈，不直接修改产品代码。
+本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。审查语言必须使用 module、interface、depth、seam、adapter、leverage、locality。
 
 ## 读取范围
 
 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
+2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`、`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
+4. 用户指定范围优先于 Git 热点；若未指定，则从最近 churn、重复编辑和报错/回归轨迹中找出最值得审查的 module。
 
 ## 输入与产物
 
@@ -43,61 +40,57 @@ keywords: [architecture, review, module, interface, depth, seam, adapter, levera
 产物：
 
 - `<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 的打开副本。
+
+每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
 
 ## 流程
 
 ### 1. 探索
 
-**扫描前先划定范围——YAGNI。** 深化一个模块的价值在于让未来变更更容易，因此特别关注近期发生过变更的部分。
+**先找结构压力，再找方案。** YAGNI 仍然成立，但只有真正的代码压力才值得写入报告。
 
-- 用户指明模块、子系统或痛点时直接采用，跳过热点推断；
-- 否则翻阅足够长的 `git log --oneline`，找出反复出现的文件和位置；
-- 变更散落、没有明确热点时才扩大搜索范围。
+- 用户指明 module、子系统或痛点时直接采用，跳过热点推断；
+- 否则翻阅足够长的 `git log --oneline`，找出反复出现的 files、call sites 和 test surfaces；
+- 变更散落、没有明确热点时才扩大搜索范围；
+- 只接受能通过删除测试的候选：删掉该 module 后，复杂性应集中或消失，而不是换一个地方继续蔓延；
+- 优先挑出结构性回归、重复 special cases、wrong-layer logic、thin wrappers、identity abstractions、type boundary drift、sequential orchestration 和 file-size/decomposition pressure；
+- 如果一个更 canonical 的 helper 已经存在，优先复用它；如果 proposal 只是 rearrange complexity，不算候选。
 
-首先阅读项目领域词汇和接触区域的 ADR。然后有机探索代码库，注意在哪里遇到摩擦：
+首先阅读项目领域词汇和接触区域的 ADR。然后有机探索 codebase，注意哪里会让 maintenance knowledge 分散：
 
-- 理解一个概念是否需要在多个小模块间反复跳跃；
-- 哪些模块是 shallow，interface 几乎与实现一样复杂；
-- 哪些纯函数仅为可测试性抽出，bug 却藏在缺少 locality 的调用方式中；
-- 哪些紧密耦合模块在 seam 泄漏；
-- 哪些区域未经测试，或难以通过当前 interface 测试。
+- 哪些 module 是 shallow，interface 几乎与 implementation 一样复杂；
+- 哪些 seam 正在 leak；
+- 哪些纯函数只是为了可测试性被拆出，但 bug 实际藏在缺少 locality 的调用方式中；
+- 哪些模块因为 ad-hoc conditionals、mode flags 或 one-off branches 变得更 spaghetti；
+- 哪些区域正在把 feature logic 泄漏进 shared path 或 canonical helper 之外；
+- 哪些结构已经逼近或超过 1k lines，应该先 decomposition 再 review；
+- 哪些 orchestration 本可以并行或更 atomic，却被无谓串行化。
 
-对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。
+对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据，并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。若没有任何候选通过这条线，明确写出“没有高置信候选”，不要为了填表而硬造一个。
 
-**完成标准**：审查范围、排除范围、领域/ADR 输入和每个候选的代码压力均可追踪。
+**完成标准**：审查范围、排除范围、领域/ADR 输入和每个候选的 code pressure 均可追踪；没有把行为正确但结构平庸的地方当成通过。
 
-### 2. 生成 Markdown 与 HTML 报告
+### 2. 生成 Markdown 报告
 
 使用 `<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 呈现质量图、横截面和调用图坍缩。
-
-每个候选包含：
+每个候选以高置信 finding 的顺序展示，而不是按文件顺序排列。每个候选包含：
 
-- **文件**——涉及的文件和 modules；
+- **文件**——涉及的 files 和 modules；
 - **问题**——当前架构造成的摩擦；
-- **解决方案**——简明描述会发生什么；
-- **收益**——用 locality、leverage 和测试改善解释；
-- **前后对比图**——并排展示 shallow 与 deep；
+- **代码 judo**——保留行为但删掉什么复杂性；
+- **收益**——用 locality、leverage、depth 和测试改善解释；
+- **删除测试**——删掉这个 module 后复杂性是否真的消失；
+- **前后对比**——用文本图示或 Mermaid 记录 shallow 与 deep；
 - **建议强度**——`Strong | Worth exploring | Speculative`；
 - **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`；
 - **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
 
-报告以“最佳推荐”结束。此时**不提出 interface**，只询问用户想探索哪一个候选。
-
-**完成标准**：每个候选字段完整、图表承担主要关系、最佳推荐唯一，Markdown 与 HTML 已原子写入并重读。
-
-### 3. 持久化并打开报告
-
-从 `$TMPDIR` 解析临时目录，回退 `/tmp`，Windows 使用 `%TEMP%`。把持久化 HTML 复制到全新的 architecture-review-&lt;timestamp&gt;.html，再用平台命令打开：Linux `xdg-open`、macOS `open`、Windows `start`。
-
-打开失败不删除任一文件；向用户返回 state 主件和临时副本的绝对路径，以及失败命令。敏感值和机器路径不写回持久化报告。
+报告以“最佳推荐”结束；若没有高置信候选，就明确写 `无高置信候选`。此时**不提出 interface**，只询问用户想探索哪一个候选，或者为何没有候选。
 
-**完成标准**：持久化主件可重读；临时副本名称唯一；打开成功或失败证据已报告。
+**完成标准**：每个候选字段完整、最佳推荐唯一或明确为空，Markdown 已原子写入并重读。
 
-### 4. 访谈用户选择的一个候选
+### 3. 访谈用户选择的一个候选
 
 用户选择候选后，调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`，用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
 
@@ -106,31 +99,33 @@ keywords: [architecture, review, module, interface, depth, seam, adapter, levera
 - 新概念加入 change CONTEXT；永久 CONTEXT 不存在时延迟到归档提升；
 - 模糊术语当场精炼；
 - 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时，询问是否记录 ADR；任一条件不满足就留在 LOG/Ticket，不制造 ADR；
-- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
+- 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`；
+- 如果候选最终只是把复杂性搬家，而不是删掉它，在访谈中直接回退，不把它升级成 Ticket。
 
-将选择、访谈状态与结论同步到 Markdown/HTML；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
+将选择、访谈状态与结论同步到 Markdown；每次运行只访谈用户选择的候选，不批量迫使用户决定所有卡片。
 
 **完成标准**：被选候选的设计树达到共识或明确 blocked；领域词汇、LOG、ADR 和审查报告一致。
 
-### 5. 转化为执行工作
+### 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 治理。
+只有被接受且有具体变更压力的提案进入 `<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。
 
 ## 完成标准
 
 - 范围来自用户方向或 Git 热点，未进行无边界扫描；
 - 每个候选通过删除测试并有真实代码压力；
 - 领域使用 CONTEXT 词汇，架构严格使用共享词汇；
-- 持久化 Markdown/HTML 与临时打开副本均可定位；
-- 每个候选有 Before/After、强度、收益和 ADR 冲突处理；
+- Markdown 决策记录可重读；
+- 每个候选有前后对比、强度、收益和 ADR 冲突处理；
 - 报告阶段没有提前设计 interface；
 - 用户选择的一个候选完成完整 frontier 访谈；
-- 接受项进入 Ticket 治理，没有直接修改产品代码。
+- 接受项进入 Ticket 治理，没有直接修改产品代码；
+- 没有把结构性弱候选包装成最佳推荐。
 
 ## 子文件引用
 
 - 共享设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
+- 证据与验证：`<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
+- 审查准则：`<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.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-review-template.md

@@ -4,10 +4,10 @@ change: <YYYY-MM-DD-topic>
 status: draft
 ---
 
-# Architecture Review: <范围>
+# 架构审查：<范围>
 
 - **决策记录：** `<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/review-rubric.md</Path>`
 
 ## 1. 审查压力与范围
 
@@ -17,33 +17,42 @@ status: draft
 - 不审查范围：
 - 成功标准：
 - 热点依据：用户指定 / Git 历史
+- 结构性压力：file-size、spaghetti growth、boundary drift、wrong-layer logic、thin wrapper、sequential orchestration
 
 ## 2. 当前结构地图
 
-### Modules 与 Interfaces
+### 模块与接口
 
-### 数据、控制与错误流及 Seams
+### 数据、控制与错误流及 seam
 
-### 变化热点、Locality 与测试表面
+### 变化热点、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
 - **问题：** 当前架构如何造成摩擦
-- **解决方案：** 将发生什么变化；报告阶段不提出具体 interface
-- **收益：** locality、leverage 与测试改善
+- **代码 judo：** 保留行为但删掉什么复杂性
+- **删除复杂性：** 会消失的 branch、helper、wrapper、mode、special case
+- **删除测试：** 删除当前 shallow module 会集中复杂性 / 只移动复杂性
+- **收益：** locality、leverage、depth 与测试改善
 - **建议强度：** Strong / Worth exploring / Speculative
 - **依赖类别：** in-process / local-substitutable / ports & adapters / mock
-- **删除测试：** 删除当前 shallow module 会集中复杂性 / 只移动复杂性
 - **ADR 冲突：** 无 / ADR-###，值得重审因为 ...
 
-#### Before / After
+#### 前后对比
 
 - Before：shallow interface、leaking seam 与分散 locality。
 - After：deep module、稳定 interface 与集中测试表面。
 
+- **证据：** `CODE:<Path>project/relative/path</Path>`、git log、测试输出
 - **推荐：**
 - **访谈状态：** unselected / selected / consensus / blocked / rejected
 - **用户结论：**
@@ -51,7 +60,7 @@ status: draft
 
 ## 4. 最佳推荐
 
-首先探索：AR-###。原因：<一句话>。
+首先探索：AR-###。原因：<一句话>。若没有高置信候选，明确写 `无高置信候选`。
 
 ## 5. 下一步
 

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

@@ -3,9 +3,11 @@
 本规则由 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 在候选被用户接受后加载。
 
 - 只有有代码证据、具体收益和用户接受的提案才生成 Ticket。
-- Prefactor Ticket 必须指出解除的后续阻碍、受益 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/review-rubric.md

@@ -0,0 +1,52 @@
+# 架构审查准则
+
+本准则只在 `<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。若没有候选通过门槛，就直接写 `无高置信候选`，不要硬造一个来填模板。