mustflow 1.15.97

package/dist/cli/lib/dashboard-preferences.js

@@ -0,0 +1,405 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './command-contract.js';
+import { isLocaleTag } from './locale-tags.js';
+import { markManifestLockFileCustomized } from './manifest-lock.js';
+import { COMMIT_MESSAGE_STYLES, TEST_AUTHORING_POLICIES } from './preferences-options.js';
+import { readTomlFile } from './toml.js';
+const PREFERENCES_RELATIVE_PATH = '.mustflow/config/preferences.toml';
+export const DASHBOARD_PREFERENCE_SETTINGS = [
+    {
+        id: 'git.auto_stage',
+        path: ['git', 'auto_stage'],
+        label: 'Git auto stage',
+        kind: 'boolean',
+        fallback: false,
+    },
+    {
+        id: 'git.auto_commit',
+        path: ['git', 'auto_commit'],
+        label: 'Git auto commit',
+        kind: 'boolean',
+        fallback: false,
+    },
+    {
+        id: 'git.auto_push',
+        path: ['git', 'auto_push'],
+        label: 'Git auto push',
+        kind: 'boolean',
+        fallback: false,
+        locked: true,
+        lockedReason: 'dashboard.locked.git.auto_push',
+    },
+    {
+        id: 'git.commit_message.style',
+        path: ['git', 'commit_message', 'style'],
+        label: 'Commit message style',
+        kind: 'select',
+        fallback: 'conventional',
+        options: COMMIT_MESSAGE_STYLES,
+    },
+    {
+        id: 'git.commit_message.language',
+        path: ['git', 'commit_message', 'language'],
+        label: 'Commit message language',
+        kind: 'select',
+        fallback: 'preserve_existing',
+        options: ['preserve_existing', 'agent_response', 'docs', 'en', 'ko', 'zh', 'es', 'fr', 'hi'],
+        acceptsLocaleTag: true,
+    },
+    {
+        id: 'git.commit_message.max_suggestions',
+        path: ['git', 'commit_message', 'max_suggestions'],
+        label: 'Commit message suggestion count',
+        kind: 'number',
+        fallback: 2,
+        min: 1,
+        max: 5,
+    },
+    {
+        id: 'git.commit_message.include_body',
+        path: ['git', 'commit_message', 'include_body'],
+        label: 'Commit body',
+        kind: 'select',
+        fallback: 'when_non_trivial',
+        options: ['never', 'when_non_trivial', 'always'],
+    },
+    {
+        id: 'git.commit_message.split_when_multiple_concerns',
+        path: ['git', 'commit_message', 'split_when_multiple_concerns'],
+        label: 'Suggest split commits',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'git.commit_message.avoid_sensitive_details',
+        path: ['git', 'commit_message', 'avoid_sensitive_details'],
+        label: 'Avoid sensitive details',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'reporting.commit_suggestion.enabled',
+        path: ['reporting', 'commit_suggestion', 'enabled'],
+        label: 'Commit message suggestions',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.strategy',
+        path: ['verification', 'selection', 'strategy'],
+        label: 'Verification strategy',
+        kind: 'select',
+        fallback: 'risk_based',
+        options: ['risk_based', 'targeted', 'full'],
+    },
+    {
+        id: 'verification.selection.prefer_related_tests',
+        path: ['verification', 'selection', 'prefer_related_tests'],
+        label: 'Prefer related tests',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.skip_docs_only_full_test',
+        path: ['verification', 'selection', 'skip_docs_only_full_test'],
+        label: 'Skip full test for docs-only changes',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.skip_low_risk_code_full_test',
+        path: ['verification', 'selection', 'skip_low_risk_code_full_test'],
+        label: 'Skip full test for low-risk code changes',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.skip_translation_only_full_test',
+        path: ['verification', 'selection', 'skip_translation_only_full_test'],
+        label: 'Skip full test for translation-only changes',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.skip_copy_only_full_test',
+        path: ['verification', 'selection', 'skip_copy_only_full_test'],
+        label: 'Skip full test for copy-only changes',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'verification.selection.report_skipped',
+        path: ['verification', 'selection', 'report_skipped'],
+        label: 'Report skipped verification',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'testing.authoring.new_test_policy',
+        path: ['testing', 'authoring', 'new_test_policy'],
+        label: 'New test policy',
+        kind: 'select',
+        fallback: 'evidence_required',
+        options: TEST_AUTHORING_POLICIES,
+    },
+    {
+        id: 'testing.authoring.prefer_existing_tests',
+        path: ['testing', 'authoring', 'prefer_existing_tests'],
+        label: 'Prefer existing tests',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'testing.authoring.require_new_test_rationale',
+        path: ['testing', 'authoring', 'require_new_test_rationale'],
+        label: 'Require new test rationale',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'code_style.avoid_drive_by_refactors',
+        path: ['code_style', 'avoid_drive_by_refactors'],
+        label: 'Avoid drive-by refactors',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'refactoring.hotspots.large_file_candidate_kb',
+        path: ['refactoring', 'hotspots', 'large_file_candidate_kb'],
+        label: 'Large file candidate threshold',
+        kind: 'number',
+        fallback: 40,
+        min: 1,
+    },
+    {
+        id: 'refactoring.hotspots.history_days',
+        path: ['refactoring', 'hotspots', 'history_days'],
+        label: 'Hotspot history window',
+        kind: 'number',
+        fallback: 90,
+        min: 1,
+    },
+    {
+        id: 'refactoring.hotspots.primary_candidate_limit',
+        path: ['refactoring', 'hotspots', 'primary_candidate_limit'],
+        label: 'Primary hotspot candidate limit',
+        kind: 'number',
+        fallback: 50,
+        min: 1,
+    },
+    {
+        id: 'refactoring.hotspots.structure_candidate_limit',
+        path: ['refactoring', 'hotspots', 'structure_candidate_limit'],
+        label: 'Structure review candidate limit',
+        kind: 'number',
+        fallback: 10,
+        min: 1,
+    },
+    {
+        id: 'refactoring.hotspots.full_file_candidate_limit',
+        path: ['refactoring', 'hotspots', 'full_file_candidate_limit'],
+        label: 'Full-file review candidate limit',
+        kind: 'number',
+        fallback: 3,
+        min: 1,
+    },
+    {
+        id: 'release.versioning.impact_check',
+        path: ['release', 'versioning', 'impact_check'],
+        label: 'Version impact check',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'release.versioning.suggest_bump',
+        path: ['release', 'versioning', 'suggest_bump'],
+        label: 'Suggest version bump',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'release.versioning.auto_bump',
+        path: ['release', 'versioning', 'auto_bump'],
+        label: 'Auto bump versions',
+        kind: 'boolean',
+        fallback: false,
+    },
+    {
+        id: 'release.versioning.require_user_confirmation',
+        path: ['release', 'versioning', 'require_user_confirmation'],
+        label: 'Require version confirmation',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'release.versioning.sync_template_version',
+        path: ['release', 'versioning', 'sync_template_version'],
+        label: 'Sync template version',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'release.versioning.sync_docs_examples',
+        path: ['release', 'versioning', 'sync_docs_examples'],
+        label: 'Sync docs examples',
+        kind: 'boolean',
+        fallback: true,
+    },
+    {
+        id: 'release.versioning.sync_tests',
+        path: ['release', 'versioning', 'sync_tests'],
+        label: 'Sync tests',
+        kind: 'boolean',
+        fallback: true,
+    },
+];
+function getPreferencesPath(projectRoot) {
+    return path.join(projectRoot, PREFERENCES_RELATIVE_PATH);
+}
+function getNestedValue(table, settingPath) {
+    let current = table;
+    for (const segment of settingPath) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function normalizeValue(definition, value) {
+    if (definition.kind === 'boolean') {
+        return typeof value === 'boolean' ? value : definition.fallback;
+    }
+    if (definition.kind === 'number') {
+        return typeof value === 'number' && Number.isInteger(value) ? value : definition.fallback;
+    }
+    return typeof value === 'string' && value.trim().length > 0 ? value : definition.fallback;
+}
+export function readDashboardPreferences(projectRoot) {
+    const preferencesPath = getPreferencesPath(projectRoot);
+    if (!existsSync(preferencesPath)) {
+        throw new Error('Missing .mustflow/config/preferences.toml. Run mf init first or switch to a mustflow root.');
+    }
+    const parsed = readTomlFile(preferencesPath);
+    if (!isRecord(parsed)) {
+        throw new Error('.mustflow/config/preferences.toml must contain a TOML table.');
+    }
+    const settings = DASHBOARD_PREFERENCE_SETTINGS.map((definition) => ({
+        ...definition,
+        editable: definition.locked !== true,
+        value: normalizeValue(definition, getNestedValue(parsed, definition.path)),
+    }));
+    return {
+        projectRoot,
+        preferencesPath,
+        settings,
+    };
+}
+function serializeTomlScalar(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function findSectionRange(lines, sectionPath) {
+    const sectionName = sectionPath.join('.');
+    const sectionPattern = new RegExp(`^\\s*\\[${escapeRegExp(sectionName)}\\]\\s*$`, 'u');
+    const anySectionPattern = /^\s*\[[^\]]+\]\s*$/u;
+    const start = lines.findIndex((line) => sectionPattern.test(line));
+    if (start < 0) {
+        return undefined;
+    }
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (anySectionPattern.test(lines[index] ?? '')) {
+            end = index;
+            break;
+        }
+    }
+    return [start, end];
+}
+function setTomlScalar(content, settingPath, value) {
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/u);
+    const key = settingPath[settingPath.length - 1];
+    const sectionPath = settingPath.slice(0, -1);
+    const assignment = `${key} = ${serializeTomlScalar(value)}`;
+    if (!key || sectionPath.length === 0) {
+        throw new Error(`Unsupported dashboard preference path: ${settingPath.join('.')}`);
+    }
+    const sectionRange = findSectionRange(lines, sectionPath);
+    if (!sectionRange) {
+        const prefix = lines.length > 0 && lines[lines.length - 1] === '' ? '' : newline;
+        return `${content}${prefix}${newline}[${sectionPath.join('.')}]${newline}${assignment}${newline}`;
+    }
+    const [start, end] = sectionRange;
+    const keyPattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=`, 'u');
+    for (let index = start + 1; index < end; index += 1) {
+        if (keyPattern.test(lines[index] ?? '')) {
+            const updated = [...lines];
+            updated[index] = assignment;
+            return updated.join(newline);
+        }
+    }
+    const updated = [...lines];
+    updated.splice(end, 0, assignment);
+    return updated.join(newline);
+}
+function coerceUpdateValue(definition, value) {
+    if (definition.locked) {
+        throw new Error(`${definition.id} is locked in the dashboard.`);
+    }
+    if (definition.kind === 'boolean') {
+        if (typeof value !== 'boolean') {
+            throw new Error(`${definition.id} must be a boolean.`);
+        }
+        return value;
+    }
+    if (definition.kind === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error(`${definition.id} must be an integer.`);
+        }
+        if (definition.min !== undefined && Number(value) < definition.min) {
+            throw new Error(`${definition.id} must be at least ${definition.min}.`);
+        }
+        if (definition.max !== undefined && Number(value) > definition.max) {
+            throw new Error(`${definition.id} must be at most ${definition.max}.`);
+        }
+        return Number(value);
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${definition.id} must be a string.`);
+    }
+    const trimmedValue = value.trim();
+    if (trimmedValue.length === 0) {
+        throw new Error(`${definition.id} must not be empty.`);
+    }
+    if (definition.options && !definition.options.includes(trimmedValue)) {
+        if (definition.acceptsLocaleTag && isLocaleTag(trimmedValue)) {
+            return trimmedValue;
+        }
+        const extra = definition.acceptsLocaleTag ? ', or a valid locale tag' : '';
+        throw new Error(`${definition.id} must be one of: ${definition.options.join(', ')}${extra}.`);
+    }
+    return trimmedValue;
+}
+export function updateDashboardPreferences(projectRoot, updates) {
+    const preferencesPath = getPreferencesPath(projectRoot);
+    const definitionsById = new Map(DASHBOARD_PREFERENCE_SETTINGS.map((definition) => [definition.id, definition]));
+    let content = readFileSync(preferencesPath, 'utf8');
+    for (const update of updates) {
+        const definition = definitionsById.get(update.id);
+        if (!definition) {
+            throw new Error(`Unknown dashboard preference: ${update.id}`);
+        }
+        const value = coerceUpdateValue(definition, update.value);
+        content = setTomlScalar(content, definition.path, value);
+    }
+    writeFileSync(preferencesPath, content);
+    markManifestLockFileCustomized(projectRoot, PREFERENCES_RELATIVE_PATH);
+    return readDashboardPreferences(projectRoot);
+}

