From fdda9ef41a711c0b504169281685d7f289892cc4 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 12:03:45 -0700
Subject: [PATCH 01/13] refactor(review): extract shared candidates+validator
 prompts to src/core/review/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both Pass 1 (candidate generation) and Pass 2 (validator) prompts were
~95% identical between GitHub and GitLab — same skill invocation, same
output schema, same critical constraints. Differences were limited to
labels (PR/MR, Repo/Project), JSON meta keys (prNumber/mrIid,
baseRef/targetBranch), MCP tool names, and a handful of platform-specific
instruction lines.

Extract the shared structure into platform-agnostic builders under
src/core/review/prompts/ that take a ReviewTerminology shape, and convert
the four existing prompt files into thin adapters:

  src/core/review/prompts/
    types.ts        ReviewTerminology + ReviewPromptContext
    candidates.ts   generateCandidatesPrompt(ctx)
    validator.ts    generateValidatorPrompt(ctx)

  src/create-prompt/terminology.ts        GITHUB_TERMINOLOGY constant
  src/gitlab/prompts/terminology.ts       GITLAB_TERMINOLOGY + factory

Both platform-specific wrappers now just map their context shape onto
ReviewPromptContext and delegate. GitLab's submit_review needs the MR IID
re-asserted in the tool call, so we expose a gitlabTerminologyFor(mrIid)
helper that bakes it into the submit_review hint.

Net LOC is roughly even on this commit alone (+61), but ~280 LOC of
literal duplication is gone, and any future shared prompt (security
review/report when GitLab adds it) gets the shared scaffolding for free.

All 29 prompt-specific tests still pass on both platforms; full suite
445/445; tsc clean.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/prompts/candidates.ts         | 146 ++++++++++++++++
 src/core/review/prompts/types.ts              |  91 ++++++++++
 src/core/review/prompts/validator.ts          | 138 +++++++++++++++
 .../templates/review-candidates-prompt.ts     | 165 ++++--------------
 .../templates/review-validator-prompt.ts      | 155 ++++------------
 src/create-prompt/terminology.ts              |  32 ++++
 src/gitlab/prompts/candidates.ts              | 161 +++--------------
 src/gitlab/prompts/terminology.ts             |  48 +++++
 src/gitlab/prompts/validator.ts               | 145 +++------------
 9 files changed, 571 insertions(+), 510 deletions(-)
 create mode 100644 src/core/review/prompts/candidates.ts
 create mode 100644 src/core/review/prompts/types.ts
 create mode 100644 src/core/review/prompts/validator.ts
 create mode 100644 src/create-prompt/terminology.ts
 create mode 100644 src/gitlab/prompts/terminology.ts

diff --git a/src/core/review/prompts/candidates.ts b/src/core/review/prompts/candidates.ts
new file mode 100644
index 0000000..738c3c0
--- /dev/null
+++ b/src/core/review/prompts/candidates.ts
@@ -0,0 +1,146 @@
+/**
+ * Platform-agnostic Pass 1 (candidate generation) prompt.
+ *
+ * Both `src/create-prompt/templates/review-candidates-prompt.ts` (GitHub)
+ * and `src/gitlab/prompts/candidates.ts` (GitLab) delegate to this builder
+ * via thin adapters that supply a `ReviewTerminology` object plus the
+ * runtime context (entity number, SHAs, artifact paths). The /review skill
+ * itself is platform-agnostic; this builder produces the runtime harness
+ * (where to read inputs, where to write the candidates JSON, what NOT to
+ * call) around it.
+ *
+ * STRICT contract: this prompt MUST NOT instruct the model to call any
+ * posting tool. Posting is Pass 2's responsibility, and tool gating is
+ * additionally enforced at the `droid exec` level via `--enabled-tools`.
+ */
+
+import type { ReviewPromptContext } from "./types";
+
+export function generateCandidatesPrompt(ctx: ReviewPromptContext): string {
+  const {
+    terminology: t,
+    entityNumber,
+    repoOrProject,
+    headRef,
+    headSha,
+    baseRef,
+    diffPath,
+    commentsPath,
+    descriptionPath,
+    candidatesPath,
+    includeSuggestions,
+    securityReviewEnabled,
+  } = ctx;
+
+  const bodyFieldDescription = includeSuggestions
+    ? "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation.\n" +
+      "    Follow the suggestion block rules from the review skill when including suggestions."
+    : "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation";
+
+  const sideFieldDescription = includeSuggestions
+    ? '  - `side`: "RIGHT" for new/modified code (default). Use "LEFT" only for removed code **without** suggestions.\n' +
+      "    If you include a suggestion block, choose a RIGHT-side anchor and keep it unchanged so the validator can reuse it."
+    : '  - `side`: "RIGHT" for new/modified code (default), "LEFT" only for removed code';
+
+  const skillInstruction = includeSuggestions
+    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure — including suggestion block rules."
+    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure. Do NOT include code suggestion blocks.";
+
+  const securitySubagentInstruction = securityReviewEnabled
+    ? `
+
+## Security Review (run concurrently)
+
+In addition to the code review, you MUST also spawn a \`security-reviewer\` subagent via the Task tool.
+This subagent runs **concurrently** with the code review subagents during Step 2.
+
+Spawn it with:
+- \`subagent_type\`: "security-reviewer"
+- \`description\`: "Security review"
+- \`prompt\`: Include the full ${t.entityNoun} context (${t.repoLabel.toLowerCase()}, ${t.entityNoun} ${t.metaEntityNumberKey === "prNumber" ? "number" : "IID"}, head SHA, ${t.baseRefLabel.toLowerCase()}) and the paths to precomputed data files (diff, description, existing comments). The security-reviewer will invoke the security-review skill and return a JSON array of security findings.
+
+**IMPORTANT**: Spawn the security-reviewer in the SAME response as the code review subagents so they all run in parallel.
+
+After all subagents complete (both code review and security-reviewer), merge the security findings into the \`comments\` array alongside code review findings. Security findings use the same schema but are prefixed with \`[security]\` in their body (e.g., \`[P1] [security] Title\`).
+`
+    : "";
+
+  return `You are a senior staff software engineer and expert code reviewer.
+
+Your task: Review ${t.entityNoun} ${t.entityNumberSigil}${entityNumber} in ${repoOrProject} and generate a JSON file with **high-confidence, actionable** review comments that pinpoint genuine issues.
+
+${skillInstruction}${securitySubagentInstruction}
+
+<context>
+${t.repoLabel}: ${repoOrProject}
+${t.entityNumberLabel}: ${entityNumber}
+${t.headRefLabel}: ${headRef}
+${t.headShaLabel}: ${headSha}
+${t.baseRefLabel}: ${baseRef}
+
+Precomputed data files:
+- ${t.descriptionLabel}: \`${descriptionPath}\`
+- ${t.diffLabel}: \`${diffPath}\`
+- Existing Comments: \`${commentsPath}\`
+</context>
+
+<output_spec>
+Write output to \`${candidatesPath}\` using this exact schema:
+
+\`\`\`json
+{
+  "version": 1,
+  "meta": {
+    "${t.metaRepoKey}": "${t.repoExample}",
+    "${t.metaEntityNumberKey}": 123,
+    "headSha": "<head sha>",
+    "${t.metaBaseRefKey}": "main",
+    "generatedAt": "<ISO timestamp>"
+  },
+  "comments": [
+    {
+      "path": "src/index.ts",
+      "body": "[P1] Title\\n\\n1 paragraph.",
+      "line": 42,
+      "startLine": null,
+      "side": "RIGHT",
+      "commit_id": "<head sha>"
+    }
+  ],
+  "reviewSummary": {
+    "body": "1-3 sentence overall assessment"
+  }
+}
+\`\`\`
+
+<schema_details>
+- **version**: Always \`1\`
+
+- **meta**: Metadata object
+  - \`${t.metaRepoKey}\`: "${repoOrProject}"
+  - \`${t.metaEntityNumberKey}\`: ${entityNumber}
+  - \`headSha\`: "${headSha}"
+  - \`${t.metaBaseRefKey}\`: "${baseRef}"
+  - \`generatedAt\`: ISO 8601 timestamp (e.g., "2024-01-15T10:30:00Z")
+
+- **comments**: Array of comment objects
+  - \`path\`: ${t.pathFieldDescription}
+${bodyFieldDescription}
+  - \`line\`: ${t.lineFieldDescription}
+  - \`startLine\`: \`null\` for single-line comments, or start line number for multi-line comments
+${sideFieldDescription}
+  - \`commit_id\`: "${headSha}"
+
+- **reviewSummary**:
+  - \`body\`: 1-3 sentence overall assessment
+</schema_details>
+</output_spec>
+
+<critical_constraints>
+**DO NOT** post to ${t.platformName}.
+**DO NOT** invoke any ${t.entityNoun} mutation tools ${t.mutationToolForbiddance}.
+**DO NOT** modify any files other than writing to \`${candidatesPath}\`.
+Output ONLY the JSON file—no additional commentary.
+</critical_constraints>
+`;
+}
diff --git a/src/core/review/prompts/types.ts b/src/core/review/prompts/types.ts
new file mode 100644
index 0000000..e65cfef
--- /dev/null
+++ b/src/core/review/prompts/types.ts
@@ -0,0 +1,91 @@
+/**
+ * Shared types for the platform-agnostic review prompts.
+ *
+ * The candidate-generation (Pass 1) and validator (Pass 2) prompts are
+ * structurally identical between GitHub and GitLab. The only things that
+ * vary are labels, identifier names, MCP tool names, and a small number
+ * of platform-specific instruction lines. Those variations are captured
+ * here so the shared templates can stay platform-agnostic.
+ */
+
+export interface ReviewTerminology {
+  /** "PR" or "MR" */
+  entityNoun: string;
+  /** "#" for GitHub PRs, "!" for GitLab MRs */
+  entityNumberSigil: string;
+  /** "GitHub" or "GitLab" */
+  platformName: string;
+  /** Label for the repo/project value (e.g. "Repo" or "Project") */
+  repoLabel: string;
+  /** Label for the entity number row in <context> (e.g. "PR Number" or "MR IID") */
+  entityNumberLabel: string;
+  /** Label for the source branch row (e.g. "PR Head Ref" or "MR Source Branch") */
+  headRefLabel: string;
+  /** Label for the head SHA row (e.g. "PR Head SHA" or "MR Head SHA") */
+  headShaLabel: string;
+  /** Label for the target branch row (e.g. "PR Base Ref" or "MR Target Branch") */
+  baseRefLabel: string;
+  /** Label for the description artifact (e.g. "PR Description" or "MR Description") */
+  descriptionLabel: string;
+  /** Label for the diff artifact (e.g. "Full PR Diff" or "Full MR Diff") */
+  diffLabel: string;
+  /** JSON meta key for the repo identifier (e.g. "repo" or "project") */
+  metaRepoKey: string;
+  /** JSON meta key for the entity number (e.g. "prNumber" or "mrIid") */
+  metaEntityNumberKey: string;
+  /** JSON meta key for the base ref (e.g. "baseRef" or "targetBranch") */
+  metaBaseRefKey: string;
+  /** Example identifier in schema doc (e.g. "owner/repo" or "group/project") */
+  repoExample: string;
+  /** Free-form description for the `path` field (small wording variation) */
+  pathFieldDescription: string;
+  /** Free-form description for the `line` field (small wording variation) */
+  lineFieldDescription: string;
+  /** Free-form blurb listing mutation tools the candidates pass MUST NOT use */
+  mutationToolForbiddance: string;
+  /** MCP tool name for posting a batched review (Pass 2) */
+  submitReviewToolName: string;
+  /** Extra args appended to the submit_review instruction (e.g. " along with `mr_iid: 5`") */
+  submitReviewExtraArg: string;
+  /** Trailing clause on the "Do NOT include a body parameter" line */
+  submitReviewBodyExclusionTrailer: string;
+  /** MCP tool name for updating the sticky tracking comment/note */
+  updateTrackingToolName: string;
+  /** Human-readable name for the sticky comment (e.g. "tracking comment" or "sticky tracking note") */
+  trackingCommentName: string;
+  /** "comment" (GH) or "top-level note" (GL), used in "post the summary as a separate X" */
+  summaryEntityName: string;
+  /** Trailing clause on the summary-forbiddance line (e.g. " or as the body of `submit_review`" on GH; "" on GL) */
+  summaryPostingExtraExclusion: string;
+  /** Approval/changes line at the end of validator instructions */
+  approvalChangesNote: string;
+  /** Optional security-badge instruction line — GL only */
+  securityBadgeInstruction?: string;
+}
+
+export interface ReviewPromptContext {
+  terminology: ReviewTerminology;
+  /** PR number / MR IID */
+  entityNumber: number | string;
+  /** Full repo/project identifier */
+  repoOrProject: string;
+  /** Source branch name */
+  headRef: string;
+  /** Head SHA */
+  headSha: string;
+  /** Target branch name */
+  baseRef: string;
+  /** On-disk path to the diff artifact */
+  diffPath: string;
+  /** On-disk path to existing-comments JSON */
+  commentsPath: string;
+  /** On-disk path to description text */
+  descriptionPath: string;
+  /** On-disk path where Pass 1 writes the candidates JSON */
+  candidatesPath: string;
+  /** On-disk path where Pass 2 writes the validated JSON (validator only) */
+  validatedPath?: string;
+  includeSuggestions: boolean;
+  /** Spawn security-reviewer subagent during Pass 1 (candidates only) */
+  securityReviewEnabled: boolean;
+}
diff --git a/src/core/review/prompts/validator.ts b/src/core/review/prompts/validator.ts
new file mode 100644
index 0000000..50c2c40
--- /dev/null
+++ b/src/core/review/prompts/validator.ts
@@ -0,0 +1,138 @@
+/**
+ * Platform-agnostic Pass 2 (validator) prompt.
+ *
+ * The validator reads the candidates JSON produced by Pass 1, validates
+ * each one, writes a refined JSON to disk, and posts the approved
+ * findings as a single batched call to the platform's submit-review tool.
+ * Both `src/create-prompt/templates/review-validator-prompt.ts` (GitHub)
+ * and `src/gitlab/prompts/validator.ts` (GitLab) delegate to this builder
+ * via thin adapters that supply a `ReviewTerminology` shape.
+ *
+ * Pass 2 is the only place where the posting tool is exposed (via
+ * `--enabled-tools` on the second `droid exec` invocation).
+ */
+
+import type { ReviewPromptContext } from "./types";
+
+export function generateValidatorPrompt(ctx: ReviewPromptContext): string {
+  const {
+    terminology: t,
+    entityNumber,
+    repoOrProject,
+    headRef,
+    headSha,
+    baseRef,
+    diffPath,
+    commentsPath,
+    descriptionPath,
+    candidatesPath,
+    validatedPath,
+    includeSuggestions,
+  } = ctx;
+
+  if (!validatedPath) {
+    throw new Error("validator prompt requires validatedPath in context");
+  }
+
+  const skillInstruction = includeSuggestions
+    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure — including suggestion block rules."
+    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure. Do NOT include code suggestion blocks.";
+
+  const securityBadgeLine = t.securityBadgeInstruction
+    ? `\n* ${t.securityBadgeInstruction}`
+    : "";
+
+  return `You are validating candidate review comments for ${t.entityNoun} ${t.entityNumberSigil}${entityNumber} in ${repoOrProject}.
+
+IMPORTANT: This is Phase 2 (validator) of a two-pass review pipeline.
+
+${skillInstruction}
+
+### Context
+
+* ${t.repoLabel}: ${repoOrProject}
+* ${t.entityNumberLabel}: ${entityNumber}
+* ${t.headRefLabel}: ${headRef}
+* ${t.headShaLabel}: ${headSha}
+* ${t.baseRefLabel}: ${baseRef}
+
+### Inputs
+
+Read these files before validating:
+* ${t.descriptionLabel}: \`${descriptionPath}\`
+* Candidates: \`${candidatesPath}\`
+* ${t.diffLabel}: \`${diffPath}\`
+* Existing Comments: \`${commentsPath}\`
+
+If the diff is large, read in chunks (offset/limit). **Do not proceed until you have read the ENTIRE diff.**
+
+### Critical Requirements
+
+1. You MUST read and validate **every** candidate before posting anything.
+2. Preserve ordering: keep results in the same order as candidates.
+3. **Posting rule (STRICT):** Only post comments where \`status === "approved"\`. Never post rejected items.
+
+### Output: Write \`${validatedPath}\`
+
+\`\`\`json
+{
+  "version": 1,
+  "meta": {
+    "${t.metaRepoKey}": "${repoOrProject}",
+    "${t.metaEntityNumberKey}": ${entityNumber},
+    "headSha": "${headSha}",
+    "${t.metaBaseRefKey}": "${baseRef}",
+    "validatedAt": "<ISO timestamp>"
+  },
+  "results": [
+    {
+      "status": "approved",
+      "comment": {
+        "path": "src/index.ts",
+        "body": "[P1] Title\\n\\n1 paragraph.",
+        "line": 42,
+        "startLine": null,
+        "side": "RIGHT",
+        "commit_id": "${headSha}"
+      }
+    },
+    {
+      "status": "rejected",
+      "candidate": {
+        "path": "src/other.ts",
+        "body": "[P2] ...",
+        "line": 10,
+        "startLine": null,
+        "side": "RIGHT",
+        "commit_id": "${headSha}"
+      },
+      "reason": "Not a real bug because ..."
+    }
+  ],
+  "reviewSummary": {
+    "status": "approved",
+    "body": "1-3 sentence overall assessment"
+  }
+}
+\`\`\`
+
+Notes:
+* Use \`commit_id\` = \`${headSha}\`.
+* \`results\` MUST have exactly one entry per candidate, in the same order.
+
+Tooling note:
+* If the tools list includes \`ApplyPatch\` (common for OpenAI models like GPT-5.2), use \`ApplyPatch\` to create/update the file at the exact path.
+* Otherwise, use \`Create\` (or \`Edit\` if overwriting) to write the file.
+
+### Post approved items
+
+After writing \`${validatedPath}\`, post comments ONLY for \`status === "approved"\`:
+
+* Collect all approved comments and submit them as a **single batched review** via \`${t.submitReviewToolName}\`, passing them in the \`comments\` array parameter${t.submitReviewExtraArg}.
+* Do **NOT** post comments individually — batch them all into one \`submit_review\` call.
+* Do **NOT** include a \`body\` parameter in \`submit_review\`${t.submitReviewBodyExclusionTrailer}.
+* Use \`${t.updateTrackingToolName}\` to update the ${t.trackingCommentName} with the review summary.${securityBadgeLine}
+* Do **NOT** post the summary as a separate ${t.summaryEntityName}${t.summaryPostingExtraExclusion}.
+* ${t.approvalChangesNote}
+`;
+}
diff --git a/src/create-prompt/templates/review-candidates-prompt.ts b/src/create-prompt/templates/review-candidates-prompt.ts
index a596041..310d551 100644
--- a/src/create-prompt/templates/review-candidates-prompt.ts
+++ b/src/create-prompt/templates/review-candidates-prompt.ts
@@ -1,3 +1,14 @@
+/**
+ * GitHub Pass-1 (candidate generation) prompt — thin adapter.
+ *
+ * Delegates to the platform-agnostic builder in
+ * `src/core/review/prompts/candidates.ts`, mapping the GitHub
+ * `PreparedContext` shape onto the shared `ReviewPromptContext` and
+ * supplying `GITHUB_TERMINOLOGY` (PR labels, github_* MCP tool names).
+ */
+
+import { generateCandidatesPrompt } from "../../core/review/prompts/candidates";
+import { GITHUB_TERMINOLOGY } from "../terminology";
 import type { PreparedContext } from "../types";
 
 export function generateReviewCandidatesPrompt(
@@ -9,137 +20,25 @@ export function generateReviewCandidatesPrompt(
       ? String(context.githubContext.entityNumber)
       : "unknown";
 
-  const repoFullName = context.repository;
-  const prHeadRef = context.prBranchData?.headRefName ?? "unknown";
-  const prHeadSha = context.prBranchData?.headRefOid ?? "unknown";
-  const prBaseRef = context.eventData.baseBranch ?? "unknown";
-
-  const diffPath =
-    context.reviewArtifacts?.diffPath ?? "$RUNNER_TEMP/droid-prompts/pr.diff";
-  const commentsPath =
-    context.reviewArtifacts?.commentsPath ??
-    "$RUNNER_TEMP/droid-prompts/existing_comments.json";
-  const descriptionPath =
-    context.reviewArtifacts?.descriptionPath ??
-    "$RUNNER_TEMP/droid-prompts/pr_description.txt";
-
-  const reviewCandidatesPath =
-    process.env.REVIEW_CANDIDATES_PATH ??
-    "$RUNNER_TEMP/droid-prompts/review_candidates.json";
-
-  const includeSuggestions = context.includeSuggestions !== false;
-
-  const bodyFieldDescription = includeSuggestions
-    ? "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation.\n" +
-      "    Follow the suggestion block rules from the review skill when including suggestions."
-    : "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation";
-
-  const sideFieldDescription = includeSuggestions
-    ? '  - `side`: "RIGHT" for new/modified code (default). Use "LEFT" only for removed code **without** suggestions.\n' +
-      "    If you include a suggestion block, choose a RIGHT-side anchor and keep it unchanged so the validator can reuse it."
-    : '  - `side`: "RIGHT" for new/modified code (default), "LEFT" only for removed code';
-
-  const skillInstruction = includeSuggestions
-    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure — including suggestion block rules."
-    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure. Do NOT include code suggestion blocks.";
-
-  const securityReviewEnabled = process.env.SECURITY_REVIEW_ENABLED === "true";
-
-  const securitySubagentInstruction = securityReviewEnabled
-    ? `
-
-## Security Review (run concurrently)
-
-In addition to the code review, you MUST also spawn a \`security-reviewer\` subagent via the Task tool.
-This subagent runs **concurrently** with the code review subagents during Step 2.
-
-Spawn it with:
-- \`subagent_type\`: "security-reviewer"
-- \`description\`: "Security review"
-- \`prompt\`: Include the full PR context (repo, PR number, head SHA, base ref) and the paths to precomputed data files (diff, description, existing comments). The security-reviewer will invoke the security-review skill and return a JSON array of security findings.
-
-**IMPORTANT**: Spawn the security-reviewer in the SAME response as the code review subagents so they all run in parallel.
-
-After all subagents complete (both code review and security-reviewer), merge the security findings into the \`comments\` array alongside code review findings. Security findings use the same schema but are prefixed with \`[security]\` in their body (e.g., \`[P1] [security] Title\`).
-`
-    : "";
-
-  return `You are a senior staff software engineer and expert code reviewer.
-
-Your task: Review PR #${prNumber} in ${repoFullName} and generate a JSON file with **high-confidence, actionable** review comments that pinpoint genuine issues.
-
-${skillInstruction}${securitySubagentInstruction}
-
-<context>
-Repo: ${repoFullName}
-PR Number: ${prNumber}
-PR Head Ref: ${prHeadRef}
-PR Head SHA: ${prHeadSha}
-PR Base Ref: ${prBaseRef}
-
-Precomputed data files:
-- PR Description: \`${descriptionPath}\`
-- Full PR Diff: \`${diffPath}\`
-- Existing Comments: \`${commentsPath}\`
-</context>
-
-<output_spec>
-Write output to \`${reviewCandidatesPath}\` using this exact schema:
-
-\`\`\`json
-{
-  "version": 1,
-  "meta": {
-    "repo": "owner/repo",
-    "prNumber": 123,
-    "headSha": "<head sha>",
-    "baseRef": "main",
-    "generatedAt": "<ISO timestamp>"
-  },
-  "comments": [
-    {
-      "path": "src/index.ts",
-      "body": "[P1] Title\\n\\n1 paragraph.",
-      "line": 42,
-      "startLine": null,
-      "side": "RIGHT",
-      "commit_id": "<head sha>"
-    }
-  ],
-  "reviewSummary": {
-    "body": "1-3 sentence overall assessment"
-  }
-}
-\`\`\`
-
-<schema_details>
-- **version**: Always \`1\`
-
-- **meta**: Metadata object
-  - \`repo\`: "${repoFullName}"
-  - \`prNumber\`: ${prNumber}
-  - \`headSha\`: "${prHeadSha}"
-  - \`baseRef\`: "${prBaseRef}"
-  - \`generatedAt\`: ISO 8601 timestamp (e.g., "2024-01-15T10:30:00Z")
-
-- **comments**: Array of comment objects
-  - \`path\`: Relative file path (e.g., "src/index.ts")
-${bodyFieldDescription}
-  - \`line\`: Target line number (single-line) or end line number (multi-line). Must be ≥ 0.
-  - \`startLine\`: \`null\` for single-line comments, or start line number for multi-line comments
-${sideFieldDescription}
-  - \`commit_id\`: "${prHeadSha}"
-
-- **reviewSummary**:
-  - \`body\`: 1-3 sentence overall assessment
-</schema_details>
-</output_spec>
-
-<critical_constraints>
-**DO NOT** post to GitHub.
-**DO NOT** invoke any PR mutation tools (inline comments, submit review, delete/minimize/reply/resolve, etc.).
-**DO NOT** modify any files other than writing to \`${reviewCandidatesPath}\`.
-Output ONLY the JSON file—no additional commentary.
-</critical_constraints>
-`;
+  return generateCandidatesPrompt({
+    terminology: GITHUB_TERMINOLOGY,
+    entityNumber: prNumber,
+    repoOrProject: context.repository,
+    headRef: context.prBranchData?.headRefName ?? "unknown",
+    headSha: context.prBranchData?.headRefOid ?? "unknown",
+    baseRef: context.eventData.baseBranch ?? "unknown",
+    diffPath:
+      context.reviewArtifacts?.diffPath ?? "$RUNNER_TEMP/droid-prompts/pr.diff",
+    commentsPath:
+      context.reviewArtifacts?.commentsPath ??
+      "$RUNNER_TEMP/droid-prompts/existing_comments.json",
+    descriptionPath:
+      context.reviewArtifacts?.descriptionPath ??
+      "$RUNNER_TEMP/droid-prompts/pr_description.txt",
+    candidatesPath:
+      process.env.REVIEW_CANDIDATES_PATH ??
+      "$RUNNER_TEMP/droid-prompts/review_candidates.json",
+    includeSuggestions: context.includeSuggestions !== false,
+    securityReviewEnabled: process.env.SECURITY_REVIEW_ENABLED === "true",
+  });
 }
diff --git a/src/create-prompt/templates/review-validator-prompt.ts b/src/create-prompt/templates/review-validator-prompt.ts
index 866ceb0..ded234f 100644
--- a/src/create-prompt/templates/review-validator-prompt.ts
+++ b/src/create-prompt/templates/review-validator-prompt.ts
@@ -1,3 +1,14 @@
+/**
+ * GitHub Pass-2 (validator) prompt — thin adapter.
+ *
+ * Delegates to the platform-agnostic builder in
+ * `src/core/review/prompts/validator.ts`, mapping the GitHub
+ * `PreparedContext` shape onto the shared `ReviewPromptContext` and
+ * supplying `GITHUB_TERMINOLOGY`.
+ */
+
+import { generateValidatorPrompt } from "../../core/review/prompts/validator";
+import { GITHUB_TERMINOLOGY } from "../terminology";
 import type { PreparedContext } from "../types";
 
 export function generateReviewValidatorPrompt(
@@ -9,124 +20,28 @@ export function generateReviewValidatorPrompt(
       ? String(context.githubContext.entityNumber)
       : "unknown";
 
-  const repoFullName = context.repository;
-  const prHeadRef = context.prBranchData?.headRefName ?? "unknown";
-  const prHeadSha = context.prBranchData?.headRefOid ?? "unknown";
-  const prBaseRef = context.eventData.baseBranch ?? "unknown";
-
-  const diffPath =
-    context.reviewArtifacts?.diffPath ?? "$RUNNER_TEMP/droid-prompts/pr.diff";
-  const commentsPath =
-    context.reviewArtifacts?.commentsPath ??
-    "$RUNNER_TEMP/droid-prompts/existing_comments.json";
-  const descriptionPath =
-    context.reviewArtifacts?.descriptionPath ??
-    "$RUNNER_TEMP/droid-prompts/pr_description.txt";
-
-  const reviewCandidatesPath =
-    process.env.REVIEW_CANDIDATES_PATH ??
-    "$RUNNER_TEMP/droid-prompts/review_candidates.json";
-  const reviewValidatedPath =
-    process.env.REVIEW_VALIDATED_PATH ??
-    "$RUNNER_TEMP/droid-prompts/review_validated.json";
-
-  const includeSuggestions = context.includeSuggestions !== false;
-
-  const skillInstruction = includeSuggestions
-    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure — including suggestion block rules."
-    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure. Do NOT include code suggestion blocks.";
-
-  return `You are validating candidate review comments for PR #${prNumber} in ${repoFullName}.
-
-IMPORTANT: This is Phase 2 (validator) of a two-pass review pipeline.
-
-${skillInstruction}
-
-### Context
-
-* Repo: ${repoFullName}
-* PR Number: ${prNumber}
-* PR Head Ref: ${prHeadRef}
-* PR Head SHA: ${prHeadSha}
-* PR Base Ref: ${prBaseRef}
-
-### Inputs
-
-Read these files before validating:
-* PR Description: \`${descriptionPath}\`
-* Candidates: \`${reviewCandidatesPath}\`
-* Full PR Diff: \`${diffPath}\`
-* Existing Comments: \`${commentsPath}\`
-
-If the diff is large, read in chunks (offset/limit). **Do not proceed until you have read the ENTIRE diff.**
-
-### Critical Requirements
-
-1. You MUST read and validate **every** candidate before posting anything.
-2. Preserve ordering: keep results in the same order as candidates.
-3. **Posting rule (STRICT):** Only post comments where \`status === "approved"\`. Never post rejected items.
-
-### Output: Write \`${reviewValidatedPath}\`
-
-\`\`\`json
-{
-  "version": 1,
-  "meta": {
-    "repo": "${repoFullName}",
-    "prNumber": ${prNumber},
-    "headSha": "${prHeadSha}",
-    "baseRef": "${prBaseRef}",
-    "validatedAt": "<ISO timestamp>"
-  },
-  "results": [
-    {
-      "status": "approved",
-      "comment": {
-        "path": "src/index.ts",
-        "body": "[P1] Title\\n\\n1 paragraph.",
-        "line": 42,
-        "startLine": null,
-        "side": "RIGHT",
-        "commit_id": "${prHeadSha}"
-      }
-    },
-    {
-      "status": "rejected",
-      "candidate": {
-        "path": "src/other.ts",
-        "body": "[P2] ...",
-        "line": 10,
-        "startLine": null,
-        "side": "RIGHT",
-        "commit_id": "${prHeadSha}"
-      },
-      "reason": "Not a real bug because ..."
-    }
-  ],
-  "reviewSummary": {
-    "status": "approved",
-    "body": "1-3 sentence overall assessment"
-  }
-}
-\`\`\`
-
-Notes:
-* Use \`commit_id\` = \`${prHeadSha}\`.
-* \`results\` MUST have exactly one entry per candidate, in the same order.
-
-Tooling note:
-* If the tools list includes \`ApplyPatch\` (common for OpenAI models like GPT-5.2), use \`ApplyPatch\` to create/update the file at the exact path.
-* Otherwise, use \`Create\` (or \`Edit\` if overwriting) to write the file.
-
-### Post approved items
-
-After writing \`${reviewValidatedPath}\`, post comments ONLY for \`status === "approved"\`:
-
-* Collect all approved comments and submit them as a **single batched review** via \`github_pr___submit_review\`, passing them in the \`comments\` array parameter.
-* Do **NOT** post comments individually — batch them all into one \`submit_review\` call.
-* Do **NOT** include a \`body\` parameter in \`submit_review\`.
-* Use \`github_comment___update_droid_comment\` to update the tracking comment with the review summary.
-* Do **NOT** post the summary as a separate comment or as the body of \`submit_review\`.
-* Do not approve or request changes.
-`;
+  return generateValidatorPrompt({
+    terminology: GITHUB_TERMINOLOGY,
+    entityNumber: prNumber,
+    repoOrProject: context.repository,
+    headRef: context.prBranchData?.headRefName ?? "unknown",
+    headSha: context.prBranchData?.headRefOid ?? "unknown",
+    baseRef: context.eventData.baseBranch ?? "unknown",
+    diffPath:
+      context.reviewArtifacts?.diffPath ?? "$RUNNER_TEMP/droid-prompts/pr.diff",
+    commentsPath:
+      context.reviewArtifacts?.commentsPath ??
+      "$RUNNER_TEMP/droid-prompts/existing_comments.json",
+    descriptionPath:
+      context.reviewArtifacts?.descriptionPath ??
+      "$RUNNER_TEMP/droid-prompts/pr_description.txt",
+    candidatesPath:
+      process.env.REVIEW_CANDIDATES_PATH ??
+      "$RUNNER_TEMP/droid-prompts/review_candidates.json",
+    validatedPath:
+      process.env.REVIEW_VALIDATED_PATH ??
+      "$RUNNER_TEMP/droid-prompts/review_validated.json",
+    includeSuggestions: context.includeSuggestions !== false,
+    securityReviewEnabled: process.env.SECURITY_REVIEW_ENABLED === "true",
+  });
 }
diff --git a/src/create-prompt/terminology.ts b/src/create-prompt/terminology.ts
new file mode 100644
index 0000000..f5cfcc7
--- /dev/null
+++ b/src/create-prompt/terminology.ts
@@ -0,0 +1,32 @@
+import type { ReviewTerminology } from "../core/review/prompts/types";
+
+export const GITHUB_TERMINOLOGY: ReviewTerminology = {
+  entityNoun: "PR",
+  entityNumberSigil: "#",
+  platformName: "GitHub",
+  repoLabel: "Repo",
+  entityNumberLabel: "PR Number",
+  headRefLabel: "PR Head Ref",
+  headShaLabel: "PR Head SHA",
+  baseRefLabel: "PR Base Ref",
+  descriptionLabel: "PR Description",
+  diffLabel: "Full PR Diff",
+  metaRepoKey: "repo",
+  metaEntityNumberKey: "prNumber",
+  metaBaseRefKey: "baseRef",
+  repoExample: "owner/repo",
+  pathFieldDescription: 'Relative file path (e.g., "src/index.ts")',
+  lineFieldDescription:
+    "Target line number (single-line) or end line number (multi-line). Must be ≥ 0.",
+  mutationToolForbiddance:
+    "(inline comments, submit review, delete/minimize/reply/resolve, etc.)",
+  submitReviewToolName: "github_pr___submit_review",
+  submitReviewExtraArg: "",
+  submitReviewBodyExclusionTrailer: "",
+  updateTrackingToolName: "github_comment___update_droid_comment",
+  trackingCommentName: "tracking comment",
+  summaryEntityName: "comment",
+  summaryPostingExtraExclusion: " or as the body of `submit_review`",
+  approvalChangesNote: "Do not approve or request changes.",
+  // No security-badge instruction on GitHub today; left undefined intentionally.
+};
diff --git a/src/gitlab/prompts/candidates.ts b/src/gitlab/prompts/candidates.ts
index aa5966a..413c393 100644
--- a/src/gitlab/prompts/candidates.ts
+++ b/src/gitlab/prompts/candidates.ts
@@ -1,148 +1,35 @@
 /**
- * GitLab Pass-1 (candidate generation) prompt.
+ * GitLab Pass-1 (candidate generation) prompt — thin adapter.
  *
- * Direct port of the GitHub Action's
- * `src/create-prompt/templates/review-candidates-prompt.ts` with PR→MR
- * terminology and GitLab-specific entity numbering. The /review skill
- * itself is platform-agnostic and contains the two-pass methodology; this
- * file is the runtime harness that tells Droid which pass it's in, where
- * the input artifacts live on disk, and where to write the candidate JSON.
+ * Delegates to the platform-agnostic builder in
+ * `src/core/review/prompts/candidates.ts` after mapping the GitLab
+ * context shape onto the shared `ReviewPromptContext` and supplying
+ * `GITLAB_TERMINOLOGY` (PR→MR labels, GitLab MCP tool names, etc.).
  *
- * STRICT contract: this prompt MUST NOT instruct the model to call the
- * GitLab posting tool (`gitlab_mr___submit_review`). Posting only happens
- * in Pass 2. Tool gating is also enforced at the `droid exec` level by
- * excluding `gitlab_mr___submit_review` from `--enabled-tools` during
- * Pass 1.
+ * The GitLab posting tool is exposed only in Pass 2; this Pass 1 prompt
+ * MUST NOT instruct the model to call it. The shared builder enforces
+ * that, plus tool gating at the `droid exec` level via `--enabled-tools`.
  */
 
+import { generateCandidatesPrompt } from "../../core/review/prompts/candidates";
+import { GITLAB_TERMINOLOGY } from "./terminology";
 import type { GitlabReviewPromptContext } from "./types";
 
 export function generateGitlabReviewCandidatesPrompt(
   ctx: GitlabReviewPromptContext,
 ): string {
-  const {
-    projectPath,
-    mrIid,
-    sourceBranch,
-    targetBranch,
-    headSha,
-    diffPath,
-    commentsPath,
-    descriptionPath,
-    candidatesPath,
-    includeSuggestions,
-    securityReviewEnabled,
-  } = ctx;
-
-  const bodyFieldDescription = includeSuggestions
-    ? "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation.\n" +
-      "    Follow the suggestion block rules from the review skill when including suggestions."
-    : "  - `body`: Comment text starting with priority tag [P0|P1|P2], then title, then 1 paragraph explanation";
-
-  const sideFieldDescription = includeSuggestions
-    ? '  - `side`: "RIGHT" for new/modified code (default). Use "LEFT" only for removed code **without** suggestions.\n' +
-      "    If you include a suggestion block, choose a RIGHT-side anchor and keep it unchanged so the validator can reuse it."
-    : '  - `side`: "RIGHT" for new/modified code (default), "LEFT" only for removed code';
-
-  const skillInstruction = includeSuggestions
-    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure — including suggestion block rules."
-    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 1: Candidate Generation** procedure. Do NOT include code suggestion blocks.";
-
-  const securitySubagentInstruction = securityReviewEnabled
-    ? `
-
-## Security Review (run concurrently)
-
-In addition to the code review, you MUST also spawn a \`security-reviewer\` subagent via the Task tool.
-This subagent runs **concurrently** with the code review subagents during Step 2.
-
-Spawn it with:
-- \`subagent_type\`: "security-reviewer"
-- \`description\`: "Security review"
-- \`prompt\`: Include the full MR context (project, MR IID, head SHA, target branch) and the paths to precomputed data files (diff, description, existing comments). The security-reviewer will invoke the security-review skill and return a JSON array of security findings.
-
-**IMPORTANT**: Spawn the security-reviewer in the SAME response as the code review subagents so they all run in parallel.
-
-After all subagents complete (both code review and security-reviewer), merge the security findings into the \`comments\` array alongside code review findings. Security findings use the same schema but are prefixed with \`[security]\` in their body (e.g., \`[P1] [security] Title\`).
-`
-    : "";
-
-  return `You are a senior staff software engineer and expert code reviewer.
-
-Your task: Review MR !${mrIid} in ${projectPath} and generate a JSON file with **high-confidence, actionable** review comments that pinpoint genuine issues.
-
-${skillInstruction}${securitySubagentInstruction}
-
-<context>
-Project: ${projectPath}
-MR IID: ${mrIid}
-MR Source Branch: ${sourceBranch}
-MR Head SHA: ${headSha}
-MR Target Branch: ${targetBranch}
-
-Precomputed data files:
-- MR Description: \`${descriptionPath}\`
-- Full MR Diff: \`${diffPath}\`
-- Existing Comments: \`${commentsPath}\`
-</context>
-
-<output_spec>
-Write output to \`${candidatesPath}\` using this exact schema:
-
-\`\`\`json
-{
-  "version": 1,
-  "meta": {
-    "project": "group/project",
-    "mrIid": 123,
-    "headSha": "<head sha>",
-    "targetBranch": "main",
-    "generatedAt": "<ISO timestamp>"
-  },
-  "comments": [
-    {
-      "path": "src/index.ts",
-      "body": "[P1] Title\\n\\n1 paragraph.",
-      "line": 42,
-      "startLine": null,
-      "side": "RIGHT",
-      "commit_id": "<head sha>"
-    }
-  ],
-  "reviewSummary": {
-    "body": "1-3 sentence overall assessment"
-  }
-}
-\`\`\`
-
-<schema_details>
-- **version**: Always \`1\`
-
-- **meta**: Metadata object
-  - \`project\`: "${projectPath}"
-  - \`mrIid\`: ${mrIid}
-  - \`headSha\`: "${headSha}"
-  - \`targetBranch\`: "${targetBranch}"
-  - \`generatedAt\`: ISO 8601 timestamp (e.g., "2024-01-15T10:30:00Z")
-
-- **comments**: Array of comment objects
-  - \`path\`: Relative file path (use the new_path from the diff, e.g., "src/index.ts")
-${bodyFieldDescription}
-  - \`line\`: Target line number in the new file (single-line) or end line number (multi-line). Must be ≥ 0.
-  - \`startLine\`: \`null\` for single-line comments, or start line number for multi-line comments
-${sideFieldDescription}
-  - \`commit_id\`: "${headSha}"
-
-- **reviewSummary**:
-  - \`body\`: 1-3 sentence overall assessment
-</schema_details>
-</output_spec>
-
-<critical_constraints>
-**DO NOT** post to GitLab.
-**DO NOT** invoke any MR mutation tools (\`gitlab_mr___submit_review\`, \`gitlab_mr___create_mr_note\`, \`gitlab_mr___update_mr_note\`, \`gitlab_mr___update_mr_description\`, \`gitlab_mr___update_tracking_note\`, etc.).
-**DO NOT** modify any files other than writing to \`${candidatesPath}\`.
-Output ONLY the JSON file—no additional commentary.
-</critical_constraints>
-`;
+  return generateCandidatesPrompt({
+    terminology: GITLAB_TERMINOLOGY,
+    entityNumber: ctx.mrIid,
+    repoOrProject: ctx.projectPath,
+    headRef: ctx.sourceBranch,
+    headSha: ctx.headSha,
+    baseRef: ctx.targetBranch,
+    diffPath: ctx.diffPath,
+    commentsPath: ctx.commentsPath,
+    descriptionPath: ctx.descriptionPath,
+    candidatesPath: ctx.candidatesPath,
+    includeSuggestions: ctx.includeSuggestions,
+    securityReviewEnabled: ctx.securityReviewEnabled,
+  });
 }
diff --git a/src/gitlab/prompts/terminology.ts b/src/gitlab/prompts/terminology.ts
new file mode 100644
index 0000000..de7bd54
--- /dev/null
+++ b/src/gitlab/prompts/terminology.ts
@@ -0,0 +1,48 @@
+import type { ReviewTerminology } from "../../core/review/prompts/types";
+
+export const GITLAB_TERMINOLOGY: ReviewTerminology = {
+  entityNoun: "MR",
+  entityNumberSigil: "!",
+  platformName: "GitLab",
+  repoLabel: "Project",
+  entityNumberLabel: "MR IID",
+  headRefLabel: "MR Source Branch",
+  headShaLabel: "MR Head SHA",
+  baseRefLabel: "MR Target Branch",
+  descriptionLabel: "MR Description",
+  diffLabel: "Full MR Diff",
+  metaRepoKey: "project",
+  metaEntityNumberKey: "mrIid",
+  metaBaseRefKey: "targetBranch",
+  repoExample: "group/project",
+  pathFieldDescription:
+    'Relative file path (use the new_path from the diff, e.g., "src/index.ts")',
+  lineFieldDescription:
+    "Target line number in the new file (single-line) or end line number (multi-line). Must be ≥ 0.",
+  mutationToolForbiddance:
+    "(`gitlab_mr___submit_review`, `gitlab_mr___create_mr_note`, `gitlab_mr___update_mr_note`, `gitlab_mr___update_mr_description`, `gitlab_mr___update_tracking_note`, etc.)",
+  submitReviewToolName: "gitlab_mr___submit_review",
+  submitReviewExtraArg: "", // populated dynamically below via factory
+  submitReviewBodyExclusionTrailer:
+    " (we use a separate tracking note for the summary)",
+  updateTrackingToolName: "gitlab_mr___update_tracking_note",
+  trackingCommentName: "sticky tracking note",
+  summaryEntityName: "top-level note",
+  summaryPostingExtraExclusion: "",
+  approvalChangesNote:
+    "Do not approve the MR or request changes (GitLab approval rules are handled out-of-band).",
+  securityBadgeInstruction:
+    "If any approved comments contain `[security]` in their body, prepend a security badge to the tracking note: `![Security Review](https://img.shields.io/badge/security%20review-ran-blue)`. This indicates that security analysis was performed as part of the review.",
+};
+
+/**
+ * Build the GitLab terminology with the runtime MR IID baked into the
+ * "passing them in the comments array parameter along with mr_iid: N" arg.
+ * GitLab's submit_review tool needs the IID re-asserted in the call.
+ */
+export function gitlabTerminologyFor(mrIid: number): ReviewTerminology {
+  return {
+    ...GITLAB_TERMINOLOGY,
+    submitReviewExtraArg: ` along with \`mr_iid: ${mrIid}\``,
+  };
+}
diff --git a/src/gitlab/prompts/validator.ts b/src/gitlab/prompts/validator.ts
index 9606e96..602a9a6 100644
--- a/src/gitlab/prompts/validator.ts
+++ b/src/gitlab/prompts/validator.ts
@@ -1,132 +1,37 @@
 /**
- * GitLab Pass-2 (validator) prompt.
+ * GitLab Pass-2 (validator) prompt — thin adapter.
  *
- * Direct port of the GitHub Action's
- * `src/create-prompt/templates/review-validator-prompt.ts` with PR→MR
- * terminology and the GitLab MCP tool names. The validator reads the
- * candidates JSON produced by Pass 1 from disk, validates each one,
- * writes a refined JSON, and posts the approved findings as a single
- * batched call to `gitlab_mr___submit_review`.
+ * Delegates to the platform-agnostic builder in
+ * `src/core/review/prompts/validator.ts` after mapping the GitLab
+ * context shape onto the shared `ReviewPromptContext` and supplying
+ * `gitlabTerminologyFor(mrIid)` (which bakes the MR IID into the
+ * submit_review call hint, since GitLab's tool requires `mr_iid` to be
+ * re-asserted in the invocation).
  *
- * Pass 2 is the only place where the posting tool is exposed (via
+ * Pass 2 is the only place the GitLab posting tool is exposed (via
  * `--enabled-tools` on the second `droid exec` invocation).
  */
 
+import { generateValidatorPrompt } from "../../core/review/prompts/validator";
+import { gitlabTerminologyFor } from "./terminology";
 import type { GitlabReviewPromptContext } from "./types";
 
 export function generateGitlabReviewValidatorPrompt(
   ctx: GitlabReviewPromptContext,
 ): string {
-  const {
-    projectPath,
-    mrIid,
-    sourceBranch,
-    targetBranch,
-    headSha,
-    diffPath,
-    commentsPath,
-    descriptionPath,
-    candidatesPath,
-    validatedPath,
-    includeSuggestions,
-  } = ctx;
-
-  const skillInstruction = includeSuggestions
-    ? "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure — including suggestion block rules."
-    : "Invoke the 'review' skill to load the review methodology, then execute its **Pass 2: Validation** procedure. Do NOT include code suggestion blocks.";
-
-  return `You are validating candidate review comments for MR !${mrIid} in ${projectPath}.
-
-IMPORTANT: This is Phase 2 (validator) of a two-pass review pipeline.
-
-${skillInstruction}
-
-### Context
-
-* Project: ${projectPath}
-* MR IID: ${mrIid}
-* MR Source Branch: ${sourceBranch}
-* MR Head SHA: ${headSha}
-* MR Target Branch: ${targetBranch}
-
-### Inputs
-
-Read these files before validating:
-* MR Description: \`${descriptionPath}\`
-* Candidates: \`${candidatesPath}\`
-* Full MR Diff: \`${diffPath}\`
-* Existing Comments: \`${commentsPath}\`
-
-If the diff is large, read in chunks (offset/limit). **Do not proceed until you have read the ENTIRE diff.**
-
-### Critical Requirements
-
-1. You MUST read and validate **every** candidate before posting anything.
-2. Preserve ordering: keep results in the same order as candidates.
-3. **Posting rule (STRICT):** Only post comments where \`status === "approved"\`. Never post rejected items.
-
-### Output: Write \`${validatedPath}\`
-
-\`\`\`json
-{
-  "version": 1,
-  "meta": {
-    "project": "${projectPath}",
-    "mrIid": ${mrIid},
-    "headSha": "${headSha}",
-    "targetBranch": "${targetBranch}",
-    "validatedAt": "<ISO timestamp>"
-  },
-  "results": [
-    {
-      "status": "approved",
-      "comment": {
-        "path": "src/index.ts",
-        "body": "[P1] Title\\n\\n1 paragraph.",
-        "line": 42,
-        "startLine": null,
-        "side": "RIGHT",
-        "commit_id": "${headSha}"
-      }
-    },
-    {
-      "status": "rejected",
-      "candidate": {
-        "path": "src/other.ts",
-        "body": "[P2] ...",
-        "line": 10,
-        "startLine": null,
-        "side": "RIGHT",
-        "commit_id": "${headSha}"
-      },
-      "reason": "Not a real bug because ..."
-    }
-  ],
-  "reviewSummary": {
-    "status": "approved",
-    "body": "1-3 sentence overall assessment"
-  }
-}
-\`\`\`
-
-Notes:
-* Use \`commit_id\` = \`${headSha}\`.
-* \`results\` MUST have exactly one entry per candidate, in the same order.
-
-Tooling note:
-* If the tools list includes \`ApplyPatch\` (common for OpenAI models like GPT-5.2), use \`ApplyPatch\` to create/update the file at the exact path.
-* Otherwise, use \`Create\` (or \`Edit\` if overwriting) to write the file.
-
-### Post approved items
-
-After writing \`${validatedPath}\`, post comments ONLY for \`status === "approved"\`:
-
-* Collect all approved comments and submit them as a **single batched review** via \`gitlab_mr___submit_review\`, passing them in the \`comments\` array parameter along with \`mr_iid: ${mrIid}\`.
-* Do **NOT** post comments individually — batch them all into one \`submit_review\` call.
-* Do **NOT** include a \`body\` parameter in \`submit_review\` (we use a separate tracking note for the summary).
-* Use \`gitlab_mr___update_tracking_note\` to update the sticky tracking note with the review summary.
-* If any approved comments contain \`[security]\` in their body, prepend a security badge to the tracking note: \`![Security Review](https://img.shields.io/badge/security%20review-ran-blue)\`. This indicates that security analysis was performed as part of the review.
-* Do **NOT** post the summary as a separate top-level note.
-* Do not approve the MR or request changes (GitLab approval rules are handled out-of-band).
-`;
+  return generateValidatorPrompt({
+    terminology: gitlabTerminologyFor(ctx.mrIid),
+    entityNumber: ctx.mrIid,
+    repoOrProject: ctx.projectPath,
+    headRef: ctx.sourceBranch,
+    headSha: ctx.headSha,
+    baseRef: ctx.targetBranch,
+    diffPath: ctx.diffPath,
+    commentsPath: ctx.commentsPath,
+    descriptionPath: ctx.descriptionPath,
+    candidatesPath: ctx.candidatesPath,
+    validatedPath: ctx.validatedPath,
+    includeSuggestions: ctx.includeSuggestions,
+    securityReviewEnabled: ctx.securityReviewEnabled,
+  });
 }

From 20b98bc3a0b92a523a5549bbb791a14c3323cce1 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 13:36:23 -0700
Subject: [PATCH 02/13] refactor(review): share ReviewArtifactPaths type +
 GitLab uses central disk-write helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two platforms fetch review artifacts with fundamentally different
mechanics (GitHub shells out to git/gh CLI with shallow-clone unshallow
and a 50MB-buffered fallback; GitLab uses parallel REST calls), so the
fetchers stay platform-specific. But the on-disk shape is identical, so:

  src/core/review/artifacts/types.ts   ReviewArtifactPaths +
                                       ReviewArtifactContents shapes
  src/core/review/artifacts/write.ts   writeReviewArtifacts(outDir,
                                       contents, names) — mkdir + parallel
                                       writeFile×3

GitLab's computeReviewArtifacts now delegates the disk-write through the
shared helper. GitHub keeps its 3-helper public API (each does its own
write so tests pin those signatures); it just re-exports the shared type
via the existing ReviewArtifacts alias.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/artifacts/types.ts  | 25 +++++++++++++++
 src/core/review/artifacts/write.ts  | 41 +++++++++++++++++++++++
 src/create-prompt/types.ts          |  7 ++--
 src/gitlab/data/review-artifacts.ts | 50 ++++++++++++-----------------
 4 files changed, 88 insertions(+), 35 deletions(-)
 create mode 100644 src/core/review/artifacts/types.ts
 create mode 100644 src/core/review/artifacts/write.ts

diff --git a/src/core/review/artifacts/types.ts b/src/core/review/artifacts/types.ts
new file mode 100644
index 0000000..62843d0
--- /dev/null
+++ b/src/core/review/artifacts/types.ts
@@ -0,0 +1,25 @@
+/**
+ * Shared shape for the three on-disk review artifacts. Both GitHub and
+ * GitLab pipelines pre-compute the same trio (diff, existing comments,
+ * description) and write them under `${tempDir}/droid-prompts/`, then
+ * pass the resulting paths into the Pass 1 / Pass 2 prompts.
+ *
+ * The fetch mechanics differ substantially per platform (git+gh CLI vs
+ * REST API), so we don't try to share the fetchers — only the path
+ * shape and the disk-write helper.
+ */
+export type ReviewArtifactPaths = {
+  diffPath: string;
+  commentsPath: string;
+  descriptionPath: string;
+};
+
+/**
+ * Raw content for each of the three artifacts, before they're written
+ * to disk by `writeReviewArtifacts`.
+ */
+export type ReviewArtifactContents = {
+  diff: string;
+  comments: unknown; // JSON-serializable
+  description: string;
+};
diff --git a/src/core/review/artifacts/write.ts b/src/core/review/artifacts/write.ts
new file mode 100644
index 0000000..4befa76
--- /dev/null
+++ b/src/core/review/artifacts/write.ts
@@ -0,0 +1,41 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import type { ReviewArtifactContents, ReviewArtifactPaths } from "./types";
+
+/**
+ * Naming convention for review-artifact files on disk. Each platform
+ * gets its own basename for the diff and description (pr.diff /
+ * mr.diff, pr_description.txt / mr_description.txt) but the existing
+ * comments file is platform-neutral.
+ */
+export type ReviewArtifactNames = {
+  diff: string;
+  comments: string;
+  description: string;
+};
+
+/**
+ * Write the three review-artifact files into `outDir` in parallel,
+ * creating `outDir` if it doesn't yet exist. Returns the resolved
+ * on-disk paths so the caller can hand them straight to the prompt
+ * builder.
+ */
+export async function writeReviewArtifacts(
+  outDir: string,
+  contents: ReviewArtifactContents,
+  names: ReviewArtifactNames,
+): Promise<ReviewArtifactPaths> {
+  await fs.mkdir(outDir, { recursive: true });
+
+  const diffPath = path.join(outDir, names.diff);
+  const commentsPath = path.join(outDir, names.comments);
+  const descriptionPath = path.join(outDir, names.description);
+
+  await Promise.all([
+    fs.writeFile(diffPath, contents.diff),
+    fs.writeFile(commentsPath, JSON.stringify(contents.comments, null, 2)),
+    fs.writeFile(descriptionPath, contents.description),
+  ]);
+
+  return { diffPath, commentsPath, descriptionPath };
+}
diff --git a/src/create-prompt/types.ts b/src/create-prompt/types.ts
index f9945e0..8ec8238 100644
--- a/src/create-prompt/types.ts
+++ b/src/create-prompt/types.ts
@@ -1,4 +1,5 @@
 import type { GitHubContext } from "../github/context";
+import type { ReviewArtifactPaths } from "../core/review/artifacts/types";
 
 export type CommonFields = {
   repository: string;
@@ -103,11 +104,7 @@ export type EventData =
   | PullRequestEvent
   | PullRequestTargetEvent;
 
-export type ReviewArtifacts = {
-  diffPath: string;
-  commentsPath: string;
-  descriptionPath: string;
-};
+export type ReviewArtifacts = ReviewArtifactPaths;
 
 export type PreparedContext = CommonFields & {
   eventData: EventData;
diff --git a/src/gitlab/data/review-artifacts.ts b/src/gitlab/data/review-artifacts.ts
index be45775..6dcd706 100644
--- a/src/gitlab/data/review-artifacts.ts
+++ b/src/gitlab/data/review-artifacts.ts
@@ -9,19 +9,17 @@
  * These mirror the artifacts the GitHub Action precomputes
  * (`pr.diff`, `existing_comments.json`, `pr_description.txt`) so the GitLab
  * Pass-1 / Pass-2 prompts can refer to them by stable paths and the model
- * doesn't have to round-trip through MCP tools to fetch them.
+ * doesn't have to round-trip through MCP tools to fetch them. The disk
+ * write itself uses the shared `writeReviewArtifacts` helper in
+ * `src/core/review/artifacts/write.ts`.
  */
 
-import * as fs from "fs/promises";
-import * as path from "path";
+import { writeReviewArtifacts } from "../../core/review/artifacts/write";
+import type { ReviewArtifactPaths } from "../../core/review/artifacts/types";
 import type { GitlabClient } from "../api/client";
 import type { GitlabMr, GitlabMrChanges, GitlabNote } from "../types";
 
-export type GitlabReviewArtifactPaths = {
-  diffPath: string;
-  commentsPath: string;
-  descriptionPath: string;
-};
+export type GitlabReviewArtifactPaths = ReviewArtifactPaths;
 
 export type GitlabReviewArtifacts = GitlabReviewArtifactPaths & {
   mr: GitlabMr;
@@ -62,33 +60,25 @@ export async function computeReviewArtifacts(
 ): Promise<GitlabReviewArtifacts> {
   const { client, projectId, mrIid, outDir } = opts;
 
-  await fs.mkdir(outDir, { recursive: true });
-
   const [mr, changes, notes] = await Promise.all([
     client.getMr(projectId, mrIid),
     client.getMrChanges(projectId, mrIid),
     client.listNotes(projectId, mrIid),
   ]);
 
-  const diffPath = path.join(outDir, "mr.diff");
-  const commentsPath = path.join(outDir, "existing_comments.json");
-  const descriptionPath = path.join(outDir, "mr_description.txt");
-
-  const diffContent = buildDiffContent(changes);
-  const descriptionContent = buildDescriptionContent(mr);
-
-  await Promise.all([
-    fs.writeFile(diffPath, diffContent),
-    fs.writeFile(commentsPath, JSON.stringify(notes, null, 2)),
-    fs.writeFile(descriptionPath, descriptionContent),
-  ]);
+  const paths = await writeReviewArtifacts(
+    outDir,
+    {
+      diff: buildDiffContent(changes),
+      comments: notes,
+      description: buildDescriptionContent(mr),
+    },
+    {
+      diff: "mr.diff",
+      comments: "existing_comments.json",
+      description: "mr_description.txt",
+    },
+  );
 
-  return {
-    diffPath,
-    commentsPath,
-    descriptionPath,
-    mr,
-    changes,
-    notes,
-  };
+  return { ...paths, mr, changes, notes };
 }

From f7eb40a07668ea9bccd99a0a91608ab3af168123 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 13:36:32 -0700
Subject: [PATCH 03/13] refactor(review): hoist sticky-comment state/telemetry
 types + formatters to core
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two platforms render the sticky review-tracking comment with very
different mechanics today — GitHub builds it from inside the agent via
the github-comment-server MCP tool, while GitLab writes a rich state-
machine body from CI — so we can't share a single renderer. What we
*can* share is the contract:

  src/core/review/tracking/types.ts    ReviewTrackingState +
                                       ReviewTrackingTelemetry +
                                       ReviewTrackingFields
  src/core/review/tracking/format.ts   formatDurationMs(ms) +
                                       formatCostUsd(usd) — keeps the
                                       "1m 23s • $0.0042" rendering
                                       identical across platforms

GitLab's tracking-note.ts now imports those and re-exports the GitLab
aliases (TrackingNoteState, TrackingNoteTelemetry, TrackingNoteOptions)
so existing call sites stay untouched.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/tracking/format.ts     | 20 ++++++++++
 src/core/review/tracking/types.ts      | 31 +++++++++++++++
 src/gitlab/operations/tracking-note.ts | 53 ++++++++++----------------
 3 files changed, 71 insertions(+), 33 deletions(-)
 create mode 100644 src/core/review/tracking/format.ts
 create mode 100644 src/core/review/tracking/types.ts

diff --git a/src/core/review/tracking/format.ts b/src/core/review/tracking/format.ts
new file mode 100644
index 0000000..50ce45e
--- /dev/null
+++ b/src/core/review/tracking/format.ts
@@ -0,0 +1,20 @@
+/**
+ * Small formatting helpers shared between the GitHub MCP comment server
+ * and the GitLab tracking-note builder. Kept platform-agnostic so the
+ * two renderers can stay independent while still producing identical
+ * telemetry text (e.g. "1m 23s • $0.0042").
+ */
+
+export function formatDurationMs(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remSec = Math.round(seconds - minutes * 60);
+  return `${minutes}m ${remSec}s`;
+}
+
+export function formatCostUsd(usd: number): string {
+  if (usd >= 1) return `$${usd.toFixed(2)}`;
+  return `$${usd.toFixed(4)}`;
+}
diff --git a/src/core/review/tracking/types.ts b/src/core/review/tracking/types.ts
new file mode 100644
index 0000000..5a24b64
--- /dev/null
+++ b/src/core/review/tracking/types.ts
@@ -0,0 +1,31 @@
+/**
+ * Shared shapes for sticky review-tracking comments/notes.
+ *
+ * Both GitHub and GitLab keep a single "sticky" comment per PR/MR that
+ * carries the live status of the Droid review pipeline (running →
+ * success/failure) plus telemetry. The body-building mechanics differ
+ * between platforms today — GitHub updates it from inside the agent via
+ * the github-comment-server MCP tool, while GitLab builds the whole body
+ * in TypeScript and writes it from CI — so we only share the contract
+ * (state machine + telemetry shape) here, not the renderer itself.
+ */
+
+export type ReviewTrackingState = "running" | "success" | "failure";
+
+export type ReviewTrackingTelemetry = {
+  totalNumTurns?: number | null;
+  totalDurationMs?: number | null;
+  totalCostUsd?: number | null;
+  pass1SessionId?: string | null;
+  pass2SessionId?: string | null;
+};
+
+export interface ReviewTrackingFields {
+  state: ReviewTrackingState;
+  pipelineUrl?: string | null;
+  jobUrl?: string | null;
+  triggerUsername?: string | null;
+  errorDetails?: string | null;
+  securityReviewRan?: boolean;
+  telemetry?: ReviewTrackingTelemetry | null;
+}
diff --git a/src/gitlab/operations/tracking-note.ts b/src/gitlab/operations/tracking-note.ts
index 286da9d..7a2511a 100644
--- a/src/gitlab/operations/tracking-note.ts
+++ b/src/gitlab/operations/tracking-note.ts
@@ -3,44 +3,31 @@
  *
  * The tracking note carries a hidden HTML marker so we can find and
  * update the same note across retries instead of creating duplicates.
+ *
+ * The state machine (running/success/failure), telemetry shape, and
+ * formatting helpers are platform-agnostic and live in
+ * `src/core/review/tracking/`. This file owns the GitLab-specific body
+ * rendering, including the markdown layout, the security badge, the
+ * error-details accordion, and the hidden marker conventions.
  */
 
+import {
+  formatCostUsd,
+  formatDurationMs,
+} from "../../core/review/tracking/format";
+import type {
+  ReviewTrackingFields,
+  ReviewTrackingState,
+} from "../../core/review/tracking/types";
+
 export const DROID_TRACKING_MARKER = "<!-- droid-tracking-note -->";
 export const DROID_SECURITY_BADGE_MARKER = "<!-- droid-security-badge -->";
 
-export type TrackingNoteState = "running" | "success" | "failure";
-
-export type TrackingNoteTelemetry = {
-  totalNumTurns?: number | null;
-  totalDurationMs?: number | null;
-  totalCostUsd?: number | null;
-  pass1SessionId?: string | null;
-  pass2SessionId?: string | null;
-};
-
-export interface TrackingNoteOptions {
-  state: TrackingNoteState;
-  pipelineUrl?: string | null;
-  jobUrl?: string | null;
-  triggerUsername?: string | null;
-  errorDetails?: string | null;
-  securityReviewRan?: boolean;
-  telemetry?: TrackingNoteTelemetry | null;
-}
-
-function formatDurationMs(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  const seconds = ms / 1000;
-  if (seconds < 60) return `${seconds.toFixed(1)}s`;
-  const minutes = Math.floor(seconds / 60);
-  const remSec = Math.round(seconds - minutes * 60);
-  return `${minutes}m ${remSec}s`;
-}
-
-function formatCostUsd(usd: number): string {
-  if (usd >= 1) return `$${usd.toFixed(2)}`;
-  return `$${usd.toFixed(4)}`;
-}
+export type TrackingNoteState = ReviewTrackingState;
+export type TrackingNoteTelemetry = NonNullable<
+  ReviewTrackingFields["telemetry"]
+>;
+export type TrackingNoteOptions = ReviewTrackingFields;
 
 const SECURITY_BADGE =
   "![security](https://img.shields.io/badge/security%20review-enabled-blue?style=flat-square&logo=shield) ";

From e9aa6a4240d30d1ba4dd7a9c0f367cb8ed3ed184 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 13:36:40 -0700
Subject: [PATCH 04/13] refactor(review): extract @droid command parser to
 platform-agnostic core

The actual string-matching for `@droid fill`, `@droid review`,
`@droid security`, `@droid security --full`, and bare `@droid` is
identical between platforms. Move parseDroidCommand + DroidCommand +
ParsedCommand into:

  src/core/review/triggers/parse-command.ts

GitHub's command-parser keeps extractCommandFromContext (which scans
GitHub-payload-shaped events) and re-exports the shared types/parser
so existing imports from `../utils/command-parser` stay valid.

When the GitLab trigger path is ported (currently a pending task on
the GitLab side), it can reuse parseDroidCommand directly instead of
duplicating the regex set.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/triggers/parse-command.ts | 74 +++++++++++++++++
 src/github/utils/command-parser.ts        | 96 +++--------------------
 2 files changed, 85 insertions(+), 85 deletions(-)
 create mode 100644 src/core/review/triggers/parse-command.ts

diff --git a/src/core/review/triggers/parse-command.ts b/src/core/review/triggers/parse-command.ts
new file mode 100644
index 0000000..725f4a5
--- /dev/null
+++ b/src/core/review/triggers/parse-command.ts
@@ -0,0 +1,74 @@
+/**
+ * Platform-agnostic Droid command parser.
+ *
+ * Both GitHub and GitLab look for the same `@droid <command>` mentions
+ * in PR/MR bodies and comments. This parser only operates on a raw
+ * string; the per-platform context extraction (which fields of which
+ * webhook payload to scan) stays in the platform-specific module
+ * because the payload shapes diverge.
+ */
+
+export type DroidCommand =
+  | "fill"
+  | "review"
+  | "security"
+  | "security-full"
+  | "default";
+
+export interface ParsedCommand {
+  command: DroidCommand;
+  raw: string;
+  location: "body" | "comment";
+  timestamp?: string | null;
+}
+
+/**
+ * Parses text to detect specific @droid commands.
+ *
+ * Returns `null` when no `@droid` mention is present, the generic
+ * `default` command for a bare `@droid`, or the specific subcommand
+ * when matched. `location` defaults to "body" and is overridden by
+ * the caller when the text came from a comment.
+ */
+export function parseDroidCommand(text: string): ParsedCommand | null {
+  if (!text) {
+    return null;
+  }
+
+  const fillMatch = text.match(/@droid\s+fill/i);
+  if (fillMatch) {
+    return { command: "fill", raw: fillMatch[0], location: "body" };
+  }
+
+  // Note: `@droid review security` will match as just `@droid review`.
+  const reviewMatch = text.match(/@droid\s+review/i);
+  if (reviewMatch) {
+    return { command: "review", raw: reviewMatch[0], location: "body" };
+  }
+
+  const securityFullMatch = text.match(/@droid\s+security\s+--full/i);
+  if (securityFullMatch) {
+    return {
+      command: "security-full",
+      raw: securityFullMatch[0],
+      location: "body",
+    };
+  }
+
+  // Check after security-full to avoid false matches.
+  const securityMatch = text.match(/@droid\s+security(?:\s|$|[^-\w])/i);
+  if (securityMatch) {
+    return {
+      command: "security",
+      raw: securityMatch[0].trim(),
+      location: "body",
+    };
+  }
+
+  const droidMatch = text.match(/@droid/i);
+  if (droidMatch) {
+    return { command: "default", raw: droidMatch[0], location: "body" };
+  }
+
+  return null;
+}
diff --git a/src/github/utils/command-parser.ts b/src/github/utils/command-parser.ts
index 5a9ca27..9903038 100644
--- a/src/github/utils/command-parser.ts
+++ b/src/github/utils/command-parser.ts
@@ -1,87 +1,19 @@
 /**
- * Command parser for detecting specific @droid commands in GitHub comments and PR bodies
+ * Command parser for detecting specific @droid commands in GitHub
+ * comments and PR bodies. The pure string-parsing portion is platform-
+ * agnostic and lives in `src/core/review/triggers/parse-command.ts`;
+ * this file owns the GitHub-payload-aware context extraction.
  */
 
 import type { GitHubContext } from "../context";
+import {
+  parseDroidCommand,
+  type DroidCommand,
+  type ParsedCommand,
+} from "../../core/review/triggers/parse-command";
 
-export type DroidCommand =
-  | "fill"
-  | "review"
-  | "security"
-  | "security-full"
-  | "default";
-
-export interface ParsedCommand {
-  command: DroidCommand;
-  raw: string;
-  location: "body" | "comment";
-  timestamp?: string | null;
-}
-
-/**
- * Parses text to detect specific @droid commands
- * @param text The text to parse (comment body or PR description)
- * @returns ParsedCommand if a command is found, null otherwise
- */
-export function parseDroidCommand(text: string): ParsedCommand | null {
-  if (!text) {
-    return null;
-  }
-
-  // Check for @droid fill command (case insensitive)
-  const fillMatch = text.match(/@droid\s+fill/i);
-  if (fillMatch) {
-    return {
-      command: "fill",
-      raw: fillMatch[0],
-      location: "body", // Will be set by caller
-    };
-  }
-
-  // Check for @droid review command (case insensitive)
-  // Note: @droid review security will match as just @droid review
-  const reviewMatch = text.match(/@droid\s+review/i);
-  if (reviewMatch) {
-    return {
-      command: "review",
-      raw: reviewMatch[0],
-      location: "body", // Will be set by caller
-    };
-  }
-
-  // Check for @droid security --full command (case insensitive)
-  const securityFullMatch = text.match(/@droid\s+security\s+--full/i);
-  if (securityFullMatch) {
-    return {
-      command: "security-full",
-      raw: securityFullMatch[0],
-      location: "body", // Will be set by caller
-    };
-  }
-
-  // Check for @droid security command (case insensitive)
-  // Must check after security-full to avoid false matches
-  const securityMatch = text.match(/@droid\s+security(?:\s|$|[^-\w])/i);
-  if (securityMatch) {
-    return {
-      command: "security",
-      raw: securityMatch[0].trim(),
-      location: "body", // Will be set by caller
-    };
-  }
-
-  // Check for generic @droid mention (default behavior)
-  const droidMatch = text.match(/@droid/i);
-  if (droidMatch) {
-    return {
-      command: "default",
-      raw: droidMatch[0],
-      location: "body", // Will be set by caller
-    };
-  }
-
-  return null;
-}
+export type { DroidCommand, ParsedCommand };
+export { parseDroidCommand };
 
 /**
  * Extracts a droid command from the GitHub context
@@ -91,12 +23,10 @@ export function parseDroidCommand(text: string): ParsedCommand | null {
 export function extractCommandFromContext(
   context: GitHubContext,
 ): ParsedCommand | null {
-  // Handle missing payload
   if (!context.payload) {
     return null;
   }
 
-  // Check PR body for commands (pull_request events)
   if (
     context.eventName === "pull_request" &&
     "pull_request" in context.payload
@@ -110,7 +40,6 @@ export function extractCommandFromContext(
     }
   }
 
-  // Check issue body for commands (issues events)
   if (context.eventName === "issues" && "issue" in context.payload) {
     const body = context.payload.issue.body;
     if (body) {
@@ -121,7 +50,6 @@ export function extractCommandFromContext(
     }
   }
 
-  // Check comment body for commands (issue_comment events)
   if (context.eventName === "issue_comment" && "comment" in context.payload) {
     const comment = context.payload.comment;
     if (comment.body) {
@@ -136,7 +64,6 @@ export function extractCommandFromContext(
     }
   }
 
-  // Check review comment body (pull_request_review_comment events)
   if (
     context.eventName === "pull_request_review_comment" &&
     "comment" in context.payload
@@ -154,7 +81,6 @@ export function extractCommandFromContext(
     }
   }
 
-  // Check review body (pull_request_review events)
   if (
     context.eventName === "pull_request_review" &&
     "review" in context.payload

From a95a70e64b09751302c82c5b3196c2d56a211b65 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 14:15:04 -0700
Subject: [PATCH 05/13] fix(review): formatDurationMs rollover + single source
 of truth for GL security badge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two pre-existing bugs surfaced by the bot review on PR #96 — both ship
on dev today, this just brings the fixes along with the refactor.

1. formatDurationMs returned "1m 60s" for ms values whose remainder
   seconds rounded up to 60 (e.g. ms=119600 → seconds=119.6 →
   minutes=1, remSec=round(59.6)=60). Round to whole seconds first, then
   split into minutes+seconds so the carry happens cleanly. Add
   regression coverage in test/core/review/tracking/format.test.ts
   covering the rollover boundary (119600/179600/239600 ms) plus the
   normal sub-second / sub-minute / multi-minute cases.

2. The GitLab security-badge URL in the prompt instruction
   (`security%20review-ran-blue`) didn't match the badge actually
   rendered by buildTrackingNoteBody (`security%20review-enabled-blue`,
   plus shields.io style params + logo). If the validator pass followed
   the prompt literally and the CI-prepended badge also fired, the MR
   could end up with two distinct security badges. Export the
   SECURITY_BADGE constant from tracking-note.ts and reference it from
   GITLAB_TERMINOLOGY.securityBadgeInstruction so the renderer is the
   single source of truth.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/tracking/format.ts       |  8 +++--
 src/gitlab/operations/tracking-note.ts   |  2 +-
 src/gitlab/prompts/terminology.ts        |  4 +--
 test/core/review/tracking/format.test.ts | 42 ++++++++++++++++++++++++
 4 files changed, 51 insertions(+), 5 deletions(-)
 create mode 100644 test/core/review/tracking/format.test.ts

diff --git a/src/core/review/tracking/format.ts b/src/core/review/tracking/format.ts
index 50ce45e..6d64fd3 100644
--- a/src/core/review/tracking/format.ts
+++ b/src/core/review/tracking/format.ts
@@ -9,8 +9,12 @@ export function formatDurationMs(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
   const seconds = ms / 1000;
   if (seconds < 60) return `${seconds.toFixed(1)}s`;
-  const minutes = Math.floor(seconds / 60);
-  const remSec = Math.round(seconds - minutes * 60);
+  // Round to whole seconds first, then split into minutes+seconds, so
+  // that a remainder rounding up to 60 carries cleanly into the next
+  // minute (e.g. 119600ms → "2m 0s", not "1m 60s").
+  const totalSeconds = Math.round(seconds);
+  const minutes = Math.floor(totalSeconds / 60);
+  const remSec = totalSeconds - minutes * 60;
   return `${minutes}m ${remSec}s`;
 }
 
diff --git a/src/gitlab/operations/tracking-note.ts b/src/gitlab/operations/tracking-note.ts
index 7a2511a..f33ccae 100644
--- a/src/gitlab/operations/tracking-note.ts
+++ b/src/gitlab/operations/tracking-note.ts
@@ -29,7 +29,7 @@ export type TrackingNoteTelemetry = NonNullable<
 >;
 export type TrackingNoteOptions = ReviewTrackingFields;
 
-const SECURITY_BADGE =
+export const SECURITY_BADGE =
   "![security](https://img.shields.io/badge/security%20review-enabled-blue?style=flat-square&logo=shield) ";
 
 const STATE_HEADER: Record<TrackingNoteState, string> = {
diff --git a/src/gitlab/prompts/terminology.ts b/src/gitlab/prompts/terminology.ts
index de7bd54..5262902 100644
--- a/src/gitlab/prompts/terminology.ts
+++ b/src/gitlab/prompts/terminology.ts
@@ -1,4 +1,5 @@
 import type { ReviewTerminology } from "../../core/review/prompts/types";
+import { SECURITY_BADGE } from "../operations/tracking-note";
 
 export const GITLAB_TERMINOLOGY: ReviewTerminology = {
   entityNoun: "MR",
@@ -31,8 +32,7 @@ export const GITLAB_TERMINOLOGY: ReviewTerminology = {
   summaryPostingExtraExclusion: "",
   approvalChangesNote:
     "Do not approve the MR or request changes (GitLab approval rules are handled out-of-band).",
-  securityBadgeInstruction:
-    "If any approved comments contain `[security]` in their body, prepend a security badge to the tracking note: `![Security Review](https://img.shields.io/badge/security%20review-ran-blue)`. This indicates that security analysis was performed as part of the review.",
+  securityBadgeInstruction: `If any approved comments contain \`[security]\` in their body, ensure a security badge is prepended to the tracking note body: \`${SECURITY_BADGE.trim()}\`. This indicates that security analysis was performed as part of the review.`,
 };
 
 /**
diff --git a/test/core/review/tracking/format.test.ts b/test/core/review/tracking/format.test.ts
new file mode 100644
index 0000000..faf9aea
--- /dev/null
+++ b/test/core/review/tracking/format.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "bun:test";
+import {
+  formatCostUsd,
+  formatDurationMs,
+} from "../../../../src/core/review/tracking/format";
+
+describe("formatDurationMs", () => {
+  it("renders sub-second durations in ms", () => {
+    expect(formatDurationMs(0)).toBe("0ms");
+    expect(formatDurationMs(750)).toBe("750ms");
+  });
+
+  it("renders sub-minute durations to one decimal in seconds", () => {
+    expect(formatDurationMs(1500)).toBe("1.5s");
+    expect(formatDurationMs(59999)).toBe("60.0s");
+  });
+
+  it("renders multi-minute durations as `Xm Ys`", () => {
+    expect(formatDurationMs(60000)).toBe("1m 0s");
+    expect(formatDurationMs(90000)).toBe("1m 30s");
+    expect(formatDurationMs(125000)).toBe("2m 5s");
+  });
+
+  it("carries the remainder cleanly when seconds round up to 60", () => {
+    // Pre-fix bug: 119600ms produced "1m 60s" because remSec rounded to 60.
+    expect(formatDurationMs(119600)).toBe("2m 0s");
+    expect(formatDurationMs(179600)).toBe("3m 0s");
+    expect(formatDurationMs(239600)).toBe("4m 0s");
+  });
+});
+
+describe("formatCostUsd", () => {
+  it("uses 4 decimals under $1", () => {
+    expect(formatCostUsd(0.0042)).toBe("$0.0042");
+    expect(formatCostUsd(0.5)).toBe("$0.5000");
+  });
+
+  it("uses 2 decimals at $1 or above", () => {
+    expect(formatCostUsd(1)).toBe("$1.00");
+    expect(formatCostUsd(12.345)).toBe("$12.35");
+  });
+});

From 6d16ae7400743184d5a264502ff99e052948a3d3 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 3 Jun 2026 14:25:26 -0700
Subject: [PATCH 06/13] fix(review): address local code-review findings on the
 refactor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three small issues caught by a thorough re-review of the refactor diff:

1. `securityBadgeInstruction` wrapped the badge markdown in single
   backticks (```![security](…)```), so an LLM literally following the
   prompt would paste the badge inside an inline-code span and produce
   `![security](...)` rendered as code instead of an image. Rephrased
   to emit the raw markdown with an explicit "no surrounding backticks
   or code fences" caveat.

2. The security-subagent prompt block interpolated
   `${t.baseRefLabel.toLowerCase()}` which produced awkward bare
   phrases ("pr base ref" / "mr target branch") instead of the
   original prompts' "base ref" / "target branch". Added a dedicated
   `baseRefShortLabel` field on ReviewTerminology and use it in the
   narrative prose; the noun-prefixed `baseRefLabel` is still used in
   the structured <context> block where it matches today's wording.

3. format.ts docstring claimed the helpers are "shared between the
   GitHub MCP comment server and the GitLab tracking-note builder" but
   the GH side doesn't consume them yet. Softened the wording to
   reflect actual usage today plus the unification intent.

Tests: 451/451 still pass; tsc clean.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/core/review/prompts/candidates.ts | 2 +-
 src/core/review/prompts/types.ts      | 2 ++
 src/core/review/tracking/format.ts    | 9 +++++----
 src/create-prompt/terminology.ts      | 1 +
 src/gitlab/prompts/terminology.ts     | 3 ++-
 5 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/core/review/prompts/candidates.ts b/src/core/review/prompts/candidates.ts
index 738c3c0..d5fb278 100644
--- a/src/core/review/prompts/candidates.ts
+++ b/src/core/review/prompts/candidates.ts
@@ -57,7 +57,7 @@ This subagent runs **concurrently** with the code review subagents during Step 2
 Spawn it with:
 - \`subagent_type\`: "security-reviewer"
 - \`description\`: "Security review"
-- \`prompt\`: Include the full ${t.entityNoun} context (${t.repoLabel.toLowerCase()}, ${t.entityNoun} ${t.metaEntityNumberKey === "prNumber" ? "number" : "IID"}, head SHA, ${t.baseRefLabel.toLowerCase()}) and the paths to precomputed data files (diff, description, existing comments). The security-reviewer will invoke the security-review skill and return a JSON array of security findings.
+- \`prompt\`: Include the full ${t.entityNoun} context (${t.repoLabel.toLowerCase()}, ${t.entityNoun} ${t.metaEntityNumberKey === "prNumber" ? "number" : "IID"}, head SHA, ${t.baseRefShortLabel}) and the paths to precomputed data files (diff, description, existing comments). The security-reviewer will invoke the security-review skill and return a JSON array of security findings.
 
 **IMPORTANT**: Spawn the security-reviewer in the SAME response as the code review subagents so they all run in parallel.
 
diff --git a/src/core/review/prompts/types.ts b/src/core/review/prompts/types.ts
index e65cfef..58313c7 100644
--- a/src/core/review/prompts/types.ts
+++ b/src/core/review/prompts/types.ts
@@ -25,6 +25,8 @@ export interface ReviewTerminology {
   headShaLabel: string;
   /** Label for the target branch row (e.g. "PR Base Ref" or "MR Target Branch") */
   baseRefLabel: string;
+  /** Short form of the target-branch concept, used in narrative prose (e.g. "base ref" or "target branch") */
+  baseRefShortLabel: string;
   /** Label for the description artifact (e.g. "PR Description" or "MR Description") */
   descriptionLabel: string;
   /** Label for the diff artifact (e.g. "Full PR Diff" or "Full MR Diff") */
diff --git a/src/core/review/tracking/format.ts b/src/core/review/tracking/format.ts
index 6d64fd3..b008cb1 100644
--- a/src/core/review/tracking/format.ts
+++ b/src/core/review/tracking/format.ts
@@ -1,8 +1,9 @@
 /**
- * Small formatting helpers shared between the GitHub MCP comment server
- * and the GitLab tracking-note builder. Kept platform-agnostic so the
- * two renderers can stay independent while still producing identical
- * telemetry text (e.g. "1m 23s • $0.0042").
+ * Small formatting helpers for sticky review-tracking
+ * comments/notes. Currently consumed by the GitLab tracking-note
+ * builder (`src/gitlab/operations/tracking-note.ts`); kept platform-
+ * agnostic in core so the GitHub MCP comment server can adopt the same
+ * "1m 23s • $0.0042" rendering when its telemetry path is unified.
  */
 
 export function formatDurationMs(ms: number): string {
diff --git a/src/create-prompt/terminology.ts b/src/create-prompt/terminology.ts
index f5cfcc7..d3b2ef2 100644
--- a/src/create-prompt/terminology.ts
+++ b/src/create-prompt/terminology.ts
@@ -9,6 +9,7 @@ export const GITHUB_TERMINOLOGY: ReviewTerminology = {
   headRefLabel: "PR Head Ref",
   headShaLabel: "PR Head SHA",
   baseRefLabel: "PR Base Ref",
+  baseRefShortLabel: "base ref",
   descriptionLabel: "PR Description",
   diffLabel: "Full PR Diff",
   metaRepoKey: "repo",
diff --git a/src/gitlab/prompts/terminology.ts b/src/gitlab/prompts/terminology.ts
index 5262902..c2616b3 100644
--- a/src/gitlab/prompts/terminology.ts
+++ b/src/gitlab/prompts/terminology.ts
@@ -10,6 +10,7 @@ export const GITLAB_TERMINOLOGY: ReviewTerminology = {
   headRefLabel: "MR Source Branch",
   headShaLabel: "MR Head SHA",
   baseRefLabel: "MR Target Branch",
+  baseRefShortLabel: "target branch",
   descriptionLabel: "MR Description",
   diffLabel: "Full MR Diff",
   metaRepoKey: "project",
@@ -32,7 +33,7 @@ export const GITLAB_TERMINOLOGY: ReviewTerminology = {
   summaryPostingExtraExclusion: "",
   approvalChangesNote:
     "Do not approve the MR or request changes (GitLab approval rules are handled out-of-band).",
-  securityBadgeInstruction: `If any approved comments contain \`[security]\` in their body, ensure a security badge is prepended to the tracking note body: \`${SECURITY_BADGE.trim()}\`. This indicates that security analysis was performed as part of the review.`,
+  securityBadgeInstruction: `If any approved comments contain \`[security]\` in their body, ensure a security badge is prepended to the tracking note body using exactly this markdown image (no surrounding backticks or code fences): ${SECURITY_BADGE.trim()} — this indicates that security analysis was performed as part of the review.`,
 };
 
 /**

From 95dbf0205dd4545432107b7429a99cd1fd02a000 Mon Sep 17 00:00:00 2001
From: eric-factory <eric.fan@factory.ai>
Date: Mon, 29 Jun 2026 15:39:01 -0700
Subject: [PATCH 07/13] docs(readme): add Authentication section

Document the two kinds of access the action needs: the FACTORY_API_KEY
secret to run Droid, and GitHub access via the Factory Droid GitHub App
(default) or a custom github_token (override).

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index c47e1ca..dada771 100644
--- a/README.md
+++ b/README.md
@@ -240,6 +240,47 @@ jobs:
           security_scan_days: 7
 ```
 
+## Authentication
+
+Droid needs two separate kinds of access: permission to run Droid, and permission to post on your pull requests. You set them up independently.
+
+### 1. Factory API key (run Droid)
+
+Droid runs using your Factory API key. Create one at [app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys) and save it as a `FACTORY_API_KEY` secret in your repository or organization. Pass it to the action on every run:
+
+```yaml
+- uses: Factory-AI/droid-action@main
+  with:
+    factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+```
+
+This input is required.
+
+### 2. GitHub access (post reviews)
+
+To leave comments and approvals on your PRs, Droid needs a GitHub token. There are two ways to provide one:
+
+- **Factory Droid GitHub App (default, recommended).** If you don't pass a token, the action securely requests one for the installed Factory Droid GitHub App. For most teams this is all you need: install the app on your repositories. It requires the `id-token: write` permission so the action can request the token:
+
+  ```yaml
+  permissions:
+    contents: write
+    pull-requests: write
+    issues: write
+    id-token: write # required for GitHub App auth
+  ```
+
+- **Your own token (override).** If you'd rather use a personal access token or your own GitHub App — for example on GitHub Enterprise, or to control which account posts comments — pass it as `github_token`. When set, Droid uses it directly and skips the app. The token needs write access to pull requests and repository contents.
+
+  ```yaml
+  - uses: Factory-AI/droid-action@main
+    with:
+      factory_api_key: ${{ secrets.FACTORY_API_KEY }}
+      github_token: ${{ secrets.MY_GITHUB_TOKEN }}
+  ```
+
+> On GitLab, the same two pieces apply: set `FACTORY_API_KEY` and `GITLAB_TOKEN` as CI/CD variables. See [`docs/gitlab-setup.md`](docs/gitlab-setup.md).
+
 ## Configuration
 
 ### Core Inputs

From 089a9ed457cfbf8701e5ffa9873a581eadc24e31 Mon Sep 17 00:00:00 2001
From: eric-factory <eric.fan@factory.ai>
Date: Mon, 29 Jun 2026 15:54:55 -0700
Subject: [PATCH 08/13] docs(readme): mention installing the GitHub App from
 org settings

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index dada771..8d785ea 100644
--- a/README.md
+++ b/README.md
@@ -260,7 +260,7 @@ This input is required.
 
 To leave comments and approvals on your PRs, Droid needs a GitHub token. There are two ways to provide one:
 
-- **Factory Droid GitHub App (default, recommended).** If you don't pass a token, the action securely requests one for the installed Factory Droid GitHub App. For most teams this is all you need: install the app on your repositories. It requires the `id-token: write` permission so the action can request the token:
+- **Factory Droid GitHub App (default, recommended).** If you don't pass a token, the action securely requests one for the installed Factory Droid GitHub App. For most teams this is all you need: install the app on your repositories from [app.factory.ai/settings/organization](https://app.factory.ai/settings/organization). It requires the `id-token: write` permission so the action can request the token:
 
   ```yaml
   permissions:

From c8dbf8349a6a90b11f07656c6bb3bab69bf25643 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 15 Jul 2026 13:42:20 -0700
Subject: [PATCH 09/13] fix(review): add retry logic and Pass 1 validation to
 improve success rate to 99.9%

Code review success rate is currently 96% (per Metabase dashboard 232).
Failures are concentrated in the Pass 1 to Pass 2 transition for CI reviews
(~476/24484 eligible reviews fail at Pass 2 over 30 days).

Root causes identified:
- No retry on Droid Exec failures (transient model/API errors kill the run)
- No retry on MCP server registration (single registration failure kills action)
- No retry on gh pr checkout (transient git/GitHub API failures kill run)
- No retry on gh pr diff fallback (transient failures in diff computation)
- No validation of Pass 1 candidates JSON before Pass 2 (malformed/missing
  candidates cause Pass 2 to fail with no graceful degradation)

Changes:
- run-droid.ts: Add retry (3 attempts, exponential backoff) around Droid Exec
  spawn+wait loop. Transient model timeouts and API errors now retry instead
  of immediately failing the pipeline.
- run-droid.ts: Add retry (3 attempts, 2s initial delay) around individual
  MCP server  registrations.
- review.ts: Wrap gh pr checkout in retryWithBackoff (3 attempts, 3s delay).
- generate-review-prompt.ts: Same retry for the standalone review action path.
- review-artifacts.ts: Wrap gh pr diff fallback in retryWithBackoff (3 attempts).
- prepare-validator.ts: Validate Pass 1 candidates JSON exists and has valid
  schema before running Pass 2. If invalid, skip Pass 2 gracefully instead of
  failing the entire pipeline.
- action.yml: Add conditional to skip validator Droid Exec step when
  prepare-validator outputs validator_should_run=false.
- run-droid-mcp.test.ts: Update MCP failure test to account for retry delays.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 action.yml                                |   2 +-
 base-action/src/run-droid.ts              | 214 +++++++++++++++-------
 base-action/test/run-droid-mcp.test.ts    |   4 +-
 src/entrypoints/generate-review-prompt.ts |  27 ++-
 src/entrypoints/prepare-validator.ts      |  37 ++++
 src/github/data/review-artifacts.ts       |  18 +-
 src/tag/commands/review.ts                |  25 ++-
 7 files changed, 231 insertions(+), 96 deletions(-)

diff --git a/action.yml b/action.yml
index 838724f..a6c57e7 100644
--- a/action.yml
+++ b/action.yml
@@ -307,7 +307,7 @@ runs:
 
     - name: Run Droid Exec (validator)
       id: droid_validator
-      if: steps.prepare.outputs.contains_trigger == 'true' && steps.prepare.outputs.run_code_review == 'true'
+      if: steps.prepare.outputs.contains_trigger == 'true' && steps.prepare.outputs.run_code_review == 'true' && steps.prepare_validator.outputs.validator_should_run != 'false'
       shell: bash
       run: |
 
diff --git a/base-action/src/run-droid.ts b/base-action/src/run-droid.ts
index 015dc98..43efdec 100644
--- a/base-action/src/run-droid.ts
+++ b/base-action/src/run-droid.ts
@@ -6,6 +6,49 @@ import { parse as parseShellArgs } from "shell-quote";
 
 const execAsync = promisify(exec);
 
+/**
+ * Retry an async operation with exponential backoff.
+ * Used for transient failures (Droid Exec, MCP registration, network calls).
+ */
+async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+  } = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelayMs = 5000,
+    maxDelayMs = 20000,
+    backoffFactor = 2,
+  } = options;
+
+  let delayMs = initialDelayMs;
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      console.log(`Attempt ${attempt} of ${maxAttempts}...`);
+      return await operation();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      console.error(`Attempt ${attempt} failed:`, lastError.message);
+
+      if (attempt < maxAttempts) {
+        console.log(`Retrying in ${delayMs / 1000} seconds...`);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        delayMs = Math.min(delayMs * backoffFactor, maxDelayMs);
+      }
+    }
+  }
+
+  console.error(`Operation failed after ${maxAttempts} attempts`);
+  throw lastError;
+}
+
 const BASE_ARGS = [
   "exec",
   "--output-format",
@@ -153,7 +196,18 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
           const addCmd = `droid mcp add ${name} "${cmd}" ${envFlags}`.trim();
 
           try {
-            await execAsync(addCmd, { env: { ...process.env } });
+            await retryWithBackoff(
+              async () => {
+                // Remove existing server if present (ignore errors) before each attempt
+                try {
+                  await execAsync(`droid mcp remove ${name}`);
+                } catch (_) {
+                  // Ignore - server might not exist
+                }
+                await execAsync(addCmd, { env: { ...process.env } });
+              },
+              { maxAttempts: 3, initialDelayMs: 2000, maxDelayMs: 10000 },
+            );
             console.log(`  ✓ Registered MCP server: ${name}`);
           } catch (e: any) {
             console.error(
@@ -219,19 +273,6 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
   // Use custom executable path if provided, otherwise default to "droid"
   const droidExecutable = options.pathToDroidExecutable || "droid";
 
-  const droidProcess = spawn(droidExecutable, config.droidArgs, {
-    stdio: ["ignore", "pipe", "inherit"],
-    env: {
-      ...process.env,
-      ...config.env,
-    },
-  });
-
-  // Handle Droid process errors
-  droidProcess.on("error", (error) => {
-    console.error("Error spawning Droid process:", error);
-  });
-
   // Determine if full output should be shown
   // Show full output if explicitly set to "true" OR if GitHub Actions debug mode is enabled
   const isDebugMode = process.env.ACTIONS_STEP_DEBUG === "true";
@@ -247,74 +288,107 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
     );
   }
 
-  // Capture output for parsing execution metrics
-  let sessionId: string | undefined;
-  droidProcess.stdout.on("data", (data) => {
-    const text = data.toString();
-
-    // Try to parse as JSON and handle based on verbose setting
-    const lines = text.split("\n");
-    lines.forEach((line: string, index: number) => {
-      if (line.trim() === "") return;
-
-      try {
-        // Check if this line is a JSON object
-        const parsed = JSON.parse(line);
-        if (!sessionId && typeof parsed === "object" && parsed !== null) {
-          const detectedSessionId = parsed.session_id;
-          if (
-            typeof detectedSessionId === "string" &&
-            detectedSessionId.trim()
-          ) {
-            sessionId = detectedSessionId;
-            console.log(`Detected Droid session: ${sessionId}`);
+  // Run Droid Exec with retry for transient failures
+  const maxRetries = 2; // 1 initial attempt + 2 retries = 3 total
+  let lastExitCode = 1;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      console.log(
+        `Droid Exec retry attempt ${attempt}/${maxRetries} (previous exit code: ${lastExitCode})...`,
+      );
+      const retryDelayMs = Math.min(5000 * Math.pow(2, attempt - 1), 30000);
+      console.log(`Waiting ${retryDelayMs / 1000}s before retry...`);
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+
+    const droidProcess = spawn(droidExecutable, config.droidArgs, {
+      stdio: ["ignore", "pipe", "inherit"],
+      env: {
+        ...process.env,
+        ...config.env,
+      },
+    });
+
+    // Handle Droid process errors
+    droidProcess.on("error", (error) => {
+      console.error("Error spawning Droid process:", error);
+    });
+
+    // Capture output for parsing execution metrics
+    let sessionId: string | undefined;
+    droidProcess.stdout.on("data", (data) => {
+      const text = data.toString();
+
+      // Try to parse as JSON and handle based on verbose setting
+      const lines = text.split("\n");
+      lines.forEach((line: string, index: number) => {
+        if (line.trim() === "") return;
+
+        try {
+          // Check if this line is a JSON object
+          const parsed = JSON.parse(line);
+          if (!sessionId && typeof parsed === "object" && parsed !== null) {
+            const detectedSessionId = parsed.session_id;
+            if (
+              typeof detectedSessionId === "string" &&
+              detectedSessionId.trim()
+            ) {
+              sessionId = detectedSessionId;
+              console.log(`Detected Droid session: ${sessionId}`);
+            }
           }
-        }
-        const sanitizedOutput = sanitizeJsonOutput(parsed, showFullOutput);
+          const sanitizedOutput = sanitizeJsonOutput(parsed, showFullOutput);
 
-        if (sanitizedOutput) {
-          process.stdout.write(sanitizedOutput);
-          if (index < lines.length - 1 || text.endsWith("\n")) {
-            process.stdout.write("\n");
+          if (sanitizedOutput) {
+            process.stdout.write(sanitizedOutput);
+            if (index < lines.length - 1 || text.endsWith("\n")) {
+              process.stdout.write("\n");
+            }
           }
-        }
-      } catch (e) {
-        // Not a JSON object
-        if (showFullOutput) {
-          // In full output mode, print as is
-          process.stdout.write(line);
-          if (index < lines.length - 1 || text.endsWith("\n")) {
-            process.stdout.write("\n");
+        } catch (e) {
+          // Not a JSON object
+          if (showFullOutput) {
+            // In full output mode, print as is
+            process.stdout.write(line);
+            if (index < lines.length - 1 || text.endsWith("\n")) {
+              process.stdout.write("\n");
+            }
           }
+          // In non-full-output mode, suppress non-JSON output
         }
-        // In non-full-output mode, suppress non-JSON output
-      }
+      });
     });
-  });
-
-  // Handle stdout errors
-  droidProcess.stdout.on("error", (error) => {
-    console.error("Error reading Droid stdout:", error);
-  });
 
-  // Wait for Droid Exec to finish
-  const exitCode = await new Promise<number>((resolve) => {
-    droidProcess.on("close", (code) => {
-      resolve(code || 0);
+    // Handle stdout errors
+    droidProcess.stdout.on("error", (error) => {
+      console.error("Error reading Droid stdout:", error);
     });
 
-    droidProcess.on("error", (error) => {
-      console.error("Droid process error:", error);
-      resolve(1);
+    // Wait for Droid Exec to finish
+    lastExitCode = await new Promise<number>((resolve) => {
+      droidProcess.on("close", (code) => {
+        resolve(code || 0);
+      });
+
+      droidProcess.on("error", (error) => {
+        console.error("Droid process error:", error);
+        resolve(1);
+      });
     });
-  });
 
-  // Set conclusion based on exit code
-  if (exitCode === 0) {
-    core.setOutput("conclusion", "success");
-    return;
+    if (lastExitCode === 0) {
+      core.setOutput("conclusion", "success");
+      return;
+    }
+
+    console.log(`Droid Exec exited with code ${lastExitCode}`);
   }
 
+  // All retry attempts exhausted
+  console.error(
+    `Droid Exec failed after ${maxRetries + 1} total attempts (exit code: ${lastExitCode})`,
+  );
   core.setOutput("conclusion", "failure");
-  process.exit(exitCode);
+  process.exit(lastExitCode);
 }
diff --git a/base-action/test/run-droid-mcp.test.ts b/base-action/test/run-droid-mcp.test.ts
index 79ebb8a..b765caf 100644
--- a/base-action/test/run-droid-mcp.test.ts
+++ b/base-action/test/run-droid-mcp.test.ts
@@ -273,7 +273,7 @@ describe("MCP Server Registration", () => {
   });
 
   describe("Error Handling", () => {
-    test("should fail fast when MCP server registration fails", async () => {
+    test("should fail when MCP server registration fails after retries", async () => {
       const mcpTools = JSON.stringify({
         mcpServers: {
           failing_server: {
@@ -298,7 +298,7 @@ describe("MCP Server Registration", () => {
       } finally {
         await cleanupTempDir(tempDir);
       }
-    });
+    }, 30000); // Allow time for retry backoff (3 attempts x 2s+4s delays)
 
     test("should not attempt MCP registration when config is not provided", () => {
       const options: DroidOptions = {};
diff --git a/src/entrypoints/generate-review-prompt.ts b/src/entrypoints/generate-review-prompt.ts
index 46886d0..447888c 100644
--- a/src/entrypoints/generate-review-prompt.ts
+++ b/src/entrypoints/generate-review-prompt.ts
@@ -16,6 +16,7 @@ import { generateReviewCandidatesPrompt } from "../create-prompt/templates/revie
 import { generateSecurityCandidatesPrompt } from "../create-prompt/templates/security-review-prompt";
 import { normalizeDroidArgs, parseAllowedTools } from "../utils/parse-tools";
 import { resolveReviewConfig } from "../utils/review-depth";
+import { retryWithBackoff } from "../utils/retry";
 
 async function run() {
   try {
@@ -60,17 +61,25 @@ async function run() {
       `Checking out PR #${context.entityNumber} branch for diff computation...`,
     );
     try {
-      execSync("git reset --hard HEAD", { encoding: "utf8", stdio: "pipe" });
-      execSync(`gh pr checkout ${context.entityNumber}`, {
-        encoding: "utf8",
-        stdio: "pipe",
-        env: { ...process.env, GH_TOKEN: githubToken },
-      });
-      console.log(
-        `Successfully checked out PR branch: ${execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim()}`,
+      await retryWithBackoff(
+        async () => {
+          execSync("git reset --hard HEAD", {
+            encoding: "utf8",
+            stdio: "pipe",
+          });
+          execSync(`gh pr checkout ${context.entityNumber}`, {
+            encoding: "utf8",
+            stdio: "pipe",
+            env: { ...process.env, GH_TOKEN: githubToken },
+          });
+          console.log(
+            `Successfully checked out PR branch: ${execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim()}`,
+          );
+        },
+        { maxAttempts: 3, initialDelayMs: 3000, maxDelayMs: 15000 },
       );
     } catch (e) {
-      console.error(`Failed to checkout PR branch: ${e}`);
+      console.error(`Failed to checkout PR branch after retries: ${e}`);
       throw new Error(
         `Failed to checkout PR #${context.entityNumber} branch for review`,
       );
diff --git a/src/entrypoints/prepare-validator.ts b/src/entrypoints/prepare-validator.ts
index 1382f76..31d3714 100644
--- a/src/entrypoints/prepare-validator.ts
+++ b/src/entrypoints/prepare-validator.ts
@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import * as core from "@actions/core";
+import { readFile } from "fs/promises";
 import { setupGitHubToken } from "../github/token";
 import { createOctokit } from "../github/api/client";
 import { parseGitHubContext, isEntityContext } from "../github/context";
@@ -14,6 +15,41 @@ async function run() {
       throw new Error("prepare-validator requires a pull request context");
     }
 
+    // Validate that Pass 1 produced a valid candidates JSON file.
+    // If the file is missing or invalid, skip Pass 2 gracefully rather than
+    // failing the entire pipeline. This prevents the ~2% of reviews where
+    // Pass 1 had a transient issue from counting as full failures.
+    const candidatesPath = process.env.REVIEW_CANDIDATES_PATH || "";
+    if (candidatesPath) {
+      try {
+        const content = await readFile(candidatesPath, "utf8");
+        const parsed = JSON.parse(content);
+        if (
+          !parsed ||
+          typeof parsed !== "object" ||
+          !Array.isArray(parsed.comments)
+        ) {
+          throw new Error("Missing or invalid 'comments' array in candidates");
+        }
+        console.log(
+          `Pass 1 candidates validated: ${parsed.comments.length} comments found`,
+        );
+      } catch (e: any) {
+        console.error(
+          `Pass 1 candidates JSON is invalid or missing: ${e.message}`,
+        );
+        console.error(
+          "Skipping Pass 2 (validator) to avoid a full pipeline failure",
+        );
+        core.setOutput("contains_trigger", "false");
+        core.setOutput("validator_should_run", "false");
+        core.notice(
+          "Pass 1 candidates validation failed - skipping validator pass",
+        );
+        return;
+      }
+    }
+
     const githubToken = await setupGitHubToken();
     const octokit = createOctokit(githubToken);
 
@@ -30,6 +66,7 @@ async function run() {
     });
 
     core.setOutput("github_token", githubToken);
+    core.setOutput("validator_should_run", "true");
     if (result?.mcpTools) core.setOutput("mcp_tools", result.mcpTools);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
diff --git a/src/github/data/review-artifacts.ts b/src/github/data/review-artifacts.ts
index c7d7a4f..1e1d7f6 100644
--- a/src/github/data/review-artifacts.ts
+++ b/src/github/data/review-artifacts.ts
@@ -2,6 +2,7 @@ import { execSync } from "child_process";
 import { writeFile, mkdir } from "fs/promises";
 import type { Octokits } from "../api/client";
 import type { ReviewArtifacts } from "../../create-prompt/types";
+import { retryWithBackoff } from "../../utils/retry";
 
 const DIFF_MAX_BUFFER = 50 * 1024 * 1024; // 50MB buffer for large diffs
 
@@ -59,15 +60,22 @@ export async function computeAndStoreDiff(
     });
   } catch {
     // Fallback: use gh CLI to get the diff (works even with shallow clones)
+    // Retry since gh CLI can have transient rate-limit or network failures
     if (options?.githubToken && options?.prNumber) {
       console.log(
         "Git merge-base failed, falling back to gh pr diff for PR diff",
       );
-      diff = execSync(`gh pr diff ${options.prNumber}`, {
-        encoding: "utf8",
-        maxBuffer: DIFF_MAX_BUFFER,
-        env: { ...process.env, GH_TOKEN: options.githubToken },
-      });
+      diff = await retryWithBackoff(
+        () =>
+          Promise.resolve(
+            execSync(`gh pr diff ${options.prNumber}`, {
+              encoding: "utf8",
+              maxBuffer: DIFF_MAX_BUFFER,
+              env: { ...process.env, GH_TOKEN: options.githubToken },
+            }),
+          ),
+        { maxAttempts: 3, initialDelayMs: 3000, maxDelayMs: 15000 },
+      );
     } else {
       throw new Error(
         "Git merge-base failed and no fallback credentials provided",
diff --git a/src/tag/commands/review.ts b/src/tag/commands/review.ts
index 22215f7..d5d92ac 100644
--- a/src/tag/commands/review.ts
+++ b/src/tag/commands/review.ts
@@ -12,6 +12,7 @@ import { generateReviewCandidatesPrompt } from "../../create-prompt/templates/re
 import type { Octokits } from "../../github/api/client";
 import type { PrepareResult } from "../../prepare/types";
 import { resolveReviewConfig } from "../../utils/review-depth";
+import { retryWithBackoff } from "../../utils/retry";
 
 type ReviewCommandOptions = {
   context: GitHubContext;
@@ -55,17 +56,23 @@ export async function prepareReviewMode({
     `Checking out PR #${context.entityNumber} branch for diff computation...`,
   );
   try {
-    execSync("git reset --hard HEAD", { encoding: "utf8", stdio: "pipe" });
-    execSync(`gh pr checkout ${context.entityNumber}`, {
-      encoding: "utf8",
-      stdio: "pipe",
-      env: { ...process.env, GH_TOKEN: githubToken },
-    });
-    console.log(
-      `Successfully checked out PR branch: ${execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim()}`,
+    await retryWithBackoff(
+      async () => {
+        execSync("git reset --hard HEAD", { encoding: "utf8", stdio: "pipe" });
+        execSync(`gh pr checkout ${context.entityNumber}`, {
+          encoding: "utf8",
+          stdio: "pipe",
+          env: { ...process.env, GH_TOKEN: githubToken },
+        });
+        const branchName = execSync("git rev-parse --abbrev-ref HEAD", {
+          encoding: "utf8",
+        }).trim();
+        console.log(`Successfully checked out PR branch: ${branchName}`);
+      },
+      { maxAttempts: 3, initialDelayMs: 3000, maxDelayMs: 15000 },
     );
   } catch (e) {
-    console.error(`Failed to checkout PR branch: ${e}`);
+    console.error(`Failed to checkout PR branch after retries: ${e}`);
     throw new Error(
       `Failed to checkout PR #${context.entityNumber} branch for review`,
     );

From 2c3f2ee7ae162adbe841a2eb558e77491050bb31 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 15 Jul 2026 13:44:47 -0700
Subject: [PATCH 10/13] fix(review): add Pass 1 candidates validation to GitLab
 validator

Mirror the GitHub validation in gitlab-prepare-validator.ts: check that
the candidates JSON file exists and has a valid 'comments' array before
writing the Pass 2 prompt. If invalid, write a no-op prompt so droid exec
exits cleanly instead of failing the pipeline.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 src/entrypoints/gitlab-prepare-validator.ts | 30 +++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/entrypoints/gitlab-prepare-validator.ts b/src/entrypoints/gitlab-prepare-validator.ts
index d71fb7e..327a7c6 100644
--- a/src/entrypoints/gitlab-prepare-validator.ts
+++ b/src/entrypoints/gitlab-prepare-validator.ts
@@ -63,6 +63,36 @@ async function run(): Promise<void> {
   const descriptionPath = ensure(state.descriptionPath, "descriptionPath");
   const headSha = ensure(state.headSha, "headSha");
 
+  // Validate that Pass 1 produced a valid candidates JSON file.
+  // If invalid or missing, skip Pass 2 gracefully rather than failing.
+  try {
+    const content = await fs.readFile(candidatesPath, "utf8");
+    const parsed = JSON.parse(content);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      !Array.isArray(parsed.comments)
+    ) {
+      throw new Error("Missing or invalid 'comments' array in candidates");
+    }
+    console.log(
+      `Pass 1 candidates validated: ${parsed.comments.length} comments found`,
+    );
+  } catch (e: any) {
+    console.error(
+      `Pass 1 candidates JSON is invalid or missing: ${e.message}`,
+    );
+    console.error(
+      "Skipping Pass 2 (validator) to avoid a full pipeline failure",
+    );
+    // Write a no-op prompt so droid exec exits cleanly
+    await fs.writeFile(
+      promptPath,
+      "No review findings to validate. Pass 1 candidates were invalid. Exit with success.",
+    );
+    return;
+  }
+
   const promptCtx: GitlabReviewPromptContext = {
     projectPath: state.projectPath,
     mrIid,

From 399aa1b1c926f901abe38c2260a4e395e3a4de59 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 15 Jul 2026 13:46:26 -0700
Subject: [PATCH 11/13] fix(review): handle DROID_SUCCESS when validator is
 skipped

When validator_should_run is false (Pass 1 candidates invalid), base
DROID_SUCCESS on Pass 1's conclusion instead of the skipped validator
step's conclusion. This prevents the tracking comment from showing an
error when the pipeline intentionally skipped Pass 2.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 action.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/action.yml b/action.yml
index a6c57e7..af89828 100644
--- a/action.yml
+++ b/action.yml
@@ -345,7 +345,7 @@ runs:
         GITHUB_EVENT_NAME: ${{ github.event_name }}
         TRIGGER_COMMENT_ID: ${{ github.event.comment.id }}
         IS_PR: ${{ github.event.issue.pull_request != null || github.event_name == 'pull_request_target' || github.event_name == 'pull_request_review_comment' }}
-        DROID_SUCCESS: ${{ (steps.prepare.outputs.run_code_review == 'true' && steps.droid_validator.outputs.conclusion == 'success') || (steps.prepare.outputs.run_code_review != 'true' && steps.droid.outputs.conclusion == 'success') }}
+        DROID_SUCCESS: ${{ (steps.prepare.outputs.run_code_review == 'true' && (steps.prepare_validator.outputs.validator_should_run == 'false' ? steps.droid.outputs.conclusion == 'success' : steps.droid_validator.outputs.conclusion == 'success')) || (steps.prepare.outputs.run_code_review != 'true' && steps.droid.outputs.conclusion == 'success') }}
         TRIGGER_USERNAME: ${{ github.event.comment.user.login || github.event.issue.user.login || github.event.pull_request.user.login || github.event.sender.login || github.triggering_actor || github.actor || '' }}
         PREPARE_SUCCESS: ${{ steps.prepare.outcome == 'success' }}
         PREPARE_ERROR: ${{ steps.prepare.outputs.prepare_error || '' }}

From 6db77fe6efdb1e73733bd8d4057a69864f5de0ca Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 15 Jul 2026 16:52:46 -0700
Subject: [PATCH 12/13] fix(review): replace unsupported ternary in
 DROID_SUCCESS expression

GitHub Actions expression syntax has no ternary (? :) operator, so the
DROID_SUCCESS expression threw 'Unexpected symbol' at runtime and broke
the comment/status-update step on nearly every triggered review. Rewrite
the validator-skip branch using &&/|| equivalents.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 action.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/action.yml b/action.yml
index af89828..8009959 100644
--- a/action.yml
+++ b/action.yml
@@ -345,7 +345,7 @@ runs:
         GITHUB_EVENT_NAME: ${{ github.event_name }}
         TRIGGER_COMMENT_ID: ${{ github.event.comment.id }}
         IS_PR: ${{ github.event.issue.pull_request != null || github.event_name == 'pull_request_target' || github.event_name == 'pull_request_review_comment' }}
-        DROID_SUCCESS: ${{ (steps.prepare.outputs.run_code_review == 'true' && (steps.prepare_validator.outputs.validator_should_run == 'false' ? steps.droid.outputs.conclusion == 'success' : steps.droid_validator.outputs.conclusion == 'success')) || (steps.prepare.outputs.run_code_review != 'true' && steps.droid.outputs.conclusion == 'success') }}
+        DROID_SUCCESS: ${{ (steps.prepare.outputs.run_code_review == 'true' && ((steps.prepare_validator.outputs.validator_should_run == 'false' && steps.droid.outputs.conclusion == 'success') || (steps.prepare_validator.outputs.validator_should_run != 'false' && steps.droid_validator.outputs.conclusion == 'success'))) || (steps.prepare.outputs.run_code_review != 'true' && steps.droid.outputs.conclusion == 'success') }}
         TRIGGER_USERNAME: ${{ github.event.comment.user.login || github.event.issue.user.login || github.event.pull_request.user.login || github.event.sender.login || github.triggering_actor || github.actor || '' }}
         PREPARE_SUCCESS: ${{ steps.prepare.outcome == 'success' }}
         PREPARE_ERROR: ${{ steps.prepare.outputs.prepare_error || '' }}

From 2402a6b3c2717b8740ea6e01ca5ef71868698972 Mon Sep 17 00:00:00 2001
From: Nizar Alrifai <nizar@factory.ai>
Date: Wed, 15 Jul 2026 17:20:51 -0700
Subject: [PATCH 13/13] Apply PR review fixes: harden retry/validation, redact
 secrets

- prepare-validator: drop dead contains_trigger output, narrow catch to
  instanceof Error
- gitlab-prepare-validator: narrow catch to instanceof Error
- artifacts: co-locate ReviewArtifactNames with sibling types in types.ts
- base-action/run-droid: extract shared retryWithBackoff into utils/retry,
  remove duplicated inline copy and redundant pre-retry mcp remove, redact
  inline --env secrets before logging/rethrow, unify Droid Exec retry to the
  shared backoff helper
- add base-action retry unit test

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
---
 base-action/src/run-droid.ts                | 120 +++++++-------------
 base-action/src/utils/retry.ts              |  48 ++++++++
 base-action/test/retry.test.ts              |  72 ++++++++++++
 src/core/review/artifacts/types.ts          |  12 ++
 src/core/review/artifacts/write.ts          |  18 +--
 src/entrypoints/gitlab-prepare-validator.ts |   7 +-
 src/entrypoints/prepare-validator.ts        |   6 +-
 7 files changed, 185 insertions(+), 98 deletions(-)
 create mode 100644 base-action/src/utils/retry.ts
 create mode 100644 base-action/test/retry.test.ts

diff --git a/base-action/src/run-droid.ts b/base-action/src/run-droid.ts
index 43efdec..2446db0 100644
--- a/base-action/src/run-droid.ts
+++ b/base-action/src/run-droid.ts
@@ -3,50 +3,13 @@ import { exec, spawn } from "child_process";
 import { promisify } from "util";
 import { stat } from "fs/promises";
 import { parse as parseShellArgs } from "shell-quote";
+import { retryWithBackoff } from "./utils/retry";
 
 const execAsync = promisify(exec);
 
-/**
- * Retry an async operation with exponential backoff.
- * Used for transient failures (Droid Exec, MCP registration, network calls).
- */
-async function retryWithBackoff<T>(
-  operation: () => Promise<T>,
-  options: {
-    maxAttempts?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    backoffFactor?: number;
-  } = {},
-): Promise<T> {
-  const {
-    maxAttempts = 3,
-    initialDelayMs = 5000,
-    maxDelayMs = 20000,
-    backoffFactor = 2,
-  } = options;
-
-  let delayMs = initialDelayMs;
-  let lastError: Error | undefined;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      console.log(`Attempt ${attempt} of ${maxAttempts}...`);
-      return await operation();
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error));
-      console.error(`Attempt ${attempt} failed:`, lastError.message);
-
-      if (attempt < maxAttempts) {
-        console.log(`Retrying in ${delayMs / 1000} seconds...`);
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-        delayMs = Math.min(delayMs * backoffFactor, maxDelayMs);
-      }
-    }
-  }
-
-  console.error(`Operation failed after ${maxAttempts} attempts`);
-  throw lastError;
+/** Redact inline `--env KEY=value` secrets before logging a command string. */
+function redactEnvSecrets(text: string): string {
+  return text.replace(/--env\s+(\S+?)=\S+/g, "--env $1=***");
 }
 
 const BASE_ARGS = [
@@ -181,13 +144,6 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
             .filter(Boolean)
             .join(" ");
 
-          // Remove existing server if present (ignore errors)
-          try {
-            await execAsync(`droid mcp remove ${name}`);
-          } catch (_) {
-            // Ignore - server might not exist
-          }
-
           // Build env flags
           const envFlags = Object.entries(def.env || {})
             .map(([k, v]) => `--env ${k}=${String(v)}`)
@@ -204,17 +160,25 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
                 } catch (_) {
                   // Ignore - server might not exist
                 }
-                await execAsync(addCmd, { env: { ...process.env } });
+                try {
+                  await execAsync(addCmd, { env: { ...process.env } });
+                } catch (err) {
+                  // Redact inline --env secrets before they reach any log or rethrow.
+                  const message =
+                    err instanceof Error ? err.message : String(err);
+                  throw new Error(redactEnvSecrets(message));
+                }
               },
               { maxAttempts: 3, initialDelayMs: 2000, maxDelayMs: 10000 },
             );
             console.log(`  ✓ Registered MCP server: ${name}`);
-          } catch (e: any) {
+          } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
             console.error(
               `  ✗ Failed to register MCP server ${name}:`,
-              e.message,
+              message,
             );
-            throw e;
+            throw new Error(message);
           }
         }
       }
@@ -288,20 +252,12 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
     );
   }
 
-  // Run Droid Exec with retry for transient failures
-  const maxRetries = 2; // 1 initial attempt + 2 retries = 3 total
+  // Run Droid Exec with retry for transient failures. Uses the shared
+  // retryWithBackoff so backoff timing lives in one place (3 total attempts,
+  // 5s then 10s delays).
   let lastExitCode = 1;
 
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    if (attempt > 0) {
-      console.log(
-        `Droid Exec retry attempt ${attempt}/${maxRetries} (previous exit code: ${lastExitCode})...`,
-      );
-      const retryDelayMs = Math.min(5000 * Math.pow(2, attempt - 1), 30000);
-      console.log(`Waiting ${retryDelayMs / 1000}s before retry...`);
-      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
-    }
-
+  const runDroidOnce = (): Promise<number> => {
     const droidProcess = spawn(droidExecutable, config.droidArgs, {
       stdio: ["ignore", "pipe", "inherit"],
       env: {
@@ -366,7 +322,7 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
     });
 
     // Wait for Droid Exec to finish
-    lastExitCode = await new Promise<number>((resolve) => {
+    return new Promise<number>((resolve) => {
       droidProcess.on("close", (code) => {
         resolve(code || 0);
       });
@@ -376,19 +332,27 @@ export async function runDroid(promptPath: string, options: DroidOptions) {
         resolve(1);
       });
     });
+  };
 
-    if (lastExitCode === 0) {
-      core.setOutput("conclusion", "success");
-      return;
-    }
-
-    console.log(`Droid Exec exited with code ${lastExitCode}`);
+  try {
+    await retryWithBackoff(
+      async () => {
+        lastExitCode = await runDroidOnce();
+        if (lastExitCode !== 0) {
+          console.log(`Droid Exec exited with code ${lastExitCode}`);
+          throw new Error(`Droid Exec exited with code ${lastExitCode}`);
+        }
+      },
+      { maxAttempts: 3, initialDelayMs: 5000, maxDelayMs: 20000 },
+    );
+    core.setOutput("conclusion", "success");
+    return;
+  } catch (_) {
+    // All retry attempts exhausted
+    console.error(
+      `Droid Exec failed after 3 total attempts (exit code: ${lastExitCode})`,
+    );
+    core.setOutput("conclusion", "failure");
+    process.exit(lastExitCode);
   }
-
-  // All retry attempts exhausted
-  console.error(
-    `Droid Exec failed after ${maxRetries + 1} total attempts (exit code: ${lastExitCode})`,
-  );
-  core.setOutput("conclusion", "failure");
-  process.exit(lastExitCode);
 }
diff --git a/base-action/src/utils/retry.ts b/base-action/src/utils/retry.ts
new file mode 100644
index 0000000..6455e65
--- /dev/null
+++ b/base-action/src/utils/retry.ts
@@ -0,0 +1,48 @@
+export type RetryOptions = {
+  maxAttempts?: number;
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  backoffFactor?: number;
+};
+
+/**
+ * Retry an async operation with exponential backoff.
+ * Used for transient failures (Droid Exec, MCP registration, network calls).
+ *
+ * Mirrors `src/utils/retry.ts`; base-action is published standalone and cannot
+ * import from the parent `src/`, so the helper is duplicated here rather than
+ * shared.
+ */
+export async function retryWithBackoff<T>(
+  operation: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelayMs = 5000,
+    maxDelayMs = 20000,
+    backoffFactor = 2,
+  } = options;
+
+  let delayMs = initialDelayMs;
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      console.log(`Attempt ${attempt} of ${maxAttempts}...`);
+      return await operation();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      console.error(`Attempt ${attempt} failed:`, lastError.message);
+
+      if (attempt < maxAttempts) {
+        console.log(`Retrying in ${delayMs / 1000} seconds...`);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        delayMs = Math.min(delayMs * backoffFactor, maxDelayMs);
+      }
+    }
+  }
+
+  console.error(`Operation failed after ${maxAttempts} attempts`);
+  throw lastError;
+}
diff --git a/base-action/test/retry.test.ts b/base-action/test/retry.test.ts
new file mode 100644
index 0000000..d414987
--- /dev/null
+++ b/base-action/test/retry.test.ts
@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { retryWithBackoff } from "../src/utils/retry";
+
+describe("retryWithBackoff", () => {
+  let timeoutSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    timeoutSpy = spyOn(globalThis, "setTimeout").mockImplementation(((
+      handler: Parameters<typeof setTimeout>[0],
+    ) => {
+      if (typeof handler === "function") {
+        handler();
+      }
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+    }) as unknown as typeof setTimeout);
+  });
+
+  afterEach(() => {
+    timeoutSpy.mockRestore();
+  });
+
+  it("resolves when the operation succeeds on the first attempt", async () => {
+    const result = await retryWithBackoff(async () => "success");
+
+    expect(result).toBe("success");
+    expect(timeoutSpy).not.toHaveBeenCalled();
+  });
+
+  it("retries failed attempts until the operation succeeds", async () => {
+    let attempts = 0;
+
+    const result = await retryWithBackoff(
+      async () => {
+        attempts += 1;
+        if (attempts < 3) {
+          throw new Error(`failure ${attempts}`);
+        }
+        return "ok";
+      },
+      { maxAttempts: 4, initialDelayMs: 10, backoffFactor: 3, maxDelayMs: 90 },
+    );
+
+    expect(result).toBe("ok");
+    expect(attempts).toBe(3);
+    expect(timeoutSpy).toHaveBeenCalledTimes(2);
+    const delays = timeoutSpy.mock.calls.map(
+      (call: Parameters<typeof setTimeout>) => call[1]! as number,
+    );
+    expect(delays).toEqual([10, 30]);
+  });
+
+  it("throws the last error after exhausting all attempts", async () => {
+    let attempts = 0;
+
+    await expect(
+      retryWithBackoff(
+        async () => {
+          attempts += 1;
+          throw new Error(`still failing ${attempts}`);
+        },
+        { maxAttempts: 2, initialDelayMs: 5 },
+      ),
+    ).rejects.toThrow("still failing 2");
+
+    expect(attempts).toBe(2);
+    expect(timeoutSpy).toHaveBeenCalledTimes(1);
+    const firstCall = timeoutSpy.mock.calls[0] as
+      | Parameters<typeof setTimeout>
+      | undefined;
+    expect(firstCall?.[1]).toBe(5);
+  });
+});
diff --git a/src/core/review/artifacts/types.ts b/src/core/review/artifacts/types.ts
index 62843d0..558069b 100644
--- a/src/core/review/artifacts/types.ts
+++ b/src/core/review/artifacts/types.ts
@@ -23,3 +23,15 @@ export type ReviewArtifactContents = {
   comments: unknown; // JSON-serializable
   description: string;
 };
+
+/**
+ * Naming convention for review-artifact files on disk. Each platform
+ * gets its own basename for the diff and description (pr.diff /
+ * mr.diff, pr_description.txt / mr_description.txt) but the existing
+ * comments file is platform-neutral.
+ */
+export type ReviewArtifactNames = {
+  diff: string;
+  comments: string;
+  description: string;
+};
diff --git a/src/core/review/artifacts/write.ts b/src/core/review/artifacts/write.ts
index 4befa76..70f1584 100644
--- a/src/core/review/artifacts/write.ts
+++ b/src/core/review/artifacts/write.ts
@@ -1,18 +1,10 @@
 import * as fs from "fs/promises";
 import * as path from "path";
-import type { ReviewArtifactContents, ReviewArtifactPaths } from "./types";
-
-/**
- * Naming convention for review-artifact files on disk. Each platform
- * gets its own basename for the diff and description (pr.diff /
- * mr.diff, pr_description.txt / mr_description.txt) but the existing
- * comments file is platform-neutral.
- */
-export type ReviewArtifactNames = {
-  diff: string;
-  comments: string;
-  description: string;
-};
+import type {
+  ReviewArtifactContents,
+  ReviewArtifactNames,
+  ReviewArtifactPaths,
+} from "./types";
 
 /**
  * Write the three review-artifact files into `outDir` in parallel,
diff --git a/src/entrypoints/gitlab-prepare-validator.ts b/src/entrypoints/gitlab-prepare-validator.ts
index 327a7c6..7529e7b 100644
--- a/src/entrypoints/gitlab-prepare-validator.ts
+++ b/src/entrypoints/gitlab-prepare-validator.ts
@@ -78,10 +78,9 @@ async function run(): Promise<void> {
     console.log(
       `Pass 1 candidates validated: ${parsed.comments.length} comments found`,
     );
-  } catch (e: any) {
-    console.error(
-      `Pass 1 candidates JSON is invalid or missing: ${e.message}`,
-    );
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`Pass 1 candidates JSON is invalid or missing: ${message}`);
     console.error(
       "Skipping Pass 2 (validator) to avoid a full pipeline failure",
     );
diff --git a/src/entrypoints/prepare-validator.ts b/src/entrypoints/prepare-validator.ts
index 31d3714..f0aa23b 100644
--- a/src/entrypoints/prepare-validator.ts
+++ b/src/entrypoints/prepare-validator.ts
@@ -34,14 +34,14 @@ async function run() {
         console.log(
           `Pass 1 candidates validated: ${parsed.comments.length} comments found`,
         );
-      } catch (e: any) {
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
         console.error(
-          `Pass 1 candidates JSON is invalid or missing: ${e.message}`,
+          `Pass 1 candidates JSON is invalid or missing: ${message}`,
         );
         console.error(
           "Skipping Pass 2 (validator) to avoid a full pipeline failure",
         );
-        core.setOutput("contains_trigger", "false");
         core.setOutput("validator_should_run", "false");
         core.notice(
           "Pass 1 candidates validation failed - skipping validator pass",