feat: update terminology from "跨层纪律" to "流程级约束" across multiple documents for consistency

cs-feat-accept/SKILL.md

@@ -41,7 +41,7 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现
 1. **代码确实实现到位**——git status / 最近提交看到本功能改动，否则退回 implement
 2. **方案 doc 完整**——frontmatter `doc_type=feature-design` / `feature` 一致 / `status=approved` / `summary` 非空 / `tags` ≥ 2；标准 design 第 0/1/2/3 节 + 第 4 节已填写
 3. **`{slug}-checklist.yaml`**——存在且 `feature` 一致；`steps` 全 `done`（有 `pending` 退回 implement）；`checks` 非空全 `pending`
-4. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 跨层纪律、2.3 挂载点、第 3 节场景）+ checklist + 第 4 节提到的所有架构 doc + 本次代码改动（git log / diff）
+4. **上下文读全**——方案 doc 全文（重点：第 1 节明确不做、2.1 接口示例、2.2 流程级约束、2.3 挂载点、第 3 节场景）+ checklist + 第 4 节提到的所有架构 doc + 本次代码改动（git log / diff）
 5. **断点恢复**——`{slug}-acceptance.md` 已存在且部分填好 → 从下一个未完成节继续，跳过 checks 中已 `passed` 的项；汇报"上次做到第 X 节，从第 Y 节继续"
 
 **Fastforward design 验收报告映射表**：
@@ -98,7 +98,7 @@ description: feature 流程阶段 3——验收闭环：对照 design 核实现
 **编排层"现状 → 变化"逐项核对**：
 - [ ] 变化 V1：{在哪一步插入 / 哪条分支变更} → 代码实际落点
 
-**跨层纪律核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）：
+**流程级约束核对**（错误语义 / 幂等 / 并发 / 扩展点 / 可观测点）：
 - [ ] 纪律 R1：{描述} → 代码遵守方式
 
 **挂载点反向核对（可卸载性）**——对照第 2.3 节，必做两件事：
@@ -136,7 +136,7 @@ Fastforward 方案没有挂载点清单 → 现场 grep 盘点本次改动命中
 
 - **名词归并** ← 第 2.1 节新增 / 变化的实体、类型、对外契约 → architecture 的"结构与交互 / 数据与状态"节
 - **动词骨架归并** ← 第 2.2 节跨模块可见的主流程 / 关键编排 → architecture 的结构图 / 模块交互
-- **跨层纪律归并** ← 第 2.2 节跨 feature 稳定的约束 → architecture 的"已知约束"节
+- **流程级约束归并** ← 第 2.2 节跨 feature 稳定的约束 → architecture 的"已知约束"节
 
 逐项核对：
 - [ ] 架构 doc X（{路径}）：归并内容 {描述}；已写入 ✓ / 不需要（理由：{具体}）
@@ -222,6 +222,7 @@ req 是现状档案，本节是 req 落档 / 刷新的**唯一时机**。对照
 
 1. 复用价值的坑点 / 经验 → "需要沉淀 learning 吗？（`cs-learn`）"
 2. 长期约束 / 技术选型 → "需要归档决定吗？（`cs-decide`）"
+   - **特检**：design 第 2.5 节是否有"建议沉淀的 convention"段。有就把那条规则原文念给用户："design 2.5 建议沉淀这条 convention：『{规则一句话}』，跑通了，要不要现在 `cs-decide` 归档？"——这种是 design 阶段就识别出的稳定模式，比一般"问问看"更应该主动提
 3. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-guide`）"
 4. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-libdoc`）"
 5. 第 8 节有 AGENTS.md / CLAUDE.md 候选 → 逐条问"候选 X 加到 {AGENTS.md / CLAUDE.md} 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条**

cs-feat-design/SKILL.md

@@ -83,9 +83,9 @@ design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在
 
 1. **名词层**——值对象 / 实体 / 数据结构 / 对外契约 / 类型定义
 2. **编排层**——主流程 / workflow / 关键编排函数 / 控制流拓扑（线性 / 分支 / 并行 DAG / 状态机）。开头一张主流程图建 mental model
