openplanr 1.2.7 → 1.2.8

package/dist/models/types.d.ts

@@ -276,4 +276,124 @@ export interface VoiceStandupSession {
     transcript: string;
     errorMessage?: string;
 }
+export type ReviseAction = 'revise' | 'skip' | 'flag';
+/**
+ * Typed evidence kinds the agent must use when citing why a revision or
+ * flag is justified. Every kind is verifiable by the post-flight guard:
+ * - `file_exists` / `file_absent` — fs.stat check against `ref`
+ * - `grep_match` — substring match in the provided codebase context
+ * - `sibling_artifact` — quote from another artifact within the same scope
+ * - `source_quote` — quote from a declared source (PRD, design, ADR, rule file)
+ * - `pattern_rule` — an architectural pattern rule detected by existing pattern-rules
+ */
+export type ReviseEvidenceType = 'file_exists' | 'file_absent' | 'grep_match' | 'sibling_artifact' | 'source_quote' | 'pattern_rule';
+export interface ReviseEvidence {
+    type: ReviseEvidenceType;
+    /** What the evidence points at — a file path, artifact id, or rule id. */
+    ref: string;
+    /** Verbatim snippet supporting the evidence (when applicable to the type). */
+    quote?: string;
+}
+export interface ReviseAmbiguity {
+    /** Section of the target artifact the ambiguity touches. */
+    section: string;
+    /** Why the agent could not resolve this without a human decision. */
+    reason: string;
+}
+/**
+ * One agent decision for one artifact. Produced by the revise agent,
+ * validated by `aiReviseDecisionSchema`, verified by the post-flight guard.
+ *
+ * Invariants (enforced by the zod schema, not the TS type):
+ * - `action === 'revise'` requires non-empty `revisedMarkdown` and at least one `evidence` entry
+ * - `action === 'flag'` requires at least one `ambiguous` entry
+ * - `action === 'skip'` has no `revisedMarkdown` and no `ambiguous` entries
+ */
+export interface ReviseDecision {
+    artifactId: string;
+    action: ReviseAction;
+    /** Proposed full artifact markdown; required when action === 'revise'. */
+    revisedMarkdown?: string;
+    rationale: string;
+    /** Typed evidence citations — post-flight verifies these. Always present, empty when none. */
+    evidence: ReviseEvidence[];
+    /** Ambiguities requiring human decision — populated when action === 'flag', empty otherwise. */
+    ambiguous: ReviseAmbiguity[];
+}
+/** Audit log output format. */
+export type ReviseAuditFormat = 'md' | 'json';
+/**
+ * Terminal state recorded in the audit log for a single artifact in a
+ * revise run. Superset of the agent's `ReviseAction` so we can also record
+ * human overrides (skipped / quit) and system outcomes (failed / demoted).
+ */
+export type ReviseAuditOutcome = 'applied' | 'would-apply' | 'skipped-by-agent' | 'skipped-by-user' | 'flagged' | 'failed' | 'demoted';
+/**
+ * One row in the revise audit log. Flushed to disk as soon as it is
+ * produced (FEAT-012 §4.1) so an interrupted run still leaves an accurate
+ * on-disk record of what was written.
+ */
+export interface ReviseAuditEntry {
+    artifactId: string;
+    artifactPath?: string;
+    outcome: ReviseAuditOutcome;
+    rationale: string;
+    evidence: ReviseEvidence[];
+    ambiguous: ReviseAmbiguity[];
+    /** Cascade level the entry was produced at; omitted for single-artifact runs. */
+    cascadeLevel?: 'epic' | 'features' | 'stories' | 'tasks';
+    /** Unified diff against the pre-revise artifact body; present when outcome wrote content. */
+    diff?: string;
+    /** Present when outcome === 'failed'. */
+    error?: string;
+    timestamp: string;
+}
+/** Aggregate audit record covering a single revise run. */
+export interface ReviseAudit {
+    scope: string;
+    cascade: boolean;
+    dryRun: boolean;
+    startedAt: string;
+    completedAt?: string;
+    entries: ReviseAuditEntry[];
+    /** Populated when the run stopped before normal completion. */
+    interrupted?: {
+        reason: 'q' | 'sigint' | 'agent_error' | 'graph_rollback';
+        atArtifactId?: string;
+    };
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * One level in a top-down cascade. Tracks which artifact type the level
+ * covers and the ordered artifact ids processed at that level.
+ */
+export interface CascadeLevel {
+    type: ArtifactType;
+    label: 'epic' | 'features' | 'stories' | 'tasks';
+    artifactIds: string[];
+}
+/**
+ * Plan for a cascade run. Built by `buildCascadeOrder` and consumed by the
+ * cascade executor; immutable after construction.
+ */
+export interface CascadePlan {
+    /** Root artifact that started the cascade (epic / feature / story / task). */
+    rootId: string;
+    rootType: ArtifactType;
+    levels: CascadeLevel[];
+    /** Convenience: flat list of all artifact ids in cascade order. */
+    orderedIds: string[];
+}
+/** Live progress snapshot emitted during cascade execution. */
+export interface CascadeProgress {
+    completed: number;
+    total: number;
+    currentArtifactId: string;
+    currentLevelLabel: CascadeLevel['label'];
+    /** Rolling estimate of remaining time in seconds; null until enough samples collected. */
+    etaSeconds: number | null;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/models/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/models/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/models/types.ts"],"names":[],"mappings":"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"}

package/dist/services/atomic-write-service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Atomic artifact writes with sidecar backup (EPIC-003, FEAT-011 §3.0).
+ *
+ * Atomicity = temp file → fsync → rename. If any step fails mid-write, the
+ * original file was never modified and the temp file is removed. There is
+ * nothing to "roll back" at the file level — atomicity is the guarantee.
+ * The word "rollback" is reserved for FEAT-013's post-flight git mechanism.
+ *
+ * The sidecar backup copy is for *manual* recovery (e.g., if a user wants
+ * to diff an already-written artifact against what was there before). It is
+ * not consulted by any automated rollback path.
+ */
+export interface AtomicWriteOptions {
+    /**
+     * If provided, the original file is copied here before the write. A
+     * typical value is `.planr/reports/revise-<scope>-<date>/backup/<name>.bak`.
+     * Missing originals (first write) silently skip the backup step — there
+     * is nothing to back up.
+     */
+    backupPath?: string;
+}
+export interface AtomicWriteResult {
+    /** Absolute path of the file that now holds the new content. */
+    targetPath: string;
+    /** Absolute path of the sidecar backup, if one was created. */
+    backupPath?: string;
+}
+/**
+ * Replace `targetPath` atomically with `content`. Creates the target's
+ * parent directory if needed. When `options.backupPath` is set, the
+ * existing file (if any) is copied there before the new content is written.
+ */
+export declare function atomicWriteFile(targetPath: string, content: string, options?: AtomicWriteOptions): Promise<AtomicWriteResult>;
+/**
+ * Copy `targetPath` to `backupPath` when the original exists. Returns the
+ * backup path on success, or `undefined` when there was nothing to back up
+ * (original absent). Throws on unexpected I/O errors so callers do not
+ * silently proceed with a missing safety copy.
+ */
+export declare function backupIfPresent(targetPath: string, backupPath: string): Promise<string | undefined>;
+//# sourceMappingURL=atomic-write-service.d.ts.map

package/dist/services/atomic-write-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write-service.d.ts","sourceRoot":"","sources":["../../src/services/atomic-write-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA+B5B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B"}

package/dist/services/atomic-write-service.js

@@ -0,0 +1,87 @@
+/**
+ * Atomic artifact writes with sidecar backup (EPIC-003, FEAT-011 §3.0).
+ *
+ * Atomicity = temp file → fsync → rename. If any step fails mid-write, the
+ * original file was never modified and the temp file is removed. There is
+ * nothing to "roll back" at the file level — atomicity is the guarantee.
+ * The word "rollback" is reserved for FEAT-013's post-flight git mechanism.
+ *
+ * The sidecar backup copy is for *manual* recovery (e.g., if a user wants
+ * to diff an already-written artifact against what was there before). It is
+ * not consulted by any automated rollback path.
+ */
+import { close, constants, copyFile, fsync, open, rename, unlink, writeFile } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { ensureDir } from '../utils/fs.js';
+const copyFileAsync = promisify(copyFile);
+const fsyncAsync = promisify(fsync);
+const renameAsync = promisify(rename);
+const unlinkAsync = promisify(unlink);
+const writeFileAsync = promisify(writeFile);
+const openAsync = promisify(open);
+const closeAsync = promisify(close);
+/**
+ * Replace `targetPath` atomically with `content`. Creates the target's
+ * parent directory if needed. When `options.backupPath` is set, the
+ * existing file (if any) is copied there before the new content is written.
+ */
+export async function atomicWriteFile(targetPath, content, options = {}) {
+    await ensureDir(path.dirname(targetPath));
+    let backupCreated;
+    if (options.backupPath) {
+        backupCreated = await backupIfPresent(targetPath, options.backupPath);
+    }
+    // Temp file in the same directory as the target — required for rename to
+    // be atomic (cross-device renames fall back to copy + delete on some fs).
+    const tmpName = `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.tmp`;
+    const tmpPath = path.join(path.dirname(targetPath), tmpName);
+    try {
+        await writeFileAsync(tmpPath, content, 'utf-8');
+        // fsync the temp file so the new content is durable before the rename.
+        const fd = await openAsync(tmpPath, constants.O_RDONLY);
+        try {
+            await fsyncAsync(fd);
+        }
+        finally {
+            await closeAsync(fd);
+        }
+        await renameAsync(tmpPath, targetPath);
+        return { targetPath, backupPath: backupCreated };
+    }
+    catch (err) {
+        // Best-effort cleanup of the temp file; the original is already safe.
+        await unlinkAsync(tmpPath).catch(() => {
+            // ignore — temp file may not exist if write never started
+        });
+        throw err;
+    }
+}
+/**
+ * Copy `targetPath` to `backupPath` when the original exists. Returns the
+ * backup path on success, or `undefined` when there was nothing to back up
+ * (original absent). Throws on unexpected I/O errors so callers do not
+ * silently proceed with a missing safety copy.
+ */
+export async function backupIfPresent(targetPath, backupPath) {
+    await ensureDir(path.dirname(backupPath));
+    try {
+        await copyFileAsync(targetPath, backupPath, constants.COPYFILE_EXCL);
+        return backupPath;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            // Original file doesn't exist — not a real error, nothing to back up.
+            return undefined;
+        }
+        if (code === 'EEXIST') {
+            // Backup slot already taken (possible on re-run against same scope/date).
+            // Fall back to non-exclusive copy so re-runs remain idempotent.
+            await copyFileAsync(targetPath, backupPath);
+            return backupPath;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=atomic-write-service.js.map

package/dist/services/atomic-write-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write-service.js","sourceRoot":"","sources":["../../src/services/atomic-write-service.ts"],"names":[],"mappings":"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"}

package/dist/services/audit-log-service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Audit log writer for `planr revise` (EPIC-003, FEAT-011 §6.0).
+ *
+ * Every revise run — dry-run included — produces an audit log capturing
+ * applied / skipped / flagged / failed artifacts with rationale, evidence,
+ * ambiguities, and unified diffs. Entries are *flushed immediately* to
+ * disk as they are produced (see `appendEntry`), not batched at cascade
+ * end, so an interrupted run still leaves an accurate record of exactly
+ * what was written.
+ *
+ * Two output formats: Markdown (human-readable, default) and JSON (for CI /
+ * tooling / the `planr revise feedback` telemetry workflow planned in
+ * Phase 5).
+ *
+ * FEAT-014 §4.5 extends this writer with token-usage and cache-hit/miss
+ * stats; core structure lives here so those extensions are additive.
+ */
+import type { ReviseAudit, ReviseAuditEntry, ReviseAuditFormat } from '../models/types.js';
+export interface AuditLogWriterOptions {
+    projectDir: string;
+    scope: string;
+    cascade: boolean;
+    dryRun: boolean;
+    format: ReviseAuditFormat;
+    /** Override the default path (.planr/reports/revise-<scope>-<date>.<ext>). */
+    overridePath?: string;
+    /** ISO date used in the default filename. Defaults to today in local time. */
+    dateStamp?: string;
+}
+export interface AuditLogWriter {
+    /** Absolute path of the audit file being written. */
+    path: string;
+    /** Append one artifact entry and flush to disk immediately. */
+    appendEntry(entry: ReviseAuditEntry): void;
+    /**
+     * Close the audit — records `completedAt`, final summary, and (for JSON
+     * format) rewrites the file with the accumulated entries wrapped in a
+     * ReviseAudit envelope. Markdown output is append-only and closes with a
+     * trailing summary section.
+     */
+    close(summary?: Partial<Pick<ReviseAudit, 'interrupted' | 'tokenUsage'>>): void;
+}
+/**
+ * Create a writer. For Markdown output, writes the header immediately so
+ * users can `tail -f` the log during long cascades. For JSON output, the
+ * accumulated entries are materialized on close (JSON is not line-oriented).
+ */
+export declare function createAuditLogWriter(options: AuditLogWriterOptions): AuditLogWriter;
+export declare function readAuditJson(logPath: string): ReviseAudit;
+//# sourceMappingURL=audit-log-service.d.ts.map

package/dist/services/audit-log-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log-service.d.ts","sourceRoot":"","sources":["../../src/services/audit-log-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE3F,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC;CACjF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA0CnF;AA4JD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAM1D"}

package/dist/services/audit-log-service.js

@@ -0,0 +1,213 @@
+/**
+ * Audit log writer for `planr revise` (EPIC-003, FEAT-011 §6.0).
+ *
+ * Every revise run — dry-run included — produces an audit log capturing
+ * applied / skipped / flagged / failed artifacts with rationale, evidence,
+ * ambiguities, and unified diffs. Entries are *flushed immediately* to
+ * disk as they are produced (see `appendEntry`), not batched at cascade
+ * end, so an interrupted run still leaves an accurate record of exactly
+ * what was written.
+ *
+ * Two output formats: Markdown (human-readable, default) and JSON (for CI /
+ * tooling / the `planr revise feedback` telemetry workflow planned in
+ * Phase 5).
+ *
+ * FEAT-014 §4.5 extends this writer with token-usage and cache-hit/miss
+ * stats; core structure lives here so those extensions are additive.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Create a writer. For Markdown output, writes the header immediately so
+ * users can `tail -f` the log during long cascades. For JSON output, the
+ * accumulated entries are materialized on close (JSON is not line-oriented).
+ */
+export function createAuditLogWriter(options) {
+    const audit = {
+        scope: options.scope,
+        cascade: options.cascade,
+        dryRun: options.dryRun,
+        startedAt: new Date().toISOString(),
+        entries: [],
+    };
+    const logPath = options.overridePath ?? defaultAuditPath(options);
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    if (options.format === 'md') {
+        writeFileSync(logPath, renderHeader(audit), 'utf-8');
+    }
+    else {
+        writeFileSync(logPath, JSON.stringify(audit, null, 2), 'utf-8');
+    }
+    return {
+        path: logPath,
+        appendEntry(entry) {
+            audit.entries.push(entry);
+            if (options.format === 'md') {
+                appendFileSync(logPath, renderEntry(entry), 'utf-8');
+            }
+            else {
+                // JSON: rewrite the envelope each append. O(n²) over the run, but
+                // for a typical cascade (<100 artifacts) this is well under 10ms.
+                // The guarantee we need is durability, not write efficiency.
+                writeFileSync(logPath, JSON.stringify(audit, null, 2), 'utf-8');
+            }
+        },
+        close(summary) {
+            audit.completedAt = new Date().toISOString();
+            if (summary?.interrupted)
+                audit.interrupted = summary.interrupted;
+            if (summary?.tokenUsage)
+                audit.tokenUsage = summary.tokenUsage;
+            if (options.format === 'md') {
+                appendFileSync(logPath, renderFooter(audit), 'utf-8');
+            }
+            else {
+                writeFileSync(logPath, JSON.stringify(audit, null, 2), 'utf-8');
+            }
+        },
+    };
+}
+function defaultAuditPath(options) {
+    const date = options.dateStamp ?? toIsoDate(new Date());
+    const ext = options.format === 'json' ? 'json' : 'md';
+    const file = `revise-${options.scope}-${date}.${ext}`;
+    return path.join(options.projectDir, '.planr', 'reports', file);
+}
+function toIsoDate(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderHeader(audit) {
+    const mode = audit.dryRun ? 'dry-run' : 'apply';
+    const cascade = audit.cascade ? 'on' : 'off';
+    return [
+        `# Revise audit — ${audit.scope} (${toIsoDate(new Date(audit.startedAt))})`,
+        `> mode=${mode} · cascade=${cascade} · started=${audit.startedAt}`,
+        '',
+        '## Entries',
+        '',
+        '',
+    ].join('\n');
+}
+function renderEntry(entry) {
+    const out = [];
+    out.push(`### [${entry.outcome}] ${entry.artifactId}`);
+    if (entry.artifactPath)
+        out.push(`> ${entry.artifactPath}`);
+    out.push(`> timestamp=${entry.timestamp}`);
+    out.push('');
+    out.push(`**Rationale:** ${entry.rationale}`);
+    if (entry.evidence.length > 0) {
+        out.push('');
+        out.push('**Evidence:**');
+        for (const ev of entry.evidence) {
+            const quote = ev.quote ? ` — "${truncate(ev.quote, 120)}"` : '';
+            out.push(`- [${ev.type}] \`${ev.ref}\`${quote}`);
+        }
+    }
+    if (entry.ambiguous.length > 0) {
+        out.push('');
+        out.push('**Ambiguous (human decision required):**');
+        for (const a of entry.ambiguous) {
+            out.push(`- §${a.section}: ${a.reason}`);
+        }
+    }
+    if (entry.error) {
+        out.push('');
+        out.push(`**Error:** \`${entry.error}\``);
+    }
+    if (entry.diff && entry.diff.length > 0) {
+        out.push('');
+        out.push('**Diff:**');
+        out.push('```diff');
+        out.push(entry.diff);
+        out.push('```');
+    }
+    out.push('');
+    return `${out.join('\n')}\n`;
+}
+function renderFooter(audit) {
+    const counts = audit.entries.reduce((acc, e) => {
+        acc[e.outcome] = (acc[e.outcome] ?? 0) + 1;
+        return acc;
+    }, {});
+    const summaryRows = Object.entries(counts)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([outcome, n]) => `- ${outcome}: ${n}`);
+    const out = [];
+    out.push('');
+    out.push('## Summary');
+    out.push(`> completed=${audit.completedAt ?? 'n/a'} · entries=${audit.entries.length}`);
+    out.push('');
+    if (summaryRows.length > 0) {
+        out.push(...summaryRows);
+    }
+    else {
+        out.push('- (no entries recorded)');
+    }
+    // Cascade-level grouping — only emitted when at least one entry carries
+    // a level tag. Includes empty groups (with a count of 0) so readers can
+    // see which levels had nothing to process.
+    if (audit.cascade) {
+        const levels = [
+            'epic',
+            'features',
+            'stories',
+            'tasks',
+        ];
+        const byLevel = audit.entries.reduce((acc, e) => {
+            const key = e.cascadeLevel ?? 'unlabeled';
+            if (!acc[key])
+                acc[key] = [];
+            acc[key].push({ outcome: e.outcome, artifactId: e.artifactId });
+            return acc;
+        }, {});
+        out.push('');
+        out.push('### By cascade level');
+        for (const level of levels) {
+            const rows = byLevel[level] ?? [];
+            out.push('');
+            out.push(`**${level}** (${rows.length}):`);
+            if (rows.length === 0) {
+                out.push('- (no artifacts at this level)');
+                continue;
+            }
+            for (const row of rows) {
+                out.push(`- [${row.outcome}] ${row.artifactId}`);
+            }
+        }
+    }
+    if (audit.interrupted) {
+        out.push('');
+        out.push(`**Interrupted:** reason=${audit.interrupted.reason}${audit.interrupted.atArtifactId ? ` (at ${audit.interrupted.atArtifactId})` : ''}`);
+    }
+    if (audit.tokenUsage) {
+        out.push('');
+        out.push(`**Tokens:** ${audit.tokenUsage.inputTokens.toLocaleString()} in → ${audit.tokenUsage.outputTokens.toLocaleString()} out`);
+    }
+    out.push('');
+    return `${out.join('\n')}\n`;
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n)}…`;
+}
+// ---------------------------------------------------------------------------
+// Convenience: load an audit log back into a ReviseAudit (for tooling).
+// Not used by the revise command itself but required by future `planr
+// revise feedback <finding-id>` in Phase 5.
+// ---------------------------------------------------------------------------
+export function readAuditJson(logPath) {
+    if (!existsSync(logPath)) {
+        throw new Error(`Audit log not found at ${logPath}`);
+    }
+    const raw = readFileSync(logPath, 'utf-8');
+    return JSON.parse(raw);
+}
+//# sourceMappingURL=audit-log-service.js.map

package/dist/services/audit-log-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log-service.js","sourceRoot":"","sources":["../../src/services/audit-log-service.ts"],"names":[],"mappings":"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"}

package/dist/services/cascade-service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Cascade execution for `planr revise` (EPIC-003, FEAT-012).
+ *
+ * Responsibilities:
+ *
+ *   1. **Build cascade order** — top-down: epic → features → stories → tasks.
+ *      The artifact hierarchy is a strict tree; no cycle detection is needed.
+ *   2. **Execute the cascade** — for each artifact in order, call the
+ *      caller-provided `processOne` closure. The cascade stops on
+ *      SIGINT, `[q]uit`, or an unrecoverable agent error, and always
+ *      flushes audit entries immediately so an interrupted run leaves an
+ *      accurate record.
+ *   3. **Progress tracking** — emits a `CascadeProgress` snapshot before
+ *      each artifact, with a rolling ETA.
+ *
+ * This service owns NO rollback logic. Partial cascades that break the
+ * artifact graph are the concern of FEAT-013's post-flight rollback.
+ */
+import type { ArtifactType, CascadeLevel, CascadePlan, CascadeProgress, OpenPlanrConfig } from '../models/types.js';
+/**
+ * Resolve the cascade plan for a root artifact, walking its descendants in
+ * top-down order. For an epic root, the plan is:
+ *   EPIC → [features under epic] → [stories under those features] → [tasks under those stories]
+ * For a feature root, the EPIC level is empty and features contain only the root, etc.
+ */
+export declare function buildCascadeOrder(projectDir: string, config: OpenPlanrConfig, rootType: ArtifactType, rootId: string): Promise<CascadePlan>;
+export interface CascadeProcessOutcome {
+    /** Set to `false` when the processor wants the cascade to stop cleanly
+     *  (e.g., user pressed `q` at a diff prompt). `true` for normal continuation. */
+    continue: boolean;
+    /** When `continue === false`, the cascade records this reason in the interrupted state. */
+    stopReason?: 'q' | 'agent_error' | 'graph_rollback';
+}
+export type CascadeProcessor = (args: {
+    artifactId: string;
+    levelLabel: CascadeLevel['label'];
+    progress: CascadeProgress;
+}) => Promise<CascadeProcessOutcome>;
+export interface CascadeExecuteOptions {
+    plan: CascadePlan;
+    processor: CascadeProcessor;
+    /** Called with every progress snapshot; typically wires into a spinner. */
+    onProgress?: (p: CascadeProgress) => void;
+    /** Overrides the process-level SIGINT handler for tests; default uses `process`. */
+    signalTarget?: NodeJS.Process;
+}
+export interface CascadeResult {
+    completed: number;
+    total: number;
+    interrupted?: {
+        reason: 'q' | 'sigint' | 'agent_error';
+        atArtifactId: string;
+    };
+}
+/**
+ * Drive the cascade plan through the provided processor. Installs a SIGINT
+ * handler for the duration of the run; on Ctrl+C it waits for the current
+ * artifact to finish (so no half-written files) and then stops. The SIGINT
+ * handler is removed on completion whether or not it fired.
+ */
+export declare function executeCascade(options: CascadeExecuteOptions): Promise<CascadeResult>;
+//# sourceMappingURL=cascade-service.d.ts.map

package/dist/services/cascade-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-service.d.ts","sourceRoot":"","sources":["../../src/services/cascade-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAQ5B;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAyEtB;AAMD,MAAM,WAAW,qBAAqB;IACpC;qFACiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,GAAG,GAAG,aAAa,GAAG,gBAAgB,CAAC;CACrD;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE,eAAe,CAAC;CAC3B,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,GAAG,GAAG,QAAQ,GAAG,aAAa,CAAC;QACvC,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqE3F"}