wendkeep 0.88.0 → 0.89.0

package/packages/integrations/src/spec-kit-adapter.mjs

@@ -0,0 +1,259 @@
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { assessBridgeAdapter } from './bridge-config.mjs';
+import {
+  bridgeSha256, canonicalBridgeJson, createBridgeProjection, detectBridgeDrift,
+  sealBridgeProjection, validateBridgeProjection, validateBridgeRuntimeEnvelope,
+} from './bridge-contract.mjs';
+import { bridgeDiagnostic } from './bridge-diagnostics.mjs';
+
+const MAX_SOURCE_FILES = 256;
+const MAX_SOURCE_BYTES = 1024 * 1024;
+
+function inside(root, target) {
+  const rel = relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
+function findMarkdownFiles(root, fs) {
+  const { existsSync, lstatSync, readdirSync } = fs;
+  const files = [];
+  function visit(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = resolve(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(path);
+        if (files.length > MAX_SOURCE_FILES) throw Object.assign(new Error('Spec Kit source exceeds file limit'), { code: 'BRIDGE_SOURCE_LIMIT' });
+      }
+    }
+  }
+  if (existsSync(root)) {
+    const stat = lstatSync(root);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) visit(root);
+  }
+  return files.sort();
+}
+
+function sourceKind(path) {
+  const name = basename(path).toLowerCase();
+  if (name === 'constitution.md') return 'constitution';
+  if (name === 'tasks.md') return 'task';
+  if (name === 'plan.md') return 'plan';
+  return 'spec';
+}
+
+function idsFor(kind, content, path) {
+  const patterns = kind === 'task'
+    ? [/\b(T\d{3,})\b/g]
+    : kind === 'constitution'
+      ? [/\b(CONST-[A-Z0-9-]+)\b/g]
+      : kind === 'spec'
+        ? [/\b([A-Z][A-Z0-9]*-\d+)\b/g, /\b(US\d+)\b/g]
+        : [];
+  const ids = [];
+  for (const pattern of patterns) {
+    for (const match of content.matchAll(pattern)) if (!ids.includes(match[1])) ids.push(match[1]);
+  }
+  if (ids.length) return ids;
+  const rel = path.replaceAll('\\', '/');
+  return [`${rel.replace(/\.md$/i, '').replace(/[^a-zA-Z0-9_-]+/g, ':')}`];
+}
+
+function featureFor(projectRoot, path) {
+  const parts = relative(projectRoot, path).replaceAll('\\', '/').split('/');
+  const specsIndex = parts.lastIndexOf('specs');
+  const change_slug = specsIndex >= 0 ? String(parts[specsIndex + 1] || '') : '';
+  return { change_slug, capability: change_slug.replace(/^\d+[-_]?/, '') || change_slug };
+}
+
+function linkedTasks(content) {
+  const links = new Map();
+  for (const line of String(content).split(/\r?\n/)) {
+    const taskId = line.match(/\b(T\d{3,})\b/)?.[1];
+    if (!taskId) continue;
+    for (const match of line.matchAll(/\b([A-Z][A-Z0-9]*-\d+|US\d+)\b/g)) {
+      const ids = links.get(match[1]) || [];
+      if (!ids.includes(taskId)) ids.push(taskId);
+      links.set(match[1], ids);
+    }
+  }
+  return links;
+}
+
+function titleFor(content) {
+  return String(content).match(/^#\s+(.+)$/m)?.[1]?.trim().slice(0, 300) || '';
+}
+
+export function detectSpecKit({ projectRoot, config, fs = null } = {}) {
+  if (!fs || ['existsSync', 'lstatSync', 'readFileSync', 'realpathSync'].some((name) => typeof fs[name] !== 'function')) {
+    return {
+      present: false,
+      source: resolve(projectRoot, config?.adapters?.['spec-kit']?.root || '.specify'),
+      version: '',
+      assessment: { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_SOURCE_INVALID', {
+        adapter: 'spec-kit', message: 'bridge filesystem capability is unavailable',
+      })] },
+    };
+  }
+  const { existsSync, lstatSync, readFileSync, realpathSync } = fs;
+  const adapter = config?.adapters?.['spec-kit'] || { enabled: false };
+  const source = resolve(projectRoot, adapter.root || '.specify');
+  if (!adapter.enabled) {
+    return { present: existsSync(source), source, version: '', assessment: assessBridgeAdapter('spec-kit', { config, present: existsSync(source) }) };
+  }
+  if (!existsSync(source) || !lstatSync(source).isDirectory()) {
+    return { present: false, source, version: '', assessment: assessBridgeAdapter('spec-kit', { config, present: false }) };
+  }
+  const projectReal = realpathSync(projectRoot);
+  const sourceReal = realpathSync(source);
+  if (!inside(projectReal, sourceReal)) {
+    return {
+      present: false,
+      source,
+      version: '',
+      assessment: { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_SOURCE_INVALID', { adapter: 'spec-kit', path: source })] },
+    };
+  }
+  const versionPath = resolve(sourceReal, 'version');
+  const version = adapter.version || (existsSync(versionPath) ? readFileSync(versionPath, 'utf8').trim() : '');
+  return { present: true, source: sourceReal, version, assessment: assessBridgeAdapter('spec-kit', { config, detectedVersion: version }) };
+}
+
+export function importSpecKitProjection({ projectRoot, config, previousProjection = null, fs = null } = {}) {
+  const detected = detectSpecKit({ projectRoot: resolve(projectRoot), config, fs });
+  if (!detected.assessment.available) {
+    const disabled = detected.assessment.diagnostics.every((item) => !item.blocking);
+    return {
+      schema_version: 1,
+      adapter: 'spec-kit',
+      authority: 'reported',
+      active: false,
+      ok: disabled,
+      references: [],
+      diagnostics: detected.assessment.diagnostics,
+    };
+  }
+  try {
+    if (!fs || ['lstatSync', 'readFileSync', 'readdirSync'].some((name) => typeof fs[name] !== 'function')) {
+      throw Object.assign(new Error('bridge filesystem capability is unavailable'), { code: 'BRIDGE_SOURCE_INVALID' });
+    }
+    const { lstatSync, readFileSync } = fs;
+    const files = [
+      ...findMarkdownFiles(resolve(detected.source, 'memory'), fs),
+      ...findMarkdownFiles(resolve(detected.source, 'specs'), fs),
+    ];
+    const references = [];
+    const taskLinks = new Map();
+    for (const path of [...new Set(files)]) {
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) {
+        throw Object.assign(new Error(`Spec Kit source exceeds byte limit: ${path}`), { code: 'BRIDGE_SOURCE_LIMIT' });
+      }
+      const content = readFileSync(path, 'utf8');
+      const kind = sourceKind(path);
+      const relativePath = relative(projectRoot, path).replaceAll('\\', '/');
+      const sha256 = bridgeSha256(content);
+      if (kind === 'task') {
+        for (const [sourceId, taskIds] of linkedTasks(content)) {
+          const current = taskLinks.get(sourceId) || [];
+          taskLinks.set(sourceId, [...new Set([...current, ...taskIds])]);
+        }
+      }
+      for (const source_id of idsFor(kind, content, relativePath)) {
+        references.push({ kind, source_id, path: relativePath, sha256, title: titleFor(content) });
+      }
+    }
+    const duplicateDiagnostics = [];
+    const seenIds = new Map();
+    for (const reference of references) {
+      const firstPath = seenIds.get(reference.source_id);
+      if (firstPath && firstPath !== reference.path) {
+        duplicateDiagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_ID_DUPLICATE', {
+          adapter: 'spec-kit', path: reference.path, expected: firstPath, observed: reference.path,
+          message: `external source id is duplicated: ${reference.source_id}`,
+        }));
+      } else seenIds.set(reference.source_id, reference.path);
+    }
+    const mappings = references.filter((item) => item.kind === 'spec').map((item) => {
+      const feature = featureFor(projectRoot, resolve(projectRoot, item.path));
+      return {
+        source_id: item.source_id,
+        source_kind: /^(?:US-?\d+|STORY-\d+)$/.test(item.source_id) ? 'story' : 'requirement',
+        capability: feature.capability,
+        change_slug: feature.change_slug,
+        task_ids: taskLinks.get(item.source_id) || [],
+      };
+    });
+    const adapterClaims = config?.adapters?.['spec-kit']?.ownership_claims || [];
+    const projection = createBridgeProjection({
+      adapter: 'spec-kit',
+      adapterVersion: detected.version,
+      sourceRoot: relative(projectRoot, detected.source),
+      claims: [
+        { concept: 'spec_source', owner: 'wendkeep' },
+        { concept: 'plan', owner: 'wendkeep' },
+        { concept: 'task', owner: 'wendkeep' },
+        ...adapterClaims,
+      ],
+      references,
+      mappings,
+    });
+    const drift = previousProjection ? detectBridgeDrift(previousProjection, projection) : { ok: true, diagnostics: [] };
+    return sealBridgeProjection({
+      ...projection,
+      active: true,
+      ok: projection.ok && drift.ok && duplicateDiagnostics.length === 0,
+      diagnostics: [...projection.diagnostics, ...duplicateDiagnostics, ...drift.diagnostics],
+    });
+  } catch (error) {
+    return {
+      schema_version: 1,
+      adapter: 'spec-kit',
+      authority: 'reported',
+      active: true,
+      ok: false,
+      references: [],
+      diagnostics: [bridgeDiagnostic(error?.code || 'BRIDGE_SOURCE_INVALID', {
+        adapter: 'spec-kit', path: detected.source, message: error?.message || String(error),
+      })],
+    };
+  }
+}
+
+export function buildSpecKitStatusProjection({ sourceProjection, taskContracts = [], artifacts = [] } = {}) {
+  const sourceValidation = validateBridgeProjection(sourceProjection);
+  if (sourceProjection?.adapter !== 'spec-kit' || sourceProjection?.ok !== true || !sourceValidation.valid) {
+    throw Object.assign(new Error('a valid Spec Kit source projection is required'), { code: 'BRIDGE_CONTRACT_INVALID' });
+  }
+  const projection = {
+    schema_version: 1,
+    contract_kind: 'status-projection',
+    adapter: 'spec-kit',
+    mode: 'status-projection',
+    source_projection_id: String(sourceProjection.projection_id),
+    authority: 'reported',
+    canonical_owner: 'wendkeep',
+    origin: { tool: 'wendkeep', source_projection_id: String(sourceProjection.projection_id) },
+    provenance: { state: 'reported', source: 'canonical-status-export' },
+    tasks: (Array.isArray(taskContracts) ? taskContracts : []).map((task) => ({
+      task_id: String(task?.task_id || ''),
+      contract_id: String(task?.contract_id || ''),
+      status: String(task?.status || ''),
+    })),
+    evidence: (Array.isArray(artifacts) ? artifacts : []).map((artifact) => ({
+      external_id: String(artifact?.external_id || ''),
+      sha256: String(artifact?.sha256 || ''),
+      authority: 'reported',
+    })),
+  };
+  projection.status_projection_id = bridgeSha256(canonicalBridgeJson(projection));
+  const validation = validateBridgeRuntimeEnvelope(projection);
+  if (!validation.valid) {
+    throw Object.assign(new Error('generated Spec Kit status projection is invalid'), {
+      code: 'BRIDGE_CONTRACT_INVALID', diagnostics: validation.diagnostics,
+    });
+  }
+  return projection;
+}

