perttool 0.1.0 → 0.3.0

package/dist/cli.js

@@ -2,17 +2,21 @@
 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 { getAgentHelp } from "./application/agent-help.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getAgentHelpCommandHelp, getHelp, } from "./help/registry.js";
-import { serializeAgentGuidanceResult } from "./guidance/projection.js";
+import { getGuide, renderGuideResult, serializeGuideResult, } from "./help/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 { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { documentContentFromBytes, readDocumentFile, } from "./io/document-file.js";
 import { createArtifactFile, createDocumentFile, replaceDocumentFile, SafeWriteConflictError, SafeWriteVerificationError, } from "./io/safe-write.js";
@@ -25,183 +29,6 @@ import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
 }
-function topLevelHelp() {
-    return [
-        "perttool - document-based PERT/CPM task management",
-        "",
-        "Usage:",
-        "  perttool --version",
-        "  perttool --help",
-        "  perttool dsl check <file> [--format text|json]",
-        "  perttool dsl format <file> [--check] [--diff] [--format text|json]",
-        "  perttool dsl help [topic [subtopic]] [--level index|quick|detail] [--format text|json]",
-        "  perttool agent help [provider [surface]] [--level index|quick|detail] [--format text|json]",
-        "  perttool project show <file> [--format text|json]",
-        "  perttool project set <file> [field options] [--diff] [--write | --out <path>]",
-        "  perttool dag analyze <file> [--schedule precedence|resource|both] [--format text|json]",
-        "  perttool dag next <file> [--capacity <resource-id>=<integer>] [--format text|json]",
-        "  perttool dag advance <file> [--diff] [--write | --out <path>] [--format text|json]",
-        "  perttool dag render <file> --to mermaid [--profile perttool|plain] [--format text|json]",
-        "  perttool dag import <file> --from mermaid [--strict-loss] [--out <path>] [--format text|json]",
-        "  perttool task add|set|remove|finish ...",
-        "  perttool milestone add|set|remove ...",
-        "  perttool resource add|set|remove ...",
-        "  perttool mutation apply <file> --request <json-file|-> [--diff] [--format text|json]",
-        "",
-        "Format and mutation commands preview by default; use --write or --out for explicit writes.",
-    ].join("\n");
-}
-function commandHelp(resource, action) {
-    if (resource === "agent" && action === "help") {
-        return getAgentHelpCommandHelp().syntax.join("\n");
-    }
-    if (resource === "dsl" && action === "check") {
-        return [
-            "Usage: perttool dsl check <file>",
-            "  [--warnings-as-errors]",
-            "  [--max-diagnostics <integer>]",
-            "  [--format text|json]",
-            "  [--color auto|always|never]",
-        ].join("\n");
-    }
-    if (resource === "dsl" && action === "format")
-        return [
-            "Usage: perttool dsl format <file>",
-            "  [--check] [--diff]",
-            "  [--write [--expect-digest <digest>] | --out <path>]",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "dsl" && action === "help")
-        return [
-            "Usage: perttool dsl help [topic [subtopic]]",
-            "  [--level index|quick|detail]",
-            "  [--format text|json]",
-            "  [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "project" && action === "show")
-        return [
-            "Usage: perttool project show <file>",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "project" && action === "set")
-        return [
-            "Usage: perttool project set <file> [field options]",
-            "  [--id <id>] [--version <integer>] [--title <text>] [--description <text>]",
-            "  [--as-of <date-or-date-time>] [--duration-unit day|hour|point]",
-            "  [--velocity <velocity>] [--finish <milestone-id>]",
-            "  [--critical-epsilon <duration>] [--target-duration <duration>]",
-            "  [--clear description|as_of|velocity|critical_epsilon|target_duration]...",
-            "  [--diff] [--write [--expect-digest <digest>] | --out <path>]",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "dag" && action === "analyze")
-        return [
-            "Usage: perttool dag analyze <file>",
-            "  [--schedule precedence|resource|both]",
-            "  [--capacity <resource-id>=<integer>]...",
-            "  [--max-paths <integer>] [--precision <integer>]",
-            "  [--max-diagnostics <integer>]",
-            "  [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "dag" && action === "next")
-        return [
-            "Usage: perttool dag next <file>",
-            "  [--capacity <resource-id>=<integer>]...",
-            "  [--explain-depth <integer>] [--precision <integer>]",
-            "  [--max-diagnostics <integer>]",
-            "  [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-            "Output: Perttool.NextResult.v3 with a complete recommendation graph in JSON.",
-            "Consumers must inspect schema_version before using recommendation authority.",
-        ].join("\n");
-    if (resource === "dag" && action === "advance")
-        return [
-            "Usage: perttool dag advance <file>",
-            "  [--diff] [--write [--expect-digest <digest>] | --out <path>]",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "dag" && action === "render")
-        return [
-            "Usage: perttool dag render <file> --to mermaid",
-            "  [--profile perttool|plain] [--analysis none|precedence|resource|both]",
-            "  [--capacity <resource-id>=<integer>]... [--strict-loss] [--out <path>]",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    if (resource === "dag" && action === "import")
-        return [
-            "Usage: perttool dag import <file> --from mermaid",
-            "  [--strict-loss] [--out <path>]",
-            "  [--max-diagnostics <integer>] [--warnings-as-errors]",
-            "  [--format text|json] [--color auto|always|never]",
-        ].join("\n");
-    const preview = "  [--diff] [--write [--expect-digest <digest>] | --out <path>] [--max-diagnostics <integer>] [--warnings-as-errors] [--format text|json] [--color auto|always|never]";
-    if (resource === "task" && action === "add")
-        return [
-            "Usage: perttool task add <file> <id> <from> <to>",
-            "  --title <text> (--duration <duration> | --optimistic <duration> --most-likely <duration> --pessimistic <duration>)",
-            "  [--description <text>] [--status planned|active|blocked|done] [--priority <integer>]",
-            "  [--owner <text>] [--blocked-reason <text>] [--source <text>] [--tag <tag>]... [--require <resource-id>=<integer>]...",
-            preview,
-        ].join("\n");
-    if (resource === "task" && action === "set")
-        return [
-            "Usage: perttool task set <file> <id> [field options]",
-            "  [--from <id>] [--to <id>] [--title <text>] [--description <text>] [--duration <duration>]",
-            "  [--optimistic <duration> --most-likely <duration> --pessimistic <duration>]",
-            "  [--status planned|active|blocked|done] [--priority <integer>] [--owner <text>]",
-            "  [--blocked-reason <text>] [--source <text>] [--require <resource-id>=<integer>]...",
-            "  [--add-tag <tag>]... [--remove-tag <tag>]... [--remove-require <resource-id>]... [--clear <field>]...",
-            preview,
-        ].join("\n");
-    if (resource === "task")
-        return [
-            `Usage: perttool task ${action} <file> <id>`,
-            preview,
-        ].join("\n");
-    if (resource === "milestone" && action === "add")
-        return [
-            "Usage: perttool milestone add <file> <id> --title <text>",
-            "  [--description <text>] [--state planned|reached] [--tag <tag>]...",
-            preview,
-        ].join("\n");
-    if (resource === "milestone" && action === "set")
-        return [
-            "Usage: perttool milestone set <file> <id> [--title <text>] [--description <text>] [--state planned|reached]",
-            "  [--add-tag <tag>]... [--remove-tag <tag>]... [--clear description|state|tags]...",
-            preview,
-        ].join("\n");
-    if (resource === "milestone")
-        return [
-            `Usage: perttool milestone ${action} <file> <id>`,
-            preview,
-        ].join("\n");
-    if (resource === "resource" && action === "add")
-        return [
-            "Usage: perttool resource add <file> <id> --title <text> --capacity <integer>",
-            "  [--description <text>]",
-            preview,
-        ].join("\n");
-    if (resource === "resource" && action === "set")
-        return [
-            "Usage: perttool resource set <file> <id> [--title <text>] [--description <text>] [--capacity <integer>] [--clear description]",
-            preview,
-        ].join("\n");
-    if (resource === "resource")
-        return [
-            `Usage: perttool resource ${action} <file> <id>`,
-            preview,
-        ].join("\n");
-    return [
-        "Usage: perttool mutation apply <file> --request <json-file|->",
-        preview,
-    ].join("\n");
-}
 function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new Set()) {
     const positionals = [];
     const values = new Map();
@@ -251,6 +78,14 @@ 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);
+    if (descriptor === undefined) {
+        throw new Error(`command descriptor is missing for ${operation}`);
+    }
+    const optionSets = commandOptionSets(descriptor);
+    return parseOptions(args, optionSets.values, optionSets.flags, optionSets.repeatable);
+}
 function outputFormat(value) {
     if (value === undefined || value === "text")
         return "text";
@@ -300,7 +135,8 @@ function jsonDiagnostic(diagnostic) {
             message: related.message,
             span: jsonSpan(related.span),
         })),
