artifact-chain-assistant 0.8.2 → 0.8.4

package/adapters/claude/scripts/lib/method-query.mjs

@@ -0,0 +1,177 @@
+// @feature ACA18 @scenario S-66 @decision D-ACA-18
+// Dependency-free project-facts and Method Query protocol implementation.
+// JSON Schemas are compiled at build time into the generated validators below.
+//
+// Registry is the sole Method Query producer. This library provides:
+// - buildProjectFactsEnvelope / validateProjectFacts: envelope lifecycle
+// - buildMethodQueryCandidate: produces the 5-key candidate for Registry consumption
+//
+// DEPRECATED: buildMethodQuery and computeQueryDigest were removed to enforce
+// Registry as the only producer of target/contract/evidence/queryDigest.
+import { createHash } from 'node:crypto';
+import { canonicalStringify, cloneStrictJsonData } from './generated/canonical-json-v1.generated.mjs';
+import validateProjectFactsSchema, { schemaDigest as projectFactsSchemaDigest } from './generated/project-facts-validator.generated.mjs';
+
+export { projectFactsSchemaDigest };
+
+function digestObject(value) {
+  return `sha256:${createHash('sha256').update(canonicalStringify(value)).digest('hex')}`;
+}
+
+export function computeEvidenceDigest(envelope) {
+  const clone = structuredClone(envelope);
+  delete clone.evidenceDigest;
+  return digestObject(clone);
+}
+
+export function buildProjectFactsEnvelope(facts) {
+  const snapshot = cloneStrictJsonData(facts);
+  const contextTargets = normalizeContextTargets(snapshot.artifactGraphSummary?.contextTargets);
+  const envelope = {
+    schemaVersion: 1,
+    projectRoot: snapshot.projectRoot,
+    configDigest: snapshot.configDigest,
+    artifactGraphSummary: {
+      ...snapshot.artifactGraphSummary,
+      contextTargets,
+    },
+    targetArtifact: snapshot.targetArtifact,
+    contractRevisionDigest: snapshot.contractRevisionDigest,
+    proofStatus: snapshot.proofStatus,
+    versionLockStatus: snapshot.versionLockStatus,
+    sourcesFreshness: snapshot.sourcesFreshness,
+    bindingFreshness: snapshot.bindingFreshness,
+  };
+  if (Object.hasOwn(snapshot, 'policyDigest')) envelope.policyDigest = snapshot.policyDigest;
+  envelope.evidenceDigest = computeEvidenceDigest(envelope);
+  return envelope;
+}
+
+function normalizeContextTargets(value) {
+  if (!Array.isArray(value) || !value.every(item => typeof item === 'string')) {
+    throw new TypeError('artifactGraphSummary.contextTargets must be a string array');
+  }
+  return [...new Set(value)].sort();
+}
+
+function hasCanonicalContextTargets(value) {
+  if (!Array.isArray(value) || !value.every(item => typeof item === 'string')) return false;
+  return value.every((item, index) => index === 0 || value[index - 1] < item);
+}
+
+function schemaErrors(validate) {
+  return (validate.errors || []).map(error => ({
+    code: 'SCHEMA_VALIDATION',
+    path: error.instancePath || '/',
+    message: error.message,
+  }));
+}
+
+function validateProjectFactsSync(envelope) {
+  if (!validateProjectFactsSchema(envelope)) {
+    return { ok: false, status: 'NEEDS_INPUT', errors: schemaErrors(validateProjectFactsSchema) };
+  }
+  if (!hasCanonicalContextTargets(envelope.artifactGraphSummary.contextTargets)) {
+    return {
+      ok: false,
+      status: 'NEEDS_INPUT',
+      errors: [{
+        code: 'NON_CANONICAL_CONTEXT_TARGETS',
+        path: '/artifactGraphSummary/contextTargets',
+        message: 'contextTargets must be sorted and unique',
+      }],
+    };
+  }
+  const computed = computeEvidenceDigest(envelope);
+  if (computed !== envelope.evidenceDigest) {
+    return {
+      ok: false,
+      status: 'NEEDS_INPUT',
+      errors: [{
+        code: 'DIGEST_MISMATCH',
+        path: '/evidenceDigest',
+        message: 'evidenceDigest mismatch',
+      }],
+    };
+  }
+  return { ok: true, status: 'READY', errors: [] };
+}
+
+export async function validateProjectFacts(envelope) {
+  return validateProjectFactsSync(envelope);
+}
+
+/**
+ * Build a Method Query candidate (5 top-level keys).
+ * This is the input for Registry's queryEffectiveIndex. Registry may create a
+ * process-local preparedQueryHandle for a downstream executor; this library
+ * never receives, serializes or substitutes that capability.
+ * Registry is the sole Method Query producer — do NOT use this to build a full query.
+ */
+export function buildMethodQueryCandidate(params) {
+  const snapshot = cloneStrictJsonData(params);
+  const allowedKeys = ['mode', 'intent', 'kind', 'projectFactsEvidence', 'authorization'];
+  const keys = Object.keys(snapshot);
+  const extraKeys = keys.filter(key => !allowedKeys.includes(key));
+  const missingKeys = allowedKeys.filter(key => !Object.hasOwn(snapshot, key));
+  if (extraKeys.length > 0 || missingKeys.length > 0) {
+    throw new TypeError(`Method Query Candidate must contain exactly 5 keys; extra=[${extraKeys.join(', ')}], missing=[${missingKeys.join(', ')}]`);
+  }
+
+  // mode must be 'standard' (the only valid value)
+  if (snapshot.mode !== 'standard') {
+    throw new TypeError("mode must be 'standard'");
+  }
+
+  // intent must be a valid Method Query intent enum
+  const VALID_INTENTS = new Set(['default', 'help', 'author', 'review', 'repair', 'route', 'audit', 'generate', 'batch']);
+  if (typeof snapshot.intent !== 'string' || !VALID_INTENTS.has(snapshot.intent)) {
+    throw new TypeError(`intent must be one of: ${[...VALID_INTENTS].join(', ')}`);
+  }
+
+  // kind must be 'workflow' or 'operation'
+  if (snapshot.kind !== 'workflow' && snapshot.kind !== 'operation') {
+    throw new TypeError("kind must be 'workflow' or 'operation'");
+  }
+
+  // authorization must have exactly sideEffectBudget and granted
+  if (!snapshot.authorization || typeof snapshot.authorization !== 'object' || Array.isArray(snapshot.authorization)) {
+    throw new TypeError('authorization must be an object');
+  }
+  const authorizationKeys = Object.keys(snapshot.authorization);
+  const AUTHORIZATION_REQUIRED = ['sideEffectBudget', 'granted'];
+  const AUTHORIZATION_ALLOWED = new Set(AUTHORIZATION_REQUIRED);
+  const extraAuthKeys = authorizationKeys.filter(k => !AUTHORIZATION_ALLOWED.has(k));
+  const missingAuthKeys = AUTHORIZATION_REQUIRED.filter(k => !authorizationKeys.includes(k));
+  if (extraAuthKeys.length > 0 || missingAuthKeys.length > 0) {
+    throw new TypeError(`authorization must have exactly sideEffectBudget and granted; extra=[${extraAuthKeys.join(', ')}], missing=[${missingAuthKeys.join(', ')}]`);
+  }
+
+  // sideEffectBudget must be a valid enum value
+  const VALID_BUDGETS = new Set(['none', 'read-only', 'write-authorized-artifacts', 'write-review-result', 'write-project-artifacts']);
+  if (!VALID_BUDGETS.has(snapshot.authorization.sideEffectBudget)) {
+    throw new TypeError(`authorization.sideEffectBudget must be one of: ${[...VALID_BUDGETS].join(', ')}`);
+  }
+
+  // granted must be boolean
+  if (typeof snapshot.authorization.granted !== 'boolean') {
+    throw new TypeError('authorization.granted must be a boolean');
+  }
+
+  if (!snapshot.projectFactsEvidence || typeof snapshot.projectFactsEvidence !== 'object' || Array.isArray(snapshot.projectFactsEvidence)) {
+    throw new TypeError('projectFactsEvidence must be a valid Project Facts Evidence Envelope object');
+  }
+  const validation = validateProjectFactsSync(snapshot.projectFactsEvidence);
+  if (!validation.ok) {
+    const codes = validation.errors.map(error => error.code).join(', ');
+    throw new TypeError(`projectFactsEvidence validation failed: ${codes}`);
+  }
+
+  return {
+    mode: snapshot.mode,
+    intent: snapshot.intent,
+    kind: snapshot.kind,
+    projectFactsEvidence: snapshot.projectFactsEvidence,
+    authorization: snapshot.authorization,
+  };
+}

