@jam-mcp/server 1.0.1 → 1.2.0

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,72 +1,86 @@
-# @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 three tools
-
-The external contract is exactly three 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 |
-
-A `jira_search` result is never complete issue context — nothing about
-agreement, approval, or done-ness follows from it.
-
-## 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.0.1 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.0.1 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.
+
+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.2.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.2.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)

package/dist/adapters/credentials/windows-user-env.d.ts

@@ -15,6 +15,8 @@ export type RegQueryFn = (name: string) => string | undefined;
  */
 export declare class WindowsUserEnvCredentialSource implements CredentialValueSource {
     private readonly queryFn;
-    constructor(queryFn?: RegQueryFn);
+    private readonly env;
+    constructor(queryFn?: RegQueryFn, env?: NodeJS.ProcessEnv);
     read(): RawCredentialValues;
 }
+export declare function userEnvDisabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/adapters/credentials/windows-user-env.js

@@ -15,12 +15,16 @@ import { CREDENTIAL_ENV_KEYS } from "./process-env.js";
  */
 export class WindowsUserEnvCredentialSource {
     queryFn;
-    constructor(queryFn = defaultRegQuery) {
+    env;
+    constructor(queryFn = defaultRegQuery, env = process.env) {
         this.queryFn = queryFn;
+        this.env = env;
     }
     read() {
         if (process.platform !== "win32")
             return {};
+        if (userEnvDisabled(this.env))
+            return {};
         const out = {};
         for (const key of CREDENTIAL_ENV_KEYS) {
             const value = this.queryFn(key)?.trim();
@@ -30,6 +34,21 @@ export class WindowsUserEnvCredentialSource {
         return out;
     }
 }
+/**
+ * Escape hatch for isolated test sandboxes, matching JAM_DISABLE_SECRET_STORE.
+ *
+ * HKCU\Environment is per-user, not per-HOME, so repointing HOME does not make
+ * a sandbox credential-free on Windows: a developer who ran `setx JIRA_API_TOKEN`
+ * once has credentials that every process of theirs can see. Without this, a
+ * hermetic test would pass or fail depending on whose machine ran it, and
+ * "zero HOME" would be mistaken for "zero credentials".
+ *
+ * Not a user-facing feature. Production never sets it.
+ */
+const DISABLE_ENV = "JAM_DISABLE_USER_ENV";
+export function userEnvDisabled(env = process.env) {
+    return Boolean(env[DISABLE_ENV]);
+}
 const VALUE_LINE = /^\s*\S+\s+REG_(?:SZ|EXPAND_SZ)\s+(.*)$/;
 // Built from a char code rather than a literal backslash escape - a lone
 // backslash before a letter isn't a recognized JS escape and silently

package/dist/adapters/jira-cloud/jira-client.d.ts

@@ -2,9 +2,18 @@ import { JamError } from "../../domain/errors.js";
 import type { CredentialPort } from "../../ports/credentials.port.js";
 export type JiraRequest = {
     path: string;
-    method?: "GET" | "POST";
+    method?: "GET" | "POST" | "PUT";
     query?: Record<string, string | number | undefined>;
     body?: unknown;
+    /**
+     * Whether a transient failure may be retried.
+     *
+     * Reads say yes and get the retry loop below. Writes say no: a request that
+     * timed out may already have been applied, so resending it is how one
+     * comment becomes two. The write path resolves that ambiguity by reading the
+     * issue back, never by trying again.
+     */
+    retry?: boolean;
 };
 export type JiraResponse<T> = {
     data: T;

package/dist/adapters/jira-cloud/jira-client.js

@@ -67,7 +67,7 @@ export class JiraClient {
             // ponytail: fixed 2 retries on transient statuses; add backoff tuning if
             // `complete` searches start tripping Jira's rate limiter in practice.
             const transient = res.status === 429 || res.status >= 500;
-            if (transient && attempt < MAX_RETRIES) {
+            if (req.retry !== false && transient && attempt < MAX_RETRIES) {
                 lastError = error;
                 await sleep(retryDelayMs(res.headers.get("retry-after"), attempt));
                 continue;

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

@@ -0,0 +1,27 @@
+import type { CreateFieldMetadata, CreateIssueType } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
+import type { JiraCreateMetadataPort } from "../../ports/jira-create-metadata.port.js";
+/**
+ * Jira Cloud REST v3 create metadata, per project and per issue type.
+ *
+ * The two-endpoint form, not the aggregate `createmeta?expand=` one: the
+ * aggregate endpoint is deprecated on Jira Cloud and returns every issue type's
+ * every field in one document, which is both larger and less precise than the
+ * question being asked. Planning wants one project's issue types, and then one
+ * issue type's fields.
+ *
+ * `retry: false` throughout. These answers decide whether a create is possible
+ * and what it will contain, so a retried-and-stale answer is worse than a
+ * failure - the same reason `getTransitions` does not retry.
+ *
+ * Both mappers are defensive about shape. Jira omits fields it considers
+ * irrelevant and different deployments populate different ones, so anything
+ * unrecognised is dropped rather than guessed at: an entry JAM cannot read is
+ * an entry JAM must not claim to have understood.
+ */
+export declare class JiraCloudCreateMetadataAdapter implements JiraCreateMetadataPort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    getIssueTypes(projectKey: string): Promise<CreateIssueType[]>;
+    getCreateFields(projectKey: string, issueTypeId: string): Promise<CreateFieldMetadata[]>;
+}

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

@@ -0,0 +1,81 @@
+import { JiraClient } from "./jira-client.js";
+/**
+ * Jira Cloud REST v3 create metadata, per project and per issue type.
+ *
+ * The two-endpoint form, not the aggregate `createmeta?expand=` one: the
+ * aggregate endpoint is deprecated on Jira Cloud and returns every issue type's
+ * every field in one document, which is both larger and less precise than the
+ * question being asked. Planning wants one project's issue types, and then one
+ * issue type's fields.
+ *
+ * `retry: false` throughout. These answers decide whether a create is possible
+ * and what it will contain, so a retried-and-stale answer is worse than a
+ * failure - the same reason `getTransitions` does not retry.
+ *
+ * Both mappers are defensive about shape. Jira omits fields it considers
+ * irrelevant and different deployments populate different ones, so anything
+ * unrecognised is dropped rather than guessed at: an entry JAM cannot read is
+ * an entry JAM must not claim to have understood.
+ */
+export class JiraCloudCreateMetadataAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl ? new JiraClient(credentials, fetchImpl) : new JiraClient(credentials);
+    }
+    async getIssueTypes(projectKey) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes`,
+            retry: false,
+        });
+        return (data.issueTypes ?? [])
+            .filter((t) => typeof t.id === "string" && typeof t.name === "string")
+            .map((t) => ({ id: t.id, name: t.name, subtask: t.subtask === true }));
+    }
+    async getCreateFields(projectKey, issueTypeId) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes/${encodeURIComponent(issueTypeId)}`,
+            retry: false,
+        });
+        return (data.fields ?? [])
+            .map(toFieldMetadata)
+            .filter((f) => f !== undefined);
+    }
+}
+function toFieldMetadata(raw) {
+    // Jira has called this `fieldId` and `key` in different responses. Without
+    // one of them the entry cannot be matched to anything, so it is dropped -
+    // and if it was required, the required-field gate will refuse the plan
+    // because JAM cannot show it was supplied.
+    const id = typeof raw.fieldId === "string" ? raw.fieldId : typeof raw.key === "string" ? raw.key : undefined;
+    if (!id)
+        return undefined;
+    const allowed = mapAllowedValues(raw.allowedValues);
+    return {
+        id,
+        name: typeof raw.name === "string" ? raw.name : id,
+        required: raw.required === true,
+        hasDefaultValue: raw.hasDefaultValue === true,
+        ...(allowed ? { allowedValues: allowed } : {}),
+    };
+}
+/**
+ * Allowed values, when Jira constrains the field at all.
+ *
+ * Undefined and empty mean different things and are kept apart: undefined is
+ * "Jira did not constrain this", empty is "Jira constrains it and offers
+ * nothing". The first permits a free value, the second permits none.
+ */
+function mapAllowedValues(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.map((entry) => {
+        const id = typeof entry?.id === "string" ? entry.id : undefined;
+        // Components and priorities use `name`; some option fields use `value`.
+        const name = typeof entry?.name === "string"
+            ? entry.name
+            : typeof entry?.value === "string"
+                ? entry.value
+                : undefined;
+        return { ...(id ? { id } : {}), ...(name ? { name } : {}) };
+    });
+}

package/dist/adapters/jira-cloud/jira-read.adapter.d.ts

@@ -1,11 +1,20 @@
 import type { ProjectConfig } from "../../config/schema.js";
 import type { CredentialPort } from "../../ports/credentials.port.js";
-import type { CurrentUser, GetCommentsRequest, GetCommentsResult, GetIssuesRequest, GetIssuesResult, JiraReadPort, ListProjectsResult, SearchPageRequest, SearchPageResult } from "../../ports/jira-read.port.js";
+import type { CurrentUser, GetCommentsRequest, GetCommentsResult, GetIssueRequest, GetIssueResult, GetIssuesRequest, GetIssuesResult, JiraReadPort, ListProjectsResult, SearchPageRequest, SearchPageResult } from "../../ports/jira-read.port.js";
 export declare class JiraCloudReadAdapter implements JiraReadPort {
     private readonly config;
     private readonly client;
     constructor(credentials: CredentialPort, config: ProjectConfig, fetchImpl?: typeof fetch);
     searchPage(req: SearchPageRequest): Promise<SearchPageResult>;
+    /**
+     * `GET /rest/api/3/issue/{key}` - the single-issue endpoint, not bulkfetch.
+     *
+     * This is what ConsistencyPolicy means by a direct issue read, and the write
+     * plane is the only caller. A 404 is an answer, not a failure: the issue is
+     * not there, or not visible to this account, and the caller decides which of
+     * those matters.
+     */
+    getIssue(req: GetIssueRequest): Promise<GetIssueResult>;
     getIssues(req: GetIssuesRequest): Promise<GetIssuesResult>;
     getComments(req: GetCommentsRequest): Promise<GetCommentsResult>;
     listProjects(): Promise<ListProjectsResult>;

package/dist/adapters/jira-cloud/jira-read.adapter.js

@@ -27,6 +27,23 @@ export class JiraCloudReadAdapter {
             result.nextPageToken = data.nextPageToken;
         return result;
     }
+    /**
+     * `GET /rest/api/3/issue/{key}` - the single-issue endpoint, not bulkfetch.
+     *
+     * This is what ConsistencyPolicy means by a direct issue read, and the write
+     * plane is the only caller. A 404 is an answer, not a failure: the issue is
+     * not there, or not visible to this account, and the caller decides which of
+     * those matters.
+     */
+    async getIssue(req) {
+        const { data, bytes } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(req.key)}`,
+            query: { fields: req.fields.join(",") },
+        });
+        if (!data?.key)
+            return { responseBytes: bytes };
+        return { issue: mapIssueWithMeta(data, this.config).issue, responseBytes: bytes };
+    }
     async getIssues(req) {
         const issues = [];
         const commentTotals = {};

package/dist/adapters/jira-cloud/jira-write.adapter.d.ts

@@ -1,12 +1,47 @@
+import type { JiraTransition } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
 import type { JiraWritePort } from "../../ports/jira-write.port.js";
 /**
- * Deliberate stub. The first release is read-only; the existing Atlassian MCP
- * remains the write path. The port exists so adding writes later is an adapter
- * swap rather than an application-layer change.
+ * Jira Cloud REST v3, mutating half.
+ *
+ * Every request here sets `retry: false`. The read adapter's retry loop is
+ * correct for reads and dangerous here: a request that times out after Jira
+ * accepted it is indistinguishable from one Jira never saw, and resending it
+ * duplicates the change. The application layer resolves that by reading the
+ * issue back - see applyWritePlan.
+ *
+ * This adapter also never reads its own work. Confirmation is a direct issue
+ * GET through the read port, which keeps "what JAM did" and "what Jira shows"
+ * two separate observations rather than one hopeful one.
  */
-export declare class UnsupportedJiraWriteAdapter implements JiraWritePort {
-    updateIssue(): Promise<void>;
-    addComment(): Promise<{
+export declare class JiraCloudWriteAdapter implements JiraWritePort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    /**
+     * Create one issue, once.
+     *
+     * `retry: false` matters more here than anywhere else behind this port. A
+     * retried update converges; a retried create leaves two issues, and the
+     * second one has a different key nobody is holding. An ambiguous failure is
+     * handed to the application layer as JAM_WRITE_UNCERTAIN and resolved by
+     * looking, never by sending it again.
+     */
+    createIssue(fields: Record<string, unknown>): Promise<{
         id: string;
+        key: string;
     }>;
+    updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
+    /**
+     * Add a comment, converting plain text to ADF here rather than accepting ADF.
+     *
+     * Jira's comment body is a document tree, and letting an agent supply one
+     * would mean accepting arbitrary structure - panels, mentions, embedded
+     * content - through a field that reads like "text". The conversion is narrow
+     * on purpose: paragraphs, and nothing else.
+     */
+    addComment(key: string, body: string): Promise<{
+        id: string;
+    }>;
+    getTransitions(key: string): Promise<JiraTransition[]>;
+    transitionIssue(key: string, transitionId: string): Promise<void>;
 }

package/dist/adapters/jira-cloud/jira-write.adapter.js

@@ -1,17 +1,102 @@
+import { textToAdf } from "../../domain/adf.js";
 import { JamError } from "../../domain/errors.js";
+import { JiraClient } from "./jira-client.js";
 /**
- * Deliberate stub. The first release is read-only; the existing Atlassian MCP
- * remains the write path. The port exists so adding writes later is an adapter
- * swap rather than an application-layer change.
+ * Jira Cloud REST v3, mutating half.
+ *
+ * Every request here sets `retry: false`. The read adapter's retry loop is
+ * correct for reads and dangerous here: a request that times out after Jira
+ * accepted it is indistinguishable from one Jira never saw, and resending it
+ * duplicates the change. The application layer resolves that by reading the
+ * issue back - see applyWritePlan.
+ *
+ * This adapter also never reads its own work. Confirmation is a direct issue
+ * GET through the read port, which keeps "what JAM did" and "what Jira shows"
+ * two separate observations rather than one hopeful one.
  */
-export class UnsupportedJiraWriteAdapter {
-    async updateIssue() {
-        throw notSupported();
+export class JiraCloudWriteAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl
+            ? new JiraClient(credentials, fetchImpl)
+            : new JiraClient(credentials);
     }
-    async addComment() {
-        throw notSupported();
+    /**
+     * Create one issue, once.
+     *
+     * `retry: false` matters more here than anywhere else behind this port. A
+     * retried update converges; a retried create leaves two issues, and the
+     * second one has a different key nobody is holding. An ambiguous failure is
+     * handed to the application layer as JAM_WRITE_UNCERTAIN and resolved by
+     * looking, never by sending it again.
+     */
+    async createIssue(fields) {
+        const { data } = await this.client.request({
+            path: "rest/api/3/issue",
+            method: "POST",
+            body: { fields },
+            retry: false,
+        });
+        if (!data?.key || !data.id) {
+            // Jira took the request and told us nothing identifying, so an issue may
+            // now exist that JAM cannot name. That is exactly the uncertain case:
+            // report it, do not retry, and let a person look.
+            throw new JamError("JAM_WRITE_UNCERTAIN", "Jira accepted a create but returned no issue key, so JAM cannot tell which issue it made - or whether it made one. Look in the project before trying again: retrying could create a second issue.", { project: fields["project"]?.key });
+        }
+        return { id: data.id, key: data.key };
+    }
+    async updateIssue(key, fields) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}`,
+            method: "PUT",
+            body: { fields },
+            retry: false,
+        });
+    }
+    /**
+     * Add a comment, converting plain text to ADF here rather than accepting ADF.
+     *
+     * Jira's comment body is a document tree, and letting an agent supply one
+     * would mean accepting arbitrary structure - panels, mentions, embedded
+     * content - through a field that reads like "text". The conversion is narrow
+     * on purpose: paragraphs, and nothing else.
+     */
+    async addComment(key, body) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/comment`,
+            method: "POST",
+            body: { body: textToAdf(body) },
+            retry: false,
+        });
+        if (!data?.id) {
+            // Jira accepted it but told us nothing identifying. Treat that as
+            // unconfirmed rather than inventing an id: the caller's direct read is
+            // what decides whether the comment exists.
+            throw new JamError("JAM_WRITE_UNCERTAIN", `Jira accepted a comment on ${key} but returned no comment id, so JAM cannot confirm which comment it created.`, { issueKey: key });
+        }
+        return { id: data.id };
+    }
+    async getTransitions(key) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+            // A read, but on the write path: its answer decides a mutation, so a
+            // retried-and-stale transition list would be worse than a failure.
+            retry: false,
+        });
+        return (data.transitions ?? [])
+            .filter((t) => typeof t.id === "string")
+            .map((t) => ({
+            id: t.id,
+            name: t.name ?? t.id,
+            to: t.to?.name ?? t.name ?? "",
+        }));
+    }
+    async transitionIssue(key, transitionId) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+            method: "POST",
+            body: { transition: { id: transitionId } },
+            retry: false,
+        });
     }
-}
-function notSupported() {
-    return new JamError("CONFIG_INVALID", "JAM is read-only in this release. Use the Atlassian MCP for Jira writes.");
 }

package/dist/application/apply-create-issue.d.ts

@@ -0,0 +1,20 @@
+import type { JamDeps } from "../deps.js";
+import type { CreateIssueWritePlan, WriteApplyReceipt } from "../domain/write.js";
+/**
+ * Create the issue a plan describes, then go and look at what was created.
+ *
+ * The same three-step shape as every other apply, with one substitution.
+ * Updating an existing issue re-reads that issue and compares its revision;
+ * there is no issue to re-read here, so what gets checked instead is the
+ * premise the plan was built on - the project's create schema. That is
+ * creation's concurrency boundary.
+ *
+ *  1. Re-derive the schema and check the plan's premises still hold. If the
+ *     issue type went away, or a required field JAM cannot fill appeared, or a
+ *     resolved value is no longer offered, nothing is sent.
+ *  2. POST the create exactly once. No retry, ever - see below.
+ *  3. Read the new issue by the key Jira returned, and check it says what the
+ *     plan intended. A 201 with a key is Jira accepting a request, not
+ *     evidence that the issue exists as described.
+ */
+export declare function applyCreateIssue(deps: JamDeps, plan: CreateIssueWritePlan): Promise<WriteApplyReceipt>;