-        help_topic: diagnostic.helpTopic ?? null,
+        help_topic: null,
+        guide_topic: diagnostic.helpTopic ?? null,
         expected_syntax: diagnostic.expectedSyntax ?? null,
         fixes: [],
         data: diagnostic.data ?? {},
@@ -326,7 +162,7 @@ function renderDiagnostic(diagnostic, source, mode) {
     }
     if (diagnostic.helpTopic !== undefined) {
         const [topic, subtopic] = diagnostic.helpTopic.split(".", 2);
-        lines.push(`  help: perttool dsl help ${topic}${subtopic === undefined ? "" : ` ${subtopic}`} --level quick`);
+        lines.push(`  guide: perttool guide ${topic}${subtopic === undefined ? "" : ` ${subtopic}`} --level quick`);
     }
     return lines.join("\n");
 }
@@ -346,6 +182,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
@@ -369,6 +217,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -381,9 +230,9 @@ function cliError(error, exitCode, operation, json) {
     return exitCode;
 }
 async function runCheck(args) {
-    const parsed = parseOptions(args, new Set(["format", "color", "max-diagnostics"]), new Set(["warnings-as-errors"]));
+    const parsed = parseCommandOptions("document.check", args);
     if (parsed.positionals.length !== 1) {
-        throw new UsageError("dsl check requires exactly one <file>");
+        throw new UsageError("document check requires exactly one <file>");
     }
     const format = outputFormat(parsed.values.get("format"));
     const color = colorMode(parsed.values.get("color"), format);
@@ -395,7 +244,7 @@ async function runCheck(args) {
         input = await readDocument(sourceOperand);
     }
     catch (error) {
-        return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dsl.check", format === "json");
+        return cliError(error instanceof Error ? error : new Error(String(error)), 3, "document.check", format === "json");
     }
     const result = checkDocument(input.text, { maxDiagnostics });
     const warningsAsErrors = parsed.flags.has("warnings-as-errors");
@@ -403,9 +252,10 @@ async function runCheck(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.CheckResult.v1",
+            schema_version: "Perttool.CheckResult.v2",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
-            operation: "dsl.check",
+            operation: "document.check",
             ok,
             document_id: result.documentId,
             source,
@@ -414,11 +264,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`);
@@ -435,32 +286,37 @@ function projectJson(project) {
         version: project.version,
         title: project.title,
         description: project.description,
-        as_of: project.asOf,
+        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 ${optional(project.asOf)}`,
+        `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 = parseOptions(args, new Set(["format", "color", "max-diagnostics"]), new Set(["warnings-as-errors"]));
+    const parsed = parseCommandOptions("project.show", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("project show requires exactly one <file>");
     }
@@ -483,7 +339,8 @@ async function runProjectShow(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.ProjectResult.v1",
+            schema_version: "Perttool.ProjectResult.v2",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
             operation: "project.show",
             ok,
@@ -509,6 +366,61 @@ async function runProjectShow(args) {
     }
     return ok ? 0 : 1;
 }
+async function runProjectInit(args) {
+    const parsed = parseCommandOptions("project.init", args);
+    const format = outputFormat(parsed.values.get("format"));
+    const color = colorMode(parsed.values.get("color"), format);
+    const durationUnit = enumOption(requiredOption(parsed, "duration-unit"), "duration-unit", new Set(["day", "hour", "point"]));
+    const version = optionalInteger(parsed, "version", 0, 2_147_483_647);
+    let result = planProjectInit({
+        projectId: parsed.positionals[0],
+        title: requiredOption(parsed, "title"),
+        durationUnit,
+        initialMilestone: requiredOption(parsed, "initial-milestone"),
+        initialMilestoneTitle: requiredOption(parsed, "initial-milestone-title"),
+        finish: requiredOption(parsed, "finish"),
+        ...(version === undefined ? {} : { version }),
+        ...(parsed.values.get("as-of") === undefined
+            ? {}
+            : { asOf: parsed.values.get("as-of") }),
+        ...(parsed.values.get("velocity") === undefined
+            ? {}
+            : { velocity: parsed.values.get("velocity") }),
+        ...(parsed.values.get("initial-milestone-deadline") === undefined
+            ? {}
+            : {
+                initialMilestoneDeadline: parsed.values.get("initial-milestone-deadline"),
+            }),
+    });
+    let writeResult = null;
+    const output = parsed.values.get("out");
+    if (result.ok && output !== undefined) {
+        try {
+            writeResult = await createDocumentFile(output, result.candidateText);
+            result = withProjectInitOutput(result, writeResult);
+        }
+        catch (error) {
+            return writeFailureExit(error, "project.init", format === "json");
+        }
+    }
+    if (format === "json") {
+        writeJson(projectInitResultToJson(result));
+    }
+    else {
+        if (result.ok) {
+            if (writeResult === null) {
+                process.stdout.write(renderProjectInitResult(result));
+            }
+            else {
+                process.stderr.write(renderWriteSummary("project.init", writeResult));
+            }
+        }
+        for (const diagnostic of result.diagnostics) {
+            process.stderr.write(`${renderDiagnostic(diagnostic, "<project-init>", color)}\n`);
+        }
+    }
+    return result.ok ? 0 : 1;
+}
 function boundedInteger(raw, option, defaultValue, minimum, maximum) {
     if (raw === undefined)
         return defaultValue;
@@ -546,14 +458,6 @@ function capacityOverrides(values) {
     }
     return overrides;
 }
-const mutationCommonValueOptions = [
-    "format",
-    "color",
-    "max-diagnostics",
-    "out",
-    "expect-digest",
-];
-const mutationCommonFlagOptions = ["diff", "write", "warnings-as-errors"];
 function editingWriteRequest(parsed, sourceOperand, check = false) {
     const write = parsed.flags.has("write");
     const out = parsed.values.get("out");
@@ -594,12 +498,12 @@ function assertExpectedDigest(request, initialDigest) {
     if (request.mode === "in_place" &&
         request.expectedDigest !== undefined &&
         request.expectedDigest !== initialDigest) {
-        throw new SafeWriteConflictError("expected_digest_mismatch", "--expect-digestがinitial document digestと一致しません");
+        throw new SafeWriteConflictError("expected_digest_mismatch", "--expect-digest does not match the initial document digest");
     }
 }
 async function commitCandidate(request, candidateText, initialDigest) {
     if (candidateText === null) {
-        throw new SafeWriteVerificationError("invalid_candidate", "successful editing resultにcandidate textがありません");
+        throw new SafeWriteVerificationError("invalid_candidate", "successful editing result has no candidate text");
     }
     return request.mode === "in_place"
         ? replaceDocumentFile(request.target, candidateText, {
@@ -623,9 +527,9 @@ function renderWriteSummary(operation, result) {
     return `WRITE ${operation} mode=${result.mode} target=${result.target} digest=${result.digest} written=${result.written}\n`;
 }
 async function runFormat(args) {
-    const parsed = parseOptions(args, new Set(["format", "color", "max-diagnostics", "out", "expect-digest"]), new Set(["check", "diff", "write", "warnings-as-errors"]));
+    const parsed = parseCommandOptions("document.format", args);
     if (parsed.positionals.length !== 1) {
-        throw new UsageError("dsl format requires exactly one <file>");
+        throw new UsageError("document format requires exactly one <file>");
     }
     const format = outputFormat(parsed.values.get("format"));
     const color = colorMode(parsed.values.get("color"), format);
@@ -638,7 +542,7 @@ async function runFormat(args) {
         input = await readDocument(sourceOperand);
     }
     catch (error) {
-        return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dsl.format", format === "json");
+        return cliError(error instanceof Error ? error : new Error(String(error)), 3, "document.format", format === "json");
     }
     const result = planFormat(input.text, {
         maxDiagnostics,
@@ -659,14 +563,15 @@ async function runFormat(args) {
             }
         }
         catch (error) {
-            return writeFailureExit(error, "dsl.format", format === "json");
+            return writeFailureExit(error, "document.format", format === "json");
         }
     }
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
-            operation: "dsl.format",
+            operation: "document.format",
             ok,
             document_id: result.documentId,
             source,
@@ -680,7 +585,7 @@ async function runFormat(args) {
         const candidateAllowed = result.ok && !warningFailure;
         if (candidateAllowed) {
             if (writeResult !== null) {
-                process.stderr.write(renderWriteSummary("dsl.format", writeResult));
+                process.stderr.write(renderWriteSummary("document.format", writeResult));
             }
             else if (parsed.flags.has("check")) {
                 if (parsed.flags.has("diff"))
@@ -689,7 +594,7 @@ async function runFormat(args) {
             else {
                 process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
                 if (!parsed.flags.has("diff")) {
-                    process.stderr.write(`PREVIEW dsl.format changed=${result.changed} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest}\n`);
+                    process.stderr.write(`PREVIEW document.format changed=${result.changed} original_digest=${result.originalDigest} updated_digest=${result.updatedDigest}\n`);
                 }
             }
         }
@@ -702,50 +607,6 @@ async function runFormat(args) {
     }
     return ok ? 0 : 1;
 }
-function mutationOptionSets(resource, action) {
-    const values = new Set(mutationCommonValueOptions);
-    const flags = new Set(mutationCommonFlagOptions);
-    const repeatable = new Set();
-    const addValues = (...names) => {
-        for (const name of names)
-            values.add(name);
-    };
-    const addRepeatable = (...names) => {
-        for (const name of names)
-            repeatable.add(name);
-    };
-    if (resource === "project" && action === "set") {
-        addValues("id", "version", "title", "description", "as-of", "duration-unit", "velocity", "finish", "critical-epsilon", "target-duration");
-        addRepeatable("clear");
-    }
-    else if (resource === "task" && action === "add") {
-        addValues("title", "description", "duration", "optimistic", "most-likely", "pessimistic", "status", "priority", "owner", "blocked-reason", "source");
-        addRepeatable("tag", "require");
-    }
-    else if (resource === "task" && action === "set") {
-        addValues("from", "to", "title", "description", "duration", "optimistic", "most-likely", "pessimistic", "status", "priority", "owner", "blocked-reason", "source");
-        addRepeatable("require", "add-tag", "remove-tag", "remove-require", "clear");
-    }
-    else if (resource === "milestone" && action === "add") {
-        addValues("title", "description", "state");
-        addRepeatable("tag");
-    }
-    else if (resource === "milestone" && action === "set") {
-        addValues("title", "description", "state");
-        addRepeatable("add-tag", "remove-tag", "clear");
-    }
-    else if (resource === "resource" && action === "add") {
-        addValues("title", "description", "capacity");
-    }
-    else if (resource === "resource" && action === "set") {
-        addValues("title", "description", "capacity");
-        addRepeatable("clear");
-    }
-    else if (resource === "mutation" && action === "apply") {
-        addValues("request");
-    }
-    return { values, flags, repeatable };
-}
 function requiredOption(parsed, name) {
     const value = parsed.values.get(name);
     if (value === undefined)
@@ -862,6 +723,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 }),
@@ -882,7 +749,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");
@@ -897,6 +764,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
@@ -911,6 +784,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")],
@@ -1010,18 +885,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");
     }
@@ -1033,6 +912,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",
@@ -1086,6 +968,37 @@ function resourceMutationFromOptions(action, parsed) {
         ...(clear.length === 0 ? {} : { clear }),
     };
 }
+function gateMutationFromOptions(action, parsed) {
+    const expectedPositionals = action === "add" ? 4 : 2;
+    if (parsed.positionals.length !== expectedPositionals) {
+        throw new UsageError(`gate ${action} requires ${action === "add" ? "<file> <id> <from> <to>" : "<file> <id>"}`);
+    }
+    const id = parsed.positionals[1];
+    if (action === "remove")
+        return { kind: "gate.remove", id };
+    if (action === "add") {
+        return {
+            kind: "gate.add",
+            id,
+            from: parsed.positionals[2],
+            to: parsed.positionals[3],
+            gate: { reason: requiredOption(parsed, "reason") },
+        };
+    }
+    const from = parsed.values.get("from");
+    const to = parsed.values.get("to");
+    const reason = parsed.values.get("reason");
+    if (from === undefined && to === undefined && reason === undefined) {
+        throw new UsageError("gate set requires --from, --to, or --reason");
+    }
+    return {
+        kind: "gate.set",
+        id,
+        ...(from === undefined ? {} : { from }),
+        ...(to === undefined ? {} : { to }),
+        ...(reason === undefined ? {} : { set: { reason } }),
+    };
+}
 function previewResultJson(result, exposeCandidate, writeRequest = { mode: "preview", target: null }, writeResult = null) {
     return {
         changed: exposeCandidate ? result.changed : false,
@@ -1116,8 +1029,7 @@ async function readMutationRequest(source) {
     }
 }
 async function runMutation(resource, action, args) {
-    const config = mutationOptionSets(resource, action);
-    const parsed = parseOptions(args, config.values, config.flags, config.repeatable);
+    const parsed = parseCommandOptions(`${resource}.${action}`, args);
     const format = outputFormat(parsed.values.get("format"));
     const color = colorMode(parsed.values.get("color"), format);
     const maxDiagnostics = boundedInteger(parsed.values.get("max-diagnostics"), "max-diagnostics", 100, 1, 1000);
@@ -1125,9 +1037,9 @@ async function runMutation(resource, action, args) {
     let sourceOperand;
     let writeRequest;
     let mutation;
-    if (resource === "mutation") {
+    if (resource === "batch") {
         if (parsed.positionals.length !== 1) {
-            throw new UsageError("mutation apply requires exactly one <file>");
+            throw new UsageError("batch apply requires exactly one <file>");
         }
         sourceOperand = parsed.positionals[0];
         writeRequest = editingWriteRequest(parsed, sourceOperand);
@@ -1152,9 +1064,11 @@ async function runMutation(resource, action, args) {
                 ? projectMutationFromOptions(parsed)
                 : resource === "task"
                     ? taskMutationFromOptions(action, parsed)
-                    : resource === "milestone"
-                        ? milestoneMutationFromOptions(action, parsed)
-                        : resourceMutationFromOptions(action, parsed);
+                    : resource === "gate"
+                        ? gateMutationFromOptions(action, parsed)
+                        : resource === "milestone"
+                            ? milestoneMutationFromOptions(action, parsed)
+                            : resourceMutationFromOptions(action, parsed);
         sourceOperand = parsed.positionals[0];
         writeRequest = editingWriteRequest(parsed, sourceOperand);
     }
@@ -1171,7 +1085,7 @@ async function runMutation(resource, action, args) {
         originalLabel: source,
         updatedLabel: "candidate",
     };
-    const result = resource === "mutation"
+    const result = resource === "batch"
         ? planBatchMutation(input.text, mutation, mutationOptions)
         : planMutation(input.text, mutation, mutationOptions);
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
@@ -1193,6 +1107,7 @@ 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,
@@ -1225,6 +1140,142 @@ async function runMutation(resource, action, args) {
     }
     return ok ? 0 : 1;
 }
+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: 4,
+        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 advanceResultJson(details) {
     return details === null
         ? null
@@ -1247,7 +1298,7 @@ function renderAdvanceSummary(details) {
     ].join("\n");
 }
 async function runAdvance(args) {
-    const parsed = parseOptions(args, new Set(["format", "color", "max-diagnostics", "out", "expect-digest"]), new Set(["diff", "write", "warnings-as-errors"]));
+    const parsed = parseCommandOptions("dag.advance", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("dag advance requires exactly one <file>");
     }
@@ -1288,6 +1339,7 @@ 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,
@@ -1565,17 +1617,45 @@ 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) {
-    const parsed = parseOptions(args, new Set([
-        "schedule",
-        "max-paths",
-        "precision",
-        "max-diagnostics",
-        "format",
-        "color",
-    ]), new Set(["warnings-as-errors"]), new Set(["capacity"]));
+    const parsed = parseCommandOptions("dag.analyze", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("dag analyze requires exactly one <file>");
     }
@@ -1608,7 +1688,8 @@ async function runAnalyze(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.AnalysisResult.v2",
+            schema_version: "Perttool.AnalysisResult.v3",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1617,6 +1698,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
@@ -1633,6 +1715,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 {
@@ -1668,15 +1751,7 @@ function renderConversionLoss(loss, source, color) {
     }, source, color);
 }
 async function runRender(args) {
-    const parsed = parseOptions(args, new Set([
-        "to",
-        "profile",
-        "analysis",
-        "out",
-        "max-diagnostics",
-        "format",
-        "color",
-    ]), new Set(["strict-loss", "warnings-as-errors"]), new Set(["capacity"]));
+    const parsed = parseCommandOptions("dag.render", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("dag render requires exactly one <file>");
     }
@@ -1728,6 +1803,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1778,7 +1854,7 @@ async function runRender(args) {
     return strictFailure ? 4 : ok ? 0 : 1;
 }
 async function runImport(args) {
-    const parsed = parseOptions(args, new Set(["from", "out", "max-diagnostics", "format", "color"]), new Set(["strict-loss", "warnings-as-errors"]));
+    const parsed = parseCommandOptions("dag.import", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("dag import requires exactly one <file>");
     }
@@ -1819,6 +1895,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
+            cli_contract_version: 4,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -2035,7 +2112,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 ?? "-"}`,
@@ -2074,10 +2159,19 @@ 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) {
-    const parsed = parseOptions(args, new Set(["explain-depth", "precision", "max-diagnostics", "format", "color"]), new Set(["warnings-as-errors"]), new Set(["capacity"]));
+    const parsed = parseCommandOptions("dag.next", args);
     if (parsed.positionals.length !== 1) {
         throw new UsageError("dag next requires exactly one <file>");
     }
@@ -2108,6 +2202,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
+                cli_contract_version: 4,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2127,7 +2222,8 @@ async function runNext(args) {
     const ok = result.ok && !warningFailure;
     if (format === "json") {
         writeJson({
-            schema_version: "Perttool.NextResult.v3",
+            schema_version: "Perttool.NextResult.v4",
+            cli_contract_version: 4,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2137,7 +2233,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 {
@@ -2152,65 +2250,56 @@ async function runNext(args) {
     }
     return ok ? 0 : 1;
 }
-function renderHelpText(result) {
-    const lines = [result.title, "", result.summary];
-    if (result.topics.length > 0) {
-        lines.push("", "Topics:");
-        for (const topic of result.topics)
-            lines.push(`  ${topic.id.padEnd(12)} ${topic.summary}`);
-    }
-    for (const section of result.sections) {
-        lines.push("", section.title, section.body);
-    }
-    if (result.syntax.length > 0)
-        lines.push("", "Syntax:", ...result.syntax.map((line) => `  ${line}`));
-    if (result.examples.length > 0) {
-        lines.push("", "Examples:", ...result.examples.map((example) => `  ${example.id}: ${example.text}`));
-    }
-    if (result.related.length > 0)
-        lines.push("", `Related: ${result.related.join(", ")}`);
-    return `${lines.join("\n")}\n`;
-}
-function runHelp(args) {
-    const parsed = parseOptions(args, new Set(["level", "format", "color"]), new Set());
+function runGuide(args) {
+    const parsed = parseCommandOptions("guide", args);
     if (parsed.positionals.length > 2) {
-        throw new UsageError("dsl help accepts at most <topic> <subtopic>");
+        throw new UsageError("guide accepts at most <topic> <subtopic>");
     }
     const format = outputFormat(parsed.values.get("format"));
     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 = getHelp(topicId, level);
+    const result = getGuide(topicId, level);
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.HelpResult.v1",
-            tool_version: TOOL_VERSION,
-            operation: "dsl.help",
-            ok: result.ok,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            topic_id: result.topicId,
-            level: result.level,
-            title: result.title,
-            summary: result.summary,
-            sections: result.sections,
-            syntax: result.syntax,
-            examples: result.examples,
-            related: result.related,
-            topics: result.topics,
-        });
+        process.stdout.write(serializeGuideResult(result));
+    }
+    else {
+        const rendered = renderGuideResult(result);
+        if (result.ok) {
+            process.stdout.write(rendered);
+        }
+        else {
+            process.stderr.write(rendered);
+        }
     }
-    else if (result.ok) {
-        process.stdout.write(renderHelpText(result));
+    return result.ok ? 0 : 1;
+}
+function runCommandHelp(args) {
+    const parsed = parseCommandOptions("help", args);
+    if (parsed.positionals.length > 2) {
+        throw new UsageError("help accepts at most <resource> <action>");
+    }
+    const format = outputFormat(parsed.values.get("format"));
+    const result = getCommandDiscovery({
+        resource: parsed.positionals[0] ?? null,
+        action: parsed.positionals[1] ?? null,
+    });
+    if (format === "json") {
+        process.stdout.write(serializeCommandHelpResult(result));
     }
     else {
-        for (const diagnostic of result.diagnostics) {
-            process.stderr.write(`${renderDiagnostic(diagnostic, "<help>", "never")}\n`);
+        const rendered = renderCommandHelpResult(result);
+        if (result.ok) {
+            process.stdout.write(rendered);
+        }
+        else {
+            process.stderr.write(rendered);
         }
     }
     return result.ok ? 0 : 1;
 }
 function runAgentHelp(args) {
-    const parsed = parseOptions(args, new Set(["level", "format", "color"]), new Set());
+    const parsed = parseCommandOptions("agent.help", args);
     if (parsed.positionals.length > 2) {
         throw new UsageError("agent help accepts at most <provider> <surface>");
     }
@@ -2225,7 +2314,13 @@ function runAgentHelp(args) {
         level,
     });
     if (format === "json") {
-        process.stdout.write(serializeAgentGuidanceResult(result));
+        const projected = agentGuidanceResultToJson(result);
+        const { schema_version: schemaVersion, ...payload } = projected;
+        writeJson({
+            schema_version: schemaVersion,
+            cli_contract_version: 4,
+            ...payload,
+        });
     }
     else {
         if (result.ok) {
@@ -2245,74 +2340,90 @@ function runAgentHelp(args) {
     }
     return agentGuidanceExitCode(result.diagnostics);
 }
+async function dispatchCommand(descriptor, args) {
+    switch (descriptor.operation) {
+        case "help":
+            return runCommandHelp(args);
+        case "guide":
+            return runGuide(args);
+        case "document.check":
+            return runCheck(args);
+        case "document.format":
+            return runFormat(args);
+        case "agent.help":
+            return runAgentHelp(args);
+        case "project.init":
+            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":
+            return runNext(args);
+        case "dag.advance":
+            return runAdvance(args);
+        case "dag.render":
+            return runRender(args);
+        case "dag.import":
+            return runImport(args);
+    }
+    if (descriptor.path.length === 2
+        && (descriptor.operation === "project.set"
+            || descriptor.operation === "batch.apply"
+            || /^(?:task|gate|milestone|resource)\.(?:add|set|remove|finish)$/.test(descriptor.operation))) {
+        const [resource, action] = descriptor.path;
+        return runMutation(resource, action, args);
+    }
+    throw new Error(`no Contract 4 handler for ${descriptor.operation}`);
+}
+function emitCommandUsage(error, json) {
+    if (json) {
+        process.stdout.write(serializeCommandUsageError(error));
+    }
+    else {
+        process.stderr.write(renderCommandUsageError(error));
+    }
+    return 2;
+}
 async function main(argv) {
     if (argv.length === 1 && argv[0] === "--version") {
         process.stdout.write(`perttool ${TOOL_VERSION}\n`);
         return 0;
     }
     if (argv.length === 1 && argv[0] === "--help") {
-        process.stdout.write(`${topLevelHelp()}\n`);
-        return 0;
-    }
-    if (argv.length < 2)
-        throw new UsageError("expected <resource> <action>");
-    const resource = argv[0];
-    const action = argv[1];
-    const entityActions = new Map([
-        ["project", new Set(["set"])],
-        ["task", new Set(["add", "set", "remove", "finish"])],
-        ["milestone", new Set(["add", "set", "remove"])],
-        ["resource", new Set(["add", "set", "remove"])],
-        ["mutation", new Set(["apply"])],
-    ]);
-    const isMutationCommand = entityActions.get(resource)?.has(action) === true;
-    if (argv.length === 3 &&
-        argv[2] === "--help" &&
-        ((resource === "agent" && action === "help") ||
-            (resource === "dsl" && ["check", "format", "help"].includes(action)) ||
-            (resource === "project" && action === "show") ||
-            (resource === "dag" && ["analyze", "next", "advance", "render", "import"].includes(action)) ||
-            isMutationCommand)) {
-        process.stdout.write(`${commandHelp(resource, action)}\n`);
-        return 0;
-    }
-    if (resource === "dag" && action === "analyze") {
-        return runAnalyze(argv.slice(2));
-    }
-    if (resource === "dag" && action === "next") {
-        return runNext(argv.slice(2));
-    }
-    if (resource === "dag" && action === "advance") {
-        return runAdvance(argv.slice(2));
-    }
-    if (resource === "dag" && action === "render") {
-        return runRender(argv.slice(2));
-    }
-    if (resource === "dag" && action === "import") {
-        return runImport(argv.slice(2));
-    }
-    if (resource === "agent" && action === "help") {
-        return runAgentHelp(argv.slice(2));
+        return runCommandHelp([]);
     }
-    if (resource === "project" && action === "show") {
-        return runProjectShow(argv.slice(2));
+    const validation = validateCommandInvocation(argv);
+    if (!validation.ok) {
+        if (jsonRequested(argv)) {
+            process.stdout.write(serializeCommandUsageError(validation.error));
+        }
+        else {
+            process.stderr.write(renderCommandUsageError(validation.error));
+        }
+        return 2;
     }
-    if (resource === "dsl" && action === "format") {
-        return runFormat(argv.slice(2));
+    const descriptor = validation.descriptor;
+    if (validation.helpAlias) {
+        return runCommandHelp([...descriptor.path]);
     }
-    if (isMutationCommand) {
-        return runMutation(resource, action, argv.slice(2));
+    try {
+        return await dispatchCommand(descriptor, argv.slice(descriptor.path.length));
     }
-    if (resource !== "dsl" || (action !== "check" && action !== "help")) {
-        throw new UsageError(`unknown or not-yet-implemented command: ${resource} ${action}`);
+    catch (error) {
+        if (error instanceof UsageError) {
+            return emitCommandUsage(handlerCommandUsageError(descriptor, error.message), jsonRequested(argv));
+        }
+        throw error;
     }
-    return action === "check" ? runCheck(argv.slice(2)) : runHelp(argv.slice(2));
 }
 const args = process.argv.slice(2);
 try {
     process.exitCode = await main(args);
 }
 catch (error) {
-    process.exitCode = cliError(error instanceof Error ? error : new Error(String(error)), error instanceof UsageError ? 2 : 70, args.length >= 2 ? `${args[0]}.${args[1]}` : null, jsonRequested(args));
+    process.exitCode = cliError(error instanceof Error ? error : new Error(String(error)), 70, null, jsonRequested(args));
 }
 //# sourceMappingURL=cli.js.map