artifact-chain-assistant 0.8.0 → 0.8.2

package/adapters/claude/skills/scenario-script/author/references/inspect.md

@@ -0,0 +1,105 @@
+# scenario-script inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅场景剧本制品前，收集项目配置、已有制品、关联关系和场景模板的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认场景类型注册和路径
+artifact-graph --help
+```
+
+提取：
+- 场景剧本对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 项目模板与治理文档
+
+读取以下文件以派生场景剧本的合法字段、status 枚举和章节结构：
+- `artifact-graph.config.yaml` 中场景类型的注册信息
+- `artifacts/README.md` 中的制品边界说明
+- `AGENTS.md` 或 `CLAUDE.md` 中的治理规则
+- 同类已有制品（从步骤 3 的扫描结果中选取典型样本）
+
+从以上来源派生：
+- frontmatter 必填字段（不得假设固定字段集）
+- status 合法枚举（不得假设固定枚举值）
+- 章节结构要求（不得假设固定章节名）
+
+### 3. 已有制品扫描
+
+从步骤 1 提取的制品路径扫描已有场景制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 4. 关联制品可达性
+
+对目标制品的关联制品 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 5. 实现状态检查
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- validate 警告列表
+- 制品链一致性状态
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的场景剧本类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+template:
+  required_fields: [<从项目模板派生的必填字段>]
+  status_enum: [<从项目模板派生的合法状态>]
+  sections: [<从项目模板派生的必要章节>]
+existing_artifacts:
+  - id: <ID>
+    path: <文件路径>
+    status: <status>
+target_artifact:
+  id: <ID> | null
+  path: <文件路径> | null
+  exists: true | false
+related:
+  artifacts: [{ type, id, status }]
+validation:
+  warnings: [<警告列表>]
+  pass: true | false
+```

package/adapters/claude/skills/scenario-script/author/references/validate.md

@@ -0,0 +1,72 @@
+# scenario-script validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证场景剧本制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、治理文档和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从项目配置中派生制品扫描路径，确认新制品的 ID 不与已有制品冲突。
+
+### 4. 关联可达性
+
+对项目规则声明的关联字段中的每个 ID：
+
+```bash
+artifact-graph query --from <ID>
+```
+
+确认关联制品在图中存在。
+
+### 5. 场景质量基本检查
+
+- 能定位角色与目标、前置条件、主路径和可观察结果（章节名服从项目模板）
+- 关键异常路径得到覆盖
+- 步骤与结果可验证，不依赖模糊表述
+
+## 输出
+
+validate 输出供 review 和 repair 消费：
+
+```yaml
+validation:
+  artifact_id: <ID>
+  artifact_path: <文件路径>
+  issues:
+    - code: <问题代码>
+      severity: error | warning | info
+      message: <问题描述>
+      location: <文件路径>:<行号>
+  pass: true | false
+  chain_check:
+    validate_output: <artifact-graph validate 关键输出>
+    related_check:
+      - id: <关联 ID>
+        exists: true | false
+quality_dimensions:
+  role_and_goals: present | missing
+  preconditions: present | missing
+  main_path: present | missing
+  exception_paths: present | missing
+  observable_results: present | missing
+  traceability: present | missing
+```

package/adapters/claude/skills/scenario-script/review/references/compose.md

@@ -0,0 +1,43 @@
+# scenario-script compose
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+基于 inspect 结果编写场景剧本制品的 frontmatter 和正文。
+
+## 步骤
+
+### 1. 确定制品 ID
+
+- 从项目 `idPatterns` 中场景类型对应的 pattern 派生合法 ID
+- 检查与已有制品 ID 不冲突
+- ID 应简短且具有业务语义
+
+### 2. 编写 frontmatter
+
+从 inspect 输出的项目模板、配置和同类制品派生 frontmatter。不得自行增加项目未采用的字段或状态。
+
+### 3. 编写正文结构
+
+正文应覆盖角色与目标、前置条件、主路径、异常路径、可观察结果和必要追溯等通用质量维度；具体章节名和布局从项目模板与已有制品派生。
+
+### 4. 场景步骤编写规则
+
+每个主路径和异常路径步骤必须：
+- 使用编号列表
+- 以动词开头
+- 包含可验证的条件（不使用"足够""合理""尽快"等模糊词）
+- 每个异常路径描述触发条件和预期处理方式
+
+### 5. 文件放置
+
+- 文件名按项目制品命名模式（从已有制品扫描结果派生）
+- 路径按项目中场景剧本注册类型的 paths 配置
+- 文件名与 ID 保持可追溯对应
+
+## 输出
+
+compose 输出供 validate 和 review 消费：
+- 完整的制品文件内容
+- 制品 ID 和路径

