feat(*): Skill 优化 + Eval 管线 + 架构治理

.claude/CLAUDE.md

@@ -42,7 +42,7 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
 5. **Rules 是分发规范，不是开发规范**：`rules/devpace-rules.md` 面向 Plugin 用户，开发规范在 `.claude/rules/`
 6. **UX 优先**：零摩擦、渐进暴露、副产物非前置、容错恢复（设计原则见 `design.md §2`）
 7. **理论对齐**：新增功能或调整概念模型时，对照 `knowledge/theory.md` 确保一致性
-8. **规范优先，不猜测**：开发 Claude Code 组件时，必须遵循 `.claude/rules/plugin-dev-spec.md` 的规范。对不确定的 API、frontmatter 字段或机制行为，通过 `claude-code-guide` agent 或官方文档查证，禁止凭记忆猜测
+8. **规范优先，不猜测**：开发 Claude Code 组件时，必须遵循 `.claude/rules/plugin-spec.md` 的规范。对不确定的 API、frontmatter 字段或机制行为，通过 `claude-code-guide` agent 或官方文档查证，禁止凭记忆猜测
 
 ## 会话协议
 
@@ -65,8 +65,9 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
 | 战略规划 | `docs/planning/roadmap.md` | 阶段、里程碑、任务定义 |
 | 操作跟踪 | `docs/planning/progress.md` | 当前任务状态、会话历史、变更记录 |
 | 运行时行为规则 | `rules/devpace-rules.md` | 插件加载后 Claude 的行为 |
-| 文件格式契约 | `knowledge/_schema/*.md` | state/project/CR 的字段定义 |
+| 文件格式契约 | `knowledge/_schema/<subdir>/*.md` | 价值链对象/运行时流程/外部集成/辅助支撑的数据格式定义（四组） |
 | 度量指标定义 | `knowledge/metrics.md` | 指标名称、计算方式、用途 |
+| Skill 评估工具 | `eval/` | eval-trigger/eval-fix/eval-regress 自动化管线 |
 
 ### 开发规范索引（.claude/rules/，自动加载）
 
@@ -75,15 +76,11 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
 | `project-structure.md` | 项目目录结构、文件放置规则、配置文件索引；分层架构约束见本文件"分层架构"章节 |
 | `common.md` | 响应语言、Git 提交规范、文档命名 |
 | `dev-workflow.md` | 开发会话协议、任务执行、质量检查、跨会话连续性、文档级联 |
-| `plugin-dev-spec.md` | Claude Code 核心组件规范（Plugin 结构、Skill 规范、常见陷阱；Agent/Hook/MCP 参考见 `references/component-reference.md`） |
-| `info-architecture.md` | 信息架构（devpace 适配）：IA-1 至 IA-11 索引、六层架构映射、约束分级、分发层分离规则；完整原则见 `references/ia-principles.md` |
+| `plugin-spec.md` | devpace Plugin 编写约定（CSO、章节顺序、分拆模式；平台 API 参考见 `references/component-reference.md`） |
+| `ia-principles-details.md` | 信息架构元规则：IA-1 至 IA-11 索引（高冗余原则折叠为指针）、稳定性/分类/权威/预算/分级/职责的独有规则；完整原则见 `references/ia-principles.md` |
+| `product-architecture.md` | 产品层组件架构：依赖矩阵、通信模式、合规检测（详细映射表见 `references/product-arch-details.md`） |
+| `harness-engineering.md` | Harness Engineering 开发原则：环境优先调试、规则是乘数、Agent Legibility、组件设计标准、仓库知识治理 |
 
 ## 质量检查
 
