feat: add codestable docs neat skill

README.en.md

@@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow
 
 <p>
   <img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
-  <img src="https://img.shields.io/badge/cs--skills-30-6366F1?style=flat-square" alt="CodeStable Skills"/>
+  <img src="https://img.shields.io/badge/cs--skills-32-6366F1?style=flat-square" alt="CodeStable Skills"/>
   <img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
 </p>
 
@@ -110,6 +110,8 @@ CodeStable models real coding work as **6 entities** and **3 flows**.
 | **Issue fixing** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | Tell AI what's wrong → AI finds the root cause → AI fixes precisely |
 | **Refactoring** | `cs-refactor` (beta) | Architectural rot doesn't happen overnight. AI assists, but **humans refactor**. Still iterating — feedback welcome |
 
+At a phase or milestone boundary, use `cs-docs-neat` to reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory so docs do not drift from code.
+
 ---
 
 ## Skill catalog

README.md

@@ -12,7 +12,7 @@
 
 <p>
   <img src="https://img.shields.io/badge/status-beta-F59E0B?style=flat-square" alt="Status"/>
-  <img src="https://img.shields.io/badge/cs--skills-30-6366F1?style=flat-square" alt="CodeStable Skills"/>
+  <img src="https://img.shields.io/badge/cs--skills-32-6366F1?style=flat-square" alt="CodeStable Skills"/>
   <img src="https://img.shields.io/badge/license-MIT-10B981?style=flat-square" alt="License"/>
 </p>
 
@@ -111,6 +111,8 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成
 | **问题修改** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | 跟 AI 说哪里有问题 → 让 AI 分析根因 → 让 AI 定点修复 |
 | **代码重构** | `cs-refactor` (beta) | 软件架构腐化不是一蹴而就的。AI 辅助重构，但**终归是人在重构**——还在迭代中，欢迎赐教 |
 
+阶段或里程碑收尾时，用 `cs-docs-neat` 整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，避免文档与代码脱节。
+
 
 ---
 

SKILL_CATALOG.en.md

@@ -32,3 +32,4 @@
 | Explore and docs | `cs-audit` | Audit code for bug, security, performance, maintainability, and architecture risks |
 | Explore and docs | `cs-guide` | Write outward-facing developer guides |
 | Explore and docs | `cs-libdoc` | Generate reference docs for public library surfaces |
+| Explore and docs | `cs-docs-neat` | Reconcile `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory at phase close |

SKILL_CATALOG.md

@@ -32,3 +32,4 @@
 | 探索与文档 | `cs-audit` | 主动审计代码中的 bug 隐患、安全、性能、可维护性和架构偏离 |
 | 探索与文档 | `cs-guide` | 编写对外开发者指南 |
 | 探索与文档 | `cs-libdoc` | 为库的公开表面生成参考文档 |
+| 探索与文档 | `cs-docs-neat` | 阶段收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆 |

WORKFLOW.en.md

@@ -14,10 +14,11 @@ cs
     ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept
     ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix
     ├── cs-refactor / cs-refactor-ff
-    └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note
+    └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note / cs-docs-neat
 ```
 
 Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow. The cross-cut layer is the knowledge flywheel.
+`cs-docs-neat` is the phase-close cleanup skill: it reconciles `.codestable/`, README/docs, `CLAUDE.md` / `AGENTS.md`, and agent memory without adding a new archive document type.
 
 ## Runtime Structure
 

WORKFLOW.md

@@ -14,10 +14,11 @@ cs
     ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept
     ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix
     ├── cs-refactor / cs-refactor-ff
