@gonovus-ai/spec-flow-cli 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,3339 @@
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { randomUUID } from "node:crypto";
+import createClient from "openapi-fetch";
+import { z } from "zod";
+import { addAuthenticationCommandTopology } from "./authentication-command-topology.js";
+import { registerGitHubAccountCommands } from "./github-account-commands.js";
+import { parseHttpOrigin, unresolvedSpecFlowApiOrigin, } from "./http-origin.js";
+import { specFlowCliUserAgent } from "./user-agent.js";
+import { registerUserApiKeyCommands } from "./user-api-key-commands.js";
+import { registerWorkItemAssetCommands } from "./work-item-asset-commands.js";
+import { readWorkItemImportFile } from "./work-item-exchange-file.js";
+import { registerWorkItemResourceLinkCommands } from "./work-item-resource-link-commands.js";
+import { parseTimeEntryTimestamp, parseTimeEntryUuid, parseTimeEntryDescription } from "./work-item-time-entry-input.js";
+export function formatResourceDiagnostic(message) {
+    return `${JSON.stringify({ diagnostic: { level: "warning", message } })}\n`;
+}
+const workItemBulkActions = [
+    "updateStatus",
+    "updatePriority",
+    "updateAssignee",
+    "delete",
+    "addLabel",
+    "removeLabel",
+    "updateDueDate",
+];
+const glossaryEntryInputSchema = z
+    .object({
+    canonicalTerm: z.string().trim().min(1).max(200),
+    definition: z.string().trim().min(1).max(4_000),
+    id: z.string().trim().min(1).max(200),
+    usageNote: z.string().trim().min(1).max(2_000).nullable(),
+})
+    .strict();
+const glossaryEntriesInputSchema = z.array(glossaryEntryInputSchema).max(500);
+const sourceReferenceInputSchema = z
+    .object({
+    externalRevision: z.string().trim().min(1).max(200).optional(),
+    section: z.string().trim().min(1).max(500).optional(),
+    title: z.string().trim().min(1).max(300),
+    url: z.url().max(2_000).refine((value) => {
+        const url = new URL(value);
+        return ((url.protocol === "https:" || url.protocol === "http:") &&
+            url.username.length === 0 &&
+            url.password.length === 0);
+    }),
+})
+    .strict();
+const sourceReferencesInputSchema = z.array(sourceReferenceInputSchema).max(20);
+const roleStatementsInputSchema = z.record(z.string().trim().min(1).max(200), z.array(z.string().trim().min(1).max(200)).min(1).max(50));
+const findingReferenceSchema = z
+    .object({
+    kind: z.enum(["SharedPrecondition", "ExampleTable", "Title", "Rule", "Scenario", "Line"]),
+    text: z.string().trim().min(1).max(20_000),
+})
+    .strict();
+const findingTargetSchema = z
+    .object({
+    references: z.array(findingReferenceSchema).min(1).max(50),
+    specId: z.string().trim().toUpperCase().regex(/^[A-Z]{2,10}-[1-9]\d*$/u),
+})
+    .strict();
+const findingEvidenceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        incompatibleClaims: z.tuple([
+            z.string().trim().min(1).max(4_000),
+            z.string().trim().min(1).max(4_000),
+        ]),
+        kind: z.literal("Contradiction"),
+    })
+        .strict(),
+    z
+        .object({
+        incompatibleRequirements: z.tuple([
+            z.string().trim().min(1).max(4_000),
+            z.string().trim().min(1).max(4_000),
+        ]),
+        kind: z.literal("Conflict"),
+    })
+        .strict(),
+    z
+        .object({
+        duplicatedBehavior: z.string().trim().min(1).max(4_000),
+        kind: z.literal("Duplicate"),
+    })
+        .strict(),
+    z
+        .object({
+        interpretations: z.tuple([
+            z
+                .object({
+                behavior: z.string().trim().min(1).max(4_000),
+                meaning: z.string().trim().min(1).max(4_000),
+            })
+                .strict(),
+            z
+                .object({
+                behavior: z.string().trim().min(1).max(4_000),
+                meaning: z.string().trim().min(1).max(4_000),
+            })
+                .strict(),
+        ]),
+        kind: z.literal("Ambiguity"),
+    })
+        .strict(),
+    z
+        .object({
+        glossaryEntryIds: z.array(z.string().trim().min(1).max(200)).max(20),
+        issue: z.enum(["MissingDefinition", "GlossaryConflict", "MultipleMeanings"]),
+        kind: z.literal("Terminology"),
+        term: z.string().trim().min(1).max(200),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("Unverifiable"),
+        missingCriterion: z.string().trim().min(1).max(4_000),
+    })
+        .strict(),
+]);
+const findingCreateInputSchema = z
+    .object({
+    affectedScenarios: z.array(z.string().trim().min(1).max(300)).max(50),
+    conclusion: z.string().trim().min(1).max(4_000),
+    evidence: findingEvidenceSchema,
+    explanation: z.string().trim().min(1).max(8_000),
+    targets: z.array(findingTargetSchema).min(1).max(10),
+})
+    .strict();
+export async function runCli(arguments_, dependencies) {
+    let exitCode = 0;
+    const program = new Command()
+        .name("specflow")
+        .description("Read and govern SpecFlow through supported commands")
+        .option("--allow-file-fallback", "use a warned owner-only local credential file if the system store is unavailable")
+        .option("--server <url>", "SpecFlow server origin")
+        .option("--api-key-id <id>", "Use an origin-scoped User API Key from the credential store")
+        .exitOverride()
+        .configureOutput({
+        writeErr: () => undefined,
+        writeOut: dependencies.stdout,
+    });
+    const run = (request, options = {}) => executeRequest(dependencies, request, options, program.getOptionValue("server"), program.getOptionValue("apiKeyId"));
+    registerUserApiKeyCommands(program, { dependencies, run, setExitCode: (value) => { exitCode = value; }, parseScopes: parseRoleStatements, parseLimit: parseSearchLimit });
+    registerGitHubAccountCommands(program, { dependencies, run, setExitCode: (value) => { exitCode = value; } });
+    const authentication = addAuthenticationCommandTopology(program);
+    program.hook("preAction", (_command, actionCommand) => {
+        const options = actionCommand.opts();
+        if (typeof options.projectId === "string") {
+            actionCommand.setOptionValue("projectId", parseProjectId(options.projectId));
+        }
+        if (typeof options.specId === "string") {
+            actionCommand.setOptionValue("specId", parseSpecId(options.specId));
+        }
+        if (typeof options.workItemId === "string") {
+            actionCommand.setOptionValue("workItemId", parseWorkItemId(options.workItemId));
+        }
+    });
+    for (const command of [
+        authentication.login,
+        authentication.logout,
+        authentication.status,
+    ]) {
+        command.action(() => {
+            throw new CommanderError(2, "specflow.authenticationCommand", "Authentication commands use the human-facing CLI boundary");
+        });
+    }
+    const workspace = program.command("workspace");
+    workspace
+        .command("list")
+        .action(async () => {
+        exitCode = await run((client) => client.GET("/v1/workspaces"), { rejectProjectReadToken: true });
+    });
+    workspace
+        .command("create")
+        .requiredOption("--name <name>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/workspaces", {
+            body: { name: options.name },
+            params: { header: { "idempotency-key": idempotencyKey } },
+        }), { retryTransportOnce: true });
+    });
+    const workspaceMember = workspace.command("member");
+    workspaceMember
+        .command("list")
+        .requiredOption("--workspace-id <workspaceId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/workspaces/{workspaceId}/members", {
+            params: { path: { workspaceId: options.workspaceId } },
+        }), { rejectProjectReadToken: true });
+    });
+    workspaceMember
+        .command("search")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--query <query>")
+        .option("--limit <limit>", "Maximum directory candidates", parseSearchLimit, 10)
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/workspaces/{workspaceId}/members/directory", {
+            params: {
+                path: { workspaceId: options.workspaceId },
+                query: { limit: options.limit, query: options.query },
+            },
+        }), { rejectProjectReadToken: true });
+    });
+    workspaceMember
+        .command("add")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--issuer <issuer>", "Authentik issuer URL from `workspace member search`")
+        .requiredOption("--subject <subject>", "Authentik subject from `workspace member search`")
+        .requiredOption("--role <role>", "Workspace Role name")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/workspaces/{workspaceId}/members", {
+            body: {
+                issuer: options.issuer,
+                role: options.role,
+                subject: options.subject,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { workspaceId: options.workspaceId },
+            },
+        }), { retryTransportOnce: true });
+    });
+    workspaceMember
+        .command("set-role")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--user-id <userId>", "Member User ID from `workspace member list`")
+        .requiredOption("--role <role>", "Workspace Role name")
+        .requiredOption("--expected-version <version>", "Opaque Member version from `workspace member list`", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PATCH("/v1/workspaces/{workspaceId}/members/{userId}", {
+            body: { role: options.role },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    userId: options.userId,
+                    workspaceId: options.workspaceId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Member Role change outcome is unknown; read `workspace member list` before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workspaceMember
+        .command("remove")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--user-id <userId>", "Member User ID from `workspace member list`")
+        .requiredOption("--expected-version <version>", "Opaque Member version from `workspace member list`", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.DELETE("/v1/workspaces/{workspaceId}/members/{userId}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    userId: options.userId,
+                    workspaceId: options.workspaceId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Member removal outcome is unknown; read `workspace member list` before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const workspaceRole = workspace.command("role");
+    workspaceRole
+        .command("list")
+        .requiredOption("--workspace-id <workspaceId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/workspaces/{workspaceId}/roles", {
+            params: { path: { workspaceId: options.workspaceId } },
+        }), { rejectProjectReadToken: true });
+    });
+    workspaceRole
+        .command("create")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--name <name>", "Custom Workspace Role name")
+        .requiredOption("--statements <statements>", "JSON object mapping permission resources to granted actions", parseRoleStatements)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/workspaces/{workspaceId}/roles", {
+            body: { name: options.name, statements: options.statements },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { workspaceId: options.workspaceId },
+            },
+        }), { retryTransportOnce: true });
+    });
+    workspaceRole
+        .command("update")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--name <name>", "Workspace Role name from `workspace role list`")
+        .requiredOption("--statements <statements>", "JSON object mapping permission resources to granted actions", parseRoleStatements)
+        .requiredOption("--expected-version <version>", "Opaque Role version from `workspace role list`", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/workspaces/{workspaceId}/roles/{roleName}", {
+            body: { statements: options.statements },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    roleName: options.name,
+                    workspaceId: options.workspaceId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Role update outcome is unknown; read `workspace role list` before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workspaceRole
+        .command("delete")
+        .requiredOption("--workspace-id <workspaceId>")
+        .requiredOption("--name <name>", "Custom Workspace Role name")
+        .requiredOption("--expected-version <version>", "Opaque Role version from `workspace role list`", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.DELETE("/v1/workspaces/{workspaceId}/roles/{roleName}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    roleName: options.name,
+                    workspaceId: options.workspaceId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Role deletion outcome is unknown; read `workspace role list` before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const project = program.command("project");
+    project
+        .command("list")
+        .option("--status <status>", "Filter by Project lifecycle status", parseProjectStatus)
+        .option("--workspace-id <workspaceId>", "Filter by owning Workspace ID from `workspace list`")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects", {
+            params: {
+                query: {
+                    ...(options.status === undefined
+                        ? {}
+                        : { status: options.status }),
+                    ...(options.workspaceId === undefined
+                        ? {}
+                        : { workspaceId: options.workspaceId }),
+                },
+            },
+        }), { rejectProjectReadToken: true });
+    });
+    project
+        .command("create")
+        .requiredOption("--name <name>")
+        .requiredOption("--project-id <projectId>", "Immutable Project ID (2-10 letters)", parseProjectId)
+        .requiredOption("--workspace-id <workspaceId>", "Workspace ID returned by `workspace list` or `workspace create`")
+        .option("--spec-language <language>", "Spec Language: en or zh-CN (default: en)")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects", {
+            body: {
+                name: options.name,
+                projectId: options.projectId,
+                workspaceId: options.workspaceId,
+                ...(options.specLanguage === undefined
+                    ? {}
+                    : { specLanguage: options.specLanguage }),
+            },
+            params: { header: { "idempotency-key": idempotencyKey } },
+        }), { retryTransportOnce: true });
+    });
+    for (const operation of ["archive", "restore", "trash"]) {
+        project
+            .command(operation)
+            .requiredOption("--project-id <projectId>")
+            .requiredOption("--expected-version <version>", "Opaque Project version", parseOpaqueVersion)
+            .action(async (options) => {
+            const idempotencyKey = randomUUID();
+            exitCode = await run((client) => client.POST(`/v1/projects/{projectId}/${operation}`, {
+                params: {
+                    header: {
+                        "idempotency-key": idempotencyKey,
+                        "if-match": options.expectedVersion,
+                    },
+                    path: { projectId: options.projectId },
+                },
+            }), {
+                ambiguousOutcomeMessage: `Project ${operation} outcome is unknown; read Project context before retrying`,
+                rejectProjectReadToken: true,
+                retryTransportOnce: true,
+            });
+        });
+    }
+    project
+        .command("context")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/context", {
+            params: { path: { projectId: options.projectId } },
+        }));
+    });
+    project
+        .command("directory")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/spec-directory", {
+            params: { path: { projectId: options.projectId } },
+        }));
+    });
+    const sharing = project.command("sharing").description("Manage anonymous task-only Project sharing");
+    sharing.command("read")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/sharing", {
+            params: { path: { projectId: options.projectId } },
+        }), { rejectProjectReadToken: true });
+    });
+    sharing.command("set")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--public <boolean>", "true or false", (value) => {
+        if (value !== "true" && value !== "false")
+            throw new InvalidArgumentError("--public must be true or false");
+        return value === "true";
+    })
+        .requiredOption("--expected-version <version>", "Opaque sharing version from project sharing read", parseOpaqueVersion)
+        .requiredOption("--idempotency-key <key>", "UUID; reuse the same key and intent after an uncertain response", (value) => {
+        if (!z.uuid().safeParse(value).success)
+            throw new InvalidArgumentError("The sharing command key must be a UUID");
+        return value;
+    })
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/sharing", {
+            body: { isPublic: options.public },
+            params: { path: { projectId: options.projectId }, header: { "if-match": options.expectedVersion, "idempotency-key": options.idempotencyKey } },
+        }), { rejectProjectReadToken: true, retryTransportOnce: true, ambiguousOutcomeMessage: "Sharing outcome is unknown; reread project sharing and retry the same command key and intent" });
+    });
+    const spec = program.command("spec");
+    spec
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/specs/{specId}", {
+            params: { path: options },
+        }), { rejectProjectReadToken: true });
+    });
+    spec
+        .command("changelog")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/specs/{specId}/changelog", { params: { path: options } }), { rejectProjectReadToken: true });
+    });
+    spec
+        .command("search")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--query <query>")
+        .option("--limit <limit>", "Maximum results", parseSearchLimit, 20)
+        .option("--cursor <cursor>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/spec-search", {
+            params: {
+                path: { projectId: options.projectId },
+                query: {
+                    ...(options.cursor === undefined
+                        ? {}
+                        : { cursor: options.cursor }),
+                    limit: options.limit,
+                    query: options.query,
+                },
+            },
+        }));
+    });
+    spec
+        .command("current")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/specs/{specId}/current-revision", { params: { path: options } }));
+    });
+    spec
+        .command("revision")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--revision-id <revisionId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/specs/{specId}/revisions/{revisionId}", { params: { path: options } }));
+    });
+    spec
+        .command("edit")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--content <content>")
+        .option("--agent-revision <agentRevision>")
+        .option("--agent-model <agentModel>")
+        .option("--source-reference-ids <sourceReferenceIds>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/specs/{specId}/draft", {
+            body: {
+                content: options.content,
+                provenance: toAgentProvenance(options),
+            },
+            params: { path: options },
+        }));
+    });
+    spec
+        .command("assign-scenario-ids")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .option("--agent-revision <agentRevision>")
+        .option("--agent-model <agentModel>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs/{specId}/draft/scenario-ids", {
+            body: { provenance: toAgentProvenance(options) },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: options,
+            },
+        }), {
+            ambiguousOutcomeMessage: "Scenario ID assignment outcome is unknown; inspect the Working Draft before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    spec
+        .command("publish")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs/{specId}/publish", {
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: options,
+            },
+        }), {
+            ambiguousOutcomeMessage: "Spec Publish outcome is unknown; inspect the Spec Changelog before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    spec
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .option("--capability-id <capabilityId>")
+        .requiredOption("--feature-name <featureName>")
+        .option("--source-references <sourceReferences>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        const sourceReferences = parseSourceReferences(options.sourceReferences ?? "[]");
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs", {
+            body: {
+                capabilityId: options.capabilityId ?? null,
+                featureName: options.featureName,
+                sourceReferences,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Spec Creation outcome is unknown; inspect the Project directory before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    spec
+        .command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--capability-id <capabilityId>")
+        .option("--source-references <sourceReferences>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.capabilityId === undefined &&
+            options.sourceReferences === undefined) {
+            throw invalidArgument("Spec update requires Metadata to change");
+        }
+        const sourceReferences = options.sourceReferences === undefined
+            ? undefined
+            : parseSourceReferences(options.sourceReferences);
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/specs/{specId}", {
+            body: {
+                ...(options.capabilityId === undefined
+                    ? {}
+                    : { capabilityId: options.capabilityId === "none" ? null : options.capabilityId }),
+                ...(sourceReferences === undefined
+                    ? {}
+                    : { sourceReferences }),
+            },
+            params: {
+                header: { "if-match": options.expectedVersion },
+                path: options,
+            },
+        }));
+    });
+    spec
+        .command("draft")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs/{specId}/draft-session", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: options,
+            },
+        }), {
+            ambiguousOutcomeMessage: "Spec Draft Session outcome is unknown; read the Spec before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    spec
+        .command("state")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .requiredOption("--state <state>", "Ready or Unavailable", parseSpecState)
+        .option("--unavailability-reason <unavailabilityReason>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.state === "Unavailable" &&
+            options.unavailabilityReason === undefined) {
+            throw invalidArgument("Unavailable requires --unavailability-reason");
+        }
+        if (options.state === "Ready" &&
+            options.unavailabilityReason !== undefined) {
+            throw invalidArgument("Ready does not accept --unavailability-reason");
+        }
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/specs/{specId}/state", {
+            body: options.state === "Ready"
+                ? { state: "Ready" }
+                : {
+                    state: "Unavailable",
+                    unavailabilityReason: options.unavailabilityReason ?? "",
+                },
+            params: {
+                header: { "if-match": options.expectedVersion },
+                path: options,
+            },
+        }));
+    });
+    spec
+        .command("rollback")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--revision-id <revisionId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs/{specId}/rollback", {
+            body: { revisionId: options.revisionId },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: options,
+            },
+        }), {
+            ambiguousOutcomeMessage: "Spec Rollback outcome is unknown; inspect the Spec Changelog before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    spec
+        .command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/specs/{specId}", {
+            params: {
+                header: { "if-match": options.expectedVersion },
+                path: options,
+            },
+        }), { deleted: { specId: options.specId } }));
+    });
+    const glossary = program.command("glossary");
+    glossary
+        .command("revision")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--revision-id <revisionId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/glossary/revisions/{revisionId}", { params: { path: options } }));
+    });
+    glossary
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/glossary", {
+            params: { path: { projectId: options.projectId } },
+        }), { rejectProjectReadToken: true });
+    });
+    glossary
+        .command("changelog")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/glossary/changelog", {
+            params: { path: { projectId: options.projectId } },
+        }), { rejectProjectReadToken: true });
+    });
+    glossary
+        .command("draft")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/glossary/draft-session", {
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Glossary Draft Session outcome is unknown; read the Glossary before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    glossary
+        .command("edit")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--entries <entries>")
+        .option("--agent-revision <agentRevision>")
+        .option("--agent-model <agentModel>")
+        .option("--source-reference-ids <sourceReferenceIds>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const entries = parseGlossaryEntries(options.entries);
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/glossary/draft", {
+            body: { entries, provenance: toAgentProvenance(options) },
+            params: { path: { projectId: options.projectId } },
+        }));
+    });
+    glossary
+        .command("publish")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/glossary/publish", {
+            body: {},
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Glossary Publish outcome is unknown; inspect the Glossary Changelog before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    glossary
+        .command("rollback")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--revision-id <revisionId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/glossary/rollback", {
+            body: { revisionId: options.revisionId },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Glossary Rollback outcome is unknown; inspect the Glossary Changelog before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const proposal = program.command("proposal");
+    proposal
+        .command("create-spec")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .requiredOption("--baseline-content <baselineContent>")
+        .requiredOption("--proposed-content <proposedContent>")
+        .option("--agent-revision <agentRevision>")
+        .option("--agent-model <agentModel>")
+        .option("--source-reference-ids <sourceReferenceIds>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/draft-proposals", {
+            body: {
+                baselineContent: options.baselineContent,
+                kind: "Spec",
+                proposedContent: options.proposedContent,
+                provenance: toAgentProvenance(options),
+                specId: options.specId,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Draft Proposal Creation outcome is unknown; list open Proposals before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    proposal
+        .command("create-glossary")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--baseline-entries <baselineEntries>")
+        .requiredOption("--proposed-entries <proposedEntries>")
+        .option("--agent-revision <agentRevision>")
+        .option("--agent-model <agentModel>")
+        .option("--source-reference-ids <sourceReferenceIds>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/draft-proposals", {
+            body: {
+                baselineEntries: parseGlossaryEntries(options.baselineEntries),
+                kind: "Glossary",
+                proposedEntries: parseGlossaryEntries(options.proposedEntries),
+                provenance: toAgentProvenance(options),
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Draft Proposal Creation outcome is unknown; list open Proposals before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    proposal
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .option("--target-kind <targetKind>", "Spec or Glossary", parseProposalTargetKind)
+        .option("--spec-id <specId>")
+        .option("--status <status>", "Open, Applied, or Discarded", parseProposalStatus)
+        .action(async (options) => {
+        if ((options.targetKind === "Spec" && options.specId === undefined) ||
+            (options.targetKind !== "Spec" && options.specId !== undefined)) {
+            throw invalidArgument("--spec-id requires --target-kind Spec");
+        }
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/draft-proposals", {
+            params: {
+                path: { projectId: options.projectId },
+                query: {
+                    ...(options.specId === undefined ? {} : { specId: options.specId }),
+                    ...(options.status === undefined ? {} : { status: options.status }),
+                    ...(options.targetKind === undefined
+                        ? {}
+                        : { targetKind: options.targetKind }),
+                },
+            },
+        }));
+    });
+    proposal
+        .command("apply")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--proposal-id <proposalId>")
+        .option("--change-ids <changeIds>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/draft-proposals/{proposalId}/apply", {
+            body: {
+                changeIds: options.changeIds === undefined
+                    ? null
+                    : parseStringArray(options.changeIds, "change IDs"),
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: {
+                    projectId: options.projectId,
+                    proposalId: options.proposalId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Draft Proposal Apply outcome is unknown; reread the Proposal and Working Draft",
+            retryTransportOnce: true,
+        });
+    });
+    proposal
+        .command("discard")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--proposal-id <proposalId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/draft-proposals/{proposalId}/discard", {
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: {
+                    projectId: options.projectId,
+                    proposalId: options.proposalId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Draft Proposal Discard outcome is unknown; reread the Proposal",
+            retryTransportOnce: true,
+        });
+    });
+    program
+        .command("authoring-history")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/authoring-history", {
+            params: { path: { projectId: options.projectId } },
+        }));
+    });
+    const capability = program.command("capability");
+    capability
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--name <name>")
+        .option("--parent-id <parentId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/capabilities", {
+            body: {
+                name: options.name,
+                parentId: options.parentId ?? null,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Capability Creation outcome is unknown; inspect the Project directory before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    capability
+        .command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--capability-id <capabilityId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--name <name>")
+        .option("--parent-id <parentId>")
+        .option("--move-to-root")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.parentId !== undefined && options.moveToRoot === true) {
+            throw invalidArgument("Capability update cannot combine --parent-id and --move-to-root");
+        }
+        if (options.name === undefined &&
+            options.parentId === undefined &&
+            options.moveToRoot !== true) {
+            throw invalidArgument("Capability update requires a change");
+        }
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/capabilities/{capabilityId}", {
+            body: {
+                ...(options.name === undefined ? {} : { name: options.name }),
+                ...(options.moveToRoot === true
+                    ? { parentId: null }
+                    : options.parentId === undefined
+                        ? {}
+                        : { parentId: options.parentId }),
+            },
+            params: {
+                header: { "if-match": options.expectedVersion },
+                path: options,
+            },
+        }));
+    });
+    capability
+        .command("delete")
+        .option("--idempotency-key <key>", "Reuse this key when retrying the same deletion")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--capability-id <capabilityId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = options.idempotencyKey ?? randomUUID();
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/capabilities/{capabilityId}", {
+            params: {
+                header: { "if-match": options.expectedVersion, "idempotency-key": idempotencyKey },
+                path: options,
+            },
+        }), { deleted: { capabilityId: options.capabilityId } }));
+    });
+    const finding = program.command("finding");
+    finding
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .option("--status <status>", "Finding status", parseFindingStatus)
+        .option("--limit <limit>", "Maximum results", parseSearchLimit, 20)
+        .option("--cursor <cursor>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/specs/{specId}/findings", {
+            params: {
+                path: { projectId: options.projectId, specId: options.specId },
+                query: {
+                    ...(options.cursor === undefined
+                        ? {}
+                        : { cursor: options.cursor }),
+                    limit: options.limit,
+                    ...(options.status === undefined
+                        ? {}
+                        : { status: options.status }),
+                },
+            },
+        }), { rejectProjectReadToken: true });
+    });
+    finding
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--finding-id <findingId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/findings/{findingId}", {
+            params: { path: options },
+        }), { rejectProjectReadToken: true });
+    });
+    finding
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--input <input>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        const input = parseFindingInput(options.input);
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/findings", {
+            body: input,
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Finding Creation outcome is unknown; inspect the Finding list before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    for (const [commandName, status] of [
+        ["confirm", "Confirmed"],
+        ["dismiss", "Dismissed"],
+        ["resolve", "Resolved"],
+    ]) {
+        finding
+            .command(commandName)
+            .requiredOption("--project-id <projectId>")
+            .requiredOption("--finding-id <findingId>")
+            .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+            .action(async (options) => {
+            if (hasProjectReadToken(dependencies.environment)) {
+                exitCode = rejectTokenWrite(dependencies);
+                return;
+            }
+            const idempotencyKey = randomUUID();
+            exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/findings/{findingId}/status", {
+                body: { status },
+                params: {
+                    header: {
+                        "idempotency-key": idempotencyKey,
+                        "if-match": options.expectedVersion,
+                    },
+                    path: options,
+                },
+            }), {
+                ambiguousOutcomeMessage: "Finding disposition outcome is unknown; read the Finding before retrying",
+                retryTransportOnce: true,
+            });
+        });
+    }
+    const notification = program.command("notification").description("Read and manage your personal task notifications");
+    notification.command("list").action(async () => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectProjectReadTokenOperation(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.GET("/v1/notifications"));
+    });
+    notification.command("create")
+        .option("--title <title>")
+        .option("--message <message>")
+        .option("--type <type>", "Notification type", "info")
+        .option("--event-data <json>", "JSON object for presentation", parseNotificationEventData)
+        .option("--related-entity-id <id>", "Public task ID or Workspace ID")
+        .option("--related-entity-type <type>", "task or workspace", (value) => { if (value !== "task" && value !== "workspace")
+        throw invalidArgument("Notification target must be task or workspace"); return value; })
+        .requiredOption("--idempotency-key <key>", "Reuse the same command key and inputs when retrying", parseNotificationUuid)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectProjectReadTokenOperation(dependencies);
+            return;
+        }
+        if ((options.relatedEntityId === undefined) !== (options.relatedEntityType === undefined))
+            throw invalidArgument("Notification target identity and type must be provided together");
+        exitCode = await run((client) => client.POST("/v1/notifications", { body: { type: options.type, ...(options.title === undefined ? {} : { title: options.title }), ...(options.message === undefined ? {} : { message: options.message }), ...(options.eventData === undefined ? {} : { eventData: options.eventData }), ...(options.relatedEntityId === undefined ? {} : { relatedEntityId: options.relatedEntityId }), ...(options.relatedEntityType === undefined ? {} : { relatedEntityType: options.relatedEntityType }) }, params: { header: { "idempotency-key": options.idempotencyKey } } }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Notification creation outcome is unknown; retry with the same inputs and command key" });
+    });
+    notification.command("read")
+        .requiredOption("--notification-id <id>", "Notification UUID returned by the list", parseNotificationUuid)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key when retrying", parseNotificationUuid)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectProjectReadTokenOperation(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.PATCH("/v1/notifications/{notificationId}/read", { params: { path: { notificationId: options.notificationId }, header: { "idempotency-key": options.idempotencyKey } } }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Notification read outcome is unknown; retry with the same notification and command key" });
+    });
+    for (const action of ["read-all", "clear"]) {
+        notification.command(action).requiredOption("--idempotency-key <key>", "Reuse the same key to avoid changing notifications that arrived after the first command", parseNotificationUuid)
+            .action(async (options) => {
+            if (hasProjectReadToken(dependencies.environment)) {
+                exitCode = rejectProjectReadTokenOperation(dependencies);
+                return;
+            }
+            const params = { header: { "idempotency-key": options.idempotencyKey } };
+            exitCode = await run((client) => action === "read-all" ? client.PATCH("/v1/notifications/read", { params }) : client.DELETE("/v1/notifications", { params }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Notification bulk command outcome is unknown; retry with the same command key" });
+        });
+    }
+    const notificationPreferences = notification.command("preferences");
+    notificationPreferences.command("get").action(async () => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectProjectReadTokenOperation(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.GET("/v1/notification-preferences"));
+    });
+    notificationPreferences.command("update")
+        .requiredOption("--expected-version <version>", "Opaque preference version returned by get")
+        .requiredOption("--preferences <json>", "JSON category settings; omitted settings remain unchanged", parseNotificationPreferences)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and settings when retrying", parseNotificationUuid)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectProjectReadTokenOperation(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.PATCH("/v1/notification-preferences", { body: options.preferences, params: { header: { "idempotency-key": options.idempotencyKey, "if-match": options.expectedVersion } } }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Notification preference outcome is unknown; retry with the same settings and command key" });
+    });
+    const workItem = program.command("work-item");
+    registerWorkItemAssetCommands(workItem, { dependencies, run, setExitCode: (value) => { exitCode = value; }, rejectWrite: () => rejectTokenWrite(dependencies) });
+    registerWorkItemResourceLinkCommands(workItem, spec, { run, setExitCode: (value) => { exitCode = value; }, canWrite: () => !hasProjectReadToken(dependencies.environment), rejectWrite: () => rejectTokenWrite(dependencies), parseOpaqueVersion, parseLimit: parseSearchLimit });
+    const timeEntry = workItem.command("time-entry").description("Record and read task time entries");
+    timeEntry.command("list")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .option("--limit <limit>", "Maximum results, 1 through 100", parseSearchLimit, 50)
+        .option("--cursor <cursor>", "Opaque cursor returned by the previous page")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/time-entries", { params: { path: { projectId: options.projectId, workItemId: options.workItemId }, query: { limit: options.limit, ...(options.cursor === undefined ? {} : { cursor: options.cursor }) } } }));
+    });
+    timeEntry.command("get")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--entry-id <entryId>", "Time Entry UUID", (value) => { try {
+        return parseTimeEntryUuid(value);
+    }
+    catch {
+        throw invalidArgument("Time Entry ID must be a UUID");
+    } })
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/time-entries/{entryId}", { params: { path: options } }));
+    });
+    for (const action of ["create", "update"]) {
+        const command = timeEntry.command(action)
+            .requiredOption("--project-id <projectId>")
+            .requiredOption("--work-item-id <workItemId>")
+            .requiredOption("--start-time <timestamp>", "ISO date-time with an offset", (value) => { try {
+            return parseTimeEntryTimestamp(value);
+        }
+        catch {
+            throw invalidArgument("Start time must be a valid ISO 8601 timestamp with an offset");
+        } })
+            .option("--end-time <timestamp>", "Omit to start running, or preserve the stored end on update", (value) => { try {
+            return parseTimeEntryTimestamp(value);
+        }
+        catch {
+            throw invalidArgument("End time must be a valid ISO 8601 timestamp with an offset");
+        } })
+            .option("--description <description>", "Optional recorded work description", (value) => { try {
+            return parseTimeEntryDescription(value);
+        }
+        catch {
+            throw invalidArgument("Time Entry description exceeds the allowed limit");
+        } })
+            .requiredOption("--idempotency-key <key>", "Reuse this key and inputs for the same action", (value) => { try {
+            return parseTimeEntryUuid(value);
+        }
+        catch {
+            throw invalidArgument("Command key must be a UUID");
+        } });
+        if (action === "update")
+            command.requiredOption("--entry-id <entryId>", "Time Entry UUID", (value) => { try {
+                return parseTimeEntryUuid(value);
+            }
+            catch {
+                throw invalidArgument("Time Entry ID must be a UUID");
+            } }).requiredOption("--expected-version <version>", "Opaque version returned by SpecFlow", parseOpaqueVersion);
+        command.action(async (options) => {
+            if (hasProjectReadToken(dependencies.environment)) {
+                exitCode = rejectTokenWrite(dependencies);
+                return;
+            }
+            const input = { startTime: options.startTime, ...(options.endTime === undefined ? {} : { endTime: options.endTime }), ...(options.description === undefined ? {} : { description: options.description }) };
+            if (options.endTime !== undefined && Date.parse(options.startTime) > Date.parse(options.endTime))
+                throw invalidArgument("Start time cannot follow end time");
+            const path = { projectId: options.projectId, workItemId: options.workItemId };
+            const header = { "idempotency-key": options.idempotencyKey };
+            exitCode = await run((client) => {
+                if (action === "create")
+                    return client.POST("/v1/projects/{projectId}/work-items/{workItemId}/time-entries", { body: input, params: { path, header } });
+                if (options.entryId === undefined || options.expectedVersion === undefined)
+                    throw new Error("Time Entry update requires its identity and observed version");
+                return client.PATCH("/v1/projects/{projectId}/work-items/{workItemId}/time-entries/{entryId}", { body: input, params: { path: { ...path, entryId: options.entryId }, header: { ...header, "if-match": options.expectedVersion } } });
+            }, { retryTransportOnce: true, ambiguousOutcomeMessage: "Time Entry outcome is unknown; retry the same inputs and command key" });
+        });
+    }
+    const workItemComment = workItem.command("comment").description("Read and manage authored task comments");
+    workItemComment.command("list")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .option("--limit <limit>", "Maximum results, 1 through 100", parseSearchLimit, 50)
+        .option("--cursor <cursor>", "Opaque cursor returned by the previous page")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/comments", {
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId }, query: { limit: options.limit, ...(options.cursor === undefined ? {} : { cursor: options.cursor }) } },
+        }));
+    });
+    workItem.command("discussion").description("Read comments and immutable activity newest first")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .option("--limit <limit>", "Maximum results, 1 through 100", parseSearchLimit, 50)
+        .option("--cursor <cursor>", "Opaque cursor returned by the previous page")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/discussion", {
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId }, query: { limit: options.limit, ...(options.cursor === undefined ? {} : { cursor: options.cursor }) } },
+        }));
+    });
+    workItemComment.command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--content <markdown>", "Markdown comment body, up to 20000 characters", parseCommentContent)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseCommentCommandKey)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/comments", {
+            body: { content: options.content },
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId }, header: { "idempotency-key": options.idempotencyKey } },
+        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Comment creation outcome is unknown; retry with the same inputs and command key" });
+    });
+    workItemComment.command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--comment-id <commentId>", "Identifier returned by comments", parseCommentId)
+        .requiredOption("--content <markdown>", "Markdown comment body, up to 20000 characters", parseCommentContent)
+        .requiredOption("--expected-version <version>", "Opaque comment version returned by SpecFlow", parseOpaqueVersion)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseCommentCommandKey)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/work-items/{workItemId}/comments/{commentId}", {
+            body: { content: options.content },
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId, commentId: options.commentId },
+                header: { "idempotency-key": options.idempotencyKey, "if-match": options.expectedVersion } },
+        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Comment edit outcome is unknown; reread the comment or retry the same inputs and command key" });
+    });
+    workItemComment.command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--comment-id <commentId>", "Identifier returned by comments", parseCommentId)
+        .requiredOption("--expected-version <version>", "Opaque comment version returned by SpecFlow", parseOpaqueVersion)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseCommentCommandKey)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.DELETE("/v1/projects/{projectId}/work-items/{workItemId}/comments/{commentId}", {
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId, commentId: options.commentId },
+                header: { "idempotency-key": options.idempotencyKey, "if-match": options.expectedVersion } },
+        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Comment deletion outcome is unknown; reread the comment or retry the same inputs and command key" });
+    });
+    const workItemRelation = workItem.command("relation").description("Manage subtask, blocking and related task links");
+    workItemRelation.command("list")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}/relations", { params: { path: options } }));
+    });
+    workItemRelation.command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--target-project-id <projectId>", "Target task's current Project", parseProjectId)
+        .requiredOption("--target-work-item-id <workItemId>", "Target task's public identity", parseWorkItemId)
+        .requiredOption("--type <type>", "subtask, blocks or related", (value) => {
+        const result = z.enum(["subtask", "blocks", "related"]).safeParse(value);
+        if (!result.success)
+            throw invalidArgument("Relation type must be subtask, blocks or related");
+        return result.data;
+    })
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseRelationCommandKey)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/relations", {
+            body: { targetProjectId: options.targetProjectId, targetWorkItemId: options.targetWorkItemId, relationType: options.type },
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId }, header: { "idempotency-key": options.idempotencyKey } },
+        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Relation creation outcome is unknown; retry with the same inputs and command key" });
+    });
+    workItemRelation.command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--peer-project-id <projectId>", "Other endpoint's current Project", parseProjectId)
+        .requiredOption("--relation-id <relationId>", "Relation identifier returned by list", (value) => {
+        if (!z.uuid().safeParse(value).success)
+            throw invalidArgument("Relation ID must be a UUID returned by SpecFlow");
+        return value;
+    })
+        .requiredOption("--expected-version <expectedVersion>", "Opaque relation version returned by SpecFlow", parseOpaqueVersion)
+        .requiredOption("--idempotency-key <key>", "Reuse the same key and inputs when retrying", parseRelationCommandKey)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run((client) => client.DELETE("/v1/projects/{projectId}/work-items/{workItemId}/relations/{relationId}", {
+            params: { path: { projectId: options.projectId, workItemId: options.workItemId, relationId: options.relationId },
+                query: { peerProjectId: options.peerProjectId }, header: { "idempotency-key": options.idempotencyKey, "if-match": options.expectedVersion } },
+        }), { retryTransportOnce: true, ambiguousOutcomeMessage: "Relation removal outcome is unknown; retry with the same inputs and command key" });
+    });
+    workItemSelectionFlags(workItem.command("list"))
+        .requiredOption("--project-id <projectId>")
+        .option("--limit <limit>", "Maximum results", parseSearchLimit, 20)
+        .option("--cursor <cursor>")
+        .option("--group-by <field>", "Group the page by field (status)", (value) => {
+        if (value === "status") {
+            return "status";
+        }
+        throw invalidArgument("Work Items can only be grouped by status");
+    })
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items", {
+            params: {
+                path: { projectId: options.projectId },
+                query: {
+                    ...workItemSelectionQuery(options),
+                    ...(options.cursor === undefined
+                        ? {}
+                        : { cursor: options.cursor }),
+                    ...(options.groupBy === undefined
+                        ? {}
+                        : { groupBy: options.groupBy }),
+                    limit: options.limit,
+                },
+            },
+        }));
+    });
+    workItem
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/{workItemId}", {
+            params: { path: options },
+        }));
+    });
+    workItem
+        .command("assignees")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-item-assignees", {
+            params: { path: options },
+        }));
+    });
+    workItem
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--title <title>")
+        .option("--description <description>")
+        .option("--label <labelId>", "Workspace label definition ID; repeat for several labels", collectOption, [])
+        .option("--assignee <assignee>", "Workspace member User ID")
+        .option("--custom-field <fieldId=value>", "Custom Field value as fieldId=value; repeat for several fields", collectOption, [])
+        .option("--priority <priority>", "Work Item priority", parseWorkItemPriority)
+        .option("--start-date <startDate>", "ISO 8601 date", parseWorkItemDate)
+        .option("--due-date <dueDate>", "ISO 8601 date", parseWorkItemDate)
+        .option("--status <status>", "Workflow Column slug or virtual status to create the Work Item in")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items", {
+            body: {
+                ...(options.assignee === undefined
+                    ? {}
+                    : { assigneeId: options.assignee }),
+                ...(options.customField.length === 0
+                    ? {}
+                    : {
+                        customFields: options.customField.map(parseCustomFieldAssignment),
+                    }),
+                ...(options.description === undefined
+                    ? {}
+                    : { description: options.description }),
+                ...(options.label.length === 0 ? {} : { labelIds: [...new Set(options.label)] }),
+                ...(options.dueDate === undefined
+                    ? {}
+                    : { dueDate: options.dueDate }),
+                ...(options.priority === undefined
+                    ? {}
+                    : { priority: options.priority }),
+                ...(options.startDate === undefined
+                    ? {}
+                    : { startDate: options.startDate }),
+                ...(options.status === undefined
+                    ? {}
+                    : { status: options.status }),
+                title: options.title,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item creation outcome is unknown; list Work Items before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--title <title>")
+        .option("--description <description>")
+        .option("--clear-description", "Remove the Work Item description")
+        .option("--priority <priority>", "Work Item priority", parseWorkItemPriority)
+        .option("--start-date <startDate>", "ISO 8601 date", parseWorkItemDate)
+        .option("--due-date <dueDate>", "ISO 8601 date", parseWorkItemDate)
+        .option("--clear-start-date", "Remove the Work Item start date")
+        .option("--clear-due-date", "Remove the Work Item due date")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.title === undefined &&
+            options.description === undefined &&
+            options.clearDescription !== true &&
+            options.priority === undefined &&
+            options.startDate === undefined &&
+            options.dueDate === undefined &&
+            options.clearStartDate !== true &&
+            options.clearDueDate !== true) {
+            throw invalidArgument("Work Item update requires a field change");
+        }
+        if (options.clearDescription === true &&
+            options.description !== undefined) {
+            throw invalidArgument("Work Item update cannot set and clear the description together");
+        }
+        if (options.clearStartDate === true && options.startDate !== undefined) {
+            throw invalidArgument("Work Item update cannot set and clear the start date together");
+        }
+        if (options.clearDueDate === true && options.dueDate !== undefined) {
+            throw invalidArgument("Work Item update cannot set and clear the due date together");
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/work-items/{workItemId}", {
+            body: {
+                ...(options.clearDescription === true
+                    ? { description: null }
+                    : options.description === undefined
+                        ? {}
+                        : { description: options.description }),
+                ...(options.clearDueDate === true
+                    ? { dueDate: null }
+                    : options.dueDate === undefined
+                        ? {}
+                        : { dueDate: options.dueDate }),
+                ...(options.clearStartDate === true
+                    ? { startDate: null }
+                    : options.startDate === undefined
+                        ? {}
+                        : { startDate: options.startDate }),
+                ...(options.priority === undefined
+                    ? {}
+                    : { priority: options.priority }),
+                ...(options.title === undefined
+                    ? {}
+                    : { title: options.title }),
+            },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item update outcome is unknown; read the Work Item before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("assign")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--assignee <assignee>", "Workspace member User ID")
+        .option("--unassign", "Remove the Work Item assignee")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.assignee === undefined && options.unassign !== true) {
+            throw invalidArgument("Work Item assign requires an assignee or --unassign");
+        }
+        if (options.assignee !== undefined && options.unassign === true) {
+            throw invalidArgument("Work Item assign cannot set and clear the assignee together");
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/work-items/{workItemId}/assignee", {
+            body: {
+                assigneeId: options.unassign === true ? null : (options.assignee ?? null),
+            },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item assignment outcome is unknown; read the Work Item before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/work-items/{workItemId}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), { deleted: { workItemId: options.workItemId } }), {
+            ambiguousOutcomeMessage: "Work Item deletion outcome is unknown; list Work Items before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemSelectionFlags(workItem.command("board"))
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-item-board", {
+            params: {
+                path: { projectId: options.projectId },
+                query: workItemSelectionQuery(options),
+            },
+        }));
+    });
+    workItem
+        .command("bulk")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--action <action>", `Bulk action: ${workItemBulkActions.join(", ")}`, parseWorkItemBulkAction)
+        .requiredOption("--target <id@version>", "Target Work Item ID with its observed version, e.g. PAY-1@3; repeat for several Projects in the same Workspace", parseWorkItemBulkTarget, [])
+        .option("--status <status>", "Destination Workflow Column slug or virtual status (updateStatus)")
+        .option("--priority <priority>", "Priority (updatePriority)", parseWorkItemPriority)
+        .option("--assignee <assignee>", "Assignee User ID (updateAssignee)")
+        .option("--unassign", "Clear the assignee (updateAssignee)")
+        .option("--label-id <labelId>", "Work Item Label ID (addLabel/removeLabel)")
+        .option("--due-date <dueDate>", "Due date (updateDueDate)", parseWorkItemDate)
+        .option("--clear-due-date", "Clear the due date (updateDueDate)")
+        .description("Apply one action to several Work Items, which may span Projects inside the same Workspace")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.unassign === true && options.assignee !== undefined) {
+            writeSkillError(dependencies, {
+                message: "--assignee and --unassign cannot be combined for updateAssignee",
+                reason: "Invalid Operation",
+                retryable: false,
+            });
+            exitCode = 1;
+            return;
+        }
+        if (options.clearDueDate === true && options.dueDate !== undefined) {
+            writeSkillError(dependencies, {
+                message: "--due-date and --clear-due-date cannot be combined for updateDueDate",
+                reason: "Invalid Operation",
+                retryable: false,
+            });
+            exitCode = 1;
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/bulk", {
+            body: {
+                action: options.action,
+                ...(options.action === "updateAssignee"
+                    ? options.unassign === true
+                        ? { assigneeId: null }
+                        : options.assignee === undefined
+                            ? {}
+                            : { assigneeId: options.assignee }
+                    : {}),
+                ...(options.action === "updateDueDate"
+                    ? options.clearDueDate === true
+                        ? { dueDate: null }
+                        : options.dueDate === undefined
+                            ? {}
+                            : { dueDate: options.dueDate }
+                    : {}),
+                ...((options.action === "addLabel" ||
+                    options.action === "removeLabel") &&
+                    options.labelId !== undefined
+                    ? { labelId: options.labelId }
+                    : {}),
+                ...(options.action === "updatePriority" &&
+                    options.priority !== undefined
+                    ? { priority: options.priority }
+                    : {}),
+                ...(options.action === "updateStatus" &&
+                    options.status !== undefined
+                    ? { status: options.status }
+                    : {}),
+                workItems: options.target.map((target) => ({
+                    id: target.id,
+                    version: target.expectedVersion,
+                })),
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item bulk outcome is unknown; list Work Items before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("import")
+        .description("Import JSON tasks into the explicit Project; imported labels are reported as skipped")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--file <path>", "JSON task file, at most 1 MiB and 1000 tasks")
+        .requiredOption("--idempotency-key <key>", "Reuse this key with the same file when retrying")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const key = options.idempotencyKey.trim();
+        if (key.length === 0 || key.length > 200) {
+            throw invalidArgument("The import idempotency key must contain 1 to 200 characters");
+        }
+        const body = await readWorkItemImportFile(options.file);
+        if (body === null) {
+            writeSkillError(dependencies, {
+                message: "The import file must be valid task JSON within 1 MiB and 1000 tasks",
+                reason: "Invalid Operation", retryable: false,
+            });
+            exitCode = 2;
+            return;
+        }
+        let failed = 0;
+        exitCode = await run(async (client) => {
+            const result = await client.POST("/v1/projects/{projectId}/work-items/import", {
+                body, params: { header: { "idempotency-key": key }, path: { projectId: options.projectId } },
+            });
+            if (result.data !== undefined) {
+                failed = result.data.results.failed;
+            }
+            return result;
+        }, {
+            ambiguousOutcomeMessage: "Import outcome is unknown; retry the same file and idempotency key",
+            retryTransportOnce: true,
+        });
+        if (exitCode === 0 && failed > 0) {
+            writeSkillError(dependencies, {
+                message: "Some tasks were refused; inspect the per-row results and import only corrected failed rows with a new key",
+                reason: "Invalid Operation", retryable: false,
+            });
+            exitCode = 2;
+        }
+    });
+    workItemSelectionFlags(workItem.command("export"))
+        .description("Export selected readable Project tasks as JSON on stdout")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-items/export", {
+            params: { path: { projectId: options.projectId }, query: workItemSelectionQuery(options) },
+        }));
+    });
+    workItem
+        .command("transfer")
+        .description("Move a Work Item into another Project in its Workspace")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--destination-project-id <projectId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--destination-status <status>", "Destination Workflow Column slug; defaults to the matching or first column")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/transfer", {
+            body: {
+                destinationProjectId: options.destinationProjectId,
+                ...(options.destinationStatus === undefined ? {} : { destinationStatus: options.destinationStatus }),
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey, "if-match": options.expectedVersion },
+                path: { projectId: options.projectId, workItemId: options.workItemId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item transfer outcome is unknown; inspect both Projects before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("move")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .requiredOption("--status <status>", "Destination Workflow Column slug or virtual status")
+        .option("--position <position>", "Board index inside the destination column", parseBoardPosition)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-items/{workItemId}/move", {
+            body: {
+                ...(options.position === undefined
+                    ? {}
+                    : { position: options.position }),
+                status: options.status,
+            },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item move outcome is unknown; read the Work Item board before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItem
+        .command("complete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .description("Move a Work Item into the Project's first final Workflow Column")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run(async (client) => {
+            const board = await client.GET("/v1/projects/{projectId}/work-item-board", { params: { path: { projectId: options.projectId } } });
+            if (!board.response.ok) {
+                return board;
+            }
+            const finalColumn = board.data?.workflowColumns.find((column) => column.isFinal);
+            if (finalColumn === undefined) {
+                return {
+                    error: {
+                        code: "WORKFLOW_COLUMN_NO_FINAL",
+                        message: "The Project has no final Workflow Column; mark a column final or move the Work Item to its slug directly",
+                    },
+                    response: new Response(null, { status: 422 }),
+                };
+            }
+            return await client.POST("/v1/projects/{projectId}/work-items/{workItemId}/move", {
+                body: { status: finalColumn.slug },
+                params: {
+                    header: {
+                        "idempotency-key": idempotencyKey,
+                        "if-match": options.expectedVersion,
+                    },
+                    path: {
+                        projectId: options.projectId,
+                        workItemId: options.workItemId,
+                    },
+                },
+            });
+        }, {
+            ambiguousOutcomeMessage: "Work Item completion outcome is unknown; read the Work Item board before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const workItemLabel = program.command("work-item-label");
+    workItemLabel
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .option("--work-item-id <workItemId>", "List only the labels attached to one Work Item")
+        .action(async (options) => {
+        exitCode = await run((client) => options.workItemId === undefined
+            ? client.GET("/v1/projects/{projectId}/work-item-labels", {
+                params: { path: { projectId: options.projectId } },
+            })
+            : client.GET("/v1/projects/{projectId}/work-items/{workItemId}/labels", {
+                params: {
+                    path: {
+                        projectId: options.projectId,
+                        workItemId: options.workItemId,
+                    },
+                },
+            }));
+    });
+    workItemLabel
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--label-id <labelId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-item-labels/{labelId}", { params: { path: options } }));
+    });
+    workItemLabel
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--name <name>")
+        .requiredOption("--color <color>")
+        .option("--work-item-id <workItemId>", "Create the label directly on the named Work Item instead of the Workspace definition")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-item-labels", {
+            body: {
+                color: options.color,
+                name: options.name,
+                ...(options.workItemId === undefined
+                    ? {}
+                    : { workItemId: options.workItemId }),
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Label creation outcome is unknown; list Work Item Labels before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemLabel
+        .command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--label-id <labelId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--name <name>")
+        .option("--color <color>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.name === undefined && options.color === undefined) {
+            throw invalidArgument("Work Item Label update requires a field change");
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/work-item-labels/{labelId}", {
+            body: {
+                ...(options.color === undefined
+                    ? {}
+                    : { color: options.color }),
+                ...(options.name === undefined ? {} : { name: options.name }),
+            },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    labelId: options.labelId,
+                    projectId: options.projectId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Label update outcome is unknown; read the Work Item Label before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemLabel
+        .command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--label-id <labelId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .description("Delete a Work Item Label; a Workspace definition's task-copy cascade resumes automatically across bounded batches")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run(async (client) => {
+            const request = () => client.DELETE("/v1/projects/{projectId}/work-item-labels/{labelId}", {
+                params: {
+                    header: {
+                        "idempotency-key": idempotencyKey,
+                        "if-match": options.expectedVersion,
+                    },
+                    path: {
+                        labelId: options.labelId,
+                        projectId: options.projectId,
+                    },
+                },
+            });
+            let result = await request();
+            // HTTP 202 marks a definition cascade still in flight; the same
+            // request resumes it, bounded so a runaway copy count stops.
+            for (let attempt = 0; result.response.status === 202 && attempt < 40; attempt += 1) {
+                result = await request();
+            }
+            return withSuccessData(result, {
+                deleted: { labelId: options.labelId },
+            });
+        }, {
+            ambiguousOutcomeMessage: "Work Item Label deletion outcome is unknown; list Work Item Labels before retrying",
+            retryTransportOnce: true,
+            // A bounded 202 stream that never completes is not a success —
+            // report the resumable deletion as retryable instead of printing
+            // the pending payload as if it were done.
+            validateSuccess: (data) => isWorkItemLabelDeletionPending(data)
+                ? {
+                    message: "Work Item Label deletion is still in progress; run the same command again to resume it",
+                    reason: "Temporary Failure",
+                    retryable: true,
+                }
+                : null,
+        });
+    });
+    workItemLabel
+        .command("attach")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--label-id <labelId>")
+        .option("--expected-version <expectedVersion>", "Opaque version of the task copy being moved; required when the Label is already attached elsewhere", parseOpaqueVersion)
+        .description("Attach a Work Item Label to a Work Item as a task-level copy")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/work-items/{workItemId}/labels/{labelId}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    ...(options.expectedVersion === undefined
+                        ? {}
+                        : { "if-match": options.expectedVersion }),
+                },
+                path: {
+                    labelId: options.labelId,
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Label attachment outcome is unknown; list the Work Item's labels before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemLabel
+        .command("detach")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--label-id <labelId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow for the attached copy", parseOpaqueVersion)
+        .description("Detach a Work Item Label copy from a Work Item")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.DELETE("/v1/projects/{projectId}/work-items/{workItemId}/labels/{labelId}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    labelId: options.labelId,
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Label detachment outcome is unknown; list the Work Item's labels before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const workItemCustomField = program.command("work-item-custom-field");
+    workItemCustomField
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-item-custom-fields", {
+            params: { path: options },
+        }));
+    });
+    workItemCustomField
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--name <name>")
+        .requiredOption("--type <type>", "text, number, date, dropdown, or boolean", parseWorkItemCustomFieldType)
+        .option("--option <option>", "Dropdown option; repeat for every choice", collectOption, [])
+        .option("--default-value <defaultValue>")
+        .option("--required", "Reject Work Items that leave the field blank")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/work-item-custom-fields", {
+            body: {
+                ...(options.defaultValue === undefined
+                    ? {}
+                    : { defaultValue: options.defaultValue }),
+                name: options.name,
+                ...(options.option.length === 0
+                    ? {}
+                    : { options: options.option }),
+                ...(options.required === undefined
+                    ? {}
+                    : { required: options.required }),
+                type: options.type,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Custom Field creation outcome is unknown; list Work Item Custom Fields before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemCustomField
+        .command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--field-id <fieldId>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .description("Delete a Work Item Custom Field; its stored values cascade with the definition")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/work-item-custom-fields/{fieldId}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    fieldId: options.fieldId,
+                    projectId: options.projectId,
+                },
+            },
+        }), { deleted: { fieldId: options.fieldId } }), {
+            ambiguousOutcomeMessage: "Work Item Custom Field deletion outcome is unknown; list Work Item Custom Fields before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemCustomField
+        .command("reorder")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--order <order>", "Comma-separated id@version pairs in display order — version is the integer inside the field's opaque \"N\" version")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const fields = parseFieldOrder(options.order);
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/work-item-custom-fields/reorder", {
+            body: { fields },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Custom Field reorder outcome is unknown; list Work Item Custom Fields before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workItemCustomField
+        .command("values")
+        .requiredOption("--project-id <projectId>")
+        .option("--work-item-id <workItemId>", "List only the values stored on one Work Item")
+        .action(async (options) => {
+        exitCode = await run((client) => options.workItemId === undefined
+            ? client.GET("/v1/projects/{projectId}/work-item-custom-field-values", {
+                params: { path: { projectId: options.projectId } },
+            })
+            : client.GET("/v1/projects/{projectId}/work-items/{workItemId}/custom-field-values", {
+                params: {
+                    path: {
+                        projectId: options.projectId,
+                        workItemId: options.workItemId,
+                    },
+                },
+            }));
+    });
+    workItemCustomField
+        .command("filter-values")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/work-item-custom-field-filter-values", { params: { path: options } }));
+    });
+    workItemCustomField
+        .command("set")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--work-item-id <workItemId>")
+        .requiredOption("--field-id <fieldId>")
+        .requiredOption("--expected-version <version>", "The opaque Work Item version returned by SpecFlow")
+        .requiredOption("--value <value>", "Stored value; an empty string clears a non-required field")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const expectedVersion = parseOpaqueVersion(options.expectedVersion);
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/work-items/{workItemId}/custom-field-values/{fieldId}", {
+            body: { value: options.value },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": expectedVersion,
+                },
+                path: {
+                    fieldId: options.fieldId,
+                    projectId: options.projectId,
+                    workItemId: options.workItemId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Work Item Custom Field value outcome is unknown; list the Work Item's Custom Field values before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const workflowColumn = program.command("workflow-column");
+    workflowColumn
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/workflow-columns", {
+            params: { path: options },
+        }));
+    });
+    workflowColumn
+        .command("create")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--name <name>")
+        .option("--icon <icon>", "Column icon name")
+        .option("--color <color>", "Column color")
+        .option("--final", "Mark the column as an explicit completion lane")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/workflow-columns", {
+            body: {
+                ...(options.color === undefined
+                    ? {}
+                    : { color: options.color }),
+                ...(options.final === undefined
+                    ? {}
+                    : { isFinal: options.final }),
+                ...(options.icon === undefined ? {} : { icon: options.icon }),
+                name: options.name,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Workflow Column creation outcome is unknown; list Workflow Columns before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workflowColumn
+        .command("update")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--column-slug <columnSlug>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .option("--name <name>")
+        .option("--icon <icon>", "Column icon name")
+        .option("--color <color>", "Column color")
+        .option("--clear-icon", "Remove the column icon")
+        .option("--clear-color", "Remove the column color")
+        .option("--final", "Mark the column as an explicit completion lane")
+        .option("--not-final", "Remove the column's completion marker")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        if (options.name === undefined &&
+            options.icon === undefined &&
+            options.clearIcon !== true &&
+            options.color === undefined &&
+            options.clearColor !== true &&
+            options.final !== true &&
+            options.notFinal !== true) {
+            throw invalidArgument("Workflow Column update requires a field change");
+        }
+        if (options.clearIcon === true && options.icon !== undefined) {
+            throw invalidArgument("Workflow Column update cannot set and clear the icon together");
+        }
+        if (options.clearColor === true && options.color !== undefined) {
+            throw invalidArgument("Workflow Column update cannot set and clear the color together");
+        }
+        if (options.final === true && options.notFinal === true) {
+            throw invalidArgument("Workflow Column update cannot set and clear the final marker together");
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PATCH("/v1/projects/{projectId}/workflow-columns/{columnSlug}", {
+            body: {
+                ...(options.clearColor === true
+                    ? { color: null }
+                    : options.color === undefined
+                        ? {}
+                        : { color: options.color }),
+                ...(options.clearIcon === true
+                    ? { icon: null }
+                    : options.icon === undefined
+                        ? {}
+                        : { icon: options.icon }),
+                ...(options.final === true
+                    ? { isFinal: true }
+                    : options.notFinal === true
+                        ? { isFinal: false }
+                        : {}),
+                ...(options.name === undefined
+                    ? {}
+                    : { name: options.name }),
+            },
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    columnSlug: options.columnSlug,
+                    projectId: options.projectId,
+                },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Workflow Column update outcome is unknown; list Workflow Columns before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workflowColumn
+        .command("delete")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--column-slug <columnSlug>")
+        .requiredOption("--expected-version <expectedVersion>", "Opaque version returned by SpecFlow", parseOpaqueVersion)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/workflow-columns/{columnSlug}", {
+            params: {
+                header: {
+                    "idempotency-key": idempotencyKey,
+                    "if-match": options.expectedVersion,
+                },
+                path: {
+                    columnSlug: options.columnSlug,
+                    projectId: options.projectId,
+                },
+            },
+        }), { deleted: { columnSlug: options.columnSlug } }), {
+            ambiguousOutcomeMessage: "Workflow Column deletion outcome is unknown; list Workflow Columns before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    workflowColumn
+        .command("reorder")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--order <order>", "Comma-separated slug@version pairs in board order — version is the integer inside the column's opaque \"N\" version")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const columns = parseColumnOrder(options.order);
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.PUT("/v1/projects/{projectId}/workflow-column-order", {
+            body: { columns },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Workflow Column reorder outcome is unknown; list Workflow Columns before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const token = program.command("token");
+    token
+        .command("issue")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--name <name>")
+        .option("--expires-at <expiresAt>", "ISO 8601 expiry date-time", parseIsoDateTime)
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/read-tokens", {
+            body: {
+                expiresAt: options.expiresAt ?? null,
+                name: options.name,
+            },
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: { projectId: options.projectId },
+            },
+        }), {
+            ambiguousOutcomeMessage: "Project Read Token issuance outcome is unknown; list tokens before retrying",
+            retryTransportOnce: true,
+            validateSuccess: validateIssuedProjectReadToken,
+        });
+    });
+    token
+        .command("list")
+        .requiredOption("--project-id <projectId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/read-tokens", {
+            params: { path: { projectId: options.projectId } },
+        }), { rejectProjectReadToken: true });
+    });
+    token
+        .command("revoke")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--token-id <tokenId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        exitCode = await run(async (client) => withSuccessData(await client.DELETE("/v1/projects/{projectId}/read-tokens/{tokenId}", { params: { path: options } }), { revoked: { tokenId: options.tokenId } }), {
+            ambiguousOutcomeMessage: "Project Read Token revocation outcome is unknown; list tokens before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    const review = program.command("review");
+    review
+        .command("request")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--spec-id <specId>")
+        .action(async (options) => {
+        if (hasProjectReadToken(dependencies.environment)) {
+            exitCode = rejectTokenWrite(dependencies);
+            return;
+        }
+        const idempotencyKey = randomUUID();
+        exitCode = await run((client) => client.POST("/v1/projects/{projectId}/specs/{specId}/reviews", {
+            params: {
+                header: { "idempotency-key": idempotencyKey },
+                path: options,
+            },
+        }), {
+            ambiguousOutcomeMessage: "Manual Review request outcome is unknown; inspect Review Records before retrying",
+            retryTransportOnce: true,
+        });
+    });
+    review
+        .command("read")
+        .requiredOption("--project-id <projectId>")
+        .requiredOption("--review-id <reviewId>")
+        .action(async (options) => {
+        exitCode = await run((client) => client.GET("/v1/projects/{projectId}/reviews/{reviewId}", {
+            params: { path: options },
+        }), { rejectProjectReadToken: true });
+    });
+    try {
+        await program.parseAsync([...arguments_], { from: "user" });
+        return exitCode;
+    }
+    catch (cause) {
+        if (cause instanceof CommanderError) {
+            if (cause.code === "commander.helpDisplayed") {
+                return cause.exitCode;
+            }
+            writeSkillError(dependencies, {
+                message: "The command does not match the supported CLI contract",
+                reason: "Invalid Operation",
+                retryable: false,
+            });
+            return 2;
+        }
+        throw cause;
+    }
+}
+async function executeRequest(dependencies, request, options = {}, serverFlag, apiKeyIdFlag) {
+    const environmentCredential = dependencies.environment.SPEC_FLOW_PROJECT_READ_TOKEN;
+    const apiKeyEnvironment = dependencies.environment.SPEC_FLOW_API_KEY;
+    const usesApiKey = apiKeyEnvironment !== undefined || apiKeyIdFlag !== undefined;
+    if (options.requireUserSession === true && (usesApiKey || hasProjectReadToken(dependencies.environment))) {
+        writeSkillError(dependencies, { message: "A User Session is required for account management", reason: "Permission Denied", retryable: false });
+        return 3;
+    }
+    if ((apiKeyEnvironment !== undefined && apiKeyIdFlag !== undefined) || (usesApiKey && hasProjectReadToken(dependencies.environment))) {
+        writeSkillError(dependencies, { message: "Select exactly one API Key or Project Read Token credential", reason: "Invalid Operation", retryable: false });
+        return 2;
+    }
+    if (apiKeyIdFlag !== undefined && !z.uuid().safeParse(apiKeyIdFlag).success) {
+        writeSkillError(dependencies, { message: "API Key ID must be a UUID", reason: "Invalid Operation", retryable: false });
+        return 2;
+    }
+    if (apiKeyEnvironment !== undefined && !/^sfk_[A-Za-z0-9_-]{43}$/u.test(apiKeyEnvironment)) {
+        writeSkillError(dependencies, { message: "SPEC_FLOW_API_KEY does not contain a User API Key", reason: "Authentication Failed", retryable: false });
+        return 2;
+    }
+    if (options.rejectProjectReadToken === true &&
+        hasProjectReadToken(dependencies.environment)) {
+        return rejectProjectReadTokenOperation(dependencies);
+    }
+    const baseUrl = resolveApiOrigin(dependencies, serverFlag);
+    if (baseUrl === null) {
+        return 2;
+    }
+    let credential;
+    try {
+        if (apiKeyEnvironment !== undefined)
+            credential = apiKeyEnvironment;
+        else if (typeof apiKeyIdFlag === "string") {
+            if (dependencies.credentialStore.readApiKey === undefined)
+                throw new Error("API Key storage is unavailable");
+            credential = await dependencies.credentialStore.readApiKey(apiKeyIdFlag.toLowerCase());
+        }
+        else {
+            credential = environmentCredential === undefined || environmentCredential.trim().length === 0
+                ? await dependencies.credentialStore.read() : environmentCredential;
+        }
+    }
+    catch {
+        writeSkillError(dependencies, {
+            message: "The CLI credential store is temporarily unavailable",
+            reason: "Temporary Failure",
+            retryable: true,
+        });
+        return 4;
+    }
+    if (credential === null || credential.trim().length === 0) {
+        writeSkillError(dependencies, {
+            message: "An authenticated CLI Session, User API Key or Project Read Token is required",
+            reason: "Authentication Failed",
+            retryable: false,
+        });
+        return 2;
+    }
+    const client = createClient({
+        baseUrl,
+        ...(usesApiKey || options.requireUserSession === true ? { redirect: "error" } : {}),
+        fetch: options.retryTransportOnce === true
+            ? retryTransportOnce(dependencies.fetch)
+            : dependencies.fetch,
+        headers: {
+            ...(usesApiKey ? { "x-api-key": credential } : { authorization: `Bearer ${credential}` }),
+            "user-agent": specFlowCliUserAgent,
+        },
+    });
+    try {
+        const result = await request(client);
+        if (result.response.ok && result.data !== undefined) {
+            const validationError = options.validateSuccess?.(result.data) ?? null;
+            if (validationError !== null) {
+                writeSkillError(dependencies, validationError);
+                return skillErrorExitCode(validationError);
+            }
+            dependencies.stdout(`${JSON.stringify(result.data)}\n`);
+            return 0;
+        }
+        if (result.response.ok && options.retryTransportOnce === true) {
+            const error = ambiguousMutationError(options.ambiguousOutcomeMessage);
+            writeSkillError(dependencies, error);
+            return skillErrorExitCode(error);
+        }
+        const error = mapHttpFailure(result.response, result.error);
+        writeSkillError(dependencies, error);
+        return skillErrorExitCode(error);
+    }
+    catch {
+        const error = options.retryTransportOnce === true
+            ? ambiguousMutationError(options.ambiguousOutcomeMessage)
+            : {
+                message: "SpecFlow is temporarily unavailable",
+                reason: "Temporary Failure",
+                retryable: true,
+            };
+        writeSkillError(dependencies, error);
+        return skillErrorExitCode(error);
+    }
+}
+function retryTransportOnce(fetch) {
+    return async (request) => {
+        const retryRequest = request.clone();
+        try {
+            return await fetch(request);
+        }
+        catch {
+            return fetch(retryRequest);
+        }
+    };
+}
+function ambiguousMutationError(message) {
+    return {
+        message: message ??
+            "Project creation outcome is unknown; run project list before trying a new create",
+        reason: "Temporary Failure",
+        retryable: false,
+    };
+}
+function validateIssuedProjectReadToken(data) {
+    if (typeof data === "object" &&
+        data !== null &&
+        "credential" in data &&
+        data.credential === null) {
+        return {
+            message: "Project Read Token issuance completed, but its credential cannot be recovered; list or revoke the token before deliberately issuing another",
+            reason: "Temporary Failure",
+            retryable: false,
+        };
+    }
+    return null;
+}
+function resolveApiOrigin(dependencies, serverFlag) {
+    const flag = typeof serverFlag === "string" ? serverFlag : undefined;
+    const result = parseHttpOrigin(unresolvedSpecFlowApiOrigin(flag, dependencies.environment.SPEC_FLOW_API_URL));
+    if (result.valid) {
+        return result.origin;
+    }
+    writeSkillError(dependencies, {
+        message: flag === undefined
+            ? "SPEC_FLOW_API_URL must be an HTTP(S) origin without a path"
+            : "--server must be an HTTP(S) origin without a path",
+        reason: "Invalid Operation",
+        retryable: false,
+    });
+    return null;
+}
+function parseRelationCommandKey(value) {
+    const key = value.trim();
+    if (key.length === 0 || key.length > 200)
+        throw invalidArgument("Relation command key must contain 1 to 200 characters");
+    return key;
+}
+function parseSearchLimit(value) {
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new CommanderError(1, "commander.invalidArgument", "Search limit must be an integer from 1 to 100");
+    }
+    return limit;
+}
+function parseFindingStatus(value) {
+    if (value === "Confirmed" ||
+        value === "Dismissed" ||
+        value === "Proposed" ||
+        value === "Resolved" ||
+        value === "Stale") {
+        return value;
+    }
+    throw invalidArgument("Finding status is not supported");
+}
+function parseProjectStatus(value) {
+    if (value === "Active" || value === "Archived" || value === "Trashed") {
+        return value;
+    }
+    throw new CommanderError(1, "commander.invalidArgument", "Project status must be Active, Archived, or Trashed");
+}
+function parseProjectId(value) {
+    const normalized = value.trim().toUpperCase();
+    if (/^[A-Z]{2,10}$/u.test(normalized)) {
+        return normalized;
+    }
+    throw invalidArgument("Project ID must contain 2-10 letters");
+}
+function parseSpecId(value) {
+    const normalized = value.trim().toUpperCase();
+    if (/^[A-Z]{2,10}-[1-9]\d*$/u.test(normalized)) {
+        return normalized;
+    }
+    throw invalidArgument("Spec ID must be a Project ID followed by a positive number");
+}
+function parseWorkItemId(value) {
+    const normalized = value.trim().toUpperCase();
+    if (/^[A-Z]{2,10}-[1-9]\d*$/u.test(normalized)) {
+        return normalized;
+    }
+    throw invalidArgument("Work Item ID must be a Project ID followed by a positive number");
+}
+const workItemPriorities = [
+    "no-priority",
+    "low",
+    "medium",
+    "high",
+    "urgent",
+];
+function parseWorkItemPriority(value) {
+    const normalized = value.trim().toLowerCase();
+    if (workItemPriorities.includes(normalized)) {
+        return normalized;
+    }
+    throw invalidArgument("Work Item priority must be no-priority, low, medium, high, or urgent");
+}
+function parseWorkItemDate(value) {
+    if (z.iso.date().safeParse(value).success ||
+        z.iso.datetime().safeParse(value).success) {
+        return value;
+    }
+    throw invalidArgument("Work Item dates must be an ISO 8601 date or date-time");
+}
+const workItemDueDateFilters = [
+    "dueThisWeek",
+    "dueNextWeek",
+    "noDueDate",
+];
+const workItemQuerySortFields = [
+    "createdAt",
+    "dueDate",
+    "number",
+    "position",
+    "priority",
+    "title",
+];
+const workItemSortOrders = ["asc", "desc"];
+function parseWorkItemDueFilter(value) {
+    if (workItemDueDateFilters.includes(value)) {
+        return value;
+    }
+    throw invalidArgument("Due filter must be dueThisWeek, dueNextWeek, or noDueDate");
+}
+function parseWorkItemSortField(value) {
+    if (workItemQuerySortFields.includes(value)) {
+        return value;
+    }
+    throw invalidArgument("Work Item sort must be createdAt, dueDate, number, position, priority, or title");
+}
+function parseWorkItemSortOrder(value) {
+    if (workItemSortOrders.includes(value)) {
+        return value;
+    }
+    throw invalidArgument("Work Item sort order must be asc or desc");
+}
+/**
+ * Builds the wire selection query shared by `work-item list` and
+ * `work-item board`: repeatable flags become the API's CSV fields and
+ * repeated `fieldId=value` pairs merge into the `customFields` JSON map.
+ */
+function workItemSelectionQuery(options) {
+    const customFields = {};
+    for (const entry of options.customField) {
+        const { fieldId, value } = parseCustomFieldAssignment(entry);
+        customFields[fieldId] = [...(customFields[fieldId] ?? []), value];
+    }
+    return {
+        ...(options.assignee.length === 0
+            ? {}
+            : { assignee: options.assignee.join(",") }),
+        ...(Object.keys(customFields).length === 0
+            ? {}
+            : { customFields: JSON.stringify(customFields) }),
+        ...(options.due.length === 0 ? {} : { due: options.due.join(",") }),
+        ...(options.dueAfter === undefined ? {} : { dueAfter: options.dueAfter }),
+        ...(options.dueBefore === undefined
+            ? {}
+            : { dueBefore: options.dueBefore }),
+        ...(options.label.length === 0 ? {} : { label: options.label.join(",") }),
+        ...(options.priority.length === 0
+            ? {}
+            : { priority: options.priority.join(",") }),
+        ...(options.search === undefined ? {} : { search: options.search }),
+        ...(options.sort === undefined ? {} : { sortBy: options.sort }),
+        ...(options.order === undefined ? {} : { sortOrder: options.order }),
+        ...(options.startAfter === undefined
+            ? {}
+            : { startAfter: options.startAfter }),
+        ...(options.startBefore === undefined
+            ? {}
+            : { startBefore: options.startBefore }),
+        ...(options.status.length === 0
+            ? {}
+            : { status: options.status.join(",") }),
+    };
+}
+/**
+ * The selection options `work-item list` and `work-item board` share.
+ * Attach with `workItemSelectionFlags(command)`.
+ */
+function workItemSelectionFlags(command) {
+    return command
+        .option("--assignee <assignee>", "Filter by assignee User ID, or unassigned for items with none; repeat for several", collectOption, [])
+        .option("--custom-field <fieldId=value>", "Filter by Custom Field value; repeat to OR values or combine fields", collectOption, [])
+        .option("--due <filter>", "Filter by due bucket: dueThisWeek, dueNextWeek, or noDueDate; repeat for several", (value, previous) => [
+        ...previous,
+        parseWorkItemDueFilter(value),
+    ], [])
+        .option("--due-after <date>", "Filter due on/after", parseWorkItemDate)
+        .option("--due-before <date>", "Filter due on/before", parseWorkItemDate)
+        .option("--label <labelId>", "Filter by Work Item Label ID; repeat for several", collectOption, [])
+        .option("--priority <priority>", "Filter by priority; repeat for several", (value, previous) => [
+        ...previous,
+        parseWorkItemPriority(value),
+    ], [])
+        .option("--search <search>", "Filter by title search text")
+        .option("--sort <field>", "Sort by field", parseWorkItemSortField)
+        .option("--order <order>", "Sort order", parseWorkItemSortOrder)
+        .option("--start-after <date>", "Filter start on/after", parseWorkItemDate)
+        .option("--start-before <date>", "Filter start on/before", parseWorkItemDate)
+        .option("--status <status>", "Filter by Workflow Column slug or virtual status; repeat for several", collectOption, []);
+}
+function parseWorkItemBulkAction(value) {
+    if (workItemBulkActions.includes(value)) {
+        return value;
+    }
+    throw invalidArgument(`Bulk action must be ${workItemBulkActions.join(", ")}`);
+}
+/**
+ * A bulk target is `WORKITEM@version` — the public id and its observed
+ * version, echoed back as the `"N"` precondition each item carries.
+ */
+function parseWorkItemBulkTarget(value, previous) {
+    const [id, version, extra] = value.split("@");
+    if (id === undefined ||
+        version === undefined ||
+        extra !== undefined ||
+        !/^[A-Z]{2,10}-[1-9]\d*$/u.test(id.trim().toUpperCase()) ||
+        !/^[1-9]\d*$/u.test(version)) {
+        throw invalidArgument(`Bulk target "${value}" must be a WORK-ITEM-ID@version pair`);
+    }
+    const numericVersion = Number(version);
+    if (!Number.isSafeInteger(numericVersion) ||
+        numericVersion > 2_147_483_647) {
+        throw invalidArgument(`Bulk target "${value}" has a version outside the supported range`);
+    }
+    return [
+        ...previous,
+        { expectedVersion: `"${version}"`, id: id.trim().toUpperCase() },
+    ];
+}
+function parseBoardPosition(value) {
+    const position = Number(value);
+    if (!Number.isInteger(position) ||
+        position < 0 ||
+        position > 2_147_483_646) {
+        throw invalidArgument("Board position must be a nonnegative integer within the supported range");
+    }
+    return position;
+}
+/**
+ * Comma-separated `slug@version` pairs become the verbatim board order —
+ * position equals list index, matching the reorder contract, and each
+ * version is the column's observed version sent as its reorder
+ * precondition.
+ */
+function parseColumnOrder(value) {
+    const entries = value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (entries.length === 0 || entries.length > 200) {
+        throw invalidArgument("Workflow Column order must list between 1 and 200 slug@version pairs");
+    }
+    const parsed = entries.map((entry, position) => {
+        const [slug, version, extra] = entry.split("@");
+        if (slug === undefined ||
+            version === undefined ||
+            extra !== undefined ||
+            !/^[1-9]\d*$/u.test(version)) {
+            throw invalidArgument(`Workflow Column order entry "${entry}" must be a slug@version pair`);
+        }
+        return { expectedVersion: `"${version}"`, position, slug };
+    });
+    const slugs = parsed.map((entry) => entry.slug);
+    if (new Set(slugs).size !== slugs.length) {
+        throw invalidArgument("Workflow Column order cannot repeat a slug");
+    }
+    return parsed;
+}
+const workItemCustomFieldTypes = [
+    "text",
+    "number",
+    "date",
+    "dropdown",
+    "boolean",
+];
+function parseWorkItemCustomFieldType(value) {
+    const normalized = value.trim().toLowerCase();
+    if (workItemCustomFieldTypes.includes(normalized)) {
+        return normalized;
+    }
+    throw invalidArgument("Custom Field type must be text, number, date, dropdown, or boolean");
+}
+function collectOption(value, previous) {
+    return [...previous, value];
+}
+/**
+ * A `fieldId=value` assignment splits on the first `=` so values may carry
+ * the separator; the field id itself is an opaque server identity.
+ */
+function parseCustomFieldAssignment(value) {
+    const separator = value.indexOf("=");
+    const fieldId = separator === -1 ? "" : value.slice(0, separator).trim();
+    if (fieldId.length === 0 || fieldId.length > 200) {
+        throw invalidArgument("Custom Field values must be written as fieldId=value");
+    }
+    const fieldValue = value.slice(separator + 1);
+    if (fieldValue.length > 2_000) {
+        throw invalidArgument("Custom Field values must stay within the supported length");
+    }
+    return { fieldId, value: fieldValue };
+}
+/**
+ * Comma-separated `id@version` pairs become the verbatim display order —
+ * position equals list index, matching the reorder contract, and each
+ * version is the field's observed version sent as its reorder
+ * precondition.
+ */
+function parseFieldOrder(value) {
+    const entries = value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (entries.length === 0 || entries.length > 500) {
+        throw invalidArgument("Custom Field order must list between 1 and 500 id@version pairs");
+    }
+    const parsed = entries.map((entry, position) => {
+        const [id, version, extra] = entry.split("@");
+        if (id === undefined ||
+            version === undefined ||
+            extra !== undefined ||
+            !/^[1-9]\d*$/u.test(version)) {
+            throw invalidArgument(`Custom Field order entry "${entry}" must be an id@version pair`);
+        }
+        return { expectedVersion: `"${version}"`, id, position };
+    });
+    const ids = parsed.map((entry) => entry.id);
+    if (new Set(ids).size !== ids.length) {
+        throw invalidArgument("Custom Field order cannot repeat a field id");
+    }
+    return parsed;
+}
+function parseOpaqueVersion(value) {
+    if (/^"[1-9]\d*"$/u.test(value)) {
+        return value;
+    }
+    throw invalidArgument("Expected version must be the opaque version returned by SpecFlow");
+}
+function parseIsoDateTime(value) {
+    if (z.iso.datetime().safeParse(value).success) {
+        return value;
+    }
+    throw invalidArgument("Expiry must be an ISO 8601 date-time");
+}
+function parseSpecState(value) {
+    if (value === "Ready" || value === "Unavailable") {
+        return value;
+    }
+    throw invalidArgument("Spec State must be Ready or Unavailable");
+}
+function parseSourceReferences(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument("Source References must be valid JSON");
+    }
+    const sourceReferences = sourceReferencesInputSchema.safeParse(parsed);
+    if (!sourceReferences.success) {
+        throw invalidArgument("Source References do not match the supported bounded contract");
+    }
+    return sourceReferences.data.map((reference) => ({
+        ...(reference.externalRevision === undefined
+            ? {}
+            : { externalRevision: reference.externalRevision }),
+        ...(reference.section === undefined ? {} : { section: reference.section }),
+        title: reference.title,
+        url: reference.url,
+    }));
+}
+function invalidArgument(message) {
+    return new CommanderError(1, "commander.invalidArgument", message);
+}
+function parseGlossaryEntries(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new CommanderError(1, "commander.invalidArgument", "Glossary Entries must be valid JSON");
+    }
+    const entries = glossaryEntriesInputSchema.safeParse(parsed);
+    if (!entries.success) {
+        throw new CommanderError(1, "commander.invalidArgument", "Glossary Entries do not match the supported contract");
+    }
+    return entries.data;
+}
+function parseStringArray(value, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument(`${label} must be valid JSON`);
+    }
+    const result = z.array(z.string().trim().min(1).max(200)).max(500).safeParse(parsed);
+    if (!result.success) {
+        throw invalidArgument(`${label} must be a bounded JSON string array`);
+    }
+    return result.data;
+}
+function toAgentProvenance(options) {
+    return {
+        ...(options.agentRevision === undefined
+            ? {}
+            : { agentRevision: options.agentRevision }),
+        ...(options.agentModel === undefined ? {} : { model: options.agentModel }),
+        sourceReferenceIds: options.sourceReferenceIds === undefined
+            ? []
+            : parseStringArray(options.sourceReferenceIds, "source reference IDs"),
+    };
+}
+function parseRoleStatements(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument("Role statements must be valid JSON");
+    }
+    const statements = roleStatementsInputSchema.safeParse(parsed);
+    if (!statements.success) {
+        throw invalidArgument("Role statements must map permission resources to non-empty action arrays");
+    }
+    return statements.data;
+}
+function parseProposalTargetKind(value) {
+    if (value === "Glossary" || value === "Spec") {
+        return value;
+    }
+    throw invalidArgument("Proposal target kind must be Spec or Glossary");
+}
+function parseProposalStatus(value) {
+    if (value === "Applied" || value === "Discarded" || value === "Open") {
+        return value;
+    }
+    throw invalidArgument("Proposal status must be Open, Applied, or Discarded");
+}
+function parseFindingInput(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument("Finding input must be valid JSON");
+    }
+    const finding = findingCreateInputSchema.safeParse(parsed);
+    if (!finding.success) {
+        throw invalidArgument("Finding input does not match the supported contract");
+    }
+    return finding.data;
+}
+function withSuccessData(result, data) {
+    return result.response.ok && result.data === undefined
+        ? { ...result, data }
+        : result;
+}
+/**
+ * Whether a `work-item-label delete` payload is the still-running cascade —
+ * the 202 body carries the definition with its deletion boundary set.
+ */
+function isWorkItemLabelDeletionPending(data) {
+    if (typeof data !== "object" || data === null || !("workItemLabel" in data)) {
+        return false;
+    }
+    const label = data.workItemLabel;
+    return (typeof label === "object" &&
+        label !== null &&
+        label.deletionStartedAt !==
+            null &&
+        label.deletionStartedAt !==
+            undefined);
+}
+function rejectTokenWrite(dependencies) {
+    if (hasProjectReadToken(dependencies.environment)) {
+        writeSkillError(dependencies, {
+            message: "Project Read Token does not permit write operations",
+            reason: "Permission Denied",
+            retryable: false,
+        });
+        return 3;
+    }
+    writeSkillError(dependencies, {
+        message: "An authenticated CLI Session is required",
+        reason: "Authentication Failed",
+        retryable: false,
+    });
+    return 2;
+}
+function rejectProjectReadTokenOperation(dependencies) {
+    writeSkillError(dependencies, {
+        message: "Project Read Token does not permit this operation",
+        reason: "Permission Denied",
+        retryable: false,
+    });
+    return 3;
+}
+function hasProjectReadToken(environment) {
+    const credential = environment.SPEC_FLOW_PROJECT_READ_TOKEN;
+    return credential !== undefined && credential.trim().length > 0;
+}
+function mapHttpFailure(response, payload) {
+    const { status } = response;
+    const serverMessage = readServerMessage(payload);
+    const serverCode = readServerCode(payload);
+    if (status === 401) {
+        return {
+            message: serverMessage ?? "Project Read Token is invalid, expired, or revoked",
+            reason: "Authentication Failed",
+            retryable: false,
+        };
+    }
+    if (status === 403) {
+        return {
+            message: serverMessage ?? "Project Read Token does not permit this operation",
+            reason: "Permission Denied",
+            retryable: false,
+        };
+    }
+    if (status === 404) {
+        if (serverCode === "PROJECT_NOT_ACCESSIBLE") {
+            return {
+                message: serverMessage ?? "The Project is not accessible",
+                reason: "Project Not Accessible",
+                retryable: false,
+            };
+        }
+        return {
+            message: serverMessage ?? "The requested Project resource was not found",
+            reason: "Resource Not Found",
+            retryable: false,
+        };
+    }
+    if (status === 409 && serverCode === "RESOURCE_CHANGED") {
+        return {
+            message: serverMessage ?? "The Working Draft changed after the Proposal baseline",
+            reason: "Resource Changed",
+            retryable: false,
+        };
+    }
+    if (status === 400 || status === 409 || status === 422) {
+        const diagnostics = readServerDiagnostics(payload);
+        return {
+            ...(diagnostics === undefined ? {} : { diagnostics }),
+            message: serverMessage ?? "The requested operation is invalid",
+            reason: "Invalid Operation",
+            retryable: false,
+        };
+    }
+    if (status === 412) {
+        return {
+            message: serverMessage ?? "The resource changed after it was read",
+            reason: "Resource Changed",
+            retryable: false,
+        };
+    }
+    if (status === 429) {
+        const retryAfter = response.headers.get("retry-after");
+        return {
+            message: serverMessage ?? "SpecFlow is temporarily throttling this client",
+            reason: "Temporary Failure",
+            ...(retryAfter === null ? {} : { retryAfter }),
+            retryable: true,
+        };
+    }
+    return {
+        message: serverMessage ?? "SpecFlow is temporarily unavailable",
+        reason: "Temporary Failure",
+        retryable: status >= 500,
+    };
+}
+function readServerMessage(payload) {
+    return typeof payload === "object" &&
+        payload !== null &&
+        "message" in payload &&
+        typeof payload.message === "string"
+        ? payload.message
+        : null;
+}
+function readServerCode(payload) {
+    return typeof payload === "object" &&
+        payload !== null &&
+        "code" in payload &&
+        typeof payload.code === "string"
+        ? payload.code
+        : null;
+}
+function readServerDiagnostics(payload) {
+    if (typeof payload !== "object" ||
+        payload === null ||
+        !("diagnostics" in payload) ||
+        !Array.isArray(payload.diagnostics)) {
+        return undefined;
+    }
+    const diagnostics = payload.diagnostics.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null) {
+            return [];
+        }
+        const { column, line, message, reason } = entry;
+        if (typeof reason !== "string" || typeof message !== "string") {
+            return [];
+        }
+        return [
+            {
+                ...(typeof column === "number" ? { column } : {}),
+                ...(typeof line === "number" ? { line } : {}),
+                message,
+                reason,
+            },
+        ];
+    });
+    return diagnostics.length === 0 ? undefined : diagnostics;
+}
+function skillErrorExitCode(error) {
+    if (error.reason === "Permission Denied") {
+        return 3;
+    }
+    return error.reason === "Temporary Failure" ? 4 : 2;
+}
+function writeSkillError(dependencies, error) {
+    dependencies.stderr(`${JSON.stringify({ error })}\n`);
+}
+function parseCommentContent(value) {
+    const result = z.string().trim().min(1).max(20_000).refine((content) => !content.includes("\0")).safeParse(value);
+    if (!result.success)
+        throw invalidArgument("Comment content must contain 1 through 20000 characters without null characters");
+    return result.data;
+}
+function parseCommentId(value) {
+    if (!z.uuid().safeParse(value).success)
+        throw invalidArgument("Comment ID must be a UUID returned by SpecFlow");
+    return value;
+}
+function parseCommentCommandKey(value) {
+    if (!z.uuid().safeParse(value).success)
+        throw invalidArgument("Comment command key must be a UUID; reuse the same key and inputs when retrying");
+    return value;
+}
+function parseNotificationUuid(value) {
+    if (!z.uuid().safeParse(value).success)
+        throw invalidArgument("Notification identity and command keys must be UUIDs");
+    return value;
+}
+function parseNotificationEventData(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument("Notification event data must be a JSON object");
+    }
+    const result = z.record(z.string(), z.json()).safeParse(parsed);
+    if (!result.success)
+        throw invalidArgument("Notification event data must be a JSON object");
+    return result.data;
+}
+function parseNotificationPreferences(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalidArgument("Notification preferences must be a JSON object");
+    }
+    const result = z.object({ taskAssignmentEnabled: z.boolean().optional(), taskCommentEnabled: z.boolean().optional(), taskStatusChangeEnabled: z.boolean().optional(), dueDateReminderEnabled: z.boolean().optional(), dueDateReminderMinutes: z.number().int().min(5).max(43200).optional() }).strict().safeParse(parsed);
+    if (!result.success)
+        throw invalidArgument("Notification preferences contain unsupported settings or invalid values");
+    const data = result.data;
+    return { ...(data.taskAssignmentEnabled === undefined ? {} : { taskAssignmentEnabled: data.taskAssignmentEnabled }), ...(data.taskCommentEnabled === undefined ? {} : { taskCommentEnabled: data.taskCommentEnabled }), ...(data.taskStatusChangeEnabled === undefined ? {} : { taskStatusChangeEnabled: data.taskStatusChangeEnabled }), ...(data.dueDateReminderEnabled === undefined ? {} : { dueDateReminderEnabled: data.dueDateReminderEnabled }), ...(data.dueDateReminderMinutes === undefined ? {} : { dueDateReminderMinutes: data.dueDateReminderMinutes }) };
+}
+//# sourceMappingURL=cli.js.map