perttool 0.3.0 → 0.5.0

package/dist/cli.js

@@ -2,20 +2,26 @@
 import { readFile } from "node:fs/promises";
 import process from "node:process";
 import { TextDecoder } from "node:util";
-import { analyzeDocument, selectNextTasks, } from "./application/contract4.js";
+import { analyzeDocument, selectNextTasks, } from "./application/contract6-actuals.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 { 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 { 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 { getGuide, renderGuideResult, serializeGuideResult, } from "./help/guide.js";
+import { getActualsGuide, renderActualsGuideResult, serializeActualsGuideResult, } from "./help/actuals-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { CONTRACT4_COMMAND_REGISTRY, getCommandDiscovery, renderCommandHelpResult, serializeCommandHelpResult, } from "./command/discovery.js";
-import { handlerCommandUsageError, renderCommandUsageError, serializeCommandUsageError, validateCommandInvocation, } from "./command/usage.js";
+import { ACTUALS_COMMAND_REGISTRY, getActualsCommandDiscovery, renderActualsCommandHelpResult, serializeActualsCommandHelpResult, } from "./command/actuals-discovery.js";
+import { handlerCommandUsageError, } from "./command/usage.js";
+import { renderActualsCommandUsageError, serializeActualsCommandUsageError, validateActualsCommandInvocation, } from "./command/actuals-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 +30,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_5_CAPABILITY, } from "./parser/document-parser.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
@@ -79,7 +85,7 @@ function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new S
     return { positionals, values, repeatedValues, flags };
 }
 function parseCommandOptions(operation, args) {
-    const descriptor = CONTRACT4_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
+    const descriptor = ACTUALS_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
     if (descriptor === undefined) {
         throw new Error(`command descriptor is missing for ${operation}`);
     }
@@ -217,7 +223,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -252,8 +258,8 @@ async function runCheck(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.CheckResult.v2",
-            cli_contract_version: 4,
+            schema_version: result.schemaVersion,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -265,6 +271,12 @@ async function runCheck(args) {
             grammar_version: result.grammarVersion,
             summary: result.summary,
             temporal_inputs: snakeJson(result.temporalInputs),
+            actuals_inputs: result.actualsInputs === null
+                ? null
+                : {
+                    model_version: result.actualsInputs.modelVersion,
+                    events: result.actualsInputs.events.map(contract6WorkEventToJson),
+                },
         });
     }
     else {
@@ -280,41 +292,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: snakeJson(project.asOf),
-        duration_unit: project.durationUnit,
-        velocity: project.velocity,
-        finish: project.finish,
-        finish_deadline: snakeJson(project.finishDeadline),
-        critical_epsilon: project.criticalEpsilon,
-        target_duration: project.targetDuration,
-    };
-}
-function renderProjectText(project) {
-    const optional = (value) => value ?? "-";
-    const calendar = (value) => value === null
-        ? "-"
-        : `${value.kind.toUpperCase()} ${value.sourceText ?? "-"}`;
-    return [
-        `PROJECT ${project.id}`,
-        `VERSION ${project.version}`,
-        `TITLE ${JSON.stringify(project.title)}`,
-        `DESCRIPTION ${project.description === null ? "-" : JSON.stringify(project.description)}`,
-        `AS_OF ${calendar(project.asOf)}`,
-        `DURATION_UNIT ${project.durationUnit}`,
-        `VELOCITY ${optional(project.velocity)}`,
-        `FINISH ${project.finish}`,
-        `FINISH_DEADLINE ${calendar(project.finishDeadline)}`,
-        `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) {
@@ -338,24 +315,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.v2",
-            cli_contract_version: 4,
-            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(contract6ProjectResultToJson(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`);
@@ -391,6 +355,22 @@ async function runProjectInit(args) {
             : {
                 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");
@@ -494,6 +474,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 persistTargetActualsResult(result, TARGET_GRAMMAR_5_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 &&
@@ -526,6 +539,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) {
@@ -569,7 +585,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -613,6 +629,11 @@ function requiredOption(parsed, name) {
         throw new UsageError(`option --${name} is required`);
     return value;
 }
+function exactMeasurementToken(value, suffix) {
+    return /^(?:[0-9]+(?:\.[0-9]+)?|[0-9]+\/[1-9][0-9]*)$/.test(value)
+        ? `${value}${suffix}`
+        : value;
+}
 function optionalInteger(parsed, name, minimum, maximum) {
     const raw = parsed.values.get(name);
     return raw === undefined
@@ -637,6 +658,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)) {
@@ -823,6 +850,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")],
@@ -830,6 +861,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) {
@@ -860,6 +895,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",
@@ -1037,6 +1088,7 @@ async function runMutation(resource, action, args) {
     let sourceOperand;
     let writeRequest;
     let mutation;
+    let lifecycleMutation = null;
     if (resource === "batch") {
         if (parsed.positionals.length !== 1) {
             throw new UsageError("batch apply requires exactly one <file>");
@@ -1071,6 +1123,37 @@ async function runMutation(resource, action, args) {
                             : resourceMutationFromOptions(action, parsed);
         sourceOperand = parsed.positionals[0];
         writeRequest = editingWriteRequest(parsed, sourceOperand);
+        if (resource === "task" &&
+            action === "finish" &&
+            parsed.values.has("at")) {
+            lifecycleMutation = {
+                kind: "task.finish.actual",
+                taskId: parsed.positionals[1],
+                event: {
+                    occurredAt: parsed.values.get("at"),
+                    ...(parsed.values.get("event-id") === undefined
+                        ? {}
+                        : { id: parsed.values.get("event-id") }),
+                    ...(parsed.values.get("active-time") === undefined
+                        ? {}
+                        : {
+                            activeTime: exactMeasurementToken(parsed.values.get("active-time"), "h"),
+                        }),
+                    ...(parsed.values.get("effort") === undefined
+                        ? {}
+                        : {
+                            effort: exactMeasurementToken(parsed.values.get("effort"), "ph"),
+                        }),
+                },
+            };
+        }
+        else if (resource === "task" &&
+            action === "finish" &&
+            (parsed.values.has("event-id") ||
+                parsed.values.has("active-time") ||
+                parsed.values.has("effort"))) {
+            throw new UsageError("--event-id, --active-time, and --effort require --at");
+        }
     }
     const source = sourceOperand === "-" ? "<stdin>" : sourceOperand;
     let input;
@@ -1084,20 +1167,26 @@ 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);
+    const result = lifecycleMutation !== null
+        ? planFinishActuals(input.text, lifecycleMutation, mutationOptions)
+        : resource === "batch"
+            ? planBatchMutation(input.text, mutation, mutationOptions)
+            : planMutation(input.text, mutation, 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) {
@@ -1105,24 +1194,12 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 4,
-            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(contract6MutationResultToJson(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 ?? ""));
@@ -1131,6 +1208,97 @@ 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`);
+        }
+        if (result.diagnosticsTruncated) {
+            process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
+        }
+    }
+    return ok ? 0 : 1;
+}
+async function runLifecycleMutation(action, args) {
+    const operation = `task.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    if (parsed.positionals.length !== 2) {
+        throw new UsageError(`task ${action} requires <file> <task-id>`);
+    }
+    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);
+    const event = {
+        occurredAt: requiredOption(parsed, "at"),
+        ...(parsed.values.get("event-id") === undefined
+            ? {}
+            : { id: parsed.values.get("event-id") }),
+        ...(action !== "suspend" || parsed.values.get("reason") === undefined
+            ? {}
+            : { reason: parsed.values.get("reason") }),
+    };
+    const mutation = action === "start"
+        ? { kind: "task.start", taskId: parsed.positionals[1], event }
+        : action === "suspend"
+            ? { kind: "task.suspend", taskId: parsed.positionals[1], event }
+            : { kind: "task.resume", taskId: parsed.positionals[1], event };
+    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 = planLifecycle(input.text, mutation, {
+        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 = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
+    if (result.ok && ok && writeRequest.mode !== "preview") {
+        try {
+            writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
+        }
+        catch (error) {
+            return writeFailureExit(error, operation, format === "json");
+        }
+    }
+    if (format === "json") {
+        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+    }
+    else {
+        if (ok) {
+            if (writeRequest.mode !== "preview") {
+                process.stderr.write(renderGovernanceWriteSummary(operation, writeResult, result.updatedDigest));
+            }
+            else {
+                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`);
+                }
+            }
+        }
+        if (result.lifecycle !== null) {
+            process.stderr.write(`LIFECYCLE task=${result.lifecycle.taskId} from=${result.lifecycle.fromState} to=${result.lifecycle.toState} event=${result.lifecycle.event.id} coverage=${result.lifecycle.coverage}\n`);
+        }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
@@ -1148,7 +1316,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 4,
+        cli_contract_version: 6,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1276,23 +1444,90 @@ async function runUnitMigration(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,
-        };
+async function readHistoryForCommand(operation, parsed, format) {
+    if (parsed.positionals.length !== 1) {
+        throw new UsageError(`${operation.replace(".", " ")} requires exactly one <file>`);
+    }
+    const source = parsed.positionals[0];
+    if (source === "-") {
+        throw new UsageError(`${operation.replace(".", " ")} requires an on-disk file`);
+    }
+    try {
+        return await inspectTargetProjectHistoryFile({
+            targetPath: source,
+            ...(parsed.values.get("rev") === undefined
+                ? {}
+                : { revision: parsed.values.get("rev") }),
+            ...(parsed.repeatedValues.get("task") === undefined
+                ? {}
+                : { taskIds: parsed.repeatedValues.get("task") }),
+        }, TARGET_GRAMMAR_5_CAPABILITY);
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+}
+async function runProjectHistory(args) {
+    const parsed = parseCommandOptions("project.history", args);
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const result = await readHistoryForCommand("project.history", parsed, format);
+    if (result instanceof Error) {
+        return cliError(result, 3, "project.history", format === "json");
+    }
+    const warningFailure = parsed.flags.has("warnings-as-errors") &&
+        result.diagnostics.some((diagnostic) => diagnostic.severity === "warning");
+    const ok = result.ok && !warningFailure;
+    if (format === "json") {
+        writeJson(targetProjectHistoryResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), parsed.positionals[0]));
+    }
+    else {
+        if (ok)
+            process.stdout.write(renderTargetProjectHistoryText(result));
+        for (const diagnostic of result.diagnostics) {
+            process.stderr.write(`${renderDiagnostic(diagnostic, parsed.positionals[0], color)}\n`);
+        }
+    }
+    return ok ? 0 : 1;
+}
+async function runProjectVelocityObservation(args) {
+    const parsed = parseCommandOptions("project.observe-velocity", args);
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const history = await readHistoryForCommand("project.observe-velocity", parsed, format);
+    if (history instanceof Error) {
+        return cliError(history, 3, "project.observe-velocity", format === "json");
+    }
+    const evidenceValue = parsed.values.get("evidence") ?? "declared";
+    const evidence = evidenceValue === "git-recorded"
+        ? "git_recorded"
+        : evidenceValue;
+    const result = observeTargetProjectVelocity(history, {
+        ...(parsed.repeatedValues.get("task") === undefined
+            ? {}
+            : { taskIds: parsed.repeatedValues.get("task") }),
+        evidence,
+    });
+    const warningFailure = parsed.flags.has("warnings-as-errors") &&
+        result.diagnostics.some((diagnostic) => diagnostic.severity === "warning");
+    const ok = result.ok && !warningFailure;
+    if (format === "json") {
+        writeJson(targetVelocityObservationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), parsed.positionals[0]));
+    }
+    else {
+        if (ok) {
+            process.stdout.write(renderTargetVelocityObservationText(result));
+        }
+        for (const diagnostic of result.diagnostics) {
+            process.stderr.write(`${renderDiagnostic(diagnostic, parsed.positionals[0], color)}\n`);
+        }
+    }
+    return ok ? 0 : 1;
 }
 function renderAdvanceSummary(details) {
     const list = (ids) => ids.join(",") || "-";
     return [
-        `ADVANCE removed_tasks=${list(details.removedTaskIds)} removed_gates=${list(details.removedGateIds)} removed_milestones=${list(details.removedMilestoneIds)}`,
+        `ADVANCE removed_tasks=${list(details.removedTaskIds)} removed_gates=${list(details.removedGateIds)} removed_milestones=${list(details.removedMilestoneIds)} removed_work_events=${list("removedWorkEventIds" in details ? details.removedWorkEventIds : [])}`,
         `ADVANCE frontier_before=${list(details.frontierBefore)} frontier_after=${list(details.frontierAfter)} ready_before=${list(details.readyBefore)} ready_after=${list(details.readyAfter)}`,
         "",
     ].join("\n");
@@ -1319,17 +1554,21 @@ async function runAdvance(args) {
         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) {
@@ -1337,25 +1576,12 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 4,
-            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(contract6MutationResultToJson(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 ?? ""));
@@ -1365,6 +1591,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`);
         }
@@ -1394,6 +1623,8 @@ function precedenceJson(result, unit, precision) {
         makespan: rationalJson(result.makespan, unit, precision),
         conditional_on_blocks_resolved: result.conditionalOnBlocksResolved,
         blocked_task_ids: result.blockedTaskIds,
+        conditional_on_suspensions_resumed: result.conditionalOnSuspensionsResumed,
+        suspended_task_ids: result.suspendedTaskIds,
         milestones: result.milestones.map((milestone) => ({
             id: milestone.id,
             earliest: rationalJson(milestone.earliest, unit, precision),
@@ -1445,6 +1676,8 @@ function resourceJson(result, unit, precision) {
         algorithm: result.algorithm,
         conditional_on_blocks_resolved: result.conditionalOnBlocksResolved,
         blocked_task_ids: result.blockedTaskIds,
+        conditional_on_suspensions_resumed: result.conditionalOnSuspensionsResumed,
+        suspended_task_ids: result.suspendedTaskIds,
         capacities: result.capacities.map((capacity) => ({
             id: capacity.id,
             declared: capacity.declared,
@@ -1553,11 +1786,14 @@ function renderAnalysisText(result) {
     const conditional = result.precedence?.conditionalOnBlocksResolved === true ||
         result.resource?.conditionalOnBlocksResolved === true;
     const blockedTaskIds = result.precedence?.blockedTaskIds ?? result.resource?.blockedTaskIds ?? [];
+    const suspendedTaskIds = result.precedence?.suspendedTaskIds ??
+        result.resource?.suspendedTaskIds ??
+        [];
     const pathsTruncated = result.precedence?.critical.pathsTruncated === true ||
         result.resource?.scheduleCritical.pathsTruncated === true;
     const overrides = [...result.capacityOverrides]
         .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
-    lines.push(`CONDITIONAL_ON_BLOCKS_RESOLVED ${conditional}`, `BLOCKED_TASKS ${blockedTaskIds.join(", ") || "-"}`, `PATHS_TRUNCATED ${pathsTruncated}`, `CAPACITY_OVERRIDES ${overrides.map(([id, capacity]) => `${id}=${capacity}`).join(", ") || "-"}`, `VELOCITY ${result.velocity === null ? "-" : velocityText(result.velocity, result.precision)}`, `VELOCITY_FORECAST_UNIT ${result.velocityForecast?.targetUnit ?? "-"}`);
+    lines.push(`CONDITIONAL_ON_BLOCKS_RESOLVED ${conditional}`, `BLOCKED_TASKS ${blockedTaskIds.join(", ") || "-"}`, `CONDITIONAL_ON_SUSPENSIONS_RESUMED ${suspendedTaskIds.length > 0}`, `SUSPENDED_TASKS ${suspendedTaskIds.join(", ") || "-"}`, `PATHS_TRUNCATED ${pathsTruncated}`, `CAPACITY_OVERRIDES ${overrides.map(([id, capacity]) => `${id}=${capacity}`).join(", ") || "-"}`, `VELOCITY ${result.velocity === null ? "-" : velocityText(result.velocity, result.precision)}`, `VELOCITY_FORECAST_UNIT ${result.velocityForecast?.targetUnit ?? "-"}`);
     if (result.precedence !== null) {
         const precedence = result.precedence;
         lines.push("", "PRECEDENCE", `MAKESPAN ${durationText(precedence.makespan, unit, result.precision)}`, ...(result.velocityForecast === null
@@ -1633,7 +1869,7 @@ function renderAnalysisText(result) {
             ["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(",") || "-"}`);
+            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(",") || "-"}`, `CONDITIONAL_ON_SUSPENSIONS_RESUMED ${projection.conditionalOnSuspensionsResumed}`, `SUSPENDED_TASKS ${projection.suspendedTaskIds.join(",") || "-"}`);
             for (const task of projection.tasks) {
                 lines.push(`${task.taskId} START ${temporalPoint(task.start)} FINISH ${temporalPoint(task.finish)}`);
             }
@@ -1688,8 +1924,8 @@ async function runAnalyze(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.AnalysisResult.v3",
-            cli_contract_version: 4,
+            schema_version: "Perttool.AnalysisResult.v4",
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1699,6 +1935,11 @@ async function runAnalyze(args) {
             diagnostics: result.diagnostics.map(jsonDiagnostic),
             diagnostics_truncated: result.diagnosticsTruncated,
             grammar_version: result.grammarVersion,
+            task_actuals: result.taskActuals.map((actuals) => ({
+                task_id: actuals.taskId,
+                status: actuals.status,
+                coverage: actuals.coverage,
+            })),
             mode: result.mode,
             precision: result.precision,
             ...(result.durationUnit === null
@@ -1803,7 +2044,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1895,7 +2136,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -1986,6 +2227,7 @@ function nextJson(result) {
             runnable_now: result.groups.runnableNow,
             blocked_now: result.groups.blockedNow,
             upcoming: result.groups.upcoming,
+            suspended: result.groups.suspended,
         },
         tasks: result.tasks.map((task) => ({
             id: task.id,
@@ -2158,6 +2400,7 @@ function renderNextText(result) {
     section("RUNNABLE NOW", result.groups.runnableNow);
     section("READY / WAITING RESOURCE", result.groups.ready.filter((id) => !result.groups.runnableNow.includes(id)), "rejection");
     section("BLOCKED NOW", result.groups.blockedNow, "blocked");
+    section("SUSPENDED", result.groups.suspended);
     section("UPCOMING", result.groups.upcoming, "explanation");
     lines.push("", "TEMPORAL CONTEXT");
     for (const temporal of result.temporal.tasks) {
@@ -2202,7 +2445,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 4,
+                cli_contract_version: 6,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2222,8 +2465,8 @@ async function runNext(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.NextResult.v4",
-            cli_contract_version: 4,
+            schema_version: "Perttool.NextResult.v5",
+            cli_contract_version: 6,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2259,12 +2502,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 = getActualsGuide(topicId, level);
     if (format === "json") {
-        process.stdout.write(serializeGuideResult(result));
+        process.stdout.write(serializeActualsGuideResult(result));
     }
     else {
-        const rendered = renderGuideResult(result);
+        const rendered = renderActualsGuideResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2280,15 +2523,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 = getActualsCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
         action: parsed.positionals[1] ?? null,
     });
     if (format === "json") {
-        process.stdout.write(serializeCommandHelpResult(result));
+        process.stdout.write(serializeActualsCommandHelpResult(result));
     }
     else {
-        const rendered = renderCommandHelpResult(result);
+        const rendered = renderActualsCommandHelpResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2318,7 +2561,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 4,
+            cli_contract_version: 6,
             ...payload,
         });
     }
@@ -2356,6 +2599,10 @@ async function dispatchCommand(descriptor, args) {
             return runProjectInit(args);
         case "project.show":
             return runProjectShow(args);
+        case "project.history":
+            return runProjectHistory(args);
+        case "project.observe-velocity":
+            return runProjectVelocityObservation(args);
         case "project.migrate-unit":
             return runUnitMigration(args);
         case "dag.analyze":
@@ -2368,6 +2615,12 @@ async function dispatchCommand(descriptor, args) {
             return runRender(args);
         case "dag.import":
             return runImport(args);
+        case "task.start":
+            return runLifecycleMutation("start", args);
+        case "task.suspend":
+            return runLifecycleMutation("suspend", args);
+        case "task.resume":
+            return runLifecycleMutation("resume", args);
     }
     if (descriptor.path.length === 2
         && (descriptor.operation === "project.set"
@@ -2376,14 +2629,14 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 4 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 6 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {
-        process.stdout.write(serializeCommandUsageError(error));
+        process.stdout.write(serializeActualsCommandUsageError(error));
     }
     else {
-        process.stderr.write(renderCommandUsageError(error));
+        process.stderr.write(renderActualsCommandUsageError(error));
     }
     return 2;
 }
@@ -2395,13 +2648,13 @@ async function main(argv) {
     if (argv.length === 1 && argv[0] === "--help") {
         return runCommandHelp([]);
     }
-    const validation = validateCommandInvocation(argv);
+    const validation = validateActualsCommandInvocation(argv);
     if (!validation.ok) {
         if (jsonRequested(argv)) {
-            process.stdout.write(serializeCommandUsageError(validation.error));
+            process.stdout.write(serializeActualsCommandUsageError(validation.error));
         }
         else {
-            process.stderr.write(renderCommandUsageError(validation.error));
+            process.stderr.write(renderActualsCommandUsageError(validation.error));
         }
         return 2;
     }