-- plugin.json 与文件系统同步（新增/删除 Skill 后立即更新）
-- 每个 rules/ 和 _schema/ 文件有 §0 速查卡片
-- 模板文件用 `{{PLACEHOLDER}}` 标记需填充的内容
-- Skill 的 SKILL.md 遵循 `.claude/rules/plugin-dev-spec.md` 的 frontmatter 字段定义
-- Skill 分拆模式：详见 `plugin-dev-spec.md` "分拆模式"章节。参考 pace-dev 和 pace-change
-- **分层完整性**：产品层文件不得引用 `docs/` 或 `.claude/`（见分层架构章节）
-- **多处出现内容的同步维护**：修改 Skill 子命令、能力描述、信号定义或 Schema 时，查阅 `.claude/references/sync-checklists.md` 获取完整同步链路和扩展清单
+质量检查流程详见 `dev-workflow.md` §4。补充提醒：修改 Skill 子命令、能力描述、信号定义或 Schema 时，查阅 `.claude/references/sync-checklists.md` 获取完整同步链路。

.claude/references/component-reference.md

@@ -1,10 +1,52 @@
 # Claude Code 组件参考
 
-> **职责**：Agent、Hook、MCP Server 的完整规格参考。按需加载，仅在开发/修改对应组件时使用。
+> **职责**：Claude Code 平台级组件 API 参考（Plugin / Skill / Agent / Hook / MCP）。按需加载。
 >
-> 核心开发规范见 `.claude/rules/plugin-dev-spec.md`（始终加载）。
+> devpace 编写约定见 `plugin-spec.md`（始终加载）。devpace 项目级映射见 `references/product-arch-details.md`。
 
