supipowers 2.0.2 → 2.2.0

package/src/git/commit.ts

@@ -139,28 +139,27 @@ interface CommitStagingContext {
   stagedFiles: string[];
 }
 
-async function ensureStagedChanges(
-  platform: Platform,
+const STAGE_ALL_CHANGES_OPTION = "Stage all changes — include staged, unstaged, and untracked files";
+const USE_STAGED_CHANGES_OPTION = "Use staged changes only — commit the index as-is";
+
+async function stageAllChanges(
+  exec: ExecFn,
   ctx: any,
   cwd: string,
-  status: Awaited<ReturnType<typeof getWorkingTreeStatus>>,
+  fileCount: number,
   progress: ReturnType<typeof createProgress>,
-): Promise<CommitStagingContext | null> {
-  const exec = platform.exec.bind(platform);
-
-  if (status.stagedFiles.length === 0) {
-    progress.activate(1, `${status.files.length} file(s)`);
-    const addResult = await exec("git", ["add", "-A"], { cwd });
-    if (addResult.code !== 0) {
-      notifyError(ctx, "git add failed", addResult.stderr || "Non-zero exit");
-      return null;
-    }
-    progress.complete(1, `${status.files.length} file(s)`);
-  } else {
-    progress.activate(1, `${status.stagedFiles.length} staged`);
-    progress.complete(1, `${status.stagedFiles.length} staged`);
+): Promise<boolean> {
+  progress.activate(1, `${fileCount} file(s)`);
+  const addResult = await exec("git", ["add", "-A"], { cwd });
+  if (addResult.code !== 0) {
+    notifyError(ctx, "git add failed", addResult.stderr || "Non-zero exit");
+    return false;
   }
+  progress.complete(1, `${fileCount} file(s)`);
+  return true;
+}
 
+async function readStagedFiles(exec: ExecFn, ctx: any, cwd: string): Promise<string[] | null> {
   const stagedFilesResult = await exec("git", ["diff", "--cached", "--name-only"], { cwd });
   if (stagedFilesResult.code !== 0) {
     notifyError(ctx, "git diff failed", stagedFilesResult.stderr || "Could not read staged files");
@@ -173,7 +172,66 @@ async function ensureStagedChanges(
     return null;
   }
 
-  return { stagedFiles };
+  return stagedFiles;
+}
+
+function formatFilePreview(files: string[], label: string): string {
+  const preview = files.slice(0, 8).join("\n");
+  const extra = files.length > 8 ? `\n… and ${files.length - 8} more ${label}` : "";
+  return `${preview}${extra}`;
+}
+
+async function ensureStagedChanges(
+  platform: Platform,
+  ctx: any,
+  cwd: string,
+  status: Awaited<ReturnType<typeof getWorkingTreeStatus>>,
+  progress: ReturnType<typeof createProgress>,
+): Promise<CommitStagingContext | null> {
+  const exec = platform.exec.bind(platform);
+
+  if (status.stagedFiles.length > 0 && status.unstagedFiles.length > 0) {
+    const selection = await ctx.ui.select(
+      "Staged and unstaged changes detected",
+      [STAGE_ALL_CHANGES_OPTION, USE_STAGED_CHANGES_OPTION],
+      {
+        helpText: [
+          "Choose the source of truth for /supi:commit.",
+          `Staged (${status.stagedFiles.length}):\n${formatFilePreview(status.stagedFiles, "staged")}`,
+          `Unstaged/untracked (${status.unstagedFiles.length}):\n${formatFilePreview(status.unstagedFiles, "unstaged")}`,
+        ].join("\n\n"),
+      },
+    );
+
+    if (!selection) {
+      progress.dispose();
+      return null;
+    }
+
+    if (selection === STAGE_ALL_CHANGES_OPTION) {
+      if (!await stageAllChanges(exec, ctx, cwd, status.files.length, progress)) {
+        return null;
+      }
+    } else {
+      progress.activate(1, `${status.stagedFiles.length} staged`);
+      progress.complete(1, `${status.stagedFiles.length} staged`);
+    }
+
+    const stagedFiles = await readStagedFiles(exec, ctx, cwd);
+    return stagedFiles ? { stagedFiles } : null;
+  }
+
+  if (status.stagedFiles.length === 0) {
+    if (!await stageAllChanges(exec, ctx, cwd, status.files.length, progress)) {
+      return null;
+    }
+  } else {
+    progress.activate(1, `${status.stagedFiles.length} staged`);
+    progress.complete(1, `${status.stagedFiles.length} staged`);
+  }
+
+  const stagedFiles = await readStagedFiles(exec, ctx, cwd);
+  return stagedFiles ? { stagedFiles } : null;
 }
 
 // ── Main entry point ───────────────────────────────────────

package/src/harness/command.ts

@@ -39,9 +39,9 @@ import {
   loadHarnessSession,
   loadHarnessValidateReport,
   readSlopQueue,
+  saveHarnessDesignSpecJson,
   saveHarnessSession,
 } from "./storage.js";
-import { getHarnessSessionDir } from "./project-paths.js";
 import { computeScore } from "./anti_slop/score.js";
 import {
   type BuildRunnerInput,
@@ -55,6 +55,9 @@ import { newHarnessSessionId } from "./stage-runner.js";
 import { buildBackendAdapter } from "./anti_slop/backend-factory.js";
 import { getWorkingTreeStatus } from "../git/status.js";
 import { DEFAULT_HARNESS_CONFIG } from "./hooks/register.js";
+import { handlePrComment } from "./pr-comment/handler.js";
+import { runGitVerificationQa } from "./git-verify-qa.js";
+import { getHarnessSessionDir } from "./project-paths.js";
 import type { HarnessDesignSpec, HarnessGateMode, HarnessSession, HarnessStage } from "../types.js";
 
 modelRegistry.register({
@@ -67,6 +70,7 @@ modelRegistry.register({
 export interface HarnessCommandContext {
   cwd: string;
   hasUI?: boolean;
+  newSession?: (options?: any) => Promise<{ cancelled: boolean }>;
   ui: {
     notify(message: string, type?: "info" | "warning" | "error"): void;
     select?: (title: string, options: unknown[]) => Promise<string | null>;
@@ -80,6 +84,7 @@ export const HARNESS_SUBCOMMANDS = [
   { name: "design", description: "Run/advance the design stage (requires Discover + Research)" },
   { name: "plan-draft", description: "Render and persist the plan from the in-flight design spec" },
   { name: "implement", description: "Route plan to in-session steer or batch" },
+  { name: "docs", description: "Generate per-layer agent docs (extensive mode only)" },
   { name: "validate", description: "Run validate sub-checks" },
   { name: "resume", description: "Pick up an in-flight session" },
   { name: "status", description: "Print stage + score badge" },
@@ -88,6 +93,7 @@ export const HARNESS_SUBCOMMANDS = [
   { name: "resolve", description: "Mark a queue entry resolved" },
   { name: "backlog", description: "List every open queue entry" },
   { name: "score", description: "Recompute and display the score" },
+  { name: "pr-comment", description: "Render or post the harness PR sticky comment" },
 ] as const;
 
 type HarnessSubcommand = (typeof HARNESS_SUBCOMMANDS)[number]["name"];
@@ -100,6 +106,7 @@ const HARNESS_STAGE_LABELS: Readonly<Record<HarnessStage, string>> = {
   design: "Design harness",
   plan: "Draft plan",
   implement: "Apply artifacts",
+  docs: "Generate per-layer docs",
   validate: "Validate results",
 };
 
@@ -122,7 +129,7 @@ export interface HarnessCommandRequest {
 // ── Progress (status-bar + one final notification) ───────────────
 
 function createHarnessProgress(ctx: HarnessCommandContext) {
-  const SO = ["discover", "research", "design", "plan", "implement", "validate"] as HarnessStage[];
+  const SO = ["discover", "research", "design", "plan", "implement", "docs", "validate"] as HarnessStage[];
   let done = 0;
   let cur: HarnessStage | null = null;
   const completed: string[] = [];
@@ -197,8 +204,10 @@ export async function handleHarness(
       case "design": await handleStageCommand(platform, ctx, "design", request.args); return;
       case "plan-draft": await handleStageCommand(platform, ctx, "plan", request.args); return;
       case "implement": await handleStageCommand(platform, ctx, "implement", request.args); return;
+      case "docs": await handleStageCommand(platform, ctx, "docs", request.args); return;
       case "validate": await handleStageCommand(platform, ctx, "validate", request.args); return;
       case "resume": await handleResume(platform, ctx, request.args); return;
+      case "pr-comment": await handlePrComment(platform, ctx, request.args); return;
       default:
         notifyError(ctx, "Unknown harness subcommand", `\`${request.subcommand}\` is not recognized.`);
         return;
@@ -217,12 +226,13 @@ async function runPipelineWithProgress(
   gates: HarnessGateMode,
   stageInputs: BuildRunnerInput,
   startStage?: HarnessStage,
+  forceStages?: ReadonlySet<HarnessStage>,
 ): Promise<PipelineRunOutcome> {
   const harnessProgress = createHarnessProgress(ctx);
   const modelConfig = loadModelConfig(platform.paths, ctx.cwd);
   const outcome = await pipelineDriver({
     platform, paths: platform.paths, cwd: ctx.cwd, sessionId,
-    modelConfig, gates, stageInputs, startStage,
+    modelConfig, gates, stageInputs, startStage, forceStages,
     onProgress: harnessProgress.onProgress,
   });
   // Single consolidated notification.
@@ -276,7 +286,8 @@ async function presentGateForStage(
         `Design spec ready\n\n${summary}\n\nContinue to plan?`,
         ["Continue", "Stop — I'll customize the design"],
       );
-      return choice === "Continue" ? "continue" : "stop";
+      if (choice !== "Continue") return "stop";
+      return await promptDocsTierIfNeeded(platform, ctx, sessionId, layers);
     }
     case "plan": {
       const plansDir = getProjectStatePath(platform.paths, ctx.cwd, "plans");
@@ -293,6 +304,27 @@ async function presentGateForStage(
       );
       return choice === "Approve and continue" ? "continue" : "stop";
     }
+    case "docs": {
+      const session = loadHarnessSession(platform.paths, ctx.cwd, sessionId);
+      const tier = session.ok ? (session.value.docsTier ?? "simple") : "simple";
+      const docsDir = path.join(ctx.cwd, "docs", "layers");
+      let layerCount = 0;
+      if (fs.existsSync(docsDir)) {
+        try {
+          layerCount = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md")).length;
+        } catch {
+          /* best-effort */
+        }
+      }
+      const summary = tier === "extensive"
+        ? `Tier: extensive\nPer-layer docs at docs/layers/ (${layerCount} layer file${layerCount === 1 ? "" : "s"}).\nIndex: docs/README.md.`
+        : `Tier: simple\nNo per-layer docs were generated.`;
+      const choice = await ctx.ui.select(
+        `Per-layer agent docs\n\n${summary}\n\nContinue to validate?`,
+        ["Continue", "Stop — I want to inspect the docs first"],
+      );
+      return choice === "Continue" ? "continue" : "stop";
+    }
     case "validate": {
       const report = loadHarnessValidateReport(platform.paths, ctx.cwd, sessionId);
       const passed = report.ok ? report.value.passed : false;
@@ -312,6 +344,55 @@ async function presentGateForStage(
   }
 }
 
+/**
+ * Ask the user whether the upcoming docs stage should generate per-layer agent docs.
+ *
+ * Behavior:
+ *   - If the session manifest already records a `docsTier`, skip the prompt.
+ *   - In `auto` gate mode (no UI), default to "simple" silently.
+ *   - In default/manual modes, prompt the user; "cancel" aborts via `stop` propagated
+ *     by the caller; "simple"/"extensive" persist on the manifest.
+ *
+ * Layer count <2 always resolves to "simple" — extensive mode is meaningless with a
+ * single-bucket architecture.
+ */
+async function promptDocsTierIfNeeded(
+  platform: Platform,
+  ctx: HarnessCommandContext,
+  sessionId: string,
+  layerCount: number,
+): Promise<"continue" | "stop"> {
+  const session = loadHarnessSession(platform.paths, ctx.cwd, sessionId);
+  if (!session.ok) return "continue";
+  const isRerun =
+    session.value.reRunMode === "rebuild" || session.value.reRunMode === "harden";
+  if (session.value.docsTier && !isRerun) return "continue";
+
+  let tier: "simple" | "extensive" = session.value.docsTier ?? "simple";
+  if (layerCount >= 2 && ctx.ui.select) {
+    const currentLabel = session.value.docsTier ? ` (current: ${session.value.docsTier})` : "";
+    const summary = `simple    — Tier 1 docs only (AGENTS.md, architecture.md, golden-principles.md)\nextensive — Tier 1 + per-layer docs at docs/layers/<id>.md + index at docs/README.md\n              (≤150 LOC/doc, ${layerCount} layers detected → ~${layerCount} subagent calls)`;
+    const choice = await ctx.ui.select(
+      `Generate per-layer agent docs in the upcoming Docs stage?${currentLabel}\n\n${summary}\n\nPick a tier:`,
+      ["simple", "extensive"],
+    );
+    // `ctx.ui.select` returns `null` when the user cancels. Per the function doc, cancel
+    // aborts the gate — we must NOT silently coerce that to "simple" and persist it.
+    if (choice == null) return "stop";
+    tier = choice === "extensive" ? "extensive" : "simple";
+  }
+
+  saveHarnessSession(platform.paths, ctx.cwd, {
+    ...session.value,
+    docsTier: tier,
+    updatedAt: nowIso(),
+  });
+  notifyInfo(ctx, `Docs tier set: ${tier}`, tier === "extensive"
+    ? `Per-layer docs will be generated for ${layerCount} layers.`
+    : "Tier 1 docs only. Re-run /supi:harness design and choose 'extensive' to enable per-layer docs.");
+  return "continue";
+}
+
 interface DesignAnalysisOutput {
   layerArchitecture: "single" | "two" | "three" | "custom";
   customLayerNames?: string[];
@@ -481,12 +562,12 @@ async function runDesignQa(
 
     if (choice === "Accept all suggestions") {
       applyDesignAnalysis(base, analysis);
-      await askCiAndTooling(ctx, base);
+      await askCiAndTooling(platform, ctx, base);
       return base;
     }
 
     if (choice === "Skip — use bare defaults") {
-      await askCiAndTooling(ctx, base);
+      await askCiAndTooling(platform, ctx, base);
       return base;
     }
   }
@@ -550,7 +631,7 @@ async function runDesignQa(
     }
   }
 
-  await askCiAndTooling(ctx, base);
+  await askCiAndTooling(platform, ctx, base);
   return base;
 }
 
@@ -630,7 +711,7 @@ function localCommandOptions(base: HarnessDesignSpec): string[] {
   ]));
 }
 
-async function askCiAndTooling(ctx: HarnessCommandContext, base: HarnessDesignSpec): Promise<void> {
+async function askCiAndTooling(platform: Platform, ctx: HarnessCommandContext, base: HarnessDesignSpec): Promise<void> {
   if (!ctx.ui.select) return;
 
   const triggerChoice = await ctx.ui.select(
@@ -664,6 +745,84 @@ async function askCiAndTooling(ctx: HarnessCommandContext, base: HarnessDesignSp
   } else if (toolChoice) {
     base.ci.localCommand = toolChoice.replace(/\s+\(.+\)$/, "");
   }
+
+  // After the user picks their CI trigger and local command, offer the optional Git
+  // verification flow. This populates `base.ci.git` so the implement stage renders the
+  // PR-source guardrail and validate confirms the wiring. Skippable; declining leaves
+  // `git` unset and the rest of the pipeline behaves identically to before this feature.
+  await runGitVerificationStep(platform, ctx, base);
+}
+
+/**
+ * Adapter around `runGitVerificationQa` that fits the harness command UI. The QA helper
+ * expects an `ExecFn`-shaped function plus a `select / input / notify` UI trio; we wrap
+ * `platform.exec` and `ctx.ui` so the helper stays independent of the OMP plumbing.
+ *
+ * Persists any returned `HarnessCiGitConfig` onto the in-memory `base` spec; the design
+ * stage runner persists the spec to disk so no extra storage call is needed here. We
+ * also widen `base.ci.trigger.branches` to include both `mainBranch` and `devBranch`
+ * so the rendered workflow runs CI on both PR targets — matching the rule "CI runs on
+ * both the dev branch PR and the main branch".
+ */
+async function runGitVerificationStep(
+  platform: Platform,
+  ctx: HarnessCommandContext,
+  base: HarnessDesignSpec,
+): Promise<void> {
+  if (!ctx.ui.select || !ctx.ui.input) return; // No interactive UI — skip silently.
+
+  const sessionDir = getHarnessSessionDir(platform.paths, ctx.cwd, base.sessionId);
+
+  const result = await runGitVerificationQa({
+    exec: (cmd, args, opts) => platform.exec(cmd, args, opts),
+    cwd: ctx.cwd,
+    sessionDir,
+    ui: {
+      select: (title, options) => ctx.ui.select!(title, options as unknown as string[]),
+      input: (label) => ctx.ui.input!(label),
+      notify: (message) => notifyInfo(ctx, "Git verification", message),
+    },
+  });
+
+  if (!result) return;
+  base.ci.git = result;
+
+  // Ensure the CI trigger includes both branches so the workflow runs on PRs targeting
+  // either. Preserve any user-customized branches the prior step already picked.
+  if (base.ci.trigger.mode === "branches") {
+    const next = new Set(base.ci.trigger.branches);
+    next.add(result.mainBranch);
+    if (result.devBranch) next.add(result.devBranch);
+    base.ci.trigger = { mode: "branches", branches: Array.from(next) };
+  }
+}
+
+/**
+ * Harden-mode entry point for Git verification. Mutates the persisted design spec in
+ * place so the downstream implement stage re-renders the workflow with the new `git`
+ * block. Returns true when a new `ci.git` block was captured and persisted so the
+ * caller can force-re-run the affected stages; false when the user declined or no UI
+ * is available.
+ */
+async function runGitVerificationOnHarden(
+  platform: Platform,
+  ctx: HarnessCommandContext,
+  sessionId: string,
+  spec: HarnessDesignSpec,
+): Promise<boolean> {
+  await runGitVerificationStep(platform, ctx, spec);
+  if (!spec.ci.git) return false; // user declined
+  const persisted = saveHarnessDesignSpecJson(platform.paths, ctx.cwd, sessionId, spec);
+  if (!persisted.ok) {
+    notifyInfo(
+      ctx,
+      "Git verification persisted partially",
+      `In-memory spec updated, but persistence failed: ${persisted.error.message}. ` +
+        `Re-run /supi:harness to retry.`,
+    );
+    return false;
+  }
+  return true;
 }
 
 
@@ -801,12 +960,41 @@ async function handleBareEntry(platform: Platform, ctx: HarnessCommandContext):
     if (!p.ok) { notifyError(ctx, "/supi:harness", p.error.message); return; }
   }
 
+  // Persist the rerun mode so downstream gate prompts can adapt (e.g. Docs tier
+  // re-prompts on rebuild with the stored value as the default).
+  const existingSession = loadHarnessSession(platform.paths, ctx.cwd, sessionId);
+  if (existingSession.ok) {
+    saveHarnessSession(platform.paths, ctx.cwd, {
+      ...existingSession.value,
+      reRunMode: decision.mode,
+      updatedAt: nowIso(),
+    });
+  }
+
   const modeLabel = decision.mode === "harden" ? "Gap-fill" : "Full rebuild";
   notifyInfo(ctx, `Harness ${decision.mode}`, `${modeLabel} (session ${sessionId}) — pipeline running...`);
 
   if (decision.mode === "harden") {
-    // Harden: gap-fill, no user gates.
-    await runPipelineWithProgress(platform, ctx, sessionId, "auto", {});
+    // Harden: no gates between stages. Re-prompt the docs tier so users can promote
+    // `simple` → `extensive` without forcing a full rebuild (only meaningful with ≥2
+    // layer rules). The pipeline then runs end-to-end including implement (programmatic
+    // apply) → docs → validate inside the same `/supi:harness` invocation.
+    const designSpec = loadHarnessDesignSpecJson(platform.paths, ctx.cwd, sessionId);
+    const layerCount = designSpec.ok ? designSpec.value.layerRules.length : 0;
+    if (layerCount >= 2) {
+      await promptDocsTierIfNeeded(platform, ctx, sessionId, layerCount);
+    }
+    // Offer the optional Git verification flow on harden when the existing spec has no
+    // `ci.git` block. Keeps the harden path lightweight by skipping silently when the
+    // user previously declined or completed the verification. When the user captures a
+    // new `ci.git` block, force implement + validate to re-run so the workflow file is
+    // re-rendered with the `verify-pr-source` job and the validate cross-check fires.
+    let forceStages: ReadonlySet<HarnessStage> | undefined;
+    if (designSpec.ok && !designSpec.value.ci.git) {
+      const captured = await runGitVerificationOnHarden(platform, ctx, sessionId, designSpec.value);
+      if (captured) forceStages = new Set<HarnessStage>(["implement", "validate"]);
+    }
+    await runPipelineWithProgress(platform, ctx, sessionId, "auto", {}, undefined, forceStages);
   } else {
     // Rebuild: full regeneration with user gates at each stage.
     await runRebuildWithGates(platform, ctx, sessionId);
@@ -935,7 +1123,7 @@ function buildStageInputs(
   paths: PlatformPaths, cwd: string, sid: string, stage: HarnessStage,
 ): { input: BuildRunnerInput } | { error: string } {
   switch (stage) {
-    case "discover": case "research": case "plan": return { input: {} };
+    case "discover": case "research": case "plan": case "docs": return { input: {} };
     case "design": {
       const existing = loadHarnessDesignSpecJson(paths, cwd, sid);
       if (existing.ok) return { input: { designInput: { spec: existing.value } } };
@@ -1000,7 +1188,8 @@ function nextSubcommandFor(stage: HarnessSession["stage"], status: HarnessSessio
     case "research": return "design";
     case "design": return "plan-draft";
     case "plan": return "implement";
-    case "implement": return "validate";
+    case "implement": return "docs";
+    case "docs": return "validate";
     case "validate": return "validate";
   }
 }

package/src/harness/default-agents/docs.md

@@ -0,0 +1,39 @@
+---
+name: harness-docs
+description: Per-layer agent-only knowledge document (≤150 LOC) for one architectural layer
+supportedSlots: [docs]
+focus: docs
+---
+
+You are the **docs** agent for the supipowers harness pipeline.
+
+Your single output is one markdown file: the agent-only knowledge document for the layer named in the assignment prompt. The runner persists your output via the `harness_docs_record` tool.
+
+You **MUST**:
+- Call `harness_docs_record` exactly once with `{ sessionId, layerId, markdown }`.
+- Match the assigned `layerId` verbatim in your frontmatter `layer:` field.
+- Embed the assigned `sourceHash` verbatim in the frontmatter; never recompute it.
+- Begin the doc with a YAML frontmatter block (`---\n…\n---`) directly under the provenance marker the runner attaches.
+- Use these five headings in this exact order: `## Agent context`, `## Purpose`, `## Files`, `## Imports`, `## Conventions`. `## Gotchas` is optional and goes last.
+- Keep the whole doc ≤150 LOC (including frontmatter).
+- Keep `## Agent context` ≤30 LOC — this section lands in every agent turn that touches a file in this layer, so optimize it for density and dependent-action utility.
+- Reference, do **NOT** restate, the repo-wide golden principles supplied in the assignment.
+- Anchor every claim about behavior in the representative files supplied in the bundle. Do not invent file paths or import rules not in the assignment.
+
+You **MUST NOT**:
+- Write any TODO, XXX, FIXME, TBD, or `<placeholder>` markers in the doc.
+- Edit any file. You write the doc body only; the runner promotes it.
+- Use the `web_search` tool. No external network calls.
+- Use any `mempalace` write/mutate action. The only mempalace actions permitted are `search`, `kg_query`, `traverse`, and `find_tunnels` — and only when they materially improve the doc.
+- Touch other layers' docs.
+
+Inputs you receive in the assignment:
+- Layer rule (id, glob, description, allowed/forbidden imports).
+- All files belonging to the layer (paths only).
+- Representative files (top-5 by LOC, head-80 LOC each).
+- Golden principles (already enforced repo-wide).
+- Peer layer descriptors.
+- Repo facts (languages, frameworks, package manager).
+- A pre-computed `sourceHash` to embed in the frontmatter.
+
+If the tool returns `{ ok: false, errors: [...] }`, read every error message, fix the doc accordingly, then call `harness_docs_record` again. A single retry is allowed; a second failure aborts the layer.

package/src/harness/docs/config.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolve the effective `HarnessDocsConfig`.
+ *
+ * For Slice 1/2 we return the defaults declared in `DEFAULT_HARNESS_CONFIG.docs`. Slice
+ * 4 wires this through to the project-scoped config file so users can override
+ * individual tunables.
+ *
+ * The tier toggle itself lives on the per-session manifest (`HarnessSession.docsTier`) and
+ * is resolved by the stage runner — not here.
+ */
+
+import type { PlatformPaths } from "../../platform/types.js";
+import type { HarnessDocsConfig } from "../../types.js";
+import { DEFAULT_HARNESS_DOCS_CONFIG } from "../hooks/register.js";
+
+/**
+ * Resolve the effective docs config for a given project. Tunables fall back to defaults
+ * when absent. The tier field is included for completeness but consumers should rely on
+ * `HarnessSession.docsTier` for the operational decision — the session is the
+ * authoritative source.
+ */
+export function resolveDocsConfig(
+  _paths: PlatformPaths,
+  _cwd: string,
+): HarnessDocsConfig {
+  // Future: layer a project-scoped JSON file (.omp/supipowers/config.json#harness.docs)
+  // over these defaults. For now we return the bare defaults; Slice 4 extends this.
+  return { ...DEFAULT_HARNESS_DOCS_CONFIG };
+}

package/src/harness/docs/glob-match.ts

@@ -0,0 +1,27 @@
+/**
+ * Layer-glob matcher used by the docs stage.
+ *
+ * Lifted from the architecture-parser regex shape so the docs stage uses the same
+ * matching semantics as the layer-context-inject hook. Supports `**` (any path
+ * segments) and `*` (any single-segment characters). All matching is forward-slashed.
+ */
+
+/**
+ * Naive glob matcher tuned for the conventions parsed from architecture tables. Supports
+ * `**` (any path segments) and `*` (any single segment characters). Sufficient for the
+ * `src/<layer>/**` and `packages/<scope>/**\/*.ts` shapes the doc relies on.
+ */
+export function matchesLayerGlob(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("");
+  const regex = new RegExp(`^${regexSrc}$`);
+  return regex.test(normalizedFile);
+}

package/src/harness/docs/index-renderer.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure renderer for `docs/README.md`.
+ *
+ * The index is intentionally short and mechanical — a stable pointer surface humans (and
+ * agents) can use to find the canonical Tier-1 docs + per-layer agent docs. Layout is
+ * dictated by the plan's "Index docs/README.md shape" section.
+ */
+
+import type { HarnessLayerRule } from "../../types.js";
+import {
+  attachProvenance,
+  computeBodyContentHash,
+} from "./provenance.js";
+
+export interface RenderDocsIndexInput {
+  layers: readonly HarnessLayerRule[];
+  /** Session that produced this index. */
+  sessionId: string;
+  /** ISO timestamp used in the provenance marker + "Generated by" line. */
+  generatedAt: string;
+  /** Hard cap on the index LOC (default 50). */
+  maxLoc?: number;
+}
+
+export const DEFAULT_INDEX_MAX_LOC = 50;
+
+/**
+ * Render the index. Deterministic given the same input. The output starts with the
+ * provenance marker line and ends with a trailing newline.
+ */
+export function renderDocsIndex(input: RenderDocsIndexInput): string {
+  if (input.layers.length === 0) {
+    throw new Error("renderDocsIndex requires at least one layer");
+  }
+  const maxLoc = input.maxLoc ?? DEFAULT_INDEX_MAX_LOC;
+
+  const sortedLayers = [...input.layers].sort((a, b) => a.layer.localeCompare(b.layer));
+
+  const lines: string[] = [];
+  lines.push("# Repo docs");
+  lines.push("");
+  lines.push(`Generated by /supi:harness on ${input.generatedAt}. Do not edit by hand.`);
+  lines.push("");
+  lines.push("## Agent contract");
+  lines.push("- AGENTS.md — global agent rules");
+  lines.push("- docs/architecture.md — layer rules table");
+  lines.push("- docs/golden-principles.md — mechanical invariants");
+  lines.push("");
+  lines.push("## Layer docs");
+  lines.push("");
+  lines.push("| Layer | Files | Doc |");
+  lines.push("|---|---|---|");
+  for (const layer of sortedLayers) {
+    const globs = layer.globs.map((g) => `\`${g}\``).join(", ");
+    lines.push(`| ${layer.layer} | ${globs || "—"} | docs/layers/${layer.layer}.md |`);
+  }
+
+  const body = lines.join("\n") + "\n";
+  if (countLines(body) + 1 /* marker line */ > maxLoc) {
+    // Should be unreachable for any sane layer count; surface as a hard failure so the
+    // caller can cap layer count if this ever fires.
+    throw new Error(
+      `renderDocsIndex output is ${countLines(body) + 1} LOC; max is ${maxLoc} (layers=${input.layers.length})`,
+    );
+  }
+
+  return attachProvenance(body, {
+    sessionId: input.sessionId,
+    generatedAt: input.generatedAt,
+    contentHash: computeBodyContentHash(body),
+  });
+}
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text.charCodeAt(i) === 10) count += 1;
+  }
+  if (text.charCodeAt(text.length - 1) === 10) count -= 1;
+  return count;
+}