feat: add architecture deepening scan to refactor

cs-refactor/SKILL.md

@@ -17,6 +17,8 @@ scan（扫优化点清单）→ design（和用户定做哪几条 + 顺序）→
 
 **核心纪律**：行为等价是底线。一旦会改外部可观察行为 → 不走 refactor，走 feature（需求变）或 issue（bug 修）。
 
+**架构 deepening 模式**：用户说"架构优化 / 模块太浅 / seam 不对 / 可测试性差 / AI 难导航"时，仍走本技能三阶段，不生成 HTML。scan 用 `codebase-design` 词汇找 deepening opportunities；这是内嵌词汇引用，不切换到独立 `codebase-design` skill。候选项写进标准 `{slug}-scan.md`，用户勾选后再进 design/checklist/apply。
+
 ## 执行 gate（worktree + commit）
 
 进入 apply 前运行 start gate，`{slug}` 为 refactor 目录名：
@@ -94,8 +96,9 @@ gate 不通过不开始改代码；override 时先在 unit 目录写 `worktree-o
 - **L2 代码级重构**：超长函数（> 50 行 / 圈复杂度 > 10）、重复条件片段、神秘临时变量、多层嵌套 if-else
 - **L3 结构拆分**：组件 > 300 行 / 文件承担多件事 / 容器与展示混在一起 / 相同逻辑多组件各写一份（前端）；Controller 直接调 DB / Service 缺失 / Repository 被绕开（后端）
 - **L4 性能**：重复计算（可 memo）/ N+1 查询 / 列表无虚拟化或分页 / 事件监听无清理 / 大对象深响应（Vue）
+- **Architecture deepening**：shallow module、pass-through wrapper、seam 泄漏、假 adapter、测试越过 interface、locality 缺失。候选项分类写"架构"，字段按 `reference/scan-checklist-format.md` 的架构扩展。
 
-完整方法库在 `reference/methods.md` 和 `reference/methods-l4.md`，扫描时全量加载作匹配表。
+完整方法库在 `reference/methods.md`、`reference/methods-l4.md` 和 `reference/methods-architecture.md`，扫描时全量加载作匹配表。
 
 ### 产出格式
 
@@ -113,7 +116,7 @@ gate 不通过不开始改代码；override 时先在 unit 目录写 `worktree-o
 ### 输入
 
 - 用户勾选过的 `{slug}-scan.md`
-- 方法库（每条勾选项必须映射到方法号 M-Ln-NN）
+- 方法库（每条勾选项必须映射到方法号 M-Ln-NN，含 architecture deepening 方法）
 
 ### 做的事
 
@@ -243,4 +246,5 @@ refactor: {YYYY-MM-DD}-{slug}
 - `reference/refusal-routing.md` — scan 前置检查 7 条 + 路由表
 - `reference/methods.md` — 方法库（L1-L3）
 - `reference/methods-l4.md` — 方法库（L4 性能与异步）
+- `reference/methods-architecture.md` — 方法库（architecture deepening）
 - `.codestable/reference/shared-conventions.md` — 跨工作流共享口径

cs-refactor/reference/methods-architecture.md

