@jam-mcp/server 1.1.0 → 1.2.0

package/README.md

@@ -70,10 +70,10 @@ 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.1.0 doctor`, or just `jam
+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.1.0 init` instead.
+`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

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-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

@@ -17,6 +17,19 @@ import type { JiraWritePort } from "../../ports/jira-write.port.js";
 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.
@@ -32,10 +45,3 @@ export declare class JiraCloudWriteAdapter implements JiraWritePort {
     getTransitions(key: string): Promise<JiraTransition[]>;
     transitionIssue(key: string, transitionId: string): Promise<void>;
 }
-/**
- * Plain text to the narrowest ADF that represents it.
- *
- * Blank lines separate paragraphs; everything else is literal. No markdown is
- * interpreted, so a comment containing `*` or `#` says what it says.
- */
-export declare function textToAdf(text: string): unknown;

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

@@ -1,3 +1,4 @@
+import { textToAdf } from "../../domain/adf.js";
 import { JamError } from "../../domain/errors.js";
 import { JiraClient } from "./jira-client.js";
 /**
@@ -20,6 +21,30 @@ export class JiraCloudWriteAdapter {
             ? new JiraClient(credentials, fetchImpl)
             : new JiraClient(credentials);
     }
+    /**
+     * 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)}`,
@@ -75,23 +100,3 @@ export class JiraCloudWriteAdapter {
         });
     }
 }
-/**
- * Plain text to the narrowest ADF that represents it.
- *
- * Blank lines separate paragraphs; everything else is literal. No markdown is
- * interpreted, so a comment containing `*` or `#` says what it says.
- */
-export function textToAdf(text) {
-    const paragraphs = text
-        .split(/\n{2,}/)
-        .map((block) => block.trim())
-        .filter(Boolean);
-    return {
-        type: "doc",
-        version: 1,
-        content: (paragraphs.length > 0 ? paragraphs : [text]).map((block) => ({
-            type: "paragraph",
-            content: [{ type: "text", text: block }],
-        })),
-    };
-}

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>;

package/dist/application/apply-create-issue.js

