perttool 0.8.0 → 0.9.0

package/dist/cli.js

@@ -19,11 +19,29 @@ import { formatDecimal } from "./model/rational.js";
 import { convertWithVelocity, durationSuffix } from "./model/units.js";
 import { recommendationInvariantExitCode } from "./recommendation/failure.js";
 import { recommendationAnalysisToJson } from "./recommendation/json.js";
+import { applyTextEdits, normalizeTextEdits } from "./mutation/text-edits.js";
+import { createUnifiedDiff } from "./editing/unified-diff.js";
+import { sha256DigestUtf8 } from "./model/sha256.js";
 import { TARGET_GRAMMAR_6_CAPABILITY, } from "./parser/document-parser.js";
 import { exportPlanAssuranceMermaid, importPlanAssuranceMermaid, } from "./assurance/mermaid.js";
 import { getJsonSchemaResult, renderJsonSchemaResult, serializeJsonSchemaResult, } from "./schema/registry.js";
 import { TOOL_VERSION } from "./version.js";
-const { analyzeDocument, checkDocument, selectNextTasks, planFormat, planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, planUnitMigration, withUnitMigrationWrite, getProjectMetadata, contract7ProjectResultToJson, renderContract7ProjectText, planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, planAssuranceMutation, renderTargetGovernanceDecision, contract7InspectionResultToJson, contract7MutationResultToJson, contract7SnakeJson, contract6WorkEventToJson, renderAdvanceHistoryGuard, prepareTargetPlanAssuranceAdvanceHistory, withTargetPlanAssuranceAdvanceHistoryRace, persistTargetPlanAssuranceResult, inspectTargetPlanAssurance, inspectTargetProjectHistoryFile, renderTargetProjectHistoryText, targetProjectHistoryResultToJson, observeTargetProjectVelocity, renderTargetVelocityObservationText, targetVelocityObservationResultToJson, getAgentHelp, documentContentFromBytes, readDocumentContent, readBytes, recheckAdvanceHistoryBaseline, createArtifactFile, createTargetGrammar6DocumentFile, replaceTargetGrammar6DocumentFile, inspectTargetHistoricalGraphFile, renderTargetHistoricalGraphText, targetHistoricalGraphResultToJson, } = createCliApplicationFacade(createNodeHost(), createHistoricalGraphGitEvidenceHost());
+import { analyzeDocument as analyzeContract8Document, checkDocument as checkContract8Document, selectNextTasks as selectContract8NextTasks, } from "./application/contract8-milestone-acceptance.js";
+import { persistMilestoneAcceptanceMutation, planAcceptanceReceiptMutation, planCriterionSetReplacement, showMilestoneAcceptance, } from "./milestone-acceptance/mutation.js";
+import { planMilestoneAcceptanceMigration, recheckCommittedMigrationProof, } from "./milestone-acceptance/migration.js";
+import { MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY, milestoneAcceptanceBaseText, parseMilestoneAcceptanceSource } from "./milestone-acceptance/source.js";
+import { planMilestoneAcceptanceAdvance } from "./milestone-acceptance/advance.js";
+const { analyzeDocument: _analyzeContract7Document, checkDocument: _checkContract7Document, selectNextTasks: _selectContract7NextTasks, planFormat, planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, planUnitMigration, withUnitMigrationWrite, getProjectMetadata, contract7ProjectResultToJson, renderContract7ProjectText, planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, planAssuranceMutation, renderTargetGovernanceDecision, contract7InspectionResultToJson, contract7MutationResultToJson, contract7SnakeJson, contract6WorkEventToJson, renderAdvanceHistoryGuard, prepareTargetPlanAssuranceAdvanceHistory, prepareAdvanceHistory, withAdvanceHistoryRace, withTargetPlanAssuranceAdvanceHistoryRace, persistTargetPlanAssuranceResult, inspectTargetPlanAssurance, inspectTargetProjectHistoryFile, renderTargetProjectHistoryText, targetProjectHistoryResultToJson, observeTargetProjectVelocity, renderTargetVelocityObservationText, targetVelocityObservationResultToJson, getAgentHelp, documentContentFromBytes, readDocumentContent, readBytes, recheckAdvanceHistoryBaseline, captureAdvanceHistoryBaseline, createArtifactFile, createValidatedDocumentFile, createTargetGrammar6DocumentFile, replaceTargetGrammar6DocumentFile, replaceValidatedDocumentFile, inspectTargetHistoricalGraphFile, renderTargetHistoricalGraphText, targetHistoricalGraphResultToJson, } = createCliApplicationFacade(createNodeHost(), createHistoricalGraphGitEvidenceHost());
+const analyzeDocument = analyzeContract8Document;
+const checkDocument = checkContract8Document;
+const selectNextTasks = selectContract8NextTasks;
+function contract8MutationResultToJson(result, ...args) {
+    return Object.freeze({
+        ...contract7MutationResultToJson(result, ...args),
+        schema_version: "Perttool.MutationResult.v5",
+        cli_contract_version: 8,
+    });
+}
 class UsageError extends Error {
     code = "PTCLI-001";
 }
