artifact-chain-assistant 0.8.0

package/adapters/claude/templates/core/test/starter.md

@@ -0,0 +1,70 @@
+# {测试文件名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 测试制品通常是代码文件，此模板提供测试结构指引 -->
+
+## 测试结构指引
+
+### 单元测试
+
+```typescript
+describe('{模块/函数名称}', () => {
+  it('should {预期行为} when {条件}', () => {
+    // Arrange
+    const input = {测试输入};
+
+    // Act
+    const result = {被测函数}(input);
+
+    // Assert
+    expect(result).toEqual({预期输出});
+  });
+
+  it('should throw error when {异常条件}', () => {
+    // Arrange
+    const invalidInput = {无效输入};
+
+    // Act & Assert
+    expect(() => {被测函数}(invalidInput)).toThrow({预期错误});
+  });
+});
+```
+
+### 集成测试
+
+```typescript
+describe('{模块集成}', () => {
+  beforeAll(async () => {
+    // 初始化测试环境
+  });
+
+  afterAll(async () => {
+    // 清理测试环境
+  });
+
+  it('should {集成场景描述}', async () => {
+    // Arrange
+    const {依赖} = await {初始化依赖}();
+
+    // Act
+    const result = await {被测流程}({依赖});
+
+    // Assert
+    expect(result).toMatchObject({预期结果});
+  });
+});
+```
+
+## 测试覆盖要求
+
+- [ ] 正常路径测试
+- [ ] 边界条件测试
+- [ ] 异常路径测试
+- [ ] 性能关键路径测试（如适用）
+
+## 关联制品
+
+<!-- 在源码中使用追溯注释 -->
+<!-- @feature {FEATURE_ID} -->
+<!-- @scenario {SCENARIO_ID} -->
+<!-- @decision {DECISION_ID} -->

package/adapters/claude/templates/extended/ADOPTION-GUIDE.md

