pumuki 6.3.26 → 6.3.28

package/integrations/lifecycle/install.ts

@@ -1,22 +1,38 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { installPumukiHooks } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { doctorHasBlockingIssues, runLifecycleDoctor } from './doctor';
 import { runOpenSpecBootstrap, type OpenSpecBootstrapResult } from './openSpecBootstrap';
 import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
-import { getCurrentPumukiVersion } from './packageInfo';
+import { resolveCurrentPumukiDependency } from './consumerPackage';
+import { getCurrentPumukiPackageName, getCurrentPumukiVersion } from './packageInfo';
 import { generateEvidence } from '../evidence/generateEvidence';
 import { readEvidence } from '../evidence/readEvidence';
 import { captureRepoState } from '../evidence/repoState';
 import { createEmptyEvaluationMetrics } from '../evidence/evaluationMetrics';
 import { readOpenSpecManagedArtifacts, writeLifecycleState } from './state';
 
+export type LifecycleConsumerPackageBootstrapResult = {
+  packageInstalled: boolean;
+  dependencySource?: 'dependencies' | 'devDependencies';
+  targetSpec?: string;
+  skippedReason?:
+    | 'NO_PACKAGE_JSON'
+    | 'PACKAGE_JSON_INVALID'
+    | 'SELF_PACKAGE_REPO'
+    | 'ALREADY_DECLARED'
+    | 'NPM_INSTALL_FAILED'
+    | 'ENGINE_MISMATCH';
+  skippedDetails?: string;
+};
+
 export type LifecycleInstallResult = {
   repoRoot: string;
   version: string;
   changedHooks: ReadonlyArray<string>;
   openSpecBootstrap?: OpenSpecBootstrapResult;
+  consumerPackageBootstrap: LifecycleConsumerPackageBootstrapResult;
 };
 
 const shouldBootstrapEvidence = (repoRoot: string): boolean =>
@@ -37,6 +53,95 @@ const writeBootstrapEvidence = (repoRoot: string): void => {
   });
 };
 
+const readConsumerPackageName = (
+  repoRoot: string
+): {
+  name?: string;
+  parseError?: string;
+} => {
+  const packageJsonPath = join(repoRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    const parsed = JSON.parse(raw) as { name?: unknown };
+    const name = typeof parsed.name === 'string' ? parsed.name.trim() : undefined;
+    return {
+      name: name && name.length > 0 ? name : undefined,
+    };
+  } catch (error) {
+    return {
+      parseError: error instanceof Error ? error.message : 'Invalid package.json',
+    };
+  }
+};
+
+const runConsumerPackageBootstrap = (params: {
+  repoRoot: string;
+  npm: ILifecycleNpmService;
+  openSpecBootstrap?: OpenSpecBootstrapResult;
+}): LifecycleConsumerPackageBootstrapResult => {
+  if (params.openSpecBootstrap?.skippedReason === 'ENGINE_MISMATCH') {
+    return {
+      packageInstalled: false,
+      skippedReason: 'ENGINE_MISMATCH',
+      skippedDetails: params.openSpecBootstrap.skippedDetails,
+    };
+  }
+
+  const packageJsonPath = join(params.repoRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return {
+      packageInstalled: false,
+      skippedReason: 'NO_PACKAGE_JSON',
+    };
+  }
+
+  const packageInfo = readConsumerPackageName(params.repoRoot);
+  if (packageInfo.parseError) {
+    return {
+      packageInstalled: false,
+      skippedReason: 'PACKAGE_JSON_INVALID',
+      skippedDetails: packageInfo.parseError,
+    };
+  }
+
+  const packageName = getCurrentPumukiPackageName();
+  if (packageInfo.name === packageName) {
+    return {
+      packageInstalled: false,
+      skippedReason: 'SELF_PACKAGE_REPO',
+    };
+  }
+
+  const declaredDependency = resolveCurrentPumukiDependency(params.repoRoot);
+  if (declaredDependency.source !== 'none') {
+    return {
+      packageInstalled: false,
+      dependencySource: declaredDependency.source,
+      targetSpec: declaredDependency.spec,
+      skippedReason: 'ALREADY_DECLARED',
+    };
+  }
+
+  const targetSpec = `${packageName}@latest`;
+  try {
+    params.npm.runNpm(['install', '--save-dev', '--save-exact', targetSpec], params.repoRoot);
+    return {
+      packageInstalled: true,
+      dependencySource: 'devDependencies',
+      targetSpec,
+    };
+  } catch (error) {
+    return {
+      packageInstalled: false,
+      skippedReason: 'NPM_INSTALL_FAILED',
+      skippedDetails: error instanceof Error ? error.message : 'npm install failed',
+    };
+  }
+};
+
 export const runLifecycleInstall = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
