diff --git a/handlers/work_item_update.ts b/handlers/work_item_update.ts
new file mode 100644
index 0000000..5a12566
--- /dev/null
+++ b/handlers/work_item_update.ts
@@ -0,0 +1,87 @@
+// work_item_update — adapter-dispatching shell (#287).
+// Sister to handlers/work_item.ts: that one creates issues/PRs; this one
+// updates an existing issue's title, body, labels, assignees, milestone, or a
+// single H2 section of the body. Subprocess and platform branching live in
+// lib/adapters/work-item-update-{github,gitlab}.ts; this handler is purely the
+// schema validation + envelope shaping.
+//
+// Section-level patches: when patch.body_section is provided, the adapter
+// reads the current issue body, splices the section, and sends the resulting
+// full body to the platform CLI's edit/update sub-command. This preserves all
+// other sections verbatim — the AC contract for #287.
+
+import { z } from 'zod';
+import type { HandlerDef } from '../types.js';
+import { getAdapter } from '../lib/adapters/index.js';
+
+const issueRefSchema = z
+  .string()
+  .regex(/^(?:[A-Za-z0-9._/-]+#)?\d+$|^#\d+$/, 'issue_ref must match `#N` or `owner/repo#N`');
+
+const patchSchema = z
+  .object({
+    title: z.string().min(1).optional(),
+    body: z.string().optional(),
+    body_section: z
+      .object({
+        heading: z.string().min(1, 'body_section.heading must be non-empty'),
+        content: z.string(),
+      })
+      .optional(),
+    labels: z.array(z.string()).optional(),
+    assignees: z.array(z.string()).optional(),
+    milestone: z.string().optional(),
+  })
+  .refine(
+    (p) =>
+      p.title !== undefined ||
+      p.body !== undefined ||
+      p.body_section !== undefined ||
+      p.labels !== undefined ||
+      p.assignees !== undefined ||
+      p.milestone !== undefined,
+    { message: 'patch must include at least one field' },
+  )
+  .refine((p) => !(p.body !== undefined && p.body_section !== undefined), {
+    message: 'patch.body and patch.body_section are mutually exclusive',
+  });
+
+const inputSchema = z.object({
+  issue_ref: issueRefSchema,
+  patch: patchSchema,
+  dry_run: z.boolean().optional(),
+  repo: z
+    .string()
+    .regex(/^[a-zA-Z0-9._/-]+\/[a-zA-Z0-9._-]+$/, 'repo must be owner/repo format')
+    .optional(),
+});
+
+function envelope(payload: unknown) {
+  return { content: [{ type: 'text' as const, text: JSON.stringify(payload) }] };
+}
+
+const workItemUpdateHandler: HandlerDef = {
+  name: 'work_item_update',
+  description:
+    'Update an existing GitHub or GitLab issue (title, body, body_section, labels, assignees, milestone). Section-level patches preserve all other H2 sections. Use dry_run:true to preview without committing. Sister tool to `work_item` (which is create-only).',
+  inputSchema,
+  async execute(rawArgs: unknown) {
+    let args;
+    try {
+      args = inputSchema.parse(rawArgs);
+    } catch (err) {
+      return envelope({ ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+
+    const adapter = getAdapter({ repo: args.repo });
+    const result = await adapter.workItemUpdate(args);
+
+    if ('platform_unsupported' in result) {
+      return envelope({ ok: false, platform_unsupported: true, error: result.hint });
+    }
+    if (!result.ok) return envelope({ ok: false, error: result.error, code: result.code });
+    return envelope({ ok: true, ...result.data });
+  },
+};
+
+export default workItemUpdateHandler;
diff --git a/lib/adapters/github.ts b/lib/adapters/github.ts
index 2ae08c7..6280012 100644
--- a/lib/adapters/github.ts
+++ b/lib/adapters/github.ts
@@ -40,6 +40,7 @@ import { prMergeWaitGithub } from './pr-merge-wait-github.js';
 import { prStatusGithub } from './pr-status-github.js';
 import { prWaitCiGithub } from './pr-wait-ci-github.js';
 import { workItemGithub } from './work-item-github.js';
+import { workItemUpdateGithub } from './work-item-update-github.js';
 
 const stubMethod = async (_args: unknown) => ({
   platform_unsupported: true as const,
@@ -64,6 +65,7 @@ export const githubAdapter: PlatformAdapter = {
   labelCreate: labelCreateGithub,
   labelList: labelListGithub,
   workItem: workItemGithub,
+  workItemUpdate: workItemUpdateGithub,
   ibm: stubMethod,
   epicSubIssues: stubMethod,
   specGet: stubMethod,
diff --git a/lib/adapters/gitlab.ts b/lib/adapters/gitlab.ts
index f9675f2..72fdbf7 100644
--- a/lib/adapters/gitlab.ts
+++ b/lib/adapters/gitlab.ts
@@ -41,6 +41,7 @@ import { prMergeWaitGitlab } from './pr-merge-wait-gitlab.js';
 import { prStatusGitlab } from './pr-status-gitlab.js';
 import { prWaitCiGitlab } from './pr-wait-ci-gitlab.js';
 import { workItemGitlab } from './work-item-gitlab.js';
+import { workItemUpdateGitlab } from './work-item-update-gitlab.js';
 
 const stubMethod = async (_args: unknown) => ({
   platform_unsupported: true as const,
@@ -65,6 +66,7 @@ export const gitlabAdapter: PlatformAdapter = {
   labelCreate: labelCreateGitlab,
   labelList: labelListGitlab,
   workItem: workItemGitlab,
+  workItemUpdate: workItemUpdateGitlab,
   ibm: stubMethod,
   epicSubIssues: stubMethod,
   specGet: stubMethod,
diff --git a/lib/adapters/types.test.ts b/lib/adapters/types.test.ts
index 72ffae8..9dac8c6 100644
--- a/lib/adapters/types.test.ts
+++ b/lib/adapters/types.test.ts
@@ -86,6 +86,10 @@ describe('PlatformAdapter contract', () => {
   //                    after this lands the `handlers/` tree has zero
   //                    `gitlabApi*` importers, unblocking Phase 3 Story 3.1
   //                    (delete the pre-retrofit GitLab helper module).
+  // #287:              workItemUpdate — sister to workItem (Story 2.17) but
+  //                    for updating an existing issue (title, body,
+  //                    body_section, labels, assignees, milestone) instead of
+  //                    creating one. New tool, not a migration.
   const MIGRATED_METHODS = new Set<string>([
     'prCreate',
     'prDiff',
@@ -110,6 +114,7 @@ describe('PlatformAdapter contract', () => {
     'labelList',
     'resolveBranchSha',
     'workItem',
+    'workItemUpdate',
     'createBranch',
     'findExistingPr',
     'fetchCiTrustSignal',
diff --git a/lib/adapters/types.ts b/lib/adapters/types.ts
index 1a0b8e3..4ee9310 100644
--- a/lib/adapters/types.ts
+++ b/lib/adapters/types.ts
@@ -608,6 +608,63 @@ export interface WorkItemResponse {
   url: string;
   number: number;
 }
+
+/**
+ * `work_item_update` args/response (#287). Update an existing GitHub issue or
+ * GitLab issue via the appropriate platform CLI.
+ *
+ * `issue_ref` is parsed by `parseIssueRef` (`#N` or `owner/repo#N`). Adapters
+ * use the parsed `(owner, repo, number)` triple plus an optional `repo` arg
+ * to compose the cross-repo `--repo` / `-R` flag.
+ *
+ * `patch` is a partial mutation:
+ *   - `title` — replace the title
+ *   - `body` — replace the FULL body
+ *   - `body_section` — replace ONE H2 section (the H2 heading is matched after
+ *      `normalizeHeading`); preserves all other sections verbatim. Mutually
+ *      exclusive with `body` (handler validates and rejects with both).
+ *   - `labels` — replace the FULL label set on the issue
+ *   - `assignees` — replace the FULL assignee set
+ *   - `milestone` — set the milestone (GitHub only; on GitLab the adapter
+ *      returns `platform_unsupported`).
+ *
+ * `dry_run` returns the proposed patch without invoking the platform CLI.
+ *
+ * Cross-platform asymmetry (R-03):
+ *   - `milestone` is a GitHub concept (`gh issue edit --milestone`). GitLab's
+ *     equivalent is "milestone" too, BUT the work-item-update adapter on
+ *     GitLab returns `platform_unsupported` for `milestone` because GitLab's
+ *     `glab issue update --milestone` requires the milestone *id* and group/
+ *     project resolution that this thin tool does not own. Callers needing
+ *     GitLab milestone updates should call `glab` directly today.
+ */
+export interface WorkItemUpdatePatch {
+  title?: string;
+  body?: string;
+  body_section?: { heading: string; content: string };
+  labels?: string[];
+  assignees?: string[];
+  milestone?: string;
+}
+
+export interface WorkItemUpdateArgs {
+  issue_ref: string;
+  patch: WorkItemUpdatePatch;
+  dry_run?: boolean;
+  repo?: string;
+}
+
+export interface WorkItemUpdateResponse {
+  url: string;
+  number: number;
+  /** True when this call was a dry-run; no platform CLI was invoked. */
+  dry_run: boolean;
+  /** The fields that were (or would be) updated. */
+  updated_fields: string[];
+  /** When `body_section` was used, the resulting full body (recomputed). */
+  resolved_body?: string;
+}
+
 export type IbmArgs = unknown;
 export type IbmResponse = unknown;
 export type EpicSubIssuesArgs = unknown;
@@ -846,6 +903,9 @@ export interface PlatformAdapter {
   labelCreate(args: LabelCreateArgs): Promise<AdapterResult<NormalizedLabel>>;
   labelList(args: LabelListArgs): Promise<AdapterResult<LabelListResponse>>;
   workItem(args: WorkItemArgs): Promise<AdapterResult<WorkItemResponse>>;
+  workItemUpdate(
+    args: WorkItemUpdateArgs,
+  ): Promise<AdapterResult<WorkItemUpdateResponse>>;
   ibm(args: IbmArgs): Promise<AdapterResult<IbmResponse>>;
   epicSubIssues(args: EpicSubIssuesArgs): Promise<AdapterResult<EpicSubIssuesResponse>>;
 
@@ -917,6 +977,7 @@ export const PLATFORM_ADAPTER_METHODS = [
   'labelCreate',
   'labelList',
   'workItem',
+  'workItemUpdate',
   'ibm',
   'epicSubIssues',
   'specGet',
diff --git a/lib/adapters/work-item-update-github.test.ts b/lib/adapters/work-item-update-github.test.ts
new file mode 100644
index 0000000..ce4634f
--- /dev/null
+++ b/lib/adapters/work-item-update-github.test.ts
@@ -0,0 +1,378 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import type { AdapterResult, WorkItemUpdateResponse } from './types.ts';
+
+// Subprocess-boundary tests for the GitHub work_item_update adapter (#287).
+// Argv strictness per `lesson_origin_ops_pitfalls.md`: gh takes `--repo`
+// (long flag) and `--body <string>` inline; NOT glab's `-R` / `--description`.
+
+interface ThrowableError extends Error {
+  stderr?: string;
+  stdout?: string;
+  status?: number;
+}
+
+let execRegistry: Array<{ match: string; respond: string | (() => string) }> = [];
+let execCalls: string[] = [];
+
+function unquote(cmd: string): string {
+  return cmd.replace(/'([^']*)'/g, '$1');
+}
+
+const mockExecSync = mock((cmd: string, _opts?: unknown) => {
+  execCalls.push(cmd);
+  const flat = unquote(cmd);
+  if (
+    flat.includes('gh issue edit') &&
+    (/\s-R\s/.test(flat) || /--description/.test(flat))
+  ) {
+    const err = new Error('FAIL: gh issue edit invoked with glab-style flags') as ThrowableError;
+    err.status = 127;
+    throw err;
+  }
+  for (const { match, respond } of execRegistry) {
+    if (cmd.includes(match) || flat.includes(match)) {
+      return typeof respond === 'function' ? respond() : respond;
+    }
+  }
+  const err = new Error(`Unexpected exec: ${cmd}`) as ThrowableError;
+  err.stderr = `Unexpected exec: ${cmd}`;
+  err.status = 127;
+  throw err;
+});
+
+mock.module('child_process', () => ({ execSync: mockExecSync }));
+
+const { workItemUpdateGithub } = await import('./work-item-update-github.ts');
+
+function on(match: string, respond: string | (() => string)): void {
+  execRegistry.push({ match, respond });
+}
+
+function expectOk(
+  r: AdapterResult<WorkItemUpdateResponse>,
+): asserts r is { ok: true; data: WorkItemUpdateResponse } {
+  if (!('ok' in r) || !r.ok) {
+    throw new Error(`expected ok result, got ${JSON.stringify(r)}`);
+  }
+}
+
+function expectErr(
+  r: AdapterResult<WorkItemUpdateResponse>,
+): asserts r is { ok: false; error: string; code: string } {
+  if (!('ok' in r) || r.ok) {
+    throw new Error(`expected error result, got ${JSON.stringify(r)}`);
+  }
+}
+
+function findCall(needle: string): string {
+  return execCalls.find((c) => c.includes(needle) || unquote(c).includes(needle)) ?? '';
+}
+
+beforeEach(() => {
+  execRegistry = [];
+  execCalls = [];
+});
+
+describe('workItemUpdateGithub — subprocess boundary', () => {
+  // ---- title-only patch ----
+
+  test("title-only patch: emits gh issue edit with --title and no --body", async () => {
+    on('gh issue edit', 'https://github.com/org/repo/issues/42\n');
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#42',
+      patch: { title: 'New title' },
+    });
+    expectOk(result);
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'gh' 'issue' 'edit' '42'");
+    expect(call).toContain("'--title' 'New title'");
+    expect(call).not.toContain('--body');
+    expect(result.data.number).toBe(42);
+    expect(result.data.dry_run).toBe(false);
+    expect(result.data.updated_fields).toEqual(['title']);
+  });
+
+  // ---- body-only patch (no pre-fetch needed) ----
+
+  test('body-only patch: emits --body and skips the pre-fetch view', async () => {
+    on('gh issue edit', 'https://github.com/org/repo/issues/42\n');
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#42',
+      patch: { body: 'completely new body' },
+    });
+    expectOk(result);
+
+    expect(execCalls.some((c) => unquote(c).includes('gh issue view'))).toBe(false);
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'--body' 'completely new body'");
+    expect(result.data.updated_fields).toEqual(['body']);
+  });
+
+  // ---- repo flag forwarding ----
+
+  test('--repo forwarded for cross-repo update', async () => {
+    on('gh issue edit', 'https://github.com/foo/bar/issues/9\n');
+
+    await workItemUpdateGithub({
+      issue_ref: '#9',
+      patch: { title: 'X' },
+      repo: 'foo/bar',
+    });
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'--repo' 'foo/bar'");
+  });
+
+  test('rejects malformed repo slug with typed error', async () => {
+    const result = await workItemUpdateGithub({
+      issue_ref: '#1',
+      patch: { title: 'x' },
+      repo: 'not a slug',
+    });
+    expectErr(result);
+    expect(result.code).toBe('invalid_repo_slug');
+  });
+
+  // ---- issue_ref parsing ----
+
+  test('parses owner/repo#N issue_ref', async () => {
+    on('gh issue edit', 'https://github.com/org/repo/issues/123\n');
+
+    const result = await workItemUpdateGithub({
+      issue_ref: 'org/repo#123',
+      patch: { title: 'X' },
+    });
+    expectOk(result);
+    expect(result.data.number).toBe(123);
+  });
+
+  test('rejects unparseable issue_ref', async () => {
+    const result = await workItemUpdateGithub({
+      issue_ref: 'not-an-issue',
+      patch: { title: 'x' },
+    });
+    expectErr(result);
+    expect(result.code).toBe('invalid_issue_ref');
+  });
+
+  // ---- labels: replacement-via-add/remove diff ----
+
+  test('labels patch: pre-fetches current labels and emits add/remove diff', async () => {
+    on(
+      'gh issue view',
+      JSON.stringify({
+        number: 7,
+        url: 'https://github.com/org/repo/issues/7',
+        body: '## Summary\nbody\n',
+        labels: [{ name: 'old-keep' }, { name: 'old-drop' }],
+        assignees: [],
+      }),
+    );
+    on('gh issue edit', 'https://github.com/org/repo/issues/7\n');
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#7',
+      patch: { labels: ['old-keep', 'new-add'] },
+    });
+    expectOk(result);
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'--add-label' 'new-add'");
+    expect(call).toContain("'--remove-label' 'old-drop'");
+    expect(call).not.toContain("'--add-label' 'old-keep'");
+  });
+
+  // ---- assignees: same diff shape ----
+
+  test('assignees patch: emits add/remove diff against current set', async () => {
+    on(
+      'gh issue view',
+      JSON.stringify({
+        number: 11,
+        url: 'https://github.com/org/repo/issues/11',
+        body: '',
+        labels: [],
+        assignees: [{ login: 'alice' }, { login: 'bob' }],
+      }),
+    );
+    on('gh issue edit', 'https://github.com/org/repo/issues/11\n');
+
+    await workItemUpdateGithub({
+      issue_ref: '#11',
+      patch: { assignees: ['alice', 'carol'] },
+    });
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'--add-assignee' 'carol'");
+    expect(call).toContain("'--remove-assignee' 'bob'");
+    expect(call).not.toContain("'--add-assignee' 'alice'");
+  });
+
+  // ---- milestone (GitHub only) ----
+
+  test('milestone patch: emits --milestone flag', async () => {
+    on('gh issue edit', 'https://github.com/org/repo/issues/3\n');
+
+    await workItemUpdateGithub({
+      issue_ref: '#3',
+      patch: { milestone: 'v1.0' },
+    });
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain("'--milestone' 'v1.0'");
+  });
+
+  // ---- body_section: read-modify-write ----
+
+  test('body_section patch: pre-fetches body, splices section, sends full body', async () => {
+    const originalBody = [
+      '## Summary',
+      'short summary',
+      '',
+      '## Dependencies',
+      '- old dep',
+      '',
+      '## Acceptance Criteria',
+      '- [ ] AC',
+    ].join('\n');
+
+    on(
+      'gh issue view',
+      JSON.stringify({
+        number: 5,
+        url: 'https://github.com/org/repo/issues/5',
+        body: originalBody,
+        labels: [],
+        assignees: [],
+      }),
+    );
+    on('gh issue edit', 'https://github.com/org/repo/issues/5\n');
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#5',
+      patch: { body_section: { heading: 'Dependencies', content: '- new dep' } },
+    });
+    expectOk(result);
+    expect(result.data.updated_fields).toEqual(['body_section']);
+    expect(result.data.resolved_body).toContain('## Dependencies');
+    expect(result.data.resolved_body).toContain('- new dep');
+    expect(result.data.resolved_body).not.toContain('- old dep');
+    // AC: section patching preserves other H2 sections unmodified
+    expect(result.data.resolved_body).toContain('## Summary');
+    expect(result.data.resolved_body).toContain('short summary');
+    expect(result.data.resolved_body).toContain('## Acceptance Criteria');
+    expect(result.data.resolved_body).toContain('- [ ] AC');
+
+    const call = findCall('gh issue edit');
+    expect(call).toContain('--body');
+  });
+
+  test('body_section: missing section returns typed error, no edit invoked', async () => {
+    on(
+      'gh issue view',
+      JSON.stringify({
+        number: 5,
+        url: 'https://github.com/org/repo/issues/5',
+        body: '## Summary\nx\n',
+        labels: [],
+        assignees: [],
+      }),
+    );
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#5',
+      patch: { body_section: { heading: 'Dependencies', content: '- x' } },
+    });
+    expectErr(result);
+    expect(result.code).toBe('section_splice_failed');
+    expect(execCalls.some((c) => unquote(c).includes('gh issue edit'))).toBe(false);
+  });
+
+  // ---- dry_run: no side effect ----
+
+  test('dry_run:true returns proposed changes without invoking gh issue edit', async () => {
+    const result = await workItemUpdateGithub({
+      issue_ref: '#42',
+      patch: { title: 'Preview' },
+      dry_run: true,
+    });
+    expectOk(result);
+    expect(result.data.dry_run).toBe(true);
+    expect(result.data.updated_fields).toEqual(['title']);
+    expect(execCalls.some((c) => unquote(c).includes('gh issue edit'))).toBe(false);
+  });
+
+  test('dry_run:true with body_section pre-fetches and returns resolved_body', async () => {
+    on(
+      'gh issue view',
+      JSON.stringify({
+        number: 9,
+        url: 'https://github.com/org/repo/issues/9',
+        body: '## A\nold\n',
+        labels: [],
+        assignees: [],
+      }),
+    );
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#9',
+      patch: { body_section: { heading: 'A', content: 'new' } },
+      dry_run: true,
+    });
+    expectOk(result);
+    expect(result.data.dry_run).toBe(true);
+    expect(result.data.resolved_body).toContain('new');
+    expect(execCalls.some((c) => unquote(c).includes('gh issue edit'))).toBe(false);
+  });
+
+  // ---- patch validation ----
+
+  test('rejects empty patch', async () => {
+    const result = await workItemUpdateGithub({ issue_ref: '#1', patch: {} });
+    expectErr(result);
+    expect(result.code).toBe('empty_patch');
+  });
+
+  test('rejects body + body_section together', async () => {
+    const result = await workItemUpdateGithub({
+      issue_ref: '#1',
+      patch: { body: 'x', body_section: { heading: 'A', content: 'y' } },
+    });
+    expectErr(result);
+    expect(result.code).toBe('patch_conflict');
+  });
+
+  // ---- error surface ----
+
+  test('returns AdapterResult.error on gh issue edit failure', async () => {
+    on('gh issue edit', () => {
+      const err = new Error('not authenticated') as ThrowableError;
+      err.stderr = 'gh: not authenticated';
+      err.status = 1;
+      throw err;
+    });
+
+    const result = await workItemUpdateGithub({ issue_ref: '#1', patch: { title: 'x' } });
+    expectErr(result);
+    expect(result.code).toBe('gh_issue_edit_failed');
+  });
+
+  test('returns AdapterResult.error on gh issue view failure during pre-fetch', async () => {
+    on('gh issue view', () => {
+      const err = new Error('not found') as ThrowableError;
+      err.stderr = 'no such issue';
+      err.status = 1;
+      throw err;
+    });
+
+    const result = await workItemUpdateGithub({
+      issue_ref: '#1',
+      patch: { labels: ['x'] },
+    });
+    expectErr(result);
+    expect(result.code).toBe('gh_issue_view_failed');
+  });
+});
diff --git a/lib/adapters/work-item-update-github.ts b/lib/adapters/work-item-update-github.ts
new file mode 100644
index 0000000..9e6e9bf
--- /dev/null
+++ b/lib/adapters/work-item-update-github.ts
@@ -0,0 +1,243 @@
+/**
+ * GitHub `work_item_update` adapter implementation (#287).
+ *
+ * Updates an existing GitHub issue via `gh issue edit`. Supports title-only,
+ * body-only, label, assignee, milestone, and section-level body patches.
+ *
+ * Argv composition:
+ *   gh issue edit <number>
+ *     [--title <new title>]
+ *     [--body <new full body>]
+ *     [--add-label <label>]... [--remove-label <label>]...
+ *     [--add-assignee <user>]... [--remove-assignee <user>]...
+ *     [--milestone <name>]
+ *     [--repo <owner/repo>]
+ *
+ * Body-section patching:
+ *   When `patch.body_section` is set, this adapter first reads the current
+ *   issue body (via `gh issue view --json body`), splices in the new section
+ *   content via `spliceH2Section`, and sends the resulting full body to
+ *   `gh issue edit --body`. Section-level patches are mutually exclusive with
+ *   `patch.body` — the handler's schema enforces that.
+ *
+ * Label/assignee replacement semantics:
+ *   `gh issue edit` does not have a "replace all labels" flag — it only
+ *   supports `--add-label` and `--remove-label`. To get replacement semantics
+ *   we read the current label set, compute the (add, remove) diff, and emit
+ *   the matching flags. Same shape for assignees.
+ */
+
+import { execSync } from 'child_process';
+import { runArgv } from '../shared/error-norm.js';
+import { spliceH2Section } from '../work-item-section.js';
+import type {
+  AdapterResult,
+  WorkItemUpdateArgs,
+  WorkItemUpdateResponse,
+} from './types.js';
+
+function projectDir(): string {
+  return process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+}
+
+const GITHUB_REPO_SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+interface GhIssueViewBody {
+  body?: string;
+  url?: string;
+  number?: number;
+  labels?: Array<{ name?: string }>;
+  assignees?: Array<{ login?: string }>;
+}
+
+function parseIssueRefNumber(ref: string): number | null {
+  const full = /^(.+)\/([^/\s#]+)#(\d+)$/.exec(ref);
+  if (full) return parseInt(full[3], 10);
+  const short = /^#?(\d+)$/.exec(ref);
+  if (short) return parseInt(short[1], 10);
+  return null;
+}
+
+function fetchCurrentIssue(
+  num: number,
+  repo: string | undefined,
+  cwd: string,
+): { ok: true; data: GhIssueViewBody } | { ok: false; error: string } {
+  const cmd = [
+    'gh',
+    'issue',
+    'view',
+    String(num),
+    '--json',
+    'number,url,body,labels,assignees',
+  ];
+  if (repo !== undefined) cmd.push('--repo', repo);
+  const result = runArgv(cmd, cwd);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      error: `gh issue view failed: ${result.stderr.trim() || result.stdout.trim()}`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(result.stdout) as GhIssueViewBody;
+    return { ok: true, data: parsed };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `gh issue view returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+function diffSets(current: string[], next: string[]): { add: string[]; remove: string[] } {
+  const cur = new Set(current);
+  const nxt = new Set(next);
+  const add: string[] = [];
+  const remove: string[] = [];
+  for (const v of nxt) if (!cur.has(v)) add.push(v);
+  for (const v of cur) if (!nxt.has(v)) remove.push(v);
+  return { add, remove };
+}
+
+export async function workItemUpdateGithub(
+  args: WorkItemUpdateArgs,
+): Promise<AdapterResult<WorkItemUpdateResponse>> {
+  const num = parseIssueRefNumber(args.issue_ref);
+  if (num === null) {
+    return {
+      ok: false,
+      code: 'invalid_issue_ref',
+      error: `cannot parse issue_ref: ${args.issue_ref}`,
+    };
+  }
+  if (args.repo !== undefined && !GITHUB_REPO_SLUG.test(args.repo)) {
+    return {
+      ok: false,
+      code: 'invalid_repo_slug',
+      error: `invalid repo slug: ${args.repo}`,
+    };
+  }
+
+  const patch = args.patch;
+  if (patch.body !== undefined && patch.body_section !== undefined) {
+    return {
+      ok: false,
+      code: 'patch_conflict',
+      error: 'patch.body and patch.body_section are mutually exclusive',
+    };
+  }
+
+  const cwd = projectDir();
+  const updated_fields: string[] = [];
+  let resolvedBody: string | undefined;
+  let needCurrentLabels = patch.labels !== undefined;
+  let needCurrentAssignees = patch.assignees !== undefined;
+  const needCurrentBody = patch.body_section !== undefined;
+  let urlFromView: string | undefined;
+  let currentLabels: string[] = [];
+  let currentAssignees: string[] = [];
+
+  if (needCurrentLabels || needCurrentAssignees || needCurrentBody) {
+    const fetched = fetchCurrentIssue(num, args.repo, cwd);
+    if (!fetched.ok) {
+      return { ok: false, code: 'gh_issue_view_failed', error: fetched.error };
+    }
+    urlFromView = fetched.data.url;
+    currentLabels = (fetched.data.labels ?? [])
+      .map((l) => (typeof l.name === 'string' ? l.name : ''))
+      .filter((n) => n.length > 0);
+    currentAssignees = (fetched.data.assignees ?? [])
+      .map((a) => (typeof a.login === 'string' ? a.login : ''))
+      .filter((n) => n.length > 0);
+
+    if (needCurrentBody) {
+      const splice = spliceH2Section(
+        fetched.data.body ?? '',
+        patch.body_section!.heading,
+        patch.body_section!.content,
+      );
+      if (!splice.ok) {
+        return { ok: false, code: 'section_splice_failed', error: splice.error };
+      }
+      resolvedBody = splice.body;
+    }
+  }
+
+  if (patch.title !== undefined) updated_fields.push('title');
+  if (patch.body !== undefined) updated_fields.push('body');
+  if (patch.body_section !== undefined) updated_fields.push('body_section');
+  if (patch.labels !== undefined) updated_fields.push('labels');
+  if (patch.assignees !== undefined) updated_fields.push('assignees');
+  if (patch.milestone !== undefined) updated_fields.push('milestone');
+
+  if (updated_fields.length === 0) {
+    return {
+      ok: false,
+      code: 'empty_patch',
+      error: 'patch must include at least one field',
+    };
+  }
+
+  // Dry-run: short-circuit before running gh.
+  if (args.dry_run) {
+    return {
+      ok: true,
+      data: {
+        url: urlFromView ?? '',
+        number: num,
+        dry_run: true,
+        updated_fields,
+        ...(resolvedBody !== undefined ? { resolved_body: resolvedBody } : {}),
+      },
+    };
+  }
+
+  // Compose `gh issue edit` argv.
+  const cmd = ['gh', 'issue', 'edit', String(num)];
+  if (patch.title !== undefined) cmd.push('--title', patch.title);
+  if (patch.body !== undefined) cmd.push('--body', patch.body);
+  else if (resolvedBody !== undefined) cmd.push('--body', resolvedBody);
+
+  if (patch.labels !== undefined) {
+    const { add, remove } = diffSets(currentLabels, patch.labels);
+    for (const l of add) cmd.push('--add-label', l);
+    for (const l of remove) cmd.push('--remove-label', l);
+  }
+  if (patch.assignees !== undefined) {
+    const { add, remove } = diffSets(currentAssignees, patch.assignees);
+    for (const a of add) cmd.push('--add-assignee', a);
+    for (const a of remove) cmd.push('--remove-assignee', a);
+  }
+  if (patch.milestone !== undefined) cmd.push('--milestone', patch.milestone);
+  if (args.repo !== undefined) cmd.push('--repo', args.repo);
+
+  const result = runArgv(cmd, cwd);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'gh_issue_edit_failed',
+      error: `gh issue edit failed: ${result.stderr.trim() || result.stdout.trim()}`,
+    };
+  }
+
+  // gh issue edit prints the issue URL on success — reuse it; otherwise fall
+  // back to the URL captured during the pre-fetch.
+  const url = result.stdout.trim().split('\n').pop()?.trim() || urlFromView || '';
+
+  return {
+    ok: true,
+    data: {
+      url,
+      number: num,
+      dry_run: false,
+      updated_fields,
+      ...(resolvedBody !== undefined ? { resolved_body: resolvedBody } : {}),
+    },
+  };
+}
+
+// `execSync` is intentionally re-imported so adapter-level tests can
+// `mock.module('child_process', ...)` and intercept this module's subprocess
+// calls. See work-item-github.ts for the rationale.
+void execSync;
diff --git a/lib/adapters/work-item-update-gitlab.test.ts b/lib/adapters/work-item-update-gitlab.test.ts
new file mode 100644
index 0000000..f108a79
--- /dev/null
+++ b/lib/adapters/work-item-update-gitlab.test.ts
@@ -0,0 +1,297 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+import type { AdapterResult, WorkItemUpdateResponse } from './types.ts';
+
+// Subprocess-boundary tests for the GitLab work_item_update adapter (#287).
+// Argv strictness per `lesson_origin_ops_pitfalls.md`: glab uses `-R`,
+// `--description` (not `--body`), CSV labels — NOT GitHub-style flags.
+
+interface ThrowableError extends Error {
+  stderr?: string;
+  stdout?: string;
+  status?: number;
+}
+
+let execRegistry: Array<{ match: string; respond: string | (() => string) }> = [];
+let execCalls: string[] = [];
+
+function unquote(cmd: string): string {
+  return cmd.replace(/'([^']*)'/g, '$1');
+}
+
+const mockExecSync = mock((cmd: string, _opts?: unknown) => {
+  execCalls.push(cmd);
+  const flat = unquote(cmd);
+  if (
+    flat.includes('glab issue update') &&
+    (/--repo/.test(flat) || /--body\s/.test(flat) || /--add-label/.test(flat))
+  ) {
+    const err = new Error(
+      'FAIL: glab issue update invoked with gh-style flags',
+    ) as ThrowableError;
+    err.status = 127;
+    throw err;
+  }
+  for (const { match, respond } of execRegistry) {
+    if (cmd.includes(match) || flat.includes(match)) {
+      return typeof respond === 'function' ? respond() : respond;
+    }
+  }
+  const err = new Error(`Unexpected exec: ${cmd}`) as ThrowableError;
+  err.stderr = `Unexpected exec: ${cmd}`;
+  err.status = 127;
+  throw err;
+});
+
+mock.module('child_process', () => ({ execSync: mockExecSync }));
+
+const { workItemUpdateGitlab } = await import('./work-item-update-gitlab.ts');
+
+function on(match: string, respond: string | (() => string)): void {
+  execRegistry.push({ match, respond });
+}
+
+function expectOk(
+  r: AdapterResult<WorkItemUpdateResponse>,
+): asserts r is { ok: true; data: WorkItemUpdateResponse } {
+  if (!('ok' in r) || !r.ok) {
+    throw new Error(`expected ok result, got ${JSON.stringify(r)}`);
+  }
+}
+
+function expectErr(
+  r: AdapterResult<WorkItemUpdateResponse>,
+): asserts r is { ok: false; error: string; code: string } {
+  if (!('ok' in r) || r.ok) {
+    throw new Error(`expected error result, got ${JSON.stringify(r)}`);
+  }
+}
+
+function expectUnsupported(
+  r: AdapterResult<WorkItemUpdateResponse>,
+): asserts r is { platform_unsupported: true; hint: string } {
+  if (!('platform_unsupported' in r)) {
+    throw new Error(`expected platform_unsupported, got ${JSON.stringify(r)}`);
+  }
+}
+
+function findCall(needle: string): string {
+  return execCalls.find((c) => c.includes(needle) || unquote(c).includes(needle)) ?? '';
+}
+
+beforeEach(() => {
+  execRegistry = [];
+  execCalls = [];
+});
+
+describe('workItemUpdateGitlab — subprocess boundary', () => {
+  test('title-only patch emits glab issue update --title', async () => {
+    on('glab issue update', 'https://gitlab.com/org/repo/-/issues/42\n');
+
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#42',
+      patch: { title: 'New title' },
+    });
+    expectOk(result);
+
+    const call = findCall('glab issue update');
+    expect(call).toContain("'glab' 'issue' 'update' '42'");
+    expect(call).toContain("'--title' 'New title'");
+    expect(result.data.dry_run).toBe(false);
+  });
+
+  test('body-only patch emits --description (NOT --body)', async () => {
+    on('glab issue update', 'https://gitlab.com/org/repo/-/issues/42\n');
+
+    await workItemUpdateGitlab({ issue_ref: '#42', patch: { body: 'x' } });
+
+    const call = findCall('glab issue update');
+    expect(call).toContain("'--description' 'x'");
+    expect(call).not.toContain("'--body' 'x'");
+  });
+
+  test('-R forwarded for cross-repo update (NOT --repo)', async () => {
+    on('glab issue update', 'https://gitlab.com/foo/bar/-/issues/9\n');
+
+    await workItemUpdateGitlab({
+      issue_ref: '#9',
+      patch: { title: 'X' },
+      repo: 'foo/bar',
+    });
+
+    const call = findCall('glab issue update');
+    expect(call).toContain("'-R' 'foo/bar'");
+    expect(call).not.toContain('--repo');
+  });
+
+  test('labels patch emits CSV --label / --unlabel diff', async () => {
+    on(
+      'glab issue view',
+      JSON.stringify({
+        iid: 7,
+        web_url: 'https://gitlab.com/org/repo/-/issues/7',
+        description: '',
+        labels: ['old-keep', 'old-drop'],
+        assignees: [],
+      }),
+    );
+    on('glab issue update', 'https://gitlab.com/org/repo/-/issues/7\n');
+
+    await workItemUpdateGitlab({
+      issue_ref: '#7',
+      patch: { labels: ['old-keep', 'new-add'] },
+    });
+
+    const call = findCall('glab issue update');
+    expect(call).toContain("'--label' 'new-add'");
+    expect(call).toContain("'--unlabel' 'old-drop'");
+  });
+
+  test('assignees patch emits --assignee / --unassign diff', async () => {
+    on(
+      'glab issue view',
+      JSON.stringify({
+        iid: 11,
+        web_url: 'https://gitlab.com/org/repo/-/issues/11',
+        description: '',
+        labels: [],
+        assignees: [{ username: 'alice' }, { username: 'bob' }],
+      }),
+    );
+    on('glab issue update', 'https://gitlab.com/org/repo/-/issues/11\n');
+
+    await workItemUpdateGitlab({
+      issue_ref: '#11',
+      patch: { assignees: ['alice', 'carol'] },
+    });
+
+    const call = findCall('glab issue update');
+    expect(call).toContain("'--assignee' 'carol'");
+    expect(call).toContain("'--unassign' 'bob'");
+  });
+
+  // ---- #287: cross-platform asymmetry ----
+
+  test('milestone returns platform_unsupported (#287 — GitLab milestone resolution out of scope)', async () => {
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#1',
+      patch: { milestone: 'v1.0' },
+    });
+    expectUnsupported(result);
+    expect(result.hint.toLowerCase()).toContain('milestone');
+    // No glab subprocess should have been attempted.
+    expect(execCalls.length).toBe(0);
+  });
+
+  // ---- body_section: read-modify-write ----
+
+  test('body_section: pre-fetches description, splices, sends full description', async () => {
+    const original = [
+      '## Summary',
+      'short',
+      '',
+      '## Dependencies',
+      '- old',
+      '',
+      '## Acceptance Criteria',
+      '- [ ] AC',
+    ].join('\n');
+
+    on(
+      'glab issue view',
+      JSON.stringify({
+        iid: 5,
+        web_url: 'https://gitlab.com/org/repo/-/issues/5',
+        description: original,
+        labels: [],
+        assignees: [],
+      }),
+    );
+    on('glab issue update', 'https://gitlab.com/org/repo/-/issues/5\n');
+
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#5',
+      patch: { body_section: { heading: 'Dependencies', content: '- new' } },
+    });
+    expectOk(result);
+    expect(result.data.resolved_body).toContain('- new');
+    expect(result.data.resolved_body).not.toContain('- old');
+    expect(result.data.resolved_body).toContain('## Acceptance Criteria');
+
+    const call = findCall('glab issue update');
+    expect(call).toContain('--description');
+  });
+
+  test('body_section missing returns typed error', async () => {
+    on(
+      'glab issue view',
+      JSON.stringify({
+        iid: 5,
+        web_url: 'https://gitlab.com/org/repo/-/issues/5',
+        description: '## Summary\nx\n',
+        labels: [],
+        assignees: [],
+      }),
+    );
+
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#5',
+      patch: { body_section: { heading: 'NotPresent', content: 'y' } },
+    });
+    expectErr(result);
+    expect(result.code).toBe('section_splice_failed');
+  });
+
+  // ---- dry_run ----
+
+  test('dry_run:true skips glab issue update', async () => {
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#42',
+      patch: { title: 'Preview' },
+      dry_run: true,
+    });
+    expectOk(result);
+    expect(result.data.dry_run).toBe(true);
+    expect(execCalls.some((c) => unquote(c).includes('glab issue update'))).toBe(false);
+  });
+
+  // ---- validation ----
+
+  test('rejects unparseable issue_ref', async () => {
+    const result = await workItemUpdateGitlab({
+      issue_ref: 'not-an-issue',
+      patch: { title: 'x' },
+    });
+    expectErr(result);
+    expect(result.code).toBe('invalid_issue_ref');
+  });
+
+  test('rejects empty patch', async () => {
+    const result = await workItemUpdateGitlab({ issue_ref: '#1', patch: {} });
+    expectErr(result);
+    expect(result.code).toBe('empty_patch');
+  });
+
+  test('rejects body + body_section together', async () => {
+    const result = await workItemUpdateGitlab({
+      issue_ref: '#1',
+      patch: { body: 'x', body_section: { heading: 'A', content: 'y' } },
+    });
+    expectErr(result);
+    expect(result.code).toBe('patch_conflict');
+  });
+
+  // ---- error surface ----
+
+  test('returns AdapterResult.error on glab issue update failure', async () => {
+    on('glab issue update', () => {
+      const err = new Error('forbidden') as ThrowableError;
+      err.stderr = 'glab: 403';
+      err.status = 1;
+      throw err;
+    });
+
+    const result = await workItemUpdateGitlab({ issue_ref: '#1', patch: { title: 'x' } });
+    expectErr(result);
+    expect(result.code).toBe('glab_issue_update_failed');
+  });
+});
diff --git a/lib/adapters/work-item-update-gitlab.ts b/lib/adapters/work-item-update-gitlab.ts
new file mode 100644
index 0000000..f2a848c
--- /dev/null
+++ b/lib/adapters/work-item-update-gitlab.ts
@@ -0,0 +1,233 @@
+/**
+ * GitLab `work_item_update` adapter implementation (#287).
+ *
+ * Updates an existing GitLab issue via `glab issue update`. Supports
+ * title-only, body-only, label, assignee, and section-level body patches.
+ *
+ * Argv composition (per `lesson_origin_ops_pitfalls.md` — glab uses `-R`,
+ * `--description`, comma-separated labels, NOT GitHub-style flags):
+ *
+ *   glab issue update <number>
+ *     [--title <new title>]
+ *     [--description <new full body>]
+ *     [--label <added,csv>]
+ *     [--unlabel <removed,csv>]
+ *     [--assignee <added,csv>]
+ *     [--unassign <removed,csv>]
+ *     [-R <owner/repo>]
+ *
+ * Cross-platform asymmetry (R-03 / #281):
+ *   - `patch.milestone` returns `platform_unsupported`. GitLab does have
+ *     milestones, but `glab issue update --milestone` requires a milestone
+ *     *id* and group/project resolution that this thin tool does not own.
+ *     Callers that need GitLab milestone updates should call `glab` directly.
+ *
+ * Body-section patching:
+ *   When `patch.body_section` is set, this adapter first reads the current
+ *   issue body (via `glab issue view -F json`), splices in the new section
+ *   content via `spliceH2Section`, and sends the resulting full body to
+ *   `glab issue update --description`.
+ *
+ * Label/assignee replacement semantics:
+ *   `glab issue update` accepts `--label` (additive csv) and `--unlabel`
+ *   (csv to remove). To get replacement semantics we read the current label
+ *   set, compute the (add, remove) diff, and emit the matching flags. Same
+ *   shape for assignees (`--assignee` / `--unassign`).
+ */
+
+import { execSync } from 'child_process';
+import { runArgv } from '../shared/error-norm.js';
+import { spliceH2Section } from '../work-item-section.js';
+import type {
+  AdapterResult,
+  WorkItemUpdateArgs,
+  WorkItemUpdateResponse,
+} from './types.js';
+
+function projectDir(): string {
+  return process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+}
+
+interface GlabIssueViewBody {
+  iid?: number;
+  description?: string;
+  web_url?: string;
+  labels?: string[];
+  assignees?: Array<{ username?: string }>;
+}
+
+function parseIssueRefNumber(ref: string): number | null {
+  const full = /^(.+)\/([^/\s#]+)#(\d+)$/.exec(ref);
+  if (full) return parseInt(full[3], 10);
+  const short = /^#?(\d+)$/.exec(ref);
+  if (short) return parseInt(short[1], 10);
+  return null;
+}
+
+function fetchCurrentIssue(
+  num: number,
+  repo: string | undefined,
+  cwd: string,
+): { ok: true; data: GlabIssueViewBody } | { ok: false; error: string } {
+  const cmd = ['glab', 'issue', 'view', String(num), '-F', 'json'];
+  if (repo !== undefined) cmd.push('-R', repo);
+  const result = runArgv(cmd, cwd);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      error: `glab issue view failed: ${result.stderr.trim() || result.stdout.trim()}`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(result.stdout) as GlabIssueViewBody;
+    return { ok: true, data: parsed };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `glab issue view returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+function diffSets(current: string[], next: string[]): { add: string[]; remove: string[] } {
+  const cur = new Set(current);
+  const nxt = new Set(next);
+  const add: string[] = [];
+  const remove: string[] = [];
+  for (const v of nxt) if (!cur.has(v)) add.push(v);
+  for (const v of cur) if (!nxt.has(v)) remove.push(v);
+  return { add, remove };
+}
+
+export async function workItemUpdateGitlab(
+  args: WorkItemUpdateArgs,
+): Promise<AdapterResult<WorkItemUpdateResponse>> {
+  const num = parseIssueRefNumber(args.issue_ref);
+  if (num === null) {
+    return {
+      ok: false,
+      code: 'invalid_issue_ref',
+      error: `cannot parse issue_ref: ${args.issue_ref}`,
+    };
+  }
+
+  const patch = args.patch;
+  if (patch.body !== undefined && patch.body_section !== undefined) {
+    return {
+      ok: false,
+      code: 'patch_conflict',
+      error: 'patch.body and patch.body_section are mutually exclusive',
+    };
+  }
+  if (patch.milestone !== undefined) {
+    return {
+      platform_unsupported: true,
+      hint: 'milestone updates not supported via work_item_update on GitLab; call glab directly with the numeric milestone id',
+    };
+  }
+
+  const cwd = projectDir();
+  const updated_fields: string[] = [];
+  let resolvedBody: string | undefined;
+  const needCurrentLabels = patch.labels !== undefined;
+  const needCurrentAssignees = patch.assignees !== undefined;
+  const needCurrentBody = patch.body_section !== undefined;
+  let urlFromView: string | undefined;
+  let currentLabels: string[] = [];
+  let currentAssignees: string[] = [];
+
+  if (needCurrentLabels || needCurrentAssignees || needCurrentBody) {
+    const fetched = fetchCurrentIssue(num, args.repo, cwd);
+    if (!fetched.ok) {
+      return { ok: false, code: 'glab_issue_view_failed', error: fetched.error };
+    }
+    urlFromView = fetched.data.web_url;
+    currentLabels = Array.isArray(fetched.data.labels)
+      ? fetched.data.labels.filter((s): s is string => typeof s === 'string')
+      : [];
+    currentAssignees = (fetched.data.assignees ?? [])
+      .map((a) => (typeof a.username === 'string' ? a.username : ''))
+      .filter((n) => n.length > 0);
+
+    if (needCurrentBody) {
+      const splice = spliceH2Section(
+        fetched.data.description ?? '',
+        patch.body_section!.heading,
+        patch.body_section!.content,
+      );
+      if (!splice.ok) {
+        return { ok: false, code: 'section_splice_failed', error: splice.error };
+      }
+      resolvedBody = splice.body;
+    }
+  }
+
+  if (patch.title !== undefined) updated_fields.push('title');
+  if (patch.body !== undefined) updated_fields.push('body');
+  if (patch.body_section !== undefined) updated_fields.push('body_section');
+  if (patch.labels !== undefined) updated_fields.push('labels');
+  if (patch.assignees !== undefined) updated_fields.push('assignees');
+
+  if (updated_fields.length === 0) {
+    return {
+      ok: false,
+      code: 'empty_patch',
+      error: 'patch must include at least one field',
+    };
+  }
+
+  if (args.dry_run) {
+    return {
+      ok: true,
+      data: {
+        url: urlFromView ?? '',
+        number: num,
+        dry_run: true,
+        updated_fields,
+        ...(resolvedBody !== undefined ? { resolved_body: resolvedBody } : {}),
+      },
+    };
+  }
+
+  const cmd = ['glab', 'issue', 'update', String(num)];
+  if (patch.title !== undefined) cmd.push('--title', patch.title);
+  if (patch.body !== undefined) cmd.push('--description', patch.body);
+  else if (resolvedBody !== undefined) cmd.push('--description', resolvedBody);
+
+  if (patch.labels !== undefined) {
+    const { add, remove } = diffSets(currentLabels, patch.labels);
+    if (add.length > 0) cmd.push('--label', add.join(','));
+    if (remove.length > 0) cmd.push('--unlabel', remove.join(','));
+  }
+  if (patch.assignees !== undefined) {
+    const { add, remove } = diffSets(currentAssignees, patch.assignees);
+    if (add.length > 0) cmd.push('--assignee', add.join(','));
+    if (remove.length > 0) cmd.push('--unassign', remove.join(','));
+  }
+  if (args.repo !== undefined) cmd.push('-R', args.repo);
+
+  const result = runArgv(cmd, cwd);
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'glab_issue_update_failed',
+      error: `glab issue update failed: ${result.stderr.trim() || result.stdout.trim()}`,
+    };
+  }
+
+  const url = result.stdout.trim().split('\n').pop()?.trim() || urlFromView || '';
+
+  return {
+    ok: true,
+    data: {
+      url,
+      number: num,
+      dry_run: false,
+      updated_fields,
+      ...(resolvedBody !== undefined ? { resolved_body: resolvedBody } : {}),
+    },
+  };
+}
+
+// See work-item-gitlab.ts for the rationale on this `void`.
+void execSync;
diff --git a/lib/work-item-section.test.ts b/lib/work-item-section.test.ts
new file mode 100644
index 0000000..c95ef58
--- /dev/null
+++ b/lib/work-item-section.test.ts
@@ -0,0 +1,95 @@
+import { describe, test, expect } from 'bun:test';
+import { spliceH2Section } from './work-item-section.ts';
+
+describe('spliceH2Section', () => {
+  test('replaces a middle H2 section while preserving siblings', () => {
+    const body = [
+      '## Summary',
+      'short summary',
+      '',
+      '## Dependencies',
+      '- old dep',
+      '',
+      '## Acceptance Criteria',
+      '- [ ] do the thing',
+    ].join('\n');
+
+    const result = spliceH2Section(body, 'Dependencies', '- new dep\n- another dep');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body).toContain('## Summary');
+    expect(result.body).toContain('short summary');
+    expect(result.body).toContain('## Dependencies');
+    expect(result.body).toContain('- new dep');
+    expect(result.body).toContain('- another dep');
+    expect(result.body).not.toContain('- old dep');
+    expect(result.body).toContain('## Acceptance Criteria');
+    expect(result.body).toContain('- [ ] do the thing');
+  });
+
+  test('replaces the LAST H2 section (no trailing H2 to anchor on)', () => {
+    const body = ['## Summary', 'just summary', '', '## Notes', 'old notes'].join('\n');
+
+    const result = spliceH2Section(body, 'Notes', 'new notes line');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body).toContain('new notes line');
+    expect(result.body).not.toContain('old notes');
+    expect(result.body).toContain('## Summary');
+  });
+
+  test('heading match is normalized (case + whitespace insensitive)', () => {
+    const body = '##  Acceptance Criteria  \n- old\n';
+    const result = spliceH2Section(body, 'acceptance criteria', '- new');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body).toContain('- new');
+    expect(result.body).not.toContain('- old');
+  });
+
+  test('accepts heading with leading ## prefix', () => {
+    const body = '## Foo\nold\n';
+    const result = spliceH2Section(body, '## Foo', 'new');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body).toContain('new');
+    expect(result.body).not.toContain('old');
+  });
+
+  test('returns error when section is missing', () => {
+    const body = '## Summary\nx\n';
+    const result = spliceH2Section(body, 'Dependencies', '- thing');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toContain('Dependencies');
+    expect(result.error).toContain('not found');
+  });
+
+  test('rejects empty heading', () => {
+    const body = '## Foo\nx\n';
+    const result = spliceH2Section(body, '   ', 'new');
+    expect(result.ok).toBe(false);
+  });
+
+  test('preserves preamble before first H2 verbatim', () => {
+    const body = ['<!-- some yaml -->', 'a paragraph', '', '## Body', 'old'].join('\n');
+    const result = spliceH2Section(body, 'Body', 'new');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body.startsWith('<!-- some yaml -->\na paragraph\n')).toBe(true);
+    expect(result.body).toContain('new');
+  });
+
+  test('does not change body when only one section matches and content is identical', () => {
+    const body = '## A\nfoo\n\n## B\nbar\n';
+    const result = spliceH2Section(body, 'B', 'bar');
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.body).toContain('## A');
+    expect(result.body).toContain('foo');
+    expect(result.body).toContain('## B');
+    expect(result.body).toContain('bar');
+  });
+});
diff --git a/lib/work-item-section.ts b/lib/work-item-section.ts
new file mode 100644
index 0000000..36865db
--- /dev/null
+++ b/lib/work-item-section.ts
@@ -0,0 +1,82 @@
+/**
+ * Body-section splicing for `work_item_update` (#287).
+ *
+ * Replace a single `## H2` section in an issue body, preserving all other
+ * sections verbatim — including any pre-H2 preamble, section ordering, and
+ * trailing whitespace style. Heading match is normalized via
+ * `normalizeHeading` from `lib/spec_parser.ts`, so `## Dependencies`,
+ * `## dependencies`, and `##  Dependencies  ` all match the same canonical key.
+ *
+ * Lives in `lib/` so the handler registry codegen (which scans `handlers/*.ts`)
+ * ignores it.
+ */
+
+import { normalizeHeading } from './spec_parser.js';
+
+export type SpliceResult =
+  | { ok: true; body: string }
+  | { ok: false; error: string };
+
+/**
+ * Replace the content of a single H2 section in `body`.
+ *
+ * - `heading` is the canonical heading text (e.g. `Dependencies` or
+ *   `## Dependencies`); leading `##` is stripped, then normalized.
+ * - `content` is the new section body (without the H2 header line). It is
+ *   inserted verbatim between the existing H2 line and the next H2 (or EOF).
+ *
+ * If the section is not found, returns `{ok: false, error}` so the caller can
+ * surface a typed envelope error rather than silently appending a new section.
+ *
+ * The H2 header line is preserved exactly as it appeared in the input (so we
+ * don't normalize `##  Dependencies` to `## Dependencies` on the way through).
+ */
+export function spliceH2Section(
+  body: string,
+  heading: string,
+  content: string,
+): SpliceResult {
+  const targetKey = normalizeHeading(heading.replace(/^#+\s*/, ''));
+  if (!targetKey) {
+    return { ok: false, error: 'heading must be non-empty' };
+  }
+
+  const lines = body.split('\n');
+  let startIdx = -1;
+  let endIdx = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^##\s+(.+?)\s*$/.exec(lines[i]);
+    if (m && normalizeHeading(m[1]) === targetKey) {
+      startIdx = i;
+      // Walk forward to the next H2 (or EOF) — that's the section's end.
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^##\s+/.test(lines[j])) {
+          endIdx = j;
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  if (startIdx === -1) {
+    return {
+      ok: false,
+      error: `section "## ${heading}" not found in body`,
+    };
+  }
+
+  // Build replacement: keep the H2 header line as-is, then a blank line, then
+  // the new content, then a trailing blank line if the original section had
+  // one. This preserves the most common formatting style without trying to be
+  // clever about exact whitespace.
+  const headerLine = lines[startIdx];
+  const trimmedContent = content.replace(/\n+$/, '');
+  const newSectionLines = ['', trimmedContent, ''];
+  const before = lines.slice(0, startIdx);
+  const after = lines.slice(endIdx);
+
+  const merged = [...before, headerLine, ...newSectionLines, ...after];
+  return { ok: true, body: merged.join('\n').replace(/\n{3,}/g, '\n\n') };
+}
diff --git a/tests/work_item_update.test.ts b/tests/work_item_update.test.ts
new file mode 100644
index 0000000..02b08a8
--- /dev/null
+++ b/tests/work_item_update.test.ts
@@ -0,0 +1,203 @@
+import { describe, test, expect, mock, beforeEach } from 'bun:test';
+
+// Integration coverage for the work_item_update handler (#287).
+//
+// Mirrors tests/work_item.test.ts: argv-shape assertions live in the colocated
+// adapter tests; this file owns:
+//   - schema validation
+//   - handler envelope shape
+//   - cross-platform dispatch via detect-platform
+//   - dry-run preview path
+//
+// Per `lesson_origin_ops_pitfalls.md` the work-item-update adapters call
+// runArgv which shell-escapes its argv. The unquote shim strips that quoting
+// so test match-keys can stay as plain `gh issue edit` strings.
+
+interface MockExecError extends Error {
+  stderr?: string;
+  stdout?: string;
+  status?: number;
+}
+
+let execRegistry: Array<{ match: string; respond: string | (() => string) }> = [];
+let execCalls: string[] = [];
+
+function unquote(cmd: string): string {
+  return cmd.replace(/'([^']*)'/g, '$1');
+}
+
+const mockExecSync = mock((cmd: string, _opts?: unknown) => {
+  execCalls.push(cmd);
+  const flat = unquote(cmd);
+  for (const { match, respond } of execRegistry) {
+    if (cmd.includes(match) || flat.includes(match)) {
+      return typeof respond === 'function' ? respond() : respond;
+    }
+  }
+  throw new Error(`Unexpected exec: ${cmd}`);
+});
+
+mock.module('child_process', () => ({ execSync: mockExecSync }));
+
+const { default: handler } = await import('../handlers/work_item_update.ts');
+
+function parseResult(content: Array<{ type: string; text: string }>) {
+  return JSON.parse(content[0].text) as Record<string, unknown>;
+}
+
+function onExec(match: string, respond: string | (() => string)): void {
+  execRegistry.push({ match, respond });
+}
+
+beforeEach(() => {
+  execRegistry = [];
+  execCalls = [];
+});
+
+describe('work_item_update handler', () => {
+  test('handler exports valid HandlerDef shape', () => {
+    expect(handler.name).toBe('work_item_update');
+    expect(typeof handler.execute).toBe('function');
+  });
+
+  // ---- schema validation ----
+
+  test('schema rejects bad issue_ref', async () => {
+    const result = await handler.execute({
+      issue_ref: 'totally not a ref',
+      patch: { title: 'x' },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(false);
+    expect(String(data.error)).toMatch(/issue_ref/);
+  });
+
+  test('schema rejects empty patch object', async () => {
+    const result = await handler.execute({ issue_ref: '#1', patch: {} });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(false);
+    expect(String(data.error)).toMatch(/patch/);
+  });
+
+  test('schema rejects body + body_section together', async () => {
+    const result = await handler.execute({
+      issue_ref: '#1',
+      patch: { body: 'x', body_section: { heading: 'A', content: 'y' } },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(false);
+    expect(String(data.error)).toMatch(/mutually exclusive/i);
+  });
+
+  // ---- github dispatch ----
+
+  test('github — title patch dispatches to gh issue edit', async () => {
+    onExec('git remote get-url origin', 'https://github.com/org/repo.git');
+    onExec('gh issue edit', 'https://github.com/org/repo/issues/42\n');
+
+    const result = await handler.execute({
+      issue_ref: '#42',
+      patch: { title: 'Renamed' },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(true);
+    expect(data.number).toBe(42);
+    expect(data.dry_run).toBe(false);
+
+    const call = execCalls.find((c) => unquote(c).includes('gh issue edit')) ?? '';
+    expect(call).toContain("'--title' 'Renamed'");
+  });
+
+  test('github — body_section patch reads body, splices, sends full --body', async () => {
+    onExec('git remote get-url origin', 'https://github.com/org/repo.git');
+    onExec(
+      'gh issue view',
+      JSON.stringify({
+        number: 5,
+        url: 'https://github.com/org/repo/issues/5',
+        body: '## Summary\nx\n\n## Dependencies\n- old\n',
+        labels: [],
+        assignees: [],
+      }),
+    );
+    onExec('gh issue edit', 'https://github.com/org/repo/issues/5\n');
+
+    const result = await handler.execute({
+      issue_ref: '#5',
+      patch: { body_section: { heading: 'Dependencies', content: '- new' } },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(true);
+    expect(data.resolved_body).toContain('- new');
+    expect(data.resolved_body).not.toContain('- old');
+    // AC: section patching preserves other H2 sections unmodified
+    expect(data.resolved_body).toContain('## Summary');
+
+    const editCall = execCalls.find((c) => unquote(c).includes('gh issue edit')) ?? '';
+    expect(editCall).toContain('--body');
+  });
+
+  test('github — dry_run:true returns preview without invoking gh issue edit', async () => {
+    onExec('git remote get-url origin', 'https://github.com/org/repo.git');
+
+    const result = await handler.execute({
+      issue_ref: '#42',
+      patch: { title: 'Preview' },
+      dry_run: true,
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(true);
+    expect(data.dry_run).toBe(true);
+    expect(execCalls.find((c) => unquote(c).includes('gh issue edit'))).toBeUndefined();
+  });
+
+  // ---- gitlab dispatch ----
+
+  test('gitlab — title patch dispatches to glab issue update', async () => {
+    onExec('git remote get-url origin', 'https://gitlab.com/org/repo.git');
+    onExec('glab issue update', 'https://gitlab.com/org/repo/-/issues/42\n');
+
+    const result = await handler.execute({
+      issue_ref: '#42',
+      patch: { title: 'Renamed' },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(true);
+
+    const call = execCalls.find((c) => unquote(c).includes('glab issue update')) ?? '';
+    expect(call).toContain("'--title' 'Renamed'");
+  });
+
+  test('gitlab — milestone patch returns platform_unsupported', async () => {
+    onExec('git remote get-url origin', 'https://gitlab.com/org/repo.git');
+
+    const result = await handler.execute({
+      issue_ref: '#1',
+      patch: { milestone: 'v1.0' },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(false);
+    expect(data.platform_unsupported).toBe(true);
+    expect(String(data.error).toLowerCase()).toContain('milestone');
+  });
+
+  // ---- error surface ----
+
+  test('github — surfaces ok:false on subprocess failure', async () => {
+    onExec('git remote get-url origin', 'https://github.com/org/repo.git');
+    onExec('gh issue edit', () => {
+      const err: MockExecError = new Error('not authenticated') as MockExecError;
+      err.stderr = 'gh: not authenticated';
+      err.status = 1;
+      throw err;
+    });
+
+    const result = await handler.execute({
+      issue_ref: '#1',
+      patch: { title: 'x' },
+    });
+    const data = parseResult(result.content);
+    expect(data.ok).toBe(false);
+    expect(String(data.error)).toContain('gh issue edit failed');
+  });
+});