package/packages/integrations/src/superpowers-adapter.mjs

@@ -0,0 +1,269 @@
+import { assessBridgeAdapter } from './bridge-config.mjs';
+import {
+  bridgeSha256, canonicalBridgeJson, validateBridgeOwnership, validateBridgeProjection,
+  validateBridgeRuntimeEnvelope,
+} from './bridge-contract.mjs';
+import { bridgeDiagnostic } from './bridge-diagnostics.mjs';
+import {
+  readCanonicalArtifactProof, readCanonicalDispatchAuthority,
+} from './canonical-bridge-authority.mjs';
+
+function publicTaskContract(contract) {
+  return {
+    schema_version: 1,
+    contract_id: String(contract.contract_id),
+    task_id: String(contract.task_id),
+    change_slug: String(contract.change_slug || ''),
+    title: String(contract.title || '').slice(0, 500),
+    phase: String(contract.phase || ''),
+    status: String(contract.status || ''),
+    inputs: [...(contract.inputs || [])].map(String),
+    expected_outputs: [...(contract.expected_outputs || [])].map(String),
+    acceptance_criteria: [...(contract.acceptance_criteria || [])].map(String),
+    requirement_ids: [...(contract.requirement_ids || [])].map(String),
+    required_sensors: [...(contract.required_sensors || [])].map(String),
+    required_artifacts: [...(contract.required_artifacts || [])].map(String),
+    dependencies: [...(contract.dependencies || [])].map(String),
+    authored_sha256: String(contract.authored_sha256 || ''),
+    binding: {
+      project_id: String(contract.binding?.project_id || ''),
+      active_context_id: String(contract.binding?.active_context_id || ''),
+      head_sha: String(contract.binding?.head_sha || ''),
+      tasks_sha256: String(contract.binding?.tasks_sha256 || ''),
+      effective_spec_sha256: String(contract.binding?.effective_spec_sha256 || ''),
+      artifact_manifest_sha256: String(contract.binding?.artifact_manifest_sha256 || ''),
+    },
+  };
+}
+
+function validateDispatchInput(taskContract, activeContext) {
+  const diagnostics = [];
+  if (taskContract?.schema_version !== 1 || !taskContract?.contract_id || !taskContract?.task_id
+    || !taskContract?.authored_sha256 || !taskContract?.binding?.active_context_id || !taskContract?.binding?.head_sha) {
+    diagnostics.push(bridgeDiagnostic('BRIDGE_CONTRACT_INVALID', {
+      adapter: 'superpowers', message: 'a complete canonical task contract is required',
+    }));
+    return diagnostics;
+  }
+  for (const field of ['active_context_id', 'head_sha']) {
+    if (activeContext?.[field] && String(activeContext[field]) !== String(taskContract.binding[field])) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_CONTRACT_INVALID', {
+        adapter: 'superpowers',
+        expected: taskContract.binding[field],
+        observed: activeContext[field],
+        message: `canonical task binding is stale: ${field}`,
+      }));
+    }
+  }
+  return diagnostics;
+}
+
+function canonicalDispatchAuthority(submitted, authority) {
+  const diagnostics = [];
+  const issued = readCanonicalDispatchAuthority(authority);
+  if (!issued?.task_contract || !issued?.active_context) {
+    diagnostics.push(bridgeDiagnostic('BRIDGE_CANONICAL_AUTHORITY_REQUIRED', {
+      adapter: 'superpowers', message: 'dispatch requires a task contract rederived from canonical WendKeep state',
+    }));
+    return { taskContract: null, activeContext: null, diagnostics };
+  }
+  const canonical = issued.task_contract;
+  const activeContext = issued.active_context;
+  for (const field of ['contract_id', 'authored_sha256', 'task_id', 'change_slug']) {
+    if (String(submitted?.[field] || '') !== String(canonical?.[field] || '')) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_CONTRACT_STALE', {
+        adapter: 'superpowers', expected: canonical?.[field], observed: submitted?.[field],
+        message: `submitted task contract differs from canonical ${field}`,
+      }));
+    }
+  }
+  for (const field of ['project_id', 'active_context_id', 'head_sha', 'tasks_sha256', 'effective_spec_sha256', 'artifact_manifest_sha256']) {
+    if (String(submitted?.binding?.[field] || '') !== String(canonical?.binding?.[field] || '')) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_CONTRACT_STALE', {
+        adapter: 'superpowers', expected: canonical?.binding?.[field], observed: submitted?.binding?.[field],
+        message: `submitted task binding differs from canonical ${field}`,
+      }));
+    }
+  }
+  diagnostics.push(...validateDispatchInput(canonical, activeContext));
+  return { taskContract: canonical, activeContext, diagnostics };
+}
+
+export function buildSuperpowersDispatch({
+  taskContract, canonicalAuthority = null, handoffContract = null, specKitProjection = null,
+  config, detectedVersion = '', present = true,
+} = {}) {
+  const assessment = assessBridgeAdapter('superpowers', { config, detectedVersion, present });
+  if (!assessment.available) {
+    const disabled = assessment.diagnostics.every((item) => !item.blocking);
+    return { schema_version: 1, adapter: 'superpowers', active: false, ok: disabled, diagnostics: assessment.diagnostics };
+  }
+  const canonical = canonicalDispatchAuthority(taskContract, canonicalAuthority);
+  const authoritativeTask = canonical.taskContract;
+  const diagnostics = [...canonical.diagnostics];
+  const ownership = validateBridgeOwnership({
+    adapter: 'superpowers', claims: config?.adapters?.superpowers?.ownership_claims || [],
+  });
+  diagnostics.push(...ownership.diagnostics);
+  const handoffEnvelope = handoffContract ? {
+    schema_version: 1,
+    contract_kind: 'handoff',
+    handoff_id: String(handoffContract.handoff_id || ''),
+    task_contract_id: String(handoffContract.task_contract_id || ''),
+    task_id: String(handoffContract.task_id || ''),
+    head_sha: String(handoffContract.head_sha || ''),
+    authority: 'reported',
+    origin: { tool: 'wendkeep' },
+    provenance: { state: 'reported', source: 'canonical-handoff-reference' },
+  } : null;
+  const handoffValidation = handoffEnvelope ? validateBridgeRuntimeEnvelope(handoffEnvelope) : { valid: true };
+  if (handoffContract && (!handoffValidation.valid || handoffContract.schema_version !== 1
+    || (handoffContract.task_contract_id && handoffContract.task_contract_id !== authoritativeTask?.contract_id)
+    || (handoffContract.task_id && handoffContract.task_id !== authoritativeTask?.task_id))) {
+    diagnostics.push(bridgeDiagnostic('BRIDGE_CONTRACT_INVALID', {
+      adapter: 'superpowers', message: 'handoff does not bind the selected canonical task contract',
+    }));
+  }
+  if (specKitProjection) {
+    const blockers = (Array.isArray(specKitProjection.diagnostics) ? specKitProjection.diagnostics : [])
+      .filter((item) => item?.blocking)
+      .map((item) => ({
+        schema_version: 1,
+        code: String(item.code || 'BRIDGE_SOURCE_DRIFT'),
+        adapter: 'spec-kit',
+        blocking: true,
+        message: String(item.message || item.code || 'external source blocks dispatch'),
+        ...(item.expected ? { expected: String(item.expected) } : {}),
+        ...(item.observed ? { observed: String(item.observed) } : {}),
+      }));
+    const projectionValidation = validateBridgeProjection(specKitProjection);
+    if (!projectionValidation.valid) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_PROJECTION_INVALID', {
+        adapter: 'spec-kit', message: 'Spec Kit projection_id/schema does not match its canonical content',
+      }));
+      diagnostics.push(...blockers);
+    } else if (specKitProjection.ok !== true) {
+      diagnostics.push(...(blockers.length ? blockers : [bridgeDiagnostic('BRIDGE_PROJECTION_INVALID', {
+        adapter: 'spec-kit', message: 'Spec Kit projection must be explicitly green before dispatch',
+      })]));
+    }
+  }
+  if (diagnostics.length) {
+    return { schema_version: 1, adapter: 'superpowers', active: true, ok: false, diagnostics };
+  }
+  const dispatch = {
+    schema_version: 1,
+    contract_kind: 'dispatch',
+    adapter: 'superpowers',
+    adapter_version: assessment.version,
+    active: true,
+    canonical_owner: 'wendkeep',
+    executor: 'superpowers',
+    authority: 'reported',
+    origin: { tool: 'superpowers', version: assessment.version },
+    compatibility: {
+      range: assessment.manifest.compatibility_range,
+      detected_version: assessment.version,
+      supported: true,
+    },
+    provenance: { state: 'reported', source: 'wendkeep-canonical-dispatch' },
+    task_contract: publicTaskContract(authoritativeTask),
+    ...(handoffContract ? {
+      handoff_ref: {
+        handoff_id: String(handoffContract.handoff_id || ''),
+        task_contract_id: String(handoffContract.task_contract_id || ''),
+        head_sha: String(handoffContract.head_sha || ''),
+      },
+    } : {}),
+    spec_refs: (specKitProjection?.references || [])
+      .filter((item) => ['spec', 'constitution'].includes(item.kind))
+      .map((item) => ({ source_id: String(item.source_id), sha256: String(item.sha256) })),
+    worktree: {
+      provider: 'wendkeep',
+      mode: 'reuse-or-create',
+      create_argv: ['wendkeep', 'worktree', 'create', String(authoritativeTask.change_slug)],
+      finish_argv: ['wendkeep', 'worktree', 'finish', String(authoritativeTask.change_slug), '--pr', '<number-or-url>'],
+    },
+    diagnostics: [],
+  };
+  dispatch.dispatch_id = bridgeSha256(canonicalBridgeJson(dispatch));
+  const runtime = validateBridgeRuntimeEnvelope(dispatch);
+  if (!runtime.valid) {
+    return { schema_version: 1, adapter: 'superpowers', active: true, ok: false, diagnostics: runtime.diagnostics };
+  }
+  return { ...dispatch, ok: true };
+}
+
+export function ingestSuperpowersArtifacts(items = []) {
+  return (Array.isArray(items) ? items : []).map((item, index) => {
+    const externalId = String(item?.external_id || '').trim();
+    const kind = String(item?.kind || 'artifact').trim();
+    if (!externalId || !['artifact', 'review', 'commit'].includes(kind)) {
+      throw Object.assign(new Error(`invalid Superpowers artifact at index ${index}`), { code: 'BRIDGE_CONTRACT_INVALID' });
+    }
+    const bytes = item.content === undefined ? String(item.sha256 || '') : String(item.content);
+    const sha256 = /^[a-f0-9]{64}$/.test(String(item.sha256 || '')) && item.content === undefined
+      ? String(item.sha256)
+      : bridgeSha256(bytes);
+    const artifact = {
+      schema_version: 1,
+      contract_kind: 'external-artifact',
+      source: 'superpowers',
+      external_id: externalId,
+      kind,
+      sha256,
+      authority: 'reported',
+      origin: { tool: 'superpowers', external_id: externalId },
+      provenance: { state: 'reported', source: 'external-ingest' },
+      proof: null,
+      diagnostics: [],
+    };
+    const runtime = validateBridgeRuntimeEnvelope(artifact);
+    if (!runtime.valid) {
+      throw Object.assign(new Error(`invalid Superpowers artifact at index ${index}`), {
+        code: 'BRIDGE_CONTRACT_INVALID', diagnostics: runtime.diagnostics,
+      });
+    }
+    return artifact;
+  });
+}
+
+export function verifyExternalArtifact(artifact, { proofs = [], canonicalProofs = [] } = {}) {
+  const canonical = (Array.isArray(canonicalProofs) ? canonicalProofs : [])
+    .map(readCanonicalArtifactProof)
+    .find((proof) => (
+      proof?.external_id === artifact?.external_id
+      && proof?.artifact_sha256 === artifact?.sha256
+      && proof?.authority === 'verified'
+      && proof?.evidence_envelope_id
+      && proof?.sensor_id
+      && proof?.head_sha
+      && proof?.proof_id
+    ));
+  if (canonical) {
+    return {
+      ...artifact,
+      authority: 'verified',
+      origin: { tool: 'wendkeep', evidence_envelope_id: canonical.evidence_envelope_id },
+      provenance: { state: 'verified', source: 'wendkeep-evidence-envelope' },
+      proof: { ...canonical },
+      diagnostics: [],
+    };
+  }
+  const matching = (Array.isArray(proofs) ? proofs : []).find((proof) => (
+    ['git', 'ci', 'evidence-envelope'].includes(String(proof?.type || ''))
+      && proof?.state === 'verified'
+      && String(proof?.artifact_sha256 || '') === String(artifact?.sha256 || '')
+  ));
+  return {
+    ...artifact,
+    authority: 'reported',
+    proof: null,
+    diagnostics: [bridgeDiagnostic(matching ? 'BRIDGE_PROOF_UNVERIFIED' : 'BRIDGE_PROOF_MISSING', {
+      adapter: 'superpowers',
+      message: matching
+        ? 'self-declared proof cannot promote authority; use the WendKeep Evidence Envelope/provenance gate'
+        : `no independent proof binds ${artifact?.external_id || 'artifact'}`,
+    })],
+  };
+}