-3. **跨层纪律**——错误语义、幂等性、并发 / 顺序、扩展点位置、可观测点。挂载点清单也归这类
+3. **流程级约束**——错误语义、幂等性、并发 / 顺序、扩展点位置、可观测点。挂载点清单也归这类
 
-外加一个**固定结构健康度环节**（第 2.5 节）：评估即将被改动的文件是否偏胖 / 职责混杂，决定是否在实现前先做"只搬不改行为"的微重构。即使结论是"不做"也要在 design 里显式写出来——否则 AI 默认会持续往胖文件里塞代码。这一节随整稿一起进整体 review，不单独走确认。
+外加一个**固定结构健康度环节**（第 2.5 节）：评估即将被改动的文件是否偏胖 / 职责混杂、以及新文件要落进的目录是否摊平，决定是否在实现前先做"只搬不改行为"的微重构（拆文件 / 重组目录）。即使结论是"不做"也要在 design 里显式写出来——否则 AI 默认会持续往胖文件里塞代码、往拥挤目录里加文件。这一节随整稿一起进整体 review，不单独走确认。
 
 **判据**：换一种写法名词层或编排层会变得不同 → design 的事；换一种写法只是"代码不那么好看 / 函数拆法不同 / 测试用了别的 framework" → implement 的事。
 
@@ -141,7 +141,7 @@ design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在
    - design `status=draft` 各节基本完整 → 跳到本流程"5. 整体 review"
    - design 部分节缺失 → 补缺失节，汇报"上次写到 X，补齐统一给你 review"
    - design `status=approved` → 别默认覆盖，问用户接着改还是另起 slug
-2. **读 architecture**——`codestable/architecture/ARCHITECTURE.md` + 索引 + 相关子系统 doc。重点看名词（能不能复用 / 冲突）和跨层纪律
+2. **读 architecture**——`codestable/architecture/ARCHITECTURE.md` + 索引 + 相关子系统 doc。重点看名词（能不能复用 / 冲突）和流程级约束
 3. **对齐 requirement**（只读不写，design 阶段不建也不改 req）：
    - 有对应 req：frontmatter `requirement` 填 slug，读 req 的"用户故事 / 边界"两节避免冲突
    - 新能力首次出现：`requirement` 留空，由 acceptance 阶段触发 `cs-req` backfill
@@ -180,10 +180,14 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。
 - 编排层开头一张 mermaid 图建 mental model
 - 挂载点按"删了它 feature 是否消失"判据，3-5 条为正常区间
 - 推进策略按 paradigm 维度切片（编排骨架 → 计算节点 → 持久化 → 测试），不下沉到 file:line
-- **第 2.5 节"结构健康度与微重构"是固定步骤**——按 reference.md 写作要求评估即将改动的文件，结论二选一：
-  1. **不做**——文件健康 / 改动量小 / 微重构收益不抵风险，写"本次不做微重构，原因：……"
-  2. **做微重构（只搬不改行为）**——文件偏胖或职责混杂但能用 provable refactor（拆函数 / 拆文件 / 移动定义，编译器全程绿灯）解决。给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为**第 1 步且独立验证退出**，再开始 feature 主体
-- **design 只做安全的微重构，边界严格守住**："只搬不改行为"——能用 IDE rename / move + 编译器校验完成。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定
+- **第 2.5 节"结构健康度与微重构"是固定步骤**——按 reference.md 写作要求评估**两类对象**：要改的文件（文件级）+ 要落新文件的目标目录（目录级）。**评估前先查 compound 已有 convention**（关键词围绕"目录组织 / 文件归属 / 命名约定"），命中就直接照办。结论三选一：
+  1. **不做**——文件健康 / 目录不挤 / 改动量小 / 微重构收益不抵风险，写"本次不做微重构，原因：……"
+  2. **做微重构（拆文件）**——文件偏胖或职责混杂但能用 provable refactor（拆函数 / 拆文件 / 移动定义，编译器全程绿灯）解决
+  3. **做微重构（重组目录）**——目标目录摊平且能通过纯文件移动 + import 路径更新解决（编译器全程绿灯）
+
+  选择 2 / 3 时给出"搬什么 → 搬到哪 → 怎么验证行为不变"的具体方案，落进 checklist 作为**第 1 步且独立验证退出**，再开始 feature 主体
+- **重组目录时多问一步：是稳定模式还是一次性整理**——稳定模式（如"自定义业务组件统一放 `components/custom/`"，未来其他 feature 也该遵守）就在 2.5 末尾加"建议沉淀的 convention"段，提示用户 implement 跑通后走 `cs-decide` 归档；一次性整理（只是这个目录碰巧挤了）就只搬不归档。**design 阶段不直接归档**——方案还没真跑过，留钩子给 implement 后再决定
+- **design 只做安全的微重构，边界严格守住**："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定
 - **第 2.5 节随整稿一起 review，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长
 
 ### 4. 补齐剩下各节，整稿一次性给 review
