@jam-mcp/server 1.0.0 → 1.1.0

package/dist/application/plan-write.js

@@ -0,0 +1,167 @@
+import { JamError } from "../domain/errors.js";
+import { assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+/**
+ * Work out whether a requested change is currently possible, and describe it.
+ *
+ * Reads only. Nothing here mutates Jira, and that is the whole point of the
+ * step: the agent gets to see what the issue looks like now, what JAM would
+ * do to it, and what a direct read will have to show before JAM will call it
+ * done - all before anything has happened.
+ *
+ * The order matters. Scope and operation are checked before any Jira call, so
+ * an out-of-scope key costs nothing and comes back as a JAM refusal rather
+ * than a 404. Everything after that is derived from the issue as Jira reports
+ * it right now, never from what the caller asserted about it.
+ */
+export async function planWrite(deps, request) {
+    const issueKey = request.key.trim().toUpperCase();
+    const projectKey = assertWriteScope(issueKey, deps.config.project.key);
+    const operation = assertOperationAllowed(request.operation);
+    // Everything that can be refused from the request alone is refused here,
+    // before a Jira call is spent on it. An agent asking to write a field JAM
+    // does not write should get that answer, not a round trip and then that
+    // answer.
+    const input = validateInput(operation, request.input);
+    const issue = await readIssue(deps, issueKey);
+    const { before, intendedAfter, mutation, transition } = await describe(deps, operation, issueKey, issue, input);
+    const createdAt = new Date();
+    const plan = deps.writePlans.create({
+        issueKey,
+        projectKey,
+        operation,
+        before,
+        intendedAfter,
+        baseUpdated: issue.updated,
+        createdAt: createdAt.toISOString(),
+        expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
+        ...(transition ? { transition } : {}),
+        mutation,
+    });
+    return {
+        plan,
+        receipt: {
+            status: "planned",
+            planId: plan.planId,
+            issue: plan.issueKey,
+            operation: plan.operation,
+            before: plan.before,
+            intendedAfter: plan.intendedAfter,
+            expiresAt: plan.expiresAt,
+            verification: { method: "direct-issue-read", expects: plan.intendedAfter },
+        },
+    };
+}
+/**
+ * The issue as Jira has it, read directly by key.
+ *
+ * A direct read, never a search: ConsistencyPolicy requires it for anything
+ * that decides a write, and a JQL result can lag behind the issue it describes.
+ */
+export async function readIssue(deps, issueKey) {
+    const { issues } = await deps.jira.getIssues({
+        keys: [issueKey],
+        fields: ["summary", "status", "priority", "labels", "components", "updated"],
+    });
+    const issue = issues[0];
+    if (!issue) {
+        throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
+    }
+    return issue;
+}
+/**
+ * Check the request against the contract, and normalize it.
+ *
+ * Pure: no Jira, no state. Whether an operation is supported, whether a field
+ * is writable and whether the input is even the right shape are all knowable
+ * without asking Jira anything, so they are answered first.
+ */
+function validateInput(operation, raw) {
+    switch (operation) {
+        case "comment.add": {
+            const text = raw.text;
+            if (typeof text !== "string" || text.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "comment.add needs non-empty `input.text`.", { operation });
+            }
+            return { text: text.trim() };
+        }
+        case "field.update":
+            return assertFieldsAllowed(raw);
+        case "status.transition": {
+            const status = raw.status;
+            if (typeof status !== "string" || status.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "status.transition needs non-empty `input.status`.", { operation });
+            }
+            return { status: status.trim() };
+        }
+    }
+}
+async function describe(deps, operation, issueKey, issue, input) {
+    switch (operation) {
+        case "comment.add": {
+            const { text } = input;
+            // Comments accumulate rather than replace, so `before` says what is
+            // there now by count - the plan is not claiming to know the thread.
+            return {
+                before: { comments: issue.comments.length },
+                intendedAfter: { commentAdded: text },
+                mutation: { kind: "comment", text },
+            };
+        }
+        case "field.update": {
+            const fields = input;
+            const before = {};
+            const after = {};
+            for (const [field, value] of Object.entries(fields)) {
+                before[field] = currentValue(issue, field);
+                after[field] = value;
+            }
+            return {
+                before,
+                intendedAfter: after,
+                mutation: { kind: "fields", fields: toJiraFields(fields) },
+            };
+        }
+        case "status.transition": {
+            const { status: target } = input;
+            // Ask Jira what is reachable rather than deriving an id from a name:
+            // transition ids are per-workflow, and a guessed one either fails or
+            // moves the issue somewhere nobody asked for.
+            const available = await deps.jiraWrite.getTransitions(issueKey);
+            const transition = resolveTransition(target, available);
+            return {
+                before: { status: issue.status },
+                intendedAfter: { status: transition.to },
+                mutation: { kind: "transition", transitionId: transition.id },
+                transition,
+            };
+        }
+    }
+}
+function currentValue(issue, field) {
+    switch (field) {
+        case "summary":
+            return issue.summary;
+        case "priority":
+            return issue.priority;
+        case "labels":
+            return issue.labels;
+        case "components":
+            return issue.components;
+        default:
+            return undefined;
+    }
+}
+/** Whitelisted values to the shapes Jira's field API expects. */
+function toJiraFields(input) {
+    const fields = {};
+    if (input.summary !== undefined)
+        fields["summary"] = input.summary;
+    if (input.priority !== undefined)
+        fields["priority"] = { name: input.priority };
+    if (input.labels !== undefined)
+        fields["labels"] = input.labels;
+    if (input.components !== undefined) {
+        fields["components"] = input.components.map((name) => ({ name }));
+    }
+    return fields;
+}

