feat: add gh board-row upsert

scripts/gh-cli-issue-guard-contract-test.ts

@@ -109,6 +109,40 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque
   ].join("\n");
   let boardIssueBody = boardIssueBodyInitial;
   let boardIssueUpdatedAt = "2026-05-20T01:00:00Z";
+  const upsertBoardIssueBodyInitial = [
+    "# Upsert Board",
+    "",
+    "## 看板（OPEN）",
+    "",
+    "| Issue | GitHub 状态 | Category | Branch | Summary | 验收状态 | 相关 Code Queue 任务 | 当前关注点 | 进度 |",
+    "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    "| #70 | OPEN | cli | master | existing summary | pass | cq-70 | existing focus | doing |",
+    "| #72 | OPEN | cli | master | duplicate open | pass | cq-72 | duplicate open | doing |",
+    "| #79 | OPEN | defect | master | bad row | pass | cq-79 | missing progress |",
+    "",
+    "## 看板（CLOSED）",
+    "",
+    "| Issue | GitHub 状态 | Category | Branch | Summary | 验收状态 | 相关 Code Queue 任务 | 当前关注点 | 进度 |",
+    "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
+    "| #71 | CLOSED | ops | master | closed summary | pass | — | archived focus | done |",
+    "| #72 | CLOSED | ops | master | duplicate closed | pass | — | duplicate closed | done |",
+    "",
+    "## 更新 2026-05-21 10:00 北京时间",
+    "",
+    "- 表后的更新段落必须保留。",
+    "",
+  ].join("\n");
+  let upsertBoardIssueBody = upsertBoardIssueBodyInitial;
+  let upsertBoardIssueUpdatedAt = "2026-05-20T01:30:00Z";
+  const upsertBoardIssue = {
+    ...issue,
+    id: 2062,
+    number: 62,
+    title: "Upsert board fixture",
+    body: upsertBoardIssueBody,
+    html_url: "https://github.com/pikasTech/unidesk/issues/62",
+    updated_at: upsertBoardIssueUpdatedAt,
+  };
   const legacyBoardIssue = {
     ...issue,
     id: 2600,
@@ -413,6 +447,10 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque
       sendJson(res, 200, legacyBoardIssue);
       return;
     }
