supipowers 2.0.2 → 2.2.0

package/src/harness/git-verify-qa.ts

@@ -0,0 +1,406 @@
+/**
+ * Interactive Git topology + branch-protection sub-step for `/supi:harness`.
+ *
+ * Pure-ish entry point: takes an `ExecFn`, a minimal UI interface, and a session dir, and
+ * returns a populated `HarnessCiGitConfig` (or null when the user opts out). All side
+ * effects — branch creation, ruleset POST, manual-instructions doc — are routed through
+ * the dependencies so the harness command layer can drive it without changing.
+ *
+ * Why split this out of `src/harness/command.ts`? Two reasons:
+ *  1. Testability. The command file is 1100+ LOC and pulls in the full platform/agent
+ *     stack; we want a tight Q&A test surface that operates on a fake UI + scripted
+ *     `exec` results.
+ *  2. Separation of concerns. The command layer owns "when do we ask?", this module owns
+ *     "what do we ask, and what do we do with the answers?".
+ *
+ * Decision tree (matches the user's spec):
+ *  1. Detect topology (default branch + dev candidates).
+ *  2. If default is `main`/`master`:
+ *       a. "Do you have a development branch?"
+ *          - Yes → "Which one?" (existing candidates or custom).
+ *          - No  → "Do you want one?"
+ *                  - Yes → "Name?" → "Create new from main, or promote existing?"
+ *                  - No  → record devBranch=null, no enforcement.
+ *  3. If default is *not* main/master, treat it as already-dev and ask the user to
+ *     confirm + pick a separate "main" branch from the listed remotes.
+ *  4. Optionally apply protections via gh; render manual-instructions doc on any
+ *     skipped/failed protection step.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type {
+  HarnessCiGitConfig,
+  HarnessCiGitFinding,
+} from "../types.js";
+import {
+  applyMainProtectionRuleset,
+  createBranchFromRef,
+  detectGitTopology,
+  isSafeBranchName,
+  renderManualInstructions,
+  type ExecFn,
+  type GhExecOutcome,
+} from "./git-verification.js";
+
+export interface GitVerifyQaUi {
+  select: (title: string, options: string[]) => Promise<string | null>;
+  input: (label: string) => Promise<string | null>;
+  notify: (message: string, level?: "info" | "warning" | "error") => void;
+}
+
+export interface GitVerifyQaInput {
+  exec: ExecFn;
+  cwd: string;
+  ui: GitVerifyQaUi;
+  /** Absolute path to the harness session directory where manual instructions land. */
+  sessionDir: string;
+  /** Clock injection for deterministic tests. */
+  now?: () => string;
+}
+
+const TOP_LEVEL_RUN = "Run verification";
+const TOP_LEVEL_SKIP = "Skip";
+
+/**
+ * Capture-side validation for branch names that flow into the persisted design spec.
+ * Any value that reaches `HarnessCiGitConfig.{mainBranch,devBranch}` is rendered into
+ * the GitHub Actions workflow (single-quoted YAML expression and double-quoted shell
+ * line). We accept only the strict subset defined by `isSafeBranchName` so the render
+ * path stays escape-free and an injected branch name cannot break the workflow.
+ *
+ * Returns the trimmed name on success; pushes a finding and returns `null` otherwise.
+ */
+function captureBranchName(
+  raw: string | null | undefined,
+  role: "main" | "dev",
+  findings: HarnessCiGitFinding[],
+): string | null {
+  const trimmed = raw?.trim() ?? "";
+  if (trimmed.length === 0) return null;
+  if (!isSafeBranchName(trimmed)) {
+    findings.push({
+      severity: "warning",
+      message: `Rejected unsafe ${role} branch name: ${JSON.stringify(trimmed)}`,
+      remediation:
+        "Branch names must match [A-Za-z0-9._/-]+ (no whitespace, quotes, or shell metacharacters). " +
+        "Re-run /supi:harness with a sanitized name.",
+    });
+    return null;
+  }
+  return trimmed;
+}
+
+/**
+ * Drive the interactive Git verification flow.
+ *
+ * Returns:
+ *  - `null` when the user opts out of running verification entirely.
+ *  - A populated `HarnessCiGitConfig` otherwise. Even when sub-steps fail (gh missing,
+ *    branch creation rejected by the remote), we return a config so the design spec
+ *    captures the user's intent — the failures land in `verification.findings`.
+ */
+export async function runGitVerificationQa(
+  input: GitVerifyQaInput,
+): Promise<HarnessCiGitConfig | null> {
+  const now = input.now ?? (() => new Date().toISOString());
+
+  const topLevel = await input.ui.select(
+    "Run Git branching verification now? (checks default branch, optional dev branch, and PR-source restrictions)",
+    [TOP_LEVEL_RUN, TOP_LEVEL_SKIP],
+  );
+  if (topLevel !== TOP_LEVEL_RUN) {
+    return null;
+  }
+
+  const topology = await detectGitTopology(input.exec, input.cwd);
+  input.ui.notify(
+    `Detected default branch: ${topology.mainBranch}` +
+      (topology.devBranchCandidates.length > 0
+        ? ` — dev candidates: ${topology.devBranchCandidates.join(", ")}`
+        : ""),
+    "info",
+  );
+
+  const findings: HarnessCiGitFinding[] = [];
+  const appliedProtections: string[] = [];
+
+  let mainBranch = topology.mainBranch;
+  let devBranch: string | null = null;
+  let enforceMainFromDevOnly = false;
+
+  if (topology.defaultIsMainOrMaster) {
+    const decision = await resolveDevBranchWhenDefaultIsMain(input, topology, findings, appliedProtections);
+    devBranch = decision.devBranch;
+    enforceMainFromDevOnly = decision.enforceMainFromDevOnly;
+  } else {
+    const decision = await resolveDevBranchWhenDefaultIsAlreadyDev(input, topology, findings);
+    if (decision.mainBranch) mainBranch = decision.mainBranch;
+    devBranch = decision.devBranch;
+    enforceMainFromDevOnly = decision.enforceMainFromDevOnly;
+  }
+
+  // Attempt the server-side ruleset opportunistically when enforcement is on.
+  if (enforceMainFromDevOnly && devBranch) {
+    const outcome = await applyMainProtectionRuleset(input.exec, input.cwd, {
+      mainBranch,
+      devBranch,
+    });
+    foldRulesetOutcome(outcome, findings, appliedProtections);
+  }
+
+  // CI-side guardrail always applies when enforcement is on — recorded so the validate
+  // stage can confirm the rendered workflow contains the verify-pr-source job.
+  if (enforceMainFromDevOnly && devBranch) {
+    appliedProtections.push("ci-guardrail");
+  }
+
+  // Manual-instructions doc lives at <session>/git-verification.md whenever any
+  // protection step skipped or failed — gives the user a copy-pasteable fallback.
+  const ghAvailable = appliedProtections.includes("ruleset");
+  const needsManualDoc =
+    enforceMainFromDevOnly && devBranch !== null && !ghAvailable;
+
+  let manualInstructionsPath: string | null = null;
+  if (needsManualDoc) {
+    const md = renderManualInstructions({
+      mainBranch,
+      devBranch,
+      enforceMainFromDevOnly,
+      ghAvailable,
+    });
+    const rel = "git-verification.md";
+    fs.mkdirSync(input.sessionDir, { recursive: true });
+    fs.writeFileSync(path.join(input.sessionDir, rel), md, "utf8");
+    manualInstructionsPath = rel;
+    input.ui.notify(
+      `Wrote manual Git verification steps to ${rel}.`,
+      "info",
+    );
+  }
+
+  return {
+    mainBranch,
+    devBranch,
+    enforceMainFromDevOnly,
+    verification: {
+      checkedAt: now(),
+      appliedProtections,
+      findings,
+      manualInstructionsPath,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Decision sub-flows
+// ---------------------------------------------------------------------------
+
+interface DevDecision {
+  devBranch: string | null;
+  enforceMainFromDevOnly: boolean;
+  /** Set by the "default is already dev" path; left undefined when the caller keeps the detected main. */
+  mainBranch?: string;
+}
+
+async function resolveDevBranchWhenDefaultIsMain(
+  input: GitVerifyQaInput,
+  topology: Awaited<ReturnType<typeof detectGitTopology>>,
+  findings: HarnessCiGitFinding[],
+  appliedProtections: string[],
+): Promise<DevDecision> {
+  const hasOptions = topology.devBranchCandidates.length > 0;
+  const haveDevPrompt = hasOptions
+    ? "Yes — use " + topology.devBranchCandidates[0]
+    : "Yes, I have one";
+  const decision = await input.ui.select(
+    "Do you have a development branch?",
+    [haveDevPrompt, "No, I don't have one"],
+  );
+
+  if (decision && decision.startsWith("Yes")) {
+    if (hasOptions) {
+      const picked = topology.devBranchCandidates[0];
+      const safe = captureBranchName(picked, "dev", findings);
+      if (safe) return { devBranch: safe, enforceMainFromDevOnly: true };
+      return { devBranch: null, enforceMainFromDevOnly: false };
+    }
+    const safe = captureBranchName(
+      await input.ui.input("What is your development branch?"),
+      "dev",
+      findings,
+    );
+    if (safe) return { devBranch: safe, enforceMainFromDevOnly: true };
+    findings.push({
+      severity: "warning",
+      message: "User claimed to have a dev branch but provided no usable name.",
+      remediation: "Re-run /supi:harness and provide a valid branch name.",
+    });
+    return { devBranch: null, enforceMainFromDevOnly: false };
+  }
+
+  // No existing dev branch — ask if they want one.
+  const wantsOne = await input.ui.select(
+    "Do you want a dedicated development branch?",
+    ["Yes — create one", "No, run CI on main only"],
+  );
+  if (!wantsOne || !wantsOne.startsWith("Yes")) {
+    findings.push({
+      severity: "info",
+      message: "User opted out of a dedicated dev branch.",
+      remediation: "Re-run /supi:harness if you change your mind.",
+    });
+    return { devBranch: null, enforceMainFromDevOnly: false };
+  }
+
+  const rawName = (await input.ui.input("What name? (default: dev)"))?.trim() || "dev";
+  const name = captureBranchName(rawName, "dev", findings);
+  if (!name) {
+    return { devBranch: null, enforceMainFromDevOnly: false };
+  }
+  const action = await input.ui.select(
+    `Create \`${name}\` from \`${topology.mainBranch}\`, or promote an existing branch?`,
+    [
+      "Create new branch from main",
+      ...(topology.allBranches.length > 0 ? ["Promote an existing branch"] : []),
+    ],
+  );
+
+  if (action === "Promote an existing branch") {
+    const existingPick = await input.ui.select(
+      "Pick the branch to promote:",
+      topology.allBranches.filter((b) => b !== topology.mainBranch),
+    );
+    const safePick = captureBranchName(existingPick, "dev", findings);
+    if (safePick) {
+      return { devBranch: safePick, enforceMainFromDevOnly: true };
+    }
+    findings.push({
+      severity: "warning",
+      message: "No branch picked for promotion.",
+      remediation: "Re-run /supi:harness to finish wiring the dev branch.",
+    });
+    return { devBranch: null, enforceMainFromDevOnly: false };
+  }
+
+  // Create new branch from main.
+  const outcome = await createBranchFromRef(
+    input.exec,
+    input.cwd,
+    name,
+    `origin/${topology.mainBranch}`,
+  );
+  if (outcome.kind === "created" || outcome.kind === "already-exists") {
+    appliedProtections.push("branch-created");
+    if (outcome.kind === "already-exists") {
+      findings.push({
+        severity: "info",
+        message: `Branch \`${name}\` already exists — reusing.`,
+      });
+    }
+    return { devBranch: name, enforceMainFromDevOnly: true };
+  }
+  findings.push({
+    severity: "error",
+    message: `Failed to create branch \`${name}\`: ${outcome.reason}`,
+    remediation: `Create the branch manually with: git switch -c ${name} origin/${topology.mainBranch} && git push -u origin ${name}`,
+  });
+  // Still record the user's intent so the design spec captures it; protections will be
+  // rejected by validate.
+  return { devBranch: name, enforceMainFromDevOnly: true };
+}
+
+async function resolveDevBranchWhenDefaultIsAlreadyDev(
+  input: GitVerifyQaInput,
+  topology: Awaited<ReturnType<typeof detectGitTopology>>,
+  findings: HarnessCiGitFinding[],
+): Promise<DevDecision> {
+  const otherBranches = topology.allBranches.filter((b) => b !== topology.mainBranch);
+  const pick = await input.ui.select(
+    `\`${topology.mainBranch}\` looks like a development branch. Pick the *dev* branch the harness should target:`,
+    [topology.mainBranch, ...otherBranches],
+  );
+  const devBranch = captureBranchName(pick ?? topology.mainBranch, "dev", findings);
+  if (!devBranch) {
+    return { devBranch: null, enforceMainFromDevOnly: false };
+  }
+
+  // Ask which branch is the protected main.
+  const mainCandidates = topology.allBranches.filter(
+    (b) => b === "main" || b === "master",
+  );
+  let mainBranch: string | null = mainCandidates[0] ?? "main";
+  if (mainCandidates.length === 0) {
+    const provided = await input.ui.input("What is your main/master branch?");
+    if (provided && provided.trim().length > 0) {
+      mainBranch = captureBranchName(provided, "main", findings);
+    }
+  }
+  if (!mainBranch) {
+    return { devBranch, enforceMainFromDevOnly: false };
+  }
+
+  if (mainBranch === devBranch) {
+    findings.push({
+      severity: "warning",
+      message: "Main branch and dev branch are the same; PR-source restriction will be disabled.",
+      remediation: "Re-run /supi:harness and pick distinct branches.",
+    });
+    return { devBranch, mainBranch, enforceMainFromDevOnly: false };
+  }
+
+  return { devBranch, mainBranch, enforceMainFromDevOnly: true };
+}
+
+function foldRulesetOutcome(
+  outcome: GhExecOutcome,
+  findings: HarnessCiGitFinding[],
+  appliedProtections: string[],
+): void {
+  switch (outcome.kind) {
+    case "applied":
+      appliedProtections.push("ruleset");
+      return;
+    case "skipped":
+      switch (outcome.reason) {
+        case "no-cli":
+          findings.push({
+            severity: "warning",
+            message: "`gh` CLI is not installed; could not apply server-side ruleset.",
+            remediation: "Install gh (https://cli.github.com/) and re-run /supi:harness, or follow the manual steps.",
+          });
+          return;
+        case "no-auth":
+          findings.push({
+            severity: "warning",
+            message: "`gh` is not authenticated; could not apply server-side ruleset.",
+            remediation: "Run `gh auth login --scopes admin:repo` and re-run /supi:harness.",
+          });
+          return;
+        case "no-permission":
+          findings.push({
+            severity: "warning",
+            message: "`gh` lacks `admin:repo` scope; could not apply server-side ruleset.",
+            remediation: "Run `gh auth refresh -s admin:repo` and re-run /supi:harness, or follow the manual steps.",
+          });
+          return;
+        case "no-repo":
+          findings.push({
+            severity: "info",
+            message: "Could not detect GitHub repo from `gh repo view`; skipping ruleset.",
+            remediation: "Confirm the repository is connected to GitHub (gh repo view should print owner/repo).",
+          });
+          return;
+        case "no-dev-branch":
+          return; // Should be unreachable here — we gate on devBranch above.
+      }
+    case "failed":
+      findings.push({
+        severity: "error",
+        message: `Ruleset API call failed: ${outcome.reason}`,
+        remediation: "Inspect the failure and apply the ruleset manually via Settings → Rules → Rulesets.",
+      });
+      return;
+  }
+}

package/src/harness/hooks/layer-context-inject.ts

@@ -31,6 +31,8 @@ import {
   getHarnessArchitectureDocPath,
   getHarnessMarkerPath,
 } from "../project-paths.js";
+import { extractAgentContextSection } from "../docs/validator.js";
+import { parseProvenance } from "../docs/provenance.js";
 
 export interface LayerContextHookOptions {
   /**
@@ -86,6 +88,13 @@ export interface LayerContextInjectionResult {
 /**
  * Compute the addendum for a single hook invocation. Pure-ish: reads the file system but
  * never mutates state. Tests call this directly with a known cwd + candidate file.
+ *
+ * Resolution order:
+ *   1. If `docs/layers/<layerId>.md` exists, extract its `## Agent context` section and
+ *      return it (capped at `addendum_max_chars`). This is the preferred path once the
+ *      docs stage has run.
+ *   2. Otherwise, fall back to the architecture-doc-derived addendum so projects that
+ *      have not generated per-layer docs still receive a useful reminder.
  */
 export function computeLayerAddendum(input: {
   cwd: string;
@@ -93,6 +102,8 @@ export function computeLayerAddendum(input: {
   config: HarnessHookConfig["layer_context_inject"];
   /** Override the resolved architecture-doc path; tests use this to point at a fixture. */
   archPath?: string;
+  /** Override the resolved per-layer doc path; tests use this to point at a fixture. */
+  layerDocPath?: (layerId: string) => string;
 }): LayerContextInjectionResult {
   if (!input.config.enabled) return { addendum: "", reason: "disabled" };
   if (!input.candidateFile) return { addendum: "", reason: "no candidate file" };
@@ -101,8 +112,31 @@ export function computeLayerAddendum(input: {
   if (rules.length === 0) return { addendum: "", reason: "no rules parsed" };
   const rule = resolveLayerForFile(input.candidateFile, rules);
   if (!rule) return { addendum: "", reason: "no rule matches candidate file" };
+
+  // Preferred path: per-layer agent doc.
+  const docPath = input.layerDocPath
+    ? input.layerDocPath(rule.layer)
+    : `${input.cwd}/docs/layers/${rule.layer}.md`;
+  if (fs.existsSync(docPath)) {
+    try {
+      const contents = fs.readFileSync(docPath, "utf8");
+      const parsed = parseProvenance(contents);
+      const body = parsed ? parsed.body : contents;
+      const section = extractAgentContextSection(body);
+      if (section.length > 0) {
+        const cap = input.config.addendum_max_chars;
+        const capped = section.length <= cap
+          ? section
+          : `${section.slice(0, Math.max(0, cap - 1))}…`;
+        return { addendum: capped, reason: "matched (per-layer doc)" };
+      }
+    } catch {
+      // fall through to architecture-doc fallback on any read error
+    }
+  }
+
   const addendum = buildLayerAddendum(input.candidateFile, rule, input.config.addendum_max_chars);
-  return { addendum, reason: "matched" };
+  return { addendum, reason: "matched (architecture.md fallback)" };
 }
 
 /**

package/src/harness/hooks/register.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Platform } from "../../platform/types.js";
-import type { HarnessConfig, HarnessHookConfig } from "../../types.js";
+import type { HarnessConfig, HarnessDocsConfig, HarnessHookConfig } from "../../types.js";
 import { buildBackendAdapter } from "../anti_slop/backend-factory.js";
 import {
   registerLayerContextInjectHook,
@@ -31,9 +31,21 @@ export const DEFAULT_HARNESS_HOOK_CONFIG: HarnessHookConfig = {
   score_floor: { strict: 75, lenient: 90, release_blocking: false },
 };
 
+export const DEFAULT_HARNESS_DOCS_CONFIG: HarnessDocsConfig = {
+  tier: "simple",
+  max_per_doc_loc: 150,
+  agent_context_loc: 30,
+  max_index_loc: 50,
+  max_units: 12,
+  max_concurrent_subagents: null,
+  drift_warning: { enabled: true },
+  regen_preview_threshold: 1,
+};
+
 export const DEFAULT_HARNESS_CONFIG: HarnessConfig = {
   anti_slop: DEFAULT_HARNESS_HOOK_CONFIG,
   implement_in_session_threshold: 10,
+  docs: DEFAULT_HARNESS_DOCS_CONFIG,
 };
 
 export interface HarnessHookRegistration {
@@ -54,19 +66,28 @@ export interface RegisterHooksOptions {
    * unless a real resolver is wired).
    */
   resolveCandidateFile?: (event: unknown, ctx: unknown) => string | null;
+  /** CWD whose repo-local marker controls registration. Defaults to process.cwd(). */
+  cwd?: string;
 }
 
 // Re-export so existing call sites keep working without an import path change.
 export { buildBackendAdapter };
 
 /**
- * Register every harness hook. Idempotent at the dispose boundary: calling
- * `dispose()` twice is safe.
+ * Register every harness hook. Hooks subscribe unconditionally at bootstrap time; each
+ * hook checks the repo-local marker per event, so creating the marker after install
+ * activates already-registered handlers without an OMP restart, and removing the marker
+ * disables them. `dispose()` is idempotent.
+ *
+ * The `cwd` option is retained for tests that exercise the legacy marker check; it is
+ * unused by the new registration path because per-event handlers resolve cwd from the
+ * event payload.
  */
 export function registerHarnessHooks(
   platform: Platform,
   options: RegisterHooksOptions = {},
 ): HarnessHookRegistration {
+  void options.cwd; // reserved for future per-repo gating
   const backend = options.backend ?? "fallow";
   const hooks = options.hooks ?? DEFAULT_HARNESS_HOOK_CONFIG;
   const adapter = buildBackendAdapter(backend);

package/src/harness/pipeline.ts

@@ -31,6 +31,7 @@ import {
 } from "./stages/design.js";
 import { HarnessPlanStage, type PlanStageInput } from "./stages/plan.js";
 import { HarnessImplementStage, type ImplementStageInput } from "./stages/implement.js";
+import { HarnessDocsStage, type DocsStageInput } from "./stages/docs.js";
 import { HarnessValidateStage, type ValidateStageInput } from "./stages/validate.js";
 import { loadHarnessDesignSpecJson, loadHarnessDiscover } from "./storage.js";
 import { buildBackendAdapter } from "./anti_slop/backend-factory.js";
@@ -52,6 +53,7 @@ const STAGE_ORDER: readonly HarnessStage[] = [
   "design",
   "plan",
   "implement",
+  "docs",
   "validate",
 ];
 
@@ -60,6 +62,7 @@ const GATE_STAGES_DEFAULT: ReadonlySet<HarnessStage> = new Set([
   "discover",
   "design",
   "plan",
+  "docs",
   "validate",
 ]);
 const GATE_STAGES_MANUAL: ReadonlySet<HarnessStage> = new Set([
@@ -68,6 +71,7 @@ const GATE_STAGES_MANUAL: ReadonlySet<HarnessStage> = new Set([
   "design",
   "plan",
   "implement",
+  "docs",
   "validate",
 ]);
 
@@ -89,6 +93,8 @@ export interface BuildRunnerInput {
   planInput?: PlanStageInput;
   /** Required when running the implement stage. */
   implementInput?: ImplementStageInput;
+  /** Optional override for the docs stage (tier, max-units, test-only factories). */
+  docsInput?: DocsStageInput;
   /** Required when running the validate stage. */
   validateInput?: ValidateStageInput;
 }
@@ -111,6 +117,8 @@ export function buildHarnessRunner(stage: HarnessStage, input: BuildRunnerInput)
         throw new Error("buildHarnessRunner: implement stage requires implementInput");
       }
       return new HarnessImplementStage(input.implementInput);
+    case "docs":
+      return new HarnessDocsStage(input.docsInput ?? {});
     case "validate":
       if (!input.validateInput) {
         throw new Error("buildHarnessRunner: validate stage requires validateInput");
@@ -143,6 +151,12 @@ export interface PipelineDriverInput {
    * complete). Used by per-stage subcommands.
    */
   startStage?: HarnessStage;
+  /**
+   * Stages listed here bypass their `isComplete` short-circuit. Used by the harden
+   * path after mutating the persisted design spec to force a fresh re-render even when
+   * a prior successful run left the stage's completion artifact on disk.
+   */
+  forceStages?: ReadonlySet<HarnessStage>;
   /** Hard cap on stage iterations. */
   safetyLimit?: number;
   /** Optional callback for progress events (wire up a progress widget). */
@@ -215,6 +229,15 @@ function formatStageDetail(result: HarnessStageRunResult): string {
     const layers = typeof d.layerCount === "number" ? `${d.layerCount} layers` : "";
     return layers ? `${backend} · ${layers}` : `${backend}`;
   }
+  if (result.stage === "docs") {
+    const regen = Array.isArray(d.regenerated) ? (d.regenerated as string[]).length : 0;
+    const skip = Array.isArray(d.skipped) ? (d.skipped as string[]).length : 0;
+    const user = Array.isArray(d.userEdited) ? (d.userEdited as string[]).length : 0;
+    if (typeof d.tier === "string" && d.tier === "extensive") {
+      return `${regen} regen · ${skip} skip${user > 0 ? ` · ${user} user-edited` : ""}`;
+    }
+    if (typeof d.reason === "string") return d.reason;
+  }
   if (result.stage === "validate" && typeof d.passed === "boolean") {
     return d.passed ? "passed" : "issues found";
   }
@@ -252,14 +275,17 @@ export async function runHarnessPipelineUntilGate(
     const stageInputs = ensureStageInputs(input, stage);
     const runner = buildHarnessRunner(stage, stageInputs);
 
-    const isComplete = await runner.isComplete({
-      platform: input.platform,
-      paths: input.paths,
-      cwd: input.cwd,
-      sessionId: input.sessionId,
-      modelConfig: input.modelConfig,
-      gateMode: input.gates,
-    });
+    const forced = input.forceStages?.has(stage) ?? false;
+    const isComplete = forced
+      ? false
+      : await runner.isComplete({
+          platform: input.platform,
+          paths: input.paths,
+          cwd: input.cwd,
+          sessionId: input.sessionId,
+          modelConfig: input.modelConfig,
+          gateMode: input.gates,
+        });
 
     if (isComplete) {
       input.onProgress?.({ type: "stage-skipped", stage });
@@ -279,9 +305,9 @@ export async function runHarnessPipelineUntilGate(
 
     const result = await runner.run(ctx);
 
-    // In auto mode, awaiting-user is equivalent to completed — normalize
-    // both the trace entry and any outcome derived from it so the UI never
-    // shows a confusing mix of checkmarks and "awaiting user".
+    // In auto mode, awaiting-user from authoring stages (design, etc.) is equivalent to
+    // completed: the artifact is on disk and the next stage can consume it. Gates honor
+    // awaiting-user as a real stop signal.
     const isGate = gateStages.has(stage);
     const normalizedStatus: HarnessStageRunResult["status"] =
       result.status === "awaiting-user" && !isGate
@@ -307,8 +333,6 @@ export async function runHarnessPipelineUntilGate(
       };
     }
 
-    // In auto mode, awaiting-user is equivalent to completed — the pipeline
-    // continues without stopping. Only surface the distinction when gated.
     if (normalizedStatus === "awaiting-user" && isGate) {
       input.onProgress?.({ type: "awaiting-user", stage, detail: awaitUserDetail(result) });
     } else {