@@ -0,0 +1,62 @@
+# 重构方法库：Architecture Deepening
+
+本文件承接 `methods.md` 的 L3 结构拆分方法，专放 deep-module / seam / interface 相关方法。方法号继续使用 `M-L3-NN`，但不塞回 `methods.md`，避免单文件超过 300 行。
+
+## L3 Architecture Deepening
+
+### M-L3-08 Deepen Module 深化模块
+
+- **适用**：多个 callers 需要理解同一组内部步骤；当前 module interface 几乎和 implementation 一样复杂；测试必须拼内部 helper 才能覆盖真实行为
+- **不适用**：只是想换命名 / 分文件；复杂度没有散到 callers；会改变外部可观察行为
+- **步骤**：
+  1. 列出 callers 必须知道的 internal facts（invariant / ordering / error mode / config）
+  2. 设计一个更小的 interface，把这些 facts 收进 module implementation
+  3. 用 Parallel Change（M-L1-01）迁移 callers，必要时保留旧 interface 过渡
+  4. 在新 interface 上补 characterization / integration-style tests
+  5. grep 确认 callers 不再依赖内部 helper / 内部状态
+- **风险点**：interface 设计过大变成新 shallow module；迁移期间新旧路径行为不一致
+- **验证**：新旧行为测试一致；caller 只依赖目标 interface；旧 internal imports / helper calls 归零
+- **前后端**：通用
+- **配哪种 scan 项**：shallow module / locality 缺失 / 测试越过 interface
+
+### M-L3-09 Move Seam 移动接缝
+
+- **适用**：当前 seam 放错位置，导致 caller 知道 transport、存储、第三方 client 或内部编排细节
+- **不适用**：只有一个实现且没有测试替身 / 生产替换需求；移动 seam 会改变公开契约
+- **步骤**：
+  1. 标出 seam 泄漏的 facts：哪些 caller 被迫知道内部细节
+  2. 选择新 seam，让 caller 和 tests 都穿过同一个 interface
+  3. 若跨远程或第三方依赖，定义 port；production adapter 和 test adapter 同时成立才引入 adapter
+  4. 逐个迁移 caller，删除旧 seam 上的泄漏依赖
+- **风险点**：只有一个 adapter 的假 seam；把业务语义泄漏进 transport adapter
+- **验证**：tests 通过新 seam 断言 observable outcome；旧 transport / storage 细节不再出现在 callers
+- **前后端**：通用
+- **配哪种 scan 项**：seam 泄漏 / 假 boundary / caller 依赖内部实现
+
+### M-L3-10 Collapse Shallow Wrappers 折叠浅包装
+
+- **适用**：一串 wrapper / helper 只转发参数或改名，interface surface 几乎等于 implementation；删除它们不会让复杂度回到 callers
+- **不适用**：wrapper 承载稳定领域语义、权限检查、缓存、重试、观测或多 adapter 切换
+- **步骤**：
+  1. 列出 wrapper 链和每层实际增加的行为
+  2. 保留真正承载语义的一层，把纯 pass-through 层 inline 或移动到 deep module 内部
+  3. 更新 imports / 调用点，删除空壳 wrapper
+  4. grep wrapper 名称和路径确认无残留
+- **风险点**：误删未来扩展点；inline 后 caller 暴露过多 implementation detail
+- **验证**：行为测试通过；被删除 wrapper 0 引用；callers 没有新增 internal dependency
+- **前后端**：通用
+- **配哪种 scan 项**：pass-through module / wrapper chain / shallow abstraction
+
+### M-L3-11 Replace Layered Tests with Interface Tests 替换分层测试
+
+- **适用**：测试散在多个 shallow helper 上，重构内部实现就大量失败；真实 bug 出现在 helpers 如何组合而不是单个 helper 内
+- **不适用**：helper 本身是稳定公共 interface；缺少能观察行为的上层 interface
+- **步骤**：
+  1. 找出当前测试绑定的 internal helper / call order / private state
+  2. 在目标 module interface 上写 characterization tests，覆盖同一 observable behavior
+  3. 确认新测试先能保护当前行为，再删除或降级旧 internal tests
+  4. 后续结构调整只保留 interface-level tests 作为行为等价证据
+- **风险点**：删除测试过早导致覆盖缺口；新 interface test 太粗，漏掉关键边界
+- **验证**：关键行为仍有测试覆盖；旧 internal tests 删除后整体 suite 仍能在行为破坏时失败
+- **前后端**：通用
+- **配哪种 scan 项**：tests 越过 interface / testability 差 / 重构被内部测试绑死

cs-refactor/reference/refusal-routing.md

@@ -36,6 +36,8 @@ scan 开始前跑一遍 7 条前置检查。任一命中**中止 scan 给路由
 
 **触发**：扫描时多数候选优化点涉及——A 依赖 B 内部实现（不是公开接口）/ 同一职责分散在 3+ 个模块各写一份 / 模块边界本身混乱。量化阈值：> 50% 候选点落在跨模块关系上。
 
