supipowers 1.2.6 → 1.5.0

package/src/review/types.ts

@@ -0,0 +1,296 @@
+import { Type } from "@sinclair/typebox";
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import type {
+  ConfiguredReviewAgent,
+  ReviewAgentConfig,
+  ReviewAgentDefinition,
+  ReviewAgentsConfig,
+  ReviewFinding,
+  ReviewFixOutput,
+  ReviewFixRecord,
+  ReviewIterationSummary,
+  ReviewOutput,
+  ReviewPostConsolidationAction,
+  ReviewScope,
+  ReviewScopeFile,
+  ReviewScopeStats,
+  ReviewSession,
+  ReviewSessionArtifacts,
+} from "../types.js";
+export type {
+  ConfiguredReviewAgent,
+  ReviewAgentConfig,
+  ReviewAgentDefinition,
+  ReviewAgentsConfig,
+  ReviewFinding,
+  ReviewFixOutput,
+  ReviewFixRecord,
+  ReviewIterationSummary,
+  ReviewOutput,
+  ReviewPostConsolidationAction,
+  ReviewScope,
+  ReviewScopeFile,
+  ReviewScopeStats,
+  ReviewSession,
+  ReviewSessionArtifacts,
+} from "../types.js";
+export const REVIEW_LEVELS = ["quick", "deep", "multi-agent"] as const;
+export const REVIEW_SCOPE_MODES = ["pull-request", "uncommitted", "commit", "custom"] as const;
+export const REVIEW_OUTPUT_STATUSES = ["passed", "failed", "blocked"] as const;
+export const REVIEW_FINDING_SEVERITIES = ["error", "warning", "info"] as const;
+export const REVIEW_FINDING_PRIORITIES = ["P0", "P1", "P2", "P3"] as const;
+export const REVIEW_VALIDATION_VERDICTS = ["confirmed", "rejected", "uncertain"] as const;
+export const REVIEW_SESSION_STATUSES = ["running", "completed", "blocked", "cancelled"] as const;
+export const REVIEW_POST_CONSOLIDATION_ACTIONS = ["fix-now", "document-only", "discuss-before-fixing"] as const;
+export const REVIEW_FIX_STATUSES = ["applied", "skipped", "failed"] as const;
+
+export const ReviewScopeFileSchema = Type.Object(
+  {
+    path: Type.String({ minLength: 1 }),
+    additions: Type.Number({ minimum: 0 }),
+    deletions: Type.Number({ minimum: 0 }),
+    diff: Type.String(),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewScopeStatsSchema = Type.Object(
+  {
+    filesChanged: Type.Number({ minimum: 0 }),
+    excludedFiles: Type.Number({ minimum: 0 }),
+    additions: Type.Number({ minimum: 0 }),
+    deletions: Type.Number({ minimum: 0 }),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewScopeSchema = Type.Object(
+  {
+    mode: Type.Union(REVIEW_SCOPE_MODES.map((mode) => Type.Literal(mode))),
+    description: Type.String({ minLength: 1 }),
+    diff: Type.String(),
+    files: Type.Array(ReviewScopeFileSchema),
+    stats: ReviewScopeStatsSchema,
+    baseBranch: Type.Optional(Type.String({ minLength: 1 })),
+    commit: Type.Optional(Type.String({ minLength: 1 })),
+    customInstructions: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewFindingValidationSchema = Type.Object(
+  {
+    verdict: Type.Union(REVIEW_VALIDATION_VERDICTS.map((value) => Type.Literal(value))),
+    reasoning: Type.String({ minLength: 1 }),
+    validatedBy: Type.String({ minLength: 1 }),
+    validatedAt: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewFindingSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    title: Type.String({ minLength: 1 }),
+    severity: Type.Union(REVIEW_FINDING_SEVERITIES.map((value) => Type.Literal(value))),
+    priority: Type.Union(REVIEW_FINDING_PRIORITIES.map((value) => Type.Literal(value))),
+    confidence: Type.Number({ minimum: 0, maximum: 1 }),
+    file: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+    lineStart: Type.Union([Type.Number({ minimum: 1 }), Type.Null()]),
+    lineEnd: Type.Union([Type.Number({ minimum: 1 }), Type.Null()]),
+    body: Type.String({ minLength: 1 }),
+    suggestion: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+    agent: Type.Optional(Type.String({ minLength: 1 })),
+    validation: Type.Optional(ReviewFindingValidationSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewOutputSchema = Type.Object(
+  {
+    findings: Type.Array(ReviewFindingSchema),
+    summary: Type.String({ minLength: 1 }),
+    status: Type.Union(REVIEW_OUTPUT_STATUSES.map((value) => Type.Literal(value))),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewAgentConfigSchema = Type.Object(
+  {
+    name: Type.String({ minLength: 1 }),
+    enabled: Type.Boolean(),
+    data: Type.String({ minLength: 1 }),
+    model: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewAgentsConfigSchema = Type.Object(
+  {
+    agents: Type.Array(ReviewAgentConfigSchema),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewAgentFrontmatterSchema = Type.Object(
+  {
+    name: Type.String({ minLength: 1 }),
+    description: Type.String({ minLength: 1 }),
+    focus: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewIterationSummarySchema = Type.Object(
+  {
+    iteration: Type.Number({ minimum: 1 }),
+    findings: Type.Number({ minimum: 0 }),
+    status: Type.Union(REVIEW_OUTPUT_STATUSES.map((value) => Type.Literal(value))),
+    file: Type.String({ minLength: 1 }),
+    createdAt: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewFixRecordSchema = Type.Object(
+  {
+    findingIds: Type.Array(Type.String({ minLength: 1 })),
+    file: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+    status: Type.Union(REVIEW_FIX_STATUSES.map((value) => Type.Literal(value))),
+    summary: Type.String({ minLength: 1 }),
+  },
+  { additionalProperties: false },
+);
+
+export const REVIEW_FIX_OUTPUT_STATUSES = ["applied", "partial", "skipped", "blocked"] as const;
+
+export const ReviewFixOutputSchema = Type.Object(
+  {
+    fixes: Type.Array(ReviewFixRecordSchema),
+    summary: Type.String({ minLength: 1 }),
+    status: Type.Union(REVIEW_FIX_OUTPUT_STATUSES.map((value) => Type.Literal(value))),
+  },
+  { additionalProperties: false },
+);
+
+
+export const ReviewSessionArtifactsSchema = Type.Object(
+  {
+    scope: Type.String({ minLength: 1 }),
+    iterationsDir: Type.String({ minLength: 1 }),
+    agentsDir: Type.String({ minLength: 1 }),
+    rawFindings: Type.Optional(Type.String({ minLength: 1 })),
+    validatedFindings: Type.Optional(Type.String({ minLength: 1 })),
+    consolidatedFindings: Type.Optional(Type.String({ minLength: 1 })),
+    findingsReport: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export const ReviewSessionSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    createdAt: Type.String({ minLength: 1 }),
+    updatedAt: Type.String({ minLength: 1 }),
+    level: Type.Union(REVIEW_LEVELS.map((value) => Type.Literal(value))),
+    status: Type.Union(REVIEW_SESSION_STATUSES.map((value) => Type.Literal(value))),
+    scope: ReviewScopeSchema,
+    validateFindings: Type.Boolean(),
+    consolidate: Type.Boolean(),
+    postConsolidationAction: Type.Union([
+      Type.Union(REVIEW_POST_CONSOLIDATION_ACTIONS.map((value) => Type.Literal(value))),
+      Type.Null(),
+    ]),
+    maxIterations: Type.Number({ minimum: 0 }),
+    currentIteration: Type.Number({ minimum: 0 }),
+    iterations: Type.Array(ReviewIterationSummarySchema),
+    fixes: Type.Array(ReviewFixRecordSchema),
+    artifacts: ReviewSessionArtifactsSchema,
+    agents: Type.Array(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export interface ReviewValidationError {
+  path: string;
+  message: string;
+}
+
+function normalizeErrorPath(path: string): string {
+  return path.replace(/^\//, "").replace(/\//g, ".") || "(root)";
+}
+
+export function collectReviewValidationErrors(schema: TSchema, data: unknown): ReviewValidationError[] {
+  return [...Value.Errors(schema, data)].map((error) => ({
+    path: normalizeErrorPath(error.path),
+    message: error.message,
+  }));
+}
+
+export function formatReviewValidationErrors(errors: ReviewValidationError[]): string[] {
+  return errors.map((error) => `${error.path}: ${error.message}`);
+}
+
+export function isReviewScopeFile(value: unknown): value is ReviewScopeFile {
+  return Value.Check(ReviewScopeFileSchema, value);
+}
+
+export function isReviewScopeStats(value: unknown): value is ReviewScopeStats {
+  return Value.Check(ReviewScopeStatsSchema, value);
+}
+
+export function isReviewScope(value: unknown): value is ReviewScope {
+  return Value.Check(ReviewScopeSchema, value);
+}
+
+export function isReviewFinding(value: unknown): value is ReviewFinding {
+  return Value.Check(ReviewFindingSchema, value);
+}
+
+export function isReviewOutput(value: unknown): value is ReviewOutput {
+  return Value.Check(ReviewOutputSchema, value);
+}
+
+export function isReviewAgentConfig(value: unknown): value is ReviewAgentConfig {
+  return Value.Check(ReviewAgentConfigSchema, value);
+}
+
+export function isReviewAgentsConfig(value: unknown): value is ReviewAgentsConfig {
+  return Value.Check(ReviewAgentsConfigSchema, value);
+}
+
+export function isReviewSessionArtifacts(value: unknown): value is ReviewSessionArtifacts {
+  return Value.Check(ReviewSessionArtifactsSchema, value);
+}
+
+export function isReviewIterationSummary(value: unknown): value is ReviewIterationSummary {
+  return Value.Check(ReviewIterationSummarySchema, value);
+}
+
+export function isReviewFixRecord(value: unknown): value is ReviewFixRecord {
+  return Value.Check(ReviewFixRecordSchema, value);
+}
+
+export function isReviewSession(value: unknown): value is ReviewSession {
+  return Value.Check(ReviewSessionSchema, value);
+}
+
+export function isReviewAgentDefinition(value: unknown): value is ReviewAgentDefinition {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const candidate = value as ReviewAgentDefinition;
+  return (
+    typeof candidate.name === "string" &&
+    candidate.name.length > 0 &&
+    typeof candidate.description === "string" &&
+    candidate.description.length > 0 &&
+    (candidate.focus === null || typeof candidate.focus === "string") &&
+    typeof candidate.prompt === "string" &&
+    candidate.prompt.length > 0 &&
+    typeof candidate.filePath === "string" &&
+    candidate.filePath.length > 0
+  );
+}

package/src/review/validator.ts

@@ -0,0 +1,160 @@
+import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
+import validationReviewPrompt from "./prompts/validation-review.md" with { type: "text" };
+import type { GateExecutionContext, ReviewFinding, ReviewOutput, ReviewScope } from "../types.js";
+import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
+import { renderReviewTemplate } from "./template.js";
+
+export interface ReviewValidationInput {
+  cwd: string;
+  scope: ReviewScope;
+  findings: ReviewFinding[];
+  createAgentSession: GateExecutionContext["createAgentSession"];
+  model?: string;
+  thinkingLevel?: string | null;
+  timeoutMs?: number;
+  validatorName?: string;
+  now?: () => Date;
+}
+
+export interface ReviewValidationResult {
+  output: ReviewOutput;
+  attempts: number;
+  rawOutputs: string[];
+}
+
+function summarizeValidation(findings: ReviewFinding[]): string {
+  const counts = findings.reduce(
+    (summary, finding) => {
+      const verdict = finding.validation?.verdict ?? "uncertain";
+      summary[verdict] += 1;
+      return summary;
+    },
+    { confirmed: 0, rejected: 0, uncertain: 0 },
+  );
+
+  return `Validation complete: ${counts.confirmed} confirmed, ${counts.rejected} rejected, ${counts.uncertain} uncertain.`;
+}
+
+function statusFromValidation(findings: ReviewFinding[]): ReviewOutput["status"] {
+  const confirmed = findings.filter((finding) => finding.validation?.verdict === "confirmed").length;
+  const uncertain = findings.filter((finding) => finding.validation?.verdict === "uncertain").length;
+
+  if (confirmed > 0) {
+    return "failed";
+  }
+  if (uncertain > 0) {
+    return "blocked";
+  }
+  return "passed";
+}
+
+function applyValidationResults(
+  findings: ReviewFinding[],
+  candidate: ReviewFinding[],
+  validatorName: string,
+  validatedAt: string,
+  fallbackReason: string,
+): ReviewFinding[] {
+  const byId = new Map(candidate.map((finding) => [finding.id, finding]));
+
+  return findings.map((finding) => {
+    const validated = byId.get(finding.id);
+    const verdict = validated?.validation?.verdict ?? "uncertain";
+    const reasoning = validated?.validation?.reasoning?.trim() || fallbackReason;
+
+    return {
+      ...finding,
+      validation: {
+        verdict,
+        reasoning,
+        validatedBy: validatorName,
+        validatedAt,
+      },
+    };
+  });
+}
+
+export function buildValidationPrompt(
+  scope: ReviewScope,
+  findings: ReviewFinding[],
+  validatorName: string,
+  validatedAt: string,
+): string {
+  return renderReviewTemplate(validationReviewPrompt, {
+    scope,
+    findingsJson: JSON.stringify(findings, null, 2),
+    validatorName,
+    validatedAt,
+    outputSchema: reviewOutputSchema.trim(),
+  });
+}
+
+export async function validateReviewFindings(input: ReviewValidationInput): Promise<ReviewValidationResult> {
+  if (input.findings.length === 0) {
+    return {
+      output: {
+        findings: [],
+        summary: "No findings to validate.",
+        status: "passed",
+      },
+      attempts: 0,
+      rawOutputs: [],
+    };
+  }
+
+  const validatorName = input.validatorName ?? "validator";
+  const validatedAt = (input.now ?? (() => new Date()))().toISOString();
+  const result = await runWithOutputValidation(input.createAgentSession, {
+    cwd: input.cwd,
+    prompt: buildValidationPrompt(input.scope, input.findings, validatorName, validatedAt),
+    schema: reviewOutputSchema.trim(),
+    parse(raw) {
+      const output = parseReviewOutput(raw);
+      return {
+        output,
+        error: output ? null : explainReviewOutputFailure(raw),
+      };
+    },
+    model: input.model,
+    thinkingLevel: input.thinkingLevel ?? null,
+    timeoutMs: input.timeoutMs ?? 120_000,
+  });
+
+  if (result.status === "blocked") {
+    const findings = applyValidationResults(
+      input.findings,
+      [],
+      validatorName,
+      validatedAt,
+      result.error,
+    );
+
+    return {
+      output: {
+        findings,
+        summary: result.error,
+        status: "blocked",
+      },
+      attempts: result.attempts,
+      rawOutputs: result.rawOutputs,
+    };
+  }
+
+  const findings = applyValidationResults(
+    input.findings,
+    result.output.findings,
+    validatorName,
+    validatedAt,
+    "Validator did not return a verdict for this finding.",
+  );
+
+  return {
+    output: {
+      findings,
+      summary: summarizeValidation(findings),
+      status: statusFromValidation(findings),
+    },
+    attempts: result.attempts,
+    rawOutputs: [result.rawOutput],
+  };
+}

package/src/storage/plans.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { normalizeLineEndings } from "../text.js";
 import type { Plan, PlanTask, TaskComplexity } from "../types.js";
 import type { PlatformPaths } from "../platform/types.js";
 
@@ -36,7 +37,8 @@ export function savePlan(paths: PlatformPaths, cwd: string, filename: string, co
 
 /** Parse a plan markdown file into a Plan object */
 export function parsePlan(content: string, filePath: string): Plan {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  const normalizedContent = normalizeLineEndings(content);
+  const frontmatterMatch = normalizedContent.match(/^---\n([\s\S]*?)\n---/);
   const meta: Record<string, string | string[]> = {};
 
   if (frontmatterMatch) {
@@ -56,13 +58,13 @@ export function parsePlan(content: string, filePath: string): Plan {
     }
   }
 
-  const tasks = parseTasksFromMarkdown(content);
+  const tasks = parseTasksFromMarkdown(normalizedContent);
 
   return {
     name: (meta.name as string) ?? path.basename(filePath, ".md"),
     created: (meta.created as string) ?? "",
     tags: (meta.tags as string[]) ?? [],
-    context: extractContext(content),
+    context: extractContext(normalizedContent),
     tasks,
     filePath,
   };

package/src/storage/reports.ts

@@ -1,12 +1,47 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ReviewReport } from "../types.js";
+import type { GateResult, GateStatus, ReviewReport } from "../types.js";
 import type { PlatformPaths } from "../platform/types.js";
 
 function getReportsDir(paths: PlatformPaths, cwd: string): string {
   return paths.project(cwd, "reports");
 }
 
+function isGateStatus(value: unknown): value is GateStatus {
+  return value === "passed" || value === "failed" || value === "skipped" || value === "blocked";
+}
+
+function isGateResult(value: unknown): value is GateResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as GateResult).gate === "string" &&
+    isGateStatus((value as GateResult).status) &&
+    typeof (value as GateResult).summary === "string" &&
+    Array.isArray((value as GateResult).issues)
+  );
+}
+
+function isReviewReport(value: unknown): value is ReviewReport {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as ReviewReport).timestamp === "string" &&
+    Array.isArray((value as ReviewReport).selectedGates) &&
+    Array.isArray((value as ReviewReport).gates) &&
+    (value as ReviewReport).gates.every(isGateResult) &&
+    typeof (value as ReviewReport).summary === "object" &&
+    (value as ReviewReport).summary !== null &&
+    typeof (value as ReviewReport).summary.passed === "number" &&
+    typeof (value as ReviewReport).summary.failed === "number" &&
+    typeof (value as ReviewReport).summary.skipped === "number" &&
+    typeof (value as ReviewReport).summary.blocked === "number" &&
+    ((value as ReviewReport).overallStatus === "passed" ||
+      (value as ReviewReport).overallStatus === "failed" ||
+      (value as ReviewReport).overallStatus === "blocked")
+  );
+}
+
 /** Save a review report */
 export function saveReviewReport(paths: PlatformPaths, cwd: string, report: ReviewReport): string {
   const dir = getReportsDir(paths, cwd);
@@ -21,15 +56,23 @@ export function saveReviewReport(paths: PlatformPaths, cwd: string, report: Revi
 export function loadLatestReport(paths: PlatformPaths, cwd: string): ReviewReport | null {
   const dir = getReportsDir(paths, cwd);
   if (!fs.existsSync(dir)) return null;
+
   const files = fs
     .readdirSync(dir)
-    .filter((f) => f.startsWith("review-") && f.endsWith(".json"))
+    .filter((file) => file.startsWith("review-") && file.endsWith(".json"))
     .sort()
     .reverse();
-  if (files.length === 0) return null;
-  try {
-    return JSON.parse(fs.readFileSync(path.join(dir, files[0]), "utf-8"));
-  } catch {
-    return null;
+
+  for (const file of files) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
+      if (isReviewReport(parsed)) {
+        return parsed;
+      }
+    } catch {
+      // Ignore malformed report files and continue to older entries.
+    }
   }
+
+  return null;
 }

package/src/storage/review-sessions.ts

@@ -0,0 +1,117 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PlatformPaths } from "../platform/types.js";
+import type { ReviewSession } from "../types.js";
+import { isReviewSession } from "../review/types.js";
+
+const SESSIONS_DIR = "reviews";
+const ITERATIONS_DIR = "iterations";
+const AGENTS_DIR = "agents";
+
+function getSessionsDir(paths: PlatformPaths, cwd: string): string {
+  return paths.project(cwd, SESSIONS_DIR);
+}
+
+function ensureLayout(sessionDir: string): void {
+  fs.mkdirSync(path.join(sessionDir, ITERATIONS_DIR), { recursive: true });
+  fs.mkdirSync(path.join(sessionDir, AGENTS_DIR), { recursive: true });
+}
+
+function getLedgerPath(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getReviewSessionDir(paths, cwd, sessionId), "session.json");
+}
+
+function resolveArtifactPath(sessionDir: string, relativePath: string): string {
+  if (!relativePath || path.isAbsolute(relativePath)) {
+    throw new Error("Artifact path must be a non-empty relative path.");
+  }
+
+  const resolved = path.resolve(sessionDir, relativePath);
+  const normalizedBase = path.resolve(sessionDir);
+  if (resolved !== normalizedBase && !resolved.startsWith(`${normalizedBase}${path.sep}`)) {
+    throw new Error("Artifact path must stay within the review session directory.");
+  }
+
+  return resolved;
+}
+
+export function getReviewSessionDir(paths: PlatformPaths, cwd: string, sessionId: string): string {
+  return path.join(getSessionsDir(paths, cwd), sessionId);
+}
+
+export function generateReviewSessionId(now = new Date()): string {
+  const iso = now.toISOString();
+  const date = iso.slice(0, 10).replace(/-/g, "");
+  const time = iso.slice(11, 19).replace(/:/g, "");
+  const suffix = Math.random().toString(36).slice(2, 6);
+  return `review-${date}-${time}-${suffix}`;
+}
+
+export function createReviewSession(paths: PlatformPaths, cwd: string, session: ReviewSession): void {
+  const sessionDir = getReviewSessionDir(paths, cwd, session.id);
+  ensureLayout(sessionDir);
+  fs.writeFileSync(getLedgerPath(paths, cwd, session.id), `${JSON.stringify(session, null, 2)}\n`);
+}
+
+export function loadReviewSession(paths: PlatformPaths, cwd: string, sessionId: string): ReviewSession | null {
+  const ledgerPath = getLedgerPath(paths, cwd, sessionId);
+  if (!fs.existsSync(ledgerPath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(ledgerPath, "utf-8"));
+    return isReviewSession(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function updateReviewSession(paths: PlatformPaths, cwd: string, session: ReviewSession): void {
+  session.updatedAt = new Date().toISOString();
+  const sessionDir = getReviewSessionDir(paths, cwd, session.id);
+  ensureLayout(sessionDir);
+  fs.writeFileSync(getLedgerPath(paths, cwd, session.id), `${JSON.stringify(session, null, 2)}\n`);
+}
+
+export function listReviewSessions(paths: PlatformPaths, cwd: string): string[] {
+  const sessionsDir = getSessionsDir(paths, cwd);
+  if (!fs.existsSync(sessionsDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(sessionsDir)
+    .filter((entry) => entry.startsWith("review-"))
+    .sort()
+    .reverse();
+}
+
+export function writeReviewArtifact(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  relativePath: string,
+  payload: unknown,
+): string {
+  const sessionDir = getReviewSessionDir(paths, cwd, sessionId);
+  ensureLayout(sessionDir);
+  const artifactPath = resolveArtifactPath(sessionDir, relativePath);
+  fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+
+  const content = typeof payload === "string"
+    ? payload
+    : `${JSON.stringify(payload, null, 2)}\n`;
+  fs.writeFileSync(artifactPath, content);
+  return artifactPath;
+}
+
+export function readReviewArtifact(paths: PlatformPaths, cwd: string, sessionId: string, relativePath: string): string | null {
+  const sessionDir = getReviewSessionDir(paths, cwd, sessionId);
+  const artifactPath = resolveArtifactPath(sessionDir, relativePath);
+  if (!fs.existsSync(artifactPath)) {
+    return null;
+  }
+
+  return fs.readFileSync(artifactPath, "utf-8");
+}