@jam-mcp/server 1.0.1 → 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

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.0.1", "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

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;

package/dist/domain/write.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The write contract.
+ *
+ * JAM's write plane is not a Jira REST proxy. An agent cannot hand JAM a
+ * mutation and have it forwarded; it describes an intent, JAM works out whether
+ * that intent is currently possible, and only a plan JAM itself produced can be
+ * applied. Everything in this file exists to keep that shape: a closed set of
+ * operations, a fixed field whitelist, and a plan that records what the issue
+ * looked like when the plan was made.
+ *
+ * Read semantics are deliberately not reused here. A read result's `meta`
+ * answers "how complete was this retrieval"; a write result answers "did this
+ * change happen, and did we see it happen". Mixing them would let a confident
+ * `complete: true` stand in for a verified mutation.
+ */
+/** The operations the public MCP surface accepts. Nothing else is reachable. */
+export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition"];
+export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
+/**
+ * Fields `field.update` may touch.
+ *
+ * A whitelist rather than an open field map: an open map turns every
+ * project-specific screen, custom field and permission quirk into a runtime
+ * surprise, and makes "what can an agent change" unanswerable. Custom fields
+ * and assignee are deliberately absent - both need resolution work (schema
+ * discovery, accountId lookup) that belongs in its own round.
+ */
+export declare const WRITABLE_FIELDS: readonly ["summary", "priority", "labels", "components"];
+export type WritableField = (typeof WRITABLE_FIELDS)[number];
+export type CommentAddInput = {
+    text: string;
+};
+export type FieldUpdateInput = {
+    summary?: string;
+    priority?: string;
+    labels?: string[];
+    components?: string[];
+};
+export type StatusTransitionInput = {
+    status: string;
+};
+export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput;
+/** A transition as Jira currently offers it for one issue. */
+export type JiraTransition = {
+    id: string;
+    name: string;
+    /** The status this transition leads to, as Jira names it. */
+    to: string;
+};
+/**
+ * What a plan captured, and what it intends.
+ *
+ * `baseUpdated` is the issue's `updated` timestamp at plan time. Apply re-reads
+ * the issue and refuses when it has moved: a plan that was valid is not the
+ * same as a plan that is still valid.
+ */
+export type WritePlan = {
+    planId: string;
+    issueKey: string;
+    projectKey: string;
+    operation: WriteOperation;
+    /** Only the fields this operation touches. */
+    before: Record<string, unknown>;
+    intendedAfter: Record<string, unknown>;
+    baseUpdated: string;
+    createdAt: string;
+    expiresAt: string;
+    /**
+     * The transition Jira offered for this target status, resolved at plan time.
+     * Present only for `status.transition` - a transition id is never guessed
+     * from a status name.
+     */
+    transition?: JiraTransition;
+    /** Normalized payload the apply step will send. Never supplied by a caller. */
+    mutation: WriteMutation;
+};
+/** What apply will actually send. Produced by planning, never by an agent. */
+export type WriteMutation = {
+    kind: "comment";
+    text: string;
+} | {
+    kind: "fields";
+    fields: Record<string, unknown>;
+} | {
+    kind: "transition";
+    transitionId: string;
+};
+/** What `jira_write_plan` returns. The mutation itself is not exposed. */
+export type WritePlanReceipt = {
+    status: "planned";
+    planId: string;
+    issue: string;
+    operation: WriteOperation;
+    before: Record<string, unknown>;
+    intendedAfter: Record<string, unknown>;
+    expiresAt: string;
+    /** How the result of applying this plan will be confirmed. */
+    verification: {
+        method: "direct-issue-read";
+        /** What a direct read must show before JAM calls the write applied. */
+        expects: Record<string, unknown>;
+    };
+};
+/** What `jira_write_apply` returns once a direct read has confirmed the change. */
+export type WriteApplyReceipt = {
+    status: "applied";
+    issue: string;
+    operation: WriteOperation;
+    before: Record<string, unknown>;
+    after: Record<string, unknown>;
+    /** Always true in an `applied` receipt - an unverified write is an error. */
+    verified: true;
+    /** Present for `comment.add`: the comment Jira created. */
+    commentId?: string;
+};
+export declare function isWriteOperation(value: string): value is WriteOperation;
+export declare function isWritableField(value: string): value is WritableField;

package/dist/domain/write.js

@@ -0,0 +1,33 @@
+/**
+ * The write contract.
+ *
+ * JAM's write plane is not a Jira REST proxy. An agent cannot hand JAM a
+ * mutation and have it forwarded; it describes an intent, JAM works out whether
+ * that intent is currently possible, and only a plan JAM itself produced can be
+ * applied. Everything in this file exists to keep that shape: a closed set of
+ * operations, a fixed field whitelist, and a plan that records what the issue
+ * looked like when the plan was made.
+ *
+ * Read semantics are deliberately not reused here. A read result's `meta`
+ * answers "how complete was this retrieval"; a write result answers "did this
+ * change happen, and did we see it happen". Mixing them would let a confident
+ * `complete: true` stand in for a verified mutation.
+ */
+/** The operations the public MCP surface accepts. Nothing else is reachable. */
+export const WRITE_OPERATIONS = ["comment.add", "field.update", "status.transition"];
+/**
+ * Fields `field.update` may touch.
+ *
+ * A whitelist rather than an open field map: an open map turns every
+ * project-specific screen, custom field and permission quirk into a runtime
+ * surprise, and makes "what can an agent change" unanswerable. Custom fields
+ * and assignee are deliberately absent - both need resolution work (schema
+ * discovery, accountId lookup) that belongs in its own round.
+ */
+export const WRITABLE_FIELDS = ["summary", "priority", "labels", "components"];
+export function isWriteOperation(value) {
+    return WRITE_OPERATIONS.includes(value);
+}
+export function isWritableField(value) {
+    return WRITABLE_FIELDS.includes(value);
+}

package/dist/mcp/create-server.d.ts

@@ -1,9 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { JamDeps } from "../deps.js";
 export declare const SERVER_NAME = "jam";
+export declare const TOOL_COUNT: number;
 /**
- * The external contract: exactly three read tools, stable from the first
- * release. Internal changes (cache, Rovo, remote transport) must not add or
- * rename anything here.
+ * The external contract: three read tools and two write tools.
+ *
+ * The read three have been stable since the first release and do not change.
+ * The write pair is a single operation split in half on purpose - deciding and
+ * doing are separate calls, so an agent cannot mutate Jira without first
+ * having been shown what it is about to change. Internal changes (cache, Rovo,
+ * remote transport) must not add or rename anything here.
  */
 export declare function createServer(deps: JamDeps): McpServer;