package/dist/application/write-plan-store.d.ts

@@ -0,0 +1,42 @@
+import type { WritePlan } from "../domain/write.js";
+/**
+ * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
+ *
+ * In this process, and nowhere else. The alternative considered was a signed
+ * self-contained token, and it is worse here on both counts that matter: the
+ * signing key would have to come from somewhere (a new secret on disk, or a
+ * per-process key that gives the token exactly this lifetime anyway), and the
+ * mutation would have to travel through the agent to come back. Keeping the
+ * mutation in memory makes forgery impossible rather than merely hard - a
+ * `planId` is an opaque handle, and what it names never leaves this process.
+ *
+ * The cost is that plans do not survive a restart. That is acceptable: a plan
+ * is only valid while the issue has not moved, so a stale one was going to be
+ * rejected on its own terms, and re-planning is a single read.
+ *
+ * See docs/decisions/adr-jira-write-plane.md.
+ */
+export declare class WritePlanStore {
+    private readonly now;
+    private readonly plans;
+    /** Injected by tests so expiry does not depend on wall-clock timing. */
+    constructor(now?: () => Date);
+    create(plan: Omit<WritePlan, "planId">): WritePlan;
+    /**
+     * Resolve a plan for applying.
+     *
+     * An expired plan is reported as expired rather than as missing: those are
+     * different situations, and telling them apart is the difference between
+     * "re-plan" and "you are calling this wrong".
+     */
+    take(planId: string): WritePlan;
+    /**
+     * Retire a plan once it has been applied.
+     *
+     * Single use, so a receipt cannot be turned into a second mutation by
+     * calling apply again with the same id - which for `comment.add` would mean
+     * two comments.
+     */
+    consume(planId: string): void;
+    private evictExpired;
+}

package/dist/application/write-plan-store.js

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import { JamError } from "../domain/errors.js";
+import { planExpired } from "../policy/write-policy.js";
+/**
+ * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
+ *
+ * In this process, and nowhere else. The alternative considered was a signed
+ * self-contained token, and it is worse here on both counts that matter: the
+ * signing key would have to come from somewhere (a new secret on disk, or a
+ * per-process key that gives the token exactly this lifetime anyway), and the
+ * mutation would have to travel through the agent to come back. Keeping the
+ * mutation in memory makes forgery impossible rather than merely hard - a
+ * `planId` is an opaque handle, and what it names never leaves this process.
+ *
+ * The cost is that plans do not survive a restart. That is acceptable: a plan
+ * is only valid while the issue has not moved, so a stale one was going to be
+ * rejected on its own terms, and re-planning is a single read.
+ *
+ * See docs/decisions/adr-jira-write-plane.md.
+ */
+export class WritePlanStore {
+    now;
+    plans = new Map();
+    /** Injected by tests so expiry does not depend on wall-clock timing. */
+    constructor(now = () => new Date()) {
+        this.now = now;
+    }
+    create(plan) {
+        this.evictExpired();
+        const stored = { ...plan, planId: randomUUID() };
+        this.plans.set(stored.planId, stored);
+        return stored;
+    }
+    /**
+     * Resolve a plan for applying.
+     *
+     * An expired plan is reported as expired rather than as missing: those are
+     * different situations, and telling them apart is the difference between
+     * "re-plan" and "you are calling this wrong".
+     */
+    take(planId) {
+        const plan = this.plans.get(planId);
+        if (!plan) {
+            throw new JamError("JAM_WRITE_PLAN_NOT_FOUND", "No such write plan. Plans live in the running JAM server and do not survive a restart - call jira_write_plan again.", { planId });
+        }
+        if (planExpired(plan.expiresAt, this.now())) {
+            this.plans.delete(planId);
+            throw new JamError("JAM_WRITE_PLAN_EXPIRED", `This write plan expired at ${plan.expiresAt}. Re-plan against the current state of ${plan.issueKey}.`, { planId, issueKey: plan.issueKey, expiresAt: plan.expiresAt });
+        }
+        return plan;
+    }
+    /**
+     * Retire a plan once it has been applied.
+     *
+     * Single use, so a receipt cannot be turned into a second mutation by
+     * calling apply again with the same id - which for `comment.add` would mean
+     * two comments.
+     */
+    consume(planId) {
+        this.plans.delete(planId);
+    }
+    evictExpired() {
+        const now = this.now();
+        for (const [id, plan] of this.plans) {
+            if (planExpired(plan.expiresAt, now))
+                this.plans.delete(id);
+        }
+    }
+}

