pumuki 6.3.73 → 6.3.76

package/integrations/lifecycle/governanceObservationSnapshot.ts

@@ -1,6 +1,8 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { readEvidenceResult } from '../evidence/readEvidence';
+import { readRepoTrackingState } from '../evidence/trackingContract';
+import type { RepoTrackingState } from '../evidence/schema';
 import { readSddStatus } from '../sdd';
 import type { SddStatusPayload } from '../sdd/types';
 import type { LifecycleExperimentalFeaturesSnapshot } from './experimentalFeaturesSnapshot';
@@ -57,6 +59,7 @@ export type GovernanceObservationSnapshot = {
     on_protected_branch_hint: boolean;
   };
   contract_surface: GovernanceContractSurface;
+  tracking: RepoTrackingState;
   attention_codes: ReadonlyArray<string>;
   governance_effective: 'green' | 'attention' | 'blocked';
   agent_bootstrap_hints: ReadonlyArray<string>;
@@ -142,7 +145,8 @@ const summarizeEvidence = (repoRoot: string): GovernanceEvidenceSummary => {
 const buildHints = (
   surface: GovernanceContractSurface,
   branch: string | null,
-  protectedBranchHint: boolean
+  protectedBranchHint: boolean,
+  tracking: RepoTrackingState
 ): string[] => {
   const hints: string[] = [];
   if (surface.agents_md) {
@@ -157,6 +161,17 @@ const buildHints = (
   if (protectedBranchHint && branch) {
     hints.push(`La rama "${branch}" cae en el set protegido por defecto: usa feature/* o refactor/*.`);
   }
+  if (tracking.conflict) {
+    hints.push('Tracking canónico en conflicto: AGENTS.md y los README del repo no apuntan al mismo MD.');
+  }
+  if (tracking.enforced && !tracking.canonical_present) {
+    hints.push(`Falta el tracking canónico declarado (${tracking.canonical_path ?? 'sin resolver'}).`);
+  }
+  if (tracking.enforced && tracking.single_in_progress_valid === false) {
+    hints.push(
+      `El tracking canónico debe dejar exactamente una 🚧 (actual=${tracking.in_progress_count ?? 'n/a'}).`
+    );
+  }
   hints.push('SDD/OpenSpec: usa PUMUKI_EXPERIMENTAL_SDD=advisory|strict cuando el loop SDD esté activo.');
   hints.push('WARN-as-BLOCK: activa PUMUKI_ENTERPRISE_STRICT_WARN_AS_BLOCK=1 si el repo exige promoción dura.');
   return hints;
@@ -176,6 +191,7 @@ export const readGovernanceObservationSnapshot = (params: {
   const branch = readCurrentBranch(git, repoRoot);
   const onProtected = typeof branch === 'string' && DEFAULT_PROTECTED_BRANCHES.has(branch.trim().toLowerCase());
   const surface = buildContractSurface(repoRoot);
+  const tracking = readRepoTrackingState(repoRoot);
   const warnAsBlock = truthyEnv(process.env.PUMUKI_ENTERPRISE_STRICT_WARN_AS_BLOCK);
 
   const attention: string[] = [];
@@ -209,6 +225,15 @@ export const readGovernanceObservationSnapshot = (params: {
   if (onProtected) {
     attention.push('GITFLOW_PROTECTED_BRANCH_CONTEXT');
   }
+  if (tracking.conflict) {
+    attention.push('TRACKING_CANONICAL_SOURCE_CONFLICT');
+  }
+  if (tracking.enforced && !tracking.canonical_present) {
+    attention.push('TRACKING_CANONICAL_FILE_MISSING');
+  }
+  if (tracking.enforced && tracking.single_in_progress_valid === false) {
+    attention.push('TRACKING_CANONICAL_IN_PROGRESS_INVALID');
+  }
 
   let governanceEffective: GovernanceObservationSnapshot['governance_effective'] = 'green';
   if (
@@ -248,9 +273,10 @@ export const readGovernanceObservationSnapshot = (params: {
       on_protected_branch_hint: onProtected,
     },
     contract_surface: surface,
+    tracking,
     attention_codes: attention,
     governance_effective: governanceEffective,
-    agent_bootstrap_hints: buildHints(surface, branch, onProtected),
+    agent_bootstrap_hints: buildHints(surface, branch, onProtected, tracking),
   };
 };
 
@@ -263,6 +289,7 @@ export const buildGovernanceObservationSummaryLines = (
     `SDD: env=${snapshot.sdd.experimental_raw ?? '(unset)'} effective=${snapshot.sdd.effective_mode} session_active=${snapshot.sdd_session.active} session_valid=${snapshot.sdd_session.valid} change=${snapshot.sdd_session.change_id ?? 'none'}`,
     `Evidence: readable=${snapshot.evidence.readable} stage=${snapshot.evidence.snapshot_stage ?? 'n/a'} outcome=${snapshot.evidence.snapshot_outcome ?? 'n/a'} ai_gate=${snapshot.evidence.ai_gate_status ?? 'n/a'} findings=${snapshot.evidence.findings_count ?? 'n/a'}`,
     `GitFlow: branch=${snapshot.git.current_branch ?? 'unknown'} protected_hint=${snapshot.git.on_protected_branch_hint ? 'yes' : 'no'}`,
+    `Tracking: enforced=${snapshot.tracking.enforced} canonical=${snapshot.tracking.canonical_path ?? 'none'} present=${snapshot.tracking.canonical_present} single_active=${snapshot.tracking.single_in_progress_valid ?? 'n/a'} count=${snapshot.tracking.in_progress_count ?? 'n/a'} conflict=${snapshot.tracking.conflict}`,
     `Policy strict: PRE_WRITE=${snapshot.policy_strict.pre_write} PRE_COMMIT=${snapshot.policy_strict.pre_commit} PRE_PUSH=${snapshot.policy_strict.pre_push} CI=${snapshot.policy_strict.ci}`,
   ];
   if (snapshot.attention_codes.length > 0) {

package/integrations/lifecycle/index.ts

@@ -1,6 +1,4 @@
 export { runLifecycleDoctor, doctorHasBlockingIssues } from './doctor';
-export { runLifecycleAudit } from './audit';
-export type { LifecycleAuditResult, LifecycleAuditStage } from './audit';
 export { runLifecycleInstall } from './install';
 export { runLifecycleUninstall } from './uninstall';
 export { runLifecycleRemove } from './remove';

package/integrations/lifecycle/install.ts

@@ -13,6 +13,7 @@ import { createEmptyEvaluationMetrics } from '../evidence/evaluationMetrics';
 import { readOpenSpecManagedArtifacts, writeLifecycleState } from './state';
 import { ensureRuntimeArtifactsIgnored } from './artifacts';
 import { runLifecycleAdapterInstall } from './adapter';
+import { writeLifecycleBootstrapManifest } from './bootstrapManifest';
 
 export type LifecycleInstallResult = {
   repoRoot: string;
@@ -20,6 +21,10 @@ export type LifecycleInstallResult = {
   changedHooks: ReadonlyArray<string>;
   openSpecBootstrap?: OpenSpecBootstrapResult;
   degradedDoctorBypass?: boolean;
+  bootstrapManifest: {
+    path: string;
+    changed: boolean;
+  };
 };
 
 const shouldBootstrapEvidence = (repoRoot: string): boolean =>
@@ -103,12 +108,20 @@ export const runLifecycleInstall = (params?: {
         openSpecManagedArtifacts: priorArtifacts.length > 0 ? priorArtifacts : undefined,
       });
       ensureRepoBaselineAdapter(report.repoRoot);
+      const bootstrapManifest = writeLifecycleBootstrapManifest({
+        git,
+        repoRoot: report.repoRoot,
+      });
       return {
         repoRoot: report.repoRoot,
         version,
         changedHooks,
         openSpecBootstrap: undefined,
         degradedDoctorBypass: true,
+        bootstrapManifest: {
+          path: bootstrapManifest.path,
+          changed: bootstrapManifest.changed,
+        },
       };
     }
     const renderedIssues = report.issues.map((issue) => `- [${issue.severity}] ${issue.message}`).join('\n');
@@ -142,11 +155,19 @@ export const runLifecycleInstall = (params?: {
     openSpecManagedArtifacts: Array.from(mergedOpenSpecArtifacts),
   });
   ensureRepoBaselineAdapter(report.repoRoot);
+  const bootstrapManifest = writeLifecycleBootstrapManifest({
+    git,
+    repoRoot: report.repoRoot,
+  });
 
   return {
     repoRoot: report.repoRoot,
     version,
     changedHooks,
     openSpecBootstrap,
+    bootstrapManifest: {
+      path: bootstrapManifest.path,
+      changed: bootstrapManifest.changed,
+    },
   };
 };

package/integrations/lifecycle/state.ts

@@ -49,10 +49,17 @@ export const writeLifecycleState = (params: {
   openSpecManagedArtifacts?: ReadonlyArray<string>;
 }): void => {
   const { git, repoRoot, version } = params;
+  const existingInstalledAt = git.localConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt);
   git.applyLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installed, 'true');
   git.applyLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version, version);
   git.applyLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks, PUMUKI_MANAGED_HOOKS.join(','));
-  git.applyLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt, new Date().toISOString());
+  git.applyLocalConfig(
+    repoRoot,
+    PUMUKI_CONFIG_KEYS.installedAt,
+    typeof existingInstalledAt === 'string' && existingInstalledAt.trim().length > 0
+      ? existingInstalledAt
+      : new Date().toISOString()
+  );
   if (params.openSpecManagedArtifacts) {
     const serialized = serializeManagedArtifacts(params.openSpecManagedArtifacts);
     if (serialized) {

package/integrations/mcp/aiGateCheck.ts

@@ -2,9 +2,17 @@ import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
 import { resolveRemediationHintForViolationCode } from '../gate/remediationCatalog';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
 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;
@@ -31,6 +39,7 @@ export type EnterpriseAiGateCheckResult = {
       reason_code: 'HOOK_RUNNER_CAN_REFRESH_EVIDENCE' | null;
       message: string;
     };
+    platform_gate_alignment?: PlatformGateAlignment;
   };
 };
 
@@ -41,23 +50,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 +76,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 +140,14 @@ const buildAutoFixes = (
   return fixes;
 };
 
-const buildMessage = (evaluation: ReturnType<typeof evaluateAiGate>): string => {
+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 +158,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;
@@ -180,3 +229,84 @@ 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);
+
+  return {
+    tool: 'ai_gate_check',
+    dryRun: true,
+    executed: true,
+    success: allowed,
+    result: {
+      allowed,
+      status,
+      timestamp,
+      branch,
+      message,
+      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),
+    },
+  };
+};

package/integrations/mcp/alignedPlatformGate.ts

@@ -0,0 +1,232 @@
+import type { AiGateStage } from '../gate/evaluateAiGate';
+import { resolvePolicyForStage } from '../gate/stagePolicies';
+import type { SddDecision } from '../sdd';
+import { GitService } from '../git/GitService';
+import { runPlatformGate } from '../git/runPlatformGate';
+import type { GateScope } from '../git/runPlatformGateFacts';
+import { readMcpPrePushStdin } from './readMcpPrePushStdin';
+
+const ZERO_HASH = /^0+$/;
+
+const runGit = (repoRoot: string, args: ReadonlyArray<string>): string | null => {
+  try {
+    return new GitService().runGit(args, repoRoot).trim();
+  } catch {
+    return null;
+  }
+};
+
+const resolveUpstreamRefInRepo = (repoRoot: string): string | null =>
+  runGit(repoRoot, ['rev-parse', '@{u}']);
+
+const resolveHeadOidInRepo = (repoRoot: string): string | null =>
+  runGit(repoRoot, ['rev-parse', 'HEAD']);
+
+const resolveCiBaseRefInRepo = (repoRoot: string): string => {
+  const fromEnv = process.env.GITHUB_BASE_REF?.trim();
+  if (fromEnv) {
+    if (runGit(repoRoot, ['rev-parse', '--verify', fromEnv])) {
+      return fromEnv;
+    }
+    const remoteRef = `origin/${fromEnv}`;
+    if (runGit(repoRoot, ['rev-parse', '--verify', remoteRef])) {
+      return remoteRef;
+    }
+  }
+
+  for (const candidate of ['origin/main', 'main', 'HEAD']) {
+    if (runGit(repoRoot, ['rev-parse', '--verify', candidate])) {
+      return candidate;
+    }
+  }
+
+  return 'HEAD';
+};
+
+const resolvePrePushBootstrapBaseRefInRepo = (repoRoot: string): string => {
+  const candidates = ['origin/develop', 'develop', resolveCiBaseRefInRepo(repoRoot)];
+  for (const candidate of candidates) {
+    if (runGit(repoRoot, ['rev-parse', '--verify', candidate])) {
+      return candidate;
+    }
+  }
+
+  return 'HEAD';
+};
+
+const shouldAllowBootstrapPrePush = (rawInput: string): boolean => {
+  const lines = rawInput
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  for (const line of lines) {
+    const [localRef, localOid, remoteRef, remoteOid] = line.split(/\s+/);
+    if (!localRef || !localOid || !remoteRef || !remoteOid) {
+      continue;
+    }
+    const localIsBranch = localRef.startsWith('refs/heads/');
+    const remoteIsBranch = remoteRef.startsWith('refs/heads/');
+    const localIsDeletion = ZERO_HASH.test(localOid);
+    const remoteIsNewBranch = ZERO_HASH.test(remoteOid);
+
+    if (localIsBranch && remoteIsBranch && !localIsDeletion && remoteIsNewBranch) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const resolveExplicitPrePushRange = (
+  rawInput: string
+): { fromRef: string; toRef: string } | undefined => {
+  const lines = rawInput
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  const eligibleRanges = lines
+    .map((line) => {
+      const [localRef, localOid, remoteRef, remoteOid] = line.split(/\s+/);
+      if (!localRef || !localOid || !remoteRef || !remoteOid) {
+        return undefined;
+      }
+      const localIsDeletion = ZERO_HASH.test(localOid);
+      const remoteIsNewBranch = ZERO_HASH.test(remoteOid);
+      if (localIsDeletion || remoteIsNewBranch) {
+        return undefined;
+      }
+      return {
+        fromRef: remoteOid,
+        toRef: localOid,
+      };
+    })
+    .filter((value): value is { fromRef: string; toRef: string } => Boolean(value));
+
+  if (eligibleRanges.length !== 1) {
+    return undefined;
+  }
+
+  return eligibleRanges[0];
+};
+
+type PrePushScopeResolution =
+  | { kind: 'scope'; scope: GateScope; sddDecisionOverride?: Pick<SddDecision, 'allowed' | 'code' | 'message'> }
+  | { kind: 'upstream_missing' };
+
+const resolvePrePushScopeForMcp = (params: { repoRoot: string }): PrePushScopeResolution => {
+  const prePushInput = readMcpPrePushStdin();
+  const upstreamRef = resolveUpstreamRefInRepo(params.repoRoot);
+  if (!upstreamRef) {
+    const bootstrapBaseRef = resolvePrePushBootstrapBaseRefInRepo(params.repoRoot);
+    const bootstrapByPrePushStdIn = shouldAllowBootstrapPrePush(prePushInput);
+    const bootstrapByFallbackBase = !bootstrapByPrePushStdIn && bootstrapBaseRef !== 'HEAD';
+    const manualInvocationFallback =
+      !bootstrapByPrePushStdIn &&
+      !bootstrapByFallbackBase &&
+      prePushInput.trim().length === 0;
+    if (bootstrapByPrePushStdIn || bootstrapByFallbackBase) {
+      return {
+        kind: 'scope',
+        scope: {
+          kind: 'range',
+          fromRef: bootstrapBaseRef,
+          toRef: 'HEAD',
+        },
+      };
+    }
+    if (manualInvocationFallback) {
+      return { kind: 'scope', scope: { kind: 'workingTree' } };
+    }
+    return { kind: 'upstream_missing' };
+  }
+  const explicitPrePushRange = resolveExplicitPrePushRange(prePushInput);
+  const prePushFromRef = explicitPrePushRange?.fromRef ?? upstreamRef;
+  const prePushToRef = explicitPrePushRange?.toRef ?? 'HEAD';
+  const headOid = resolveHeadOidInRepo(params.repoRoot);
+  const sddDecisionOverride =
+    explicitPrePushRange && headOid && explicitPrePushRange.toRef !== headOid
+      ? ({
+        allowed: true,
+        code: 'ALLOWED',
+        message:
+          `SDD enforcement suspended for PRE_PUSH historical publish targeting ${explicitPrePushRange.toRef.slice(0, 12)} ` +
+          `instead of current HEAD ${headOid.slice(0, 12)}.`,
+      } as Pick<SddDecision, 'allowed' | 'code' | 'message'>)
+      : undefined;
+  return {
+    kind: 'scope',
+    scope: {
+      kind: 'range',
+      fromRef: prePushFromRef,
+      toRef: prePushToRef,
+    },
+    sddDecisionOverride,
+  };
+};
+
+type RunAlignedParams = {
+  repoRoot: string;
+  stage: AiGateStage;
+};
+
+export const runMcpAlignedPlatformGate = async (
+  params: RunAlignedParams
+): Promise<{ exitCode: number; aligned: boolean; skipReason: string | null }> => {
+  const git = new GitService();
+  const resolved = resolvePolicyForStage(params.stage, params.repoRoot);
+  if (params.stage === 'PRE_WRITE') {
+    const exitCode = await runPlatformGate({
+      policy: resolved.policy,
+      policyTrace: resolved.trace,
+      scope: { kind: 'workingTree' },
+      silent: true,
+      services: { git },
+    });
+    return { exitCode, aligned: true, skipReason: null };
+  }
+  if (params.stage === 'PRE_COMMIT') {
+    const exitCode = await runPlatformGate({
+      policy: resolved.policy,
+      policyTrace: resolved.trace,
+      scope: { kind: 'staged' },
+      silent: true,
+      services: { git },
+    });
+    return { exitCode, aligned: true, skipReason: null };
+  }
+  if (params.stage === 'CI') {
+    const ciBaseRef = resolveCiBaseRefInRepo(params.repoRoot);
+    const exitCode = await runPlatformGate({
+      policy: resolved.policy,
+      policyTrace: resolved.trace,
+      scope: {
+        kind: 'range',
+        fromRef: ciBaseRef,
+        toRef: 'HEAD',
+      },
+      silent: true,
+      services: { git },
+    });
+    return { exitCode, aligned: true, skipReason: null };
+  }
+  if (params.stage === 'PRE_PUSH') {
+    const scopeResolution = resolvePrePushScopeForMcp({ repoRoot: params.repoRoot });
+    if (scopeResolution.kind === 'upstream_missing') {
+      return { exitCode: 1, aligned: false, skipReason: 'PRE_PUSH_UPSTREAM_MISSING' };
+    }
+    const exitCode = await runPlatformGate({
+      policy: resolved.policy,
+      policyTrace: resolved.trace,
+      scope: scopeResolution.scope,
+      silent: true,
+      services: { git },
+      ...(scopeResolution.sddDecisionOverride
+        ? { sddDecisionOverride: scopeResolution.sddDecisionOverride }
+        : {}),
+    });
+    return { exitCode, aligned: true, skipReason: null };
+  }
+  throw new Error(`Unsupported MCP aligned stage: ${String(params.stage)}`);
+};

package/integrations/mcp/autoExecuteAiStart.ts

@@ -54,7 +54,10 @@ const confidenceFromViolation = (violationCode: string | null): number => {
   if (isEvidenceCode(violationCode)) {
     return 65;
   }
-  if (violationCode === 'GITFLOW_PROTECTED_BRANCH') {
+  if (
+    violationCode === 'GITFLOW_PROTECTED_BRANCH'
+    || violationCode === 'GITFLOW_BRANCH_NAMING_INVALID'
+  ) {
     return 40;
   }
   return 50;
@@ -67,6 +70,8 @@ const normalizeGovernanceCatalogCode = (code: string): string => {
       return 'EVIDENCE_INVALID_OR_CHAIN';
     case 'GITFLOW_PROTECTED_BRANCH':
       return 'GITFLOW_PROTECTED_BRANCH_CONTEXT';
+    case 'GITFLOW_BRANCH_NAMING_INVALID':
+      return 'GITFLOW_BRANCH_NAMING_INVALID_CONTEXT';
     default:
       return code;
   }