-    └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note
+    └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note / cs-docs-neat
 ```
 
 纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor。横切层是知识飞轮：任何流程都可以把值得复用的经验沉淀到 compound。
+`cs-docs-neat` 是阶段收尾整理器，负责同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，不新增沉淀文档类型。
 
 ## 运行时结构
 

cs-docs-neat/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: cs-docs-neat
+description: CodeStable 文档与知识库收尾整理技能。用于阶段结束、里程碑完成、准备交接/提交、用户说"整理文档"、"同步记忆"、"更新 AGENTS/CLAUDE"、"收尾"、"这个阶段做完了"、"新人能直接上手"、"docs 过期/冲突了"、"sync up"、"tidy up docs"、"update memory"、"/sync"、"/neat"时，对 `.codestable/`、项目根 `CLAUDE.md` / `AGENTS.md`、README、docs/ 和可用 agent 记忆做全局盘点、反膨胀、补漏和冲突修正。
+---
+
+# cs-docs-neat
+
+## 启动必读
+
+开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。
+
+你是**知识库编辑**，不是记录员。记录员只会追加；编辑要审查全局、合并重复、修正过期、删除废弃，把稳定知识放到正确受众层。目标是让下一位人类、下一次 agent、下游项目都不会被旧文档误导。
+
+不要把任务降级成“补几句文档”。在 AI 协作开发中，代码可以重写，但文档和记忆是跨会话、跨 agent 的桥梁。错误记忆会让下个 agent 基于错误前提动手；混乱 docs 会让接手者浪费时间重新推断系统。
+
+`cs-docs-neat` 不是 `cs-guide`：`cs-guide` 写单篇开发者 / 用户指南；`cs-docs-neat` 做阶段收尾的全局知识库卫生检查和同步。
+
+---
+
+## 四层知识，四种受众
+
+必须先理解分工，否则会只改 `CLAUDE.md` / `AGENTS.md` 就结束，把 docs、`.codestable/` 和记忆晾在一边。
+
+| 层级 | 典型文件 | 读者 | 职责 | 不同步的代价 |
+|---|---|---|---|---|
+| CodeStable 工作流记忆 | `.codestable/attention.md`、`requirements/`、`architecture/`、`roadmap/`、`compound/` | CodeStable 技能和项目维护者 | 软件生命周期事实、长期约束、架构现状、规划、沉淀 | 后续 feature / issue 读到过期事实 |
+| 项目 agent 入口 | `CLAUDE.md`、`AGENTS.md`、平台等价文件 | 当前仓库里的 AI agent | 每次写代码必须遵守的规则、命令、红线、文档索引 | 下次 AI 在项目里走弯路 |
+| 外部读者文档 | `README.md`、`docs/` | 人类同事、下游开发者、未来接手者 | 接入、使用、集成、运维、架构解释 | 人或系统无法正确接入 / 运维 |
+| 外部 agent 记忆 | Claude / Codex / OpenCode 等平台记忆或全局配置 | 某个 agent 跨会话复用 | 个人偏好、跨项目原则、临时教训、权威文档指针 | 个人记忆膨胀或下次忘记历史原则 |
+
+四层都要看。`CLAUDE.md` / `AGENTS.md` 不是 CodeStable spec 的替代品，但它们是 agent 实际会读的入口，必须保持同步。
+
+---
+
+## 毕业机制：把稳定知识往上泵
+
+docs 靠就地编辑收敛，agent memory 天生容易追加膨胀。没有反向阀门，稳定知识会困在几十个松散记忆文件里，既进不了上下文，也没变成别人能看的文档。
+
+**反向阀门 = 毕业（promote）。** 外部 memory 或临时记录满足任一条件，就把内容并进对应项目文档，然后删除原记忆或缩成一行指针：
+
+- 同一主题教训反复出现到第 3 次：它已是稳定知识，不是“最近踩的坑”。
+- 内容讲的是“系统怎么工作”：它属于 `.codestable/architecture/`、README 或 docs。
+- 内容是“X 上线 / 落地 / 就位”的事件记录：现役事实进 docs / architecture，过程归 git log / changelog，memory 不留常驻文件。
+- 内容是项目命令 / 红线 / 环境陷阱：规则进 `CLAUDE.md` / `AGENTS.md`，必要时一行进 `.codestable/attention.md`。
+
+判据一句话：**下一个接手的人（不只是当前 agent）需要知道这件事吗？** 需要，就属于项目文档；不需要，才可能留在个人 memory。
+
+若 memory 文件有类型前缀：`reference_` 通常可长期常驻；`feedback_` 稳定后毕业；`project_` 多数是事件记录，优先毕业或删除。
+
+---
+
+## `CLAUDE.md` / `AGENTS.md` 是规则手册，不是变更日志
+
+最常见翻车模式：每次开发完都在 agent 入口顶部加历史叙事：“2026-05-08 X 功能上线，详见 docs/Y”。一次很爽，半年后真正规则被 200 行历史推到看不见。
+
+判断一条信息该不该进 agent 入口，问：**下次 AI 写代码时如果没看到这条，会不会犯错？**
+
+| 例子 | 进 `CLAUDE.md` / `AGENTS.md`？ | 理由 |
+|---|---|---|
+| “Prisma 查询只写在 `modules/**/data/`” | 是 | 违反就是边界破坏 |
+| “rsync 单文件部署必须用完整 target 路径” | 是 | 命令陷阱会反复踩 |
+| “禁止裸跑 `systemctl stop worker`” | 是 | 红线，事故级 |
+| “2026-05-08 timelineAt 上线，详见 docs/ARCHITECTURE.md” | 否 | 详细机制在 docs；agent 入口只需索引 |
+| “修了 X bug 的复盘细节” | 否 | 单次事故归 learning / runbook 或删除 |
+
+该进 agent 入口：硬边界规则、禁止事项、命令速查、权限模型、协作流程、深入文档指针表、会重复影响实现的踩坑警示。
+
+不该进：历史叙事、详细机制、单次事故复盘、bug fix 流水账、已经由索引表覆盖的“详见 docs/Z”指针句。
+
+---
+
+## Phase 0：尺寸体检（防膨胀）
+
+任何同步动作之前，先量关键文件：
+
+```bash
+wc -l CLAUDE.md AGENTS.md README.md 2>/dev/null
+find docs .codestable -path '*/.git' -prune -o -name '*.md' -print 2>/dev/null | xargs wc -l
+```
+
+再查外部 memory（如存在）：
+
+```bash
+wc -l <memory-dir>/MEMORY.md 2>/dev/null
+wc -c <memory-dir>/MEMORY.md 2>/dev/null
+du -sh <memory-dir> docs .codestable 2>/dev/null
+```
+
+阈值和处理：
+
+| 文件 | 上限 | 超过怎么办 |
+|---|---|---|
+| `CLAUDE.md` / `AGENTS.md` | 约 300 行 / 15KB，项目约束更严格时按项目约束 | 先删历史叙事；规则收敛成表；详细机制迁 docs / `.codestable/` |
+| `.codestable/attention.md` | 约 150 行 | 只留启动必读短规则；长解释毕业到 decision / learning / architecture |
+| memory 索引 | Claude `MEMORY.md` ≤ 200 行且 ≤ 25KB | 超出部分可能静默不加载；通过毕业压缩，不硬删稳定知识 |
+| 单条 memory | 约 100 行 | 拆、删，或把稳定机制提升进项目文档后缩成指针 |
+| 单篇 docs | 约 1500 行；项目有更严格上限时按项目约束 | 拆分并建索引；若用户要求先确认，只列建议不擅自拆 |
+
+额外查体量倒挂：健康态是项目文档厚、memory 薄。memory 比 docs / `.codestable/` 更厚，通常说明稳定知识还赖在个人记忆里。
+
+**执行顺序**：先精简（破除膨胀）→ 再补本次增量。两件事不要混：精简时问“什么不该在这”，补漏时问“什么该补到这”。
+
+---
+
+## Phase 1：机械式枚举（不能跳）
+
+先 `ls` / `find`，再判断。不要凭印象挑几个文件。
+
+1. 读 `.codestable/attention.md`。
+2. 枚举 `.codestable/`：
+   - `ls .codestable/`
+   - `find .codestable -maxdepth 3 -type f \( -name '*.md' -o -name '*.yaml' \) | sort`
+3. 枚举项目根 markdown：
+   - `README.md`
+   - `CLAUDE.md`
+   - `AGENTS.md`
+   - `AGENTS.override.md`
+   - `TEAM_GUIDE.md`
+   - `.agents.md`
+4. 枚举外部文档：
+   - `ls docs/ 2>/dev/null`
+   - `find . -maxdepth 2 -name '*.md' -not -path '*/node_modules/*' -not -path '*/.git/*' | sort`
+5. 查外部 agent 记忆路径。路径速查见 `references/agent-paths.md`，只读当前平台实际存在的文件。
+6. 回顾本次对话、当前 `git diff`、最近提交，确认本阶段发生了什么。
+
+内部维护一张清单：每个文件标 `评估过 / 要改 / 不用改 / 需用户确认`。漏一个关键文档就不能进入落盘。
+
+---
+
+## Phase 2：变更影响矩阵
+
+不要只看对话里新增了什么事实，要看事实会波及哪些文档层。先查 `references/sync-matrix.md`，再下判断。
+
+常见映射：
+
+- 新 API / 路由：`CLAUDE.md` / `AGENTS.md` 速查 + integration / dev guide + architecture routes。
+- 新环境变量：agent 入口环境变量表 + README setup + runbook + 下游 integration guide。
+- 新数据库表 / schema：architecture data model + dev guide；必要时 agent 入口加迁移 / 测试规则。
+- 新大特性：requirements / architecture / roadmap / user guide / dev guide 都可能受影响。
+- 新长期约束：decision + agent 入口执行规则；若每次 CodeStable 启动都得知道，再进 attention。
+- 踩坑或调试路径：learning；如果会反复影响实现，再提炼一行进 agent 入口或 attention。
+- 文档结构变化：README / docs index / agent 入口文档指针同步。
+
+跨项目要特别小心：上游 API、SDK、子域、认证、共享环境变量、公共组件变化时，下游项目 docs 也要对齐。当前仓库改完不等于同步完成。
+
+---
+
+## Phase 3：实际修改
+
+必须真的修改文件。只说“建议怎么改”不算完成。
+
+推荐顺序：
+
+1. `.codestable/` 权威层：requirements / architecture / compound / attention。
+2. README / docs：给人和下游看的安装、使用、集成、运维说明。
+3. `CLAUDE.md` / `AGENTS.md`：agent 必须遵守的规则、命令、红线、文档索引。
+4. 外部 memory：毕业、删除、缩指针；全局配置极度克制。
+
+编辑原则：
+
+- **减优于加**：agent 入口净涨幅超过约 30 行就是红灯，回头查是不是在写历史叙事。
+- **合并优于追加**：新信息是旧信息更新就改旧段；新增条目前先 grep 同关键词。
+- **删除优于保留**：完成的临时计划、推翻的决策、过期记忆、单次事故流水账要删或归档。
+- **毕业优于内部挪腾**：稳定 memory 不在 memory 里搬家，直接并进项目文档。
+- **精确优于冗长**：一条记忆说一件事。
+- **绝对时间**：写实际日期 `YYYY-MM-DD`，不写“今天 / 最近 / 上周”。
+- **受众不混**：docs 不写“我记得上次”；agent 入口不抄 docs 全文。
+- **指针不重复**：同一事实如果 docs 详写，agent 入口只在文档索引出现一次。
+
+写入规则：
+
+- `.codestable/attention.md`：只放每次 CodeStable skill 启动都必须知道的短规则。
+- `.codestable/architecture/`：只写现状，不写未来计划。
+- `.codestable/requirements/`：写能力愿景和边界，不塞实现细节。
+- `.codestable/compound/`：仍使用 learning / trick / decision / explore；不要新增本技能专属 doc_type。
+- `CLAUDE.md` / `AGENTS.md`：只放 agent 写代码会用到的规则、命令、禁区、索引；不写变更日志。
+- README / docs：面向第一次接触项目的人，保持命令、API、环境变量和代码一致。
+- 全局配置：`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` 只有用户表达跨项目原则时才改；项目细节禁止写全局。
+
+新增一个能力时，通常四处都要补：
+
+1. integration / dev guide：怎么用。
+2. architecture：怎么工作。
+3. runbook / README：怎么运行和排障。
+4. handoff / changelog 或 roadmap：已完成状态。
+
+---
+
+## Phase 4：自检清单
+
+改完后逐项过，哪条不过就回去修。
+
+尺寸 / 反膨胀：
+
+- [ ] `CLAUDE.md` / `AGENTS.md` 净增长 ≤ 30 行；超了已删 / 迁历史叙事。
+- [ ] 没新增“X 起 Y 上线，详见 docs/Z”式历史条目。
+- [ ] 没在 agent 入口复制 docs 已有的详细机制。
+- [ ] `.codestable/attention.md` 没被写成长文。
+- [ ] 单条 memory 没超过约 100 行；稳定内容已毕业。
+- [ ] memory 索引（若有）≤ 平台阈值，Claude `MEMORY.md` ≤ 200 行且 ≤ 25KB。
+- [ ] 没有体量倒挂：memory 不应比项目 docs / `.codestable/` 更厚。
+
+完整性 / 反漏改：
+
+- [ ] Phase 1 枚举到的每个文件都有结论。
+- [ ] memory 索引里的每个链接指向存在文件。
+- [ ] memory 文件 description 和内容对得上。
+- [ ] memory / agent 入口 / docs 之间没有互相矛盾。
+- [ ] agent 入口提到的路径、命令、工具、环境变量在代码中真实存在。
+- [ ] README 的安装 / 运行 / 测试步骤跟代码一致。
+- [ ] 新增 API：integration / dev guide 和 architecture 都出现。
+- [ ] 新增环境变量：README / runbook 和 agent 入口都出现。
+- [ ] 新增数据库表：architecture data model 和相关开发文档都出现。
+- [ ] 跨项目影响已搜索并处理，或列入未处理原因。
+- [ ] 没有相对时间残留：
+  ```bash
+  rg "今天|昨天|刚刚|最近|上周|today|yesterday|recently" .codestable README.md docs CLAUDE.md AGENTS.md 2>/dev/null
+  ```
+- [ ] `git diff` 只包含本次文档 / 知识库整理相关改动。
+
+---
+
+## Phase 5：变更摘要
+
+所有文件修改完之后，再给用户摘要：
+
+```markdown
+## 文档整理完成
+
+### CodeStable
+- `.codestable/attention.md` — ...
+- `.codestable/architecture/...` — ...
+- `.codestable/compound/...` — ...
+
+### Agent 入口
+- `CLAUDE.md` — ...
+- `AGENTS.md` — ...
+
+### README / docs
+- `README.md` — ...
+- `docs/...` — ...
+
+### 外部记忆
+- 更新：...
+- 删除：...
+- 毕业：...
+
+### 未处理
+- ...（需要用户确认或刻意跳过）
+```
+
+只列实际变更。没改的层级写“无变更”即可。
+
+---
+
+## 特殊情况
+
+- 项目还没有 README 或 `CLAUDE.md` / `AGENTS.md`：如果已有可运行代码就创建；还在早期探索就跳过并说明。
+- 对话没有产生新事实：仍要审查现有文档是否过期、冲突、含相对时间。
+- 记忆之间出现无法判断的矛盾：列到“未处理”让用户决定；这是少数需要用户介入的情况。
+- 跨项目改动：每个项目都跑一遍 Phase 1，不要假设上游文档改了下游就不用改。
+- 发现之前同步漏了东西：直接修掉，不要说“那不是这次对话的事”。
+- 用户明确要求先确认大文档拆分：只给拆分建议和依据，不擅自重组。
+
+---
+
+## 与其他技能的关系
+
+| 技能 | 关系 |
+|---|---|
+| `cs-onboard` | 仓库未接入或需要迁移归档时先 onboard；本技能不负责搭骨架 |
+| `cs-guide` | 发现缺对外指南时建议或触发；已有指南过期可直接小修 |
+| `cs-libdoc` | 公开 API 参考缺失或过期时建议 libdoc；本技能不批量生成 API 参考 |
+| `cs-learn` / `cs-trick` / `cs-decide` / `cs-explore` | 发现稳定知识要归档时使用这些既有 doc_type |
+| `cs-note` | 发现一两行启动必读硬约束时，可建议或更新 attention |
+| `cs-feat-accept` / `cs-issue-fix` / `cs-feat-ff` | 阶段结束后触发 neat 做全局同步 |
+
+---
+
+## 参考资料
+
+- `references/sync-matrix.md` — 变化类型到文档层的映射
+- `references/agent-paths.md` — 外部 agent 记忆与配置路径速查

cs-docs-neat/references/agent-paths.md

@@ -0,0 +1,58 @@
+# Agent 记忆与入口路径速查
+
+执行 `cs-docs-neat` 时按当前实际存在的文件读取。没有独立 memory 的平台就跳过 memory 层，但仍要检查项目根 agent 入口。
+
+## 项目根 agent 入口
+
+| 文件 | 用途 |
+|---|---|
+| `CLAUDE.md` | Claude Code 项目级指令 |
+| `AGENTS.md` | Codex 项目级指令 |
+| `AGENTS.override.md` | Codex 同目录 override，存在时必须读 |
+| `TEAM_GUIDE.md` / `.agents.md` | 部分团队或工具的 fallback 入口，存在时读 |
+
+这些文件需要同步，但只放 agent 执行需要的规则、命令、红线、文档索引；不要变成项目 changelog。
+
+## Claude Code
+
+| 用途 | 路径 |
+|---|---|
+| 项目级指令 | 项目根 `CLAUDE.md` |
+| 全局指令 | `~/.claude/CLAUDE.md` |
+| 项目 memory | `~/.claude/projects/<encoded-project-path>/memory/` |
+| memory 索引 | `~/.claude/projects/<...>/memory/MEMORY.md` |
+
+Claude memory 常用 frontmatter：`name`、`description`、`type`。稳定项目事实应毕业到项目文档，memory 留个人偏好或指针。
+
+## OpenAI Codex
+
+| 用途 | 路径 |
+|---|---|
+| 项目级指令 | 项目根 `AGENTS.md` |
+| 项目级 override | `AGENTS.override.md` |
+| 全局指令 | `~/.codex/AGENTS.md` 或 `$CODEX_HOME/AGENTS.md` |
+
+Codex 通常没有独立的项目 memory 文件。项目事实不要写进全局 `AGENTS.md`；应写项目根 `AGENTS.md` 或 `.codestable/`。
+
+## OpenCode
+
+| 用途 | 路径 |
+|---|---|
+| 全局配置 | `~/.config/opencode/` |
+| 项目配置 | `.opencode/` |
+| 项目 skills | `.opencode/skills/`、`.claude/skills/`、`.codex/skills/` |
+
+若 `.opencode/` 内有项目指令或 memory 类文件，按 agent 入口处理。
+
+## OpenClaw
+
+| 用途 | 路径 |
+|---|---|
+| 用户级 skills | `~/.openclaw/skills/` |
+| 项目级 skills | `.openclaw/skills/` |
+
+OpenClaw 没有统一 memory 约定；发现项目级指令文件时按 agent 入口检查。
+
+## 全局配置边界
+
+`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` 等全局配置只有在用户表达了跨项目原则时才改。项目专属事实禁止写全局；把它们迁回项目根或 `.codestable/`。

cs-docs-neat/references/sync-matrix.md

@@ -0,0 +1,52 @@
+# 文档同步影响矩阵
+
+遇到不确定"这次变化要同步哪些文档"时查本表。两个方向都要看：补漏（该加到哪里）和反膨胀（该从哪里删）。
+
+## 先删 / 迁的反模式
+
+| 反模式 | 处理 |
+|---|---|
+| `CLAUDE.md` / `AGENTS.md` 顶部堆"某日某功能上线" | 删除；历史归 git log / changelog，稳定事实归 docs 或 `.codestable/` |
+| agent 入口里复制 architecture / design 的详细机制 | 删除细节，只留规则和文档索引 |
+| `.codestable/attention.md` 写成长篇事故复盘 | 提炼成一行硬约束；细节归 learning / runbook |
+| 外部 memory 描述项目架构 / API / 工作流 | 毕业到 `.codestable/architecture/`、README 或 docs；memory 留指针或删除 |
+| 单次调试流水账长期保留 | 留可复用坑点到 learning；其余删除 |
+| 已被新版本取代的中间态说明 | 保留最终态；旧文档标 superseded 或删除临时记忆 |
+| README 和 docs 命令互相矛盾 | 以代码和实际可运行命令为准统一 |
+
+判断句：下次 agent 写代码时不看这条会犯错吗？会，进 agent 入口或 attention；不会，进 docs / compound / git log，或者删。
+
+## 代码或行为变化 → 文档层
+
+| 变化 | `.codestable/` | `CLAUDE.md` / `AGENTS.md` | README / docs |
+|---|---|---|---|
+| 新增 API / 路由 | architecture routes；必要时 requirement | 路由速查或测试命令，只写 agent 会用到的 | integration / dev guide，示例和错误码 |
+| 新增环境变量 | architecture / decision（如是长期约束） | 本地运行必需变量和禁区 | README setup、operator runbook |
+| 新增数据库表 / schema | architecture data model | 迁移/测试注意事项 | dev guide / architecture docs |
+| 新功能 / 用户流程 | requirement 当前能力；architecture 现状；roadmap 状态 | 相关命令或目录规则 | user guide / README usage |
+| 新长期约束 / 技术选型 | decision；attention 候选 | 必须遵守的规则 | 架构说明或开发者指南 |
+| 踩坑 / 调试路径 | learning；必要时 attention 一行 | 会反复影响实现的红线 | runbook troubleshooting |
+| 公开 API / CLI / 组件表面变化 | architecture 索引或 libdoc 关联 | 测试/发布注意事项 | libdoc / dev guide |
+| 文档结构调整 | reference / system overview 如涉及 CodeStable | 文档索引更新 | README / docs index |
+
+## 外部 memory 毕业规则
+
+| memory 内容 | 处理 |
+|---|---|
+| 个人偏好、跨项目协作原则 | 可留在外部全局记忆 |
+| 项目专属命令 / 红线 | 迁到 `CLAUDE.md` / `AGENTS.md`，必要时同步 `.codestable/attention.md` |
+| 项目架构 / API / 业务能力 | 迁到 `.codestable/architecture/`、requirements 或 docs |
+| 稳定踩坑 | 迁到 `.codestable/compound/` 的 learning |
+| 长期规定 | 迁到 decision，并在 agent 入口保留一行执行规则 |
+| 事件流水账 | 删除；必要时由 git log / changelog 承担 |
+
+## 跨项目影响
+
+以下情况必须搜索下游项目或相关 docs：
+
+- 上游 API / SDK / 协议变更。
+- 共享域名、子域、环境变量、认证方式变化。
+- 公共组件或基础设施升级。
+- 文档里有"如何接入本项目"的说明。
+
+当前仓库改完不代表同步完成；依赖方的 setup / integration 文档也可能要改。

cs-feat-accept/SKILL.md

@@ -298,7 +298,8 @@ final audit 发现任何缺口：
 3. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-guide`）"
 4. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-libdoc`）"
 5. 第 8 节有 attention.md 候选 → 逐条问"候选 X 加到 attention.md 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条**
-6. 最后问是否代为 scoped-commit
+6. 阶段 / 里程碑收尾、准备交接，或本次改动影响 README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆 → "要做一轮文档与记忆整理吗？（`cs-docs-neat`）"
+7. 最后问是否代为 scoped-commit
 
 收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的架构 doc / req doc / roadmap items.yaml + 主文档。
 

cs-feat-ff/SKILL.md

@@ -184,7 +184,8 @@ tags: [...]
 
 1. 暴露的坑 → "沉淀 learning？（`cs-learn`）"
 2. 拍板的长期约束 → "归档决定？（`cs-decide`）"
-3. 最后问是否代为 scoped-commit
+3. 快速改动影响 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）"
+4. 最后问是否代为 scoped-commit
 
 ---
 

cs-issue-fix/SKILL.md

@@ -128,7 +128,8 @@ issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该
 1. 暴露了值得复用的坑点 → "沉淀 learning？（`cs-learn`）"
 2. 沉淀出长期约束 / 规约 / 技术决定 → "归档决定？（`cs-decide`）"
 3. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、CodeStable 技能每次启动都该知道）→ "记到 attention.md？（`cs-note`）"
-4. 最后问是否代为提交。同意时按收尾提交规则执行
+4. 修复暴露了 README/docs、`CLAUDE.md` / `AGENTS.md` 或 agent 记忆不一致 → "做一轮文档与记忆整理吗？（`cs-docs-neat`）"
+5. 最后问是否代为提交。同意时按收尾提交规则执行
 
 建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue-report` 处理别塞这个 PR。
 

