@jam-mcp/server 1.3.0 → 1.3.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 colosair
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 colosair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,86 +1,90 @@
-# @jam-mcp/server
-
-JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
-
-JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
-should not be making — which fields to request, when to paginate, when to read
-the comment thread, what to do when a result is too big — so everyday reads stay
-cheap and important judgements still get full context.
-
-## The tools
-
-The external contract is five tools. Adding or renaming one is a breaking
-change.
-
-| Tool | Use it for |
-|---|---|
-| `jira_search` | listing, discovery, "what's open", picking candidates |
-| `jira_context` | readiness, blockers, dependencies, priority |
-| `jira_full` | agreement, contract, approval, closure |
-| `jira_write_plan` | work out how to change an issue — changes nothing |
-| `jira_write_apply` | apply a plan, then confirm it by reading the issue back |
-
-A `jira_search` result is never complete issue context — nothing about
-agreement, approval, or done-ness follows from it.
-
-Writing is deliberately two calls. `jira_write_apply` takes a `planId` and no
-payload, so a change cannot be made that JAM has not first read the issue for,
-checked against the configured project, and described. Before writing it
-re-reads the issue and refuses if it moved; after writing it reads again and
-refuses to report success unless the intended result is actually there. An
-ambiguous failure is reported as uncertain rather than retried — retrying a
-write that may have landed is how one comment becomes two.
-
-Three operations: `comment.add` (plain text, converted to ADF here),
-`field.update` (summary, priority, labels, components), and `status.transition`
-(matched against the transitions Jira currently offers, never a guessed id).
-
-## Evidence boundary
-
-Every result carries a `meta` block, and nothing is ever truncated silently.
-
-`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
-is not a statement about the project: not readiness, not "unblocked", not "the
-whole story". What JAM did not look at is named in the same block —
-`evidenceScope` and `limitations` call out the repository, external sources, and
-dependencies that live outside Jira. `provenance` and `source` say where the
-records came from.
-
-So an empty comment thread on a complete read is a complete read *of Jira*, not
-proof that nothing was agreed. If the issue points at an external canonical
-source, that source is what settles the question.
-
-## Running it
-
-Don't install this package to use JAM. Your coding agent launches
-[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
-reads your `~/.jam/config.yaml`, decides which JAM build this machine should
-run, and dispatches here. Naming the server directly instead pins one machine
-to one build and bypasses that choice — and it is what keeps a committed
-`.mcp.json` free of machine-specific paths.
-
-The same binary carries the CLI, and every command below is reachable through
-the launcher:
-
-```text
-serve        Run the MCP server over stdio
-doctor       Diagnose config, credentials and Jira connectivity
-setup        Wire up JAM and verify (personal by default; --shared for the team)
-auth login   Store Jira credentials in this user's OS secret store
-runtime      Show or change which JAM build this machine runs
-```
-
-Written out, that is `npx --yes @jam-mcp/launcher@1.3.0 doctor`, or just `jam
-doctor` if you took the launcher's optional global install. Starting from
-nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.3.0 init` instead.
-
-Credentials come from the process environment or this user's OS secret store —
-never from a repository file — and never appear in logs, telemetry, or tool
-results. `stdout` is reserved for the MCP protocol and for JSON output;
-diagnostics go to `stderr`.
-
-## More
-
-- [Repository README](https://github.com/colosair/jam#readme)
-- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)
+# @jam-mcp/server
+
+JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
+
+JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
+should not be making — which fields to request, when to paginate, when to read
+the comment thread, what to do when a result is too big — so everyday reads stay
+cheap and important judgements still get full context.
+
+## The tools
+
+The external contract is five tools. Adding or renaming one is a breaking
+change.
+
+| Tool | Use it for |
+|---|---|
+| `jira_search` | listing, discovery, "what's open", picking candidates |
+| `jira_context` | readiness, blockers, dependencies, priority |
+| `jira_full` | agreement, contract, approval, closure |
+| `jira_write_plan` | work out how to change an issue — changes nothing |
+| `jira_write_apply` | apply a plan, then confirm it by reading the issue back |
+
+A `jira_search` result is never complete issue context — nothing about
+agreement, approval, or done-ness follows from it.
+
+Writing is deliberately two calls. `jira_write_apply` takes a `planId` and no
+payload, so a change cannot be made that JAM has not first read the issue for,
+checked against the configured project, and described. Before writing it
+re-reads the issue and refuses if it moved; after writing it reads again and
+refuses to report success unless the intended result is actually there. An
+ambiguous failure is reported as uncertain rather than retried — retrying a
+write that may have landed is how one comment becomes two.
+
+Five operations: `comment.add` (plain text, converted to ADF here),
+`field.update` (summary, priority, labels, components), `status.transition`
+(matched against the transitions Jira currently offers, never a guessed id),
+`assignee.update` (resolved to an account by exact display name or accountId,
+never a substring match), and `issue.create` (planned against the project's own
+create schema, so an unavailable issue type is a refusal here rather than a
+Jira 400 later).
+
+## Evidence boundary
+
+Every result carries a `meta` block, and nothing is ever truncated silently.
+
+`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
+is not a statement about the project: not readiness, not "unblocked", not "the
+whole story". What JAM did not look at is named in the same block —
+`evidenceScope` and `limitations` call out the repository, external sources, and
+dependencies that live outside Jira. `provenance` and `source` say where the
+records came from.
+
+So an empty comment thread on a complete read is a complete read *of Jira*, not
+proof that nothing was agreed. If the issue points at an external canonical
+source, that source is what settles the question.
+
+## Running it
+
+Don't install this package to use JAM. Your coding agent launches
+[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
+reads your `~/.jam/config.yaml`, decides which JAM build this machine should
+run, and dispatches here. Naming the server directly instead pins one machine
+to one build and bypasses that choice — and it is what keeps a committed
+`.mcp.json` free of machine-specific paths.
+
+The same binary carries the CLI, and every command below is reachable through
+the launcher:
+
+```text
+serve        Run the MCP server over stdio
+doctor       Diagnose config, credentials and Jira connectivity
+setup        Wire up JAM and verify (personal by default; --shared for the team)
+auth login   Store Jira credentials in this user's OS secret store
+runtime      Show or change which JAM build this machine runs
+```
+
+Written out, that is `npx --yes @jam-mcp/launcher@1.3.2 doctor`, or just `jam
+doctor` if you took the launcher's optional global install. Starting from
+nothing — no install, no runtime chosen yet — use
+`npx --yes @jam-mcp/bootstrap@1.3.2 init` instead.
+
+Credentials come from the process environment or this user's OS secret store —
+never from a repository file — and never appear in logs, telemetry, or tool
+results. `stdout` is reserved for the MCP protocol and for JSON output;
+diagnostics go to `stderr`.
+
+## More
+
+- [Repository README](https://github.com/colosair/jam#readme)
+- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.d.ts

@@ -0,0 +1,25 @@
+import type { EditFieldMetadata } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraEditMetadataPort } from "../../ports/jira-edit-metadata.port.js";
+/**
+ * Jira Cloud REST v3 edit metadata for one issue.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
+ * whether a mutation may proceed and what shape it takes, so a
+ * retried-and-stale answer is worse than a failure - the same argument that
+ * keeps `getTransitions`, the create metadata calls and the assignability
+ * check on the non-retrying side.
+ *
+ * Jira keys the response by field id, and describes each field with a `schema`
+ * and a list of `operations`. Both travel, because both are what the decision
+ * is made in; the rest of the document does not.
+ *
+ * Anything JAM cannot read is dropped rather than half-understood. A field
+ * that survives here with the wrong shape would be a field JAM claims to
+ * understand well enough to write.
+ */
+export declare class JiraCloudEditMetadataAdapter implements JiraEditMetadataPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
+}

package/dist/adapters/jira-cloud/jira-edit-metadata.adapter.js

@@ -0,0 +1,84 @@
+import { JiraClient } from "./jira-client.js";
+/**
+ * Jira Cloud REST v3 edit metadata for one issue.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta`, `retry: false`. Its answer decides
+ * whether a mutation may proceed and what shape it takes, so a
+ * retried-and-stale answer is worse than a failure - the same argument that
+ * keeps `getTransitions`, the create metadata calls and the assignability
+ * check on the non-retrying side.
+ *
+ * Jira keys the response by field id, and describes each field with a `schema`
+ * and a list of `operations`. Both travel, because both are what the decision
+ * is made in; the rest of the document does not.
+ *
+ * Anything JAM cannot read is dropped rather than half-understood. A field
+ * that survives here with the wrong shape would be a field JAM claims to
+ * understand well enough to write.
+ */
+export class JiraCloudEditMetadataAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async getEditableFields(issueKey) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(issueKey)}/editmeta`,
+            retry: false,
+        });
+        const fields = data?.fields;
+        if (!fields || typeof fields !== "object")
+            return [];
+        return Object.entries(fields)
+            .map(([id, raw]) => toEditField(id, raw))
+            .filter((f) => f !== undefined);
+    }
+}
+function toEditField(id, raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    // A field with no schema type is a field JAM cannot classify, and an
+    // unclassifiable field is one it must not decide it can write.
+    const type = typeof raw.schema?.type === "string" ? raw.schema.type : undefined;
+    if (!type)
+        return undefined;
+    const allowed = toOptions(raw.allowedValues);
+    return {
+        id,
+        name: typeof raw.name === "string" ? raw.name : id,
+        required: raw.required === true,
+        operations: Array.isArray(raw.operations)
+            ? raw.operations.filter((op) => typeof op === "string")
+            : [],
+        schema: {
+            type,
+            ...(typeof raw.schema?.items === "string" ? { items: raw.schema.items } : {}),
+            ...(typeof raw.schema?.custom === "string" ? { custom: raw.schema.custom } : {}),
+            ...(typeof raw.schema?.customId === "number" ? { customId: raw.schema.customId } : {}),
+        },
+        ...(allowed ? { allowedValues: allowed } : {}),
+    };
+}
+/**
+ * The options Jira offers, when it constrains the field at all.
+ *
+ * Absent and empty mean different things and stay apart: absent is "Jira did
+ * not constrain this", empty is "Jira constrains it and offers nothing". The
+ * first permits a free value, the second permits none.
+ *
+ * Jira labels an option `value` on a select and `name` on some other pickers.
+ * Both are read; an option with neither an id nor a label is dropped, because
+ * it can be neither chosen nor recognised afterwards.
+ */
+function toOptions(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw
+        .map((entry) => {
+        const o = entry;
+        const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : undefined;
+        const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : undefined;
+        return id && label ? { id, label } : undefined;
+    })
+        .filter((o) => o !== undefined);
+}

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.3.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.2", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one

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

@@ -64,10 +64,21 @@ export type SetupPlan = {
      * 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.
+     *
+     * `userCommand` is the opposite: a command for the person, which the agent
+     * relays and never runs. Authentication is the only step of that shape, and
+     * it carries no `command` precisely so that no caller can execute it. The
+     * separation is the point - one field is for running, the other for showing.
+     *
+     * `env` names the variables that would satisfy the same requirement without
+     * the interactive command, so an agent that cannot show a prompt still knows
+     * what the person has to provide - never their values.
      */
     nextAction?: {
         type: "authenticate" | "select_project" | "configure_runtime";
         command?: string;
+        userCommand?: string;
+        env?: string[];
     };
     project?: {
         root: string;

package/dist/bootstrap/setup-plan.js

@@ -113,7 +113,16 @@ function finish(changes, state, project) {
             code: "JAM_AUTH_REQUIRED",
             changes,
             requiresUserAction: true,
-            nextAction: { type: "authenticate" },
+            nextAction: {
+                type: "authenticate",
+                // Deliberately no `command`: an agent must not run the login, and the
+                // absence is what stops it. `userCommand` is what it hands the person
+                // instead - previously that instruction existed only in CLI prose, so
+                // an agent reading the JSON alone knew a human was needed but not for
+                // what.
+                userCommand: portableBootstrapCommand("auth login"),
+                env: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+            },
             project,
         };
     }

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/mcp/tools/jira-write-apply.tool.js

@@ -1,20 +1,20 @@
 import { z } from "zod";
 import { applyWritePlan } from "../../application/apply-write.js";
 import { runTool } from "../tool-result.js";
-const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
-
-Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
-
-Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
-
-After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
-
-Failures worth handling differently:
-- JAM_WRITE_CONFLICT             the issue moved; re-plan
-- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
-- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
-- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
-
+const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
+
+Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
+
+Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
+
+After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
+
+Failures worth handling differently:
+- JAM_WRITE_CONFLICT             the issue moved; re-plan
+- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
+- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
+- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
+
 Never report an uncertain or unverified write as done.`;
 export function registerJiraWriteApply(server, deps) {
     server.registerTool("jira_write_apply", {

package/dist/mcp/tools/jira-write-plan.tool.js

@@ -2,27 +2,27 @@ import { z } from "zod";
 import { planWrite } from "../../application/plan-write.js";
 import { CREATABLE_FIELDS, WRITABLE_FIELDS, WRITE_OPERATIONS } from "../../domain/write.js";
 import { runTool } from "../tool-result.js";
-const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
-
-This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
-
-Operations on an issue that already exists - these need \`key\`:
-- comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
-- field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
-- status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
-- assignee.update    input: { "assignee": "..." }     a display name or an accountId; JAM resolves it against Jira's own directory
-
-Creating an issue - no \`key\`, because there is no issue yet:
-- issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
-
-issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
-
-assignee.update never sends the name you pass. JAM searches Jira's user directory, and assigns only when exactly one user matches your string exactly - an exact display name (case-insensitive) or an accountId. A partial match is Jira reporting a similarity, not identifying a person, so several matches or none come back as a refusal with the candidates attached: name one exactly, or pass their accountId. JAM also checks Jira offers that person as an assignee for this issue, before planning and again before writing, and confirms the result by accountId rather than by name. Unassigning, and setting an assignee while creating, are not in this version.
-
-Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
-
-The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
-
+const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
+
+This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
+
+Operations on an issue that already exists - these need \`key\`:
+- comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
+- field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
+- status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
+- assignee.update    input: { "assignee": "..." }     a display name or an accountId; JAM resolves it against Jira's own directory
+
+Creating an issue - no \`key\`, because there is no issue yet:
+- issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
+
+issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
+
+assignee.update never sends the name you pass. JAM searches Jira's user directory, and assigns only when exactly one user matches your string exactly - an exact display name (case-insensitive) or an accountId. A partial match is Jira reporting a similarity, not identifying a person, so several matches or none come back as a refusal with the candidates attached: name one exactly, or pass their accountId. JAM also checks Jira offers that person as an assignee for this issue, before planning and again before writing, and confirms the result by accountId rather than by name. Unassigning, and setting an assignee while creating, are not in this version.
+
+Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
+
+The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
+
 A plan is a statement about what is possible right now, not a promise that it will happen. Nothing is written until jira_write_apply runs.`;
 export function registerJiraWritePlan(server, deps) {
     server.registerTool("jira_write_plan", {

package/dist/policy/custom-field-policy.d.ts

@@ -0,0 +1,93 @@
+import type { ProjectConfig } from "../config/schema.js";
+import type { CustomFieldKind, CustomFieldRequirements, CustomFieldUpdateInput, CustomFieldValueView, EditFieldMetadata, EditFieldOption } from "../domain/write.js";
+/**
+ * What JAM will write to a custom field, and everything that has to be true
+ * first.
+ *
+ * Three separate permissions have to line up, and none of them implies
+ * another:
+ *
+ *  1. **The team said so.** The field's exact id is in the project's whitelist
+ *     with `writable: true`. Being readable is not being writable - reading a
+ *     field and letting an agent change it are different decisions, and a
+ *     config written before JAM could write must not start granting writes
+ *     because JAM learned how.
+ *  2. **Jira allows it here and now.** The field is on this issue's edit
+ *     screen for this account, and Jira lists `set` among its operations.
+ *     Asked, never modelled: applicability depends on project, issue type,
+ *     field contexts, screens and permissions, and JAM does not carry a copy
+ *     of any of that.
+ *  3. **JAM knows the shape.** The field's type is one of four families whose
+ *     wire form JAM can produce from a plain value and compare afterwards.
+ *     Anything else is refused rather than posted to find out.
+ */
+type WritableField = {
+    id: string;
+    name: string;
+};
+/**
+ * Which configured field this selector names.
+ *
+ * The id is the identity; the name is an alias for people. Resolution is exact
+ * on either - no substring, no fuzz - because the alternative is an agent's
+ * approximate word choosing which field on somebody's board gets rewritten.
+ *
+ * Only `writable: true` entries are candidates, including for the refusal
+ * message: naming a read-only field as an alternative would suggest it is one
+ * selector away from being written.
+ */
+export declare function resolveWritableField(config: ProjectConfig, requested: string): WritableField;
+/**
+ * The field as Jira currently offers it on this issue, or a refusal.
+ *
+ * Absent from the edit metadata and present-but-not-settable are different
+ * situations with the same answer for the caller, so they share a code and
+ * differ in the detail: one means the field is not on this screen, the other
+ * that Jira will not let this account set it.
+ */
+export declare function assertEditable(issueKey: string, field: WritableField, metadata: EditFieldMetadata[]): EditFieldMetadata;
+/**
+ * Which of the four families this field belongs to, if any.
+ *
+ * Classified from Jira's own `schema`, which is the vocabulary Jira answers
+ * in. The implementation key (`schema.custom`) deliberately does not decide
+ * it: there are hundreds of them, they are app-specific, and a field's wire
+ * shape follows its type rather than its plugin.
+ *
+ * Anything unclassified is refused. Posting an unknown type to see what
+ * happens would use a Jira 400 as schema discovery, and on the occasions it
+ * did not 400 it would write something nobody described.
+ */
+export declare function classifyKind(field: EditFieldMetadata): CustomFieldKind;
+/**
+ * The value, checked against the family and turned into what Jira expects.
+ *
+ * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
+ * say so, and silently converting would make JAM's idea of the value differ
+ * from the caller's in exactly the cases where it matters.
+ *
+ * Nothing here clears a field. Empty strings, empty arrays and null are
+ * refused rather than treated as "unset" - removing a value is a different
+ * intent from setting one, and it is not in this version.
+ */
+export declare function resolveCustomFieldValue(field: EditFieldMetadata, kind: CustomFieldKind, input: CustomFieldUpdateInput): {
+    jiraValue: unknown;
+    view: CustomFieldValueView;
+    resolvedOptions?: EditFieldOption[];
+};
+/**
+ * Do this plan's premises still hold?
+ *
+ * Semantic, like the create schema check and for the same reason: comparing
+ * whole metadata documents would invalidate every outstanding plan whenever an
+ * unrelated field appeared on the screen. What is compared is what the plan
+ * actually rested on - the field is still settable, still the same family,
+ * still the same schema, and every option it chose is still offered under the
+ * same label.
+ *
+ * A renamed option is treated as a changed one. The id is the identity, but a
+ * label is what the plan showed a human before they agreed to it, and "Backend"
+ * becoming "Platform" is a different statement about the issue.
+ */
+export declare function assertCustomFieldUnchanged(issueKey: string, requirements: CustomFieldRequirements, metadata: EditFieldMetadata[]): void;
+export {};

package/dist/policy/custom-field-policy.js

@@ -0,0 +1,230 @@
+import { JamError } from "../domain/errors.js";
+/**
+ * Which configured field this selector names.
+ *
+ * The id is the identity; the name is an alias for people. Resolution is exact
+ * on either - no substring, no fuzz - because the alternative is an agent's
+ * approximate word choosing which field on somebody's board gets rewritten.
+ *
+ * Only `writable: true` entries are candidates, including for the refusal
+ * message: naming a read-only field as an alternative would suggest it is one
+ * selector away from being written.
+ */
+export function resolveWritableField(config, requested) {
+    const wanted = requested.trim();
+    if (wanted.length === 0) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs a non-empty `input.field`.", { operation: "custom-field.update" });
+    }
+    const writable = config.customFields.filter((f) => f.writable);
+    const match = writable.find((f) => f.id.toLowerCase() === wanted.toLowerCase()) ??
+        writable.find((f) => f.name.trim().toLowerCase() === wanted.toLowerCase());
+    if (!match) {
+        throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", writable.length === 0
+            ? `No custom field in this project is writable. A team opts one in by adding \`writable: true\` to its entry in .jira-agent/project.yaml; being readable does not make a field writable.`
+            : `"${requested}" is not a writable custom field in this project. JAM writes only the exact ids a team has opted in.`, {
+            requested,
+            writableCustomFields: writable.map((f) => ({ id: f.id, name: f.name })),
+        });
+    }
+    return { id: match.id, name: match.name };
+}
+/**
+ * The field as Jira currently offers it on this issue, or a refusal.
+ *
+ * Absent from the edit metadata and present-but-not-settable are different
+ * situations with the same answer for the caller, so they share a code and
+ * differ in the detail: one means the field is not on this screen, the other
+ * that Jira will not let this account set it.
+ */
+export function assertEditable(issueKey, field, metadata) {
+    const found = metadata.find((f) => f.id === field.id);
+    if (!found) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira does not offer ${field.name} (${field.id}) on ${issueKey}'s edit screen for this account. The field may not apply to this project or issue type, or this account may not be able to edit it.`, { issueKey, fieldId: field.id, fieldName: field.name, reason: "NOT_ON_EDIT_SCREEN" });
+    }
+    if (!found.operations.includes("set")) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", `Jira lists ${field.name} (${field.id}) on ${issueKey} but does not offer "set" for it${found.operations.length > 0 ? ` - only ${found.operations.join(", ")}` : ""}. JAM only sets a value; it does not add to or remove from one.`, {
+            issueKey,
+            fieldId: field.id,
+            fieldName: field.name,
+            operations: found.operations,
+            reason: "SET_NOT_OFFERED",
+        });
+    }
+    return found;
+}
+/**
+ * Which of the four families this field belongs to, if any.
+ *
+ * Classified from Jira's own `schema`, which is the vocabulary Jira answers
+ * in. The implementation key (`schema.custom`) deliberately does not decide
+ * it: there are hundreds of them, they are app-specific, and a field's wire
+ * shape follows its type rather than its plugin.
+ *
+ * Anything unclassified is refused. Posting an unknown type to see what
+ * happens would use a Jira 400 as schema discovery, and on the occasions it
+ * did not 400 it would write something nobody described.
+ */
+export function classifyKind(field) {
+    const { type, items } = field.schema;
+    if (type === "string" && !items)
+        return "text";
+    if (type === "number" && !items)
+        return "number";
+    if (type === "option" && !items)
+        return "single-option";
+    if (type === "array" && items === "option")
+        return "multi-option";
+    throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a ${describeType(field)} field, and JAM does not know how to write one safely yet. Supported: single-line text, number, single-select and multi-select.`, {
+        fieldId: field.id,
+        fieldName: field.name,
+        schema: field.schema,
+        supported: ["text", "number", "single-option", "multi-option"],
+    });
+}
+function describeType(field) {
+    const { type, items } = field.schema;
+    return items ? `${type} of ${items}` : type;
+}
+/**
+ * The value, checked against the family and turned into what Jira expects.
+ *
+ * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
+ * say so, and silently converting would make JAM's idea of the value differ
+ * from the caller's in exactly the cases where it matters.
+ *
+ * Nothing here clears a field. Empty strings, empty arrays and null are
+ * refused rather than treated as "unset" - removing a value is a different
+ * intent from setting one, and it is not in this version.
+ */
+export function resolveCustomFieldValue(field, kind, input) {
+    const { value } = input;
+    const named = { id: field.id, name: field.name };
+    switch (kind) {
+        case "text": {
+            if (typeof value !== "string")
+                throw wrongType(field, kind, value);
+            const text = value.trim();
+            if (text.length === 0)
+                throw refuseClear(field);
+            return { jiraValue: text, view: { ...named, value: text } };
+        }
+        case "number": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                throw wrongType(field, kind, value);
+            return { jiraValue: value, view: { ...named, value } };
+        }
+        case "single-option": {
+            if (typeof value !== "string")
+                throw wrongType(field, kind, value);
+            const option = resolveOption(field, value);
+            // Jira takes the option by id. The label is what a person reads, and two
+            // options could carry the same one.
+            return {
+                jiraValue: { id: option.id },
+                view: { ...named, value: option },
+                resolvedOptions: [option],
+            };
+        }
+        case "multi-option": {
+            if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+                throw wrongType(field, kind, value);
+            }
+            if (value.length === 0)
+                throw refuseClear(field);
+            const seen = new Set();
+            for (const raw of value) {
+                const key = raw.trim().toLowerCase();
+                if (seen.has(key)) {
+                    throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${raw}" appears more than once in the value for ${field.name}. JAM does not quietly drop the repeat - say each option once.`, { fieldId: field.id, repeated: raw });
+                }
+                seen.add(key);
+            }
+            // Every option resolves, or none is written. A partly-applied selection
+            // is a selection nobody asked for.
+            const options = value.map((raw) => resolveOption(field, raw));
+            return {
+                jiraValue: options.map((o) => ({ id: o.id })),
+                view: { ...named, value: options },
+                resolvedOptions: options,
+            };
+        }
+    }
+}
+/**
+ * Which option Jira offers under this name, if exactly one does.
+ *
+ * An option id wins outright, then an exact label ignoring case and space.
+ * Nothing partial: Jira's option lists are short and a caller can name one
+ * exactly, so a near miss is a question rather than a guess.
+ */
+function resolveOption(field, requested) {
+    const allowed = field.allowedValues;
+    if (!allowed) {
+        throw new JamError("JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", `${field.name} (${field.id}) is a select field, but Jira did not say which options it offers, so JAM cannot resolve "${requested}" to one.`, { fieldId: field.id, fieldName: field.name, schema: field.schema });
+    }
+    const wanted = requested.trim();
+    const byId = allowed.filter((o) => o.id === wanted);
+    const matches = byId.length > 0
+        ? byId
+        : allowed.filter((o) => o.label.trim().toLowerCase() === wanted.toLowerCase());
+    if (matches.length === 0) {
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", allowed.length === 0
+            ? `Jira offers no options for ${field.name} on this issue, so "${requested}" cannot be set.`
+            : `"${requested}" is not an option Jira offers for ${field.name}. Allowed: ${allowed.map((o) => o.label).join(", ")}.`, { fieldId: field.id, requested, allowed });
+    }
+    if (matches.length > 1) {
+        throw new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `"${requested}" matches ${matches.length} options for ${field.name}. Pass the option id of the one you mean.`, { fieldId: field.id, requested, candidates: matches });
+    }
+    return matches[0];
+}
+/**
+ * Do this plan's premises still hold?
+ *
+ * Semantic, like the create schema check and for the same reason: comparing
+ * whole metadata documents would invalidate every outstanding plan whenever an
+ * unrelated field appeared on the screen. What is compared is what the plan
+ * actually rested on - the field is still settable, still the same family,
+ * still the same schema, and every option it chose is still offered under the
+ * same label.
+ *
+ * A renamed option is treated as a changed one. The id is the identity, but a
+ * label is what the plan showed a human before they agreed to it, and "Backend"
+ * becoming "Platform" is a different statement about the issue.
+ */
+export function assertCustomFieldUnchanged(issueKey, requirements, metadata) {
+    const field = metadata.find((f) => f.id === requirements.fieldId);
+    if (!field) {
+        throw schemaChanged(`${requirements.fieldName} (${requirements.fieldId}) is no longer on ${issueKey}'s edit screen for this account.`, { issueKey, fieldId: requirements.fieldId });
+    }
+    if (!field.operations.includes("set")) {
+        throw schemaChanged(`Jira no longer offers "set" for ${requirements.fieldName} on ${issueKey}.`, { issueKey, fieldId: field.id, operations: field.operations });
+    }
+    if (field.schema.type !== requirements.schema.type ||
+        field.schema.items !== requirements.schema.items) {
+        throw schemaChanged(`${requirements.fieldName} is no longer a ${requirements.kind} field.`, { issueKey, fieldId: field.id, planned: requirements.schema, current: field.schema });
+    }
+    for (const planned of requirements.resolvedOptions ?? []) {
+        const current = field.allowedValues?.find((o) => o.id === planned.id);
+        if (!current) {
+            throw schemaChanged(`Option "${planned.label}" is no longer offered for ${requirements.fieldName}.`, { issueKey, fieldId: field.id, option: planned });
+        }
+        if (current.label !== planned.label) {
+            throw schemaChanged(`Option "${planned.label}" has been renamed to "${current.label}", so this plan no longer describes the change it showed.`, { issueKey, fieldId: field.id, planned, current });
+        }
+    }
+}
+function schemaChanged(what, details) {
+    return new JamError("JAM_WRITE_SCHEMA_CHANGED", `${what} This plan was built on the field's configuration as it was, so it no longer describes a change JAM can make. Nothing was written - plan again.`, details);
+}
+function wrongType(field, kind, value) {
+    const wanted = {
+        text: "a string",
+        number: "a number",
+        "single-option": "a string naming one option",
+        "multi-option": "an array of strings naming options",
+    }[kind];
+    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `${field.name} (${field.id}) is a ${kind} field and needs ${wanted}. JAM does not convert between types - "5" and 5 are different values, and guessing which was meant is not JAM's to do.`, { fieldId: field.id, kind, received: typeof value });
+}
+function refuseClear(field) {
+    return new JamError("JAM_WRITE_VALUE_NOT_ALLOWED", `custom-field.update sets a value; it does not clear one. ${field.name} cannot be set to an empty value in this version.`, { fieldId: field.id, reason: "CLEAR_NOT_SUPPORTED" });
+}