@@ -195,7 +213,11 @@ async function readStdin() {
     return Buffer.concat(chunks);
 }
 function writeJson(value) {
-    process.stdout.write(`${JSON.stringify(value)}\n`);
+    const contract8Value = typeof value === "object" && value !== null && !Array.isArray(value) &&
+        "cli_contract_version" in value
+        ? { ...value, cli_contract_version: 8 }
+        : value;
+    process.stdout.write(`${JSON.stringify(contract8Value)}\n`);
 }
 function snakeJson(value) {
     if (typeof value === "bigint")
@@ -232,7 +254,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -268,7 +290,7 @@ async function runCheck(args) {
     if (format === "json") {
         writeJson({
             schema_version: result.schemaVersion,
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -288,6 +310,7 @@ async function runCheck(args) {
                 },
             assurance: contract7SnakeJson(result.assurance),
             assurance_state_counts: contract7SnakeJson(result.assuranceStateCounts),
+            acceptance: snakeJson(result.acceptance),
         });
     }
     else {
@@ -345,7 +368,7 @@ async function runProjectInit(args) {
     const parsed = parseCommandOptions("project.init", args);
     const format = outputFormat(parsed.values.get("format"));
     const color = colorMode(parsed.values.get("color"), format);
-    const durationUnit = enumOption(requiredOption(parsed, "duration-unit"), "duration-unit", new Set(["day", "hour", "point"]));
+    const durationUnit = enumOption(parsed.values.get("duration-unit") ?? "point", "duration-unit", new Set(["day", "hour", "point"]));
     const version = optionalInteger(parsed, "version", 0, 2_147_483_647);
     let result = planProjectInit({
         projectId: parsed.positionals[0],
@@ -518,6 +541,28 @@ async function persistGovernedResult(result, request, sourceOperand) {
             target: request.target,
         });
 }
+async function persistContract8CandidateResult(result, request) {
+    if (request.mode === "preview" || !result.changed) {
+        return Object.freeze({ mode: request.mode, target: request.target, written: false });
+    }
+    if (!result.ok || !result.governance?.writeAuthorized || result.updatedText === null) {
+        throw new TypeError("authorized Contract 8 result does not contain a digest-bound candidate");
+    }
+    const validator = (candidate) => {
+        const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+        return { ok: parsed.ok, diagnostics: [] };
+    };
+    if (request.mode === "in_place") {
+        await replaceValidatedDocumentFile(request.target, result.updatedText, {
+            initialDigest: result.originalDigest,
+            ...(request.expectedDigest === undefined ? {} : { expectedDigest: request.expectedDigest }),
+        }, validator);
+    }
+    else {
+        await createValidatedDocumentFile(request.target, result.updatedText, validator);
+    }
+    return Object.freeze({ mode: request.mode, target: request.target, written: true });
+}
 function assertExpectedDigest(request, initialDigest) {
     if (request.mode === "in_place" &&
         request.expectedDigest !== undefined &&
@@ -529,6 +574,21 @@ async function commitCandidate(request, candidateText, initialDigest) {
     if (candidateText === null) {
         throw new SafeWriteVerificationError("invalid_candidate", "successful editing result has no candidate text");
     }
+    const acceptanceSource = parseMilestoneAcceptanceSource(candidateText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+    if (acceptanceSource.grammarVersion === 7) {
+        const validator = (candidate) => {
+            const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+            return { ok: parsed.ok, diagnostics: [] };
+        };
+        return request.mode === "in_place"
+            ? replaceValidatedDocumentFile(request.target, candidateText, {
+                initialDigest,
+                ...(request.expectedDigest === undefined
+                    ? {}
+                    : { expectedDigest: request.expectedDigest }),
+            }, validator)
+            : createValidatedDocumentFile(request.target, candidateText, validator);
+    }
     return request.mode === "in_place"
         ? replaceTargetGrammar6DocumentFile(request.target, candidateText, TARGET_GRAMMAR_6_CAPABILITY, {
             initialDigest,
@@ -596,7 +656,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -1197,7 +1257,7 @@ async function runMutation(resource, action, args) {
     if (result.ok) {
         try {
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+                writeResult = await persistContract8CandidateResult(result, writeRequest);
             }
         }
         catch (error) {
@@ -1205,7 +1265,7 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract8MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1281,14 +1341,14 @@ async function runLifecycleMutation(action, args) {
     });
     if (result.ok && ok && writeRequest.mode !== "preview") {
         try {
-            writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+            writeResult = await persistContract8CandidateResult(result, writeRequest);
         }
         catch (error) {
             return writeFailureExit(error, operation, format === "json");
         }
     }
     if (format === "json") {
-        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract8MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1327,7 +1387,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 7,
+        cli_contract_version: 8,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1628,16 +1688,94 @@ async function runAdvance(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.advance", format === "json");
     }
-    const planned = planAdvance(input.text, {
+    const acceptancePlan = planMilestoneAcceptanceAdvance(input.text, {
+        maxDiagnostics,
+        originalLabel: source,
+        updatedLabel: "candidate",
+        provisionalPlanner: (baseText) => planAdvance(baseText, {
+            maxDiagnostics,
+            originalLabel: source,
+            updatedLabel: "candidate",
+        }),
+    });
+    if (!acceptancePlan.ok) {
+        if (format === "json")
+            writeJson({
+                schema_version: "Perttool.AdvanceResult.v3",
+                cli_contract_version: 8,
+                tool_version: TOOL_VERSION,
+                operation: "dag.advance",
+                ok: false,
+                document_id: /^project ([A-Za-z][A-Za-z0-9_-]*):$/mu.exec(input.text)?.[1] ?? null,
+                source,
+                source_digest: input.digest,
+                diagnostics: acceptancePlan.diagnostics.map(jsonDiagnostic),
+                diagnostics_truncated: false,
+                changed: acceptancePlan.provisional !== null,
+                original_digest: acceptancePlan.originalDigest,
+                updated_digest: acceptancePlan.provisional?.updatedDigest ?? null,
+                updated_text: acceptancePlan.provisional?.updatedText ?? null,
+                diff: acceptancePlan.provisional?.diff ?? null,
+                edits: snakeJson(acceptancePlan.provisional?.edits ?? []),
+                write: { mode: writeRequest.mode, target: writeRequest.target, written: false },
+                governance: null,
+                lifecycle: null,
+                advance: acceptancePlan.provisional === null ? null : snakeJson({
+                    ...acceptancePlan.provisional.advance,
+                    removedWorkEventIds: [],
+                    removedAssuranceRecordIds: [],
+                    updatedAssuranceReceiptIds: [],
+                }),
+                history_guard: null,
+                assurance_guard: null,
+                acceptance_guard: snakeJson(acceptancePlan.acceptanceGuard),
+            });
+        else {
+            if (acceptancePlan.provisional !== null)
+                process.stdout.write(parsed.flags.has("diff") ? acceptancePlan.provisional.diff : acceptancePlan.provisional.updatedText);
+            for (const diagnostic of acceptancePlan.diagnostics)
+                process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
+        }
+        return 1;
+    }
+    const contract7BaseText = milestoneAcceptanceBaseText(input.text);
+    const contract7Planned = planAdvance(contract7BaseText, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
         governance: governanceRequest(parsed, writeRequest),
     });
+    const combinedEdits = contract7Planned.updatedText === null
+        ? contract7Planned.edits
+        : normalizeTextEdits(input.text, [...contract7Planned.edits, ...acceptancePlan.provisional.edits].filter((edit, index, values) => values.findIndex((candidate) => candidate.startOffset === edit.startOffset &&
+            candidate.endOffset === edit.endOffset &&
+            candidate.replacement === edit.replacement) === index), "Contract 8 acceptance-aware advance");
+    const combinedText = contract7Planned.updatedText === null
+        ? null
+        : applyTextEdits(input.text, combinedEdits);
+    const combinedSource = combinedText === null
+        ? null
+        : parseMilestoneAcceptanceSource(combinedText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+    if (combinedSource !== null && !combinedSource.ok) {
+        throw new Error("acceptance-aware assurance advance lost Grammar 7 validation");
+    }
+    const planned = Object.freeze({
+        ...contract7Planned,
+        schemaVersion: "Perttool.AdvanceResult.v3",
+        originalDigest: input.digest,
+        updatedText: combinedText,
+        updatedDigest: combinedText === null ? null : sha256DigestUtf8(combinedText),
+        diff: combinedText === null ? null : createUnifiedDiff(input.text, combinedText, {
+            originalLabel: source,
+            updatedLabel: "candidate",
+        }),
+        edits: combinedEdits,
+        acceptanceGuard: acceptancePlan.acceptanceGuard,
+    });
     const initialWarningFailure = parsed.flags.has("warnings-as-errors") &&
         (planned.diagnosticsTruncated ||
             planned.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
-    const prepared = await prepareTargetPlanAssuranceAdvanceHistory(input.text, planned, TARGET_GRAMMAR_6_CAPABILITY, {
+    const preparedBase = await prepareAdvanceHistory(input.text, planned, {
         mode: writeRequest.mode === "out"
             ? "out"
             : writeRequest.mode,
@@ -1649,6 +1787,28 @@ async function runAdvance(args) {
         forceRequested,
         warningDenied: initialWarningFailure,
         maxDiagnostics,
+        documentValidator: (candidateText, candidateMaxDiagnostics) => {
+            const acceptanceSource = parseMilestoneAcceptanceSource(candidateText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+            const checked = checkContract8Document(candidateText, { maxDiagnostics: candidateMaxDiagnostics });
+            return {
+                ok: checked.ok && acceptanceSource.ok,
+                document: checked.document,
+                documentId: checked.documentId,
+                diagnostics: checked.diagnostics,
+                diagnosticsTruncated: checked.diagnosticsTruncated,
+            };
+        },
+    });
+    const prepared = Object.freeze({
+        ...preparedBase,
+        result: Object.freeze({
+            ...preparedBase.result,
+            schemaVersion: "Perttool.AdvanceResult.v3",
+            governance: planned.governance,
+            assuranceGuard: planned.assuranceGuard,
+            acceptanceGuard: acceptancePlan.acceptanceGuard,
+            advance: planned.advance,
+        }),
     });
     let result = prepared.result;
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
@@ -1671,13 +1831,20 @@ async function runAdvance(args) {
                     result.historyGuard?.status === "forced")) {
                 const recheck = await recheckAdvanceHistoryBaseline(prepared.baseline, sourceOperand);
                 if (!recheck.ok) {
-                    result = withTargetPlanAssuranceAdvanceHistoryRace(result, recheck, maxDiagnostics);
+                    result = Object.freeze({
+                        ...withAdvanceHistoryRace(result, recheck, maxDiagnostics),
+                        schemaVersion: "Perttool.AdvanceResult.v3",
+                        governance: result.governance,
+                        assuranceGuard: result.assuranceGuard,
+                        acceptanceGuard: result.acceptanceGuard,
+                        advance: result.advance,
+                    });
                     ok = false;
                     historyRace = true;
                 }
             }
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+                writeResult = await persistContract8CandidateResult(result, writeRequest);
             }
         }
         catch (error) {
@@ -1685,7 +1852,12 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
+        writeJson({
+            ...contract7MutationResultToJson((ok ? result : Object.freeze({ ...result, ok: false })), "dag.advance", source, writeResult),
+            schema_version: "Perttool.AdvanceResult.v3",
+            cli_contract_version: 8,
+            acceptance_guard: snakeJson(result.acceptanceGuard),
+        });
     }
     else {
         if (result.advance !== null) {
@@ -2046,7 +2218,7 @@ async function runAnalyze(args) {
     if (format === "json") {
         writeJson({
             schema_version: result.schemaVersion,
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -2079,6 +2251,7 @@ async function runAnalyze(args) {
                 : resourceJson(result.resource, result.durationUnit, result.precision),
             temporal: snakeJson(result.temporal),
             assurance: contract7SnakeJson(result.assurance),
+            acceptance: snakeJson(result.acceptance),
         });
     }
     else {
@@ -2193,7 +2366,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -2306,7 +2479,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -2615,7 +2788,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 7,
+                cli_contract_version: 8,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2636,7 +2809,7 @@ async function runNext(args) {
     if (format === "json") {
         writeJson({
             schema_version: result.schemaVersion,
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2650,6 +2823,7 @@ async function runNext(args) {
             ...(result.durationUnit === null ? {} : nextJson(result)),
             temporal: snakeJson(result.temporal),
             assurance: contract7SnakeJson(result.assurance),
+            acceptance: snakeJson(result.acceptance),
         });
     }
     else {
@@ -2664,6 +2838,142 @@ async function runNext(args) {
     }
     return ok ? 0 : 1;
 }
+async function runMilestoneAcceptance(action, args) {
+    const operation = `milestone-acceptance.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    if (sourceOperand === undefined)
+        throw new UsageError(`${operation} requires <file>`);
+    const input = await readDocument(sourceOperand);
+    if (action === "show") {
+        if (parsed.positionals.length !== 1)
+            throw new UsageError("milestone acceptance show requires exactly one <file>");
+        const result = checkDocument(input.text).acceptance ?? showMilestoneAcceptance(input.text, []);
+        if (format === "json")
+            writeJson({ schema_version: "Perttool.MilestoneAcceptanceResult.v1", cli_contract_version: 8, tool_version: TOOL_VERSION, operation, ok: result.ok, milestones: snakeJson(result.milestones), diagnostics: snakeJson(result.diagnostics) });
+        else
+            process.stdout.write(`${result.milestones.map(({ milestoneId, closure, acceptance }) => `${milestoneId} closure=${closure} acceptance=${acceptance}`).join("\n")}\n`);
+        return result.ok ? 0 : 1;
+    }
+    if (parsed.positionals.length !== 4)
+        throw new UsageError(`${operation} requires four operands`);
+    const request = editingWriteRequest(parsed, sourceOperand);
+    if (request.mode === "out")
+        throw new UsageError(`${operation} does not support --out in Contract 8`);
+    const governance = governanceRequest(parsed, request);
+    let result;
+    if (action === "replace") {
+        const criteria = (parsed.repeatedValues.get("criterion") ?? []).map((value) => {
+            const [criterionId, requiredText, evidenceKind, ...description] = value.split(":");
+            if (criterionId === undefined || !["required", "optional"].includes(requiredText ?? "") || !["test", "command", "artifact", "observation", "owner"].includes(evidenceKind ?? "") || description.length === 0)
+                throw new UsageError("--criterion must be ID:required|optional:kind:description");
+            return { criterionId, required: requiredText === "required", evidenceKind: evidenceKind, description: description.join(":") };
+        });
+        result = planCriterionSetReplacement(input.text, { milestoneId: parsed.positionals[1], setId: parsed.positionals[2], revisionId: parsed.positionals[3], criteria }, { governance });
+    }
+    else {
+        result = planAcceptanceReceiptMutation(input.text, {
+            setId: parsed.positionals[1], criterionId: parsed.positionals[2], receiptId: parsed.positionals[3], action: action,
+            ...(parsed.values.get("evidence-kind") === undefined ? {} : { evidenceKind: parsed.values.get("evidence-kind") }),
+            ...(parsed.values.get("evidence-reference") === undefined ? {} : { evidenceReference: parsed.values.get("evidence-reference") }),
+            ...(parsed.values.get("evidence-revision") === undefined ? {} : { evidenceRevision: parsed.values.get("evidence-revision") }),
+            ...(parsed.values.get("verifier") === undefined ? {} : { verifier: parsed.values.get("verifier") }),
+            ...(parsed.values.get("occurred-at") === undefined ? {} : { occurredAt: parsed.values.get("occurred-at") }),
+            ...(parsed.values.get("reason") === undefined ? {} : { reason: parsed.values.get("reason") }),
+            ...(parsed.values.get("revokes") === undefined ? {} : { revokes: parsed.values.get("revokes") }),
+        }, { governance });
+    }
+    let written = false;
+    if (result.ok && request.mode === "in_place" && result.changed) {
+        await persistMilestoneAcceptanceMutation(sourceOperand, result, request.expectedDigest);
+        written = true;
+    }
+    if (format === "json")
+        writeJson({
+            schema_version: "Perttool.MutationResult.v5",
+            cli_contract_version: 8,
+            tool_version: TOOL_VERSION,
+            operation,
+            ok: result.ok,
+            document_id: /^project ([A-Za-z][A-Za-z0-9_-]*):$/mu.exec(input.text)?.[1] ?? null,
+            source: sourceOperand,
+            source_digest: input.digest,
+            diagnostics: result.diagnostics.map((code) => jsonDiagnostic({
+                code,
+                severity: code === "PTGOV-103" || code === "PTGOV-104" ? "warning" : "error",
+                message: code,
+                helpTopic: "editing",
+            })),
+            diagnostics_truncated: false,
+            changed: result.changed,
+            original_digest: result.originalDigest,
+            updated_digest: result.updatedDigest,
+            updated_text: result.updatedText,
+            diff: result.updatedText === null ? null : createUnifiedDiff(input.text, result.updatedText, { originalLabel: sourceOperand, updatedLabel: "candidate" }),
+            edits: result.changed && result.updatedText !== null ? [{ start_offset: 0, end_offset: input.text.length, replacement: result.updatedText }] : [],
+            write: { mode: request.mode, target: request.target, written },
+            governance: result.governance === null ? null : {
+                ...snakeJson(result.governance),
+                schema_version: "Perttool.GovernanceDecision.v2",
+                governance_interface_version: 2,
+                governance_semantics_version: 2,
+            },
+            lifecycle: null,
+            assurance_impact: null,
+        });
+    else if (result.updatedText !== null)
+        process.stdout.write(result.updatedText);
+    return result.ok ? 0 : 1;
+}
+async function runDocumentMigration(args) {
+    const parsed = parseCommandOptions("document.migrate", args);
+    if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "7")
+        throw new UsageError("document migrate requires <file> --target-grammar 7");
+    const sourceOperand = parsed.positionals[0];
+    if (sourceOperand === "-")
+        throw new UsageError("document migrate requires a repository file");
+    const format = outputFormat(parsed.values.get("format"));
+    const input = await readDocument(sourceOperand);
+    const baseline = await captureAdvanceHistoryBaseline({ targetPath: sourceOperand, expectedSourceDigest: input.digest });
+    const toProof = (value) => value.status === "complete" && value.repositorySnapshotId !== null &&
+        value.repositoryRelativePath !== null && value.objectFormat !== null &&
+        value.headCommitId !== null && value.headBlobId !== null &&
+        value.indexBlobId !== null && value.currentSourceDigest !== null
+        ? {
+            repositoryId: value.repositorySnapshotId,
+            repositoryRelativePath: value.repositoryRelativePath,
+            objectFormat: value.objectFormat,
+            headCommit: value.headCommitId,
+            headBlob: value.headBlobId,
+            stage0Blob: value.indexBlobId,
+            sourceDigest: value.currentSourceDigest,
+        }
+        : null;
+    const proof = toProof(baseline);
+    let result = proof === null
+        ? { ok: false, modelVersion: 1, changed: false, sourceGrammarVersion: null, targetGrammarVersion: null, sourceDigest: input.digest, candidateDigest: null, grandfatheredMilestoneIds: Object.freeze([]), candidateText: null, diagnostics: Object.freeze(["PTMAC-109"]) }
+        : planMilestoneAcceptanceMigration(input.text, proof);
+    let race = false;
+    if (result.ok && result.changed && result.candidateText !== null && parsed.flags.has("write")) {
+        const current = toProof(await captureAdvanceHistoryBaseline({
+            targetPath: sourceOperand,
+            expectedSourceDigest: input.digest,
+        }));
+        if (proof === null || current === null || !recheckCommittedMigrationProof(proof, current)) {
+            result = Object.freeze({ ...result, ok: false, diagnostics: Object.freeze(["PTMAC-110"]) });
+            race = true;
+        }
+        else {
+            await replaceValidatedDocumentFile(sourceOperand, result.candidateText, { initialDigest: input.digest, ...(parsed.values.get("expect-digest") === undefined ? {} : { expectedDigest: parsed.values.get("expect-digest") }) }, (candidate) => ({ ok: parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY).ok, diagnostics: [] }));
+        }
+    }
+    if (format === "json")
+        writeJson({ schema_version: "Perttool.MilestoneAcceptanceMigrationResult.v1", cli_contract_version: 8, tool_version: TOOL_VERSION, operation: "document.migrate", ...snakeJson(result) });
+    else if (result.candidateText !== null)
+        process.stdout.write(result.candidateText);
+    return result.ok ? 0 : race ? 5 : 1;
+}
 function runGuide(args) {
     const parsed = parseCommandOptions("guide", args);
     if (parsed.positionals.length > 2) {
@@ -2690,13 +3000,13 @@ function runGuide(args) {
 }
 function runCommandHelp(args) {
     const parsed = parseCommandOptions("help", args);
-    if (parsed.positionals.length > 2) {
-        throw new UsageError("help accepts at most <resource> <action>");
+    if (parsed.positionals.length > 3) {
+        throw new UsageError("help accepts at most <resource> <group> <action>");
     }
     const format = outputFormat(parsed.values.get("format"));
     const result = getAssuranceCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
-        action: parsed.positionals[1] ?? null,
+        action: parsed.positionals.length < 2 ? null : parsed.positionals.slice(1).join(" "),
     });
     if (format === "json") {
         process.stdout.write(serializeAssuranceCommandHelpResult(result));
@@ -2770,7 +3080,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 7,
+            cli_contract_version: 8,
             ...payload,
         });
     }
@@ -2974,14 +3284,14 @@ async function runAssuranceMutation(resource, action, args) {
     });
     if (result.ok && writeRequest.mode !== "preview") {
         try {
-            writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+            writeResult = await persistContract8CandidateResult(result, writeRequest);
         }
         catch (error) {
             return writeFailureExit(error, operation, format === "json");
         }
     }
     if (format === "json") {
-        writeJson(contract7MutationResultToJson(result, operation, source, writeResult));
+        writeJson(contract8MutationResultToJson(result, operation, source, writeResult));
     }
     else {
         if (result.ok) {
@@ -3021,6 +3331,8 @@ async function dispatchCommand(descriptor, args) {
             return runCheck(args);
         case "document.format":
             return runFormat(args);
+        case "document.migrate":
+            return runDocumentMigration(args);
         case "agent.help":
             return runAgentHelp(args);
         case "project.init":
@@ -3051,6 +3363,14 @@ async function dispatchCommand(descriptor, args) {
             return runLifecycleMutation("suspend", args);
         case "task.resume":
             return runLifecycleMutation("resume", args);
+        case "milestone-acceptance.show":
+        case "milestone-acceptance.replace":
+        case "milestone-acceptance.verify":
+        case "milestone-acceptance.fail":
+        case "milestone-acceptance.unavailable":
+        case "milestone-acceptance.revoke":
+        case "milestone-acceptance.waive":
+            return runMilestoneAcceptance(descriptor.path[2], args);
         case "plan-assurance.show":
             return runPlanAssuranceInspection("show", args);
         case "plan-assurance.hash":
@@ -3069,7 +3389,7 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 7 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 8 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {