openplanr 1.2.7 → 1.3.0

package/dist/services/revise-plan-service.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Revise plan parser.
+ *
+ * A "plan" is a previously-written revise audit log that we replay to disk
+ * without any model calls. This service parses a Markdown audit file
+ * emitted by `audit-log-service.ts` back into structured `ReviseAuditEntry`
+ * records that the CLI's apply-from-audit path can replay.
+ *
+ * Parsing is deliberately strict about structure but tolerant of
+ * whitespace — audit files are written by us and edited by no-one, so we
+ * can rely on the heading hierarchy and section markers. If a user has
+ * hand-edited the audit, the parser surfaces specific errors so the user
+ * can fix or discard the file rather than silently getting bad replays.
+ *
+ * Future extension: we may emit a sidecar `.plan.json` next to the
+ * Markdown audit to carry content hashes and `revisedMarkdown` without
+ * parsing overhead. The Markdown path remains supported indefinitely —
+ * older audits predate any sidecar format and still need replay support.
+ */
+import type { ReviseAuditEntry } from '../models/types.js';
+export interface ReplayablePlan {
+    /** Absolute path of the audit file this plan was parsed from. */
+    sourcePath: string;
+    /** Scope recorded in the audit header (e.g., "EPIC-001"). */
+    scope: string;
+    /** When the dry-run was started, from the audit header. */
+    startedAt?: string;
+    /** All entries, preserving original order. Includes skipped/flagged for the summary. */
+    entries: ReviseAuditEntry[];
+}
+/**
+ * Parse a revise Markdown audit log into its constituent entries.
+ * Throws if the file cannot be read, is empty, or has no entries.
+ */
+export declare function readPlanFromAudit(auditPath: string): ReplayablePlan;
+/** Entries that can actually be written on replay (have a diff and target path). */
+export declare function filterReplayable(plan: ReplayablePlan): ReviseAuditEntry[];
+//# sourceMappingURL=revise-plan-service.d.ts.map

package/dist/services/revise-plan-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revise-plan-service.d.ts","sourceRoot":"","sources":["../../src/services/revise-plan-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAIjB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAuBnE;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,EAAE,CAIzE"}

package/dist/services/revise-plan-service.js