+    if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues/62") {
+      sendJson(res, 200, { ...upsertBoardIssue, body: upsertBoardIssueBody, updated_at: upsertBoardIssueUpdatedAt });
+      return;
+    }
     if (req.method === "GET" && req.url === "/repos/pikasTech/unidesk/issues/20/comments?per_page=100") {
       sendJson(res, 200, comments);
       return;
@@ -466,6 +504,13 @@ async function startMockGitHub(): Promise<{ baseUrl: string; requests: MockReque
       sendJson(res, 200, { ...issue, body: boardIssueBody, updated_at: boardIssueUpdatedAt });
       return;
     }
+    if (req.method === "PATCH" && req.url === "/repos/pikasTech/unidesk/issues/62") {
+      const parsed = JSON.parse(body) as JsonRecord;
+      upsertBoardIssueBody = String(parsed.body ?? upsertBoardIssueBody);
+      upsertBoardIssueUpdatedAt = "2026-05-20T01:35:00Z";
+      sendJson(res, 200, { ...upsertBoardIssue, body: upsertBoardIssueBody, updated_at: upsertBoardIssueUpdatedAt });
+      return;
+    }
     if (req.method === "POST" && req.url === "/repos/pikasTech/unidesk/issues/20/comments") {
       const parsed = JSON.parse(body) as JsonRecord;
       sendJson(res, 201, { id: 9001, body: String(parsed.body ?? ""), html_url: "https://github.com/pikasTech/unidesk/issues/20#issuecomment-9001", user: { login: "tester" }, created_at: "2026-05-20T06:00:00Z", updated_at: "2026-05-20T06:00:00Z" });
@@ -528,11 +573,13 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> {
   assertCondition(usage.some((line) => line.includes("gh issue board-row list")), "gh help should list board-row list", { usage });
   assertCondition(usage.some((line) => line.includes("gh issue board-row update")), "gh help should list board-row update", { usage });
   assertCondition(usage.some((line) => line.includes("gh issue board-row add")), "gh help should list board-row add", { usage });
+  assertCondition(usage.some((line) => line.includes("gh issue board-row upsert")), "gh help should list board-row upsert", { usage });
   assertCondition(usage.some((line) => line.includes("gh issue board-row move")), "gh help should list board-row move", { usage });
   assertCondition(usage.some((line) => line.includes("gh issue board-row delete")), "gh help should list board-row delete", { usage });
   assertCondition(notes.some((line) => line.includes("canonical read path")), "gh help should state issue read is canonical", { notes });
   assertCondition(notes.some((line) => line.includes("compatibility alias")), "gh help should state issue view is alias", { notes });
   assertCondition(notes.some((line) => line.includes("board-row update changes one table cell")), "gh help should describe board-row update safety", { notes });
+  assertCondition(notes.some((line) => line.includes("board-row upsert updates an existing row")), "gh help should describe board-row upsert safety", { notes });
   assertCondition(notes.some((line) => line.includes("board-row add/move/delete are row-scoped")), "gh help should describe board-row row mutation safety", { notes });
 
   const mock = await startMockGitHub();
@@ -658,6 +705,176 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> {
     assertCondition(Array.isArray(boardRowGetRow.cells) && boardRowGetRow.cells[1] === "OPEN", "board-row get should expose the GitHub status column", boardRowGetRow);
     assertCondition(boardRowGetFields.branch === "master" && boardRowGetFields.status === "pass" && boardRowGetFields.validation === "pass" && boardRowGetFields.tasks === "cq-35" && String(boardRowGetFields.focus ?? "").includes("当前关注点"), "board-row get should expose canonical field aliases", boardRowGetFields);
 
+    const boardRowUpsertUpdateRequestCountBefore = mock.requests.length;
+    const boardRowUpsertUpdate = await runCli([
+      "gh", "issue", "board-row", "upsert", "70",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--summary", "中文 `code` [#20](https://github.com/pikasTech/unidesk/issues/20) A | B\nsecond line",
+      "--focus", "焦点 A | B\n下一行",
+      "--validation", "manual pass",
+      "--progress", "reviewing",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertUpdate.status === 0, "board-row upsert existing row should dry-run update", boardRowUpsertUpdate.json ?? { stdout: boardRowUpsertUpdate.stdout, stderr: boardRowUpsertUpdate.stderr });
+    const boardRowUpsertUpdateData = dataOf(boardRowUpsertUpdate.json ?? {});
+    assertCondition(boardRowUpsertUpdateData.command === "issue board-row upsert" && boardRowUpsertUpdateData.operation === "update" && boardRowUpsertUpdateData.dryRun === true && boardRowUpsertUpdateData.planned === true, "upsert existing row should report update operation", boardRowUpsertUpdateData);
+    const boardRowUpsertUpdatePlan = boardRowUpsertUpdateData.upsert as JsonRecord;
+    assertCondition(boardRowUpsertUpdatePlan.operation === "update" && boardRowUpsertUpdatePlan.section === "open", "upsert update plan should stay in existing section", boardRowUpsertUpdatePlan);
+    assertCondition(boardRowUpsertUpdatePlan.oldRow === "| #70 | OPEN | cli | master | existing summary | pass | cq-70 | existing focus | doing |", "upsert update should expose old row", boardRowUpsertUpdatePlan);
+    assertCondition(boardRowUpsertUpdatePlan.newRow === "| #70 | OPEN | cli | master | 中文 `code` [#20](https://github.com/pikasTech/unidesk/issues/20) A \\| B second line | manual pass | cq-70 | 焦点 A \\| B 下一行 | reviewing |", "upsert update should escape pipes, preserve backticks/link text, and fold real newlines", boardRowUpsertUpdatePlan);
+    const boardRowUpsertUpdateSafety = boardRowUpsertUpdateData.bodyOnlySafety as JsonRecord;
+    const boardRowUpsertUpdateNewBody = boardRowUpsertUpdateSafety.newBody as JsonRecord;
+    assertCondition(boardRowUpsertUpdateNewBody.containsLiteralBackslashN === false && boardRowUpsertUpdateNewBody.containsBackticks === true && boardRowUpsertUpdateNewBody.containsMarkdownTable === true, "upsert update should preserve markdown safety signals", boardRowUpsertUpdateNewBody);
+    const boardRowUpsertUpdateWriteCount = mock.requests.slice(boardRowUpsertUpdateRequestCountBefore).filter((request) => request.method === "PATCH").length;
+    assertCondition(boardRowUpsertUpdateWriteCount === 0, "board-row upsert update dry-run must not PATCH GitHub", { requests: mock.requests.slice(boardRowUpsertUpdateRequestCountBefore) });
+
+    const boardRowUpsertAddRequestCountBefore = mock.requests.length;
+    const boardRowUpsertAdd = await runCli([
+      "gh", "issue", "board-row", "upsert", "73",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--category", "cli",
+      "--branch", "master",
+      "--tasks", "cq-73",
+      "--summary", "新增中文 `code` [#20](https://github.com/pikasTech/unidesk/issues/20) A | B\n真实换行",
+      "--focus", "关注 | 重点\nnext",
+      "--validation", "pending",
+      "--progress", "queued",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertAdd.status === 0, "board-row upsert missing row should dry-run add", boardRowUpsertAdd.json ?? { stdout: boardRowUpsertAdd.stdout, stderr: boardRowUpsertAdd.stderr });
+    const boardRowUpsertAddData = dataOf(boardRowUpsertAdd.json ?? {});
+    assertCondition(boardRowUpsertAddData.command === "issue board-row upsert" && boardRowUpsertAddData.operation === "add" && boardRowUpsertAddData.dryRun === true && boardRowUpsertAddData.planned === true, "upsert missing row should report add operation", boardRowUpsertAddData);
+    const boardRowUpsertAddPlan = boardRowUpsertAddData.upsert as JsonRecord;
+    assertCondition(boardRowUpsertAddPlan.operation === "add" && boardRowUpsertAddPlan.section === "open" && Number(boardRowUpsertAddPlan.insertAfterLine ?? 0) > 0, "upsert add should expose insertion plan", boardRowUpsertAddPlan);
+    assertCondition(boardRowUpsertAddPlan.newRow === "| #73 | OPEN | cli | master | 新增中文 `code` [#20](https://github.com/pikasTech/unidesk/issues/20) A \\| B 真实换行 | pending | cq-73 | 关注 \\| 重点 next | queued |", "upsert add should generate a full escaped row", boardRowUpsertAddPlan);
+    const boardRowUpsertAddNewBody = ((boardRowUpsertAddData.bodyOnlySafety as JsonRecord).newBody as JsonRecord);
+    assertCondition(boardRowUpsertAddNewBody.containsLiteralBackslashN === false && boardRowUpsertAddNewBody.containsBackticks === true, "upsert add should not introduce literal backslash-n", boardRowUpsertAddNewBody);
+    const boardRowUpsertAddWriteCount = mock.requests.slice(boardRowUpsertAddRequestCountBefore).filter((request) => request.method === "PATCH").length;
+    assertCondition(boardRowUpsertAddWriteCount === 0, "board-row upsert add dry-run must not PATCH GitHub", { requests: mock.requests.slice(boardRowUpsertAddRequestCountBefore) });
+
+    const boardRowUpsertNoGuardRequestCountBefore = mock.requests.length;
+    const boardRowUpsertNoGuard = await runCli([
+      "gh", "issue", "board-row", "upsert", "74",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--category", "cli",
+      "--branch", "master",
+      "--tasks", "cq-74",
+      "--summary", "formal write omitted guard",
+      "--focus", "focus",
+      "--validation", "pending",
+      "--progress", "queued",
+    ], env);
+    assertCondition(boardRowUpsertNoGuard.status === 0, "board-row upsert without guard should stay on the dry-run path", boardRowUpsertNoGuard.json ?? { stdout: boardRowUpsertNoGuard.stdout, stderr: boardRowUpsertNoGuard.stderr });
+    const boardRowUpsertNoGuardData = dataOf(boardRowUpsertNoGuard.json ?? {});
+    assertCondition(boardRowUpsertNoGuardData.dryRun === true && boardRowUpsertNoGuardData.planned === true && boardRowUpsertNoGuardData.operation === "add", "upsert without guard should not PATCH GitHub", boardRowUpsertNoGuardData);
+    const boardRowUpsertNoGuardWriteCount = mock.requests.slice(boardRowUpsertNoGuardRequestCountBefore).filter((request) => request.method === "PATCH").length;
+    assertCondition(boardRowUpsertNoGuardWriteCount === 0, "board-row upsert without guard must not PATCH GitHub", { requests: mock.requests.slice(boardRowUpsertNoGuardRequestCountBefore) });
+
+    const boardRowUpsertListBeforeWrite = await runCli(["gh", "issue", "board-row", "list", "--repo", "pikasTech/unidesk", "--board-issue", "62", "--state", "all"], env);
+    assertCondition(boardRowUpsertListBeforeWrite.status === 0, "upsert board list before guarded write should succeed", boardRowUpsertListBeforeWrite.json ?? { stdout: boardRowUpsertListBeforeWrite.stdout, stderr: boardRowUpsertListBeforeWrite.stderr });
+    const boardRowUpsertBoardSha = String((dataOf(boardRowUpsertListBeforeWrite.json ?? {}).boardIssue as JsonRecord).bodySha ?? "");
+    const boardRowUpsertWriteRequestCountBefore = mock.requests.length;
+    const boardRowUpsertWrite = await runCli([
+      "gh", "issue", "board-row", "upsert", "73",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--category", "cli",
+      "--branch", "master",
+      "--tasks", "cq-73",
+      "--summary", "guarded add keeps table trailer",
+      "--focus", "focus",
+      "--validation", "pending",
+      "--progress", "queued",
+      "--expect-body-sha", boardRowUpsertBoardSha,
+    ], env);
+    assertCondition(boardRowUpsertWrite.status === 0, "board-row upsert with expect body sha should PATCH", boardRowUpsertWrite.json ?? { stdout: boardRowUpsertWrite.stdout, stderr: boardRowUpsertWrite.stderr });
+    const boardRowUpsertWriteData = dataOf(boardRowUpsertWrite.json ?? {});
+    assertCondition(boardRowUpsertWriteData.dryRun === false && boardRowUpsertWriteData.rest === true && boardRowUpsertWriteData.operation === "add", "upsert guarded write should report real add", boardRowUpsertWriteData);
+    const boardRowUpsertWriteRequests = mock.requests.slice(boardRowUpsertWriteRequestCountBefore).filter((request) => request.method === "PATCH" && request.url === "/repos/pikasTech/unidesk/issues/62");
+    assertCondition(boardRowUpsertWriteRequests.length === 1, "board-row upsert should send exactly one PATCH", { requests: mock.requests.slice(boardRowUpsertWriteRequestCountBefore) });
+    const boardRowUpsertWritePayload = JSON.parse(boardRowUpsertWriteRequests[0]?.body ?? "{}") as JsonRecord;
+    const boardRowUpsertWrittenBody = String(boardRowUpsertWritePayload.body ?? "");
+    assertCondition(boardRowUpsertWrittenBody.includes("| #73 | OPEN | cli | master | guarded add keeps table trailer | pending | cq-73 | focus | queued |"), "upsert write payload should include generated row", boardRowUpsertWritePayload);
+    assertCondition(boardRowUpsertWrittenBody.includes("## 看板（CLOSED）") && boardRowUpsertWrittenBody.includes("## 更新 2026-05-21 10:00 北京时间") && boardRowUpsertWrittenBody.includes("- 表后的更新段落必须保留。"), "upsert write should preserve CLOSED table and post-table update section", boardRowUpsertWritePayload);
+
+    const boardRowUpsertStale = await runCli([
+      "gh", "issue", "board-row", "upsert", "76",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--category", "cli",
+      "--branch", "master",
+      "--tasks", "cq-76",
+      "--summary", "stale guard must fail",
+      "--focus", "focus",
+      "--validation", "pending",
+      "--progress", "queued",
+      "--expect-body-sha", boardRowUpsertBoardSha,
+    ], env);
+    assertCondition(boardRowUpsertStale.status !== 0, "stale board-row upsert should fail structurally", boardRowUpsertStale.json ?? { stdout: boardRowUpsertStale.stdout, stderr: boardRowUpsertStale.stderr });
+    const boardRowUpsertStaleData = failedDataOf(boardRowUpsertStale.json ?? {});
+    assertCondition(boardRowUpsertStaleData.degradedReason === "validation-failed" && boardRowUpsertStaleData.command === "issue board-row upsert", "stale board-row upsert should be validation-failed", boardRowUpsertStaleData);
+
+    const boardRowUpsertDuplicate = await runCli([
+      "gh", "issue", "board-row", "upsert", "72",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--focus", "duplicate should fail",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertDuplicate.status !== 0, "duplicate board-row upsert should fail structurally", boardRowUpsertDuplicate.json ?? { stdout: boardRowUpsertDuplicate.stdout, stderr: boardRowUpsertDuplicate.stderr });
+    const boardRowUpsertDuplicateData = failedDataOf(boardRowUpsertDuplicate.json ?? {});
+    assertCondition(String((boardRowUpsertDuplicateData.details as JsonRecord).message ?? "").includes("ambiguous"), "duplicate upsert should report ambiguous row", boardRowUpsertDuplicateData);
+
+    const boardRowUpsertSectionConflict = await runCli([
+      "gh", "issue", "board-row", "upsert", "70",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "closed",
+      "--focus", "migration belongs to move",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertSectionConflict.status !== 0, "upsert section conflict should fail structurally", boardRowUpsertSectionConflict.json ?? { stdout: boardRowUpsertSectionConflict.stdout, stderr: boardRowUpsertSectionConflict.stderr });
+    const boardRowUpsertSectionConflictData = failedDataOf(boardRowUpsertSectionConflict.json ?? {});
+    assertCondition(String((boardRowUpsertSectionConflictData.details as JsonRecord).message ?? "").includes("use gh issue board-row move"), "upsert section conflict should point to move", boardRowUpsertSectionConflictData);
+
+    const boardRowUpsertMissingField = await runCli([
+      "gh", "issue", "board-row", "upsert", "75",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--section", "open",
+      "--category", "cli",
+      "--branch", "master",
+      "--tasks", "cq-75",
+      "--summary", "missing progress field",
+      "--focus", "focus",
+      "--validation", "pending",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertMissingField.status !== 0, "upsert add missing required generated cell should fail", boardRowUpsertMissingField.json ?? { stdout: boardRowUpsertMissingField.stdout, stderr: boardRowUpsertMissingField.stderr });
+    const boardRowUpsertMissingFieldData = failedDataOf(boardRowUpsertMissingField.json ?? {});
+    const boardRowUpsertMissingFieldDetails = boardRowUpsertMissingFieldData.details as JsonRecord;
+    assertCondition(String(boardRowUpsertMissingFieldDetails.message ?? "").includes("requires values") && Array.isArray(boardRowUpsertMissingFieldData.missingFields) && (boardRowUpsertMissingFieldData.missingFields as unknown[]).includes("progress"), "upsert missing field should be structured", boardRowUpsertMissingFieldData);
+
+    const boardRowUpsertColumnMismatch = await runCli([
+      "gh", "issue", "board-row", "upsert", "79",
+      "--repo", "pikasTech/unidesk",
+      "--board-issue", "62",
+      "--focus", "bad existing row",
+      "--dry-run",
+    ], env);
+    assertCondition(boardRowUpsertColumnMismatch.status !== 0, "upsert existing row with column mismatch should fail", boardRowUpsertColumnMismatch.json ?? { stdout: boardRowUpsertColumnMismatch.stdout, stderr: boardRowUpsertColumnMismatch.stderr });
+    const boardRowUpsertColumnMismatchData = failedDataOf(boardRowUpsertColumnMismatch.json ?? {});
+    assertCondition(String((boardRowUpsertColumnMismatchData.details as JsonRecord).message ?? "").includes("column count"), "upsert column mismatch should be structured", boardRowUpsertColumnMismatchData);
+
     const boardRowDryRunRequestCountBefore = mock.requests.length;
     const boardRowDryRun = await runCli(["gh", "issue", "board-row", "update", "35", "--repo", "pikasTech/unidesk", "--board-issue", "20", "--field", "focus", "--value", "复核 A | B\nsecond line"], env);
     assertCondition(boardRowDryRun.status === 0, "board-row update should default to dry-run without concurrency expectation", boardRowDryRun.json ?? { stdout: boardRowDryRun.stdout, stderr: boardRowDryRun.stderr });
@@ -1078,6 +1295,7 @@ export async function runGhCliIssueGuardContract(): Promise<JsonRecord> {
         "issue cleanup-plan remains dry-run with body/comment cleanup suggestions",
         "issue board-audit reports missing open rows, closed/open section mismatches, missing closed rows, meta/brief-index ignores, and row validation warnings without writes",
         "issue board-row list/get expose parsed #20 rows without writes",
+        "issue board-row upsert updates existing rows, adds missing rows, reports operation, preserves table trailers, rejects ambiguous rows, blocks stale body SHA writes, and stays dry-run without concurrency guards",
         "issue board-row add/delete without guard stay on dry-run and do not PATCH",
         "issue board-row update defaults to dry-run, reports old/new row, body SHA, guard result, and does not introduce literal backslash-n",
         "issue board-row update rejects literal backslash-n cell values",

scripts/src/gh.ts

@@ -16,6 +16,7 @@ const COMMANDER_BRIEF_TARGET_ISSUE = 24;
 const DEFAULT_BOARD_KNOWN_META_ISSUES = [CODE_QUEUE_BOARD_TARGET_ISSUE, COMMANDER_BRIEF_TARGET_ISSUE] as const;
 const BOARD_AUDIT_REQUIRED_COLUMNS = ["branch", "acceptance", "relatedTask", "progress"] as const;
 const BOARD_ROW_FIELDS = ["progress", "status", "validation", "branch", "tasks", "focus"] as const;
+const BOARD_ROW_UPSERT_TEXT_FIELDS = ["category", "branch", "tasks", "summary", "focus", "validation", "progress"] as const;
 const ISSUE_VIEW_JSON_FIELDS = ["body", "title", "state", "comments", "number", "url", "author", "createdAt", "updatedAt"] as const;
 const ISSUE_LIST_JSON_FIELDS = ["number", "title", "state", "url", "updatedAt", "createdAt", "author", "labels"] as const;
 const PR_JSON_FIELDS = ["body", "title", "state", "number", "url", "author", "head", "base", "draft", "createdAt", "updatedAt"] as const;
@@ -56,8 +57,10 @@ type EscapeBodyKind = "issue-body" | "comment-body";
 type CleanupSuggestionAction = "rewrite-issue-body-with-body-file" | "review-comment-manually" | "review-body-length" | "no-cleanup-needed";
 type BoardSectionKind = "open" | "closed";
 type BoardRequiredColumn = typeof BOARD_AUDIT_REQUIRED_COLUMNS[number];
-type BoardColumnKind = BoardRequiredColumn | "focus" | "githubStatus";
+type BoardColumnKind = BoardRequiredColumn | "focus" | "githubStatus" | "category" | "summary";
 type BoardRowField = typeof BOARD_ROW_FIELDS[number];
+type BoardRowUpsertTextField = typeof BOARD_ROW_UPSERT_TEXT_FIELDS[number];
+type BoardRowUpsertField = BoardRowUpsertTextField | "status";
 type BoardIgnoreReason = "known-meta" | "ignored" | "brief-index-managed";
 
 type GitHubDegradedReason =
@@ -255,6 +258,17 @@ interface BoardRowMutationPlanResult {
   newBody: string;
 }
 
+interface BoardRowUpsertValues {
+  category?: string;
+  branch?: string;
+  tasks?: string;
+  summary?: string;
+  focus?: string;
+  validation?: string;
+  progress?: string;
+  status?: BoardGithubStatus;
+}
+
 interface GitHubCommandResult {
   ok: boolean;
   repo: string;
@@ -305,6 +319,7 @@ interface GitHubOptions {
   boardSection?: BoardMutationSection;
   boardMoveTo?: BoardMutationSection;
   boardGithubStatus?: BoardGithubStatus;
+  boardRowUpsertValues: BoardRowUpsertValues;
 }
 
 interface IssueProfileValidationContext {
@@ -548,8 +563,21 @@ function parseBoardRowField(args: string[]): BoardRowField | undefined {
   return validateEnumValue("--field", raw, BOARD_ROW_FIELDS);
 }
 
+function parseBoardRowUpsertValues(args: string[]): BoardRowUpsertValues {
+  return {
+    category: optionValue(args, "--category"),
+    branch: optionValue(args, "--branch"),
+    tasks: optionValue(args, "--tasks"),
+    summary: optionValue(args, "--summary"),
+    focus: optionValue(args, "--focus"),
+    validation: optionValue(args, "--validation"),
+    progress: optionValue(args, "--progress"),
+    status: parseBoardGithubStatus(args),
+  };
+}
+
 function validateKnownOptions(args: string[]): void {
-  const valueOptions = new Set(["--repo", "--limit", "--board-issue", "--known-meta-issue", "--ignore-issue", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label", "--field", "--value", "--section", "--to", "--status", "--row-file"]);
+  const valueOptions = new Set(["--repo", "--limit", "--board-issue", "--known-meta-issue", "--ignore-issue", "--title", "--body-file", "--body", "--base", "--head", "--json", "--state", "--mode", "--expect-updated-at", "--expect-body-sha", "--body-profile", "--label", "--field", "--value", "--section", "--to", "--status", "--row-file", "--category", "--branch", "--tasks", "--summary", "--focus", "--validation", "--progress"]);
   const flagOptions = new Set(["--dry-run", "--draft", "--notify-claudeqq-brief-diff", "--allow-short-body"]);
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -597,6 +625,7 @@ function parseOptions(args: string[]): GitHubOptions {
     boardSection: parseBoardMutationSection(args, "--section"),
     boardMoveTo: parseBoardMutationSection(args, "--to"),
     boardGithubStatus: parseBoardGithubStatus(args),
+    boardRowUpsertValues: parseBoardRowUpsertValues(args),
   };
 }
 
@@ -1312,10 +1341,12 @@ function normalizeBoardHeader(header: string): string {
 
 function boardHeaderColumnKind(header: string): BoardColumnKind | null {
   const normalized = normalizeBoardHeader(header);
+  if (["category", "类别", "分类", "类型", "任务类型"].includes(normalized)) return "category";
   if (["branch", "分支", "目标分支", "工作分支"].includes(normalized)) return "branch";
   if (["acceptance", "验收", "验收状态", "验收结果", "验收标准"].includes(normalized)) return "acceptance";
   if (["relatedtask", "task", "codequeue", "codequeuetask", "相关任务", "任务", "codequeue任务", "cq任务", "相关codequeue任务", "相关codequeuetask"].includes(normalized)) return "relatedTask";
   if (["githubstatus", "githubstate", "github状态", "githubissue状态", "issuestate", "issue状态", "issuegithub状态", "开闭状态", "openclosed", "openclosed状态"].includes(normalized)) return "githubStatus";
+  if (["summary", "摘要", "概述", "任务摘要", "任务概述", "标题"].includes(normalized)) return "summary";
   if (["focus", "currentfocus", "关注点", "当前关注点", "当前focus"].includes(normalized)) return "focus";
   if (["progress", "进度", "状态", "当前进度"].includes(normalized)) return "progress";
   return null;
@@ -1602,6 +1633,25 @@ function boardRowFieldValues(section: BoardTableSection, row: BoardTableRow): Re
   };
 }
 
+function boardRowUpsertFieldValues(section: BoardTableSection, row: BoardTableRow): Record<BoardRowUpsertField, string | null> {
+  const columnMap = boardColumnIndexMap(section.headers);
+  const valueFor = (kind: BoardColumnKind): string | null => {
+    const index = columnMap.get(kind);
+    return index === undefined ? null : row.cells[index] ?? "";
+  };
+  const acceptance = valueFor("acceptance");
+  return {
+    category: valueFor("category"),
+    branch: valueFor("branch"),
+    tasks: valueFor("relatedTask"),
+    summary: valueFor("summary"),
+    focus: valueFor("focus"),
+    validation: acceptance,
+    progress: valueFor("progress"),
+    status: valueFor("githubStatus"),
+  };
+}
+
 function boardRowSummary(section: BoardTableSection, row: BoardTableRow): Record<string, unknown> {
   return {
     issueNumber: row.issueNumber,
@@ -1617,6 +1667,13 @@ function boardRowSummary(section: BoardTableSection, row: BoardTableRow): Record
   };
 }
 
+function boardRowsExactMatch(
+  sections: BoardTableSection[],
+  issueNumber: number,
+): Array<{ section: BoardTableSection; row: BoardTableRow }> {
+  return boardRowsForState(sections, "all").filter(({ row }) => row.issueNumber === issueNumber);
+}
+
 function boardRowsForState(sections: BoardTableSection[], state: IssueListState): Array<{ section: BoardTableSection; row: BoardTableRow }> {
   return sections
     .filter((section) => state === "all" || section.kind === state)
@@ -1922,6 +1979,456 @@ function boardRowStatusConsistency(
   return { ok: true, githubStatusColumnIndex, actualStatus, expectedStatus };
 }
 
+function boardRowUpsertValueEntries(values: BoardRowUpsertValues): Array<{ field: BoardRowUpsertField; value: string }> {
+  const entries: Array<{ field: BoardRowUpsertField; value: string }> = [];
+  for (const field of BOARD_ROW_UPSERT_TEXT_FIELDS) {
+    const value = values[field];
+    if (value !== undefined) entries.push({ field, value });
+  }
+  if (values.status !== undefined) entries.push({ field: "status", value: values.status });
+  return entries;
+}
+
+function boardColumnKindForUpsertField(field: BoardRowUpsertField): BoardColumnKind {
+  if (field === "category") return "category";
+  if (field === "branch") return "branch";
+  if (field === "tasks") return "relatedTask";
+  if (field === "summary") return "summary";
+  if (field === "focus") return "focus";
+  if (field === "validation") return "acceptance";
+  if (field === "status") return "githubStatus";
+  return "progress";
+}
+
+function renderBoardIssueCell(repo: string, issueNumber: number, summary: string | undefined): string {
+  const trimmed = (summary ?? "").trim();
+  if (trimmed.length === 0) return `#${issueNumber}`;
+  const targetHref = `https://github.com/${repo}/issues/${issueNumber}`;
+  const firstMarkdownIssue = /^\s*\[[^\]]*\]\(([^)]*)\)/u.exec(trimmed)?.[1] ?? "";
+  if (new RegExp(`/issues/${issueNumber}(?:\\b|$)`, "u").test(firstMarkdownIssue)) return trimmed;
+  return `[#${issueNumber}](${targetHref}) ${trimmed}`;
+}
+
+function boardRowUpsertTargetColumn(
+  repo: string,
+  commandName: string,
+  section: BoardTableSection,
+  issueNumber: number,
+  field: BoardRowUpsertField,
+): { ok: true; columnIndex: number; targetColumn: BoardColumnKind | "issue"; usesIssueCell: boolean } | GitHubCommandFailure {
+  const columnMap = boardColumnIndexMap(section.headers);
+  if (field === "summary") {
+    const summaryIndex = columnMap.get("summary");
+    if (summaryIndex !== undefined) return { ok: true, columnIndex: summaryIndex, targetColumn: "summary", usesIssueCell: false };
+    const issueColumnIndex = boardIssueColumnIndex(section.headers);
+    if (issueColumnIndex !== null) return { ok: true, columnIndex: issueColumnIndex, targetColumn: "issue", usesIssueCell: true };
+  }
+  const targetColumn = boardColumnKindForUpsertField(field);
+  const columnIndex = columnMap.get(targetColumn);
+  if (columnIndex === undefined) {
+    return validationError(commandName, repo, `board table does not contain a column for --${field}`, {
+      issueNumber,
+      field,
+      targetColumn,
+      section: section.kind,
+      headers: section.headers,
+    }) as GitHubCommandFailure;
+  }
+  return { ok: true, columnIndex, targetColumn, usesIssueCell: false };
+}
+
+function boardRowUpsertRenderedValue(
+  repo: string,
+  issueNumber: number,
+  field: BoardRowUpsertField,
+  value: string,
+  targetColumn: BoardColumnKind | "issue",
+): string {
+  if (field === "summary" && targetColumn === "issue") return renderBoardIssueCell(repo, issueNumber, value);
+  return value;
+}
+
+function boardRowUpsertPollutionFailure(
+  repo: string,
+  commandName: string,
+  issueNumber: number,
+  values: BoardRowUpsertValues,
+): GitHubCommandFailure | null {
+  const findings = BOARD_ROW_UPSERT_TEXT_FIELDS
+    .map((field) => {
+      const value = values[field];
+      if (value === undefined) return null;
+      const evidence = boardRowValuePollutionEvidence(value);
+      return evidence.length === 0 ? null : { field, valuePreview: preview(value), evidence };
+    })
+    .filter((item): item is { field: BoardRowUpsertTextField; valuePreview: string; evidence: string[] } => item !== null);
+  if (findings.length === 0) return null;
+  return validationError(commandName, repo, "issue board-row upsert field value contains literal shell escape text that would pollute a board cell; pass real newlines or plain text instead", {
+    issueNumber,
+    shellPollution: { suspected: true, findings },
+  }) as GitHubCommandFailure;
+}
+
+function boardRowUpsertUpdatePlan(
+  repo: string,
+  boardIssue: GitHubIssue,
+  issueNumber: number,
+  found: { section: BoardTableSection; row: BoardTableRow },
+  values: BoardRowUpsertValues,
+  requestedSection: BoardMutationSection | undefined,
+  parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
+): BoardRowMutationPlanResult | GitHubCommandFailure {
+  const commandName = "issue board-row upsert";
+  const { section, row } = found;
+  if (requestedSection !== undefined && requestedSection !== section.kind) {
+    return validationError(commandName, repo, `--section ${requestedSection} conflicts with existing row in ${section.kind}; use gh issue board-row move for section migration`, {
+      issueNumber,
+      requestedSection,
+      existingSection: section.kind,
+      moveCommand: `bun scripts/cli.ts gh issue board-row move ${issueNumber} --board-issue ${boardIssue.number} --to ${requestedSection}`,
+    }) as GitHubCommandFailure;
+  }
+  if (values.status !== undefined) {
+    const expectedStatus = expectedBoardGithubStatus(section.kind);
+    if (values.status !== expectedStatus) {
+      return validationError(commandName, repo, `--status ${values.status} conflicts with existing ${section.kind.toUpperCase()} section; use gh issue board-row move for section migration`, {
+        issueNumber,
+        existingSection: section.kind,
+        requestedStatus: values.status,
+        expectedStatus,
+        moveCommand: `bun scripts/cli.ts gh issue board-row move ${issueNumber} --board-issue ${boardIssue.number} --to ${values.status === "OPEN" ? "open" : "closed"} --status ${values.status}`,
+      }) as GitHubCommandFailure;
+    }
+  }
+  const entries = boardRowUpsertValueEntries(values);
+  if (entries.length === 0) {
+    return validationError(commandName, repo, "issue board-row upsert found an existing row but no upsert fields were provided", {
+      issueNumber,
+      existingSection: section.kind,
+      supportedFields: ["--category", "--branch", "--tasks", "--summary", "--focus", "--validation", "--progress", "--status"],
+    }) as GitHubCommandFailure;
+  }
+  if (row.cells.length !== section.headers.length) {
+    return validationError(commandName, repo, "existing row column count does not match the board table header", {
+      issueNumber,
+      section: section.kind,
+      expectedColumns: section.headers.length,
+      actualColumns: row.cells.length,
+      headers: section.headers,
+      lineNumber: row.lineNumber,
+      rowPreview: preview(row.raw),
+    }) as GitHubCommandFailure;
+  }
+  const oldCells = row.cells.slice();
+  const newCells = oldCells.slice();
+  const changedFields: Record<string, unknown>[] = [];
+  for (const entry of entries) {
+    const target = boardRowUpsertTargetColumn(repo, commandName, section, issueNumber, entry.field);
+    if (target.ok === false) return target;
+    const newValue = boardRowUpsertRenderedValue(repo, issueNumber, entry.field, entry.value, target.targetColumn);
+    const oldValue = oldCells[target.columnIndex] ?? "";
+    newCells[target.columnIndex] = newValue;
+    changedFields.push({
+      field: entry.field,
+      targetColumn: target.targetColumn,
+      targetColumnIndex: target.columnIndex,
+      requestedValue: entry.value,
+      oldValue,
+      newValue,
+      changed: oldValue !== newValue,
+    });
+  }
+  const newRow = renderMarkdownTableRow(newCells);
+  const oldBody = boardIssue.body ?? "";
+  let newBody: string;
+  try {
+    newBody = replaceBoardBodyLine(oldBody, row.lineNumber, newRow);
+  } catch (error) {
+    return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
+      issueNumber,
+      lineNumber: row.lineNumber,
+    }) as GitHubCommandFailure;
+  }
+  return {
+    ok: true,
+    newBody,
+    plan: {
+      repo,
+      boardIssue: boardIssue.number,
+      issueNumber,
+      operation: "update",
+      action: "update",
+      section: section.kind,
+      lineNumber: row.lineNumber,
+      requestedSection: requestedSection ?? null,
+      providedFields: entries.map((entry) => entry.field),
+      changedFields,
+      oldRow: row.raw,
+      newRow,
+      oldCells,
+      newCells,
+      row: {
+        old: boardRowSummary(section, row),
+        new: {
+          ...boardRowSummary(section, { ...row, raw: newRow, cells: newCells }),
+          upsertFields: boardRowUpsertFieldValues(section, { ...row, raw: newRow, cells: newCells }),
+        },
+      },
+      linePlan: {
+        action: "replace",
+        section: section.kind,
+        lineNumber: row.lineNumber,
+      },
+      sectionPlan: {
+        kind: section.kind,
+        heading: section.heading,
+        headerLine: section.headerLine,
+        rowCount: section.rows.length,
+      },
+      body: {
+        oldBodyChars: oldBody.length,
+        oldBodySha: bodySha(oldBody),
+        newBodyChars: newBody.length,
+        newBodySha: bodySha(newBody),
+        changed: oldBody !== newBody,
+      },
+      tableParser: {
+        reused: "parseBoardTables",
+        rowValidationWarnings: parsed.warnings.length,
+      },
+      request: {
+        method: "PATCH",
+        path: `/repos/{owner}/{repo}/issues/${boardIssue.number}`,
+        body: { bodyChars: newBody.length },
+      },
+    },
+  };
+}
+
+function boardRowUpsertAddPlan(
+  repo: string,
+  boardIssue: GitHubIssue,
+  issueNumber: number,
+  sectionKind: BoardMutationSection,
+  values: BoardRowUpsertValues,
+  parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
+): BoardRowMutationPlanResult | GitHubCommandFailure {
+  const commandName = "issue board-row upsert";
+  const targetLookup = targetBoardSection(repo, parsed.sections, sectionKind, commandName);
+  if (targetLookup.ok === false) return targetLookup;
+  const target = targetLookup.section;
+  const issueColumnIndex = boardIssueColumnIndex(target.headers);
+  if (issueColumnIndex === null) {
+    return validationError(commandName, repo, "board table does not contain an Issue column required for generated upsert rows", {
+      boardIssue: boardIssue.number,
+      section: sectionKind,
+      headers: target.headers,
+    }) as GitHubCommandFailure;
+  }
+  const columnMap = boardColumnIndexMap(target.headers);
+  const githubStatusColumnIndex = columnMap.get("githubStatus");
+  if (githubStatusColumnIndex === undefined) {
+    return validationError(commandName, repo, "board table does not contain a GitHub 状态 column required for generated upsert rows", {
+      boardIssue: boardIssue.number,
+      section: sectionKind,
+      headers: target.headers,
+    }) as GitHubCommandFailure;
+  }
+  const expectedStatus = expectedBoardGithubStatus(sectionKind);
+  const requestedStatus = values.status ?? expectedStatus;
+  if (requestedStatus !== expectedStatus) {
+    return validationError(commandName, repo, `--status ${requestedStatus} conflicts with --section ${sectionKind}; expected ${expectedStatus}`, {
+      issueNumber,
+      section: sectionKind,
+      requestedStatus,
+      expectedStatus,
+    }) as GitHubCommandFailure;
+  }
+  const appliedFields = new Set<BoardRowUpsertField>();
+  const missingFields: BoardRowUpsertTextField[] = [];
+  const unsupportedColumns: Array<{ index: number; header: string }> = [];
+  const summaryColumnIndex = columnMap.get("summary");
+  const cells = target.headers.map((header, index) => {
+    if (index === issueColumnIndex) {
+      if (summaryColumnIndex === undefined && values.summary !== undefined) appliedFields.add("summary");
+      return summaryColumnIndex === undefined ? renderBoardIssueCell(repo, issueNumber, values.summary) : `#${issueNumber}`;
+    }
+    const kind = boardHeaderColumnKind(header);
+    if (kind === "githubStatus") {
+      if (values.status !== undefined) appliedFields.add("status");
+      return requestedStatus;
+    }
+    const valueFor = (field: BoardRowUpsertTextField, value: string | undefined): string => {
+      if (value === undefined) {
+        missingFields.push(field);
+        return "";
+      }
+      appliedFields.add(field);
+      return value;
+    };
+    if (kind === "category") return valueFor("category", values.category);
+    if (kind === "branch") return valueFor("branch", values.branch);
+    if (kind === "relatedTask") return valueFor("tasks", values.tasks);
+    if (kind === "summary") return valueFor("summary", values.summary);
+    if (kind === "focus") return valueFor("focus", values.focus);
+    if (kind === "acceptance") return valueFor("validation", values.validation);
+    if (kind === "progress") return valueFor("progress", values.progress);
+    unsupportedColumns.push({ index, header });
+    return "";
+  });
+  if (unsupportedColumns.length > 0) {
+    return validationError(commandName, repo, "target board table contains unsupported column(s) for generated upsert rows", {
+      issueNumber,
+      section: sectionKind,
+      unsupportedColumns,
+      headers: target.headers,
+    }) as GitHubCommandFailure;
+  }
+  const unappliedFields = boardRowUpsertValueEntries(values)
+    .map((entry) => entry.field)
+    .filter((field) => !appliedFields.has(field));
+  if (unappliedFields.length > 0) {
+    return validationError(commandName, repo, "target board table does not contain column(s) for supplied upsert field(s)", {
+      issueNumber,
+      section: sectionKind,
+      unappliedFields,
+      headers: target.headers,
+    }) as GitHubCommandFailure;
+  }
+  const uniqueMissingFields = Array.from(new Set(missingFields));
+  if (uniqueMissingFields.length > 0) {
+    return validationError(commandName, repo, "issue board-row upsert add requires values for every generated row column", {
+      issueNumber,
+      section: sectionKind,
+      missingFields: uniqueMissingFields,
+      requiredOptions: uniqueMissingFields.map((field) => `--${field}`),
+      headers: target.headers,
+    }) as GitHubCommandFailure;
+  }
+  const newRow = renderMarkdownTableRow(cells);
+  const row = boardRowFromCells(target, newRow, cells, 0);
+  if (row.issueNumber !== issueNumber) {
+    return validationError(commandName, repo, "generated Issue column does not match the requested issue number", {
+      issueNumber,
+      issueColumnIndex,
+      issueCell: cells[issueColumnIndex] ?? "",
+      detectedIssueNumber: row.issueNumber,
+      rowPreview: preview(newRow),
+    }) as GitHubCommandFailure;
+  }
+  const actualStatus = normalizeBoardGithubStatusCell(cells[githubStatusColumnIndex]);
+  if (actualStatus !== expectedStatus) {
+    return validationError(commandName, repo, "generated GitHub 状态 column does not match the target section", {
+      issueNumber,
+      section: sectionKind,
+      expectedStatus,
+      actualStatus,
+      statusColumnIndex: githubStatusColumnIndex,
+      statusCell: cells[githubStatusColumnIndex] ?? "",
+      rowPreview: preview(newRow),
+    }) as GitHubCommandFailure;
+  }
+  const oldBody = boardIssue.body ?? "";
+  const insertAfterLine = boardSectionInsertAfterLine(target);
+  let newBody: string;
+  try {
+    newBody = insertBoardBodyLineAfter(oldBody, insertAfterLine, newRow);
+  } catch (error) {
+    return validationError(commandName, repo, error instanceof Error ? error.message : String(error), {
+      issueNumber,
+      section: sectionKind,
+      insertAfterLine,
+    }) as GitHubCommandFailure;
+  }
+  return {
+    ok: true,
+    newBody,
+    plan: {
+      repo,
+      boardIssue: boardIssue.number,
+      issueNumber,
+      operation: "add",
+      action: "add",
+      section: sectionKind,
+      insertAfterLine,
+      providedFields: boardRowUpsertValueEntries(values).map((entry) => entry.field),
+      newRow,
+      newCells: cells,
+      row: {
+        old: null,
+        new: {
+          ...boardRowSummary(target, { ...row, lineNumber: insertAfterLine + 1 }),
+          upsertFields: boardRowUpsertFieldValues(target, { ...row, lineNumber: insertAfterLine + 1 }),
+        },
+      },
+      linePlan: {
+        action: "insert",
+        section: sectionKind,
+        insertAfterLine,
+        newLineNumber: insertAfterLine + 1,
+      },
+      sectionPlan: {
+        kind: sectionKind,
+        heading: target.heading,
+        headerLine: target.headerLine,
+        rowCount: target.rows.length,
+      },
+      validation: {
+        issueColumnIndex,
+        githubStatusColumnIndex,
+        expectedStatus,
+        actualStatus,
+        columnCount: cells.length,
+      },
+      body: {
+        oldBodyChars: oldBody.length,
+        oldBodySha: bodySha(oldBody),
+        newBodyChars: newBody.length,
+        newBodySha: bodySha(newBody),
+        changed: oldBody !== newBody,
+      },
+      tableParser: {
+        reused: "parseBoardTables",
+        rowValidationWarnings: parsed.warnings.length,
+      },
+      request: {
+        method: "PATCH",
+        path: `/repos/{owner}/{repo}/issues/${boardIssue.number}`,
+        body: { bodyChars: newBody.length },
+      },
+    },
+  };
+}
+
+function boardRowUpsertPlan(
+  repo: string,
+  boardIssue: GitHubIssue,
+  issueNumber: number,
+  options: GitHubOptions,
+  parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
+): BoardRowMutationPlanResult | GitHubCommandFailure {
+  const commandName = "issue board-row upsert";
+  const pollutionFailure = boardRowUpsertPollutionFailure(repo, commandName, issueNumber, options.boardRowUpsertValues);
+  if (pollutionFailure !== null) return pollutionFailure;
+  const matches = boardRowsExactMatch(parsed.sections, issueNumber);
+  if (matches.length > 1) {
+    return validationError(commandName, repo, `board row for issue #${issueNumber} is ambiguous; refusing upsert`, {
+      issueNumber,
+      matches: matches.map(({ section, row }) => ({ section: section.kind, lineNumber: row.lineNumber, rowPreview: preview(row.raw) })),
+    }) as GitHubCommandFailure;
+  }
+  if (matches.length === 1) {
+    return boardRowUpsertUpdatePlan(repo, boardIssue, issueNumber, matches[0], options.boardRowUpsertValues, options.boardSection, parsed);
+  }
+  if (options.boardSection === undefined) {
+    return validationError(commandName, repo, "issue board-row upsert add requires --section open|closed when the row does not already exist", {
+      issueNumber,
+      supportedSections: BOARD_MUTATION_SECTIONS.slice(),
+    }) as GitHubCommandFailure;
+  }
+  return boardRowUpsertAddPlan(repo, boardIssue, issueNumber, options.boardSection, options.boardRowUpsertValues, parsed);
+}
+
 function boardRowAddPlan(
   repo: string,
   boardIssue: GitHubIssue,
@@ -2260,8 +2767,8 @@ async function issueBoardRowMutation(
   token: string,
   issueNumber: number,
   options: GitHubOptions,
-  commandName: "issue board-row add" | "issue board-row move" | "issue board-row delete",
-  mutationKey: "add" | "move" | "delete",
+  commandName: "issue board-row add" | "issue board-row move" | "issue board-row delete" | "issue board-row upsert",
+  mutationKey: "add" | "move" | "delete" | "upsert",
   buildPlan: (boardIssue: GitHubIssue, parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] }) => BoardRowMutationPlanResult | GitHubCommandFailure,
 ): Promise<GitHubCommandResult> {
   const concurrencyOptionError = assertConcurrencyOptions(options, commandName);
@@ -2289,6 +2796,7 @@ async function issueBoardRowMutation(
       updatedAt: boardIssue.updated_at ?? null,
     },
     issueNumber,
+    operation: typeof planned.plan.operation === "string" ? planned.plan.operation : mutationKey,
     dryRun: effectiveDryRun,
     planned: true,
     [mutationKey]: planned.plan,
@@ -2519,6 +3027,19 @@ async function issueBoardRowAdd(repo: string, token: string, issueNumber: number
   );
 }
 
+async function issueBoardRowUpsert(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
+  const commandName = "issue board-row upsert";
+  return issueBoardRowMutation(
+    repo,
+    token,
+    issueNumber,
+    options,
+    commandName,
+    "upsert",
+    (boardIssue, parsed) => boardRowUpsertPlan(repo, boardIssue, issueNumber, options, parsed),
+  );
+}
+
 async function issueBoardRowMove(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
   const commandName = "issue board-row move";
   if (options.boardMoveTo === undefined) return validationError(commandName, repo, "issue board-row move requires --to open|closed", { issueNumber, supportedTargets: BOARD_MUTATION_SECTIONS.slice() });
@@ -4071,6 +4592,7 @@ export function ghHelp(): unknown {
       "bun scripts/cli.ts gh issue board-row get <issueNumber> [--repo owner/name] --board-issue 20",
       "bun scripts/cli.ts gh issue board-row update <issueNumber> [--repo owner/name] --board-issue 20 --field progress|status|validation|branch|tasks|focus --value <text> [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256]",
       "bun scripts/cli.ts gh issue board-row add <issueNumber> [--repo owner/name] --board-issue 20 --section open|closed --row-file <markdown-row-file> [--dry-run] [--expect-body-sha sha256]",
+      "bun scripts/cli.ts gh issue board-row upsert <issueNumber> [--repo owner/name] --board-issue 20 --section open|closed [--category text] --branch <branch> --tasks <task> --summary <text> --focus <text> --validation <text> --progress <text> [--status OPEN|CLOSED] [--dry-run] [--expect-updated-at ts|--expect-body-sha sha256]",
       "bun scripts/cli.ts gh issue board-row move <issueNumber> [--repo owner/name] --board-issue 20 --to open|closed [--status OPEN|CLOSED] [--dry-run] [--expect-body-sha sha256]",
       "bun scripts/cli.ts gh issue board-row delete <issueNumber> [--repo owner/name] --board-issue 20 [--dry-run] [--expect-body-sha sha256]",
       "bun scripts/cli.ts gh pr list [--repo owner/name] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]",
@@ -4101,6 +4623,7 @@ export function ghHelp(): unknown {
       "issue scan-escape classifies literal \\n findings as suspected-pollution, explanatory-mention, or risk, and emits cleanupSuggestions with body/comment ids plus diff-like previews. cleanup-plan is an alias that remains dry-run/read-only.",
       "issue board-audit is read-only and defaults to repo pikasTech/unidesk plus board issue #20. It compares GitHub open/closed issue lists with the board OPEN/CLOSED tables and reports missingOpenIssues, closedInOpenRows, missingClosedRows, rowValidationWarnings, ignoredIssues, and recommendedActions. When an Issue column exists, row.issueNumber is taken from that column; #20 and #24 are known meta issues by default. Daily rolling brief issues titled YYYY-MM-DD 指挥简报（北京时间） are managed by #20's brief index and appear in ignoredIssues with reason=brief-index-managed instead of missingOpenIssues.",
       "issue board-row list/get reuse the board-audit table parser and are read-only. board-row update changes one table cell by issue number, returns old/new row, body SHA, body guard and request plan, and defaults to dry-run unless --expect-updated-at or --expect-body-sha is supplied for the guarded PATCH. Field aliases map status and validation to the 验收状态 column, tasks to 相关 Code Queue 任务, and focus to 当前关注点.",
+      "issue board-row upsert updates an existing row when the issue is already present, or generates a complete row in --section open|closed when missing. It returns operation=update or operation=add, defaults to dry-run, requires --expect-body-sha or --expect-updated-at before PATCH, and refuses section migration; use board-row move for OPEN/CLOSED migration.",
       "issue board-row add/move/delete are row-scoped #20 table mutations. add validates a one-line --row-file against the target table column count, Issue column, and GitHub 状态 column; move refuses duplicate/ambiguous rows and can update GitHub 状态 via --status; delete removes only the matched row. All three default to dry-run and require --expect-body-sha or --expect-updated-at before PATCH. add/move/delete return old/new row, body SHA, and line/section plan details for the parsed table mutation.",
       "issue edit 24 --notify-claudeqq-brief-diff remains the legacy #24 notification helper: it reads the old issue body, PATCHes the new body, and sends only newly added '## 更新 ... 北京时间' sections to ClaudeQQ; ClaudeQQ failure does not roll back GitHub.",
       "Commander brief ClaudeQQ defaults to private target 645275593 through backend-core /api/microservices/claudeqq/proxy; UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_* env vars can override target, base URL, timeout, and enabled state.",
@@ -4142,9 +4665,9 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
     const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
     return validationError(command, options.repo, "--mode is only supported by gh issue update/edit and gh pr update");
   }
-  if ((options.allowShortBody || options.expectUpdatedAt !== undefined || options.expectBodySha !== undefined || optionWasProvided(args, "--body-profile")) && !(top === "issue" && (sub === "edit" || sub === "update" || sub === "board-row" && ["update", "add", "move", "delete"].includes(third ?? "")))) {
+  if ((options.allowShortBody || options.expectUpdatedAt !== undefined || options.expectBodySha !== undefined || optionWasProvided(args, "--body-profile")) && !(top === "issue" && (sub === "edit" || sub === "update" || sub === "board-row" && ["update", "add", "move", "delete", "upsert"].includes(third ?? "")))) {
     const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
-    return validationError(command, options.repo, "--allow-short-body, --expect-updated-at, --expect-body-sha, and --body-profile are only supported by gh issue update/edit and gh issue board-row update/add/move/delete");
+    return validationError(command, options.repo, "--allow-short-body, --expect-updated-at, --expect-body-sha, and --body-profile are only supported by gh issue update/edit and gh issue board-row update/add/move/delete/upsert");
   }
   if ((optionWasProvided(args, "--board-issue") || optionWasProvided(args, "--known-meta-issue") || optionWasProvided(args, "--ignore-issue")) && !(top === "issue" && (sub === "board-audit" || sub === "board-row"))) {
     const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
@@ -4162,13 +4685,21 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
     const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
     return validationError(command, options.repo, "--row-file is only supported by gh issue board-row add");
   }
-  if (optionWasProvided(args, "--section") && !(top === "issue" && sub === "board-row" && third === "add")) {
+  if (optionWasProvided(args, "--section") && !(top === "issue" && sub === "board-row" && (third === "add" || third === "upsert"))) {
     const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
-    return validationError(command, options.repo, "--section is only supported by gh issue board-row add");
+    return validationError(command, options.repo, "--section is only supported by gh issue board-row add/upsert");
   }
-  if ((optionWasProvided(args, "--to") || optionWasProvided(args, "--status")) && !(top === "issue" && sub === "board-row" && third === "move")) {
+  if (optionWasProvided(args, "--to") && !(top === "issue" && sub === "board-row" && third === "move")) {
     const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
-    return validationError(command, options.repo, "--to and --status are only supported by gh issue board-row move");
+    return validationError(command, options.repo, "--to is only supported by gh issue board-row move");
+  }
+  if (optionWasProvided(args, "--status") && !(top === "issue" && sub === "board-row" && (third === "move" || third === "upsert"))) {
+    const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
+    return validationError(command, options.repo, "--status is only supported by gh issue board-row move/upsert");
+  }
+  if ((optionWasProvided(args, "--category") || optionWasProvided(args, "--branch") || optionWasProvided(args, "--tasks") || optionWasProvided(args, "--summary") || optionWasProvided(args, "--focus") || optionWasProvided(args, "--validation") || optionWasProvided(args, "--progress")) && !(top === "issue" && sub === "board-row" && third === "upsert")) {
+    const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
+    return validationError(command, options.repo, "--category, --branch, --tasks, --summary, --focus, --validation, and --progress are only supported by gh issue board-row upsert");
   }
   if (optionWasProvided(args, "--label") && !(top === "issue" && sub === "create")) {
     const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
@@ -4213,8 +4744,8 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
     if (sub === "board-row") {
       const action = third;
       const commandName = `issue board-row ${action ?? ""}`.trim();
-      if (action !== "list" && action !== "get" && action !== "update" && action !== "add" && action !== "move" && action !== "delete") {
-        return unsupportedCommand(commandName, options.repo, "board-row supported commands are list, get, update, add, move, and delete.");
+      if (action !== "list" && action !== "get" && action !== "update" && action !== "add" && action !== "move" && action !== "delete" && action !== "upsert") {
+        return unsupportedCommand(commandName, options.repo, "board-row supported commands are list, get, update, add, move, delete, and upsert.");
       }
       const { token, probe } = resolveToken(true);
       const missing = authRequired(options.repo, commandName, probe);
@@ -4225,6 +4756,7 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
       if (action === "get") return issueBoardRowGet(options.repo, token, issueNumber, options);
       if (action === "update") return issueBoardRowUpdate(options.repo, token, issueNumber, options);
       if (action === "add") return issueBoardRowAdd(options.repo, token, issueNumber, options);
+      if (action === "upsert") return issueBoardRowUpsert(options.repo, token, issueNumber, options);
       if (action === "move") return issueBoardRowMove(options.repo, token, issueNumber, options);
       return issueBoardRowDelete(options.repo, token, issueNumber, options);
     }