supipowers 2.1.0 → 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/pipeline.ts

@@ -151,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). */
@@ -269,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 });

package/src/harness/stages/implement-apply.ts

@@ -470,11 +470,32 @@ function applyCiWorkflow(
   );
 }
 
+/**
+ * Literal Actions expression `${{ github.event.pull_request.head.ref }}`. Hoisted as a
+ * named constant because the inline `${"${{ ... }}"}` form (TS template literal escaping
+ * a YAML expression) reads as a typo at the call site.
+ */
+const PR_HEAD_REF_EXPR = "${{ github.event.pull_request.head.ref }}";
+
 function renderGithubActionsWorkflow(spec: HarnessDesignSpec): string {
   const trigger = spec.ci.trigger;
+  // Defense in depth: when the PR-source guardrail is on, force `mainBranch` into the
+  // trigger's branch list at render time even if the persisted spec was hand-edited and
+  // omits it. Without this, the `verify-pr-source` job below is dead code on PRs into
+  // main (the workflow never fires). `runGitVerificationStep` widens the set at capture
+  // time too — this is the symmetrical render-time guard.
+  const renderBranches = (() => {
+    if (trigger.mode !== "branches") return null;
+    if (!shouldRenderPrSourceGuardrail(spec)) return trigger.branches;
+    const git = spec.ci.git!;
+    const merged = new Set(trigger.branches);
+    merged.add(git.mainBranch);
+    if (git.devBranch) merged.add(git.devBranch);
+    return Array.from(merged);
+  })();
   const onBlock = trigger.mode === "all-prs"
     ? ["on:", "  pull_request:", "    branches: ['**']"]
-    : ["on:", "  pull_request:", `    branches: [${trigger.branches.map((b) => `'${b}'`).join(", ")}]`];
+    : ["on:", "  pull_request:", `    branches: [${renderBranches!.map((b) => `'${b}'`).join(", ")}]`];
   const setupNode = [
     "      - uses: actions/checkout@v4",
     "      - uses: oven-sh/setup-bun@v2",
@@ -483,7 +504,7 @@ function renderGithubActionsWorkflow(spec: HarnessDesignSpec): string {
   ];
   const installStep = "      - run: bun install";
   const runStep = `      - run: ${spec.ci.localCommand}`;
-  return [
+  const lines: string[] = [
     "# Generated by /supi:harness.",
     "name: Harness Quality",
     ...onBlock,
@@ -497,8 +518,44 @@ function renderGithubActionsWorkflow(spec: HarnessDesignSpec): string {
     ...setupNode,
     installStep,
     runStep,
-    "",
-  ].join("\n");
+  ];
+
+  // PR-source guardrail: when the design recorded a dev branch and asked us to enforce
+  // "main only accepts PRs from dev", append a deterministic job that fails the PR
+  // check whenever a PR targets main from a branch other than dev. This is the
+  // workflow-side complement to the optional GitHub ruleset (which the user may not
+  // have permission to install) — together they provide defense-in-depth.
+  //
+  // Safety: `git.mainBranch` / `git.devBranch` are validated by `isSafeBranchName` at
+  // capture in `runGitVerificationQa`, so the single-quoted YAML expression and the
+  // double-quoted shell line below cannot be broken by injected metacharacters.
+  if (shouldRenderPrSourceGuardrail(spec)) {
+    const git = spec.ci.git!;
+    lines.push(
+      "  verify-pr-source:",
+      `    if: github.event.pull_request.base.ref == '${git.mainBranch}'`,
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - name: Reject PRs into main from non-dev branches",
+      "        run: |",
+      `          if [ "${PR_HEAD_REF_EXPR}" != "${git.devBranch}" ]; then`,
+      `            echo "PRs into '${git.mainBranch}' must come from '${git.devBranch}'." >&2`,
+      "            exit 1",
+      "          fi",
+    );
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+function shouldRenderPrSourceGuardrail(spec: HarnessDesignSpec): boolean {
+  const git = spec.ci.git;
+  if (!git) return false;
+  if (!git.enforceMainFromDevOnly) return false;
+  if (!git.devBranch) return false;
+  if (git.devBranch === git.mainBranch) return false;
+  return true;
 }
 
 async function applyAntiSlopBackend(

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,6 +55,7 @@ import {
   getHarnessAgentsMdPath,
   getHarnessArchitectureDocPath,
   getHarnessGoldenPrinciplesPath,
+  getHarnessSessionDir,
 } from "../project-paths.js";
 import { resolveDocsConfig } from "../docs/config.js";
 import { matchesLayerGlob } from "../docs/glob-match.js";
@@ -279,6 +282,63 @@ function workflowGrantsPrCommentPermission(workflow: string): boolean {
   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,
@@ -395,6 +455,28 @@ async function checkCiLocalWiring(
           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",
@@ -406,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"),