perttool 0.5.5 → 0.7.0

package/dist/cli.js

@@ -1,36 +1,43 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
+import { lstat, readFile } from "node:fs/promises";
 import process from "node:process";
 import { TextDecoder } from "node:util";
-import { analyzeDocument, selectNextTasks, } from "./application/contract6-actuals.js";
-import { checkDocument } from "./application/check.js";
-import { planFormat } from "./application/format.js";
+import { analyzeDocument, checkDocument, selectNextTasks, } from "./application/contract7-assurance.js";
+import { planFormat, } from "./application/contract7-source.js";
 import { planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, } from "./application/init.js";
-import { planUnitMigration, withUnitMigrationWrite, } from "./application/unit-migration.js";
-import { getProjectMetadata, } from "./application/project.js";
-import { planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, } from "./application/contract6-mutation.js";
-import { renderTargetGovernanceDecision, renderTargetGovernanceProjectText, } from "./application/target-governance-projection.js";
-import { contract6MutationResultToJson, contract6ProjectResultToJson, contract6WorkEventToJson, } from "./application/contract6-projection.js";
-import { persistTargetActualsResult, } from "./application/target-actuals-write.js";
+import { planUnitMigration, withUnitMigrationWrite, } from "./application/contract7-unit-migration.js";
+import { getProjectMetadata, } from "./application/contract7-project.js";
+import { planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, planAssuranceMutation, } from "./application/contract7-mutation.js";
+import { renderTargetGovernanceDecision, } from "./application/target-governance-projection.js";
+import { contract7InspectionResultToJson, contract7MutationResultToJson, contract7SnakeJson, } from "./application/contract7-projection.js";
+import { contract7ProjectResultToJson, renderContract7ProjectText, } from "./application/contract7-project.js";
+import { contract6WorkEventToJson, } from "./application/contract6-projection.js";
+import { renderAdvanceHistoryGuard, } from "./application/advance-history.js";
+import { prepareTargetPlanAssuranceAdvanceHistory, withTargetPlanAssuranceAdvanceHistoryRace, } from "./application/target-assurance-advance-history.js";
+import { persistTargetPlanAssuranceResult, } from "./application/target-assurance-write.js";
+import { inspectTargetPlanAssurance, } from "./application/target-assurance-inspection.js";
 import { inspectTargetProjectHistoryFile, renderTargetProjectHistoryText, targetProjectHistoryResultToJson, } from "./application/target-project-history.js";
 import { observeTargetProjectVelocity, renderTargetVelocityObservationText, targetVelocityObservationResultToJson, } from "./application/target-velocity-observation.js";
 import { getAgentHelp } from "./application/agent-help.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getActualsGuide, renderActualsGuideResult, serializeActualsGuideResult, } from "./help/actuals-guide.js";
+import { getAssuranceGuide, renderAssuranceGuideResult, serializeAssuranceGuideResult, } from "./help/assurance-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { ACTUALS_COMMAND_REGISTRY, getActualsCommandDiscovery, renderActualsCommandHelpResult, serializeActualsCommandHelpResult, } from "./command/actuals-discovery.js";
+import { ASSURANCE_COMMAND_REGISTRY, getAssuranceCommandDiscovery, renderAssuranceCommandHelpResult, serializeAssuranceCommandHelpResult, } from "./command/assurance-discovery.js";
 import { handlerCommandUsageError, } from "./command/usage.js";