package/adapters/claude/scripts/method-query.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-66 @decision D-ACA-18
+// Method Query CLI: validate/build project-facts envelopes and candidates.
+// Deterministic, fail-closed: invalid input → non-zero exit.
+//
+// Registry is the sole Method Query producer. This CLI provides:
+// - validate-envelope: validate a project-facts evidence envelope
+// - build-envelope: build and validate an envelope from raw facts
+// - build-candidate: build a 5-key candidate for Registry consumption
+//
+// REMOVED: build-query, digest — these produced full Method Query/queryDigest
+// outside Registry, violating the single-producer invariant.
+import { readFile } from 'node:fs/promises';
+import {
+  buildProjectFactsEnvelope,
+  validateProjectFacts,
+  buildMethodQueryCandidate,
+} from './lib/method-query.mjs';
+
+const command = process.argv[2];
+
+if (!command || command === '--help') {
+  process.stderr.write(`Usage:
+  method-query.mjs validate-envelope <path>   Validate a project-facts envelope
+  method-query.mjs build-envelope <path>      Build envelope from raw facts JSON
+  method-query.mjs build-candidate <path>     Build candidate for Registry
+`);
+  process.exit(command ? 0 : 1);
+}
+
+try {
+  switch (command) {
+    case 'validate-envelope': {
+      const filePath = process.argv[3];
+      if (!filePath) { process.stderr.write('Missing file path\n'); process.exit(1); }
+      const envelope = JSON.parse(await readFile(filePath, 'utf8'));
+      const result = await validateProjectFacts(envelope);
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+      if (!result.ok) process.exit(1);
+      break;
+    }
+    case 'build-envelope': {
+      const filePath = process.argv[3];
+      if (!filePath) { process.stderr.write('Missing file path\n'); process.exit(1); }
+      const facts = JSON.parse(await readFile(filePath, 'utf8'));
+      const envelope = buildProjectFactsEnvelope(facts);
+      const validation = await validateProjectFacts(envelope);
+      process.stdout.write(JSON.stringify({ ...validation, envelope }, null, 2) + '\n');
+      if (!validation.ok) process.exit(1);
+      break;
+    }
+    case 'build-candidate': {
+      const filePath = process.argv[3];
+      if (!filePath) { process.stderr.write('Missing file path\n'); process.exit(1); }
+      const params = JSON.parse(await readFile(filePath, 'utf8'));
+      const candidate = buildMethodQueryCandidate(params);
+      process.stdout.write(JSON.stringify({ ok: true, candidate }, null, 2) + '\n');
+      break;
+    }
+    default:
+      process.stderr.write(`Unknown command: ${command}\n`);
+      process.exit(1);
+  }
+} catch (err) {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+}

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

