artifact-chain-assistant 0.8.0

package/runtime/claude/version-lock-stop.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export async function readHookEvent(input) {
+  let source = '';
+  for await (const chunk of input) {
+    source += chunk;
+  }
+  if (source.trim() === '') return {};
+
+  const event = JSON.parse(source);
+  if (event === null || Array.isArray(event) || typeof event !== 'object') {
+    throw new Error('Claude hook input must be a JSON object');
+  }
+  return event;
+}
+
+export function buildCliCandidates(root, env) {
+  const candidates = [
+    { command: join(root, 'node_modules', '.bin', 'artifact-graph'), prefix: [] },
+    { command: 'artifact-graph', prefix: [] },
+  ];
+  const legacyCli = env.ARTIFACT_GRAPH_LEGACY_CLI;
+  if (legacyCli) {
+    const legacyPath = isAbsolute(legacyCli) ? legacyCli : resolve(root, legacyCli);
+    if (existsSync(legacyPath)) {
+      candidates.push({ command: process.execPath, prefix: [legacyPath] });
+    }
+  }
+  return candidates;
+}
+
+export async function runStopAudit({
+  input = process.stdin,
+  env = process.env,
+  cwd = process.cwd(),
+  spawn = spawnSync,
+  stderr = (text) => process.stderr.write(text),
+} = {}) {
+  let event;
+  try {
+    event = await readHookEvent(input);
+  } catch (error) {
+    stderr(`artifact-chain-assistant: invalid Claude hook input: ${error.message}\n`);
+    return 2;
+  }
+  if (event.stop_hook_active === true) return 0;
+
+  const root = resolve(env.CLAUDE_PROJECT_DIR || cwd);
+  if (!existsSync(join(root, 'artifact-graph.config.yaml')) &&
+      !existsSync(join(root, 'artifacts', 'traceability-version-lock.json'))) {
+    return 0;
+  }
+
+  for (const candidate of buildCliCandidates(root, env)) {
+    const result = spawn(candidate.command, [
+      ...candidate.prefix,
+      'version-lock', 'audit', '--root', root, '--strict-missing-lock',
+    ], { cwd: root, env, stdio: ['ignore', 'ignore', 'inherit'] });
+    if (result.error?.code === 'ENOENT') continue;
+    if (result.error || result.status !== 0) {
+      stderr('artifact-chain-assistant: version-lock audit failed; repair the lock before stopping.\n');
+      return 2;
+    }
+    return 0;
+  }
+
+  stderr('artifact-chain-assistant: artifact-graph CLI not found.\n');
+  return 2;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await runStopAudit();
+}

package/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/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);
+  }
+}

package/scripts/batch-split.mjs