package/dist/cli/lib/doc-review-ledger.js

@@ -0,0 +1,226 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { triageDocReview } from '../../core/doc-review-triage.js';
+import { ensureInside, ensureInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, toPosixPath, writeUtf8FileInsideWithoutSymlinks, } from './filesystem.js';
+import { parseTomlText, stringifyToml } from './toml.js';
+export const DOC_REVIEW_LEDGER_RELATIVE_PATH = '.mustflow/review/docs.toml';
+export const DOC_REVIEW_STATUSES = ['pending', 'in_review', 'changes_made', 'approved', 'needs_human', 'ignored'];
+export const DOC_REVIEW_ACTIVE_STATUSES = ['pending', 'in_review', 'changes_made', 'needs_human'];
+export const REVIEWER_KINDS = ['human', 'llm', 'tool', 'external'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+export function isDocReviewStatus(value) {
+    return typeof value === 'string' && DOC_REVIEW_STATUSES.includes(value);
+}
+export function isReviewerKind(value) {
+    return typeof value === 'string' && REVIEWER_KINDS.includes(value);
+}
+function parseReviewerKind(value, fallback) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (!isReviewerKind(value)) {
+        throw new Error(`reviewer kind must be one of: ${REVIEWER_KINDS.join(', ')}`);
+    }
+    return value;
+}
+function nowIso(now) {
+    return now ?? new Date().toISOString();
+}
+function normalizePath(projectRoot, inputPath) {
+    if (inputPath.trim().length === 0) {
+        throw new Error('document path must be a non-empty string');
+    }
+    const absolutePath = path.resolve(projectRoot, inputPath);
+    ensureInside(projectRoot, absolutePath);
+    return toPosixPath(path.relative(projectRoot, absolutePath));
+}
+function parseDocReviewEntry(value) {
+    if (!isRecord(value)) {
+        throw new Error('document review entry must be a table');
+    }
+    const pathValue = readOptionalString(value.path);
+    if (!pathValue) {
+        throw new Error('document review entry path must be a non-empty string');
+    }
+    if (!isDocReviewStatus(value.status)) {
+        throw new Error(`document review status must be one of: ${DOC_REVIEW_STATUSES.join(', ')}`);
+    }
+    return {
+        path: pathValue,
+        status: value.status,
+        origin: readOptionalString(value.origin) ?? 'llm_modified',
+        reason: readOptionalString(value.reason) ?? 'document requires review',
+        first_seen_at: readOptionalString(value.first_seen_at) ?? readOptionalString(value.last_touched_at) ?? nowIso(),
+        last_touched_at: readOptionalString(value.last_touched_at) ?? nowIso(),
+        last_touched_by_kind: parseReviewerKind(value.last_touched_by_kind),
+        last_touched_by_id: readOptionalString(value.last_touched_by_id),
+        reviewed_at: readOptionalString(value.reviewed_at),
+        reviewer_kind: parseReviewerKind(value.reviewer_kind),
+        reviewer_id: readOptionalString(value.reviewer_id),
+        reviewer_label: readOptionalString(value.reviewer_label),
+        reviewer_provider: readOptionalString(value.reviewer_provider),
+        reviewer_model: readOptionalString(value.reviewer_model),
+        reviewer_command_intent: readOptionalString(value.reviewer_command_intent),
+        review_summary: readOptionalString(value.review_summary),
+        review_comment: readOptionalString(value.review_comment),
+        commented_at: readOptionalString(value.commented_at),
+        commented_by_kind: parseReviewerKind(value.commented_by_kind),
+        commented_by_id: readOptionalString(value.commented_by_id),
+    };
+}
+function readLedgerFile(projectRoot) {
+    const ledgerPath = path.join(projectRoot, DOC_REVIEW_LEDGER_RELATIVE_PATH);
+    const ledgerDirectoryPath = path.dirname(ledgerPath);
+    ensureInside(projectRoot, ledgerPath);
+    ensureInsideWithoutSymlinks(projectRoot, ledgerDirectoryPath, { allowMissingLeaf: true });
+    if (!existsSync(ledgerDirectoryPath)) {
+        return { schema_version: '1', documents: [] };
+    }
+    ensureInsideWithoutSymlinks(projectRoot, ledgerPath, { allowMissingLeaf: true });
+    if (!existsSync(ledgerPath)) {
+        return { schema_version: '1', documents: [] };
+    }
+    const parsed = parseTomlText(readUtf8FileInsideWithoutSymlinks(projectRoot, ledgerPath));
+    if (!isRecord(parsed)) {
+        throw new Error(`${DOC_REVIEW_LEDGER_RELATIVE_PATH} must contain a TOML table`);
+    }
+    const documents = Array.isArray(parsed.documents) ? parsed.documents.map(parseDocReviewEntry) : [];
+    return {
+        schema_version: readOptionalString(parsed.schema_version) ?? '1',
+        documents,
+    };
+}
+function entryToToml(entry) {
+    const table = {
+        path: entry.path,
+        status: entry.status,
+        origin: entry.origin,
+        reason: entry.reason,
+        first_seen_at: entry.first_seen_at,
+        last_touched_at: entry.last_touched_at,
+    };
+    for (const key of [
+        'last_touched_by_kind',
+        'last_touched_by_id',
+        'reviewed_at',
+        'reviewer_kind',
+        'reviewer_id',
+        'reviewer_label',
+        'reviewer_provider',
+        'reviewer_model',
+        'reviewer_command_intent',
+        'review_summary',
+        'review_comment',
+        'commented_at',
+        'commented_by_kind',
+        'commented_by_id',
+    ]) {
+        const value = entry[key];
+        if (value) {
+            table[key] = value;
+        }
+    }
+    return table;
+}
+function writeLedgerFile(projectRoot, ledger) {
+    const ledgerPath = path.join(projectRoot, DOC_REVIEW_LEDGER_RELATIVE_PATH);
+    writeUtf8FileInsideWithoutSymlinks(projectRoot, ledgerPath, stringifyToml({
+        schema_version: ledger.schema_version,
+        documents: ledger.documents.map(entryToToml),
+    }));
+    return ledgerPath;
+}
+export function readDocReviewLedger(projectRoot) {
+    return readLedgerFile(projectRoot);
+}
+export function listDocReviewEntries(projectRoot, options = {}) {
+    const ledger = readLedgerFile(projectRoot);
+    const activeStatuses = new Set(DOC_REVIEW_ACTIVE_STATUSES);
+    return ledger.documents.filter((entry) => {
+        if (options.status) {
+            return entry.status === options.status;
+        }
+        return options.includeAll === true || activeStatuses.has(entry.status);
+    }).map((entry) => ({
+        ...entry,
+        ...triageDocReview(entry),
+    }));
+}
+export function addDocReviewEntry(projectRoot, input) {
+    const ledger = readLedgerFile(projectRoot);
+    const reviewPath = normalizePath(projectRoot, input.path);
+    const timestamp = nowIso(input.now);
+    const existing = ledger.documents.find((entry) => entry.path === reviewPath);
+    const nextEntry = {
+        ...existing,
+        path: reviewPath,
+        status: 'pending',
+        origin: input.origin ?? existing?.origin ?? 'llm_modified',
+        reason: input.reason ?? existing?.reason ?? 'LLM-created or LLM-modified documentation requires review',
+        first_seen_at: existing?.first_seen_at ?? timestamp,
+        last_touched_at: timestamp,
+        last_touched_by_kind: input.actorKind ?? existing?.last_touched_by_kind,
+        last_touched_by_id: input.actorId ?? existing?.last_touched_by_id,
+        review_comment: input.comment ?? existing?.review_comment,
+        commented_at: input.comment ? timestamp : existing?.commented_at,
+        commented_by_kind: input.comment ? input.actorKind : existing?.commented_by_kind,
+        commented_by_id: input.comment ? input.actorId : existing?.commented_by_id,
+    };
+    const documents = existing
+        ? ledger.documents.map((entry) => (entry.path === reviewPath ? nextEntry : entry))
+        : [...ledger.documents, nextEntry].sort((left, right) => left.path.localeCompare(right.path));
+    writeLedgerFile(projectRoot, { ...ledger, documents });
+    return nextEntry;
+}
+export function commentDocReviewEntry(projectRoot, input) {
+    const ledger = readLedgerFile(projectRoot);
+    const reviewPath = normalizePath(projectRoot, input.path);
+    const existing = ledger.documents.find((entry) => entry.path === reviewPath);
+    if (!existing) {
+        throw new Error(`document is not in the review queue: ${reviewPath}`);
+    }
+    const timestamp = nowIso(input.now);
+    const nextEntry = {
+        ...existing,
+        status: 'pending',
+        last_touched_at: timestamp,
+        last_touched_by_kind: input.actorKind ?? existing.last_touched_by_kind,
+        last_touched_by_id: input.actorId ?? existing.last_touched_by_id,
+        review_comment: input.comment,
+        commented_at: timestamp,
+        commented_by_kind: input.actorKind,
+        commented_by_id: input.actorId,
+    };
+    const documents = ledger.documents.map((entry) => (entry.path === reviewPath ? nextEntry : entry));
+    writeLedgerFile(projectRoot, { ...ledger, documents });
+    return nextEntry;
+}
+export function markDocReviewEntry(projectRoot, input) {
+    const ledger = readLedgerFile(projectRoot);
+    const reviewPath = normalizePath(projectRoot, input.path);
+    const existing = ledger.documents.find((entry) => entry.path === reviewPath);
+    if (!existing) {
+        throw new Error(`document is not in the review queue: ${reviewPath}`);
+    }
+    const timestamp = nowIso(input.now);
+    const nextEntry = {
+        ...existing,
+        status: input.status,
+        reviewed_at: timestamp,
+        reviewer_kind: input.reviewerKind,
+        reviewer_id: input.reviewerId,
+        reviewer_label: input.reviewerLabel,
+        reviewer_provider: input.reviewerProvider,
+        reviewer_model: input.reviewerModel,
+        reviewer_command_intent: input.reviewerCommandIntent,
+        review_summary: input.summary,
+    };
+    const documents = ledger.documents.map((entry) => (entry.path === reviewPath ? nextEntry : entry));
+    writeLedgerFile(projectRoot, { ...ledger, documents });
+    return nextEntry;
+}