@jam-mcp/server 1.2.0 → 1.3.1

package/dist/application/apply-write.js

@@ -1,8 +1,10 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
+import { assertAssignable } from "../policy/assignee-policy.js";
+import { assertCustomFieldUnchanged } from "../policy/custom-field-policy.js";
 import { assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
-import { readIssue } from "./plan-write.js";
+import { currentCustomFieldView, readIssue } from "./plan-write.js";
 /**
  * Execute a plan JAM made, then go and look at what happened.
  *
@@ -35,7 +37,12 @@ export async function applyWritePlan(deps, request) {
     if (plan.kind === "create-issue")
         return applyCreateIssue(deps, plan);
     const current = await readIssue(deps, plan.issueKey);
-    assertUnchanged(plan.issueKey, plan.baseUpdated, current.updated);
+    assertUnchanged(plan.issueKey, plan.baseUpdated, current.issue.updated);
+    // Whatever the plan depends on that the revision check cannot see, checked
+    // again here. For an assignment that is the target's permission to hold this
+    // issue: it can be revoked between planning and applying, and a plan that
+    // was valid is not the same as a plan that is still valid.
+    await revalidate(deps, plan);
     const outcome = await mutate(deps, plan);
     const after = await verify(deps, plan);
     deps.writePlans.consume(plan.planId);
@@ -49,6 +56,26 @@ export async function applyWritePlan(deps, request) {
         ...(outcome.commentId ? { commentId: outcome.commentId } : {}),
     };
 }
+/**
+ * Re-derive the premises the revision check does not cover.
+ *
+ * Only `assignee.update` has any: the rest are fully described by the issue's
+ * own state, which `assertUnchanged` already compared.
+ */
+async function revalidate(deps, plan) {
+    if (plan.mutation.kind === "assignee") {
+        const target = plan.intendedAfter["assignee"];
+        assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
+        return;
+    }
+    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
+        // A field can be taken off a screen, lose its `set` operation, change type
+        // or have an option renamed without the issue's own revision moving, so
+        // `assertUnchanged` cannot see any of it. These are the premises the plan
+        // actually rested on, re-derived.
+        assertCustomFieldUnchanged(plan.issueKey, plan.customFieldRequirements, await deps.jiraEditMetadata.getEditableFields(plan.issueKey));
+    }
+}
 /**
  * Send the mutation, once.
  *
@@ -71,6 +98,17 @@ async function mutate(deps, plan) {
             case "transition":
                 await deps.jiraWrite.transitionIssue(plan.issueKey, plan.mutation.transitionId);
                 return {};
+            case "assignee":
+                await deps.jiraWrite.assignIssue(plan.issueKey, plan.mutation.accountId);
+                return {};
+            case "custom-field":
+                // The ordinary issue edit endpoint. A custom field is a field; what
+                // made it need its own operation was deciding whether it may be
+                // written and in what shape, and that is already settled here.
+                await deps.jiraWrite.updateIssue(plan.issueKey, {
+                    [plan.mutation.fieldId]: plan.mutation.value,
+                });
+                return {};
             case "create":
                 // Unreachable: a create plan is routed to applyCreateIssue above. The
                 // case exists so adding a mutation kind is a compile error here rather
@@ -103,7 +141,22 @@ function isAmbiguous(err) {
  * ours.
  */
 async function verify(deps, plan) {
-    const issue = await readIssue(deps, plan.issueKey);
+    const snapshot = await readIssue(deps, plan.issueKey, plan.mutation.kind === "custom-field" ? [plan.mutation.fieldId] : []);
+    const issue = snapshot.issue;
+    if (plan.mutation.kind === "assignee") {
+        // On the accountId, never on the display name. Two people can share a
+        // name, so a name comparison would accept the wrong person's assignment as
+        // proof of the right one's - which is the entire reason resolution went to
+        // the trouble of producing an identity.
+        const expected = plan.intendedAfter["assignee"];
+        const observed = snapshot.assigneeAccountId
+            ? { accountId: snapshot.assigneeAccountId, displayName: issue.assignee ?? "" }
+            : null;
+        if (snapshot.assigneeAccountId !== expected.accountId) {
+            throw verificationFailed(plan, { assignee: expected }, { assignee: observed });
+        }
+        return { assignee: { accountId: expected.accountId, displayName: issue.assignee ?? expected.displayName } };
+    }
     if (plan.mutation.kind === "comment") {
         // Direct issue GET again, not the bulk endpoint: this is post-write
         // confirmation, and ConsistencyPolicy makes no exception for the read that
@@ -120,6 +173,15 @@ async function verify(deps, plan) {
         }
         return { comments: comments.length, commentAdded: wanted };
     }
+    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
+        const requirements = plan.customFieldRequirements;
+        const expected = plan.intendedAfter["customField"];
+        const observedValue = currentCustomFieldView({ id: requirements.fieldId, name: requirements.fieldName }, requirements.kind, snapshot.customFieldValues?.[requirements.fieldId]);
+        if (!sameCustomFieldValue(requirements.kind, expected.value, observedValue.value)) {
+            throw verificationFailed(plan, { customField: expected }, { customField: observedValue });
+        }
+        return { customField: observedValue };
+    }
     const observed = observedFor(plan, issue);
     for (const [field, expected] of Object.entries(plan.intendedAfter)) {
         if (!sameValue(observed[field], expected)) {
@@ -153,6 +215,27 @@ function observedFor(plan, issue) {
     }
     return observed;
 }
+/**
+ * Did the field end up holding what was planned?
+ *
+ * Options are compared on their ids, never on their labels - an option is
+ * identified by its id, and a label is what a person reads. For a multi-select
+ * the comparison is set-wise: Jira is free to return the same selection in a
+ * different order, and that is not a different selection.
+ */
+function sameCustomFieldValue(kind, expected, observed) {
+    if (kind === "multi-option") {
+        const ids = (v) => (Array.isArray(v) ? v.map((o) => o.id) : []).sort();
+        const a = ids(expected);
+        const b = ids(observed);
+        return a.length === b.length && a.every((id, i) => id === b[i]);
+    }
+    if (kind === "single-option") {
+        const id = (v) => v && typeof v === "object" && !Array.isArray(v) ? v.id : undefined;
+        return id(expected) === id(observed);
+    }
+    return expected === observed;
+}
 function sameValue(observed, expected) {
     if (Array.isArray(expected) || Array.isArray(observed)) {
         const a = Array.isArray(observed) ? [...observed].map(String).sort() : [];

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

@@ -1,6 +1,6 @@
 import type { JamDeps } from "../deps.js";
 import type { FullIssueContext } from "../domain/context.js";
-import type { WritePlan, WritePlanReceipt } from "../domain/write.js";
+import type { CustomFieldKind, CustomFieldValueView, WritePlan, WritePlanReceipt } from "../domain/write.js";
 export type PlanWriteRequest = {
     /** Absent for `issue.create`, which names a project rather than an issue. */
     key?: string;
@@ -36,4 +36,22 @@ export declare function planWrite(deps: JamDeps, request: PlanWriteRequest): Pro
  * The one read every write goes through - the pre-write conflict check, the
  * post-write confirmation, and the post-create confirmation.
  */
-export declare function readIssue(deps: JamDeps, issueKey: string): Promise<FullIssueContext>;
+export type IssueSnapshot = {
+    issue: FullIssueContext;
+    /** Identity of the current assignee, which `issue.assignee` cannot supply. */
+    assigneeAccountId?: string;
+    /** Raw values for any custom field ids that were asked for. */
+    customFieldValues?: Record<string, unknown>;
+};
+export declare function readIssue(deps: JamDeps, issueKey: string, extraFields?: string[]): Promise<IssueSnapshot>;
+/**
+ * What the field holds now, in the shape a receipt shows.
+ *
+ * Jira stores an option as an object and a scalar as itself; a person reading
+ * `before` wants the same canonical form they will see in `intendedAfter`, so
+ * they can compare the two rather than a payload against a summary.
+ */
+export declare function currentCustomFieldView(field: {
+    id: string;
+    name: string;
+}, kind: CustomFieldKind, raw: unknown): CustomFieldValueView;

package/dist/application/plan-write.js

@@ -1,5 +1,7 @@
 import { JamError } from "../domain/errors.js";
 import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
+import { assertAssignable, assertNotAlreadyAssigned, exactMatches, resolveAssignee, } from "../policy/assignee-policy.js";
+import { assertEditable, classifyKind, resolveCustomFieldValue, resolveWritableField, } from "../policy/custom-field-policy.js";
 import { planCreateIssue } from "./plan-create-issue.js";
 /**
  * Work out whether a requested change is currently possible, and describe it.
@@ -30,8 +32,15 @@ export async function planWrite(deps, request) {
     // does not write should get that answer, not a round trip and then that
     // answer.
     const input = validateInput(operation, request.input);
-    const issue = await readIssue(deps, issueKey);
-    const { before, intendedAfter, mutation, transition } = await describe(deps, operation, issueKey, issue, input);
+    // Which custom field the whitelist says this is, settled before the read so
+    // the read can fetch its current value in the same request. A selector the
+    // team never opted in costs no Jira call at all.
+    const targetField = operation === "custom-field.update"
+        ? resolveWritableField(deps.config, input.field)
+        : undefined;
+    const snapshot = await readIssue(deps, issueKey, targetField ? [targetField.id] : []);
+    const issue = snapshot.issue;
+    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId, customFieldRequirements } = await describe(deps, operation, issueKey, snapshot, input, targetField);
     const createdAt = new Date();
     const plan = deps.writePlans.create({
         kind: "existing-issue",
@@ -44,6 +53,8 @@ export async function planWrite(deps, request) {
         createdAt: createdAt.toISOString(),
         expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
         ...(transition ? { transition } : {}),
+        ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
+        ...(customFieldRequirements ? { customFieldRequirements } : {}),
         mutation,
     });
     return {
@@ -60,20 +71,8 @@ export async function planWrite(deps, request) {
         },
     };
 }
-/**
- * The issue as Jira has it, read directly by key.
- *
- * `getIssue`, not `getIssues`: ConsistencyPolicy requires a direct issue GET
- * for anything that decides or confirms a write, and the bulk endpoint is not
- * one. A JQL result can lag behind the issue it describes; a bulk fetch is
- * free to answer from a different path than the single-issue endpoint. Neither
- * difference matters for ordinary reads, and both matter here.
- *
- * The one read every write goes through - the pre-write conflict check, the
- * post-write confirmation, and the post-create confirmation.
- */
-export async function readIssue(deps, issueKey) {
-    const { issue: found } = await deps.jira.getIssue({
+export async function readIssue(deps, issueKey, extraFields = []) {
+    const { issue: found, assigneeAccountId, customFieldValues } = await deps.jira.getIssue({
         key: issueKey,
         // `issuetype` and `description` are here for creation's verification step,
         // which has to confirm the issue Jira made is the one that was asked for.
@@ -85,17 +84,38 @@ export async function readIssue(deps, issueKey) {
             "status",
             "issuetype",
             "description",
+            "assignee",
             "priority",
             "labels",
             "components",
             "updated",
+            // A custom field is only read when one is being written, and then only
+            // that one - so a custom-field update still costs a single direct GET
+            // rather than a second read for the field it is about to change.
+            ...extraFields.filter((f) => !BASE_WRITE_FIELDS.has(f)),
         ],
     });
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return found;
+    return {
+        issue: found,
+        ...(assigneeAccountId ? { assigneeAccountId } : {}),
+        ...(customFieldValues ? { customFieldValues } : {}),
+    };
 }
+/** Requested on every write-plane read, so an extra field is never a duplicate. */
+const BASE_WRITE_FIELDS = new Set([
+    "summary",
+    "status",
+    "issuetype",
+    "description",
+    "assignee",
+    "priority",
+    "labels",
+    "components",
+    "updated",
+]);
 /**
  * The issue an existing-issue operation names, or a refusal that says why.
  *
@@ -136,9 +156,41 @@ function validateInput(operation, raw) {
             }
             return { status: status.trim() };
         }
+        case "custom-field.update": {
+            // Anything outside this operation's own two keys is refused rather than
+            // ignored. Silently dropping a key an agent supplied is how a caller
+            // ends up with a write that is not the one it described - and the shared
+            // input object means another operation's key is a plausible mistake.
+            const extra = Object.keys(raw).filter((k) => raw[k] !== undefined && k !== "field" && k !== "value");
+            if (extra.length > 0) {
+                throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", `custom-field.update takes only \`field\` and \`value\`. Remove: ${extra.join(", ")}.`, { operation, rejected: extra });
+            }
+            const { field, value } = raw;
+            if (typeof field !== "string" || field.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs non-empty `input.field` - a configured custom field id or name.", { operation });
+            }
+            // The value's family is checked against Jira's schema later; what is
+            // checked here is that it is a shape the contract admits at all. An
+            // object, a boolean or a null never reaches the type policy.
+            const isString = typeof value === "string";
+            const isNumber = typeof value === "number";
+            const isStringArray = Array.isArray(value) && value.every((v) => typeof v === "string");
+            if (!isString && !isNumber && !isStringArray) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs `input.value` to be a string, a number, or an array of strings.", { operation, received: Array.isArray(value) ? "array" : typeof value });
+            }
+            return { field: field.trim(), value };
+        }
+        case "assignee.update": {
+            const assignee = raw.assignee;
+            if (typeof assignee !== "string" || assignee.trim().length === 0) {
+                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs non-empty `input.assignee` - a display name, or an accountId.", { operation });
+            }
+            return { assignee: assignee.trim() };
+        }
     }
 }
-async function describe(deps, operation, issueKey, issue, input) {
+async function describe(deps, operation, issueKey, snapshot, input, targetField) {
+    const issue = snapshot.issue;
     switch (operation) {
         case "comment.add": {
             const { text } = input;
@@ -178,8 +230,79 @@ async function describe(deps, operation, issueKey, issue, input) {
                 transition,
             };
         }
+        case "custom-field.update": {
+            const field = targetField;
+            const requested = input;
+            // Jira decides what is editable here and now, and in what shape. JAM
+            // does not model project contexts, screens or permissions - it asks the
+            // one endpoint that answers all three at once for this issue.
+            const metadata = await deps.jiraEditMetadata.getEditableFields(issueKey);
+            const editable = assertEditable(issueKey, field, metadata);
+            const kind = classifyKind(editable);
+            const { jiraValue, view, resolvedOptions } = resolveCustomFieldValue(editable, kind, requested);
+            return {
+                before: {
+                    customField: currentCustomFieldView(field, kind, snapshot.customFieldValues?.[field.id]),
+                },
+                intendedAfter: { customField: view },
+                mutation: { kind: "custom-field", fieldId: field.id, value: jiraValue },
+                customFieldRequirements: {
+                    fieldId: field.id,
+                    fieldName: field.name,
+                    kind,
+                    schema: editable.schema,
+                    ...(resolvedOptions ? { resolvedOptions } : {}),
+                },
+            };
+        }
+        case "assignee.update": {
+            const { assignee: requested } = input;
+            // Ask Jira who this is, and decide from what it says. The requested
+            // string never reaches a mutation: what gets written is the accountId
+            // that resolution settled on, and resolution refuses rather than picks
+            // when the answer is not one person.
+            const target = resolveAssignee(requested, await findCandidates(deps, requested));
+            // Two independent refusals, in the order that costs least. Already-set
+            // needs no Jira call; assignability does.
+            assertNotAlreadyAssigned(issueKey, snapshot.assigneeAccountId, target);
+            assertAssignable(issueKey, target, await deps.jiraAssignees.isAssignable(issueKey, target.accountId));
+            return {
+                before: {
+                    assignee: snapshot.assigneeAccountId
+                        ? { accountId: snapshot.assigneeAccountId, displayName: issue.assignee ?? "" }
+                        : null,
+                },
+                intendedAfter: { assignee: target },
+                mutation: { kind: "assignee", accountId: target.accountId },
+                ...(snapshot.assigneeAccountId
+                    ? { baseAssigneeAccountId: snapshot.assigneeAccountId }
+                    : {}),
+            };
+        }
     }
 }
+/**
+ * Who Jira thinks this string could be.
+ *
+ * The search first, because it answers both halves of the contract most of the
+ * time - Jira's user search currently matches an accountId as readily as a
+ * name. "Currently" is the problem: that is a property of a substring search
+ * rather than a promise, and the contract says an accountId identifies a
+ * person. So when the search settles nothing, the exact lookup is asked before
+ * giving up.
+ *
+ * Ordered this way because it costs nothing on the paths that work. The extra
+ * request happens only where resolution was about to fail anyway, and the
+ * string is never inspected to guess whether it looks like an accountId - Jira
+ * is asked, and Jira answers.
+ */
+async function findCandidates(deps, requested) {
+    const candidates = await deps.jiraAssignees.searchUsers(requested);
+    if (exactMatches(requested, candidates).length > 0)
+        return candidates;
+    const byId = await deps.jiraAssignees.getUserByAccountId(requested);
+    return byId ? [byId] : candidates;
+}
 function currentValue(issue, field) {
     switch (field) {
         case "summary":
@@ -194,6 +317,31 @@ function currentValue(issue, field) {
             return undefined;
     }
 }
+/**
+ * What the field holds now, in the shape a receipt shows.
+ *
+ * Jira stores an option as an object and a scalar as itself; a person reading
+ * `before` wants the same canonical form they will see in `intendedAfter`, so
+ * they can compare the two rather than a payload against a summary.
+ */
+export function currentCustomFieldView(field, kind, raw) {
+    const named = { id: field.id, name: field.name };
+    if (kind === "multi-option") {
+        return { ...named, value: Array.isArray(raw) ? raw.map(toOptionView) : [] };
+    }
+    if (kind === "single-option") {
+        return { ...named, value: raw == null ? null : toOptionView(raw) };
+    }
+    if (raw == null)
+        return { ...named, value: null };
+    return { ...named, value: kind === "number" ? Number(raw) : String(raw) };
+}
+function toOptionView(raw) {
+    const o = raw;
+    const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : "";
+    const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : String(raw);
+    return { id, label };
+}
 /** Whitelisted values to the shapes Jira's field API expects. */
 function toJiraFields(input) {
     const fields = {};

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.2.0", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.1", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded path to one

package/dist/bootstrap/setup-plan.d.ts

@@ -64,10 +64,21 @@ export type SetupPlan = {
      * configured - so it is an `npx` bootstrap invocation, never a bare `jam`.
      * A human interface is free to render the short form; this field is the one
      * a script runs, and a script has no PATH to rely on.
+     *
+     * `userCommand` is the opposite: a command for the person, which the agent
+     * relays and never runs. Authentication is the only step of that shape, and
+     * it carries no `command` precisely so that no caller can execute it. The
+     * separation is the point - one field is for running, the other for showing.
+     *
+     * `env` names the variables that would satisfy the same requirement without
+     * the interactive command, so an agent that cannot show a prompt still knows
+     * what the person has to provide - never their values.
      */
     nextAction?: {
         type: "authenticate" | "select_project" | "configure_runtime";
         command?: string;
+        userCommand?: string;
+        env?: string[];
     };
     project?: {
         root: string;

package/dist/bootstrap/setup-plan.js

@@ -113,7 +113,16 @@ function finish(changes, state, project) {
             code: "JAM_AUTH_REQUIRED",
             changes,
             requiresUserAction: true,
-            nextAction: { type: "authenticate" },
+            nextAction: {
+                type: "authenticate",
+                // Deliberately no `command`: an agent must not run the login, and the
+                // absence is what stops it. `userCommand` is what it hands the person
+                // instead - previously that instruction existed only in CLI prose, so
+                // an agent reading the JSON alone knew a human was needed but not for
+                // what.
+                userCommand: portableBootstrapCommand("auth login"),
+                env: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+            },
             project,
         };
     }

package/dist/cli-entry.js

@@ -11,39 +11,39 @@ import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyComm
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export const USAGE = `jam - Jira Agent MCP
-
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
-  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
-                          alone, writing nothing to the repository; --shared
-                          adopts JAM for the team (project.yaml, .mcp.json)
-  jam runtime             Show which JAM build this machine runs
-  jam runtime use package | development <path>
-                          Change it (writes ~/.jam/config.yaml only, never a project)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
-
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
-
-Environment:
-  JIRA_BASE_URL     https://your-site.atlassian.net
-  JIRA_EMAIL        Atlassian account email
-  JIRA_API_TOKEN    Atlassian API token
-  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
-                     .jira-agent/project.yaml exists yet
-
-Credentials and JAM_PROJECT_KEY are read from the current shell's environment
-first, then (on Windows) from the User environment - so a value set with
-\`setx\` works without opening a new terminal.
+export const USAGE = `jam - Jira Agent MCP
+
+Usage:
+  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
+  jam doctor              Diagnose config, credentials and Jira connectivity
+  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
+                          Wire up this project and run doctor. Binds it to you
+                          alone, writing nothing to the repository; --shared
+                          adopts JAM for the team (project.yaml, .mcp.json)
+  jam runtime             Show which JAM build this machine runs
+  jam runtime use package | development <path>
+                          Change it (writes ~/.jam/config.yaml only, never a project)
+  jam auth login          Store Jira credentials in this user's OS secret store
+  jam auth logout         Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam doctor --json       Health check as structured output
+  jam auth status --json  Whether Jira credentials are configured (never their value)
+
+Environment:
+  JIRA_BASE_URL     https://your-site.atlassian.net
+  JIRA_EMAIL        Atlassian account email
+  JIRA_API_TOKEN    Atlassian API token
+  JAM_PROJECT_KEY   Jira project key, used by \`jam setup\`/\`jam serve\` when no
+                     .jira-agent/project.yaml exists yet
+
+Credentials and JAM_PROJECT_KEY are read from the current shell's environment
+first, then (on Windows) from the User environment - so a value set with
+\`setx\` works without opening a new terminal.
 `;
 function findFlagValue(argv, flag) {
     const index = argv.indexOf(flag);

package/dist/config/schema.d.ts

@@ -19,6 +19,7 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     customFields: z.ZodDefault<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
+        writable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     output: z.ZodPrefault<z.ZodObject<{
         searchTokens: z.ZodDefault<z.ZodNumber>;

package/dist/config/schema.js

@@ -1,4 +1,23 @@
 import { z } from "zod";
+/** Values that appear more than once, each named once. */
+function duplicates(values) {
+    const seen = new Set();
+    const repeated = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            repeated.add(value);
+        seen.add(value);
+    }
+    return [...repeated];
+}
+function report(ctx, repeated, what) {
+    for (const value of repeated) {
+        ctx.addIssue({
+            code: "custom",
+            message: `duplicate custom field ${what} "${value}" - a selector must name one field`,
+        });
+    }
+}
 /**
  * `.jira-agent/project.yaml` - per-project policy only.
  * Credentials are never stored here; they come from the CredentialPort.
@@ -41,13 +60,28 @@ export const ProjectConfigSchema = z.object({
     /**
      * Whitelisted project-specific custom fields, surfaced at CONTEXT level and up.
      * `id` is the Jira field id (customfield_10011); `name` is what the agent sees.
+     *
+     * `writable` is a second, separate consent. Reading a field and letting an
+     * agent change it are different decisions, and a config written when JAM
+     * could only read must not start granting writes because JAM learned how.
+     * So it defaults to false: every whitelist that predates this is read-only,
+     * and a team opts a field in by saying so.
      */
     customFields: z
         .array(z.object({
         id: z.string().regex(/^customfield_\d+$/),
         name: z.string().min(1),
+        writable: z.boolean().default(false),
     }))
-        .default([]),
+        .default([])
+        .superRefine((fields, ctx) => {
+        // Ambiguity in a whitelist is worse than an omission: `custom-field.update`
+        // resolves a selector against these entries, and two rows answering to
+        // the same selector would make which field gets written a matter of
+        // ordering.
+        report(ctx, duplicates(fields.map((f) => f.id.toLowerCase())), "id");
+        report(ctx, duplicates(fields.filter((f) => f.writable).map((f) => f.name.trim().toLowerCase())), "writable name");
+    }),
     output: z
         .object({
         /** Rough token ceilings per level. Enforced by OutputBudgetPolicy. */

package/dist/deps.d.ts

@@ -4,7 +4,9 @@ import type { ProjectConfig } from "./config/schema.js";
 import type { CachePort } from "./ports/cache.port.js";
 import type { CredentialPort } from "./ports/credentials.port.js";
 import type { JiraReadPort } from "./ports/jira-read.port.js";
+import type { JiraAssigneeResolutionPort } from "./ports/jira-assignee-resolution.port.js";
 import type { JiraCreateMetadataPort } from "./ports/jira-create-metadata.port.js";
+import type { JiraEditMetadataPort } from "./ports/jira-edit-metadata.port.js";
 import type { JiraWritePort } from "./ports/jira-write.port.js";
 import { WritePlanStore } from "./application/write-plan-store.js";
 import type { TelemetryPort } from "./ports/telemetry.port.js";
@@ -29,6 +31,18 @@ export type JamDeps = {
      * completeness semantics would mean nothing for it.
      */
     jiraCreateMetadata: JiraCreateMetadataPort;
+    /**
+     * Who a name refers to, and who may hold an issue. A fourth port for the
+     * same reason as the third: it reads a directory rather than an issue, and
+     * it mutates nothing.
+     */
+    jiraAssignees: JiraAssigneeResolutionPort;
+    /**
+     * What Jira will let this account change on one issue. A fifth read-shaped
+     * port, for the same reason as the third and fourth: it mutates nothing, and
+     * it answers a question about a configuration rather than about an issue.
+     */
+    jiraEditMetadata: JiraEditMetadataPort;
     /**
      * Plans awaiting apply. Lives for the life of this server process - see
      * WritePlanStore for why it is not persisted.
@@ -46,6 +60,10 @@ export type BuildDepsOptions = {
     jiraWrite?: JiraWritePort;
     /** Injected by tests so create metadata comes from a fixture, not a site. */
     jiraCreateMetadata?: JiraCreateMetadataPort;
+    /** Injected by tests so user resolution never reaches a real directory. */
+    jiraAssignees?: JiraAssigneeResolutionPort;
+    /** Injected by tests so edit metadata comes from a fixture, not a site. */
+    jiraEditMetadata?: JiraEditMetadataPort;
     /** Injected by tests to bypass the real process/registry credential lookup. */
     credentials?: CredentialPort;
     /**