wendkeep 0.88.0 → 0.89.0

package/packages/integrations/src/bridge-config.mjs

@@ -0,0 +1,139 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { ECOSYSTEM_ADAPTER_MANIFESTS, isVersionInRange } from './capabilities.mjs';
+import { bridgeDiagnostic, bridgeError } from './bridge-diagnostics.mjs';
+
+const ADAPTERS = ['spec-kit', 'superpowers'];
+
+export function isProjectContainedPath(projectRoot, targetPath, pathApi = { relative, isAbsolute, sep }) {
+  const rel = pathApi.relative(projectRoot, targetPath);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${pathApi.sep}`) && !pathApi.isAbsolute(rel));
+}
+
+export function inspectBridgeAdapterRoot(projectRoot, configuredRoot, { adapter = '', fs = null } = {}) {
+  const invalid = (path, message) => ({
+    valid: false,
+    present: false,
+    path,
+    diagnostics: [bridgeDiagnostic('BRIDGE_SOURCE_INVALID', {
+      adapter, path, message,
+    })],
+  });
+  if (!fs || ['existsSync', 'lstatSync', 'realpathSync'].some((name) => typeof fs[name] !== 'function')) {
+    return invalid(resolve(projectRoot), 'bridge filesystem capability is unavailable');
+  }
+  const { existsSync, lstatSync, realpathSync } = fs;
+  let root;
+  try {
+    root = realpathSync(resolve(projectRoot));
+  } catch (error) {
+    return invalid(resolve(projectRoot), `project root is not a real directory: ${error?.message || error}`);
+  }
+  const candidate = resolve(root, configuredRoot || `.${adapter}`);
+  if (!isProjectContainedPath(root, candidate)) {
+    return invalid(candidate, `${adapter} root must stay inside the project`);
+  }
+  if (!existsSync(candidate)) return { valid: true, present: false, path: candidate, diagnostics: [] };
+  try {
+    const real = realpathSync(candidate);
+    if (!isProjectContainedPath(root, real)) {
+      return invalid(candidate, `${adapter} root symlink escapes the project`);
+    }
+    if (!lstatSync(real).isDirectory()) {
+      return invalid(candidate, `${adapter} root must be a directory`);
+    }
+    return { valid: true, present: true, path: real, diagnostics: [] };
+  } catch (error) {
+    return invalid(candidate, `${adapter} root is unsafe: ${error?.message || error}`);
+  }
+}
+
+export function normalizeBridgeConfig(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw bridgeError('BRIDGE_CONFIG_INVALID', 'bridge config must be an object');
+  }
+  if (input.schema_version !== undefined && input.schema_version !== 1) {
+    throw bridgeError('BRIDGE_CONFIG_INVALID', 'bridge config requires schema_version 1');
+  }
+  const configured = input.adapters || {};
+  const unknown = Object.keys(configured).filter((name) => !ADAPTERS.includes(name));
+  if (unknown.length) throw bridgeError('BRIDGE_CONFIG_INVALID', `unknown bridge adapter: ${unknown.join(', ')}`);
+  const adapters = {};
+  for (const name of ADAPTERS) {
+    const value = configured[name] || {};
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      throw bridgeError('BRIDGE_CONFIG_INVALID', `adapter config must be an object: ${name}`);
+    }
+    const ownershipClaims = value.ownership_claims === undefined ? [] : value.ownership_claims;
+    if (!Array.isArray(ownershipClaims) || ownershipClaims.some((claim) => (
+      !claim || typeof claim !== 'object' || Array.isArray(claim)
+      || !String(claim.concept || '').trim() || !String(claim.owner || '').trim()
+    ))) {
+      throw bridgeError('BRIDGE_CONFIG_INVALID', `ownership_claims must contain concept/owner pairs: ${name}`);
+    }
+    adapters[name] = {
+      enabled: value.enabled === true,
+      ...(value.root ? { root: String(value.root) } : {}),
+      ...(value.version ? { version: String(value.version) } : {}),
+      ...(ownershipClaims.length ? {
+        ownership_claims: ownershipClaims.map((claim) => ({
+          concept: String(claim.concept).trim(), owner: String(claim.owner).trim(),
+        })),
+      } : {}),
+    };
+  }
+  return { schema_version: 1, adapters };
+}
+
+export function readBridgeConfig(projectRoot, configPath = '', { fs = null } = {}) {
+  if (!fs || ['existsSync', 'readFileSync', 'realpathSync'].some((name) => typeof fs[name] !== 'function')) {
+    throw bridgeError('BRIDGE_CONFIG_INVALID', 'bridge filesystem capability is unavailable');
+  }
+  const { existsSync, readFileSync, realpathSync } = fs;
+  const root = realpathSync(resolve(projectRoot));
+  const path = resolve(root, configPath || '.wendkeep/ecosystem-bridges.json');
+  if (!isProjectContainedPath(root, path)) {
+    throw bridgeError('BRIDGE_CONFIG_INVALID', 'bridge config must stay inside the project', { path });
+  }
+  if (!existsSync(path)) return { path, exists: false, config: normalizeBridgeConfig({}) };
+  const real = realpathSync(path);
+  if (!isProjectContainedPath(root, real)) {
+    throw bridgeError('BRIDGE_CONFIG_INVALID', 'bridge config symlink escapes the project', { path });
+  }
+  try {
+    return { path: real, exists: true, config: normalizeBridgeConfig(JSON.parse(readFileSync(real, 'utf8'))) };
+  } catch (error) {
+    if (error?.code === 'BRIDGE_CONFIG_INVALID') throw error;
+    throw bridgeError('BRIDGE_CONFIG_INVALID', `invalid bridge config: ${error?.message || error}`, { path });
+  }
+}
+
+export function assessBridgeAdapter(name, { config = normalizeBridgeConfig({}), detectedVersion = '', present = true } = {}) {
+  const manifest = ECOSYSTEM_ADAPTER_MANIFESTS[name];
+  if (!manifest) {
+    return { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_ADAPTER_UNKNOWN', { adapter: name })] };
+  }
+  const adapter = config.adapters[name] || { enabled: false };
+  if (!adapter.enabled) {
+    return { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_ADAPTER_DISABLED', {
+      adapter: name, blocking: false, message: `${name} adapter is disabled`,
+    })] };
+  }
+  if (!present) {
+    return { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_ADAPTER_MISSING', {
+      adapter: name, message: `${name} adapter source was not found`,
+    })] };
+  }
+  const version = detectedVersion || adapter.version || '';
+  if (!version) {
+    return { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_VERSION_MISSING', {
+      adapter: name, expected: manifest.compatibility_range,
+    })] };
+  }
+  if (!isVersionInRange(version, manifest.compatibility_range)) {
+    return { available: false, diagnostics: [bridgeDiagnostic('BRIDGE_VERSION_INCOMPATIBLE', {
+      adapter: name, expected: manifest.compatibility_range, observed: version,
+    })] };
+  }
+  return { available: true, adapter: name, version, manifest, diagnostics: [] };
+}

package/packages/integrations/src/bridge-contract.mjs

@@ -0,0 +1,316 @@
+import { createHash } from 'node:crypto';
+
+import { ECOSYSTEM_ADAPTER_MANIFESTS, isVersionInRange } from './capabilities.mjs';
+import { bridgeDiagnostic, bridgeError } from './bridge-diagnostics.mjs';
+
+export const ECOSYSTEM_BRIDGE_SCHEMA_VERSION = 1;
+
+const SPEC_PROJECTION_ADAPTER = 'spec-kit';
+const REFERENCE_KINDS = new Set(['constitution', 'spec', 'plan', 'task', 'artifact', 'review', 'commit']);
+const MAPPING_SOURCE_KINDS = new Set(['story', 'requirement']);
+
+export const BRIDGE_AUTHORITY_MATRIX = Object.freeze({
+  spec_source: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['spec-kit'], external_authority: 'reported' }),
+  plan: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['spec-kit'], external_authority: 'reported' }),
+  task: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['spec-kit', 'superpowers'], external_authority: 'reported' }),
+  execution: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['superpowers'], external_authority: 'reported' }),
+  artifact: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['superpowers'], external_authority: 'reported' }),
+  evidence: Object.freeze({ canonical_owner: 'wendkeep', adapters: ['superpowers'], external_authority: 'reported' }),
+});
+
+export function canonicalBridgeJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalBridgeJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalBridgeJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function bridgeSha256(value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function validateBridgeOwnership({ adapter = '', claims = [] } = {}) {
+  const diagnostics = [];
+  for (const claim of Array.isArray(claims) ? claims : []) {
+    const concept = String(claim?.concept || '');
+    const owner = String(claim?.owner || '');
+    const policy = BRIDGE_AUTHORITY_MATRIX[concept];
+    if (!policy || owner !== policy.canonical_owner) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_OWNERSHIP_CONFLICT', {
+        adapter,
+        expected: policy?.canonical_owner || 'wendkeep',
+        observed: owner || '(missing)',
+        message: `external adapter cannot own canonical ${concept || 'state'}`,
+      }));
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
+
+function projectionIdentity(value) {
+  const { projection_id: ignoredId, ...identity } = value || {};
+  return identity;
+}
+
+function validSha(value, size = 64) {
+  return new RegExp(`^[a-f0-9]{${size}}$`).test(String(value || ''));
+}
+
+function validReportedMetadata(value) {
+  return Boolean(value?.origin?.tool && value?.provenance?.state === 'reported' && value?.provenance?.source);
+}
+
+function validVerifiedMetadata(value) {
+  return Boolean(value?.origin?.tool === 'wendkeep'
+    && value?.provenance?.state === 'verified'
+    && value?.provenance?.source === 'wendkeep-evidence-envelope');
+}
+
+function hasExactKeys(value, expected) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join('\0') === [...expected].sort().join('\0'));
+}
+
+export function createBridgeProjection({
+  adapter, adapterVersion, sourceRoot = '', references = [], mappings = [], claims = [],
+} = {}) {
+  const ownership = validateBridgeOwnership({ adapter, claims });
+  const manifest = ECOSYSTEM_ADAPTER_MANIFESTS[String(adapter || '')];
+  const projection = {
+    schema_version: ECOSYSTEM_BRIDGE_SCHEMA_VERSION,
+    contract_kind: 'spec-projection',
+    adapter: String(adapter || ''),
+    adapter_version: String(adapterVersion || ''),
+    source_root: String(sourceRoot || '').replaceAll('\\', '/'),
+    authority: 'reported',
+    origin: {
+      tool: String(adapter || ''), version: String(adapterVersion || ''),
+      root: String(sourceRoot || '').replaceAll('\\', '/'),
+    },
+    compatibility: {
+      range: String(manifest?.compatibility_range || ''),
+      detected_version: String(adapterVersion || ''),
+      supported: Boolean(manifest && isVersionInRange(adapterVersion, manifest.compatibility_range)),
+    },
+    provenance: { state: 'reported', source: 'external-read-only' },
+    ownership: claims.map((claim) => ({ concept: String(claim.concept || ''), owner: String(claim.owner || '') })),
+    references: references.map((item) => ({
+      kind: String(item.kind || ''),
+      source_id: String(item.source_id || ''),
+      path: String(item.path || '').replaceAll('\\', '/'),
+      sha256: String(item.sha256 || ''),
+      authority: 'reported',
+      ...(item.title ? { title: String(item.title).slice(0, 300) } : {}),
+    })),
+    mappings: mappings.map((item) => ({
+      source_id: String(item.source_id || ''),
+      source_kind: String(item.source_kind || ''),
+      capability: String(item.capability || ''),
+      change_slug: String(item.change_slug || ''),
+      task_ids: [...new Set(Array.isArray(item.task_ids) ? item.task_ids.map(String) : [])],
+    })),
+    diagnostics: ownership.diagnostics,
+  };
+  const sealed = sealBridgeProjection({ ...projection, ok: ownership.ok });
+  const validation = validateBridgeProjection(sealed);
+  const contractDiagnostics = validation.diagnostics.filter((item) => item.code === 'BRIDGE_PROJECTION_INVALID');
+  if (contractDiagnostics.length) {
+    throw bridgeError('BRIDGE_PROJECTION_INVALID', contractDiagnostics[0].message, {
+      adapter: String(adapter || ''), diagnostics: contractDiagnostics,
+    });
+  }
+  return sealed;
+}
+
+export function sealBridgeProjection(value) {
+  const projection = structuredClone(value || {});
+  delete projection.projection_id;
+  return {
+    ...projection,
+    projection_id: bridgeSha256(canonicalBridgeJson(projectionIdentity(projection))),
+  };
+}
+
+export function validateBridgeProjection(value) {
+  const diagnostics = [];
+  const fail = (message) => diagnostics.push(bridgeDiagnostic('BRIDGE_PROJECTION_INVALID', {
+    adapter: String(value?.adapter || ''), message,
+  }));
+  if (value?.schema_version !== 1 || value?.contract_kind !== 'spec-projection') fail('projection contract kind/schema is invalid');
+  const manifest = ECOSYSTEM_ADAPTER_MANIFESTS[SPEC_PROJECTION_ADAPTER];
+  if (value?.adapter !== SPEC_PROJECTION_ADAPTER) fail('spec projection adapter must be spec-kit');
+  if (typeof value?.adapter_version !== 'string' || !value.adapter_version
+    || !value?.origin || !value?.compatibility || !value?.provenance) fail('projection metadata is incomplete');
+  if (value?.authority !== 'reported' || value?.provenance?.state !== 'reported'
+    || value?.provenance?.source !== 'external-read-only') fail('external projection cannot be authoritative');
+  if (!hasExactKeys(value?.provenance, ['state', 'source'])) fail('projection provenance shape is invalid');
+  if (value?.origin?.tool !== SPEC_PROJECTION_ADAPTER || value?.origin?.version !== value?.adapter_version
+    || typeof value?.origin?.root !== 'string') fail('projection origin does not match its adapter/version');
+  if (!hasExactKeys(value?.compatibility, ['range', 'detected_version', 'supported'])
+    || value?.compatibility?.range !== manifest.compatibility_range
+    || value?.compatibility?.detected_version !== value?.adapter_version
+    || value?.compatibility?.supported !== true
+    || !isVersionInRange(value?.adapter_version, manifest.compatibility_range)) {
+    fail('projection adapter version is incompatible');
+  }
+  const decisionFieldsValid = Array.isArray(value?.diagnostics) && typeof value?.ok === 'boolean';
+  if (!decisionFieldsValid) fail('projection decision fields are invalid');
+  if (decisionFieldsValid) {
+    const malformedDiagnostic = value.diagnostics.some((item) => (
+      !item || typeof item !== 'object' || Array.isArray(item)
+      || typeof item.code !== 'string' || !item.code
+      || typeof item.blocking !== 'boolean'
+      || typeof item.message !== 'string' || !item.message
+    ));
+    if (malformedDiagnostic) fail('projection diagnostics are malformed');
+    const hasBlockingDiagnostic = value.diagnostics.some((item) => item?.blocking === true);
+    if (value.ok === hasBlockingDiagnostic) fail('projection ok decision does not match blocking diagnostics');
+  }
+  if (!Array.isArray(value?.ownership)) fail('projection ownership is invalid');
+  if (!Array.isArray(value?.references) || value.references.some((item) => (
+    !REFERENCE_KINDS.has(item?.kind) || typeof item?.source_id !== 'string' || !item.source_id
+    || typeof item?.path !== 'string' || !item.path || !validSha(item?.sha256) || item?.authority !== 'reported'
+    || (item?.title !== undefined && (typeof item.title !== 'string' || item.title.length > 300))
+  ))) fail('projection references are invalid');
+  if (!Array.isArray(value?.mappings) || value.mappings.some((item) => (
+    !hasExactKeys(item, ['source_id', 'source_kind', 'capability', 'change_slug', 'task_ids'])
+    || typeof item?.source_id !== 'string' || !item.source_id || !MAPPING_SOURCE_KINDS.has(item?.source_kind)
+    || typeof item?.capability !== 'string' || !item.capability
+    || typeof item?.change_slug !== 'string' || !item.change_slug
+    || !Array.isArray(item?.task_ids) || item.task_ids.some((taskId) => typeof taskId !== 'string' || !taskId)
+    || new Set(item.task_ids).size !== item.task_ids.length
+  ))) fail('projection mappings are invalid');
+  const ownership = validateBridgeOwnership({ adapter: value?.adapter, claims: value?.ownership });
+  diagnostics.push(...ownership.diagnostics);
+  const expected = bridgeSha256(canonicalBridgeJson(projectionIdentity(value)));
+  if (!validSha(value?.projection_id) || value.projection_id !== expected) fail('projection_id does not match canonical projection bytes');
+  return { valid: diagnostics.length === 0, diagnostics, expected_projection_id: expected };
+}
+
+export function validateBridgeRuntimeEnvelope(value) {
+  const diagnostics = [];
+  const invalid = (message) => diagnostics.push(bridgeDiagnostic('BRIDGE_SCHEMA_INVALID', {
+    adapter: String(value?.adapter || ''), message,
+  }));
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.schema_version !== 1) {
+    invalid('bridge envelope must be a schema v1 object');
+    return { valid: false, diagnostics };
+  }
+  const kind = String(value.contract_kind || '');
+  if (kind === 'spec-projection') {
+    const projection = validateBridgeProjection(value);
+    return {
+      valid: projection.valid,
+      diagnostics: projection.valid ? [] : projection.diagnostics.map((item) => bridgeDiagnostic('BRIDGE_SCHEMA_INVALID', {
+        adapter: value.adapter, message: item.message,
+      })),
+    };
+  }
+  if (kind === 'dispatch') {
+    if (value.adapter !== 'superpowers' || value.authority !== 'reported' || value.canonical_owner !== 'wendkeep'
+      || !validReportedMetadata(value) || !value.compatibility?.range || value.compatibility?.supported !== true
+      || !value.task_contract?.contract_id
+      || !value.task_contract?.binding?.active_context_id || !value.worktree?.provider || !validSha(value.dispatch_id)) {
+      invalid('dispatch envelope is incomplete');
+    }
+    const { dispatch_id: ignoredId, ok: ignoredOk, ...identity } = value;
+    if (validSha(value.dispatch_id) && bridgeSha256(canonicalBridgeJson(identity)) !== value.dispatch_id) {
+      invalid('dispatch_id does not match canonical dispatch bytes');
+    }
+  } else if (kind === 'handoff') {
+    if (!value.handoff_id || !value.task_contract_id || !validSha(value.head_sha, 40)
+      || value.authority !== 'reported' || !validReportedMetadata(value)) invalid('handoff envelope is incomplete');
+  } else if (kind === 'external-artifact') {
+    const authorityValid = value.authority === 'reported'
+      ? validReportedMetadata(value)
+      : (value.authority === 'verified' && validVerifiedMetadata(value)
+        && validateBridgeRuntimeEnvelope(value.proof).valid
+        && value.proof.artifact_sha256 === value.sha256);
+    if (value.source !== 'superpowers' || !value.external_id || !['artifact', 'review', 'commit'].includes(value.kind)
+      || !validSha(value.sha256) || !authorityValid) invalid('external artifact envelope is invalid');
+  } else if (kind === 'proof') {
+    const { proof_id: ignoredId, ...identity } = value;
+    if (value.type !== 'evidence-envelope' || !validSha(value.artifact_sha256)
+      || value.authority !== 'verified' || !validVerifiedMetadata(value)
+      || !validSha(value.proof_id) || bridgeSha256(canonicalBridgeJson(identity)) !== value.proof_id
+      || !String(value.evidence_envelope_id || '').match(/^sha256:[a-f0-9]{64}$/)
+      || value.origin?.evidence_envelope_id !== value.evidence_envelope_id
+      || !value.external_id || !value.sensor_id || !value.task_id || !value.path
+      || !validSha(value.head_sha, 40) || !validSha(value.git_blob, 40) || !validSha(value.manifest_git_blob, 40)) {
+      invalid('proof envelope is invalid');
+    }
+  } else if (kind === 'status-projection') {
+    if (value.adapter !== 'spec-kit' || value.authority !== 'reported' || value.canonical_owner !== 'wendkeep'
+      || !validReportedMetadata(value) || !validSha(value.source_projection_id)
+      || !Array.isArray(value.tasks) || !Array.isArray(value.evidence)) invalid('status projection is invalid');
+    const { status_projection_id: ignoredId, ...identity } = value;
+    if (!validSha(value.status_projection_id)
+      || bridgeSha256(canonicalBridgeJson(identity)) !== value.status_projection_id) invalid('status_projection_id is invalid');
+  } else {
+    invalid(`unknown bridge contract_kind: ${kind || '(missing)'}`);
+  }
+  return { valid: diagnostics.length === 0, diagnostics };
+}
+
+export function detectBridgeDrift(previous, current) {
+  const before = new Map((previous?.references || []).map((item) => [item.source_id, item]));
+  const after = new Map((current?.references || []).map((item) => [item.source_id, item]));
+  const diagnostics = [];
+  for (const item of current?.references || []) {
+    const expected = before.get(item.source_id);
+    if (!before.has(item.source_id)) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_DRIFT', {
+        adapter: current.adapter,
+        path: item.path,
+        expected: '(absent)',
+        observed: 'new',
+        message: `new external source appeared: ${item.source_id}`,
+      }));
+    } else if (canonicalBridgeJson({ kind: expected.kind, path: expected.path, sha256: expected.sha256 })
+      !== canonicalBridgeJson({ kind: item.kind, path: item.path, sha256: item.sha256 })) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_DRIFT', {
+        adapter: current.adapter,
+        path: item.path,
+        expected: canonicalBridgeJson({ kind: expected.kind, path: expected.path, sha256: expected.sha256 }),
+        observed: canonicalBridgeJson({ kind: item.kind, path: item.path, sha256: item.sha256 }),
+        message: `external source path/kind/hash drifted: ${item.source_id}`,
+      }));
+    }
+  }
+  for (const item of previous?.references || []) {
+    if (!after.has(item.source_id)) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_DRIFT', {
+        adapter: current.adapter,
+        path: item.path,
+        expected: canonicalBridgeJson({ kind: item.kind, path: item.path, sha256: item.sha256 }),
+        observed: '(missing)',
+        message: `external source disappeared: ${item.source_id}`,
+      }));
+    }
+  }
+  const beforeMappings = new Map((previous?.mappings || []).map((item) => [item.source_id, item]));
+  const afterMappings = new Map((current?.mappings || []).map((item) => [item.source_id, item]));
+  for (const [sourceId, mapping] of afterMappings) {
+    const expected = beforeMappings.get(sourceId);
+    if (!expected || canonicalBridgeJson(expected) !== canonicalBridgeJson(mapping)) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_DRIFT', {
+        adapter: current?.adapter,
+        expected: expected ? canonicalBridgeJson(expected) : '(absent)',
+        observed: canonicalBridgeJson(mapping),
+        message: `external capability/change/task mapping drifted: ${sourceId}`,
+      }));
+    }
+  }
+  for (const [sourceId, mapping] of beforeMappings) {
+    if (!afterMappings.has(sourceId)) {
+      diagnostics.push(bridgeDiagnostic('BRIDGE_SOURCE_DRIFT', {
+        adapter: current?.adapter,
+        expected: canonicalBridgeJson(mapping), observed: '(missing)',
+        message: `external capability/change/task mapping disappeared: ${sourceId}`,
+      }));
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}

package/packages/integrations/src/bridge-diagnostics.mjs

@@ -0,0 +1,45 @@
+export const BRIDGE_DIAGNOSTIC_CODES = Object.freeze({
+  adapterDisabled: 'BRIDGE_ADAPTER_DISABLED',
+  adapterMissing: 'BRIDGE_ADAPTER_MISSING',
+  adapterUnknown: 'BRIDGE_ADAPTER_UNKNOWN',
+  versionMissing: 'BRIDGE_VERSION_MISSING',
+  versionIncompatible: 'BRIDGE_VERSION_INCOMPATIBLE',
+  ownershipConflict: 'BRIDGE_OWNERSHIP_CONFLICT',
+  sourceInvalid: 'BRIDGE_SOURCE_INVALID',
+  sourceDrift: 'BRIDGE_SOURCE_DRIFT',
+  sourceIdDuplicate: 'BRIDGE_SOURCE_ID_DUPLICATE',
+  contractInvalid: 'BRIDGE_CONTRACT_INVALID',
+  contractStale: 'BRIDGE_CONTRACT_STALE',
+  canonicalAuthorityRequired: 'BRIDGE_CANONICAL_AUTHORITY_REQUIRED',
+  projectionInvalid: 'BRIDGE_PROJECTION_INVALID',
+  schemaInvalid: 'BRIDGE_SCHEMA_INVALID',
+  baselineMissing: 'BRIDGE_BASELINE_MISSING',
+  baselineStale: 'BRIDGE_BASELINE_STALE',
+  baselineInvalid: 'BRIDGE_BASELINE_INVALID',
+  artifactManifestInvalid: 'BRIDGE_ARTIFACT_MANIFEST_INVALID',
+  artifactManifestUntracked: 'BRIDGE_ARTIFACT_MANIFEST_UNTRACKED',
+  artifactForged: 'BRIDGE_ARTIFACT_FORGED',
+  artifactTaskUnbound: 'BRIDGE_ARTIFACT_TASK_UNBOUND',
+  artifactResultMissing: 'BRIDGE_ARTIFACT_RESULT_MISSING',
+  proofMissing: 'BRIDGE_PROOF_MISSING',
+  proofUnverified: 'BRIDGE_PROOF_UNVERIFIED',
+});
+
+export function bridgeDiagnostic(code, {
+  adapter = '', message = '', blocking = true, expected = '', observed = '', path = '',
+} = {}) {
+  return {
+    schema_version: 1,
+    code: String(code),
+    adapter: String(adapter),
+    blocking: Boolean(blocking),
+    message: String(message || code),
+    ...(expected ? { expected: String(expected) } : {}),
+    ...(observed ? { observed: String(observed) } : {}),
+    ...(path ? { path: String(path).replaceAll('\\', '/') } : {}),
+  };
+}
+
+export function bridgeError(code, message, details = {}) {
+  return Object.assign(new Error(message), { code, diagnostics: [bridgeDiagnostic(code, details)] });
+}

package/packages/integrations/src/canonical-bridge-authority.mjs

@@ -0,0 +1,32 @@
+const dispatchReceipts = new WeakMap();
+const artifactProofReceipts = new WeakMap();
+
+function receipt(kind) {
+  return Object.freeze({ schema_version: 1, kind });
+}
+
+// Internal composition-root capability. This module is deliberately not re-exported by index.mjs.
+export function issueCanonicalDispatchAuthority({ task_contract, active_context } = {}) {
+  const value = receipt('canonical-dispatch-authority');
+  dispatchReceipts.set(value, {
+    task_contract: structuredClone(task_contract),
+    active_context: structuredClone(active_context),
+  });
+  return value;
+}
+
+export function readCanonicalDispatchAuthority(value) {
+  const payload = value && typeof value === 'object' ? dispatchReceipts.get(value) : null;
+  return payload ? structuredClone(payload) : null;
+}
+
+export function issueCanonicalArtifactProof(proof = {}) {
+  const value = receipt('canonical-artifact-proof');
+  artifactProofReceipts.set(value, structuredClone(proof));
+  return value;
+}
+
+export function readCanonicalArtifactProof(value) {
+  const payload = value && typeof value === 'object' ? artifactProofReceipts.get(value) : null;
+  return payload ? structuredClone(payload) : null;
+}

package/packages/integrations/src/capabilities.mjs

@@ -7,6 +7,40 @@ export const HOST_CAPABILITIES = [
 
 export const HOST_CAPABILITY_STATES = ['native', 'adapted', 'polled', 'manual', 'unavailable'];
 
+export const ECOSYSTEM_ADAPTER_MANIFESTS = Object.freeze({
+  'spec-kit': Object.freeze({
+    adapter_id: 'spec-kit', contract_version: 1, compatibility_range: '>=0.1.0 <2.0.0', optional: true,
+  }),
+  superpowers: Object.freeze({
+    adapter_id: 'superpowers', contract_version: 1, compatibility_range: '>=1.0.0 <2.0.0', optional: true,
+  }),
+});
+
+function semverTuple(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function compareVersion(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function isVersionInRange(version, range) {
+  const observed = semverTuple(version);
+  if (!observed) return false;
+  const clauses = String(range || '').split(/\s+/).filter(Boolean);
+  if (!clauses.length) return false;
+  return clauses.every((clause) => {
+    const match = clause.match(/^(>=|>|<=|<|=)?(\d+\.\d+\.\d+)$/);
+    if (!match) return false;
+    const comparison = compareVersion(observed, semverTuple(match[2]));
+    return ({ '>=': comparison >= 0, '>': comparison > 0, '<=': comparison <= 0, '<': comparison < 0, '=': comparison === 0 }[match[1] || '=']);
+  });
+}
+
 function matrix(defaultState, overrides = {}) {
   return Object.fromEntries(HOST_CAPABILITIES.map((capability) => [
     capability, overrides[capability] || defaultState,

package/packages/integrations/src/ecosystem-bridge.mjs

@@ -0,0 +1,82 @@
+import { resolve } from 'node:path';
+
+import { assessBridgeAdapter, inspectBridgeAdapterRoot, readBridgeConfig } from './bridge-config.mjs';
+import { validateBridgeOwnership } from './bridge-contract.mjs';
+import { detectSpecKit } from './spec-kit-adapter.mjs';
+
+export function inspectEcosystemBridges({ projectRoot, configPath = '', fs = null } = {}) {
+  try {
+    const root = resolve(projectRoot || process.cwd());
+    const loaded = readBridgeConfig(root, configPath, { fs });
+    const spec = detectSpecKit({ projectRoot: root, config: loaded.config, fs });
+    const specOwnership = validateBridgeOwnership({
+      adapter: 'spec-kit', claims: loaded.config.adapters['spec-kit'].ownership_claims || [],
+    });
+    const superConfig = loaded.config.adapters.superpowers;
+    const superRoot = inspectBridgeAdapterRoot(root, superConfig.root || '.superpowers', { adapter: 'superpowers', fs });
+    const superAssessment = !superRoot.valid
+      ? {
+        available: false,
+        diagnostics: superRoot.diagnostics,
+      }
+      : assessBridgeAdapter('superpowers', {
+        config: loaded.config,
+        detectedVersion: superConfig.version || '',
+        present: superRoot.present,
+      });
+    const superOwnership = validateBridgeOwnership({
+      adapter: 'superpowers', claims: superConfig.ownership_claims || [],
+    });
+    const adapters = [
+      {
+        adapter: 'spec-kit',
+        active: spec.assessment.available,
+        available: spec.assessment.available,
+        version: spec.version,
+        diagnostics: [...spec.assessment.diagnostics, ...(loaded.config.adapters['spec-kit'].enabled ? specOwnership.diagnostics : [])],
+      },
+      {
+        adapter: 'superpowers',
+        active: superAssessment.available,
+        available: superAssessment.available,
+        version: superAssessment.version || superConfig.version || '',
+        diagnostics: [...superAssessment.diagnostics, ...(superConfig.enabled ? superOwnership.diagnostics : [])],
+      },
+    ];
+    const diagnostics = adapters.flatMap((item) => item.diagnostics);
+    return {
+      schema_version: 1,
+      ok: diagnostics.every((item) => !item.blocking),
+      config_path: loaded.path,
+      config_exists: loaded.exists,
+      adapters,
+      diagnostics,
+    };
+  } catch (error) {
+    return {
+      schema_version: 1,
+      ok: false,
+      config_path: '',
+      config_exists: false,
+      adapters: [],
+      diagnostics: error?.diagnostics || [{
+        schema_version: 1,
+        code: error?.code || 'BRIDGE_CONFIG_INVALID',
+        adapter: '',
+        blocking: true,
+        message: error?.message || String(error),
+      }],
+    };
+  }
+}
+
+export function renderEcosystemBridgeLines(result) {
+  const lines = [`[bridges] ${result.ok ? 'saudável' : 'bloqueado'} · ${result.adapters.filter((item) => item.active).length} ativo(s)`];
+  for (const adapter of result.adapters) {
+    lines.push(`  ${adapter.active ? '✓' : '·'} ${adapter.adapter}: ${adapter.active ? `compatível ${adapter.version}` : adapter.diagnostics[0]?.code || 'inativo'}`);
+  }
+  for (const diagnostic of result.diagnostics.filter((item) => item.blocking)) {
+    lines.push(`  ✗ ${diagnostic.code}: ${diagnostic.message}`);
+  }
+  return lines;
+}

package/packages/integrations/src/index.mjs

@@ -5,3 +5,9 @@ export * from './prompt-content.mjs';
 export * from './transcript-usage.mjs';
 export * from './transcripts.mjs';
 export * from './session-identity.mjs';
+export * from './bridge-contract.mjs';
+export * from './bridge-diagnostics.mjs';
+export * from './bridge-config.mjs';
+export * from './spec-kit-adapter.mjs';
+export * from './superpowers-adapter.mjs';
+export * from './ecosystem-bridge.mjs';