package/adapters/claude/skills/scenario-script/review/references/inspect.md

@@ -0,0 +1,105 @@
+# scenario-script inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅场景剧本制品前，收集项目配置、已有制品、关联关系和场景模板的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认场景类型注册和路径
+artifact-graph --help
+```
+
+提取：
+- 场景剧本对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 项目模板与治理文档
+
+读取以下文件以派生场景剧本的合法字段、status 枚举和章节结构：
+- `artifact-graph.config.yaml` 中场景类型的注册信息
+- `artifacts/README.md` 中的制品边界说明
+- `AGENTS.md` 或 `CLAUDE.md` 中的治理规则
+- 同类已有制品（从步骤 3 的扫描结果中选取典型样本）
+
+从以上来源派生：
+- frontmatter 必填字段（不得假设固定字段集）
+- status 合法枚举（不得假设固定枚举值）
+- 章节结构要求（不得假设固定章节名）
+
+### 3. 已有制品扫描
+
+从步骤 1 提取的制品路径扫描已有场景制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 4. 关联制品可达性
+
+对目标制品的关联制品 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 5. 实现状态检查
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- validate 警告列表
+- 制品链一致性状态
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的场景剧本类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+template:
+  required_fields: [<从项目模板派生的必填字段>]
+  status_enum: [<从项目模板派生的合法状态>]
+  sections: [<从项目模板派生的必要章节>]
+existing_artifacts:
+  - id: <ID>
+    path: <文件路径>
+    status: <status>
+target_artifact:
+  id: <ID> | null
+  path: <文件路径> | null
+  exists: true | false
+related:
+  artifacts: [{ type, id, status }]
+validation:
+  warnings: [<警告列表>]
+  pass: true | false
+```

package/adapters/claude/skills/scenario-script/review/references/validate.md

@@ -0,0 +1,72 @@
+# scenario-script validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证场景剧本制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、治理文档和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从项目配置中派生制品扫描路径，确认新制品的 ID 不与已有制品冲突。
+
+### 4. 关联可达性
+
+对项目规则声明的关联字段中的每个 ID：
+
+```bash
+artifact-graph query --from <ID>
+```
+
+确认关联制品在图中存在。
+
+### 5. 场景质量基本检查
+
+- 能定位角色与目标、前置条件、主路径和可观察结果（章节名服从项目模板）
+- 关键异常路径得到覆盖
+- 步骤与结果可验证，不依赖模糊表述
+
+## 输出
+
+validate 输出供 review 和 repair 消费：
+
+```yaml
+validation:
+  artifact_id: <ID>
+  artifact_path: <文件路径>
+  issues:
+    - code: <问题代码>
+      severity: error | warning | info
+      message: <问题描述>
+      location: <文件路径>:<行号>
+  pass: true | false
+  chain_check:
+    validate_output: <artifact-graph validate 关键输出>
+    related_check:
+      - id: <关联 ID>
+        exists: true | false
+quality_dimensions:
+  role_and_goals: present | missing
+  preconditions: present | missing
+  main_path: present | missing
+  exception_paths: present | missing
+  observable_results: present | missing
+  traceability: present | missing
+```

