pumuki 6.3.34 → 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:

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,37 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 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:

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.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

@@ -1838,11 +1838,115 @@ 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.
   - 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.
+    - 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/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}`
   );
 };

package/integrations/lifecycle/cli.ts

@@ -27,6 +27,7 @@ import {
   openSddSession,
   readSddStatus,
   refreshSddSession,
+  runSddLearn,
   runSddSyncDocs,
   type SddStage,
 } from '../sdd';
@@ -62,7 +63,7 @@ type LifecycleCommand =
   | 'adapter'
   | 'analytics';
 
-type SddCommand = 'status' | 'validate' | 'session' | 'sync-docs';
+type SddCommand = 'status' | 'validate' | 'session' | 'sync-docs' | 'learn';
 type LoopCommand = 'run' | 'status' | 'stop' | 'resume' | 'list' | 'export';
 type AnalyticsCommand = 'hotspots';
 type AnalyticsHotspotsCommand = 'report' | 'diagnose';
@@ -87,6 +88,13 @@ type ParsedArgs = {
   sddChangeId?: string;
   sddTtlMinutes?: number;
   sddSyncDocsDryRun?: boolean;
+  sddSyncDocsChange?: string;
+  sddSyncDocsStage?: SddStage;
+  sddSyncDocsTask?: string;
+  sddLearnDryRun?: boolean;
+  sddLearnChange?: string;
+  sddLearnStage?: SddStage;
+  sddLearnTask?: string;
   adapterCommand?: 'install';
   adapterAgent?: AdapterAgent;
   adapterDryRun?: boolean;
@@ -120,7 +128,8 @@ Pumuki lifecycle commands:
   pumuki sdd session --open --change=<change-id> [--ttl-minutes=<n>] [--json]
   pumuki sdd session --refresh [--ttl-minutes=<n>] [--json]
   pumuki sdd session --close [--json]
-  pumuki sdd sync-docs [--dry-run] [--json]
+  pumuki sdd sync-docs [--change=<change-id>] [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--dry-run] [--json]
+  pumuki sdd learn --change=<change-id> [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--dry-run] [--json]
 `.trim();
 
 const LOOP_RUN_POLICY: GatePolicy = {
@@ -420,6 +429,13 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let sddChangeId: ParsedArgs['sddChangeId'];
   let sddTtlMinutes: ParsedArgs['sddTtlMinutes'];
   let sddSyncDocsDryRun = false;
+  let sddSyncDocsChange: ParsedArgs['sddSyncDocsChange'];
+  let sddSyncDocsStage: ParsedArgs['sddSyncDocsStage'];
+  let sddSyncDocsTask: ParsedArgs['sddSyncDocsTask'];
+  let sddLearnDryRun = false;
+  let sddLearnChange: ParsedArgs['sddLearnChange'];
+  let sddLearnStage: ParsedArgs['sddLearnStage'];
+  let sddLearnTask: ParsedArgs['sddLearnTask'];
   let adapterCommand: ParsedArgs['adapterCommand'];
   let adapterAgent: ParsedArgs['adapterAgent'];
   let adapterDryRun = false;
@@ -598,7 +614,8 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
       subcommandRaw !== 'status' &&
       subcommandRaw !== 'validate' &&
       subcommandRaw !== 'session' &&
-      subcommandRaw !== 'sync-docs'
+      subcommandRaw !== 'sync-docs' &&
+      subcommandRaw !== 'learn'
     ) {
       throw new Error(`Unsupported SDD subcommand "${subcommandRaw}".\n\n${HELP_TEXT}`);
     }