-import { renderActualsCommandUsageError, serializeActualsCommandUsageError, validateActualsCommandInvocation, } from "./command/actuals-usage.js";
+import { renderAssuranceCommandUsageError, serializeAssuranceCommandUsageError, validateAssuranceCommandInvocation, } from "./command/assurance-usage.js";
 import { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { documentContentFromBytes, readDocumentFile, } from "./io/document-file.js";
-import { createArtifactFile, createDocumentFile, replaceDocumentFile, SafeWriteConflictError, SafeWriteVerificationError, } from "./io/safe-write.js";
+import { recheckAdvanceHistoryBaseline, } from "./history/git-probe.js";
+import { createArtifactFile, SafeWriteConflictError, SafeWriteVerificationError, } from "./io/safe-write.js";
 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 { TARGET_GRAMMAR_5_CAPABILITY, } from "./parser/document-parser.js";
+import { TARGET_GRAMMAR_6_CAPABILITY, } from "./parser/document-parser.js";
+import { createTargetGrammar6DocumentFile, replaceTargetGrammar6DocumentFile, } from "./io/target-safe-write.js";
+import { exportPlanAssuranceMermaid, importPlanAssuranceMermaid, } from "./assurance/mermaid.js";
 import { getJsonSchemaResult, renderJsonSchemaResult, serializeJsonSchemaResult, } from "./schema/registry.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
@@ -86,7 +93,7 @@ function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new S
     return { positionals, values, repeatedValues, flags };
 }
 function parseCommandOptions(operation, args) {
-    const descriptor = ACTUALS_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
+    const descriptor = ASSURANCE_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
     if (descriptor === undefined) {
         throw new Error(`command descriptor is missing for ${operation}`);
     }
@@ -177,7 +184,24 @@ async function readDocument(source) {
     const content = source === "-"
         ? documentContentFromBytes(await readStdin())
         : await readDocumentFile(source);
-    return { text: content.text, digest: content.digest };
+    let modifiedAt = null;
+    if (source !== "-") {
+        try {
+            const metadata = await lstat(source, { bigint: true });
+            if (metadata.isFile() && !metadata.isSymbolicLink()) {
+                modifiedAt = new Date(Number(metadata.mtimeNs / 1000000n)).toISOString();
+            }
+        }
+        catch {
+            modifiedAt = null;
+        }
+    }
+    return {
+        text: content.text,
+        digest: content.digest,
+        bytes: content.bytes,
+        modifiedAt,
+    };
 }
 async function readStdin() {
     const chunks = [];
@@ -224,7 +248,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -260,7 +284,7 @@ async function runCheck(args) {
     if (format === "json") {
         writeJson({
             schema_version: result.schemaVersion,
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -278,6 +302,8 @@ async function runCheck(args) {
                     model_version: result.actualsInputs.modelVersion,
                     events: result.actualsInputs.events.map(contract6WorkEventToJson),
                 },
+            assurance: contract7SnakeJson(result.assurance),
+            assurance_state_counts: contract7SnakeJson(result.assuranceStateCounts),
         });
     }
     else {
@@ -316,11 +342,11 @@ async function runProjectShow(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson(contract6ProjectResultToJson(result, source, input.digest, ok));
+        writeJson(contract7ProjectResultToJson(result, source, input.digest, ok));
     }
     else {
         if (ok && result.project !== null) {
-            process.stdout.write(renderTargetGovernanceProjectText(result.project));
+            process.stdout.write(renderContract7ProjectText(result.project));
         }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
@@ -377,7 +403,7 @@ async function runProjectInit(args) {
     const output = parsed.values.get("out");
     if (result.ok && output !== undefined) {
         try {
-            writeResult = await createDocumentFile(output, result.candidateText);
+            writeResult = await createTargetGrammar6DocumentFile(output, result.candidateText, TARGET_GRAMMAR_6_CAPABILITY);
             result = withProjectInitOutput(result, writeResult);
         }
         catch (error) {
@@ -494,7 +520,7 @@ async function persistGovernedResult(result, request, sourceOperand) {
             written: false,
         });
     }
-    return persistTargetActualsResult(result, TARGET_GRAMMAR_5_CAPABILITY, request.mode === "in_place"
+    return persistTargetPlanAssuranceResult(result, TARGET_GRAMMAR_6_CAPABILITY, request.mode === "in_place"
         ? {
             mode: "in_place",
             target: request.target,
@@ -520,13 +546,13 @@ async function commitCandidate(request, candidateText, initialDigest) {
         throw new SafeWriteVerificationError("invalid_candidate", "successful editing result has no candidate text");
     }
     return request.mode === "in_place"
-        ? replaceDocumentFile(request.target, candidateText, {
+        ? replaceTargetGrammar6DocumentFile(request.target, candidateText, TARGET_GRAMMAR_6_CAPABILITY, {
             initialDigest,
             ...(request.expectedDigest === undefined
                 ? {}
                 : { expectedDigest: request.expectedDigest }),
         })
-        : createDocumentFile(request.target, candidateText);
+        : createTargetGrammar6DocumentFile(request.target, candidateText, TARGET_GRAMMAR_6_CAPABILITY);
 }
 function writeFailureExit(error, operation, json) {
     const normalized = error instanceof Error ? error : new Error(String(error));
@@ -586,7 +612,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -1195,7 +1221,7 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1278,7 +1304,7 @@ async function runLifecycleMutation(action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1317,7 +1343,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 6,
+        cli_contract_version: 7,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1462,7 +1488,7 @@ async function readHistoryForCommand(operation, parsed, format) {
             ...(parsed.repeatedValues.get("task") === undefined
                 ? {}
                 : { taskIds: parsed.repeatedValues.get("task") }),
-        }, TARGET_GRAMMAR_5_CAPABILITY);
+        }, TARGET_GRAMMAR_6_CAPABILITY);
     }
     catch (error) {
         return error instanceof Error ? error : new Error(String(error));
@@ -1533,6 +1559,15 @@ function renderAdvanceSummary(details) {
         "",
     ].join("\n");
 }
+function renderAssuranceGuard(guard) {
+    const list = (values) => values.join(",") || "-";
+    return [
+        `ASSURANCE_GUARD status=${guard.status} cause=${guard.cause}`,
+        `ASSURANCE_GUARD crossing_producers=${list(guard.crossingProducerTaskIds)} created_receipts=${list(guard.createdReceiptIds)} updated_receipts=${list(guard.updatedReceiptIds)} removed_receipts=${list(guard.removedReceiptIds)}`,
+        ...guard.retainedBasisChecks.map((check) => `ASSURANCE_BASIS task=${check.taskId} before=${check.beforeBasisHash ?? "-"} after=${check.afterBasisHash ?? "-"} equal=${check.equal}`),
+        "",
+    ].join("\n");
+}
 async function runAdvance(args) {
     const parsed = parseCommandOptions("dag.advance", args);
     if (parsed.positionals.length !== 1) {
@@ -1543,6 +1578,10 @@ async function runAdvance(args) {
     const maxDiagnostics = boundedInteger(parsed.values.get("max-diagnostics"), "max-diagnostics", 100, 1, 1000);
     const sourceOperand = parsed.positionals[0];
     const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    const forceRequested = parsed.flags.has("force-history-loss");
+    if (forceRequested && writeRequest.mode !== "in_place") {
+        throw new UsageError("--force-history-loss can only be used with --write");
+    }
     const source = sourceOperand === "-" ? "<stdin>" : sourceOperand;
     let input;
     try {
@@ -1551,23 +1590,54 @@ async function runAdvance(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.advance", format === "json");
     }
-    const result = planAdvance(input.text, {
+    const planned = planAdvance(input.text, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
         governance: governanceRequest(parsed, writeRequest),
     });
+    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, {
+        mode: writeRequest.mode === "out"
+            ? "out"
+            : writeRequest.mode,
+        sourceBytes: input.bytes,
+        sourceModifiedAt: input.modifiedAt,
+        ...(writeRequest.mode === "in_place"
+            ? { targetPath: sourceOperand }
+            : {}),
+        forceRequested,
+        warningDenied: initialWarningFailure,
+        maxDiagnostics,
+    });
+    let result = prepared.result;
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
-    const ok = result.ok && !warningFailure;
+    let ok = result.ok && !warningFailure;
+    let historyRace = false;
     let writeResult = Object.freeze({
         mode: writeRequest.mode,
         target: writeRequest.target,
         written: false,
     });
-    if (result.ok) {
+    if (result.updatedText !== null) {
         try {
+            if (ok &&
+                writeRequest.mode === "in_place" &&
+                prepared.baseline !== null &&
+                prepared.baseline.status === "complete" &&
+                (result.historyGuard?.status === "passed" ||
+                    result.historyGuard?.status === "forced")) {
+                const recheck = await recheckAdvanceHistoryBaseline(prepared.baseline, sourceOperand);
+                if (!recheck.ok) {
+                    result = withTargetPlanAssuranceAdvanceHistoryRace(result, recheck, maxDiagnostics);
+                    ok = false;
+                    historyRace = true;
+                }
+            }
             if (ok && writeRequest.mode !== "preview") {
                 writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
             }
@@ -1577,20 +1647,32 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
+        writeJson(contract7MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
     }
     else {
-        if (ok && result.advance !== null) {
-            if (writeRequest.mode !== "preview") {
-                process.stderr.write(renderGovernanceWriteSummary("dag.advance", writeResult, result.updatedDigest));
-            }
-            else {
-                process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
-                if (!parsed.flags.has("diff")) {
-                    process.stderr.write(`PREVIEW dag.advance changed=${result.changed} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest}\n`);
+        if (result.advance !== null) {
+            if (ok) {
+                if (writeRequest.mode !== "preview") {
+                    process.stderr.write(renderGovernanceWriteSummary("dag.advance", writeResult, result.updatedDigest));
                 }
+                else {
+                    process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
+                    if (!parsed.flags.has("diff")) {
+                        process.stderr.write(`PREVIEW dag.advance changed=${result.changed} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest}\n`);
+                    }
+                }
+            }
+            if (ok ||
+                result.historyGuard?.status === "blocked" ||
+                result.historyGuard?.status === "forced") {
+                process.stderr.write(renderAdvanceSummary(result.advance));
             }
-            process.stderr.write(renderAdvanceSummary(result.advance));
+        }
+        if (result.historyGuard !== null) {
+            process.stderr.write(renderAdvanceHistoryGuard(result.historyGuard));
+        }
+        if (result.assuranceGuard !== null) {
+            process.stderr.write(renderAssuranceGuard(result.assuranceGuard));
         }
         if (result.governance !== null) {
             process.stderr.write(renderTargetGovernanceDecision(result.governance));
@@ -1602,7 +1684,7 @@ async function runAdvance(args) {
             process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
         }
     }
-    return ok ? 0 : 1;
+    return ok ? 0 : historyRace ? 5 : 1;
 }
 function rationalJson(value, unit, precision) {
     return {
@@ -1925,8 +2007,8 @@ async function runAnalyze(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.AnalysisResult.v4",
-            cli_contract_version: 6,
+            schema_version: result.schemaVersion,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1958,6 +2040,7 @@ async function runAnalyze(args) {
                 ? null
                 : resourceJson(result.resource, result.durationUnit, result.precision),
             temporal: snakeJson(result.temporal),
+            assurance: contract7SnakeJson(result.assurance),
         });
     }
     else {
@@ -2020,12 +2103,39 @@ async function runRender(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.render", format === "json");
     }
-    const result = exportMermaid(input.text, {
-        profile,
-        analysis,
-        capacityOverrides: overrides,
-        maxDiagnostics,
-    });
+    const sourceCheck = checkDocument(input.text, { maxDiagnostics });
+    const grammar6 = sourceCheck.grammarVersion === 6;
+    const assuranceExport = grammar6
+        ? exportPlanAssuranceMermaid(input.text, TARGET_GRAMMAR_6_CAPABILITY, {
+            profile: profile === "perttool" ? 2 : "plain",
+            allowLoss: !parsed.flags.has("strict-loss"),
+            analysis,
+            capacityOverrides: overrides,
+            maxDiagnostics,
+        })
+        : null;
+    const legacyExport = grammar6
+        ? null
+        : exportMermaid(input.text, {
+            profile,
+            analysis,
+            capacityOverrides: overrides,
+            maxDiagnostics,
+        });
+    const result = assuranceExport === null
+        ? legacyExport
+        : Object.freeze({
+            ok: assuranceExport.ok,
+            documentId: assuranceExport.documentId,
+            diagnostics: assuranceExport.diagnostics,
+            diagnosticsTruncated: assuranceExport.diagnosticsTruncated,
+            profile,
+            analysis,
+            capacityOverrides: overrides,
+            artifact: assuranceExport.artifact,
+            artifactDigest: assuranceExport.artifactDigest,
+            lossReport: assuranceExport.lossReport,
+        });
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
@@ -2045,7 +2155,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -2117,7 +2227,28 @@ async function runImport(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.import", format === "json");
     }
-    const result = importMermaid(input.text, { maxDiagnostics });
+    const profile2 = input.text.startsWith("flowchart LR\n  %% perttool:profile {\"schema_version\":\"Perttool.MermaidProfile.v2\"");
+    const assuranceImport = profile2
+        ? importPlanAssuranceMermaid(input.text, TARGET_GRAMMAR_6_CAPABILITY)
+        : null;
+    const legacyImport = profile2
+        ? null
+        : importMermaid(input.text, { maxDiagnostics });
+    const result = assuranceImport === null
+        ? legacyImport
+        : Object.freeze({
+            ok: assuranceImport.ok,
+            documentId: assuranceImport.documentId,
+            diagnostics: assuranceImport.diagnostics,
+            diagnosticsTruncated: assuranceImport.diagnosticsTruncated,
+            profile: "perttool",
+            analysis: assuranceImport.analysis,
+            capacityOverrides: assuranceImport.capacityOverrides,
+            artifact: assuranceImport.sourceText,
+            artifactDigest: assuranceImport.sourceDigest,
+            lossReport: assuranceImport.lossReport,
+            generatedIds: Object.freeze([]),
+        });
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
@@ -2128,7 +2259,7 @@ async function runImport(args) {
     let writeResult = null;
     if (ok && out !== null) {
         try {
-            writeResult = await createDocumentFile(out, result.artifact);
+            writeResult = await createTargetGrammar6DocumentFile(out, result.artifact, TARGET_GRAMMAR_6_CAPABILITY);
         }
         catch (error) {
             return writeFailureExit(error, "dag.import", format === "json");
@@ -2137,7 +2268,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -2446,7 +2577,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 6,
+                cli_contract_version: 7,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2466,8 +2597,8 @@ async function runNext(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.NextResult.v5",
-            cli_contract_version: 6,
+            schema_version: result.schemaVersion,
+            cli_contract_version: 7,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2480,6 +2611,7 @@ async function runNext(args) {
             grammar_version: result.grammarVersion,
             ...(result.durationUnit === null ? {} : nextJson(result)),
             temporal: snakeJson(result.temporal),
+            assurance: contract7SnakeJson(result.assurance),
         });
     }
     else {
@@ -2503,12 +2635,12 @@ function runGuide(args) {
     colorMode(parsed.values.get("color"), format);
     const topicId = parsed.positionals.length === 0 ? null : parsed.positionals.join(".");
     const level = helpLevel(parsed.values.get("level"), topicId !== null);
-    const result = getActualsGuide(topicId, level);
+    const result = getAssuranceGuide(topicId, level);
     if (format === "json") {
-        process.stdout.write(serializeActualsGuideResult(result));
+        process.stdout.write(serializeAssuranceGuideResult(result));
     }
     else {
-        const rendered = renderActualsGuideResult(result);
+        const rendered = renderAssuranceGuideResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2524,15 +2656,15 @@ function runCommandHelp(args) {
         throw new UsageError("help accepts at most <resource> <action>");
     }
     const format = outputFormat(parsed.values.get("format"));
-    const result = getActualsCommandDiscovery({
+    const result = getAssuranceCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
         action: parsed.positionals[1] ?? null,
     });
     if (format === "json") {
-        process.stdout.write(serializeActualsCommandHelpResult(result));
+        process.stdout.write(serializeAssuranceCommandHelpResult(result));
     }
     else {
-        const rendered = renderActualsCommandHelpResult(result);
+        const rendered = renderAssuranceCommandHelpResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2600,7 +2732,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 6,
+            cli_contract_version: 7,
             ...payload,
         });
     }
@@ -2622,6 +2754,223 @@ function runAgentHelp(args) {
     }
     return agentGuidanceExitCode(result.diagnostics);
 }
+function renderPlanAssuranceProjection(value) {
+    const list = (values) => values.join(",") || "-";
+    const lines = [
+        `PLAN_ASSURANCE model=${value.modelVersion ?? "-"} hash_model=${value.hashModelVersion ?? "-"} coverage=${value.coverage}`,
+        `REPLAN_REQUIRED ${list(value.replanRequiredTaskIds)}`,
+        `ACTIVE_ATTENTION ${list(value.activeAttentionRequiredTaskIds)}`,
+    ];
+    for (const task of value.taskResults) {
+        lines.push(`TASK ${task.taskId} status=${task.status} contract=${task.contractHash ?? "-"} computed_basis=${task.computedBasisHash ?? "-"} accepted_basis=${task.acceptedBasisHash ?? "-"} exported=${task.exportedAssuranceHash ?? "-"}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function runPlanAssuranceInspection(action, args) {
+    const operation = `plan-assurance.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const maxDiagnostics = boundedInteger(parsed.values.get("max-diagnostics"), "max-diagnostics", 100, 1, 1000);
+    const sourceOperand = parsed.positionals[0];
+    const source = sourceOperand === "-" ? "<stdin>" : sourceOperand;
+    let input;
+    try {
+        input = await readDocument(sourceOperand);
+    }
+    catch (error) {
+        return cliError(error instanceof Error ? error : new Error(String(error)), 3, operation, format === "json");
+    }
+    const result = inspectTargetPlanAssurance(input.text, action === "show"
+        ? {
+            operation: "plan-assurance.show",
+            taskIds: parsed.repeatedValues.get("task") ?? Object.freeze([]),
+        }
+        : {
+            operation: "plan-assurance.hash",
+            taskId: parsed.positionals[1],
+            kind: requiredOption(parsed, "kind"),
+        }, TARGET_GRAMMAR_6_CAPABILITY, { maxDiagnostics });
+    const warningFailure = parsed.flags.has("warnings-as-errors") &&
+        (result.diagnosticsTruncated || result.diagnostics.some(({ severity }) => severity === "warning"));
+    const ok = result.ok && !warningFailure;
+    if (format === "json") {
+        writeJson(contract7InspectionResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), source));
+    }
+    else if (ok) {
+        if (action === "hash") {
+            if (result.selectedHash === null) {
+                throw new Error("successful assurance hash result has no digest");
+            }
+            process.stdout.write(`${result.selectedHash}\n`);
+        }
+        else if (result.assurance !== null) {
+            process.stdout.write(renderPlanAssuranceProjection(result.assurance));
+        }
+    }
+    for (const diagnostic of result.diagnostics) {
+        process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
+    }
+    if (result.diagnosticsTruncated) {
+        process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
+    }
+    return ok ? 0 : 1;
+}
+function dependencyMode(value) {
+    return value === "execution-only"
+        ? "execution_only"
+        : value === "planning-only"
+            ? "planning_only"
+            : "both";
+}
+function assuranceMutationFromOptions(resource, action, parsed) {
+    if (resource === "plan-assurance") {
+        return action === "seal"
+            ? {
+                kind: "plan_assurance.seal",
+                reason: requiredOption(parsed, "reason"),
+            }
+            : {
+                kind: "plan_assurance.reseal",
+                taskIds: uniqueRepeated(parsed, "task"),
+                reason: requiredOption(parsed, "reason"),
+            };
+    }
+    const id = parsed.positionals[1];
+    if (resource === "plan-dependency") {
+        if (action === "add") {
+            return {
+                kind: "plan_dependency.add",
+                id,
+                predecessorTaskId: parsed.positionals[2],
+                successorTaskId: parsed.positionals[3],
+                mode: dependencyMode(requiredOption(parsed, "mode")),
+                ...(parsed.values.get("reason") === undefined
+                    ? {}
+                    : { reason: parsed.values.get("reason") }),
+            };
+        }
+        if (action === "remove")
+            return { kind: "plan_dependency.remove", id };
+        const clear = uniqueRepeated(parsed, "clear");
+        return {
+            kind: "plan_dependency.set",
+            id,
+            ...(parsed.values.get("predecessor") === undefined
+                ? {}
+                : { predecessorTaskId: parsed.values.get("predecessor") }),
+            ...(parsed.values.get("successor") === undefined
+                ? {}
+                : { successorTaskId: parsed.values.get("successor") }),
+            ...(parsed.values.get("mode") === undefined
+                ? {}
+                : { mode: dependencyMode(parsed.values.get("mode")) }),
+            ...(parsed.values.get("reason") === undefined
+                ? {}
+                : { reason: parsed.values.get("reason") }),
+            ...(clear.includes("reason") ? { clearReason: true } : {}),
+        };
+    }
+    if (action === "add") {
+        return {
+            kind: "task_outcome.add",
+            id,
+            taskId: parsed.positionals[2],
+            status: requiredOption(parsed, "status"),
+            ...(parsed.values.get("summary") === undefined
+                ? {}
+                : { summary: parsed.values.get("summary") }),
+            reason: requiredOption(parsed, "reason"),
+        };
+    }
+    if (action === "remove")
+        return { kind: "task_outcome.remove", id };
+    const clear = uniqueRepeated(parsed, "clear");
+    return {
+        kind: "task_outcome.set",
+        id,
+        ...(parsed.values.get("status") === undefined
+            ? {}
+            : {
+                status: parsed.values.get("status"),
+            }),
+        ...(parsed.values.get("summary") === undefined
+            ? {}
+            : { summary: parsed.values.get("summary") }),
+        ...(clear.includes("summary") ? { clearSummary: true } : {}),
+        ...(parsed.values.get("reason") === undefined
+            ? {}
+            : { reason: parsed.values.get("reason") }),
+        ...(parsed.flags.has("rebind-current-basis")
+            ? { rebindCurrentBasis: true }
+            : {}),
+    };
+}
+async function runAssuranceMutation(resource, action, args) {
+    const operation = `${resource}.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const maxDiagnostics = boundedInteger(parsed.values.get("max-diagnostics"), "max-diagnostics", 100, 1, 1000);
+    const sourceOperand = parsed.positionals[0];
+    const source = sourceOperand === "-" ? "<stdin>" : sourceOperand;
+    const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    let input;
+    try {
+        input = await readDocument(sourceOperand);
+    }
+    catch (error) {
+        return cliError(error instanceof Error ? error : new Error(String(error)), 3, operation, format === "json");
+    }
+    const result = planAssuranceMutation(input.text, assuranceMutationFromOptions(resource, action, parsed), {
+        maxDiagnostics,
+        originalLabel: source,
+        updatedLabel: "candidate",
+        warningsAsErrors: parsed.flags.has("warnings-as-errors"),
+        governance: governanceRequest(parsed, writeRequest),
+    });
+    let writeResult = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
+    if (result.ok && writeRequest.mode !== "preview") {
+        try {
+            writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+        }
+        catch (error) {
+            return writeFailureExit(error, operation, format === "json");
+        }
+    }
+    if (format === "json") {
+        writeJson(contract7MutationResultToJson(result, operation, source, writeResult));
+    }
+    else {
+        if (result.ok) {
+            if (writeRequest.mode === "preview") {
+                process.stdout.write(parsed.flags.has("diff")
+                    ? (result.diff ?? "")
+                    : (result.updatedText ?? ""));
+                if (!parsed.flags.has("diff")) {
+                    process.stderr.write(`PREVIEW ${operation} changed=${result.changed} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest}\n`);
+                }
+            }
+            else {
+                process.stderr.write(renderGovernanceWriteSummary(operation, writeResult, result.updatedDigest));
+            }
+        }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
+        for (const diagnostic of result.diagnostics) {
+            process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
+        }
+        if (result.diagnosticsTruncated) {
+            process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
+        }
+    }
+    return result.ok ? 0 : 1;
+}
 async function dispatchCommand(descriptor, args) {
     switch (descriptor.operation) {
         case "help":
@@ -2662,6 +3011,16 @@ async function dispatchCommand(descriptor, args) {
             return runLifecycleMutation("suspend", args);
         case "task.resume":
             return runLifecycleMutation("resume", args);
+        case "plan-assurance.show":
+            return runPlanAssuranceInspection("show", args);
+        case "plan-assurance.hash":
+            return runPlanAssuranceInspection("hash", args);
+    }
+    if (descriptor.path.length === 2 &&
+        (descriptor.path[0] === "plan-assurance" ||
+            descriptor.path[0] === "plan-dependency" ||
+            descriptor.path[0] === "task-outcome")) {
+        return runAssuranceMutation(descriptor.path[0], descriptor.path[1], args);
     }
     if (descriptor.path.length === 2
         && (descriptor.operation === "project.set"
@@ -2670,14 +3029,14 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 6 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 7 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {
-        process.stdout.write(serializeActualsCommandUsageError(error));
+        process.stdout.write(serializeAssuranceCommandUsageError(error));
     }
     else {
-        process.stderr.write(renderActualsCommandUsageError(error));
+        process.stderr.write(renderAssuranceCommandUsageError(error));
     }
     return 2;
 }
@@ -2689,13 +3048,13 @@ async function main(argv) {
     if (argv.length === 1 && argv[0] === "--help") {
         return runCommandHelp([]);
     }
-    const validation = validateActualsCommandInvocation(argv);
+    const validation = validateAssuranceCommandInvocation(argv);
     if (!validation.ok) {
         if (jsonRequested(argv)) {
-            process.stdout.write(serializeActualsCommandUsageError(validation.error));
+            process.stdout.write(serializeAssuranceCommandUsageError(validation.error));
         }
         else {
-            process.stderr.write(renderActualsCommandUsageError(validation.error));
+            process.stderr.write(renderAssuranceCommandUsageError(validation.error));
         }
         return 2;
     }