@jam-mcp/server 1.2.0 → 1.3.1

package/dist/deps.js

@@ -38,6 +38,16 @@ export async function buildDeps(options = {}) {
         const { JiraCloudCreateMetadataAdapter } = await import("./adapters/jira-cloud/jira-create-metadata.adapter.js");
         jiraCreateMetadata = new JiraCloudCreateMetadataAdapter(credentials);
     }
+    let jiraAssignees = options.jiraAssignees;
+    if (!jiraAssignees) {
+        const { JiraCloudAssigneeResolutionAdapter } = await import("./adapters/jira-cloud/jira-assignee-resolution.adapter.js");
+        jiraAssignees = new JiraCloudAssigneeResolutionAdapter(credentials);
+    }
+    let jiraEditMetadata = options.jiraEditMetadata;
+    if (!jiraEditMetadata) {
+        const { JiraCloudEditMetadataAdapter } = await import("./adapters/jira-cloud/jira-edit-metadata.adapter.js");
+        jiraEditMetadata = new JiraCloudEditMetadataAdapter(credentials);
+    }
     return {
         config: resolved.config,
         configPath: resolved.configPath,
@@ -45,6 +55,8 @@ export async function buildDeps(options = {}) {
         jira,
         jiraWrite,
         jiraCreateMetadata,
+        jiraAssignees,
+        jiraEditMetadata,
         writePlans: new WritePlanStore(),
         cache: new NoopCache(),
         telemetry,

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE", "JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -34,6 +34,20 @@ export const JAM_ERROR_CODES = [
     "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED",
     "JAM_WRITE_VALUE_NOT_ALLOWED",
     "JAM_WRITE_SCHEMA_CHANGED",
+    // Assignment. A name is not an identity, and Jira decides who may hold an
+    // issue - so "nobody by that name", "several people by that name", "that
+    // person may not hold this issue" and "they already do" are four different
+    // things for a caller to do next, and none of them is "try again".
+    "JAM_WRITE_ASSIGNEE_NOT_FOUND",
+    "JAM_WRITE_ASSIGNEE_AMBIGUOUS",
+    "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE",
+    "JAM_WRITE_ASSIGNEE_ALREADY_SET",
+    // Custom fields. Three permissions have to line up and none implies another,
+    // so a refusal says which one is missing: the team never opted this field in,
+    // Jira will not let it be set on this issue, or JAM does not know the type
+    // well enough to write it. Each points somewhere different.
+    "JAM_WRITE_CUSTOM_FIELD_NOT_EDITABLE",
+    "JAM_WRITE_CUSTOM_FIELD_TYPE_UNSUPPORTED",
     "JAM_WRITE_PLAN_NOT_FOUND",
     "JAM_WRITE_PLAN_EXPIRED",
     "JAM_WRITE_CONFLICT",

package/dist/domain/write.d.ts

@@ -20,9 +20,9 @@
  * layer: these name an issue, creation names a project; these compare a
  * revision to detect a conflict, creation has no revision to compare.
  */
-export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition"];
+export declare const EXISTING_ISSUE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "custom-field.update"];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
-export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "issue.create"];
+export declare const WRITE_OPERATIONS: readonly ["comment.add", "field.update", "status.transition", "assignee.update", "custom-field.update", "issue.create"];
 export type ExistingIssueOperation = (typeof EXISTING_ISSUE_OPERATIONS)[number];
 export type WriteOperation = (typeof WRITE_OPERATIONS)[number];
 /**
@@ -48,6 +48,32 @@ export type FieldUpdateInput = {
 export type StatusTransitionInput = {
     status: string;
 };
+/**
+ * Who to assign an issue to, as a person would say it.
+ *
+ * A display name, or an accountId if the caller already has one. Either way it
+ * is a selector, not an identifier: nothing here is ever sent to Jira. It is
+ * resolved against Jira's own user directory first, and what gets written is
+ * the accountId that resolution produced.
+ */
+export type AssigneeUpdateInput = {
+    assignee: string;
+};
+/**
+ * A Jira user as JAM identifies them.
+ *
+ * `accountId` is the identity; `displayName` is for the human reading the
+ * receipt. They are not interchangeable - two people can share a display name,
+ * which is precisely why an assignment is verified on the accountId.
+ */
+export type AssigneeRef = {
+    accountId: string;
+    displayName: string;
+};
+/** A user Jira offered in answer to a search. */
+export type AssigneeCandidate = AssigneeRef & {
+    active: boolean;
+};
 /**
  * Fields `issue.create` may set.
  *
@@ -67,7 +93,7 @@ export type CreateIssueInput = {
     labels?: string[];
     components?: string[];
 };
-export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | CreateIssueInput;
+export type WriteInput = CommentAddInput | FieldUpdateInput | StatusTransitionInput | AssigneeUpdateInput | CustomFieldUpdateInput | CreateIssueInput;
 /** An issue type as Jira offers it for one project, right now. */
 export type CreateIssueType = {
     id: string;
@@ -117,6 +143,93 @@ export type CreateSchemaRequirements = {
         resolved: string;
     }[];
 };
+/**
+ * One field on an issue's edit screen, as Jira describes it.
+ *
+ * Normalized at the adapter: `operations` and `schema` come straight from
+ * Jira's own vocabulary because they are the vocabulary the decision is made
+ * in, but nothing else of the raw document travels.
+ */
+export type EditFieldMetadata = {
+    /** Jira's field id, e.g. `customfield_10021`. */
+    id: string;
+    name: string;
+    required: boolean;
+    /** What Jira says can be done to this field: `set`, `add`, `remove`, ... */
+    operations: string[];
+    schema: {
+        type: string;
+        /** Element type, for `type: "array"`. */
+        items?: string;
+        /** The custom field's implementation key, when it is a custom field. */
+        custom?: string;
+        customId?: number;
+    };
+    /** Present only where Jira constrains the value. Absent is not empty. */
+    allowedValues?: EditFieldOption[];
+};
+/**
+ * One option Jira offers for a constrained field.
+ *
+ * `id` is the identity and `label` is what a person reads - the same split as
+ * a user's accountId and display name, and for the same reason: an option can
+ * be renamed without becoming a different option, and two options could carry
+ * the same label.
+ */
+export type EditFieldOption = {
+    id: string;
+    label: string;
+};
+/**
+ * The custom field value families JAM can write.
+ *
+ * Narrow on purpose. Each of these has an unambiguous wire shape that JAM can
+ * produce from a plain caller value and compare after the fact. Everything
+ * else - dates needing a timezone policy, rich text needing ADF, user and
+ * group pickers needing identity resolution, app-owned fields with private
+ * semantics - is refused rather than guessed at.
+ */
+export declare const CUSTOM_FIELD_KINDS: readonly ["text", "number", "single-option", "multi-option"];
+export type CustomFieldKind = (typeof CUSTOM_FIELD_KINDS)[number];
+export type CustomFieldUpdateInput = {
+    /** A configured field id, or a configured writable field name. */
+    field: string;
+    value: string | number | string[];
+};
+/**
+ * What a custom-field plan depends on, recorded so apply can check it again.
+ *
+ * The issue's revision does not cover any of this: a field can be taken off a
+ * screen, lose its `set` operation, change type, or have an option renamed
+ * without the issue itself being touched. So these premises are frozen
+ * alongside `baseUpdated`, and re-derived before the write.
+ */
+export type CustomFieldRequirements = {
+    fieldId: string;
+    fieldName: string;
+    kind: CustomFieldKind;
+    schema: {
+        type: string;
+        items?: string;
+        custom?: string;
+    };
+    /** Options resolved from Jira's allowed list, for the option kinds. */
+    resolvedOptions?: EditFieldOption[];
+};
+/** A custom field value as a receipt shows it - reviewable, not a Jira payload. */
+export type CustomFieldValueView = {
+    id: string;
+    name: string;
+    value: string | number | null;
+} | {
+    id: string;
+    name: string;
+    value: EditFieldOption | null;
+} | {
+    id: string;
+    name: string;
+    value: EditFieldOption[];
+};
 /** A transition as Jira currently offers it for one issue. */
 export type JiraTransition = {
     id: string;
@@ -154,6 +267,19 @@ export type ExistingIssueWritePlan = WritePlanCommon & {
      * from a status name.
      */
     transition?: JiraTransition;
+    /**
+     * Who the issue was assigned to when the plan was made, by identity.
+     *
+     * Present only for `assignee.update`, and separate from `before` because
+     * `before` is what a receipt shows a human while this is what apply compares.
+     * `undefined` means the issue was unassigned.
+     */
+    baseAssigneeAccountId?: string;
+    /**
+     * What this plan assumed about a custom field's configuration. Present only
+     * for `custom-field.update`; apply re-derives each premise before writing.
+     */
+    customFieldRequirements?: CustomFieldRequirements;
 };
 /**
  * A plan to create an issue that does not exist yet.
@@ -185,6 +311,13 @@ export type WriteMutation = {
 } | {
     kind: "transition";
     transitionId: string;
+} | {
+    kind: "assignee";
+    accountId: string;
+} | {
+    kind: "custom-field";
+    fieldId: string;
+    value: unknown;
 } | {
     kind: "create";
     fields: Record<string, unknown>;

package/dist/domain/write.js

@@ -24,6 +24,8 @@ export const EXISTING_ISSUE_OPERATIONS = [
     "comment.add",
     "field.update",
     "status.transition",
+    "assignee.update",
+    "custom-field.update",
 ];
 /** The operations the public MCP surface accepts. Nothing else is reachable. */
 export const WRITE_OPERATIONS = [...EXISTING_ISSUE_OPERATIONS, "issue.create"];
@@ -54,6 +56,16 @@ export const CREATABLE_FIELDS = [
     "labels",
     "components",
 ];
+/**
+ * The custom field value families JAM can write.
+ *
+ * Narrow on purpose. Each of these has an unambiguous wire shape that JAM can
+ * produce from a plain caller value and compare after the fact. Everything
+ * else - dates needing a timezone policy, rich text needing ADF, user and
+ * group pickers needing identity resolution, app-owned fields with private
+ * semantics - is refused rather than guessed at.
+ */
+export const CUSTOM_FIELD_KINDS = ["text", "number", "single-option", "multi-option"];
 export function isWriteOperation(value) {
     return WRITE_OPERATIONS.includes(value);
 }

package/dist/mcp/tools/jira-write-apply.tool.js

@@ -1,20 +1,20 @@
 import { z } from "zod";
 import { applyWritePlan } from "../../application/apply-write.js";
 import { runTool } from "../tool-result.js";
-const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
-
-Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
-
-Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
-
-After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
-
-Failures worth handling differently:
-- JAM_WRITE_CONFLICT             the issue moved; re-plan
-- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
-- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
-- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
-
+const DESCRIPTION = `Apply a plan from jira_write_plan. This changes Jira.
+
+Takes a planId and nothing else. The change was decided when the plan was made, so there is no field, payload or override to pass here - that is deliberate, and it is what stops a write happening without the state check that planning did.
+
+Before writing, JAM re-reads the issue and compares it to what the plan saw. If it moved, you get JAM_WRITE_CONFLICT and no write happens: call jira_write_plan again against the new state rather than treating the conflict as a transient failure.
+
+After writing, JAM reads the issue back and checks the intended result is actually there. Only then does it return "applied". Jira accepting a request is not the same as the issue having changed.
+
+Failures worth handling differently:
+- JAM_WRITE_CONFLICT             the issue moved; re-plan
+- JAM_WRITE_PLAN_EXPIRED         the plan aged out; re-plan
+- JAM_WRITE_VERIFICATION_FAILED  Jira accepted it but the issue does not show it; read the issue and tell the user
+- JAM_WRITE_UNCERTAIN            JAM does not know whether it landed; read the issue. Do NOT call this tool again - the write may already have been applied, and applying it twice is a second comment or a second transition.
+
 Never report an uncertain or unverified write as done.`;
 export function registerJiraWriteApply(server, deps) {
     server.registerTool("jira_write_apply", {

package/dist/mcp/tools/jira-write-plan.tool.js

@@ -2,24 +2,30 @@ import { z } from "zod";
 import { planWrite } from "../../application/plan-write.js";
 import { CREATABLE_FIELDS, WRITABLE_FIELDS, WRITE_OPERATIONS } from "../../domain/write.js";
 import { runTool } from "../tool-result.js";
-const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
-
-This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
-
-Operations on an issue that already exists - these need \`key\`:
-- comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
-- field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
-- status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
-
-Creating an issue - no \`key\`, because there is no issue yet:
-- issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
-
-issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
-
-Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
-
-The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
-
+const DESCRIPTION = `Work out how to change one Jira issue, and get back a plan. Changes nothing.
+
+This is the first half of every write. Call it, read what it says the issue looks like now and what it would become, then pass the returned planId to jira_write_apply. There is no way to write to Jira without a plan, and a plan cannot be assembled by hand - only jira_write_plan issues one.
+
+Operations on an issue that already exists - these need \`key\`:
+- comment.add        input: { "text": "..." }        plain text; JAM converts it, do not send ADF
+- field.update       input: { "summary"?, "priority"?, "labels"?, "components"? }
+- status.transition  input: { "status": "Done" }     JAM asks Jira which transitions exist and matches yours
+- assignee.update    input: { "assignee": "..." }     a display name or an accountId; JAM resolves it against Jira's own directory
+- custom-field.update input: { "field": "...", "value": ... }  one custom field the project opted in
+
+Creating an issue - no \`key\`, because there is no issue yet:
+- issue.create       input: { "issueType": "Task", "summary": "...", "description"?, "priority"?, "labels"?, "components"? }
+
+issue.create goes into the project this workspace is bound to; the project is not a parameter. Planning reads Jira's create schema for that project first, so an issue type Jira does not offer, a priority or component outside its allowed values, and a project whose create screen requires a field JAM cannot set are all refused here rather than attempted. \`description\` is plain text, like a comment. Not settable in this version: assignee, reporter, parent, custom fields, attachments.
+
+assignee.update never sends the name you pass. JAM searches Jira's user directory, and assigns only when exactly one user matches your string exactly - an exact display name (case-insensitive) or an accountId. A partial match is Jira reporting a similarity, not identifying a person, so several matches or none come back as a refusal with the candidates attached: name one exactly, or pass their accountId. JAM also checks Jira offers that person as an assignee for this issue, before planning and again before writing, and confirms the result by accountId rather than by name. Unassigning, and setting an assignee while creating, are not in this version.
+
+custom-field.update changes one custom field, and only one a team has opted in: the field's exact id must carry "writable: true" in the project's .jira-agent/project.yaml. Being readable does not make a field writable. "field" is that id or its configured name, matched exactly - no partial matches. JAM then asks Jira's edit metadata whether the field is settable on this issue for this account, and what type it is. Supported types are single-line text (string), number, single-select (string naming an option) and multi-select (array of strings). Anything else - dates, rich text, user or group pickers, app-owned fields - is refused rather than attempted. Types are not converted: "5" is not 5. Options are matched exactly against what Jira offers and written by option id. Clearing a field is not supported, so an empty string or an empty array is refused.
+
+Writes are limited to the Jira project this workspace is bound to; a key from another project is refused rather than attempted.
+
+The plan records what the issue looked like when it was made, and expires. If the issue changes in the meantime, jira_write_apply refuses with JAM_WRITE_CONFLICT - re-plan against the new state rather than forcing the old one through.
+
 A plan is a statement about what is possible right now, not a promise that it will happen. Nothing is written until jira_write_apply runs.`;
 export function registerJiraWritePlan(server, deps) {
     server.registerTool("jira_write_plan", {
@@ -34,7 +40,7 @@ export function registerJiraWritePlan(server, deps) {
                 .string()
                 .min(1)
                 .optional()
-                .describe('Issue key, e.g. "PROJECT-123". Required for comment.add, field.update and status.transition; omit for issue.create, which has no issue yet. Must be in the configured project.'),
+                .describe('Issue key, e.g. "PROJECT-123". Required for every operation that changes an existing issue; omit for issue.create, which has no issue yet. Must be in the configured project.'),
             operation: z
                 .enum(WRITE_OPERATIONS)
                 .describe(`What to do: ${WRITE_OPERATIONS.join(", ")}.`),
@@ -52,6 +58,20 @@ export function registerJiraWritePlan(server, deps) {
                     .min(1)
                     .optional()
                     .describe("status.transition: the status to move to, e.g. \"Done\"."),
+                assignee: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("assignee.update: who to assign, as an exact display name or an accountId. Not settable through field.update."),
+                field: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe("custom-field.update: the custom field, as its Jira id (customfield_10016) or its configured name. Must be writable in this project's config."),
+                value: z
+                    .union([z.string(), z.number(), z.array(z.string())])
+                    .optional()
+                    .describe("custom-field.update: the value. A string for text, a number for numeric, a string naming an option for single-select, an array of strings for multi-select."),
                 issueType: z
                     .string()
                     .min(1)
@@ -69,7 +89,7 @@ export function registerJiraWritePlan(server, deps) {
                     .optional()
                     .describe("Component names. Replaces the whole component set."),
             })
-                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")}; issue.create accepts only ${CREATABLE_FIELDS.join(", ")}. Custom fields and assignee are not writable by either.`),
+                .describe(`Operation input. field.update accepts only ${WRITABLE_FIELDS.join(", ")}; issue.create accepts only ${CREATABLE_FIELDS.join(", ")}. Custom fields are not writable by either, and the assignee is changed through assignee.update rather than through field.update.`),
         },
         // Planning reads Jira and decides; it never mutates. Hosts are free to
         // run it without asking, which is what keeps the two-step shape cheap.

package/dist/policy/assignee-policy.d.ts

@@ -0,0 +1,60 @@
+import type { AssigneeCandidate, AssigneeRef } from "../domain/write.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export declare function resolveAssignee(requested: string, candidates: AssigneeCandidate[]): AssigneeRef;
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export declare function assertAssignable(issueKey: string, target: AssigneeRef, assignable: boolean): void;
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export declare function assertNotAlreadyAssigned(issueKey: string, current: string | undefined, target: AssigneeRef): void;
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export declare function exactMatches(requested: string, candidates: AssigneeCandidate[]): AssigneeCandidate[];

package/dist/policy/assignee-policy.js

@@ -0,0 +1,103 @@
+import { JamError } from "../domain/errors.js";
+/**
+ * Turning a name into a person, without ever guessing which person.
+ *
+ * Jira's user search is a substring search: "min" finds Min Kim and Minho
+ * Park, and it returns them in whatever order it likes. An agent handing JAM a
+ * name is describing an intent, not identifying an account - so the search is
+ * how candidates are found, and never how one of them is chosen.
+ *
+ * The rule is that JAM assigns only when the answer is unambiguous on its own
+ * terms: one exact identity. Everything else comes back as a refusal carrying
+ * the candidates, so the next move is to name one of them precisely rather
+ * than to hope the same query resolves differently.
+ *
+ * This costs an agent a round trip on ambiguity. The alternative costs someone
+ * an issue assigned to the wrong colleague, discovered later.
+ */
+/**
+ * Which candidate the caller meant, if exactly one is certain.
+ *
+ * In order:
+ *
+ *  1. An exact accountId. The caller already had an identity; nothing to guess.
+ *  2. Exactly one candidate whose display name matches exactly, ignoring case
+ *     and surrounding space. "task" and "Task" are the same intent, and an
+ *     agent cannot learn a directory's casing before asking.
+ *
+ * Nothing else resolves. A single substring hit is still a substring hit: it
+ * is Jira saying "this contains what you typed", not "this is who you meant".
+ */
+export function resolveAssignee(requested, candidates) {
+    const wanted = requested.trim();
+    if (wanted.length === 0) {
+        throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "assignee.update needs a non-empty `input.assignee`.", { operation: "assignee.update" });
+    }
+    const exact = exactMatches(wanted, candidates);
+    if (exact.length === 0) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_FOUND", candidates.length === 0
+            ? `Jira has no user matching "${requested}".`
+            : `No Jira user is exactly "${requested}". JAM assigns only on an exact display name or an accountId, because a partial match is Jira reporting a similarity rather than identifying a person. Name one of the candidates exactly, or pass their accountId.`, { requested, candidates: describe(candidates) });
+    }
+    if (exact.length > 1) {
+        // Two people really can share a display name. Picking either would be a
+        // coin toss whose result is somebody's issue.
+        throw new JamError("JAM_WRITE_ASSIGNEE_AMBIGUOUS", `"${requested}" matches ${exact.length} Jira users exactly. Pass the accountId of the one you mean.`, { requested, candidates: describe(exact) });
+    }
+    const match = exact[0];
+    if (!match.active) {
+        throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `${match.displayName} is a deactivated Jira account, so this issue cannot be assigned to them.`, { requested, accountId: match.accountId, reason: "INACTIVE" });
+    }
+    return { accountId: match.accountId, displayName: match.displayName };
+}
+/**
+ * Refuse an assignment Jira would not permit, before asking it to.
+ *
+ * Assignability is a permission question with a per-project answer, and JAM
+ * does not model Jira's permission scheme - it asks. Called at plan time so a
+ * refusal is a JAM decision rather than a 400, and again immediately before
+ * the write, because a permission that held when the plan was made is not the
+ * same as one that still holds.
+ */
+export function assertAssignable(issueKey, target, assignable) {
+    if (assignable)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", `Jira does not offer ${target.displayName} as an assignee for ${issueKey}. They may lack the assignable-user permission in this project, or have lost it since this plan was made.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * Refuse an assignment that would change nothing.
+ *
+ * Not an error in Jira's eyes, and not harmful - but a write JAM reports as
+ * applied should be a write that happened. Saying so plainly is more useful
+ * than a receipt claiming to have changed something that already was.
+ */
+export function assertNotAlreadyAssigned(issueKey, current, target) {
+    if (current !== target.accountId)
+        return;
+    throw new JamError("JAM_WRITE_ASSIGNEE_ALREADY_SET", `${issueKey} is already assigned to ${target.displayName}. Nothing to change.`, { issueKey, accountId: target.accountId, displayName: target.displayName });
+}
+/**
+ * The candidates this string identifies exactly, if any.
+ *
+ * Exported so the caller can tell "the search settled it" from "the search did
+ * not" without reimplementing the rule - a second copy of what counts as exact
+ * is a second answer waiting to disagree with this one.
+ *
+ * An accountId match wins outright: it is an identity, and a display name that
+ * happens to equal somebody's account id is not a reason to consider them.
+ */
+export function exactMatches(requested, candidates) {
+    const wanted = requested.trim();
+    const byAccountId = candidates.filter((c) => c.accountId === wanted);
+    if (byAccountId.length > 0)
+        return byAccountId;
+    return candidates.filter((c) => c.displayName.trim().toLowerCase() === wanted.toLowerCase());
+}
+/** Candidates as an agent can act on them: a name to repeat, and an id to be sure. */
+function describe(candidates) {
+    return candidates.map((c) => ({
+        accountId: c.accountId,
+        displayName: c.displayName,
+        active: c.active,
+    }));
+}

package/dist/policy/custom-field-policy.d.ts

@@ -0,0 +1,93 @@
+import type { ProjectConfig } from "../config/schema.js";
+import type { CustomFieldKind, CustomFieldRequirements, CustomFieldUpdateInput, CustomFieldValueView, EditFieldMetadata, EditFieldOption } from "../domain/write.js";
+/**
+ * What JAM will write to a custom field, and everything that has to be true
+ * first.
+ *
+ * Three separate permissions have to line up, and none of them implies
+ * another:
+ *
+ *  1. **The team said so.** The field's exact id is in the project's whitelist
+ *     with `writable: true`. Being readable is not being writable - reading a
+ *     field and letting an agent change it are different decisions, and a
+ *     config written before JAM could write must not start granting writes
+ *     because JAM learned how.
+ *  2. **Jira allows it here and now.** The field is on this issue's edit
+ *     screen for this account, and Jira lists `set` among its operations.
+ *     Asked, never modelled: applicability depends on project, issue type,
+ *     field contexts, screens and permissions, and JAM does not carry a copy
+ *     of any of that.
+ *  3. **JAM knows the shape.** The field's type is one of four families whose
+ *     wire form JAM can produce from a plain value and compare afterwards.
+ *     Anything else is refused rather than posted to find out.
+ */
+type WritableField = {
+    id: string;
+    name: string;
+};
+/**
+ * Which configured field this selector names.
+ *
+ * The id is the identity; the name is an alias for people. Resolution is exact
+ * on either - no substring, no fuzz - because the alternative is an agent's
+ * approximate word choosing which field on somebody's board gets rewritten.
+ *
+ * Only `writable: true` entries are candidates, including for the refusal
+ * message: naming a read-only field as an alternative would suggest it is one
+ * selector away from being written.
+ */
+export declare function resolveWritableField(config: ProjectConfig, requested: string): WritableField;
+/**
+ * The field as Jira currently offers it on this issue, or a refusal.
+ *
+ * Absent from the edit metadata and present-but-not-settable are different
+ * situations with the same answer for the caller, so they share a code and
+ * differ in the detail: one means the field is not on this screen, the other
+ * that Jira will not let this account set it.
+ */
+export declare function assertEditable(issueKey: string, field: WritableField, metadata: EditFieldMetadata[]): EditFieldMetadata;
+/**
+ * Which of the four families this field belongs to, if any.
+ *
+ * Classified from Jira's own `schema`, which is the vocabulary Jira answers
+ * in. The implementation key (`schema.custom`) deliberately does not decide
+ * it: there are hundreds of them, they are app-specific, and a field's wire
+ * shape follows its type rather than its plugin.
+ *
+ * Anything unclassified is refused. Posting an unknown type to see what
+ * happens would use a Jira 400 as schema discovery, and on the occasions it
+ * did not 400 it would write something nobody described.
+ */
+export declare function classifyKind(field: EditFieldMetadata): CustomFieldKind;
+/**
+ * The value, checked against the family and turned into what Jira expects.
+ *
+ * Types are never coerced. `"5"` is not `5`: a caller that meant a number can
+ * say so, and silently converting would make JAM's idea of the value differ
+ * from the caller's in exactly the cases where it matters.
+ *
+ * Nothing here clears a field. Empty strings, empty arrays and null are
+ * refused rather than treated as "unset" - removing a value is a different
+ * intent from setting one, and it is not in this version.
+ */
+export declare function resolveCustomFieldValue(field: EditFieldMetadata, kind: CustomFieldKind, input: CustomFieldUpdateInput): {
+    jiraValue: unknown;
+    view: CustomFieldValueView;
+    resolvedOptions?: EditFieldOption[];
+};
+/**
+ * Do this plan's premises still hold?
+ *
+ * Semantic, like the create schema check and for the same reason: comparing
+ * whole metadata documents would invalidate every outstanding plan whenever an
+ * unrelated field appeared on the screen. What is compared is what the plan
+ * actually rested on - the field is still settable, still the same family,
+ * still the same schema, and every option it chose is still offered under the
+ * same label.
+ *
+ * A renamed option is treated as a changed one. The id is the identity, but a
+ * label is what the plan showed a human before they agreed to it, and "Backend"
+ * becoming "Platform" is a different statement about the issue.
+ */
+export declare function assertCustomFieldUnchanged(issueKey: string, requirements: CustomFieldRequirements, metadata: EditFieldMetadata[]): void;
+export {};