@@ -59,13 +164,19 @@ export const runLifecycleInstall = (params?: {
 
   const shouldBootstrapOpenSpec =
     params?.bootstrapOpenSpec ?? process.env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP !== '1';
+  const npm = params?.npm ?? new LifecycleNpmService();
 
   const openSpecBootstrap = shouldBootstrapOpenSpec
     ? runOpenSpecBootstrap({
       repoRoot: report.repoRoot,
-      npm: params?.npm ?? new LifecycleNpmService(),
+      npm,
     })
     : undefined;
+  const consumerPackageBootstrap = runConsumerPackageBootstrap({
+    repoRoot: report.repoRoot,
+    npm,
+    openSpecBootstrap,
+  });
 
   const hookResult = installPumukiHooks(report.repoRoot);
   const version = getCurrentPumukiVersion();
@@ -91,5 +202,6 @@ export const runLifecycleInstall = (params?: {
     version,
     changedHooks: hookResult.changedHooks,
     openSpecBootstrap,
+    consumerPackageBootstrap,
   };
 };

package/integrations/lifecycle/openSpecBootstrap.ts

@@ -14,7 +14,8 @@ export type OpenSpecBootstrapResult = {
   projectInitialized: boolean;
   actions: ReadonlyArray<string>;
   managedArtifacts: ReadonlyArray<string>;
-  skippedReason?: 'NO_PACKAGE_JSON';
+  skippedReason?: 'NO_PACKAGE_JSON' | 'NPM_INSTALL_FAILED' | 'ENGINE_MISMATCH';
+  skippedDetails?: string;
 };
 
 type PackageDependencySource = 'dependencies' | 'devDependencies' | 'none';
@@ -22,6 +23,10 @@ type PackageDependencySource = 'dependencies' | 'devDependencies' | 'none';
 type PackageJson = {
   dependencies?: Record<string, string>;
   devDependencies?: Record<string, string>;
+  engines?: {
+    node?: string;
+    npm?: string;
+  };
 };
 
 const readPackageJson = (repoRoot: string): PackageJson | undefined => {
@@ -48,6 +53,43 @@ const resolveDependencySource = (
   return 'none';
 };
 
+const normalizeSemverToken = (value: string): string => value.trim().replace(/^v/i, '');
+
+const isExactSemver = (value: string): boolean => /^\d+\.\d+\.\d+$/.test(normalizeSemverToken(value));
+
+const resolveCurrentNpmVersionFromEnv = (): string | undefined => {
+  const userAgent = process.env.npm_config_user_agent;
+  if (!userAgent) {
+    return undefined;
+  }
+  const match = userAgent.match(/npm\/(\d+\.\d+\.\d+)/);
+  return match ? normalizeSemverToken(match[1]) : undefined;
+};
+
+const resolveEngineMismatch = (packageJson: PackageJson | undefined): string | undefined => {
+  const requiredNode = packageJson?.engines?.node;
+  if (requiredNode && isExactSemver(requiredNode)) {
+    const normalizedRequiredNode = normalizeSemverToken(requiredNode);
+    const currentNode = normalizeSemverToken(process.versions.node);
+    if (currentNode !== normalizedRequiredNode) {
+      return `node required=${normalizedRequiredNode} current=${currentNode}`;
+    }
+  }
+
+  const requiredNpm = packageJson?.engines?.npm;
+  if (requiredNpm && isExactSemver(requiredNpm)) {
+    const currentNpm = resolveCurrentNpmVersionFromEnv();
+    if (currentNpm) {
+      const normalizedRequiredNpm = normalizeSemverToken(requiredNpm);
+      if (currentNpm !== normalizedRequiredNpm) {
+        return `npm required=${normalizedRequiredNpm} current=${currentNpm}`;
+      }
+    }
+  }
+
+  return undefined;
+};
+
 const OPENSPEC_LEGACY_NPM_PACKAGE_NAME = 'openspec';
 const OPENSPEC_PROJECT_MD = 'openspec/project.md';
 const OPENSPEC_ARCHIVE_GITKEEP = 'openspec/changes/archive/.gitkeep';
@@ -163,20 +205,37 @@ export const runOpenSpecBootstrap = (params: {
 }): OpenSpecBootstrapResult => {
   const npm = params.npm ?? new LifecycleNpmService();
   const actions: string[] = [];
+  const packageJson = readPackageJson(params.repoRoot);
 
   const installation = detectOpenSpecInstallation(params.repoRoot);
   const compatibility = evaluateOpenSpecCompatibility(installation);
   let packageInstalled = installation.installed;
   const packageJsonPath = join(params.repoRoot, 'package.json');
   const hasPackageJson = existsSync(packageJsonPath);
+  let skippedReason: OpenSpecBootstrapResult['skippedReason'];
+  let skippedDetails: string | undefined;
 
   if ((!packageInstalled || !compatibility.compatible) && hasPackageJson) {
-    npm.runNpm(
-      ['install', '--save-dev', '--save-exact', `${OPENSPEC_NPM_PACKAGE_NAME}@latest`],
-      params.repoRoot
-    );
-    packageInstalled = true;
-    actions.push(`npm-install:${OPENSPEC_NPM_PACKAGE_NAME}@latest`);
+    const engineMismatch = resolveEngineMismatch(packageJson);
+    if (engineMismatch) {
+      skippedReason = 'ENGINE_MISMATCH';
+      skippedDetails = engineMismatch;
+      actions.push('npm-install-skipped:engine-mismatch');
+    } else {
+      try {
+        npm.runNpm(
+          ['install', '--save-dev', '--save-exact', `${OPENSPEC_NPM_PACKAGE_NAME}@latest`],
+          params.repoRoot
+        );
+        packageInstalled = true;
+        actions.push(`npm-install:${OPENSPEC_NPM_PACKAGE_NAME}@latest`);
+      } catch (error) {
+        skippedReason = 'NPM_INSTALL_FAILED';
+        skippedDetails =
+          error instanceof Error ? error.message : 'npm install failed during OpenSpec bootstrap';
+        actions.push(`npm-install-failed:${OPENSPEC_NPM_PACKAGE_NAME}@latest`);
+      }
+    }
   }
 
   const projectInitializedBefore = isOpenSpecProjectInitialized(params.repoRoot);
@@ -194,6 +253,7 @@ export const runOpenSpecBootstrap = (params: {
     projectInitialized: isOpenSpecProjectInitialized(params.repoRoot),
     actions,
     managedArtifacts,
-    skippedReason: !packageInstalled && !hasPackageJson ? 'NO_PACKAGE_JSON' : undefined,
+    skippedReason: skippedReason ?? (!packageInstalled && !hasPackageJson ? 'NO_PACKAGE_JSON' : undefined),
+    skippedDetails,
   };
 };

package/integrations/lifecycle/preWriteAutomation.ts

@@ -0,0 +1,142 @@
+import { evaluateAiGate } from '../gate/evaluateAiGate';
+import { runPlatformGate } from '../git/runPlatformGate';
+import { runEnterpriseAiGateCheck } from '../mcp/aiGateCheck';
+import { writeMcpAiGateReceipt } from '../mcp/aiGateReceipt';
+import { evaluateSddPolicy } from '../sdd';
+
+const PRE_WRITE_AUTOFIXABLE_EVIDENCE_CODES = new Set<string>([
+  'EVIDENCE_MISSING',
+  'EVIDENCE_INVALID',
+  'EVIDENCE_STALE',
+  'EVIDENCE_REPO_ROOT_MISMATCH',
+  'EVIDENCE_BRANCH_MISMATCH',
+  'EVIDENCE_RULES_COVERAGE_MISSING',
+  'EVIDENCE_RULES_COVERAGE_STAGE_MISMATCH',
+  'EVIDENCE_RULES_COVERAGE_INCOMPLETE',
+  'EVIDENCE_UNSUPPORTED_AUTO_RULES',
+  'EVIDENCE_TIMESTAMP_INVALID',
+  'EVIDENCE_TIMESTAMP_FUTURE',
+]);
+
+const PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES = new Set<string>([
+  'MCP_ENTERPRISE_RECEIPT_MISSING',
+  'MCP_ENTERPRISE_RECEIPT_INVALID',
+  'MCP_ENTERPRISE_RECEIPT_STALE',
+  'MCP_ENTERPRISE_RECEIPT_STAGE_MISMATCH',
+  'MCP_ENTERPRISE_RECEIPT_REPO_ROOT_MISMATCH',
+  'MCP_ENTERPRISE_RECEIPT_TIMESTAMP_INVALID',
+  'MCP_ENTERPRISE_RECEIPT_TIMESTAMP_FUTURE',
+]);
+
+export type PreWriteAutomationAction = {
+  action: 'refresh_evidence' | 'refresh_mcp_receipt';
+  status: 'OK' | 'FAILED';
+  details: string;
+};
+
+export type PreWriteAutomationTrace = {
+  attempted: boolean;
+  actions: PreWriteAutomationAction[];
+};
+
+export const buildPreWriteAutomationTrace = async (params: {
+  repoRoot: string;
+  sdd: ReturnType<typeof evaluateSddPolicy>;
+  aiGate: ReturnType<typeof evaluateAiGate>;
+  runPlatformGate: typeof runPlatformGate;
+}): Promise<{
+  aiGate: ReturnType<typeof evaluateAiGate>;
+  trace: PreWriteAutomationTrace;
+}> => {
+  const trace: PreWriteAutomationTrace = {
+    attempted: false,
+    actions: [],
+  };
+  if (params.sdd.stage !== 'PRE_WRITE' || !params.sdd.decision.allowed || params.aiGate.allowed) {
+    return {
+      aiGate: params.aiGate,
+      trace,
+    };
+  }
+
+  let aiGate = params.aiGate;
+  const hasEvidenceAutoFixableViolation = aiGate.violations.some((violation) =>
+    PRE_WRITE_AUTOFIXABLE_EVIDENCE_CODES.has(violation.code)
+  );
+  if (hasEvidenceAutoFixableViolation) {
+    trace.attempted = true;
+    try {
+      const gateExitCode = await params.runPlatformGate({
+        policy: {
+          stage: 'PRE_COMMIT',
+          blockOnOrAbove: 'ERROR',
+          warnOnOrAbove: 'WARN',
+        },
+        scope: {
+          kind: 'workingTree',
+        },
+        auditMode: 'gate',
+        dependencies: {
+          printGateFindings: () => {},
+        },
+      });
+      trace.actions.push({
+        action: 'refresh_evidence',
+        status: 'OK',
+        details: `runPlatformGate exit_code=${gateExitCode}`,
+      });
+      aiGate = runEnterpriseAiGateCheck({
+        repoRoot: params.repoRoot,
+        stage: 'PRE_WRITE',
+        requireMcpReceipt: true,
+      }).result;
+    } catch (error) {
+      trace.actions.push({
+        action: 'refresh_evidence',
+        status: 'FAILED',
+        details: error instanceof Error ? error.message : 'Unknown evidence refresh error',
+      });
+    }
+  }
+
+  const hasReceiptAutoFixableViolation = aiGate.violations.some((violation) =>
+    PRE_WRITE_AUTOFIXABLE_MCP_RECEIPT_CODES.has(violation.code)
+  );
+  if (hasReceiptAutoFixableViolation) {
+    trace.attempted = true;
+    try {
+      const aiGateWithoutReceiptRequirement = evaluateAiGate({
+        repoRoot: params.repoRoot,
+        stage: 'PRE_WRITE',
+        requireMcpReceipt: false,
+      });
+      const receiptWrite = writeMcpAiGateReceipt({
+        repoRoot: params.repoRoot,
+        stage: 'PRE_WRITE',
+        status: aiGateWithoutReceiptRequirement.status,
+        allowed: aiGateWithoutReceiptRequirement.allowed,
+      });
+      trace.actions.push({
+        action: 'refresh_mcp_receipt',
+        status: 'OK',
+        details: `receipt=${receiptWrite.path}`,
+      });
+      aiGate = runEnterpriseAiGateCheck({
+        repoRoot: params.repoRoot,
+        stage: 'PRE_WRITE',
+        requireMcpReceipt: true,
+      }).result;
+    } catch (error) {
+      trace.actions.push({
+        action: 'refresh_mcp_receipt',
+        status: 'FAILED',
+        details: error instanceof Error ? error.message : 'Unknown MCP receipt refresh error',
+      });
+    }
+  }
+
+  return {
+    aiGate,
+    trace,
+  };
+};

package/integrations/mcp/aiGateCheck.ts

@@ -12,6 +12,8 @@ export type EnterpriseAiGateCheckResult = {
     policy: ReturnType<typeof evaluateAiGate>['policy'];
     violations: ReturnType<typeof evaluateAiGate>['violations'];
     evidence: ReturnType<typeof evaluateAiGate>['evidence'];
+    mcp_receipt: ReturnType<typeof evaluateAiGate>['mcp_receipt'];
+    waivers: ReturnType<typeof evaluateAiGate>['waivers'];
     repo_state: ReturnType<typeof evaluateAiGate>['repo_state'];
   };
 };
@@ -19,10 +21,12 @@ export type EnterpriseAiGateCheckResult = {
 export const runEnterpriseAiGateCheck = (params: {
   repoRoot: string;
   stage: AiGateStage;
+  requireMcpReceipt?: boolean;
 }): EnterpriseAiGateCheckResult => {
   const evaluation = evaluateAiGate({
     repoRoot: params.repoRoot,
     stage: params.stage,
+    requireMcpReceipt: params.requireMcpReceipt ?? false,
   });
 
   return {
@@ -37,6 +41,8 @@ export const runEnterpriseAiGateCheck = (params: {
       policy: evaluation.policy,
       violations: evaluation.violations,
       evidence: evaluation.evidence,
+      mcp_receipt: evaluation.mcp_receipt,
+      waivers: evaluation.waivers,
       repo_state: evaluation.repo_state,
     },
   };

package/integrations/mcp/aiGateReceipt.ts

@@ -0,0 +1,188 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export type McpAiGateStage = 'PRE_WRITE' | 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+
+export type McpAiGateReceipt = {
+  version: '1';
+  source: 'pumuki-enterprise-mcp';
+  tool: 'ai_gate_check';
+  repo_root: string;
+  stage: McpAiGateStage;
+  status: 'ALLOWED' | 'BLOCKED';
+  allowed: boolean;
+  issued_at: string;
+};
+
+export type McpAiGateReceiptReadResult =
+  | {
+      kind: 'missing';
+      path: string;
+    }
+  | {
+      kind: 'invalid';
+      path: string;
+      reason: string;
+    }
+  | {
+      kind: 'valid';
+      path: string;
+      receipt: McpAiGateReceipt;
+    };
+
+const RECEIPT_RELATIVE_PATH = '.pumuki/artifacts/mcp-ai-gate-receipt.json';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isStage = (value: unknown): value is McpAiGateStage =>
+  value === 'PRE_WRITE' ||
+  value === 'PRE_COMMIT' ||
+  value === 'PRE_PUSH' ||
+  value === 'CI';
+
+const isStatus = (value: unknown): value is 'ALLOWED' | 'BLOCKED' =>
+  value === 'ALLOWED' || value === 'BLOCKED';
+
+const isValidIsoTimestamp = (value: string): boolean => Number.isFinite(Date.parse(value));
+
+export const resolveMcpAiGateReceiptPath = (repoRoot: string): string =>
+  resolve(repoRoot, RECEIPT_RELATIVE_PATH);
+
+export const writeMcpAiGateReceipt = (params: {
+  repoRoot: string;
+  stage: McpAiGateStage;
+  status: 'ALLOWED' | 'BLOCKED';
+  allowed: boolean;
+  issuedAt?: string;
+}): { path: string; receipt: McpAiGateReceipt } => {
+  const issuedAt = params.issuedAt ?? new Date().toISOString();
+  const path = resolveMcpAiGateReceiptPath(params.repoRoot);
+  const receipt: McpAiGateReceipt = {
+    version: '1',
+    source: 'pumuki-enterprise-mcp',
+    tool: 'ai_gate_check',
+    repo_root: params.repoRoot,
+    stage: params.stage,
+    status: params.status,
+    allowed: params.allowed,
+    issued_at: issuedAt,
+  };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+  return {
+    path,
+    receipt,
+  };
+};
+
+const parseReceipt = (value: unknown): { ok: true; receipt: McpAiGateReceipt } | { ok: false; reason: string } => {
+  if (!isRecord(value)) {
+    return {
+      ok: false,
+      reason: 'Receipt payload must be an object.',
+    };
+  }
+  if (value.version !== '1') {
+    return {
+      ok: false,
+      reason: 'Receipt version must be "1".',
+    };
+  }
+  if (value.source !== 'pumuki-enterprise-mcp') {
+    return {
+      ok: false,
+      reason: 'Receipt source must be "pumuki-enterprise-mcp".',
+    };
+  }
+  if (value.tool !== 'ai_gate_check') {
+    return {
+      ok: false,
+      reason: 'Receipt tool must be "ai_gate_check".',
+    };
+  }
+  if (typeof value.repo_root !== 'string' || value.repo_root.trim().length === 0) {
+    return {
+      ok: false,
+      reason: 'Receipt repo_root must be a non-empty string.',
+    };
+  }
+  if (!isStage(value.stage)) {
+    return {
+      ok: false,
+      reason: 'Receipt stage must be PRE_WRITE, PRE_COMMIT, PRE_PUSH or CI.',
+    };
+  }
+  if (!isStatus(value.status)) {
+    return {
+      ok: false,
+      reason: 'Receipt status must be ALLOWED or BLOCKED.',
+    };
+  }
+  if (typeof value.allowed !== 'boolean') {
+    return {
+      ok: false,
+      reason: 'Receipt allowed must be boolean.',
+    };
+  }
+  if (typeof value.issued_at !== 'string' || !isValidIsoTimestamp(value.issued_at)) {
+    return {
+      ok: false,
+      reason: 'Receipt issued_at must be a valid ISO timestamp.',
+    };
+  }
+  if ((value.status === 'ALLOWED' && value.allowed !== true) || (value.status === 'BLOCKED' && value.allowed !== false)) {
+    return {
+      ok: false,
+      reason: 'Receipt status and allowed must be coherent.',
+    };
+  }
+
+  return {
+    ok: true,
+    receipt: {
+      version: value.version,
+      source: value.source,
+      tool: value.tool,
+      repo_root: value.repo_root,
+      stage: value.stage,
+      status: value.status,
+      allowed: value.allowed,
+      issued_at: value.issued_at,
+    },
+  };
+};
+
+export const readMcpAiGateReceipt = (repoRoot: string): McpAiGateReceiptReadResult => {
+  const path = resolveMcpAiGateReceiptPath(repoRoot);
+  if (!existsSync(path)) {
+    return {
+      kind: 'missing',
+      path,
+    };
+  }
+
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    const receipt = parseReceipt(parsed);
+    if (!receipt.ok) {
+      return {
+        kind: 'invalid',
+        path,
+        reason: receipt.reason,
+      };
+    }
+    return {
+      kind: 'valid',
+      path,
+      receipt: receipt.receipt,
+    };
+  } catch (error) {
+    return {
+      kind: 'invalid',
+      path,
+      reason: error instanceof Error ? error.message : 'Unknown receipt parsing error.',
+    };
+  }
+};

package/integrations/mcp/enterpriseServer.ts

@@ -9,6 +9,7 @@ import { evaluateSddPolicy, readSddStatus } from '../sdd';
 import type { SddStage } from '../sdd';
 import { toStatusPayload } from './evidencePayloads';
 import { runEnterpriseAiGateCheck } from './aiGateCheck';
+import { writeMcpAiGateReceipt } from './aiGateReceipt';
 
 export interface EnterpriseServerOptions {
   host?: string;
@@ -357,12 +358,24 @@ const executeEnterpriseTool = (
         repoRoot,
         stage,
       });
+      const receiptWrite = writeMcpAiGateReceipt({
+        repoRoot,
+        stage: execution.result.stage,
+        status: execution.result.status,
+        allowed: execution.result.allowed,
+      });
       return {
         name: toolName,
         success: execution.success,
         dryRun: execution.dryRun,
         executed: execution.executed,
-        data: execution.result,
+        data: {
+          ...execution.result,
+          receipt: {
+            path: receiptWrite.path,
+            issued_at: receiptWrite.receipt.issued_at,
+          },
+        },
       };
     }
     case 'check_sdd_status': {