@colin4k1024/tsp 2.4.1 → 2.4.2

package/README.md

@@ -66,6 +66,7 @@ TSP 整合了多个社区开源框架的精华能力，而非从零构建：
 | **BMAD** | 方法来源（已吸收） | 单入口主链（`/team-help`）、Requirement Challenge、Design Review、Implementation Readiness、Story Slice、`artifact:persist` 落盘、Release→Closeout 收口 |
 | **Graphify** | 社区（`safishamsi/graphify`） | 可选知识图谱能力（brownfield 结构扫描、依赖路径分析、架构问答证据），以 runbook + 本地 skill 接入，不替换 workflow-engine |
 | **GitNexus** | 社区（`abhigyanpatwari/GitNexus`） | 受控可选代码智能能力（MCP 查询、impact、detect_changes、多仓图谱证据），以 runbook + thin skill 接入，不内置依赖 |
+| **Open Design** | 社区（`nexu-io/open-design`） | 受控可选设计工作台能力（本地优先原型、deck、dashboard、mobile flow、`DESIGN.md`、导出 artifact），以 runbook + thin skill 接入，不内置 daemon |
 | **GSD** (Getting Shit Done) | 社区 | Quality Gates 分类法（4 类 gate）、wave-execution、session-continuity、discuss-phase、quick-execution、context-engineering、workflow-forensics |
 | **gstack** | 社区 | brainstorming 苏格拉底式创意探索、cross-model-review 跨模型交叉审查、multi-perspective-review 多视角评审（CEO/Design/Eng/DevEx） |
 | **Superpowers** | 社区 | session-continuity 会话暂停/恢复、subagent-driven-development 子 agent 驱动开发、git-worktree-isolation 任务隔离 |
@@ -73,15 +74,19 @@ TSP 整合了多个社区开源框架的精华能力，而非从零构建：
 | **rtk** (Rust Token Killer) | 社区 | CLI 代理透明命令重写，60-90% token 节约，100+ 命令支持（git/gh/cargo/npm/docker/kubectl/aws） |
 | 社区贡献 | 多方 | UI/UX Pro Max 设计系统、vertical workflow examples、Santa Method 对抗验证、Ralph RFC Pipeline |
 
-### 外部设计 skill 接入
+### 外部设计能力接入
 
