artifact-chain-assistant 0.8.1 → 0.8.2

package/adapters/claude/skills/prd-feature/review/references/inspect.md

@@ -0,0 +1,94 @@
+# prd-feature inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅 PRD 功能特性制品前，收集项目配置、已有制品、关联关系和实现状态的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认 CLI 能力
+artifact-graph --help
+```
+
+提取：
+- PRD 对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目模板、`artifacts/README.md`、`AGENTS.md`/`CLAUDE.md` 中的本地规则
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 已有制品扫描
+
+从步骤 1 提取的 PRD 注册类型 paths 扫描已有制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 3. 关联制品可达性
+
+对项目配置、模板或同类制品声明的每个关联 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 4. 实现状态检查
+
+```bash
+artifact-graph context --target <type>:<ID> --mode implementation
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- 实现文件列表
+- validate 警告列表
+- 追溯注释存在性
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的 PRD 类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+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
+implementation:
+  files: [<实现文件列表>]
+  trace_comments: [<追溯注释列表>]
+```

package/adapters/claude/skills/prd-feature/review/references/validate.md

@@ -0,0 +1,65 @@
+# prd-feature validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证 PRD 功能特性制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、`artifacts/README.md` 和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从 `artifact-graph.config.yaml` 中 PRD 注册类型的 paths 派生扫描路径，确认新制品 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
+```

package/adapters/claude/skills/scenario-script/author/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/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/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,7 +1,7 @@
 {
   "name": "artifact-chain-assistant",
   "displayName": "Artifact Chain Assistant",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Artifact-chain intake, review/repair/batch/audit workflows, diagnostics, and version-lock maintenance helpers.",
   "author": {
     "name": "Artifact Graph Maintainers"

package/adapters/codex/INSTALL.md

@@ -16,7 +16,7 @@ instructions.
 ## Prerequisites
 
 - Node.js `>=22.0.0`.
-- `artifact-graph` 0.8.1 installed in the target project.
+- `artifact-graph` 0.8.2 installed in the target project.
 - **GitHub SSH key** — Claude Code clones `source: github` entries over SSH by default. If you
   have not configured a GitHub SSH key, set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` in your shell
   profile, or add the marketplace with an explicit `https://` URL. Codex users can check
@@ -28,24 +28,24 @@ instructions.
 
 | Plugin | Verified Runtime | Install |
 | --- | --- | --- |
-| `artifact-chain-assistant` 0.8.1 | `artifact-graph` 0.8.1 | `pnpm add -D artifact-graph@0.8.1` |
+| `artifact-chain-assistant` 0.8.2 | `artifact-graph` 0.8.2 | `pnpm add -D artifact-graph@0.8.2` |
 
 ### Install The Runtime
 
 The default installation path uses the npm registry with a precise version:
 
 ```bash
-pnpm add -D artifact-graph@0.8.1
+pnpm add -D artifact-graph@0.8.2
 ```
 
 If the npm registry is unavailable, use the explicit GitHub fallback pinned to the verified tag:
 
 ```bash
-pnpm add -D github:ifoohoo/artifact-graph#artifact-graph-v0.8.1
+pnpm add -D github:ifoohoo/artifact-graph#artifact-graph-v0.8.2
 ```
 
 > **Never** install with an unlocked range (`artifact-graph`, `artifact-graph@latest`,
-> `artifact-graph@^0.8.1`) or an unpinned GitHub URL (`github:ifoohoo/artifact-graph`).
+> `artifact-graph@^0.8.2`) or an unpinned GitHub URL (`github:ifoohoo/artifact-graph`).
 > Unlocked installs produce non-reproducible dependency trees and break version-lock audit.
 
 With pnpm 10+, projects that install `artifact-graph` must allow the native `better-sqlite3`
@@ -72,7 +72,7 @@ allowBuilds:
 
 The plugin's `doctor` command validates the installed runtime version before running any
 diagnostic. If it detects a version mismatch or missing CLI, it reports the exact remediation
-command (`pnpm add -D artifact-graph@0.8.1`) and exits non-zero.
+command (`pnpm add -D artifact-graph@0.8.2`) and exits non-zero.
 
 ### CLI Resolution Order
 
@@ -147,7 +147,7 @@ wrappers, and Stop-hook guardrail. These assistant controls do not replace Git h
 
 > **Marketplace note**: `ifoohoo/artifact-skill-set` is an external independent marketplace. The
 > plugin payload is still published from `ifoohoo/artifact-chain-assistant`. The marketplace entry
-> must publish and enable `artifact-chain-assistant` 0.8.1 before the install commands above will
+> must publish and enable `artifact-chain-assistant` 0.8.2 before the install commands above will
 > succeed.
 
 ## Post-Installation Discovery
@@ -197,7 +197,7 @@ The plugin should not move these files into the plugin repository.
 
 For a first-time setup, the end-to-end sequence is:
 
-1. **Install the CLI** — `pnpm add -D artifact-graph@0.8.1` (see Prerequisites above).
+1. **Install the CLI** — `pnpm add -D artifact-graph@0.8.2` (see Prerequisites above).
 2. **Install the plugin** — follow the Codex or Claude Code section above.
 3. **Run bootstrap** — ask the assistant to use the `artifact-chain-bootstrap` skill (see prompt
    below). The skill will:
@@ -995,7 +995,7 @@ with append-only behavior; it does not overwrite local rules.
 ### Recovery Steps
 
 ```bash
-# 1. Install dependencies from lockfile (gets artifact-graph@0.8.1)
+# 1. Install dependencies from lockfile (gets artifact-graph@0.8.2)
 pnpm install --frozen-lockfile
 
 # 2. Install plugin per your host (Codex / Claude Code)
@@ -1062,7 +1062,7 @@ pnpm exec artifact-graph hooks install-git --hook all
 ### Enterprise Mirror
 
 If the corporate environment cannot access the public npm registry or GitHub, mirror both
-`artifact-graph@0.8.1` and the plugin marketplace repository on an internal registry. The mirror
+`artifact-graph@0.8.2` and the plugin marketplace repository on an internal registry. The mirror
 does not change the state ownership model: Git-tracked files remain authoritative, local caches
 remain derived.