package/dist/ports/jira-edit-metadata.port.d.ts

@@ -0,0 +1,22 @@
+import type { EditFieldMetadata } from "../domain/write.js";
+/**
+ * What Jira will let this account change on one issue, right now.
+ *
+ * `GET /rest/api/3/issue/{key}/editmeta` is the authority, and it is asked
+ * rather than reconstructed. A custom field's applicability depends on the
+ * project, the issue type, the field's contexts, the screen it is on and the
+ * permissions of whoever is asking - JAM does not carry a copy of that model,
+ * and the field-context APIs that would let it try need administrator rights
+ * most tokens do not have. So the question is put to Jira in the form it can
+ * answer exactly: on this issue, for this account, what is editable and how.
+ *
+ * The same shape as the other read-shaped ports, for the same reasons: it
+ * mutates nothing, so it does not belong behind the write port's no-retry
+ * contract, and it answers a question about a configuration rather than about
+ * an issue, so the read port's completeness semantics would mean nothing here.
+ *
+ * It does not retry. Its answer decides a mutation.
+ */
+export interface JiraEditMetadataPort {
+    getEditableFields(issueKey: string): Promise<EditFieldMetadata[]>;
+}

package/dist/ports/jira-edit-metadata.port.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@jam-mcp/server",
-  "version": "1.3.0",
-  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
-  "keywords": [
-    "jira",
-    "mcp",
-    "model-context-protocol",
-    "claude-code",
-    "codex",
-    "jira-api"
-  ],
-  "homepage": "https://github.com/colosair/jam#readme",
-  "bugs": {
-    "url": "https://github.com/colosair/jam/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/colosair/jam.git",
-    "directory": "packages/server"
-  },
-  "author": "colosair (https://github.com/colosair)",
-  "type": "module",
-  "bin": {
-    "jam-server": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "engines": {
-    "node": ">=20"
-  },
-  "files": [
-    "dist",
-    "!dist/**/*.js.map",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@jam-mcp/launcher": "1.3.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.11"
-  },
-  "license": "MIT",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./cli-entry": {
-      "types": "./dist/cli-entry.d.ts",
-      "default": "./dist/cli-entry.js"
-    }
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@jam-mcp/server",
+  "version": "1.3.2",
+  "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
+  "keywords": [
+    "jira",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "jira-api"
+  ],
+  "homepage": "https://github.com/colosair/jam#readme",
+  "bugs": {
+    "url": "https://github.com/colosair/jam/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colosair/jam.git",
+    "directory": "packages/server"
+  },
+  "author": "colosair (https://github.com/colosair)",
+  "type": "module",
+  "bin": {
+    "jam-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.js.map",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jam-mcp/launcher": "1.3.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli-entry": {
+      "types": "./dist/cli-entry.d.ts",
+      "default": "./dist/cli-entry.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}