@jam-mcp/server 1.4.4 → 1.4.6

package/README.md

@@ -74,10 +74,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.4.4 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.6 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.4.4 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.6 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/jira-cloud/mapper.js

@@ -22,6 +22,15 @@ export function mapIssueWithMeta(raw, config) {
         customFields: mapCustomFields(f, config),
         comments: [],
     };
+    // Jira returns `id` as a property of the issue resource, not as a field, so
+    // it arrives whatever the field list says and costs nothing to keep. Set
+    // only when Jira sent one: an empty string would read as an identity that
+    // was looked at and found blank.
+    if (raw.id)
+        issue.issueId = raw.id;
+    const statusCategory = category(f["status"]);
+    if (statusCategory)
+        issue.statusCategory = statusCategory;
     const assignee = user(f["assignee"]);
     if (assignee)
         issue.assignee = assignee;
@@ -123,12 +132,17 @@ export function normalizeFieldValue(value) {
 }
 function issueRef(raw) {
     const ref = { key: raw.key ?? "" };
+    if (raw.id)
+        ref.issueId = raw.id;
     const summary = raw.fields?.summary;
     if (summary)
         ref.summary = summary;
     const status = raw.fields?.status?.name;
     if (status)
         ref.status = status;
+    const statusCategory = raw.fields?.status?.statusCategory?.key;
+    if (statusCategory)
+        ref.statusCategory = statusCategory;
     return ref;
 }
 function str(v) {
@@ -137,6 +151,17 @@ function str(v) {
 function named(v) {
     return v?.name;
 }
+/**
+ * Jira's status category key, or nothing.
+ *
+ * Nothing, specifically, rather than a guess: the alternative is matching
+ * `status.name` against a list of words that mean "done", which is wrong in
+ * every language a project is not configured in and wrong in English the
+ * moment someone renames a status.
+ */
+function category(v) {
+    return v?.statusCategory?.key;
+}
 function user(v) {
     const u = v;
     return u?.displayName ?? u?.emailAddress ?? undefined;

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

@@ -26,11 +26,12 @@ export async function applyCreateIssue(deps, plan) {
     }
     await revalidateSchema(deps, plan);
     const created = await create(deps, plan);
-    const after = await verify(deps, plan, created.key);
+    const { observed: after, issueId } = await verify(deps, plan, created);
     deps.writePlans.consume(plan.planId);
     return {
         status: "applied",
         issue: created.key,
+        issueId,
         operation: plan.operation,
         before: plan.before,
         after,
@@ -118,7 +119,8 @@ function isAmbiguous(err) {
  * 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) {
+async function verify(deps, plan, created) {
+    const issueKey = created.key;
     // 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
@@ -127,7 +129,15 @@ async function verify(deps, plan, issueKey) {
     if (createdProject !== plan.projectKey) {
         throw verificationFailed(plan, issueKey, { project: plan.projectKey }, { project: createdProject ?? issueKey });
     }
-    const { issue } = await readIssue(deps, issueKey);
+    const { issue, issueId } = await readIssue(deps, issueKey);
+    // Jira named both the id and the key when it accepted the create; the
+    // read-back names them again. They have to agree - a key that already
+    // resolves to a different issue than the one just created is the one case
+    // where reporting the created key would point whoever reads the receipt at
+    // somebody else's issue.
+    if (issueId !== created.id) {
+        throw verificationFailed(plan, issueKey, { issueId: created.id }, { issueId });
+    }
     const observed = {};
     for (const field of Object.keys(plan.intendedAfter)) {
         observed[field] = observedValue(issue, field);
@@ -137,7 +147,7 @@ async function verify(deps, plan, issueKey) {
             throw verificationFailed(plan, issueKey, plan.intendedAfter, observed);
         }
     }
-    return observed;
+    return { observed, issueId };
 }
 /**
  * The created issue's value for one requested field.

package/dist/application/apply-write.js

@@ -1,7 +1,7 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertAssignable } from "../policy/assignee-policy.js";
-import { assertUnchanged } from "../policy/write-policy.js";
+import { assertSameIssue, assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
 import { readIssue } from "./plan-write.js";
 /**
@@ -36,6 +36,10 @@ export async function applyWritePlan(deps, request) {
     if (plan.kind === "create-issue")
         return applyCreateIssue(deps, plan);
     const current = await readIssue(deps, plan.issueKey);
+    // Identity before revision: if the key now names a different issue, its
+    // `updated` timestamp is a fact about something nobody planned to change,
+    // and comparing it would be answering the wrong question.
+    assertSameIssue(plan.issueKey, plan.issueId, current.issueId);
     assertUnchanged(plan.issueKey, plan.baseUpdated, current.issue.updated);
     // Whatever the plan depends on that the revision check cannot see, checked
     // again here. For an assignment that is the target's permission to hold this
@@ -48,6 +52,7 @@ export async function applyWritePlan(deps, request) {
     return {
         status: "applied",
         issue: plan.issueKey,
+        issueId: plan.issueId,
         operation: plan.operation,
         before: plan.before,
         after,
@@ -126,6 +131,10 @@ function isAmbiguous(err) {
 async function verify(deps, plan) {
     const snapshot = await readIssue(deps, plan.issueKey);
     const issue = snapshot.issue;
+    // The same identity question again, for the read that produces the evidence.
+    // Confirming the intended value on an issue the key has since come to name
+    // would be reporting somebody else's state as proof of our write.
+    assertSameIssue(plan.issueKey, plan.issueId, snapshot.issueId);
     if (plan.mutation.kind === "assignee") {
         // On the accountId, never on the display name. Two people can share a
         // name, so a name comparison would accept the wrong person's assignment as

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

@@ -38,6 +38,16 @@ export declare function planWrite(deps: JamDeps, request: PlanWriteRequest): Pro
  */
 export type IssueSnapshot = {
     issue: FullIssueContext;
+    /**
+     * The issue's canonical Jira id, carried separately because the write plane
+     * requires it and the read shape only offers it.
+     *
+     * A key is a locator: Jira can move one between issues, and an integration
+     * that recorded a key months ago is holding a string, not a target. Every
+     * write is pinned to this instead - planned against it, re-checked against
+     * it before the mutation, and confirmed against it afterwards.
+     */
+    issueId: string;
     /** Identity of the current assignee, which `issue.assignee` cannot supply. */
     assigneeAccountId?: string;
 };

package/dist/application/plan-write.js

@@ -38,6 +38,7 @@ export async function planWrite(deps, request) {
     const plan = deps.writePlans.create({
         kind: "existing-issue",
         issueKey,
+        issueId: snapshot.issueId,
         projectKey,
         operation,
         before,
@@ -55,6 +56,7 @@ export async function planWrite(deps, request) {
             status: "planned",
             planId: plan.planId,
             issue: plan.issueKey,
+            issueId: plan.issueId,
             operation: plan.operation,
             before: plan.before,
             intendedAfter: plan.intendedAfter,
@@ -86,7 +88,20 @@ export async function readIssue(deps, issueKey) {
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
+    // Jira answered with an issue but named no canonical id. That is not a
+    // resolution JAM can build a write on, and it is refused here - at the one
+    // read every write goes through - rather than by filling the field with an
+    // empty string and carrying a fake identity into a plan. Reads are
+    // unaffected: a list of issues is not invalidated because one entry arrived
+    // thin, and only the write plane treats identity as proof.
+    if (!found.issueId) {
+        throw new JamError("PARTIAL_RESULT", `Jira returned ${issueKey} without a canonical issue id, so JAM cannot confirm which issue this key currently names. Read the issue in Jira before changing it.`, { issueKey });
+    }
+    return {
+        issue: found,
+        issueId: found.issueId,
+        ...(assigneeAccountId ? { assigneeAccountId } : {}),
+    };
 }
 /**
  * The issue an existing-issue operation names, or a refusal that says why.

package/dist/application/search-issues.js

@@ -77,10 +77,19 @@ export async function searchIssues(deps, input) {
 }
 /** Project down to lite fields so heavy data cannot leak through this path. */
 export function toSummary(issue) {
+    // Identity and status semantics ride along at every level, next to the
+    // fields they qualify. Both are already in the payload this projection is
+    // narrowing, so carrying them costs nothing - and dropping them would make
+    // the cheapest read the one an agent cannot safely act on: a key with no
+    // identity behind it, and a status name whose meaning it would have to
+    // guess. Spread rather than assigned afterwards so the JSON an agent reads
+    // puts each beside its subject.
     const summary = {
         key: issue.key,
+        ...(issue.issueId ? { issueId: issue.issueId } : {}),
         summary: issue.summary,
         status: issue.status,
+        ...(issue.statusCategory ? { statusCategory: issue.statusCategory } : {}),
         updated: issue.updated,
         labels: issue.labels,
         components: issue.components,

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

package/dist/cli/jira-read.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reading Jira without the MCP channel.
+ *
+ * JAM's reads have lived only behind MCP tools. That is the right home when the
+ * agent's session already has them - but a session that registers JAM cannot be
+ * shown the new tools: Claude Code has no reload surface (`claude mcp` offers
+ * add / get / list / login / remove / reset-project-choices / serve, and nothing
+ * that re-reads registrations for a running session). So the agent that just
+ * installed JAM has to wait for its next session before it can read anything.
+ *
+ * What it did instead was worse: it answered Jira questions from whatever was at
+ * hand - git log, the code host, project documents - which is the exact
+ * substitution JAM exists to prevent.
+ *
+ * This is the same read, addressed differently. `search` / `context` / `full`
+ * call the same application functions the tools call, with the same deps, the
+ * same policies and the same `meta`. Nothing here re-implements a read, and
+ * nothing here is a second source of truth.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ */
+import { type BuildDepsOptions, type JamDeps } from "../deps.js";
+export declare const JIRA_READ_USAGE = "Usage:\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n\nReads only. Output is one JSON document on stdout - the same result the MCP\ntools return, for a session that cannot see them yet.\n";
+export type JiraReadOptions = BuildDepsOptions & {
+    /** Injected by tests so no test reaches a real Jira. */
+    deps?: JamDeps;
+    /** Where the JSON document goes. Defaults to stdout. */
+    write?: (text: string) => void;
+    /** Where diagnostics go. Defaults to stderr. */
+    warn?: (text: string) => void;
+};
+export declare function runJiraRead(argv: readonly string[], options?: JiraReadOptions): Promise<number>;

package/dist/cli/jira-read.js

@@ -0,0 +1,98 @@
+/**
+ * Reading Jira without the MCP channel.
+ *
+ * JAM's reads have lived only behind MCP tools. That is the right home when the
+ * agent's session already has them - but a session that registers JAM cannot be
+ * shown the new tools: Claude Code has no reload surface (`claude mcp` offers
+ * add / get / list / login / remove / reset-project-choices / serve, and nothing
+ * that re-reads registrations for a running session). So the agent that just
+ * installed JAM has to wait for its next session before it can read anything.
+ *
+ * What it did instead was worse: it answered Jira questions from whatever was at
+ * hand - git log, the code host, project documents - which is the exact
+ * substitution JAM exists to prevent.
+ *
+ * This is the same read, addressed differently. `search` / `context` / `full`
+ * call the same application functions the tools call, with the same deps, the
+ * same policies and the same `meta`. Nothing here re-implements a read, and
+ * nothing here is a second source of truth.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ */
+import { getFullIssueContext } from "../application/get-full-issue-context.js";
+import { getIssueContext } from "../application/get-issue-context.js";
+import { searchIssues } from "../application/search-issues.js";
+import { buildDeps } from "../deps.js";
+import { toJamError } from "../domain/errors.js";
+export const JIRA_READ_USAGE = `Usage:
+  jam jira search <jql> [--scope preview|complete]
+  jam jira context <KEY> [KEY...]
+  jam jira full <KEY> [KEY...]
+
+Reads only. Output is one JSON document on stdout - the same result the MCP
+tools return, for a session that cannot see them yet.
+`;
+/** `--scope complete` / `--scope=complete`, and nothing invented when absent. */
+function flagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index >= 0)
+        return argv[index + 1];
+    const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
+    return inline ? inline.slice(flag.length + 1) : undefined;
+}
+const positional = (argv) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--scope") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        out.push(arg);
+    }
+    return out;
+};
+export async function runJiraRead(argv, options = {}) {
+    const write = options.write ?? ((text) => process.stdout.write(text));
+    const warn = options.warn ?? ((text) => process.stderr.write(text));
+    const [subcommand, ...rest] = argv;
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        warn(JIRA_READ_USAGE);
+        return subcommand ? 0 : 1;
+    }
+    if (subcommand !== "search" && subcommand !== "context" && subcommand !== "full") {
+        warn(`Unknown jira command: ${subcommand}\n\n${JIRA_READ_USAGE}`);
+        return 1;
+    }
+    const args = positional(rest);
+    if (args.length === 0) {
+        warn(subcommand === "search" ? "jam jira search needs a JQL query.\n" : `jam jira ${subcommand} needs at least one issue key.\n`);
+        return 1;
+    }
+    const scope = flagValue(rest, "--scope");
+    if (scope !== undefined && scope !== "preview" && scope !== "complete") {
+        warn(`--scope is preview|complete (got ${scope}).\n`);
+        return 1;
+    }
+    try {
+        const { deps: injected, write: _w, warn: _n, ...depsOptions } = options;
+        const deps = injected ?? (await buildDeps(depsOptions));
+        const result = subcommand === "search"
+            ? await searchIssues(deps, { jql: args.join(" "), ...(scope ? { scope } : {}) })
+            : subcommand === "context"
+                ? await getIssueContext(deps, { issueKeys: args })
+                : await getFullIssueContext(deps, { issueKeys: args });
+        write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (err) {
+        // The same normalized codes the tools produce - an agent reads one contract,
+        // not two.
+        write(`${JSON.stringify(toJamError(err).toPayload())}\n`);
+        return 1;
+    }
+}

package/dist/cli-entry.d.ts

@@ -3,5 +3,5 @@
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
+export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
 export declare function runJamCommand(argv: string[]): Promise<number>;

package/dist/cli-entry.js

@@ -6,6 +6,7 @@ import { setup } from "./cli/setup.js";
 import { runSetupWizard } from "./cli/setup-wizard.js";
 import { reportPromptError, Ui } from "./cli/ui.js";
 import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyCommand, setupPlanCommand, } from "./cli/agent-api.js";
+import { runJiraRead } from "./cli/jira-read.js";
 /**
  * Command dispatch for the JAM CLI, separated from the bin so other entry
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
@@ -33,6 +34,11 @@ For coding agents and scripts (stdout is JSON only, never prompts):
                           Execute the plan
   jam doctor --json       Health check as structured output
   jam auth status --json  Whether Jira credentials are configured (never their value)
+  jam jira search <jql> [--scope preview|complete]
+  jam jira context <KEY> [KEY...]
+  jam jira full <KEY> [KEY...]
+                          Read Jira from the shell - the same reads the MCP
+                          tools do, for a session that cannot see them yet
 
 Environment:
   JIRA_BASE_URL     https://your-site.atlassian.net
@@ -112,6 +118,10 @@ export async function runJamCommand(argv) {
             process.stderr.write("Usage: jam auth login | status [--json] | logout\n");
             return 1;
         }
+        case "jira":
+            // Reads addressed to the shell, for a session that cannot see the MCP
+            // tools yet. Same application path as the tools - see cli/jira-read.ts.
+            return runJiraRead(rest);
         case "help":
         case "--help":
         case "-h":

package/dist/domain/issue.d.ts

@@ -1,7 +1,24 @@
+/**
+ * A reference to a Jira issue.
+ *
+ * `key` is what a person types, a branch name carries and an integration links
+ * on - and it is not an identity. Jira mints keys per project and a key can be
+ * moved between issues, so the same string can name a different issue later.
+ * `issueId` is the identity: the immutable id Jira assigns once and never
+ * reuses.
+ *
+ * `issueId` is optional because JAM will not invent one. Jira supplies it on
+ * every issue resource and on the nested references it embeds, but a payload
+ * that omits it leaves the field absent rather than empty - "not returned" and
+ * "returned blank" are different facts, and only one of them is true.
+ */
 export type IssueRef = {
     key: string;
+    issueId?: string;
     summary?: string;
     status?: string;
+    /** See IssueSummary.statusCategory. */
+    statusCategory?: string;
 };
 /**
  * SEARCH level. Deliberately excludes description/comments/attachments/changelog
@@ -9,8 +26,25 @@ export type IssueRef = {
  */
 export type IssueSummary = {
     key: string;
+    /** Jira's immutable issue id. See IssueRef. */
+    issueId?: string;
     summary: string;
     status: string;
+    /**
+     * Jira's own machine-readable status category key, as Jira publishes it -
+     * currently `new`, `indeterminate` or `done`, plus `undefined` for a status
+     * in no category.
+     *
+     * Passed through, never derived. `status` is a workflow-defined, localized
+     * name: a project can call a category-`done` status "Shipped", "완료" or
+     * "Won't Fix", and matching those strings is how an agent decides an issue
+     * is finished when it is not. This is the field to read instead, and JAM
+     * neither renames Jira's values nor turns them into a verdict of its own.
+     *
+     * Absent when Jira returned a status without a category. Absent is absent -
+     * it is not `new`.
+     */
+    statusCategory?: string;
     assignee?: string;
     priority?: string;
     updated: string;

package/dist/domain/write.d.ts

@@ -172,6 +172,16 @@ type WritePlanCommon = {
 export type ExistingIssueWritePlan = WritePlanCommon & {
     kind: "existing-issue";
     issueKey: string;
+    /**
+     * The canonical Jira id of the issue this plan was made against.
+     *
+     * `issueKey` says where to look; this says what was found there. They are
+     * not the same guarantee: a key is a locator Jira can move between issues,
+     * so re-reading the key at apply time can return a different issue than the
+     * one the plan described. Comparing this is what turns "the key still
+     * resolves" into "it still resolves to the issue that was planned".
+     */
+    issueId: string;
     operation: ExistingIssueOperation;
     baseUpdated: string;
     /**
@@ -239,6 +249,11 @@ export type WritePlanReceipt = {
      * yet - a placeholder key here would be a claim JAM cannot make.
      */
     issue?: string;
+    /**
+     * The canonical Jira id of that issue. Absent for `issue.create` for the
+     * same reason `issue` is: Jira mints both, and it has not been asked yet.
+     */
+    issueId?: string;
     /** The project a new issue would be created in. Present for `issue.create`. */
     project?: string;
     /** How the result of applying this plan will be confirmed. */
@@ -253,6 +268,14 @@ export type WriteApplyReceipt = {
     status: "applied";
     /** For `issue.create`, the key Jira minted - known only after applying. */
     issue: string;
+    /**
+     * The canonical Jira id of the issue that was written, read back from Jira.
+     *
+     * What to record if this write is going to be referred to later. The key is
+     * how a person and an integration will find the issue; this is what says the
+     * thing they find is the thing that was changed.
+     */
+    issueId: string;
     operation: WriteOperation;
     before: Record<string, unknown>;
     after: Record<string, unknown>;

package/dist/mcp/tools/jira-context.tool.js

@@ -9,7 +9,11 @@ Returns everything jira_search returns plus issue type, parent, subtasks, issue
 
 This is the Jira-recorded evidence relevant to readiness, blockers, dependencies and priority - not a readiness verdict. blocksThisIssue reports how Jira words a link; an empty links array means Jira holds no visible link for you, not that nothing blocks the work. Repository and external sources are not evaluated.
 
-Pass every key you care about in one call; they are fetched in a single batched round trip. Check meta.complete and meta.missingKeys before drawing conclusions.`;
+Every issue carries issueId, Jira's immutable id, alongside key. The key is the current human- and integration-facing locator and Jira can move it to another issue; issueId is the identity. Record issueId when a reference has to survive. statusCategory is Jira's own machine-readable category for the status - read it instead of matching status text, which is workflow-defined and localized. Parent, subtasks and links carry issueId too, wherever Jira supplies one.
+
+Pass every key you care about in one call; they are fetched in a single batched round trip. Check meta.complete and meta.missingKeys before drawing conclusions.
+
+This is also how a Jira issue key is checked. Asking for an exact key and getting an issue back is a positive resolution: that key names that issue, right now. A key listed in meta.missingKeys resolved to nothing JAM can see - it may not exist, or it may not be visible to this account, and those are indistinguishable from here. Either way it is unusable, and it is NOT evidence that the number is free, unused or reservable. Never synthesize, increment, predict or reserve a Jira issue key; keys are minted by Jira.`;
 export function registerJiraContext(server, deps) {
     server.registerTool("jira_context", {
         title: "Jira issue context (dependencies, blockers, readiness)",

package/dist/mcp/tools/jira-full.tool.js

@@ -5,7 +5,7 @@ const DESCRIPTION = `Get the complete record for one or more Jira issues, includ
 
 Use for final judgements: was this agreed, is the contract settled, was it approved, can it be closed, what did the other team actually answer, what does this issue mean right now.
 
-Returns everything jira_context returns plus description and every comment (normalized to plain text). This is the most expensive tool - prefer jira_search for listing and jira_context for readiness, and reach for this one when the answer must not be wrong.
+Returns everything jira_context returns - issueId and statusCategory included - plus description and every comment (normalized to plain text). This is the most expensive tool - prefer jira_search for listing and jira_context for readiness, and reach for this one when the answer must not be wrong.
 
 Ask for as few keys as possible: with several issues at once the output budget may drop the oldest comments. Always check meta.commentsComplete and meta.complete - if either is false, the thread you are reading is partial and a "yes, it is agreed" answer is not supported.
 

package/dist/mcp/tools/jira-search.tool.js

@@ -5,10 +5,12 @@ const DESCRIPTION = `Find Jira issues by JQL and get a lightweight list back.
 
 Use for: discovery, listing, "what is open", "what is assigned to me", recent changes, picking candidate issues.
 
-Returns key, summary, status, assignee, priority, updated, labels and components only. It deliberately does NOT return description, comments, attachments or links - that keeps listing cheap.
+Returns key, issueId, summary, status, statusCategory, assignee, priority, updated, labels and components only. It deliberately does NOT return description, comments, attachments or links - that keeps listing cheap.
 
 Because of that, a jira_search result is NOT complete issue context. Never conclude from it that something is agreed, approved, unblocked, or done. Follow up with jira_context (readiness, blockers, dependencies, priority) or jira_full (agreement, contract, approval, closure).
 
+Every issue carries issueId, Jira's immutable id, alongside key. The key is the current human- and integration-facing locator and Jira can move it to another issue; issueId is the identity. Record issueId when a reference has to survive. statusCategory is Jira's own machine-readable category for the status - read it instead of matching status text, which is workflow-defined and localized.
+
 Repository and external sources are not evaluated.
 
 scope="preview" (default) returns the first page for interactive exploration. scope="complete" walks every page - use it whenever the answer depends on the total count or on seeing every match. Check meta.complete before treating the list as exhaustive.`;

package/dist/policy/write-policy.d.ts

@@ -31,6 +31,21 @@ export declare function projectKeyOf(issueKey: string): string | undefined;
  * comment - must not be able to reach into another team's project through it.
  */
 export declare function assertWriteScope(issueKey: string, configuredProject: string): string;
+/**
+ * The key still names the issue the plan was made against.
+ *
+ * A revision check answers "has this issue changed"; this answers the question
+ * underneath it - "is this the same issue at all". Jira keys are locators, not
+ * identities: one can be moved to another issue, and an integration holding
+ * the string would then be pointed somewhere nobody chose. Re-reading the key
+ * and finding a different canonical id means the plan describes an issue this
+ * key no longer names, and the answer is a new plan, not this write.
+ *
+ * JAM_WRITE_CONFLICT rather than a code of its own: the situation is the one
+ * an agent already knows how to handle - the ground moved, plan again against
+ * the current state - and a second code for it would only fragment that.
+ */
+export declare function assertSameIssue(issueKey: string, planned: string, observed: string): void;
 export declare function assertOperationAllowed(operation: string): WriteOperation;
 /**
  * Narrow an already-allowed operation to one that acts on an existing issue.

package/dist/policy/write-policy.js

@@ -48,6 +48,25 @@ export function assertWriteScope(issueKey, configuredProject) {
     }
     return project;
 }
+/**
+ * The key still names the issue the plan was made against.
+ *
+ * A revision check answers "has this issue changed"; this answers the question
+ * underneath it - "is this the same issue at all". Jira keys are locators, not
+ * identities: one can be moved to another issue, and an integration holding
+ * the string would then be pointed somewhere nobody chose. Re-reading the key
+ * and finding a different canonical id means the plan describes an issue this
+ * key no longer names, and the answer is a new plan, not this write.
+ *
+ * JAM_WRITE_CONFLICT rather than a code of its own: the situation is the one
+ * an agent already knows how to handle - the ground moved, plan again against
+ * the current state - and a second code for it would only fragment that.
+ */
+export function assertSameIssue(issueKey, planned, observed) {
+    if (planned === observed)
+        return;
+    throw new JamError("JAM_WRITE_CONFLICT", `${issueKey} no longer names the issue this plan was made against (planned ${planned}, now ${observed}). Plan again against the issue the key names now.`, { issueKey, plannedIssueId: planned, observedIssueId: observed });
+}
 export function assertOperationAllowed(operation) {
     if (!isWriteOperation(operation)) {
         throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", `"${operation}" is not a JAM write operation. Supported: ${WRITE_OPERATIONS.join(", ")}.`, { operation, supported: [...WRITE_OPERATIONS] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
   "keywords": [
     "jira",
@@ -41,7 +41,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jam-mcp/launcher": "1.4.4",
+    "@jam-mcp/launcher": "1.4.6",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"