Repository navigation
JAM v1.4.5
JAM 1.4.5 makes a Jira reference survivable. Every issue now carries issueId
— Jira's immutable id — beside key, and statusCategory beside status, so
an agent can hold a reference that does not move and can tell whether something
is finished without matching localized status text. It also states the rule
that was missing: a Jira issue key is minted by Jira and is never predicted.
The five-tool MCP surface is unchanged. Everything here is additive output and
costs no extra Jira request.
What changed
issueIdtravels withkey. At all three read levels, and on nested
references — parent, subtasks, and both sides of an issue link — wherever
Jira supplies one. A key is the current human- and integration-facing
locator and Jira can move it to another issue;issueIdis the issue.
Nothing is fabricated: a payload without an id leaves the field absent
rather than empty.statusCategorytravels withstatus. Jira's own machine-readable
category key, passed through unchanged.statusis a workflow-defined,
localized name, so matching it against words is wrong in some project or
some language. JAM does not rename Jira's values, does not derive one from a
status name, and does not turn it into a verdict of its own.- Issue-key prediction is forbidden, and gated.
AGENTS.mdand
CLAUDE.mdcarry a mirrored "Jira issue keys" section: never synthesize,
increment, predict, reserve, or infer the availability of a key; positively
resolve an exact key against live Jira before reusing it; a key that did not
resolve is unusable and is not evidence the number is free.
release:checkfails if any of those three claims leaves either file. - Writes are pinned to the issue, not to the string. A plan records the
target'sissueId; apply asks the identity question before the revision
question, and again on the verification read. A key that has come to name a
different issue stops withJAM_WRITE_CONFLICTbefore anything is written.
A direct read returning an issue with no canonical id is refused
(PARTIAL_RESULT) rather than carried into a plan; list reads are
unaffected. - Both write receipts report
issueId,issue.createincluded — taken
from the verification read that was already happening. - No extra Jira traffic.
idandkeyare properties of the issue
resource rather than fields, andstatusCategoryarrives inside the
statusfield that was always requested. No nested reference is ever
fetched to fill in an id.
The reasoning is recorded in
ADR: Jira reference integrity.
Install / Upgrade
npx --yes @jam-mcp/bootstrap@1.4.5 initOptional persistent command:
npm install -g @jam-mcp/launcher@1.4.5Existing users: re-run setup. Bindings, runtime selection, host registration
and credentials are untouched.
Agent setup
The canonical entry is unchanged:
npx --yes @jam-mcp/bootstrap@1.4.5 setup --agentCompatibility
- Node 20 or newer, unchanged. The five-tool MCP surface is unchanged — same
names, same input schemas. - Additive JSON only:
issueIdandstatusCategoryon read results and on
nested references,issueIdon the plan and apply receipts. A consumer that
ignores them sees the contract it saw before. - No GitHub/GitLab runtime dependency. JAM does not create branches, read
commits or manage pull requests, and gains none of that here.
Verified
- Build, 39 launcher + 493 server tests,
release:check, pack and tarball
smoke — green locally on Windows and on CI (Ubuntu/Windows × Node 20/22). - Live read acceptance against a real Jira project, read-only:
issueId
equals Jira's raw id and is not the key;statusCategoryequals the raw
statusCategory.keyand is not the status name; the same issue read through
two endpoints reports the same id; 20 issues and 20 nested references all
carried identity in one Jira request. Zero mutations. - A key that does not resolve comes back in
meta.missingKeyswith
complete: false, and nothing in the result says or implies the number is
free. - The documentation gate was proven by removing a phrase and watching
release:checkfail. - Consumer compatibility: an existing MCP consumer's projection was driven
with real output from this release and is unchanged in shape — the additive
fields are ignored, which is the intended outcome.
Known limitations
- Live
issue.createwas not exercised. Creating an issue is not
reversible and a disposable fixture is not worth an unwanted issue on a real
board, so the create path's identity receipt is covered by unit and
integration tests rather than by a live mutation. - Nested identity is as good as Jira's payload. Where a response shape
does not carry an id for a nested reference, the field is absent. JAM will
not fetch the reference to fill it in — that would trade a correctness fix
for an N+1. - No Git or SCM enforcement, deliberately. JAM removes the premise the
mistake rests on and states the correct procedure where an agent reads it.
Guarding branches, commits and pull requests belongs to a control plane
above JAM, which can build it on the identity JAM now returns. - Subtask creation is still out of scope.
issue.createtakes no parent;
that is a write-capability change with its own schema and verification
questions.