-TSP 当前支持把第三方设计 skill 作为外部扩展能力接入使用，其中 [huashu-design](https://github.com/alchaincyf/huashu-design) 是与本平台协同性较高的一项：它偏向高保真设计产出，覆盖 HTML 原生交互原型、浏览器演讲幻灯片、时间轴动画、信息图与 5 维度设计评审；TSP 则负责团队协作、角色分工、handoff、quality gate 与发布收口。
+TSP 当前支持把第三方设计能力作为外部扩展接入使用。设计工具负责高保真 artifact，TSP 负责团队协作、角色分工、handoff、quality gate 与发布收口。
 
-推荐的组合方式是：让 TSP 管任务链路，让 huashu-design 管最终视觉和动效交付。典型场景包括：
+[Open Design](https://github.com/nexu-io/open-design) 是当前已纳入安装面导航的受控可选设计工作台：它提供本地优先 web/daemon、coding-agent CLI 调度、31 个设计 skills、设计系统库、sandbox preview 与 HTML/PDF/PPTX/ZIP/MP4 等导出链路。TSP 侧落点是 [skills/open-design/SKILL.md](skills/open-design/SKILL.md) 与 [docs/runbooks/open-design-integration.md](docs/runbooks/open-design-integration.md)，并通过 `design-prototyping` module 进入 `team` / `full` profile。其中 `full` profile 会自动执行 [scripts/install-open-design.js](scripts/install-open-design.js)，把 Open Design clone/update 到 `~/.tsp/open-design`，并在 `corepack` / `pnpm` 可用时安装依赖。TSP 不 vendoring Open Design 源码、daemon、skills、design-systems 或 SQLite 数据。
 
-- `frontend-engineer` 先在 TSP 流程内收敛页面目标、状态边界和验收标准，再调用 huashu-design 做高保真原型或动画样机。
-- `tech-lead` / `qa-engineer` 在评审阶段把 huashu-design 产出的 HTML demo、deck 或动画作为 UI 证据补充到 review / release 资料里。
-- `product-manager` / `architect` 在方案讨论阶段借助 huashu-design 的设计方向顾问、设计评审与 deck 产出，加速多方案对比。
+[huashu-design](https://github.com/alchaincyf/huashu-design) 仍作为文档级协同能力保留：它偏向高保真设计产出，覆盖 HTML 原生交互原型、浏览器演讲幻灯片、时间轴动画、信息图与 5 维度设计评审。
+
+推荐的组合方式是：让 TSP 管任务链路，让外部设计工具管最终视觉和动效交付。典型场景包括：
+
+- `frontend-engineer` 先在 TSP 流程内收敛页面目标、状态边界和验收标准，再调用 Open Design 或 huashu-design 做高保真原型或动画样机。
+- `tech-lead` / `qa-engineer` 在评审阶段把 HTML demo、deck、dashboard、mobile flow 或动画作为 UI 证据补充到 review / release 资料里。
+- `product-manager` / `architect` 在方案讨论阶段借助设计方向顾问、设计评审与 deck 产出，加速多方案对比。
 
 上游安装方式：
 
@@ -204,6 +209,7 @@ TSP 的公开能力是在多个社区项目、技能仓库和工程方法论的
 | [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 上游能力来源 | ECC harness layer、specialist agents、skills、runtime hooks 与安装工具链的重要参考来源 |
 | [safishamsi/graphify](https://github.com/safishamsi/graphify) | 已吸收并本地化 | 为 brownfield 结构扫描、依赖路径分析与架构问答补充知识图谱能力 |
 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | 受控可选接入 | 为 brownfield MCP 查询、impact、detect_changes 和多仓代码图谱证据提供外部能力；因许可证与 Node 20 要求，不内置依赖 |
+| [nexu-io/open-design](https://github.com/nexu-io/open-design) | 受控可选接入 | 为本地优先原型、deck、dashboard、mobile flow、`DESIGN.md` 与可导出视觉 artifact 提供外部设计工作台；不内置 daemon 或上游源码 |
 | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | 已集成运行时能力 | CLI 透明命令重写与 token 优化能力来源 |
 | [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) | 设计资产来源 | 为 `DESIGN.md` 品牌风格扩展提供参考品牌库 |
 | [alchaincyf/huashu-design](https://github.com/alchaincyf/huashu-design) | 外部协同能力 | 提供高保真原型、HTML slides、动画与设计评审能力；当前仅做文档级接入说明，不内置分发 |

package/docs/.vitepress/config.mts

@@ -0,0 +1,199 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  base: '/harness-engineering/',
+  title: 'Team Skills Platform',
+  description: 'Company-grade role-based Team Skills Platform for AI-assisted development',
+  lang: 'zh-CN',
+  ignoreDeadLinks: true,
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
+  ],
+
+  themeConfig: {
+    logo: '/logo.svg',
+    siteTitle: 'TSP',
+
+    nav: [
+      { text: '首页', link: '/' },
+      { text: '快速开始', link: '/runbooks/claude-quick-start' },
+      { text: '用户指南', link: '/runbooks/team-skills-usage' },
+      {
+        text: '手册',
+        items: [
+          { text: 'Claude 快速开始', link: '/runbooks/claude-quick-start' },
+          { text: 'Codex 快速开始', link: '/runbooks/codex-quick-start' },
+          { text: 'Cursor 快速开始', link: '/runbooks/cursor-quick-start' },
+          { text: 'OpenCode 快速开始', link: '/runbooks/opencode-quick-start' },
+        ],
+      },
+    ],
+
+    sidebar: {
+      '/guides/': [
+        {
+          text: '指南',
+          items: [
+            { text: '安装（入口页）', link: '/guides/installation' },
+            { text: '用户指南（入口页）', link: '/guides/user-guide' },
+            { text: '权威安装文档', link: '/runbooks/claude-quick-start' },
+            { text: '权威使用手册', link: '/runbooks/team-skills-usage' },
+          ],
+        },
+      ],
+      '/runbooks/': [
+        {
+          text: '快速开始',
+          collapsed: false,
+          items: [
+            { text: 'Claude 快速开始', link: '/runbooks/claude-quick-start' },
+            { text: 'Codex 快速开始', link: '/runbooks/codex-quick-start' },
+            { text: 'Cursor 快速开始', link: '/runbooks/cursor-quick-start' },
+            { text: 'OpenCode 快速开始', link: '/runbooks/opencode-quick-start' },
+            { text: '首次主链演练', link: '/runbooks/first-team-workflow-walkthrough' },
+            { text: '项目接入', link: '/runbooks/project-onboarding' },
+            { text: '故障排查', link: '/runbooks/troubleshooting' },
+          ],
+        },
+        {
+          text: '使用场景',
+          collapsed: true,
+          items: [
+            { text: 'Claude 使用场景', link: '/runbooks/claude-usage-scenarios' },
+            { text: 'Codex 使用场景', link: '/runbooks/codex-usage-scenarios' },
+            { text: 'Solo 交付模式', link: '/runbooks/solo-delivery-mode' },
+            { text: 'Solo 单页速查', link: '/runbooks/solo-delivery-one-page' },
+          ],
+        },
+        {
+          text: '提示与对话',
+          collapsed: true,
+          items: [
+            { text: 'Claude 提示模板', link: '/runbooks/claude-conversation-prompt-recipes' },
+            { text: 'Codex 并行模板', link: '/runbooks/codex-parallel-prompt-recipes' },
+            { text: '角色提示模板', link: '/runbooks/role-prompt-recipes' },
+            { text: 'Claude 完整对话示例', link: '/runbooks/claude-end-to-end-conversation-example' },
+            { text: 'Codex 完整对话示例', link: '/runbooks/codex-end-to-end-conversation-example' },
+          ],
+        },
+        {
+          text: '角色操作手册',
+          collapsed: true,
+          items: [
+            { text: '架构师日常', link: '/runbooks/architect-daily-operations' },
+            { text: '后端工程师日常', link: '/runbooks/backend-engineer-daily-operations' },
+            { text: '产品经理对话示例', link: '/runbooks/product-manager-clarification-conversation-example' },
+            { text: '项目经理规划示例', link: '/runbooks/project-manager-planning-conversation-example' },
+            { text: '架构师设计对话', link: '/runbooks/architect-design-conversation-example' },
+            { text: 'QA 评审对话', link: '/runbooks/qa-review-conversation-example' },
+            { text: 'DevOps 发布对话', link: '/runbooks/devops-release-conversation-example' },
+            { text: 'Tech Lead 收口对话', link: '/runbooks/tech-lead-closure-conversation-example' },
+          ],
+        },
+        {
+          text: '速查手册',
+          collapsed: true,
+          items: [
+            { text: '前端 Bugfix 速查', link: '/runbooks/frontend-bugfix-one-page' },
+            { text: '后端 API 交付速查', link: '/runbooks/backend-api-delivery-one-page' },
+            { text: '发布收口速查', link: '/runbooks/release-closure-one-page' },
+          ],
+        },
+        {
+          text: '平台能力',
+          collapsed: true,
+          items: [
+            { text: '命令与能力矩阵', link: '/runbooks/command-and-capability-matrix' },
+            { text: 'ECC Harness 使用', link: '/runbooks/ecc-harness-usage' },
+            { text: '运行时能力概览', link: '/runbooks/runtime-capabilities-overview' },
+            { text: 'Agent 治理', link: '/runbooks/agent-governance' },
+            { text: 'Sub-agent 调用地图', link: '/runbooks/sub-agent-invocation-map' },
+            { text: 'Handoff 治理', link: '/runbooks/handoff-governance' },
+            { text: '错误经验库', link: '/runbooks/error-experience-usage' },
+            { text: '并行执行', link: '/runbooks/parallel-execution-usage' },
+            { text: '进化系统', link: '/runbooks/evolution-usage' },
+            { text: 'Graphify 知识图谱', link: '/runbooks/graphify-knowledge-graph-usage' },
+          ],
+        },
+        {
+          text: '工程实践',
+          collapsed: true,
+          items: [
+            { text: 'Git PR 工作流', link: '/runbooks/git-pr-workflow' },
+            { text: 'AI PR Review 自动化', link: '/runbooks/ai-pr-review-automation' },
+            { text: '契约测试', link: '/runbooks/contract-testing-playbook' },
+            { text: 'Helm 单元测试', link: '/runbooks/helm-unittest-playbook' },
+            { text: '依赖更新自动化', link: '/runbooks/dependency-update-automation' },
+            { text: 'Release Notes 自动化', link: '/runbooks/release-notes-automation' },
+          ],
+        },
+        {
+          text: 'CI/CD 安全门禁',
+          collapsed: true,
+          items: [
+            { text: 'CodeQL 安全门禁', link: '/runbooks/codeql-pr-security-gates' },
+            { text: 'Secret Scanning', link: '/runbooks/secret-scanning-gates' },
+            { text: 'Trivy 安全扫描', link: '/runbooks/trivy-security-gates' },
+            { text: 'Checkov IaC 门禁', link: '/runbooks/checkov-iac-gates' },
+            { text: 'API Lint 门禁', link: '/runbooks/api-lint-gates' },
+            { text: 'API Breaking Change', link: '/runbooks/api-breaking-change-gates' },
+            { text: 'Reviewdog PR 门禁', link: '/runbooks/reviewdog-pr-gates' },
+            { text: 'Scorecard 供应链', link: '/runbooks/scorecard-supply-chain-gates' },
+            { text: 'SBOM 生成', link: '/runbooks/sbom-generation-gates' },
+            { text: 'Cosign 签名', link: '/runbooks/cosign-signing-gates' },
+            { text: 'SLSA 验证', link: '/runbooks/slsa-verification-gates' },
+          ],
+        },
+        {
+          text: '企业扩展',
+          collapsed: true,
+          items: [
+            { text: '企业扩展快速开始', link: '/runbooks/enterprise-extension-quick-start' },
+            { text: '公司技能集成', link: '/runbooks/company-skills-integration' },
+            { text: '公司技能决策框架', link: '/runbooks/company-skills-decision-framework' },
+            { text: '外部能力引入', link: '/runbooks/external-capability-intake' },
+            { text: '企业标准映射', link: '/runbooks/enterprise-standards-mapping' },
+          ],
+        },
+        {
+          text: '历史档案',
+          collapsed: true,
+          items: [
+            { text: '版本收口（2026-03-29）', link: '/runbooks/version-closure-2026-03-29' },
+            { text: '平台能力演示剧本（历史）', link: '/runbooks/platform-capability-demo-script' },
+            { text: '平台能力演示执行记录（历史）', link: '/runbooks/platform-capability-demo-execution-log' },
+            { text: '平台迁移计划（历史）', link: '/plans/team-skills-platform-migration' },
+          ],
+        },
+      ],
+    },
+
+    search: {
+      provider: 'local',
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Colin4k1024/harness-engineering' },
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: '© 2026 Team Skills Platform',
+    },
+
+    outline: {
+      level: [2, 3],
+      label: '页面导航',
+    },
+
+    lastUpdated: {
+      text: '最后更新',
+    },
+
+    docFooter: {
+      prev: '上一页',
+      next: '下一页',
+    },
+  },
+})

package/docs/adr/ADR-001-doc-architecture-integration.md

@@ -0,0 +1,33 @@
+---
+artifact: adr
+task: doc-architecture-demo
+date: 2026-04-01
+role: architect
+status: draft
+---
+
+# ADR-001: Doc Architecture Integration
+
+## 决策信息
+- 编号：ADR-001
+- 标题：将文档架构能力集成到 team 主链
+- 状态：Accepted
+- 决策日期：2026-04-01
+- Owner：architect
+
+## 背景与约束
+- 背景：原能力存在独立文档目录习惯，当前平台要求统一 artifact 持久化。
+- 约束：不得新增并行主命令，不得破坏角色边界。
+
+## 备选方案
+- 方案 A：新增 team-doc-architect 命令。
+- 方案 B：角色内嵌 shared skill + 现有命令契约增强。
+- 结论：采用方案 B。
+
+## 决策结果
+- 采用 `doc-architecture` shared skill。
+- 通过 artifact-standards 与输出契约扩展保证落盘一致性。
+- 回退思路：若复杂度过高，先仅在 tech-lead/architect 启用。
+
+## 后续动作
+- 在后续任务中持续验证主链闭环。

package/docs/guides/README.md

@@ -0,0 +1,5 @@
+# Guides Index
+
+| 文档 | 说明 |
+|------|------|
+| [user-guide.md](user-guide.md) | 完整用户指南，包含项目概述、快速开始、核心概念、命令详解等 |

package/docs/guides/installation.md

@@ -0,0 +1,33 @@
+---
+version: "2.3.0"
+status: active
+created: 2026-04-17
+updated: 2026-04-18
+owner: 工程团队
+doc_tier: redirect
+last_verified: 2026-04-18
+source_of_truth:
+  - ../runbooks/claude-quick-start.md
+  - ../runbooks/codex-quick-start.md
+  - ../runbooks/project-onboarding.md
+  - ../runbooks/troubleshooting.md
+---
+
+# 安装指南（入口页）
+
+本页作为**薄入口**保留，不再承载安装细节。安装与排障的权威内容统一维护在 runbooks：
+
+- Claude：[/runbooks/claude-quick-start](../runbooks/claude-quick-start.md)
+- Codex：[/runbooks/codex-quick-start](../runbooks/codex-quick-start.md)
+- Cursor：[/runbooks/cursor-quick-start](../runbooks/cursor-quick-start.md)
+- OpenCode：[/runbooks/opencode-quick-start](../runbooks/opencode-quick-start.md)
+- 项目接入：[/runbooks/project-onboarding](../runbooks/project-onboarding.md)
+- 故障排查：[/runbooks/troubleshooting](../runbooks/troubleshooting.md)
+
+## 最短路径
+
+1. 选择目标平台 quick start。
+2. 完成安装后先执行 `/team-help`。
+3. 正式任务产出按 `artifact:persist` 写回项目仓库。
+
+> 说明：为避免入口层双写漂移，本页不再维护版本 tarball、脚本细节与示例命令。

package/docs/guides/user-guide.md

@@ -0,0 +1,36 @@
+---
+version: "2.3.0"
+status: active
+created: 2026-04-17
+updated: 2026-04-18
+owner: 工程团队
+doc_tier: redirect
+last_verified: 2026-04-18
+source_of_truth:
+  - ../runbooks/team-skills-usage.md
+  - ../runbooks/command-and-capability-matrix.md
+  - ../runbooks/project-onboarding.md
+  - ../runbooks/troubleshooting.md
+---
+
+# 用户指南（入口页）
+
+本页作为**薄入口**保留，不再维护完整使用手册正文。权威内容统一在 runbooks：
+
+- 主手册：[/runbooks/team-skills-usage](../runbooks/team-skills-usage.md)
+- 命令矩阵：[/runbooks/command-and-capability-matrix](../runbooks/command-and-capability-matrix.md)
+- 项目接入：[/runbooks/project-onboarding](../runbooks/project-onboarding.md)
+- 故障排查：[/runbooks/troubleshooting](../runbooks/troubleshooting.md)
+
+## 推荐阅读顺序
+
+1. `/runbooks/command-and-capability-matrix`
+2. `/runbooks/team-skills-usage`
+3. `/runbooks/project-onboarding`
+4. `/runbooks/troubleshooting`
+
+## 主链入口提醒
+
+无论从哪份手册进入，正式任务都建议先执行 `/team-help` 判断主链入口，再进入 `/team-intake` 或 `/quick`。
+
+> 说明：本页不再维护重复命令清单与安装示例，避免与 runbooks 并行漂移。

package/docs/index.md

@@ -0,0 +1,65 @@
+---
+layout: home
+status: active
+updated: 2026-04-17
+owner: 工程团队
+doc_tier: entry
+last_verified: 2026-04-17
+source_of_truth:
+  - ../README.md
+  - ../AGENTS.md
+  - ./runbooks/command-and-capability-matrix.md
+
+hero:
+  name: Team Skills Platform
+  text: 角色化 AI 研发团队
+  tagline: 200+ Skills · 8 Roles · 多平台支持 — 内置 /team-help、brownfield 补齐与 story-sized execution
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /runbooks/claude-quick-start
+    - theme: alt
+      text: 用户指南
+      link: /runbooks/team-skills-usage
+    - theme: alt
+      text: GitHub
+      link: https://github.com/Colin4k1024/tsp
+
+features:
+  - icon: 🧭
+    title: 单入口主链
+    details: 通过 /team-help 统一判断当前应该进入 intake、plan 还是先补 brownfield 文档、project context 与 readiness 证据，降低首次接入成本。
+  - icon: 👥
+    title: 角色化协作
+    details: Tech Lead 编排 + 产品、架构、前端、后端、测试、运维 8 个专业角色协作，每个角色有明确的职责边界和交接规则。
+  - icon: ⚡
+    title: 200+ AI Skills
+    details: 覆盖调试验证、编排效率、学习记忆、进化复用等多个维度，包含前端工程、后端模式、安全审查、TDD 等专项能力。
+  - icon: 🔧
+    title: 多平台支持
+    details: 一套定义，同时支持 Claude Code、Codex、Cursor、OpenCode 四个平台，通过 npx 一键安装。
+  - icon: 🏗️
+    title: ECC Harness Layer
+    details: Specialist agents、快捷命令、分层规则、运行时 hooks、上下文管理、成本追踪与持续学习等工程增强能力。
+  - icon: 🧩
+    title: BMAD 经验吸收
+    details: 已吸收 implementation-readiness、brownfield/document-project、Story Slice Plan 与阶段化 readiness gate，不额外引入第二套平行框架。
+  - icon: 🕸️
+    title: Graphify 可选能力
+    details: 提供 brownfield 结构扫描、依赖路径分析与架构问答证据，作为 `/team-*` 主链的可选补充而非替代引擎。
+  - icon: 🎨
+    title: 前端治理
+    details: React/Next 优先的工程规范 + UI/UX 设计知识库 + 强制质量门禁，从 intake 到 release 全链路覆盖。
+  - icon: 🏢
+    title: 企业级扩展
+    details: 支持公司领域 Skill 扩展、企业架构治理、组件基线、数据库/缓存规范，可对齐集团标准。
+---
+
+## 文档生命周期字段
+
+| 字段 | 值 | 说明 |
+|------|----|------|
+| `status` | `active` | 首页属于公开入口，作为文档导航首屏 |
+| `doc_tier` | `entry` | 入口层文档；不承载与 runbooks 重复的细节说明 |
+| `last_verified` | `2026-04-17` | 最近一次入口链路回归核对日期 |
+| `source_of_truth` | `README.md`、`AGENTS.md`、`runbooks/command-and-capability-matrix.md` | 命令面与入口说明的权威来源 |

package/docs/memory/backlog.md

@@ -0,0 +1,10 @@
+# Backlog
+
+## 2026-04-21 - Community adoption follow-up
+
+The release-blocking open-source readiness gaps from this round are closed: public installer surface is aligned, support depth is now documented, CI enforces the declared doc/reference gates, and prebuilt binaries are treated as release/package artifacts instead of git-tracked assets.
+
+Next follow-ups are now narrowly adoption-oriented:
+
+- Add minimal quick-start stubs or examples for `antigravity`, `codebuddy`, `gemini`, `copilot`, `windsurf`, and `augment` if community usage warrants it.
+- Keep the new `npm run release:health` summary and `open-source-release-checklist.md` aligned with future support-surface changes.

package/docs/memory/decisions.md

@@ -0,0 +1,43 @@
+# Decisions Log
+
+> 追加策略：每次重大技术决策由主责角色追加，不覆盖历史行。格式：`## YYYY-MM-DD · {标题}`
+
+---
+
+## 2026-03-31 · Memory Persistence Hook 从被动等待改为主动采集
+
+**背景**：原 `session_end.py` 设计依赖 Claude 发送结构化 JSON 结束信号，实际上 Claude 从不发送该信号，导致 hook 永远处于等待状态，经验数据完全不落盘。
+
+**决策**：彻底重写 `session_end.py`，改为主动通过 `git log -15` + `docs/memory/` 文件读取的方式采集经验；`session_start.py` 改为双源加载（repo docs/memory/ + ~/.claude/memory/ 经验文件）。
+
+**影响**：hook 现在不依赖 Claude 输出行为，在任何 session end 场景下都能落盘。Smoke test 验证：15 commits、61 experience capsules。待确认：session_start payload 中 repo_memory_files_found 是否非空（依赖 docs/memory/ 存在）。
+
+---
+
+## 2026-03-31 · Observability Trace Skill 归入公共增强层
+
+**背景**：通用编码链路追踪能力不绑定特定业务系统，适合作为编码类 skill 的公共增强。
+
+**决策**：将这类能力保留在公开增强层，配置给 backend-engineer 和 qa-engineer，而不是作为私有企业扩展的默认依赖。
+
+**影响**：公共仓可以保留通用可观测性说明，而不会默认暴露私有企业发布或权限集成。
+
+---
+
+## 2026-04-01 · 文档架构能力并入 team 主链
+
+**背景**：需要将 eags 风格 discovery/modeling/audit 能力与当前 team-skills 体系整合，并避免并行文档目录。
+
+**决策**：新增 `skills/doc-architecture`，并将其装配到 tech-lead、architect、backend-engineer、frontend-engineer、qa-engineer、devops-engineer。同步增强 artifact 标准、输出契约与模板字段。
+
+**影响**：主链可直接产出并追溯 PRD、Plan、Arch、API、Execute、Test、Release、ADR、Session Summary，不需要新增 team 主命令。
+
+---
+
+## 2026-04-02 · Internal Workflow and Permission Case Studies Moved Out of Public Memory
+
+**背景**：部分记忆条目直接绑定私有流程系统、权限中心和组织专属案例，不适合作为公开仓的默认示例。
+
+**决策**：将组织专属案例从公开记忆层移出，只保留公共运行时、文档架构和平台演进相关的决策记录；私有案例转入 `enterprise` overlay 或私有仓。
+
+**影响**：公开仓的 `docs/memory/` 更适合外部用户阅读，也不会把私有领域案例误当成公共默认路径。

package/docs/memory/lessons-learned.md

@@ -0,0 +1,87 @@
+# Lessons Learned
+
+> 追加策略：由 qa-engineer 或 devops-engineer 在遇到可复用经验时追加。格式：`## YYYY-MM-DD · {标题}`
+
+---
+
+## 2026-03-31 · session_end hook 不能依赖 LLM 主动发送结构化数据
+
+**场景**：设计 memory persistence hook 时，原方案希望 Claude 在会话结束时输出结构化 JSON 摘要，由 hook 捕获存盘。
+
+**问题**：Claude 不会主动向 hook stdin 发送任何结束信号。`while True: line = sys.stdin.readline()` 会永久阻塞，数据永远不落盘。
+
+**建议**：session_end hook 应主动采集，而非被动等待。可读 git log、docs/memory/、changelog 等文件作为替代数据源；不依赖 LLM 在特定格式下产出数据。
+
+---
+
+## 2026-03-31 · _experience.json 文件格式与 SessionSummary dataclass 不兼容
+
+**场景**：session_end.py 在同一目录写入 `{id}.json`（SessionSummary）和 `{id}_experience.json`（experience capsules）两类文件。
+
+**问题**：`memory_store.py` 的 `load_latest_session_summary` 按日期排序读取所有 `.json` 文件，`_experience.json` 字段不同会导致 dataclass 反序列化失败。
+
+**建议**：在 `load_latest_session_summary` 中添加 `if "_experience" in session_file.name: continue` 跳过逻辑；或将两类文件放入不同子目录隔离。
+
+---
+
+## 2026-03-31 · docs/memory/ 目录必须提前初始化
+
+**场景**：session_start.py 重写后从 `docs/memory/project-context.md` 等文件读取上下文，但该目录在项目初始未被创建。
+
+**问题**：`repo_memory_files_found: []` — session_start 运行无报错但上下文为空，导致新会话缺少项目感知。
+
+**建议**：每个接入项目在首次配置 hooks 后，应立即创建 `docs/memory/project-context.md`、`decisions.md`、`lessons-learned.md` 三个基础文件，哪怕内容只是占位符。可在 `docs/runbooks/project-onboarding.md` 中补充这一步骤。
+
+---
+
+## 2026-03-31 · validate_library.py（当前等价 `node scripts/validate-library.js`）的 REQUIRED_ECC_SKILLS 必须与目录同步更新
+
+**场景**：新增 ecc skill（langfuse-coding-trace、harness-audit）后，历史脚本 `validate_library.py`（当前等价 `node scripts/validate-library.js`）仍只检查旧的 9 个 required skills。
+
+**问题**：新 skill 存在但不被验证，脚本 PASS 不代表实际完整性正确。
+
+**建议**：每次在 `skills/` 新增 skill 时，同步更新 `scripts/validate-library.js` 中的 `REQUIRED_ECC_SKILLS` 列表；可考虑改为动态读取 `skills/` 自动发现。
+
+---
+
+## 2026-04-01 · 文档能力整合优先走 artifacts 映射而非新目录
+
+**场景**：将外部文档能力并入 team-skills 主链。
+
+**问题**：若沿用外部目录习惯（architecture/domains/specs/plans/runbooks），会与现有 artifact 持久化规则冲突，导致事实源分裂。
+
+**建议**：统一把 discovery/modeling/audit 内容映射到现有 artifact 文件；新增能力优先通过 shared skill + 输出契约字段扩展落地，不新增并行主命令或并行主目录。
+
+---
+
+## 2026-04-09 · skills 子目录嵌套会阻止 Claude 自动发现
+
+**场景**：skills 按 shared/ecc/company 三层子目录组织（`skills/shared/api-contract`、`skills/ecc/eval-harness`），认为逻辑清晰。
+
+**问题**：Claude Code 只自动扫描 `skills/` 根目录下的 SKILL.md，嵌套一层子目录后 skill 不会出现在可用列表中，用户无法直接使用。
+
+**建议**：所有 skill 统一平铺到 `skills/` 根目录。分类信息通过 manifest module 和 role.yaml 的 recommended_*_skills 字段表达，不依赖目录层级。
+
+---
+
+## 2026-04-09 · JSON 文件中的 Unicode 弯引号导致解析歧义
+
+**场景**：`roles/architect/role.yaml` 中 outputs 字段包含中文弯引号 `"前端页面"`，Node.js `JSON.parse` 报错 position 422。
+
+**问题**：中文弯引号 U+201C/U+201D 在 JSON 字符串内部时，解析器会在遇到 ASCII `"` 时错误地判断字符串终止位置。
+
+**建议**：JSON 文件内的中文引号统一使用 `「」` 或反斜杠转义。CI 可加一条 pre-commit 检查，检测 .yaml/.json 中的 U+201C/U+201D。
+
+---
+
+## 2026-04-09 · 批量路径替换后验证脚本需单独修复
+
+**场景**：sed 全局替换了 `skills/shared/` → `skills/`，文档和配置文件正确，但验证脚本内部 `path.join(root, "skills", "shared", skill)` 硬编码路径未被替换。
+
+**问题**：验证脚本通过 string concat 拼路径，sed 替换 markdown/JSON 中的字符串引用时不会命中 JS/Python 代码中的路径拼接。
+
+**建议**：路径替换后，必须单独 grep 验证脚本中的硬编码子目录名（如 `"shared"`、`"ecc"`、`"company"`），并运行验证脚本确认。
+
+## 2026-04-17 - BMAD Source Adoption v2.2 closeout
+
+Closeout readiness for /team-closeout depends on complete artifacts (prd, delivery-plan, handoff, execute/review/release docs). When continuing from mid-stream work, run a gate completeness check early to avoid end-stage backfill.