@@ -0,0 +1,263 @@
+# Starter 模板采用指南
+
+本指南说明如何将插件 starter 模板定制为项目本地权威模板，以及后续模板升级时的评审流程。
+
+## 概述
+
+`artifact-chain-assistant` 提供的 starter 模板是**入门指导**，不是项目权威。项目采用扩展制品类型时，必须将 starter 模板复制到本地并定制，定制后的模板成为项目权威。
+
+```
+插件 starter 模板（入门指导）
+    ↓ 复制 + 定制
+项目本地模板（权威）
+```
+
+## 采用流程
+
+### 步骤 1：评估是否需要该类型
+
+在采用前，确认项目有对应的本地证据：
+
+| 制品类型 | 启用证据 |
+|---------|---------|
+| `api_contract` | 存在 OpenAPI spec、API 文档或 REST 端点代码 |
+| `cli_contract` | 存在 CLI 入口代码或命令定义 |
+| `data_contract` | 存在数据模型定义或 schema 文件 |
+| `domain_model` | 存在 DDD 聚合、实体或值对象代码 |
+| `database_migration` | 存在数据库 schema 或迁移脚本 |
+| `security_review` | 存在安全审查流程、安全相关代码或 Spring Security 配置 |
+| `performance_budget` | 存在性能测试脚本、监控配置或性能基线文档 |
+| `migration_plan` | 存在迁移规划文档、架构演进方案或系统过渡计划 |
+| `runbook` | 存在运维流程或操作手册 |
+| `deployment_manifest` | 存在部署配置（K8s、Docker 等） |
+| `agent_skill` | 存在 Agent 技能定义文件 |
+| `hook_policy` | 存在 CI/CD hook 配置 |
+
+**规则**：仅当本地证据存在时才启用对应类型。不要因为插件提供了模板就启用。
+
+### 步骤 2：复制 starter 模板到项目本地
+
+```bash
+# 示例：复制 api_contract starter
+cp plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/starter.md \
+   artifacts/templates/api_contract.md
+
+# 示例：复制 review checklist
+cp plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/review-checklist.md \
+   artifacts/templates/api_contract-review-checklist.md
+```
+
+**推荐目录结构**：
+
+```
+artifacts/templates/
+  api_contract.md              # 制品模板
+  api_contract-review-checklist.md  # 审查清单
+  cli_contract.md
+  cli_contract-review-checklist.md
+  ...
+```
+
+### 步骤 3：定制模板内容
+
+定制四个维度：
+
+#### 3.1 定制路径
+
+修改 `artifact-graph.config.yaml` 中的 `types.{type}.paths`，匹配项目实际目录结构：
+
+```yaml
+types:
+  api_contract:
+    paths: ["artifacts/contracts/api/**/*.md"]  # 按项目实际路径调整
+```
+
+#### 3.2 定制 ID 模式
+
+修改 `artifact-graph.config.yaml` 中的 `idPatterns.{type}`，匹配项目命名规范：
+
+```yaml
+idPatterns:
+  api_contract: "^API-\\d+$"  # 或 "{service}-API-{version}" 等项目特定模式
+```
+
+#### 3.3 定制 frontmatter
+
+修改模板中的 frontmatter 字段，匹配项目需求：
+
+```markdown
+---
+id: {API_ID}           # 替换为项目 ID 模式，如 API-001
+title: {API 名称}       # 替换为实际标题
+status: draft           # 按项目状态值调整
+version: {v1}           # 替换为实际版本
+base_url: {基础 URL}    # 替换为实际 URL
+related_features: []    # 填入关联的功能特性 ID
+---
+```
+
+**必须保留的字段**：`id`、`title`、`status`（artifact-graph 依赖这些字段索引）
+
+**可扩展的字段**：根据制品类型添加项目特定字段（如 `api_contract` 的 `base_url`、`version`）
+
+#### 3.4 定制 review checklist
+
+修改审查清单，添加项目特定检查项：
+
+```markdown
+## 项目特定检查项
+
+- [ ] 与项目 API 网关集成点一致
+- [ ] 符合项目安全认证规范
+- [ ] 响应时间满足 SLA 要求
+```
+
+**规则**：项目本地审查规则覆盖插件通用基线。
+
+### 步骤 4：在 artifacts/README.md 中记录模板来源
+
+在项目 `artifacts/README.md` 或模板目录的 README 中记录：
+
+```markdown
+## 扩展制品模板
+
+本项目采用以下扩展制品类型，模板来自插件 `templates/extended/`，已定制为本地权威：
+
+| 制品类型 | 模板路径 | 定制日期 | 定制摘要 |
+|---------|---------|---------|---------|
+| api_contract | artifacts/templates/api_contract.md | 2026-07-09 | 添加项目认证规范、调整 ID 模式 |
+| runbook | artifacts/templates/runbook.md | 2026-07-09 | 添加告警关联规则 |
+```
+
+### 步骤 5：更新 config 并验证
+
+```bash
+# 1. 更新 config
+# 编辑 artifact-graph.config.yaml 添加新类型
+
+# 2. 验证图
+artifact-graph validate --root . --warning-only
+
+# 3. 刷新版本锁
+artifact-graph version-lock refresh --all --format markdown
+
+# 4. 审计版本锁
+artifact-graph version-lock audit --root . --strict-missing-lock
+```
+
+### 步骤 6：提交变更
+
+```bash
+git add artifact-graph.config.yaml artifacts/templates/ artifacts/README.md
+git commit -m "feat: adopt api_contract template with local customization"
+```
+
+## 模板升级评审流程
+
+当 `artifact-chain-assistant` 发布新版本且更新了 starter 模板时，已采用项目需要评审是否同步更新本地模板。
+
+### 步骤 1：发现变更
+
+查看插件 `CHANGELOG.md` 或 `templates/extended/` 目录的 git diff：
+
+```bash
+# 查看模板目录变更
+git diff HEAD~1 plugins/artifact-chain-assistant/templates/extended/
+```
+
+### 步骤 2：对比本地模板
+
+使用 diff 工具对比插件 starter 和项目本地模板：
+
+```bash
+# 对比 api_contract 模板
+diff plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/starter.md \
+     artifacts/templates/api_contract.md
+```
+
+**diff 关注点**：
+- 插件新增的章节是否对项目有用
+- 插件修改的审查点是否应纳入项目审查清单
+- 插件删除的章节是否项目仍在使用
+
+### 步骤 3：评审决策
+
+| 情况 | 决策 |
+|------|------|
+| 插件新增了有用的章节 | 选择性合入本地模板 |
+| 插件修改了通用审查点 | 评估是否提升项目审查标准 |
+| 插件删除了项目使用的章节 | 保留本地版本，不跟随删除 |
+| 插件模板与本地模板冲突 | 以本地模板为准，插件仅作参考 |
+
+**核心原则**：项目本地模板是权威，插件 starter 是参考。不要盲目同步。
+
+### 步骤 4：选择性合并
+
+手动合并有用的变更到本地模板：
+
+```bash
+# 不要直接复制覆盖！手动编辑合并
+vim artifacts/templates/api_contract.md
+```
+
+### 步骤 5：更新审查清单
+
+如果插件更新了 review-checklist.md，评估并选择性合入：
+
+```bash
+# 对比审查清单
+diff plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/review-checklist.md \
+     artifacts/templates/api_contract-review-checklist.md
+```
+
+### 步骤 6：记录升级
+
+在模板目录 README 中记录升级历史：
+
+```markdown
+## 升级历史
+
+| 日期 | 插件版本 | 变更摘要 |
+|------|---------|---------|
+| 2026-07-09 | v1.2.0 | 合入插件新增的"安全认证"章节 |
+```
+
+## 常见问题
+
+### Q: 可以直接引用插件 starter 模板吗？
+
+**A: 不可以。** 插件 starter 是入门指导，不是权威。必须复制到本地定制后使用。
+
+### Q: 插件更新时需要同步吗？
+
+**A: 不需要自动同步。** 评审插件变更，选择性合入有用的部分。本地模板是权威。
+
+### Q: 如何确认模板已定制完成？
+
+**A: 检查清单**：
+- [ ] 模板已复制到 `artifacts/templates/` 或等价位置
+- [ ] frontmatter 字段符合项目 ID 模式
+- [ ] 审查清单包含项目特定检查项
+- [ ] `artifacts/README.md` 已记录模板来源
+- [ ] `artifact-graph.config.yaml` 已添加类型定义
+- [ ] `artifact-graph validate` 通过
+
+### Q: 多个项目可以共享本地模板吗？
+
+**A: 可以，但需各自定制。** 每个项目有独立的 `artifact-graph.config.yaml` 和本地模板，即使内容相似，也是各自维护的权威。
+
+## 与三层权威模型的关系
+
+本指南执行 D-ACA-07 定义的三层权威模型：
+
+| 层级 | 对模板的职责 | 本指南动作 |
+|------|------------|-----------|
+| artifact-graph | 从 config 读取类型定义，索引制品 | 更新 config 的 types 和 idPatterns |
+| artifact-chain-assistant | 提供 starter 模板作入门指导 | 复制 starter 到本地 |
+| 目标项目 | 维护本地模板作权威 | 定制模板、记录来源、建立审查规则 |
+
+## 相关文档
+
+- [templates/extended/README.md](README.md) - Starter 模板目录
+- [扩展制品目录](../../EXTENDED-ARTIFACT-CATALOG.md) - 类型分类、路径/ID 模式、生命周期规则
+- [INSTALL.md](../../INSTALL.md) - 插件安装指南

