pumuki 6.3.33 → 6.3.35

package/docs/CONFIGURATION.md

@@ -97,6 +97,101 @@ 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`.
+
 ## Gate telemetry export (optional)
 
 Structured telemetry output is disabled by default and can be enabled with environment variables:
@@ -104,6 +199,9 @@ Structured telemetry output is disabled by default and can be enabled with envir
 - `PUMUKI_TELEMETRY_JSONL_PATH`:
   - JSONL file path for `telemetry_event_v1` records.
   - Accepts absolute path or repo-relative path.
+- `PUMUKI_TELEMETRY_JSONL_MAX_BYTES`:
+  - Optional max size for JSONL file growth.
+  - When current file size plus next event exceeds this value, current file rotates to `<path>.1` before append.
 - `PUMUKI_TELEMETRY_OTEL_ENDPOINT`:
   - OTLP HTTP logs endpoint (`/v1/logs`).
 - `PUMUKI_TELEMETRY_OTEL_SERVICE_NAME`:
@@ -116,6 +214,21 @@ Notes:
 - You can enable JSONL only, OTel only, or both.
 - If unset, no telemetry export is attempted.
 - Gate execution remains deterministic even when OTel endpoint is unavailable (best-effort dispatch).
+- Rotation is opt-in; without `PUMUKI_TELEMETRY_JSONL_MAX_BYTES`, append behavior remains unchanged.
+
+Quick verification (JSONL):
+
+```bash
+PUMUKI_TELEMETRY_JSONL_PATH=.pumuki/artifacts/gate-telemetry.jsonl \
+  npx --yes --package pumuki@latest pumuki-pre-commit
+```
+
+Expected JSONL keys for enterprise audit ingestion:
+
+- `schema=telemetry_event_v1` with `schema_version=1.0`
+- `stage`, `gate_outcome`, `severity_counts`
+- `policy.bundle`, `policy.hash`, `policy.version`, `policy.signature`, `policy.policy_source`
+- `policy.validation_status`, `policy.validation_code` (when policy-as-code validation is available)
 
 ## Heuristic pilot flag
 

package/docs/RELEASE_NOTES.md

@@ -3,6 +3,53 @@
 This file tracks the active deterministic framework line used in this repository.
 Detailed commit history remains available through Git history (`git log` / `git show`).
 
+## 2026-03 (enterprise hardening updates)
+
+### 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:
+  - `pumuki doctor --deep --json` now includes explicit compatibility contract payload under `deep.contract`.
+  - New deep check id `compatibility-contract` validates the active contract for `pumuki/openspec/hooks/adapter`.
+- Traceability:
+  - implementation PR: `#563`
+  - release PR: `#567`
+- Consumer quick verification:
+  - `npx --yes --package pumuki@latest pumuki doctor --deep --json`
+  - expected signal in JSON:
+    - `deep.checks` contains an item with `id=compatibility-contract`
+    - `deep.contract.overall` resolves to `compatible` or `incompatible` deterministically
+
 ## 2026-02 (enterprise-refactor updates)
 
 ### 2026-02-27 (v6.3.24)

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.T55` (publicar patch release del contrato de compatibilidad `doctor --deep`, issue `#565`).
+- Última task cerrada (`✅`): `P12.F2.T68` (nuevo comando `pumuki sdd learn`, issue `#597`, PR `#599`).
+- Task activa (`🚧`): `P12.F2.T69` (publicar release `6.3.35` con cierre SDD incremental en npm).
 
 ## Historial resumido
 - No se mantienen MDs históricos de seguimiento en este repositorio.

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

@@ -1780,11 +1780,173 @@ Criterio de salida F5:
     - `npm run -s validation:contract-suite:enterprise -- --json`
     - `npm run -s validation:tracking-single-active`
 
