Repository navigation
docs: align documentation with the 1.6 product contract - #38
Merged
Merged
Conversation
Four things read as current instructions while stating something the product no longer does. **Node.** The manifests declare `engines.node >= 20` in all three packages, and the 1.6.0 note said "Node 22 or newer". Corrected to what the machine enforces. **doctor vs status.** `jam status` is the lifecycle command; `doctor` is the older name that still works and prints a deprecation line. The README listed `doctor` first and explained it as the primary diagnostic. It now leads with the six lifecycle words — setup, status, update, refresh, uninstall, runtime, the same ones ASC answers to — and `serve` is named as what the host launches rather than something a person types. The instruction-shaped `doctor` mentions elsewhere moved to `status`; the ones inside ADRs, past release notes and recorded acceptance runs stayed exactly as they are, because those are records of what was run. **Architecture.** `jira-agent-mcp-design.md` is referenced as the design of record from six places, so it keeps its path and numbering and is now labelled as the historical baseline, naming what actually changed: the external contract is five tools (three read, two write), not three. `current-architecture.md` is the short current one — responsibilities, the five tools, key vs issueId vs statusCategory, the read and write paths, the lifecycle, and where JAM's boundary with ASC and with Jira falls. **Release procedure vs release evidence.** `operations/release.md` carried both the procedure and every past acceptance transcript. One file cannot be both: a procedure moves when the product moves, a record has to stay still. The transcripts moved verbatim to `release-evidence.md`, nothing deleted, and the procedure links to them. Also: `release-check` no longer pins the 29-line Jira-key section word for word between AGENTS.md and CLAUDE.md. What has to hold is the three load-bearing claims, which a separate check already verifies in both files; freezing the prose froze it for the wrong reason. AGENTS.md keeps the long form, CLAUDE.md carries the contract and points at it. Runtime changes: none. Co-Authored-By: Claude Opus 5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. No runtime, package, version or tag changes.
What became canonical
docs/architecture/current-architecture.md— what JAM is today: its responsibilities, thefive MCP tools (three read, two write), key vs
issueIdvsstatusCategory, the read andwrite paths with their failure vocabulary, the six lifecycle words, and where the boundary
with ASC and with Jira falls.
The README now leads with those lifecycle words —
setup,status,update,refresh,uninstall,runtime— and namesjam servefor what it is: what Claude Code and Codexlaunch, not something a person types.
What was reclassified as historical
docs/architecture/jira-agent-mcp-design.mdkeeps its path and numbering: six documentsand ADRs cite it as the design of record. It is now labelled a historical baseline and
names what changed — the external contract is five tools, not three, and
doctoris theold name for
status.docs/operations/release-evidence.mdholds the past acceptance transcripts, movedverbatim out of
release.md. Nothing was deleted. One file cannot be both a procedure anda record: the procedure moves when the product moves, the record has to stay still.
What factual contradictions were corrected
docs/releases/v1.6.0.mdsaid "Node 22 or newer". Every manifest declaresengines.node >= 20. Corrected to what the machine enforces.jam doctoras the primary diagnostic.jam statusis thelifecycle command;
doctorstill works and prints a deprecation line. Theinstruction-shaped mentions elsewhere (
setup-ux.md, the release procedure) moved tostatus.What duplicate prose was removed
release-checkpinned the 29-line "Jira issue keys" section word for word acrossAGENTS.md and CLAUDE.md. That froze the wording for the wrong reason: what has to hold is
the three load-bearing claims, and a separate check already verifies exactly those in both
files. AGENTS.md keeps the long form with the failure it comes from; CLAUDE.md carries the
contract and points at it. The install-instruction mirror stays — that one drifted in
practice and the drift was the incident.
What was deliberately NOT moved or rewritten
Verification
🤖 Generated with Claude Code