@jam-mcp/server 1.0.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 colosair
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 colosair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,65 +1,86 @@
-# @jam-mcp/server
-
-JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
-
-JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
-should not be making — which fields to request, when to paginate, when to read
-the comment thread, what to do when a result is too big — so everyday reads stay
-cheap and important judgements still get full context.
-
-## The three tools
-
-The external contract is exactly three tools. Adding or renaming one is a
-breaking change.
-
-| Tool | Use it for |
-|---|---|
-| `jira_search` | listing, discovery, "what's open", picking candidates |
-| `jira_context` | readiness, blockers, dependencies, priority |
-| `jira_full` | agreement, contract, approval, closure |
-
-A `jira_search` result is never complete issue context — nothing about
-agreement, approval, or done-ness follows from it.
-
-## Evidence boundary
-
-Every result carries a `meta` block, and nothing is ever truncated silently.
-
-`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
-is not a statement about the project: not readiness, not "unblocked", not "the
-whole story". What JAM did not look at is named in the same block —
-`evidenceScope` and `limitations` call out the repository, external sources, and
-dependencies that live outside Jira. `provenance` and `source` say where the
-records came from.
-
-So an empty comment thread on a complete read is a complete read *of Jira*, not
-proof that nothing was agreed. If the issue points at an external canonical
-source, that source is what settles the question.
-
-## Running it
-
-Normally you don't run this package directly — your coding agent launches
-[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
-resolves which JAM build this machine runs and dispatches here. Going through
-the launcher is what keeps a committed `.mcp.json` free of machine-specific
-paths.
-
-The `jam` CLI is the same binary:
-
-```text
-jam serve      Run the MCP server over stdio
-jam doctor     Diagnose config, credentials and Jira connectivity
-jam setup      Wire up JAM and verify (personal by default; --shared for the team)
-jam auth login Store Jira credentials in this user's OS secret store
-jam runtime    Show or change which JAM build this machine runs
-```
-
-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
-results. `stdout` is reserved for the MCP protocol and for JSON output;
-diagnostics go to `stderr`.
-
-## More
-
-- [Repository README](https://github.com/colosair/jam#readme)
-- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)
+# @jam-mcp/server
+
+JAM (Jira Agent MCP) itself: the MCP server, the setup core, and the `jam` CLI.
+
+JAM is an agent-facing Jira **read** layer. It takes over the decisions an agent
+should not be making — which fields to request, when to paginate, when to read
+the comment thread, what to do when a result is too big — so everyday reads stay
+cheap and important judgements still get full context.
+
+## The tools
+
+The external contract is five tools. Adding or renaming one is a breaking
+change.
+
+| Tool | Use it for |
+|---|---|
+| `jira_search` | listing, discovery, "what's open", picking candidates |
+| `jira_context` | readiness, blockers, dependencies, priority |
+| `jira_full` | agreement, contract, approval, closure |
+| `jira_write_plan` | work out how to change an issue — changes nothing |
+| `jira_write_apply` | apply a plan, then confirm it by reading the issue back |
+
+A `jira_search` result is never complete issue context — nothing about
+agreement, approval, or done-ness follows from it.
+
+Writing is deliberately two calls. `jira_write_apply` takes a `planId` and no
+payload, so a change cannot be made that JAM has not first read the issue for,
+checked against the configured project, and described. Before writing it
+re-reads the issue and refuses if it moved; after writing it reads again and
+refuses to report success unless the intended result is actually there. An
+ambiguous failure is reported as uncertain rather than retried — retrying a
+write that may have landed is how one comment becomes two.
+
+Three operations: `comment.add` (plain text, converted to ADF here),
+`field.update` (summary, priority, labels, components), and `status.transition`
+(matched against the transitions Jira currently offers, never a guessed id).
+
+## Evidence boundary
+
+Every result carries a `meta` block, and nothing is ever truncated silently.
+
+`meta.complete` means **JAM finished the Jira retrieval with no known loss**. It
+is not a statement about the project: not readiness, not "unblocked", not "the
+whole story". What JAM did not look at is named in the same block —
+`evidenceScope` and `limitations` call out the repository, external sources, and
+dependencies that live outside Jira. `provenance` and `source` say where the
+records came from.
+
+So an empty comment thread on a complete read is a complete read *of Jira*, not
+proof that nothing was agreed. If the issue points at an external canonical
+source, that source is what settles the question.
+
+## Running it
+
+Don't install this package to use JAM. Your coding agent launches
+[`@jam-mcp/launcher`](https://www.npmjs.com/package/@jam-mcp/launcher), which
+reads your `~/.jam/config.yaml`, decides which JAM build this machine should
+run, and dispatches here. Naming the server directly instead pins one machine
+to one build and bypasses that choice — and it is what keeps a committed
+`.mcp.json` free of machine-specific paths.
+
+The same binary carries the CLI, and every command below is reachable through
+the launcher:
+
+```text
+serve        Run the MCP server over stdio
+doctor       Diagnose config, credentials and Jira connectivity
+setup        Wire up JAM and verify (personal by default; --shared for the team)
+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.1.0 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.1.0 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
+results. `stdout` is reserved for the MCP protocol and for JSON output;
+diagnostics go to `stderr`.
+
+## More
+
+- [Repository README](https://github.com/colosair/jam#readme)
+- [JAM design of record](https://github.com/colosair/jam/blob/main/docs/architecture/jira-agent-mcp-design.md)

package/dist/adapters/jira-cloud/jira-client.d.ts

@@ -2,9 +2,18 @@ import { JamError } from "../../domain/errors.js";
 import type { CredentialPort } from "../../ports/credentials.port.js";
 export type JiraRequest = {
     path: string;
-    method?: "GET" | "POST";
+    method?: "GET" | "POST" | "PUT";
     query?: Record<string, string | number | undefined>;
     body?: unknown;
+    /**
+     * Whether a transient failure may be retried.
+     *
+     * Reads say yes and get the retry loop below. Writes say no: a request that
+     * timed out may already have been applied, so resending it is how one
+     * comment becomes two. The write path resolves that ambiguity by reading the
+     * issue back, never by trying again.
+     */
+    retry?: boolean;
 };
 export type JiraResponse<T> = {
     data: T;

package/dist/adapters/jira-cloud/jira-client.js

@@ -67,7 +67,7 @@ export class JiraClient {
             // ponytail: fixed 2 retries on transient statuses; add backoff tuning if
             // `complete` searches start tripping Jira's rate limiter in practice.
             const transient = res.status === 429 || res.status >= 500;
-            if (transient && attempt < MAX_RETRIES) {
+            if (req.retry !== false && transient && attempt < MAX_RETRIES) {
                 lastError = error;
                 await sleep(retryDelayMs(res.headers.get("retry-after"), attempt));
                 continue;

package/dist/adapters/jira-cloud/jira-write.adapter.d.ts

@@ -1,12 +1,41 @@
+import type { JiraTransition } from "../../domain/write.js";
+import type { CredentialPort } from "../../ports/credentials.port.js";
 import type { JiraWritePort } from "../../ports/jira-write.port.js";
 /**
- * Deliberate stub. The first release is read-only; the existing Atlassian MCP
- * remains the write path. The port exists so adding writes later is an adapter
- * swap rather than an application-layer change.
+ * Jira Cloud REST v3, mutating half.
+ *
+ * Every request here sets `retry: false`. The read adapter's retry loop is
+ * correct for reads and dangerous here: a request that times out after Jira
+ * accepted it is indistinguishable from one Jira never saw, and resending it
+ * duplicates the change. The application layer resolves that by reading the
+ * issue back - see applyWritePlan.
+ *
+ * This adapter also never reads its own work. Confirmation is a direct issue
+ * GET through the read port, which keeps "what JAM did" and "what Jira shows"
+ * two separate observations rather than one hopeful one.
  */
-export declare class UnsupportedJiraWriteAdapter implements JiraWritePort {
-    updateIssue(): Promise<void>;
-    addComment(): Promise<{
+export declare class JiraCloudWriteAdapter implements JiraWritePort {
+    private readonly client;
+    constructor(credentials: CredentialPort, fetchImpl?: typeof fetch);
+    updateIssue(key: string, fields: Record<string, unknown>): Promise<void>;
+    /**
+     * Add a comment, converting plain text to ADF here rather than accepting ADF.
+     *
+     * Jira's comment body is a document tree, and letting an agent supply one
+     * would mean accepting arbitrary structure - panels, mentions, embedded
+     * content - through a field that reads like "text". The conversion is narrow
+     * on purpose: paragraphs, and nothing else.
+     */
+    addComment(key: string, body: string): Promise<{
         id: string;
     }>;
+    getTransitions(key: string): Promise<JiraTransition[]>;
+    transitionIssue(key: string, transitionId: string): Promise<void>;
 }
+/**
+ * Plain text to the narrowest ADF that represents it.
+ *
+ * Blank lines separate paragraphs; everything else is literal. No markdown is
+ * interpreted, so a comment containing `*` or `#` says what it says.
+ */
+export declare function textToAdf(text: string): unknown;

package/dist/adapters/jira-cloud/jira-write.adapter.js

@@ -1,17 +1,97 @@
 import { JamError } from "../../domain/errors.js";
+import { JiraClient } from "./jira-client.js";
 /**
- * Deliberate stub. The first release is read-only; the existing Atlassian MCP
- * remains the write path. The port exists so adding writes later is an adapter
- * swap rather than an application-layer change.
+ * Jira Cloud REST v3, mutating half.
+ *
+ * Every request here sets `retry: false`. The read adapter's retry loop is
+ * correct for reads and dangerous here: a request that times out after Jira
+ * accepted it is indistinguishable from one Jira never saw, and resending it
+ * duplicates the change. The application layer resolves that by reading the
+ * issue back - see applyWritePlan.
+ *
+ * This adapter also never reads its own work. Confirmation is a direct issue
+ * GET through the read port, which keeps "what JAM did" and "what Jira shows"
+ * two separate observations rather than one hopeful one.
  */
-export class UnsupportedJiraWriteAdapter {
-    async updateIssue() {
-        throw notSupported();
+export class JiraCloudWriteAdapter {
+    client;
+    constructor(credentials, fetchImpl) {
+        this.client = fetchImpl
+            ? new JiraClient(credentials, fetchImpl)
+            : new JiraClient(credentials);
     }
-    async addComment() {
-        throw notSupported();
+    async updateIssue(key, fields) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}`,
+            method: "PUT",
+            body: { fields },
+            retry: false,
+        });
+    }
+    /**
+     * Add a comment, converting plain text to ADF here rather than accepting ADF.
+     *
+     * Jira's comment body is a document tree, and letting an agent supply one
+     * would mean accepting arbitrary structure - panels, mentions, embedded
+     * content - through a field that reads like "text". The conversion is narrow
+     * on purpose: paragraphs, and nothing else.
+     */
+    async addComment(key, body) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/comment`,
+            method: "POST",
+            body: { body: textToAdf(body) },
+            retry: false,
+        });
+        if (!data?.id) {
+            // Jira accepted it but told us nothing identifying. Treat that as
+            // unconfirmed rather than inventing an id: the caller's direct read is
+            // what decides whether the comment exists.
+            throw new JamError("JAM_WRITE_UNCERTAIN", `Jira accepted a comment on ${key} but returned no comment id, so JAM cannot confirm which comment it created.`, { issueKey: key });
+        }
+        return { id: data.id };
+    }
+    async getTransitions(key) {
+        const { data } = await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+            // A read, but on the write path: its answer decides a mutation, so a
+            // retried-and-stale transition list would be worse than a failure.
+            retry: false,
+        });
+        return (data.transitions ?? [])
+            .filter((t) => typeof t.id === "string")
+            .map((t) => ({
+            id: t.id,
+            name: t.name ?? t.id,
+            to: t.to?.name ?? t.name ?? "",
+        }));
+    }
+    async transitionIssue(key, transitionId) {
+        await this.client.request({
+            path: `rest/api/3/issue/${encodeURIComponent(key)}/transitions`,
+            method: "POST",
+            body: { transition: { id: transitionId } },
+            retry: false,
+        });
     }
 }
-function notSupported() {
-    return new JamError("CONFIG_INVALID", "JAM is read-only in this release. Use the Atlassian MCP for Jira writes.");
+/**
+ * Plain text to the narrowest ADF that represents it.
+ *
+ * Blank lines separate paragraphs; everything else is literal. No markdown is
+ * interpreted, so a comment containing `*` or `#` says what it says.
+ */
+export function textToAdf(text) {
+    const paragraphs = text
+        .split(/\n{2,}/)
+        .map((block) => block.trim())
+        .filter(Boolean);
+    return {
+        type: "doc",
+        version: 1,
+        content: (paragraphs.length > 0 ? paragraphs : [text]).map((block) => ({
+            type: "paragraph",
+            content: [{ type: "text", text: block }],
+        })),
+    };
 }

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

@@ -0,0 +1,25 @@
+import type { JamDeps } from "../deps.js";
+import type { WriteApplyReceipt } from "../domain/write.js";
+export type ApplyWriteRequest = {
+    planId: string;
+};
+/**
+ * Execute a plan JAM made, then go and look at what happened.
+ *
+ * Three things happen in order, and none of them can be skipped:
+ *
+ *  1. Re-read the issue and compare its revision to the plan's. A plan that
+ *     was valid is not the same as a plan that is still valid.
+ *  2. Send the mutation the plan recorded. The caller never supplies it, so
+ *     there is no path from "an agent wants to write X" to "JAM writes X"
+ *     that does not pass through planning.
+ *  3. Read the issue again and check the intended result is actually there.
+ *     Jira accepting a request is not evidence that the issue changed - a
+ *     transition can be accepted and land somewhere else, a field update can
+ *     be silently dropped by a screen configuration.
+ *
+ * A write that cannot be confirmed is never reported as success. Depending on
+ * why, that is JAM_WRITE_VERIFICATION_FAILED (Jira answered, and shows
+ * something else) or JAM_WRITE_UNCERTAIN (we do not know whether it landed).
+ */
+export declare function applyWritePlan(deps: JamDeps, request: ApplyWriteRequest): Promise<WriteApplyReceipt>;

package/dist/application/apply-write.js

@@ -0,0 +1,151 @@
+import { JamError, toJamError } from "../domain/errors.js";
+import { readModeAfterWrite } from "../policy/consistency-policy.js";
+import { assertUnchanged } from "../policy/write-policy.js";
+import { readIssue } from "./plan-write.js";
+/**
+ * Execute a plan JAM made, then go and look at what happened.
+ *
+ * Three things happen in order, and none of them can be skipped:
+ *
+ *  1. Re-read the issue and compare its revision to the plan's. A plan that
+ *     was valid is not the same as a plan that is still valid.
+ *  2. Send the mutation the plan recorded. The caller never supplies it, so
+ *     there is no path from "an agent wants to write X" to "JAM writes X"
+ *     that does not pass through planning.
+ *  3. Read the issue again and check the intended result is actually there.
+ *     Jira accepting a request is not evidence that the issue changed - a
+ *     transition can be accepted and land somewhere else, a field update can
+ *     be silently dropped by a screen configuration.
+ *
+ * A write that cannot be confirmed is never reported as success. Depending on
+ * why, that is JAM_WRITE_VERIFICATION_FAILED (Jira answered, and shows
+ * something else) or JAM_WRITE_UNCERTAIN (we do not know whether it landed).
+ */
+export async function applyWritePlan(deps, request) {
+    const plan = deps.writePlans.take(request.planId);
+    // Post-write reads are direct by policy; so is this pre-write one. Both
+    // decide a mutation, and a search result can lag behind the issue it names.
+    if (readModeAfterWrite() !== "direct") {
+        throw new JamError("CONFIG_INVALID", "Write confirmation must use a direct issue read.");
+    }
+    const current = await readIssue(deps, plan.issueKey);
+    assertUnchanged(plan.issueKey, plan.baseUpdated, current.updated);
+    const outcome = await mutate(deps, plan);
+    const after = await verify(deps, plan);
+    deps.writePlans.consume(plan.planId);
+    return {
+        status: "applied",
+        issue: plan.issueKey,
+        operation: plan.operation,
+        before: plan.before,
+        after,
+        verified: true,
+        ...(outcome.commentId ? { commentId: outcome.commentId } : {}),
+    };
+}
+/**
+ * Send the mutation, once.
+ *
+ * There is no retry here and there must not be one. A request that fails
+ * ambiguously - a timeout, a dropped connection - may already have been
+ * applied, and resending it turns one comment into two or replays a
+ * transition. So an ambiguous failure is converted into JAM_WRITE_UNCERTAIN
+ * and handed back with what to do about it: look, do not retry.
+ */
+async function mutate(deps, plan) {
+    try {
+        switch (plan.mutation.kind) {
+            case "comment": {
+                const { id } = await deps.jiraWrite.addComment(plan.issueKey, plan.mutation.text);
+                return { commentId: id };
+            }
+            case "fields":
+                await deps.jiraWrite.updateIssue(plan.issueKey, plan.mutation.fields);
+                return {};
+            case "transition":
+                await deps.jiraWrite.transitionIssue(plan.issueKey, plan.mutation.transitionId);
+                return {};
+        }
+    }
+    catch (err) {
+        const jamError = toJamError(err);
+        if (!isAmbiguous(jamError))
+            throw jamError;
+        throw new JamError("JAM_WRITE_UNCERTAIN", `JAM could not tell whether the ${plan.operation} on ${plan.issueKey} was applied: ${jamError.message} Read the issue to find out - do not retry this write, which could apply it twice.`, { issueKey: plan.issueKey, operation: plan.operation, cause: jamError.code });
+    }
+}
+/**
+ * A failure that says nothing about whether Jira acted.
+ *
+ * A 403 or a 400 is a decision Jira made and did not act on. A dropped
+ * connection or a 5xx is not: the request may have been processed before the
+ * answer went missing.
+ */
+function isAmbiguous(err) {
+    return err.code === "JIRA_UNAVAILABLE" || err.code === "RATE_LIMITED";
+}
+/**
+ * Confirm by reading, and say what was expected when the reading disagrees.
+ *
+ * Comments are confirmed by the comment appearing, not by a count: another
+ * writer could have added one in between, and a count would accept theirs as
+ * ours.
+ */
+async function verify(deps, plan) {
+    const issue = await readIssue(deps, plan.issueKey);
+    if (plan.mutation.kind === "comment") {
+        const { comments } = await deps.jira.getIssues({
+            keys: [plan.issueKey],
+            fields: ["summary", "status", "comment", "updated"],
+        }).then((r) => ({ comments: r.issues[0]?.comments ?? [] }));
+        const wanted = plan.mutation.text.trim();
+        const found = comments.some((c) => c.body.trim() === wanted);
+        if (!found) {
+            throw verificationFailed(plan, { commentAdded: wanted }, { comments: comments.length });
+        }
+        return { comments: comments.length, commentAdded: wanted };
+    }
+    const observed = observedFor(plan, issue);
+    for (const [field, expected] of Object.entries(plan.intendedAfter)) {
+        if (!sameValue(observed[field], expected)) {
+            throw verificationFailed(plan, plan.intendedAfter, observed);
+        }
+    }
+    return observed;
+}
+function observedFor(plan, issue) {
+    const observed = {};
+    for (const field of Object.keys(plan.intendedAfter)) {
+        switch (field) {
+            case "status":
+                observed[field] = issue.status;
+                break;
+            case "summary":
+                observed[field] = issue.summary;
+                break;
+            case "priority":
+                observed[field] = issue.priority;
+                break;
+            case "labels":
+                observed[field] = issue.labels;
+                break;
+            case "components":
+                observed[field] = issue.components;
+                break;
+            default:
+                observed[field] = undefined;
+        }
+    }
+    return observed;
+}
+function sameValue(observed, expected) {
+    if (Array.isArray(expected) || Array.isArray(observed)) {
+        const a = Array.isArray(observed) ? [...observed].map(String).sort() : [];
+        const b = Array.isArray(expected) ? [...expected].map(String).sort() : [];
+        return a.length === b.length && a.every((value, i) => value === b[i]);
+    }
+    return observed === expected;
+}
+function verificationFailed(plan, expected, observed) {
+    return new JamError("JAM_WRITE_VERIFICATION_FAILED", `Jira accepted the ${plan.operation} on ${plan.issueKey}, but a direct read does not show the intended result. The issue may have been changed by something else, or a workflow rule may have altered the outcome.`, { issueKey: plan.issueKey, operation: plan.operation, expected, observed });
+}

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

@@ -0,0 +1,32 @@
+import type { JamDeps } from "../deps.js";
+import type { FullIssueContext } from "../domain/context.js";
+import type { WritePlan, WritePlanReceipt } from "../domain/write.js";
+export type PlanWriteRequest = {
+    key: string;
+    operation: string;
+    input: Record<string, unknown>;
+};
+/**
+ * Work out whether a requested change is currently possible, and describe it.
+ *
+ * Reads only. Nothing here mutates Jira, and that is the whole point of the
+ * step: the agent gets to see what the issue looks like now, what JAM would
+ * do to it, and what a direct read will have to show before JAM will call it
+ * done - all before anything has happened.
+ *
+ * The order matters. Scope and operation are checked before any Jira call, so
+ * an out-of-scope key costs nothing and comes back as a JAM refusal rather
+ * than a 404. Everything after that is derived from the issue as Jira reports
+ * it right now, never from what the caller asserted about it.
+ */
+export declare function planWrite(deps: JamDeps, request: PlanWriteRequest): Promise<{
+    plan: WritePlan;
+    receipt: WritePlanReceipt;
+}>;
+/**
+ * The issue as Jira has it, read directly by key.
+ *
+ * A direct read, never a search: ConsistencyPolicy requires it for anything
+ * that decides a write, and a JQL result can lag behind the issue it describes.
+ */
+export declare function readIssue(deps: JamDeps, issueKey: string): Promise<FullIssueContext>;