wendkeep 0.88.0 → 0.89.0

package/schema/wendkeep.evidence-envelope-v2.schema.json

@@ -52,6 +52,10 @@
       "type": "array",
       "items": { "$ref": "#/$defs/sensor" }
     },
+    "external_artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/externalArtifact" }
+    },
     "host_coverage": { "$ref": "host-coverage-v1.schema.json" },
     "tdd_attestations": {
       "type": "array",
@@ -100,10 +104,45 @@
         "exit_code": { "type": ["integer", "null"] },
         "output_sha256": { "$ref": "#/$defs/sha256" },
         "output_tail": { "type": "string", "maxLength": 2000 },
+        "artifact_results": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/sensorArtifactResult" }
+        },
         "note": { "type": "string", "maxLength": 2000 },
         "survivors": { "type": "array" },
         "ts": { "type": "string", "format": "date-time" }
       }
+    },
+    "sensorArtifactResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "external_id", "path", "algorithm", "digest"],
+      "properties": {
+        "schema_version": { "const": 1 },
+        "external_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+        "path": { "type": "string", "minLength": 1 },
+        "algorithm": { "const": "sha256" },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "externalArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema_version", "source", "external_id", "kind", "path", "sha256", "authority", "sensor_id", "task_id", "git_blob", "manifest_path", "manifest_git_blob"],
+      "properties": {
+        "schema_version": { "const": 1 },
+        "source": { "const": "superpowers" },
+        "external_id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["artifact", "review", "commit"] },
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "authority": { "enum": ["reported", "verified"] },
+        "sensor_id": { "type": "string", "minLength": 1 },
+        "task_id": { "type": "string", "minLength": 1 },
+        "git_blob": { "$ref": "#/$defs/gitObject" },
+        "manifest_path": { "const": ".wendkeep/bridge-artifacts.json" },
+        "manifest_git_blob": { "$ref": "#/$defs/gitObject" }
+      }
     }
   }
 }

package/schema/wendkeep.sensors.schema.json

@@ -40,6 +40,20 @@
           "severity": { "enum": ["critical", "warning"], "default": "critical" },
           "type": { "enum": ["command", "mutation"], "default": "command" },
           "command": { "type": "string", "minLength": 1 },
+          "artifact_results": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["schema_version", "external_id", "path", "algorithm"],
+              "properties": {
+                "schema_version": { "const": 1 },
+                "external_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+                "path": { "type": "string", "minLength": 1 },
+                "algorithm": { "const": "sha256" }
+              }
+            }
+          },
           "report": {
             "type": "string",
             "description": "type: mutation only — path (project-relative) to the mutation-testing-elements report."

package/src/doctor.mjs

@@ -1,5 +1,6 @@
 // `wendkeep doctor` — vault/session integrity (hooks/vault-health.mjs) PLUS the a2
 // harness integrity check (hooks/harness-doctor.mjs). Exits 1 on any error.
+import * as bridgeFs from 'node:fs';
 import { resolve } from 'node:path';
 import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines, checkUnpricedModels, renderUnpricedModelLines, checkStaleDerivedSections, renderStaleDerivedSectionLines, checkSessionObservability, renderSessionObservabilityLines } from '../hooks/harness-doctor.mjs';
 import { diagnoseManagedWorktrees } from './worktree.mjs';
@@ -20,6 +21,7 @@ import { inspectPortableState } from './portable.mjs';
 import { inspectSyncOutbox, readLocalSyncState } from './sync-outbox.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
 import { inspectGitCommitHooks } from './git-commit-hooks.mjs';
