pumuki 6.3.129 → 6.3.130

package/integrations/lifecycle/trackingState.ts

@@ -0,0 +1,403 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+
+export type TrackingDeclaration = {
+  source_file: string;
+  declared_path: string;
+  resolved_path: string;
+};
+
+export type RepoTrackingState = {
+  enforced: boolean;
+  canonical_path: string | null;
+  canonical_present: boolean;
+  source_file: string | null;
+  in_progress_count: number;
+  single_in_progress_valid: boolean;
+  conflict: boolean;
+  declarations: ReadonlyArray<TrackingDeclaration>;
+  in_progress_entries?: ReadonlyArray<{
+    line_number: number;
+    task_id: string | null;
+  }>;
+  active_task_id?: string | null;
+  last_run_path?: string | null;
+  last_run_status?: string | null;
+};
+
+export const formatTrackingActionableContext = (tracking: RepoTrackingState): string | null => {
+  const activeEntries = (tracking.in_progress_entries ?? [])
+    .map((entry) => `${entry.task_id ?? 'UNKNOWN'}@L${entry.line_number}`)
+    .join(', ');
+  if (!activeEntries) {
+    return null;
+  }
+  const lastRunStatus = tracking.last_run_status ?? 'absent';
+  return `active_entries=${activeEntries} last_run_status=${lastRunStatus}`;
+};
+
+type TrackingDeclarationSource = {
+  sourceFile: string;
+  priority: number;
+  patterns: ReadonlyArray<RegExp>;
+};
+
+type TrackingCandidate = TrackingDeclaration & {
+  priority: number;
+};
+
+type InProgressEntry = {
+  lineNumber: number;
+  taskId: string | null;
+};
+
+const TRACKING_DECLARATION_SOURCES: ReadonlyArray<TrackingDeclarationSource> = [
+  {
+    sourceFile: 'AGENTS.md',
+    priority: 100,
+    patterns: [
+      /[uú]nica fuente viva del tracking interno es [`']([^`'\n]+)[`']/i,
+      /ningun documento de seguimiento fuera de [`']([^`'\n]+)[`']/i,
+    ],
+  },
+  {
+    sourceFile: 'docs/README.md',
+    priority: 80,
+    patterns: [
+      /todo el seguimiento operativo[\s\S]{0,240}?\[[^\]]+\]\(([^)]+)\)/i,
+      /[uú]nica fuente de verdad[^`\n]*[`']([^`'\n]+)[`']/i,
+      /fuente viva del tracking interno:\s*[`']([^`'\n]+)[`']/i,
+      /quiero saber en qué estamos ahora:\s*[\s\S]{0,80}[-*]\s*[`']([^`'\n]+)[`']/i,
+    ],
+  },
+  {
+    sourceFile: 'docs/validation/README.md',
+    priority: 60,
+    patterns: [/[uú]nica fuente de seguimiento:\s*[`']([^`'\n]+)[`']/i],
+  },
+];
+
+const toRepoRelativePath = (repoRoot: string, candidatePath: string): string | null => {
+  const repoRootAbsolute = resolve(repoRoot);
+  const resolved = resolve(candidatePath);
+  const rel = relative(repoRootAbsolute, resolved);
+  if (
+    rel === '..' ||
+    rel.startsWith('../') ||
+    rel.startsWith('..\\')
+  ) {
+    return null;
+  }
+  return rel.length > 0 ? rel.split('\\').join('/') : '.';
+};
+
+const normalizeDeclaredPath = (value: string): string => value.trim().replace(/[#?].*$/, '');
+
+const resolveDeclaredPath = (params: {
+  repoRoot: string;
+  sourceFile: string;
+  declaredPath: string;
+}): string | null => {
+  const sourceAbsolutePath = resolve(params.repoRoot, params.sourceFile);
+  const candidate = normalizeDeclaredPath(params.declaredPath);
+  if (candidate.length === 0) {
+    return null;
+  }
+  const resolved = candidate.startsWith('./') || candidate.startsWith('../')
+    ? resolve(dirname(sourceAbsolutePath), candidate)
+    : resolve(params.repoRoot, candidate);
+  return toRepoRelativePath(params.repoRoot, resolved);
+};
+
+const collectTrackingCandidates = (repoRoot: string): ReadonlyArray<TrackingCandidate> => {
+  const candidates = new Map<string, TrackingCandidate>();
+
+  for (const source of TRACKING_DECLARATION_SOURCES) {
+    const sourcePath = resolve(repoRoot, source.sourceFile);
+    if (!existsSync(sourcePath)) {
+      continue;
+    }
+    const markdown = readFileSync(sourcePath, 'utf8');
+    for (const pattern of source.patterns) {
+      const match = pattern.exec(markdown);
+      const declaredPath = match?.[1]?.trim();
+      if (!declaredPath) {
+        continue;
+      }
+      const resolvedPath = resolveDeclaredPath({
+        repoRoot,
+        sourceFile: source.sourceFile,
+        declaredPath,
+      });
+      if (!resolvedPath) {
+        continue;
+      }
+      const key = `${source.sourceFile}::${resolvedPath}`;
+      if (candidates.has(key)) {
+        continue;
+      }
+      candidates.set(key, {
+        source_file: source.sourceFile,
+        declared_path: declaredPath,
+        resolved_path: resolvedPath,
+        priority: source.priority,
+      });
+    }
+  }
+
+  return Array.from(candidates.values()).sort((left, right) => {
+    if (right.priority !== left.priority) {
+      return right.priority - left.priority;
+    }
+    const bySource = left.source_file.localeCompare(right.source_file);
+    return bySource !== 0 ? bySource : left.resolved_path.localeCompare(right.resolved_path);
+  });
+};
+
+const extractTaskId = (value: string): string | null => {
+  const directMatch = value.match(/\b([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+)\b/);
+  if (directMatch?.[1]) {
+    return directMatch[1];
+  }
+  const dottedMatch = value.match(/\b([A-Z][A-Z0-9]*(?:[.-][A-Z0-9]+)+)\b/);
+  return dottedMatch?.[1] ?? null;
+};
+
+const collectInProgressEntries = (markdown: string): ReadonlyArray<InProgressEntry> => {
+  const lines = markdown.split(/\r?\n/);
+  const entries: InProgressEntry[] = [];
+
+  lines.forEach((line, index) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+
+    if (trimmed.startsWith('|')) {
+      const cells = trimmed
+        .split('|')
+        .map((cell) => cell.trim())
+        .filter((cell) => cell.length > 0);
+      const firstCell = cells[0] ?? '';
+      const secondCell = cells[1] ?? '';
+      if (firstCell === '🚧') {
+        entries.push({
+          lineNumber: index + 1,
+          taskId: extractTaskId(secondCell),
+        });
+        return;
+      }
+      const bracketCell = cells.find((cell) => /\[\s*🚧\s*\]\s*-/.test(cell));
+      if (bracketCell) {
+        entries.push({
+          lineNumber: index + 1,
+          taskId: extractTaskId(bracketCell),
+        });
+        return;
+      }
+      const emojiCell = cells.find((cell) => /^🚧(?:\b|\s|[*_`])/.test(cell));
+      if (emojiCell) {
+        const taskCell = cells.find((cell) => cell !== emojiCell && !/^[:\- ]+$/.test(cell)) ?? emojiCell;
+        entries.push({
+          lineNumber: index + 1,
+          taskId: extractTaskId(taskCell),
+        });
+        return;
+      }
+    }
+
+    if (/^- Estado:\s*🚧(?:\s|$)/.test(trimmed) || /\[\s*🚧\s*\]\s*-/.test(trimmed)) {
+      entries.push({
+        lineNumber: index + 1,
+        taskId: extractTaskId(trimmed),
+      });
+    }
+  });
+
+  return entries;
+};
+
+const readActiveTaskHeader = (markdown: string): string | null => {
+  const explicitHeader = markdown.match(/- Tarea activa principal:\s*`([^`]+)`/i)?.[1]?.trim();
+  if (explicitHeader && explicitHeader.length > 0) {
+    return extractTaskId(explicitHeader) ?? explicitHeader;
+  }
+  const bracketTask = markdown.match(/\[\s*🚧\s*\]\s*-\s*(.+)$/m)?.[1]?.trim();
+  if (!bracketTask || bracketTask.length === 0) {
+    return null;
+  }
+  return extractTaskId(bracketTask) ?? bracketTask;
+};
+
+const readLastRunAlignment = (params: {
+  repoRoot: string;
+  canonicalPath: string;
+  activeTaskId: string | null;
+  inProgressCount: number;
+  activeTaskHeader: string | null;
+}): {
+  path: string | null;
+  status: string | null;
+  valid: boolean;
+} => {
+  const lastRunPath = resolve(params.repoRoot, 'docs', 'validation', 'refactor', 'last-run.json');
+  if (!existsSync(lastRunPath)) {
+    return {
+      path: null,
+      status: null,
+      valid: params.inProgressCount === 1,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(lastRunPath, 'utf8')) as unknown;
+  } catch {
+    return {
+      path: toRepoRelativePath(params.repoRoot, lastRunPath),
+      status: null,
+      valid: false,
+    };
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return {
+      path: toRepoRelativePath(params.repoRoot, lastRunPath),
+      status: null,
+      valid: false,
+    };
+  }
+
+  const payload = parsed as Record<string, unknown>;
+  const status = typeof payload.status === 'string' ? payload.status.trim().toUpperCase() : null;
+  const planFile = typeof payload.plan_file === 'string' ? payload.plan_file.trim() : null;
+  const nextValue = typeof payload.next === 'string' ? payload.next : '';
+  const lastRunRelativePath = toRepoRelativePath(params.repoRoot, lastRunPath);
+  const planMatches = planFile === params.canonicalPath;
+
+  if (status === 'IN_PROGRESS') {
+    const headerMatches =
+      !params.activeTaskHeader ||
+      params.activeTaskHeader === params.activeTaskId ||
+      (params.activeTaskHeader === 'NINGUNA' && params.activeTaskId === null);
+    const nextMatches = !params.activeTaskId || nextValue.includes(params.activeTaskId);
+    return {
+      path: lastRunRelativePath,
+      status,
+      valid:
+        planMatches &&
+        params.inProgressCount === 1 &&
+        headerMatches &&
+        nextMatches,
+    };
+  }
+
+  if (status === 'DONE') {
+    return {
+      path: lastRunRelativePath,
+      status,
+      valid:
+        planMatches &&
+        params.inProgressCount === 0 &&
+        (params.activeTaskHeader === null || params.activeTaskHeader === 'NINGUNA'),
+    };
+  }
+
+  return {
+    path: lastRunRelativePath,
+    status,
+    valid: false,
+  };
+};
+
+export const resolveRepoTrackingState = (repoRoot: string): RepoTrackingState => {
+  const declarations = collectTrackingCandidates(repoRoot);
+  const enforced = declarations.length > 0;
+  if (!enforced) {
+    return {
+      enforced: false,
+      canonical_path: null,
+      canonical_present: false,
+      source_file: null,
+      in_progress_count: 0,
+      single_in_progress_valid: false,
+      conflict: false,
+      declarations: [],
+      in_progress_entries: [],
+      active_task_id: null,
+      last_run_path: null,
+      last_run_status: null,
+    };
+  }
+
+  const highestPriority = declarations[0]?.priority ?? 0;
+  const highestPriorityDeclarations = declarations.filter(
+    (declaration) => declaration.priority === highestPriority
+  );
+  const uniqueCanonicalPaths = Array.from(
+    new Set(highestPriorityDeclarations.map((declaration) => declaration.resolved_path))
+  );
+  const allDeclaredPaths = Array.from(
+    new Set(declarations.map((declaration) => declaration.resolved_path))
+  );
+  const canonicalPath = uniqueCanonicalPaths.length === 1 ? uniqueCanonicalPaths[0] : null;
+  const canonicalPresent =
+    typeof canonicalPath === 'string' && canonicalPath.length > 0
+      ? existsSync(resolve(repoRoot, canonicalPath))
+      : false;
+  const sourceFile =
+    canonicalPath === null
+      ? null
+      : highestPriorityDeclarations.find(
+          (declaration) => declaration.resolved_path === canonicalPath
+        )?.source_file ?? null;
+
+  if (!canonicalPath || !canonicalPresent) {
+    return {
+      enforced: true,
+      canonical_path: canonicalPath,
+      canonical_present: canonicalPresent,
+      source_file: sourceFile,
+      in_progress_count: 0,
+      single_in_progress_valid: false,
+      conflict: allDeclaredPaths.length > 1,
+      declarations: declarations.map(({ priority: _priority, ...declaration }) => declaration),
+      in_progress_entries: [],
+      active_task_id: null,
+      last_run_path: null,
+      last_run_status: null,
+    };
+  }
+
+  const markdown = readFileSync(resolve(repoRoot, canonicalPath), 'utf8');
+  const inProgressEntries = collectInProgressEntries(markdown);
+  const inProgressCount = inProgressEntries.length;
+  const activeTaskId = inProgressEntries[0]?.taskId ?? null;
+  const activeTaskHeader = readActiveTaskHeader(markdown);
+  const lastRunAlignment = readLastRunAlignment({
+    repoRoot,
+    canonicalPath,
+    activeTaskId,
+    inProgressCount,
+    activeTaskHeader,
+  });
+
+  return {
+    enforced: true,
+    canonical_path: canonicalPath,
+    canonical_present: true,
+    source_file: sourceFile,
+    in_progress_count: inProgressCount,
+    single_in_progress_valid:
+      uniqueCanonicalPaths.length === 1 && lastRunAlignment.valid,
+    conflict: allDeclaredPaths.length > 1,
+    declarations: declarations.map(({ priority: _priority, ...declaration }) => declaration),
+    in_progress_entries: inProgressEntries.map((entry) => ({
+      line_number: entry.lineNumber,
+      task_id: entry.taskId,
+    })),
+    active_task_id: activeTaskId,
+    last_run_path: lastRunAlignment.path,
+    last_run_status: lastRunAlignment.status,
+  };
+};

package/integrations/lifecycle/watch.ts

@@ -736,7 +736,7 @@ export const runLifecycleWatch = async (
           driftFromRuntime,
           driftWarning,
           alignmentCommand: driftFromRuntime
-            ? buildLifecycleAlignmentCommand(versionMetadata.runtimeVersion)
+            ? buildLifecycleAlignmentCommand(versionMetadata.runtimeVersion, repoRoot)
             : null,
         },
         stage,

package/integrations/mcp/aiGateCheck.ts

@@ -1,10 +1,20 @@
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
 import { resolveRemediationHintForViolationCode } from '../gate/remediationCatalog';
+import { readLifecyclePolicyValidationSnapshot } from '../lifecycle/policyValidationSnapshot';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
+import { resolvePreWriteEnforcement } from '../policy/preWriteEnforcement';
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
+import { runMcpAlignedPlatformGate } from './alignedPlatformGate';
 
 const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
 
+type PlatformGateAlignment = {
+  mode: 'full' | 'policy';
+  exit_code: number;
+  aligned: boolean;
+  skip_reason: string | null;
+};
+
 export type EnterpriseAiGateCheckResult = {
   tool: 'ai_gate_check';
   dryRun: true;
@@ -16,6 +26,19 @@ export type EnterpriseAiGateCheckResult = {
     timestamp: string | null;
     branch: string | null;
     message: string;
+    reason_code: string;
+    instruction: string;
+    prewrite_effective: {
+      mode: ReturnType<typeof resolvePreWriteEnforcement>['mode'];
+      source: ReturnType<typeof resolvePreWriteEnforcement>['source'];
+      blocking: boolean;
+      strict_policy: boolean;
+    };
+    next_action: {
+      kind: 'info';
+      reason: string;
+      message: string;
+    };
     stage: ReturnType<typeof evaluateAiGate>['stage'];
     policy: ReturnType<typeof evaluateAiGate>['policy'];
     violations: ReturnType<typeof evaluateAiGate>['violations'];
@@ -31,6 +54,7 @@ export type EnterpriseAiGateCheckResult = {
       reason_code: 'HOOK_RUNNER_CAN_REFRESH_EVIDENCE' | null;
       message: string;
     };
+    platform_gate_alignment?: PlatformGateAlignment;
   };
 };
 
@@ -41,23 +65,18 @@ const isHookRefreshableEvidenceCode = (code: string): boolean =>
 
 type AiGateCheckDependencies = {
   evaluateAiGate: typeof evaluateAiGate;
+  runMcpAlignedPlatformGate: typeof runMcpAlignedPlatformGate;
 };
 
 const defaultDependencies: AiGateCheckDependencies = {
   evaluateAiGate,
+  runMcpAlignedPlatformGate,
 };
 
 const buildConsistencyHint = (
-  evaluation: ReturnType<typeof evaluateAiGate>
+  evaluation: ReturnType<typeof evaluateAiGate>,
+  platform?: { exitCode: number; aligned: boolean; skipReason: string | null }
 ): EnterpriseAiGateCheckResult['result']['consistency_hint'] => {
-  if (!HOOK_STAGE_SET.has(evaluation.stage)) {
-    return {
-      comparable_with_hook_runner: true,
-      reason_code: null,
-      message: 'Stage is directly comparable with ai_gate_check semantics.',
-    };
-  }
-
   const hasRefreshableEvidenceViolation = evaluation.violations.some((violation) =>
     isHookRefreshableEvidenceCode(violation.code)
   );
@@ -72,6 +91,24 @@ const buildConsistencyHint = (
     };
   }
 
+  if (platform?.aligned) {
+    return {
+      comparable_with_hook_runner: true,
+      reason_code: null,
+      message:
+        `ai_gate_check ejecutó runPlatformGate después de leer la evidencia actual (exit_code=${platform.exitCode}); ` +
+        'alineación hook-like habilitada explícitamente para este stage.',
+    };
+  }
+
+  if (!HOOK_STAGE_SET.has(evaluation.stage)) {
+    return {
+      comparable_with_hook_runner: true,
+      reason_code: null,
+      message: 'Stage is directly comparable with ai_gate_check semantics.',
+    };
+  }
+
   return {
     comparable_with_hook_runner: true,
     reason_code: null,
@@ -118,7 +155,31 @@ const buildAutoFixes = (
   return fixes;
 };
 
-const buildMessage = (evaluation: ReturnType<typeof evaluateAiGate>): string => {
+const buildReasonCode = (evaluation: ReturnType<typeof evaluateAiGate>): string =>
+  evaluation.violations[0]?.code ?? 'AI_GATE_ALLOWED';
+
+const buildInstruction = (evaluation: ReturnType<typeof evaluateAiGate>): string =>
+  evaluation.allowed
+    ? 'Continúa con el stage actual manteniendo el vocabulario canónico de governance.'
+    : 'Corrige el bloqueante primario y vuelve a ejecutar ai_gate_check en el mismo stage.';
+
+const buildNextAction = (
+  evaluation: ReturnType<typeof evaluateAiGate>,
+  autoFixes: ReadonlyArray<string>
+): EnterpriseAiGateCheckResult['result']['next_action'] => ({
+  kind: 'info',
+  reason: buildReasonCode(evaluation),
+  message: autoFixes[0] ?? buildInstruction(evaluation),
+});
+
+const buildMessage = (
+  evaluation: ReturnType<typeof evaluateAiGate>,
+  platform?: { exitCode: number; skipReason: string | null }
+): string => {
+  if (platform && platform.exitCode !== 0) {
+    const suffix = platform.skipReason ? ` (${platform.skipReason})` : '';
+    return `🔴 runPlatformGate exit_code=${platform.exitCode}${suffix}.`;
+  }
   if (evaluation.allowed) {
     return `✅ Gate ${evaluation.stage} ALLOWED.`;
   }
@@ -129,6 +190,26 @@ const buildMessage = (evaluation: ReturnType<typeof evaluateAiGate>): string =>
   return `🔴 ${firstViolation.code}: ${firstViolation.message}`;
 };
 
+const resolveAiGateCheckMode = (): PlatformGateAlignment['mode'] => {
+  const raw = process.env.PUMUKI_MCP_AI_GATE_CHECK_MODE?.trim().toLowerCase();
+  return raw === 'full' || raw === 'aligned' ? 'full' : 'policy';
+};
+
+const toPlatformGateAlignment = (
+  mode: PlatformGateAlignment['mode'],
+  platform?: { exitCode: number; aligned: boolean; skipReason: string | null }
+): PlatformGateAlignment | undefined => {
+  if (mode !== 'full' || !platform) {
+    return undefined;
+  }
+  return {
+    mode,
+    exit_code: platform.exitCode,
+    aligned: platform.aligned,
+    skip_reason: platform.skipReason,
+  };
+};
+
 export const runEnterpriseAiGateCheck = (params: {
   repoRoot: string;
   stage: AiGateStage;
@@ -151,6 +232,8 @@ export const runEnterpriseAiGateCheck = (params: {
     : readSddLearningContext({
       repoRoot: params.repoRoot,
     });
+  const preWriteEnforcement = resolvePreWriteEnforcement();
+  const policyValidation = readLifecyclePolicyValidationSnapshot(params.repoRoot);
   const warnings = buildWarnings(evaluation);
   const autoFixes = buildAutoFixes(evaluation, learningContext);
   const message = buildMessage(evaluation);
@@ -166,6 +249,15 @@ export const runEnterpriseAiGateCheck = (params: {
       timestamp,
       branch,
       message,
+      reason_code: buildReasonCode(evaluation),
+      instruction: buildInstruction(evaluation),
+      prewrite_effective: {
+        mode: preWriteEnforcement.mode,
+        source: preWriteEnforcement.source,
+        blocking: preWriteEnforcement.blocking,
+        strict_policy: policyValidation.stages.PRE_WRITE.strict,
+      },
+      next_action: buildNextAction(evaluation, autoFixes),
       stage: evaluation.stage,
       policy: evaluation.policy,
       violations: evaluation.violations,
@@ -180,3 +272,95 @@ export const runEnterpriseAiGateCheck = (params: {
     },
   };
 };
+
+export const runEnterpriseAiGateCheckAsync = async (params: {
+  repoRoot: string;
+  stage: AiGateStage;
+  requireMcpReceipt?: boolean;
+}, dependencies: Partial<AiGateCheckDependencies> = {}): Promise<EnterpriseAiGateCheckResult> => {
+  const mode = resolveAiGateCheckMode();
+  const activeDependencies: AiGateCheckDependencies = {
+    ...defaultDependencies,
+    ...dependencies,
+  };
+  const evaluation = activeDependencies.evaluateAiGate({
+    repoRoot: params.repoRoot,
+    stage: params.stage,
+    requireMcpReceipt: params.requireMcpReceipt ?? false,
+  });
+
+  let platform:
+    | { exitCode: number; aligned: boolean; skipReason: string | null }
+    | undefined;
+  if (mode === 'full') {
+    platform = await activeDependencies.runMcpAlignedPlatformGate({
+      repoRoot: params.repoRoot,
+      stage: params.stage,
+    });
+  }
+
+  const platformBlocks = Boolean(platform && platform.exitCode !== 0);
+  const allowed = evaluation.allowed && !platformBlocks;
+  const status: 'ALLOWED' | 'BLOCKED' = allowed ? 'ALLOWED' : 'BLOCKED';
+  const violations = platformBlocks && platform
+    ? [
+      ...evaluation.violations,
+      {
+        code: 'PLATFORM_GATE_EXIT_NON_ZERO',
+        message:
+          `runPlatformGate devolvió exit_code=${platform.exitCode}` +
+          (platform.skipReason ? ` (${platform.skipReason})` : ''),
+        severity: 'ERROR' as const,
+      },
+    ]
+    : evaluation.violations;
+  const branch = evaluation.repo_state.git.branch;
+  const timestamp = evaluation.evidence.source.generated_at;
+  const learningContextFeature = resolveLearningContextExperimentalFeature();
+  const learningContext = learningContextFeature.mode === 'off'
+    ? null
+    : readSddLearningContext({
+      repoRoot: params.repoRoot,
+    });
+  const evaluationForHints = { ...evaluation, allowed, status, violations };
+  const warnings = buildWarnings(evaluationForHints);
+  const autoFixes = buildAutoFixes(evaluationForHints, learningContext);
+  const message = buildMessage(evaluationForHints, platform);
+  const preWriteEnforcement = resolvePreWriteEnforcement();
+  const policyValidation = readLifecyclePolicyValidationSnapshot(params.repoRoot);
+
+  return {
+    tool: 'ai_gate_check',
+    dryRun: true,
+    executed: true,
+    success: allowed,
+    result: {
+      allowed,
+      status,
+      timestamp,
+      branch,
+      message,
+      reason_code: buildReasonCode(evaluationForHints),
+      instruction: buildInstruction(evaluationForHints),
+      prewrite_effective: {
+        mode: preWriteEnforcement.mode,
+        source: preWriteEnforcement.source,
+        blocking: preWriteEnforcement.blocking,
+        strict_policy: policyValidation.stages.PRE_WRITE.strict,
+      },
+      next_action: buildNextAction(evaluationForHints, autoFixes),
+      stage: evaluation.stage,
+      policy: evaluation.policy,
+      violations,
+      warnings,
+      auto_fixes: autoFixes,
+      learning_context: learningContext,
+      evidence: evaluation.evidence,
+      mcp_receipt: evaluation.mcp_receipt,
+      skills_contract: evaluation.skills_contract,
+      repo_state: evaluation.repo_state,
+      consistency_hint: buildConsistencyHint(evaluationForHints, platform),
+      platform_gate_alignment: toPlatformGateAlignment(mode, platform),
+    },
+  };
+};