@@ -219,7 +223,7 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。
 - [ ] 第 2.1 / 2.2 用"现状 → 变化"两段式；接口有示例 + 来源位置；编排层开头有主流程图
 - [ ] 第 2.3 挂载点按"删了它 feature 是否消失"判据收紧（一般 3-5 条）
 - [ ] 第 2.4 推进策略按 paradigm 维度切片，每步有退出信号
-- [ ] 第 2.5 结构健康度结论显式写出（不做 / 微重构方案）；选"微重构"时 checklist 第 1 步是它且有独立退出信号；超出"只搬不改行为"的结构性问题列在"超出范围的观察"，仅提示不阻塞
+- [ ] 第 2.5 结构健康度评估覆盖文件级 + 目录级；评估前已查 compound convention；结论显式写出（不做 / 拆文件 / 重组目录）；选"微重构"时 checklist 第 1 步是它且有独立退出信号；选"重组目录"且属稳定模式时含"建议沉淀的 convention"段；超出"只搬不改行为"的结构性问题列在"超出范围的观察"，仅提示不阻塞
 - [ ] 第 3 节关键场景覆盖正常 + 边界 + 错误；含"明确不做"反向核对项
 - [ ] `{slug}-checklist.yaml` 已落盘并通过 `validate-yaml.py` 校验
 - [ ] roadmap 起头时 items.yaml 已回写（`status: in-progress` + `feature` 填上）

cs-feat-design/reference.md

@@ -48,7 +48,7 @@ steps:
 
 checks:
   - item: "{检查项描述}"