+import { inspectEcosystemBridges, renderEcosystemBridgeLines } from '../packages/integrations/src/ecosystem-bridge.mjs';
 
 const healthStatusLabel = (status) => ({
   healthy: 'saudável', warning: 'atenção', degraded: 'degradada', blocked: 'bloqueada', legacy: 'legado',
@@ -178,6 +180,8 @@ export function runDoctor(argv) {
   for (const w of warnings) process.stdout.write(`  ! ${w}\n`);
 
   const worktrees = diagnoseManagedWorktrees({ startDir: projectRoot });
+  const bridges = inspectEcosystemBridges({ projectRoot, fs: bridgeFs });
+  process.stdout.write(`\n${renderEcosystemBridgeLines(bridges).join('\n')}\n`);
   process.stdout.write(`\n[worktrees] ${worktrees.initialized ? `${worktrees.issues.length} problema(s)` : 'não inicializado'}\n`);
   for (const issue of worktrees.issues) {
     process.stdout.write(`  → ${issue.slug}: ${issue.errorCode} — ${issue.repair}\n`);
@@ -264,6 +268,7 @@ export function runDoctor(argv) {
     || warnings.length
     || worktrees.issues.length
     || (commitHooks.configured && commitHooks.status !== 'healthy')
+    || !bridges.ok
     || activeContexts.issues.length
     || ['diverged', 'invalid'].includes(portable.status)
     || sync.status === 'corrupt'
@@ -276,5 +281,5 @@ export function runDoctor(argv) {
     || (staleDerived.notes || staleDerived.items || []).length
     || !observability.ok
   );
-  return (scope !== 'runtime' && (healthStatus !== 0 || recallStatus !== 0)) || errors.length || strictDebt ? 1 : 0;
+  return (scope !== 'runtime' && (healthStatus !== 0 || recallStatus !== 0)) || errors.length || !bridges.ok || strictDebt ? 1 : 0;
 }

package/src/ecosystem-bridge-artifact-collector.mjs

@@ -0,0 +1,111 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
+import { isProjectContainedPath } from '../packages/integrations/src/bridge-config.mjs';
+
+const MANIFEST_PATH = '.wendkeep/bridge-artifacts.json';
+const MAX_ARTIFACT_BYTES = 1024 * 1024;
+
+function fail(code, message) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function gitText(projectRoot, args, spawn = spawnSync) {
+  const result = spawn('git', args, {
+    cwd: projectRoot, encoding: 'utf8', windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return result.status === 0 && !result.error ? String(result.stdout || '').trim() : '';
+}
+
+function trackedBlob(projectRoot, path, spawn) {
+  if (!gitText(projectRoot, ['ls-files', '--error-unmatch', '--', path], spawn)) return '';
+  const working = gitText(projectRoot, ['hash-object', '--', path], spawn);
+  const indexed = gitText(projectRoot, ['rev-parse', `:${path}`], spawn);
+  return working && working === indexed ? indexed : '';
+}
+
+function safeProjectFile(projectRoot, path, code) {
+  const candidate = resolve(projectRoot, String(path || ''));
+  if (!String(path || '').trim() || !isProjectContainedPath(projectRoot, candidate)
+    || !existsSync(candidate) || !lstatSync(candidate).isFile()) {
+    fail(code, `bridge artifact path is unavailable: ${path || '<missing>'}`);
+  }
+  const file = realpathSync(candidate);
+  if (!isProjectContainedPath(projectRoot, file) || lstatSync(file).size > MAX_ARTIFACT_BYTES) {
+    fail(code, `bridge artifact path is unsafe: ${path}`);
+  }
+  return { file, path: relative(projectRoot, file).replaceAll('\\', '/') };
+}
+
+function readManifest(projectRoot, spawn) {
+  const candidate = resolve(projectRoot, MANIFEST_PATH);
+  const tracked = gitText(projectRoot, ['ls-files', '--error-unmatch', '--', MANIFEST_PATH], spawn);
+  if (!tracked && !existsSync(candidate)) return null;
+  if (!tracked || !existsSync(candidate)) {
+    fail('BRIDGE_ARTIFACT_MANIFEST_UNTRACKED', 'bridge artifact manifest must exist and match the Git index');
+  }
+  const manifest = safeProjectFile(projectRoot, MANIFEST_PATH, 'BRIDGE_ARTIFACT_MANIFEST_INVALID');
+  const gitBlob = trackedBlob(projectRoot, manifest.path, spawn);
+  if (!gitBlob) fail('BRIDGE_ARTIFACT_MANIFEST_UNTRACKED', 'bridge artifact manifest must match the Git index');
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(manifest.file, 'utf8')); }
+  catch { fail('BRIDGE_ARTIFACT_MANIFEST_INVALID', 'bridge artifact manifest must be valid JSON'); }
+  if (parsed?.schema_version !== 1 || !Array.isArray(parsed?.artifacts)) {
+    fail('BRIDGE_ARTIFACT_MANIFEST_INVALID', 'bridge artifact manifest requires schema_version 1 and artifacts');
+  }
+  if (Object.keys(parsed).some((key) => !['schema_version', 'artifacts'].includes(key))) {
+    fail('BRIDGE_ARTIFACT_MANIFEST_INVALID', 'bridge artifact manifest contains unsupported fields');
+  }
+  return { artifacts: parsed.artifacts, gitBlob, path: manifest.path };
+}
+
+export function collectBridgeArtifactEvidence({
+  projectRoot, tasks = [], sensors = [], spawn = spawnSync,
+} = {}) {
+  const root = realpathSync(resolve(projectRoot));
+  const manifest = readManifest(root, spawn);
+  if (!manifest) return [];
+  const taskById = new Map((tasks || []).map((task) => [String(task.id || ''), task]));
+  const sensorById = new Map((sensors || []).map((sensor) => [String(sensor.id || ''), sensor]));
+  const seen = new Set();
+  return manifest.artifacts.map((entry) => {
+    const externalId = String(entry?.external_id || '').trim();
+    const kind = String(entry?.kind || '').trim();
+    const sensorId = String(entry?.sensor_id || '').trim();
+    const taskId = String(entry?.task_id || '').trim();
+    if (Object.keys(entry || {}).some((key) => ![
+      'source', 'external_id', 'kind', 'path', 'sensor_id', 'task_id',
+    ].includes(key)) || entry?.source !== 'superpowers' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(externalId)
+      || !['artifact', 'review', 'commit'].includes(kind) || !sensorId || !taskId || seen.has(externalId)) {
+      fail('BRIDGE_ARTIFACT_MANIFEST_INVALID', `invalid or duplicate bridge artifact: ${externalId || '<missing>'}`);
+    }
+    seen.add(externalId);
+    const task = taskById.get(taskId);
+    const requiredSensors = Array.isArray(task?.sensors) && task.sensors.length ? task.sensors : [task?.sensor].filter(Boolean);
+    if (!task || !requiredSensors.includes(sensorId)) {
+      fail('BRIDGE_ARTIFACT_TASK_UNBOUND', `bridge artifact ${externalId} is not bound to task ${taskId} and sensor ${sensorId}`);
+    }
+    const artifact = safeProjectFile(root, entry.path, 'BRIDGE_ARTIFACT_FORGED');
+    const gitBlob = trackedBlob(root, artifact.path, spawn);
+    if (!gitBlob) fail('BRIDGE_ARTIFACT_FORGED', `bridge artifact ${externalId} must match the Git index`);
+    const digest = createHash('sha256').update(readFileSync(artifact.file)).digest('hex');
+    const sensor = sensorById.get(sensorId);
+    const result = (sensor?.artifact_results || []).find((item) => (
+      item?.schema_version === 1 && item.external_id === externalId && item.path === artifact.path
+      && item.algorithm === 'sha256' && item.digest === digest
+    ));
+    if (sensor?.status === 'green' && sensor?.exit_code === 0 && !result) {
+      fail('BRIDGE_ARTIFACT_RESULT_MISSING', `green sensor ${sensorId} did not produce the bound digest for ${externalId}`);
+    }
+    const verified = sensor?.status === 'green' && sensor?.exit_code === 0 && Boolean(result);
+    return {
+      schema_version: 1,
+      source: 'superpowers', external_id: externalId, kind, path: artifact.path,
+      sha256: digest, authority: verified ? 'verified' : 'reported', sensor_id: sensorId, task_id: taskId,
+      git_blob: gitBlob, manifest_path: manifest.path, manifest_git_blob: manifest.gitBlob,
+    };
+  });
+}

package/src/ecosystem-bridge-baseline.mjs

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getLocale } from '../hooks/locale.mjs';
+import { writeVaultFileAtomic } from '../packages/vault/src/vault-path-safety.mjs';
+import { validateBridgeProjection } from '../packages/integrations/src/bridge-contract.mjs';
+
+const BASELINE_FILE = 'spec-kit-baseline.v1.json';
+
+function safeChangeSlug(value) {
+  const slug = String(value || '').trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(slug) || slug.includes('..')) {
+    throw Object.assign(new Error('a safe change slug is required for the Spec Kit baseline'), {
+      code: 'BRIDGE_BASELINE_CONTEXT_INVALID',
+    });
+  }
+  return slug;
+}
+
+export function specKitBaselinePath(vaultBase, changeSlug) {
+  return join(vaultBase, getLocale(vaultBase).folders.changes, safeChangeSlug(changeSlug), BASELINE_FILE);
+}
+
+export function readSpecKitBaseline(vaultBase, changeSlug) {
+  const path = specKitBaselinePath(vaultBase, changeSlug);
+  if (!existsSync(path)) return null;
+  let projection;
+  try { projection = JSON.parse(readFileSync(path, 'utf8')); } catch {
+    throw Object.assign(new Error('canonical Spec Kit baseline is invalid JSON'), { code: 'BRIDGE_BASELINE_INVALID' });
+  }
+  const validation = validateBridgeProjection(projection);
+  if (!validation.valid || projection.ok !== true || projection.adapter !== 'spec-kit') {
+    throw Object.assign(new Error('canonical Spec Kit baseline is invalid or blocked'), {
+      code: 'BRIDGE_BASELINE_INVALID', diagnostics: validation.diagnostics,
+    });
+  }
+  return projection;
+}
+
+export function writeSpecKitBaseline(vaultBase, changeSlug, projection) {
+  const validation = validateBridgeProjection(projection);
+  if (!validation.valid || projection.ok !== true || projection.adapter !== 'spec-kit') {
+    throw Object.assign(new Error('only a valid green Spec Kit projection can become baseline'), {
+      code: 'BRIDGE_BASELINE_INVALID', diagnostics: validation.diagnostics,
+    });
+  }
+  const path = specKitBaselinePath(vaultBase, changeSlug);
+  const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, safeChangeSlug(changeSlug));
+  if (!existsSync(changeDir)) {
+    throw Object.assign(new Error(`change not found for Spec Kit baseline: ${changeSlug}`), {
+      code: 'BRIDGE_BASELINE_CONTEXT_INVALID',
+    });
+  }
+  writeVaultFileAtomic(vaultBase, path, `${JSON.stringify(projection, null, 2)}\n`, 'utf8', {
+    scopeRoot: changeDir, label: 'baseline canônico Spec Kit', code: 'BRIDGE_BASELINE_PATH_UNSAFE',
+  });
+  return projection;
+}

package/src/ecosystem-bridge-proof.mjs

@@ -0,0 +1,97 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { getLocale } from '../hooks/locale.mjs';
+import { parseTasks } from '../hooks/change-core.mjs';
+import { buildEffectiveRequirementPackage, tasksHashOf } from '../hooks/spec-core.mjs';
+import { loadSensorsDetailed, requiredSensors } from '../hooks/sensors-core.mjs';
+import { evaluateEvidenceBinding } from '../packages/vault/src/evidence-envelope.mjs';
+import { bridgeSha256, canonicalBridgeJson } from '../packages/integrations/src/index.mjs';
+import { issueCanonicalArtifactProof } from '../packages/integrations/src/canonical-bridge-authority.mjs';
+import { captureGitSnapshot, resolveEvidenceIdentity, sensorConfigSha256 } from './evidence-envelope.mjs';
+import { collectBridgeArtifactEvidence } from './ecosystem-bridge-artifact-collector.mjs';
+
+function safeSlug(value) {
+  const slug = String(value || '').trim();
+  return /^[a-z0-9][a-z0-9._-]*$/i.test(slug) && !slug.includes('..') ? slug : '';
+}
+
+export function deriveCanonicalArtifactProof({
+  artifact, proof, projectRoot, vaultBase, changeSlug, sessionId = '', spawn = spawnSync,
+} = {}) {
+  try {
+    const slug = safeSlug(changeSlug);
+    if (!slug || proof?.type !== 'evidence-envelope'
+      || String(proof?.external_id || '') !== String(artifact?.external_id || '')) return null;
+
+    const root = realpathSync(resolve(projectRoot));
+
+    const evidencePath = join(vaultBase, getLocale(vaultBase).folders.changes, slug, 'evidencia.json');
+    if (!existsSync(evidencePath) || !lstatSync(evidencePath).isFile()) return null;
+    const evidence = JSON.parse(readFileSync(evidencePath, 'utf8'));
+    const changeDir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+    const tarefas = readFileSync(join(changeDir, 'tarefas.md'), 'utf8');
+    const tasks = parseTasks(tarefas);
+    const sensorIds = requiredSensors(tasks);
+    const loaded = loadSensorsDetailed(root);
+    if (loaded.error || loaded.missing) return null;
+    const reqIds = [...new Set(tasks.flatMap((task) => task.reqs ?? []))];
+    const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
+    const identity = resolveEvidenceIdentity({
+      vaultBase, projectRoot: root, changeSlug: slug, sessionId, spawn,
+    });
+    const snapshot = captureGitSnapshot(root, { spawn });
+    const binding = evaluateEvidenceBinding(evidence, {
+      change_slug: slug,
+      identity,
+      snapshot,
+      tasks_sha256: tasksHashOf(tarefas),
+      effective_spec_sha256: `sha256:${effective.hash}`,
+      sensor_config_sha256: sensorConfigSha256(loaded.sensors, sensorIds),
+    });
+    if (binding.state !== 'bound') return null;
+    const envelopeArtifact = (evidence.external_artifacts || []).find((item) => (
+      item.source === 'superpowers'
+      && item.external_id === artifact.external_id
+      && item.kind === artifact.kind
+      && item.sha256 === artifact.sha256
+      && item.authority === 'verified'
+    ));
+    if (!envelopeArtifact) return null;
+    const currentArtifacts = collectBridgeArtifactEvidence({
+      projectRoot: root, tasks, sensors: evidence.sensors || [], spawn,
+    });
+    const currentArtifact = currentArtifacts.find((item) => item.external_id === artifact.external_id);
+    if (!currentArtifact || currentArtifact.authority !== 'verified'
+      || canonicalBridgeJson(currentArtifact) !== canonicalBridgeJson(envelopeArtifact)) return null;
+    const sensor = (evidence.sensors || []).find((item) => item.id === envelopeArtifact.sensor_id);
+    const artifactResult = (sensor?.artifact_results || []).find((item) => (
+      item.external_id === artifact.external_id && item.path === envelopeArtifact.path
+      && item.algorithm === 'sha256' && item.digest === artifact.sha256
+    ));
+    if (!sensor || sensor.status !== 'green' || sensor.exit_code !== 0 || !artifactResult) return null;
+
+    const canonical = {
+      schema_version: 1,
+      contract_kind: 'proof',
+      type: 'evidence-envelope',
+      authority: 'verified',
+      external_id: artifact.external_id,
+      artifact_sha256: artifact.sha256,
+      origin: { tool: 'wendkeep', evidence_envelope_id: evidence.envelope_id },
+      provenance: { state: 'verified', source: 'wendkeep-evidence-envelope' },
+      evidence_envelope_id: evidence.envelope_id,
+      sensor_id: envelopeArtifact.sensor_id,
+      task_id: envelopeArtifact.task_id,
+      path: envelopeArtifact.path,
+      head_sha: evidence.head_sha,
+      git_blob: envelopeArtifact.git_blob,
+      manifest_git_blob: envelopeArtifact.manifest_git_blob,
+    };
+    canonical.proof_id = bridgeSha256(canonicalBridgeJson(canonical));
+    return issueCanonicalArtifactProof(canonical);
+  } catch {
+    return null;
+  }
+}

package/src/ecosystem-bridges.mjs

@@ -0,0 +1,227 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import * as bridgeFs from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  importSpecKitProjection,
+  buildSpecKitStatusProjection,
+  ingestSuperpowersArtifacts,
+  inspectEcosystemBridges,
+  inspectBridgeAdapterRoot,
+  readBridgeConfig,
+  verifyExternalArtifact,
+  isProjectContainedPath,
+  sealBridgeProjection,
+  bridgeDiagnostic,
+} from '../packages/integrations/src/index.mjs';
+import { buildCanonicalExternalTaskDispatch } from './task.mjs';
+import { resolveProjectVault } from './project-vault.mjs';
+import { readSpecKitBaseline, writeSpecKitBaseline } from './ecosystem-bridge-baseline.mjs';
+import { deriveCanonicalArtifactProof } from './ecosystem-bridge-proof.mjs';
+
+export const BRIDGE_HELP = `wendkeep bridge <status|import-spec-kit|export-status|dispatch-superpowers|verify-artifacts>
+
+  --project <path>          consumer project (default: current directory)
+  --config <path>           config path (default: .wendkeep/ecosystem-bridges.json)
+  --task-id <id>            canonical WendKeep task selected from the active context
+  --task-contract <path>    optional submitted copy; rejected when it differs from canonical state
+  --spec-projection <path>  optional read-only Spec Kit projection
+  --change <slug>           causal change holding the canonical Spec Kit baseline/evidence
+  --accept-baseline         anchor the first green Spec Kit projection in the bound Vault
+  --input <path>            external artifacts JSON for verify-artifacts
+  --proofs <path>           artifact IDs to resolve from the canonical Evidence Envelope
+  --json                    emit typed JSON
+`;
+
+function opt(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function inside(root, target) {
+  return isProjectContainedPath(root, target);
+}
+
+function readProjectJson(projectRoot, pathValue, label, optional = false) {
+  if (!pathValue && optional) return null;
+  if (!pathValue) throw Object.assign(new Error(`${label} path is required`), { code: 'BRIDGE_ARGUMENT_INVALID' });
+  const rootReal = realpathSync(projectRoot);
+  const path = resolve(projectRoot, pathValue);
+  if (!inside(rootReal, path)) throw Object.assign(new Error(`${label} escapes the project`), { code: 'BRIDGE_INPUT_ESCAPE' });
+  if (!existsSync(path) || !lstatSync(path).isFile()) {
+    throw Object.assign(new Error(`${label} file not found`), { code: 'BRIDGE_INPUT_MISSING' });
+  }
+  const pathReal = realpathSync(path);
+  if (!inside(rootReal, pathReal)) throw Object.assign(new Error(`${label} escapes the project`), { code: 'BRIDGE_INPUT_ESCAPE' });
+  if (lstatSync(pathReal).size > 1024 * 1024) throw Object.assign(new Error(`${label} exceeds 1 MiB`), { code: 'BRIDGE_INPUT_LIMIT' });
+  try {
+    return JSON.parse(readFileSync(pathReal, 'utf8'));
+  } catch (error) {
+    throw Object.assign(new Error(`${label} is not valid JSON: ${error.message}`), { code: 'BRIDGE_INPUT_INVALID' });
+  }
+}
+
+function write(value, json) {
+  process.stdout.write(json ? `${JSON.stringify(value)}\n` : `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function runEcosystemBridge(argv = []) {
+  const sub = argv[0];
+  if (!sub || ['help', '--help', '-h'].includes(sub)) {
+    process.stdout.write(BRIDGE_HELP);
+    return 0;
+  }
+  const json = argv.includes('--json');
+  const projectRoot = resolve(opt(argv, '--project') || process.cwd());
+  try {
+    if (sub === 'status') {
+      const result = inspectEcosystemBridges({ projectRoot, configPath: opt(argv, '--config'), fs: bridgeFs });
+      write(result, json);
+      return result.ok ? 0 : 1;
+    }
+    const loaded = readBridgeConfig(projectRoot, opt(argv, '--config'), { fs: bridgeFs });
+    if (sub === 'import-spec-kit') {
+      if (opt(argv, '--previous')) {
+        throw Object.assign(new Error('--previous cannot replace the canonical Vault baseline'), { code: 'BRIDGE_ARGUMENT_INVALID' });
+      }
+      const adapter = loaded.config.adapters['spec-kit'];
+      if (!adapter.enabled) {
+        const result = importSpecKitProjection({ projectRoot, config: loaded.config, fs: bridgeFs });
+        write(result, json);
+        return result.ok ? 0 : 1;
+      }
+      const changeSlug = opt(argv, '--change');
+      if (!changeSlug) throw Object.assign(new Error('--change is required for the canonical Spec Kit baseline'), { code: 'BRIDGE_BASELINE_CONTEXT_INVALID' });
+      const vault = resolveProjectVault({ startDir: projectRoot, explicitVault: opt(argv, '--vault') || '' }).base;
+      const baseline = readSpecKitBaseline(vault, changeSlug);
+      const current = importSpecKitProjection({ projectRoot, config: loaded.config, previousProjection: baseline, fs: bridgeFs });
+      let result = current;
+      if (argv.includes('--accept-baseline')) {
+        if (baseline && baseline.projection_id !== current.projection_id) {
+          result = sealBridgeProjection({
+            ...current, ok: false,
+            diagnostics: [...current.diagnostics, bridgeDiagnostic('BRIDGE_BASELINE_STALE', {
+              adapter: 'spec-kit', message: 'canonical Spec Kit baseline already exists and cannot be replaced implicitly',
+            })],
+          });
+        } else if (!baseline && current.ok) writeSpecKitBaseline(vault, changeSlug, current);
+      } else if (!baseline) {
+        result = sealBridgeProjection({
+          ...current, ok: false,
+          diagnostics: [...current.diagnostics, bridgeDiagnostic('BRIDGE_BASELINE_MISSING', {
+            adapter: 'spec-kit', message: 'anchor the first projection with --accept-baseline',
+          })],
+        });
+      }
+      write(result, json);
+      return result.ok ? 0 : 1;
+    }
+    if (sub === 'export-status') {
+      const sourceProjection = readProjectJson(projectRoot, opt(argv, '--spec-projection'), 'Spec Kit projection');
+      const taskContract = readProjectJson(projectRoot, opt(argv, '--task-contract'), 'task contract', true);
+      const artifactInput = readProjectJson(projectRoot, opt(argv, '--input'), 'artifact input', true);
+      const result = buildSpecKitStatusProjection({
+        sourceProjection,
+        taskContracts: taskContract ? [taskContract] : [],
+        artifacts: artifactInput ? (Array.isArray(artifactInput) ? artifactInput : artifactInput.artifacts || []) : [],
+      });
+      write(result, json);
+      return 0;
+    }
+    if (sub === 'dispatch-superpowers') {
+      const taskId = opt(argv, '--task-id');
+      if (!taskId) throw Object.assign(new Error('task id is required'), { code: 'BRIDGE_ARGUMENT_INVALID' });
+      const submitted = readProjectJson(projectRoot, opt(argv, '--task-contract'), 'task contract', true);
+      const specKitProjection = readProjectJson(projectRoot, opt(argv, '--spec-projection'), 'Spec Kit projection', true);
+      const adapter = loaded.config.adapters.superpowers;
+      const adapterRoot = inspectBridgeAdapterRoot(projectRoot, adapter.root || '.superpowers', { adapter: 'superpowers', fs: bridgeFs });
+      if (!adapterRoot.valid) {
+        const result = {
+          schema_version: 1, adapter: 'superpowers', active: false, ok: false,
+          diagnostics: adapterRoot.diagnostics,
+        };
+        write(result, json);
+        return 1;
+      }
+      const present = adapterRoot.present;
+      const vault = resolveProjectVault({
+        startDir: projectRoot,
+        explicitVault: opt(argv, '--vault') || '',
+      }).base;
+      const changeSlug = opt(argv, '--change');
+      let baselineProjection = null;
+      if (loaded.config.adapters['spec-kit'].enabled) {
+        if (!changeSlug || !specKitProjection) {
+          const result = {
+            schema_version: 1, adapter: 'superpowers', active: true, ok: false,
+            diagnostics: [bridgeDiagnostic('BRIDGE_BASELINE_MISSING', {
+              adapter: 'spec-kit', message: 'dispatch requires --change and --spec-projection when Spec Kit is active',
+            })],
+          };
+          write(result, json);
+          return 1;
+        }
+        baselineProjection = readSpecKitBaseline(vault, changeSlug);
+        if (!baselineProjection) {
+          const result = {
+            schema_version: 1, adapter: 'superpowers', active: true, ok: false,
+            diagnostics: [bridgeDiagnostic('BRIDGE_BASELINE_MISSING', {
+              adapter: 'spec-kit', message: 'canonical Spec Kit baseline is missing from the bound Vault change',
+            })],
+          };
+          write(result, json);
+          return 1;
+        }
+      }
+      const authorityArgs = ['--project', projectRoot, '--vault', vault, '--task-id', taskId];
+      for (const name of ['--session', '--change']) {
+        const value = opt(argv, name);
+        if (value) authorityArgs.push(name, value);
+      }
+      const result = buildCanonicalExternalTaskDispatch({
+        adapter: 'superpowers',
+        authorityArgv: authorityArgs,
+        taskId,
+        submittedTaskContract: submitted,
+        projectRoot,
+        specKitProjection,
+        baselineProjection,
+        config: loaded.config,
+        detectedVersion: adapter.version || '',
+        present,
+      });
+      write(result, json);
+      return result.ok ? 0 : 1;
+    }
+    if (sub === 'verify-artifacts') {
+      const input = readProjectJson(projectRoot, opt(argv, '--input'), 'artifact input');
+      const proofs = readProjectJson(projectRoot, opt(argv, '--proofs'), 'proof input');
+      const artifacts = ingestSuperpowersArtifacts(Array.isArray(input) ? input : input.artifacts);
+      const proofList = (Array.isArray(proofs) ? proofs : proofs.proofs) || [];
+      const canonicalRequested = proofList.some((proof) => proof?.type === 'evidence-envelope');
+      const changeSlug = opt(argv, '--change');
+      const vault = canonicalRequested && changeSlug
+        ? resolveProjectVault({ startDir: projectRoot, explicitVault: opt(argv, '--vault') || '' }).base
+        : '';
+      const verified = artifacts.map((artifact) => {
+        const artifactProofs = proofList.filter((proof) => (
+          !proof.external_id || proof.external_id === artifact.external_id
+        ));
+        const canonicalProofs = vault ? artifactProofs.map((proof) => deriveCanonicalArtifactProof({
+          artifact, proof, projectRoot, vaultBase: vault, changeSlug,
+          sessionId: opt(argv, '--session') || '',
+        })).filter(Boolean) : [];
+        return verifyExternalArtifact(artifact, { proofs: artifactProofs, canonicalProofs });
+      });
+      const result = { schema_version: 1, ok: verified.every((item) => item.authority === 'verified'), artifacts: verified };
+      write(result, json);
+      return result.ok ? 0 : 1;
+    }
+    throw Object.assign(new Error(`unknown bridge subcommand: ${sub}`), { code: 'BRIDGE_SUBCOMMAND_UNKNOWN' });
+  } catch (error) {
+    const payload = { ok: false, code: error?.code || 'BRIDGE_COMMAND_FAILED', error: error?.message || String(error) };
+    process.stderr.write(json ? `${JSON.stringify(payload)}\n` : `wendkeep bridge: ${payload.code}: ${payload.error}\n`);
+    return 2;
+  }
+}

package/src/evidence-envelope.mjs

@@ -268,6 +268,7 @@ export function buildEvidenceEnvelope({
   version = '',
   runtimePlatform = `${process.platform}-${process.arch}`,
   hostCoverage = null,
+  externalArtifacts = [],
 } = {}) {
   const envelope = {
     schema_version: 2,
@@ -287,6 +288,7 @@ export function buildEvidenceEnvelope({
     started_at: startedAt,
     finished_at: finishedAt,
     sensors,
+    ...(externalArtifacts.length ? { external_artifacts: structuredClone(externalArtifacts) } : {}),
     ...(hostCoverage ? { host_coverage: structuredClone(hostCoverage) } : {}),
     tdd_attestations: tddAttestations,
   };

package/src/task-contracts.mjs

@@ -43,6 +43,25 @@ function uniqueStrings(values) {
   return [...new Set(list.map((value) => String(value).trim()).filter(Boolean))];
 }
 
+export function normalizeExternalArtifactEvidence(input = {}) {
+  const source = String(input.source || '').trim();
+  const externalId = String(input.external_id || '').trim();
+  const kind = String(input.kind || '').trim();
+  const sha256Value = String(input.sha256 || '').trim();
+  if (!source || !externalId || !['artifact', 'review', 'commit'].includes(kind)
+    || !/^[a-f0-9]{64}$/.test(sha256Value)) {
+    throw Object.assign(new Error('external artifact evidence is incomplete'), { code: 'TASK_EXTERNAL_ARTIFACT_INVALID' });
+  }
+  return {
+    schema_version: 1,
+    source,
+    external_id: externalId,
+    kind,
+    sha256: sha256Value,
+    authority: 'reported',
+  };
+}
+
 function bindingFrom(input) {
   return {
     project_id: String(input.projectId || ''),