@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/providers/contract/adapters/github/governed-write.mjs

@@ -0,0 +1,121 @@
+/**
+ * lib/providers/contract/adapters/github/governed-write.mjs — envelope-shaped
+ * GitHub write adapter.
+ *
+ * Wraps the CLI-backed github adapter (./index.mjs) in the provider shape
+ * lib/writes/envelope.mjs expects: write(config, payload), meta.id, search().
+ * Adds two behaviors the raw CLI adapter cannot provide on its own:
+ *
+ *   - Cross-run duplicate detection: every created issue carries a hidden
+ *     idempotency marker (HTML comment) in its body. Before creating, this
+ *     wrapper searches GitHub itself for an issue carrying that marker, so
+ *     dedup survives across process restarts and machines, not just the
+ *     local sent-log.
+ *   - Secondary-rate-limit backoff: GitHub content-creation endpoints return
+ *     403 with a "secondary rate limit" message (no clean HTTP Retry-After
+ *     on the gh CLI transport). This wrapper retries a bounded number of
+ *     times honoring the parsed retry-after, then surfaces the error rather
+ *     than spinning silently — the envelope's own generic retry/backoff is
+ *     bypassed here because it is not retry-after aware.
+ *
+ * Only `type: 'issue'` writes get marker + dedup treatment; other write
+ * types pass straight through to the underlying adapter.
+ */
+
+import { RateLimitError } from '../../errors.mjs';
+
+const MARKER_PREFIX = 'construct:idempotency:';
+
+function markerFor(key) {
+  return `<!-- ${MARKER_PREFIX}${key} -->`;
+}
+
+function extractMarkerKey(text) {
+  const match = new RegExp(`${MARKER_PREFIX}([a-zA-Z0-9_-]+)`).exec(text || '');
+  return match ? match[1] : null;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.ghAdapter - underlying CLI adapter (default export of ./index.mjs)
+ * @param {number} [opts.maxRateLimitRetries] - bounded retry-after retries before surfacing (default 2)
+ * @param {function} [opts.sleepFn] - injectable sleep for tests
+ */
+export function createGovernedGithubProvider({ ghAdapter, maxRateLimitRetries = 2, sleepFn = sleep } = {}) {
+  if (!ghAdapter) throw new Error('createGovernedGithubProvider: ghAdapter is required');
+
+  async function findExistingByMarker(config, { title, markerKey }) {
+    const results = await ghAdapter.search(`${title} in:title`, { scope: 'issues' });
+    for (const candidate of results || []) {
+      const body = candidate.body ?? candidate.textMatches?.map((m) => m.fragment).join(' ') ?? '';
+      const haystack = `${candidate.title ?? ''} ${body}`;
+      if (extractMarkerKey(haystack) === markerKey || candidate.title === title) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+
+  async function writeIssueWithRetry(config, payload, markerKey) {
+    const bodyWithMarker = `${payload.body ?? ''}\n\n${markerFor(markerKey)}`;
+    let attempt = 0;
+    for (;;) {
+      try {
+        return await ghAdapter.write({
+          type: 'issue',
+          title: payload.title,
+          body: bodyWithMarker,
+          labels: payload.labels,
+        });
+      } catch (err) {
+        const isSecondaryRateLimit = err instanceof RateLimitError || err.status === 403;
+        if (!isSecondaryRateLimit || attempt >= maxRateLimitRetries) {
+          throw err;
+        }
+        attempt += 1;
+        const retryAfterMs = (err.retryAfter ?? 60) * 1000;
+        await sleepFn(retryAfterMs);
+      }
+    }
+  }
+
+  return {
+    meta: {
+      id: 'github',
+      displayName: 'GitHub (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed GitHub writes with marker-based dedup and retry-after backoff.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type !== 'issue') {
+        return ghAdapter.write(payload);
+      }
+      if (!payload.title) throw new Error('github governed write: payload.title is required for type "issue"');
+
+      const markerKey = payload.idempotencyKey || payload.title;
+      const existing = await findExistingByMarker(config, { title: payload.title, markerKey });
+      if (existing) {
+        return {
+          type: 'issue-duplicate',
+          id: existing.number ?? existing.id,
+          number: existing.number,
+          url: existing.url,
+          linkback: existing.url,
+        };
+      }
+
+      return writeIssueWithRetry(config, payload, markerKey);
+    },
+
+    async search(config, query) {
+      return ghAdapter.search(query, { scope: 'issues' });
+    },
+  };
+}
+
+export default createGovernedGithubProvider;

package/lib/providers/contract/adapters/github/index.mjs

@@ -27,7 +27,26 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { AuthError, NotFoundError } from '../../errors.mjs';
+import { AuthError, NotFoundError, RateLimitError } from '../../errors.mjs';
+
+// gh CLI has no HTTP header access; secondary rate limits surface as a 403
+// with "secondary rate limit" text in stderr and sometimes a suggested wait
+// in seconds. Default to GitHub's documented minimum backoff when absent.
+const SECONDARY_RATE_LIMIT_DEFAULT_RETRY_AFTER = 60;
+
+function parseRetryAfterSeconds(stderr) {
+  const match = /retry.{0,10}?(\d+)\s*second/i.exec(stderr || '');
+  return match ? parseInt(match[1], 10) : SECONDARY_RATE_LIMIT_DEFAULT_RETRY_AFTER;
+}
+
+function throwIfRateLimited(stderr) {
+  if (/secondary rate limit|403/i.test(stderr || '') && /rate limit/i.test(stderr || '')) {
+    throw new RateLimitError(stderr.trim(), {
+      provider: 'github',
+      retryAfter: parseRetryAfterSeconds(stderr),
+    });
+  }
+}
 
 function gh(args, { json = true, input } = {}) {
   const fullArgs = json ? [...args, '--json', ...ghJsonFields(args)] : args;
@@ -115,6 +134,10 @@ export default {
       const args = ['issue', 'create', ...repoFlag, '--title', item.title, '--body', item.body ?? ''];
       if (item.labels?.length) args.push('--label', item.labels.join(','));
       const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh issue create failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'issue-created', url: out.stdout.trim() };
     }
 
@@ -127,21 +150,33 @@ export default {
       ];
       if (item.draft) args.push('--draft');
       const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh pr create failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'pr-created', url: out.stdout.trim() };
     }
 
     if (item.type === 'comment') {
       const args = ['issue', 'comment', String(item.issue_number), ...repoFlag, '--body', item.body];
-      spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      const out = spawnSync('gh', args, { encoding: 'utf8', env: process.env });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh issue comment failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'comment-created', issue_number: item.issue_number };
     }
 
     if (item.type === 'pr-merge') {
       const method = item.merge_method ?? 'squash';
-      spawnSync('gh', ['pr', 'merge', String(item.number), ...repoFlag, `--${method}`], {
+      const out = spawnSync('gh', ['pr', 'merge', String(item.number), ...repoFlag, `--${method}`], {
         encoding: 'utf8',
         env: process.env,
       });
+      if (out.status !== 0) {
+        throwIfRateLimited(out.stderr);
+        throw new Error(`gh pr merge failed: ${out.stderr?.trim() || `exit ${out.status}`}`);
+      }
       return { type: 'pr-merged', number: item.number };
     }
 

package/lib/providers/contract/adapters/jira/adf.mjs

@@ -0,0 +1,151 @@
+/**
+ * lib/providers/contract/adapters/jira/adf.mjs — Atlassian Document Format
+ * (ADF) construction for Jira Cloud write fields.
+ *
+ * Jira Cloud REST API v3 requires `description`, `comment.body`, and any
+ * multiline custom field of type `doc` to be submitted as an ADF document
+ * rather than plain text. Covers the minimal ADF subset issue/comment write
+ * ops need: paragraphs split on blank lines, single-level bullet lists for
+ * lines starting with "- " or "* ", and inline text nodes. Full markdown
+ * fidelity (headings, tables, nested lists) is out of scope.
+ *
+ * `renderAdfPreview(adf)` renders an ADF document back to a readable plain
+ * string for dry-run display, so a human reviewing a dry-run payload sees
+ * text rather than a raw ADF tree.
+ */
+
+const ADF_VERSION = 1;
+
+function textNode(text) {
+  return { type: 'text', text: String(text) };
+}
+
+function paragraphNode(text) {
+  return { type: 'paragraph', content: text ? [textNode(text)] : [] };
+}
+
+function bulletListNode(items) {
+  return {
+    type: 'bulletList',
+    content: items.map((item) => ({
+      type: 'listItem',
+      content: [paragraphNode(item)],
+    })),
+  };
+}
+
+// Blank-line-separated blocks become paragraphs; a contiguous run of lines
+// each starting with "- " or "* " becomes a single bullet list. This covers
+// the shapes specialists actually produce (short prose + a checklist) without
+// pretending to be a markdown parser.
+
+function blocksFromText(text) {
+  const lines = String(text ?? '').split('\n');
+  const blocks = [];
+  let paragraphLines = [];
+  let listItems = [];
+
+  function flushParagraph() {
+    if (paragraphLines.length) {
+      blocks.push(paragraphNode(paragraphLines.join(' ').trim()));
+      paragraphLines = [];
+    }
+  }
+  function flushList() {
+    if (listItems.length) {
+      blocks.push(bulletListNode(listItems));
+      listItems = [];
+    }
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    const bulletMatch = /^[-*]\s+(.*)$/.exec(line);
+    if (bulletMatch) {
+      flushParagraph();
+      listItems.push(bulletMatch[1]);
+    } else if (line === '') {
+      flushParagraph();
+      flushList();
+    } else {
+      flushList();
+      paragraphLines.push(line);
+    }
+  }
+  flushParagraph();
+  flushList();
+
+  return blocks.length ? blocks : [paragraphNode('')];
+}
+
+/**
+ * Build a full ADF document from a plain-text (or already-ADF) input.
+ * Passing an object that already looks like an ADF doc (`{ type: 'doc' }`)
+ * returns it unchanged so callers can pass through pre-built documents.
+ *
+ * @param {string|object} content
+ * @returns {object} ADF document
+ */
+export function buildAdfDocument(content) {
+  if (content && typeof content === 'object' && content.type === 'doc') {
+    return content;
+  }
+  return {
+    type: 'doc',
+    version: ADF_VERSION,
+    content: blocksFromText(content),
+  };
+}
+
+/**
+ * Render an ADF document (or plain text) back to a flat human-readable
+ * string, for dry-run display. Not a full ADF renderer — only understands
+ * the node types buildAdfDocument produces plus a defensive fallback for
+ * unknown node types (renders as `[<type>]`).
+ *
+ * @param {object|string} adf
+ * @returns {string}
+ */
+export function renderAdfPreview(adf) {
+  if (typeof adf === 'string') return adf;
+  if (!adf || typeof adf !== 'object') return '';
+
+  function renderNode(node) {
+    if (!node || typeof node !== 'object') return '';
+    switch (node.type) {
+      case 'doc':
+        return (node.content ?? []).map(renderNode).join('\n');
+      case 'paragraph':
+        return (node.content ?? []).map(renderNode).join('');
+      case 'text':
+        return node.text ?? '';
+      case 'bulletList':
+        return (node.content ?? []).map((item) => `- ${renderNode(item)}`).join('\n');
+      case 'listItem':
+        return (node.content ?? []).map(renderNode).join('').trim();
+      default:
+        return `[${node.type ?? 'unknown'}]`;
+    }
+  }
+
+  return renderNode(adf);
+}
+
+/**
+ * True when the given value is a well-formed ADF document envelope
+ * (`{ type: 'doc', version, content: [...] }`). Distinguishes a doc node
+ * from a bare string, for rejecting fields the API requires as ADF but
+ * were submitted as plain text.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isAdfDocument(value) {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    value.type === 'doc' &&
+    typeof value.version === 'number' &&
+    Array.isArray(value.content)
+  );
+}

package/lib/providers/contract/adapters/jira/createmeta.mjs

@@ -0,0 +1,143 @@
+/**
+ * lib/providers/contract/adapters/jira/createmeta.mjs — Jira Cloud createmeta
+ * validation for write payloads.
+ *
+ * Jira Cloud's `GET /rest/api/3/issue/createmeta` (expanded with
+ * `projects.issuetypes.fields`) reports, per project + issue type, which
+ * fields exist, which are required, and which accept a `doc` (ADF) shape
+ * versus a plain scalar. `validateAgainstCreatemeta` runs before any issue
+ * create/comment submit so a bad project key, unknown issue type, missing
+ * required field, or wrong ADF/plain-text shape surfaces as a client-side
+ * error with an actionable message instead of a raw 400 from Jira after the
+ * request has already gone out.
+ *
+ * Providers inject a `fetchCreatemeta(projectKey, issueTypeName)` function
+ * so this module has no transport dependency and the fake-jira test double
+ * can simulate arbitrary createmeta shapes and failure modes.
+ */
+
+import { isAdfDocument } from './adf.mjs';
+
+/**
+ * Normalize a raw createmeta API response into a lookup map of
+ * `{ [fieldKey]: { required, schema } }` for the requested issue type.
+ *
+ * @param {object} raw - createmeta response body
+ * @param {string} projectKey
+ * @param {string} issueTypeName
+ * @returns {{ issueTypeId: string|null, fields: Record<string, {required: boolean, schema: object}> } | null}
+ */
+export function extractIssueTypeMeta(raw, projectKey, issueTypeName) {
+  const project = (raw?.projects ?? []).find((p) => p.key === projectKey);
+  if (!project) return null;
+
+  const issueType = (project.issuetypes ?? []).find(
+    (it) => it.name?.toLowerCase() === issueTypeName?.toLowerCase(),
+  );
+  if (!issueType) return null;
+
+  const fields = {};
+  for (const [key, def] of Object.entries(issueType.fields ?? {})) {
+    fields[key] = { required: !!def.required, schema: def.schema ?? {} };
+  }
+  return { issueTypeId: issueType.id ?? null, fields };
+}
+
+/**
+ * Validate an issue-create payload against createmeta for its project +
+ * issue type before submit. Returns a structured result rather than
+ * throwing, so callers can map failures to actionable messages themselves.
+ *
+ * @param {object} opts
+ * @param {function(string, string): Promise<object>} opts.fetchCreatemeta
+ * @param {string} opts.projectKey
+ * @param {string} opts.issueTypeName
+ * @param {object} opts.fieldValues - candidate field values keyed by createmeta field key
+ *   (e.g. { summary, description, labels }). `description` is checked for
+ *   ADF shape when createmeta reports its schema type as `doc`.
+ * @returns {Promise<{ ok: true } | { ok: false, reason: string, errors: string[] }>}
+ */
+export async function validateAgainstCreatemeta({ fetchCreatemeta, projectKey, issueTypeName, fieldValues }) {
+  let raw;
+  try {
+    raw = await fetchCreatemeta(projectKey, issueTypeName);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'createmeta-fetch-failed',
+      errors: [mapCreatemetaTransportError(err, { projectKey })],
+    };
+  }
+
+  const meta = extractIssueTypeMeta(raw, projectKey, issueTypeName);
+  if (!meta) {
+    const knownProjects = (raw?.projects ?? []).map((p) => p.key);
+    if (!knownProjects.includes(projectKey)) {
+      return {
+        ok: false,
+        reason: 'unknown-project',
+        errors: [
+          `Project "${projectKey}" was not found or you lack the Browse Projects / Create Issues permission for it.` +
+          (knownProjects.length ? ` Accessible projects: ${knownProjects.join(', ')}.` : ''),
+        ],
+      };
+    }
+    return {
+      ok: false,
+      reason: 'unknown-issue-type',
+      errors: [`Issue type "${issueTypeName}" is not available in project "${projectKey}".`],
+    };
+  }
+
+  const errors = [];
+
+  for (const [fieldKey, def] of Object.entries(meta.fields)) {
+    if (!def.required) continue;
+    const present = fieldValues[fieldKey] !== undefined && fieldValues[fieldKey] !== null && fieldValues[fieldKey] !== '';
+    if (!present) {
+      errors.push(`Field "${fieldKey}" is required by project "${projectKey}" / issue type "${issueTypeName}" but was not provided.`);
+    }
+  }
+
+  for (const [fieldKey, value] of Object.entries(fieldValues)) {
+    const def = meta.fields[fieldKey];
+    if (!def) continue;
+    if (def.schema?.type === 'doc' && value !== undefined && value !== null && !isAdfDocument(value)) {
+      errors.push(`Field "${fieldKey}" requires an Atlassian Document Format (ADF) body, but a plain value was submitted.`);
+    }
+  }
+
+  if (errors.length) {
+    return { ok: false, reason: 'field-validation-failed', errors };
+  }
+
+  return { ok: true, issueTypeId: meta.issueTypeId };
+}
+
+/**
+ * Map a createmeta transport failure (401/403/404/5xx) to an actionable
+ * message. Jira Cloud returns 404 for both "project does not exist" and
+ * "no permission to view project" — the same ambiguity the create-issue
+ * endpoint itself has — so the message names both possibilities rather
+ * than asserting one.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ projectKey: string }} ctx
+ * @returns {string}
+ */
+export function mapCreatemetaTransportError(err, { projectKey }) {
+  const status = err?.status;
+  if (status === 401) {
+    return 'Jira authentication failed while fetching createmeta. Check JIRA_EMAIL / JIRA_TOKEN.';
+  }
+  if (status === 403) {
+    return `Forbidden: the authenticated account lacks permission to create issues in project "${projectKey}".`;
+  }
+  if (status === 404) {
+    return `Project "${projectKey}" was not found, or the authenticated account cannot browse it.`;
+  }
+  if (status && status >= 500) {
+    return `Jira createmeta endpoint returned a server error (${status}); retry later.`;
+  }
+  return `Failed to fetch createmeta for project "${projectKey}": ${err?.message ?? String(err)}`;
+}

package/lib/providers/contract/adapters/jira/governed-write.mjs

@@ -0,0 +1,182 @@
+/**
+ * lib/providers/contract/adapters/jira/governed-write.mjs — envelope-shaped
+ * Jira write adapter.
+ *
+ * Wraps a Jira REST transport in the provider shape lib/writes/envelope.mjs
+ * expects: write(config, payload), meta.id, search(). This is the only
+ * exposed entry point for Jira writes — specialists and CLI callers route
+ * through writeWithEnvelope(), never through a raw Jira client, so dedup,
+ * retry, dry-run, approval, and audit stay centralized in the envelope
+ * (LMCP-J2) rather than being reimplemented per-adapter.
+ *
+ * Adds the two behaviors createmeta + ADF require that a generic envelope
+ * cannot provide:
+ *
+ *   - createmeta validation before submit: fetches
+ *     `issue/createmeta?projectKeys=X&issuetypeNames=Y` (via the injected
+ *     `jiraTransport`) and checks required fields and ADF-vs-plain field
+ *     shape before making the create/comment call, so a bad project key,
+ *     unknown issue type, missing required field, or wrong field shape
+ *     surfaces as an actionable client-side error rather than a raw Jira
+ *     400.
+ *   - ADF body construction: `description` (issue create) and `body`
+ *     (comment) are converted from plain text to Atlassian Document Format
+ *     via lib/providers/contract/adapters/jira/adf.mjs before submit.
+ *
+ * Only `type: 'issue'` and `type: 'comment'` writes get createmeta + ADF
+ * treatment; other write types are rejected — this adapter does not
+ * support transitions or field updates (non-goal per LMCP-J3).
+ */
+
+import { AuthError } from '../../errors.mjs';
+import { buildAdfDocument, renderAdfPreview } from './adf.mjs';
+import { validateAgainstCreatemeta } from './createmeta.mjs';
+
+/**
+ * @param {object} opts
+ * @param {object} opts.jiraTransport - underlying Jira REST transport; must implement
+ *   `fetchCreatemeta(projectKey, issueTypeName)`, `createIssue(fields)`,
+ *   `createComment(issueKey, adfBody)`, and `searchIssues(jql)`.
+ */
+export function createGovernedJiraProvider({ jiraTransport } = {}) {
+  if (!jiraTransport) throw new Error('createGovernedJiraProvider: jiraTransport is required');
+
+  async function writeIssue(payload) {
+    const { project, issueType = 'Task', summary, description, labels, assignee } = payload;
+    if (!project) throw new Error('jira governed write: payload.project is required for type "issue"');
+    if (!summary) throw new Error('jira governed write: payload.summary is required for type "issue"');
+
+    const descriptionAdf = description !== undefined ? buildAdfDocument(description) : undefined;
+
+    const validation = await validateAgainstCreatemeta({
+      fetchCreatemeta: jiraTransport.fetchCreatemeta.bind(jiraTransport),
+      projectKey: project,
+      issueTypeName: issueType,
+      fieldValues: {
+        summary,
+        description: descriptionAdf,
+        labels,
+        assignee,
+      },
+    });
+
+    if (!validation.ok) {
+      const err = new Error(validation.errors.join(' '));
+      err.code = validation.reason;
+      err.jiraValidation = validation;
+      throw err;
+    }
+
+    try {
+      const result = await jiraTransport.createIssue({
+        project,
+        issueType,
+        summary,
+        description: descriptionAdf,
+        labels,
+        assignee,
+      });
+      return { type: 'issue-created', id: result.id, key: result.key, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { project });
+    }
+  }
+
+  async function writeComment(payload) {
+    const { issueKey, body } = payload;
+    if (!issueKey) throw new Error('jira governed write: payload.issueKey is required for type "comment"');
+    if (!body) throw new Error('jira governed write: payload.body is required for type "comment"');
+
+    const bodyAdf = buildAdfDocument(body);
+
+    try {
+      const result = await jiraTransport.createComment(issueKey, bodyAdf);
+      return { type: 'comment-created', id: result.id, issueKey, url: result.url };
+    } catch (err) {
+      throw mapWriteTransportError(err, { issueKey });
+    }
+  }
+
+  return {
+    meta: {
+      id: 'jira',
+      displayName: 'Jira (governed)',
+      capabilities: ['write', 'search'],
+      description: 'Envelope-routed Jira writes with createmeta pre-validation and ADF body construction.',
+    },
+
+    async write(config, payload) {
+      if (payload?.type === 'issue') return writeIssue(payload);
+      if (payload?.type === 'comment') return writeComment(payload);
+      throw new Error(`jira governed write: unsupported type "${payload?.type}" (only 'issue' and 'comment' are supported)`);
+    },
+
+    async search(config, query) {
+      return jiraTransport.searchIssues(query);
+    },
+
+    /**
+     * Render the ADF-shaped payload the envelope would submit, without
+     * calling createmeta or the transport. Feeds the envelope's dry-run
+     * path (lib/writes/envelope.mjs `dryRun: true`), giving a human
+     * reviewing a pending write both the raw ADF tree and a flattened
+     * preview string, not just the plain-text input.
+     *
+     * @param {object} payload
+     * @returns {{ type: string, fields: object, adfPreview: Record<string,string> }}
+     */
+    renderDryRun(payload) {
+      if (payload?.type === 'issue') {
+        const descriptionAdf = payload.description !== undefined ? buildAdfDocument(payload.description) : undefined;
+        return {
+          type: 'issue',
+          fields: {
+            project: { key: payload.project },
+            issuetype: { name: payload.issueType ?? 'Task' },
+            summary: payload.summary,
+            ...(descriptionAdf ? { description: descriptionAdf } : {}),
+            ...(payload.labels ? { labels: payload.labels } : {}),
+            ...(payload.assignee ? { assignee: payload.assignee } : {}),
+          },
+          adfPreview: descriptionAdf ? { description: renderAdfPreview(descriptionAdf) } : {},
+        };
+      }
+      if (payload?.type === 'comment') {
+        const bodyAdf = buildAdfDocument(payload.body);
+        return {
+          type: 'comment',
+          fields: { issueKey: payload.issueKey, body: bodyAdf },
+          adfPreview: { body: renderAdfPreview(bodyAdf) },
+        };
+      }
+      throw new Error(`jira governed write: cannot render dry-run for unsupported type "${payload?.type}"`);
+    },
+  };
+}
+
+/**
+ * Map a create/comment transport failure (401/403/404) to an actionable
+ * message. Distinct from mapCreatemetaTransportError since it covers the
+ * write call itself, not the pre-flight createmeta fetch.
+ *
+ * @param {Error & {status?: number}} err
+ * @param {{ project?: string, issueKey?: string }} ctx
+ * @returns {Error}
+ */
+function mapWriteTransportError(err, ctx) {
+  const status = err?.status;
+  if (status === 401) {
+    return new AuthError('Jira authentication failed. Check JIRA_EMAIL / JIRA_TOKEN.', { provider: 'jira' });
+  }
+  if (status === 403) {
+    const target = ctx.project ? `project "${ctx.project}"` : `issue "${ctx.issueKey}"`;
+    return new Error(`Forbidden: the authenticated account lacks permission to write to ${target}.`);
+  }
+  if (status === 404) {
+    const target = ctx.project ? `Project "${ctx.project}"` : `Issue "${ctx.issueKey}"`;
+    return new Error(`${target} was not found, or the authenticated account cannot access it.`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+export default createGovernedJiraProvider;

package/lib/providers/contract/adapters/jira/manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "jira-write",
+  "version": "1.0.0",
+  "kind": "data-source",
+  "capabilities": ["write", "search"],
+  "secretEnvKeys": ["JIRA_URL", "JIRA_EMAIL", "JIRA_TOKEN"],
+  "operations": ["write:issue", "write:comment", "search"],
+  "securityClassification": "trusted",
+  "owner": "construct-core",
+  "compatVersion": 1,
+  "installSource": "builtin",
+  "exposure": "envelope-only",
+  "envelopeModule": "lib/writes/envelope.mjs",
+  "adapterModule": "lib/providers/contract/adapters/jira/governed-write.mjs",
+  "transportModule": "lib/providers/contract/adapters/jira/transport.mjs",
+  "notes": "Colocated write-capability manifest for LMCP-J3. Follows the lib/extensions/manifests/*.manifest.json schema (see atlassian-jira.manifest.json, which declares read/search only). Wiring this into the shared lib/extensions/manifests/ discovery directory is out of scope for this bead; capabilities here are reachable only via writeWithEnvelope(), never a direct provider-registry lookup."
+}