-    source: 名词契约 | 编排骨架 | 跨层纪律 | 挂载点 | 范围守护 | 验收场景
+    source: 名词契约 | 编排骨架 | 流程级约束 | 挂载点 | 范围守护 | 验收场景
     status: pending
 ```
 
@@ -64,7 +64,7 @@ checks:
 `checks`（design 阶段产出，提取来源）：
 
 - 名词契约 ← 第 2.1 节关键接口签名
-- 编排骨架 / 跨层纪律 ← 第 2.2 节主流程关键步骤、跨层纪律
+- 编排骨架 / 流程级约束 ← 第 2.2 节主流程关键步骤、流程级约束
 - 挂载点 ← 第 2.3 节每个挂入点（acceptance 反向核对可卸载性）
 - 范围守护 ← 第 1 节"明确不做"每条
 - 验收场景 ← 第 3 节"关键场景清单"每条
@@ -104,7 +104,7 @@ design 的灵魂。**所有子节用"现状 → 变化"两段式**——不写"
 - **主流程图**（开头一张）：mermaid sequence 或 flowchart。正常路径 + 关键异常 / 边界。这是读者建 mental model 的入口
 - **现状**：当前主流程 / workflow / 关键编排函数承担什么；拓扑（线性 pipeline / 分支 router / 并行 DAG / 状态机）
 - **变化**：在哪一步插入、哪条分支变更、新增哪个支线、是否升级拓扑
-- **跨层纪律**：错误语义（失败回滚还是重试，对外返回什么）、幂等性、并发 / 顺序约束、扩展点位置、可观测点
+- **流程级约束**：错误语义（失败回滚还是重试，对外返回什么）、幂等性、并发 / 顺序约束、扩展点位置、可观测点
 
 #### 2.3 挂载点清单
 
@@ -147,41 +147,63 @@ design 的灵魂。**所有子节用"现状 → 变化"两段式**——不写"
 
 #### 2.5 结构健康度与微重构
 
-固定节，每个 design 都要写。**评估对象**：第 2.1 / 2.2 节"变化"涉及的源码文件（新增不算，只看要改的）。
+固定节，每个 design 都要写。**评估对象**：
 
-**评估维度**（任一显著就算"偏胖"）：
+- **文件级**：第 2.1 / 2.2 节"变化"涉及的源码文件（新增不算，只看要改的）
+- **目录级**：本次要落新文件的目标目录（新增文件不评估文件本身，但要评估它们要落进的目录是否摊平）
 
-- 行数：单文件 > 500 行（语言略有差异，TS/JS/Vue 偏严，Python 略松）
-- 职责：一个文件混了 2 个以上不相关概念（编排 + 计算混写、UI + 数据请求 + 业务逻辑混写）
-- 改动密度：本次要在同一文件改 / 加 3 处以上，且每处之间逻辑独立
+**评估前先查 compound**——围绕"目录组织 / 文件归属 / 命名约定"关键词查一次：
 
-**结论二选一，必须显式写出来**：
+```bash
+python codestable/tools/search-yaml.py --dir codestable/compound \
+  --filter doc_type=decision --filter category=convention \
+  --query "目录组织 OR 命名 OR 归属"
+```
+
+命中已有 convention（如"composable 统一放 `src/composables/`"）：本节相关维度结论直接写"按 compound `{slug}` 执行"，不再讨论。
+
+**评估维度**（任一显著就算需要处理）：
+
+- 文件行数：单文件 > 500 行（TS/JS/Vue 偏严，Python 略松）
+- 文件职责：一个文件混了 2 个以上不相关概念（编排 + 计算混写、UI + 数据请求 + 业务逻辑混写）
+- 文件改动密度：本次要在同一文件改 / 加 3 处以上，且每处之间逻辑独立
+- **目录摊平**：目标目录已有 ≥ 8 个同层文件且本次还要再加 ≥ 2 个；或目录内文件命名出现明显可分组前缀 / 后缀（如 `XxxModal.vue` / `XxxForm.vue` 一堆混在通用目录），本次新增会延续这种摊平
+
+**结论必须显式写出来**：
 
 ```markdown
 ##### 评估
-- {文件路径} — {行数 / 职责 / 改动密度三个观察点}
+- 文件级 — {文件路径}：{行数 / 职责 / 改动密度三个观察点}
+- 目录级 — {目录路径}：{现有文件数 / 命名模式 / 本次新增情况}
 - ...
 
-##### 结论：{不做 | 微重构}
+##### 结论：{不做 | 微重构（拆文件） | 微重构（重组目录）}
 
 ##### 方案（仅"微重构"时填）
-- 搬什么：{从 file A 把 X / Y / Z 这几块代码搬走}
-- 搬到哪：{新文件 file B，命名 / 归属说明}
-- 行为不变怎么验证：{编译绿灯 + 现有测试通过 + 对外接口签名零 diff}
+- 搬什么：{从 file A 把 X / Y / Z 这几块搬走 / 把目录 D 下匹配 {模式} 的文件搬走}
+- 搬到哪：{新文件 / 新子目录路径，命名 / 归属说明}
+- 行为不变怎么验证：{编译绿灯 + 现有测试通过 + 对外接口签名零 diff + 仅 import 路径有 diff}
 - 步骤序列（provable refactor）：
   1. ...
   2. ...
 
+##### 建议沉淀的 convention（可选，仅"重组目录"且属稳定模式时填）
+- 是否稳定模式：{一次性整理 → 省略整段；稳定模式 → 继续填以下}
+- 规则一句话：{如"自定义业务组件统一放 src/components/custom/，通用组件放 src/components/common/"}
+- 适用范围：{本仓库全部 / 仅 frontend / 仅某模块}
+  → 建议 implement 跑通后走 `cs-decide` 归档为 `category: convention`，未来 design 在开篇 compound 检索就能命中
+
 ##### 超出范围的观察（可选，仅提示不阻塞）
