artifact-chain-assistant 0.8.2 → 0.8.4

package/adapters/codex/family-apis/e2e-test/api.json

@@ -0,0 +1,205 @@
+{
+  "schemaVersion": 1,
+  "api": {
+    "id": "artifact.e2e-test-family",
+    "major": 1,
+    "revisionDigest": "sha256:66cdd1098a93eb8d128c57010a9405dd1de55bee1e702ced44a93c202cc4b463",
+    "displayName": "E2E Test Skill Family",
+    "summary": "Standard skill family for authoring, reviewing, and repairing E2E test specification artifacts",
+    "artifactTypes": [
+      "e2e-test"
+    ]
+  },
+  "services": [
+    {
+      "id": "artifact.e2e-test.default",
+      "required": true,
+      "kind": "workflow",
+      "intents": [
+        "route"
+      ],
+      "accepts": [
+        "User request or intent to work with E2E test specifications"
+      ],
+      "produces": [
+        "Routed to appropriate E2E test service"
+      ],
+      "sideEffectCeiling": "read-only",
+      "mixSafe": false,
+      "discoverable": {
+        "default": true
+      }
+    },
+    {
+      "id": "artifact.e2e-test.help",
+      "required": true,
+      "kind": "operation",
+      "intents": [
+        "help"
+      ],
+      "accepts": [
+        "Help request for E2E test capabilities"
+      ],
+      "produces": [
+        "Capability overview and adoption guidance"
+      ],
+      "sideEffectCeiling": "read-only",
+      "mixSafe": false,
+      "discoverable": {
+        "help": true
+      }
+    },
+    {
+      "id": "artifact.e2e-test.author",
+      "required": true,
+      "kind": "workflow",
+      "intents": [
+        "author"
+      ],
+      "accepts": [
+        {
+          "protocol": "prd-feature-input",
+          "version": "1.0",
+          "input": "PRD feature artifact or user intent for E2E test authoring"
+        },
+        {
+          "protocol": "scenario-script-input",
+          "version": "1.0",
+          "input": "Scenario script artifact providing E2E test context"
+        },
+        {
+          "protocol": "e2e-raw-input-envelope",
+          "version": "1.0",
+          "input": "schemas/author-raw-input.json"
+        },
+        {
+          "protocol": "e2e-stage-resume",
+          "version": "1.0",
+          "input": "inputs.{inspection,assessment,matrix} resume with source and digest revalidation"
+        }
+      ],
+      "produces": [
+        "artifact.e2e-test@1",
+        {
+          "protocol": "preview-manifest-v1.0",
+          "version": "1.0",
+          "input": "schemas/preview-manifest.json"
+        }
+      ],
+      "sideEffectCeiling": "write-authorized-artifacts",
+      "mixSafe": false,
+      "modes": {
+        "supported": ["preview", "commit"],
+        "default": "preview"
+      }
+    },
+    {
+      "id": "artifact.e2e-test.review",
+      "required": true,
+      "kind": "operation",
+      "intents": [
+        "review"
+      ],
+      "accepts": [
+        "artifact.e2e-test@1"
+      ],
+      "produces": [
+        {
+          "protocol": "review-result-v1.0",
+          "version": "1.0",
+          "input": "Review Result Protocol v1.0 JSON object"
+        }
+      ],
+      "sideEffectCeiling": "write-review-result",
+      "mixSafe": false
+    },
+    {
+      "id": "artifact.e2e-test.repair",
+      "required": true,
+      "kind": "workflow",
+      "intents": [
+        "repair"
+      ],
+      "accepts": [
+        {
+          "protocol": "review-result-v1.0",
+          "version": "1.0",
+          "input": "Review Result Protocol v1.0 JSON with open findings"
+        },
+        "artifact.e2e-test@1"
+      ],
+      "produces": [
+        "artifact.e2e-test@1",
+        {
+          "protocol": "preview-manifest-v1.0",
+          "version": "1.0",
+          "input": "schemas/preview-manifest.json"
+        }
+      ],
+      "sideEffectCeiling": "write-authorized-artifacts",
+      "mixSafe": false,
+      "modes": {
+        "supported": ["preview", "commit"],
+        "default": "preview"
+      }
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "e2e-candidate-assessment",
+      "summary": "Risk-driven E2E candidate path identification from PRD and scenario artifacts"
+    },
+    {
+      "id": "e2e-matrix-design",
+      "summary": "Eight-dimensional E2E test case design model"
+    },
+    {
+      "id": "e2e-proof-reconciliation",
+      "summary": "Traceability from test specification through implementation to execution evidence"
+    },
+    {
+      "id": "e2e-finding-capability-manifest",
+      "summary": "Machine-readable E2E-F-001..012 capability states with stable blockers"
+    }
+  ],
+  "dataTransferObjects": [
+    {
+      "id": "e2e-test-matrix",
+      "schemaId": "e2e-test/matrix/v1",
+      "schema": "schemas/matrix.json",
+      "version": "1.0",
+      "digestRule": "stableDigest(canonicalize key-sorted JSON) -> sha256:<64hex>",
+      "services": [
+        { "service": "artifact.e2e-test.author", "position": "intermediate-output (run root)" },
+        { "service": "artifact.e2e-test.review", "position": "intermediate-input (cross-validation)" },
+        { "service": "artifact.e2e-test.repair", "position": "intermediate-input" }
+      ],
+      "artifactBinding": "E2E artifact package manifest binds the minimal artifact and authoritative matrix by relative references and content digests"
+    },
+    {
+      "id": "e2e-finding-capability-manifest",
+      "schemaId": "e2e-test/finding-capability-manifest/v1",
+      "schema": "schemas/finding-capability-manifest.json",
+      "version": "1.0",
+      "digestRule": "stableDigest(rules) -> sha256:<64hex>",
+      "services": []
+    },
+    {
+      "id": "e2e-artifact-package-manifest",
+      "schemaId": "e2e-test/artifact-package-manifest/v1",
+      "schema": "schemas/artifact-package-manifest.json",
+      "version": "1.0",
+      "digestRule": "stableDigest(manifest excluding packageDigest) -> sha256:<64hex>",
+      "services": [
+        { "service": "artifact.e2e-test.author", "position": "formal-output" },
+        { "service": "artifact.e2e-test.review", "position": "required-input" },
+        { "service": "artifact.e2e-test.repair", "position": "required-input-and-output" }
+      ]
+    }
+  ],
+  "qualificationKinds": [
+    "operationalQualification",
+    "methodForwardQualification",
+    "releaseArtifactCertification"
+  ]
+}

