@colin4k1024/tsp 2.4.1 → 2.4.2

package/docs/runbooks/dependency-update-automation.md

@@ -0,0 +1,83 @@
+# Dependency Update 自动化手册
+
+本手册承接 `renovatebot/renovate` 的工程实践，用于规范依赖升级自动化的接入方式。它补的是“如何持续发现、批量整理、分层 triage 和安全落回 PR / 发布链”这一层，不替代人工验证、`dependency-review-gates`、`codeql-pr-security-gates` 或正式发布放行判断。
+
+## 适用场景
+
+- 仓库依赖数量较多，手工跟进安全补丁、次版本升级和锁文件漂移成本很高。
+- 团队希望把依赖升级从“偶尔集中处理”变成“持续小步前进”。
+- 需要把依赖更新按风险分组、按优先级批量处理，并让 PR review 更容易 triage。
+- 希望把依赖升级和测试、发布门禁联动起来，而不是只自动改版本号。
+
+## 不适用场景
+
+- 仓库依赖很少，手工升级已经足够轻量。
+- 团队还没有稳定的测试、回归和发布检查，却想把所有依赖更新都自动合并。
+- 依赖变更会直接影响数据库迁移、API 契约或运行时协议，但团队没有明确的验证链。
+- 期望这份手册替代人工判断、`dependency-review-gates` 或上线放行责任。
+
+## 推荐落地方式
+
+1. 先把依赖更新分层，不要把所有升级都当成同一类风险：
+   - patch / security update：优先自动提 PR
+   - minor update：批量合并，但保留 triage
+   - major update：默认单独 PR 或单独批次
+2. 第一阶段只接少量影响面明确的目录或 package manager，不要一开始全仓库铺开。
+3. 采用“批量发现 + 批量 triage + 分组合并”的节奏：
+   - 先收集可升级项
+   - 再按风险、语言、目录或 owner 分组
+   - 最后只合并已通过验证的批次
+4. 将依赖更新与现有链路分层：
+   - `dependency-review-gates` 负责新增依赖、许可证和已知漏洞检查
+   - QA 角色、`pairwise-test-design` 和相关测试规则负责回归范围判断
+   - `devops-engineer` / `/team-release` 负责放行判断
+   - `dependency-update-automation` 负责持续发现、批量整理和 PR 组织
+5. 对高风险依赖，先保持分支 PR 或草稿 PR，再决定是否自动合并。
+6. 结果必须回写到 `/team-review`、`/team-release` 或 handoff，不让升级结论只停在机器人评论里。
+
+## 最小门禁模型
+
+- `discovery layer`：自动发现可升级依赖、版本差异和安全更新
+- `batching layer`：按语言、目录、风险或 owner 把升级项分批
+- `triage layer`：判断哪些升级是低风险可自动合并，哪些需要人工确认
+- `verification layer`：对应测试、lint、依赖审查和发布前检查
+- `decision layer`：`qa-engineer`、`backend-engineer`、`devops-engineer`、`tech-lead` 决定是否合并或阻塞
+
+重点不是“自动开很多 PR”，而是让 PR 数量、风险和验证成本都可控。
+
+## 重点检查项
+
+- 依赖更新是否有明确的分组策略，而不是把 patch、minor、major 混成一锅
+- 自动生成的 PR 是否包含版本说明、风险提示和需要补测的范围
+- 是否区分安全更新、常规升级和破坏性升级的处理路径
+- 更新后是否能复用现有测试与回归链，而不是每次都临时加命令
+- 是否存在频繁 rebase、冲突重提或重复噪音，导致团队忽略自动化结果
+- 自动合并条件是否过宽，容易把高风险升级悄悄放掉
+
+## 反模式
+
+- 一上来就全仓库自动升级，还默认自动合并。
+- 把所有依赖升级都当成同一优先级，导致高风险升级被批量吞掉。
+- 自动化只负责改版本号，却不补验证建议和 triage 责任。
+- PR 太碎、太多、太乱，最后团队把依赖机器人当噪音源。
+- 只看版本号是否已更新，不看 API 兼容性、许可证变化和锁文件行为。
+
+## 输出回落
+
+- PR 阶段：把批量升级列表、风险分组和建议验证命令写入 PR 描述或 review 结论。
+- 团队协作：在 `/team-review` 中说明哪些依赖升级已经验证，哪些仍需人工 triage。
+- 发布阶段：若某批升级影响放行判断，回写到 `/team-release` 的检查结果或观察项。
+
+## 许可证与使用边界
+
+- `renovatebot/renovate` 采用 AGPL-3.0。
+- 由于其许可证边界较强，当前平台继续保持 `reference-only-runbook` 定位，只吸收方法论、分组策略和 triage 做法，不直接把上游实现并入正式 skill 层。
+- 启用前应确认仓库的 package manager、分支保护、自动合并策略和 PR 处理容量。
+- 如果团队当前还没有稳定测试和依赖审查链，先只启用发现与提 PR，不要直接启用自动合并。
+
+## 参考来源
+
+- [renovatebot/renovate](https://github.com/renovatebot/renovate)
+- [dependency-review-gates.md](dependency-review-gates.md)
+- [qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)
+- [release-plan.md](../../templates/release-plan.md)

package/docs/runbooks/design-md-workflow.md

@@ -0,0 +1,185 @@
+# DESIGN.md Workflow
+
+> **定位**：DESIGN.md 是 AI agent 的设计执行层文件，放在项目根目录后，
+> 前端 agent 读取即可生成视觉一致的 UI，无需 Figma 导出或手写设计规范。
+>
+> 本文说明如何在 Team Skills Platform `/team-*` 工作流中创建、使用和维护 DESIGN.md。
+
+---
+
+## 默认推荐：根目录已有 DESIGN.md
+
+本仓库根目录已内置一份基于 **Notion 风格**（温暖极简，企业管理类）的 `DESIGN.md`，
+可直接使用，无需额外配置。
+
+**直接使用**：前端 agent 读取 `DESIGN.md` 即可，无需操作。
+
+**覆盖为其他风格**（在项目根目录执行）：
+
+```bash
+# 推荐备选风格（企业管理 / SaaS 工具类）
+npx getdesign@latest add linear.app   # SaaS 超极简 / 品牌紫
+npx getdesign@latest add stripe       # 企业渐变 / weight-300 优雅感
+npx getdesign@latest add mintlify     # 文档平台 / 绿色阅读优化
+npx getdesign@latest add hashicorp    # 企业简洁 / 黑白为主
+
+# 执行后 DESIGN.md 将被替换为对应品牌的 token 值
+# 替换后按项目需要编辑定制；完成后 git commit 即可
+```
+
+完整品牌库（69+ 品牌）：https://getdesign.md
+
+---
+
+---
+
+## 为什么需要 DESIGN.md
+
+现有设计流程存在一个传递断层：
+
+```
+design-system-brief.md     → 设计意图（What & Why）
+        ↓  ← ❌ 传递断层：没有具体值
+ui-implementation-plan.md  → 实现指引（How to build）
+```
+
+`design-system-brief` 记录的是**策略**（"用企业管理风格，品牌色为紫色"），
+但前端 agent 在写 `bg-brand` 时不知道具体是哪个紫——是 `#5e6ad2` 还是 `#6366f1`？
+
+DESIGN.md 填补这个断层，提供**可直接使用的具体值**：
+
+```
+design-system-brief.md → DESIGN.md → ui-implementation-plan.md
+     设计意图            具体 token        实现指引
+```
+
+---
+
+## 三种创建路径
+
+### 路径 A — 从品牌参考库选参考（推荐）
+
+适用于：有明确风格偏好，想快速获得高质量起点。
+
+```bash
+# 1. 在项目根目录运行（需要 Node.js）
+npx getdesign@latest add notion        # 企业管理类（温暖极简）
+npx getdesign@latest add linear.app   # SaaS 工具（超极简 / 紫色）
+npx getdesign@latest add mintlify     # 文档平台（绿色 / 阅读优化）
+npx getdesign@latest add stripe       # 企业 SaaS（渐变 / 优雅感）
+
+# 命令会在根目录生成 DESIGN.md（以及可选的 preview.html）
+# 2. 编辑 DESIGN.md，按项目需要调整色值、字体、组件样式
+# 3. 完成后无需其他配置，前端 agent 读取即生效
+```
+
+**品牌选型参考（企业管理类）**：
+
+| 品牌 | 风格 | 适合场景 |
+|------|------|----------|
+| `notion` | 暖白、衬线标题、柔和阴影 | 知识库、文档管理、内容平台 |
+| `linear.app` | 纯黑深色、Inter 字体、品牌紫 | 项目管理、任务追踪、工程工具 |
+| `mintlify` | 绿色强调、清晰排版 | 开发者文档、API 平台 |
+| `hashicorp` | 企业简洁、黑白为主 | 基础设施、运维工具 |
+| `posthog` | 深色仪表盘、数据密集 | 数据分析、监控面板 |
+
+完整列表：[github.com/VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
+
+---
+
+### 路径 B — 从 design-system-brief 提取生成
+
+适用于：已填写 `design-system-brief.md`，需要将设计意图转化为具体 token 值。
+
+1. 打开 [`templates/design-system-brief.md`](../../templates/design-system-brief.md) 查看第 2 节（视觉方向）和第 3 节（Token 策略）。
+2. 复制 [`templates/DESIGN.md`](../../templates/DESIGN.md) 到项目根目录。
+3. 根据 `design-system-brief` 中的视觉方向和 token 策略，逐区块填写具体值：
+   - **Section 02**（色盘）：从 brief 第 3 节 Color token 提取，补充具体 hex 值
+   - **Section 03**（排版）：从 brief 第 3 节 Typography token 提取，补充具体 size/weight
+   - **Section 04**（组件）：参考 brief 第 4 节高风险交互，补充具体组件状态
+4. 同步更新 `design-system-brief.md` 第 7 节，记录引用品牌和定制要点。
+
+---
+
+### 路径 C — 从头填写
+
+适用于：全新项目，没有现成品牌参考，需要从零设计。
+
+1. 复制 [`templates/DESIGN.md`](../../templates/DESIGN.md) 到项目根目录。
+2. 按照 9 个区块逐一填写，删除所有注释行（以 `>` 开头的行）。
+3. 重点先填 Section 02（色盘）、Section 03（排版）、Section 04（组件），其余区块可后续补充。
+4. 提交前请用 [ui-review-checklist.md](../../templates/ui-review-checklist.md) 验证设计的一致性。
+
+---
+
+## 与 `/team-*` 命令的对接
+
+### `/team-intake` 阶段
+
+- `tech-lead` 在 intake 时确认前端设计约束，需要锁定：
+  - **产品类型**（如"企业管理工具"）
+  - **参考品牌**（如"参考 Notion 风格定制"）
+  - 填写 `design-system-brief.md` 第 7 节
+- **输出**：intake 产出的 PRD 应注明"DESIGN.md 参考品牌：`<brand>`"
+
+### `/team-execute` 阶段（前端任务）
+
+- `frontend-engineer` 在开始编码前：
+  1. 检查根目录是否存在 `DESIGN.md`
+  2. 若不存在 → 根据 `design-system-brief` 第 7 节选择路径 A/B/C 创建
+  3. 若存在 → 优先读取，所有 token 值以 DESIGN.md 为准
+- **实现约束**：代码中不允许出现与 DESIGN.md 不一致的硬编码色值
+
+### `/team-review` 阶段
+
+- `qa-engineer` 评审时额外检查：
+  - [ ] 实现色值是否与 DESIGN.md Section 02 一致（无散装硬编码）
+  - [ ] 组件状态（hover / focus / error / disabled）是否符合 Section 04
+  - [ ] 响应式行为是否符合 Section 08 规则
+
+---
+
+## DESIGN.md 在项目中的位置
+
+```
+my-project/
+├── DESIGN.md           ← 放这里（项目根目录，全局共享）
+├── AGENTS.md
+├── src/
+├── docs/
+│   └── artifacts/
+│       └── {slug}/
+│           └── design-system-brief.md   ← 设计意图
+│           └── ui-implementation-plan.md
+```
+
+- **一个项目一个 DESIGN.md**：全局共享，不按任务隔离。
+- 如果一个项目有多个明显差异的子产品（如管理端 + C 端），考虑用 `DESIGN-admin.md` / `DESIGN-consumer.md` 区分，并在 AGENTS.md 中说明各部分引用哪个文件。
+
+---
+
+## 维护策略
+
+### 何时需要更新 DESIGN.md
+
+| 触发条件 | 建议操作 |
+|----------|---------|
+| 品牌色变更 | 更新 Section 02，运行一次 `ui-review-checklist` 回归验证 |
+| 新增重要组件（如 DatePicker / Table） | 在 Section 04 新增组件样式描述 |
+| 设计系统大版本升级 | 重新运行 `npx getdesign@latest add <brand>`，对比 diff 决定采纳哪些变更 |
+| 发现实现与 DESIGN.md 不一致 | 先确认是设计值错误还是实现错误，再对应修改 |
+
+### 不需要更新的情况
+
+- 单个页面的局部样式调整（如调整某个表格的行间距）——这属于组件级变更，在代码注释中说明即可。
+- QA 发现的轻微响应式问题——在 `ui-review-checklist` 记录，不必改 DESIGN.md。
+
+---
+
+## 参考资料
+
+- [templates/DESIGN.md](../../templates/DESIGN.md) — 项目模板（9 区块 + 企业管理风格示例值）
+- [templates/design-system-brief.md](../../templates/design-system-brief.md) — 设计意图模板（含第 7 节 DESIGN.md 产出）
+- [skills/frontend-ui-ux-system/references/design-md-integration.md](../../skills/frontend-ui-ux-system/references/design-md-integration.md) — DESIGN.md 字段与 token 体系的映射说明
+- [awesome-design-md GitHub](https://github.com/VoltAgent/awesome-design-md) — 69+ 品牌参考库
+- [getdesign.md](https://getdesign.md/) — 在线浏览和预览各品牌 DESIGN.md

package/docs/runbooks/devops-engineer-daily-operations.md

@@ -0,0 +1,60 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# DevOps Engineer 日常操作手册
+
+本文面向 DevOps 工程师，说明发布、回滚、环境变更和线上保障如何在主链中表达。
+
+如果你想先看发布相关命令和验证能力怎么映射，先读 [command-and-capability-matrix.md](command-and-capability-matrix.md)。如果你在排查 observation、cost、budget、compact 对长会话发布协同的影响，再看 [runtime-capabilities-overview.md](runtime-capabilities-overview.md)。
+
+## 1. 你的默认职责
+
+- 评估发布窗口、环境依赖和上线风险
+- 确认回滚条件、监控指标和观察窗口
+- 收口发布步骤与执行记录
+- 在高风险场景下要求补齐验证或回滚准备
+
+## 2. 开始准备发布前必须确认什么
+
+- 当前变更是否具备可发布条件
+- 是否存在数据库、配置或基础设施变更
+- 回滚路径是否清楚
+- 是否需要 GitLab 手动流水线或其他 company 能力
+
+## 3. 发布前的固定检查
+
+- 发布步骤是否可执行
+- 环境变量和配置是否齐全
+- 监控、告警和日志观察项是否明确
+- 失败后是否可以安全回滚
+- 依赖服务是否已经同步
+
+## 4. 进入 release 阶段应交付什么
+
+- 发布步骤与负责人
+- 回滚条件和回滚步骤
+- 观察窗口与核心指标
+- 上线后需继续跟踪的问题
+
+## 5. 常用命令组合
+
+- `/team-plan`：提前识别发布和环境风险
+- `/team-execute`：读取研发侧交付物和验证结果
+- `/verify`：确认上线前关键路径
+- `/handoff`：整理发布输入
+- `/team-release`：形成正式上线方案
+- `/harness-audit`：平台安装、命令入口或文档刚变更后，检查发布侧入口是否同步
+
+## 6. 常见错误
+
+- 只有上线步骤，没有回滚条件
+- 环境变更没有进入 handoff
+- 监控指标没有明确观察窗口
+- 平台入口或发布 runbook 刚变更，却没有用 `/harness-audit` 检查安装和文档链路是否一致
+
+可结合这些演练一起看：[release-governance-reading-path.md](release-governance-reading-path.md)、[pre-release-checklist.md](pre-release-checklist.md)、、、[devops-release-conversation-example.md](devops-release-conversation-example.md)、[hotfix-emergency-release-walkthrough.md](hotfix-emergency-release-walkthrough.md)、[multi-service-backend-integration-walkthrough.md](multi-service-backend-integration-walkthrough.md)

package/docs/runbooks/devops-release-conversation-example.md

@@ -0,0 +1,88 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# DevOps 发布对话样例
+
+本文给出一份偏 DevOps 视角的成品对话样例，重点展示发布方案、观察窗口、回滚条件和企业扩展执行记录应该如何进入 `/team-release`。
+
+## 1. 场景
+
+- 任务：审批记录查询能力已通过 QA
+- 当前输入：QA 放行建议、研发 handoff、发布窗口已确认
+- 目标：形成正式发布方案
+
+## 2. 用户怎么说
+
+```text
+/team-release
+请以 devops-engineer 视角基于当前测试放行结果，整理发布方案、观察窗口、回滚条件、责任链，并判断是否需要 GitLab 手动流水线或 Langfuse 追踪。
+如果这些能力只是 runbook 补充，而不是正式 custom overlay，也请明确写出。
+```
+
+## 3. 期望结果长什么样
+
+```text
+发布方案
+- 范围：审批记录查询接口、列表页、权限过滤逻辑
+- 方式：先 staging smoke，再 10% 灰度，观察 30 分钟后决定是否全量
+
+上线检查结果
+- QA 放行：通过
+- 环境检查：通过
+- 回滚路径：已确认
+
+放行结论与后续观察项
+- 结论：有条件放行
+- 观察项：错误率、慢请求、审批查询成功率
+
+回滚与监控动作
+- 回滚条件：错误率超过阈值，或关键业务成功率明显下降
+- 回滚步骤：关闭入口开关，回滚服务版本与配置
+- 责任人：devops-engineer、backend-engineer
+
+可选领域扩展执行记录
+- enterprise：未启用
+- runbook：gitlab-manual-pipeline-release、langfuse-coding-trace
+- 说明：本次仅作为发布补充动作，不构成项目长期默认装配
+```
+
+## 4. 不合格结果通常长什么样
+
+```text
+今晚发布，先上线看看，有问题再回滚。
+```
+
+这类结果的问题是：
+
+- 没写观察窗口
+- 没写回滚条件
+- 没写责任链
+- 实际用了 GitLab / Langfuse，却没回写
+
+## 5. DevOps 在对话里最容易漏什么
+
+- 发布前检查是否完成
+- 回滚动作是否可执行
+- 观察窗口与核心指标
+- GitLab、Langfuse 是否只是当前 runbook 补充
+
+## 6. 继续推进时怎么说
+
+如果发布阶段出现异常，下一句通常是：
+
+```text
+当前灰度期间出现异常，请按事故处理视角重新输出 /team-review 结论，并说明是否立即进入回滚。
+```
+
+如果发布完成，需要保留后续记录，下一句通常是：
+
+```text
+请把本次发布观察结果和可选领域扩展执行记录整理成一次 /handoff，供 tech-lead 收口。
+```
+
+与这些文档配合阅读：[devops-engineer-daily-operations.md](devops-engineer-daily-operations.md)、[team-release-example.md](team-release-example.md)、

package/docs/runbooks/doc-architecture-integration.md

@@ -0,0 +1,59 @@
+# Doc Architecture Integration
+
+## 目标
+
+将文档架构能力拆分到现有 `/team-*` 主链，在不新增并行主命令和并行主目录的前提下，持续产出可审计文档。
+
+## 适用范围
+
+- 需要补齐架构文档、服务拆分文档、接口契约文档的任务。
+- 需要在实现与发布阶段保持文档-代码一致性的任务。
+
+## 映射原则
+
+1. 只使用 `docs/artifacts/`、`docs/adr/`、`docs/memory/` 作为落盘事实源。
+2. 原 discovery/modeling/audit 结果必须映射到现有 artifact 文件，不新增平行交付目录。
+3. 角色边界不变：tech-lead 负责 intake/plan 收口，architect 负责方案与契约，qa 负责一致性审计证据。
+
+## 主链落点
+
+### /team-intake
+
+- 记录 Project Profile Card：项目目标、技术栈、架构风格、部署与 API 约束。
+- 产出落点：`prd.md`。
+
+### /team-plan
+
+- 记录 Service Catalog、Communication Matrix、NFR Summary。
+- 若为 brownfield，先记录 Brownfield Context Snapshot：现有模块、外部集成、主要技术债、缺失文档和改造边界；必要时先跑 `/update-codemaps` 再回填。
+- 在进入 execute 前，将需求切成可独立验收的 Story Slice Plan，并把每个 slice 的 owner、依赖、验收标准与 handoff 终点写入 `delivery-plan.md`。
+- 产出落点：`delivery-plan.md`、`arch-design.md`、`api-contract.md`（按需）。
+
+### /team-execute
+
+- 记录实现偏差、契约漂移、事件变更。
+- 产出落点：`execute-log.md`、`docs/adr/`、`docs/memory/decisions.md`（按需）。
+
+### /team-review
+
+- 执行一致性审计：服务名、API、事件、鉴权、索引。
+- 产出落点：`test-plan.md`，并给出阻塞与放行建议。
+
+### /team-release
+
+- 记录部署验证、监控与回滚，以及文档追溯状态。
+- 产出落点：`release-plan.md`、`docs/memory/sessions/*.md`。
+
+## 审计清单（最小版）
+
+1. 服务名在架构文档、契约文档、实现代码中一致。
+2. 核心 API 在契约文档中可追溯。
+3. 关键事件在文档与实现中一一对应。
+4. 鉴权说明与真实权限控制点一致。
+5. INDEX 与各 artifact 文件链接完整可达。
+
+## 推荐执行顺序
+
+1. 先启用 `doc-architecture` shared skill。
+2. 再在 role 装配中接入 tech-lead、architect、backend、frontend、qa、devops。
+3. 最后运行构建与校验脚本，确认平台产物可生成。

package/docs/runbooks/doc-architecture-quick-start.md

@@ -0,0 +1,122 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-04-01
+updated: 2026-04-01
+owner: 工程团队
+---
+
+# Doc Architecture Quick Start
+
+## 目标
+
+在现有 `/team-*` 主链中使用 `doc-architecture` 完成一条最小文档输出链路，不新增额外命令。
+
+## 适用场景
+
+- 补齐架构文档
+- 新系统方案设计
+- 服务拆分与契约梳理
+- 已有文档的演进更新
+
+## 最小使用步骤
+
+### 1. 运行 `/team-intake`
+
+输入至少包含：
+
+- 需求背景
+- 项目目标
+- 技术栈
+- 架构风格
+- 部署方式
+- API 风格
+- 关键约束
+
+推荐提示：
+
+```text
+/team-intake
+目标：补齐订单中心的架构文档
+范围：服务拆分、接口契约、测试与发布文档
+技术栈：Java Spring Boot + MySQL + Redis
+架构风格：微服务
+部署方式：Kubernetes
+API 风格：REST
+约束：需要统一回落到 docs/artifacts、docs/adr、docs/memory
+```
+
+### 2. 运行 `/team-plan`
+
+重点补齐：
+
+- Project Profile Card
+- Service Catalog
+- Communication Matrix
+- NFR Summary
+- Artifact Mapping
+
+推荐提示：
+
+```text
+/team-plan
+基于上一步 intake 结果：
+1. 补齐 Project Profile Card
+2. 拆出 Service Catalog 和 Communication Matrix
+3. 给出 NFR Summary
+4. 明确这些内容分别写入哪些 artifact 文件
+```
+
+### 3. 进入 `/team-execute`
+
+要求实现角色回写：
+
+- 执行偏差
+- 接口或事件漂移
+- 决策记录
+
+### 4. 进入 `/team-review`
+
+要求 QA 核对：
+
+- 服务名一致性
+- API 覆盖一致性
+- 事件覆盖一致性
+- 鉴权一致性
+- 索引与落盘一致性
+
+### 5. 进入 `/team-release`
+
+要求发布侧补齐：
+
+- 发布步骤
+- 验证与监控
+- 回滚方案
+- 文档追溯状态
+
+## 预期产物
+
+- `docs/artifacts/{date}-{slug}/prd.md`
+- `docs/artifacts/{date}-{slug}/delivery-plan.md`
+- `docs/artifacts/{date}-{slug}/arch-design.md`
+- `docs/artifacts/{date}-{slug}/api-contract.md`（按需）
+- `docs/artifacts/{date}-{slug}/execute-log.md`
+- `docs/artifacts/{date}-{slug}/test-plan.md`
+- `docs/artifacts/{date}-{slug}/release-plan.md`
+- `docs/adr/ADR-{NNN}-{slug}.md`（按需）
+- `docs/memory/decisions.md`
+- `docs/memory/lessons-learned.md`
+- `docs/memory/sessions/{date}-{NNN}-{slug}.md`
+
+## 推荐搭配文档
+
+- [doc-architecture-integration.md](doc-architecture-integration.md)
+- [team-command-output-contracts.md](team-command-output-contracts.md)
+- [artifact-persistence.md](artifact-persistence.md)
+- [team-skills-usage.md](team-skills-usage.md)
+
+## 成功标准
+
+1. 主链命令中能明确看到 `doc-architecture` 的使用提示。
+2. 产物全部写入 artifacts/adr/memory。
+3. `node scripts/validate-library.js` 通过。

package/docs/runbooks/document-execution-audit.md

@@ -0,0 +1,32 @@
+# Document Execution Audit
+
+本文记录本轮“整体文档落地性核对”的问题台账，按 `P0 / P1 / P2` 标记风险级别，并说明当前处理状态与残余风险。
+
+## P0
+
+| 问题 | 影响 | 处理状态 |
+|------|------|----------|
+| 主链文档已引入 `领域技能包启用建议`、`技能装配清单`、`领域扩展执行记录` 等输出项，但没有统一输出合同 | 上下游知道要产出什么，却不知道按什么结构交付 | 已通过 [team-command-output-contracts.md](team-command-output-contracts.md) 补齐 |
+| `handoff-contract.md` 未承接 custom overlay 场景输出 | `/team-*` 与 handoff 之间断链，结果无法稳定回落 | 已补齐 conditional 字段要求 |
+| 多数 `skills/` 含占位变量或“按需读取”，但缺少变量解析与输出回落说明 | 实施者会卡在“变量怎么定、结果写到哪里” | 本轮为已挂载的 custom overlay 补齐任务输入合同 |
+
+## P1
+
+| 问题 | 影响 | 处理状态 |
+|------|------|----------|
+| 入口文档、规则、runbook 对三层技能结构虽基本一致，但缺少主链输出合同入口 | 平台理解成本高，实施者不容易找到执行基线 | 已在入口和使用手册中增加 runbook 引用 |
+| `custom-overlay.md` 说明了技能定位，但对“默认挂载 / 可选启用 / 结果回落”不够细 | custom overlay 接入方式理解不完整 | 本轮补充默认挂载、输出回落和合同引用 |
+| 架构设计主链、发布治理 runbook、`frontend-engineering` 和语言 / 后端规则已部分接入 custom overlay 场景，但没有完全说明与主链输出的关系 | 角色知道要看 role skill 或 runbook，不知道如何把结果回写主链 | 本轮补充相关回落说明 |
+
+## P2
+
+| 问题 | 影响 | 处理状态 |
+|------|------|----------|
+| custom overlay 仍保留内部脚手架和过程文档约定，如 `process.md`、`qa-pending.md` | 对非组织内部脚手架项目可读性一般，但不阻塞本平台落地 | 保留，已补充变量来源和主链回落规则 |
+| 历史企业扩展导入区仍包含未正式接入的能力 | 容易误认为可直接安装 | 已在文档中强调其仅是历史导入区 |
+
+## 残余风险
+
+- `skills/` 中部分技能依然强依赖组织内部脚手架、私有权限中心 或集团内部 SDK；这属于领域限制，不属于文档缺口。
+- 若后续继续接入新的原始 skill，必须重复执行本轮核对流程，不能只复制文件。
+- 本轮只精修已挂载、已纳入正式层的 skills；原始导入区未接入项不在深度精修范围内。

package/docs/runbooks/documentation-update-walkthrough.md

@@ -0,0 +1,37 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-28
+updated: 2026-03-28
+owner: 工程团队
+---
+
+# 文档更新协作演练
+
+本文演示代码变更之后，如何判断哪些文档需要同步、由谁补齐、如何验证文档没有脱离事实。
+
+## 1. 场景
+
+- 新增命令、规则或示例后，需要同步 runbook 和 example
+- 目标是避免文档入口存在但内容过时
+
+## 2. 推荐链路
+
+1. `/team-execute`
+2. 触发 `doc-updater` / `docs-lookup` specialist 做文档影响判断
+3. `/handoff`
+4. `/team-review`
+
+## 3. 关键输出
+
+- 哪些文档受影响
+- 哪些链接或示例已同步
+- 哪些文档仍待后续补充
+
+## 4. 常见错误
+
+- 代码改了，README 和 runbook 没更新
+- 只更新一个入口，其他入口继续失联
+- 文档补了，但没有校验链接
+
+与这些文档配合阅读：[specialist-commands-playbook.md](specialist-commands-playbook.md)、[troubleshooting.md](troubleshooting.md)