pumuki 6.3.72 → 6.3.73

package/integrations/git/runPlatformGateOutput.ts

@@ -1,27 +1,5 @@
 import type { Finding } from '../../core/gate/Finding';
-
-const BLOCK_NEXT_ACTION_BY_CODE: Readonly<Record<string, string>> = {
-  SDD_SESSION_MISSING:
-    'npx --yes --package pumuki@latest pumuki sdd session --open --change=<id>',
-  SDD_SESSION_INVALID:
-    'npx --yes --package pumuki@latest pumuki sdd session --refresh --ttl-minutes=90',
-  PRE_PUSH_UPSTREAM_MISSING:
-    'git push --set-upstream origin <branch>',
-  PRE_PUSH_UPSTREAM_MISALIGNED:
-    'git branch --unset-upstream && git push --set-upstream origin <branch>',
-  EVIDENCE_STALE:
-    'npx --yes --package pumuki@latest pumuki-pre-commit',
-  EVIDENCE_BRANCH_MISMATCH:
-    'npx --yes --package pumuki@latest pumuki-pre-commit',
-  GIT_ATOMICITY_TOO_MANY_FILES:
-    'git restore --staged . && separa cambios en commits más pequeños',
-  GIT_ATOMICITY_TOO_MANY_SCOPES:
-    'Revisa scope_files del bloqueo y aplica: git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"',
-  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',
-  SKILLS_SKILLS_FRONTEND_NO_SOLID_VIOLATIONS:
-    'Aplica refactor incremental: extrae 1 componente/hook por commit y vuelve a ejecutar PRE_COMMIT.',
-};
+import { resolveGovernanceCatalogAction } from '../gate/governanceActionCatalog';
 
 const severityWeight = (severity: string): number => {
   switch (severity.toUpperCase()) {
@@ -94,18 +72,49 @@ const formatFinding = (finding: Finding): string => {
   return `[${severity}] ${finding.ruleId}: ${finding.message} -> ${location}`;
 };
 
-export const printGateFindings = (findings: ReadonlyArray<Finding>): void => {
+const resolveAtomicityFallback = (code: string): string | null => {
+  switch (code) {
+    case 'GIT_ATOMICITY_TOO_MANY_FILES':
+      return 'git restore --staged . && separa cambios en commits más pequeños';
+    case 'GIT_ATOMICITY_TOO_MANY_SCOPES':
+      return 'Revisa scope_files del bloqueo y aplica: git restore --staged . && git add <scope>/ && git commit -m "<tipo>: <scope>"';
+    default:
+      return null;
+  }
+};
+
+export const printGateFindings = (
+  findings: ReadonlyArray<Finding>,
+  params?: { stage?: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI' }
+): void => {
   if (findings.length === 0) {
     return;
   }
   const primary = resolvePrimaryFinding(findings);
-  const nextAction =
-    BLOCK_NEXT_ACTION_BY_CODE[primary.code]
-    ?? 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.';
+  const action = resolveGovernanceCatalogAction({
+    code: primary.code,
+    stage: params?.stage ?? 'PRE_COMMIT',
+    fallback: {
+      reason_code: primary.code,
+      instruction: 'Corrige el bloqueante primario y vuelve a ejecutar la validación del stage actual.',
+      next_action: {
+        kind: 'info',
+        message:
+          resolveAtomicityFallback(primary.code)
+          ?? 'Corrige el bloqueante primario y vuelve a ejecutar el mismo comando.',
+      },
+    },
+  });
+  const nextAction = action.next_action.command ?? action.next_action.message;
   process.stdout.write(
     `[pumuki][block-summary] primary=${primary.code} severity=${primary.severity.toUpperCase()} rule=${primary.ruleId}\n`
   );
+  process.stdout.write(`[pumuki][block-summary] reason_code=${action.reason_code}\n`);
+  process.stdout.write(`[pumuki][block-summary] instruction=${action.instruction}\n`);
   process.stdout.write(`[pumuki][block-summary] next_action=${nextAction}\n`);
+  if (action.next_action.command) {
+    process.stdout.write(`[pumuki][block-summary] command=${action.next_action.command}\n`);
+  }
   for (const finding of findings) {
     process.stdout.write(`${formatFinding(finding)}\n`);
   }

package/integrations/lifecycle/adapter.templates.json

@@ -2,6 +2,7 @@
   "codex": [
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {
@@ -31,6 +32,7 @@
   "repo": [
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {
@@ -143,6 +145,7 @@
     },
     {
       "path": ".pumuki/adapter.json",
+      "mode": "json-merge",
       "payload": {
         "hooks": {
           "pre_write": {

package/integrations/lifecycle/audit.ts

@@ -0,0 +1,101 @@
+import { readEvidence } from '../evidence/readEvidence';
+import { GitService } from '../git/GitService';
+import { hasAllowedExtension } from '../git/gitDiffUtils';
+import { runPlatformGate } from '../git/runPlatformGate';
+import { evaluatePlatformGateFindings } from '../git/runPlatformGateEvaluation';
+import { DEFAULT_FACT_FILE_EXTENSIONS } from '../git/runPlatformGateFacts';
+import { resolvePolicyForStage } from '../gate/stagePolicies';
+
+export type LifecycleAuditStage = 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+
+export type LifecycleAuditResult = {
+  command: 'pumuki audit';
+  repo_root: string;
+  stage: LifecycleAuditStage;
+  scope: { kind: 'repo' };
+  audit_mode: 'gate' | 'engine';
+  gate_exit_code: number;
+  files_scanned: number | null;
+  untracked_matching_extensions_count: number;
+  snapshot_outcome: string | null;
+  policy_reconcile_hint: string;
+};
+
+const POLICY_RECONCILE_HINT =
+  'If .pumuki/policy-as-code.json signatures drift after a pumuki upgrade, run: pumuki policy reconcile --apply';
+
+const countUntrackedMatchingExtensions = (
+  git: GitService,
+  extensions: ReadonlyArray<string>
+): number => {
+  const repoRoot = git.resolveRepoRoot();
+  const raw = git.runGit(['ls-files', '--others', '--exclude-standard'], repoRoot);
+  return raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .filter((path) => hasAllowedExtension(path, extensions)).length;
+};
+
+export const runLifecycleAudit = async (params: {
+  stage: LifecycleAuditStage;
+  auditMode: 'gate' | 'engine';
+}): Promise<LifecycleAuditResult> => {
+  const git = new GitService();
+  const repoRoot = git.resolveRepoRoot();
+  const resolved = resolvePolicyForStage(params.stage, repoRoot);
+  const extensions = DEFAULT_FACT_FILE_EXTENSIONS;
+  const untrackedMatchingExtensionsCount = countUntrackedMatchingExtensions(git, extensions);
+
+  const gateParams =
+    params.auditMode === 'engine'
+      ? {
+          policy: resolved.policy,
+          policyTrace: resolved.trace,
+          scope: { kind: 'repo' as const },
+          silent: true,
+          auditMode: 'engine' as const,
+          dependencies: {
+            evaluatePlatformGateFindings: (
+              evalParams: Parameters<typeof evaluatePlatformGateFindings>[0]
+            ) =>
+              evaluatePlatformGateFindings(evalParams, {
+                loadHeuristicsConfig: () => ({
+                  astSemanticEnabled: true,
+                  typeScriptScope: 'all',
+                }),
+              }),
+            printGateFindings: () => {},
+          },
+        }
+      : {
+          policy: resolved.policy,
+          policyTrace: resolved.trace,
+          scope: { kind: 'repo' as const },
+          silent: true,
+          auditMode: 'gate' as const,
+        };
+
+  const gateExitCode = await runPlatformGate(gateParams);
+  const evidence = readEvidence(repoRoot);
+  const filesScanned =
+    typeof evidence?.snapshot.files_scanned === 'number' &&
+    Number.isFinite(evidence.snapshot.files_scanned)
+      ? evidence.snapshot.files_scanned
+      : null;
+  const snapshotOutcome =
+    typeof evidence?.snapshot.outcome === 'string' ? evidence.snapshot.outcome : null;
+
+  return {
+    command: 'pumuki audit',
+    repo_root: repoRoot,
+    stage: params.stage,
+    scope: { kind: 'repo' },
+    audit_mode: params.auditMode,
+    gate_exit_code: gateExitCode,
+    files_scanned: filesScanned,
+    untracked_matching_extensions_count: untrackedMatchingExtensionsCount,
+    snapshot_outcome: snapshotOutcome,
+    policy_reconcile_hint: POLICY_RECONCILE_HINT,
+  };
+};

package/integrations/lifecycle/cli.ts

@@ -4,11 +4,16 @@ import type { GatePolicy } from '../../core/gate/GatePolicy';
 import { runPlatformGate } from '../git/runPlatformGate';
 import { collectWorktreeAtomicSlices } from '../git/worktreeAtomicSlices';
 import {
+  doctorCommandShouldFailExit,
+  doctorCommandShouldWarnHuman,
   doctorHasBlockingIssues,
+  doctorHasGovernanceAttention,
   doctorHasParityMismatch,
   runLifecycleDoctor,
   type LifecycleDoctorReport,
 } from './doctor';
+import { printGovernanceObservationHuman } from './governanceObservationSnapshot';
+import { printGovernanceNextActionHuman } from './governanceNextAction';
 import { runLifecycleInstall } from './install';
 import { runLifecycleRemove } from './remove';
 import { readLifecycleStatus } from './status';
@@ -72,6 +77,7 @@ import {
   type RemoteCiDiagnostics,
 } from './remoteCiDiagnostics';
 import { runPolicyReconcile } from './policyReconcile';
+import { runLifecycleAudit, type LifecycleAuditStage } from './audit';
 import { resolvePreWriteEnforcement, type PreWriteEnforcementResolution } from '../policy/preWriteEnforcement';
 
 type LifecycleCommand =
@@ -87,7 +93,8 @@ type LifecycleCommand =
   | 'sdd'
   | 'adapter'
   | 'analytics'
-  | 'policy';
+  | 'policy'
+  | 'audit';
 
 type SddCommand =
   | 'status'
@@ -173,6 +180,8 @@ export type ParsedArgs = {
   policyCommand?: PolicyCommand;
   policyStrict?: boolean;
   policyApply?: boolean;
+  auditStage?: LifecycleAuditStage;
+  auditEngine?: boolean;
 };
 
 const HELP_TEXT = `
@@ -183,6 +192,7 @@ Pumuki lifecycle commands:
   pumuki remove
   pumuki update [--latest|--spec=<package-spec>]
   pumuki doctor [--remote-checks] [--deep] [--parity] [--json]
+  pumuki audit [--stage=PRE_COMMIT|PRE_PUSH|CI] [--engine] [--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]
@@ -228,7 +238,8 @@ const isLifecycleCommand = (value: string): value is LifecycleCommand =>
   value === 'sdd' ||
   value === 'adapter' ||
   value === 'analytics' ||
-  value === 'policy';
+  value === 'policy' ||
+  value === 'audit';
 
 const parseAdapterAgent = (value?: string): AdapterAgent => {
   const normalized = (value ?? '').trim();
@@ -258,6 +269,16 @@ const parseSddStage = (value?: string): SddStage => {
   throw new Error(`Unsupported SDD stage "${value}". Use PRE_WRITE, PRE_COMMIT, PRE_PUSH or CI.`);
 };
 
+const parseAuditStage = (value?: string): LifecycleAuditStage => {
+  const stage = parseSddStage(value);
+  if (stage === 'PRE_WRITE') {
+    throw new Error(
+      'PRE_WRITE is not supported for "pumuki audit". Use PRE_COMMIT, PRE_PUSH or CI (aliases GREEN, REFACTOR, CLOSE).'
+    );
+  }
+  return stage;
+};
+
 const parseSddEvidencePath = (value: string): string => {
   const normalized = value.trim();
   if (normalized.length === 0) {
@@ -623,6 +644,8 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let analyticsSinceDays: ParsedArgs['analyticsSinceDays'];
   let analyticsJsonOutputPath: ParsedArgs['analyticsJsonOutputPath'];
   let analyticsMarkdownOutputPath: ParsedArgs['analyticsMarkdownOutputPath'];
+  let auditStage: LifecycleAuditStage | undefined;
+  let auditEngine = false;
 
   if (commandRaw === 'watch') {
     for (const arg of argv.slice(1)) {
@@ -806,6 +829,31 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     };
   }
 
+  if (commandRaw === 'audit') {
+    for (const arg of argv.slice(1)) {
+      if (arg === '--json') {
+        json = true;
+        continue;
+      }
+      if (arg === '--engine') {
+        auditEngine = true;
+        continue;
+      }
+      if (arg.startsWith('--stage=')) {
+        auditStage = parseAuditStage(arg.slice('--stage='.length));
+        continue;
+      }
+      throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
+    }
+    return {
+      command: commandRaw,
+      purgeArtifacts: false,
+      json,
+      auditStage: auditStage ?? 'PRE_COMMIT',
+      ...(auditEngine ? { auditEngine: true } : {}),
+    };
+  }
+
   if (commandRaw === 'loop') {
     const subcommandRaw = argv[1] ?? '';
     if (
@@ -1517,6 +1565,8 @@ const printDoctorReport = (
   writeInfo(
     `[pumuki] hook pre-push: ${report.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
   );
+  printGovernanceObservationHuman(report.governanceObservation);
+  printGovernanceNextActionHuman(report.governanceNextAction);
   writeInfo(
     `[pumuki] policy-as-code: PRE_COMMIT=${report.policyValidation.stages.PRE_COMMIT.validationCode ?? 'n/a'} strict=${report.policyValidation.stages.PRE_COMMIT.strict ? 'yes' : 'no'} ` +
     `PRE_PUSH=${report.policyValidation.stages.PRE_PUSH.validationCode ?? 'n/a'} strict=${report.policyValidation.stages.PRE_PUSH.strict ? 'yes' : 'no'} ` +
@@ -1554,17 +1604,19 @@ const printDoctorReport = (
     }
   }
 
-  const hasBlocking =
-    doctorHasBlockingIssues(report) || doctorHasParityMismatch(report);
-  const hasWarnings =
-    report.issues.length > 0 ||
-    report.deep?.checks.some((check) => check.status !== 'pass') === true;
+  const hasBlocking = doctorCommandShouldFailExit(report);
+  const hasWarnings = doctorCommandShouldWarnHuman(report);
 
   if (!hasWarnings && !hasBlocking) {
     writeInfo('[pumuki] doctor verdict: PASS');
   } else {
     writeInfo(`[pumuki] doctor verdict: ${hasBlocking ? 'BLOCKED' : 'WARN'}`);
   }
+  if (!hasBlocking && doctorHasGovernanceAttention(report)) {
+    writeInfo(
+      '[pumuki] doctor: governance_effective is not GREEN (see governance truth).'
+    );
+  }
 
   if (remoteCiDiagnostics) {
     printRemoteCiDiagnostics(remoteCiDiagnostics);
@@ -2250,6 +2302,24 @@ export const runLifecycleCli = async (
         );
         return 0;
       }
+      case 'audit': {
+        const result = await runLifecycleAudit({
+          stage: parsed.auditStage ?? 'PRE_COMMIT',
+          auditMode: parsed.auditEngine === true ? 'engine' : 'gate',
+        });
+        if (parsed.json) {
+          writeInfo(JSON.stringify(result, null, 2));
+        } else {
+          writeInfo(
+            `[pumuki] audit: repo=${result.repo_root} stage=${result.stage} mode=${result.audit_mode} exit=${result.gate_exit_code}`
+          );
+          writeInfo(
+            `[pumuki] audit: files_scanned=${result.files_scanned ?? 'n/a'} untracked_matching_extensions=${result.untracked_matching_extensions_count} outcome=${result.snapshot_outcome ?? 'n/a'}`
+          );
+          writeInfo(`[pumuki] audit: hint=${result.policy_reconcile_hint}`);
+        }
+        return result.gate_exit_code;
+      }
       case 'doctor': {
         const report = runLifecycleDoctor({
           deep: parsed.doctorDeep === true,
@@ -2276,7 +2346,7 @@ export const runLifecycleCli = async (
         } else {
           printDoctorReport(report, remoteCiDiagnostics);
         }
-        return doctorHasBlockingIssues(report) || doctorHasParityMismatch(report) ? 1 : 0;
+        return doctorCommandShouldFailExit(report) ? 1 : 0;
       }
       case 'status': {
         const status = readLifecycleStatus();
@@ -2329,6 +2399,8 @@ export const runLifecycleCli = async (
           writeInfo(
             `[pumuki] hooks: pre-commit=${status.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}, pre-push=${status.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
           );
+          printGovernanceObservationHuman(status.governanceObservation);
+          printGovernanceNextActionHuman(status.governanceNextAction);
           writeInfo(
             `[pumuki] tracked node_modules paths: ${status.trackedNodeModulesCount}`
           );

package/integrations/lifecycle/doctor.ts

@@ -5,10 +5,25 @@ import { resolvePolicyForStage } from '../gate/stagePolicies';
 import { getPumukiHooksStatus, resolvePumukiHooksDirectory } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { buildLifecycleVersionReport, getCurrentPumukiVersion } from './packageInfo';
+import {
+  readLifecycleExperimentalFeaturesSnapshot,
+  type LifecycleExperimentalFeaturesSnapshot,
+} from './experimentalFeaturesSnapshot';
 import {
   readLifecyclePolicyValidationSnapshot,
   type LifecyclePolicyValidationSnapshot,
 } from './policyValidationSnapshot';
+import {
+  doctorGovernanceIsBlocking,
+  doctorGovernanceNeedsAttention,
+  readGovernanceObservationSnapshot,
+  type GovernanceObservationSnapshot,
+} from './governanceObservationSnapshot';
+import {
+  readGovernanceNextAction,
+  type GovernanceNextActionReader,
+  type GovernanceNextActionSummary,
+} from './governanceNextAction';
 import { readLifecycleState, type LifecycleState } from './state';
 import {
   detectOpenSpecInstallation,
@@ -95,6 +110,10 @@ export type LifecycleDoctorReport = {
   hooksDirectory: string;
   hooksDirectoryResolution: 'git-rev-parse' | 'git-config' | 'default';
   policyValidation: LifecyclePolicyValidationSnapshot;
+  experimentalFeatures: LifecycleExperimentalFeaturesSnapshot;
+  governanceObservation: GovernanceObservationSnapshot;
+  governanceNextAction: GovernanceNextActionSummary;
+  policy_signature_remediation?: string;
   issues: ReadonlyArray<DoctorIssue>;
   deep?: DoctorDeepReport;
   parity_profile?: DoctorParityProfile;
@@ -792,11 +811,21 @@ const compareDoctorParityProfile = (params: {
   };
 };
 
+const buildPolicySignatureRemediation = (
+  policyValidation: LifecyclePolicyValidationSnapshot
+): string | undefined => {
+  const mismatch = Object.values(policyValidation.stages).some(
+    (stage) => stage.validationCode === 'POLICY_AS_CODE_SIGNATURE_MISMATCH'
+  );
+  return mismatch ? 'pumuki policy reconcile --apply' : undefined;
+};
+
 export const runLifecycleDoctor = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
   deep?: boolean;
   parity?: boolean;
+  governanceNextActionReader?: GovernanceNextActionReader;
 }): LifecycleDoctorReport => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -824,6 +853,19 @@ export const runLifecycleDoctor = (params?: {
     repoRoot,
     lifecycleVersion: lifecycleState.version,
   });
+  const policyValidation = readLifecyclePolicyValidationSnapshot(repoRoot);
+  const experimentalFeatures = readLifecycleExperimentalFeaturesSnapshot();
+  const governanceObservation = readGovernanceObservationSnapshot({
+    repoRoot,
+    experimentalFeatures,
+    policyValidation,
+    git,
+  });
+  const governanceNextAction = (params?.governanceNextActionReader ?? readGovernanceNextAction)({
+    repoRoot,
+    stage: 'PRE_WRITE',
+    governanceObservation,
+  });
 
   const parity_profile =
     params?.parity === true
@@ -837,6 +879,8 @@ export const runLifecycleDoctor = (params?: {
       ? compareDoctorParityProfile({ repoRoot, actual: parity_profile })
       : undefined;
 
+  const policySignatureRemediation = buildPolicySignatureRemediation(policyValidation);
+
   return {
     repoRoot,
     packageVersion: version.effective,
@@ -846,7 +890,13 @@ export const runLifecycleDoctor = (params?: {
     hookStatus,
     hooksDirectory: hooksDirectory.path,
     hooksDirectoryResolution: hooksDirectory.source,
-    policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
+    policyValidation,
+    experimentalFeatures,
+    governanceObservation,
+    governanceNextAction,
+    ...(policySignatureRemediation
+      ? { policy_signature_remediation: policySignatureRemediation }
+      : {}),
     issues,
     deep,
     parity_profile,
@@ -859,3 +909,16 @@ export const doctorHasBlockingIssues = (report: LifecycleDoctorReport): boolean
 
 export const doctorHasParityMismatch = (report: LifecycleDoctorReport): boolean =>
   typeof report.parity_comparison !== 'undefined' && report.parity_comparison.matches === false;
+
+export const doctorHasGovernanceAttention = (report: LifecycleDoctorReport): boolean =>
+  doctorGovernanceNeedsAttention(report.governanceObservation);
+
+export const doctorCommandShouldWarnHuman = (report: LifecycleDoctorReport): boolean =>
+  report.issues.length > 0 ||
+  report.deep?.checks.some((check) => check.status !== 'pass') === true ||
+  doctorHasGovernanceAttention(report);
+
+export const doctorCommandShouldFailExit = (report: LifecycleDoctorReport): boolean =>
+  doctorHasBlockingIssues(report) ||
+  doctorHasParityMismatch(report) ||
+  doctorGovernanceIsBlocking(report.governanceObservation);

package/integrations/lifecycle/governanceNextAction.ts

@@ -0,0 +1,164 @@
+import type { AiGateStage } from '../gate/evaluateAiGate';
+import { resolveGovernanceCatalogAction } from '../gate/governanceActionCatalog';
+import type { GovernanceObservationSnapshot } from './governanceObservationSnapshot';
+import { writeInfo } from './cliOutputs';
+
+export type GovernanceNextActionSummary = {
+  stage: AiGateStage;
+  phase: 'GREEN' | 'RED';
+  action: 'proceed' | 'ask';
+  confidence_pct: number;
+  reason_code: string;
+  instruction: string;
+  message: string;
+  next_action: {
+    kind: 'info' | 'run_command';
+    message: string;
+    command?: string;
+  };
+};
+
+export type GovernanceNextActionReader = (params: {
+  repoRoot: string;
+  stage?: AiGateStage;
+  governanceObservation: GovernanceObservationSnapshot;
+}) => GovernanceNextActionSummary;
+
+const resolveBlockedAction = (
+  snapshot: GovernanceObservationSnapshot,
+  stage: AiGateStage
+): GovernanceNextActionSummary => {
+  if (snapshot.attention_codes.includes('EVIDENCE_INVALID_OR_CHAIN')) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 80,
+      ...resolveGovernanceCatalogAction({ code: 'EVIDENCE_INVALID_OR_CHAIN', stage }),
+      message: 'La evidencia actual no es fiable; detén la ejecución automática hasta regenerarla.',
+    };
+  }
+  if (
+    snapshot.attention_codes.includes('AI_GATE_BLOCKED')
+    || snapshot.attention_codes.includes('EVIDENCE_SNAPSHOT_BLOCK')
+  ) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 75,
+      ...resolveGovernanceCatalogAction({ code: 'AI_GATE_BLOCKED', stage }),
+      message: 'El gate efectivo sigue bloqueado; Pumuki no debe marcar verde ni dejar continuar.',
+    };
+  }
+  if (snapshot.attention_codes.includes('SDD_SESSION_INVALID_OR_EXPIRED')) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 70,
+      ...resolveGovernanceCatalogAction({ code: 'SDD_SESSION_INVALID_OR_EXPIRED', stage }),
+      message: 'Hay una sesión SDD activa pero inválida; eso rompe el loop documental esperado.',
+    };
+  }
+  if (snapshot.attention_codes.includes('GITFLOW_PROTECTED_BRANCH_CONTEXT')) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 65,
+      ...resolveGovernanceCatalogAction({ code: 'GITFLOW_PROTECTED_BRANCH_CONTEXT', stage }),
+      message: 'El contexto actual cae sobre una rama protegida; el flujo enterprise no debe continuar ahí.',
+    };
+  }
+  if (
+    snapshot.attention_codes.some((code) => code.startsWith('POLICY_'))
+    || snapshot.enterprise_warn_as_block_env
+  ) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 60,
+      ...resolveGovernanceCatalogAction({ code: 'POLICY_STAGE_NOT_STRICT', stage }),
+      message: 'La política efectiva todavía no es estricta en todos los stages requeridos.',
+    };
+  }
+  if (!snapshot.contract_surface.skills_lock_json || !snapshot.contract_surface.skills_sources_json) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 55,
+      ...resolveGovernanceCatalogAction({ code: 'SKILLS_CONTRACT_SURFACE_INCOMPLETE', stage }),
+      message: 'El contrato de skills todavía no está completamente materializado en el repo.',
+    };
+  }
+  if (!snapshot.contract_surface.pumuki_adapter_json) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 50,
+      ...resolveGovernanceCatalogAction({ code: 'ADAPTER_WIRING_MISSING', stage }),
+      message: 'La línea base Git puede operar, pero el wiring adaptador aún no está materializado.',
+    };
+  }
+  if (snapshot.attention_codes.includes('EVIDENCE_SNAPSHOT_WARN')) {
+    return {
+      stage,
+      phase: 'RED',
+      action: 'ask',
+      confidence_pct: 50,
+      ...resolveGovernanceCatalogAction({ code: 'EVIDENCE_SNAPSHOT_WARN', stage }),
+      message: 'La evidencia está en WARN; no conviene tratar el repo como completamente verde.',
+    };
+  }
+  return {
+    stage,
+    phase: 'RED',
+    action: 'ask',
+    confidence_pct: 40,
+    ...resolveGovernanceCatalogAction({ code: 'GOVERNANCE_ATTENTION', stage }),
+    message: 'Todavía hay señales de governance no resueltas.',
+  };
+};
+
+export const readGovernanceNextAction: GovernanceNextActionReader = (params) => {
+  const stage = params.stage ?? 'PRE_WRITE';
+  const snapshot = params.governanceObservation;
+  if (snapshot.governance_effective === 'green') {
+    return {
+      stage,
+      phase: 'GREEN',
+      action: 'proceed',
+      confidence_pct: 90,
+      ...resolveGovernanceCatalogAction({ code: 'READY', stage }),
+      message: 'Governance efectiva en verde: continúa con la implementación mínima.',
+    };
+  }
+  return resolveBlockedAction(snapshot, stage);
+};
+
+export const buildGovernanceNextActionSummaryLines = (
+  snapshot: GovernanceNextActionSummary
+): string[] => {
+  const lines = [
+    `Next action: stage=${snapshot.stage} phase=${snapshot.phase} action=${snapshot.action} confidence=${snapshot.confidence_pct}% reason=${snapshot.reason_code}`,
+    `Instruction: ${snapshot.instruction}`,
+    `Action detail: ${snapshot.next_action.message}`,
+  ];
+  if (snapshot.next_action.command) {
+    lines.push(`Command: ${snapshot.next_action.command}`);
+  }
+  return lines;
+};
+
+export const printGovernanceNextActionHuman = (
+  snapshot: GovernanceNextActionSummary
+): void => {
+  writeInfo('[pumuki] governance next action (S1 / governance console baseline):');
+  for (const line of buildGovernanceNextActionSummaryLines(snapshot)) {
+    writeInfo(`[pumuki]   ${line}`);
+  }
+};