@@ -610,18 +627,30 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         continue;
       }
       if (arg === '--dry-run') {
-        if (sddCommand !== 'sync-docs') {
-          throw new Error(`--dry-run is only supported with "pumuki sdd sync-docs".\n\n${HELP_TEXT}`);
+        if (sddCommand === 'sync-docs') {
+          sddSyncDocsDryRun = true;
+          continue;
         }
-        sddSyncDocsDryRun = true;
-        continue;
+        if (sddCommand === 'learn') {
+          sddLearnDryRun = true;
+          continue;
+        }
+        throw new Error(`--dry-run is only supported with "pumuki sdd sync-docs" or "pumuki sdd learn".\n\n${HELP_TEXT}`);
       }
       if (arg.startsWith('--stage=')) {
-        if (sddCommand !== 'validate') {
-          throw new Error(`--stage is only supported with "pumuki sdd validate".\n\n${HELP_TEXT}`);
+        if (sddCommand === 'validate') {
+          sddStage = parseSddStage(arg.slice('--stage='.length));
+          continue;
         }
-        sddStage = parseSddStage(arg.slice('--stage='.length));
-        continue;
+        if (sddCommand === 'sync-docs') {
+          sddSyncDocsStage = parseSddStage(arg.slice('--stage='.length));
+          continue;
+        }
+        if (sddCommand === 'learn') {
+          sddLearnStage = parseSddStage(arg.slice('--stage='.length));
+          continue;
+        }
+        throw new Error(`--stage is only supported with "pumuki sdd validate", "pumuki sdd sync-docs" or "pumuki sdd learn".\n\n${HELP_TEXT}`);
       }
       if (arg === '--open') {
         if (sddCommand !== 'session') {
@@ -645,11 +674,46 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         continue;
       }
       if (arg.startsWith('--change=')) {
-        if (sddCommand !== 'session') {
-          throw new Error(`--change is only supported with "pumuki sdd session".\n\n${HELP_TEXT}`);
+        if (sddCommand === 'session') {
+          sddChangeId = arg.slice('--change='.length).trim();
+          continue;
         }
-        sddChangeId = arg.slice('--change='.length).trim();
-        continue;
+        if (sddCommand === 'sync-docs') {
+          const changeValue = arg.slice('--change='.length).trim();
+          if (changeValue.length === 0) {
+            throw new Error(`Invalid --change value "${arg}".`);
+          }
+          sddSyncDocsChange = changeValue;
+          continue;
+        }
+        if (sddCommand === 'learn') {
+          const changeValue = arg.slice('--change='.length).trim();
+          if (changeValue.length === 0) {
+            throw new Error(`Invalid --change value "${arg}".`);
+          }
+          sddLearnChange = changeValue;
+          continue;
+        }
+        throw new Error(`--change is only supported with "pumuki sdd session", "pumuki sdd sync-docs" or "pumuki sdd learn".\n\n${HELP_TEXT}`);
+      }
+      if (arg.startsWith('--task=')) {
+        if (sddCommand === 'sync-docs') {
+          const taskValue = arg.slice('--task='.length).trim();
+          if (taskValue.length === 0) {
+            throw new Error(`Invalid --task value "${arg}".`);
+          }
+          sddSyncDocsTask = taskValue;
+          continue;
+        }
+        if (sddCommand === 'learn') {
+          const taskValue = arg.slice('--task='.length).trim();
+          if (taskValue.length === 0) {
+            throw new Error(`Invalid --task value "${arg}".`);
+          }
+          sddLearnTask = taskValue;
+          continue;
+        }
+        throw new Error(`--task is only supported with "pumuki sdd sync-docs" or "pumuki sdd learn".\n\n${HELP_TEXT}`);
       }
       if (arg.startsWith('--ttl-minutes=')) {
         if (sddCommand !== 'session') {
@@ -685,7 +749,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     if (sddCommand === 'sync-docs') {
       if (sddSessionAction || sddChangeId || typeof sddTtlMinutes === 'number') {
         throw new Error(
-          `"pumuki sdd sync-docs" only supports [--dry-run] [--json].\n\n${HELP_TEXT}`
+          `"pumuki sdd sync-docs" only supports [--change=<change-id>] [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--dry-run] [--json].\n\n${HELP_TEXT}`
         );
       }
       return {
@@ -694,6 +758,29 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         json,
         sddCommand,
         sddSyncDocsDryRun,
+        ...(sddSyncDocsChange ? { sddSyncDocsChange } : {}),
+        ...(sddSyncDocsStage ? { sddSyncDocsStage } : {}),
+        ...(sddSyncDocsTask ? { sddSyncDocsTask } : {}),
+      };
+    }
+    if (sddCommand === 'learn') {
+      if (sddSessionAction || sddChangeId || typeof sddTtlMinutes === 'number') {
+        throw new Error(
+          `"pumuki sdd learn" only supports --change=<change-id> [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--task=<task-id>] [--dry-run] [--json].\n\n${HELP_TEXT}`
+        );
+      }
+      if (!sddLearnChange || sddLearnChange.length === 0) {
+        throw new Error(`Missing --change=<change-id> for "pumuki sdd learn".\n\n${HELP_TEXT}`);
+      }
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        sddCommand,
+        sddLearnDryRun,
+        sddLearnChange,
+        ...(sddLearnStage ? { sddLearnStage } : {}),
+        ...(sddLearnTask ? { sddLearnTask } : {}),
       };
     }
 
@@ -1696,12 +1783,15 @@ export const runLifecycleCli = async (
           const syncResult = runSddSyncDocs({
             repoRoot: process.cwd(),
             dryRun: parsed.sddSyncDocsDryRun === true,
+            change: parsed.sddSyncDocsChange,
+            stage: parsed.sddSyncDocsStage,
+            task: parsed.sddSyncDocsTask,
           });
           if (parsed.json) {
             writeInfo(JSON.stringify(syncResult, null, 2));
           } else {
             writeInfo(
-              `[pumuki][sdd] sync-docs dry_run=${syncResult.dryRun ? 'yes' : 'no'} updated=${syncResult.updated ? 'yes' : 'no'} files=${syncResult.files.length}`
+              `[pumuki][sdd] sync-docs dry_run=${syncResult.dryRun ? 'yes' : 'no'} updated=${syncResult.updated ? 'yes' : 'no'} files=${syncResult.files.length} change=${syncResult.context.change ?? 'none'} stage=${syncResult.context.stage ?? 'none'} task=${syncResult.context.task ?? 'none'}`
             );
             for (const file of syncResult.files) {
               writeInfo(
@@ -1714,6 +1804,26 @@ export const runLifecycleCli = async (
           }
           return 0;
         }
+        if (parsed.sddCommand === 'learn') {
+          const learnResult = runSddLearn({
+            repoRoot: process.cwd(),
+            dryRun: parsed.sddLearnDryRun === true,
+            change: parsed.sddLearnChange,
+            stage: parsed.sddLearnStage,
+            task: parsed.sddLearnTask,
+          });
+          if (parsed.json) {
+            writeInfo(JSON.stringify(learnResult, null, 2));
+          } else {
+            writeInfo(
+              `[pumuki][sdd] learn dry_run=${learnResult.dryRun ? 'yes' : 'no'} change=${learnResult.context.change} stage=${learnResult.context.stage ?? 'none'} task=${learnResult.context.task ?? 'none'} written=${learnResult.learning.written ? 'yes' : 'no'} digest=${learnResult.learning.digest}`
+            );
+            writeInfo(
+              `[pumuki][sdd] learning_path=${learnResult.learning.path} failed=${learnResult.learning.artifact.failed_patterns.length} successful=${learnResult.learning.artifact.successful_patterns.length} anomalies=${learnResult.learning.artifact.gate_anomalies.length} updates=${learnResult.learning.artifact.rule_updates.length}`
+            );
+          }
+          return 0;
+        }
         return 0;
       }
       case 'adapter': {

package/integrations/sdd/index.ts

@@ -9,4 +9,4 @@ export type {
 } from './types';
 export { evaluateSddPolicy, readSddStatus } from './policy';
 export { closeSddSession, openSddSession, readSddSession, refreshSddSession } from './sessionStore';
-export { runSddSyncDocs } from './syncDocs';
+export { runSddLearn, runSddSyncDocs } from './syncDocs';

package/integrations/sdd/policy.ts

@@ -8,6 +8,7 @@ import {
   validateOpenSpecChanges,
 } from './openSpecCli';
 import { readSddSession, refreshSddSession } from './sessionStore';
+import { resolveDegradedMode } from '../gate/degradedMode';
 import type {
   SddDecision,
   SddEvaluateResult,
@@ -208,6 +209,42 @@ export const evaluateSddPolicy = (params: {
     };
   }
 
+  const degradedMode = resolveDegradedMode(params.stage, repoRoot);
+  if (degradedMode?.action === 'block') {
+    return {
+      stage: params.stage,
+      status,
+      decision: blocked(
+        'SDD_DEGRADED_MODE_BLOCKED',
+        `SDD blocked by degraded mode (action=block). reason=${degradedMode.reason} source=${degradedMode.source}.`,
+        {
+          degraded_mode: true,
+          degraded_action: degradedMode.action,
+          degraded_reason: degradedMode.reason,
+          degraded_source: degradedMode.source,
+          degraded_code: degradedMode.code,
+        }
+      ),
+    };
+  }
+
+  if (degradedMode?.action === 'allow') {
+    return {
+      stage: params.stage,
+      status,
+      decision: allowed(
+        `SDD allowed in degraded mode (action=allow). reason=${degradedMode.reason} source=${degradedMode.source}.`,
+        {
+          degraded_mode: true,
+          degraded_action: degradedMode.action,
+          degraded_reason: degradedMode.reason,
+          degraded_source: degradedMode.source,
+          degraded_code: degradedMode.code,
+        }
+      ),
+    };
+  }
+
   if (!status.openspec.installed) {
     return {
       stage: params.stage,

package/integrations/sdd/syncDocs.ts

@@ -1,11 +1,9 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { readEvidenceResult, type EvidenceReadResult } from '../evidence/readEvidence';
 import { readSddStatus } from './policy';
-
-export const SDD_SYNC_DOCS_CANONICAL_FILES = [
-  'docs/technical/08-validation/refactor/pumuki-integration-feedback.md',
-] as const;
+import type { SddStage } from './types';
 
 const SDD_STATUS_SECTION = {
   id: 'sdd-status',
@@ -21,6 +19,18 @@ type ManagedSectionSyncResult = {
   diffMarkdown: string;
 };
 
+export type SddSyncDocsManagedSection = {
+  id: string;
+  beginMarker: string;
+  endMarker: string;
+  renderBody: (repoRoot: string) => string;
+};
+
+export type SddSyncDocsTarget = {
+  path: string;
+  sections: ReadonlyArray<SddSyncDocsManagedSection>;
+};
+
 export type SddSyncDocsFileResult = {
   path: string;
   updated: boolean;
@@ -34,8 +44,45 @@ export type SddSyncDocsResult = {
   command: 'pumuki sdd sync-docs';
   dryRun: boolean;
   repoRoot: string;
+  context: {
+    change: string | null;
+    stage: SddStage | null;
+    task: string | null;
+  };
   updated: boolean;
   files: ReadonlyArray<SddSyncDocsFileResult>;
+  learning?: {
+    path: string;
+    written: boolean;
+    digest: string;
+    artifact: {
+      version: '1.0';
+      change_id: string;
+      stage: SddStage | null;
+      task: string | null;
+      generated_at: string;
+      failed_patterns: string[];
+      successful_patterns: string[];
+      rule_updates: string[];
+      gate_anomalies: string[];
+      sync_docs: {
+        updated: boolean;
+        file_paths: string[];
+      };
+    };
+  };
+};
+
+export type SddLearnResult = {
+  command: 'pumuki sdd learn';
+  dryRun: boolean;
+  repoRoot: string;
+  context: {
+    change: string;
+    stage: SddStage | null;
+    task: string | null;
+  };
+  learning: NonNullable<SddSyncDocsResult['learning']>;
 };
 
 const normalizeSectionBody = (value: string): string => value.trim().replace(/\r\n/g, '\n');
@@ -86,6 +133,24 @@ const formatSddStatusManagedBody = (repoRoot: string): string => {
   ].join('\n');
 };
 
+const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+  {
+    path: 'docs/technical/08-validation/refactor/pumuki-integration-feedback.md',
+    sections: [
+      {
+        id: SDD_STATUS_SECTION.id,
+        beginMarker: SDD_STATUS_SECTION.begin,
+        endMarker: SDD_STATUS_SECTION.end,
+        renderBody: formatSddStatusManagedBody,
+      },
+    ],
+  },
+];
+
+export const SDD_SYNC_DOCS_CANONICAL_FILES = DEFAULT_SYNC_DOCS_TARGETS.map(
+  (target) => target.path
+);
+
 const applyManagedSection = (params: {
   filePath: string;
   source: string;
@@ -132,38 +197,124 @@ const applyManagedSection = (params: {
   return { nextSource, result };
 };
 
+const toSortedArray = (set: Set<string>): string[] => {
+  return [...set].sort((left, right) => left.localeCompare(right));
+};
+
+const collectLearningSignals = (params: {
+  updated: boolean;
+  evidenceResult: EvidenceReadResult;
+}): {
+  failedPatterns: string[];
+  successfulPatterns: string[];
+  gateAnomalies: string[];
+  ruleUpdates: string[];
+} => {
+  const failedPatterns = new Set<string>();
+  const successfulPatterns = new Set<string>();
+  const gateAnomalies = new Set<string>();
+  const ruleUpdates = new Set<string>();
+
+  successfulPatterns.add('sync-docs.completed');
+  successfulPatterns.add(params.updated ? 'sync-docs.updated' : 'sync-docs.no_changes');
+
+  if (params.evidenceResult.kind === 'missing') {
+    gateAnomalies.add('evidence.missing');
+    ruleUpdates.add('evidence.bootstrap.required');
+  } else if (params.evidenceResult.kind === 'invalid') {
+    gateAnomalies.add(`evidence.invalid.${params.evidenceResult.reason}`);
+    ruleUpdates.add('evidence.rebuild.required');
+    if (params.evidenceResult.reason === 'schema') {
+      ruleUpdates.add('evidence.schema.repair');
+    }
+    if (params.evidenceResult.reason === 'evidence-chain-invalid') {
+      ruleUpdates.add('evidence.chain.repair');
+    }
+  } else {
+    const evidence = params.evidenceResult.evidence;
+    if (evidence.ai_gate.status === 'BLOCKED') {
+      failedPatterns.add('ai-gate.blocked');
+      ruleUpdates.add('ai-gate.unblock.required');
+      for (const violation of evidence.ai_gate.violations) {
+        gateAnomalies.add(`ai-gate.violation.${violation.code}`);
+        ruleUpdates.add(`ai-gate.violation.${violation.code}.review`);
+      }
+    } else {
+      successfulPatterns.add('ai-gate.allowed');
+    }
+    if (evidence.snapshot.outcome === 'BLOCK') {
+      gateAnomalies.add('snapshot.outcome.block');
+      ruleUpdates.add('snapshot.outcome.review');
+    }
+    const sddDecision = evidence.sdd_metrics?.decision;
+    if (sddDecision) {
+      if (sddDecision.allowed) {
+        successfulPatterns.add('sdd.allowed');
+      } else {
+        failedPatterns.add(`sdd.blocked.${sddDecision.code}`);
+        ruleUpdates.add(`sdd.${sddDecision.code}.remediate`);
+      }
+    }
+  }
+
+  return {
+    failedPatterns: toSortedArray(failedPatterns),
+    successfulPatterns: toSortedArray(successfulPatterns),
+    gateAnomalies: toSortedArray(gateAnomalies),
+    ruleUpdates: toSortedArray(ruleUpdates),
+  };
+};
+
 export const runSddSyncDocs = (params?: {
   repoRoot?: string;
   dryRun?: boolean;
+  change?: string;
+  stage?: SddStage;
+  task?: string;
+  targets?: ReadonlyArray<SddSyncDocsTarget>;
+  now?: () => Date;
+  evidenceReader?: (repoRoot: string) => EvidenceReadResult;
 }): SddSyncDocsResult => {
   const repoRoot = resolve(params?.repoRoot ?? process.cwd());
   const dryRun = params?.dryRun === true;
+  const change = params?.change?.trim() ? params.change.trim() : null;
+  const stage = params?.stage ?? null;
+  const task = params?.task?.trim() ? params.task.trim() : null;
+  const targets = params?.targets ?? DEFAULT_SYNC_DOCS_TARGETS;
+  const now = params?.now ?? (() => new Date());
+  const evidenceReader = params?.evidenceReader ?? readEvidenceResult;
 
-  const updates = SDD_SYNC_DOCS_CANONICAL_FILES.map((relativePath) => {
-    const absolutePath = resolve(repoRoot, relativePath);
+  const updates = targets.map((target) => {
+    const absolutePath = resolve(repoRoot, target.path);
     if (!existsSync(absolutePath)) {
       throw new Error(
-        `[pumuki][sdd] sync-docs missing canonical file: ${relativePath}`
+        `[pumuki][sdd] sync-docs missing canonical file: ${target.path}`
       );
     }
 
     const currentSource = readFileSync(absolutePath, 'utf8');
-    const renderedStatusBody = formatSddStatusManagedBody(repoRoot);
-    const sectionUpdate = applyManagedSection({
-      filePath: relativePath,
-      source: currentSource,
-      beginMarker: SDD_STATUS_SECTION.begin,
-      endMarker: SDD_STATUS_SECTION.end,
-      renderedBody: renderedStatusBody,
-      sectionId: SDD_STATUS_SECTION.id,
-    });
+    let nextSource = currentSource;
+    const sectionUpdates: ManagedSectionSyncResult[] = [];
+
+    for (const section of target.sections) {
+      const update = applyManagedSection({
+        filePath: target.path,
+        source: nextSource,
+        beginMarker: section.beginMarker,
+        endMarker: section.endMarker,
+        renderedBody: section.renderBody(repoRoot),
+        sectionId: section.id,
+      });
+      nextSource = update.nextSource;
+      sectionUpdates.push(update.result);
+    }
 
     return {
-      relativePath,
+      relativePath: target.path,
       absolutePath,
       currentSource,
-      nextSource: sectionUpdate.nextSource,
-      sections: [sectionUpdate.result] as const,
+      nextSource,
+      sections: sectionUpdates,
     };
   });
 
@@ -188,11 +339,97 @@ export const runSddSyncDocs = (params?: {
     }),
   }));
 
+  const updated = files.some((file) => file.updated);
+  let learning: SddSyncDocsResult['learning'];
+  if (change) {
+    const signals = collectLearningSignals({
+      updated,
+      evidenceResult: evidenceReader(repoRoot),
+    });
+    const artifact = {
+      version: '1.0' as const,
+      change_id: change,
+      stage,
+      task,
+      generated_at: now().toISOString(),
+      failed_patterns: signals.failedPatterns,
+      successful_patterns: signals.successfulPatterns,
+      rule_updates: signals.ruleUpdates,
+      gate_anomalies: signals.gateAnomalies,
+      sync_docs: {
+        updated,
+        file_paths: files.map((file) => file.path),
+      },
+    };
+    const relativePath = `openspec/changes/${change}/learning.json`;
+    const absolutePath = resolve(repoRoot, relativePath);
+    const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
+    const digest = computeDigest(serialized);
+    if (!dryRun) {
+      mkdirSync(dirname(absolutePath), { recursive: true });
+      writeFileSync(absolutePath, serialized, 'utf8');
+    }
+    learning = {
+      path: relativePath,
+      written: !dryRun,
+      digest,
+      artifact,
+    };
+  }
+
   return {
     command: 'pumuki sdd sync-docs',
     dryRun,
     repoRoot,
-    updated: files.some((file) => file.updated),
+    context: {
+      change,
+      stage,
+      task,
+    },
+    updated,
     files,
+    ...(learning ? { learning } : {}),
+  };
+};
+
+export const runSddLearn = (params?: {
+  repoRoot?: string;
+  dryRun?: boolean;
+  change?: string;
+  stage?: SddStage;
+  task?: string;
+  now?: () => Date;
+  evidenceReader?: (repoRoot: string) => EvidenceReadResult;
+}): SddLearnResult => {
+  const change = params?.change?.trim();
+  if (!change) {
+    throw new Error('[pumuki][sdd] learn requires --change=<change-id>.');
+  }
+
+  const result = runSddSyncDocs({
+    repoRoot: params?.repoRoot,
+    dryRun: params?.dryRun,
+    change,
+    stage: params?.stage,
+    task: params?.task,
+    now: params?.now,
+    evidenceReader: params?.evidenceReader,
+    targets: [],
+  });
+
+  if (!result.learning) {
+    throw new Error('[pumuki][sdd] learn could not generate learning artifact.');
+  }
+
+  return {
+    command: 'pumuki sdd learn',
+    dryRun: result.dryRun,
+    repoRoot: result.repoRoot,
+    context: {
+      change,
+      stage: result.context.stage,
+      task: result.context.task,
+    },
+    learning: result.learning,
   };
 };

package/integrations/sdd/types.ts

@@ -12,6 +12,7 @@ export type SddDecisionCode =
   | 'SDD_VALIDATION_FAILED'
   | 'SDD_VALIDATION_ERROR'
   | 'SDD_VALIDATION_EMPTY_SCOPE'
+  | 'SDD_DEGRADED_MODE_BLOCKED'
   | 'SDD_CHANGE_INCOMPLETE';
 
 export type SddDecision = {

package/integrations/telemetry/gateTelemetry.ts

@@ -28,6 +28,13 @@ type PolicyTrace = ResolvedStagePolicy['trace'] & {
     status: 'valid' | 'invalid' | 'expired' | 'unknown-source';
     code: string;
   };
+  degraded?: {
+    enabled: true;
+    action: 'allow' | 'block';
+    reason: string;
+    source: 'env' | 'file:.pumuki/degraded-mode.json';
+    code: 'DEGRADED_MODE_ALLOWED' | 'DEGRADED_MODE_BLOCKED';
+  };
 };
 
 const toSeverityCounts = (
@@ -184,6 +191,11 @@ export type GateTelemetryEventV1 = {
     policy_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';
   };
   sdd?: {
     allowed: boolean;
@@ -267,6 +279,15 @@ const toTelemetryEvent = (params: {
               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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.34",
+  "version": "6.3.35",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {