pumuki 6.3.72 → 6.3.75

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}`);
+  }
+};

package/integrations/lifecycle/governanceObservationSnapshot.ts

@@ -0,0 +1,315 @@
+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';
+import type { ILifecycleGitService } from './gitService';
+import { LifecycleGitService } from './gitService';
+import type { LifecyclePolicyValidationSnapshot } from './policyValidationSnapshot';
+import { writeInfo } from './cliOutputs';
+
+const DEFAULT_PROTECTED_BRANCHES = new Set(['main', 'master', 'develop', 'dev']);
+
+export type GovernanceEvidenceSummary = {
+  path: string;
+  readable: 'missing' | 'invalid' | 'valid';
+  snapshot_stage?: string;
+  snapshot_outcome?: 'PASS' | 'WARN' | 'BLOCK';
+  matched_warn_count?: number;
+  matched_blocking_count?: number;
+  findings_count?: number;
+  ai_gate_status?: 'ALLOWED' | 'BLOCKED';
+  human_summary_preview: string[];
+};
+
+export type GovernanceContractSurface = {
+  agents_md: boolean;
+  skills_lock_json: boolean;
+  skills_sources_json: boolean;
+  vendor_skills_dir: boolean;
+  pumuki_adapter_json: boolean;
+};
+
+export type GovernanceObservationSnapshot = {
+  schema_version: '1';
+  sdd: {
+    experimental_raw: string | null;
+    effective_mode: 'off' | 'advisory' | 'strict';
+    experimental_source: string;
+  };
+  sdd_session: {
+    active: boolean;
+    valid: boolean;
+    change_id: string | null;
+    remaining_seconds: number | null;
+  };
+  policy_strict: {
+    pre_write: boolean;
+    pre_commit: boolean;
+    pre_push: boolean;
+    ci: boolean;
+  };
+  enterprise_warn_as_block_env: boolean;
+  evidence: GovernanceEvidenceSummary;
+  git: {
+    current_branch: string | null;
+    on_protected_branch_hint: boolean;
+  };
+  contract_surface: GovernanceContractSurface;
+  tracking: RepoTrackingState;
+  attention_codes: ReadonlyArray<string>;
+  governance_effective: 'green' | 'attention' | 'blocked';
+  agent_bootstrap_hints: ReadonlyArray<string>;
+};
+
+const truthyEnv = (value: string | undefined): boolean => {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'strict';
+};
+
+const readCurrentBranch = (git: ILifecycleGitService, repoRoot: string): string | null => {
+  try {
+    const branch = git.runGit(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot).trim();
+    return branch.length > 0 ? branch : null;
+  } catch {
+    return null;
+  }
+};
+
+const readSddStatusSafe = (repoRoot: string): SddStatusPayload => {
+  try {
+    return readSddStatus(repoRoot);
+  } catch {
+    return {
+      repoRoot,
+      openspec: {
+        installed: false,
+        projectInitialized: false,
+        minimumVersion: '0.0.0',
+        recommendedVersion: '0.0.0',
+        compatible: false,
+      },
+      session: {
+        repoRoot,
+        active: false,
+        valid: false,
+      },
+    };
+  }
+};
+
+const buildContractSurface = (repoRoot: string): GovernanceContractSurface => ({
+  agents_md: existsSync(join(repoRoot, 'AGENTS.md')),
+  skills_lock_json: existsSync(join(repoRoot, 'skills.lock.json')),
+  skills_sources_json: existsSync(join(repoRoot, 'skills.sources.json')),
+  vendor_skills_dir: existsSync(join(repoRoot, 'vendor', 'skills')),
+  pumuki_adapter_json: existsSync(join(repoRoot, '.pumuki', 'adapter.json')),
+});
+
+const summarizeEvidence = (repoRoot: string): GovernanceEvidenceSummary => {
+  const evidenceResult = readEvidenceResult(repoRoot);
+  const path = evidenceResult.source_descriptor.path;
+  if (evidenceResult.kind === 'missing') {
+    return { path, readable: 'missing', human_summary_preview: [] };
+  }
+  if (evidenceResult.kind === 'invalid') {
+    return {
+      path,
+      readable: 'invalid',
+      human_summary_preview: [evidenceResult.detail ?? evidenceResult.reason],
+    };
+  }
+
+  const snapshot = evidenceResult.evidence.snapshot;
+  const hints = evidenceResult.evidence.operational_hints?.human_summary_lines ?? [];
+  const breakdown = evidenceResult.evidence.operational_hints?.rule_execution_breakdown;
+  return {
+    path,
+    readable: 'valid',
+    snapshot_stage: snapshot.stage,
+    snapshot_outcome: snapshot.outcome,
+    matched_warn_count: breakdown?.matched_warn_count,
+    matched_blocking_count: breakdown?.matched_blocking_count,
+    findings_count: Array.isArray(snapshot.findings) ? snapshot.findings.length : 0,
+    ai_gate_status: evidenceResult.evidence.ai_gate.status,
+    human_summary_preview: hints.slice(0, 5),
+  };
+};
+
+const buildHints = (
+  surface: GovernanceContractSurface,
+  branch: string | null,
+  protectedBranchHint: boolean,
+  tracking: RepoTrackingState
+): string[] => {
+  const hints: string[] = [];
+  if (surface.agents_md) {
+    hints.push('AGENTS.md presente: aplica el contrato del repo antes de dar governance en verde.');
+  }
+  if (!surface.skills_lock_json) {
+    hints.push('Falta skills.lock.json: genera lock canónico de skills antes de cerrar la gobernanza.');
+  }
+  if (!surface.pumuki_adapter_json) {
+    hints.push('Falta .pumuki/adapter.json: instala el adaptador si quieres wiring IDE/MCP explícito.');
+  }
+  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;
+};
+
+export const readGovernanceObservationSnapshot = (params: {
+  repoRoot: string;
+  experimentalFeatures: LifecycleExperimentalFeaturesSnapshot;
+  policyValidation: LifecyclePolicyValidationSnapshot;
+  git?: ILifecycleGitService;
+}): GovernanceObservationSnapshot => {
+  const git = params.git ?? new LifecycleGitService();
+  const { repoRoot, experimentalFeatures, policyValidation } = params;
+  const rawSdd = process.env.PUMUKI_EXPERIMENTAL_SDD?.trim();
+  const sddStatus = readSddStatusSafe(repoRoot);
+  const evidence = summarizeEvidence(repoRoot);
+  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[] = [];
+  if (evidence.readable === 'invalid') {
+    attention.push('EVIDENCE_INVALID_OR_CHAIN');
+  }
+  if (evidence.readable === 'valid' && evidence.ai_gate_status === 'BLOCKED') {
+    attention.push('AI_GATE_BLOCKED');
+  }
+  if (evidence.readable === 'valid' && evidence.snapshot_outcome === 'WARN') {
+    attention.push('EVIDENCE_SNAPSHOT_WARN');
+  }
+  if (evidence.readable === 'valid' && evidence.snapshot_outcome === 'BLOCK') {
+    attention.push('EVIDENCE_SNAPSHOT_BLOCK');
+  }
+  if (sddStatus.session.active === true && sddStatus.session.valid !== true) {
+    attention.push('SDD_SESSION_INVALID_OR_EXPIRED');
+  }
+  if (!policyValidation.stages.PRE_WRITE.strict) {
+    attention.push('POLICY_PRE_WRITE_NOT_STRICT');
+  }
+  if (!policyValidation.stages.PRE_COMMIT.strict) {
+    attention.push('POLICY_PRE_COMMIT_NOT_STRICT');
+  }
+  if (!policyValidation.stages.PRE_PUSH.strict) {
+    attention.push('POLICY_PRE_PUSH_NOT_STRICT');
+  }
+  if (!policyValidation.stages.CI.strict) {
+    attention.push('POLICY_CI_NOT_STRICT');
+  }
+  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 (
+    evidence.readable === 'invalid'
+    || (evidence.readable === 'valid' && evidence.ai_gate_status === 'BLOCKED')
+    || (evidence.readable === 'valid' && evidence.snapshot_outcome === 'BLOCK')
+  ) {
+    governanceEffective = 'blocked';
+  } else if (attention.length > 0) {
+    governanceEffective = 'attention';
+  }
+
+  return {
+    schema_version: '1',
+    sdd: {
+      experimental_raw: rawSdd && rawSdd.length > 0 ? rawSdd : null,
+      effective_mode: experimentalFeatures.features.sdd.mode,
+      experimental_source: experimentalFeatures.features.sdd.source,
+    },
+    sdd_session: {
+      active: sddStatus.session.active,
+      valid: sddStatus.session.valid,
+      change_id: sddStatus.session.changeId ?? null,
+      remaining_seconds:
+        typeof sddStatus.session.remainingSeconds === 'number' ? sddStatus.session.remainingSeconds : null,
+    },
+    policy_strict: {
+      pre_write: policyValidation.stages.PRE_WRITE.strict,
+      pre_commit: policyValidation.stages.PRE_COMMIT.strict,
+      pre_push: policyValidation.stages.PRE_PUSH.strict,
+      ci: policyValidation.stages.CI.strict,
+    },
+    enterprise_warn_as_block_env: warnAsBlock,
+    evidence,
+    git: {
+      current_branch: branch,
+      on_protected_branch_hint: onProtected,
+    },
+    contract_surface: surface,
+    tracking,
+    attention_codes: attention,
+    governance_effective: governanceEffective,
+    agent_bootstrap_hints: buildHints(surface, branch, onProtected, tracking),
+  };
+};
+
+export const buildGovernanceObservationSummaryLines = (
+  snapshot: GovernanceObservationSnapshot
+): string[] => {
+  const lines = [
+    `Governance: ${snapshot.governance_effective.toUpperCase()}`,
+    `Contract: AGENTS=${snapshot.contract_surface.agents_md ? 'yes' : 'no'} skills.lock=${snapshot.contract_surface.skills_lock_json ? 'yes' : 'no'} skills.sources=${snapshot.contract_surface.skills_sources_json ? 'yes' : 'no'} vendor/skills=${snapshot.contract_surface.vendor_skills_dir ? 'yes' : 'no'} adapter=${snapshot.contract_surface.pumuki_adapter_json ? 'yes' : 'no'}`,
+    `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) {
+    lines.push(`Attention: ${snapshot.attention_codes.join(', ')}`);
+  }
+  return lines;
+};
+
+export const printGovernanceObservationHuman = (snapshot: GovernanceObservationSnapshot): void => {
+  writeInfo('[pumuki] governance truth (S1 / governance console baseline):');
+  for (const line of buildGovernanceObservationSummaryLines(snapshot)) {
+    writeInfo(`[pumuki]   ${line}`);
+  }
+  for (const hint of snapshot.evidence.human_summary_preview) {
+    writeInfo(`[pumuki]   evidence hint: ${hint}`);
+  }
+};
+
+export const doctorGovernanceIsBlocking = (snapshot: GovernanceObservationSnapshot): boolean =>
+  snapshot.governance_effective === 'blocked';
+
+export const doctorGovernanceNeedsAttention = (snapshot: GovernanceObservationSnapshot): boolean =>
+  snapshot.governance_effective !== 'green';

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/lifecycle/status.ts

