supipowers 2.0.2 → 2.1.0

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

@@ -0,0 +1,198 @@
+/**
+ * Handler for `/supi:harness pr-comment`.
+ *
+ * Resolves a validate report → baseline → CI context → renders → posts (or writes a
+ * step-summary fallback). Always notifies the UI with a one-line outcome; never throws.
+ *
+ * Flags (parsed via `parseFlags`):
+ *   --dry-run                  Print the body to stdout/UI, no `gh` call, no env required.
+ *   --pr=<n>                   Override PR number (otherwise read from env).
+ *   --repo=<owner>/<repo>      Override repo (otherwise read from GITHUB_REPOSITORY).
+ *   --session=<id>             Override which session's validate report we render.
+ *   --mode=every-push|on-status-change
+ *                              Override the config-supplied posting cadence.
+ */
+
+import type { Platform } from "../../platform/types.js";
+import type { HarnessCommandContext } from "../command.js";
+import {
+  listHarnessSessions,
+  loadHarnessDesignSpecJson,
+  loadHarnessValidateReport,
+} from "../storage.js";
+import { renderHarnessPrComment } from "./render.js";
+import { loadBaseline } from "./baseline.js";
+import { detectCiContext } from "./ci-env.js";
+import { postStickyComment } from "./gh-poster.js";
+import { STICKY_MARKER_PREFIX } from "./status.js";
+import { writeStepSummary } from "./workflow-summary.js";
+
+interface ParsedFlags {
+  dryRun: boolean;
+  prNumber?: number;
+  repo?: string;
+  sessionId?: string;
+  mode?: "every-push" | "on-status-change";
+}
+
+/** Default floor used when no design spec exists yet (purely defensive). */
+const DEFAULT_SCORE_FLOOR = { strict: 75, lenient: 90 } as const;
+
+/** Default mode when neither flag nor config supplies one. */
+const DEFAULT_MODE = "every-push" satisfies NonNullable<ParsedFlags["mode"]>;
+
+export async function handlePrComment(
+  platform: Platform,
+  ctx: HarnessCommandContext,
+  args: readonly string[],
+): Promise<void> {
+  const flags = parseFlags(args);
+
+  // 1. Pick the session.
+  const sessionId = flags.sessionId ?? listHarnessSessions(platform.paths, ctx.cwd)[0];
+  if (!sessionId) {
+    ctx.ui.notify(
+      "No harness session found. Run `/supi:harness validate` first or pass --session=<id>.",
+      "error",
+    );
+    return;
+  }
+
+  // 2. Load the validate report.
+  const reportResult = loadHarnessValidateReport(platform.paths, ctx.cwd, sessionId);
+  if (!reportResult.ok) {
+    ctx.ui.notify(
+      `Cannot read validate report for session ${sessionId}: ${reportResult.error.message}`,
+      "error",
+    );
+    return;
+  }
+  const report = reportResult.value;
+
+  // 3. Load baseline + score floor + config-supplied mode from the design spec.
+  const baseline = loadBaseline(platform.paths, ctx.cwd, { currentSessionId: sessionId });
+  const designSpec = loadHarnessDesignSpecJson(platform.paths, ctx.cwd, sessionId);
+  const scoreFloor = designSpec.ok ? designSpec.value.antiSlop.hooks.score_floor : DEFAULT_SCORE_FLOOR;
+  const configMode = designSpec.ok ? designSpec.value.ci.prComment?.mode : undefined;
+  const enabled = designSpec.ok ? designSpec.value.ci.prComment?.enabled !== false : true;
+  if (!enabled && !flags.dryRun) {
+    ctx.ui.notify(
+      "PR comments are disabled in this harness design spec (ci.prComment.enabled=false).",
+      "info",
+    );
+    return;
+  }
+
+  const mode = flags.mode ?? configMode ?? DEFAULT_MODE;
+
+  // 4. CI context (flag overrides > env). For --dry-run we tolerate a missing context.
+  const ciContext = detectCiContext(process.env, {
+    repo: flags.repo,
+    prNumber: flags.prNumber,
+  });
+
+  // 5. Render.
+  const rendered = renderHarnessPrComment({
+    report,
+    previousScore: baseline.previousScore,
+    trend: baseline.trend,
+    scoreFloor: { strict: scoreFloor.strict, lenient: scoreFloor.lenient },
+    sessionId,
+    generatedAt: new Date().toISOString(),
+    runUrl: ciContext?.runUrl,
+    baseRef: ciContext?.baseRef,
+  });
+
+  // 6. Branch on transport.
+  if (flags.dryRun) {
+    ctx.ui.notify(`PR comment preview (status=${rendered.status}):\n\n${rendered.body}`, "info");
+    return;
+  }
+
+  if (!ciContext) {
+    // No PR context — fall back to the step summary unconditionally. This is the
+    // expected path on `push` events that should not post a PR comment.
+    const summary = writeStepSummary(rendered.body);
+    if (summary.ok && summary.path) {
+      ctx.ui.notify(`No PR context; wrote summary to ${summary.path}.`, "info");
+    } else if (summary.ok) {
+      ctx.ui.notify("Skipped: no PR context and no GITHUB_STEP_SUMMARY available.", "info");
+    } else {
+      ctx.ui.notify(`Skipped: ${summary.reason ?? "no PR context"}`, "warning");
+    }
+    return;
+  }
+
+  const outcome = await postStickyComment(platform, {
+    repo: ciContext.repo,
+    prNumber: ciContext.prNumber,
+    cwd: ctx.cwd,
+    body: rendered.body,
+    mode,
+    currentStatus: rendered.status,
+  });
+
+  switch (outcome.kind) {
+    case "created":
+      ctx.ui.notify(`PR comment created (id=${outcome.commentId}).`, "info");
+      return;
+    case "updated":
+      ctx.ui.notify(`PR comment updated (id=${outcome.commentId}).`, "info");
+      return;
+    case "unchanged":
+      ctx.ui.notify(`PR comment unchanged (status still ${rendered.status}, id=${outcome.commentId}).`, "info");
+      return;
+    case "skipped":
+    case "failed": {
+      // Fail-open: write the body to the workflow summary so the run page still has the
+      // report, then notify with a warning (not an error — this is auxiliary signal).
+      const summary = writeStepSummary(rendered.body);
+      const fallback = summary.ok && summary.path ? ` (summary at ${summary.path})` : "";
+      const reason = outcome.kind === "failed" ? outcome.reason : outcome.reason;
+      ctx.ui.notify(`PR comment ${outcome.kind}: ${reason}.${fallback}`, "warning");
+      return;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Flag parsing
+// ---------------------------------------------------------------------------
+
+function parseFlags(args: readonly string[]): ParsedFlags {
+  const flags: ParsedFlags = { dryRun: false };
+  for (const arg of args) {
+    if (arg === "--dry-run") {
+      flags.dryRun = true;
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq === -1) continue;
+    const name = arg.slice(0, eq);
+    const value = arg.slice(eq + 1);
+    switch (name) {
+      case "--pr": {
+        const n = Number(value);
+        if (Number.isFinite(n) && n > 0) flags.prNumber = n;
+        break;
+      }
+      case "--repo":
+        flags.repo = value;
+        break;
+      case "--session":
+        flags.sessionId = value;
+        break;
+      case "--mode":
+        if (value === "every-push" || value === "on-status-change") flags.mode = value;
+        break;
+      default:
+        // Unknown flag — ignored. The dispatcher already filters by subcommand name.
+        break;
+    }
+  }
+  return flags;
+}
+
+// Suppress unused-import warning for STICKY_MARKER_PREFIX — re-exported indirectly for
+// downstream consumers that import from this module.
+void STICKY_MARKER_PREFIX;

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

@@ -0,0 +1,297 @@
+/**
+ * Pure renderer for the harness PR sticky comment.
+ *
+ * No IO, no clock — every output depends only on `input`. This makes the renderer
+ * exhaustively unit-testable and reproducible. All UI lives here; the gh poster is a
+ * dumb pipe.
+ *
+ * Layout (Proposal A, locked in design conversation):
+ *   1. marker line (HTML comment, machine-parseable)
+ *   2. status banner (emoji + score + delta + blocked flag)
+ *   3. one-sentence summary
+ *   4. failed checks (auto-expanded <details open>) — per-check invariant + finding table
+ *   5. passed checks (collapsed <details>) — single-line list
+ *   6. scorecard table — dimensions × {score, Δ, open, resolved, wontfix}
+ *   7. optional trend line / collapsible
+ *   8. footer h6 — floor · session · links · attribution
+ */
+
+import type {
+  HarnessScoreDimension,
+  HarnessValidateCheck,
+  HarnessValidateFinding,
+  HarnessValidateReport,
+} from "../../types.js";
+import { deriveStatus, renderMarker } from "./status.js";
+import type {
+  PrCommentDimensionDelta,
+  PrCommentPreviousScore,
+  PrCommentStatus,
+  PrCommentTrendPoint,
+  RenderInput,
+  RenderResult,
+} from "./types.js";
+
+const STATUS_EMOJI: Readonly<Record<PrCommentStatus, string>> = {
+  passed: "🟢",
+  warned: "🟡",
+  failed: "🔴",
+};
+
+const SEVERITY_EMOJI: Readonly<Record<HarnessValidateFinding["severity"], string>> = {
+  error: "🛑",
+  warning: "⚠",
+  info: "ℹ",
+};
+
+const DIMENSION_LABELS: Readonly<Record<HarnessScoreDimension["name"], string>> = {
+  duplicates: "Duplicates",
+  deadCode: "Dead code",
+  layerViolations: "Layer violations",
+  other: "Other",
+};
+
+/** Render a complete PR comment body for a validate report. */
+export function renderHarnessPrComment(input: RenderInput): RenderResult {
+  const status = deriveStatus(input.report);
+  const scoreDelta = computeScoreDelta(input.report.score.strict, input.previousScore);
+  const dimensionDeltas = computeDimensionDeltas(
+    input.report.score.dimensions,
+    input.previousScore?.dimensions ?? null,
+  );
+
+  const marker = renderMarker({
+    status,
+    strict: input.report.score.strict,
+    lenient: input.report.score.lenient,
+    sessionId: input.sessionId,
+    generatedAt: input.generatedAt,
+  });
+
+  const sections: string[] = [
+    marker,
+    "",
+    renderBanner(input, status, scoreDelta),
+    "",
+    renderSummaryLine(input, status),
+    "",
+  ];
+
+  const failed = input.report.checks.filter((check) => !check.passed);
+  const passed = input.report.checks.filter((check) => check.passed);
+
+  if (failed.length > 0) {
+    sections.push(renderFailedChecks(failed, input.report));
+    sections.push("");
+  }
+
+  if (passed.length > 0) {
+    sections.push(renderPassedChecks(passed, failed.length === 0));
+    sections.push("");
+  }
+
+  sections.push(renderScorecard(input.report.score.dimensions, dimensionDeltas));
+  sections.push("");
+
+  const trendSection = renderTrend(input.trend, status);
+  if (trendSection) {
+    sections.push(trendSection);
+    sections.push("");
+  }
+
+  sections.push(renderFooter(input));
+
+  return {
+    body: sections.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n",
+    marker,
+    status,
+    scoreDelta,
+    dimensionDeltas,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Section renderers
+// ---------------------------------------------------------------------------
+
+function renderBanner(input: RenderInput, status: PrCommentStatus, scoreDelta: number): string {
+  const emoji = STATUS_EMOJI[status];
+  const score = input.report.score;
+  const deltaText = scoreDelta === 0 ? "" : ` · \`${formatSignedDelta(scoreDelta)}\``;
+  const blockedSuffix = status === "failed" ? " · **blocked**" : "";
+  return `## ${emoji} Harness · score **${score.strict}** / **${score.lenient}** strict${deltaText}${blockedSuffix}`;
+}
+
+function renderSummaryLine(input: RenderInput, status: PrCommentStatus): string {
+  const report = input.report;
+  const failedCount = report.checks.filter((c) => !c.passed).length;
+  const passedCount = report.checks.filter((c) => c.passed).length;
+  const totalNewSlop =
+    report.slopScan.duplicates +
+    report.slopScan.deadCode +
+    report.slopScan.layerViolations +
+    report.slopScan.other;
+
+  const parts: string[] = [];
+  if (status === "passed") {
+    parts.push(`All ${passedCount + failedCount} checks passed.`);
+    parts.push(totalNewSlop === 0 ? "No new slop." : `${totalNewSlop} slop finding(s).`);
+  } else {
+    if (failedCount > 0) {
+      parts.push(`${failedCount} check${failedCount === 1 ? "" : "s"} failed`);
+    }
+    if (totalNewSlop > 0) {
+      parts.push(`${totalNewSlop} new slop finding${totalNewSlop === 1 ? "" : "s"}`);
+    }
+    if (!report.scoreFloorPassed) {
+      parts.push(`strict score below floor (${input.scoreFloor.strict})`);
+    }
+  }
+  if (input.baseRef) parts.push(`Base: \`${input.baseRef}\``);
+  // Join with `·` for status==passed (period-separated reads weird), but with " · " for
+  // failure rows so the eye treats them as distinct facts.
+  return parts.join(status === "passed" ? " " : " · ") + (status === "passed" ? "" : ".");
+}
+
+function renderFailedChecks(failed: readonly HarnessValidateCheck[], report: HarnessValidateReport): string {
+  const blocks: string[] = [];
+  blocks.push(`<details open><summary><strong>Failed checks (${failed.length})</strong></summary>`);
+  blocks.push("");
+  for (const check of failed) {
+    blocks.push(`#### ❌ ${check.name}`);
+    blocks.push(`**Invariant**: ${check.invariant}`);
+    blocks.push(`**What broke**: ${escapeInline(check.summary)}`);
+    if (check.name === "anti-slop-scan") {
+      // The report carries counters but not the queue entries themselves. Surface the
+      // counters and point the reader at the backlog command for actionable detail.
+      const slop = report.slopScan;
+      blocks.push("");
+      blocks.push("| Kind | Count |");
+      blocks.push("|---|---:|");
+      blocks.push(`| Duplicates | ${slop.duplicates} |`);
+      blocks.push(`| Dead code | ${slop.deadCode} |`);
+      blocks.push(`| Layer violations | ${slop.layerViolations} |`);
+      blocks.push(`| Other | ${slop.other} |`);
+      blocks.push("");
+      blocks.push("Run `/supi:harness next` to start triage, or `/supi:harness backlog` for the full queue.");
+    } else if (check.findings.length > 0) {
+      blocks.push("");
+      blocks.push(renderFindingTable(check.findings));
+    }
+    blocks.push("");
+  }
+  blocks.push("</details>");
+  return blocks.join("\n");
+}
+
+function renderPassedChecks(passed: readonly HarnessValidateCheck[], collapsed: boolean): string {
+  // When everything passed we collapse by default; when there ARE failures, we still
+  // collapse the passing list because they're not actionable.
+  void collapsed; // kept for symmetry with the design — both modes collapse passing checks
+  const names = passed.map((c) => `${c.name} ✅`).join(" · ");
+  return [
+    `<details><summary>Passed checks (${passed.length})</summary>`,
+    "",
+    names,
+    "</details>",
+  ].join("\n");
+}
+
+function renderScorecard(
+  dimensions: readonly HarnessScoreDimension[],
+  deltas: readonly PrCommentDimensionDelta[],
+): string {
+  const deltaByName = new Map(deltas.map((d) => [d.name, d.strict]));
+  const rows: string[] = [];
+  rows.push("| Dimension | Score | Δ | Open | Resolved | Wontfix |");
+  rows.push("|---|---:|---:|---:|---:|---:|");
+  for (const dim of dimensions) {
+    const delta = deltaByName.get(dim.name);
+    const deltaCell = delta === undefined || delta === 0 ? "—" : formatSignedDelta(delta);
+    rows.push(
+      `| ${DIMENSION_LABELS[dim.name]} | ${dim.strict} | ${deltaCell} | ${dim.open} | ${dim.resolved} | ${dim.wontfix} |`,
+    );
+  }
+  return rows.join("\n");
+}
+
+function renderTrend(
+  trend: readonly PrCommentTrendPoint[],
+  status: PrCommentStatus,
+): string | null {
+  if (trend.length < 2) return null;
+  const arrow = trend.map((p) => String(p.strict)).join(" → ");
+  const line = `Trend (last ${trend.length} runs, strict): \`${arrow}\``;
+  // For passing reports, hide trend behind a collapsible to keep the comment lean.
+  if (status === "passed") {
+    return [
+      "<details><summary>Trend</summary>",
+      "",
+      line,
+      "</details>",
+    ].join("\n");
+  }
+  return line;
+}
+
+function renderFooter(input: RenderInput): string {
+  const segments: string[] = [];
+  segments.push(`Score floor: strict ${input.scoreFloor.strict} / lenient ${input.scoreFloor.lenient}`);
+  segments.push(`Session \`${shortSessionId(input.sessionId)}\``);
+  if (input.runUrl) segments.push(`[logs](${input.runUrl})`);
+  if (input.reportArtifactUrl) segments.push(`[full report](${input.reportArtifactUrl})`);
+  segments.push("`🤖 /supi:harness validate`");
+  return `###### ${segments.join(" · ")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function renderFindingTable(findings: readonly HarnessValidateFinding[]): string {
+  const rows: string[] = [];
+  rows.push("| Severity | File | Message |");
+  rows.push("|---|---|---|");
+  for (const finding of findings) {
+    const file = finding.line ? `\`${finding.file}:${finding.line}\`` : `\`${finding.file}\``;
+    rows.push(
+      `| ${SEVERITY_EMOJI[finding.severity]} ${finding.severity} | ${file} | ${escapeInline(finding.message)} |`,
+    );
+  }
+  return rows.join("\n");
+}
+
+function computeScoreDelta(currentStrict: number, previous: PrCommentPreviousScore | null): number {
+  if (!previous) return 0;
+  return currentStrict - previous.strict;
+}
+
+function computeDimensionDeltas(
+  current: readonly HarnessScoreDimension[],
+  previous: readonly HarnessScoreDimension[] | null,
+): PrCommentDimensionDelta[] {
+  if (!previous) {
+    return current.map((dim) => ({ name: dim.name, strict: 0 }));
+  }
+  const prevByName = new Map(previous.map((d) => [d.name, d.strict]));
+  return current.map((dim) => {
+    const before = prevByName.get(dim.name);
+    return { name: dim.name, strict: before === undefined ? 0 : dim.strict - before };
+  });
+}
+
+function formatSignedDelta(delta: number): string {
+  return delta > 0 ? `+${delta}` : String(delta);
+}
+
+function shortSessionId(sessionId: string): string {
+  // ULIDs are 26 chars; trim for footer readability while staying unique enough to grep.
+  if (sessionId.length <= 8) return sessionId;
+  return `${sessionId.slice(0, 6)}…${sessionId.slice(-2)}`;
+}
+
+function escapeInline(text: string): string {
+  // Newlines inside a markdown table cell break the row. Collapse to spaces.
+  // Pipe characters must be escaped or they're parsed as column separators.
+  return text.replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Status derivation + sticky-marker round-trip.
+ *
+ * The marker line is a stable HTML comment that:
+ *   - lets the gh-poster find the existing sticky comment by prefix;
+ *   - lets `on-status-change` mode parse the previously posted status without re-reading
+ *     any local state (the comment body is the single source of truth).
+ *
+ * Format:
+ *   <!-- supipowers:harness:v1 status=<status> strict=<n> lenient=<n> session=<id> generatedAt=<iso> -->
+ *
+ * Versioned (`:v1`) so a future change to the marker shape can coexist with old comments.
+ */
+
+import type { HarnessValidateReport } from "../../types.js";
+import type { PrCommentStatus } from "./types.js";
+
+/** Single shared prefix used by both the renderer and the poster's lookup query. */
+export const STICKY_MARKER_PREFIX = "<!-- supipowers:harness:v1 ";
+
+/**
+ * Derive the status banner from a validate report.
+ *
+ * `report.passed` is the AND of (all checks passed) and (score floor satisfied), so we
+ * branch on its two ingredients independently rather than the combined flag — that's how
+ * we distinguish "checks passed but score below floor" (warned) from "a check actually
+ * failed" (failed).
+ */
+export function deriveStatus(report: HarnessValidateReport): PrCommentStatus {
+  const anyCheckFailed = report.checks.some((check) => !check.passed);
+  if (anyCheckFailed) return "failed";
+  if (!report.scoreFloorPassed) return "warned";
+  // Defensive: when checks pass and floor passes but report.passed is false, treat as
+  // failed so we don't paint over an upstream bug. In practice this branch is unreachable
+  // when callers populate the report correctly.
+  if (!report.passed) return "failed";
+  return "passed";
+}
+
+/** Fields embedded in a sticky-comment marker. */
+export interface MarkerFields {
+  status: PrCommentStatus;
+  strict: number;
+  lenient: number;
+  sessionId: string;
+  generatedAt: string;
+}
+
+/** Serialize fields into the canonical marker line. */
+export function renderMarker(fields: MarkerFields): string {
+  // `sessionId` is harness-generated (ULID-like) and never contains spaces; we still
+  // assert below so a bad input doesn't silently corrupt the marker.
+  if (/\s/.test(fields.sessionId)) {
+    throw new Error(`sessionId must not contain whitespace: ${JSON.stringify(fields.sessionId)}`);
+  }
+  return (
+    `${STICKY_MARKER_PREFIX}` +
+    `status=${fields.status} ` +
+    `strict=${fields.strict} ` +
+    `lenient=${fields.lenient} ` +
+    `session=${fields.sessionId} ` +
+    `generatedAt=${fields.generatedAt} ` +
+    `-->`
+  );
+}
+
+/**
+ * Best-effort parse of a marker line. Returns null when the body does not start with
+ * STICKY_MARKER_PREFIX or any required field is missing. We deliberately do not throw —
+ * callers treat "unparseable" as "no previous comment".
+ */
+export function parseMarker(body: string): MarkerFields | null {
+  const firstNewline = body.indexOf("\n");
+  const head = firstNewline === -1 ? body : body.slice(0, firstNewline);
+  if (!head.startsWith(STICKY_MARKER_PREFIX)) return null;
+  // Strip the prefix + trailing "-->", then split on whitespace.
+  const inner = head.slice(STICKY_MARKER_PREFIX.length).replace(/\s*-->\s*$/, "").trim();
+  if (inner.length === 0) return null;
+  const tokens = inner.split(/\s+/);
+  const map: Record<string, string> = {};
+  for (const token of tokens) {
+    const eq = token.indexOf("=");
+    if (eq === -1) continue;
+    map[token.slice(0, eq)] = token.slice(eq + 1);
+  }
+  const status = map.status;
+  const strict = Number(map.strict);
+  const lenient = Number(map.lenient);
+  const sessionId = map.session;
+  const generatedAt = map.generatedAt;
+  if (status !== "passed" && status !== "warned" && status !== "failed") return null;
+  if (!Number.isFinite(strict) || !Number.isFinite(lenient)) return null;
+  if (!sessionId || !generatedAt) return null;
+  return { status, strict, lenient, sessionId, generatedAt };
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Shared types for the harness PR comment subsystem.
+ *
+ * Pure data shapes only — no IO contracts live here. Keeping them in their own module
+ * means the render layer can be imported by tests without dragging the gh poster or env
+ * detection along.
+ */
+
+import type { HarnessScore, HarnessValidateReport } from "../../types.js";
+
+/**
+ * Snapshot of a previous score, sourced from `score-history.jsonl`. Score-history v1
+ * carries only the top-level scalars — per-dimension breakdowns are not persisted — so the
+ * renderer can compute a banner Δ but must show "—" for dimension columns. The optional
+ * `dimensions` field is reserved so a future score-history schema change can widen this
+ * without touching call sites.
+ */
+export interface PrCommentPreviousScore {
+  recordedAt: string;
+  strict: number;
+  lenient: number;
+  dimensions?: HarnessScore["dimensions"];
+}
+
+/** Status banner derived from a validate report. */
+export type PrCommentStatus = "passed" | "warned" | "failed";
+
+/** Trend bucket (oldest-first slice from score-history.jsonl). */
+export interface PrCommentTrendPoint {
+  ts: string;
+  strict: number;
+  lenient: number;
+}
+
+/** Per-dimension delta computed against the previous score. */
+export interface PrCommentDimensionDelta {
+  name: HarnessScore["dimensions"][number]["name"];
+  /** Strict-score delta vs previous. 0 when no baseline. */
+  strict: number;
+}
+
+/** Inputs to the pure renderer. */
+export interface RenderInput {
+  report: HarnessValidateReport;
+  /** Last score before the current one (drop the current entry). null on first run. */
+  previousScore: PrCommentPreviousScore | null;
+  /** Trend slice, oldest-first. May be empty. */
+  trend: readonly PrCommentTrendPoint[];
+  /** Score floor configured on the harness (from `HarnessHookConfig.score_floor`). */
+  scoreFloor: { strict: number; lenient: number };
+  sessionId: string;
+  /** Optional URL to the workflow run for the footer. */
+  runUrl?: string;
+  /** Optional URL to the raw validate-report.json artifact. */
+  reportArtifactUrl?: string;
+  /** "main@a1b2c3d" style label for the base ref in the summary line. */
+  baseRef?: string;
+  /** ISO timestamp used in the marker. Tests pass a fixed value. */
+  generatedAt: string;
+}
+
+/** Output of the pure renderer. */
+export interface RenderResult {
+  /** GitHub-flavoured markdown. First line is exactly `marker`. */
+  body: string;
+  /** Single-line HTML comment containing every machine-parseable field. */
+  marker: string;
+  status: PrCommentStatus;
+  /** Strict-score delta vs previous. 0 when no baseline. */
+  scoreDelta: number;
+  /** Per-dimension deltas, parallel to `report.score.dimensions`. */
+  dimensionDeltas: readonly PrCommentDimensionDelta[];
+}