wendkeep 0.87.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/packages/mcp/src/executor.mjs

@@ -155,13 +155,16 @@ function changeResult(tool, args, vaultBase) {
 
 async function observerQuery(args, ctx) {
   const {
-    openObserverDatabase,
+    bootstrapObserverDatabase,
     readSqlProjectOverview,
     readUsageBreakdown,
     readUsageCalls,
     readUsageSummary,
     searchSqlDocuments,
   } = await import('../../../src/observer-sql-store.mjs');
+  const { authorizeObserverPrincipal, recordObserverAudit } = await import('../../observer/src/authz.mjs');
+  const { resolveObserverPrincipal } = await import('../../observer/src/token-registry.mjs');
+  const { observerEncryptionFromEnvironment } = await import('../../observer/src/encryption.mjs');
   const kind = String(args.query || 'overview').trim();
   const filters = args.payload?.filters && typeof args.payload.filters === 'object'
     ? args.payload.filters
@@ -169,7 +172,37 @@ async function observerQuery(args, ctx) {
   const dataDir = resolve(process.env.WENDKEEP_OBSERVER_DATA_DIR || join(homedir(), '.wendkeep-observer'));
   let db;
   try {
-    db = openObserverDatabase(dataDir);
+    const encryption = observerEncryptionFromEnvironment();
+    ({ db } = bootstrapObserverDatabase(dataDir, { security: { encryption } }));
+    const capability = {
+      overview: 'project:read',
+      usage_summary: 'usage:summary:read',
+      usage_breakdown: 'usage:breakdown:read',
+      usage_calls: 'usage:calls:read',
+      memory_search: 'memory:content:read',
+    }[kind] || 'project:read';
+    const rawToken = String(process.env.WENDKEEP_OBSERVER_TOKEN || '');
+    const requireToken = ['usage:calls:read', 'memory:content:read'].includes(capability)
+      || process.env.WENDKEEP_OBSERVER_REQUIRE_LOOPBACK_AUTH === '1';
+    if (rawToken || requireToken) {
+      const principal = resolveObserverPrincipal(db, rawToken);
+      const authorized = authorizeObserverPrincipal(principal, {
+        projectId: ctx.resolution.projectId,
+        capability,
+      });
+      if (!authorized.ok) {
+        throw Object.assign(new Error('Observer query requires a project-scoped token and capability'), {
+          code: authorized.code || 'MCP_OBSERVER_AUTH_REQUIRED',
+        });
+      }
+      if (['usage:calls:read', 'memory:content:read'].includes(capability)) recordObserverAudit(db, {
+        projectId: ctx.resolution.projectId,
+        tokenId: principal.token_id,
+        capability,
+        outcome: 'allowed',
+        metadata: { route: `mcp:${kind}`, method: 'MCP' },
+      });
+    }
     switch (kind) {
       case 'overview': return sanitize(readSqlProjectOverview(db, ctx.resolution.projectId));
       case 'usage_summary': return sanitize(readUsageSummary(db, ctx.resolution.projectId, filters));

package/packages/observer/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@wendkeep/observer",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./policy": "./src/policy.mjs",
+    "./redaction": "./src/redaction.mjs",
+    "./authz": "./src/authz.mjs",
+    "./token-registry": "./src/token-registry.mjs",
+    "./encryption": "./src/encryption.mjs",
+    "./retention": "./src/retention.mjs",
+    "./purge": "./src/purge.mjs",
+    "./audit": "./src/audit.mjs"
+  }
+}

package/packages/observer/src/audit.mjs

@@ -0,0 +1 @@
+export { recordObserverAudit } from './authz.mjs';

package/packages/observer/src/authz.mjs

@@ -0,0 +1,38 @@
+import { createHash } from 'node:crypto';
+import { sanitizeObserverAuditMetadata } from './redaction.mjs';
+
+const ROLE_CAPABILITIES = {
+  viewer: new Set(['project:read', 'usage:summary:read', 'usage:breakdown:read', 'memory:metadata:read', 'sync:read']),
+  auditor: new Set(['project:read', 'usage:summary:read', 'usage:breakdown:read', 'usage:calls:read', 'transcript:read', 'memory:metadata:read', 'memory:content:read', 'audit:read', 'sync:read']),
+  publisher: new Set(['project:read', 'project:write', 'ingest:write', 'memory:write', 'snapshot:write', 'sync:write']),
+  admin: new Set(['*']),
+};
+
+function scopeMatches(scopes, capability) {
+  return scopes.includes('*') || scopes.includes(capability)
+    || scopes.some((scope) => scope.endsWith(':*') && capability.startsWith(scope.slice(0, -1)));
+}
+
+export function authorizeObserverPrincipal(principal, { projectId, capability } = {}) {
+  if (!principal?.ok) return { ok: false, status: 401, code: principal?.code || 'observer_auth_required' };
+  if (!principal.project_ids?.includes('*') && !principal.project_ids?.includes(projectId)) {
+    return { ok: false, status: 403, code: 'observer_project_forbidden' };
+  }
+  const grants = ROLE_CAPABILITIES[principal.role] || new Set();
+  if (!grants.has('*') && !grants.has(capability)) return { ok: false, status: 403, code: 'observer_role_forbidden' };
+  if (!scopeMatches(principal.scopes || [], capability)) return { ok: false, status: 403, code: 'observer_scope_forbidden' };
+  return { ok: true, status: 200, code: 'observer_authorized' };
+}
+
+export function recordObserverAudit(db, {
+  auditId, projectId, tokenId = '', capability, outcome, occurredAt = new Date().toISOString(), metadata = {},
+} = {}) {
+  const safeMetadata = sanitizeObserverAuditMetadata(metadata);
+  const id = String(auditId || createHash('sha256').update(JSON.stringify({ projectId, tokenId, capability, outcome, occurredAt, safeMetadata })).digest('hex').slice(0, 32));
+  const persistedTokenId = tokenId && db.prepare('SELECT token_id FROM observer_tokens WHERE token_id = ?').get(tokenId)
+    ? tokenId
+    : null;
+  db.prepare(`INSERT OR IGNORE INTO observer_access_audit(audit_id, project_id, token_id, capability, outcome, occurred_at, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, projectId, persistedTokenId, capability, outcome, new Date(occurredAt).toISOString(), JSON.stringify(safeMetadata));
+  return { audit_id: id, project_id: projectId, token_id: tokenId, capability, outcome, occurred_at: new Date(occurredAt).toISOString(), metadata: safeMetadata };
+}