@pugi/cli 0.1.0-beta.30 → 0.1.0-beta.31

package/dist/core/prd-check/session-review.js

@@ -0,0 +1,557 @@
+/**
+ * PRD ↔ session review — Pugi α7 Wave 6 final (`/prd-check --session`,
+ * 2026-05-27).
+ *
+ * The shipped `/prd-check` surface verifies a PRD's acceptance criteria
+ * against committed artifacts on disk (file / test / doc / command /
+ * route verifiers — see `core/prd-check/verifiers.ts`). That mode is
+ * the canonical CI gate; it inspects a snapshot of the workspace and
+ * decides healthy / failing / unparsed.
+ *
+ * `--session` adds a complementary mode: ask "does the work I just
+ * did in this REPL session actually cover the PRD?" without requiring
+ * the acceptance criteria to be written in the structured shape the
+ * verifier expects. The mode:
+ *
+ *   1. Walks up from the current working directory looking for
+ *      `PRD.md`, then `PRODUCT.md`, then `apps/<any>/PRODUCT.md`
+ *      under the workspace root. The first hit wins; the rest are
+ *      ignored. We stop at the filesystem root.
+ *
+ *   2. Reads the last N (default 20) events from `.pugi/events.jsonl`
+ *      that represent operator-visible turns: user prompts, model
+ *      responses, and tool calls with their results. Other event
+ *      types (`session`, `hook`, …) are filtered so the prompt the
+ *      subagent receives is dominated by intent + work-actually-done
+ *      rather than infrastructure noise.
+ *
+ *   3. Builds a structured prompt for a cross-review subagent. The
+ *      subagent is dispatched via the standard `dispatch()` surface
+ *      (see `core/subagents/dispatcher.ts`) using the `pm` persona —
+ *      the closest match to a PRD reviewer in today's roster. The
+ *      subagent is instructed to return two newline-separated lists:
+ *      `Satisfied:` and `Outstanding:`.
+ *
+ *   4. Parses the subagent's response into a structured envelope so
+ *      the slash + the top-level CLI render the same output shape
+ *      (Markdown sections in the TUI, JSON for scripts).
+ *
+ * The module is pure with respect to dependencies — every IO surface
+ * (`readPrdSearch`, `readSessionEvents`, `dispatchReview`) is
+ * accepted as an injected dep so the spec can drive every branch
+ * without a real filesystem or a network call. The default
+ * implementations live in `defaultSessionReviewDeps`.
+ *
+ * The subagent return contract is intentionally loose: any line
+ * starting with `Satisfied:` (case-insensitive) opens the satisfied
+ * section; any line starting with `Outstanding:` opens the
+ * outstanding section. Bulleted lines (`-`, `*`, `•`) inside each
+ * section land as list items. Free prose between sections is
+ * captured as the `note` field on the envelope so the reviewer can
+ * still attach a sentence of context.
+ *
+ * Cross-review subagent: this module routes to whatever persona
+ * resolves the "PRD reviewer" role at dispatch time. In α7 Wave 6
+ * that is the `pm` persona via `dispatch({ role: 'pm', … })`. Once
+ * a dedicated reviewer persona lands (project tracking ID:
+ * cross-review subagent track), swapping it requires only changing
+ * `DEFAULT_REVIEW_ROLE` below.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+/**
+ * Names of PRD-style files we will try to locate. Order matters —
+ * `PRD.md` wins over `PRODUCT.md` so a project that has both an
+ * authored PRD and a legacy PRODUCT brief points at the PRD.
+ */
+const PRD_CANDIDATE_NAMES = ['PRD.md', 'PRODUCT.md'];
+/**
+ * Per-app product brief glob. We scan `apps/*` under the workspace
+ * root for a top-level `PRODUCT.md` — this matches the layout the
+ * Pugi monorepo uses (`apps/admin-api/PRODUCT.md`, etc.). Walk is
+ * shallow on purpose to keep the search bounded.
+ */
+const APPS_DIR = 'apps';
+/** Default number of NDJSON turns to surface to the reviewer. */
+export const DEFAULT_TURN_COUNT = 20;
+/**
+ * Subagent role we ask to play the PRD reviewer. `reviewer` is the
+ * canonical slot in the dispatcher's role enum (see
+ * `packages/pugi-sdk/src/subagent-contracts.ts`) — every dispatch
+ * resolves a role to a persona at runtime via the isolation matrix.
+ * The constant is exported so callers can override (e.g. route to
+ * `verifier` for a stricter pass).
+ */
+export const DEFAULT_REVIEW_ROLE = 'reviewer';
+/**
+ * Run the `--session` mode end-to-end. The function emits status
+ * lines through `deps.onStatus` (the slash dispatcher wires this to
+ * `appendSystemLine`) and returns the structured envelope.
+ */
+export async function runSessionReview(workspaceRoot, deps, options = {}) {
+    const turnCount = options.turnCount ?? DEFAULT_TURN_COUNT;
+    const status = deps.onStatus ?? (() => undefined);
+    status('Locating PRD...');
+    const prdPath = deps.resolvePrd(workspaceRoot);
+    if (prdPath === null) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'no_prd',
+            prdPath: null,
+            prdTitle: null,
+            turnsRead: 0,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: `No PRD.md or PRODUCT.md found walking up from ${workspaceRoot}.`,
+        };
+    }
+    const prdSource = safeRead(prdPath);
+    if (prdSource === null) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'no_prd',
+            prdPath: relative(workspaceRoot, prdPath) || prdPath,
+            prdTitle: null,
+            turnsRead: 0,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: `PRD file at ${prdPath} is unreadable.`,
+        };
+    }
+    const prdTitle = extractTitle(prdSource);
+    status(`Reading last ${turnCount} session turns...`);
+    const rawEvents = deps.readEventsLog(workspaceRoot);
+    const turns = rawEvents === null ? [] : parseTurns(rawEvents, turnCount);
+    status('Reviewing against PRD...');
+    const prompt = buildReviewPrompt({
+        prdPath,
+        prdTitle,
+        prdSource,
+        turns,
+        workspaceRoot,
+    });
+    const outcome = await deps.dispatchReview({
+        role: DEFAULT_REVIEW_ROLE,
+        prompt,
+        workspaceRoot,
+    });
+    if (!outcome.ok) {
+        return {
+            command: 'prd-check',
+            mode: 'session',
+            status: 'dispatch_failed',
+            prdPath: relative(workspaceRoot, prdPath) || prdPath,
+            prdTitle,
+            turnsRead: turns.length,
+            satisfied: [],
+            outstanding: [],
+            note: '',
+            rawReview: null,
+            reason: outcome.reason,
+        };
+    }
+    const parsed = parseReviewResponse(outcome.text);
+    return {
+        command: 'prd-check',
+        mode: 'session',
+        status: 'ok',
+        prdPath: relative(workspaceRoot, prdPath) || prdPath,
+        prdTitle,
+        turnsRead: turns.length,
+        satisfied: parsed.satisfied,
+        outstanding: parsed.outstanding,
+        note: parsed.note,
+        rawReview: outcome.text,
+    };
+}
+/**
+ * Render the envelope as plain-text lines for the TUI / shell. The
+ * slash + the top-level CLI both use this so the surface stays
+ * single-sourced; the structured envelope (above) feeds `--json`.
+ */
+export function renderSessionReview(result) {
+    if (result.status === 'no_prd') {
+        return result.reason ?? 'No PRD found.';
+    }
+    if (result.status === 'dispatch_failed') {
+        return `PRD review dispatch failed: ${result.reason ?? 'unknown'}`;
+    }
+    const lines = [];
+    lines.push(`PRD review (${result.turnsRead} turn(s) read from .pugi/events.jsonl)`);
+    if (result.prdPath !== null) {
+        const titlePart = result.prdTitle === null ? '' : ` — ${result.prdTitle}`;
+        lines.push(`Source: ${result.prdPath}${titlePart}`);
+    }
+    lines.push('');
+    if (result.satisfied.length === 0) {
+        lines.push('Satisfied: (none reported)');
+    }
+    else {
+        lines.push('Satisfied:');
+        for (const item of result.satisfied)
+            lines.push(`  - ${item}`);
+    }
+    lines.push('');
+    if (result.outstanding.length === 0) {
+        lines.push('Outstanding: (none reported)');
+    }
+    else {
+        lines.push('Outstanding:');
+        for (const item of result.outstanding)
+            lines.push(`  - ${item}`);
+    }
+    if (result.note.length > 0) {
+        lines.push('');
+        lines.push(`Note: ${result.note}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compose the prompt handed to the reviewer subagent. The prompt is
+ * deterministic — input order matters for prompt cache hits so we
+ * keep the layout stable: PRD source first, session turns second,
+ * forcing-question schema last.
+ */
+export function buildReviewPrompt(input) {
+    const parts = [];
+    parts.push('You are a PRD reviewer. Read the PRD below, then read the recent session turns, then decide which requirements are SATISFIED by the work-so-far and which remain OUTSTANDING.');
+    parts.push('');
+    parts.push('Reply in EXACTLY this shape:');
+    parts.push('');
+    parts.push('Satisfied:');
+    parts.push('- <requirement>');
+    parts.push('- <requirement>');
+    parts.push('');
+    parts.push('Outstanding:');
+    parts.push('- <requirement>');
+    parts.push('- <requirement>');
+    parts.push('');
+    parts.push('Each list item is one PRD requirement, paraphrased to fit a single line. Do not invent requirements that are not in the PRD. If the session shows no work toward a requirement, list it Outstanding.');
+    parts.push('');
+    parts.push('--- PRD start ---');
+    parts.push(`Path: ${relative(input.workspaceRoot, input.prdPath) || input.prdPath}`);
+    if (input.prdTitle !== null)
+        parts.push(`Title: ${input.prdTitle}`);
+    parts.push('');
+    parts.push(input.prdSource);
+    parts.push('--- PRD end ---');
+    parts.push('');
+    parts.push(`--- Last ${input.turns.length} session turn(s) start ---`);
+    for (const turn of input.turns) {
+        parts.push(formatTurn(turn));
+    }
+    parts.push('--- session turns end ---');
+    return parts.join('\n');
+}
+/**
+ * Walk up from cwd looking for the first PRD / PRODUCT file. Also
+ * scans `apps/*` under the workspace root once we find a directory
+ * that contains an `apps` folder. Returns absolute path or null.
+ */
+export function defaultResolvePrd(cwd) {
+    let current = resolve(cwd);
+    for (let i = 0; i < 32; i += 1) {
+        for (const name of PRD_CANDIDATE_NAMES) {
+            const candidate = join(current, name);
+            if (existsSync(candidate) && safeIsFile(candidate)) {
+                return candidate;
+            }
+        }
+        // If this directory holds an apps/ folder, scan one level deep
+        // for app-scoped PRODUCT.md. We do NOT keep walking up past this
+        // point — the apps/ folder marks the workspace root in our
+        // monorepo layout.
+        const appsDir = join(current, APPS_DIR);
+        if (existsSync(appsDir) && safeIsDirectory(appsDir)) {
+            const appHit = scanAppsForProduct(appsDir);
+            if (appHit !== null)
+                return appHit;
+            return null;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Default events log reader. Returns the raw file contents or null
+ * when the log is absent — `.pugi/events.jsonl` only exists when
+ * the workspace has had at least one session.
+ */
+export function defaultReadEventsLog(workspaceRoot) {
+    const path = join(workspaceRoot, '.pugi', 'events.jsonl');
+    return safeRead(path);
+}
+/**
+ * Default cross-review dispatcher. Routes through the standard
+ * subagents `dispatch()` surface in stub-mode (no engine client) so
+ * the slash + the CLI top-level have a working default that does not
+ * require a live admin-api connection. When an engine client is in
+ * scope (callers supply one via injection from the runtime cli.ts
+ * layer once auth is resolved), `dispatch()` will route to the real
+ * cross-review subagent.
+ *
+ * Imported dynamically so test paths that inject a stub never pull
+ * the dispatcher graph into the spec.
+ */
+export const defaultDispatchReview = async (input) => {
+    try {
+        const { dispatch, inMemoryDispatcherContext } = await import('../subagents/dispatcher.js');
+        // The dispatcher's role enum is the canonical schema; `as` keeps
+        // the caller's role string flowing through without re-importing
+        // the schema here (the schema parse inside `dispatch()` will
+        // reject if it does not match — that is the contract gate).
+        const task = {
+            id: `prd-review-${Date.now()}`,
+            role: input.role,
+            prompt: input.prompt,
+            permissionMode: 'plan',
+        };
+        const ctx = inMemoryDispatcherContext({
+            sessionId: `prd-review-session-${Date.now()}`,
+            workspaceRoot: input.workspaceRoot,
+            sink: [],
+        });
+        const outcome = await dispatch(task, ctx);
+        if (!outcome || typeof outcome !== 'object') {
+            return { ok: false, reason: 'dispatcher returned an unexpected shape' };
+        }
+        if (typeof outcome.summary === 'string' && outcome.summary.length > 0) {
+            return { ok: true, text: outcome.summary };
+        }
+        return { ok: false, reason: 'dispatcher response carried no reviewable summary' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: message };
+    }
+};
+/** Convenience bundle for callers that want the real-IO defaults. */
+export function defaultSessionReviewDeps(overrides = {}) {
+    return {
+        resolvePrd: overrides.resolvePrd ?? defaultResolvePrd,
+        readEventsLog: overrides.readEventsLog ?? defaultReadEventsLog,
+        dispatchReview: overrides.dispatchReview ?? defaultDispatchReview,
+        ...(overrides.onStatus !== undefined ? { onStatus: overrides.onStatus } : {}),
+    };
+}
+/**
+ * Parse NDJSON, filter to operator-visible turns, and return the
+ * last N in chronological order. Malformed lines are silently
+ * dropped — the events log is appended to from multiple processes
+ * and partial writes during shutdown can leave a trailing line.
+ */
+export function parseTurns(raw, max) {
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const events = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // Drop malformed lines.
+        }
+    }
+    const visible = [];
+    for (const event of events) {
+        const role = classifyEvent(event);
+        if (role === null)
+            continue;
+        visible.push({
+            index: visible.length,
+            role,
+            summary: summariseEvent(event, role),
+            raw: event,
+        });
+    }
+    if (visible.length <= max) {
+        return visible.map((t, idx) => ({ ...t, index: idx }));
+    }
+    return visible.slice(visible.length - max).map((t, idx) => ({ ...t, index: idx }));
+}
+/**
+ * Pull a "Satisfied:" / "Outstanding:" pair out of the subagent text.
+ * Both labels are matched case-insensitively at line start. Bulleted
+ * items use any of `- `, `* `, or `• `. Free prose before / between
+ * sections lands in `note` (concatenated with a single space so the
+ * renderer can decide on wrapping).
+ */
+export function parseReviewResponse(text) {
+    const lines = text.split('\n');
+    const satisfied = [];
+    const outstanding = [];
+    const noteParts = [];
+    let section = 'none';
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const header = matchSectionHeader(line);
+        if (header !== null) {
+            section = header;
+            // Capture any inline item after the colon, e.g. "Satisfied: foo".
+            const inline = stripHeaderPrefix(line);
+            if (inline.length > 0) {
+                pushItem(inline, section, satisfied, outstanding);
+            }
+            continue;
+        }
+        const bulleted = matchBulleted(line);
+        if (bulleted !== null) {
+            pushItem(bulleted, section, satisfied, outstanding);
+            continue;
+        }
+        if (section === 'none') {
+            noteParts.push(line);
+        }
+        else {
+            // Continuation of the previous bulleted item — append.
+            const target = section === 'satisfied' ? satisfied : outstanding;
+            if (target.length > 0) {
+                target[target.length - 1] = `${target[target.length - 1]} ${line}`;
+            }
+            else {
+                noteParts.push(line);
+            }
+        }
+    }
+    return { satisfied, outstanding, note: noteParts.join(' ') };
+}
+/* ------------------------------ helpers ------------------------------ */
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function safeIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function safeIsDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function scanAppsForProduct(appsDir) {
+    let entries;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        entries = require('node:fs').readdirSync(appsDir);
+    }
+    catch {
+        return null;
+    }
+    entries.sort();
+    for (const entry of entries) {
+        const candidate = join(appsDir, entry, 'PRODUCT.md');
+        if (existsSync(candidate) && safeIsFile(candidate))
+            return candidate;
+        const prdCandidate = join(appsDir, entry, 'PRD.md');
+        if (existsSync(prdCandidate) && safeIsFile(prdCandidate))
+            return prdCandidate;
+    }
+    return null;
+}
+function extractTitle(source) {
+    for (const raw of source.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('# '))
+            return line.slice(2).trim();
+        if (line.startsWith('#'))
+            return line.replace(/^#+/, '').trim();
+        return null;
+    }
+    return null;
+}
+function classifyEvent(event) {
+    const type = typeof event.type === 'string' ? event.type : '';
+    if (type === 'user' || type === 'user_message' || type === 'prompt')
+        return 'user';
+    if (type === 'assistant' || type === 'model' || type === 'response' || type === 'completion') {
+        return 'model';
+    }
+    if (type === 'tool_call' || type === 'tool_result' || type === 'file_mutation')
+        return 'tool';
+    return null;
+}
+function summariseEvent(event, role) {
+    const text = typeof event.text === 'string' ? event.text : '';
+    const tool = typeof event.tool === 'string' ? event.tool : '';
+    const status = typeof event.status === 'string' ? event.status : '';
+    const path = typeof event.path === 'string' ? event.path : '';
+    const op = typeof event.operation === 'string' ? event.operation : '';
+    switch (role) {
+        case 'user':
+            return clip(text, 480);
+        case 'model':
+            return clip(text, 800);
+        case 'tool': {
+            if (event.type === 'tool_call')
+                return `tool_call ${tool || '?'}`;
+            if (event.type === 'tool_result')
+                return `tool_result ${tool || '?'} ${status}`.trim();
+            if (event.type === 'file_mutation')
+                return `file_mutation ${op} ${path}`.trim();
+            return `tool ${tool}`;
+        }
+    }
+}
+function clip(text, max) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, max - 1)}…`;
+}
+function formatTurn(turn) {
+    return `[${turn.index + 1}] ${turn.role}: ${turn.summary}`;
+}
+function matchSectionHeader(line) {
+    const lower = line.toLowerCase();
+    if (/^satisfied\b/.test(lower))
+        return 'satisfied';
+    if (/^outstanding\b/.test(lower))
+        return 'outstanding';
+    return null;
+}
+function stripHeaderPrefix(line) {
+    const colon = line.indexOf(':');
+    if (colon === -1)
+        return '';
+    return line.slice(colon + 1).trim();
+}
+function matchBulleted(line) {
+    const match = /^(?:[-*•]|\d+\.)\s+(.*)$/u.exec(line);
+    return match === null ? null : (match[1] ?? '').trim();
+}
+function pushItem(item, section, satisfied, outstanding) {
+    if (item.length === 0)
+        return;
+    if (section === 'satisfied')
+        satisfied.push(item);
+    else if (section === 'outstanding')
+        outstanding.push(item);
+}
+//# sourceMappingURL=session-review.js.map

package/dist/core/repl/session.js

@@ -1052,6 +1052,15 @@ export class ReplSession {
                 // `/prd-check` and `pugi prd-check`. Dynamic-import the
                 // module to keep the parser + verifier graph out of the
                 // REPL hot path.
+                //
+                // Wave 6 final (2026-05-27): the runner now also honours
+                // `--session` mode (orthogonal to the verifier graph — walks
+                // up for PRD.md, reads NDJSON turns, dispatches a cross-
+                // review subagent). We stream the runner's status lines
+                // directly to the system pane so the operator sees
+                // "Locating PRD..." / "Reviewing against PRD..." while the
+                // dispatch is in flight, then the structured Satisfied /
+                // Outstanding lists when it lands.
                 try {
                     const { parsePrdCheckArgs, runPrdCheckCommand } = await import('../../runtime/commands/prd-check.js');
                     const parsed = parsePrdCheckArgs(verdict.args, { jsonDefault: false });
@@ -1059,7 +1068,7 @@ export class ReplSession {
                         this.appendSystemLine(`/prd-check: ${parsed.error}`);
                         return verdict;
                     }
-                    const lines = [];
+                    let sawOutput = false;
                     await runPrdCheckCommand({
                         cwd: process.cwd(),
                         ...(parsed.prdPath !== undefined ? { prdPath: parsed.prdPath } : {}),
@@ -1074,13 +1083,13 @@ export class ReplSession {
                         knownCommands: new Set(),
                         writeOutput: (_payload, text) => {
                             const trimmed = text.replace(/\n+$/u, '');
-                            if (trimmed.length > 0)
-                                lines.push(trimmed);
+                            if (trimmed.length > 0) {
+                                this.appendSystemLine(trimmed);
+                                sawOutput = true;
+                            }
                         },
                     });
-                    for (const line of lines)
-                        this.appendSystemLine(line);
-                    if (lines.length === 0) {
+                    if (!sawOutput) {
                         this.appendSystemLine('/prd-check: no output.');
                     }
                 }
@@ -1474,6 +1483,40 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'undo': {
+                // Wave 6 final (2026-05-27): graduated from stub. The runtime
+                // command `runUndoCommand` already exists with full Aider walk-
+                // back semantics — single-step revert of the most recent
+                // successful `write` / `edit` / `multi_edit` tool result, with
+                // an mtime+hash gate that refuses to overwrite uncommitted
+                // operator work. We open a fresh PugiSession against the cwd
+                // so the inverse-mutation audit lands on the same NDJSON
+                // events stream the REPL writes to; dynamic-import keeps the
+                // runner + git plumbing out of the REPL hot path.
+                try {
+                    const [{ runUndoCommand }, { openSession }] = await Promise.all([
+                        import('../../runtime/commands/undo.js'),
+                        import('../session.js'),
+                    ]);
+                    const workspaceRoot = process.cwd();
+                    const session = openSession(workspaceRoot);
+                    this.appendSystemLine('Reverting last write...');
+                    await runUndoCommand([], {
+                        workspaceRoot,
+                        session,
+                        writeOutput: (_payload, text) => {
+                            const trimmed = text.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                this.appendSystemLine(trimmed);
+                        },
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/undo failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;

package/dist/core/repl/slash-commands.js

@@ -51,7 +51,11 @@ export const SLASH_STUB_MESSAGES = Object.freeze({
     // β4 Sl7 (2026-05-26): /mcp graduated from stub to a real handler
     // that forwards to `runMcpCommand`. Stub message removed from the
     // exhaustive record so the type narrows correctly.
-    undo: 'Run `pugi undo` from a fresh shell; in-REPL undo lands in α6.5.',
+    //
+    // Wave 6 final (2026-05-27): /undo graduated from stub to a real
+    // handler that forwards to `runUndoCommand` (Aider walk-back —
+    // single-step revert of the last mutating tool result, with
+    // mtime+hash external-modification gate). Stub message removed.
 });
 export const SLASH_COMMAND_HELP = Object.freeze([
     // Workforce dispatch
@@ -89,12 +93,12 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'theme', args: '[name] [--persist|--reset|--list]', gloss: 'TUI color palette (default / dark / light / colorblind)', group: 'Settings' },
     { name: 'onboarding', args: '[--reset|--non-interactive]', gloss: 'First-run wizard — auth / mode / style / MCP / telemetry (leak L25)', group: 'Settings' },
     { name: 'vim', args: '[on|off|status]', gloss: 'Toggle vim-style modal editing in the input buffer (leak L26)', group: 'Settings' },
-    { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
+    { name: 'undo', args: '', gloss: 'Revert the last successful write / edit / multi_edit (Aider walk-back, Wave 6)', group: 'Settings' },
     // Meta
     { name: 'help', args: '', gloss: 'Show this help overlay', group: 'Meta' },
     { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
     { name: 'doctor', args: '', gloss: 'Environment health report (auth · API · Node · disk · MCP · …)', group: 'Meta' },
-    { name: 'prd-check', args: '<prd-path | --all> [--json]', gloss: 'Verify PRD acceptance criteria against committed code/tests/docs (Wave 6)', group: 'Meta' },
+    { name: 'prd-check', args: '<prd-path | --all | --session> [--json]', gloss: 'Verify PRD against code (default) or session work (--session, Wave 6 final)', group: 'Meta' },
     { name: 'chain', args: '<new|status|next|show|export|list> [...args]', gloss: 'Artifact chain — PRD → ADR → mindmap → ER → sequence → tests → code (Wave 6)', group: 'Meta' },
     { name: 'stickers', args: '', gloss: 'show Pugi brand stickers (gimmick)', group: 'Meta' },
     { name: 'feedback', args: '', gloss: 'file a bug / feature / general comment without leaving the REPL', group: 'Meta' },
@@ -553,10 +557,18 @@ export function parseSlashCommand(input) {
             const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
             return { kind: 'update', args: tokens };
         }
+        case 'undo': {
+            // Wave 6 final (2026-05-27): graduated from stub. Tail args are
+            // ignored — `runUndoCommand` is parameterless (single-step revert
+            // of the most recent successful mutating tool result). Multiple
+            // undos = stack of single-step undos. Re-do is not yet
+            // implemented; the runner reports that in the operator-facing
+            // message after each successful undo.
+            return { kind: 'undo' };
+        }
         case 'memory':
         case 'config':
-        case 'budget':
-        case 'undo': {
+        case 'budget': {
             const stubName = name;
             return {
                 kind: 'stub',

package/dist/runtime/cli.js

@@ -1695,10 +1695,11 @@ const COMMAND_HELP_BODIES = {
         'engine adapter. Safe to run anywhere; no network calls.',
     ],
     'prd-check': [
-        'pugi prd-check <prd-path> | --all   — Wave 6 verified-deliverable gate.',
+        'pugi prd-check <prd-path> | --all | --session   — Wave 6 verified-deliverable gate.',
         '',
+        'DEFAULT MODE — verify acceptance criteria against committed artifacts.',
         'Reads a markdown PRD, parses the acceptance-criteria section, and',
-        'runs verifiers against committed artifacts:',
+        'runs verifiers:',
         '  file:<path>      fs.existsSync',
         '  test:<spec>      spec file exists + has ≥1 test()/it() block',
         '  doc:<path>       doc exists + has > 100 chars',
@@ -1708,6 +1709,13 @@ const COMMAND_HELP_BODIES = {
         '  --all                   Scan docs/prd/**.md instead of one file.',
         '  --json                  Emit a structured envelope to stdout.',
         '',
+        'SESSION MODE (Wave 6 final) — review the live session against the PRD.',
+        'Walks up for PRD.md or apps/<app>/PRODUCT.md, reads the last 20 turns',
+        'from .pugi/events.jsonl, and dispatches a cross-review subagent to',
+        'list which requirements are SATISFIED and which remain OUTSTANDING.',
+        '',
+        '  --session               Run the session-review mode (no <path>, no --all).',
+        '',
         'Exit codes: 0 healthy · 1 failing · 2 unparsed / arg error.',
     ],
     status: [

package/dist/runtime/commands/prd-check.js

@@ -36,6 +36,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { parsePrd } from '../../core/prd-check/parser.js';
 import { buildEnvelope, exitCodeFor, renderTable, } from '../../core/prd-check/reporter.js';
+import { defaultSessionReviewDeps, renderSessionReview, runSessionReview, } from '../../core/prd-check/session-review.js';
 import { createDefaultDeps, verifyAll, } from '../../core/prd-check/verifiers.js';
 const DEFAULT_PRD_DIR = 'docs/prd';
 /**
@@ -44,6 +45,39 @@ const DEFAULT_PRD_DIR = 'docs/prd';
  * and sets `process.exitCode` to the worst verdict across the set.
  */
 export async function runPrdCheckCommand(ctx) {
+    // Wave 6 final (2026-05-27): session-review mode. Orthogonal to
+    // the verifier-graph mode — no PRD path resolution, no command
+    // registry. The runner walks up for PRD.md, reads the NDJSON
+    // events log, and dispatches a cross-review subagent.
+    if (ctx.flags.session) {
+        const status = (line) => {
+            // Emit status lines through the output sink so the slash
+            // surface can render them inline. The status payload is
+            // intentionally lightweight — only the human-facing text.
+            ctx.writeOutput({
+                command: 'prd-check',
+                overall: 'healthy',
+                envelopes: [],
+            }, line);
+        };
+        const sessionDeps = ctx.sessionDeps ??
+            defaultSessionReviewDeps({ onStatus: status });
+        const review = await runSessionReview(ctx.cwd, sessionDeps);
+        const overall = review.status === 'ok'
+            ? review.outstanding.length === 0
+                ? 'healthy'
+                : 'failing'
+            : 'unparsed';
+        const result = {
+            command: 'prd-check',
+            overall,
+            envelopes: [],
+            sessionReview: review,
+        };
+        ctx.writeOutput(result, renderSessionReview(review));
+        process.exitCode = exitCodeFor(overall);
+        return result;
+    }
     const paths = resolveTargets(ctx);
     if (paths.length === 0) {
         const result = {
@@ -199,6 +233,7 @@ export function combineOverall(verdicts) {
 export function parsePrdCheckArgs(args, options) {
     let json = options.jsonDefault;
     let all = false;
+    let session = false;
     let prdPath;
     for (const arg of args) {
         if (arg === '--json') {
@@ -209,6 +244,10 @@ export function parsePrdCheckArgs(args, options) {
             all = true;
             continue;
         }
+        if (arg === '--session') {
+            session = true;
+            continue;
+        }
         if (arg.startsWith('--')) {
             return { ok: false, error: `unknown flag: ${arg}` };
         }
@@ -217,10 +256,21 @@ export function parsePrdCheckArgs(args, options) {
         }
         prdPath = arg;
     }
-    if (!all && prdPath === undefined) {
+    // Wave 6 final (2026-05-27): `--session` is mutually exclusive with
+    // the verifier modes — it walks up for a PRD, reads NDJSON turns,
+    // and dispatches a subagent. No <path>, no --all, no command-
+    // registry inputs. Validating up-front gives operators a clear
+    // error instead of a silent fall-through.
+    if (session && (all || prdPath !== undefined)) {
+        return {
+            ok: false,
+            error: 'cannot combine --session with --all or <path>',
+        };
+    }
+    if (!session && !all && prdPath === undefined) {
         return {
             ok: false,
-            error: 'pugi prd-check <prd-path> | --all   (pass a PRD path or --all to scan docs/prd/**.md)',
+            error: 'pugi prd-check <prd-path> | --all | --session   (pass a PRD path, --all to scan docs/prd/**.md, or --session to review the live session against PRD.md)',
         };
     }
     if (all && prdPath !== undefined) {
@@ -228,7 +278,7 @@ export function parsePrdCheckArgs(args, options) {
     }
     return {
         ok: true,
-        flags: { json, all },
+        flags: { json, all, session },
         ...(prdPath !== undefined ? { prdPath } : {}),
     };
 }

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.30');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.31');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.30",
+  "version": "0.1.0-beta.31",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -54,7 +54,7 @@
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.30"
+    "@pugi/sdk": "0.1.0-beta.31"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",