cs-onboard/reference/shared-conventions.md

@@ -179,19 +179,27 @@ planned  → dropped      （cs-roadmap update 模式，用户决定不做时改
 2. `cs-decide`：长期约束 / 选型
 3. `cs-guide`：开发者 / 用户指南
 4. `cs-libdoc`：公开 API 参考
-5. `scoped-commit`
+5. `cs-docs-neat`：阶段 / 里程碑收尾时同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆
+6. `scoped-commit`
 
 **issue-fix** 收尾按顺序判断：
 
 1. `cs-learn`：坑点
 2. `cs-decide`：暴露的长期约束
-3. `scoped-commit`
+3. `cs-docs-neat`：修复暴露了文档、agent 入口或记忆不一致时做全局整理
+4. `scoped-commit`
 
 **feature-ff** 收尾按顺序判断（比标准 acceptance 短，没有 architecture / req 回写动作）：
 
 1. `cs-learn`：动手过程暴露的坑
 2. `cs-decide`：动手过程拍板的长期约束
-3. `scoped-commit`
+3. `cs-docs-neat`：快速改动影响 README/docs 或 agent 入口时同步
+4. `scoped-commit`
+
+**roadmap** 收尾按顺序判断：
+
+1. `cs-docs-neat`：roadmap 确认落盘或整个 roadmap goal 完成后，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆
+2. 后续若要自动推进整份 roadmap，再走 `cs-roadmap-impl-goal`
 
 **统一规则**：一律一句话提示；用户说"不用"立即跳过；不强制；上游主动提示，下游承接执行。
 

cs-onboard/reference/system-overview.md

@@ -44,6 +44,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录
 - `cs-feat-design-review` — feature design 人工确认前的只读方案审查 gate
 - `cs-guide` — 写给外部读者的开发者指南 / 用户指南
 - `cs-libdoc` — 为库的公开 API 逐条目生成参考文档
+- `cs-docs-neat` — 阶段 / 里程碑收尾时，全局整理 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆，做反膨胀、补漏和冲突修正
 
 
 ## 场景路由
@@ -68,6 +69,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录
 | 可复用的编程模式、库用法 | `cs-trick` |
 | 开发者指南 / 用户指南 | `cs-guide` |
 | 库 API 参考 | `cs-libdoc` |
+| 阶段收尾 / 整理文档 / 同步 agent 入口 / 新人交接 | `cs-docs-neat` |
 
 完整的操作手册、退出条件、和其他工作流的关系,各子技能里讲。
 
@@ -83,6 +85,8 @@ learning / trick / decision / explore 都是存档文档类型,区别在记录
 
 四者共用 `.codestable/compound/` 目录,靠 frontmatter 的 `doc_type` 字段和文件名中间的类型段(`YYYY-MM-DD-{doc_type}-{slug}.md`)区分。每个子技能只认自己的 `doc_type`,不读写别家产物——**"A 和 B 有什么不同"这种判断由本节负责,子技能里不再重复**。
 