package/adapters/codex/family-apis/schema/family-api.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://artifact-chain.dev/schemas/family-api.schema.json",
+  "title": "Skill Family API",
+  "description": "Schema for standard Skill Family API definitions owned by artifact-chain-assistant",
+  "type": "object",
+  "required": ["schemaVersion", "api", "services"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "api": {
+      "type": "object",
+      "required": ["id", "major", "revisionDigest", "displayName", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^artifact\\.[a-z][a-z0-9-]*-family$",
+          "description": "Canonical family API identity in the artifact.* namespace"
+        },
+        "major": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Major version indicating compatibility family"
+        },
+        "revisionDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Immutable SHA-256 digest of canonical API content excluding this field"
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "artifactTypes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Artifact types this family operates on"
+        }
+      }
+    },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/service"
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/capability"
+      },
+      "description": "Optional public capabilities (no implementation state)"
+    },
+    "dataTransferObjects": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/dataTransferObject" },
+      "description": "Family API 拥有的结构化中间或正式 DTO 声明；schema 仍由 family 提供，接口编译器只校验声明形状和服务引用。"
+    },
+    "qualificationKinds": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]+$" },
+      "uniqueItems": true,
+      "description": "该 Family API 区分的资格种类名称；只声明种类，不把资格证据或成熟度写入接口。"
+    }
+  },
+  "definitions": {
+    "service": {
+      "type": "object",
+      "required": ["id", "required", "kind", "intents"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^artifact\\.[a-z][a-z0-9-]+\\.[a-z][a-z0-9-]+$",
+          "description": "Canonical service identity: artifact.<family>.<intent>"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this service is required for API conformance"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["workflow", "operation"],
+          "description": "workflow = stateful multi-step; operation = stateless single-step"
+        },
+        "intents": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "enum": ["default", "help", "author", "review", "repair", "route", "audit", "generate", "batch"]
+          },
+          "uniqueItems": true
+        },
+        "accepts": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/definitions/protocolRef" }
+            ]
+          },
+          "description": "Input contract references or natural language descriptions"
+        },
+        "produces": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/definitions/protocolRef" }
+            ]
+          },
+          "description": "Output contract references or natural language descriptions"
+        },
+        "sideEffectCeiling": {
+          "type": "string",
+          "enum": ["none", "read-only", "write-authorized-artifacts", "write-review-result", "write-project-artifacts"],
+          "description": "Maximum side effect level this service may produce"
+        },
+        "mixSafe": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this service can be bound to a different family implementation than other services in the same family"
+        },
+        "discoverable": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "default": {
+              "type": "boolean",
+              "description": "Whether this is the default entry point"
+            },
+            "help": {
+              "type": "boolean",
+              "description": "Whether this is the help entry point"
+            }
+          }
+        },
+        "modes": {
+          "$ref": "#/definitions/serviceModes"
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": ["id", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "serviceModes": {
+      "type": "object",
+      "required": ["supported", "default"],
+      "additionalProperties": false,
+      "properties": {
+        "supported": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "uniqueItems": true
+        },
+        "default": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+      }
+    },
+    "dataTransferObject": {
+      "type": "object",
+      "required": ["id", "schemaId", "schema", "version", "digestRule", "services"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "schemaId": { "type": "string", "minLength": 1 },
+        "schema": { "type": "string", "pattern": "^[^/\\\\~].*\\.json$" },
+        "version": { "type": "string", "minLength": 1 },
+        "digestRule": { "type": "string", "minLength": 1 },
+        "artifactBinding": { "type": "string", "minLength": 1 },
+        "services": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["service", "position"],
+            "additionalProperties": false,
+            "properties": {
+              "service": { "type": "string", "pattern": "^artifact\\.[a-z][a-z0-9-]+\\.[a-z][a-z0-9-]+$" },
+              "position": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "contractRef": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*@[0-9]+$",
+      "description": "Artifact Contract major identity reference (e.g., artifact.e2e-test@1)"
+    },
+    "protocolRef": {
+      "type": "object",
+      "required": ["protocol", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "protocol": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Protocol name when no formal Artifact Contract exists"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Protocol version"
+        },
+        "input": {
+          "type": "string",
+          "description": "Describes what the protocol accepts or produces"
+        }
+      }
+    }
+  }
+}

