perttool 0.2.0 → 0.4.0

package/dist/cli.js

@@ -2,20 +2,23 @@
 import { readFile } from "node:fs/promises";
 import process from "node:process";
 import { TextDecoder } from "node:util";
-import { analyzeDocument } from "./application/analyze.js";
+import { analyzeDocument, selectNextTasks, } from "./application/contract4.js";
 import { checkDocument } from "./application/check.js";
 import { planFormat } from "./application/format.js";
 import { planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, } from "./application/init.js";
-import { planBatchMutation, planMutation } from "./application/mutate.js";
-import { selectNextTasks } from "./application/next.js";
+import { planUnitMigration, withUnitMigrationWrite, } from "./application/unit-migration.js";
 import { getProjectMetadata, } from "./application/project.js";
+import { planTargetGovernanceAdvance, planTargetGovernanceBatchMutation, planTargetGovernanceMutation, } from "./application/target-governance-mutation.js";
+import { renderTargetGovernanceDecision, renderTargetGovernanceProjectText, targetGovernanceMutationResultToJson, targetGovernanceProjectResultToJson, } from "./application/target-governance-projection.js";
+import { persistTargetGovernanceResult, } from "./application/target-governance-write.js";
 import { getAgentHelp } from "./application/agent-help.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getGuide, renderGuideResult, serializeGuideResult, } from "./help/guide.js";
+import { getTargetGovernanceGuide, renderTargetGovernanceGuideResult, serializeTargetGovernanceGuideResult, } from "./help/target-governance-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { CONTRACT3_COMMAND_REGISTRY, getCommandDiscovery, renderCommandHelpResult, serializeCommandHelpResult, } from "./command/discovery.js";
-import { handlerCommandUsageError, renderCommandUsageError, serializeCommandUsageError, validateCommandInvocation, } from "./command/usage.js";
+import { TARGET_GOVERNANCE_COMMAND_REGISTRY, getTargetGovernanceCommandDiscovery, renderTargetGovernanceCommandHelpResult, serializeTargetGovernanceCommandHelpResult, } from "./command/target-governance-discovery.js";
+import { handlerCommandUsageError, } from "./command/usage.js";
+import { renderTargetGovernanceCommandUsageError, serializeTargetGovernanceCommandUsageError, validateTargetGovernanceCommandInvocation, } from "./command/target-governance-usage.js";
 import { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { documentContentFromBytes, readDocumentFile, } from "./io/document-file.js";
@@ -24,7 +27,7 @@ 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 { planAdvance, } from "./mutation/advance.js";
+import { TARGET_GRAMMAR_4_CAPABILITY, } from "./parser/document-parser.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
@@ -79,7 +82,7 @@ function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new S
     return { positionals, values, repeatedValues, flags };
 }
 function parseCommandOptions(operation, args) {
-    const descriptor = CONTRACT3_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
+    const descriptor = TARGET_GOVERNANCE_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
     if (descriptor === undefined) {
         throw new Error(`command descriptor is missing for ${operation}`);
     }
@@ -182,6 +185,18 @@ async function readStdin() {
 function writeJson(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
 }
+function snakeJson(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (Array.isArray(value))
+        return value.map(snakeJson);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase(),
+        snakeJson(item),
+    ]));
+}
 function cliError(error, exitCode, operation, json) {
     const code = error instanceof UsageError
         ? error.code
@@ -205,7 +220,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 3,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -240,8 +255,8 @@ async function runCheck(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.CheckResult.v1",
-            cli_contract_version: 3,
+            schema_version: "Perttool.CheckResult.v2",
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -252,11 +267,12 @@ async function runCheck(args) {
             diagnostics_truncated: result.diagnosticsTruncated,
             grammar_version: result.grammarVersion,
             summary: result.summary,
+            temporal_inputs: snakeJson(result.temporalInputs),
         });
     }
     else {
         if (ok) {
-            process.stdout.write(`OK ${source} project=${result.documentId ?? "-"} milestones=${result.summary.milestones} tasks=${result.summary.tasks} gates=${result.summary.gates} resources=${result.summary.resources}\n`);
+            process.stdout.write(`OK ${source} project=${result.documentId ?? "-"} milestones=${result.summary.milestones} tasks=${result.summary.tasks} gates=${result.summary.gates} resources=${result.summary.resources} temporal=milestone_deadlines:${result.temporalInputs?.milestoneDeadlines.length ?? 0},task_not_before:${result.temporalInputs?.taskConstraints.filter(({ notBefore }) => notBefore !== null).length ?? 0},task_deadlines:${result.temporalInputs?.taskConstraints.filter(({ deadline }) => deadline !== null).length ?? 0}\n`);
         }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
@@ -267,36 +283,6 @@ async function runCheck(args) {
     }
     return ok ? 0 : 1;
 }
