supipowers 2.0.2 → 2.2.0

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[];
+}

package/src/harness/pr-comment/workflow-summary.ts

@@ -0,0 +1,47 @@
+/**
+ * Fallback writer for `$GITHUB_STEP_SUMMARY`.
+ *
+ * GitHub Actions reads any markdown appended to the file at this env var and renders it
+ * on the workflow run summary page. We use it as a fail-open fallback when posting a PR
+ * comment is impossible (no auth, no `gh` CLI, no PR context).
+ *
+ * Never throws. Returns `{ ok: false }` quietly on IO error so the calling pipeline does
+ * not crash on a runner with an unwritable `$GITHUB_STEP_SUMMARY`.
+ */
+
+import * as fs from "node:fs";
+
+export interface WriteStepSummaryResult {
+  /** True when the body was appended (or no-op because env is unset). */
+  ok: boolean;
+  /** Resolved summary file path when appended. */
+  path?: string;
+  /** When ok=false, a short reason for diagnostics. */
+  reason?: string;
+}
+
+/**
+ * Append `body` to the workflow step summary file. When `$GITHUB_STEP_SUMMARY` is unset
+ * (local dev), this is a successful no-op.
+ */
+export function writeStepSummary(
+  body: string,
+  env: NodeJS.ProcessEnv = process.env,
+): WriteStepSummaryResult {
+  const summaryPath = env.GITHUB_STEP_SUMMARY;
+  if (!summaryPath) {
+    return { ok: true };
+  }
+  try {
+    // The summary file is append-only between steps; we add a leading blank line so the
+    // harness section is separated from anything an earlier step contributed.
+    const payload = body.endsWith("\n") ? `\n${body}` : `\n${body}\n`;
+    fs.appendFileSync(summaryPath, payload);
+    return { ok: true, path: summaryPath };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/harness/project-paths.ts

@@ -52,6 +52,13 @@ export const HARNESS_IMPLEMENT_LOG_FILENAME = "implement-log.jsonl";
 export const HARNESS_PIPELINE_LOG_FILENAME = "pipeline-log.jsonl";
 export const HARNESS_RESEARCH_DIRNAME = "research";
 
+/** Per-session staging directory for the docs stage. */
+export const HARNESS_DOCS_STAGING_DIRNAME = "docs";
+/** Layers subdirectory within the docs staging or repo-docs directory. */
+export const HARNESS_DOCS_LAYERS_DIRNAME = "layers";
+/** Index filename rendered after layer docs promote. */
+export const HARNESS_DOCS_README_FILENAME = "README.md";
+
 /** Tier 1 / Tier 2 output paths in the repo. */
 export const HARNESS_AGENTS_MD_FILENAME = "AGENTS.md";
 export const HARNESS_DOCS_DIRNAME = "docs";
@@ -233,3 +240,91 @@ export function getHarnessGoldenPrinciplesPath(_paths: PlatformPaths, cwd: strin
 export function getHarnessFallowConfigPath(_paths: PlatformPaths, cwd: string): string {
   return path.join(cwd, HARNESS_FALLOW_CONFIG_FILENAME);
 }
+
+// ---------------------------------------------------------------------------
+// Docs stage — staging + repo paths.
+// ---------------------------------------------------------------------------
+/**
+ * Strict whitelist for per-layer doc identifiers.
+ *
+ * Layer ids are user/model-controlled (set in `design-spec.json`) and feed into
+ * `<repo>/docs/layers/<id>.md` plus the per-session staging mirror. Without a strict
+ * boundary an id like `../golden-principles` would let the docs stage overwrite Tier 1
+ * docs (or escape `docs/layers/` entirely). Reject anything that isn't a safe filename
+ * stem: alnum, hyphen, underscore, and (non-leading, non-consecutive) dots.
+ */
+const LAYER_ID_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
+
+export function isSafeLayerId(layerId: string): boolean {
+  return (
+    typeof layerId === "string" &&
+    LAYER_ID_PATTERN.test(layerId) &&
+    !layerId.includes("..")
+  );
+}
+
+export function assertSafeLayerId(layerId: string): void {
+  if (!isSafeLayerId(layerId)) {
+    throw new Error(
+      `harness: invalid layer id ${JSON.stringify(layerId)} — expected [A-Za-z0-9._-]{1,64} with no path separators, leading dot, or '..'.`,
+    );
+  }
+}
+
+
+/**
+ * Per-session staging dir for the docs stage:
+ * `<projectRoot>/sessions/<sid>/docs/`. Subagents write `layers/<id>.md` here; the stage
+ * renders the index and atomically promotes both staging files to the repo.
+ */
+export function getHarnessDocsStagingDir(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessSessionDir(paths, cwd, sessionId), HARNESS_DOCS_STAGING_DIRNAME);
+}
+
+/** Per-session staging path for a single layer doc. */
+export function getHarnessDocsStagingLayerPath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerId: string,
+): string {
+  assertSafeLayerId(layerId);
+  return path.join(
+    getHarnessDocsStagingDir(paths, cwd, sessionId),
+    HARNESS_DOCS_LAYERS_DIRNAME,
+    `${layerId}.md`,
+  );
+}
+
+/** Per-session staging path for the rendered docs index. */
+export function getHarnessDocsStagingReadmePath(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getHarnessDocsStagingDir(paths, cwd, sessionId), HARNESS_DOCS_README_FILENAME);
+}
+
+/** Repo-root path for the rendered docs index: `<repo>/docs/README.md`. */
+export function getHarnessRepoDocsReadmePath(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_DOCS_DIRNAME, HARNESS_DOCS_README_FILENAME);
+}
+
+/** Repo-root path for a single per-layer doc: `<repo>/docs/layers/<id>.md`. */
+export function getHarnessRepoDocsLayerPath(
+  _paths: PlatformPaths,
+  cwd: string,
+  layerId: string,
+): string {
+  assertSafeLayerId(layerId);
+  return path.join(cwd, HARNESS_DOCS_DIRNAME, HARNESS_DOCS_LAYERS_DIRNAME, `${layerId}.md`);
+}
+
+/** Repo-root directory hosting the per-layer docs: `<repo>/docs/layers/`. */
+export function getHarnessRepoDocsLayersDir(_paths: PlatformPaths, cwd: string): string {
+  return path.join(cwd, HARNESS_DOCS_DIRNAME, HARNESS_DOCS_LAYERS_DIRNAME);
+}

package/src/harness/stages/design.ts

@@ -61,6 +61,7 @@ export function defaultCiConfigFromDiscover(discover: HarnessDiscoverArtifact):
     trigger: { mode: "branches", branches: ["dev", "main"] },
     localCommand,
     workflowPath: ".github/workflows/harness-quality.yml",
+    prComment: { enabled: true, mode: "every-push" },
   };
 }
 

package/src/harness/stages/discover.ts

@@ -190,7 +190,6 @@ function detectOmpInfra(cwd: string): HarnessDiscoverArtifact["ompInfra"] {
   const hasSupipowers = existsSync(supipowersDir);
   const skills: string[] = [];
   const reviewAgents: string[] = [];
-  const mcpServers: string[] = [];
   let plansCount = 0;
 
   // Skills are typically in skills/ at the repo root.
@@ -226,20 +225,9 @@ function detectOmpInfra(cwd: string): HarnessDiscoverArtifact["ompInfra"] {
         plansCount = 0;
       }
     }
-    const mcpJson = path.join(supipowersDir, ".mcp.json");
-    if (existsSync(mcpJson)) {
-      try {
-        const parsed = JSON.parse(fs.readFileSync(mcpJson, "utf8")) as {
-          servers?: Record<string, unknown>;
-        };
-        if (parsed.servers) mcpServers.push(...Object.keys(parsed.servers));
-      } catch {
-        // ignore
-      }
-    }
   }
 
-  return { hasSupipowers, skills, reviewAgents, mcpServers, plansCount };
+  return { hasSupipowers, skills, reviewAgents, plansCount };
 }
 
 function detectFrameworks(cwd: string): string[] {