package/dist/bootstrap/boot-health-gate.js

@@ -1,5 +1,5 @@
 import { toJamError } from "../domain/errors.js";
-import { createServer } from "../mcp/create-server.js";
+import { createServer, TOOL_COUNT } from "../mcp/create-server.js";
 /**
  * One health-check core shared by `jam doctor`, `jam setup` and `jam serve`.
  *
@@ -60,7 +60,7 @@ export async function runHealthGate(deps, mode) {
     });
     try {
         createServer(deps);
-        add({ name: "MCP server startup", ok: true, fatal: true, detail: "3 tools registered" });
+        add({ name: "MCP server startup", ok: true, fatal: true, detail: `${TOOL_COUNT} tools registered` });
     }
     catch (err) {
         add({ name: "MCP server startup", ok: false, fatal: true, detail: toJamError(err).message });

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -1,3 +1,4 @@
+import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 /**
  * The canonical jam entry for a project's `.mcp.json`.
  *
@@ -9,10 +10,10 @@
  * Pinned to an exact version. A floating tag would silently change what a
  * teammate's editor launches.
  */
-export declare const LAUNCHER_PACKAGE_SPEC = "@jam-mcp/launcher@1.0.0";
+export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.0.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.1.0", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one
@@ -48,11 +49,11 @@ export declare function inspectMcpConfig(root: string): McpInspection;
  */
 export declare function writeJamMcpEntry(root: string, entry?: unknown): string;
 /**
- * Merge a PATH-based JAM entry into `.mcp.json`, preserving everything else.
+ * Merge the launcher entry into `.mcp.json`, preserving everything else.
  *
- * Deliberately does NOT record an absolute path to this JAM checkout - that
- * would break the moment a teammate clones to a different location. `command:
- * "jam"` relies on `jam` being on PATH (see `jam setup`'s PATH check), which is
- * what keeps this file safe to commit and share.
+ * Deliberately records neither an absolute path to a JAM checkout nor a bare
+ * `jam` - the first breaks the moment a teammate clones somewhere else, and
+ * the second assumes an optional global install every teammate would have to
+ * have made. `npx` at an exact launcher version assumes only npm.
  */
 export declare function mergeMcpConfig(root: string): McpMergeResult;

package/dist/bootstrap/mcp-config-merger.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { SERVER_VERSION } from "@jam-mcp/launcher";
+import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 /**
  * The canonical jam entry for a project's `.mcp.json`.
  *
@@ -12,7 +12,7 @@ import { SERVER_VERSION } from "@jam-mcp/launcher";
  * Pinned to an exact version. A floating tag would silently change what a
  * teammate's editor launches.
  */
