supipowers 2.0.2 → 2.2.0

package/src/harness/stages/validate.ts

@@ -19,6 +19,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { parse as parseYaml } from "yaml";
+
 import type { Platform } from "../../platform/types.js";
 import type {
   HarnessAntiSlopBackend,
@@ -53,7 +55,14 @@ import {
   getHarnessAgentsMdPath,
   getHarnessArchitectureDocPath,
   getHarnessGoldenPrinciplesPath,
+  getHarnessSessionDir,
 } from "../project-paths.js";
+import { resolveDocsConfig } from "../docs/config.js";
+import { matchesLayerGlob } from "../docs/glob-match.js";
+import { selectRepresentativeFiles } from "../docs/representative-files.js";
+import { computeLayerSourceHash, sha256 as sha256Hash } from "../docs/source-hash.js";
+import { validateLayerDocMarkdown } from "../docs/validator.js";
+import { computeLayerAddendum } from "../hooks/layer-context-inject.js";
 
 export interface ValidateStageInput {
   /** Selected backend (from the design spec). */
@@ -116,6 +125,13 @@ const CHECK_CONTRACTS: Readonly<Record<string, CheckContract>> = {
     artifact: "validate-report.json synthetic-edit-test entry",
     failSafe: "Hook failures are emitted as error findings and block validation.",
   },
+  "docs-validation": {
+    invariant: "Per-layer docs must remain valid, complete, indexed, and integrated with the layer-context-inject hook.",
+    proves: "Every docs/layers/*.md passes the validator, docs/README.md ↔ filesystem are consistent, the hook prefers the per-layer doc, and drift between layer inputs and recorded sourceHash is surfaced.",
+    doesNotProve: "The doc content is high quality, or that the layer rules themselves match the current codebase.",
+    artifact: "validate-report.json docs-validation entry plus docs/layers/*.md + docs/README.md",
+    failSafe: "Missing docs/layers/ short-circuits the check as a no-op; structural failures emit warnings and surface in the queue.",
+  },
   "ci-local-wiring": {
     invariant: "Every harness validation gate must have one local command and CI must invoke that command instead of relying on human memory.",
     proves: "The configured local command exists and the configured CI workflow calls it on the selected PR trigger.",
@@ -243,6 +259,86 @@ function scriptNameFromLocalCommand(command: string): string | null {
   return null;
 }
 
+/**
+ * Conservative check that a GitHub Actions workflow grants the write scope needed for
+ * the harness PR comment. Only inspects the `permissions:` block — if a user has wired
+ * a deploy token or `secrets.GITHUB_TOKEN` with a custom scope, this returns false and
+ * the warning is a no-op false positive. That's deliberate: a false-positive warning is
+ * cheaper than a silent 403 the first time CI tries to post.
+ *
+ * Caveats this regex deliberately does not handle:
+ *  - Job-scoped `permissions:` blocks that grant `pull-requests: write` to a job other
+ *    than the one running `/supi:harness pr-comment`. Detecting that requires real YAML
+ *    parsing; a false-positive warning is again cheaper than guessing wrong.
+ */
+function workflowGrantsPrCommentPermission(workflow: string): boolean {
+  // Strip whole-line YAML comments before matching so a commented-out
+  // `# pull-requests: write` does not falsely register as a grant.
+  const stripped = workflow.replace(/^[ \t]*#.*$/gm, "");
+  // Match either inline mapping `permissions: { pull-requests: write }`, the block form
+  // with `pull-requests: write` on its own line, or the broad `permissions: write-all`.
+  if (/permissions:\s*write-all\b/.test(stripped)) return true;
+  if (/\bpull-requests:\s*write\b/.test(stripped)) return true;
+  return false;
+}
+
+/**
+ * Structurally inspect the rendered workflow for a healthy `verify-pr-source` job.
+ *
+ * Returns `null` when the job is present, gated on the configured `mainBranch`, and
+ * its shell guard names the configured `devBranch`. Returns a short description of
+ * the first mismatch otherwise.
+ *
+ * Parsing the YAML (rather than substring-matching the source) is what catches:
+ *  - a comment mentioning `verify-pr-source` (the substring lives, the job doesn't),
+ *  - a stale job referencing a previous mainBranch/devBranch pair after the spec
+ *    was updated and the workflow was not re-rendered,
+ *  - a structurally wrong job (no `if`, no `run` block, etc.).
+ *
+ * Unparseable YAML falls back to a substring sanity check so a malformed workflow
+ * still reports *something* useful instead of silently passing.
+ */
+function inspectPrSourceGuardrailJob(
+  workflow: string,
+  mainBranch: string,
+  devBranch: string,
+): string | null {
+  let doc: unknown;
+  try {
+    doc = parseYaml(workflow);
+  } catch {
+    return workflow.includes("verify-pr-source")
+      ? "workflow YAML is unparseable; cannot confirm guardrail is correct"
+      : "workflow YAML is unparseable and contains no verify-pr-source job";
+  }
+  if (!doc || typeof doc !== "object") return "workflow root is not a mapping";
+  const jobs = (doc as { jobs?: unknown }).jobs;
+  if (!jobs || typeof jobs !== "object") return "workflow has no `jobs:` mapping";
+  const job = (jobs as Record<string, unknown>)["verify-pr-source"];
+  if (!job || typeof job !== "object") return "job `verify-pr-source` is not defined";
+  const ifExpr = (job as { if?: unknown }).if;
+  if (typeof ifExpr !== "string" || !ifExpr.includes(`'${mainBranch}'`)) {
+    return `job \`verify-pr-source\` is not gated on mainBranch '${mainBranch}'`;
+  }
+  // The shell guard lives in steps[*].run; concatenate every run block we find so we
+  // do not depend on the exact step order or composition.
+  const steps = (job as { steps?: unknown }).steps;
+  const runBlocks: string[] = [];
+  if (Array.isArray(steps)) {
+    for (const step of steps) {
+      if (step && typeof step === "object") {
+        const run = (step as { run?: unknown }).run;
+        if (typeof run === "string") runBlocks.push(run);
+      }
+    }
+  }
+  const combinedRun = runBlocks.join("\n");
+  if (!combinedRun.includes(`"${devBranch}"`)) {
+    return `job \`verify-pr-source\` does not guard against devBranch '${devBranch}'`;
+  }
+  return null;
+}
+
 async function checkCiLocalWiring(
   paths: HarnessStageRunnerContext["paths"],
   cwd: string,
@@ -347,6 +443,40 @@ async function checkCiLocalWiring(
           }
         }
       }
+      // Informational: when prComment is enabled but the workflow lacks
+      // `pull-requests: write`, the `gh api` upsert will fail with 403. Surface a warning
+      // so the user notices before the first failed PR run.
+      if (spec.value.ci.prComment?.enabled && !workflowGrantsPrCommentPermission(workflow)) {
+        findings.push({
+          severity: "warning",
+          file: spec.value.ci.workflowPath,
+          message: "CI workflow does not grant `pull-requests: write` but prComment.enabled is true.",
+          remediation: "Add `permissions: { pull-requests: write }` to the workflow so /supi:harness pr-comment can post.",
+          source: "ci-local-wiring",
+        });
+      }
+
+      // When the design recorded git verification with `enforceMainFromDevOnly: true`,
+      // confirm the workflow actually contains the `verify-pr-source` job that the
+      // implement stage is supposed to render, with an `if:` that names the current
+      // mainBranch and a shell guard that names the current devBranch. A missing or
+      // stale job means CI-side enforcement is silently absent — surface it as an error
+      // so the user notices. Substring search is intentionally avoided: a comment
+      // containing "verify-pr-source", or a stale job from a previous main/dev pairing,
+      // would pass a `workflow.includes(...)` check but provide no real enforcement.
+      const git = spec.value.ci.git;
+      if (git && git.enforceMainFromDevOnly && git.devBranch) {
+        const issue = inspectPrSourceGuardrailJob(workflow, git.mainBranch, git.devBranch);
+        if (issue) {
+          findings.push({
+            severity: "error",
+            file: spec.value.ci.workflowPath,
+            message: `CI workflow's verify-pr-source job is missing or stale: ${issue}.`,
+            remediation: `Re-run /supi:harness so the workflow re-renders with the dev/main guardrail (dev=${git.devBranch}, main=${git.mainBranch}).`,
+            source: "ci-local-wiring",
+          });
+        }
+      }
     } catch (error) {
       findings.push({
         severity: "error",
@@ -358,6 +488,32 @@ async function checkCiLocalWiring(
     }
   }
 
+  // Bubble git-verification findings recorded by the interactive QA step into the
+  // validate report. The QA helper records non-fatal issues (gh missing, no permission)
+  // so the user sees them in the validation output even if the workflow itself is fine.
+  // When a bubbled finding has no remediation of its own, fall back to the manual
+  // instructions doc — but only when one was actually written (`manualInstructionsPath`
+  // is set). The previous literal-`<session>` placeholder was never substituted and
+  // pointed at a file that was never written for declined / completed verifications.
+  const gitVerification = spec.value.ci.git?.verification;
+  if (gitVerification) {
+    const manualPath = gitVerification.manualInstructionsPath
+      ? path.join(getHarnessSessionDir(paths, cwd, sessionId), gitVerification.manualInstructionsPath)
+      : null;
+    const fallbackRemediation = manualPath
+      ? `See ${manualPath} for manual steps.`
+      : "Re-run /supi:harness to retry git verification.";
+    for (const finding of gitVerification.findings) {
+      findings.push({
+        severity: finding.severity,
+        file: spec.value.ci.workflowPath,
+        message: `git-verify: ${finding.message}`,
+        remediation: finding.remediation ?? fallbackRemediation,
+        source: "ci-local-wiring",
+      });
+    }
+  }
+
   return {
     name: "ci-local-wiring",
     passed: !findings.some((finding) => finding.severity === "error"),
@@ -539,6 +695,327 @@ function loadLayerRules(cwd: string): HarnessLayerRule[] {
   }
 }
 
+/**
+ * Validate the per-layer docs tree: doc validator on each file, index ↔ filesystem
+ * consistency, hook integration smoke test, and sourceHash drift. Soft-failure: missing
+ * `docs/layers/` short-circuits to a no-op pass — the docs stage is opt-in.
+ */
+async function checkDocsValidation(
+  ctx: HarnessStageRunnerContext,
+  layerRules: readonly HarnessLayerRule[],
+): Promise<CheckResult> {
+  const startedAt = Date.now();
+  const findings: HarnessValidateFinding[] = [];
+
+  const layersDir = path.join(ctx.cwd, "docs", "layers");
+  if (!fs.existsSync(layersDir)) {
+    return {
+      name: "docs-validation",
+      passed: true,
+      summary: "Per-layer docs disabled (no docs/layers/).",
+      findings,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  const config = resolveDocsConfig(ctx.paths, ctx.cwd);
+
+  // ── Re-validate every layer doc ──────────────────────────────────────
+  let docFiles: string[] = [];
+  try {
+    docFiles = fs.readdirSync(layersDir).filter((f) => f.endsWith(".md")).sort();
+  } catch (error) {
+    findings.push({
+      severity: "warning",
+      file: "docs/layers/",
+      message: `unable to enumerate docs/layers/: ${error instanceof Error ? error.message : String(error)}`,
+      remediation: "Inspect the docs/layers/ directory permissions and re-run validate.",
+      source: "docs-validation",
+    });
+  }
+
+  for (const fileName of docFiles) {
+    const layerId = fileName.replace(/\.md$/, "");
+    const layerPath = `docs/layers/${fileName}`;
+    const docPath = path.join(layersDir, fileName);
+    let contents: string;
+    try {
+      contents = fs.readFileSync(docPath, "utf8");
+    } catch (error) {
+      findings.push({
+        severity: "warning",
+        file: layerPath,
+        message: `unable to read doc: ${error instanceof Error ? error.message : String(error)}`,
+        remediation: "Re-run `/supi:harness docs` after fixing filesystem permissions.",
+        source: "docs-validation",
+      });
+      continue;
+    }
+    const recordedHash = readFrontmatterSourceHashForValidate(contents);
+    const validation = validateLayerDocMarkdown(contents, {
+      expectedLayerId: layerId,
+      expectedSourceHash: recordedHash ?? "",
+      maxDocLoc: config.max_per_doc_loc,
+      maxAgentContextLoc: config.agent_context_loc,
+    });
+    if (!validation.ok) {
+      for (const err of validation.errors) {
+        findings.push({
+          severity: "warning",
+          file: layerPath,
+          message: err,
+          remediation: "Re-run `/supi:harness docs` to regenerate the per-layer doc.",
+          source: "docs-validation",
+        });
+      }
+    }
+  }
+
+  // ── Index ↔ filesystem consistency ────────────────────────────────────
+  const indexPath = path.join(ctx.cwd, "docs", "README.md");
+  if (!fs.existsSync(indexPath)) {
+    findings.push({
+      severity: "warning",
+      file: "docs/README.md",
+      message: "docs/layers/ exists but docs/README.md is missing.",
+      remediation: "Re-run `/supi:harness docs` to regenerate the index.",
+      source: "docs-validation",
+    });
+  } else {
+    let indexContents: string;
+    try {
+      indexContents = fs.readFileSync(indexPath, "utf8");
+    } catch (error) {
+      findings.push({
+        severity: "warning",
+        file: "docs/README.md",
+        message: `unable to read docs/README.md: ${error instanceof Error ? error.message : String(error)}`,
+        remediation: "Inspect the file permissions and re-run validate.",
+        source: "docs-validation",
+      });
+      indexContents = "";
+    }
+    const referenced = new Set<string>();
+    for (const match of indexContents.matchAll(/docs\/layers\/([A-Za-z0-9._-]+)\.md/g)) {
+      referenced.add(match[1]);
+    }
+    const onDisk = new Set(docFiles.map((f) => f.replace(/\.md$/, "")));
+    for (const layerId of referenced) {
+      if (!onDisk.has(layerId)) {
+        findings.push({
+          severity: "warning",
+          file: "docs/README.md",
+          message: `index references docs/layers/${layerId}.md but the file is missing.`,
+          remediation: "Run `/supi:harness docs` or delete the stale row from docs/README.md.",
+          source: "docs-validation",
+        });
+      }
+    }
+    for (const layerId of onDisk) {
+      if (!referenced.has(layerId)) {
+        findings.push({
+          severity: "warning",
+          file: "docs/README.md",
+          message: `docs/layers/${layerId}.md exists but is not listed in the index.`,
+          remediation: "Run `/supi:harness docs` to refresh the index.",
+          source: "docs-validation",
+        });
+      }
+    }
+  }
+
+  // ── Hook integration smoke test ──────────────────────────────────────
+  for (const rule of layerRules) {
+    const probeFile = pickSampleFileForLayer(ctx.cwd, rule);
+    if (!probeFile) continue;
+    const result = computeLayerAddendum({
+      cwd: ctx.cwd,
+      candidateFile: probeFile,
+      config: { enabled: true, addendum_max_chars: 800 },
+    });
+    const docExists = fs.existsSync(path.join(ctx.cwd, "docs", "layers", `${rule.layer}.md`));
+    if (docExists && result.reason !== "matched (per-layer doc)") {
+      findings.push({
+        severity: "warning",
+        file: `docs/layers/${rule.layer}.md`,
+        message: `layer-context-inject hook returned "${result.reason}" despite the per-layer doc existing.`,
+        remediation: "Verify the per-layer doc has a non-empty ## Agent context section.",
+        source: "docs-validation",
+      });
+    }
+  }
+
+  // ── Source-hash drift ────────────────────────────────────────────────
+  if (config.drift_warning.enabled) {
+    const promptVersion = readDocsPromptVersion();
+    const allFiles = collectAllRepoFilesForValidate(ctx.cwd);
+    const goldenPrinciples = readGoldenPrinciplesForValidate(ctx.cwd);
+    for (const rule of layerRules) {
+      const docPath = path.join(layersDir, `${rule.layer}.md`);
+      if (!fs.existsSync(docPath)) continue;
+      let contents: string;
+      try {
+        contents = fs.readFileSync(docPath, "utf8");
+      } catch (error) {
+        findings.push({
+          severity: "warning",
+          file: `docs/layers/${rule.layer}.md`,
+          message: `unable to read doc for drift check: ${error instanceof Error ? error.message : String(error)}`,
+          remediation: "Inspect the file permissions and re-run validate.",
+          source: "docs-validation",
+        });
+        continue;
+      }
+      const recordedHash = readFrontmatterSourceHashForValidate(contents);
+      if (!recordedHash) continue;
+
+      const globPaths = allFiles
+        .filter((file) => rule.globs.some((g) => matchesLayerGlob(file, g)))
+        .sort();
+      const repSelection = selectRepresentativeFiles({ cwd: ctx.cwd, files: globPaths });
+      const peerLayers = layerRules
+        .filter((peer) => peer.layer !== rule.layer)
+        .map((peer) => ({ id: peer.layer, description: peer.description ?? "" }));
+      const currentHash = computeLayerSourceHash({
+        layerRule: rule,
+        globPaths,
+        representativeFiles: repSelection.entries.map((e) => ({
+          path: e.path,
+          contentHash: e.contentHash,
+        })),
+        goldenPrinciples,
+        peerLayers,
+        promptVersion,
+      });
+      if (currentHash !== recordedHash) {
+        findings.push({
+          severity: "warning",
+          file: `docs/layers/${rule.layer}.md`,
+          message: `sourceHash drift: layer inputs changed since the doc was generated.`,
+          remediation: "Run `/supi:harness docs` to regenerate the affected layer doc.",
+          source: "docs-validation",
+        });
+      }
+    }
+  }
+
+  return {
+    name: "docs-validation",
+    // Findings are advisory only — they never block the stage; the report records them.
+    passed: true,
+    summary: findings.length === 0
+      ? "Per-layer docs validated."
+      : `${findings.length} per-layer docs finding(s).`,
+    findings,
+    durationMs: Date.now() - startedAt,
+  };
+}
+
+function readFrontmatterSourceHashForValidate(markdown: string): string | null {
+  let body = markdown;
+  if (body.startsWith("<!--")) {
+    const newline = body.indexOf("\n");
+    if (newline > 0) body = body.slice(newline + 1);
+  }
+  if (!body.startsWith("---")) return null;
+  const firstNewline = body.indexOf("\n");
+  if (firstNewline < 0) return null;
+  const closeIdx = body.indexOf("\n---", firstNewline);
+  if (closeIdx < 0) return null;
+  const inner = body.slice(firstNewline + 1, closeIdx);
+  for (const line of inner.split("\n")) {
+    const match = line.match(/^sourceHash\s*:\s*(.+)\s*$/);
+    if (match) return match[1].trim();
+  }
+  return null;
+}
+
+function pickSampleFileForLayer(cwd: string, rule: HarnessLayerRule): string | null {
+  // Walk the tree until we find one file matching any layer glob; this is enough to
+  // exercise the hook integration check without enumerating every file twice.
+  const allFiles = collectAllRepoFilesForValidate(cwd);
+  // dynamic import keeps the top-level imports list small
+  const skipDirs = ["node_modules", ".git", "dist", "build", ".omp", ".cache", ".next"];
+  for (const file of allFiles) {
+    if (skipDirs.some((d) => file.startsWith(`${d}/`))) continue;
+    for (const glob of rule.globs) {
+      if (matchesLayerGlobForValidate(file, glob)) return file;
+    }
+  }
+  return null;
+}
+
+function matchesLayerGlobForValidate(filePath: string, glob: string): boolean {
+  const normalizedFile = filePath.replace(/\\/g, "/");
+  const normalizedGlob = glob.replace(/\\/g, "/");
+  const regexSrc = normalizedGlob
+    .split(/(\*\*|\*)/g)
+    .map((segment) => {
+      if (segment === "**") return ".*";
+      if (segment === "*") return "[^/]*";
+      return segment.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${regexSrc}$`).test(normalizedFile);
+}
+
+function collectAllRepoFilesForValidate(cwd: string): string[] {
+  const out: string[] = [];
+  const skip = new Set<string>([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".omp",
+    "coverage",
+    ".cache",
+    ".next",
+  ]);
+  function walk(absolute: string, relative: string): void {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(absolute, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (skip.has(entry.name)) continue;
+        walk(path.join(absolute, entry.name), path.posix.join(relative, entry.name));
+      } else if (entry.isFile()) {
+        out.push(relative === "" ? entry.name : path.posix.join(relative, entry.name));
+      }
+    }
+  }
+  walk(cwd, "");
+  return out;
+}
+
+function readGoldenPrinciplesForValidate(cwd: string): string[] {
+  const principlesPath = path.join(cwd, "docs", "golden-principles.md");
+  if (!fs.existsSync(principlesPath)) return [];
+  try {
+    const md = fs.readFileSync(principlesPath, "utf8");
+    return md
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => /^\d+\.\s+/.test(line))
+      .map((line) => line.replace(/^\d+\.\s+/, ""));
+  } catch {
+    return [];
+  }
+}
+
+function readDocsPromptVersion(): string {
+  try {
+    const docsPromptUrl = new URL("../default-agents/docs.md", import.meta.url);
+    const filePath = path.normalize(decodeURI(docsPromptUrl.pathname));
+    const contents = fs.readFileSync(filePath, "utf8");
+    return sha256Hash(contents);
+  } catch {
+    return sha256Hash("harness-docs-prompt-fallback");
+  }
+}
+
 /**
  * Run every sub-check and assemble the validate report. Pure-ish: side effects are limited
  * to the optional anti-slop scan (which itself is fenced behind the adapter's
@@ -567,6 +1044,7 @@ export async function runValidate(
 
   const synthetic = checkSyntheticEdit(input, layerRules);
   checks.push(synthetic);
+  checks.push(await checkDocsValidation(ctx, layerRules));
 
   // Persist scan findings to the queue so future runs see them.
   for (const finding of slopFindings) {

package/src/harness/storage.ts

@@ -29,15 +29,22 @@ import {
   getHarnessDecisionsPath,
   getHarnessDesignSpecJsonPath,
   getHarnessDiscoverPath,
+  getHarnessDocsStagingDir,
+  getHarnessDocsStagingLayerPath,
+  getHarnessDocsStagingReadmePath,
   getHarnessImplementLogPath,
   getHarnessManifestPath,
   getHarnessPipelineLogPath,
   getHarnessQueuePath,
+  getHarnessRepoDocsLayerPath,
+  getHarnessRepoDocsLayersDir,
+  getHarnessRepoDocsReadmePath,
   getHarnessRepoScorePath,
   getHarnessResearchTopicPath,
   getHarnessScoreHistoryPath,
   getHarnessSessionDir,
   getHarnessValidateReportPath,
+  HARNESS_DOCS_LAYERS_DIRNAME,
 } from "./project-paths.js";
 
 // ---------------------------------------------------------------------------
@@ -418,6 +425,44 @@ export function appendImplementLog(
   return appendJsonl(getHarnessImplementLogPath(paths, cwd, sessionId), record);
 }
 
+/**
+ * Return true if the implement log records a successful programmatic apply for this
+ * session: the most recent record has `kind: "applied"` and an empty `errors` array.
+ * Used by `HarnessImplementStage.isComplete` to fast-skip reruns.
+ */
+export function hasSuccessfulImplementApply(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): boolean {
+  const logPath = getHarnessImplementLogPath(paths, cwd, sessionId);
+  if (!fs.existsSync(logPath)) return false;
+  let raw: string;
+  try {
+    raw = fs.readFileSync(logPath, "utf8");
+  } catch {
+    return false;
+  }
+  // Scan from the end so a later failed re-apply correctly overrides an earlier success.
+  const lines = raw.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    let record: unknown;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!record || typeof record !== "object" || Array.isArray(record)) continue;
+    const r = record as { kind?: unknown; errors?: unknown };
+    if (r.kind !== "applied") continue;
+    const errCount = Array.isArray(r.errors) ? r.errors.length : 0;
+    return errCount === 0;
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Project-scoped queue + score (shared across worktrees)
 // ---------------------------------------------------------------------------
@@ -465,3 +510,100 @@ export function appendScoreHistory(
 ): UltraPlanStorageResult<string> {
   return appendJsonl(getHarnessScoreHistoryPath(paths, cwd), record);
 }
+
+// ---------------------------------------------------------------------------
+// Docs stage — staging + repo promotion.
+// ---------------------------------------------------------------------------
+
+/** Save a single layer doc into the session's staging area. Atomic write. */
+export function saveHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(
+    getHarnessDocsStagingLayerPath(paths, cwd, sessionId, layerId),
+    markdown,
+  );
+}
+
+/** Read a single staged layer doc. */
+export function loadHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerId: string,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getHarnessDocsStagingLayerPath(paths, cwd, sessionId, layerId));
+}
+
+/** List staged layer ids (file basenames without `.md`). Returns [] when dir is absent. */
+export function listHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string[] {
+  const dir = path.join(
+    getHarnessDocsStagingDir(paths, cwd, sessionId),
+    HARNESS_DOCS_LAYERS_DIRNAME,
+  );
+  if (!fs.existsSync(dir)) return [];
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => name.endsWith(".md"))
+      .map((name) => name.slice(0, -3))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Save the staged docs index. Atomic write. */
+export function saveHarnessDocsIndexStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getHarnessDocsStagingReadmePath(paths, cwd, sessionId), markdown);
+}
+
+/**
+ * Promote staged docs to the repo-local docs/ tree.
+ *
+ * Atomicity contract: layer docs are written first (each via temp → rename); the index
+ * is written last so an observer reading mid-promotion never sees an index pointing at
+ * a yet-to-land layer doc. A failure midway leaves the previous repo state in place for
+ * already-rewritten files only when their layer was earlier in the list — callers must
+ * therefore treat partial failures as a "blocked" outcome and rely on the next run to
+ * re-promote from staging.
+ */
+export function promoteHarnessDocsToRepo(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerIds: readonly string[],
+): UltraPlanStorageResult<{ layerPaths: string[]; indexPath: string }> {
+  fs.mkdirSync(getHarnessRepoDocsLayersDir(paths, cwd), { recursive: true });
+
+  const layerPaths: string[] = [];
+  for (const layerId of layerIds) {
+    const staged = loadHarnessDocsLayerStaging(paths, cwd, sessionId, layerId);
+    if (!staged.ok) return staged;
+    const repoPath = getHarnessRepoDocsLayerPath(paths, cwd, layerId);
+    const wrote = writeTextAtomic(repoPath, staged.value);
+    if (!wrote.ok) return wrote;
+    layerPaths.push(wrote.value);
+  }
+
+  const indexStaged = readTextFile(getHarnessDocsStagingReadmePath(paths, cwd, sessionId));
+  if (!indexStaged.ok) return indexStaged;
+  const indexRepo = getHarnessRepoDocsReadmePath(paths, cwd);
+  const wroteIndex = writeTextAtomic(indexRepo, indexStaged.value);
+  if (!wroteIndex.ok) return wroteIndex;
+
+  return success({ layerPaths, indexPath: wroteIndex.value });
+}