pumuki 6.3.22 → 6.3.24

package/README.md

@@ -1,6 +1,6 @@
 # Pumuki
 
-![Pumuki](assets/logo_banner.png)
+<img src="assets/logo.png" alt="Pumuki" width="100%" />
 
 [![npm version](https://img.shields.io/npm/v/pumuki?color=1d4ed8)](https://www.npmjs.com/package/pumuki)
 [![CI](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/SwiftEnProfundidad/ast-intelligence-hooks/actions/workflows/ci.yml)
@@ -46,6 +46,13 @@ npx --yes pumuki sdd session --open --change=<change-id>
 npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ```
 
+Optional loop runner session (local, deterministic):
+
+```bash
+npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
+npx --yes pumuki loop list --json
+```
+
 Run local gates:
 
 ```bash
@@ -180,6 +187,17 @@ npx --yes pumuki sdd session --close
 npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ```
 
+### Loop Runner (Consumer)
+
+```bash
+npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
+npx --yes pumuki loop status --session=<session-id> --json
+npx --yes pumuki loop stop --session=<session-id> --json
+npx --yes pumuki loop resume --session=<session-id> --json
+npx --yes pumuki loop list --json
+npx --yes pumuki loop export --session=<session-id> --output-json=.audit-reports/loop-session.json
+```
+
 ### Stage Gates (Consumer)
 
 ```bash

package/VERSION

@@ -1 +1 @@
-v6.3.21
+v6.3.24

package/docs/REFRACTOR_PROGRESS.md

@@ -119,8 +119,49 @@ Fuente unica de seguimiento operativo. No se abren nuevos MDs temporales de trac
     - PR `#451` (`docs/readme-enterprise-reliability-followup` -> `develop`) merged.
     - PR `#452` (`release/6.3.21` -> `develop`) merged.
     - PR `#453` (`develop` -> `main`) merged.
-- 🚧 `P3.T17` Hotfix visual definitivo de hero + bump `6.3.22` + cierre GitFlow + publicación npm.
-  - objetivo: forzar render full-width estable en GitHub y npm usando asset raster (`assets/logo_banner.png`) y referencia directa en README.
+- ✅ `P3.T17` Hotfix visual definitivo de hero + bump `6.3.22` + cierre GitFlow + publicación npm completados.
+  - render hero estabilizado para npm/GitHub con asset raster (`assets/logo_banner.png`) y referencia directa markdown en `README.md`.
+  - versión publicada: `pumuki@6.3.22`
+  - evidencia npm: `npm publish --access public` en verde; `npm view pumuki version dist-tags --json` => `latest: 6.3.22`
+  - cierre GitFlow:
+    - PR `#456` (`docs/readme-banner-fullwidth-png-6-3-22` -> `develop`) merged.
+    - PR `#457` (`develop` -> `main`) merged.
+  - sincronización final: `main`, `develop`, `origin/main`, `origin/develop` alineadas en `40a6872`.
+- ✅ `P3.T18` Restauración visual del hero al estilo previo estable del grafo y publicación `v6.3.23` completadas.
+  - hero raíz restaurado a imagen clásica full-width: `<img src="assets/logo.png" alt="Pumuki" width="100%" />`.
+  - versión publicada: `pumuki@6.3.23`
+  - evidencia npm: `npm publish --access public` en verde; `npm view pumuki version dist-tags --json` => `latest: 6.3.23`
+- ✅ `P3.T19` Standby post-release `6.3.23` cerrado por validación explícita del usuario.
+- ✅ `P3.T20` Cierre administrativo final del bloque `P3` en modo espera operativa (sin cambios funcionales pendientes).
+
+### Fase P4 — Integración `loop runner` local (inspiración Ralph Loop, tool-agnostic)
+- ✅ `P4.T1` Definir contrato local de sesión de loop (estado, intentos, límites y transiciones) y sus fixtures de test.
+  - implementación: `integrations/lifecycle/loopSessionContract.ts` (`create/parse/transition`).
+  - tests RED->GREEN: `integrations/lifecycle/__tests__/loopSessionContract.test.ts`.
+- ✅ `P4.T2` Implementar store determinista local de sesiones loop (`.pumuki/loop-sessions`) con operaciones `create/read/update/list`.
+  - implementación: `integrations/lifecycle/loopSessionStore.ts`.
+  - validación: `integrations/lifecycle/__tests__/loopSessionStore.test.ts` en verde.
+- ✅ `P4.T3` Integrar comando CLI `pumuki loop` (`run|status|stop|resume|list|export`) con parseo estricto.
+  - implementación: `integrations/lifecycle/cli.ts` (`parseLifecycleCliArgs` + `runLifecycleCli` loop commands).
+  - validación: `integrations/lifecycle/__tests__/cli.test.ts` (subcomandos loop parse/runtime).
+- ✅ `P4.T4` Acoplar ejecución de `loop run` al gate (`runPlatformGate`) con política fail-fast y evidencia por intento.
+  - implementación: `integrations/lifecycle/cli.ts` (`LOOP_RUN_POLICY`, intento gate por `workingTree`, evidencia `.attempt-<n>.json`).
+  - validación: test de bloqueo fail-fast en `integrations/lifecycle/__tests__/cli.test.ts`.
+- ✅ `P4.T5` Completar suite TDD end-to-end (`parse + store + runtime`) y validación de typecheck.
+  - tests en verde: `npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/loopSessionContract.test.ts integrations/lifecycle/__tests__/loopSessionStore.test.ts integrations/lifecycle/__tests__/cli.test.ts`.
+  - typecheck en verde: `npm run typecheck`.
+- ✅ `P4.T6` Consolidar documentación estable (`README/docs`) y cierre técnico del bloque P4.
+  - documentación actualizada: `README.md`, `docs/USAGE.md` (sección `loop` + semántica fail-fast + evidencia).
+- ✅ `P4.T7` Revalidación global post-P4 ejecutada y fix de no-determinismo temporal en waiver TDD/BDD aplicado.
+  - fix aplicado: `integrations/git/__tests__/tddBddEnforcement.test.ts` (`expires_at` en futuro estable).
+  - validación en verde:
+    - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/tddBddEnforcement.test.ts`
+    - `npm test`
+- ✅ `P4.T8` Cierre GitFlow post-P4 (feature -> develop -> main) y sincronización final.
+  - PR `#462` merged (`feature/p4-loop-runner-core` -> `develop`).
+  - PR `#463` merged (`develop` -> `main`, merge admin por policy de rama).
+  - sincronización final completada con `main` y `develop` alineadas.
+- 🚧 `P4.T9` Release de cierre post-P4 (`v6.3.24`): bump de versión, validación final y publicación npm.
 
 ## Plan Por Fases (Ciclo 014)
 Plan base visible para seguimiento previo y durante la implementacion.

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,25 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-02 (enterprise-refactor updates)
 
+### 2026-02-27 (v6.3.24)
+
+- Lifecycle loop runner (local deterministic mode):
+  - Added `pumuki loop` command surface (`run/status/stop/resume/list/export`).
+  - Added session contract + store for deterministic state transitions and persistence.
+- Gate integration:
+  - `loop run` now executes one strict fail-fast gate attempt on `workingTree`.
+  - Per-attempt evidence is emitted to `.pumuki/loop-sessions/<session-id>.attempt-<n>.json`.
+- Stability and governance:
+  - Fixed time-based flake in waiver enforcement test by using stable future expiry.
+  - Synced `VERSION` to package release line.
+  - Documentation updated in `README.md` and `docs/USAGE.md`.
+
+### 2026-02-27 (v6.3.23)
+
+- README visual rollback to the previous stable style from git history:
+  - root hero restored to classic logo image at full width:
+    - `<img src="assets/logo.png" alt="Pumuki" width="100%" />`
+
 ### 2026-02-27 (v6.3.22)
 
 - README hero render compatibility fix:

package/docs/USAGE.md

@@ -223,7 +223,7 @@ npx --yes pumuki-ci
 npx --yes pumuki-pre-write
 ```
 
-### 2.1) Lifecycle + SDD CLI (install / uninstall / remove / update / doctor / status / sdd)
+### 2.1) Lifecycle + SDD + Loop CLI (install / uninstall / remove / update / doctor / status / sdd / loop)
 
 Canonical npm package commands:
 
@@ -260,6 +260,14 @@ npx --yes pumuki sdd session --close
 npx --yes pumuki analytics hotspots report --top=10 --since-days=90 --json
 npx --yes pumuki analytics hotspots diagnose --json
 
+# local deterministic loop sessions (fail-fast gate per attempt)
+npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
+npx --yes pumuki loop status --session=<session-id> --json
+npx --yes pumuki loop stop --session=<session-id> --json
+npx --yes pumuki loop resume --session=<session-id> --json
+npx --yes pumuki loop list --json
+npx --yes pumuki loop export --session=<session-id> --output-json=.audit-reports/loop-session.json
+
 # update dependency to latest and re-apply hooks
 npx --yes pumuki update --latest
 
@@ -285,6 +293,12 @@ npm run skills:import:custom -- --source /abs/path/to/SKILL.md --source ./skills
 When no modules remain, it also prunes orphan `node_modules/.package-lock.json` residue.
 Plain `npm uninstall pumuki` removes only the dependency; it does not remove managed hooks or lifecycle state.
 
+Loop runtime behavior:
+- `pumuki loop run` creates a session in `.pumuki/loop-sessions/`.
+- Each run executes one gate attempt on `workingTree`.
+- Gate policy is strict fail-fast: a blocked attempt returns exit code `1` and status `blocked`.
+- Per-attempt evidence is persisted as `.pumuki/loop-sessions/<session-id>.attempt-<n>.json`.
+
 OpenSpec integration behavior:
 - `pumuki install` auto-bootstraps OpenSpec (`@fission-ai/openspec`) when missing/incompatible and scaffolds `openspec/` project baseline when absent.
 - `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` before hook reinstall.

package/integrations/lifecycle/cli.ts

@@ -1,5 +1,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import type { GatePolicy } from '../../core/gate/GatePolicy';
+import { runPlatformGate } from '../git/runPlatformGate';
 import { runLifecycleDoctor, type LifecycleDoctorReport } from './doctor';
 import { runLifecycleInstall } from './install';
 import { runLifecycleRemove } from './remove';
@@ -7,6 +9,13 @@ import { readLifecycleStatus } from './status';
 import { runLifecycleUninstall } from './uninstall';
 import { runLifecycleUpdate } from './update';
 import { runLifecycleAdapterInstall, type AdapterAgent } from './adapter';
+import { createLoopSessionContract, isLoopSessionTransitionAllowed } from './loopSessionContract';
+import {
+  createLoopSession,
+  listLoopSessions,
+  readLoopSession,
+  updateLoopSession,
+} from './loopSessionStore';
 import {
   closeSddSession,
   evaluateSddPolicy,
@@ -34,11 +43,13 @@ type LifecycleCommand =
   | 'update'
   | 'doctor'
   | 'status'
+  | 'loop'
   | 'sdd'
   | 'adapter'
   | 'analytics';
 
 type SddCommand = 'status' | 'validate' | 'session';
+type LoopCommand = 'run' | 'status' | 'stop' | 'resume' | 'list' | 'export';
 type AnalyticsCommand = 'hotspots';
 type AnalyticsHotspotsCommand = 'report' | 'diagnose';
 
@@ -50,6 +61,11 @@ type ParsedArgs = {
   updateSpec?: string;
   json: boolean;
   sddCommand?: SddCommand;
+  loopCommand?: LoopCommand;
+  loopSessionId?: string;
+  loopObjective?: string;
+  loopMaxAttempts?: number;
+  loopOutputJsonPath?: string;
   sddStage?: SddStage;
   sddSessionAction?: SddSessionAction;
   sddChangeId?: string;
@@ -73,6 +89,12 @@ Pumuki lifecycle commands:
   pumuki update [--latest|--spec=<package-spec>]
   pumuki doctor
   pumuki status
+  pumuki loop run --objective=<text> [--max-attempts=<n>] [--json]
+  pumuki loop status --session=<session-id> [--json]
+  pumuki loop stop --session=<session-id> [--json]
+  pumuki loop resume --session=<session-id> [--json]
+  pumuki loop list [--json]
+  pumuki loop export --session=<session-id> [--output-json=<path>] [--json]
   pumuki adapter install --agent=<name> [--dry-run] [--json]
   pumuki analytics hotspots report [--top=<n>] [--since-days=<n>] [--json] [--output-json=<path>] [--output-markdown=<path>]
   pumuki analytics hotspots diagnose [--json]
@@ -83,6 +105,12 @@ Pumuki lifecycle commands:
   pumuki sdd session --close [--json]
 `.trim();
 
+const LOOP_RUN_POLICY: GatePolicy = {
+  stage: 'STAGED',
+  blockOnOrAbove: 'ERROR',
+  warnOnOrAbove: 'WARN',
+};
+
 const writeInfo = (message: string): void => {
   process.stdout.write(`${message}\n`);
 };
@@ -105,6 +133,7 @@ const isLifecycleCommand = (value: string): value is LifecycleCommand =>
   value === 'update' ||
   value === 'doctor' ||
   value === 'status' ||
+  value === 'loop' ||
   value === 'sdd' ||
   value === 'adapter' ||
   value === 'analytics';
@@ -361,6 +390,11 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
   let updateSpec: ParsedArgs['updateSpec'];
   let json = false;
   let sddCommand: ParsedArgs['sddCommand'];
+  let loopCommand: ParsedArgs['loopCommand'];
+  let loopSessionId: ParsedArgs['loopSessionId'];
+  let loopObjective: ParsedArgs['loopObjective'];
+  let loopMaxAttempts: ParsedArgs['loopMaxAttempts'];
+  let loopOutputJsonPath: ParsedArgs['loopOutputJsonPath'];
   let sddStage: ParsedArgs['sddStage'];
   let sddSessionAction: ParsedArgs['sddSessionAction'];
   let sddChangeId: ParsedArgs['sddChangeId'];
@@ -447,6 +481,96 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     return parsedAnalyticsArgs;
   }
 
+  if (commandRaw === 'loop') {
+    const subcommandRaw = argv[1] ?? '';
+    if (
+      subcommandRaw !== 'run' &&
+      subcommandRaw !== 'status' &&
+      subcommandRaw !== 'stop' &&
+      subcommandRaw !== 'resume' &&
+      subcommandRaw !== 'list' &&
+      subcommandRaw !== 'export'
+    ) {
+      throw new Error(`Unsupported loop subcommand "${subcommandRaw}".\n\n${HELP_TEXT}`);
+    }
+    loopCommand = subcommandRaw;
+    for (const arg of argv.slice(2)) {
+      if (arg === '--json') {
+        json = true;
+        continue;
+      }
+      if (arg.startsWith('--session=')) {
+        loopSessionId = arg.slice('--session='.length).trim();
+        continue;
+      }
+      if (arg.startsWith('--objective=')) {
+        loopObjective = arg.slice('--objective='.length).trim();
+        continue;
+      }
+      if (arg.startsWith('--max-attempts=')) {
+        const parsedAttempts = Number.parseInt(arg.slice('--max-attempts='.length), 10);
+        if (!Number.isInteger(parsedAttempts) || parsedAttempts <= 0) {
+          throw new Error(`Invalid --max-attempts value "${arg}".`);
+        }
+        loopMaxAttempts = parsedAttempts;
+        continue;
+      }
+      if (arg.startsWith('--output-json=')) {
+        loopOutputJsonPath = parseOutputPathFlag(
+          arg.slice('--output-json='.length),
+          '--output-json'
+        );
+        continue;
+      }
+      throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
+    }
+
+    if (loopCommand === 'run') {
+      if (!loopObjective || loopObjective.length === 0) {
+        throw new Error(`Missing --objective=<text> for "pumuki loop run".\n\n${HELP_TEXT}`);
+      }
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        loopCommand,
+        loopObjective,
+        loopMaxAttempts: loopMaxAttempts ?? 3,
+      };
+    }
+    if (loopCommand === 'list') {
+      if (loopSessionId || loopObjective || typeof loopMaxAttempts === 'number' || loopOutputJsonPath) {
+        throw new Error(`"pumuki loop list" only supports [--json].\n\n${HELP_TEXT}`);
+      }
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        loopCommand,
+      };
+    }
+    if (!loopSessionId || loopSessionId.length === 0) {
+      throw new Error(`Missing --session=<session-id> for "pumuki loop ${loopCommand}".\n\n${HELP_TEXT}`);
+    }
+    if (loopObjective || typeof loopMaxAttempts === 'number') {
+      throw new Error(`Unsupported run-only flags for "pumuki loop ${loopCommand}".\n\n${HELP_TEXT}`);
+    }
+    if (loopCommand !== 'export' && loopOutputJsonPath) {
+      throw new Error(`--output-json is only supported with "pumuki loop export".\n\n${HELP_TEXT}`);
+    }
+    const parsedLoopArgs: ParsedArgs = {
+      command: commandRaw,
+      purgeArtifacts: false,
+      json,
+      loopCommand,
+      loopSessionId,
+    };
+    if (loopOutputJsonPath) {
+      parsedLoopArgs.loopOutputJsonPath = loopOutputJsonPath;
+    }
+    return parsedLoopArgs;
+  }
+
   if (commandRaw === 'sdd') {
     const subcommandRaw = argv[1] ?? 'status';
     if (
@@ -637,10 +761,12 @@ type PreWriteValidationEnvelope = {
 
 type LifecycleCliDependencies = {
   emitAuditSummaryNotificationFromAiGate: typeof emitAuditSummaryNotificationFromAiGate;
+  runPlatformGate: typeof runPlatformGate;
 };
 
 const defaultLifecycleCliDependencies: LifecycleCliDependencies = {
   emitAuditSummaryNotificationFromAiGate,
+  runPlatformGate,
 };
 
 const resolveSddDecisionLocation = (
@@ -693,6 +819,29 @@ const buildPreWriteValidationEnvelope = (
   },
 });
 
+const writeLoopAttemptEvidence = (params: {
+  repoRoot: string;
+  sessionId: string;
+  attempt: number;
+  payload: {
+    session_id: string;
+    attempt: number;
+    started_at: string;
+    finished_at: string;
+    gate_exit_code: number;
+    gate_allowed: boolean;
+    gate_code: string;
+    policy: GatePolicy;
+    scope: 'workingTree';
+  };
+}): string => {
+  const relativePath = `.pumuki/loop-sessions/${params.sessionId}.attempt-${params.attempt}.json`;
+  const absolutePath = resolve(params.repoRoot, relativePath);
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(absolutePath, `${JSON.stringify(params.payload, null, 2)}\n`, 'utf8');
+  return relativePath;
+};
+
 export const runLifecycleCli = async (
   argv: ReadonlyArray<string>,
   dependencies: Partial<LifecycleCliDependencies> = {}
@@ -779,6 +928,173 @@ export const runLifecycleCli = async (
         }
         return 0;
       }
+      case 'loop': {
+        const repoRoot = process.cwd();
+        if (parsed.loopCommand === 'run') {
+          const session = createLoopSessionContract({
+            objective: parsed.loopObjective ?? '',
+            maxAttempts: parsed.loopMaxAttempts ?? 3,
+          });
+          createLoopSession({
+            repoRoot,
+            session,
+          });
+          const attemptNumber = session.current_attempt + 1;
+          const startedAt = new Date().toISOString();
+          const gateExitCode = await activeDependencies.runPlatformGate({
+            policy: LOOP_RUN_POLICY,
+            scope: {
+              kind: 'workingTree',
+            },
+            auditMode: 'engine',
+          });
+          const finishedAt = new Date().toISOString();
+          const gateAllowed = gateExitCode === 0;
+          const gateCode = gateAllowed ? 'ALLOW' : 'BLOCK';
+          const evidencePath = writeLoopAttemptEvidence({
+            repoRoot,
+            sessionId: session.session_id,
+            attempt: attemptNumber,
+            payload: {
+              session_id: session.session_id,
+              attempt: attemptNumber,
+              started_at: startedAt,
+              finished_at: finishedAt,
+              gate_exit_code: gateExitCode,
+              gate_allowed: gateAllowed,
+              gate_code: gateCode,
+              policy: LOOP_RUN_POLICY,
+              scope: 'workingTree',
+            },
+          });
+          const updatedSession: typeof session = {
+            ...session,
+            status: gateAllowed ? 'running' : 'blocked',
+            updated_at: finishedAt,
+            current_attempt: attemptNumber,
+            attempts: [
+              ...session.attempts,
+              {
+                attempt: attemptNumber,
+                started_at: startedAt,
+                finished_at: finishedAt,
+                outcome: gateAllowed ? 'pass' : 'block',
+                gate_allowed: gateAllowed,
+                gate_code: gateCode,
+                evidence_path: evidencePath,
+              },
+            ],
+          };
+          updateLoopSession({
+            repoRoot,
+            session: updatedSession,
+          });
+          if (parsed.json) {
+            writeInfo(JSON.stringify(updatedSession, null, 2));
+          } else {
+            writeInfo(
+              `[pumuki][loop] session created: id=${updatedSession.session_id} status=${updatedSession.status} attempt=${updatedSession.current_attempt}/${updatedSession.max_attempts}`
+            );
+            writeInfo(
+              `[pumuki][loop] attempt #${attemptNumber} gate=${gateCode} evidence=${evidencePath}`
+            );
+          }
+          return gateAllowed ? 0 : 1;
+        }
+        if (parsed.loopCommand === 'list') {
+          const sessions = listLoopSessions(repoRoot);
+          if (parsed.json) {
+            writeInfo(JSON.stringify(sessions, null, 2));
+          } else {
+            writeInfo(`[pumuki][loop] sessions=${sessions.length}`);
+            for (const session of sessions) {
+              writeInfo(
+                `[pumuki][loop] ${session.session_id} status=${session.status} attempt=${session.current_attempt}/${session.max_attempts} updated_at=${session.updated_at}`
+              );
+            }
+          }
+          return 0;
+        }
+
+        const sessionRead = readLoopSession({
+          repoRoot,
+          sessionId: parsed.loopSessionId ?? '',
+        });
+        if (sessionRead.kind === 'missing') {
+          writeError(`[pumuki][loop] session not found: ${parsed.loopSessionId}`);
+          return 1;
+        }
+        if (sessionRead.kind === 'invalid') {
+          writeError(
+            `[pumuki][loop] invalid session "${parsed.loopSessionId}": ${sessionRead.reason}`
+          );
+          return 1;
+        }
+        if (parsed.loopCommand === 'status') {
+          if (parsed.json) {
+            writeInfo(JSON.stringify(sessionRead.session, null, 2));
+          } else {
+            writeInfo(
+              `[pumuki][loop] ${sessionRead.session.session_id} status=${sessionRead.session.status} attempt=${sessionRead.session.current_attempt}/${sessionRead.session.max_attempts} updated_at=${sessionRead.session.updated_at}`
+            );
+          }
+          return 0;
+        }
+        if (parsed.loopCommand === 'export') {
+          const outputPath = toLocalOutputAbsolutePath(
+            repoRoot,
+            parsed.loopOutputJsonPath ??
+              `.audit-reports/loop-session-${sessionRead.session.session_id}.json`
+          );
+          mkdirSync(dirname(outputPath), { recursive: true });
+          writeFileSync(outputPath, `${JSON.stringify(sessionRead.session, null, 2)}\n`, 'utf8');
+          if (parsed.json) {
+            writeInfo(
+              JSON.stringify(
+                {
+                  session_id: sessionRead.session.session_id,
+                  output_json: parsed.loopOutputJsonPath ??
+                    `.audit-reports/loop-session-${sessionRead.session.session_id}.json`,
+                },
+                null,
+                2
+              )
+            );
+          } else {
+            writeInfo(
+              `[pumuki][loop] export completed: session=${sessionRead.session.session_id} path=${parsed.loopOutputJsonPath ??
+                `.audit-reports/loop-session-${sessionRead.session.session_id}.json`}`
+            );
+          }
+          return 0;
+        }
+
+        const nextStatus: 'stopped' | 'running' =
+          parsed.loopCommand === 'stop' ? 'stopped' : 'running';
+        if (!isLoopSessionTransitionAllowed(sessionRead.session.status, nextStatus)) {
+          writeError(
+            `[pumuki][loop] invalid transition ${sessionRead.session.status} -> ${nextStatus} for ${sessionRead.session.session_id}`
+          );
+          return 1;
+        }
+        const updated: typeof sessionRead.session = {
+          ...sessionRead.session,
+          status: nextStatus,
+          updated_at: new Date().toISOString(),
+        };
+        updateLoopSession({
+          repoRoot,
+          session: updated,
+        });
+        if (parsed.json) {
+          writeInfo(JSON.stringify(updated, null, 2));
+        } else {
+          writeInfo(
+            `[pumuki][loop] session ${updated.session_id} status=${updated.status}`
+          );
+        }
+        return 0;
+      }
       case 'analytics': {
         if (parsed.analyticsCommand === 'hotspots' && parsed.analyticsHotspotsCommand === 'report') {
           const repoRoot = process.cwd();

package/integrations/lifecycle/index.ts

@@ -74,6 +74,20 @@ export {
   appendOperationalMemorySnapshotFromLocalSignals,
   resolveOperationalMemorySnapshotsPath,
 } from './operationalMemorySnapshot';
+export {
+  createLoopSessionContract,
+  createLoopSessionId,
+  isLoopSessionTransitionAllowed,
+  parseLoopSessionContract,
+} from './loopSessionContract';
+export {
+  createLoopSession,
+  listLoopSessions,
+  readLoopSession,
+  resolveLoopSessionPath,
+  resolveLoopSessionsDirectory,
+  updateLoopSession,
+} from './loopSessionStore';
 export type {
   CreateHotspotsSaasIngestionPayloadParams,
   HotspotsSaasIngestionPayloadBodyCompat,
@@ -107,6 +121,20 @@ export type {
   AppendOperationalMemorySnapshotFromLocalSignalsResult,
   OperationalMemorySnapshotV1,
 } from './operationalMemorySnapshot';
+export type {
+  CreateLoopSessionContractParams,
+  LoopSessionAttemptOutcome,
+  LoopSessionAttemptV1,
+  LoopSessionContractV1,
+  LoopSessionStatus,
+  ParseLoopSessionContractResult,
+} from './loopSessionContract';
+export type {
+  ReadLoopSessionParams,
+  ReadLoopSessionResult,
+  UpsertLoopSessionParams,
+  WriteLoopSessionResult,
+} from './loopSessionStore';
 export type { BuildHotspotsSaasIngestionPayloadFromLocalParams } from './saasIngestionBuilder';
 export type {
   HotspotsSaasIngestionAuthPolicy,

package/integrations/lifecycle/loopSessionContract.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+
+const loopSessionAttemptSchema = z
+  .object({
+    attempt: z.number().int().positive(),
+    started_at: z.string().datetime({ offset: true }),
+    finished_at: z.string().datetime({ offset: true }),
+    outcome: z.enum(['pass', 'block', 'error', 'stopped']),
+    gate_allowed: z.boolean(),
+    gate_code: z.string().min(1),
+    evidence_path: z.string().min(1).optional(),
+    notes: z.string().min(1).optional(),
+  })
+  .strict();
+
+const loopSessionContractSchema = z
+  .object({
+    version: z.literal('1'),
+    session_id: z.string().min(1),
+    objective: z.string().min(1),
+    status: z.enum(['running', 'blocked', 'stopped', 'completed']),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    max_attempts: z.number().int().positive(),
+    current_attempt: z.number().int().min(0),
+    attempts: z.array(loopSessionAttemptSchema),
+  })
+  .strict();
+
+const loopSessionTransitions: Readonly<Record<LoopSessionStatus, ReadonlyArray<LoopSessionStatus>>> = {
+  running: ['blocked', 'stopped', 'completed'],
+  blocked: ['running', 'stopped', 'completed'],
+  stopped: ['running'],
+  completed: [],
+};
+
+const parseValidationError = (error: z.ZodError): string =>
+  error.issues[0]
+    ? `${error.issues[0].path.join('.') || 'contract'}: ${error.issues[0].message}`
+    : 'invalid_loop_session_contract';
+
+export type LoopSessionStatus = z.infer<typeof loopSessionContractSchema>['status'];
+export type LoopSessionAttemptOutcome = z.infer<typeof loopSessionAttemptSchema>['outcome'];
+export type LoopSessionAttemptV1 = z.infer<typeof loopSessionAttemptSchema>;
+export type LoopSessionContractV1 = z.infer<typeof loopSessionContractSchema>;
+
+export type CreateLoopSessionContractParams = {
+  sessionId?: string;
+  objective: string;
+  generatedAt?: string;
+  maxAttempts: number;
+};
+
+export type ParseLoopSessionContractResult =
+  | {
+      kind: 'valid';
+      contract: LoopSessionContractV1;
+    }
+  | {
+      kind: 'invalid';
+      reason: string;
+    };
+
+export const createLoopSessionId = (): string => `loop-${randomUUID()}`;
+
+export const isLoopSessionTransitionAllowed = (
+  current: LoopSessionStatus,
+  next: LoopSessionStatus
+): boolean => {
+  if (current === next) {
+    return false;
+  }
+  return loopSessionTransitions[current].includes(next);
+};
+
+export const createLoopSessionContract = (
+  params: CreateLoopSessionContractParams
+): LoopSessionContractV1 => {
+  const generatedAt = params.generatedAt ?? new Date().toISOString();
+  return loopSessionContractSchema.parse({
+    version: '1',
+    session_id: params.sessionId?.trim() || createLoopSessionId(),
+    objective: params.objective.trim(),
+    status: 'running',
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    max_attempts: params.maxAttempts,
+    current_attempt: 0,
+    attempts: [],
+  });
+};
+
+const hasValidAttemptOrder = (attempts: ReadonlyArray<LoopSessionAttemptV1>): boolean => {
+  let expected = 1;
+  for (const attempt of attempts) {
+    if (attempt.attempt !== expected) {
+      return false;
+    }
+    expected += 1;
+  }
+  return true;
+};
+
+export const parseLoopSessionContract = (candidate: unknown): ParseLoopSessionContractResult => {
+  const parsed = loopSessionContractSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return {
+      kind: 'invalid',
+      reason: parseValidationError(parsed.error),
+    };
+  }
+  const contract = parsed.data;
+  if (contract.current_attempt > contract.max_attempts) {
+    return {
+      kind: 'invalid',
+      reason: `current_attempt exceeds max_attempts (${contract.current_attempt} > ${contract.max_attempts})`,
+    };
+  }
+  if (contract.attempts.length > contract.max_attempts) {
+    return {
+      kind: 'invalid',
+      reason: `attempts length exceeds max_attempts (${contract.attempts.length} > ${contract.max_attempts})`,
+    };
+  }
+  if (contract.current_attempt !== contract.attempts.length) {
+    return {
+      kind: 'invalid',
+      reason: `current_attempt must match attempts length (${contract.current_attempt} != ${contract.attempts.length})`,
+    };
+  }
+  if (!hasValidAttemptOrder(contract.attempts)) {
+    return {
+      kind: 'invalid',
+      reason: 'attempt sequence must be contiguous starting at 1',
+    };
+  }
+  return {
+    kind: 'valid',
+    contract,
+  };
+};

package/integrations/lifecycle/loopSessionStore.ts

@@ -0,0 +1,167 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve, join } from 'node:path';
+import {
+  parseLoopSessionContract,
+  type LoopSessionContractV1,
+} from './loopSessionContract';
+
+const DEFAULT_LOOP_SESSIONS_DIRECTORY = '.pumuki/loop-sessions';
+
+const normalizeSessionId = (sessionId: string): string => {
+  const normalized = sessionId.trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(normalized)) {
+    throw new Error(`Invalid loop session id "${sessionId}".`);
+  }
+  return normalized;
+};
+
+const toAbsolutePath = (repoRoot: string, maybeRelative: string): string => {
+  if (isAbsolute(maybeRelative)) {
+    return resolve(maybeRelative);
+  }
+  return resolve(repoRoot, maybeRelative);
+};
+
+export type ReadLoopSessionParams = {
+  repoRoot: string;
+  sessionId: string;
+};
+
+export type UpsertLoopSessionParams = {
+  repoRoot: string;
+  session: LoopSessionContractV1;
+};
+
+export type ReadLoopSessionResult =
+  | {
+      kind: 'missing';
+      path: string;
+    }
+  | {
+      kind: 'invalid';
+      path: string;
+      reason: string;
+    }
+  | {
+      kind: 'valid';
+      path: string;
+      session: LoopSessionContractV1;
+    };
+
+export type WriteLoopSessionResult = {
+  path: string;
+  bytes: number;
+};
+
+export const resolveLoopSessionsDirectory = (repoRoot: string): string => {
+  const configured = process.env.PUMUKI_LOOP_SESSIONS_DIR?.trim();
+  const candidate =
+    configured && configured.length > 0
+      ? configured
+      : DEFAULT_LOOP_SESSIONS_DIRECTORY;
+  return toAbsolutePath(repoRoot, candidate);
+};
+
+export const resolveLoopSessionPath = (repoRoot: string, sessionId: string): string =>
+  join(resolveLoopSessionsDirectory(repoRoot), `${normalizeSessionId(sessionId)}.json`);
+
+const parseStoredSession = (path: string): ReadLoopSessionResult => {
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    const contractParsed = parseLoopSessionContract(parsed);
+    if (contractParsed.kind === 'invalid') {
+      return {
+        kind: 'invalid',
+        path,
+        reason: contractParsed.reason,
+      };
+    }
+    return {
+      kind: 'valid',
+      path,
+      session: contractParsed.contract,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : 'invalid_loop_session_json';
+    return {
+      kind: 'invalid',
+      path,
+      reason,
+    };
+  }
+};
+
+export const readLoopSession = (params: ReadLoopSessionParams): ReadLoopSessionResult => {
+  const path = resolveLoopSessionPath(params.repoRoot, params.sessionId);
+  if (!existsSync(path)) {
+    return {
+      kind: 'missing',
+      path,
+    };
+  }
+  return parseStoredSession(path);
+};
+
+const validateSessionBeforeWrite = (session: LoopSessionContractV1): LoopSessionContractV1 => {
+  const parsed = parseLoopSessionContract(session);
+  if (parsed.kind === 'invalid') {
+    throw new Error(`Invalid loop session contract: ${parsed.reason}`);
+  }
+  return parsed.contract;
+};
+
+export const createLoopSession = (params: UpsertLoopSessionParams): WriteLoopSessionResult => {
+  const contract = validateSessionBeforeWrite(params.session);
+  const path = resolveLoopSessionPath(params.repoRoot, contract.session_id);
+  if (existsSync(path)) {
+    throw new Error(`Loop session already exists at "${path}".`);
+  }
+  mkdirSync(resolveLoopSessionsDirectory(params.repoRoot), { recursive: true });
+  const serialized = `${JSON.stringify(contract, null, 2)}\n`;
+  writeFileSync(path, serialized, 'utf8');
+  return {
+    path,
+    bytes: Buffer.byteLength(serialized, 'utf8'),
+  };
+};
+
+export const updateLoopSession = (params: UpsertLoopSessionParams): WriteLoopSessionResult => {
+  const contract = validateSessionBeforeWrite(params.session);
+  const path = resolveLoopSessionPath(params.repoRoot, contract.session_id);
+  if (!existsSync(path)) {
+    throw new Error(`Loop session does not exist at "${path}".`);
+  }
+  mkdirSync(resolveLoopSessionsDirectory(params.repoRoot), { recursive: true });
+  const serialized = `${JSON.stringify(contract, null, 2)}\n`;
+  writeFileSync(path, serialized, 'utf8');
+  return {
+    path,
+    bytes: Buffer.byteLength(serialized, 'utf8'),
+  };
+};
+
+export const listLoopSessions = (repoRoot: string): ReadonlyArray<LoopSessionContractV1> => {
+  const directory = resolveLoopSessionsDirectory(repoRoot);
+  if (!existsSync(directory)) {
+    return [];
+  }
+  const sessions: Array<LoopSessionContractV1> = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) {
+      continue;
+    }
+    const result = parseStoredSession(join(directory, entry.name));
+    if (result.kind === 'valid') {
+      sessions.push(result.session);
+    }
+  }
+  return sessions.sort((a, b) => {
+    const updatedA = new Date(a.updated_at).getTime();
+    const updatedB = new Date(b.updated_at).getTime();
+    if (updatedA !== updatedB) {
+      return updatedB - updatedA;
+    }
+    return a.session_id.localeCompare(b.session_id);
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.22",
+  "version": "6.3.24",
   "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": {