pumuki 6.3.34 → 6.3.36

package/VERSION

@@ -1 +1 @@
-v6.3.24
+v6.3.36

package/docs/CONFIGURATION.md

@@ -97,6 +97,102 @@ Defined in `integrations/gate/stagePolicies.ts`:
 - `PRE_PUSH`: block `ERROR`, warn from `WARN`
 - `CI`: block `ERROR`, warn from `WARN`
 
+## Degraded mode (offline / air-gapped)
+
+Pumuki supports a deterministic degraded contract by stage:
+
+- `PRE_WRITE`
+- `PRE_COMMIT`
+- `PRE_PUSH`
+- `CI`
+
+Resolution precedence:
+
+1. Environment variables (`PUMUKI_DEGRADED_MODE=1`)
+2. File contract (`.pumuki/degraded-mode.json`)
+
+Environment variables:
+
+- `PUMUKI_DEGRADED_MODE`: enable/disable (`1|0`, `true|false`, `yes|no`)
+- `PUMUKI_DEGRADED_REASON`: operator-visible reason
+- `PUMUKI_DEGRADED_ACTION`: global default action (`allow|block`)
+- `PUMUKI_DEGRADED_ACTION_PRE_WRITE`: per-stage override
+- `PUMUKI_DEGRADED_ACTION_PRE_COMMIT`: per-stage override
+- `PUMUKI_DEGRADED_ACTION_PRE_PUSH`: per-stage override
+- `PUMUKI_DEGRADED_ACTION_CI`: per-stage override
+
+File contract (`.pumuki/degraded-mode.json`):
+
+```json
+{
+  "version": "1.0",
+  "enabled": true,
+  "reason": "offline-airgapped",
+  "stages": {
+    "PRE_WRITE": "block",
+    "PRE_COMMIT": "allow",
+    "PRE_PUSH": "block",
+    "CI": "block"
+  }
+}
+```
+
+Runtime behavior:
+
+- `action=block`:
+  - gate adds finding `governance.degraded-mode.blocked`
+  - SDD returns `SDD_DEGRADED_MODE_BLOCKED`
+- `action=allow`:
+  - gate adds informational finding `governance.degraded-mode.active`
+  - SDD returns `ALLOWED` with degraded metadata in `decision.details`
+
+Traceability:
+
+- `policyTrace.degraded` is emitted for gate stages.
+- hook summaries include `degraded_mode`, `degraded_action`, and `degraded_reason` when active.
+- evidence/telemetry include degraded metadata in policy trace when available.
+
+## SDD sync-docs learning artifact
+
+When `pumuki sdd sync-docs` runs with `--change=<change-id>`, the command emits a machine-readable learning payload.
+
+Write path:
+
+- `openspec/changes/<change-id>/learning.json`
+
+Payload schema (`v1.0`):
+
+```json
+{
+  "version": "1.0",
+  "change_id": "rgo-1700-01",
+  "stage": "PRE_COMMIT",
+  "task": "P12.F2.T67",
+  "generated_at": "2026-03-04T10:05:00.000Z",
+  "failed_patterns": ["ai-gate.blocked"],
+  "successful_patterns": ["sync-docs.completed", "sync-docs.updated"],
+  "rule_updates": [
+    "ai-gate.unblock.required",
+    "ai-gate.violation.EVIDENCE_STALE.review"
+  ],
+  "gate_anomalies": ["ai-gate.violation.EVIDENCE_STALE"],
+  "sync_docs": {
+    "updated": true,
+    "file_paths": [
+      "docs/technical/08-validation/refactor/pumuki-integration-feedback.md"
+    ]
+  }
+}
+```
+
+Behavior:
+
+- `--dry-run`: includes learning payload in JSON output with `learning.written=false` and does not write files.
+- non dry-run: persists `learning.json` deterministically and reports digest/path in output.
+- `rule_updates`: deterministic recommendations derived from evidence/gate signals (`missing`, `invalid`, `blocked`, `allowed`).
+- dedicated command: `pumuki sdd learn --change=<id> [--stage=<stage>] [--task=<task>] [--dry-run] [--json]` generates/persists the same artifact without requiring `sync-docs`.
+- orchestration command: `pumuki sdd auto-sync --change=<id> [--stage=<stage>] [--task=<task>] [--dry-run] [--json]` executes deterministic docs sync plus learning generation in one step.
+
 ## Gate telemetry export (optional)
 
 Structured telemetry output is disabled by default and can be enabled with environment variables:

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,53 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-04 (v6.3.36)
+
+- SDD orchestration hardening shipped:
+  - New enterprise command `pumuki sdd auto-sync` with `--change`, optional `--stage/--task`, `--dry-run`, and `--json`.
+  - `auto-sync` orchestrates deterministic docs sync plus learning generation in one step.
+  - Fail-safe behavior preserved through the existing transactional `sync-docs` path (no partial writes on conflict).
+- Traceability:
+  - implementation issue: `#600`
+  - implementation PR: `#602`
+  - tracking sync PR: `#604`
+- Consumer quick verification:
+  - `npx --yes --package pumuki@latest pumuki sdd auto-sync --change=rgo-quickstart-02 --stage=PRE_WRITE --task=P12.F2.T70 --dry-run --json`
+  - expected signal:
+    - `command=pumuki sdd auto-sync` available in CLI help.
+    - JSON payload includes `syncDocs.updated` and `learning.path`.
+
+### 2026-03-04 (v6.3.35)
+
+- SDD enterprise incremental hardening shipped:
+  - New dedicated command `pumuki sdd learn` with `--change`, optional `--stage/--task`, `--dry-run`, and `--json`.
+  - `sync-docs` learning artifact now emits deterministic signal-derived `rule_updates`.
+  - Learning payload remains deterministic across missing/invalid/blocked/allowed evidence states.
+- Traceability:
+  - implementation PRs: `#593`, `#596`, `#599`
+- Consumer quick verification:
+  - `npx --yes --package pumuki@latest pumuki sdd learn --change=rgo-quickstart-01 --dry-run --json`
+  - `npx --yes --package pumuki@latest pumuki sdd sync-docs --change=rgo-quickstart-01 --stage=PRE_WRITE --task=P12.F2.T68 --dry-run --json`
+  - expected signal:
+    - `command=pumuki sdd learn` available in CLI help.
+    - `learning.artifact.rule_updates` populated deterministically when evidence is blocked/invalid.
+
+### 2026-03-04 (v6.3.34)
+
+- Telemetry hardening shipped for long-running enterprise repos:
+  - Gate telemetry JSONL supports deterministic size-guard rotation with `PUMUKI_TELEMETRY_JSONL_MAX_BYTES`.
+  - Enterprise contract suite now includes profile `telemetry-rotation` to validate JSONL rollover behavior.
+- Traceability:
+  - implementation PRs: `#574`, `#577`
+  - release PR: `#580`
+- Consumer quick verification:
+  - `npx --yes --package pumuki@latest pumuki doctor --json`
+  - `npm run -s validation:contract-suite:enterprise -- --json`
+  - `PUMUKI_TELEMETRY_JSONL_PATH=.pumuki/artifacts/gate-telemetry.jsonl PUMUKI_TELEMETRY_JSONL_MAX_BYTES=512 npx --yes --package pumuki@latest pumuki sdd validate --stage=PRE_WRITE --json`
+  - expected signal:
+    - contract suite list includes profile `telemetry-rotation`
+    - after repeated validations, files `gate-telemetry.jsonl` and `gate-telemetry.jsonl.1` are present
+
 ### 2026-03-04 (v6.3.33)
 
 - Runtime hardening shipped for enterprise diagnosis:

package/docs/registro-maestro-de-seguimiento.md

@@ -7,7 +7,8 @@
 ## Estado actual
 - Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`
 - Estado del plan: EN CURSO
-- Task activa (`🚧`): `P12.F2.T60` (release patch con mejoras de telemetría, issue `#578`).
+- Última task cerrada (`✅`): `P12.F2.T70` (comando orquestador `pumuki sdd auto-sync`, issue `#600`, PR `#602`, commit `2be34c5`).
+- Task activa (`🚧`): `P12.F2.T71` (publicar release `6.3.36` con `auto-sync`, issue `#603`).
 
 ## Historial resumido
 - No se mantienen MDs históricos de seguimiento en este repositorio.

package/docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md

@@ -1838,11 +1838,141 @@ Criterio de salida F5:
     - `npm run -s validation:tracking-single-active`
     - `docs/validation/README.md` actualizado con perfiles activos de la suite contractual.
 
-- 🚧 `P12.F2.T60` Publicar patch release con mejoras de telemetría (`#574`, `#577`) para disponibilidad inmediata en npm.
+- ✅ `P12.F2.T60` Publicar patch release con mejoras de telemetría (`#574`, `#577`) para disponibilidad inmediata en npm.
+  - cierre ejecutado:
+    - issue de release creada y cerrada: `#578`.
+    - rama release creada y mergeada: `release/6.3.34` -> `#580` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/580`).
+    - publicación npm completada: `pumuki@6.3.34`.
+  - evidencia:
+    - `npm run -s validation:tracking-single-active`
+    - `npm view pumuki version` => `6.3.34`
+    - `gh issue close 578 --comment "Closed via PR #580 and npm publish 6.3.34 (telemetry rotation + contract profile telemetry-rotation)."`
+
+- ✅ `P12.F2.T61` Publicar documentación de adopción de `6.3.34` (release notes + verificación operativa rápida).
+  - cierre ejecutado:
+    - issue documental creada y cerrada: `#581`.
+    - `docs/RELEASE_NOTES.md` actualizado con entrada `2026-03-04 (v6.3.34)` y comandos de verificación operativa.
+    - trazabilidad sincronizada en plan activo + registro maestro.
+  - evidencia:
+    - `npm run -s validation:tracking-single-active`
+    - `gh issue close 581 --comment "Closed via release notes update for 6.3.34 and tracking sync."`
+
+- ✅ `P12.F2.T62` Ejecutar la siguiente mejora estratégica pendiente: modo degradado offline/air-gapped para gates enterprise (`#583`).
+  - cierre ejecutado:
+    - contrato reutilizable implementado en `integrations/gate/degradedMode.ts` con precedencia `env -> .pumuki/degraded-mode.json`.
+    - `resolvePolicyForStage` expone `trace.degraded` por stage.
+    - `runPlatformGate` aplica enforcement:
+      - `action=block` -> finding `governance.degraded-mode.blocked` + gate `BLOCK`.
+      - `action=allow` -> finding `governance.degraded-mode.active` + gate permite continuar.
+    - hooks exitosos publican resumen degradado (`degraded_mode`, `degraded_action`, `degraded_reason`).
+    - SDD integra el contrato:
+      - `action=block` -> `SDD_DEGRADED_MODE_BLOCKED`.
+      - `action=allow` -> `ALLOWED` con metadata degradada en `decision.details`.
+    - documentación operativa actualizada en `docs/CONFIGURATION.md`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/gate/__tests__/stagePolicies.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/git/__tests__/hookGateSummary.test.ts integrations/sdd/__tests__/policy.test.ts` => `58 passed, 0 failed`.
+    - `npx --yes tsx@4.21.0 --test integrations/telemetry/__tests__/gateTelemetry.test.ts` => `4 passed`.
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/EvidenceService.test.ts` => `15 passed`.
+
+- ✅ `P12.F2.T63` Iniciar SDD pendiente enterprise: extender `pumuki sdd sync-docs` con contexto explícito (`--change`, `--stage`, `--task`) y trazabilidad canónica (`#585`).
+  - cierre ejecutado:
+    - `runSddSyncDocs` amplía contrato con contexto explícito (`change`, `stage`, `task`) en salida canónica.
+    - `parseLifecycleCliArgs` soporta:
+      - `pumuki sdd sync-docs --change=<id> --stage=<stage> --task=<task-id> [--dry-run] [--json]`.
+    - `runLifecycleCli` propaga contexto al runtime y lo imprime en salida texto/json.
+    - cobertura de tests ampliada para parsing + ejecución `dry-run` + contrato JSON de contexto.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `31 passed, 0 failed`.
+
+- ✅ `P12.F2.T64` Continuar SDD pendiente enterprise: ampliar `sync-docs` a múltiples documentos canónicos y secciones gestionadas (`#587`).
+  - cierre ejecutado:
+    - `runSddSyncDocs` soporta objetivos múltiples (`targets`) con secciones gestionadas por archivo.
+    - actualización determinista por archivo/sección y salida con diffs por cada target.
+    - fail-safe preservado: conflicto en cualquier archivo aborta el sync antes de cualquier escritura parcial.
+    - cobertura de tests ampliada para:
+      - actualización multi-documento.
+      - garantía fail-safe sin escrituras parciales.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `33 passed, 0 failed`.
+
+- ✅ `P12.F2.T65` Continuar SDD pendiente enterprise: artefacto de aprendizaje machine-readable por change durante `sync-docs` (`#589`).
+  - cierre ejecutado:
+    - `runSddSyncDocs` incorpora contrato `learning` en salida con:
+      - `path`, `written`, `digest`, `artifact`.
+    - cuando se provee `--change`:
+      - `--dry-run`: no escribe archivo y retorna payload de aprendizaje.
+      - ejecución normal: persiste `openspec/changes/<change>/learning.json`.
+    - cobertura de tests ampliada para dry-run y persistencia real del artefacto.
+    - documentación mínima del esquema añadida en `docs/CONFIGURATION.md`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `34 passed, 0 failed`.
+
+- ✅ `P12.F2.T66` Continuar SDD pendiente enterprise: enriquecer `learning.json` con señales reales de gate/evidence (`#591`).
+  - cierre ejecutado:
+    - `runSddSyncDocs` incorpora señales deterministas de runtime para poblar:
+      - `failed_patterns`
+      - `successful_patterns`
+      - `gate_anomalies`
+    - el cálculo cubre casos `evidence missing/invalid/valid` y decisión SDD permitida/bloqueada.
+    - soporte explícito para inyectar lector de evidencia en tests (`evidenceReader`) sin romper contrato CLI.
+    - PR mergeada: `#593` (`commit 0da619a3804ec939bc33385cfc57032c195b4ee1`).
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `35 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+
+- ✅ `P12.F2.T67` Continuar SDD pendiente enterprise: hacer `rule_updates` accionable en `learning.json` (`#594`).
+  - cierre ejecutado:
+    - `runSddSyncDocs` ahora deriva `rule_updates` de señales de evidencia/gate (`missing`, `invalid`, `blocked`, `allowed`) de forma determinista.
+    - añadidas recomendaciones específicas por familia de señal (`evidence.*`, `ai-gate.*`, `sdd.*`, `snapshot.*`).
+    - ampliada cobertura en `syncDocs` para escenarios `invalid` y `allow` además de `blocked`/persistencia.
+    - documentación de contrato actualizada en `docs/CONFIGURATION.md`.
+    - PR mergeada: `#596` (`commit 51d894c8835c9b04cb57dd810197ac7fc3d0cd3e`).
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `37 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+
+- ✅ `P12.F2.T68` Continuar SDD pendiente enterprise: añadir comando dedicado `pumuki sdd learn` (`#597`).
+  - cierre ejecutado:
+    - nuevo runtime `runSddLearn` en capa SDD con salida/persistencia de `learning.json` sin depender de `sync-docs`.
+    - CLI ampliada con:
+      - `pumuki sdd learn --change=<id> --stage=<stage> --task=<task-id> [--dry-run] [--json]`.
+    - cobertura de regresión añadida en parser y ejecución (`cli.test.ts`) y documentación actualizada en `docs/CONFIGURATION.md`.
+    - PR mergeada: `#599` (`commit c971c643883ccce679c0c5cdb3363bdd6e6cace6`).
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `38 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+
+- ✅ `P12.F2.T69` Publicar release `6.3.35` con cierre SDD incremental.
+  - cierre ejecutado:
+    - versión incrementada a `6.3.35` en `package.json` y `package-lock.json`.
+    - release notes actualizadas con entrada `2026-03-04 (v6.3.35)` en `docs/RELEASE_NOTES.md`.
+    - publicación npm ejecutada con éxito (`npm publish --access public`).
+    - propagación validada:
+      - `npm view pumuki dist-tags --json` => `"latest": "6.3.35"`.
+      - smoke `@latest` en carpeta temporal mostrando `pumuki sdd learn ...` en `--help`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `38 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+    - `npm publish --access public` => `+ pumuki@6.3.35`.
+    - `npm view pumuki@6.3.35 version` => `6.3.35`.
+
+- ✅ `P12.F2.T70` Siguiente SDD pendiente enterprise: comando orquestador `pumuki sdd auto-sync` (`#600`).
+  - cierre ejecutado:
+    - nuevo runtime `runSddAutoSync` en capa SDD para orquestar `sync-docs` + `learning` en un único paso determinista.
+    - CLI ampliada con:
+      - `pumuki sdd auto-sync --change=<id> --stage=<stage> --task=<task-id> [--dry-run] [--json]`.
+    - cobertura de regresión añadida en `syncDocs`/`index`/`cli` y documentación actualizada en `docs/CONFIGURATION.md`.
+    - issue cerrada: `#600`.
+    - PR mergeada: `#602` (`commit 2be34c5`).
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/sdd/__tests__/syncDocs.test.ts integrations/sdd/__tests__/index.test.ts integrations/lifecycle/__tests__/cli.test.ts` => `44 passed, 0 failed`.
+    - `npm run -s typecheck` => `exit 0`.
+
+- 🚧 `P12.F2.T71` Publicar release `6.3.36` con `pumuki sdd auto-sync` (`#603`).
   - salida esperada:
-    - issue de release creada con alcance/doD verificable (`#578`).
-    - nueva versión npm publicada con rotación JSONL + profile contractual `telemetry-rotation`.
-    - trazabilidad cerrada en plan activo + registro maestro.
+    - versionado a `6.3.36` en `package.json`, `package-lock.json` y `VERSION`.
+    - release notes actualizadas con entrada `v6.3.36`.
+    - publicación npm validada (`latest=6.3.36`) + smoke de `--help` mostrando `auto-sync`.
 
 Criterio de salida F6:
 - veredicto final trazable y cierre administrativo completo.

package/integrations/evidence/schema.ts

@@ -91,6 +91,11 @@ export type RulesetState = {
   source?: string;
   validation_status?: 'valid' | 'invalid' | 'expired' | 'unknown-source';
   validation_code?: string;
+  degraded_mode_enabled?: boolean;
+  degraded_mode_action?: 'allow' | 'block';
+  degraded_mode_reason?: string;
+  degraded_mode_source?: 'env' | 'file:.pumuki/degraded-mode.json';
+  degraded_mode_code?: 'DEGRADED_MODE_ALLOWED' | 'DEGRADED_MODE_BLOCKED';
 };
 
 export type HumanIntentConfidence = 'high' | 'medium' | 'low' | 'unset';

