feat: add gh board row cli

2026-05-21 07:11:57 +00:00
parent 8479258fea
commit 422274f0e3
6 changed files with 541 additions and 17 deletions
@@ -15,6 +15,7 @@ const CODE_QUEUE_BOARD_TARGET_ISSUE = 20;
 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 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;
@@ -48,6 +49,8 @@ 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";
+type BoardRowField = typeof BOARD_ROW_FIELDS[number];

 type GitHubDegradedReason =
  | "missing-binary"
@@ -225,6 +228,19 @@ interface BoardRowValidationWarning {
  rowPreview: string;
 }

+interface BoardRowLookup {
+  ok: true;
+  section: BoardTableSection;
+  row: BoardTableRow;
+  matches: Array<{ section: BoardTableSection; row: BoardTableRow }>;
+}
+
+interface BoardRowUpdatePlanResult {
+  ok: true;
+  plan: Record<string, unknown>;
+  newBody: string;
+}
+
 interface GitHubCommandResult {
  ok: boolean;
  repo: string;
@@ -235,6 +251,8 @@ interface GitHubCommandResult {
  [key: string]: unknown;
 }

+type GitHubCommandFailure = GitHubCommandResult & { ok: false };
+
 interface GitHubTokenProbe {
  present: boolean;
  source: "GH_TOKEN" | "GITHUB_TOKEN" | "gh-auth-token" | null;
@@ -267,6 +285,8 @@ interface GitHubOptions {
  expectUpdatedAt?: string;
  expectBodySha?: string;
  bodyProfile: IssueBodyProfileOption;
+  boardRowField?: BoardRowField;
+  boardRowValue?: string;
 }

 interface GitHubErrorPayload {
@@ -433,6 +453,11 @@ function positiveIntegerOption(args: string[], name: string, defaultValue: numbe
  return Math.min(value, maxValue);
 }

+function validateEnumValue<T extends string>(name: string, raw: string, allowedValues: readonly T[]): T {
+  if ((allowedValues as readonly string[]).includes(raw)) return raw as T;
+  throw new Error(`unsupported ${name} ${raw}; supported values: ${allowedValues.join(",")}`);
+}
+
 function validateJsonFields<T extends string>(command: string, requested: string[] | undefined, allowedFields: readonly T[]): T[] | undefined {
  if (requested === undefined) return undefined;
  const allowed = new Set<string>(allowedFields);
@@ -481,8 +506,14 @@ function parseIssueBodyProfile(args: string[]): IssueBodyProfileOption {
  throw new Error(`unsupported --body-profile ${raw}; supported profiles: auto, code-queue-board, commander-brief`);
 }

+function parseBoardRowField(args: string[]): BoardRowField | undefined {
+  const raw = optionValue(args, "--field");
+  if (raw === undefined) return undefined;
+  return validateEnumValue("--field", raw, BOARD_ROW_FIELDS);
+}
+
 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"]);
+  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"]);
  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];
@@ -524,6 +555,8 @@ function parseOptions(args: string[]): GitHubOptions {
    expectUpdatedAt: optionValue(args, "--expect-updated-at"),
    expectBodySha: optionValue(args, "--expect-body-sha"),
    bodyProfile: parseIssueBodyProfile(args),
+    boardRowField: parseBoardRowField(args),
+    boardRowValue: optionValue(args, "--value"),
  };
 }

@@ -1232,15 +1265,43 @@ function normalizeBoardHeader(header: string): string {
  return stripMarkdownInline(header).toLowerCase().replace(/\s+/g, "");
 }

-function boardHeaderColumnKind(header: string): BoardRequiredColumn | null {
+function boardHeaderColumnKind(header: string): BoardColumnKind | null {
  const normalized = normalizeBoardHeader(header);
  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 (["focus", "currentfocus", "关注点", "当前关注点", "当前focus"].includes(normalized)) return "focus";
  if (["progress", "进度", "状态", "当前进度"].includes(normalized)) return "progress";
  return null;
 }

+function boardColumnIndexMap(headers: string[]): Map<BoardColumnKind, number> {
+  const map = new Map<BoardColumnKind, number>();
+  headers.forEach((header, headerIndex) => {
+    const kind = boardHeaderColumnKind(header);
+    if (kind !== null && !map.has(kind)) map.set(kind, headerIndex);
+  });
+  return map;
+}
+
+function boardRequiredColumnIndexMap(headers: string[]): Map<BoardRequiredColumn, number> {
+  const map = new Map<BoardRequiredColumn, number>();
+  const allColumns = boardColumnIndexMap(headers);
+  for (const column of BOARD_AUDIT_REQUIRED_COLUMNS) {
+    const index = allColumns.get(column);
+    if (index !== undefined) map.set(column, index);
+  }
+  return map;
+}
+
+function boardColumnKindForField(field: BoardRowField): BoardColumnKind {
+  if (field === "branch") return "branch";
+  if (field === "tasks") return "relatedTask";
+  if (field === "focus") return "focus";
+  if (field === "progress") return "progress";
+  return "acceptance";
+}
+
 function boardIssueColumnIndex(headers: string[]): number | null {
  for (let index = 0; index < headers.length; index += 1) {
    const normalized = normalizeBoardHeader(headers[index]);
@@ -1252,7 +1313,20 @@ function boardIssueColumnIndex(headers: string[]): number | null {
 function markdownCells(line: string): string[] {
  const trimmed = line.trim();
  const withoutOuterPipes = trimmed.replace(/^\|/u, "").replace(/\|$/u, "");
-  return withoutOuterPipes.split("|").map((cell) => cell.trim());
+  const cells: string[] = [];
+  let current = "";
+  for (let index = 0; index < withoutOuterPipes.length; index += 1) {
+    const char = withoutOuterPipes[index];
+    const previous = withoutOuterPipes[index - 1];
+    if (char === "|" && previous !== "\\") {
+      cells.push(current.trim().replace(/\\\|/g, "|"));
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  cells.push(current.trim().replace(/\\\|/g, "|"));
+  return cells;
 }

 function isMarkdownTableSeparator(line: string): boolean {
@@ -1364,11 +1438,7 @@ function parseBoardTables(body: string): { sections: BoardTableSection[]; warnin
    const separator = lines[index + 1];
    if (separator === undefined || !separator.trim().startsWith("|") || !isMarkdownTableSeparator(separator)) continue;
    const headers = markdownCells(lines[index]);
-    const columnMap = new Map<BoardRequiredColumn, number>();
-    headers.forEach((header, headerIndex) => {
-      const kind = boardHeaderColumnKind(header);
-      if (kind !== null && !columnMap.has(kind)) columnMap.set(kind, headerIndex);
-    });
+    const columnMap = boardRequiredColumnIndexMap(headers);
    const issueColumnIndex = boardIssueColumnIndex(headers);
    const rows: BoardTableRow[] = [];
    let rowIndex = index + 2;
@@ -1460,6 +1530,342 @@ function boardRowsByIssue(rows: BoardTableRow[]): Map<number, BoardTableRow[]> {
  return map;
 }

+function boardRowFieldValues(section: BoardTableSection, row: BoardTableRow): Record<BoardRowField, 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 {
+    progress: valueFor("progress"),
+    status: acceptance,
+    validation: acceptance,
+    branch: valueFor("branch"),
+    tasks: valueFor("relatedTask"),
+    focus: valueFor("focus"),
+  };
+}
+
+function boardRowSummary(section: BoardTableSection, row: BoardTableRow): Record<string, unknown> {
+  return {
+    issueNumber: row.issueNumber,
+    section: row.section,
+    lineNumber: row.lineNumber,
+    heading: section.heading,
+    headers: section.headers,
+    title: row.title,
+    cells: row.cells,
+    fields: boardRowFieldValues(section, row),
+    raw: row.raw,
+    rowPreview: preview(row.raw),
+  };
+}
+
+function boardRowsForState(sections: BoardTableSection[], state: IssueListState): Array<{ section: BoardTableSection; row: BoardTableRow }> {
+  return sections
+    .filter((section) => state === "all" || section.kind === state)
+    .flatMap((section) => section.rows.map((row) => ({ section, row })));
+}
+
+function findBoardRow(
+  repo: string,
+  sections: BoardTableSection[],
+  issueNumber: number,
+  state: IssueListState = "all",
+): BoardRowLookup | GitHubCommandFailure {
+  const matches = boardRowsForState(sections, state).filter(({ row }) => row.issueNumber === issueNumber);
+  if (matches.length === 0) {
+    return validationError("issue board-row", repo, `board row for issue #${issueNumber} was not found`, {
+      issueNumber,
+      state,
+      availableIssueNumbers: boardRowsForState(sections, state)
+        .map(({ row }) => row.issueNumber)
+        .filter((value): value is number => value !== null)
+        .sort((a, b) => a - b),
+    }) as GitHubCommandFailure;
+  }
+  if (matches.length > 1) {
+    return validationError("issue board-row", repo, `board row for issue #${issueNumber} is ambiguous`, {
+      issueNumber,
+      state,
+      matches: matches.map(({ section, row }) => ({ section: section.kind, lineNumber: row.lineNumber, rowPreview: preview(row.raw) })),
+    }) as GitHubCommandFailure;
+  }
+  return { ok: true, ...matches[0], matches };
+}
+
+function escapeMarkdownTableCell(value: string): string {
+  return value
+    .replace(/\r\n/g, " ")
+    .replace(/[\r\n]+/g, " ")
+    .replace(/\|/g, "\\|")
+    .trim();
+}
+
+function boardRowValuePollutionEvidence(value: string): string[] {
+  return shellPollutionEvidence(value).filter((item) => item !== "bare-carriage-return");
+}
+
+function renderMarkdownTableRow(cells: string[]): string {
+  return `| ${cells.map(escapeMarkdownTableCell).join(" | ")} |`;
+}
+
+function replaceBoardBodyLine(body: string, lineNumber: number, newLine: string): string {
+  const normalized = normalizeNewlines(body);
+  const lines = normalized.split("\n");
+  if (lineNumber <= 0 || lineNumber > lines.length) throw new Error(`line ${lineNumber} is outside the board body`);
+  lines[lineNumber - 1] = newLine;
+  return lines.join("\n");
+}
+
+function boardBodySafetyIssue(repo: string, boardIssueNumber: number, body: string, options: GitHubOptions): GitHubCommandResult | null {
+  const guardOptions: GitHubOptions = { ...options, bodyProfile: boardIssueNumber === CODE_QUEUE_BOARD_TARGET_ISSUE ? "code-queue-board" : options.bodyProfile };
+  return validateIssueBodyGuard(repo, boardIssueNumber, body, guardOptions);
+}
+
+function boardBodyGuardSummary(boardIssueNumber: number, body: string, options: GitHubOptions): Record<string, unknown> {
+  const guardOptions: GitHubOptions = { ...options, bodyProfile: boardIssueNumber === CODE_QUEUE_BOARD_TARGET_ISSUE ? "code-queue-board" : options.bodyProfile };
+  return issueEditGuardSummary(boardIssueNumber, body, guardOptions);
+}
+
+function boardRowUpdatePlan(
+  repo: string,
+  boardIssue: GitHubIssue,
+  issueNumber: number,
+  field: BoardRowField,
+  value: string,
+  parsed: { sections: BoardTableSection[]; warnings: BoardRowValidationWarning[] },
+): BoardRowUpdatePlanResult | GitHubCommandFailure {
+  const found = findBoardRow(repo, parsed.sections, issueNumber);
+  if (found.ok === false) return found;
+  const { section, row } = found;
+  const targetColumn = boardColumnKindForField(field);
+  const columnMap = boardColumnIndexMap(section.headers);
+  const columnIndex = columnMap.get(targetColumn);
+  if (columnIndex === undefined) {
+    return validationError("issue board-row update", repo, `board table does not contain a column for --field ${field}`, {
+      issueNumber,
+      field,
+      targetColumn,
+      section: section.kind,
+      headers: section.headers,
+      supportedFields: BOARD_ROW_FIELDS.slice(),
+    }) as GitHubCommandFailure;
+  }
+  const oldCells = row.cells.slice();
+  const newCells = oldCells.slice();
+  while (newCells.length < section.headers.length) newCells.push("");
+  newCells[columnIndex] = value;
+  const newRow = renderMarkdownTableRow(newCells);
+  const oldBody = boardIssue.body ?? "";
+  let newBody: string;
+  try {
+    newBody = replaceBoardBodyLine(oldBody, row.lineNumber, newRow);
+  } catch (error) {
+    return validationError("issue board-row update", repo, error instanceof Error ? error.message : String(error), {
+      issueNumber,
+      field,
+      lineNumber: row.lineNumber,
+    }) as GitHubCommandFailure;
+  }
+  return {
+    ok: true,
+    newBody,
+    plan: {
+      repo,
+      boardIssue: boardIssue.number,
+      issueNumber,
+      field,
+      targetColumn,
+      targetColumnIndex: columnIndex,
+      section: section.kind,
+      lineNumber: row.lineNumber,
+      oldRow: row.raw,
+      newRow,
+      oldCells,
+      newCells,
+      oldValue: oldCells[columnIndex] ?? "",
+      newValue: value,
+      row: {
+        old: boardRowSummary(section, row),
+        new: {
+          ...boardRowSummary(section, { ...row, raw: newRow, cells: newCells }),
+          updatedField: field,
+        },
+      },
+      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 },
+      },
+    },
+  };
+}
+
+async function issueBoardRowList(repo: string, token: string, options: GitHubOptions): Promise<GitHubCommandResult> {
+  const commandName = "issue board-row list";
+  const boardIssue = await getIssue(token, repo, options.boardIssue);
+  if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue });
+  const parsed = parseBoardTables(boardIssue.body ?? "");
+  const rows = boardRowsForState(parsed.sections, options.listState);
+  return {
+    ok: true,
+    command: commandName,
+    repo,
+    dryRun: true,
+    readOnly: true,
+    boardIssue: {
+      number: boardIssue.number,
+      title: boardIssue.title,
+      state: boardIssue.state,
+      url: boardIssue.html_url,
+      bodyChars: (boardIssue.body ?? "").length,
+      bodySha: bodySha(boardIssue.body ?? ""),
+      updatedAt: boardIssue.updated_at ?? null,
+    },
+    state: options.listState,
+    count: rows.length,
+    rows: rows.map(({ section, row }) => boardRowSummary(section, row)),
+    sections: parsed.sections.map((section) => ({ kind: section.kind, heading: section.heading, headingLine: section.headingLine, headerLine: section.headerLine, headers: section.headers, rows: section.rows.length })),
+    rowValidationWarnings: parsed.warnings,
+    note: "Read-only board row list; no issue body was edited.",
+  };
+}
+
+async function issueBoardRowGet(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
+  const commandName = "issue board-row get";
+  const boardIssue = await getIssue(token, repo, options.boardIssue);
+  if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue, issueNumber });
+  const parsed = parseBoardTables(boardIssue.body ?? "");
+  const found = findBoardRow(repo, parsed.sections, issueNumber);
+  if (found.ok === false) return { ...found, command: commandName, repo, boardIssue: options.boardIssue };
+  return {
+    ok: true,
+    command: commandName,
+    repo,
+    dryRun: true,
+    readOnly: true,
+    boardIssue: {
+      number: boardIssue.number,
+      title: boardIssue.title,
+      state: boardIssue.state,
+      url: boardIssue.html_url,
+      bodyChars: (boardIssue.body ?? "").length,
+      bodySha: bodySha(boardIssue.body ?? ""),
+      updatedAt: boardIssue.updated_at ?? null,
+    },
+    issueNumber,
+    row: boardRowSummary(found.section, found.row),
+    rowValidationWarnings: parsed.warnings.filter((warning) => warning.issueNumber === issueNumber),
+    note: "Read-only board row get; no issue body was edited.",
+  };
+}
+
+async function issueBoardRowUpdate(repo: string, token: string, issueNumber: number, options: GitHubOptions): Promise<GitHubCommandResult> {
+  const commandName = "issue board-row update";
+  if (options.boardRowField === undefined) return validationError(commandName, repo, "issue board-row update requires --field progress|status|validation|branch|tasks|focus", { supportedFields: BOARD_ROW_FIELDS.slice() });
+  if (options.boardRowValue === undefined) return validationError(commandName, repo, "issue board-row update requires --value <text>", { issueNumber, field: options.boardRowField });
+  const valuePollutionEvidence = boardRowValuePollutionEvidence(options.boardRowValue);
+  if (valuePollutionEvidence.length > 0) {
+    return validationError(commandName, repo, "issue board-row update --value contains literal shell escape text that would pollute the board cell; pass real newlines or plain text instead", {
+      issueNumber,
+      field: options.boardRowField,
+      valuePreview: preview(options.boardRowValue),
+      shellPollution: { suspected: true, evidence: valuePollutionEvidence },
+    });
+  }
+  const concurrencyOptionError = assertConcurrencyOptions(options);
+  if (concurrencyOptionError !== null) return { ...concurrencyOptionError, command: commandName, repo };
+
+  const boardIssue = await getIssue(token, repo, options.boardIssue);
+  if (isGitHubError(boardIssue)) return commandError(commandName, repo, boardIssue, { boardIssue: options.boardIssue, issueNumber });
+  const parsed = parseBoardTables(boardIssue.body ?? "");
+  const planned = boardRowUpdatePlan(repo, boardIssue, issueNumber, options.boardRowField, options.boardRowValue, parsed);
+  if (planned.ok === false) return planned;
+  const guardError = boardBodySafetyIssue(repo, options.boardIssue, planned.newBody, options);
+  const guard = boardBodyGuardSummary(options.boardIssue, planned.newBody, options);
+  const effectiveDryRun = options.dryRun || (options.expectBodySha === undefined && options.expectUpdatedAt === undefined);
+  const base = {
+    ok: true,
+    command: commandName,
+    repo,
+    boardIssue: {
+      number: boardIssue.number,
+      title: boardIssue.title,
+      state: boardIssue.state,
+      url: boardIssue.html_url,
+      bodyChars: (boardIssue.body ?? "").length,
+      bodySha: bodySha(boardIssue.body ?? ""),
+      updatedAt: boardIssue.updated_at ?? null,
+    },
+    issueNumber,
+    dryRun: effectiveDryRun,
+    planned: true,
+    update: planned.plan,
+    guard,
+    bodyOnlySafety: {
+      oldBody: {
+        fetched: true,
+        bodyChars: (boardIssue.body ?? "").length,
+        bodySha: bodySha(boardIssue.body ?? ""),
+        updatedAt: boardIssue.updated_at ?? null,
+      },
+      newBody: {
+        bodyChars: planned.newBody.length,
+        bodySha: bodySha(planned.newBody),
+        ...bodySafetySignals(planned.newBody),
+      },
+    },
+    concurrency: {
+      expectUpdatedAt: options.expectUpdatedAt ?? null,
+      expectBodySha: options.expectBodySha ?? null,
+      note: "non-dry-run board-row update requires --expect-body-sha or --expect-updated-at and checks the current board issue before PATCH",
+    },
+  };
+  if (guardError !== null) return { ...guardError, command: commandName, update: planned.plan, guard };
+  if (effectiveDryRun) {
+    return {
+      ...base,
+      dryRun: true,
+      wouldPatch: { issueNumber: options.boardIssue, bodySha: bodySha(planned.newBody), bodyChars: planned.newBody.length },
+      note: options.expectBodySha === undefined && options.expectUpdatedAt === undefined
+        ? "Default dry-run because no concurrency expectation was supplied; no GitHub issue body was modified."
+        : "Dry-run only; no GitHub issue body was modified.",
+    };
+  }
+  const concurrencyError = validateIssueConcurrency(repo, options.boardIssue, boardIssue, options);
+  if (concurrencyError !== null) return { ...base, ...concurrencyError };
+  const { owner, name } = repoParts(repo);
+  const issue = await githubRequest<GitHubIssue>(token, "PATCH", `/repos/${owner}/${name}/issues/${options.boardIssue}`, { body: planned.newBody });
+  if (isGitHubError(issue)) return commandError(commandName, repo, issue, { issueNumber, update: planned.plan });
+  return {
+    ...base,
+    dryRun: false,
+    planned: false,
+    issue: issueSummary(issue),
+    concurrency: {
+      checked: true,
+      oldIssueUpdatedAt: boardIssue.updated_at ?? null,
+      oldBodySha: bodySha(boardIssue.body ?? ""),
+      expectUpdatedAt: options.expectUpdatedAt ?? null,
+      expectBodySha: options.expectBodySha ?? null,
+    },
+    rest: true,
+  };
+}
+
 function ignoredIssueList(issues: BoardIssueEntry[], ignoreMap: Map<number, "known-meta" | "ignored">): BoardIgnoredIssue[] {
  return sortedIssueEntries(issues.filter((issue) => ignoreMap.has(issue.number))).map((issue) => ({
    number: issue.number,
@@ -2921,6 +3327,10 @@ export function ghHelp(): unknown {
      "bun scripts/cli.ts gh issue scan-escape [--repo owner/name] [--limit N] [--dry-run]",
      "bun scripts/cli.ts gh issue cleanup-plan [--repo owner/name] [--limit N] [--dry-run]",
      "bun scripts/cli.ts gh issue board-audit [--repo owner/name] [--board-issue 20] [--limit N] [--known-meta-issue N[,N...]] [--ignore-issue N[,N...]] [--dry-run]",
+      "bun scripts/cli.ts gh issue board-row list [--repo owner/name] --board-issue 20 [--state open|closed|all] [--dry-run]",
+      "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 move|delete <issueNumber> [unsupported in first phase]",
      "bun scripts/cli.ts gh pr list [--repo owner/name] [--limit N] [--json number,title,state,url,updatedAt,createdAt,author,head,base,draft]",
      "bun scripts/cli.ts gh pr read <number> [--repo owner/name] [--json body,title,state,head,base,draft]",
      "bun scripts/cli.ts gh pr view <number> [--repo owner/name] [compatibility alias for pr read]",
@@ -2948,6 +3358,8 @@ export function ghHelp(): unknown {
      "For JSON request bodies in other CLI namespaces, prefer --body-file or --body-stdin over long inline shell arguments; GitHub Markdown writes intentionally use --body-file only.",
      "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.",
+      "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 move/delete are structured unsupported in this phase; open/closed relocation and row removal need explicit table placement and duplicate-row semantics before they write.",
      "issue edit 24 --notify-claudeqq-brief-diff 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.",
      "comment delete is supported because GitHub supports deleting issue comments; issue/pr hard delete is unsupported and close is the lifecycle alternative.",
@@ -2974,9 +3386,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, "--notify-claudeqq-brief-diff is only supported by gh issue edit 24");
  }
-  if (optionWasProvided(args, "--state") && !(top === "issue" && sub === "list")) {
+  if (optionWasProvided(args, "--state") && !(top === "issue" && (sub === "list" || sub === "board-row" && third === "list"))) {
    const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
-    return validationError(command, options.repo, "--state is only supported by gh issue list");
+    return validationError(command, options.repo, "--state is only supported by gh issue list and gh issue board-row list");
  }
  if (optionWasProvided(args, "--json") && !(top === "issue" && (isIssueReadCommand(sub) || sub === "list"))) {
    const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
@@ -2988,13 +3400,21 @@ 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"))) {
+  if ((options.allowShortBody || options.expectUpdatedAt !== undefined || options.expectBodySha !== undefined || optionWasProvided(args, "--body-profile")) && !(top === "issue" && (sub === "edit" || sub === "update" || sub === "board-row" && third === "update"))) {
    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");
+    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");
  }
-  if ((optionWasProvided(args, "--board-issue") || optionWasProvided(args, "--known-meta-issue") || optionWasProvided(args, "--ignore-issue")) && !(top === "issue" && sub === "board-audit")) {
+  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";
-    return validationError(command, options.repo, "--board-issue, --known-meta-issue, and --ignore-issue are only supported by gh issue board-audit");
+    return validationError(command, options.repo, "--board-issue, --known-meta-issue, and --ignore-issue are only supported by gh issue board-audit and --board-issue by gh issue board-row");
+  }
+  if ((optionWasProvided(args, "--known-meta-issue") || optionWasProvided(args, "--ignore-issue")) && !(top === "issue" && sub === "board-audit")) {
+    const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
+    return validationError(command, options.repo, "--known-meta-issue and --ignore-issue are only supported by gh issue board-audit");
+  }
+  if ((optionWasProvided(args, "--field") || optionWasProvided(args, "--value")) && !(top === "issue" && sub === "board-row" && third === "update")) {
+    const command = [top, sub, third].filter((value): value is string => value !== undefined).join(" ") || "gh";
+    return validationError(command, options.repo, "--field and --value are only supported by gh issue board-row update");
  }
  if (optionWasProvided(args, "--label") && !(top === "issue" && sub === "create")) {
    const command = [top, sub].filter((value): value is string => value !== undefined).join(" ") || "gh";
@@ -3036,6 +3456,33 @@ export async function runGhCommand(args: string[]): Promise<GitHubCommandResult
      if (missing !== null || token === null) return missing ?? authRequired(options.repo, "issue board-audit", { present: false, source: null, ghFallbackAttempted: true });
      return issueBoardAudit(options.repo, token, options);
    }
+    if (sub === "board-row") {
+      const action = third;
+      const commandName = `issue board-row ${action ?? ""}`.trim();
+      if (action === "move") {
+        return unsupportedCommand(commandName, options.repo, "board-row move is deferred in the first phase; open/closed row relocation needs explicit destination-section insertion rules, duplicate-row handling, and audit-safe closed/open semantics before it can write.", {
+          boardIssue: options.boardIssue,
+          boundary: "row list/get/update are supported; move between OPEN/CLOSED tables remains unsupported and performs no write",
+        });
+      }
+      if (action === "delete") {
+        return unsupportedCommand(commandName, options.repo, "board-row delete is deferred in the first phase; row removal needs an explicit archival/delete policy and duplicate-row guard before it can write.", {
+          boardIssue: options.boardIssue,
+          boundary: "row list/get/update are supported; delete remains unsupported and performs no write",
+        });
+      }
+      if (action !== "list" && action !== "get" && action !== "update") {
+        return unsupportedCommand(commandName, options.repo, "board-row supported commands are list, get, update, and structured unsupported move/delete.");
+      }
+      const { token, probe } = resolveToken(true);
+      const missing = authRequired(options.repo, commandName, probe);
+      if (missing !== null || token === null) return missing ?? authRequired(options.repo, commandName, { present: false, source: null, ghFallbackAttempted: true });
+      if (action === "list") return issueBoardRowList(options.repo, token, options);
+      const issueNumber = parseNumberForCommand(options.repo, args[3], commandName);
+      if (typeof issueNumber !== "number") return issueNumber;
+      if (action === "get") return issueBoardRowGet(options.repo, token, issueNumber, options);
+      return issueBoardRowUpdate(options.repo, token, issueNumber, options);
+    }
    if (options.dryRun) {
      if (sub === "create") return issueCreate(options.repo, "", options);
      if (sub === "edit") {