pumuki 6.3.70 → 6.3.72

package/integrations/git/filterFactsByPathPrefixes.ts

@@ -0,0 +1,61 @@
+import type { Fact } from '../../core/facts/Fact';
+
+const normalizePath = (value: string): string => value.replace(/\\/g, '/').replace(/^\/+/, '');
+
+export const resolveGateScopePathPrefixesFromEnv = (): string[] => {
+  const raw = process.env.PUMUKI_GATE_SCOPE_PATH_PREFIXES?.trim();
+  if (!raw) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      raw
+        .split(/[,;]/)
+        .map((segment) => normalizePath(segment.trim()))
+        .filter((segment) => segment.length > 0)
+    )
+  ).sort((a, b) => a.localeCompare(b));
+};
+
+const primaryPathForFact = (fact: Fact): string | null => {
+  if (fact.kind === 'FileContent' || fact.kind === 'FileChange') {
+    return fact.path;
+  }
+  if (fact.kind === 'Heuristic') {
+    return fact.filePath ?? null;
+  }
+  if (fact.kind === 'Dependency') {
+    return fact.from;
+  }
+  return null;
+};
+
+const pathMatchesAnyPrefix = (path: string, prefixes: ReadonlyArray<string>): boolean => {
+  const normalized = normalizePath(path);
+  for (const prefix of prefixes) {
+    if (normalized === prefix) {
+      return true;
+    }
+    const withSlash = prefix.endsWith('/') ? prefix : `${prefix}/`;
+    if (normalized.startsWith(withSlash)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+export const filterFactsByPathPrefixes = (
+  facts: ReadonlyArray<Fact>,
+  prefixes: ReadonlyArray<string>
+): Fact[] => {
+  if (prefixes.length === 0) {
+    return [...facts];
+  }
+  return facts.filter((fact) => {
+    const primary = primaryPathForFact(fact);
+    if (primary === null) {
+      return true;
+    }
+    return pathMatchesAnyPrefix(primary, prefixes);
+  });
+};

package/integrations/git/runPlatformGate.ts

@@ -35,6 +35,10 @@ import type { TddBddSnapshot } from '../tdd/types';
 import { resolveSkillsEnforcement } from '../policy/skillsEnforcement';
 import { applyTddBddEnforcement } from '../policy/tddBddEnforcement';
 import { collectAiGateRepoPolicyFindings } from './aiGateRepoPolicyFindings';
+import {
+  filterFactsByPathPrefixes,
+  resolveGateScopePathPrefixesFromEnv,
+} from './filterFactsByPathPrefixes';
 
 export type OperationalMemoryShadowRecommendation = {
   recommendedOutcome: 'ALLOW' | 'WARN' | 'BLOCK';
@@ -911,10 +915,14 @@ export async function runPlatformGate(params: {
     }
   }
 
-  const facts = await dependencies.resolveFactsForGateScope({
-    scope: params.scope,
-    git,
-  });
+  const gateScopePathPrefixes = resolveGateScopePathPrefixesFromEnv();
+  const facts = filterFactsByPathPrefixes(
+    await dependencies.resolveFactsForGateScope({
+      scope: params.scope,
+      git,
+    }),
+    gateScopePathPrefixes
+  );
   const stagedPaths = collectStagedPaths(git, repoRoot);
   const factsForPlatformEvaluation = shouldAugmentStagedSkillsContractFactsWithRepoFacts({
     scope: params.scope,

package/integrations/git/runPlatformGateFacts.ts

@@ -19,6 +19,10 @@ export type GateScope =
     kind: 'workingTree';
     extensions?: string[];
   }
+  | {
+    kind: 'unstaged';
+    extensions?: string[];
+  }
   | {
     kind: 'range';
     fromRef: string;
@@ -66,6 +70,9 @@ export const resolveFactsForGateScope = async (params: {
   if (params.scope.kind === 'workingTree') {
     return params.git.getStagedAndUnstagedFacts(extensions);
   }
+  if (params.scope.kind === 'unstaged') {
+    return params.git.getUnstagedFacts(extensions);
+  }
 
   return getFactsForCommitRange({
     fromRef: params.scope.fromRef,

package/integrations/git/stageRunners.ts

@@ -20,7 +20,9 @@ import {
 } from '../notifications/emitAuditSummaryNotification';
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildEvidenceOperationalHints } from '../evidence/operationalHints';
 import { readEvidence, readEvidenceResult } from '../evidence/readEvidence';
+import { writeEvidence } from '../evidence/writeEvidence';
 import type { EvidenceReadResult } from '../evidence/readEvidence';
 import type { SnapshotFinding } from '../evidence/schema';
 import { ensureRuntimeArtifactsIgnored } from '../lifecycle/artifacts';
@@ -31,6 +33,10 @@ import {
   resolveGitAtomicityEnforcement,
   type GitAtomicityEnforcementResolution,
 } from '../policy/gitAtomicityEnforcement';
+import {
+  DEFAULT_GATE_REMEDIATION as DEFAULT_BLOCKED_REMEDIATION,
+  REMEDIATION_HINT_BY_CODE as BLOCKED_REMEDIATION_BY_CODE,
+} from '../gate/remediationCatalog';
 
 const PRE_PUSH_UPSTREAM_REQUIRED_MESSAGE =
   'pumuki pre-push blocked: branch has no upstream tracking reference. Configure upstream first (for example: git push --set-upstream origin <branch>) and retry.';
@@ -40,39 +46,43 @@ const PRE_PUSH_MANUAL_FALLBACK_MESSAGE =
   '[pumuki][pre-push] branch has no upstream and stdin is empty; using working-tree fallback scope.';
 const PRE_PUSH_UPSTREAM_MISALIGNED_AHEAD_THRESHOLD = 5;
 
+const isTruthyEnvFlag = (value?: string): boolean => {
+  if (!value) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+};
+
+const isDocumentationOnlyStagedPath = (relativePath: string): boolean => {
+  const normalized = relativePath.replace(/\\/g, '/').trim();
+  if (normalized.length === 0) {
+    return false;
+  }
+  return /\.(md|mdx)$/i.test(normalized);
+};
+
+const shouldSkipRestagingTrackedEvidenceForDocumentationOnlyScope = (params: {
+  listStagedIndexPaths: (repoRoot: string) => ReadonlyArray<string>;
+  repoRoot: string;
+}): boolean => {
+  if (isTruthyEnvFlag(process.env.PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE)) {
+    return false;
+  }
+  const paths = params.listStagedIndexPaths(params.repoRoot).filter(
+    (p) => p !== '.ai_evidence.json' && p !== '.AI_EVIDENCE.json'
+  );
+  if (paths.length === 0) {
+    return true;
+  }
+  return paths.every(isDocumentationOnlyStagedPath);
+};
+
 const PRE_COMMIT_EVIDENCE_MAX_AGE_SECONDS = 900;
 const PRE_PUSH_EVIDENCE_MAX_AGE_SECONDS = 1800;
 const HOOK_GATE_PROGRESS_REMINDER_MS = 2000;
-const DEFAULT_BLOCKED_REMEDIATION = 'Corrige la causa del bloqueo y vuelve a ejecutar el gate.';
 const EVIDENCE_FILE_PATH = '.ai_evidence.json';
 
-const BLOCKED_REMEDIATION_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'Regenera .ai_evidence.json ejecutando una auditoría.',
-  EVIDENCE_INVALID: 'Corrige/regenera .ai_evidence.json y vuelve a ejecutar el gate.',
-  EVIDENCE_CHAIN_INVALID: 'Regenera evidencia para restaurar la cadena criptográfica.',
-  EVIDENCE_STAGE_SYNC_FAILED:
-    'Sincroniza la evidencia trackeada y reintenta: git add -- .ai_evidence.json && git commit --amend --no-edit',
-  EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
-  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este mismo repositorio.',
-  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual y reintenta.',
-  EVIDENCE_RULES_COVERAGE_MISSING: 'Ejecuta auditoría completa para recalcular rules_coverage.',
-  EVIDENCE_RULES_COVERAGE_INCOMPLETE: 'Asegura coverage_ratio=1 y unevaluated=0.',
-  ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH:
-    'Reconcilia policy/skills y reintenta PRE_COMMIT: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki-pre-commit',
-  EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:
-    'Reconcilia policy/skills y revalida PRE_WRITE: npx --yes --package pumuki@latest pumuki policy reconcile --strict --json && npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json',
-  GITFLOW_PROTECTED_BRANCH: 'Trabaja en feature/* y evita ramas protegidas.',
-  EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT:
-    'Reduce archivos staged/unstaged por debajo del umbral (o ajusta PUMUKI_PREWRITE_WORKTREE_*); divide el trabajo en commits más pequeños.',
-  EVIDENCE_PREWRITE_WORKTREE_WARN:
-    'El worktree supera el umbral de aviso; reduce alcance antes del siguiente commit/push.',
-  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta: git push --set-upstream origin <branch>',
-  PRE_PUSH_UPSTREAM_MISALIGNED:
-    'Alinea upstream con la rama actual: git branch --unset-upstream && git push --set-upstream origin <branch>',
-  MANIFEST_MUTATION_DETECTED:
-    'Los hooks/gates no deben modificar manifests. Revisa wiring y ejecuta upgrade explícito solo cuando aplique (por ejemplo: pumuki update --latest).',
-};
-
 const HOOK_POLICY_RECONCILE_CODES = new Set<string>([
   'SKILLS_PLATFORM_COVERAGE_INCOMPLETE_HIGH',
   'SKILLS_SCOPE_COMPLIANCE_INCOMPLETE_HIGH',
@@ -123,6 +133,7 @@ type StageRunnerDependencies = {
   ensureRuntimeArtifactsIgnored: (repoRoot: string) => void;
   runPolicyReconcile: typeof runPolicyReconcile;
   isPathTracked: (repoRoot: string, relativePath: string) => boolean;
+  listStagedIndexPaths: (repoRoot: string) => ReadonlyArray<string>;
   stagePath: (repoRoot: string, relativePath: string) => void;
   resolveHeadOid: (repoRoot: string) => string | null;
   resolveGitAtomicityEnforcement: () => GitAtomicityEnforcementResolution;
@@ -202,6 +213,13 @@ const defaultDependencies: StageRunnerDependencies = {
       return false;
     }
   },
+  listStagedIndexPaths: (repoRoot) => {
+    const raw = new GitService().runGit(['diff', '--cached', '--name-only'], repoRoot);
+    return raw
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  },
   stagePath: (repoRoot, relativePath) => {
     new GitService().runGit(['add', '--', relativePath], repoRoot);
   },
@@ -489,6 +507,26 @@ const runHookGateWithPolicyRetry = async (params: {
   }
 };
 
+const patchOperationalHintsAfterDocumentationOnlyEvidenceSync = (repoRoot: string): void => {
+  const evidenceRead = readEvidenceResult(repoRoot);
+  if (evidenceRead.kind !== 'valid') {
+    return;
+  }
+  const evidence = evidenceRead.evidence;
+  const hints = buildEvidenceOperationalHints({
+    stage: evidence.snapshot.stage,
+    outcome: evidence.snapshot.outcome,
+    findings: evidence.snapshot.findings,
+    rulesCoverage: evidence.snapshot.rules_coverage,
+    evaluationMetrics: evidence.snapshot.evaluation_metrics,
+    extra: {
+      requires_second_pass: true,
+      second_pass_reason: 'tracked_evidence_refreshed_on_disk_not_staged_documentation_only_commit',
+    },
+  });
+  writeEvidence({ ...evidence, operational_hints: hints }, { repoRoot });
+};
+
 const syncTrackedEvidenceAfterSuccessfulPreCommit = (params: {
   dependencies: StageRunnerDependencies;
   repoRoot: string;
@@ -500,6 +538,22 @@ const syncTrackedEvidenceAfterSuccessfulPreCommit = (params: {
   if (!params.dependencies.isPathTracked(params.repoRoot, EVIDENCE_FILE_PATH)) {
     return false;
   }
+  if (
+    shouldSkipRestagingTrackedEvidenceForDocumentationOnlyScope({
+      repoRoot: params.repoRoot,
+      listStagedIndexPaths: params.dependencies.listStagedIndexPaths,
+    })
+  ) {
+    if (!params.dependencies.isQuietMode()) {
+      process.stderr.write(
+        `[pumuki][evidence-sync] tracked ${EVIDENCE_FILE_PATH} updated on disk but not auto-staged (documentation-only staged paths: *.md / *.mdx). ` +
+          `Include in this commit if needed: git add -- ${EVIDENCE_FILE_PATH}. ` +
+          `Force previous behavior: PUMUKI_PRE_COMMIT_ALWAYS_RESTAGE_TRACKED_EVIDENCE=1\n`
+      );
+    }
+    patchOperationalHintsAfterDocumentationOnlyEvidenceSync(params.repoRoot);
+    return false;
+  }
   try {
     params.dependencies.stagePath(params.repoRoot, EVIDENCE_FILE_PATH);
     return false;

package/integrations/lifecycle/cli.ts

@@ -5,6 +5,7 @@ import { runPlatformGate } from '../git/runPlatformGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import {
   doctorHasBlockingIssues,
+  doctorHasParityMismatch,
   runLifecycleDoctor,
   type LifecycleDoctorReport,
 } from './doctor';
@@ -115,6 +116,7 @@ export type ParsedArgs = {
   installMcpAgent?: AdapterAgent;
   remoteChecks?: boolean;
   doctorDeep?: boolean;
+  doctorParity?: boolean;
   sddCommand?: SddCommand;
   loopCommand?: LoopCommand;
   loopSessionId?: string;
@@ -180,7 +182,7 @@ Pumuki lifecycle commands:
   pumuki uninstall [--purge-artifacts]
   pumuki remove
   pumuki update [--latest|--spec=<package-spec>]
-  pumuki doctor [--remote-checks] [--deep] [--json]
+  pumuki doctor [--remote-checks] [--deep] [--parity] [--json]
   pumuki status [--json] [--remote-checks]
   pumuki watch [--stage=PRE_COMMIT|PRE_PUSH|CI] [--scope=workingTree|staged|repoAndStaged|repo] [--severity=critical|high|medium|low] [--interval-ms=<n>] [--notify-cooldown-ms=<n>] [--no-notify] [--once|--iterations=<n>] [--json]
   pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
@@ -567,6 +569,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let installMcpAgent: ParsedArgs['installMcpAgent'];
   let remoteChecks = false;
   let doctorDeep = false;
+  let doctorParity = false;
   let watchStage: ParsedArgs['watchStage'];
   let watchScope: ParsedArgs['watchScope'];
   let watchIntervalMs: ParsedArgs['watchIntervalMs'];
@@ -1395,6 +1398,10 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
       doctorDeep = true;
       continue;
     }
+    if (arg === '--parity') {
+      doctorParity = true;
+      continue;
+    }
     if (arg === '--purge-artifacts') {
       purgeArtifacts = true;
       continue;
@@ -1417,6 +1424,9 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   if (doctorDeep && commandRaw !== 'doctor') {
     throw new Error(`--deep is only supported with "pumuki doctor".\n\n${HELP_TEXT}`);
   }
+  if (doctorParity && commandRaw !== 'doctor') {
+    throw new Error(`--parity is only supported with "pumuki doctor".\n\n${HELP_TEXT}`);
+  }
   if (commandRaw !== 'bootstrap' && bootstrapEnterprise) {
     throw new Error(`--enterprise is only supported with "pumuki bootstrap".\n\n${HELP_TEXT}`);
   }
@@ -1444,6 +1454,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     ...(installMcpAgent ? { installMcpAgent } : {}),
     ...(remoteChecks ? { remoteChecks: true } : {}),
     ...(doctorDeep ? { doctorDeep: true } : {}),
+    ...(doctorParity ? { doctorParity: true } : {}),
   };
 };
 
@@ -1516,6 +1527,22 @@ const printDoctorReport = (
     writeInfo(`[pumuki] ${issue.severity.toUpperCase()}: ${issue.message}`);
   }
 
+  if (report.parity_profile) {
+    writeInfo(
+      `[pumuki][doctor][parity] pumuki=${report.parity_profile.pumuki_package_version} bundle=${report.parity_profile.pre_commit_policy_bundle} hash=${report.parity_profile.pre_commit_policy_hash}`
+    );
+  }
+  if (report.parity_comparison) {
+    writeInfo(
+      `[pumuki][doctor][parity] expected_file=${report.parity_comparison.expected_path} matches=${report.parity_comparison.matches ? 'yes' : 'no'}`
+    );
+    for (const mismatch of report.parity_comparison.mismatches) {
+      writeInfo(
+        `[pumuki][doctor][parity] mismatch ${mismatch.field}: expected=${mismatch.expected} actual=${mismatch.actual}`
+      );
+    }
+  }
+
   if (report.deep?.enabled) {
     for (const check of report.deep.checks) {
       writeInfo(
@@ -1527,7 +1554,8 @@ const printDoctorReport = (
     }
   }
 
-  const hasBlocking = doctorHasBlockingIssues(report);
+  const hasBlocking =
+    doctorHasBlockingIssues(report) || doctorHasParityMismatch(report);
   const hasWarnings =
     report.issues.length > 0 ||
     report.deep?.checks.some((check) => check.status !== 'pass') === true;
@@ -2225,6 +2253,7 @@ export const runLifecycleCli = async (
       case 'doctor': {
         const report = runLifecycleDoctor({
           deep: parsed.doctorDeep === true,
+          parity: parsed.doctorParity === true,
         });
         const remoteCiDiagnostics = parsed.remoteChecks
           ? activeDependencies.collectRemoteCiDiagnostics({
@@ -2247,7 +2276,7 @@ export const runLifecycleCli = async (
         } else {
           printDoctorReport(report, remoteCiDiagnostics);
         }
-        return doctorHasBlockingIssues(report) ? 1 : 0;
+        return doctorHasBlockingIssues(report) || doctorHasParityMismatch(report) ? 1 : 0;
       }
       case 'status': {
         const status = readLifecycleStatus();

package/integrations/lifecycle/doctor.ts

@@ -69,6 +69,22 @@ export type DoctorCompatibilityContract = {
   };
 };
 
+export type DoctorParityProfile = {
+  schema_version: '1';
+  pumuki_package_version: string;
+  pre_commit_policy_bundle: string;
+  pre_commit_policy_hash: string;
+  pre_commit_policy_signature: string | null;
+  pre_commit_policy_version: string | null;
+  skills_policy_present: boolean;
+};
+
+export type DoctorParityComparison = {
+  expected_path: string;
+  matches: boolean;
+  mismatches: ReadonlyArray<{ field: string; expected: string; actual: string }>;
+};
+
 export type LifecycleDoctorReport = {
   repoRoot: string;
   packageVersion: string;
@@ -81,6 +97,8 @@ export type LifecycleDoctorReport = {
   policyValidation: LifecyclePolicyValidationSnapshot;
   issues: ReadonlyArray<DoctorIssue>;
   deep?: DoctorDeepReport;
+  parity_profile?: DoctorParityProfile;
+  parity_comparison?: DoctorParityComparison;
 };
 
 const buildDoctorIssues = (params: {
@@ -698,10 +716,87 @@ const buildDoctorDeepReport = (params: {
   };
 };
 
+const buildDoctorParityProfile = (params: {
+  repoRoot: string;
+  packageVersion: string;
+}): DoctorParityProfile => {
+  const policy = resolvePolicyForStage('PRE_COMMIT', params.repoRoot);
+  const skillsPolicyPath = join(params.repoRoot, 'skills.policy.json');
+  return {
+    schema_version: '1',
+    pumuki_package_version: params.packageVersion,
+    pre_commit_policy_bundle: policy.trace.bundle,
+    pre_commit_policy_hash: policy.trace.hash,
+    pre_commit_policy_signature: policy.trace.signature ?? null,
+    pre_commit_policy_version: policy.trace.version ?? null,
+    skills_policy_present: existsSync(skillsPolicyPath),
+  };
+};
+
+const compareDoctorParityProfile = (params: {
+  repoRoot: string;
+  actual: DoctorParityProfile;
+}): DoctorParityComparison | undefined => {
+  const expectedPath = join(params.repoRoot, '.pumuki', 'ci-parity-expected.json');
+  if (!existsSync(expectedPath)) {
+    return undefined;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(expectedPath, 'utf8')) as unknown;
+  } catch {
+    return {
+      expected_path: expectedPath,
+      matches: false,
+      mismatches: [
+        {
+          field: 'ci-parity-expected.json',
+          expected: 'valid-json',
+          actual: 'parse-error',
+        },
+      ],
+    };
+  }
+  if (!isRecord(raw)) {
+    return {
+      expected_path: expectedPath,
+      matches: false,
+      mismatches: [{ field: 'root', expected: 'object', actual: 'non-object' }],
+    };
+  }
+  const mismatches: Array<{ field: string; expected: string; actual: string }> = [];
+  const expectField = (field: string, expected: unknown, actual: string) => {
+    if (typeof expected === 'string' && expected.trim().length > 0 && expected !== actual) {
+      mismatches.push({ field, expected, actual });
+    }
+  };
+  expectField(
+    'pumuki_package_version',
+    raw.pumuki_package_version,
+    params.actual.pumuki_package_version
+  );
+  expectField(
+    'pre_commit_policy_hash',
+    raw.pre_commit_policy_hash,
+    params.actual.pre_commit_policy_hash
+  );
+  expectField(
+    'pre_commit_policy_bundle',
+    raw.pre_commit_policy_bundle,
+    params.actual.pre_commit_policy_bundle
+  );
+  return {
+    expected_path: expectedPath,
+    matches: mismatches.length === 0,
+    mismatches,
+  };
+};
+
 export const runLifecycleDoctor = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
   deep?: boolean;
+  parity?: boolean;
 }): LifecycleDoctorReport => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -730,6 +825,18 @@ export const runLifecycleDoctor = (params?: {
     lifecycleVersion: lifecycleState.version,
   });
 
+  const parity_profile =
+    params?.parity === true
+      ? buildDoctorParityProfile({
+        repoRoot,
+        packageVersion: version.effective,
+      })
+      : undefined;
+  const parity_comparison =
+    typeof parity_profile !== 'undefined'
+      ? compareDoctorParityProfile({ repoRoot, actual: parity_profile })
+      : undefined;
+
   return {
     repoRoot,
     packageVersion: version.effective,
@@ -742,8 +849,13 @@ export const runLifecycleDoctor = (params?: {
     policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
     issues,
     deep,
+    parity_profile,
+    parity_comparison,
   };
 };
 
 export const doctorHasBlockingIssues = (report: LifecycleDoctorReport): boolean =>
   report.issues.some((issue) => issue.severity === 'error') || report.deep?.blocking === true;
+
+export const doctorHasParityMismatch = (report: LifecycleDoctorReport): boolean =>
+  typeof report.parity_comparison !== 'undefined' && report.parity_comparison.matches === false;

package/integrations/mcp/aiGateCheck.ts

@@ -1,17 +1,8 @@
 import { evaluateAiGate, type AiGateStage } from '../gate/evaluateAiGate';
+import { resolveRemediationHintForViolationCode } from '../gate/remediationCatalog';
 import { resolveLearningContextExperimentalFeature } from '../policy/experimentalFeatures';
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
-const AUTO_FIX_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'Ejecuta una auditoría para generar .ai_evidence.json.',
-  EVIDENCE_INVALID: 'Regenera .ai_evidence.json y vuelve a evaluar.',
-  EVIDENCE_STALE: 'Refresca evidencia antes de continuar.',
-  EVIDENCE_BRANCH_MISMATCH: 'Regenera evidencia en la rama actual.',
-  EVIDENCE_REPO_ROOT_MISMATCH: 'Regenera evidencia desde este repositorio.',
-  PRE_PUSH_UPSTREAM_MISSING: 'Ejecuta git push --set-upstream origin <branch>.',
-  GITFLOW_PROTECTED_BRANCH: 'Crea una rama feature/* y mueve el trabajo allí.',
-};
-
 const PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
 
 export type EnterpriseAiGateCheckResult = {
@@ -112,7 +103,7 @@ const buildAutoFixes = (
     if (emittedCodes.has(violation.code)) {
       continue;
     }
-    const fix = AUTO_FIX_BY_CODE[violation.code];
+    const fix = resolveRemediationHintForViolationCode(violation.code);
     if (!fix) {
       continue;
     }

package/integrations/mcp/preFlightCheck.ts

@@ -4,7 +4,8 @@ import { resolveLearningContextExperimentalFeature } from '../policy/experimenta
 import { readSddLearningContext, type SddLearningContext } from '../sdd/learningInsights';
 
 const ACTIONABLE_HINTS_BY_CODE: Readonly<Record<string, string>> = {
-  EVIDENCE_MISSING: 'Ejecuta una auditoría (1/2/3/4) para regenerar .ai_evidence.json.',
+  EVIDENCE_MISSING:
+    'Ejecuta una auditoría (1/2/3/4 u opciones de motor 11–14) para regenerar .ai_evidence.json.',
   EVIDENCE_INVALID: 'Regenera .ai_evidence.json desde una opción de auditoría.',
   EVIDENCE_INTEGRITY_MISSING: 'Refresca evidencia para regenerar metadatos de integridad.',
   EVIDENCE_ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES:

package/integrations/sdd/openSpecCli.ts

@@ -17,20 +17,29 @@ type OpenSpecCommandResult = {
   stderr: string;
 };
 
-const resolveOpenSpecBinary = (repoRoot: string): string => {
+const resolveOpenSpecBinary = (repoRoot: string): string | undefined => {
   const binaryName = process.platform === 'win32' ? 'openspec.cmd' : 'openspec';
   const localBinaryPath = join(repoRoot, 'node_modules', '.bin', binaryName);
   if (existsSync(localBinaryPath)) {
     return localBinaryPath;
   }
-  return 'openspec';
+  return undefined;
 };
 
 const runOpenSpecCommand = (
   args: ReadonlyArray<string>,
   cwd: string
 ): OpenSpecCommandResult => {
-  const result = runSpawnSync(resolveOpenSpecBinary(cwd), [...args], {
+  const binary = resolveOpenSpecBinary(cwd);
+  if (!binary) {
+    return {
+      exitCode: 127,
+      stdout: '',
+      stderr:
+        'OpenSpec CLI not found under repo node_modules/.bin (add @fission-ai/openspec to this repository).',
+    };
+  }
+  const result = runSpawnSync(binary, [...args], {
     cwd,
     encoding: 'utf8',
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.70",
+  "version": "6.3.72",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {
@@ -259,10 +259,13 @@
     "docs/product/*.md",
     "docs/rule-packs/*.md",
     "docs/validation/*.md",
+    "docs/tracking/plan-curso-pumuki-stack-my-architecture.md",
     "assets/**/*",
     "vendor/skills/**/*",
     "index.js",
     "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
     "LICENSE",
     "VERSION",
     "tsconfig.json",