perttool 0.1.0 → 0.2.0

package/dist/cli.js

@@ -5,14 +5,18 @@ import { TextDecoder } from "node:util";
 import { analyzeDocument } from "./application/analyze.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 { 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 { CONTRACT3_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 = CONTRACT3_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");
 }
@@ -369,6 +205,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -381,9 +218,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 +232,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");
@@ -404,8 +241,9 @@ async function runCheck(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.CheckResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
-            operation: "dsl.check",
+            operation: "document.check",
             ok,
             document_id: result.documentId,
             source,
@@ -460,7 +298,7 @@ function renderProjectText(project) {
     ].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>");
     }
@@ -484,6 +322,7 @@ async function runProjectShow(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ProjectResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation: "project.show",
             ok,
@@ -509,6 +348,56 @@ 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") }),
+    });
+    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 +435,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 +475,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 +504,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 +519,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 +540,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: 3,
             tool_version: TOOL_VERSION,
-            operation: "dsl.format",
+            operation: "document.format",
             ok,
             document_id: result.documentId,
             source,
@@ -680,7 +562,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 +571,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 +584,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)
@@ -1086,6 +924,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 +985,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 +993,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 +1020,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 +1041,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 +1063,7 @@ async function runMutation(resource, action, args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.MutationResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation,
             ok,
@@ -1247,7 +1118,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 +1159,7 @@ async function runAdvance(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.MutationResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation: "dag.advance",
             ok,
@@ -1568,14 +1440,7 @@ function renderAnalysisText(result) {
     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>");
     }
@@ -1609,6 +1474,7 @@ async function runAnalyze(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.AnalysisResult.v2",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1668,15 +1534,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 +1586,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1778,7 +1637,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 +1678,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
+            cli_contract_version: 3,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -2077,7 +1937,7 @@ function renderNextText(result) {
     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 +1968,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
+                cli_contract_version: 3,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2128,6 +1989,7 @@ async function runNext(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.NextResult.v3",
+            cli_contract_version: 3,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2152,65 +2014,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 if (result.ok) {
-        process.stdout.write(renderHelpText(result));
+    else {
+        const rendered = renderGuideResult(result);
+        if (result.ok) {
+            process.stdout.write(rendered);
+        }
+        else {
+            process.stderr.write(rendered);
+        }
+    }
+    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 +2078,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: 3,
+            ...payload,
+        });
     }
     else {
         if (result.ok) {
@@ -2245,74 +2104,88 @@ 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 "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 3 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;
+        return runCommandHelp([]);
     }
-    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));
-    }
-    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