@@ -0,0 +1,187 @@
+import { JamError, toJamError } from "../domain/errors.js";
+import { canonicalizePlainText } from "../domain/adf.js";
+import { assertSchemaUnchanged } from "../policy/create-policy.js";
+import { projectKeyOf } from "../policy/write-policy.js";
+import { readIssue } from "./plan-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 async function applyCreateIssue(deps, plan) {
+    if (plan.mutation.kind !== "create") {
+        throw new JamError("CONFIG_INVALID", "A create-issue plan must carry a create mutation.");
+    }
+    await revalidateSchema(deps, plan);
+    const created = await create(deps, plan);
+    const after = await verify(deps, plan, created.key);
+    deps.writePlans.consume(plan.planId);
+    return {
+        status: "applied",
+        issue: created.key,
+        operation: plan.operation,
+        before: plan.before,
+        after,
+        verified: true,
+    };
+}
+/**
+ * Ask Jira for the create schema again, and check the plan still stands.
+ *
+ * Deliberately not a comparison of the two metadata documents. The question is
+ * not "is the schema identical" - on an active project it rarely is - but "are
+ * this plan's premises still true". See assertSchemaUnchanged.
+ */
+async function revalidateSchema(deps, plan) {
+    const { projectKey, schemaRequirements } = plan;
+    const issueTypes = await deps.jiraCreateMetadata.getIssueTypes(projectKey);
+    const fields = await deps.jiraCreateMetadata.getCreateFields(projectKey, schemaRequirements.issueTypeId);
+    assertSchemaUnchanged(schemaRequirements, issueTypes, fields, intendedInput(plan));
+}
+/**
+ * The create request as an input again, for re-running the required-field gate.
+ *
+ * Derived from `intendedAfter` rather than kept as a second copy of the
+ * request: one record of what this plan intends, read two ways.
+ */
+function intendedInput(plan) {
+    const after = plan.intendedAfter;
+    return {
+        issueType: plan.schemaRequirements.issueTypeName,
+        summary: String(after["summary"] ?? ""),
+        ...(after["description"] !== undefined ? { description: String(after["description"]) } : {}),
+        ...(after["priority"] !== undefined ? { priority: String(after["priority"]) } : {}),
+        ...(Array.isArray(after["labels"]) ? { labels: after["labels"] } : {}),
+        ...(Array.isArray(after["components"]) ? { components: after["components"] } : {}),
+    };
+}
+/**
+ * Send the create, once.
+ *
+ * There is no retry here and there must not be one. This is the sharpest
+ * version of the rule the whole write plane follows: a create that fails
+ * ambiguously may already have produced an issue, and resending it produces a
+ * second one - on someone's board, in someone's sprint, with a key nobody is
+ * holding. So an ambiguous failure becomes JAM_WRITE_UNCERTAIN and says what
+ * to do about it: look in the project, do not send it again.
+ */
+async function create(deps, plan) {
+    if (plan.mutation.kind !== "create") {
+        throw new JamError("CONFIG_INVALID", "A create-issue plan must carry a create mutation.");
+    }
+    try {
+        return await deps.jiraWrite.createIssue(plan.mutation.fields);
+    }
+    catch (err) {
+        const jamError = toJamError(err);
+        if (!isAmbiguous(jamError))
+            throw jamError;
+        throw new JamError("JAM_WRITE_UNCERTAIN", `JAM could not tell whether the issue was created in ${plan.projectKey}: ${jamError.message} Look in the project to find out - do not retry this write, which could create a second issue.`, { project: plan.projectKey, operation: plan.operation, cause: jamError.code });
+    }
+}
+/**
+ * A failure that says nothing about whether Jira acted.
+ *
+ * A 403 or a 400 is a decision Jira made and did not act on. A dropped
+ * connection or a 5xx is not: the request may have been processed before the
+ * answer went missing. JAM_WRITE_UNCERTAIN raised inside the adapter - Jira
+ * accepted a create but named no issue - is ambiguous by construction and
+ * passes through unchanged.
+ */
+function isAmbiguous(err) {
+    return (err.code === "JIRA_UNAVAILABLE" ||
+        err.code === "RATE_LIMITED" ||
+        err.code === "JAM_WRITE_UNCERTAIN");
+}
+/**
+ * Read the created issue and check it is the one the plan described.
+ *
+ * Every field in `intendedAfter` is checked, because `intendedAfter` is also
+ * what the plan receipt promised `verification.expects` would show. A field
+ * the receipt names and the check skips is worse than one it never named: it
+ * reports `verified: true` about something nobody looked at.
+ *
+ * Only the fields the create contract lets a caller ask for are in there.
+ * Jira fills in a great deal on its own - reporter, created, status, whatever
+ * a project's automation adds - and none of that was requested, so requiring
+ * it to match something would be inventing an expectation nobody stated.
+ */
+async function verify(deps, plan, issueKey) {
+    // Where the issue landed is part of what was intended. The workspace binding
+    // is the whole of JAM's write scope, so a key from another project coming
+    // back from a create is the one outcome that must never be reported as the
+    // create that was planned.
+    const createdProject = projectKeyOf(issueKey);
+    if (createdProject !== plan.projectKey) {
+        throw verificationFailed(plan, issueKey, { project: plan.projectKey }, { project: createdProject ?? issueKey });
+    }
+    const issue = await readIssue(deps, issueKey);
+    const observed = {};
+    for (const field of Object.keys(plan.intendedAfter)) {
+        observed[field] = observedValue(issue, field);
+    }
+    for (const [field, expected] of Object.entries(plan.intendedAfter)) {
+        if (!sameValue(observed[field], expected)) {
+            throw verificationFailed(plan, issueKey, plan.intendedAfter, observed);
+        }
+    }
+    return observed;
+}
+/**
+ * The created issue's value for one requested field.
+ *
+ * The description is canonicalized on the way out, the same way the plan
+ * canonicalized what was asked for. Jira stores a document and renders it back
+ * as text, so the two are never byte-identical - and a comparison that failed
+ * on Jira's own formatting would be reporting a problem that is not there.
+ */
+function observedValue(issue, field) {
+    switch (field) {
+        case "issueType":
+            return issue.issueType;
+        case "summary":
+            return issue.summary;
+        case "description":
+            return issue.description === undefined
+                ? undefined
+                : canonicalizePlainText(issue.description);
+        case "priority":
+            return issue.priority;
+        case "labels":
+            return issue.labels;
+        case "components":
+            return issue.components;
+        default:
+            return undefined;
+    }
+}
+/**
+ * The issue exists. Say so, and say not to make another one.
+ *
+ * This is the failure an agent is most likely to answer by trying again, and
+ * trying again is the one thing that turns a wrong issue into two wrong
+ * issues.
+ */
+function verificationFailed(plan, issueKey, expected, observed) {
+    return new JamError("JAM_WRITE_VERIFICATION_FAILED", `Jira created ${issueKey}, but a direct read does not show what the plan intended. A workflow rule or a project automation may have altered the issue as it was created. The issue exists - look at it and fix it there, or delete it. Do not create another one.`, { issueKey, operation: plan.operation, expected, observed });
+}
+function sameValue(observed, expected) {
+    if (Array.isArray(expected) || Array.isArray(observed)) {
+        const a = Array.isArray(observed) ? [...observed].map(String).sort() : [];
+        const b = Array.isArray(expected) ? [...expected].map(String).sort() : [];
+        return a.length === b.length && a.every((value, i) => value === b[i]);
+    }
+    return observed === expected;
+}

