perttool 0.4.0 → 0.5.0

package/dist/cli.js

@@ -2,23 +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 { 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 { 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 { getTargetGovernanceGuide, renderTargetGovernanceGuideResult, serializeTargetGovernanceGuideResult, } from "./help/target-governance-guide.js";
+import { getActualsGuide, renderActualsGuideResult, serializeActualsGuideResult, } from "./help/actuals-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { TARGET_GOVERNANCE_COMMAND_REGISTRY, getTargetGovernanceCommandDiscovery, renderTargetGovernanceCommandHelpResult, serializeTargetGovernanceCommandHelpResult, } from "./command/target-governance-discovery.js";
+import { ACTUALS_COMMAND_REGISTRY, getActualsCommandDiscovery, renderActualsCommandHelpResult, serializeActualsCommandHelpResult, } from "./command/actuals-discovery.js";
 import { handlerCommandUsageError, } from "./command/usage.js";
-import { renderTargetGovernanceCommandUsageError, serializeTargetGovernanceCommandUsageError, validateTargetGovernanceCommandInvocation, } from "./command/target-governance-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";
@@ -27,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 { TARGET_GRAMMAR_4_CAPABILITY, } from "./parser/document-parser.js";
+import { TARGET_GRAMMAR_5_CAPABILITY, } from "./parser/document-parser.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
@@ -82,7 +85,7 @@ function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new S
     return { positionals, values, repeatedValues, flags };
 }
 function parseCommandOptions(operation, args) {
-    const descriptor = TARGET_GOVERNANCE_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}`);
     }
@@ -220,7 +223,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 5,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -255,8 +258,8 @@ async function runCheck(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.CheckResult.v2",
-            cli_contract_version: 5,
+            schema_version: result.schemaVersion,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -268,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 {
@@ -306,7 +315,7 @@ async function runProjectShow(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson(targetGovernanceProjectResultToJson(result, source, input.digest, ok));
+        writeJson(contract6ProjectResultToJson(result, source, input.digest, ok));
     }
     else {
         if (ok && result.project !== null) {
@@ -484,7 +493,7 @@ async function persistGovernedResult(result, request, sourceOperand) {
             written: false,
         });
     }
-    return persistTargetGovernanceResult(result, TARGET_GRAMMAR_4_CAPABILITY, request.mode === "in_place"
+    return persistTargetActualsResult(result, TARGET_GRAMMAR_5_CAPABILITY, request.mode === "in_place"
         ? {
             mode: "in_place",
             target: request.target,
@@ -576,7 +585,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 5,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -620,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
@@ -1074,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>");
@@ -1108,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;
@@ -1123,9 +1169,11 @@ async function runMutation(resource, action, args) {
         updatedLabel: "candidate",
         governance: governanceRequest(parsed, writeRequest),
     };
-    const result = resource === "batch"
-        ? planTargetGovernanceBatchMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, mutationOptions)
-        : planTargetGovernanceMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, 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"));
@@ -1146,7 +1194,7 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1172,6 +1220,94 @@ async function runMutation(resource, action, args) {
     }
     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`);
+        }
+        if (result.diagnosticsTruncated) {
+            process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
+        }
+    }
+    return ok ? 0 : 1;
+}
 function unitMigrationJson(result, source, sourceDigest, ok) {
     const exact = (value) => ({
         numerator: value.numerator.toString(),
@@ -1180,7 +1316,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 5,
+        cli_contract_version: 6,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1308,10 +1444,90 @@ async function runUnitMigration(args) {
     }
     return ok ? 0 : 1;
 }
+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");
@@ -1334,7 +1550,7 @@ async function runAdvance(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.advance", format === "json");
     }
-    const result = planTargetGovernanceAdvance(input.text, TARGET_GRAMMAR_4_CAPABILITY, {
+    const result = planAdvance(input.text, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
@@ -1360,7 +1576,7 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
+        writeJson(contract6MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
     }
     else {
         if (ok && result.advance !== null) {
@@ -1407,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),
@@ -1458,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,
@@ -1566,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
@@ -1646,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)}`);
             }
@@ -1701,8 +1924,8 @@ async function runAnalyze(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.AnalysisResult.v3",
-            cli_contract_version: 5,
+            schema_version: "Perttool.AnalysisResult.v4",
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1712,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
@@ -1816,7 +2044,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 5,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1908,7 +2136,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 5,
+            cli_contract_version: 6,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -1999,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,
@@ -2171,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) {
@@ -2215,7 +2445,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 5,
+                cli_contract_version: 6,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2235,8 +2465,8 @@ async function runNext(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.NextResult.v4",
-            cli_contract_version: 5,
+            schema_version: "Perttool.NextResult.v5",
+            cli_contract_version: 6,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2272,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 = getTargetGovernanceGuide(topicId, level);
+    const result = getActualsGuide(topicId, level);
     if (format === "json") {
-        process.stdout.write(serializeTargetGovernanceGuideResult(result));
+        process.stdout.write(serializeActualsGuideResult(result));
     }
     else {
-        const rendered = renderTargetGovernanceGuideResult(result);
+        const rendered = renderActualsGuideResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2293,15 +2523,15 @@ function runCommandHelp(args) {
         throw new UsageError("help accepts at most <resource> <action>");
     }
     const format = outputFormat(parsed.values.get("format"));
-    const result = getTargetGovernanceCommandDiscovery({
+    const result = getActualsCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
         action: parsed.positionals[1] ?? null,
     });
     if (format === "json") {
-        process.stdout.write(serializeTargetGovernanceCommandHelpResult(result));
+        process.stdout.write(serializeActualsCommandHelpResult(result));
     }
     else {
-        const rendered = renderTargetGovernanceCommandHelpResult(result);
+        const rendered = renderActualsCommandHelpResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2331,7 +2561,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 5,
+            cli_contract_version: 6,
             ...payload,
         });
     }
@@ -2369,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":
@@ -2381,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"
@@ -2389,14 +2629,14 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 5 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 6 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {
-        process.stdout.write(serializeTargetGovernanceCommandUsageError(error));
+        process.stdout.write(serializeActualsCommandUsageError(error));
     }
     else {
-        process.stderr.write(renderTargetGovernanceCommandUsageError(error));
+        process.stderr.write(renderActualsCommandUsageError(error));
     }
     return 2;
 }
@@ -2408,13 +2648,13 @@ async function main(argv) {
     if (argv.length === 1 && argv[0] === "--help") {
         return runCommandHelp([]);
     }
-    const validation = validateTargetGovernanceCommandInvocation(argv);
+    const validation = validateActualsCommandInvocation(argv);
     if (!validation.ok) {
         if (jsonRequested(argv)) {
-            process.stdout.write(serializeTargetGovernanceCommandUsageError(validation.error));
+            process.stdout.write(serializeActualsCommandUsageError(validation.error));
         }
         else {
-            process.stderr.write(renderTargetGovernanceCommandUsageError(validation.error));
+            process.stderr.write(renderActualsCommandUsageError(validation.error));
         }
         return 2;
     }