package/adapters/codex/schemas/project-facts.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://artifact-chain.dev/schemas/project-facts.schema.json",
+  "title": "Project Facts Evidence Envelope",
+  "description": "Structured envelope capturing project identity, configuration, graph state, and evidence for registry/planner consumption",
+  "type": "object",
+  "required": ["schemaVersion", "projectRoot", "configDigest", "artifactGraphSummary", "targetArtifact", "contractRevisionDigest", "proofStatus", "versionLockStatus", "sourcesFreshness", "bindingFreshness", "evidenceDigest"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "projectRoot": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Project root identity (path or canonical identifier)"
+    },
+    "configDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of artifact-graph.config.yaml content"
+    },
+    "policyDigest": {
+      "type": ["string", "null"],
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of project policy overlay, or null if none"
+    },
+    "artifactGraphSummary": {
+      "type": "object",
+      "required": ["artifactCount", "edgeCount", "contextTargets"],
+      "additionalProperties": false,
+      "properties": {
+        "artifactCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "contextTargets": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "targetArtifact": {
+      "type": "object",
+      "required": ["type", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "contractRevisionDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the contract revision content"
+    },
+    "proofStatus": {
+      "type": "string",
+      "enum": ["present", "missing", "stale"]
+    },
+    "versionLockStatus": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"]
+    },
+    "sourcesFreshness": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"],
+      "description": "Freshness of the adopted catalog source set"
+    },
+    "bindingFreshness": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"],
+      "description": "Freshness of the project provider binding"
+    },
+    "evidenceDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the envelope content excluding this field, using stable key serialization"
+    }
+  }
+}

package/adapters/codex/scripts/check-family-api.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Deterministic Family API catalog validator.
+// Validates all API files in family-apis/ and checks catalog consistency.
+// JSON envelope output; non-zero exit on failure.
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  validateFamilyApi,
+  validateCatalogConsistency,
+  loadJson,
+} from './lib/family-api-validator.mjs';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const familyApisDir = join(root, 'family-apis');
+
+const errors = [];
+const warnings = [];
+const checked = [];
+
+try {
+  // 1. Load catalog
+  const catalogPath = join(familyApisDir, 'catalog.json');
+  let catalog;
+  try {
+    catalog = await loadJson(catalogPath);
+  } catch (err) {
+    errors.push(`Failed to load catalog.json: ${err.message}`);
+    emitResult();
+    process.exit(1);
+  }
+
+  // 2. Discover API files
+  const apiFiles = [];
+  const familiesDir = join(familyApisDir);
+  for (const entry of await readdir(familiesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'schema') continue;
+    const apiPath = join(familiesDir, entry.name, 'api.json');
+    try {
+      const content = await loadJson(apiPath);
+      apiFiles.push({
+        path: `${entry.name}/api.json`,
+        id: content.api?.id,
+        major: content.api?.major,
+        content,
+      });
+    } catch (err) {
+      // Non-API directories are fine
+    }
+  }
+
+  // 3. Validate each API file (async now)
+  for (const apiFile of apiFiles) {
+    const result = await validateFamilyApi(apiFile.content, { sourcePath: apiFile.path });
+    errors.push(...result.errors.map(e => typeof e === 'string' ? e : e.message || JSON.stringify(e)));
+    warnings.push(...result.warnings);
+    checked.push(apiFile.path);
+  }
+
+  // 4. Validate catalog consistency
+  const consistency = validateCatalogConsistency(
+    catalog,
+    apiFiles.map(f => ({ id: f.id, major: f.major, content: f.content })),
+  );
+  errors.push(...consistency.errors);
+
+  emitResult();
+  if (errors.length > 0) process.exit(1);
+} catch (err) {
+  errors.push(`Unexpected error: ${err.message}`);
+  emitResult();
+  process.exit(1);
+}
+
+function emitResult() {
+  const envelope = {
+    ok: errors.length === 0,
+    checked,
+    errors,
+    warnings,
+  };
+  process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+}