package/adapters/claude/templates/extended/README.md

@@ -0,0 +1,261 @@
+# 扩展制品 Starter 模板
+
+本目录包含 `artifact-chain-assistant` 插件为扩展制品类型提供的 **starter 模板**。
+
+## 重要声明
+
+**这些是 starter 模板，不是项目权威模板。**
+
+项目采用后，应：
+1. 复制到项目本地 `artifacts/templates/` 或等价位置
+2. 根据项目需求定制内容
+3. 本地定制后的模板成为项目权威
+4. 插件 starter 仅作入门指导参考
+
+## 模板目录
+
+### 契约类制品（contracts）
+
+- **api_contract** - REST/GraphQL/gRPC API 接口契约
+  - 路径：`contracts/api_contract/starter.md`
+  - 用途：定义 API 端点、请求/响应格式、错误码
+
+- **cli_contract** - 命令行工具接口契约
+  - 路径：`contracts/cli_contract/starter.md`
+  - 用途：定义 CLI 命令、参数、退出码、配置
+
+- **data_contract** - 数据模型和数据质量契约
+  - 路径：`contracts/data_contract/starter.md`
+  - 用途：定义数据 schema、质量规则、版本兼容性
+
+- **ui_contract** - 用户界面交互流程契约
+  - 路径：`contracts/ui_contract/starter.md`
+  - 用途：定义 UI 流程、状态转换、交互元素、可访问性要求
+  - 适用：桌面/全栈、Web/SaaS 应用
+
+- **ipc_contract** - 进程间通信契约
+  - 路径：`contracts/ipc_contract/starter.md`
+  - 用途：定义 IPC 通道、消息格式、前后端边界、序列化规范
+  - 适用：桌面/全栈（Tauri/Electron）应用
+
+- **report_contract** - 报告生成契约
+  - 路径：`contracts/report_contract/starter.md`
+  - 用途：定义报告字段、聚合逻辑、输出格式、时间窗口语义
+  - 适用：数据平台、BI、企业 Java 项目
+
+- **integration_contract** - 外部系统集成契约
+  - 路径：`contracts/integration_contract/starter.md`
+  - 用途：定义接口协议、超时、重试策略、幂等性、错误分类
+  - 适用：企业 Java、微服务、集成平台项目
+
+- **batch_job_contract** - 批处理作业契约
+  - 路径：`contracts/batch_job_contract/starter.md`
+  - 用途：定义输入/输出格式、调度表达式、幂等性、错误处理、重放策略
+  - 适用：企业 Java、数据平台项目
+
+### 领域与数据制品（domain）
+
+- **domain_model** - 领域模型设计
+  - 路径：`domain/domain_model/starter.md`
+  - 用途：定义聚合边界、领域事件、限界上下文映射、不变量
+
+- **database_migration** - 数据库迁移
+  - 路径：`domain/database_migration/starter.md`
+  - 用途：定义 schema 变更、数据迁移策略、回滚方案、兼容性分析
+  - 适用：企业 Java、有状态服务、数据库驱动项目
+
+### 部署与运维制品（ops）
+
+- **deployment_manifest** - 部署清单
+  - 路径：`ops/deployment_manifest/starter.md`
+  - 用途：定义环境配置、资源分配、健康检查、回滚计划
+
+- **runbook** - 运维操作手册
+  - 路径：`ops/runbook/starter.md`
+  - 用途：定义运维流程、告警处理、回滚步骤
+
+- **security_review** - 安全审查
+  - 路径：`ops/security_review/starter.md`
+  - 用途：定义威胁模型、安全发现项、修复跟踪、合规映射
+  - 适用：企业 Java、安全敏感项目
+
+- **performance_budget** - 性能预算
+  - 路径：`ops/performance_budget/starter.md`
+  - 用途：定义性能指标基线、阈值、回归检测策略、测量方法
+  - 适用：性能敏感项目
+
+- **migration_plan** - 迁移计划
+  - 路径：`ops/migration_plan/starter.md`
+  - 用途：定义迁移阶段、回滚点、数据迁移策略、并行运行期
+  - 适用：大规模迁移、架构演进项目
+
+### 发布治理制品（governance）
+
+- **release_policy** - 发布策略
+  - 路径：`governance/release_policy/starter.md`
+  - 用途：定义版本语义、发布节奏、分支策略、合规要求、回滚方案
+  - 适用：Parent/发布治理仓库、多包 monorepo
+
+- **publish_skill** - 发布技能
+  - 路径：`governance/publish_skill/starter.md`
+  - 用途：定义自动化发布流程、注册中心目标、质量门禁、错误处理
+  - 适用：Parent/发布治理仓库、CI/CD 集成发布
+
+- **oss_compliance** - 开源合规
+  - 路径：`governance/oss_compliance/starter.md`
+  - 用途：定义许可证策略、依赖审查、发布文件清单、安全披露和发布排除规则
+  - 适用：开源项目、Parent/发布治理仓库、多包 monorepo
+
+### Agent 与 Hook 制品（agent）
+
+- **hook_policy** - Hook 策略和门禁规则
+  - 路径：`agent/hook_policy/starter.md`
+  - 用途：定义 CI/CD hook 触发条件、门禁规则、绕过审批
+
+- **agent_skill** - Agent 技能定义
+  - 路径：`agent/agent_skill/starter.md`
+  - 用途：定义 Agent 技能的输入/输出契约、处理流程、权限边界
+
+- **prompt_packet** - Prompt Packet 上下文包
+  - 路径：`agent/prompt_packet/starter.md`
+  - 用途：定义 AI 辅助任务的上下文组装、Prompt 模板、Token 预算
+  - 适用：Agent/插件工具包、AI 辅助开发流程
+
+## 模板使用方式
+
+### Bootstrap 阶段
+
+1. `artifact-chain-bootstrap` 技能根据项目形态选择最小可用 profile
+2. bootstrap 技能引用本目录的 starter 模板生成初始制品结构
+3. 在 `artifacts/README.md` 中记录模板来源
+
+### 采用阶段
+
+1. 项目团队审阅 starter 模板
+2. 决定哪些章节保留、哪些修改、哪些删除
+3. 复制到项目本地 `artifacts/templates/` 或等价位置
+4. 修改后的模板成为项目本地权威
+
+### 成熟阶段
+
+1. 项目在本地维护完整的模板库
+2. 完全不再引用插件 starter
+3. 插件 starter 仅在新成员加入或新类型启用时被参考
+
+## 模板内容说明
+
+### starter.md
+
+每个类型的 `starter.md` 包含：
+- 制品 frontmatter 结构（id, title, status, version 等）
+- 最小填写指引
+- 关键章节说明
+- 关联制品示例
+
+**使用建议**：
+- 复制到项目本地后修改
+- 根据项目需求调整章节
+- 删除不适用的章节
+- 添加项目特定的章节
+
+### review-checklist.md
+
+每个类型的 `review-checklist.md` 包含：
+- 结构完整性检查
+- 内容质量检查
+- 追溯性检查
+- 生命周期检查
+
+**使用建议**：
+- 作为审查基线参考
+- 根据项目标准调整检查项
+- 添加项目特定的检查项
+- 在审查技能中引用
+
+## Bootstrap 裁剪策略
+
+bootstrap 的职责是根据项目形态选择**最小可用 profile**，而非启用所有已知类型。
+
+裁剪规则：
+
+1. **基础集合始终启用**：`feature`、`scenario`、`decision`、`design`、`test`、`e2e_test`
+2. **契约类按证据加入**：仅当项目本地存在对应的接口文件时启用
+3. **领域与数据类按项目形态加入**：企业 Java/DDD 项目可启用 `domain_model`；有数据库的项目可启用 `database_migration`
+4. **运维类按运维流程加入**：仅有部署配置文件、安全审查流程、性能管理需求或迁移计划的项目才启用对应类型
+5. **Agent/Hook 类按本地文件加入**：仅当项目存在 `skills/`、`policies/` 或 hook 配置文件时启用
+6. **发布治理类按治理需求加入**：仅当项目是 Parent/发布治理仓库且有发布流程或开源合规文件时启用 `release_policy`、`publish_skill`、`oss_compliance`
+7. **渐进扩展**：项目随成熟度增长，可按需添加新类型
+
+## 扩展制品目录设计
+
+本目录的模板结构遵循扩展制品目录规范：
+
+- 模板目录按类别组织（contracts、domain、ops、governance、agent），每类含 starter.md 和 review-checklist.md
+- 模板来源遵循权威层级：插件模板是入门指导，项目本地模板是权威
+- Bootstrap 按项目形态裁剪，仅启用有本地证据的类型
+- 模板生命周期：starter → 项目采用定制 → 本地权威
+
+详细的类型目录、推荐路径、ID 模式和生命周期规则，请参考
+[扩展制品目录](../../EXTENDED-ARTIFACT-CATALOG.md)。
+
+## 插件版本升级时的模板同步
+
+当 `artifact-chain-assistant` 发布新版本且包含新的 starter 模板时，已采用项目的同步流程：
+
+### 发现新模板
+
+1. 查看 `CHANGELOG.md` 中的"Extended templates"部分
+2. 浏览 `templates/extended/` 目录，对比项目本地 `artifacts/templates/`
+3. 确认哪些新类型对当前项目形态有用
+
+### 同步步骤
+
+**步骤 1：评估相关性**
+
+根据项目形态决定是否需要新模板：
+
+| 项目形态 | 可能相关的新模板 |
+|----------|-----------------|
+| API 服务 | `api_contract`, `data_contract`, `runbook`, `performance_budget` |
+| CLI/库 | `cli_contract` |
+| 企业 Java | 所有契约类、`domain_model`, `database_migration`, `deployment_manifest`, `security_review`, `runbook` |
+| Agent/插件 | `agent_skill`, `hook_policy`, `prompt_packet` |
+| Parent/发布治理 | `release_policy`, `publish_skill`, `oss_compliance` |
+| 数据平台 | `data_contract`, `batch_job_contract`, `report_contract`, `database_migration` |
+| 大规模迁移 | `migration_plan`, `database_migration`, `deployment_manifest` |
+
+**步骤 2：复制到项目本地**
+
+```bash
+# 示例：复制 api_contract starter
+cp plugins/artifact-chain-assistant/templates/extended/contracts/api_contract/starter.md \
+   artifacts/templates/api_contract.md
+```
+
+**步骤 3：定制内容**
+
+- 删除不适用的章节
+- 添加项目特定的字段或检查项
+- 调整 frontmatter 字段以匹配项目 ID 模式
+- 添加本地审查规则
+
+**步骤 4：记录模板来源**
+
+在 `artifacts/README.md` 或项目模板目录的 README 中记录：
+- 模板来源：插件 `templates/extended/`
+- 定制日期和版本
+- 本地修改摘要
+
+### 重要规则
+
+- **不要直接引用插件 starter**：复制到项目本地后定制
+- **本地定制后覆盖插件**：项目本地模板成为权威，插件 starter 仅作参考
+- **不自动同步**：插件更新不自动覆盖项目本地模板，需手动评估和复制
+
+## 相关文档
+
+- [templates/README.md](../README.md) - 模板目录总览
+- [ADOPTION-GUIDE.md](ADOPTION-GUIDE.md) - **采用指南**：如何将 starter 模板定制为项目本地权威模板，以及升级评审流程
+- [扩展制品目录](../../EXTENDED-ARTIFACT-CATALOG.md) - 类型分类、路径/ID 模式、生命周期规则
+- [INSTALL.md](../../INSTALL.md) - 插件安装指南（含升级指南）
+- [artifact-chain-bootstrap 技能](../../skills/artifact-chain-bootstrap/SKILL.md) - Bootstrap 技能文档