-function projectJson(project) {
-    return {
-        id: project.id,
-        version: project.version,
-        title: project.title,
-        description: project.description,
-        as_of: project.asOf,
-        duration_unit: project.durationUnit,
-        velocity: project.velocity,
-        finish: project.finish,
-        critical_epsilon: project.criticalEpsilon,
-        target_duration: project.targetDuration,
-    };
-}
-function renderProjectText(project) {
-    const optional = (value) => value ?? "-";
-    return [
-        `PROJECT ${project.id}`,
-        `VERSION ${project.version}`,
-        `TITLE ${JSON.stringify(project.title)}`,
-        `DESCRIPTION ${project.description === null ? "-" : JSON.stringify(project.description)}`,
-        `AS_OF ${optional(project.asOf)}`,
-        `DURATION_UNIT ${project.durationUnit}`,
-        `VELOCITY ${optional(project.velocity)}`,
-        `FINISH ${project.finish}`,
-        `CRITICAL_EPSILON ${optional(project.criticalEpsilon)}`,
-        `TARGET_DURATION ${optional(project.targetDuration)}`,
-        "",
-    ].join("\n");
-}
 async function runProjectShow(args) {
     const parsed = parseCommandOptions("project.show", args);
     if (parsed.positionals.length !== 1) {
@@ -320,24 +306,11 @@ async function runProjectShow(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.ProjectResult.v1",
-            cli_contract_version: 3,
-            tool_version: TOOL_VERSION,
-            operation: "project.show",
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            grammar_version: result.grammarVersion,
-            project: result.project === null ? null : projectJson(result.project),
-        });
+        writeJson(targetGovernanceProjectResultToJson(result, source, input.digest, ok));
     }
     else {
         if (ok && result.project !== null) {
-            process.stdout.write(renderProjectText(result.project));
+            process.stdout.write(renderTargetGovernanceProjectText(result.project));
         }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
@@ -368,6 +341,27 @@ async function runProjectInit(args) {
         ...(parsed.values.get("velocity") === undefined
             ? {}
             : { velocity: parsed.values.get("velocity") }),
+        ...(parsed.values.get("initial-milestone-deadline") === undefined
+            ? {}
+            : {
+                initialMilestoneDeadline: parsed.values.get("initial-milestone-deadline"),
+            }),
+        ...(parsed.values.get("goal-owner") === undefined
+            ? {}
+            : { goalOwner: parsed.values.get("goal-owner") }),
+        ...(parsed.values.get("goal-delegates") === undefined
+            ? {}
+            : {
+                goalDelegates: principalListOption(parsed.values.get("goal-delegates")),
+            }),
+        ...(parsed.values.get("dag-owner") === undefined
+            ? {}
+            : { dagOwner: parsed.values.get("dag-owner") }),
+        ...(parsed.values.get("dag-delegates") === undefined
+            ? {}
+            : {
+                dagDelegates: principalListOption(parsed.values.get("dag-delegates")),
+            }),
     });
     let writeResult = null;
     const output = parsed.values.get("out");
@@ -471,6 +465,39 @@ function editingWriteRequest(parsed, sourceOperand, check = false) {
         return { mode: "out", target: out };
     return { mode: "preview", target: null };
 }
