artifact-chain-assistant 0.8.0 → 0.8.2

package/adapters/codex/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/codex/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/codex/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/agent-methods/catalog.yaml

@@ -1,7 +1,7 @@
 schemaVersion: 1
 catalog:
   id: artifact-chain-assistant
-  version: "0.8.0"
+  version: "0.8.2"
 entries:
   - ref: artifact.prd-feature.default
     provider:
@@ -239,13 +239,13 @@ entries:
     sideEffects:
       - write-project-artifacts
 
-  # ── 插件级发现入口 ──────────────────────────────────────────────────────
+  # ── 插件级入口 ──────────────────────────────────────────────────────────
 
-  - ref: artifact-chain-help
+  - ref: artifact.help
     provider:
       scope: plugin
       plugin: artifact-chain-assistant
-      skill: artifact-chain-help
+      skill: help
     kind: operation
     summary: "展示标准 Family API、bundled legacy 方法和安装后采用步骤"
     match:
@@ -258,3 +258,39 @@ entries:
       - "标准能力概览和采用指导"
     sideEffects:
       - read-only
+
+  - ref: artifact.setup
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: setup
+    kind: operation
+    summary: "只读环境检查：插件闭包、CLI、config、版本锁、registry 可用性"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification, prd-feature, scenario-script]
+      intents: [setup, diagnose]
+    accepts:
+      - "环境检查请求"
+    produces:
+      - "结构化状态报告和下一步建议"
+    sideEffects:
+      - read-only
+
+  - ref: artifact.quickstart
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: quickstart
+    kind: operation
+    summary: "按意图路由到正确的技能"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification, prd-feature, scenario-script]
+      intents: [start]
+    accepts:
+      - "用户意图描述"
+    produces:
+      - "路由建议和目标技能推荐"
+    sideEffects:
+      - read-only

package/compatibility.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": "1.0",
-  "pluginVersion": "0.8.0",
+  "pluginVersion": "0.8.2",
   "artifactGraph": {
-    "verifiedVersion": "0.8.0",
-    "installSpec": "artifact-graph@0.8.0",
-    "githubFallbackSpec": "github:ifoohoo/artifact-graph#artifact-graph-v0.8.0"
+    "verifiedVersion": "0.8.2",
+    "installSpec": "artifact-graph@0.8.2",
+    "githubFallbackSpec": "github:ifoohoo/artifact-graph#artifact-graph-v0.8.2"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifact-chain-assistant",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Codex and Claude Code assistant plugin for artifact-chain projects",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,11 +49,13 @@
     "SECURITY.md",
     "EXTENDED-ARTIFACT-CATALOG.md",
     "EXTENDED-ARTIFACT-CATALOG.zh-CN.md",
+    "AGENT-METHOD-REGISTRY.md",
+    "AGENT-METHOD-REGISTRY.zh-CN.md",
     ".github",
-    ".agents",
     ".claude-plugin",
     ".codex-plugin",
     "adapters",
+    "skills",
     "skills-src",
     "templates",
     "scripts",
@@ -80,6 +82,6 @@
   },
   "devDependencies": {
     "ajv": "^8.20.0",
-    "artifact-graph": "0.8.0"
+    "artifact-graph": "0.8.2"
   }
 }

package/scripts/build-adapters.mjs

