Repository navigation
JAM v1.7.0
JAM v1.7.0 — writing Jira when the tools are unreachable
What changed
jam jira write-plan and jam jira write-apply. Reads got a shell address
in 1.4.6 and writes did not. The gap shows up in exactly the situation the reads
were opened for: a session whose MCP registry came up in a failed state cannot be
shown the tools — Claude Code has no reload surface for a running session — while
JAM, its credentials and its Jira access are all fine. That session could read
Jira and could not change it.
jam jira write-plan --operation <op> [--key KEY] --input '<json>'
jam jira write-apply <planId>Nothing here implements a second write path. Both call the same planWrite /
applyWritePlan the MCP tools call, with the same deps, project binding,
whitelist and normalized error codes. The two-call contract is not relaxed for
the shell: planning changes nothing, and apply takes a planId and has no flag
through which a payload could arrive. There is deliberately no jam jira comment
or jam jira close — a shortcut past planning is what the write plane exists to
prevent, and a terminal does not change that. issue.create goes through the
same write-plan rather than getting a command of its own.
Plans now live in a file, shared by both transports. They lived in the server
process, and the ADR said why. The same section named the condition for
revisiting — "if plans ever need to outlive a process" — and write-plan and
write-apply are two processes.
before in the server process, in memory
after ~/.jam/write-plans/<planId>.json, read by MCP and the CLI alike
Sharing the store is the point rather than a side effect: a plan made through
the tools can be applied from the shell after the tools stop answering, which
is the case this release exists for. Single use moved to the filesystem — take
claims a plan by renaming it, so two concurrent applies cannot both hold one.
For comment.add the alternative is two comments.
Integrity is re-derivation, not a signature. Apply reads the plan's own
recorded input, derives the mutation from it again, and refuses with the new
JAM_WRITE_PLAN_TAMPERED when the stored mutation is not what that input
produces. Editing the file to smuggle a different write means editing the input
to match — which is asking JAM to plan that write. The whitelist runs again too,
so an edited input cannot reach a field planning refuses. The check runs after
the revision check: a moved issue is a conflict, not tampering.
docs/decisions/adr-jira-write-plane.md §"Where plans live" is rewritten rather
than quietly contradicted, and it records what was lost as well as what was
gained.
What did not change
The MCP surface. Five tools, the same names, the same inputs, the same meta
semantics: jira_search, jira_context, jira_full, jira_write_plan,
jira_write_apply. The operation set and both whitelists are untouched, and so
is every existing error code.
JAM still has no Execution Mode. That axis belongs to ASC, and a Jira write still
travels ASC's decision path.
Install / Upgrade
jam updateMoves this machine's registration to the published release. It does not re-plan
the project binding — that is jam setup's job.
First run on a machine with no JAM:
npx --yes @jam-mcp/bootstrap@1.7.0 setup --agentAgent setup
Unchanged from 1.6.0. The agent entry points are the same:
npx --yes @jam-mcp/bootstrap@1.7.0 setup --agent
jam status --jsonAn agent that has just registered JAM and cannot yet see the tools now has a
complete shell path — reads since 1.4.6, and writes as of this release.
Compatibility
Node >= 20. The three packages ship in lockstep at 1.7.0 and depend on each
other at that exact version.
One state change on disk. Plans are now files under ~/.jam/write-plans/,
created 0600 in a 0700 directory. Nothing else in ~/.jam is touched, and
plans still expire in ten minutes and are still single-use. A plan made by 1.6.0
cannot exist across an upgrade — it was in a process that has since exited — so
there is nothing to migrate.
Verified
npx tsc --noEmit green
npm test 538 pass / 0 fail / 4 skipped (542)
npm run build green
npm run release:check consistent across manifests, code and docs
CI pr-title + ubuntu/windows × node 20/22, all green
Against real Jira, on a dedicated health-check issue in the bound project — no
team ticket was touched:
write-plan planned, no mutation
write-apply from a second process applied · verified: true
same planId again JAM_WRITE_PLAN_NOT_FOUND, directory empty
plan, move the issue, then apply JAM_WRITE_CONFLICT
edit the stored mutation, leave input JAM_WRITE_PLAN_TAMPERED, nothing reached Jira
read → plan → apply, no MCP at all applied · verified: true
The last line is what this release exists for.
Known limitations
JAM_WRITE_UNCERTAIN was not exercised. Its trigger is an ambiguous
transport failure — a request that may or may not have landed — and that cannot
be produced against real Jira on demand. Only its code path was read. This is
recorded rather than implied because it is the failure whose handling matters
most: retrying it is what turns one comment into two.
--input JSON does not survive PowerShell quoting.
PowerShell --input '{\"text\":\"...\"}' → "--input must be a JSON object."
Git Bash --input '{"text":"..."}' → fine
Not specific to JAM — the same happens to any CLI taking a JSON argument — but
it is a real obstacle in the environment this feature is most needed in, since
the sessions that lose their MCP tools are often on Windows. Use Git Bash, or
match PowerShell's quoting. A --input-file or reading the object from stdin
would remove the problem and is a candidate for a follow-up; neither was added
here to keep this release to the change it describes.
A mutation is now serialized where the machine's user can read and edit it.
That is a real reduction from "forgery is impossible" to "forgery gains
nothing", and it is the price of a write path that survives its transport. See
the ADR for why a signed token was still not the shape.