package/dist/application/apply-write.js

@@ -1,6 +1,7 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertUnchanged } from "../policy/write-policy.js";
+import { applyCreateIssue } from "./apply-create-issue.js";
 import { readIssue } from "./plan-write.js";
 /**
  * Execute a plan JAM made, then go and look at what happened.
@@ -28,6 +29,11 @@ export async function applyWritePlan(deps, request) {
     if (readModeAfterWrite() !== "direct") {
         throw new JamError("CONFIG_INVALID", "Write confirmation must use a direct issue read.");
     }
+    // Creation follows the same three steps with a different first one: there is
+    // no issue to re-read, so what gets re-checked is the create schema the plan
+    // was built on. Both paths still end in a direct read of a real issue.
+    if (plan.kind === "create-issue")
+        return applyCreateIssue(deps, plan);
     const current = await readIssue(deps, plan.issueKey);
     assertUnchanged(plan.issueKey, plan.baseUpdated, current.updated);
     const outcome = await mutate(deps, plan);
@@ -65,6 +71,11 @@ async function mutate(deps, plan) {
             case "transition":
                 await deps.jiraWrite.transitionIssue(plan.issueKey, plan.mutation.transitionId);
                 return {};
+            case "create":
+                // Unreachable: a create plan is routed to applyCreateIssue above. The
+                // case exists so adding a mutation kind is a compile error here rather
+                // than a silent fall-through that writes nothing and reports success.
+                throw new JamError("CONFIG_INVALID", "A create mutation cannot be applied through the existing-issue path.");
         }
     }
     catch (err) {
@@ -94,10 +105,14 @@ function isAmbiguous(err) {
 async function verify(deps, plan) {
     const issue = await readIssue(deps, plan.issueKey);
     if (plan.mutation.kind === "comment") {
-        const { comments } = await deps.jira.getIssues({
-            keys: [plan.issueKey],
+        // Direct issue GET again, not the bulk endpoint: this is post-write
+        // confirmation, and ConsistencyPolicy makes no exception for the read that
+        // happens to want the comment field.
+        const { issue: withComments } = await deps.jira.getIssue({
+            key: plan.issueKey,
             fields: ["summary", "status", "comment", "updated"],
-        }).then((r) => ({ comments: r.issues[0]?.comments ?? [] }));
+        });
+        const comments = withComments?.comments ?? [];
         const wanted = plan.mutation.text.trim();
         const found = comments.some((c) => c.body.trim() === wanted);
         if (!found) {

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

@@ -0,0 +1,44 @@
+import type { JamDeps } from "../deps.js";
+import type { CreateIssueInput, CreateIssueWritePlan, WritePlanReceipt } from "../domain/write.js";
+export type PlanCreateIssueRequest = {
+    input: Record<string, unknown>;
+};
+/**
+ * Work out whether an issue can be created here, and describe the one JAM
+ * would create.
+ *
+ * Reads only - the create metadata endpoints answer questions about a
+ * project's configuration and change nothing. The order is the point:
+ *
+ *  1. Validate the request against JAM's own contract. Anything refusable
+ *     without asking Jira is refused before a round trip is spent on it.
+ *  2. Ask Jira which issue types this account can create here, and resolve the
+ *     requested one against that list. An id is never derived from a name.
+ *  3. Ask Jira what that issue type's create screen requires, and refuse now if
+ *     it requires something JAM cannot express. A create JAM knows Jira will
+ *     reject is not sent.
+ *  4. Resolve every constrained value against Jira's own allowed list.
+ *
+ * What comes out is a plan that records not just the intended issue but the
+ * premises it rests on, so apply can check they still hold.
+ *
+ * The target project is never a parameter. It is the project this workspace is
+ * bound to, which is what the user consented to when they set JAM up; taking
+ * it from the caller would make the binding advisory.
+ */
+export declare function planCreateIssue(deps: JamDeps, request: PlanCreateIssueRequest): Promise<{
+    plan: CreateIssueWritePlan;
+    receipt: WritePlanReceipt;
+}>;
+/** The project this workspace is bound to, or a refusal that says so. */
+export declare function configuredProject(deps: JamDeps): string;
+/**
+ * Check the request against the create contract, and normalize it.
+ *
+ * Pure: no Jira, no state. `key` is not accepted here at all - there is no
+ * issue to name - and neither is `project`, which comes from the binding.
+ * Anything outside CREATABLE_FIELDS is rejected rather than ignored: silently
+ * dropping a field an agent asked for would create an issue that is not the
+ * one it described.
+ */
+export declare function validateCreateInput(raw: Record<string, unknown>): CreateIssueInput;