@@ -46,14 +46,6 @@ const shellResolver = `artifact_graph() {
 `;
 
 const outputs = [
-  {
-    template: 'templates/codex/marketplace.json.tpl',
-    path: '.agents/plugins/marketplace.json',
-  },
-  {
-    template: 'templates/claude/marketplace.json.tpl',
-    path: '.claude-plugin/marketplace.json',
-  },
   {
     template: 'templates/codex/plugin.json.tpl',
     path: 'adapters/codex/.codex-plugin/plugin.json',
@@ -103,6 +95,8 @@ artifact_graph version-lock refresh --changed-only --staged "$@"
 let drift = false;
 const stalePaths = [
   'adapters/claude/.claude-plugin/marketplace.json',
+  '.agents/plugins/marketplace.json',
+  '.claude-plugin/marketplace.json',
   'adapters/codex/commands',
   'adapters/codex/commands/version-lock-audit.sh',
   'adapters/codex/commands/version-lock-refresh.sh',
@@ -152,18 +146,26 @@ for (const output of outputs) {
   }
 }
 
-// Root plugin manifests required by release-skill assess. They are deterministic copies of the
-// generated adapter manifests above, so the adapter template render stays the single version source.
-// The marketplace plugin source still points at ./adapters/claude and ./adapters/codex; these root
-// files are release metadata only, not an alternate install root and not a host installation surface.
-const rootManifestCopies = [
-  { from: 'adapters/claude/.claude-plugin/plugin.json', path: '.claude-plugin/plugin.json' },
-  { from: 'adapters/codex/.codex-plugin/plugin.json', path: '.codex-plugin/plugin.json' },
+// Root plugin manifests for external marketplace installation. They derive from the generated adapter
+// manifests above, so the adapter template render stays the single version source. External market
+// installs from the repository root use these manifests to discover the generated root Claude skills
+// at ./skills and the self-contained Codex adapter skills at ./adapters/codex/skills.
+const rootManifests = [
+  { from: 'adapters/claude/.claude-plugin/plugin.json', path: '.claude-plugin/plugin.json', rewriteSkills: false },
+  { from: 'adapters/codex/.codex-plugin/plugin.json', path: '.codex-plugin/plugin.json', rewriteSkills: true, skillsPrefix: './adapters/codex/' },
 ];
-for (const copy of rootManifestCopies) {
-  const target = join(root, copy.path);
-  const content =
-    generatedContent.get(copy.from) ?? (await readFile(join(root, copy.from), 'utf-8'));
+for (const manifest of rootManifests) {
+  const target = join(root, manifest.path);
+  const sourceContent =
+    generatedContent.get(manifest.from) ?? (await readFile(join(root, manifest.from), 'utf-8'));
+  // Root Claude manifest keeps ./skills/ for standard plugin installation at repository root.
+  // Root Codex manifest rewrites to ./adapters/codex/skills/ because Codex adapter is self-contained.
+  const content = manifest.rewriteSkills
+    ? sourceContent.replace(
+        /"skills": "\.\/skills\/"/,
+        `"skills": "${manifest.skillsPrefix}skills/"`,
+      )
+    : sourceContent;
   if (check) {
     let current = '';
     try {
@@ -173,7 +175,7 @@ for (const copy of rootManifestCopies) {
     }
     if (current !== content) {
       drift = true;
-      console.error(`Generated root manifest drift: ${copy.path}`);
+      console.error(`Generated root manifest drift: ${manifest.path}`);
     }
   } else {
     await mkdir(dirname(target), { recursive: true });

package/scripts/check-method-registry.mjs

@@ -108,10 +108,11 @@ function runRegistryExpectFail(args) {
 
   const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
 
-  // ── 3. Exactly 14 entries ──
-  assert(index.entries.length === 14, `expected 14 entries, got ${index.entries.length}`);
+  // ── 3. Exactly 16 entries ──
+  assert(index.entries.length === 16, `expected 16 entries, got ${index.entries.length}`);
+  const operationRefs = new Set(['artifact.help', 'artifact.setup', 'artifact.quickstart']);
   for (const entry of index.entries) {
-    if (entry.ref === 'artifact-chain-help') {
+    if (operationRefs.has(entry.ref)) {
       assert(entry.kind === 'operation', `entry ${entry.ref} should be operation, got ${entry.kind}`);
     } else {
       assert(entry.kind === 'workflow', `entry ${entry.ref} should be workflow, got ${entry.kind}`);
@@ -133,7 +134,9 @@ function runRegistryExpectFail(args) {
     'artifact.batch',
     'artifact.audit',
     'artifact.generate',
-    'artifact-chain-help',
+    'artifact.help',
+    'artifact.setup',
+    'artifact.quickstart',
   ];
   const actualRefs = index.entries.map(e => e.ref).sort();
   const sortedExpected = [...expectedRefs].sort();
@@ -457,5 +460,5 @@ if (issues.length > 0) {
   }
   process.exit(1);
 } else {
-  console.log('Method registry check passed: 13 workflow entries, schema/query/resolve/overlay all verified.');
+  console.log('Method registry check passed: 16 entries (13 workflow + 3 operation), schema/query/resolve/overlay all verified.');
 }

package/scripts/lib/compatibility-policy.mjs

@@ -96,12 +96,6 @@ export async function validateCompatibilityPolicy(pluginRoot) {
   // Check package.json version
   await checkJsonField(pluginRoot, 'package.json', 'version', pluginVersion, issues);
 
-  // Check Claude marketplace metadata.version (real schema)
-  await checkClaudeMarketplaceVersion(pluginRoot, pluginVersion, issues);
-
-  // Check Codex marketplace plugin source path (real schema has no version field)
-  await checkCodexMarketplaceSource(pluginRoot, issues);
-
   // Check adapter manifest versions (real paths: .codex-plugin/plugin.json, .claude-plugin/plugin.json)
   for (const [adapter, manifestRel] of [
     ['codex', join('adapters', 'codex', '.codex-plugin', 'plugin.json')],
@@ -147,65 +141,6 @@ async function checkJsonField(pluginRoot, relativePath, field, expected, issues)
   }
 }
 
-/**
- * Check Claude marketplace metadata.version matches plugin version.
- * Real schema: { metadata: { version: "x.y.z" } }
- */
-async function checkClaudeMarketplaceVersion(pluginRoot, expectedVersion, issues) {
-  const relPath = join('.claude-plugin', 'marketplace.json');
-  const filePath = join(pluginRoot, relPath);
-  try {
-    const raw = await readFile(filePath, 'utf8');
-    const json = JSON.parse(raw);
-    const actual = json.metadata?.version;
-    if (actual === undefined) {
-      issues.push(`${relPath} metadata.version is missing (required)`);
-    } else if (actual !== expectedVersion) {
-      issues.push(`${relPath} metadata.version must be "${expectedVersion}", got "${actual}"`);
-    }
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      issues.push(`${relPath} is missing (required)`);
-    } else if (error instanceof SyntaxError) {
-      issues.push(`${relPath} is not valid JSON: ${error.message}`);
-    } else {
-      issues.push(`${relPath} error: ${error.message}`);
-    }
-  }
-}
-
-/**
- * Check Codex marketplace plugin source path points to ./adapters/codex.
- * Real schema has NO version field; validate source.path instead.
- */
-async function checkCodexMarketplaceSource(pluginRoot, issues) {
-  const relPath = join('.agents', 'plugins', 'marketplace.json');
-  const filePath = join(pluginRoot, relPath);
-  try {
-    const raw = await readFile(filePath, 'utf8');
-    const json = JSON.parse(raw);
-    const plugin = json.plugins?.[0];
-    if (!plugin) {
-      issues.push(`${relPath} has no plugins array entries`);
-      return;
-    }
-    const sourcePath = plugin.source?.path;
-    if (sourcePath !== './adapters/codex') {
-      issues.push(
-        `${relPath} plugins[0].source.path must be "./adapters/codex", got "${sourcePath}"`,
-      );
-    }
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      issues.push(`${relPath} is missing (required)`);
-    } else if (error instanceof SyntaxError) {
-      issues.push(`${relPath} is not valid JSON: ${error.message}`);
-    } else {
-      issues.push(`${relPath} error: ${error.message}`);
-    }
-  }
-}
-
 /**
  * Check adapter plugin manifest version.
  * Fail-closed: missing file or invalid JSON produces an issue, never silently skipped.