-export const LAUNCHER_PACKAGE_SPEC = `@jam-mcp/launcher@${SERVER_VERSION}`;
+export { LAUNCHER_PACKAGE_SPEC };
 export const JAM_MCP_ENTRY = {
     command: "npx",
     args: ["--yes", LAUNCHER_PACKAGE_SPEC, "serve"],
@@ -86,12 +86,12 @@ export function writeJamMcpEntry(root, entry = JAM_MCP_ENTRY) {
     return path;
 }
 /**
- * Merge a PATH-based JAM entry into `.mcp.json`, preserving everything else.
+ * Merge the launcher entry into `.mcp.json`, preserving everything else.
  *
- * Deliberately does NOT record an absolute path to this JAM checkout - that
- * would break the moment a teammate clones to a different location. `command:
- * "jam"` relies on `jam` being on PATH (see `jam setup`'s PATH check), which is
- * what keeps this file safe to commit and share.
+ * Deliberately records neither an absolute path to a JAM checkout nor a bare
+ * `jam` - the first breaks the moment a teammate clones somewhere else, and
+ * the second assumes an optional global install every teammate would have to
+ * have made. `npx` at an exact launcher version assumes only npm.
  */
 export function mergeMcpConfig(root) {
     const path = join(root, ".mcp.json");

package/dist/bootstrap/setup-plan.d.ts

@@ -57,6 +57,14 @@ export type SetupPlan = {
     }[];
     /** Why a requested migration was refused, when status is JAM_MIGRATION_TARGET_UNAVAILABLE. */
     migrationTarget?: MigrationTarget;
+    /**
+     * What a person or an agent has to do next.
+     *
+     * `command` is executable on a machine with nothing installed and no runtime
+     * configured - so it is an `npx` bootstrap invocation, never a bare `jam`.
+     * A human interface is free to render the short form; this field is the one
+     * a script runs, and a script has no PATH to rely on.
+     */
     nextAction?: {
         type: "authenticate" | "select_project" | "configure_runtime";
         command?: string;

package/dist/bootstrap/setup-plan.js

@@ -3,6 +3,7 @@ import { CONFIG_RELATIVE_PATH } from "../config/load-config.js";
 import { hostRegistration } from "./host-mcp.js";
 import { projectBindingsPath } from "./project-bindings.js";
 import { decideProjectKey } from "./project-config-bootstrapper.js";
+import { portableBootstrapCommand } from "@jam-mcp/launcher";
 /**
  * Decide what setup would do, changing nothing.
  *
@@ -47,7 +48,7 @@ export function computeSetupPlan(state, options = {}) {
             code: "JAM_PROJECT_SELECTION_REQUIRED",
             changes: [],
             requiresUserAction: true,
-            nextAction: { type: "select_project", command: "jam setup --project <KEY>" },
+            nextAction: { type: "select_project", command: portableBootstrapCommand("setup --project <KEY>") },
             project: { root: state.project.root },
         };
     }
@@ -122,7 +123,7 @@ function finish(changes, state, project) {
             code: "JAM_RUNTIME_CONFIG_MISSING",
             changes,
             requiresUserAction: true,
-            nextAction: { type: "configure_runtime", command: "jam runtime use package" },
+            nextAction: { type: "configure_runtime", command: portableBootstrapCommand("runtime use package") },
             project,
         };
     }

package/dist/cli/setup-wizard.js

@@ -133,7 +133,7 @@ async function chooseRuntime(ui, options) {
         {
             value: "package",
             label: "Use JAM",
-            hint: "Run the project-pinned package. Recommended for most users.",
+            hint: "Run the published JAM release. Recommended for most users.",
         },
         { value: "development", label: "Develop JAM", hint: "Run a local source checkout." },
     ], "Run: jam runtime use package");

package/dist/cli-entry.js

@@ -11,39 +11,39 @@ import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyComm
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export const USAGE = `jam - Jira Agent MCP
-
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
-  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
-                          alone, writing nothing to the repository; --shared
-                          adopts JAM for the team (project.yaml, .mcp.json)
-  jam runtime             Show which JAM build this machine runs
-  jam runtime use package | development <path>
-                          Change it (writes ~/.jam/config.yaml only, never a project)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
-
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
-
-Environment:
-  JIRA_BASE_URL     https://your-site.atlassian.net
-  JIRA_EMAIL        Atlassian account email
-  JIRA_API_TOKEN    Atlassian API token
-  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
-                     .jira-agent/project.yaml exists yet
-
-Credentials and JAM_PROJECT_KEY are read from the current shell's environment
-first, then (on Windows) from the User environment - so a value set with
-\`setx\` works without opening a new terminal.
+export const USAGE = `jam - Jira Agent MCP
+
+Usage:
+  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
+  jam doctor              Diagnose config, credentials and Jira connectivity
+  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
+                          Wire up this project and run doctor. Binds it to you
+                          alone, writing nothing to the repository; --shared
+                          adopts JAM for the team (project.yaml, .mcp.json)
+  jam runtime             Show which JAM build this machine runs
+  jam runtime use package | development <path>
+                          Change it (writes ~/.jam/config.yaml only, never a project)
+  jam auth login          Store Jira credentials in this user's OS secret store
+  jam auth logout         Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam doctor --json       Health check as structured output
+  jam auth status --json  Whether Jira credentials are configured (never their value)
+
+Environment:
+  JIRA_BASE_URL     https://your-site.atlassian.net
+  JIRA_EMAIL        Atlassian account email
+  JIRA_API_TOKEN    Atlassian API token
+  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
+                     .jira-agent/project.yaml exists yet
+
+Credentials and JAM_PROJECT_KEY are read from the current shell's environment
+first, then (on Windows) from the User environment - so a value set with
+\`setx\` works without opening a new terminal.
 `;
 function findFlagValue(argv, flag) {
     const index = argv.indexOf(flag);

package/dist/deps.d.ts

@@ -4,6 +4,8 @@ import type { ProjectConfig } from "./config/schema.js";
 import type { CachePort } from "./ports/cache.port.js";
 import type { CredentialPort } from "./ports/credentials.port.js";
 import type { JiraReadPort } from "./ports/jira-read.port.js";
+import type { JiraWritePort } from "./ports/jira-write.port.js";
+import { WritePlanStore } from "./application/write-plan-store.js";
 import type { TelemetryPort } from "./ports/telemetry.port.js";
 /** Everything the application layer is allowed to reach for. */
 export type JamDeps = {
@@ -12,6 +14,17 @@ export type JamDeps = {
     /** Where the project key came from when no config file supplied one. */
     keySource?: BootstrapSource;
     jira: JiraReadPort;
+    /**
+     * The mutating half. Separate from `jira` on purpose: reading and writing
+     * have different retry rules and different confirmation rules, and one port
+     * that did both would blur them.
+     */
+    jiraWrite: JiraWritePort;
+    /**
+     * Plans awaiting apply. Lives for the life of this server process - see
+     * WritePlanStore for why it is not persisted.
+     */
+    writePlans: WritePlanStore;
     cache: CachePort;
     telemetry: TelemetryPort;
     credentials: CredentialPort;
@@ -20,6 +33,8 @@ export type BuildDepsOptions = {
     cwd?: string;
     /** Injected by tests to bypass the real REST adapter. */
     jira?: JiraReadPort;
+    /** Injected by tests so no test can reach a real Jira write endpoint. */
+    jiraWrite?: JiraWritePort;
     /** Injected by tests to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**

package/dist/deps.js

@@ -2,6 +2,7 @@ import { NoopCache } from "./adapters/cache/noop-cache.js";
 import { CompositeCredentialProvider } from "./adapters/credentials/composite.js";
 import { ConsoleTelemetry } from "./adapters/telemetry/console-telemetry.js";
 import { resolveProjectConfig } from "./bootstrap/project-config-resolver.js";
+import { WritePlanStore } from "./application/write-plan-store.js";
 /**
  * Single composition root. `jam serve`, `jam doctor` and `jam setup` all wire
  * through here, so a doctor pass actually proves the server's configuration.
@@ -27,11 +28,18 @@ export async function buildDeps(options = {}) {
         const { JiraCloudReadAdapter } = await import("./adapters/jira-cloud/jira-read.adapter.js");
         jira = new JiraCloudReadAdapter(credentials, resolved.config);
     }
+    let jiraWrite = options.jiraWrite;
+    if (!jiraWrite) {
+        const { JiraCloudWriteAdapter } = await import("./adapters/jira-cloud/jira-write.adapter.js");
+        jiraWrite = new JiraCloudWriteAdapter(credentials);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
         keySource: resolved.keySource,
         jira,
+        jiraWrite,
+        writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,
         credentials,

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -17,6 +17,19 @@ export const JAM_ERROR_CODES = [
     "JIRA_UNAVAILABLE",
     "JAM_SETUP_REQUIRED",
     "JAM_BINDINGS_UNREADABLE",
+    // Write plane. Each names a distinct decision an agent has to make, which is
+    // why none of them collapse into CONFIG_INVALID: "you may not write there",
+    // "someone else moved it", and "we could not confirm it happened" call for
+    // three different next steps.
+    "JAM_WRITE_SCOPE_VIOLATION",
+    "JAM_WRITE_OPERATION_NOT_ALLOWED",
+    "JAM_WRITE_FIELD_NOT_ALLOWED",
+    "JAM_WRITE_TRANSITION_NOT_AVAILABLE",
+    "JAM_WRITE_PLAN_NOT_FOUND",
+    "JAM_WRITE_PLAN_EXPIRED",
+    "JAM_WRITE_CONFLICT",
+    "JAM_WRITE_VERIFICATION_FAILED",
+    "JAM_WRITE_UNCERTAIN",
 ];
 export class JamError extends Error {
     code;