@@ -0,0 +1,151 @@
+/**
+ * Revise plan parser.
+ *
+ * A "plan" is a previously-written revise audit log that we replay to disk
+ * without any model calls. This service parses a Markdown audit file
+ * emitted by `audit-log-service.ts` back into structured `ReviseAuditEntry`
+ * records that the CLI's apply-from-audit path can replay.
+ *
+ * Parsing is deliberately strict about structure but tolerant of
+ * whitespace — audit files are written by us and edited by no-one, so we
+ * can rely on the heading hierarchy and section markers. If a user has
+ * hand-edited the audit, the parser surfaces specific errors so the user
+ * can fix or discard the file rather than silently getting bad replays.
+ *
+ * Future extension: we may emit a sidecar `.plan.json` next to the
+ * Markdown audit to carry content hashes and `revisedMarkdown` without
+ * parsing overhead. The Markdown path remains supported indefinitely —
+ * older audits predate any sidecar format and still need replay support.
+ */
+import { readFileSync } from 'node:fs';
+/**
+ * Parse a revise Markdown audit log into its constituent entries.
+ * Throws if the file cannot be read, is empty, or has no entries.
+ */
+export function readPlanFromAudit(auditPath) {
+    let raw;
+    try {
+        raw = readFileSync(auditPath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Cannot read audit file at ${auditPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (raw.length === 0) {
+        throw new Error(`Audit file ${auditPath} is empty.`);
+    }
+    const { scope, startedAt } = parseHeader(raw, auditPath);
+    const entries = parseEntries(raw, auditPath);
+    if (entries.length === 0) {
+        throw new Error(`Audit file ${auditPath} contains no entries — nothing to apply. Re-run revise with --dry-run first.`);
+    }
+    return { sourcePath: auditPath, scope, startedAt, entries };
+}
+/** Entries that can actually be written on replay (have a diff and target path). */
+export function filterReplayable(plan) {
+    return plan.entries.filter((e) => e.outcome === 'would-apply' && e.artifactPath && e.diff && e.diff.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Parsing internals
+// ---------------------------------------------------------------------------
+function parseHeader(raw, auditPath) {
+    const title = raw.match(/^#\s+Revise audit\s+—\s+([A-Z]+-\d{3,})\b/m);
+    if (!title) {
+        throw new Error(`Audit file ${auditPath} does not start with a recognizable header (expected "# Revise audit — <SCOPE>").`);
+    }
+    const scope = title[1];
+    const started = raw.match(/started=([0-9T:\-.Z]+)/);
+    return { scope, startedAt: started ? started[1] : undefined };
+}
+/**
+ * Split the audit body into entries by the `### [outcome] ArtifactId` heading.
+ * Each entry then parses independently; any entry that fails to parse is
+ * collected with a reason in its error field rather than aborting the whole
+ * parse — the caller filters to `would-apply` for replay, so skipped/malformed
+ * entries simply won't be replayed.
+ */
+function parseEntries(raw, auditPath) {
+    // The `## Entries` / `## Summary` headings bookend the body; we scan between them.
+    const entriesStart = raw.indexOf('\n## Entries');
+    const summaryStart = raw.indexOf('\n## Summary');
+    const body = entriesStart >= 0
+        ? raw.slice(entriesStart, summaryStart >= 0 ? summaryStart : raw.length)
+        : raw;
+    // Split on the entry heading. Each chunk (except the first, which is the
+    // `## Entries` preamble) corresponds to one entry.
+    const chunks = body.split(/\n(?=### \[)/);
+    const entries = [];
+    for (const chunk of chunks) {
+        const trimmed = chunk.trim();
+        if (!trimmed.startsWith('### ['))
+            continue;
+        const parsed = parseEntry(trimmed, auditPath);
+        if (parsed)
+            entries.push(parsed);
+    }
+    return entries;
+}
+function parseEntry(chunk, _auditPath) {
+    const heading = chunk.match(/^### \[([^\]]+)\]\s+(\S+)/);
+    if (!heading)
+        return null;
+    const outcome = heading[1];
+    const artifactId = heading[2];
+    const artifactPathMatch = chunk.match(/\n>\s+(\/[^\s\n]+\.md)/);
+    const artifactPath = artifactPathMatch ? artifactPathMatch[1] : undefined;
+    const timestampMatch = chunk.match(/timestamp=([0-9T:\-.Z]+)/);
+    const timestamp = timestampMatch ? timestampMatch[1] : new Date().toISOString();
+    const rationaleMatch = chunk.match(/\*\*Rationale:\*\*\s+([\s\S]*?)(?=\n\n\*\*|\n\n```|$)/);
+    const rationale = rationaleMatch ? rationaleMatch[1].trim() : '';
+    const evidence = parseEvidenceList(chunk);
+    const ambiguous = parseAmbiguousList(chunk);
+    const diff = parseDiffBlock(chunk);
+    return {
+        artifactId,
+        artifactPath,
+        outcome,
+        rationale,
+        evidence,
+        ambiguous,
+        diff,
+        timestamp,
+        // Older audits don't carry these; the replay flow is responsible for
+        // computing / verifying them against live content when present.
+    };
+}
+function parseEvidenceList(chunk) {
+    // Match from `**Evidence:**` heading to the next `**Xxx:**` / `## ` /
+    // fenced-diff / end.
+    const section = chunk.match(/\*\*Evidence:\*\*\s*\n([\s\S]*?)(?=\n\n\*\*[A-Z]|\n\n```|\n## |$)/);
+    if (!section)
+        return [];
+    const out = [];
+    const lineRe = /^-\s+\[([a-z_]+)\]\s+`([^`]+)`(?:\s+—\s+"([\s\S]*?)"\s*$)?/gm;
+    let m = lineRe.exec(section[1]);
+    while (m !== null) {
+        out.push({
+            type: m[1],
+            ref: m[2],
+            quote: m[3],
+        });
+        m = lineRe.exec(section[1]);
+    }
+    return out;
+}
+function parseAmbiguousList(chunk) {
+    const section = chunk.match(/\*\*Ambiguous[^*]*\*\*\s*\n([\s\S]*?)(?=\n\n\*\*[A-Z]|\n\n```|\n## |$)/);
+    if (!section)
+        return [];
+    const out = [];
+    const lineRe = /^-\s+§([^:]+):\s+(.+)$/gm;
+    let m = lineRe.exec(section[1]);
+    while (m !== null) {
+        out.push({ section: m[1].trim(), reason: m[2].trim() });
+        m = lineRe.exec(section[1]);
+    }
+    return out;
+}
+function parseDiffBlock(chunk) {
+    const m = chunk.match(/\*\*Diff:\*\*\s*\n```diff\n([\s\S]*?)\n```/);
+    return m ? m[1] : undefined;
+}
+//# sourceMappingURL=revise-plan-service.js.map

package/dist/services/revise-plan-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revise-plan-service.js","sourceRoot":"","sources":["../../src/services/revise-plan-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAmBvC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6BAA6B,SAAS,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC9F,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,cAAc,SAAS,YAAY,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAE7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,8EAA8E,CACtG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAC9D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CACpF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,WAAW,CAAC,GAAW,EAAE,SAAiB;IACjD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,mFAAmF,CAC3G,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACpD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,GAAW,EAAE,SAAiB;IAClD,mFAAmF;IACnF,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,IAAI,GACR,YAAY,IAAI,CAAC;QACf,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QACxE,CAAC,CAAC,GAAG,CAAC;IAEV,yEAAyE;IACzE,mDAAmD;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9C,IAAI,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa,EAAE,UAAkB;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACzD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAuB,CAAC;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9B,MAAM,iBAAiB,GAAG,KAAK,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1E,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEhF,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC5F,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAEnC,OAAO;QACL,UAAU;QACV,YAAY;QACZ,OAAO;QACP,SAAS;QACT,QAAQ;QACR,SAAS;QACT,IAAI;QACJ,SAAS;QACT,qEAAqE;QACrE,gEAAgE;KACjE,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa;IACtC,sEAAsE;IACtE,qBAAqB;IACrB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACjG,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,8DAA8D,CAAC;IAC9E,IAAI,CAAC,GAA2B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QAClB,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,CAAC,CAAuB;YAChC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;YACT,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;SACZ,CAAC,CAAC;QACH,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CACzB,wEAAwE,CACzE,CAAC;IACF,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,GAAG,GAA+C,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,0BAA0B,CAAC;IAC1C,IAAI,CAAC,GAA2B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QAClB,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACpE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9B,CAAC"}

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

@@ -0,0 +1,115 @@
+/**
+ * `planr revise` — core service.
+ *
+ * Exposes composable primitives. `reviseArtifact` produces dry-run decisions;
+ * `applyDecision` writes them to disk. The verifier context is exposed so
+ * callers can run `verifyDecision` against the same inputs the agent saw.
+ */
+import { type RevisePromptArtifact, type ReviseWritableScope } from '../ai/prompts/prompt-builder.js';
+import { type AIProvider, type AIUsage } from '../ai/types.js';
+import type { ArtifactType, OpenPlanrConfig, ReviseAuditEntry, ReviseDecision } from '../models/types.js';
+import type { AuditLogWriter } from './audit-log-service.js';
+import type { EvidenceVerifierContext } from './evidence-verifier.js';
+export interface ReviseArtifactOptions {
+    /** Must be `true` in this release; reserved for future write path. */
+    dryRun: true;
+    /** Which parts of the artifact the agent may modify. Default: 'all'. */
+    writableScope?: ReviseWritableScope;
+    /** Skip codebase context assembly (fast mode). Default: include code. */
+    noCodeContext?: boolean;
+    /** Skip immediate-sibling context gathering (fast mode / first-pass). Default: include. */
+    noSiblingContext?: boolean;
+    /** Maximum number of sibling artifacts to inject (budget guard). Default: 8. */
+    maxSiblings?: number;
+}
+export interface ReviseArtifactContextStats {
+    parentsLoaded: number;
+    siblingsLoaded: number;
+    codebaseContextIncluded: boolean;
+    sourcesLoaded: number;
+}
+export interface ReviseArtifactResult {
+    decision: ReviseDecision;
+    usage: AIUsage;
+    contextStats: ReviseArtifactContextStats;
+    /** Filesystem path the decision's revisedMarkdown would be written to. */
+    artifactPath: string;
+    /** Pre-revise raw content, used for diff rendering and auditing. */
+    originalContent: string;
+    /** Context the caller should pass to `verifyDecision`. */
+    verifierContext: EvidenceVerifierContext;
+}
+/**
+ * Error thrown when an artifact id cannot be resolved to an artifact type or
+ * the artifact file does not exist on disk.
+ */
+export declare class ReviseArtifactNotFoundError extends Error {
+    readonly artifactId: string;
+    constructor(artifactId: string, message: string);
+}
+/**
+ * Revise a single artifact (dry-run).
+ *
+ * Does NOT write any files. The returned decision is the agent output after
+ * schema validation; evidence verification, diff preview, and write live in
+ * the CLI / apply path. Cascade, siblings, and declared sources are future
+ * extensions.
+ */
+export declare function reviseArtifact(projectDir: string, config: OpenPlanrConfig, provider: AIProvider, artifactId: string, options: ReviseArtifactOptions): Promise<ReviseArtifactResult>;
+export interface ApplyDecisionOptions {
+    artifactPath: string;
+    originalContent: string;
+    decision: ReviseDecision;
+    /**
+     * Directory where sidecar backups are written. Typically
+     * `.planr/reports/revise-<scope>-<date>/backup/` — set by the CLI.
+     */
+    backupDir: string;
+    /** Audit writer that will persist an entry describing the outcome. */
+    audit: AuditLogWriter;
+    /** When true, produces an audit entry but does not write the artifact. */
+    dryRun: boolean;
+    /** Cascade level tag for audit log grouping; omit for single-artifact runs. */
+    cascadeLevel?: ReviseAuditEntry['cascadeLevel'];
+}
+export interface ApplyDecisionResult {
+    outcome: ReviseAuditEntry['outcome'];
+    wrote: boolean;
+    diff: string;
+}
+/**
+ * Apply a (verified) decision: write the artifact atomically when
+ * `action === 'revise'` and `dryRun` is false, emit an audit entry
+ * describing the outcome either way.
+ *
+ * Caller is expected to have already run `verifyDecision` — `applyDecision`
+ * trusts that whatever decision arrives is allowed to be written.
+ */
+export declare function applyDecision(options: ApplyDecisionOptions): Promise<ApplyDecisionResult>;
+/**
+ * `true` when the agent's `revisedMarkdown` is byte-identical to `original`,
+ * or differs only in trailing whitespace/newlines (LLM markdown serializers
+ * routinely drop or add one trailing newline without changing semantics).
+ *
+ * Exported so the `--apply-from <audit>` replay path and the interactive
+ * UI can share the same unchanged-detection rule.
+ */
+export declare function isEffectivelyUnchanged(original: string, revised: string | undefined): boolean;
+/**
+ * Load immediate-sibling artifacts (same artifact type, same parent) as
+ * prompt entries. Lazy-reads each sibling's body only if it's going to be
+ * included — the listing check is cheap, the reads are budgeted by
+ * `maxSiblings` (default 8) so the prompt stays within token budget even on
+ * epics with many features.
+ *
+ * For epic scope, there are no siblings (epics live at the top). For types
+ * without a parent-id relationship (quick, backlog, etc.), returns empty.
+ */
+export declare function loadSiblingPromptArtifacts(projectDir: string, config: OpenPlanrConfig, type: ArtifactType, id: string, maxSiblings: number): Promise<RevisePromptArtifact[]>;
+/**
+ * Resolve the parent chain for an artifact and return it as the ordered
+ * `RevisePromptArtifact[]` the prompt builder expects (epic → feature →
+ * story). Empty array for top-level artifacts (epic scope).
+ */
+export declare function loadParentPromptArtifacts(projectDir: string, config: OpenPlanrConfig, type: ArtifactType, id: string): Promise<RevisePromptArtifact[]>;
+//# sourceMappingURL=revise-service.d.ts.map

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

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

package/dist/services/revise-service.js

@@ -0,0 +1,294 @@
+/**
+ * `planr revise` — core service.
+ *
+ * Exposes composable primitives. `reviseArtifact` produces dry-run decisions;
+ * `applyDecision` writes them to disk. The verifier context is exposed so
+ * callers can run `verifyDecision` against the same inputs the agent saw.
+ */
+import path from 'node:path';
+import { buildCodebaseContext, extractKeywords, formatCodebaseContext, } from '../ai/codebase/context-builder.js';
+import { buildRevisePrompt, } from '../ai/prompts/prompt-builder.js';
+import { aiReviseDecisionSchema } from '../ai/schemas/ai-response-schemas.js';
+import { TOKEN_BUDGETS } from '../ai/types.js';
+import { logger } from '../utils/logger.js';
+import { generateJSON } from './ai-service.js';
+import { findArtifactTypeById, getArtifactDir, getParentChain, listArtifacts, readArtifact, readArtifactRaw, resolveArtifactFilename, } from './artifact-service.js';
+import { atomicWriteFile } from './atomic-write-service.js';
+import { renderDiff } from './diff-service.js';
+import { getCanonicalSections } from './template-sections.js';
+/**
+ * Error thrown when an artifact id cannot be resolved to an artifact type or
+ * the artifact file does not exist on disk.
+ */
+export class ReviseArtifactNotFoundError extends Error {
+    artifactId;
+    constructor(artifactId, message) {
+        super(message);
+        this.name = 'ReviseArtifactNotFoundError';
+        this.artifactId = artifactId;
+    }
+}
+/**
+ * Revise a single artifact (dry-run).
+ *
+ * Does NOT write any files. The returned decision is the agent output after
+ * schema validation; evidence verification, diff preview, and write live in
+ * the CLI / apply path. Cascade, siblings, and declared sources are future
+ * extensions.
+ */
+export async function reviseArtifact(projectDir, config, provider, artifactId, options) {
+    const artifactType = findArtifactTypeById(artifactId);
+    if (!artifactType) {
+        throw new ReviseArtifactNotFoundError(artifactId, `Cannot determine artifact type from ID: ${artifactId}. Expected format: EPIC-001, FEAT-001, US-001, TASK-001.`);
+    }
+    const artifactRaw = await readArtifactRaw(projectDir, config, artifactType, artifactId);
+    if (artifactRaw === null) {
+        throw new ReviseArtifactNotFoundError(artifactId, `Artifact ${artifactId} not found under ${artifactType}/ directory.`);
+    }
+    const parents = await loadParentPromptArtifacts(projectDir, config, artifactType, artifactId);
+    const siblings = options.noSiblingContext
+        ? []
+        : await loadSiblingPromptArtifacts(projectDir, config, artifactType, artifactId, options.maxSiblings ?? 8);
+    let codebaseContextFormatted;
+    let codebaseCtx;
+    if (!options.noCodeContext) {
+        const keywords = extractKeywords(artifactRaw);
+        codebaseCtx = await buildCodebaseContext(projectDir, keywords);
+        codebaseContextFormatted = formatCodebaseContext(codebaseCtx);
+    }
+    const messages = buildRevisePrompt({
+        artifact: { id: artifactId, type: artifactType, content: artifactRaw },
+        parents,
+        siblings,
+        codebaseContextFormatted,
+        sources: [], // Declared-sources loader lands with the revise.yaml config work
+        writableScope: options.writableScope ?? 'all',
+        canonicalSections: getCanonicalSections(artifactType),
+    });
+    logger.debug(`reviseArtifact: calling AI for ${artifactId}`);
+    const result = await generateJSON(provider, messages, aiReviseDecisionSchema, {
+        maxTokens: TOKEN_BUDGETS.revise,
+    });
+    // resolveArtifactFilename strips the `.md` extension (other callers want the
+    // slug form). Revise must write to the full `.md` file, so append the
+    // extension explicitly. Defensive fallback if a future version ever returns
+    // a filename with the extension intact.
+    const filenameNoExt = await resolveArtifactFilename(projectDir, config, artifactType, artifactId);
+    const artifactDir = path.join(projectDir, getArtifactDir(config, artifactType));
+    const fullFilename = filenameNoExt.endsWith('.md') ? filenameNoExt : `${filenameNoExt}.md`;
+    const artifactPath = path.join(artifactDir, fullFilename);
+    const verifierContext = {
+        projectDir,
+        config,
+        artifactDir: path.dirname(artifactPath),
+        codebaseContextFormatted,
+        knownSourceRefs: [], // sources loader (future extension) will populate
+        knownPatternRuleIds: codebaseCtx ? codebaseCtx.patternRules.map((r) => r.name) : [],
+    };
+    return {
+        decision: result.result,
+        usage: result.usage ?? { inputTokens: 0, outputTokens: 0 },
+        contextStats: {
+            parentsLoaded: parents.length,
+            siblingsLoaded: siblings.length,
+            codebaseContextIncluded: !!codebaseContextFormatted,
+            sourcesLoaded: 0,
+        },
+        artifactPath,
+        originalContent: artifactRaw,
+        verifierContext,
+    };
+}
+/**
+ * Apply a (verified) decision: write the artifact atomically when
+ * `action === 'revise'` and `dryRun` is false, emit an audit entry
+ * describing the outcome either way.
+ *
+ * Caller is expected to have already run `verifyDecision` — `applyDecision`
+ * trusts that whatever decision arrives is allowed to be written.
+ */
+export async function applyDecision(options) {
+    const { decision, audit, dryRun, originalContent, artifactPath, backupDir } = options;
+    const timestamp = new Date().toISOString();
+    if (decision.action === 'skip') {
+        audit.appendEntry({
+            artifactId: decision.artifactId,
+            artifactPath,
+            outcome: 'skipped-by-agent',
+            rationale: decision.rationale,
+            evidence: decision.evidence,
+            ambiguous: decision.ambiguous,
+            cascadeLevel: options.cascadeLevel,
+            timestamp,
+        });
+        return { outcome: 'skipped-by-agent', wrote: false, diff: '' };
+    }
+    if (decision.action === 'flag') {
+        // When a revise → flag demotion happened upstream, `revisedMarkdown`
+        // still holds the agent's proposed rewrite. Include the would-have-been
+        // diff in the audit entry so users can see what was rejected and decide
+        // whether to hand-apply it.
+        const proposedDiff = decision.revisedMarkdown
+            ? renderDiff(originalContent, decision.revisedMarkdown, {
+                color: false,
+                oldLabel: `${decision.artifactId} (before)`,
+                newLabel: `${decision.artifactId} (proposed — REJECTED by verifier)`,
+            })
+            : undefined;
+        audit.appendEntry({
+            artifactId: decision.artifactId,
+            artifactPath,
+            outcome: 'flagged',
+            rationale: decision.rationale,
+            evidence: decision.evidence,
+            ambiguous: decision.ambiguous,
+            cascadeLevel: options.cascadeLevel,
+            ...(proposedDiff ? { diff: proposedDiff } : {}),
+            timestamp,
+        });
+        return { outcome: 'flagged', wrote: false, diff: proposedDiff ?? '' };
+    }
+    // action === 'revise'
+    const diff = decision.revisedMarkdown
+        ? renderDiff(originalContent, decision.revisedMarkdown, {
+            color: false,
+            oldLabel: `${decision.artifactId} (before)`,
+            newLabel: `${decision.artifactId} (proposed)`,
+        })
+        : '';
+    // Short-circuit: if the agent returned content that is effectively
+    // identical to the original (byte-exact, or only trailing-whitespace
+    // differences from markdown serializer normalization), skip the write
+    // and report `unchanged-by-agent`. Prevents the "Proposed diff: <empty>
+    // → applied" UX bug where a trivial newline-strip got reported as a
+    // successful revise even though the agent explicitly said the artifact
+    // was already well-structured.
+    if (isEffectivelyUnchanged(originalContent, decision.revisedMarkdown)) {
+        audit.appendEntry({
+            artifactId: decision.artifactId,
+            artifactPath,
+            outcome: 'unchanged-by-agent',
+            rationale: decision.rationale,
+            evidence: decision.evidence,
+            ambiguous: decision.ambiguous,
+            cascadeLevel: options.cascadeLevel,
+            timestamp,
+        });
+        return { outcome: 'unchanged-by-agent', wrote: false, diff: '' };
+    }
+    if (dryRun) {
+        audit.appendEntry({
+            artifactId: decision.artifactId,
+            artifactPath,
+            outcome: 'would-apply',
+            rationale: decision.rationale,
+            evidence: decision.evidence,
+            ambiguous: decision.ambiguous,
+            cascadeLevel: options.cascadeLevel,
+            diff,
+            timestamp,
+        });
+        return { outcome: 'would-apply', wrote: false, diff };
+    }
+    // Real apply: atomic write + sidecar backup.
+    const backupPath = path.join(backupDir, `${decision.artifactId}.md.bak`);
+    await atomicWriteFile(artifactPath, decision.revisedMarkdown ?? '', { backupPath });
+    audit.appendEntry({
+        artifactId: decision.artifactId,
+        artifactPath,
+        outcome: 'applied',
+        rationale: decision.rationale,
+        evidence: decision.evidence,
+        ambiguous: decision.ambiguous,
+        cascadeLevel: options.cascadeLevel,
+        diff,
+        timestamp,
+    });
+    return { outcome: 'applied', wrote: true, diff };
+}
+/**
+ * `true` when the agent's `revisedMarkdown` is byte-identical to `original`,
+ * or differs only in trailing whitespace/newlines (LLM markdown serializers
+ * routinely drop or add one trailing newline without changing semantics).
+ *
+ * Exported so the `--apply-from <audit>` replay path and the interactive
+ * UI can share the same unchanged-detection rule.
+ */
+export function isEffectivelyUnchanged(original, revised) {
+    if (revised === undefined)
+        return true;
+    if (revised === original)
+        return true;
+    return revised.replace(/\s+$/, '') === original.replace(/\s+$/, '');
+}
+/**
+ * Load immediate-sibling artifacts (same artifact type, same parent) as
+ * prompt entries. Lazy-reads each sibling's body only if it's going to be
+ * included — the listing check is cheap, the reads are budgeted by
+ * `maxSiblings` (default 8) so the prompt stays within token budget even on
+ * epics with many features.
+ *
+ * For epic scope, there are no siblings (epics live at the top). For types
+ * without a parent-id relationship (quick, backlog, etc.), returns empty.
+ */
+export async function loadSiblingPromptArtifacts(projectDir, config, type, id, maxSiblings) {
+    const parentFieldByType = {
+        feature: 'epicId',
+        story: 'featureId',
+        task: 'storyId',
+    };
+    const parentField = parentFieldByType[type];
+    if (!parentField)
+        return [];
+    const self = await readArtifact(projectDir, config, type, id);
+    if (!self)
+        return [];
+    const parentId = self.data[parentField];
+    if (!parentId)
+        return [];
+    const siblings = [];
+    const listing = await listArtifacts(projectDir, config, type);
+    for (const entry of listing) {
+        if (siblings.length >= maxSiblings)
+            break;
+        if (entry.id === id)
+            continue;
+        const sib = await readArtifact(projectDir, config, type, entry.id);
+        if (sib && sib.data[parentField] === parentId) {
+            siblings.push({ id: entry.id, type, content: sib.content });
+        }
+    }
+    return siblings;
+}
+/**
+ * Resolve the parent chain for an artifact and return it as the ordered
+ * `RevisePromptArtifact[]` the prompt builder expects (epic → feature →
+ * story). Empty array for top-level artifacts (epic scope).
+ */
+export async function loadParentPromptArtifacts(projectDir, config, type, id) {
+    const chain = await getParentChain(projectDir, config, type, id);
+    const parents = [];
+    if (chain.epic) {
+        parents.push({
+            id: String(chain.epic.data.id),
+            type: 'epic',
+            content: chain.epic.content,
+        });
+    }
+    if (chain.feature) {
+        parents.push({
+            id: String(chain.feature.data.id),
+            type: 'feature',
+            content: chain.feature.content,
+        });
+    }
+    if (chain.story) {
+        parents.push({
+            id: String(chain.story.data.id),
+            type: 'story',
+            content: chain.story.content,
+        });
+    }
+    return parents;
+}
+//# sourceMappingURL=revise-service.js.map

package/dist/services/revise-service.js.map

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

package/dist/services/template-sections.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical section lists per artifact type.
+ *
+ * The revise prompt uses these to give the agent a *soft* conformance hint:
+ * "these are the sections a ${type} artifact canonically has — don't invent
+ * new ones; flag instead." This prevents the failure mode where the agent
+ * helpfully adds something like `## Relevant Files` to an epic (a task-level
+ * convention) when there is no drift justifying it.
+ *
+ * The lists mirror what the Handlebars templates in `src/templates/<type>/`
+ * actually emit. Kept hardcoded rather than parsed from the .hbs files at
+ * runtime because:
+ *
+ *   1. Handlebars templates contain `{{ }}` interpolation that would need
+ *      stripping before we could grep `## ` headings.
+ *   2. If a template gains a new section, we want an explicit review step
+ *      in this file, not silent pickup.
+ *   3. Parsing templates would couple revise to handlebars internals.
+ *
+ * When you add or rename a template section, update the matching entry here.
+ */
+import type { ArtifactType } from '../models/types.js';
+/**
+ * Return the canonical section list for an artifact type, or `undefined`
+ * when the type has no enforced convention (e.g., `backlog`).
+ */
+export declare function getCanonicalSections(type: ArtifactType): readonly string[] | undefined;
+//# sourceMappingURL=template-sections.d.ts.map