-- {文件路径}：{发现的结构性问题——职责重划 / 模块拆合 / 接口语义需要变 / 跨文件依赖混乱}
+- {文件路径 / 目录路径}：{发现的结构性问题——职责重划 / 模块拆合 / 接口语义需要变 / 跨文件依赖混乱}
   → 建议后续走 `cs-refactor` 处理，本 feature 不动
 ```
 
 **判据**：
 
-- 选"微重构"必须满足"只搬不改行为"——能用 IDE 的 rename / move + 编译器校验完成。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，**不要在 design 里做也不要作为前置依赖**——写进"超出范围的观察"提示用户走 `cs-refactor`，本 feature 照常推进
-- 选"不做"也要列评估观察点，不能只写一句"文件健康"——避免后续 acceptance 时无法回看判断依据
-- "超出范围的观察"是发现到就提，不是必填——发现不到就省略整段
+- 选"微重构"必须满足"只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，**不要在 design 里做也不要作为前置依赖**——写进"超出范围的观察"提示用户走 `cs-refactor`，本 feature 照常推进
+- 选"不做"也要列评估观察点（文件级 + 目录级），不能只写一句"健康"——避免后续 acceptance 时无法回看判断依据
+- "建议沉淀的 convention"判定**稳定模式 vs 一次性整理**：稳定模式 = 这条规则**未来其他 feature 也应该遵守**（如归属规则、命名规则）；一次性整理 = 只是这个目录恰好挤了，没有普适规则。拿不准时倾向"一次性整理"——design 阶段方案还没真跑过，不在这里直接归档，只留钩子让 implement 跑通后由用户决定是否走 `cs-decide`
+- "超出范围的观察"和"建议沉淀的 convention"都是发现到就提，不是必填——发现不到就省略整段
 
 写完此节不单独走确认，随整稿一起进整体 review（看下文第 5 节）。
 
@@ -189,7 +211,7 @@ design 的灵魂。**所有子节用"现状 → 变化"两段式**——不写"
 
 implement 完成的判据，acceptance 核对的依据。**不写测试代码 / framework / mock 怎么搭**——归 implement 自决。
 
-- **关键场景清单**：每条"输入 / 触发 → 期望可观察结果"——能被一个测试或一次手工操作验证。覆盖正常路径（对应成功标准）+ 关键边界（边界值、空输入、上下限）+ 关键错误路径（跨层纪律的可观察行为）
+- **关键场景清单**：每条"输入 / 触发 → 期望可观察结果"——能被一个测试或一次手工操作验证。覆盖正常路径（对应成功标准）+ 关键边界（边界值、空输入、上下限）+ 关键错误路径（流程级约束的可观察行为）
 - **明确不做的反向核对项**：第 1 节"明确不做"每条 → 写成可被 grep 或测试反向核对的形式（"代码中不应出现对 X API 的调用"、"输出 JSON 不应包含字段 Y"）
 
 ### `## 4. 与项目级架构文档的关系`
@@ -198,7 +220,7 @@ implement 完成的判据，acceptance 核对的依据。**不写测试代码 /
 
 - **名词** ← 系统级可见的实体 / 类型 / 对外契约 → architecture 的"结构与交互 / 数据与状态"节
 - **动词骨架** ← 跨模块可见的主流程 / 关键编排 → architecture 的结构图 / 模块交互
-- **跨层纪律** ← 跨 feature 稳定的约束（错误语义、幂等、扩展点、挂载点规约）→ architecture 的"已知约束"
+- **流程级约束** ← 跨 feature 稳定的约束（错误语义、幂等、扩展点、挂载点规约）→ architecture 的"已知约束"
 
 外加：关联哪些已有架构 doc；架构总入口要不要新增描述（描述不是贴链接）。
 