package/integrations/gate/degradedMode.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type DegradedStage = 'PRE_WRITE' | 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+export type DegradedAction = 'allow' | 'block';
+export type DegradedCode = 'DEGRADED_MODE_ALLOWED' | 'DEGRADED_MODE_BLOCKED';
+
+export type DegradedResolution = {
+  enabled: true;
+  action: DegradedAction;
+  reason: string;
+  source: 'env' | 'file:.pumuki/degraded-mode.json';
+  code: DegradedCode;
+};
+
+const DEGRADED_MODE_FILE_PATH = '.pumuki/degraded-mode.json';
+
+const toBooleanFlag = (value: string | undefined): boolean | null => {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+    return true;
+  }
+  if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+    return false;
+  }
+  return null;
+};
+
+const toAction = (value: unknown): DegradedAction | null => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'allow') {
+    return 'allow';
+  }
+  if (normalized === 'block') {
+    return 'block';
+  }
+  return null;
+};
+
+const toCode = (action: DegradedAction): DegradedCode => {
+  return action === 'block' ? 'DEGRADED_MODE_BLOCKED' : 'DEGRADED_MODE_ALLOWED';
+};
+
+const resolveActionFromEnv = (stage: DegradedStage): DegradedAction => {
+  const stageKey = `PUMUKI_DEGRADED_ACTION_${stage}`;
+  const byStage = toAction(process.env[stageKey]);
+  if (byStage) {
+    return byStage;
+  }
+  const globalAction = toAction(process.env.PUMUKI_DEGRADED_ACTION);
+  if (globalAction) {
+    return globalAction;
+  }
+  return 'allow';
+};
+
+type DegradedModeFile = {
+  version?: unknown;
+  enabled?: unknown;
+  reason?: unknown;
+  action?: unknown;
+  stages?: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null;
+};
+
+const resolveFromFile = (
+  repoRoot: string,
+  stage: DegradedStage
+): DegradedResolution | undefined => {
+  const configPath = join(repoRoot, DEGRADED_MODE_FILE_PATH);
+  if (!existsSync(configPath)) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8')) as DegradedModeFile;
+    if (parsed.enabled !== true) {
+      return undefined;
+    }
+    const stageActions = isRecord(parsed.stages) ? parsed.stages : undefined;
+    const stageAction = stageActions ? toAction(stageActions[stage]) : null;
+    const globalAction = toAction(parsed.action);
+    const action = stageAction ?? globalAction ?? 'allow';
+    const reason =
+      typeof parsed.reason === 'string' && parsed.reason.trim().length > 0
+        ? parsed.reason.trim()
+        : 'degraded-mode';
+    return {
+      enabled: true,
+      action,
+      reason,
+      source: 'file:.pumuki/degraded-mode.json',
+      code: toCode(action),
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+export const resolveDegradedMode = (
+  stage: DegradedStage,
+  repoRoot: string = process.cwd()
+): DegradedResolution | undefined => {
+  const enabledFromEnv = toBooleanFlag(process.env.PUMUKI_DEGRADED_MODE);
+  if (enabledFromEnv === true) {
+    const action = resolveActionFromEnv(stage);
+    const reason =
+      process.env.PUMUKI_DEGRADED_REASON?.trim().length
+        ? process.env.PUMUKI_DEGRADED_REASON.trim()
+        : 'degraded-mode';
+    return {
+      enabled: true,
+      action,
+      reason,
+      source: 'env',
+      code: toCode(action),
+    };
+  }
+  if (enabledFromEnv === false) {
+    return undefined;
+  }
+  return resolveFromFile(repoRoot, stage);
+};

package/integrations/gate/stagePolicies.ts

@@ -10,6 +10,7 @@ import {
   loadSkillsPolicy,
 } from '../config/skillsPolicy';
 import type { SkillsStage } from '../config/skillsLock';
+import { resolveDegradedMode } from './degradedMode';
 
 const heuristicsPromotionStageAllowList = new Set<GateStage>([
   'PRE_COMMIT',
@@ -58,6 +59,13 @@ export type ResolvedStagePolicy = {
       message: string;
       strict: boolean;
     };
+    degraded?: {
+      enabled: true;
+      action: 'allow' | 'block';
+      reason: string;
+      source: 'env' | 'file:.pumuki/degraded-mode.json';
+      code: 'DEGRADED_MODE_ALLOWED' | 'DEGRADED_MODE_BLOCKED';
+    };
   };
 };
 
@@ -519,6 +527,7 @@ export const resolvePolicyForStage = (
   stage: SkillsStage,
   repoRoot: string = process.cwd()
 ): ResolvedStagePolicy => {
+  const degraded = resolveDegradedMode(stage, repoRoot);
   const hardModeState = resolveHardModeState(repoRoot);
   if (hardModeState.enabled) {
     const profileName = hardModeState.profileName;
@@ -553,6 +562,7 @@ export const resolvePolicyForStage = (
         signature: policyAsCode.signature,
         policySource: policyAsCode.policySource,
         validation: policyAsCode.validation,
+        ...(degraded ? { degraded } : {}),
       },
     };
   }
@@ -586,6 +596,7 @@ export const resolvePolicyForStage = (
         signature: policyAsCode.signature,
         policySource: policyAsCode.policySource,
         validation: policyAsCode.validation,
+        ...(degraded ? { degraded } : {}),
       },
     };
   }
