artifact-chain-assistant 0.8.0

package/adapters/codex/agent-methods/catalog.yaml

@@ -0,0 +1,260 @@
+schemaVersion: 1
+catalog:
+  id: artifact-chain-assistant
+  version: "0.8.0"
+entries:
+  - ref: artifact.prd-feature.default
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: prd-feature
+    kind: workflow
+    summary: "PRD feature 默认路由入口，按意图分派到 author/review/repair"
+    match:
+      domains: [artifact]
+      artifactTypes: [prd-feature]
+      intents: [route]
+    accepts:
+      - "用户需求描述或 PRD 制品变更请求"
+    produces:
+      - "PRD feature 制品草稿、审阅报告或修复补丁"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.prd-feature.author
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: prd-feature/author
+    kind: workflow
+    summary: "PRD feature 制作入口，从需求描述生成 PRD feature 草稿"
+    match:
+      domains: [artifact]
+      artifactTypes: [prd-feature]
+      intents: [author]
+    accepts:
+      - "用户需求描述"
+    produces:
+      - "PRD feature 制品草稿"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.prd-feature.review
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: prd-feature/review
+    kind: workflow
+    summary: "PRD feature 审阅入口，检查制品完整性、追溯性和一致性"
+    match:
+      domains: [artifact]
+      artifactTypes: [prd-feature]
+      intents: [review]
+    accepts:
+      - "PRD feature 制品"
+    produces:
+      - "审阅报告"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.prd-feature.repair
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: prd-feature/repair
+    kind: workflow
+    summary: "PRD feature 修复入口，根据审阅报告修复制品问题"
+    match:
+      domains: [artifact]
+      artifactTypes: [prd-feature]
+      intents: [repair]
+    accepts:
+      - "审阅报告和待修复的 PRD feature 制品"
+    produces:
+      - "修复后的 PRD feature 制品"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.scenario-script.default
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: scenario-script
+    kind: workflow
+    summary: "场景剧本默认路由入口，按意图分派到 author/review/repair"
+    match:
+      domains: [artifact]
+      artifactTypes: [scenario-script]
+      intents: [route]
+    accepts:
+      - "需求描述或场景剧本变更请求"
+    produces:
+      - "场景剧本草稿、审阅报告或修复补丁"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.scenario-script.author
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: scenario-script/author
+    kind: workflow
+    summary: "场景剧作入口，从需求描述生成场景剧本草稿"
+    match:
+      domains: [artifact]
+      artifactTypes: [scenario-script]
+      intents: [author]
+    accepts:
+      - "需求描述"
+    produces:
+      - "场景剧本草稿"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.scenario-script.review
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: scenario-script/review
+    kind: workflow
+    summary: "场景剧本审阅入口，检查剧本完整性、场景覆盖和追溯关系"
+    match:
+      domains: [artifact]
+      artifactTypes: [scenario-script]
+      intents: [review]
+    accepts:
+      - "场景剧本"
+    produces:
+      - "审阅报告"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.scenario-script.repair
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: scenario-script/repair
+    kind: workflow
+    summary: "场景剧本修复入口，根据审阅报告修复剧本问题"
+    match:
+      domains: [artifact]
+      artifactTypes: [scenario-script]
+      intents: [repair]
+    accepts:
+      - "审阅报告和待修复的场景剧本"
+    produces:
+      - "修复后的场景剧本"
+    sideEffects:
+      - write-project-artifacts
+
+  # ── 通用跨类型入口 ──────────────────────────────────────────────────────
+
+  - ref: artifact.review
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-review
+    kind: workflow
+    summary: "通用制品审阅路由，按 domain 分派到类型专用 worker"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification]
+      intents: [review]
+    accepts:
+      - "制品文件或目录路径"
+    produces:
+      - "Review Result Protocol v1.0 审阅结果"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.repair
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-repair
+    kind: workflow
+    summary: "通用制品修复入口，根据审阅结果修复 open findings"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification]
+      intents: [repair]
+    accepts:
+      - "审阅结果 JSON 和待修复制品"
+    produces:
+      - "Review Result Protocol v1.0 修复结果"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.batch
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-batch
+    kind: workflow
+    summary: "通用批处理编排，确定性切分与合并 Review Result"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification]
+      intents: [batch]
+    accepts:
+      - "制品目录和批处理参数"
+    produces:
+      - "Review Result Protocol v1.0 批次汇总"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.audit
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-audit
+    kind: workflow
+    summary: "制品链健康检查与能力审计"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification]
+      intents: [audit, health]
+    accepts:
+      - "项目根路径"
+    produces:
+      - "健康检查报告或能力审计结果"
+    sideEffects:
+      - write-project-artifacts
+
+  - ref: artifact.generate
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-generate
+    kind: workflow
+    summary: "通用制品生成入口，从模板和 profile 配置生成非 PRD/scenario 类型制品"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification]
+      intents: [generate]
+    accepts:
+      - "制品类型、目标路径和模板配置"
+    produces:
+      - "从模板生成的制品文件"
+    sideEffects:
+      - write-project-artifacts
+
+  # ── 插件级发现入口 ──────────────────────────────────────────────────────
+
+  - ref: artifact-chain-help
+    provider:
+      scope: plugin
+      plugin: artifact-chain-assistant
+      skill: artifact-chain-help
+    kind: operation
+    summary: "展示标准 Family API、bundled legacy 方法和安装后采用步骤"
+    match:
+      domains: [artifact]
+      artifactTypes: [design-spec, link, e2e, domain, contract, blueprint, verification, prd-feature, scenario-script]
+      intents: [help]
+    accepts:
+      - "帮助请求或能力查询"
+    produces:
+      - "标准能力概览和采用指导"
+    sideEffects:
+      - read-only