@@ -210,9 +232,9 @@ implement 完成的判据，acceptance 核对的依据。**不写测试代码 /
 > 1. 术语有没有和已有概念冲突？
 > 2. 第 1 节决策与约束准不准，"不做什么"有没有遗漏？
 > 3. 第 2.1 名词层：现状描述对不对？变化是否覆盖所有数据/接口改动？
-> 4. 第 2.2 编排层：主流程图和现状→变化能不能跑通你脑子里的场景？跨层纪律有没有漏？
+> 4. 第 2.2 编排层：主流程图和现状→变化能不能跑通你脑子里的场景？流程级约束有没有漏？
 > 5. 第 2.3 挂载点：照这份清单能不能完整卸载？有没有项是内部改动被误列进来？
-> 6. 第 2.5 结构健康度：评估的几个文件是否准确？结论（不做 / 微重构）和方案是否同意？"超出范围的观察"有没有遗漏或写错？
+> 6. 第 2.5 结构健康度：评估的文件 + 目录是否准确？结论（不做 / 拆文件 / 重组目录）和方案是否同意？若有"建议沉淀的 convention"是否真属稳定模式？"超出范围的观察"有没有遗漏或写错？
 > 7. 第 3 节验收场景：覆盖正常 + 边界 + 错误路径了吗？
 >
 > 有修改意见直接说，确认后进入实现阶段。

cs-feat-ff/SKILL.md

@@ -5,9 +5,9 @@ description: feature 流程的超轻量通道——不写 design / checklist 直
 
 # cs-feat-ff
 
-用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护。
+用户让你做小功能时本来 AI 就会直接动手——这个技能**不改变这件事**。它只做一件事：动手前把项目里已沉淀的 CodeStable 知识指给你，按需搜一下，写出来的代码就比裸写多一层保护；动手后回写一份**最简的 `{slug}-ff-note.md`** 让这次工作可追溯、可被 cs-arch / cs-req backfill 看到、能纳入 scoped-commit 提交。
 
-很轻：没有 design doc / checklist / 验收清单 / 用户确认。看完指引，该读代码读、该写代码写。
+很轻：没有 design doc / checklist / 验收清单 / 动手前的用户确认。看完指引，该读代码读、该写代码写、写完回写一段话。
 
 ---
 
@@ -101,11 +101,56 @@ design / implement 的硬约束在 fastforward 的精简版。没 design doc 不
 
 ---
 
+## 写完回写 `{slug}-ff-note.md`
+
+代码写完、验证完、用户确认效果 OK **之后**才动这一步——动手前先建空壳会破坏 ff 的轻体感。
+
+### 自动生成 slug
+
+不问用户。规则：
+
+- 从用户最初的请求里抽 2-4 个英文 kebab-case 词概括动作 / 对象（如 "rename-cwd-helper"、"add-export-button"、"fix-toolbar-layout"）
+- 不抽业务名词缩写、不音译中文、保持小写连字符
+- 拿不准就保守一点："tweak-{对象}" / "small-{动作}" 也比强求精准好
+
+最终路径：`codestable/features/YYYY-MM-DD-{slug}/{slug}-ff-note.md`，日期用今天。
+
+### 模板
+
+```markdown
+---
+doc_type: feature-ff-note
+feature: {slug}
+date: YYYY-MM-DD
+requirement: {req-slug 或留空}
+tags: [...]
+---
+
+## 做了什么
+{1-3 句：解决什么需求 / 加了什么能力，业务视角}
+
+## 改了哪些
+- {file:行号区间或函数名} — {一句话说改了什么}
+- ...
+
+## 怎么验证的
+{1-2 句：跑了哪些验证 / 浏览器走通了哪条路径 / 跑了什么测试}
+
+## 顺手发现（可选，不阻塞）
+- {文件:行号} {问题简述} — 不在本次范围
+```
+
+**写得真的轻**：每节就那么几行，不要把它写成迷你 design / 迷你 acceptance。这份文档的目标是"半年后有人看 git log 能跳进来 30 秒搞清楚做了啥"，不是替代标准流程。
+
+落盘后告诉用户："已写 `{slug}-ff-note.md`，本次 fastforward 闭环。"
+
+---
+
 ## 不做什么
 
 - **不写 design doc / checklist / acceptance**——这就是 fastforward 的意义。要写就去 `cs-feat-design`
 - **不跟用户确认方案**——用户让你做小功能就是不想等你开会
