supipowers 2.0.1 → 2.1.0

package/src/harness/hooks/layer-context-inject.ts

@@ -31,6 +31,8 @@ import {
   getHarnessArchitectureDocPath,
   getHarnessMarkerPath,
 } from "../project-paths.js";
+import { extractAgentContextSection } from "../docs/validator.js";
+import { parseProvenance } from "../docs/provenance.js";
 
 export interface LayerContextHookOptions {
   /**
@@ -86,6 +88,13 @@ export interface LayerContextInjectionResult {
 /**
  * Compute the addendum for a single hook invocation. Pure-ish: reads the file system but
  * never mutates state. Tests call this directly with a known cwd + candidate file.
+ *
+ * Resolution order:
+ *   1. If `docs/layers/<layerId>.md` exists, extract its `## Agent context` section and
+ *      return it (capped at `addendum_max_chars`). This is the preferred path once the
+ *      docs stage has run.
+ *   2. Otherwise, fall back to the architecture-doc-derived addendum so projects that
+ *      have not generated per-layer docs still receive a useful reminder.
  */
 export function computeLayerAddendum(input: {
   cwd: string;
@@ -93,6 +102,8 @@ export function computeLayerAddendum(input: {
   config: HarnessHookConfig["layer_context_inject"];
   /** Override the resolved architecture-doc path; tests use this to point at a fixture. */
   archPath?: string;
+  /** Override the resolved per-layer doc path; tests use this to point at a fixture. */
+  layerDocPath?: (layerId: string) => string;
 }): LayerContextInjectionResult {
   if (!input.config.enabled) return { addendum: "", reason: "disabled" };
   if (!input.candidateFile) return { addendum: "", reason: "no candidate file" };
@@ -101,8 +112,31 @@ export function computeLayerAddendum(input: {
   if (rules.length === 0) return { addendum: "", reason: "no rules parsed" };
   const rule = resolveLayerForFile(input.candidateFile, rules);
   if (!rule) return { addendum: "", reason: "no rule matches candidate file" };
+
+  // Preferred path: per-layer agent doc.
+  const docPath = input.layerDocPath
+    ? input.layerDocPath(rule.layer)
+    : `${input.cwd}/docs/layers/${rule.layer}.md`;
+  if (fs.existsSync(docPath)) {
+    try {
+      const contents = fs.readFileSync(docPath, "utf8");
+      const parsed = parseProvenance(contents);
+      const body = parsed ? parsed.body : contents;
+      const section = extractAgentContextSection(body);
+      if (section.length > 0) {
+        const cap = input.config.addendum_max_chars;
+        const capped = section.length <= cap
+          ? section
+          : `${section.slice(0, Math.max(0, cap - 1))}…`;
+        return { addendum: capped, reason: "matched (per-layer doc)" };
+      }
+    } catch {
+      // fall through to architecture-doc fallback on any read error
+    }
+  }
+
   const addendum = buildLayerAddendum(input.candidateFile, rule, input.config.addendum_max_chars);
-  return { addendum, reason: "matched" };
+  return { addendum, reason: "matched (architecture.md fallback)" };
 }
 
 /**

package/src/harness/hooks/register.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Platform } from "../../platform/types.js";
-import type { HarnessConfig, HarnessHookConfig } from "../../types.js";
+import type { HarnessConfig, HarnessDocsConfig, HarnessHookConfig } from "../../types.js";
 import { buildBackendAdapter } from "../anti_slop/backend-factory.js";
 import {
   registerLayerContextInjectHook,
@@ -31,9 +31,21 @@ export const DEFAULT_HARNESS_HOOK_CONFIG: HarnessHookConfig = {
   score_floor: { strict: 75, lenient: 90, release_blocking: false },
 };
 
+export const DEFAULT_HARNESS_DOCS_CONFIG: HarnessDocsConfig = {
+  tier: "simple",
+  max_per_doc_loc: 150,
+  agent_context_loc: 30,
+  max_index_loc: 50,
+  max_units: 12,
+  max_concurrent_subagents: null,
+  drift_warning: { enabled: true },
+  regen_preview_threshold: 1,
+};
+
 export const DEFAULT_HARNESS_CONFIG: HarnessConfig = {
   anti_slop: DEFAULT_HARNESS_HOOK_CONFIG,
   implement_in_session_threshold: 10,
+  docs: DEFAULT_HARNESS_DOCS_CONFIG,
 };
 
 export interface HarnessHookRegistration {
@@ -54,19 +66,28 @@ export interface RegisterHooksOptions {
    * unless a real resolver is wired).
    */
   resolveCandidateFile?: (event: unknown, ctx: unknown) => string | null;
+  /** CWD whose repo-local marker controls registration. Defaults to process.cwd(). */
+  cwd?: string;
 }
 
 // Re-export so existing call sites keep working without an import path change.
 export { buildBackendAdapter };
 
 /**
- * Register every harness hook. Idempotent at the dispose boundary: calling
- * `dispose()` twice is safe.
+ * Register every harness hook. Hooks subscribe unconditionally at bootstrap time; each
+ * hook checks the repo-local marker per event, so creating the marker after install
+ * activates already-registered handlers without an OMP restart, and removing the marker
+ * disables them. `dispose()` is idempotent.
+ *
+ * The `cwd` option is retained for tests that exercise the legacy marker check; it is
+ * unused by the new registration path because per-event handlers resolve cwd from the
+ * event payload.
  */
 export function registerHarnessHooks(
   platform: Platform,
   options: RegisterHooksOptions = {},
 ): HarnessHookRegistration {
+  void options.cwd; // reserved for future per-repo gating
   const backend = options.backend ?? "fallow";
   const hooks = options.hooks ?? DEFAULT_HARNESS_HOOK_CONFIG;
   const adapter = buildBackendAdapter(backend);

package/src/harness/pipeline.ts

@@ -31,6 +31,7 @@ import {
 } from "./stages/design.js";
 import { HarnessPlanStage, type PlanStageInput } from "./stages/plan.js";
 import { HarnessImplementStage, type ImplementStageInput } from "./stages/implement.js";
+import { HarnessDocsStage, type DocsStageInput } from "./stages/docs.js";
 import { HarnessValidateStage, type ValidateStageInput } from "./stages/validate.js";
 import { loadHarnessDesignSpecJson, loadHarnessDiscover } from "./storage.js";
 import { buildBackendAdapter } from "./anti_slop/backend-factory.js";
@@ -52,6 +53,7 @@ const STAGE_ORDER: readonly HarnessStage[] = [
   "design",
   "plan",
   "implement",
+  "docs",
   "validate",
 ];
 
@@ -60,6 +62,7 @@ const GATE_STAGES_DEFAULT: ReadonlySet<HarnessStage> = new Set([
   "discover",
   "design",
   "plan",
+  "docs",
   "validate",
 ]);
 const GATE_STAGES_MANUAL: ReadonlySet<HarnessStage> = new Set([
@@ -68,6 +71,7 @@ const GATE_STAGES_MANUAL: ReadonlySet<HarnessStage> = new Set([
   "design",
   "plan",
   "implement",
+  "docs",
   "validate",
 ]);
 
@@ -89,6 +93,8 @@ export interface BuildRunnerInput {
   planInput?: PlanStageInput;
   /** Required when running the implement stage. */
   implementInput?: ImplementStageInput;
+  /** Optional override for the docs stage (tier, max-units, test-only factories). */
+  docsInput?: DocsStageInput;
   /** Required when running the validate stage. */
   validateInput?: ValidateStageInput;
 }
@@ -111,6 +117,8 @@ export function buildHarnessRunner(stage: HarnessStage, input: BuildRunnerInput)
         throw new Error("buildHarnessRunner: implement stage requires implementInput");
       }
       return new HarnessImplementStage(input.implementInput);
+    case "docs":
+      return new HarnessDocsStage(input.docsInput ?? {});
     case "validate":
       if (!input.validateInput) {
         throw new Error("buildHarnessRunner: validate stage requires validateInput");
@@ -215,6 +223,15 @@ function formatStageDetail(result: HarnessStageRunResult): string {
     const layers = typeof d.layerCount === "number" ? `${d.layerCount} layers` : "";
     return layers ? `${backend} · ${layers}` : `${backend}`;
   }
+  if (result.stage === "docs") {
+    const regen = Array.isArray(d.regenerated) ? (d.regenerated as string[]).length : 0;
+    const skip = Array.isArray(d.skipped) ? (d.skipped as string[]).length : 0;
+    const user = Array.isArray(d.userEdited) ? (d.userEdited as string[]).length : 0;
+    if (typeof d.tier === "string" && d.tier === "extensive") {
+      return `${regen} regen · ${skip} skip${user > 0 ? ` · ${user} user-edited` : ""}`;
+    }
+    if (typeof d.reason === "string") return d.reason;
+  }
   if (result.stage === "validate" && typeof d.passed === "boolean") {
     return d.passed ? "passed" : "issues found";
   }
@@ -279,9 +296,9 @@ export async function runHarnessPipelineUntilGate(
 
     const result = await runner.run(ctx);
 
-    // In auto mode, awaiting-user is equivalent to completed — normalize
-    // both the trace entry and any outcome derived from it so the UI never
-    // shows a confusing mix of checkmarks and "awaiting user".
+    // In auto mode, awaiting-user from authoring stages (design, etc.) is equivalent to
+    // completed: the artifact is on disk and the next stage can consume it. Gates honor
+    // awaiting-user as a real stop signal.
     const isGate = gateStages.has(stage);
     const normalizedStatus: HarnessStageRunResult["status"] =
       result.status === "awaiting-user" && !isGate
@@ -307,8 +324,6 @@ export async function runHarnessPipelineUntilGate(
       };
     }
 
-    // In auto mode, awaiting-user is equivalent to completed — the pipeline
-    // continues without stopping. Only surface the distinction when gated.
     if (normalizedStatus === "awaiting-user" && isGate) {
       input.onProgress?.({ type: "awaiting-user", stage, detail: awaitUserDetail(result) });
     } else {

package/src/harness/pr-comment/baseline.ts

@@ -0,0 +1,105 @@
+/**
+ * Load the trend baseline from `score-history.jsonl`.
+ *
+ * The validate stage appends one record per run to this file. We split that history
+ * into:
+ *   - `previousScore`: the most recent prior entry (so we can compute a delta vs the
+ *     score we just wrote), or null when there is nothing to compare against;
+ *   - `trend`: the last N entries oldest-first, for the inline sparkline.
+ *
+ * Score-history v1 records are `{ recordedAt, sessionId, strict, lenient }` (see
+ * `src/harness/stages/validate.ts`). Per-dimension breakdowns are NOT persisted, so we
+ * surface them as `undefined` and the renderer shows "—" for the dimension Δ column.
+ */
+
+import type { PlatformPaths } from "../../platform/types.js";
+import type { UltraPlanStorageResult } from "../../types.js";
+import { readJsonl } from "../storage.js";
+import { getHarnessScoreHistoryPath } from "../project-paths.js";
+import type { PrCommentPreviousScore, PrCommentTrendPoint } from "./types.js";
+
+/** Raw score-history record as written by Validate. */
+interface ScoreHistoryRecord {
+  recordedAt: string;
+  sessionId: string;
+  strict: number;
+  lenient: number;
+}
+
+export interface Baseline {
+  /** Most recent prior entry. null when history is empty or has only one record. */
+  previousScore: PrCommentPreviousScore | null;
+  /** Last `limit` entries, oldest first. Empty when no history. */
+  trend: readonly PrCommentTrendPoint[];
+}
+
+const DEFAULT_TREND_LIMIT = 5;
+
+/**
+ * Read score-history.jsonl and split it into (previous, trend).
+ *
+ * `currentSessionId` is what just ran — we drop ALL trailing records that match it so we
+ * never compare a score against itself, even when validate is re-run for the same session.
+ *
+ * Returns an empty baseline (`previousScore: null`, `trend: []`) when the history file is
+ * missing or unreadable. We deliberately swallow IO errors here: a corrupted history file
+ * should degrade gracefully to "no baseline" rather than block PR comment generation.
+ */
+export function loadBaseline(
+  paths: PlatformPaths,
+  cwd: string,
+  options: { currentSessionId?: string; limit?: number } = {},
+): Baseline {
+  const limit = options.limit ?? DEFAULT_TREND_LIMIT;
+  const result: UltraPlanStorageResult<ScoreHistoryRecord[]> = readJsonl<ScoreHistoryRecord>(
+    getHarnessScoreHistoryPath(paths, cwd),
+  );
+  if (!result.ok) {
+    return { previousScore: null, trend: [] };
+  }
+  const records = result.value.filter((record) => isWellFormed(record));
+
+  // Strip the trailing run(s) that belong to the current session so we compare against the
+  // PRIOR run. When currentSessionId is omitted (local dry-run with no session context),
+  // we treat the most recent record as the baseline.
+  let priorEnd = records.length;
+  if (options.currentSessionId) {
+    while (priorEnd > 0 && records[priorEnd - 1].sessionId === options.currentSessionId) {
+      priorEnd -= 1;
+    }
+  }
+
+  const previousRecord = priorEnd > 0 ? records[priorEnd - 1] : null;
+  const previousScore: PrCommentPreviousScore | null = previousRecord
+    ? {
+        recordedAt: previousRecord.recordedAt,
+        strict: previousRecord.strict,
+        lenient: previousRecord.lenient,
+      }
+    : null;
+
+  // Trend is the last `limit` records oldest-first. We include the current run so the
+  // sparkline ends with the just-computed score; the renderer can choose whether to
+  // highlight it.
+  const trendSlice = records.slice(Math.max(0, records.length - limit));
+  const trend: PrCommentTrendPoint[] = trendSlice.map((record) => ({
+    ts: record.recordedAt,
+    strict: record.strict,
+    lenient: record.lenient,
+  }));
+
+  return { previousScore, trend };
+}
+
+function isWellFormed(record: unknown): record is ScoreHistoryRecord {
+  if (record === null || typeof record !== "object") return false;
+  const r = record as Record<string, unknown>;
+  return (
+    typeof r.recordedAt === "string" &&
+    typeof r.sessionId === "string" &&
+    typeof r.strict === "number" &&
+    typeof r.lenient === "number" &&
+    Number.isFinite(r.strict) &&
+    Number.isFinite(r.lenient)
+  );
+}

package/src/harness/pr-comment/ci-env.ts

@@ -0,0 +1,120 @@
+/**
+ * GitHub Actions environment detection for the PR comment subcommand.
+ *
+ * The harness PR comment workflow runs in two contexts:
+ *   - inside GitHub Actions on a `pull_request` event (real CI run), and
+ *   - locally for `--dry-run` previews and ad-hoc testing.
+ *
+ * This module owns the detection of the former. It deliberately does no IO except reading
+ * a single event JSON file when `GITHUB_EVENT_PATH` is provided.
+ */
+
+import * as fs from "node:fs";
+
+export interface CiContext {
+  /** "owner/repo" — extracted from GITHUB_REPOSITORY or supplied via flag. */
+  repo: string;
+  /** PR number — from the event payload or the --pr flag. */
+  prNumber: number;
+  /** Optional run URL, used in the comment footer. */
+  runUrl?: string;
+  /** Optional base ref, e.g. "main@a1b2c3d", used in the summary line. */
+  baseRef?: string;
+}
+
+/** Manual overrides parsed from CLI flags; flag values win over env. */
+export interface CiContextOverrides {
+  repo?: string;
+  prNumber?: number;
+}
+
+/**
+ * Detect the CI context from environment variables, applying optional overrides on top.
+ *
+ * Returns null when neither the env nor the overrides produce a complete `{repo, prNumber}`
+ * pair — that's how the handler decides to fall back to the workflow summary.
+ */
+export function detectCiContext(
+  env: NodeJS.ProcessEnv = process.env,
+  overrides: CiContextOverrides = {},
+): CiContext | null {
+  const repo = overrides.repo ?? env.GITHUB_REPOSITORY;
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+    if (!repo) return null;
+    // Malformed repo string (e.g. missing slash). Return null rather than corrupting URLs.
+    return null;
+  }
+
+  let prNumber = overrides.prNumber;
+  let baseRef: string | undefined;
+  if (prNumber === undefined) {
+    const fromEvent = readPullRequestFromEvent(env);
+    if (fromEvent) {
+      prNumber = fromEvent.prNumber;
+      baseRef = fromEvent.baseRef;
+    }
+  }
+  if (prNumber === undefined || !Number.isFinite(prNumber) || prNumber <= 0) {
+    return null;
+  }
+
+  const runUrl = buildRunUrl(env, repo);
+  const ctx: CiContext = { repo, prNumber };
+  if (runUrl) ctx.runUrl = runUrl;
+  if (baseRef) ctx.baseRef = baseRef;
+  return ctx;
+}
+
+interface PullRequestEventFields {
+  prNumber: number;
+  baseRef?: string;
+}
+
+function readPullRequestFromEvent(env: NodeJS.ProcessEnv): PullRequestEventFields | null {
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (!eventPath) return null;
+  let raw: string;
+  try {
+    raw = fs.readFileSync(eventPath, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const obj = parsed as Record<string, unknown>;
+  const pr = obj.pull_request;
+  if (pr === null || typeof pr !== "object") {
+    // Some events (issue_comment on a PR) carry `issue.pull_request` instead. We only
+    // support the `pull_request` event in v1; everything else returns null.
+    return null;
+  }
+  const prRecord = pr as Record<string, unknown>;
+  const number = prRecord.number;
+  if (typeof number !== "number" || !Number.isFinite(number)) return null;
+
+  let baseRef: string | undefined;
+  const base = prRecord.base;
+  if (base && typeof base === "object") {
+    const baseRecord = base as Record<string, unknown>;
+    const ref = baseRecord.ref;
+    const sha = baseRecord.sha;
+    if (typeof ref === "string" && typeof sha === "string") {
+      baseRef = `${ref}@${sha.slice(0, 7)}`;
+    } else if (typeof ref === "string") {
+      baseRef = ref;
+    }
+  }
+  return { prNumber: number, baseRef };
+}
+
+function buildRunUrl(env: NodeJS.ProcessEnv, repo: string): string | undefined {
+  const server = env.GITHUB_SERVER_URL;
+  const runId = env.GITHUB_RUN_ID;
+  if (!server || !runId) return undefined;
+  return `${server}/${repo}/actions/runs/${runId}`;
+}

package/src/harness/pr-comment/gh-poster.ts

@@ -0,0 +1,227 @@
+/**
+ * `gh` CLI wrapper for the harness PR sticky comment.
+ *
+ * Fail-open by design: every failure path returns a typed `PostOutcome` instead of
+ * throwing, so the caller can decide whether to surface a workflow-summary fallback. The
+ * pipeline never blocks on PR-comment posting.
+ *
+ * Pattern mirrors `src/fix-pr/fetch-comments.ts` and `src/release/channels/github.ts`:
+ * we never construct an Octokit client; `platform.exec("gh", [...])` is the only
+ * dependency.
+ */
+
+import type { Platform } from "../../platform/types.js";
+import { parseMarker, STICKY_MARKER_PREFIX } from "./status.js";
+import type { PrCommentStatus } from "./types.js";
+
+/** Outcome of an upsert attempt. */
+export type PostOutcome =
+  | { kind: "created"; commentId: number }
+  | { kind: "updated"; commentId: number }
+  | { kind: "unchanged"; commentId: number; reason: "status-unchanged" }
+  | { kind: "skipped"; reason: "no-auth" | "no-cli" | "no-pr-env" }
+  | { kind: "failed"; reason: string };
+
+export interface PostStickyOptions {
+  repo: string;
+  prNumber: number;
+  cwd: string;
+  body: string;
+  mode: "every-push" | "on-status-change";
+  currentStatus: PrCommentStatus;
+}
+
+/**
+ * Idempotent upsert of the sticky comment.
+ *
+ *  1. Verify `gh` is installed and authenticated.
+ *  2. List PR comments; find the first whose body starts with the harness marker prefix.
+ *  3. When `mode === "on-status-change"`, parse the previous status; bail with `unchanged`
+ *     when it matches `currentStatus`.
+ *  4. PATCH the existing comment, or POST a new one when nothing matched.
+ */
+export async function postStickyComment(
+  platform: Platform,
+  options: PostStickyOptions,
+): Promise<PostOutcome> {
+  const { repo, prNumber, cwd, body, mode, currentStatus } = options;
+
+  const auth = await checkAuth(platform, cwd);
+  if (auth.kind !== "ok") return auth;
+
+  const existing = await findStickyComment(platform, repo, prNumber, cwd);
+  if (existing.kind === "failed") return existing;
+
+  if (existing.kind === "found") {
+    if (mode === "on-status-change") {
+      const parsed = parseMarker(existing.body);
+      if (parsed && parsed.status === currentStatus) {
+        return { kind: "unchanged", commentId: existing.id, reason: "status-unchanged" };
+      }
+    }
+    const patched = await patchComment(platform, repo, existing.id, body, cwd);
+    return patched;
+  }
+
+  // No sticky yet — create one.
+  return createComment(platform, repo, prNumber, body, cwd);
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+async function checkAuth(
+  platform: Platform,
+  cwd: string,
+): Promise<{ kind: "ok" } | { kind: "skipped"; reason: "no-auth" | "no-cli" }> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec("gh", ["auth", "status"], { cwd });
+  } catch {
+    // ENOENT (gh missing) or other spawn-time failure — treat as no-cli.
+    return { kind: "skipped", reason: "no-cli" };
+  }
+  if (result.code === 0) return { kind: "ok" };
+  return { kind: "skipped", reason: "no-auth" };
+}
+
+type FindResult =
+  | { kind: "found"; id: number; body: string }
+  | { kind: "not-found" }
+  | { kind: "failed"; reason: string };
+
+async function findStickyComment(
+  platform: Platform,
+  repo: string,
+  prNumber: number,
+  cwd: string,
+): Promise<FindResult> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "--paginate",
+        `repos/${repo}/issues/${prNumber}/comments`,
+        "--jq",
+        ".[] | {id, body}",
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return {
+      kind: "failed",
+      reason: result.stderr.trim() || `gh api exited with code ${result.code}`,
+    };
+  }
+  // `--jq '.[] | {id, body}'` emits one JSON object per line (NOT a JSON array). Crucially,
+  // bodies may contain newlines — the `--jq` filter on a *list* shouldn't, because jq's
+  // default emits compact JSON for objects, but we still parse defensively.
+  for (const line of splitJsonObjects(result.stdout)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (parsed === null || typeof parsed !== "object") continue;
+    const obj = parsed as { id?: unknown; body?: unknown };
+    if (typeof obj.id !== "number" || typeof obj.body !== "string") continue;
+    if (obj.body.startsWith(STICKY_MARKER_PREFIX)) {
+      return { kind: "found", id: obj.id, body: obj.body };
+    }
+  }
+  return { kind: "not-found" };
+}
+
+async function createComment(
+  platform: Platform,
+  repo: string,
+  prNumber: number,
+  body: string,
+  cwd: string,
+): Promise<PostOutcome> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "-X", "POST",
+        `repos/${repo}/issues/${prNumber}/comments`,
+        "-f", `body=${body}`,
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return { kind: "failed", reason: result.stderr.trim() || `gh api POST exited with code ${result.code}` };
+  }
+  const id = extractCommentId(result.stdout);
+  if (id === null) {
+    return { kind: "failed", reason: "gh api POST succeeded but response is missing comment id" };
+  }
+  return { kind: "created", commentId: id };
+}
+
+async function patchComment(
+  platform: Platform,
+  repo: string,
+  commentId: number,
+  body: string,
+  cwd: string,
+): Promise<PostOutcome> {
+  let result: Awaited<ReturnType<Platform["exec"]>>;
+  try {
+    result = await platform.exec(
+      "gh",
+      [
+        "api",
+        "-X", "PATCH",
+        `repos/${repo}/issues/comments/${commentId}`,
+        "-f", `body=${body}`,
+      ],
+      { cwd },
+    );
+  } catch (error) {
+    return { kind: "failed", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (result.code !== 0) {
+    return { kind: "failed", reason: result.stderr.trim() || `gh api PATCH exited with code ${result.code}` };
+  }
+  return { kind: "updated", commentId };
+}
+
+function extractCommentId(stdout: string): number | null {
+  try {
+    const parsed = JSON.parse(stdout);
+    if (parsed && typeof parsed === "object" && typeof (parsed as { id?: unknown }).id === "number") {
+      return (parsed as { id: number }).id;
+    }
+  } catch {
+    // Fall through to regex scan; gh api can be configured with --jq for partial outputs.
+  }
+  const match = /"id"\s*:\s*(\d+)/.exec(stdout);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Split jq stream output into individual JSON object strings. jq's stream mode separates
+ * objects with a single newline, but body fields may contain unescaped newlines when the
+ * comment uses raw markdown. We rely on `JSON.parse` to validate each candidate and fall
+ * back to a line-based split.
+ */
+function splitJsonObjects(raw: string): string[] {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return [];
+  // Fast path: each line is its own object (the common case for `--jq '.[] | {id, body}'`).
+  const lines = trimmed.split(/\n(?=\{)/).map((s) => s.trim()).filter((s) => s.length > 0);
+  return lines;
+}