-- 🚧 `P12.F2.T55` Publicar patch release con el contrato de compatibilidad de `doctor --deep` ya mergeado en `#563`.
+- ✅ `P12.F2.T55` Publicar patch release con el contrato de compatibilidad de `doctor --deep` ya mergeado en `#563`.
+  - cierre ejecutado:
+    - issue creada y cerrada: `#565`.
+    - rama release creada y mergeada: `release/6.3.33` -> `#567` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/567`).
+    - publicación npm completada: `pumuki@6.3.33`.
+    - commit de merge en `develop`: `6f36830`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/doctor.test.ts integrations/lifecycle/__tests__/cli.test.ts`
+    - `npm run -s typecheck`
+    - `npm run -s validation:contract-suite:enterprise -- --json`
+    - `npm run -s validation:package-manifest`
+    - `npm publish --access public`
+    - `npm view pumuki version` => `6.3.33`
+
+- ✅ `P12.F2.T56` Publicar documentación de adopción de `6.3.33` (release notes + verificación operativa rápida).
+  - cierre ejecutado:
+    - issue documental creada: `#568`.
+    - release notes actualizadas con sección `2026-03-04 (v6.3.33)` y comandos de verificación para consumidores.
+    - documentación operativa alineada con el release publicado `6.3.33`.
+  - evidencia:
+    - `docs/RELEASE_NOTES.md` incluye delta funcional de `doctor --deep` para `compatibility-contract`.
+    - `npm view pumuki version` => `6.3.33`
+    - `npm run -s validation:tracking-single-active`
+
+- ✅ `P12.F2.T57` Ejecutar siguiente mejora estratégica: export de telemetría de gates en JSONL determinista para auditoría enterprise.
+  - cierre ejecutado:
+    - issue creada y cerrada: `#569`.
+    - rama técnica creada y mergeada: `feature/569-telemetry-jsonl-audit-hardening` -> `#571` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/571`).
+    - commit de merge en `develop`: `b98ef25`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/telemetry/__tests__/gateTelemetry.test.ts`
+    - `npm run -s typecheck`
+    - `npm run -s validation:tracking-single-active`
+    - `docs/CONFIGURATION.md` actualizado con verificación operativa JSONL y claves esperadas.
+
+- ✅ `P12.F2.T58` Ejecutar siguiente mejora estratégica: rotación/guard de tamaño para telemetría JSONL en repos enterprise de larga duración.
+  - cierre ejecutado:
+    - issue creada y cerrada: `#572`.
+    - rama técnica creada y mergeada: `feature/572-telemetry-jsonl-rotation-guard` -> `#574` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/574`).
+    - commit de merge en `develop`: `b3a5b27`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test integrations/telemetry/__tests__/gateTelemetry.test.ts`
+    - `npm run -s typecheck`
+    - `npm run -s validation:tracking-single-active`
+    - `docs/CONFIGURATION.md` actualizado con `PUMUKI_TELEMETRY_JSONL_MAX_BYTES`.
+
+- ✅ `P12.F2.T59` Ejecutar siguiente mejora estratégica: cubrir la rotación JSONL en la suite contractual enterprise.
+  - cierre ejecutado:
+    - issue creada y cerrada: `#575`.
+    - rama técnica creada y mergeada: `feature/575-contract-suite-telemetry-rotation` -> `#577` (`https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/pull/577`).
+    - commit de merge en `develop`: `89e2045`.
+  - evidencia:
+    - `npx --yes tsx@4.21.0 --test scripts/__tests__/enterprise-contract-suite-contract.test.ts scripts/__tests__/enterprise-contract-suite-report-lib.test.ts scripts/__tests__/enterprise-contract-suite-args-lib.test.ts integrations/telemetry/__tests__/gateTelemetry.test.ts`
+    - `npm run -s typecheck`
+    - `npm run -s validation:contract-suite:enterprise -- --json`
+    - `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.
+  - 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.
   - salida esperada:
-    - issue de release creada con alcance/doD verificable (`#565`).
-    - versión npm nueva publicada con el fix de `#562`.
-    - trazabilidad cerrada en plan activo + registro maestro con evidencia de publicación.
+    - bump de versión (`package.json`, `package-lock.json`) + nota de release.
+    - publicación npm exitosa y verificación `npm view pumuki version`.
+    - smoke mínimo con `npx --yes --package pumuki@latest pumuki --help`.
 
 Criterio de salida F6:
 - veredicto final trazable y cierre administrativo completo.

package/docs/validation/README.md

@@ -16,6 +16,11 @@ Este directorio contiene solo documentación oficial y estable de validación pa
 - Master de seguimiento: `docs/registro-maestro-de-seguimiento.md`.
 - Plan activo: `docs/seguimiento-completo-validacion-ruralgo-03-03-2026.md`.
 - Suite contractual enterprise (MVP): `npm run -s validation:contract-suite:enterprise`.
+  - Perfiles activos del reporte JSON:
+    - `minimal`
+    - `block`
+    - `minimal-repeat`
+    - `telemetry-rotation`
 
 ## Política de higiene
 

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,
+            }
+          : {}),
       });
     }