+function governanceRequest(parsed, writeRequest) {
+    return Object.freeze({
+        intent: writeRequest.mode === "preview"
+            ? "preview"
+            : "persist",
+        actor: parsed.values.get("actor") ?? null,
+        acceptedByOwner: Object.freeze([
+            ...(parsed.repeatedValues.get("accepted-by-owner") ?? []),
+        ]),
+    });
+}
+async function persistGovernedResult(result, request, sourceOperand) {
+    if (request.mode === "preview") {
+        return Object.freeze({
+            mode: "preview",
+            target: null,
+            written: false,
+        });
+    }
+    return persistTargetGovernanceResult(result, TARGET_GRAMMAR_4_CAPABILITY, request.mode === "in_place"
+        ? {
+            mode: "in_place",
+            target: request.target,
+            ...(request.expectedDigest === undefined
+                ? {}
+                : { expectedDigest: request.expectedDigest }),
+        }
+        : {
+            mode: "out",
+            source: sourceOperand,
+            target: request.target,
+        });
+}
 function assertExpectedDigest(request, initialDigest) {
     if (request.mode === "in_place" &&
         request.expectedDigest !== undefined &&
@@ -503,6 +530,9 @@ function writeFailureExit(error, operation, json) {
 function renderWriteSummary(operation, result) {
     return `WRITE ${operation} mode=${result.mode} target=${result.target} digest=${result.digest} written=${result.written}\n`;
 }
+function renderGovernanceWriteSummary(operation, result, digest) {
+    return `WRITE ${operation} mode=${result.mode} target=${result.target ?? "-"} digest=${digest ?? "-"} written=${result.written}\n`;
+}
 async function runFormat(args) {
     const parsed = parseCommandOptions("document.format", args);
     if (parsed.positionals.length !== 1) {
@@ -546,7 +576,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 3,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -614,6 +644,12 @@ function uniqueRepeated(parsed, option) {
     }
     return values;
 }
+function principalListOption(value) {
+    const interior = value.slice(1, -1).trim();
+    return interior === ""
+        ? Object.freeze([])
+        : Object.freeze(interior.split(",").map((item) => item.trim()));
+}
 function enumRepeated(parsed, option, allowed) {
     return uniqueRepeated(parsed, option).map((value) => {
         if (!allowed.has(value)) {
@@ -700,6 +736,12 @@ function taskMutationFromOptions(action, parsed) {
                 ...(parsed.values.get("description") === undefined
                     ? {}
                     : { description: parsed.values.get("description") }),
+                ...(parsed.values.get("not-before") === undefined
+                    ? {}
+                    : { notBefore: parsed.values.get("not-before") }),
+                ...(parsed.values.get("deadline") === undefined
+                    ? {}
+                    : { deadline: parsed.values.get("deadline") }),
                 ...(status === undefined ? {} : { status }),
                 ...(priority === undefined ? {} : { priority }),
                 ...(requirements.length === 0 ? {} : { requirements }),
@@ -720,7 +762,7 @@ function taskMutationFromOptions(action, parsed) {
     }
     const clear = enumRepeated(parsed, "clear", new Set([
         "description", "status", "priority", "owner", "blocked_reason", "source",
-        "tags", "requires",
+        "tags", "requires", "not_before", "deadline",
     ]));
     const addTags = uniqueRepeated(parsed, "add-tag");
     const removeTags = uniqueRepeated(parsed, "remove-tag");
@@ -735,6 +777,12 @@ function taskMutationFromOptions(action, parsed) {
             ? {}
             : { description: parsed.values.get("description") }),
         ...timing,
+        ...(parsed.values.get("not-before") === undefined
+            ? {}
+            : { notBefore: parsed.values.get("not-before") }),
+        ...(parsed.values.get("deadline") === undefined
+            ? {}
+            : { deadline: parsed.values.get("deadline") }),
         ...(status === undefined ? {} : { status }),
         ...(priority === undefined ? {} : { priority }),
         ...(parsed.values.get("owner") === undefined
@@ -749,6 +797,8 @@ function taskMutationFromOptions(action, parsed) {
     };
     const clearConflicts = new Map([
         ["description", parsed.values.has("description")],
+        ["not_before", parsed.values.has("not-before")],
+        ["deadline", parsed.values.has("deadline")],
         ["status", status !== undefined],
         ["priority", priority !== undefined],
         ["owner", parsed.values.has("owner")],
@@ -786,6 +836,10 @@ function projectMutationFromOptions(parsed) {
         "velocity",
         "critical_epsilon",
         "target_duration",
+        "goal_owner",
+        "goal_delegates",
+        "dag_owner",
+        "dag_delegates",
     ]));
     const conflicts = new Map([
         ["description", parsed.values.has("description")],
@@ -793,6 +847,10 @@ function projectMutationFromOptions(parsed) {
         ["velocity", parsed.values.has("velocity")],
         ["critical_epsilon", parsed.values.has("critical-epsilon")],
         ["target_duration", parsed.values.has("target-duration")],
+        ["goal_owner", parsed.values.has("goal-owner")],
+        ["goal_delegates", parsed.values.has("goal-delegates")],
+        ["dag_owner", parsed.values.has("dag-owner")],
+        ["dag_delegates", parsed.values.has("dag-delegates")],
     ]);
     const conflict = clear.find((field) => conflicts.get(field) === true);
     if (conflict !== undefined) {
@@ -823,6 +881,22 @@ function projectMutationFromOptions(parsed) {
         ...(parsed.values.get("target-duration") === undefined
             ? {}
             : { targetDuration: parsed.values.get("target-duration") }),
+        ...(parsed.values.get("goal-owner") === undefined
+            ? {}
+            : { goalOwner: parsed.values.get("goal-owner") }),
+        ...(parsed.values.get("goal-delegates") === undefined
+            ? {}
+            : {
+                goalDelegates: principalListOption(parsed.values.get("goal-delegates")),
+            }),
+        ...(parsed.values.get("dag-owner") === undefined
+            ? {}
+            : { dagOwner: parsed.values.get("dag-owner") }),
+        ...(parsed.values.get("dag-delegates") === undefined
+            ? {}
+            : {
+                dagDelegates: principalListOption(parsed.values.get("dag-delegates")),
+            }),
     };
     return {
         kind: "project.set",
@@ -848,18 +922,22 @@ function milestoneMutationFromOptions(action, parsed) {
                     ? {}
                     : { description: parsed.values.get("description") }),
                 ...(state === undefined ? {} : { state }),
+                ...(parsed.values.get("deadline") === undefined
+                    ? {}
+                    : { deadline: parsed.values.get("deadline") }),
                 ...((parsed.repeatedValues.get("tag") ?? []).length === 0
                     ? {}
                     : { tags: parsed.repeatedValues.get("tag") }),
             },
         };
     }
-    const clear = enumRepeated(parsed, "clear", new Set(["description", "state", "tags"]));
+    const clear = enumRepeated(parsed, "clear", new Set(["description", "state", "deadline", "tags"]));
     const addTags = uniqueRepeated(parsed, "add-tag");
     const removeTags = uniqueRepeated(parsed, "remove-tag");
     ensureDisjoint(addTags, "add-tag", removeTags, "remove-tag");
     if (clear.some((field) => (field === "description" && parsed.values.has("description")) ||
         (field === "state" && state !== undefined) ||
+        (field === "deadline" && parsed.values.has("deadline")) ||
         (field === "tags" && (addTags.length > 0 || removeTags.length > 0)))) {
         throw new UsageError("--clear conflicts with another milestone field option");
     }
@@ -871,6 +949,9 @@ function milestoneMutationFromOptions(action, parsed) {
             ? {}
             : { description: parsed.values.get("description") }),
         ...(state === undefined ? {} : { state }),
+        ...(parsed.values.get("deadline") === undefined
+            ? {}
+            : { deadline: parsed.values.get("deadline") }),
     };
     return {
         kind: "milestone.set",
@@ -1040,20 +1121,24 @@ async function runMutation(resource, action, args) {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
+        governance: governanceRequest(parsed, writeRequest),
     };
     const result = resource === "batch"
-        ? planBatchMutation(input.text, mutation, mutationOptions)
-        : planMutation(input.text, mutation, mutationOptions);
+        ? planTargetGovernanceBatchMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, mutationOptions)
+        : planTargetGovernanceMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, mutationOptions);
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
-    let writeResult = null;
+    let writeResult = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
     if (result.ok) {
         try {
-            assertExpectedDigest(writeRequest, input.digest);
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await commitCandidate(writeRequest, result.updatedText, input.digest);
+                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
             }
         }
         catch (error) {
@@ -1061,24 +1146,12 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 3,
-            tool_version: TOOL_VERSION,
-            operation,
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            ...previewResultJson(result, result.ok, writeRequest, writeResult),
-        });
+        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
-            if (writeResult !== null) {
-                process.stderr.write(renderWriteSummary(operation, writeResult));
+            if (writeRequest.mode !== "preview") {
+                process.stderr.write(renderGovernanceWriteSummary(operation, writeResult, result.updatedDigest));
             }
             else {
                 process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
@@ -1087,6 +1160,9 @@ async function runMutation(resource, action, args) {
                 }
             }
         }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
@@ -1096,18 +1172,141 @@ async function runMutation(resource, action, args) {
     }
     return ok ? 0 : 1;
 }
-function advanceResultJson(details) {
-    return details === null
-        ? null
-        : {
-            removed_task_ids: details.removedTaskIds,
-            removed_gate_ids: details.removedGateIds,
-            removed_milestone_ids: details.removedMilestoneIds,
-            frontier_before: details.frontierBefore,
-            frontier_after: details.frontierAfter,
-            ready_before: details.readyBefore,
-            ready_after: details.readyAfter,
-        };
+function unitMigrationJson(result, source, sourceDigest, ok) {
+    const exact = (value) => ({
+        numerator: value.numerator.toString(),
+        denominator: value.denominator.toString(),
+        unit: value.unit,
+    });
+    return {
+        schema_version: result.schemaVersion,
+        cli_contract_version: 5,
+        tool_version: TOOL_VERSION,
+        operation: "project.migrate-unit",
+        ok,
+        document_id: result.documentId,
+        source,
+        source_digest: sourceDigest,
+        diagnostics: result.diagnostics.map(jsonDiagnostic),
+        diagnostics_truncated: result.diagnosticsTruncated,
+        unit_migration: result.unitMigration,
+        source_grammar_version: result.sourceGrammarVersion,
+        target_grammar_version: result.targetGrammarVersion,
+        grammar_disposition: result.grammarDisposition,
+        source_unit: result.sourceUnit,
+        target_unit: result.targetUnit,
+        effective_velocity: result.effectiveVelocity === null
+            ? null
+            : {
+                points: exact(result.effectiveVelocity.points),
+                period: exact(result.effectiveVelocity.period),
+            },
+        velocity_disposition: result.velocityDisposition,
+        changed: result.changed,
+        converted_fields: result.convertedFields.map((field) => ({
+            entity_kind: field.entityKind,
+            entity_id: field.entityId,
+            field_path: field.fieldPath,
+            original: exact(field.original),
+            converted: exact(field.converted),
+            canonical_token: field.canonicalToken,
+        })),
+        reversibility: result.reversibility,
+        qualifications: result.qualifications,
+        unavailable_causes: result.unavailableCauses.map((cause) => ({
+            cause: cause.cause,
+            diagnostic_code: cause.diagnosticCode,
+            field_paths: cause.fieldPaths,
+        })),
+        original_digest: result.originalDigest,
+        updated_digest: result.updatedDigest,
+        updated_text: result.updatedText,
+        diff: result.diff,
+        edits: result.edits.map((edit) => ({
+            start_offset: edit.startOffset,
+            end_offset: edit.endOffset,
+            replacement: edit.replacement,
+        })),
+        write: {
+            mode: result.write.mode,
+            target: result.write.target,
+            written: result.write.written,
+        },
+    };
+}
+async function runUnitMigration(args) {
+    const parsed = parseCommandOptions("project.migrate-unit", args);
+    if (parsed.positionals.length !== 1) {
+        throw new UsageError("project migrate-unit requires exactly one <file>");
+    }
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const targetUnit = enumOption(requiredOption(parsed, "to-unit"), "to-unit", new Set(["day", "hour", "point"]));
+    const maxDiagnostics = boundedInteger(parsed.values.get("max-diagnostics"), "max-diagnostics", 100, 1, 1000);
+    const sourceOperand = parsed.positionals[0];
+    const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    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, "project.migrate-unit", format === "json");
+    }
+    let result = planUnitMigration(input.text, {
+        targetUnit,
+        ...(parsed.values.get("replacement-velocity") === undefined
+            ? {}
+            : {
+                replacementVelocity: parsed.values.get("replacement-velocity"),
+            }),
+    }, {
+        maxDiagnostics,
+        originalLabel: source,
+        updatedLabel: "candidate",
+    });
+    const warningFailure = parsed.flags.has("warnings-as-errors") &&
+        (result.diagnosticsTruncated ||
+            result.diagnostics.some(({ severity }) => severity === "warning"));
+    const ok = result.ok && !warningFailure;
+    let writeResult = null;
+    if (result.ok) {
+        try {
+            assertExpectedDigest(writeRequest, input.digest);
+            if (ok && writeRequest.mode !== "preview") {
+                writeResult = await commitCandidate(writeRequest, result.updatedText, input.digest);
+                result = withUnitMigrationWrite(result, writeResult);
+            }
+        }
+        catch (error) {
+            return writeFailureExit(error, "project.migrate-unit", format === "json");
+        }
+    }
+    if (format === "json") {
+        writeJson(unitMigrationJson(result, source, input.digest, ok));
+    }
+    else {
+        if (ok) {
+            if (writeResult !== null) {
+                process.stderr.write(renderWriteSummary("project.migrate-unit", writeResult));
+            }
+            else {
+                process.stdout.write(parsed.flags.has("diff")
+                    ? (result.diff ?? "")
+                    : (result.updatedText ?? ""));
+                if (!parsed.flags.has("diff")) {
+                    process.stderr.write(`PREVIEW project.migrate-unit changed=${result.changed} source_unit=${result.sourceUnit ?? "-"} target_unit=${result.targetUnit} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest ?? "-"}\n`);
+                }
+            }
+        }
+        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 renderAdvanceSummary(details) {
     const list = (ids) => ids.join(",") || "-";
@@ -1135,21 +1334,25 @@ 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 result = planTargetGovernanceAdvance(input.text, TARGET_GRAMMAR_4_CAPABILITY, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
+        governance: governanceRequest(parsed, writeRequest),
     });
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
-    let writeResult = null;
+    let writeResult = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
     if (result.ok) {
         try {
-            assertExpectedDigest(writeRequest, input.digest);
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await commitCandidate(writeRequest, result.updatedText, input.digest);
+                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
             }
         }
         catch (error) {
@@ -1157,25 +1360,12 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 3,
-            tool_version: TOOL_VERSION,
-            operation: "dag.advance",
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            ...previewResultJson(result, result.ok, writeRequest, writeResult),
-            advance: advanceResultJson(result.advance),
-        });
+        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
     }
     else {
         if (ok && result.advance !== null) {
-            if (writeResult !== null) {
-                process.stderr.write(renderWriteSummary("dag.advance", writeResult));
+            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 ?? ""));
@@ -1185,6 +1375,9 @@ async function runAdvance(args) {
             }
             process.stderr.write(renderAdvanceSummary(result.advance));
         }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
@@ -1437,6 +1630,41 @@ function renderAnalysisText(result) {
         if (resource.resources.length === 0)
             lines.push("-");
     }
+    if (result.temporal !== null) {
+        const temporalPoint = (point) => {
+            const causes = point.unavailableCauses
+                .map(({ cause }) => cause)
+                .join(",") || "-";
+            return [
+                `state=${point.state}`,
+                `relative=${point.relative === null ? "-" : `${point.relative.numerator}/${point.relative.denominator}${durationSuffix(point.relative.unit)}`}`,
+                `calendar=${point.calendar?.sourceText ?? "-"}`,
+                `causes=${causes}`,
+            ].join(" ");
+        };
+        for (const [title, projection] of [
+            ["TEMPORAL PRECEDENCE", result.temporal.precedence],
+            ["TEMPORAL RESOURCE", result.temporal.resource],
+        ]) {
+            lines.push("", title, `STATE ${projection.state}`, `ALGORITHM ${projection.algorithm === null ? "-" : `${projection.algorithm.id}@${projection.algorithm.version} optimal=${projection.algorithm.optimal}`}`, `CONDITIONAL_ON_BLOCKS_RESOLVED ${projection.conditionalOnBlocksResolved}`, `BLOCKED_TASKS ${projection.blockedTaskIds.join(",") || "-"}`);
+            for (const task of projection.tasks) {
+                lines.push(`${task.taskId} START ${temporalPoint(task.start)} FINISH ${temporalPoint(task.finish)}`);
+            }
+            if (projection.tasks.length === 0)
+                lines.push("-");
+        }
+        lines.push("", "DEADLINES");
+        for (const evaluation of result.temporal.deadlineEvaluations) {
+            const causes = [
+                ...evaluation.current.unavailableCauses,
+                ...evaluation.precedence.unavailableCauses,
+                ...evaluation.resource.unavailableCauses,
+            ].map(({ cause }) => cause).join(",") || "-";
+            lines.push(`${evaluation.subject.kind}:${evaluation.subject.id} assessment=${evaluation.combinedAssessment} precedence=${evaluation.precedence.assessment ?? evaluation.precedence.state} resource=${evaluation.resource.assessment ?? evaluation.resource.state} conditional=${evaluation.conditionalOnBlocksResolved} causes=${causes}`);
+        }
+        if (result.temporal.deadlineEvaluations.length === 0)
+            lines.push("-");
+    }
     return `${lines.join("\n")}\n`;
 }
 async function runAnalyze(args) {
@@ -1473,8 +1701,8 @@ async function runAnalyze(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.AnalysisResult.v2",
-            cli_contract_version: 3,
+            schema_version: "Perttool.AnalysisResult.v3",
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1483,6 +1711,7 @@ async function runAnalyze(args) {
             source_digest: input.digest,
             diagnostics: result.diagnostics.map(jsonDiagnostic),
             diagnostics_truncated: result.diagnosticsTruncated,
+            grammar_version: result.grammarVersion,
             mode: result.mode,
             precision: result.precision,
             ...(result.durationUnit === null
@@ -1499,6 +1728,7 @@ async function runAnalyze(args) {
             resource: result.resource === null || result.durationUnit === null
                 ? null
                 : resourceJson(result.resource, result.durationUnit, result.precision),
+            temporal: snakeJson(result.temporal),
         });
     }
     else {
@@ -1586,7 +1816,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 3,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1678,7 +1908,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 3,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -1895,7 +2125,15 @@ function renderExplanation(node, indent) {
 function renderNextText(result) {
     const unit = result.durationUnit;
     const taskById = new Map(result.tasks.map((task) => [task.id, task]));
+    const authority = result.temporal.authority;
     const lines = [
+        "START AUTHORITY",
+        `POLICY ${authority.policy}`,
+        `STARTABLE RECOMMENDED ${authority.startableRecommendedTaskIds.join(",") || "-"}`,
+        `DELAYED RECOMMENDED ${authority.delayedRecommendedTaskIds.join(",") || "-"}`,
+        `UNAVAILABLE RECOMMENDED ${authority.unavailableRecommendedTaskIds.join(",") || "-"}`,
+        "DEADLINE FACTS INFORMATIONAL FOR RANKING v1",
+        "",
         `PERTTOOL NEXT ${result.documentId ?? "-"}`,
         `VELOCITY ${result.velocity === null ? "-" : velocityText(result.velocity, result.precision)}`,
         `VELOCITY_FORECAST_UNIT ${result.velocityForecast?.targetUnit ?? "-"}`,
@@ -1934,6 +2172,15 @@ function renderNextText(result) {
     section("READY / WAITING RESOURCE", result.groups.ready.filter((id) => !result.groups.runnableNow.includes(id)), "rejection");
     section("BLOCKED NOW", result.groups.blockedNow, "blocked");
     section("UPCOMING", result.groups.upcoming, "explanation");
+    lines.push("", "TEMPORAL CONTEXT");
+    for (const temporal of result.temporal.tasks) {
+        const causes = temporal.timeEligibility.unavailableCauses
+            .map(({ cause }) => cause)
+            .join(",") || "-";
+        lines.push(`${temporal.taskId} eligibility=${temporal.timeEligibility.state} release=${temporal.timeEligibility.releaseBound === null ? "-" : `${temporal.timeEligibility.releaseBound.numerator}/${temporal.timeEligibility.releaseBound.denominator}${durationSuffix(temporal.timeEligibility.releaseBound.unit)}`} task_deadline=${temporal.taskDeadline?.sourceText ?? "-"} destination=${temporal.destinationMilestoneId} destination_deadline=${temporal.destinationDeadline?.sourceText ?? "-"} causes=${causes}`);
+    }
+    if (result.temporal.tasks.length === 0)
+        lines.push("-");
     return `${lines.join("\n")}\n`;
 }
 async function runNext(args) {
@@ -1968,7 +2215,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 3,
+                cli_contract_version: 5,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -1988,8 +2235,8 @@ async function runNext(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.NextResult.v3",
-            cli_contract_version: 3,
+            schema_version: "Perttool.NextResult.v4",
+            cli_contract_version: 5,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -1999,7 +2246,9 @@ async function runNext(args) {
             source_digest: input.digest,
             diagnostics: result.diagnostics.map(jsonDiagnostic),
             diagnostics_truncated: result.diagnosticsTruncated,
+            grammar_version: result.grammarVersion,
             ...(result.durationUnit === null ? {} : nextJson(result)),
+            temporal: snakeJson(result.temporal),
         });
     }
     else {
@@ -2023,12 +2272,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 = getGuide(topicId, level);
+    const result = getTargetGovernanceGuide(topicId, level);
     if (format === "json") {
-        process.stdout.write(serializeGuideResult(result));
+        process.stdout.write(serializeTargetGovernanceGuideResult(result));
     }
     else {
-        const rendered = renderGuideResult(result);
+        const rendered = renderTargetGovernanceGuideResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2044,15 +2293,15 @@ function runCommandHelp(args) {
         throw new UsageError("help accepts at most <resource> <action>");
     }
     const format = outputFormat(parsed.values.get("format"));
-    const result = getCommandDiscovery({
+    const result = getTargetGovernanceCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
         action: parsed.positionals[1] ?? null,
     });
     if (format === "json") {
-        process.stdout.write(serializeCommandHelpResult(result));
+        process.stdout.write(serializeTargetGovernanceCommandHelpResult(result));
     }
     else {
-        const rendered = renderCommandHelpResult(result);
+        const rendered = renderTargetGovernanceCommandHelpResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2082,7 +2331,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 3,
+            cli_contract_version: 5,
             ...payload,
         });
     }
@@ -2120,6 +2369,8 @@ async function dispatchCommand(descriptor, args) {
             return runProjectInit(args);
         case "project.show":
             return runProjectShow(args);
+        case "project.migrate-unit":
+            return runUnitMigration(args);
         case "dag.analyze":
             return runAnalyze(args);
         case "dag.next":
@@ -2138,14 +2389,14 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 3 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 5 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {
-        process.stdout.write(serializeCommandUsageError(error));
+        process.stdout.write(serializeTargetGovernanceCommandUsageError(error));
     }
     else {
-        process.stderr.write(renderCommandUsageError(error));
+        process.stderr.write(renderTargetGovernanceCommandUsageError(error));
     }
     return 2;
 }
@@ -2157,13 +2408,13 @@ async function main(argv) {
     if (argv.length === 1 && argv[0] === "--help") {
         return runCommandHelp([]);
     }
-    const validation = validateCommandInvocation(argv);
+    const validation = validateTargetGovernanceCommandInvocation(argv);
     if (!validation.ok) {
         if (jsonRequested(argv)) {
-            process.stdout.write(serializeCommandUsageError(validation.error));
+            process.stdout.write(serializeTargetGovernanceCommandUsageError(validation.error));
         }
         else {
-            process.stderr.write(renderCommandUsageError(validation.error));
+            process.stderr.write(renderTargetGovernanceCommandUsageError(validation.error));
         }
         return 2;
     }