+`cs-docs-neat` 不新增沉淀文档类型。它是收尾整理器：发现该沉淀的知识时，仍然使用 learning / trick / decision / explore 这些既有 doc_type；同时同步 README/docs、`CLAUDE.md` / `AGENTS.md` 和外部 agent 记忆。
+
 
 ## 愿景档案 vs 结构档案 vs 规划档案 vs 单次动作
 

cs-roadmap-impl-goal/SKILL.md

@@ -202,6 +202,7 @@ features:
 - architecture / requirement / roadmap 回写完成
 - 最终审计通过
 - 已做 learning reflection：筛出 pitfall / knowledge 候选，并建议用户确认后再运行 `cs-learn`
+- 已提示用户可运行 `cs-docs-neat`，同步 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md` 和 agent 记忆
 - transcript 打印 `CS_ROADMAP_GOAL_COMPLETE`
 
 注意：goal 会话只自动做学习点反思和候选筛选，不自动写 `.codestable/compound/`。长期知识库归档必须由用户确认后触发 `cs-learn`，按它自己的查重、提炼、review、归档流程执行。

cs-roadmap-impl-goal/references/protocol.md

@@ -362,7 +362,7 @@ CS_ROADMAP_GOAL_COMPLETE
 Roadmap <roadmap-slug> complete.
 Features accepted: <数量>
 Final audit passed.
-Manual follow-up: <事项|none>
+Manual follow-up: <run cs-docs-neat to reconcile docs/memory|none>
 ```
 
 只有 `CS_ROADMAP_GOAL_COMPLETE` 出现，`/goal` 才算满足。

