@jacfrost/autopm 0.0.1

package/src/autopm/plan-proposals.js

@@ -0,0 +1,907 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { ACTION_PROPOSALS_DIR, listActionProposals } from './action-proposals.js';
+import { AUTOPM_HEARTBEAT_STATE_PATH } from './heartbeat/contracts.js';
+import { AUTOPM_OBJECTIVE_CURRENT_PATH, loadObjective } from './objective.js';
+import { loadAutoPmProductContext } from './runtime-context.js';
+import { PRODUCT_CONTEXT_INDEX_PATH, PRODUCT_CONTEXT_INTRO_PATH } from './product-context.js';
+
+export const PLAN_PROPOSAL_SCHEMA_VERSION = 1;
+export const PLAN_PROPOSALS_DIR = '.autopm/plans/proposals/';
+
+export const DEFAULT_PLAN_PROPOSAL_LIMITS = Object.freeze({
+  maxProposalBytes: 256 * 1024,
+  maxListProposals: 50,
+  maxDiagnosticDetails: 10,
+  maxPreviewChars: 360,
+  maxHeartbeatSnapshotBytes: 64 * 1024,
+});
+
+const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+const SECRET_KEY_PATTERN = /(?:^|[_-])(?:api[_-]?key|authorization|auth[_-]?token|access[_-]?token|refresh[_-]?token|secret|password|passwd|credential|token)(?:$|[_-])/i;
+const SECRET_VALUE_PATTERNS = Object.freeze([
+  /Bearer\s+[A-Za-z0-9._~+/=-]+/gi,
+  /sk-[A-Za-z0-9_-]{12,}/g,
+  /\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API[-_]?KEY|AUTHORIZATION|CREDENTIAL)[A-Z0-9_]*)\s*[:=]\s*([^\s,;"'`]+|["'`][^"'`]*["'`])/gi,
+  /("(?:token|secret|password|apiKey|api_key|authorization|credential)"\s*:\s*")[^"]+(")/gi,
+  /\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*[^\s`'"]+/gi,
+  /\b[A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|CREDENTIAL)[A-Z0-9_]{8,}\b/g,
+  /https?:\/\/[^\s/@]+:[^\s/@]+@[^\s]+/gi,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function positiveInteger(value, fallback) {
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function normalizeLimits(limits = {}) {
+  return {
+    maxProposalBytes: positiveInteger(limits.maxProposalBytes, DEFAULT_PLAN_PROPOSAL_LIMITS.maxProposalBytes),
+    maxListProposals: positiveInteger(limits.maxListProposals, DEFAULT_PLAN_PROPOSAL_LIMITS.maxListProposals),
+    maxDiagnosticDetails: positiveInteger(limits.maxDiagnosticDetails, DEFAULT_PLAN_PROPOSAL_LIMITS.maxDiagnosticDetails),
+    maxPreviewChars: positiveInteger(limits.maxPreviewChars, DEFAULT_PLAN_PROPOSAL_LIMITS.maxPreviewChars),
+    maxHeartbeatSnapshotBytes: positiveInteger(limits.maxHeartbeatSnapshotBytes, DEFAULT_PLAN_PROPOSAL_LIMITS.maxHeartbeatSnapshotBytes),
+  };
+}
+
+function normalizeProjectRoot(projectRoot) {
+  const root = typeof projectRoot === 'string' && projectRoot.trim() !== '' ? projectRoot : process.cwd();
+  return path.resolve(root);
+}
+
+function nowIso(value = undefined) {
+  if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Date.parse(value))) return new Date(value).toISOString();
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value.toISOString();
+  return new Date().toISOString();
+}
+
+function unique(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
+function compactTimestampForId(timestamp) {
+  return timestamp.replace(/[^A-Za-z0-9._-]/g, '');
+}
+
+function safeErrorMessage(error) {
+  return redactPlanProposalText(error instanceof Error ? error.message : String(error));
+}
+
+export function redactPlanProposalText(value) {
+  let text = String(value ?? '');
+  for (const pattern of SECRET_VALUE_PATTERNS) {
+    text = text.replace(pattern, (...args) => {
+      const match = args[0];
+      if (pattern.source.startsWith('("')) return `${args[1]}[REDACTED]${args[2]}`;
+      if (args.length > 3 && typeof args[1] === 'string' && /TOKEN|SECRET|PASSWORD|PASSWD|API[-_]?KEY|AUTHORIZATION|CREDENTIAL/i.test(args[1])) {
+        return `${args[1]}=[REDACTED]`;
+      }
+      if (/^Bearer/i.test(match)) return 'Bearer [REDACTED]';
+      if (/^sk-/i.test(match)) return 'sk-[REDACTED]';
+      if (/^https?:\/\//i.test(match)) return '[REDACTED_CREDENTIAL_URL]';
+      if (/PRIVATE KEY/.test(match)) return '[REDACTED_PRIVATE_KEY]';
+      const separatorIndex = Math.max(match.indexOf('='), match.indexOf(':'));
+      return separatorIndex >= 0 ? `${match.slice(0, separatorIndex + 1)}[REDACTED]` : '[REDACTED]';
+    });
+  }
+  return text;
+}
+
+function boundedText(value, fallback = '', maxChars = DEFAULT_PLAN_PROPOSAL_LIMITS.maxPreviewChars) {
+  const normalized = redactPlanProposalText(typeof value === 'string' && value.trim() !== '' ? value : fallback)
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (normalized.length <= maxChars) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+
+function sanitizeValue(value, limits = DEFAULT_PLAN_PROPOSAL_LIMITS) {
+  if (typeof value === 'string') return boundedText(value, '', limits.maxPreviewChars);
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null) return value;
+  if (Array.isArray(value)) return value.slice(0, limits.maxDiagnosticDetails).map((entry) => sanitizeValue(entry, limits));
+  if (isPlainObject(value)) return sanitizeObject(value, limits);
+  if (value === undefined) return undefined;
+  return boundedText(value instanceof Error ? value.message : String(value), '', limits.maxPreviewChars);
+}
+
+function sanitizeObject(value, limits = DEFAULT_PLAN_PROPOSAL_LIMITS) {
+  if (!isPlainObject(value)) return {};
+  const output = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (SECRET_KEY_PATTERN.test(key)) {
+      output[key] = '[REDACTED]';
+      continue;
+    }
+    const sanitized = sanitizeValue(entry, limits);
+    if (sanitized !== undefined) output[key] = sanitized;
+  }
+  return output;
+}
+
+function diagnostic(code, severity, message, timestamp, details = undefined, diagnosticPath = undefined, limits = DEFAULT_PLAN_PROPOSAL_LIMITS) {
+  const entry = {
+    code,
+    severity,
+    message: boundedText(message, code, 420),
+    timestamp,
+  };
+  if (typeof diagnosticPath === 'string') entry.path = boundedText(diagnosticPath, '', 180);
+  const sanitizedDetails = sanitizeValue(details, limits);
+  if (sanitizedDetails !== undefined) entry.details = sanitizedDetails;
+  return entry;
+}
+
+function warningRecord(code, message, timestamp, details = undefined, diagnosticPath = undefined, limits = DEFAULT_PLAN_PROPOSAL_LIMITS) {
+  return diagnostic(code, 'warning', message, timestamp, details, diagnosticPath, limits);
+}
+
+function errorRecord(code, message, timestamp, details = undefined, diagnosticPath = undefined, limits = DEFAULT_PLAN_PROPOSAL_LIMITS) {
+  return diagnostic(code, 'error', message, timestamp, details, diagnosticPath, limits);
+}
+
+function codeLists(warnings, errors) {
+  return {
+    warningCodes: unique(warnings.map((entry) => entry.code)),
+    errorCodes: unique(errors.map((entry) => entry.code)),
+  };
+}
+
+function envelope({
+  status,
+  generatedAt,
+  planProposalId = null,
+  planProposalPath = null,
+  artifactPathsRead = [],
+  artifactPathsWritten = [],
+  warnings = [],
+  errors = [],
+  durableStateChanged = false,
+  proposal = null,
+  proposals = undefined,
+  proposalCount = undefined,
+  inspectedProposalCount = undefined,
+  capped = undefined,
+  readiness = undefined,
+  diagnosticsTruncated = false,
+}) {
+  const codes = codeLists(warnings, errors);
+  const result = {
+    schemaVersion: PLAN_PROPOSAL_SCHEMA_VERSION,
+    generatedAt,
+    status,
+    planProposalId,
+    planProposalPath,
+    artifactPathsRead: unique(artifactPathsRead),
+    artifactPathsWritten: unique(artifactPathsWritten),
+    ...codes,
+    warnings,
+    errors,
+    durableStateChanged: durableStateChanged === true,
+    gsdDbMutation: false,
+    externalMutationAllowed: false,
+    runtimeArtifactsMutated: false,
+    proposal,
+    proposals,
+    proposalCount,
+    inspectedProposalCount,
+    capped,
+    readiness,
+    diagnosticsTruncated: diagnosticsTruncated === true,
+  };
+  return result;
+}
+
+function normalizeId(value, label) {
+  if (typeof value !== 'string') throw new TypeError(`Invalid ${label}: expected a string.`);
+  const normalized = value.trim();
+  if (
+    normalized.length === 0
+    || normalized === '.'
+    || normalized === '..'
+    || normalized.includes('/')
+    || normalized.includes('\\')
+    || normalized.includes(':')
+    || normalized.toLowerCase().includes('.gsd')
+    || !ID_PATTERN.test(normalized)
+  ) {
+    throw new TypeError(`Invalid ${label}: ${JSON.stringify(value)}.`);
+  }
+  return normalized;
+}
+
+export function normalizePlanProposalId(planProposalId) {
+  return normalizeId(planProposalId, 'AutoPM plan proposal id');
+}
+
+export function planProposalArtifactPath(planProposalId) {
+  return `${PLAN_PROPOSALS_DIR}${normalizePlanProposalId(planProposalId)}.json`;
+}
+
+function defaultPlanProposalId(generatedAt) {
+  return normalizePlanProposalId(`plan-${compactTimestampForId(generatedAt)}`);
+}
+
+function normalizeRelativePlanPath(relativePath) {
+  if (typeof relativePath !== 'string') throw new TypeError('Plan artifact path must be a string.');
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (
+    normalized.length === 0
+    || path.isAbsolute(normalized)
+    || normalized.includes('..')
+    || normalized.includes(':')
+    || normalized.toLowerCase().includes('.gsd')
+    || !normalized.startsWith(PLAN_PROPOSALS_DIR)
+    || !normalized.endsWith('.json')
+  ) {
+    throw new TypeError(`Invalid AutoPM plan artifact path: ${JSON.stringify(relativePath)}.`);
+  }
+  const fileName = normalized.slice(PLAN_PROPOSALS_DIR.length, -'.json'.length);
+  normalizePlanProposalId(fileName);
+  return normalized;
+}
+
+function resolveProjectPath(projectRoot, relativePath, fsImpl = fs) {
+  const safeRelativePath = normalizeRelativePlanPath(relativePath);
+  const absolutePath = path.resolve(projectRoot, safeRelativePath);
+  const relative = path.relative(projectRoot, absolutePath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Artifact path escaped project root: ${safeRelativePath}`);
+  }
+  const existsSync = fsImpl.existsSync ?? fs.existsSync;
+  const realpathSync = fsImpl.realpathSync ?? fs.realpathSync;
+  if (existsSync(absolutePath)) {
+    const realRoot = path.resolve(realpathSync.call(fsImpl, projectRoot));
+    const realTarget = path.resolve(realpathSync.call(fsImpl, absolutePath));
+    const realRelative = path.relative(realRoot, realTarget);
+    if (realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
+      throw new Error(`Artifact path resolved outside project root: ${safeRelativePath}`);
+    }
+  }
+  return absolutePath;
+}
+
+function readJsonFile({ fsImpl, projectRoot, relativePath, timestamp, limits, required = false, missingCode = 'AUTOPM_PLAN_SOURCE_MISSING' }) {
+  const artifactPathsRead = [];
+  let safePath;
+  try {
+    safePath = relativePath;
+    if (typeof safePath !== 'string' || path.isAbsolute(safePath) || safePath.includes('..') || safePath.includes('\\') || safePath.includes(':') || safePath.toLowerCase().includes('.gsd')) {
+      throw new TypeError(`Unsafe local artifact path: ${safePath}`);
+    }
+    artifactPathsRead.push(safePath);
+  } catch (error) {
+    return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_SOURCE_UNSAFE_PATH', 'Plan source artifact path is unsafe.', timestamp, { path: relativePath, reason: safeErrorMessage(error) }, undefined, limits) };
+  }
+
+  const absolutePath = path.resolve(projectRoot, safePath);
+  const relative = path.relative(projectRoot, absolutePath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_SOURCE_UNSAFE_PATH', 'Plan source artifact path escaped project root.', timestamp, { path: safePath }, safePath, limits) };
+  }
+
+  try {
+    const stat = (fsImpl.statSync ?? fs.statSync).call(fsImpl, absolutePath);
+    if (Number.isFinite(stat?.size) && stat.size > limits.maxHeartbeatSnapshotBytes) {
+      return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_SOURCE_OVERSIZED', 'Plan source artifact exceeds the read limit.', timestamp, { path: safePath, bytes: stat.size, maxBytes: limits.maxHeartbeatSnapshotBytes }, safePath, limits) };
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return { ok: false, missing: true, artifactPathsRead: required ? artifactPathsRead : [], error: warningRecord(missingCode, 'Optional plan source artifact is missing.', timestamp, { path: safePath }, safePath, limits) };
+    }
+    return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_SOURCE_READ_FAILED', 'Plan source artifact could not be inspected.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+
+  let raw;
+  try {
+    raw = (fsImpl.readFileSync ?? fs.readFileSync).call(fsImpl, absolutePath, 'utf8');
+  } catch (error) {
+    const code = error?.code === 'ENOENT' ? missingCode : 'AUTOPM_PLAN_SOURCE_READ_FAILED';
+    return { ok: false, missing: error?.code === 'ENOENT', artifactPathsRead, error: warningRecord(code, 'Plan source artifact could not be read.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+
+  try {
+    return { ok: true, artifactPathsRead, value: JSON.parse(raw) };
+  } catch (error) {
+    return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_SOURCE_PARSE_FAILED', 'Plan source artifact could not be parsed as JSON.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+}
+
+function normalizeDiagnosticRecords(records, timestamp, limits, severity = 'warning') {
+  if (!Array.isArray(records)) return [];
+  return records
+    .filter((record) => isPlainObject(record) && typeof record.code === 'string')
+    .slice(0, limits.maxDiagnosticDetails)
+    .map((record) => diagnostic(record.code, record.severity ?? severity, record.message ?? record.code, timestamp, record.details ?? {}, record.path, limits));
+}
+
+function summarizeObjective(loaded, timestamp, limits) {
+  const warnings = normalizeDiagnosticRecords(loaded?.warnings, timestamp, limits, 'warning');
+  const errors = normalizeDiagnosticRecords(loaded?.errors, timestamp, limits, 'error');
+  const summary = loaded?.objectiveSummary ?? null;
+  return {
+    status: loaded?.status ?? 'missing',
+    freshnessStatus: loaded?.freshnessStatus ?? 'unknown',
+    objectiveId: summary?.objectiveId ?? null,
+    northStarPreview: summary?.northStarPreview?.preview ?? null,
+    successSignalCount: summary?.successSignalCount ?? 0,
+    constraintCount: summary?.constraintCount ?? 0,
+    updatedAt: summary?.updatedAt ?? null,
+    warnings,
+    errors,
+  };
+}
+
+function summarizeContext(loaded, timestamp, limits) {
+  return {
+    status: loaded?.status ?? 'missing',
+    sourceOfTruth: loaded?.sourceOfTruth ?? null,
+    freshnessStatus: loaded?.freshnessStatus ?? 'unknown',
+    generatedAt: loaded?.generatedAt ?? null,
+    ageMs: Number.isFinite(loaded?.ageMs) ? loaded.ageMs : null,
+    artifactPathsRead: Array.isArray(loaded?.artifactPathsRead) ? loaded.artifactPathsRead : [],
+    warningCodes: Array.isArray(loaded?.warningCodes) ? loaded.warningCodes : [],
+    errorCodes: Array.isArray(loaded?.errorCodes) ? loaded.errorCodes : [],
+    warnings: normalizeDiagnosticRecords(loaded?.warnings, timestamp, limits, 'warning'),
+    errors: normalizeDiagnosticRecords(loaded?.errors, timestamp, limits, 'error'),
+    nextAction: loaded?.nextAction ?? null,
+  };
+}
+
+function summarizeHeartbeat(snapshot) {
+  if (!isPlainObject(snapshot)) return { present: false, status: 'missing', generatedAt: null, safeNextAction: null, componentStatuses: {} };
+  const componentStatuses = {};
+  for (const [key, value] of Object.entries(snapshot.components ?? snapshot.componentStatuses ?? {})) {
+    if (isPlainObject(value)) componentStatuses[key] = value.status ?? 'unknown';
+    else if (typeof value === 'string') componentStatuses[key] = value;
+  }
+  const action = snapshot.safeNextAction ?? snapshot.nextAction ?? null;
+  return sanitizeObject({
+    present: true,
+    status: snapshot.status ?? 'unknown',
+    generatedAt: snapshot.generatedAt ?? snapshot.updatedAt ?? null,
+    safeNextAction: isPlainObject(action) ? action : typeof action === 'string' ? { command: action } : null,
+    componentStatuses,
+  });
+}
+
+function summarizeActionProposals(listed, timestamp, limits) {
+  const statusCounts = {};
+  for (const proposal of listed?.proposals ?? []) {
+    const status = proposal.status ?? 'unknown';
+    statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+  }
+  return {
+    status: listed?.status ?? 'ok',
+    proposalCount: Number.isFinite(listed?.proposalCount) ? listed.proposalCount : 0,
+    inspectedProposalCount: Number.isFinite(listed?.inspectedProposalCount) ? listed.inspectedProposalCount : 0,
+    statusCounts,
+    recent: (listed?.proposals ?? []).slice(0, 5).map((proposal) => sanitizeObject(proposal, limits)),
+    warningCodes: Array.isArray(listed?.warningCodes) ? listed.warningCodes : [],
+    errorCodes: Array.isArray(listed?.errorCodes) ? listed.errorCodes : [],
+    warnings: normalizeDiagnosticRecords(listed?.warnings, timestamp, limits, 'warning'),
+    errors: normalizeDiagnosticRecords(listed?.errors, timestamp, limits, 'error'),
+  };
+}
+
+function proposalSummary(proposal) {
+  return {
+    planProposalId: proposal.planProposalId,
+    planProposalPath: proposal.planProposalPath,
+    status: proposal.status,
+    createdAt: proposal.createdAt,
+    updatedAt: proposal.updatedAt,
+    title: proposal.plan?.title ?? null,
+    stepCount: Array.isArray(proposal.plan?.steps) ? proposal.plan.steps.length : 0,
+    warningCodes: Array.isArray(proposal.diagnostics?.warningCodes) ? proposal.diagnostics.warningCodes : [],
+    errorCodes: Array.isArray(proposal.diagnostics?.errorCodes) ? proposal.diagnostics.errorCodes : [],
+  };
+}
+
+function productContextEvidenceRefs(contextSummary) {
+  return Array.isArray(contextSummary?.artifactPathsRead) && contextSummary.artifactPathsRead.length > 0
+    ? contextSummary.artifactPathsRead
+    : [PRODUCT_CONTEXT_INDEX_PATH, PRODUCT_CONTEXT_INTRO_PATH];
+}
+
+function buildPlan({ planProposalId, generatedAt, objectiveSummary, contextSummary, heartbeatSummary, actionProposalSummary, warnings }) {
+  const objectiveLabel = objectiveSummary.northStarPreview || 'current AutoPM objective';
+  const contextEvidenceRefs = productContextEvidenceRefs(contextSummary);
+  const steps = [
+    {
+      id: 'step-001',
+      title: 'Confirm planning target and constraints',
+      description: `Review the current objective: ${objectiveLabel}`,
+      evidenceRefs: [AUTOPM_OBJECTIVE_CURRENT_PATH],
+      verification: `/plan show --proposal-id ${planProposalId}`,
+    },
+    {
+      id: 'step-002',
+      title: 'Refresh optional context if needed',
+      description: contextSummary.status === 'ok' || contextSummary.status === 'warn'
+        ? 'Use the current product-context summary as bounded untrusted grounding.'
+        : 'Refresh product context before relying on this proposal for implementation details.',
+      evidenceRefs: contextEvidenceRefs,
+      verification: '/context status',
+    },
+    {
+      id: 'step-003',
+      title: 'Choose next safe local action',
+      description: heartbeatSummary.safeNextAction?.command
+        ? `Heartbeat suggested next action: ${heartbeatSummary.safeNextAction.command}`
+        : 'Run a heartbeat tick if a fresher safe next action is needed.',
+      evidenceRefs: [AUTOPM_HEARTBEAT_STATE_PATH, ACTION_PROPOSALS_DIR],
+      verification: '/heartbeat status',
+    },
+  ];
+  return {
+    title: 'Local AutoPM plan proposal',
+    rationale: 'Bounded plan synthesized from local objective, context, heartbeat, and action proposal evidence.',
+    goals: [objectiveLabel],
+    constraints: ['local-only', 'no GSD DB mutation', 'no external mutation', 'no runtime artifact mutation'],
+    steps,
+    risks: warnings.slice(0, 5).map((entry) => ({ code: entry.code, description: entry.message })),
+    verificationCommands: [`/plan show --proposal-id ${planProposalId}`, '/context status', '/heartbeat status'],
+    nextActions: [
+      { command: `/plan show --proposal-id ${planProposalId}`, reason: 'Inspect the persisted proposal before acting.' },
+      ...(actionProposalSummary.proposalCount > 0 ? [{ command: '/triage list', reason: 'Review related action proposals.' }] : []),
+    ],
+    generatedAt,
+  };
+}
+
+function collectPlanEvidence({ projectRoot, fsImpl, timestamp, limits }) {
+  const artifactPathsRead = [];
+  const warnings = [];
+  const errors = [];
+
+  const objective = loadObjective({ projectRoot, includeObjective: false, limits });
+  artifactPathsRead.push(...(objective.artifactPathsRead ?? []));
+  const objectiveSummary = summarizeObjective(objective, timestamp, limits);
+  warnings.push(...objectiveSummary.warnings);
+  errors.push(...objectiveSummary.errors);
+
+  const context = loadAutoPmProductContext({ projectRoot, checkedAt: timestamp, limits });
+  artifactPathsRead.push(...(context.artifactPathsRead ?? []));
+  const contextSummary = summarizeContext(context, timestamp, limits);
+  warnings.push(...contextSummary.warnings);
+  errors.push(...contextSummary.errors);
+  if (context.status === 'missing') {
+    warnings.push(warningRecord('AUTOPM_PLAN_CONTEXT_MISSING', 'Product context is missing; plan proposal will use objective and local operational evidence only.', timestamp, { nextAction: context.nextAction }, PRODUCT_CONTEXT_INDEX_PATH, limits));
+  }
+
+  const heartbeatRead = readJsonFile({ fsImpl, projectRoot, relativePath: AUTOPM_HEARTBEAT_STATE_PATH, timestamp, limits, missingCode: 'AUTOPM_PLAN_HEARTBEAT_MISSING' });
+  artifactPathsRead.push(...(heartbeatRead.artifactPathsRead ?? []));
+  if (!heartbeatRead.ok) {
+    if (heartbeatRead.missing === true) warnings.push(heartbeatRead.error);
+    else errors.push(heartbeatRead.error);
+  }
+  const heartbeatSummary = heartbeatRead.ok ? summarizeHeartbeat(heartbeatRead.value) : summarizeHeartbeat(null);
+
+  const actionProposals = listActionProposals({ projectRoot, fsImpl, generatedAt: timestamp, limits });
+  artifactPathsRead.push(...(actionProposals.artifactPathsRead ?? []));
+  const actionProposalSummary = summarizeActionProposals(actionProposals, timestamp, limits);
+  warnings.push(...actionProposalSummary.warnings);
+  errors.push(...actionProposalSummary.errors);
+  if (actionProposalSummary.proposalCount === 0) {
+    warnings.push(warningRecord('AUTOPM_PLAN_ACTION_PROPOSALS_EMPTY', 'No existing action proposals were available as planning evidence.', timestamp, { path: ACTION_PROPOSALS_DIR }, ACTION_PROPOSALS_DIR, limits));
+  }
+
+  return {
+    artifactPathsRead: unique(artifactPathsRead),
+    warnings,
+    errors,
+    objective,
+    objectiveSummary,
+    contextSummary,
+    heartbeatSummary,
+    actionProposalSummary,
+  };
+}
+
+function readinessFromEvidence(evidence) {
+  if (evidence.objective.status === 'missing') return 'missing';
+  if (evidence.objective.status === 'error' || evidence.errors.length > 0) return 'error';
+  if (evidence.warnings.length > 0 || evidence.objective.status === 'warn' || evidence.contextSummary.status !== 'ok') return 'warn';
+  return 'ok';
+}
+
+function buildReadiness(evidence) {
+  return {
+    objective: {
+      status: evidence.objectiveSummary.status,
+      freshnessStatus: evidence.objectiveSummary.freshnessStatus,
+      objectiveId: evidence.objectiveSummary.objectiveId,
+      northStarPreview: evidence.objectiveSummary.northStarPreview,
+      successSignalCount: evidence.objectiveSummary.successSignalCount,
+      constraintCount: evidence.objectiveSummary.constraintCount,
+      updatedAt: evidence.objectiveSummary.updatedAt,
+    },
+    context: evidence.contextSummary,
+    heartbeat: evidence.heartbeatSummary,
+    actionProposals: evidence.actionProposalSummary,
+  };
+}
+
+export function inspectPlanProposalStatus(options = {}) {
+  const timestamp = nowIso(options.generatedAt ?? options.timestamp ?? options.now);
+  const projectRoot = normalizeProjectRoot(options.projectRoot);
+  const fsImpl = options.fsImpl ?? options.fsAdapter ?? fs;
+  const limits = normalizeLimits(options.limits);
+  const evidence = collectPlanEvidence({ projectRoot, fsImpl, timestamp, limits });
+  const status = readinessFromEvidence(evidence);
+  return envelope({
+    status,
+    generatedAt: timestamp,
+    artifactPathsRead: evidence.artifactPathsRead,
+    warnings: evidence.warnings,
+    errors: evidence.errors,
+    durableStateChanged: false,
+    readiness: buildReadiness(evidence),
+  });
+}
+
+export function createPlanProposal(options = {}) {
+  const timestamp = nowIso(options.generatedAt ?? options.timestamp ?? options.now);
+  const projectRoot = normalizeProjectRoot(options.projectRoot);
+  const fsImpl = options.fsImpl ?? options.fsAdapter ?? fs;
+  const limits = normalizeLimits(options.limits);
+  let planProposalId;
+  try {
+    planProposalId = options.planProposalId ? normalizePlanProposalId(options.planProposalId) : defaultPlanProposalId(timestamp);
+  } catch (error) {
+    const errors = [errorRecord('AUTOPM_PLAN_PROPOSAL_ID_INVALID', 'Plan proposal ID is invalid.', timestamp, { reason: safeErrorMessage(error) }, undefined, limits)];
+    return envelope({ status: 'error', generatedAt: timestamp, errors, durableStateChanged: false });
+  }
+  const planProposalPath = planProposalArtifactPath(planProposalId);
+  const evidence = collectPlanEvidence({ projectRoot, fsImpl, timestamp, limits });
+  const readinessStatus = readinessFromEvidence(evidence);
+
+  if (evidence.objective.status === 'missing') {
+    const warnings = [
+      ...evidence.warnings,
+      warningRecord('AUTOPM_PLAN_OBJECTIVE_REQUIRED', 'A current objective is required before creating a plan proposal.', timestamp, { path: AUTOPM_OBJECTIVE_CURRENT_PATH }, AUTOPM_OBJECTIVE_CURRENT_PATH, limits),
+    ];
+    return envelope({
+      status: 'missing',
+      generatedAt: timestamp,
+      planProposalId,
+      planProposalPath,
+      artifactPathsRead: evidence.artifactPathsRead,
+      warnings,
+      errors: evidence.errors,
+      durableStateChanged: false,
+      readiness: buildReadiness(evidence),
+    });
+  }
+  if (readinessStatus === 'error') {
+    return envelope({
+      status: 'error',
+      generatedAt: timestamp,
+      planProposalId,
+      planProposalPath,
+      artifactPathsRead: evidence.artifactPathsRead,
+      warnings: evidence.warnings,
+      errors: evidence.errors,
+      durableStateChanged: false,
+      readiness: buildReadiness(evidence),
+    });
+  }
+
+  const proposal = sanitizeObject({
+    schemaVersion: PLAN_PROPOSAL_SCHEMA_VERSION,
+    planProposalId,
+    planProposalPath,
+    status: 'proposed',
+    createdAt: timestamp,
+      updatedAt: timestamp,
+      source: {
+        objectivePath: AUTOPM_OBJECTIVE_CURRENT_PATH,
+      productContextPaths: productContextEvidenceRefs(evidence.contextSummary),
+      heartbeatStatePath: AUTOPM_HEARTBEAT_STATE_PATH,
+      actionProposalDir: ACTION_PROPOSALS_DIR,
+    },
+    artifactPathsRead: evidence.artifactPathsRead,
+    artifactPathsWritten: [planProposalPath],
+    evidence: buildReadiness(evidence),
+    plan: buildPlan({
+      planProposalId,
+      generatedAt: timestamp,
+      objectiveSummary: evidence.objectiveSummary,
+      contextSummary: evidence.contextSummary,
+      heartbeatSummary: evidence.heartbeatSummary,
+      actionProposalSummary: evidence.actionProposalSummary,
+      warnings: evidence.warnings,
+    }),
+    diagnostics: {
+      ...codeLists(evidence.warnings, evidence.errors),
+      warnings: evidence.warnings,
+      errors: evidence.errors,
+      redacted: true,
+      localOnly: true,
+      gsdDbMutation: false,
+      externalMutationAllowed: false,
+      runtimeArtifactMutation: false,
+    },
+    durableStateChanged: true,
+  }, limits);
+
+  const validation = validatePlanProposalArtifact(proposal);
+  if (!validation.ok) {
+    const errors = [errorRecord('AUTOPM_PLAN_PROPOSAL_SCHEMA_INVALID', 'Constructed plan proposal failed schema validation.', timestamp, { validationErrors: validation.errors.slice(0, limits.maxDiagnosticDetails).map((error) => `${error.path}:${error.code}`) }, planProposalPath, limits)];
+    return envelope({ status: 'error', generatedAt: timestamp, planProposalId, planProposalPath, artifactPathsRead: evidence.artifactPathsRead, warnings: evidence.warnings, errors, durableStateChanged: false, readiness: buildReadiness(evidence) });
+  }
+
+  const written = writePlanProposalArtifact({ fsImpl, projectRoot, planProposalPath, proposal, timestamp, limits });
+  if (!written.ok) {
+    return envelope({ status: 'error', generatedAt: timestamp, planProposalId, planProposalPath, artifactPathsRead: evidence.artifactPathsRead, warnings: evidence.warnings, errors: [written.error], durableStateChanged: false, readiness: buildReadiness(evidence) });
+  }
+
+  return envelope({
+    status: evidence.warnings.length > 0 ? 'warn' : 'proposed',
+    generatedAt: timestamp,
+    planProposalId,
+    planProposalPath,
+    artifactPathsRead: evidence.artifactPathsRead,
+    artifactPathsWritten: [planProposalPath],
+    warnings: evidence.warnings,
+    errors: [],
+    durableStateChanged: true,
+    proposal,
+    readiness: buildReadiness(evidence),
+  });
+}
+
+function writePlanProposalArtifact({ fsImpl, projectRoot, planProposalPath, proposal, timestamp, limits }) {
+  let absolutePath;
+  try {
+    absolutePath = path.resolve(projectRoot, normalizeRelativePlanPath(planProposalPath));
+  } catch (error) {
+    return { ok: false, error: errorRecord('AUTOPM_PLAN_PROPOSAL_PATH_INVALID', 'Plan proposal path is invalid.', timestamp, { path: planProposalPath, reason: safeErrorMessage(error) }, undefined, limits) };
+  }
+  const mkdirSync = fsImpl.mkdirSync ?? fs.mkdirSync;
+  const writeFileSync = fsImpl.writeFileSync ?? fs.writeFileSync;
+  const renameSync = fsImpl.renameSync ?? fs.renameSync;
+  const existsSync = fsImpl.existsSync ?? fs.existsSync;
+  const unlinkSync = fsImpl.unlinkSync ?? fs.unlinkSync;
+  const tempPath = `${absolutePath}.${process.pid}.${Date.now()}.tmp`;
+
+  if (existsSync(absolutePath)) {
+    return { ok: false, error: errorRecord('AUTOPM_PLAN_PROPOSAL_ALREADY_EXISTS', 'Plan proposal already exists and will not be overwritten.', timestamp, { path: planProposalPath }, planProposalPath, limits) };
+  }
+
+  const json = `${JSON.stringify(proposal, null, 2)}\n`;
+  if (Buffer.byteLength(json, 'utf8') > limits.maxProposalBytes) {
+    return { ok: false, error: errorRecord('AUTOPM_PLAN_PROPOSAL_OVERSIZED', 'Plan proposal JSON exceeds the write limit.', timestamp, { path: planProposalPath, bytes: Buffer.byteLength(json, 'utf8'), maxBytes: limits.maxProposalBytes }, planProposalPath, limits) };
+  }
+
+  try {
+    mkdirSync.call(fsImpl, path.dirname(absolutePath), { recursive: true });
+    resolveProjectPath(projectRoot, planProposalPath, fsImpl);
+    writeFileSync.call(fsImpl, tempPath, json, { encoding: 'utf8', mode: 0o600 });
+    renameSync.call(fsImpl, tempPath, absolutePath);
+    return { ok: true };
+  } catch (error) {
+    try {
+      unlinkSync.call(fsImpl, tempPath);
+    } catch {
+      // Best-effort cleanup; final proposal path is never claimed below.
+    }
+    return { ok: false, error: errorRecord('AUTOPM_PLAN_PROPOSAL_WRITE_FAILED', 'Plan proposal artifact could not be atomically persisted.', timestamp, { path: planProposalPath, reason: safeErrorMessage(error) }, planProposalPath, limits) };
+  }
+}
+
+function readPlanProposalRaw({ fsImpl, projectRoot, planProposalPath, timestamp, limits }) {
+  let safePath;
+  try {
+    safePath = normalizeRelativePlanPath(planProposalPath);
+  } catch (error) {
+    return { ok: false, artifactPathsRead: [], error: errorRecord('AUTOPM_PLAN_PROPOSAL_PATH_INVALID', 'Plan proposal path is invalid.', timestamp, { path: planProposalPath, reason: safeErrorMessage(error) }, undefined, limits) };
+  }
+  const artifactPathsRead = [safePath];
+  let absolutePath;
+  try {
+    absolutePath = resolveProjectPath(projectRoot, safePath, fsImpl);
+  } catch (error) {
+    return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_PROPOSAL_PATH_INVALID', 'Plan proposal path could not be safely resolved.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+
+  try {
+    const stat = (fsImpl.statSync ?? fs.statSync).call(fsImpl, absolutePath);
+    if (Number.isFinite(stat?.size) && stat.size > limits.maxProposalBytes) {
+      return { ok: false, artifactPathsRead, error: errorRecord('AUTOPM_PLAN_PROPOSAL_OVERSIZED', 'Plan proposal JSON exceeds the read limit.', timestamp, { path: safePath, bytes: stat.size, maxBytes: limits.maxProposalBytes }, safePath, limits) };
+    }
+  } catch (error) {
+    const code = error?.code === 'ENOENT' ? 'AUTOPM_PLAN_PROPOSAL_MISSING' : 'AUTOPM_PLAN_PROPOSAL_READ_FAILED';
+    return { ok: false, artifactPathsRead, error: errorRecord(code, 'Plan proposal artifact could not be inspected.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+
+  try {
+    const raw = (fsImpl.readFileSync ?? fs.readFileSync).call(fsImpl, absolutePath, 'utf8');
+    return { ok: true, artifactPathsRead, value: JSON.parse(raw) };
+  } catch (error) {
+    const code = error instanceof SyntaxError ? 'AUTOPM_PLAN_PROPOSAL_PARSE_FAILED' : 'AUTOPM_PLAN_PROPOSAL_READ_FAILED';
+    return { ok: false, artifactPathsRead, error: errorRecord(code, 'Plan proposal artifact could not be read as valid JSON.', timestamp, { path: safePath, reason: safeErrorMessage(error) }, safePath, limits) };
+  }
+}
+
+export function readPlanProposal(options = {}) {
+  const timestamp = nowIso(options.generatedAt ?? options.timestamp ?? options.now);
+  const projectRoot = normalizeProjectRoot(options.projectRoot);
+  const fsImpl = options.fsImpl ?? options.fsAdapter ?? fs;
+  const limits = normalizeLimits(options.limits);
+  let planProposalId;
+  try {
+    planProposalId = normalizePlanProposalId(options.planProposalId);
+  } catch (error) {
+    const errors = [errorRecord('AUTOPM_PLAN_PROPOSAL_ID_INVALID', 'Plan proposal ID is invalid.', timestamp, { reason: safeErrorMessage(error) }, undefined, limits)];
+    return envelope({ status: 'error', generatedAt: timestamp, errors, durableStateChanged: false });
+  }
+  const planProposalPath = planProposalArtifactPath(planProposalId);
+  const read = readPlanProposalRaw({ fsImpl, projectRoot, planProposalPath, timestamp, limits });
+  if (!read.ok) {
+    return envelope({ status: 'error', generatedAt: timestamp, planProposalId, planProposalPath, artifactPathsRead: read.artifactPathsRead, errors: [read.error], durableStateChanged: false });
+  }
+  const validation = validatePlanProposalArtifact(read.value);
+  if (!validation.ok) {
+    const errors = [errorRecord('AUTOPM_PLAN_PROPOSAL_SCHEMA_INVALID', 'Plan proposal artifact failed schema validation.', timestamp, { validationErrors: validation.errors.slice(0, limits.maxDiagnosticDetails).map((error) => `${error.path}:${error.code}`) }, planProposalPath, limits)];
+    return envelope({ status: 'error', generatedAt: timestamp, planProposalId, planProposalPath, artifactPathsRead: read.artifactPathsRead, errors, durableStateChanged: false });
+  }
+  return envelope({ status: read.value.diagnostics?.warningCodes?.length > 0 ? 'warn' : 'ok', generatedAt: timestamp, planProposalId, planProposalPath, artifactPathsRead: read.artifactPathsRead, durableStateChanged: false, proposal: sanitizeObject(read.value, limits) });
+}
+
+export function listPlanProposals(options = {}) {
+  const timestamp = nowIso(options.generatedAt ?? options.timestamp ?? options.now);
+  const projectRoot = normalizeProjectRoot(options.projectRoot);
+  const fsImpl = options.fsImpl ?? options.fsAdapter ?? fs;
+  const limits = normalizeLimits(options.limits);
+  const dirPath = path.resolve(projectRoot, PLAN_PROPOSALS_DIR);
+  const warnings = [];
+  const errors = [];
+  const summaries = [];
+  let files;
+
+  try {
+    files = (fsImpl.readdirSync ?? fs.readdirSync).call(fsImpl, dirPath, { withFileTypes: true })
+      .filter((entry) => entry.isFile?.() && entry.name.endsWith('.json'))
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return envelope({ status: 'ok', generatedAt: timestamp, proposals: [], proposalCount: 0, inspectedProposalCount: 0, capped: false, durableStateChanged: false });
+    }
+    errors.push(errorRecord('AUTOPM_PLAN_PROPOSAL_LIST_FAILED', 'Plan proposal directory could not be read.', timestamp, { path: PLAN_PROPOSALS_DIR, reason: safeErrorMessage(error) }, PLAN_PROPOSALS_DIR, limits));
+    return envelope({ status: 'error', generatedAt: timestamp, errors, proposals: [], proposalCount: 0, inspectedProposalCount: 0, capped: false, durableStateChanged: false });
+  }
+
+  const capped = files.length > limits.maxListProposals;
+  if (capped) warnings.push(warningRecord('AUTOPM_PLAN_PROPOSAL_LIST_CAPPED', 'Plan proposal list was capped by maxListProposals.', timestamp, { total: files.length, inspected: limits.maxListProposals }, PLAN_PROPOSALS_DIR, limits));
+  const artifactPathsRead = [];
+  for (const file of files.slice(0, limits.maxListProposals)) {
+    let planProposalId;
+    try {
+      planProposalId = normalizePlanProposalId(path.basename(file, '.json'));
+    } catch (error) {
+      errors.push(errorRecord('AUTOPM_PLAN_PROPOSAL_ID_INVALID', 'Plan proposal filename contains an invalid ID.', timestamp, { file, reason: safeErrorMessage(error) }, `${PLAN_PROPOSALS_DIR}${file}`, limits));
+      continue;
+    }
+    const planProposalPath = planProposalArtifactPath(planProposalId);
+    const read = readPlanProposalRaw({ fsImpl, projectRoot, planProposalPath, timestamp, limits });
+    artifactPathsRead.push(...(read.artifactPathsRead ?? []));
+    if (!read.ok) {
+      errors.push(read.error);
+      continue;
+    }
+    const validation = validatePlanProposalArtifact(read.value);
+    if (!validation.ok) {
+      errors.push(errorRecord('AUTOPM_PLAN_PROPOSAL_SCHEMA_INVALID', 'Plan proposal artifact failed schema validation.', timestamp, { path: planProposalPath, validationErrors: validation.errors.slice(0, limits.maxDiagnosticDetails).map((error) => `${error.path}:${error.code}`) }, planProposalPath, limits));
+      continue;
+    }
+    summaries.push(proposalSummary(read.value));
+  }
+  const status = errors.length > 0 ? 'error' : warnings.length > 0 ? 'warn' : 'ok';
+  return envelope({ status, generatedAt: timestamp, artifactPathsRead, warnings, errors, proposals: summaries, proposalCount: files.length, inspectedProposalCount: Math.min(files.length, limits.maxListProposals), capped, durableStateChanged: false, diagnosticsTruncated: capped });
+}
+
+function addError(errors, fieldPath, code, message) {
+  errors.push({ path: fieldPath, code, message });
+}
+
+function validateString(value, fieldPath, errors, { minLength = 0 } = {}) {
+  if (typeof value !== 'string') {
+    addError(errors, fieldPath, 'type', 'Expected a string.');
+    return false;
+  }
+  if (value.length < minLength) {
+    addError(errors, fieldPath, 'too_short', `Expected at least ${minLength} characters.`);
+    return false;
+  }
+  if (redactPlanProposalText(value) !== value) addError(errors, fieldPath, 'unredacted_secret', 'String contains unredacted credential-like text.');
+  return true;
+}
+
+function validateArray(value, fieldPath, errors) {
+  if (!Array.isArray(value)) {
+    addError(errors, fieldPath, 'type', 'Expected an array.');
+    return false;
+  }
+  return true;
+}
+
+function validateObject(value, fieldPath, errors) {
+  if (!isPlainObject(value)) {
+    addError(errors, fieldPath, 'type', 'Expected an object.');
+    return false;
+  }
+  return true;
+}
+
+function validatePathArray(value, fieldPath, errors) {
+  if (!validateArray(value, fieldPath, errors)) return;
+  value.forEach((entry, index) => {
+    if (!validateString(entry, `${fieldPath}[${index}]`, errors, { minLength: 1 })) return;
+    if (entry.toLowerCase().includes('.gsd') || path.isAbsolute(entry) || entry.includes('..') || entry.includes('\\') || entry.includes(':')) {
+      addError(errors, `${fieldPath}[${index}]`, 'unsafe_path', 'Path must be a safe workspace-relative path.');
+    }
+  });
+}
+
+function validateDiagnostics(value, fieldPath, errors) {
+  if (!validateObject(value, fieldPath, errors)) return;
+  if (value.redacted !== true) addError(errors, `${fieldPath}.redacted`, 'redacted_required', 'Diagnostics must declare redacted true.');
+  if (value.localOnly !== true) addError(errors, `${fieldPath}.localOnly`, 'local_only_required', 'Diagnostics must declare localOnly true.');
+  if (value.gsdDbMutation !== false) addError(errors, `${fieldPath}.gsdDbMutation`, 'gsd_mutation_forbidden', 'Diagnostics must declare no GSD DB mutation.');
+  if (value.externalMutationAllowed !== false) addError(errors, `${fieldPath}.externalMutationAllowed`, 'external_mutation_forbidden', 'Diagnostics must declare no external mutation.');
+  if (value.runtimeArtifactMutation !== false) addError(errors, `${fieldPath}.runtimeArtifactMutation`, 'runtime_artifact_mutation_forbidden', 'Diagnostics must declare no runtime artifact mutation.');
+  if (Object.hasOwn(value, 'warningCodes')) validatePathlessStringArray(value.warningCodes, `${fieldPath}.warningCodes`, errors);
+  if (Object.hasOwn(value, 'errorCodes')) validatePathlessStringArray(value.errorCodes, `${fieldPath}.errorCodes`, errors);
+}
+
+function validatePathlessStringArray(value, fieldPath, errors) {
+  if (!validateArray(value, fieldPath, errors)) return;
+  value.forEach((entry, index) => validateString(entry, `${fieldPath}[${index}]`, errors));
+}
+
+export function validatePlanProposalArtifact(value) {
+  const errors = [];
+  if (!validateObject(value, '$', errors)) return { ok: false, errors };
+  if (value.schemaVersion !== PLAN_PROPOSAL_SCHEMA_VERSION) addError(errors, '$.schemaVersion', 'schema_version', 'Plan proposal schemaVersion must be 1.');
+  if (!validateString(value.planProposalId, '$.planProposalId', errors, { minLength: 1 })) {}
+  else {
+    try { normalizePlanProposalId(value.planProposalId); } catch (error) { addError(errors, '$.planProposalId', 'invalid_id', safeErrorMessage(error)); }
+  }
+  if (!validateString(value.planProposalPath, '$.planProposalPath', errors, { minLength: 1 })) {}
+  else {
+    try {
+      const expected = planProposalArtifactPath(value.planProposalId);
+      if (value.planProposalPath !== expected) addError(errors, '$.planProposalPath', 'path_mismatch', `Expected ${expected}.`);
+      normalizeRelativePlanPath(value.planProposalPath);
+    } catch (error) {
+      addError(errors, '$.planProposalPath', 'unsafe_path', safeErrorMessage(error));
+    }
+  }
+  if (value.status !== 'proposed') addError(errors, '$.status', 'status', 'Plan proposal status must be proposed.');
+  if (!validateString(value.createdAt, '$.createdAt', errors, { minLength: 1 }) || Number.isNaN(Date.parse(value.createdAt))) addError(errors, '$.createdAt', 'timestamp', 'createdAt must be a parseable timestamp.');
+  if (!validateString(value.updatedAt, '$.updatedAt', errors, { minLength: 1 }) || Number.isNaN(Date.parse(value.updatedAt))) addError(errors, '$.updatedAt', 'timestamp', 'updatedAt must be a parseable timestamp.');
+  if (!validateObject(value.source, '$.source', errors)) {}
+  if (Object.hasOwn(value, 'artifactPathsRead')) validatePathArray(value.artifactPathsRead, '$.artifactPathsRead', errors);
+  if (Object.hasOwn(value, 'artifactPathsWritten')) validatePathArray(value.artifactPathsWritten, '$.artifactPathsWritten', errors);
+  if (!Array.isArray(value.artifactPathsWritten) || value.artifactPathsWritten[0] !== value.planProposalPath) addError(errors, '$.artifactPathsWritten', 'written_path_mismatch', 'Artifact paths written must include the proposal path.');
+  if (!validateObject(value.evidence, '$.evidence', errors)) {}
+  if (!validateObject(value.plan, '$.plan', errors)) {}
+  else {
+    validateString(value.plan.title, '$.plan.title', errors, { minLength: 1 });
+    validatePathlessStringArray(value.plan.constraints, '$.plan.constraints', errors);
+    if (!validateArray(value.plan.steps, '$.plan.steps', errors) || value.plan.steps.length === 0) addError(errors, '$.plan.steps', 'empty', 'Plan must include at least one step.');
+  }
+  validateDiagnostics(value.diagnostics, '$.diagnostics', errors);
+  if (value.durableStateChanged !== true) addError(errors, '$.durableStateChanged', 'durable_state_not_changed', 'Plan proposal artifacts must declare durableStateChanged true.');
+  return { ok: errors.length === 0, errors };
+}