-- **不在 `codestable/` 里留新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-learn` / `cs-trick` 写
+- **不在 `codestable/` 里留 `{slug}-ff-note.md` 之外的新文件**——除非发现值得沉淀的坑 / 技巧，另起对话用 `cs-learn` / `cs-trick` 写
 
 ---
 
@@ -122,9 +167,35 @@ design / implement 的硬约束在 fastforward 的精简版。没 design doc 不
 
 ---
 
+## 退出条件
+
+- [ ] 代码写完且用户确认效果 OK
+- [ ] `{slug}-ff-note.md` 已落盘且四节填齐（顺手发现可省）
+- [ ] 没有未对齐的"顺手发现"（都进 ff-note 末节，留给后续）
+
+---
+
+## 收尾提交
+
+按 `codestable/reference/shared-conventions.md` 第 4 节"scoped-commit"规则执行。本通道：
+
+- **提交范围**：本次代码改动 + `{slug}-ff-note.md`
+- ff-note 落盘后告诉用户"已就绪，是否代为 commit？"，用户明确同意才执行
+
+按 `shared-conventions.md` 第 3 节"feature-ff"收尾推荐顺序逐项一句话提示（用户"不用"立即跳过）：
+
+1. 暴露的坑 → "沉淀 learning？（`cs-learn`）"
+2. 拍板的长期约束 → "归档决定？（`cs-decide`）"
+3. 最后问是否代为 scoped-commit
+
+---
+
 ## 容易踩的坑
 
 - 完全跳过知识检索就写——这个技能的唯一理由就是让你搜一下再写
 - 把搜到的 learning / decision 当"参考"而不是"约束"——decision 拍过板，违反要么重新 decision 要么别做
 - 开始写 design doc——fastforward 就是不写 design
 - 发现任务变复杂还硬在 fastforward 推——切回成本远低于带着错误方案改到底
+- **动手前就建 ff-note 空壳**——破坏 fastforward 的轻体感，必须代码 + 验证完才回写
+- **把 ff-note 写成迷你 design / 迷你 acceptance**——四节加一起十几行就够，多了说明这事不该走 fastforward
+- **跳过 ff-note 直接 commit**——和 issue-ff 强制 fix-note 同样的理由：没记录后人追溯不了

cs-feat-impl/SKILL.md

@@ -40,7 +40,7 @@ frontmatter：`doc_type=feature-design` / `feature` 一致 / `status=approved` /
 **标准 design**（节 0/1/2/3/4）：
 - 第 0 节有内容；第 1 节含"明确不做"和复杂度档位
 - 第 2.1 名词层用"现状 → 变化"两段式，每个新增/变更接口至少一个示例 + 来源位置
-- 第 2.2 编排层开头有主流程图，"现状 → 变化"齐全，跨层纪律已记
+- 第 2.2 编排层开头有主流程图，"现状 → 变化"齐全，流程级约束已记
 - 第 2.3 挂载点按"删了它 feature 是否消失"判据，没把内部代码改动误列进来
 - 第 3 节有关键场景清单 + 反向核对项（不含测试代码 / framework 选型）
 
@@ -72,8 +72,13 @@ design 给的 `steps` 是 paradigm 维度切片（编排骨架 → 计算节点
 
 **design 第 2.5 节微重构的衔接**：
 
-- 如果 2.5 结论是"做微重构"，checklist 第 1 步就是它——**独立跑完**（按 2.5 节"行为不变怎么验证"那条核对：编译绿灯 + 现有测试通过 + 对外接口签名零 diff），再进 feature 主体步骤。**不要合并到下一步**——一旦混在一起，行为变更和结构变更就分不开，出问题回滚不到干净中间态
+- 如果 2.5 结论是"做微重构（拆文件）"或"做微重构（重组目录）"，checklist 第 1 步就是它——**独立跑完**，按 2.5 节"行为不变怎么验证"那条核对：
+  - 拆文件：编译绿灯 + 现有测试通过 + 对外接口签名零 diff
+  - 重组目录：编译绿灯 + 现有测试通过 + diff 仅限文件移动 + import 路径更新（**没有任何函数体改动**）
+
+  **不要合并到下一步**——一旦混在一起，行为变更和结构变更就分不开，出问题回滚不到干净中间态
 - 如果 2.5 结论是"不做"但写到中途反射检查触发了拆分信号 → 走下面"反射检查"那条路径（停下来 → 和用户对齐 → 能 provable 解决就追加独立 step），**不要绕过用户确认偷偷追加**
+- 如果 2.5 末尾有"建议沉淀的 convention"段：implement 阶段**不主动归档**——只在重组目录跑通且行为零改动确认后，在汇报里带一句"design 2.5 建议沉淀的 convention 已就绪，等 acceptance 阶段确认是否走 cs-decide"，把决定权交给 acceptance / 用户
 
 ---
 

cs-onboard/reference/shared-conventions.md

@@ -25,9 +25,10 @@ codestable/
 ├── features/              feature spec 聚合根
 │   └── YYYY-MM-DD-{slug}/  每个 feature 一个目录
 │       ├── {slug}-brainstorm.md  （可选，case 2 时产出）
-│       ├── {slug}-design.md
-│       ├── {slug}-checklist.yaml
-│       └── {slug}-acceptance.md
+│       ├── {slug}-design.md      （标准流程）
+│       ├── {slug}-checklist.yaml （标准流程）
+│       ├── {slug}-acceptance.md  （标准流程）
+│       └── {slug}-ff-note.md     （fastforward 通道唯一产物，与上面四份互斥）
 ├── issues/                issue spec 聚合根
 │   └── YYYY-MM-DD-{slug}/
 │       ├── {slug}-report.md
@@ -98,14 +99,14 @@ codestable/
 
 - 是 feature 工作流的唯一执行清单
 - 由 `cs-feat-design` 在 design 确认通过后一次生成 `steps` + `checks`
-- `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道
+- `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-arch / cs-req backfill 检索到）
 
 `steps` 的粒度是 **编排-计算分离维度的切片策略**——按"先编排骨架、后计算节点、最后持久化与测试"写（最简 Workflow 先行 → 逐个节点填充），**不下沉到 file:line / 函数级**。具体改哪个文件由 implement 阶段决定。
 
 **design 的职责**：
 
 - 提取 `steps`（4-8 步，每步独立可验证退出信号）：后端节奏 = 编排骨架 → 计算节点逐个填 → 接通持久化 → 测试覆盖；前端 = 静态结构 → 交互逻辑 → 状态接入 → 联调收尾
-- 提取 `checks`：第 1 节"明确不做"→ 范围守护；第 2.1 接口 → 名词契约；第 2.2 主流程 + 跨层纪律 → 编排骨架；第 2.3 挂载点 → 挂载点；第 3 节场景清单 → 验收场景
+- 提取 `checks`：第 1 节"明确不做"→ 范围守护；第 2.1 接口 → 名词契约；第 2.2 主流程 + 流程级约束 → 编排骨架；第 2.3 挂载点 → 挂载点；第 3 节场景清单 → 验收场景
 
 **implement 的职责**：
 
@@ -171,6 +172,12 @@ planned  → dropped      （cs-roadmap update 模式，用户决定不做时改
 2. `cs-decide`：暴露的长期约束
 3. `scoped-commit`
 
+**feature-ff** 收尾按顺序判断（比标准 acceptance 短，没有 architecture / req 回写动作）：
+
+1. `cs-learn`：动手过程暴露的坑
+2. `cs-decide`：动手过程拍板的长期约束
+3. `scoped-commit`
+
 **统一规则**：一律一句话提示；用户说"不用"立即跳过；不强制；上游主动提示，下游承接执行。
 
 ---