supipowers 2.0.2 → 2.1.0

package/src/harness/stages/implement.ts

@@ -1,20 +1,20 @@
 /**
  * IMPLEMENT stage runner.
  *
- * Counts the tasks in the approved plan and decides whether to run them in-session (steer
- * loop, mirrors `/supi:plan`) or to hand off to `/supi:ultraplan` batch / worktree
- * runtime. The threshold is configurable via `harness.implement_in_session_threshold`
- * (default 10).
+ * Programmatic apply of every Tier 1 artifact defined by the design spec. Mirrors the
+ * `/supi:checks` pattern: the stage runs deterministically inside the harness command,
+ * with no handoff to the user's active agent. After this stage completes, the pipeline
+ * naturally continues to docs (per-layer subagent dispatch) and validate (mechanical
+ * checks) inside the same `/supi:harness` invocation.
  *
- * The actual execution loop lives in the command handler — the stage runner records the
- * routing decision and validates pre-conditions (clean git tree, plan readable, etc.).
+ * `decideImplementRouting` is retained as an exported helper for tests + future tooling;
+ * the in-session-vs-batch heuristic is no longer used by the stage runner itself because
+ * the apply path no longer needs the active agent.
  */
 
 import * as fs from "node:fs";
-import * as path from "node:path";
 
 import type { Plan } from "../../types.js";