@@ -621,6 +632,7 @@ export const resolvePolicyForStage = (
       signature: policyAsCode.signature,
       policySource: policyAsCode.policySource,
       validation: policyAsCode.validation,
+      ...(degraded ? { degraded } : {}),
     },
   };
 };

package/integrations/git/EvidenceService.ts

@@ -112,6 +112,15 @@ export class EvidenceService implements IEvidenceService {
               validation_code: params.policyTrace.validation.code,
             }
           : {}),
+        ...(params.policyTrace.degraded
+          ? {
+              degraded_mode_enabled: params.policyTrace.degraded.enabled,
+              degraded_mode_action: params.policyTrace.degraded.action,
+              degraded_mode_reason: params.policyTrace.degraded.reason,
+              degraded_mode_source: params.policyTrace.degraded.source,
+              degraded_mode_code: params.policyTrace.degraded.code,
+            }
+          : {}),
       });
     }
 

package/integrations/git/runPlatformGate.ts

@@ -366,6 +366,40 @@ const toPolicyAsCodeBlockingFinding = (params: {
   };
 };
 
+const toDegradedModeFinding = (params: {
+  stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
+  policyTrace?: ResolvedStagePolicy['trace'];
+}): Finding | undefined => {
+  const degraded = params.policyTrace?.degraded;
+  if (!degraded?.enabled) {
+    return undefined;
+  }
+  if (degraded.action === 'block') {
+    return {
+      ruleId: 'governance.degraded-mode.blocked',
+      severity: 'ERROR',
+      code: degraded.code,
+      message:
+        `Degraded mode is active at ${params.stage} with fail-closed action=block. ` +
+        `reason=${degraded.reason} source=${degraded.source}.`,
+      filePath: '.pumuki/degraded-mode.json',
+      matchedBy: 'DegradedModeGuard',
+      source: 'degraded-mode',
+    };
+  }
+  return {
+    ruleId: 'governance.degraded-mode.active',
+    severity: 'INFO',
+    code: degraded.code,
+    message:
+      `Degraded mode is active at ${params.stage} with fail-open action=allow. ` +
+      `reason=${degraded.reason} source=${degraded.source}.`,
+    filePath: '.pumuki/degraded-mode.json',
+    matchedBy: 'DegradedModeGuard',
+    source: 'degraded-mode',
+  };
+};
+
 const toGateWaiverAppliedFinding = (params: {
   stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
   waiver: Extract<GateWaiverResult, { kind: 'applied' }>['waiver'];
@@ -621,6 +655,16 @@ export async function runPlatformGate(params: {
           policyTrace: params.policyTrace,
         })
       : undefined;
+  const degradedModeFinding =
+    params.policy.stage === 'PRE_COMMIT' ||
+    params.policy.stage === 'PRE_PUSH' ||
+    params.policy.stage === 'CI'
+      ? toDegradedModeFinding({
+          stage: params.policy.stage,
+          policyTrace: params.policyTrace,
+        })
+      : undefined;
+  const degradedModeBlocks = params.policyTrace?.degraded?.action === 'block';
   const rulesCoverage = coverage
     ? {
       stage: params.policy.stage,
@@ -665,6 +709,7 @@ export async function runPlatformGate(params: {
   const effectiveFindings = sddBlockingFinding
     ? [
       sddBlockingFinding,
+      ...(degradedModeFinding ? [degradedModeFinding] : []),
       ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
       ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
       ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
@@ -678,8 +723,10 @@ export async function runPlatformGate(params: {
       || skillsScopeComplianceFinding
       || coverageBlockingFinding
       || policyAsCodeBlockingFinding
+      || degradedModeFinding
       || tddBddEvaluation.findings.length > 0
       ? [
+        ...(degradedModeFinding ? [degradedModeFinding] : []),
         ...(policyAsCodeBlockingFinding ? [policyAsCodeBlockingFinding] : []),
         ...(unsupportedSkillsMappingFinding ? [unsupportedSkillsMappingFinding] : []),
         ...(platformSkillsCoverageFinding ? [platformSkillsCoverageFinding] : []),
@@ -692,6 +739,7 @@ export async function runPlatformGate(params: {
   const decision = dependencies.evaluateGate([...effectiveFindings], params.policy);
   const baseGateOutcome =
     sddBlockingFinding ||
+    degradedModeBlocks ||
     policyAsCodeBlockingFinding ||
     unsupportedSkillsMappingFinding ||
     platformSkillsCoverageFinding ||

package/integrations/git/stageRunners.ts

@@ -120,11 +120,17 @@ const emitSuccessfulHookGateSummary = (params: {
     params.stage === 'PRE_COMMIT'
       ? PRE_COMMIT_EVIDENCE_MAX_AGE_SECONDS
       : PRE_PUSH_EVIDENCE_MAX_AGE_SECONDS;
+  const degradedSummary =
+    params.policyTrace.degraded?.enabled
+      ? ` degraded_mode=enabled degraded_action=${params.policyTrace.degraded.action}` +
+        ` degraded_reason=${params.policyTrace.degraded.reason}`
+      : '';
   params.dependencies.writeHookGateSummary(
     `[pumuki][hook-gate] stage=${params.stage} policy_bundle=${params.policyTrace.bundle} policy_hash=${params.policyTrace.hash}` +
       ` policy_version=${params.policyTrace.version ?? 'n/a'}` +
       ` policy_signature=${params.policyTrace.signature ?? 'n/a'}` +
       ` policy_source=${params.policyTrace.policySource ?? 'n/a'}` +
+      `${degradedSummary}` +
       ` decision=ALLOW evidence_kind=${evidence.kind} evidence_age_seconds=${evidenceAgeSeconds ?? 'n/a'} max_age_seconds=${maxAgeSeconds}`
   );
 };