@@ -0,0 +1,184 @@
+// @feature ACA16 @scenario S-49
+// Deterministic batch splitting for artifact review workflows.
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+/**
+ * Recursively collect all .md files under a directory.
+ */
+async function collectMarkdownFiles(dir, base) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip hidden directories and node_modules
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      files.push(...await collectMarkdownFiles(fullPath, base));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const relativePath = relative(base, fullPath);
+      const content = await readFile(fullPath, 'utf8');
+      files.push({
+        path: relativePath,
+        chars: content.length,
+        content,
+        // For grouping: detect part-*.md files that belong to a batch-*.md
+        groupKey: extractGroupKey(entry.name, relativePath),
+      });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract a group key for related-file co-location.
+ * Files like batch-001-part-1.md, batch-001-part-2.md share the key "batch-001".
+ * Standalone files get a unique key based on their path.
+ */
+function extractGroupKey(fileName, relativePath) {
+  // Match batch-*.md pattern for grouping parts
+  const batchMatch = fileName.match(/^(batch-[^/]+?)(?:-part-\d+)?\.md$/);
+  if (batchMatch) {
+    return `batch:${batchMatch[1]}`;
+  }
+  // Each standalone file is its own group
+  return `file:${relativePath}`;
+}
+
+/**
+ * Sort files deterministically by path.
+ */
+function sortFiles(files) {
+  return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Build batches from sorted files.
+ *
+ * Strategy:
+ * 1. Group files by groupKey to keep related files together.
+ * 2. For each group, if adding the group to the current batch exceeds batch-size,
+ *    and the current batch is non-empty, flush it and start a new one.
+ * 3. If a single group exceeds batch-size, it gets its own batch.
+ * 4. Sort groups by their first file's path for determinism.
+ */
+function buildBatches(files, batchSize) {
+  // Group files by groupKey
+  const groups = new Map();
+  for (const file of files) {
+    if (!groups.has(file.groupKey)) {
+      groups.set(file.groupKey, []);
+    }
+    groups.get(file.groupKey).push(file);
+  }
+
+  // Sort groups by their first file's path for determinism
+  const sortedGroups = [...groups.entries()].sort(([, a], [, b]) =>
+    a[0].path.localeCompare(b[0].path)
+  );
+
+  const batches = [];
+  let currentBatchFiles = [];
+  let currentBatchChars = 0;
+
+  for (const [, groupFiles] of sortedGroups) {
+    const groupChars = groupFiles.reduce((sum, f) => sum + f.chars, 0);
+
+    // If the group alone exceeds batch-size, it gets its own batch
+    if (groupChars >= batchSize) {
+      // Flush current batch if non-empty
+      if (currentBatchFiles.length > 0) {
+        batches.push(currentBatchFiles);
+        currentBatchFiles = [];
+        currentBatchChars = 0;
+      }
+      // This group is its own batch
+      batches.push(groupFiles);
+      continue;
+    }
+
+    // If adding this group would exceed batch-size, flush current batch
+    if (currentBatchChars + groupChars > batchSize && currentBatchFiles.length > 0) {
+      batches.push(currentBatchFiles);
+      currentBatchFiles = [];
+      currentBatchChars = 0;
+    }
+
+    // Add group to current batch
+    currentBatchFiles.push(...groupFiles);
+    currentBatchChars += groupChars;
+  }
+
+  // Flush remaining files
+  if (currentBatchFiles.length > 0) {
+    batches.push(currentBatchFiles);
+  }
+
+  return batches;
+}
+
+/**
+ * Deterministic batch splitting.
+ *
+ * @param {string} targetDir - Directory to scan for .md files
+ * @param {object} options
+ * @param {number} [options.batchSize=40000] - Maximum characters per batch
+ * @returns {Promise<Array<{id: string, files: string[], chars: number}>>}
+ */
+export async function batchSplit(targetDir, options = {}) {
+  const { batchSize = 40000 } = options;
+  const base = resolve(targetDir);
+
+  // Verify target directory exists
+  const targetStat = await stat(base).catch(() => null);
+  if (!targetStat || !targetStat.isDirectory()) {
+    return [];
+  }
+
+  // Collect and sort files
+  const rawFiles = await collectMarkdownFiles(base, base);
+  const files = sortFiles(rawFiles);
+
+  // Build batches
+  const batchArrays = buildBatches(files, batchSize);
+
+  // Format output
+  return batchArrays.map((batchFiles, index) => ({
+    id: `batch-${String(index + 1).padStart(3, '0')}`,
+    files: batchFiles.map(f => f.path),
+    chars: batchFiles.reduce((sum, f) => sum + f.chars, 0),
+  }));
+}
+
+// CLI entry point
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const targetDir = args[0];
+
+  if (!targetDir) {
+    console.error('Usage: node batch-split.mjs <target-dir> [--batch-size N]');
+    process.exit(1);
+  }
+
+  let batchSize = 40000;
+  const sizeIdx = args.indexOf('--batch-size');
+  if (sizeIdx !== -1 && args[sizeIdx + 1]) {
+    batchSize = parseInt(args[sizeIdx + 1], 10);
+    if (isNaN(batchSize) || batchSize <= 0) {
+      console.error('Error: --batch-size must be a positive integer');
+      process.exit(1);
+    }
+  }
+
+  try {
+    const batches = await batchSplit(targetDir, { batchSize });
+    console.log(JSON.stringify(batches, null, 2));
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}