-**章节索引**：[Agent 定义](#agent-定义) | [Hooks](#hooks) | [MCP Server 配置](#mcp-server-配置) | [规范查证方法](#规范查证方法)
+**章节索引**：[Plugin 结构](#plugin-结构) | [plugin.json](#pluginjson) | [SKILL.md Frontmatter](#skillmd-frontmatter) | [Agent 定义](#agent-定义) | [Hooks](#hooks) | [MCP Server 配置](#mcp-server-配置) | [常见陷阱](#常见陷阱) | [官方 plugin-dev 工具](#官方-plugin-dev-工具推荐)
+
+## Plugin 结构
+
+```
+<plugin-name>/
+├── .claude-plugin/
+├── commands/
+├── agents/
+├── skills/
+├── hooks/
+├── rules/
+├── output-styles/
+├── settings.json
+└── .mcp.json
+```
+
+## plugin.json
+
+`name` 是唯一必填字段（当 manifest 存在时），同时作为 Skill 的命名空间前缀（如 `devpace:pace-init`）。
+
+可选字段（均为合法）：`version`、`homepage`、`repository`（字符串）、`license`、`keywords`、`commands`、`agents`、`skills`、`hooks`、`mcpServers`、`outputStyles`、`lspServers`。其中 `commands/skills/agents/hooks/mcpServers` 用于声明**额外**路径（补充默认目录的自动发现，不替代）。所有路径必须相对且以 `./` 开头。
+
+## SKILL.md Frontmatter
+
+每个 Skill 是 `skills/<name>/SKILL.md`。目录名即 Skill 名称。
+
+**合法 frontmatter 字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 显示名称（可选，省略则用目录名） |
+| `description` | 触发条件描述——Claude 据此判断是否自动调用 |
+| `argument-hint` | 自动补全时的参数提示（如 `[CR编号]`） |
+| `allowed-tools` | 激活时免确认的工具，逗号分隔 |
+| `model` | `sonnet` / `opus` / `haiku` |
+| `disable-model-invocation` | `true` = 仅用户可调用，Claude 不会自动调用 |
+| `user-invocable` | `false` = 从 `/` 菜单隐藏，仅 Claude 可调用 |
+| `context` | `fork` = 在子 agent 上下文中运行 |
+| `agent` | 当 `context: fork` 时使用的 agent 类型 |
+| `hooks` | 作用域为此 Skill 的 Hook 配置 |
+
+**字符串替换**：Skill 内容中可使用 `$ARGUMENTS`（全部参数）、`$0`/`$1`（按位参数）、`` !`command` ``（预处理器，执行 shell 命令并替换输出）。
 
 ## Agent 定义
 
@@ -83,7 +125,7 @@ hooks:
           timeout: 15
 ```
 
-Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 级做精细控制。
+Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 级做精细控制。devpace 当前 Skill 级 Hook 配置见 `references/product-arch-details.md` §B。
 
 ### 约束执行分级
 
@@ -114,17 +156,21 @@ Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 
 
 Plugin 内部引用路径时使用 `${CLAUDE_PLUGIN_ROOT}`。也可在 `plugin.json` 的 `mcpServers` 字段内联定义。
 
-## 规范查证方法
-
-不确定时，按优先级查证：
+## 常见陷阱
 
-1. `Task(subagent_type="claude-code-guide", prompt="查询 [具体问题]")`——内置 agent，可访问官方文档
-2. 官方文档：`https://code.claude.com/docs/en/`（plugins、skills、hooks、mcp、sub-agents、agent-teams）
-3. `claude --debug` 查看加载日志排查问题
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 组件放在 `.claude-plugin/` 内 | 只有 plugin.json 和 marketplace.json 在此目录 | 移到 Plugin 根目录 |
+| Command frontmatter 含 `name` | Command 名由文件名决定 | 删除 `name`（SKILL.md 中合法） |
+| Skill 不触发 | `description` 过于模糊 | 写明具体触发关键词 |
+| Hook 不执行 | 脚本无执行权限或缺 shebang | `chmod +x` + `#!/bin/bash` |
+| Hook 事件名大小写错误 | 事件名区分大小写 | `PostToolUse` 而非 `postToolUse` |
+| Plugin 路径用绝对路径 | 必须相对且以 `./` 开头 | 改为相对路径 |
+| MCP 环境变量不展开 | 语法错误 | 使用 `${VAR}` 或 `${VAR:-default}` |
 
-### 官方 plugin-dev 工具（推荐）
+## 官方 plugin-dev 工具（推荐）
 
-Anthropic 官方 plugin-dev Plugin 提供综合开发工具。安装后可用于 devpace 开发验证：
+查证优先级见 `plugin-spec.md` §0。Anthropic 官方 plugin-dev Plugin 提供综合开发工具：
 
 | 组件 | 用途 | 使用场景 |
 |------|------|---------|

.claude/references/ia-principles.md

@@ -1,8 +1,8 @@
 # 通用信息架构原则
 
 > **职责**：Claude Code 项目信息组织的 11 项通用原则。可跨项目复用，不含特定项目结构映射。
-> **定位**：通用原则定义层——具体项目的适配规则由各项目的 `info-architecture.md` 负责。
-> **按需加载**：本文件由 `info-architecture.md` 按需引用，不自动加载到上下文。
+> **定位**：通用原则定义层——具体项目的适配规则由各项目的 `ia-principles-details.md` 负责。
+> **按需加载**：本文件由 `ia-principles-details.md` 按需引用，不自动加载到上下文。
 
 ## 11 原则
 

.claude/references/product-arch-details.md

@@ -0,0 +1,164 @@
+# 产品层组件架构——详细映射表
+
+> 按需加载。从 `product-architecture.md` §3 引用。
+
+## §0 速查
+
+| 章节 | 内容 | 何时查阅 |
+|------|------|---------|
+| §A | Skill-Agent 路由矩阵 | 创建/修改 Skill 的 fork/inline/model/Hook 配置 |
+| §B | Hook 架构模式 | 创建/修改 Hook、理解事件映射 |
+| §C | Agent 协作架构 | 创建/修改 Agent、理解决策边界 |
+| §D | Skill→Schema 依赖矩阵 | 修改 Schema 前评估影响范围 |
+| §E | 信号系统三方同步 | 修改信号定义时 |
+
+## §A Skill-Agent 路由矩阵
+
+| Skill | Agent (fork) | model | Skill 级 Hooks |
+|-------|-------------|-------|----------------|
+| pace-dev | pace-engineer | sonnet | PreToolUse: scope-check |
+| pace-review | pace-engineer | opus | PreToolUse: scope-check |
+| pace-test | pace-engineer | sonnet | — |
+| pace-feedback | pace-engineer | — | — |
+| pace-release | pace-engineer | — | — |
+| pace-change | pace-pm | sonnet | — |
+| pace-plan | pace-pm | sonnet | — |
+| pace-biz | pace-pm | sonnet | PreToolUse: scope-check |
+| pace-retro | pace-analyst | sonnet | — |
+| pace-guard | pace-analyst | — | — |
+| pace-init | _(inline)_ | — | PreToolUse: scope-check |
+| pace-next | pace-analyst | haiku | — |
+| pace-status | pace-analyst | haiku | — |
+| pace-pulse | pace-analyst | haiku | — |
+| pace-learn | _(inline)_ | — | — |
+| pace-theory | _(inline)_ | — | — |
+| pace-role | _(inline)_ | — | — |
+| pace-trace | _(inline)_ | — | — |
+| pace-sync | _(inline)_ | — | — |
+
+**路由原则**：
+- **fork**：需要写入 `.devpace/` 或执行复杂多步操作的 Skill——提供上下文隔离
+- **inline**：查询型或轻量操作的 Skill——避免子 agent 开销
+- **Agent 鲁棒性**：fork 不可用时静默回退到 inline（rules §13.5）
+
+## §B Hook 架构模式
+
+**全局 vs Skill 级 Hook**：
+
+| 范围 | 配置位置 | 生效条件 |
+|------|---------|---------|
+| 全局 | `hooks/hooks.json` | 始终生效（匹配 matcher） |
+| Skill 级 | SKILL.md `hooks` frontmatter | 仅该 Skill 激活时生效 |
+
+Skill 级 Hook 位于 `hooks/skill/` 目录，命名规范：`pace-xxx-scope-check.mjs`。
+
+**事件-Hook-行为映射表**：
+
+| 事件 | Hook 脚本 | 行为 | 阻断? | 异步? |
+|------|----------|------|-------|-------|
+| SessionStart | session-start.sh | 加载 devpace 上下文，检测 `.devpace/` | 否 | 否 |
+| PreToolUse (Write\|Edit) | pre-tool-use.mjs | 质量检查：路径合规、状态一致性 | 是 (exit 2) | 否 |
+| PostToolUse (Write\|Edit) | post-cr-update.mjs | CR 更新后的连锁检查 | 否 | 是 |
+| PostToolUse (Write\|Edit) | pulse-counter.mjs | 脉搏计数器（节奏检测） | 否 | 是 |
+| PostToolUse (Write\|Edit) | sync-push.mjs | 外部同步推送检查 | 否 | 是 |
+| PostToolUse (Write\|Edit) | post-schema-check.mjs | Schema 合规验证 | 否 | 是 |
+| PostToolUseFailure (Write\|Edit) | post-tool-failure.mjs | 失败恢复检查 | 否 | 否 |
+| UserPromptSubmit | intent-detect.mjs | 意图检测（探索/推进模式判断） | 否 | 是 |
+| PreCompact | pre-compact.sh | 压缩前保存 devpace 状态 | 否 | 否 |
+| Stop | session-stop.sh | 会话检查 | 否 | 否 |
+| SessionEnd | session-end.sh | 最终状态保存 | 否 | 否 |
+| SubagentStop | subagent-stop.mjs | 子 agent 状态检查 | 否 | 否 |
+
+**Skill 级 Hook 映射**：
+
+| Skill | 事件 | Hook 脚本 | 用途 |
+|-------|------|----------|------|
+| pace-dev | PreToolUse (Write\|Edit) | skill/pace-dev-scope-check.mjs | 开发范围守护 |
+| pace-review | PreToolUse (Write\|Edit) | skill/pace-review-scope-check.mjs | 审核范围守护 |
+| pace-init | PreToolUse (Write\|Edit) | skill/pace-init-scope-check.mjs | 初始化范围守护 |
+| pace-biz | PreToolUse (Write\|Edit) | skill/pace-biz-scope-check.mjs | 业务分析范围守护 |
+
+**Hook 通信协议**：
+
+```
+事件触发 → stdin JSON（含 tool_name, file_path 等上下文）
+         → Hook 脚本解析 JSON + 读取 .devpace/ 状态文件
+         → exit 0（放行）| exit 2（阻断 + stderr 提示）| 其他（非阻断错误）
+         → stdout 反馈信息注入会话上下文
+```
+
+**关键约束**：Hook 脚本不解析 `rules/`、`skills/`、`knowledge/` 中的 Markdown 文件——所有状态感知通过 `.devpace/` 运行时文件和 stdin JSON 完成。
+
+## §C Agent 协作架构
+
+**三角色模型**：
+
+| Agent | 职责域 | 核心能力 | 工具权限 |
+|-------|--------|---------|---------|
+| pace-engineer | 工程执行 | CR 实现、质量门、代码变更 | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion |
+| pace-pm | 产品规划 | 迭代规划、变更管理、业务对齐 | Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion |
+| pace-analyst | 度量分析 | 指标收集、回顾分析、趋势报告 | Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion |
+
+**决策边界矩阵**：
+
+| 决策类型 | 决策者 | Agent 角色 |
+|---------|--------|-----------|
+| 代码实现方案 | pace-engineer | 执行 + 建议 |
+| CR 状态转换 | pace-engineer | 执行（受 Gate 约束） |
+| 迭代范围调整 | pace-pm | 建议（需用户确认） |
+| 需求变更评估 | pace-pm | 分析 + 建议 |
+| 度量报告生成 | pace-analyst | 执行 |
+| 风险预警 | pace-analyst | 分析 + 提示 |
+| Gate 3 审批 | **人类** | 不可代替（IR-2） |
+
+**Memory 策略**：Agent 使用 `memory: project`（`.claude/agent-memory/<name>/`）持久化跨会话上下文。下次 fork 到同一 Agent 时自动加载。适用于：迭代上下文延续（pace-pm）、技术决策记忆（pace-engineer）、度量基线记忆（pace-analyst）。
+
+## §D Skill→Schema 依赖矩阵
+
+基于产品层文件的直接路径引用统计。`>` = 直接引用。权威 fan-in 数据见 `knowledge/_schema/README.md`。
+
+| Skill | cr-format | project-format | checks-format | iteration-format | test-strategy | insights-format | 其他 Schema |
+|-------|-----------|---------------|---------------|-----------------|--------------|----------------|-------------|
+| pace-init | | > | > | | | | context-format, integrations-format |
+| pace-dev | > | | | | > | | br-format, pf-format, risk-format, context-format |
+| pace-review | > | | | | | | accept-report-contract |
+| pace-test | > | | | | > | | test-baseline-format |
+| pace-change | > | | | > | | | |
+| pace-plan | | | | > | | | |
+| pace-biz | | > | | | | | epic-format, opportunity-format, readiness-score, merge-strategy |
+| pace-retro | | | | | | > | test-baseline-format |
+| pace-guard | | | | | | | risk-format |
+| pace-feedback | > | | | | | | |
+| pace-release | | | | | | | release-format, integrations-format |
+| pace-learn | | | | | | > | |
+| pace-sync | | | | | | | sync-mapping-format |
+| pace-trace | | | | | | | adr-format |
+| pace-pulse | > | | | | | | |
+| rules | > | | > | > | | | state-format |
+
+### Schema Fan-in 摘要
+
+| Schema 文件 | Fan-in | 稳定性要求 |
+|------------|--------|-----------|
+| cr-format.md | 10 | 极高——变更需评估 5+ Skill 影响 |
+| checks-format.md | 7 | 高——变更需评估 5+ Skill 影响 |
+| iteration-format.md | 4 | 高 |
+| insights-format.md | 4 | 高 |
+| sync-mapping-format.md | 4 | 高 |
+| integrations-format.md | 3 | 中 |
+| test-baseline-format.md | 3 | 中 |
+
+## §E 信号系统三方同步
+
+信号（Signal）驱动 Skill 间的衔接推荐：
+
+```
+signal-priority.md (SSOT)     ← 定义信号优先级
+signal-collection.md           ← 定义信号采集规则
+                                    ↓
+pace-next / pace-pulse / pace-status  ← 消费信号，生成推荐
+                                    ↓
+session-start.sh (推送) → pace-next (拉取，去重)  ← 会话级信号流
+```
+
+三方同步要求：变更信号定义时，`signal-priority.md`、`signal-collection.md`、消费 Skill（next/pulse/status）三者需同步更新。详见 `references/sync-checklists.md`。