Skip to content

JAM v1.4.5

Choose a tag to compare

@github-actions github-actions released this 05 Sep 11:51
· 10 commits to main since this release
75e86e9

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

  • issueId travels with key. 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; issueId is the issue.
    Nothing is fabricated: a payload without an id leaves the field absent
    rather than empty.
  • statusCategory travels with status. Jira's own machine-readable
    category key, passed through unchanged. status is 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.md and
    CLAUDE.md carry 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:check fails if any of those three claims leaves either file.
  • Writes are pinned to the issue, not to the string. A plan records the
    target's issueId; 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 with JAM_WRITE_CONFLICT before 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.create included — taken
    from the verification read that was already happening.
  • No extra Jira traffic. id and key are properties of the issue
    resource rather than fields, and statusCategory arrives inside the
    status field 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 init

Optional persistent command:

npm install -g @jam-mcp/launcher@1.4.5

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

Compatibility

  • Node 20 or newer, unchanged. The five-tool MCP surface is unchanged — same
    names, same input schemas.
  • Additive JSON only: issueId and statusCategory on read results and on
    nested references, issueId on 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; statusCategory equals the raw
    statusCategory.key and 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.missingKeys with
    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:check fail.
  • 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.create was 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.create takes no parent;
    that is a write-capability change with its own schema and verification
    questions.