package/adapters/claude/skills/setup/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: setup
+description: 只读环境检查：插件闭包完整性、Node/CLI 可用性、doctor 诊断、项目 config、版本锁和 registry 可用性。输出结构化状态报告和精确下一步。
+---
+
+# setup
+
+## 目的
+
+在不写入任何内容的前提下，检查当前环境是否具备使用 artifact-chain-assistant 的条件。每项检查输出 PASS/WARN/FAIL 状态和精确诊断信息，最终汇总为结构化状态报告和推荐的下一步操作。
+
+## 职责边界
+
+- **只读**：不写配置、不装 hook、不刷新/建立版本锁、不修改任何文件。
+- **路由写入**：当检查发现需要写入操作时，明确路由到 `artifact-chain-bootstrap` 并说明原因。
+- **不复制 bootstrap 逻辑**：setup 只做检查和报告，不复制 bootstrap 的任何写入步骤。
+- **不猜测状态**：只报告可直接验证的事实，不推断项目生命周期或技能启用状态。
+
+## 检查序列
+
+按以下顺序执行七项只读检查：
+
+### 1. 插件闭包完整性
+
+检查插件安装目录中以下路径是否存在且为常规文件/目录：
+
+| 检查项 | 路径 | 说明 |
+|--------|------|------|
+| 技能目录 | `skills/` | 当前宿主已安装的技能目录 |
+| Family API 目录 | `family-apis/` | 标准 Family API 定义 |
+| 脚本目录 | `scripts/` | 辅助脚本 |
+| 兼容性文件 | `compatibility.json` | 运行时版本兼容声明 |
+| Catalog 文件 | `agent-methods/catalog.yaml` | 方法注册目录 |
+
+**输出**：
+- 全部存在 → `PASS: 插件闭包完整`
+- 缺失项 → `FAIL: 缺失 <路径>`，列出每个缺失路径
+
+### 2. Node.js 可用性
+
+执行 `node --version`，检查是否可用及版本。
+
+**输出**：
+- 可用 → `PASS: Node.js <版本>`
+- 不可用 → `FAIL: Node.js 未找到`
+
+### 3. artifact-graph CLI 可用性
+
+执行 `artifact-graph --help`，检查 CLI 是否在 PATH 中。
+
+**输出**：
+- 可用 → `PASS: artifact-graph CLI 可用`
+- 不可用 → `FAIL: artifact-graph CLI 未找到`，附加 `pnpm add -D artifact-graph@0.8.1` 修复建议
+
+### 4. Doctor 诊断
+
+执行 `artifact-graph doctor --format json`，解析输出。
+
+**输出**：
+- exit 0 且输出有效 → `PASS: doctor 诊断通过`
+- exit 非 0 → `WARN: doctor 报告问题`，附加诊断详情和修复建议
+- 命令不存在 → `SKIP: artifact-graph CLI 不可用`
+
+### 5. 项目 config 存在性
+
+检查当前工作目录或项目根目录下 `artifact-graph.config.yaml` 是否存在。
+
+**输出**：
+- 存在 → `PASS: 项目 config 已配置`
+- 不存在 → `WARN: 项目 config 不存在`，附加最小 config 示例和路由建议：`需要写入时请运行 artifact-chain-bootstrap`
+
+### 6. 版本锁存在性
+
+检查 `artifacts/traceability-version-lock.json` 是否存在。
+
+**输出**：
+- 存在 → `PASS: 版本锁已建立`
+- 不存在 → `WARN: 版本锁不存在`，附加路由建议：`需要建锁时请运行 artifact-chain-bootstrap`
+
+### 7. Registry CLI 可用性
+
+检查 `agent-method-registry` CLI 是否可用（在 `node_modules/.bin/` 或 PATH 中）。
+
+**输出**：
+- 可用 → `PASS: agent-method-registry CLI 可用`
+- 不可用 → `WARN: agent-method-registry CLI 不可用（contract-backed 服务解析将返回 NEEDS_INPUT）`
+
+## 输出格式
+
+```
+## 环境检查报告
+
+| # | 检查项 | 状态 | 详情 |
+|---|--------|------|------|
+| 1 | 插件闭包完整性 | PASS | 全部路径存在 |
+| 2 | Node.js | PASS | v20.11.0 |
+| 3 | artifact-graph CLI | PASS | 可用 |
+| 4 | Doctor 诊断 | PASS | 诊断通过 |
+| 5 | 项目 config | WARN | 不存在 |
+| 6 | 版本锁 | WARN | 不存在 |
+| 7 | Registry CLI | WARN | 不可用 |
+
+## 推荐下一步
+
+- 项目 config 和版本锁尚未建立。运行 `artifact-chain-bootstrap`（需用户授权）来初始化项目。
+- Registry CLI 不可用。contract-backed 服务解析将返回 NEEDS_INPUT；可选安装 `agent-method-registry`。
+
+## 状态摘要
+
+- **可直接使用的能力**：help（只读能力查询）、where-am-i（只读项目分诊）
+- **需要初始化后使用的能力**：bootstrap、maintainer、family/service（需要项目 config）
+```
+
+## 安全边界
+
+- 所有检查均为只读，不产生副作用。
+- 未获得用户明确授权时，不执行任何写入操作。
+- 需要写入时，输出明确的路由建议并说明原因，由用户决定是否执行。