+**例外**：用户明确要求"架构优化 / deepening / seam / 可测试性"扫描，且候选可以保持行为等价、写成 module/interface/seam 的 deepening 条目时，不中止；继续 scan，但分类必须写"架构"，方法映射到 `methods-architecture.md`。如果需要先拍板新的业务边界、改变外部契约或新增行为，仍按本条中止。
+
 **为什么停**：单模块 refactor 不能解决跨模块问题。强行在单模块内部改要么改不动（依赖卡着）要么改完其他模块跟着出问题。
 
 **路由**：

cs-refactor/reference/scan-checklist-format.md

@@ -20,7 +20,7 @@ summary: {发现多少条，按分类分布}
 ## 总览
 
 - 扫描范围：{文件/目录}
-- 发现 N 条优化点：结构 a / 性能 b / 可读性 c
+- 发现 N 条优化点：架构 a / 结构 b / 性能 c / 可读性 d
 - 按风险：低 x / 中 y / 高 z
 - 建议先做：#A #B #C（低风险、独立、AI 可自证）
 - 建议慎做 / 后做：#D（高风险、触发渲染路径变化、需人工目视）
@@ -41,11 +41,11 @@ summary: {发现多少条，按分类分布}
 ### [编号] {一句话标题}   ← 用户在这行末尾标 ✓ 或 ✗
 
 - **位置**：`src/xxx.vue:120-180`（可点开）
-- **分类**：结构 / 性能 / 可读性（三选一，不叠加）
+- **分类**：架构 / 结构 / 性能 / 可读性（四选一，不叠加）
 - **现状**：一句话白描现在怎么写的，必要时贴 ≤5 行原代码
 - **问题**：为什么值得改——可度量的东西（圈复杂度、重复次数、渲染次数、行数、依赖方向）
 - **建议**：动词开头，说清改成什么样
-- **建议映射的方法**：M-Ln-NN（引用 `methods.md` 或 `methods-l4.md` 里的方法号）
+- **建议映射的方法**：M-Ln-NN（引用 `methods.md`、`methods-l4.md` 或 `methods-architecture.md` 里的方法号）
 - **风险**：低 / 中 / 高 + 一句话为什么
 - **验证**：AI 自证（跑哪个测试/类型检查）｜ HUMAN（人要看什么页面/操作什么）
 - **范围**：约 N 行 / M 文件
@@ -55,6 +55,19 @@ summary: {发现多少条，按分类分布}
 
 位置 → 分类 → 现状 → 问题 → 建议 → 方法 → 风险 → 验证 → 范围。对应人类决策流：**在哪 → 是啥类型 → 现在怎样 → 为什么要动 → 怎么动 → 套哪个方法 → 多大代价 → 怎么验 → 工作量**。换顺序会让读者多次折返。
 
+### 架构 / deepening 条目的扩展字段
+
+分类为"架构"时，在"分类"后加这组字段；其他分类不要加：
+
+```markdown
+- **Module**：{当前 shallow module / 目标 deep module}
+- **Interface**：{caller 必须知道的签名、invariant、ordering、error mode；目标 interface 如何收敛}
+- **Seam**：{当前 seam 泄漏在哪里；目标 seam 放在哪里}
+- **Depth / locality**：{复杂度现在散到哪些 callers；目标如何集中到 implementation}
+- **Dependency category**：in-process | local-substitutable | remote-owned | true external
+- **Adapter**：{无 / production + test adapters / mock external；只有一个 adapter 时说明为什么不是假 seam}
+```
+
 ### 标题写作约束
 
 - ≤ 25 字，名词短语或动词短语，说**动什么**不说**好在哪**
@@ -94,7 +107,7 @@ AI 生成条目必须守，违反要自我纠正重写。
 
 ### 约束 6：每条必须映射到方法库
 
-"建议映射的方法"写不出 M-Ln-NN → 建议过于模糊重写到能对应某个方法。映射不上的不准进清单。
+"建议映射的方法"写不出 M-Ln-NN → 建议过于模糊重写到能对应某个方法。映射不上的不准进清单。架构条目优先映射 `methods-architecture.md`。
 
 ---