package/schema/ecosystem-bridge-artifact-manifest-v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/ecosystem-bridge-artifact-manifest-v1.schema.json",
+  "title": "WendKeep ecosystem bridge artifact manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "artifacts"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "artifacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/artifact" }
+    }
+  },
+  "$defs": {
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "external_id", "kind", "path", "sensor_id", "task_id"],
+      "properties": {
+        "source": { "const": "superpowers" },
+        "external_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+        "kind": { "enum": ["artifact", "review", "commit"] },
+        "path": { "type": "string", "minLength": 1 },
+        "sensor_id": { "type": "string", "minLength": 1 },
+        "task_id": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schema/ecosystem-bridge-v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/ecosystem-bridge-v1.schema.json",
+  "title": "WendKeep ecosystem bridge contracts v1",
+  "oneOf": [
+    { "$ref": "#/$defs/specProjection" }, { "$ref": "#/$defs/dispatch" },
+    { "$ref": "#/$defs/handoff" }, { "$ref": "#/$defs/externalArtifact" },
+    { "$ref": "#/$defs/proof" }, { "$ref": "#/$defs/statusProjection" }
+  ],
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "envelopeId": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "origin": {
+      "type": "object", "required": ["tool"],
+      "properties": { "tool": { "type": "string", "minLength": 1 }, "version": { "type": "string" }, "root": { "type": "string" }, "external_id": { "type": "string" }, "source_projection_id": { "$ref": "#/$defs/sha256" }, "evidence_envelope_id": { "$ref": "#/$defs/envelopeId" } }
+    },
+    "compatibility": {
+      "type": "object", "additionalProperties": false,
+      "required": ["range", "detected_version", "supported"],
+      "properties": { "range": { "type": "string", "minLength": 1 }, "detected_version": { "type": "string", "minLength": 1 }, "supported": { "type": "boolean" } }
+    },
+    "provenance": {
+      "type": "object", "additionalProperties": false, "required": ["state", "source"],
+      "properties": { "state": { "enum": ["reported", "verified"] }, "source": { "type": "string", "minLength": 1 } }
+    },
+    "mapping": {
+      "type": "object", "additionalProperties": false,
+      "required": ["source_id", "source_kind", "capability", "change_slug", "task_ids"],
+      "properties": { "source_id": { "type": "string", "minLength": 1 }, "source_kind": { "enum": ["story", "requirement"] }, "capability": { "type": "string", "minLength": 1 }, "change_slug": { "type": "string", "minLength": 1 }, "task_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true } }
+    },
+    "reference": {
+      "type": "object", "required": ["kind", "source_id", "path", "sha256", "authority"],
+      "properties": { "kind": { "enum": ["constitution", "spec", "plan", "task", "artifact", "review", "commit"] }, "source_id": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 }, "sha256": { "$ref": "#/$defs/sha256" }, "authority": { "const": "reported" }, "title": { "type": "string", "maxLength": 300 } }
+    },
+    "ownership": {
+      "type": "object", "required": ["concept", "owner"],
+      "properties": { "concept": { "enum": ["spec_source", "plan", "task", "execution", "artifact", "evidence"] }, "owner": { "const": "wendkeep" } }
+    },
+    "specProjection": {
+      "type": "object", "required": ["schema_version", "contract_kind", "projection_id", "adapter", "adapter_version", "authority", "origin", "compatibility", "provenance", "ownership", "references", "mappings", "diagnostics", "ok"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "spec-projection" }, "projection_id": { "$ref": "#/$defs/sha256" }, "adapter": { "const": "spec-kit" }, "adapter_version": { "type": "string", "minLength": 1 }, "authority": { "const": "reported" }, "origin": { "$ref": "#/$defs/origin" }, "compatibility": { "$ref": "#/$defs/compatibility" }, "provenance": { "$ref": "#/$defs/provenance" }, "ownership": { "type": "array", "items": { "$ref": "#/$defs/ownership" } }, "references": { "type": "array", "items": { "$ref": "#/$defs/reference" } }, "mappings": { "type": "array", "items": { "$ref": "#/$defs/mapping" } }, "diagnostics": { "type": "array" }, "ok": { "type": "boolean" } }
+    },
+    "dispatch": {
+      "type": "object", "required": ["schema_version", "contract_kind", "dispatch_id", "adapter", "authority", "canonical_owner", "origin", "compatibility", "provenance", "task_contract", "worktree"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "dispatch" }, "dispatch_id": { "$ref": "#/$defs/sha256" }, "adapter": { "const": "superpowers" }, "authority": { "const": "reported" }, "canonical_owner": { "const": "wendkeep" }, "origin": { "$ref": "#/$defs/origin" }, "compatibility": { "$ref": "#/$defs/compatibility" }, "provenance": { "$ref": "#/$defs/provenance" }, "task_contract": { "type": "object" }, "worktree": { "type": "object" } }
+    },
+    "handoff": {
+      "type": "object", "required": ["schema_version", "contract_kind", "handoff_id", "task_contract_id", "head_sha", "authority", "origin", "provenance"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "handoff" }, "handoff_id": { "type": "string", "minLength": 1 }, "task_contract_id": { "$ref": "#/$defs/sha256" }, "head_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "authority": { "const": "reported" }, "origin": { "$ref": "#/$defs/origin" }, "provenance": { "$ref": "#/$defs/provenance" } }
+    },
+    "externalArtifact": {
+      "type": "object", "required": ["schema_version", "contract_kind", "source", "external_id", "kind", "sha256", "authority", "origin", "provenance"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "external-artifact" }, "source": { "const": "superpowers" }, "external_id": { "type": "string", "minLength": 1 }, "kind": { "enum": ["artifact", "review", "commit"] }, "sha256": { "$ref": "#/$defs/sha256" }, "authority": { "enum": ["reported", "verified"] }, "origin": { "$ref": "#/$defs/origin" }, "provenance": { "$ref": "#/$defs/provenance" }, "proof": { "$ref": "#/$defs/proof" } },
+      "allOf": [{ "if": { "properties": { "authority": { "const": "verified" } }, "required": ["authority"] }, "then": { "required": ["proof"] } }]
+    },
+    "proof": {
+      "type": "object", "required": ["schema_version", "contract_kind", "proof_id", "type", "external_id", "artifact_sha256", "authority", "origin", "provenance", "evidence_envelope_id", "sensor_id", "task_id", "path", "head_sha", "git_blob", "manifest_git_blob"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "proof" }, "proof_id": { "$ref": "#/$defs/sha256" }, "type": { "const": "evidence-envelope" }, "external_id": { "type": "string", "minLength": 1 }, "artifact_sha256": { "$ref": "#/$defs/sha256" }, "authority": { "const": "verified" }, "origin": { "$ref": "#/$defs/origin" }, "provenance": { "$ref": "#/$defs/provenance" }, "evidence_envelope_id": { "$ref": "#/$defs/envelopeId" }, "sensor_id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 }, "head_sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "git_blob": { "type": "string", "pattern": "^[a-f0-9]{40}$" }, "manifest_git_blob": { "type": "string", "pattern": "^[a-f0-9]{40}$" } }
+    },
+    "statusProjection": {
+      "type": "object", "required": ["schema_version", "contract_kind", "status_projection_id", "adapter", "authority", "canonical_owner", "origin", "provenance", "source_projection_id", "tasks", "evidence"],
+      "properties": { "schema_version": { "const": 1 }, "contract_kind": { "const": "status-projection" }, "status_projection_id": { "$ref": "#/$defs/sha256" }, "adapter": { "const": "spec-kit" }, "authority": { "const": "reported" }, "canonical_owner": { "const": "wendkeep" }, "origin": { "$ref": "#/$defs/origin" }, "provenance": { "$ref": "#/$defs/provenance" }, "source_projection_id": { "$ref": "#/$defs/sha256" }, "tasks": { "type": "array" }, "evidence": { "type": "array" } }
+    }
+  }
+}