@@ -28,7 +28,7 @@ description: 只读环境检查：插件闭包完整性、Node/CLI 可用性、d
 |--------|------|------|
 | 技能目录 | `skills/` | 当前宿主已安装的技能目录 |
 | Family API 目录 | `family-apis/` | 标准 Family API 定义 |
-| 脚本目录 | `scripts/` | 辅助脚本 |
+| 脚本目录 | 插件根的 `scripts` 子目录 | 辅助脚本 |
 | 兼容性文件 | `compatibility.json` | 运行时版本兼容声明 |
 | Catalog 文件 | `agent-methods/catalog.yaml` | 方法注册目录 |
 
@@ -50,7 +50,8 @@ description: 只读环境检查：插件闭包完整性、Node/CLI 可用性、d
 
 **输出**：
 - 可用 → `PASS: artifact-graph CLI 可用`
-- 不可用 → `FAIL: artifact-graph CLI 未找到`，附加 `pnpm add -D artifact-graph@0.8.1` 修复建议
+- 不可用 → `FAIL: artifact-graph CLI 未找到`，读取插件根 `compatibility.json` 的
+  `artifactGraph.installSpec`，附加 `pnpm add -D <installSpec>` 精确修复建议；不得手写或猜测版本
 
 ### 4. Doctor 诊断
 

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

@@ -1,7 +1,7 @@
 {
   "name": "artifact-chain-assistant",
   "displayName": "Artifact Chain Assistant",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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.2 installed in the target project.
+- `artifact-graph` 0.8.4 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.2 | `artifact-graph` 0.8.2 | `pnpm add -D artifact-graph@0.8.2` |
+| `artifact-chain-assistant` 0.8.4 | `artifact-graph` 0.8.4 | `pnpm add -D artifact-graph@0.8.4` |
 
 ### Install The Runtime
 
 The default installation path uses the npm registry with a precise version:
 
 ```bash
-pnpm add -D artifact-graph@0.8.2
+pnpm add -D artifact-graph@0.8.4
 ```
 
 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.2
+pnpm add -D github:ifoohoo/artifact-graph#artifact-graph-v0.8.4
 ```
 
 > **Never** install with an unlocked range (`artifact-graph`, `artifact-graph@latest`,
-> `artifact-graph@^0.8.2`) or an unpinned GitHub URL (`github:ifoohoo/artifact-graph`).
+> `artifact-graph@^0.8.4`) 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.2`) and exits non-zero.
+command (`pnpm add -D artifact-graph@0.8.4`) 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.2 before the install commands above will
+> must publish and enable `artifact-chain-assistant` 0.8.4 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.2` (see Prerequisites above).
+1. **Install the CLI** — `pnpm add -D artifact-graph@0.8.4` (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.2)
+# 1. Install dependencies from lockfile (gets artifact-graph@0.8.4)
 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.2` and the plugin marketplace repository on an internal registry. The mirror