cs-roadmap/SKILL.md

@@ -167,6 +167,8 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划
 
 如果用户想把整份 roadmap 自动推进到底，确认落盘后提示下一步可以走 `cs-roadmap-impl-goal`：它会先完成所有子 feature design + design review，再让用户二次确认，最后输出可直接运行的 goal 指令。
 
+确认落盘后再提示一句："这份 roadmap 已经改变了后续工作入口和文档索引，要不要做一轮文档与记忆整理？（`cs-docs-neat`）" 用户说不用就跳过；这是收尾引导，不是 roadmap 通过条件。
+
 ---
 
 ## 和 feature 流程的衔接

cs/SKILL.md

@@ -88,6 +88,7 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物
 | 一两行的项目注意事项 / 编译特殊设置 / 命令陷阱 / "记到 attention.md" | `cs-note` |
 | 开发者指南 / 用户指南 | `cs-guide` |
 | 库 API 参考 | `cs-libdoc` |
+| 阶段收尾 / 整理文档 / 同步 `CLAUDE.md` 或 `AGENTS.md` / 新人交接 | `cs-docs-neat` |
 | 用户在 feature / issue 流程中间问"下一步" | 路由到对应入口（`cs-feat` / `cs-issue`），让该入口判断当前阶段 |
 
 **判不出来 / 太抽象**："听起来像 {猜测}，但你描述里 {缺什么}。是 {选项 A} 还是 {选项 B}？" 让用户选不要硬猜。
@@ -124,6 +125,7 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物
 - 规定"全项目今后都按 X 来" → `cs-decide`
 - 调查"X 现在是什么样" → `cs-explore`
 - 一两行常驻提示"CodeStable 技能每次启动都得知道 X" → `cs-note`（写到 `.codestable/attention.md`）
+- 阶段收尾后全局检查 `.codestable/`、README/docs、`CLAUDE.md` / `AGENTS.md`、agent 记忆是否同步 → `cs-docs-neat`
 
 判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档 / 常驻提示} 哪一种？"