@@ -9,6 +9,15 @@ import {
   readLifecyclePolicyValidationSnapshot,
   type LifecyclePolicyValidationSnapshot,
 } from './policyValidationSnapshot';
+import {
+  readGovernanceObservationSnapshot,
+  type GovernanceObservationSnapshot,
+} from './governanceObservationSnapshot';
+import {
+  readGovernanceNextAction,
+  type GovernanceNextActionReader,
+  type GovernanceNextActionSummary,
+} from './governanceNextAction';
 import { readLifecycleState, type LifecycleState } from './state';
 
 export type LifecycleStatus = {
@@ -22,11 +31,14 @@ export type LifecycleStatus = {
   trackedNodeModulesCount: number;
   policyValidation: LifecyclePolicyValidationSnapshot;
   experimentalFeatures: LifecycleExperimentalFeaturesSnapshot;
+  governanceObservation: GovernanceObservationSnapshot;
+  governanceNextAction: GovernanceNextActionSummary;
 };
 
 export const readLifecycleStatus = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
+  governanceNextActionReader?: GovernanceNextActionReader;
 }): LifecycleStatus => {
   const git = params?.git ?? new LifecycleGitService();
   const cwd = params?.cwd ?? process.cwd();
@@ -38,6 +50,19 @@ export const readLifecycleStatus = (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,
+  });
 
   return {
     repoRoot,
@@ -48,7 +73,9 @@ export const readLifecycleStatus = (params?: {
     hooksDirectory: hooksDirectory.path,
     hooksDirectoryResolution: hooksDirectory.source,
     trackedNodeModulesCount,
-    policyValidation: readLifecyclePolicyValidationSnapshot(repoRoot),
-    experimentalFeatures: readLifecycleExperimentalFeaturesSnapshot(),
+    policyValidation,
+    experimentalFeatures,
+    governanceNextAction,
+    governanceObservation,
   };
 };