+`artifact-graph@0.8.4` 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.
 

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

@@ -1,7 +1,7 @@
 schemaVersion: 1
 catalog:
   id: artifact-chain-assistant
-  version: "0.8.2"
+  version: "0.8.4"
 entries:
   - ref: artifact.prd-feature.default
     provider:

package/adapters/codex/compatibility.json

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

package/adapters/codex/families-src/prd-feature/implementation.yaml

@@ -0,0 +1,39 @@
+schemaVersion: 1
+familyImplementationId: com.github.mzdbxqh.prd-feature
+version: "0.6.1"
+targetApiStatus: pending
+lifecycle:
+  ownership: bundled
+  maturity: stable
+  channel: stable
+hostSupport:
+  codex:
+    skillPath: skills/prd-feature
+    available: true
+  claude:
+    skillPath: skills/prd-feature
+    available: true
+bundleRoots:
+  - skills-src/prd-feature
+services:
+  artifact.prd-feature.default:
+    skill: prd-feature
+    summary: "PRD feature default route entry"
+  artifact.prd-feature.author:
+    skill: prd-feature/author
+    summary: "PRD feature authoring entry"
+  artifact.prd-feature.review:
+    skill: prd-feature/review
+    summary: "PRD feature review entry"
+  artifact.prd-feature.repair:
+    skill: prd-feature/repair
+    summary: "PRD feature repair entry"
+conformance:
+  deterministicAttestation: null
+  behaviorQualification: null
+pendingApiStatus:
+  hasPublishedFamilyApi: false
+  reason: "No formal Family API published for prd-feature; migration sample only"
+  missingContracts:
+    - "artifact.prd-feature@1 (Artifact Contract not yet published)"
+notes: "Migration sample for bundled prd-feature family. No published Family API exists yet; targetApiStatus: pending. This descriptor does not claim Family API conformance. It records current bundled service mappings for future registry v2 migration."

package/adapters/codex/families-src/scenario-script/implementation.yaml

@@ -0,0 +1,39 @@
+schemaVersion: 1
+familyImplementationId: com.github.mzdbxqh.scenario-script
+version: "0.6.1"
+targetApiStatus: pending
+lifecycle:
+  ownership: bundled
+  maturity: stable
+  channel: stable
+hostSupport:
+  codex:
+    skillPath: skills/scenario-script
+    available: true
+  claude:
+    skillPath: skills/scenario-script
+    available: true
+bundleRoots:
+  - skills-src/scenario-script
+services:
+  artifact.scenario-script.default:
+    skill: scenario-script
+    summary: "Scenario script default route entry"
+  artifact.scenario-script.author:
+    skill: scenario-script/author
+    summary: "Scenario script authoring entry"
+  artifact.scenario-script.review:
+    skill: scenario-script/review
+    summary: "Scenario script review entry"
+  artifact.scenario-script.repair:
+    skill: scenario-script/repair
+    summary: "Scenario script repair entry"
+conformance:
+  deterministicAttestation: null
+  behaviorQualification: null
+pendingApiStatus:
+  hasPublishedFamilyApi: false
+  reason: "No formal Family API published for scenario-script; migration sample only"
+  missingContracts:
+    - "artifact.scenario-script@1 (Artifact Contract not yet published)"
+notes: "Migration sample for bundled scenario-script family. No published Family API exists yet; targetApiStatus: pending. This descriptor does not claim Family API conformance. It records current bundled service mappings for future registry v2 migration."

package/adapters/codex/family-apis/catalog.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "catalog": {
+    "id": "artifact-chain-assistant",
+    "version": "0.8.4"
+  },
+  "families": [
+    {
+      "id": "artifact.e2e-test-family",
+      "major": 1,
+      "apiPath": "e2e-test/api.json",
+      "revisionDigest": "sha256:66cdd1098a93eb8d128c57010a9405dd1de55bee1e702ced44a93c202cc4b463",
+      "summary": "Standard E2E test skill family for authoring, reviewing, and repairing E2E test specifications"
+    }
+  ]
+}