package/adapters/claude/templates/extended/agent/agent_skill/review-checklist.md

@@ -0,0 +1,51 @@
+# Agent Skill 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `SKILL-{nnn}`）
+- [ ] `title` 清晰描述技能功能
+- [ ] 触发条件明确
+- [ ] 适用场景已定义
+
+## 输入/输出质量
+
+- [ ] 必需输入参数完整
+- [ ] 参数类型和描述明确
+- [ ] 输出格式定义完整
+- [ ] 错误输出有标准格式
+
+## 处理流程
+
+- [ ] 处理步骤清晰
+- [ ] 每个步骤有明确输入/输出
+- [ ] 错误处理路径已定义
+- [ ] 边界条件已考虑
+
+## 工具依赖
+
+- [ ] 工具依赖已列出
+- [ ] 权限要求明确
+- [ ] 工具调用有错误处理
+- [ ] 无循环依赖
+
+## 权限安全
+
+- [ ] 可访问资源已定义
+- [ ] 禁止操作已列出
+- [ ] 数据访问范围合理
+- [ ] 敏感操作有审批
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 关联决策存在
+- [ ] 技能可追溯到用户需求
+
+## 可测试性
+
+- [ ] 示例输入/输出完整
+- [ ] 测试用例覆盖正常路径
+- [ ] 测试用例覆盖异常路径
+- [ ] 边界条件已测试