package/adapters/claude/skills/where-am-i/SKILL.md

@@ -151,7 +151,7 @@ agent-method-registry query \
 - 不得自动选择第一候选或多候选中的"最佳"
 - 只有明确标记为 generic non-contract-backed 的旧入口可按其既有协议建议，且必须与标准 service 区分
 
-必须调用插件安装根中的 `scripts/method-query.mjs` 构建并验证 envelope 和 candidate，不手工拼装摘要或 digest。Registry 不可用时：输出 `NEEDS_INPUT` + 诊断步骤，不假装可以解析。
+必须调用插件安装根中的 `<plugin-root>/scripts/method-query.mjs` 构建并验证 envelope 和 candidate，不手工拼装摘要或 digest。Registry 不可用时：输出 `NEEDS_INPUT` + 诊断步骤，不假装可以解析。
 
 ## 输出契约
 

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,7 @@
 {
   "name": "artifact-chain-assistant",
-  "version": "0.8.0",
+  "displayName": "Artifact Chain Assistant",
+  "version": "0.8.2",
   "description": "Artifact-chain intake, review/repair/batch/audit workflows, diagnostics, and version-lock maintenance helpers.",
   "author": {
     "name": "Artifact Graph Maintainers"
@@ -12,16 +13,6 @@
   "interface": {
     "displayName": "Artifact Chain Assistant",
     "shortDescription": "Artifact-chain context, review workflows, and version-lock maintenance.",
-    "longDescription": "Reusable skills for artifact-graph projects, including intake routing, generic artifact review/repair/batch/audit workflows, diagnostics, and version-lock refresh guidance.",
-    "developerName": "Artifact Graph Maintainers",
-    "category": "Productivity",
-    "capabilities": ["Write"],
-    "defaultPrompt": [
-      "Check where this artifact-chain task should start.",
-      "Review a design-spec artifact for traceability and completeness.",
-      "Run a batch review on multiple artifacts.",
-      "Refresh version locks for my staged changes.",
-      "Run artifact-chain doctor for this project."
-    ]
+    "category": "Productivity"
   }
 }

package/adapters/codex/EXTENDED-ARTIFACT-CATALOG.md

@@ -1,5 +1,8 @@
 # Extended Artifact Catalog
 
+<!-- generated by scripts/render-public-docs.mjs from docs/public/** — do not edit directly -->
+
+
 This document summarizes the extended artifact type catalog for `artifact-chain-assistant`. It
 covers type classification, recommended paths and ID patterns, template adoption rules, and the
 three-tier authority boundary between `artifact-graph`, the plugin, and target projects.

package/adapters/codex/EXTENDED-ARTIFACT-CATALOG.zh-CN.md

@@ -1,5 +1,8 @@
 # 扩展制品目录
 
+<!-- generated by scripts/render-public-docs.mjs from docs/public/** — do not edit directly -->
+
+
 [English](EXTENDED-ARTIFACT-CATALOG.md)
 
 本文档汇总 `artifact-chain-assistant` 的扩展制品类型目录，内容包括类型分类、推荐路径与 ID 模式、