package/adapters/codex/compatibility.json

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

package/adapters/codex/schemas/artifact-workflow-profile.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://artifact-graph.dev/schemas/artifact-workflow-profile.schema.json",
+  "title": "Artifact Workflow Profile",
+  "description": "Project workflow profile for artifact-chain-assistant",
+  "type": "object",
+  "required": ["schema_version", "project", "workflows"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1
+    },
+    "project": {
+      "type": "object",
+      "required": ["id", "language"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "language": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        }
+      }
+    },
+    "workflows": {
+      "type": "object",
+      "propertyNames": {
+        "enum": ["generate", "review", "repair", "audit", "batch"]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "checklists": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "validators": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "templates": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "worker": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "skill": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Project workflow skill name, not a filesystem path"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/adapters/codex/scripts/batch-merge.mjs

@@ -0,0 +1,276 @@
+// @feature ACA16 @scenario S-49
+// Deterministic batch result merging for artifact review workflows.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+/**
+ * Severity ordering for status/decision aggregation.
+ * Lower index = less severe.
+ */
+const STATUS_SEVERITY = ['SKIPPED', 'SUCCEEDED', 'NEEDS_INPUT', 'BLOCKED', 'FAILED'];
+const DECISION_SEVERITY = ['NOT_APPLICABLE', 'PASS', 'PASS_WITH_RESIDUAL_MINOR', 'NEEDS_INPUT', 'BLOCKED', 'FAIL'];
+const EXECUTORS = new Set(['script', 'worker', 'agent', 'manual', 'cli']);
+
+/**
+ * Get the most severe value from a list using a severity ordering.
+ */
+function mostSevere(values, severityOrder) {
+  let maxIdx = -1;
+  let result = null;
+  for (const v of values) {
+    const idx = severityOrder.indexOf(v);
+    if (idx > maxIdx) {
+      maxIdx = idx;
+      result = v;
+    }
+  }
+  return result;
+}
+
+/**
+ * Validate a single result object against Review Result Protocol v1.0.
+ * Returns an error string if invalid, or null if valid.
+ */
+function validateResult(result, filePath) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return `${filePath}: root must be an object`;
+  if (!result.schema_version) {
+    return `${filePath}: missing schema_version`;
+  }
+  if (result.schema_version !== '1.0') {
+    return `${filePath}: unsupported schema_version "${result.schema_version}" (expected "1.0")`;
+  }
+  if (!result.run_id) {
+    return `${filePath}: missing run_id`;
+  }
+  if (!result.status) {
+    return `${filePath}: missing status`;
+  }
+  if (!STATUS_SEVERITY.includes(result.status)) return `${filePath}: invalid status`;
+  if (!result.decision) {
+    return `${filePath}: missing decision`;
+  }
+  if (!DECISION_SEVERITY.includes(result.decision)) return `${filePath}: invalid decision`;
+  if (typeof result.summary !== 'string') return `${filePath}: invalid summary`;
+  if (result.producer !== undefined) {
+    if (!result.producer || typeof result.producer !== 'object' || Array.isArray(result.producer)) return `${filePath}: invalid producer`;
+    if (!EXECUTORS.has(result.producer.executor) || typeof result.producer.name !== 'string') return `${filePath}: invalid producer`;
+  }
+  if (result.review?.metrics !== undefined) {
+    if (!result.review.metrics || typeof result.review.metrics !== 'object' || Array.isArray(result.review.metrics)) return `${filePath}: invalid metrics`;
+    for (const value of Object.values(result.review.metrics)) {
+      if (!Number.isInteger(value) || value < 0) return `${filePath}: invalid metric`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Merge findings arrays, deduplicating by finding id.
+ * When duplicates exist, the first occurrence wins (deterministic by file sort order).
+ */
+function mergeFindings(allFindings) {
+  const seen = new Set();
+  const merged = [];
+
+  for (const finding of allFindings) {
+    if (finding.id && seen.has(finding.id)) {
+      continue;
+    }
+    if (finding.id) {
+      seen.add(finding.id);
+    }
+    merged.push(finding);
+  }
+
+  return merged;
+}
+
+/**
+ * Sum numeric metrics across all results.
+ */
+function sumMetrics(allMetrics) {
+  const sums = {};
+
+  for (const metrics of allMetrics) {
+    if (!metrics) continue;
+    for (const [key, value] of Object.entries(metrics)) {
+      if (typeof value === 'number') {
+        sums[key] = (sums[key] || 0) + value;
+      }
+    }
+  }
+
+  return sums;
+}
+
+/**
+ * Collect all findings from result objects.
+ */
+function collectFindings(results) {
+  const allFindings = [];
+
+  for (const result of results) {
+    const findings = result.review?.findings || [];
+    allFindings.push(...findings);
+
+    // Also include resolved_findings for completeness
+    const resolved = result.review?.resolved_findings || [];
+    allFindings.push(...resolved);
+  }
+
+  return allFindings;
+}
+
+/**
+ * Collect all metrics from result objects.
+ */
+function collectMetrics(results) {
+  return results
+    .map(r => r.review?.metrics)
+    .filter(Boolean);
+}
+
+/**
+ * Collect all batches from result objects.
+ */
+function collectBatches(results) {
+  const batches = [];
+
+  for (const result of results) {
+    if (result.review?.batches) {
+      batches.push(...result.review.batches);
+    }
+  }
+
+  return batches;
+}
+
+/**
+ * Determine merged run_id from results.
+ * Uses the first result's run_id as the base, or the provided override.
+ */
+function determineRunId(results, overrideRunId) {
+  if (overrideRunId) return overrideRunId;
+  return results[0].run_id;
+}
+
+/**
+ * Deterministic batch result merging.
+ *
+ * @param {string} resultsDir - Directory containing batch result JSON files
+ * @param {object} options
+ * @param {string} [options.runId] - Override run_id for merged result
+ * @returns {Promise<object>} Merged Review Result Protocol v1.0
+ * @throws {Error} If validation fails or no results found
+ */
+export async function batchMerge(resultsDir, options = {}) {
+  const base = resolve(resultsDir);
+
+  // Read all JSON files from results directory
+  const entries = await readdir(base).catch(() => {
+    throw new Error(`Cannot read results directory: ${base}`);
+  });
+
+  const jsonFiles = entries
+    .filter(e => e.endsWith('.json'))
+    .sort(); // Deterministic sort by filename
+
+  if (jsonFiles.length === 0) {
+    throw new Error(`No JSON files found in ${base}`);
+  }
+
+  // Load and validate all results
+  const results = [];
+  const errors = [];
+
+  for (const fileName of jsonFiles) {
+    const filePath = join(base, fileName);
+    const content = await readFile(filePath, 'utf8');
+
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch (e) {
+      errors.push(`${fileName}: invalid JSON - ${e.message}`);
+      continue;
+    }
+
+    const validationError = validateResult(parsed, fileName);
+    if (validationError) {
+      errors.push(validationError);
+      continue;
+    }
+
+    results.push(parsed);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Validation errors:\n${errors.join('\n')}`);
+  }
+
+  if (results.length === 0) {
+    throw new Error(`No valid results found in ${base}`);
+  }
+
+  // Sort results by stage_id for deterministic ordering
+  results.sort((a, b) => {
+    const aKey = a.stage_id || '';
+    const bKey = b.stage_id || '';
+    return aKey.localeCompare(bKey);
+  });
+
+  // Merge components
+  const allFindings = collectFindings(results);
+  const mergedFindings = mergeFindings(allFindings);
+  const mergedMetrics = sumMetrics(collectMetrics(results));
+  const mergedBatches = collectBatches(results);
+
+  // Aggregate status and decision
+  const statuses = results.map(r => r.status);
+  const decisions = results.map(r => r.decision);
+  const mergedStatus = statuses.every(s => s === 'SUCCEEDED') ? 'SUCCEEDED' : mostSevere(statuses, STATUS_SEVERITY);
+  const mergedDecision = decisions.includes('FAIL') ? 'FAIL' : decisions.includes('BLOCKED') ? 'BLOCKED' : mostSevere(decisions, DECISION_SEVERITY);
+
+  // Build merged result
+  const merged = {
+    schema_version: '1.0',
+    run_id: determineRunId(results, options.runId),
+    status: mergedStatus,
+    decision: mergedDecision,
+    summary: `Batch completed: ${mergedBatches.length || results.length} batches, ${mergedMetrics.files_scanned || 0} files, ${mergedFindings.length} findings.`,
+    review: {
+      batches: mergedBatches,
+      metrics: mergedMetrics,
+      findings: mergedFindings,
+    },
+  };
+
+  return merged;
+}
+
+// CLI entry point
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const resultsDir = args[0];
+
+  if (!resultsDir) {
+    console.error('Usage: node batch-merge.mjs <results-dir> [--run-id <id>]');
+    process.exit(1);
+  }
+
+  let runId;
+  const runIdIdx = args.indexOf('--run-id');
+  if (runIdIdx !== -1 && args[runIdIdx + 1]) {
+    runId = args[runIdIdx + 1];
+  }
+
+  try {
+    const merged = await batchMerge(resultsDir, { runId });
+    console.log(JSON.stringify(merged, null, 2));
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}