-import { parsePlan } from "../../storage/plans.js";
 import {
   type HarnessStageRunResult,
   type HarnessStageRunner,
@@ -23,7 +23,10 @@ import {
 } from "../stage-runner.js";
 import {
   appendImplementLog,
+  hasSuccessfulImplementApply,
+  loadHarnessDesignSpecJson,
 } from "../storage.js";
+import { applyHarnessPlan } from "./implement-apply.js";
 
 const DEFAULT_IN_SESSION_THRESHOLD = 10;
 
@@ -81,20 +84,15 @@ export class HarnessImplementStage implements HarnessStageRunner {
     return fs.existsSync(this.input.planPath);
   }
 
+  /**
+   * Implement is driven by the programmatic apply, so `isComplete` returns true once a
+   * successful apply has been recorded in `implement-log.jsonl`. This keeps reruns
+   * idempotent without re-walking every applier (the appliers themselves are also
+   * idempotent — this is a fast-skip for the common case). A subsequent failed apply in
+   * the same session resets the result via the scan-from-end logic in storage.
+   */
   async isComplete(ctx: HarnessStageRunnerContext): Promise<boolean> {
-    // Implement is complete when the post-implement self-check has been recorded in
-    // implement-log.jsonl with `kind: "self-check-passed"`. The command handler appends
-    // that record after running typecheck/test/scan.
-    const logPath = path.join(
-      path.dirname(this.input.planPath),
-      "..",
-      "harness",
-      "sessions",
-      ctx.sessionId,
-      "implement-log.jsonl",
-    );
-    void logPath; // tracked but the stage runner does not introspect it directly.
-    return false;
+    return hasSuccessfulImplementApply(ctx.paths, ctx.cwd, ctx.sessionId);
   }
 
   async run(ctx: HarnessStageRunnerContext): Promise<HarnessStageRunResult> {
@@ -111,51 +109,66 @@ export class HarnessImplementStage implements HarnessStageRunner {
         blocker: { code: "implement-preflight-failed", message: errors.join("; ") },
       };
     }
-    let raw: string;
-    try {
-      raw = fs.readFileSync(this.input.planPath, "utf8");
-    } catch (error) {
+    const designResult = loadHarnessDesignSpecJson(ctx.paths, ctx.cwd, ctx.sessionId);
+    if (!designResult.ok) {
       return {
-        status: "failed",
-        stage: this.stage,
-        artifactPaths: [],
-        error: `unable to read plan: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-    let plan: Plan;
-    try {
-      plan = parsePlan(raw, this.input.planPath);
-    } catch (error) {
-      return {
-        status: "failed",
+        status: "blocked",
         stage: this.stage,
         artifactPaths: [],
-        error: `unable to parse plan: ${error instanceof Error ? error.message : String(error)}`,
+        blocker: {
+          code: "design-spec-missing",
+          message: "implement stage requires <session>/design-spec.json. Run /supi:harness design first.",
+        },
       };
     }
 
-    const decision = decideImplementRouting({
-      plan,
-      threshold: this.input.threshold ?? DEFAULT_IN_SESSION_THRESHOLD,
+    const recordedAt = nowIso(ctx);
+    const outcome = await applyHarnessPlan({
+      platform: ctx.platform,
+      paths: ctx.paths,
+      cwd: ctx.cwd,
+      spec: designResult.value,
+      apply: true,
     });
 
     appendImplementLog(ctx.paths, ctx.cwd, ctx.sessionId, {
-      recordedAt: nowIso(ctx),
-      kind: "routing-decision",
-      routing: decision.routing,
-      taskCount: decision.taskCount,
-      reason: decision.reason,
+      recordedAt,
+      kind: "applied",
       planPath: this.input.planPath,
+      applied: outcome.applied,
+      warnings: outcome.warnings,
+      errors: outcome.errors,
     });
 
+    const artifactPaths = outcome.applied
+      .filter((entry) => entry.action === "wrote" || entry.action === "patched")
+      .map((entry) => entry.path);
+
+    if (outcome.errors.length > 0) {
+      const summary = outcome.errors
+        .map((err) => `${err.step}: ${err.message}`)
+        .join("; ");
+      return {
+        status: "blocked",
+        stage: this.stage,
+        artifactPaths,
+        blocker: { code: "implement-apply-failed", message: summary },
+        details: {
+          applied: outcome.applied.length,
+          errors: outcome.errors.length,
+          warnings: outcome.warnings.length,
+        },
+      };
+    }
+
     return {
-      status: "awaiting-user",
+      status: "completed",
       stage: this.stage,
-      artifactPaths: ["implement-log.jsonl"],
+      artifactPaths,
       details: {
-        routing: decision.routing,
-        taskCount: decision.taskCount,
-        reason: decision.reason,
+        applied: outcome.applied.length,
+        warnings: outcome.warnings.length,
+        wrote: artifactPaths.length,
       },
     };
   }

package/src/harness/stages/plan.ts

@@ -24,6 +24,7 @@ import {
 } from "../stage-runner.js";
 import {
   loadHarnessDesignSpecJson,
+  loadHarnessSession,
 } from "../storage.js";
 
 export interface HarnessPlanTask {
@@ -36,22 +37,14 @@ export interface HarnessPlanTask {
 }
 
 /**
- * Build the canonical task list from a design spec. Always emits the "harden" tasks
- * (AGENTS.md, docs/architecture.md, docs/golden-principles.md, lint/structural/eval
- * configs); appends the conditional anti-slop tasks per Design's backend choice.
+ * Build the canonical task list from a design spec. Always emits the source
+ * harness artifacts first (docs, tooling, CI, queue, review wiring), then ends
+ * with AGENTS.md so the agent-facing summary can reference completed artifacts.
  */
 export function buildHarnessPlanTasks(spec: HarnessDesignSpec): HarnessPlanTask[] {
   const tasks: HarnessPlanTask[] = [];
   let id = 1;
 
-  tasks.push({
-    id: id++,
-    name: "Generate AGENTS.md",
-    description: "Write a ≤120-line AGENTS.md at the repo root summarizing the harness contract for any agent.",
-    files: ["AGENTS.md"],
-    criteria: "AGENTS.md exists, references docs/architecture.md and docs/golden-principles.md, and ends with a 'When in doubt' section.",
-    complexity: "small",
-  });
 
   tasks.push({
     id: id++,
@@ -159,10 +152,10 @@ export function buildHarnessPlanTasks(spec: HarnessDesignSpec): HarnessPlanTask[
 
   tasks.push({
     id: id++,
-    name: "Register anti-slop hooks",
-    description: "Ensure src/harness/hooks/register.ts wires pre-edit dupe probe, post-session sweep, and layer-context-inject only when the harness marker exists.",
-    files: ["src/harness/hooks/register.ts"],
-    criteria: "Hooks are registered idempotently and gated by the marker file.",
+    name: "Enable repo-local anti-slop hooks",
+    description: "Create the repo-local harness marker. The installed Supipowers extension already registers the runtime hooks; the marker gates them for this repository.",
+    files: [".omp/supipowers/harness/marker.json"],
+    criteria: `Marker JSON exists with backend ${spec.antiSlop.backend}; no supipowers extension source files are modified.`,
     complexity: "small",
   });
 
@@ -206,9 +199,20 @@ export function buildHarnessPlanTasks(spec: HarnessDesignSpec): HarnessPlanTask[
     });
   }
 
+  tasks.push({
+    id: id++,
+    name: "Generate AGENTS.md",
+    description: "Write a ≤120-line AGENTS.md at the repo root summarizing the harness contract for any agent.",
+    files: ["AGENTS.md"],
+    criteria: "AGENTS.md exists, references docs/architecture.md and docs/golden-principles.md, and ends with a 'When in doubt' section.",
+    complexity: "small",
+  });
+
   return tasks;
 }
 
+
+
 /** Render the plan markdown that lands in the canonical plans directory. */
 export function renderHarnessPlanMarkdown(input: {
   spec: HarnessDesignSpec;
@@ -321,7 +325,12 @@ export function emitHarnessPlanFromSpec(input: {
   const recordedAt = input.recordedAt ?? new Date().toISOString();
   const planName = input.planName ?? `harness-${input.spec.sessionId}`;
   const tasks = buildHarnessPlanTasks(input.spec);
-  const planMarkdown = renderHarnessPlanMarkdown({ spec: input.spec, tasks, recordedAt, planName });
+  const planMarkdown = renderHarnessPlanMarkdown({
+    spec: input.spec,
+    tasks,
+    recordedAt,
+    planName,
+  });
   const filename = `${planName}.md`;
   const planPath = savePlan(input.ctx.paths, input.ctx.cwd, filename, planMarkdown);
   return { planPath, planMarkdown, tasks };

package/src/harness/stages/validate.ts

@@ -54,6 +54,12 @@ import {
   getHarnessArchitectureDocPath,
   getHarnessGoldenPrinciplesPath,
 } 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 +122,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 +256,29 @@ 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;
+}
+
 async function checkCiLocalWiring(
   paths: HarnessStageRunnerContext["paths"],
   cwd: string,
@@ -347,6 +383,18 @@ 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",
+        });
+      }
     } catch (error) {
       findings.push({
         severity: "error",
@@ -539,6 +587,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 +936,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) {