@lnilluv/pi-ralph-loop 0.3.0 → 1.0.0

package/src/ralph.ts

@@ -1,15 +1,25 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { SECRET_PATH_POLICY_TOKEN, filterSecretBearingTopLevelNames, isSecretBearingPath, isSecretBearingTopLevelName } from "./secret-paths.ts";
 
 export type CommandDef = { name: string; run: string; timeout: number };
+export type DraftSource = "deterministic" | "llm-strengthened" | "fallback";
+export type DraftStrengtheningScope = "body-only" | "body-and-commands";
+export type CommandIntent = CommandDef & { source: "heuristic" | "repo-signal" };
+export type RuntimeArg = { name: string; value: string };
+export type RuntimeArgs = Record<string, string>;
 export type Frontmatter = {
   commands: CommandDef[];
+  args?: string[];
   maxIterations: number;
+  interIterationDelay: number;
   timeout: number;
   completionPromise?: string;
+  requiredOutputs?: string[];
   guardrails: { blockCommands: string[]; protectedFiles: string[] };
   invalidCommandEntries?: number[];
+  invalidArgEntries?: number[];
 };
 export type ParsedRalph = { frontmatter: Frontmatter; body: string };
 export type CommandOutput = { name: string; output: string };
@@ -18,9 +28,12 @@ export type RalphTargetResolution = {
   absoluteTarget: string;
   markdownPath: string;
 };
-export type CommandArgs =
-  | { mode: "path" | "task"; value: string }
-  | { mode: "auto"; value: string };
+export type CommandArgs = {
+  mode: "path" | "task" | "auto";
+  value: string;
+  runtimeArgs: RuntimeArg[];
+  error?: string;
+};
 export type ExistingTargetInspection =
   | { kind: "run"; ralphPath: string }
   | { kind: "invalid-markdown"; path: string }
@@ -29,12 +42,20 @@ export type ExistingTargetInspection =
   | { kind: "missing-path"; dirPath: string; ralphPath: string }
   | { kind: "not-path" };
 export type DraftMode = "analysis" | "fix" | "migration" | "general";
-export type DraftMetadata = {
-  generator: "pi-ralph-loop";
-  version: 1;
-  task: string;
-  mode: DraftMode;
-};
+export type DraftMetadata =
+  | {
+      generator: "pi-ralph-loop";
+      version: 1;
+      task: string;
+      mode: DraftMode;
+    }
+  | {
+      generator: "pi-ralph-loop";
+      version: 2;
+      source: DraftSource;
+      task: string;
+      mode: DraftMode;
+    };
 export type DraftTarget = {
   slug: string;
   dirPath: string;
@@ -51,10 +72,29 @@ export type RepoSignals = {
   topLevelDirs: string[];
   topLevelFiles: string[];
 };
+export type RepoContextSelectedFile = {
+  path: string;
+  content: string;
+  reason: string;
+};
+export type RepoContext = {
+  summaryLines: string[];
+  selectedFiles: RepoContextSelectedFile[];
+};
+export type DraftRequest = {
+  task: string;
+  mode: DraftMode;
+  target: DraftTarget;
+  repoSignals: RepoSignals;
+  repoContext: RepoContext;
+  commandIntent: CommandIntent[];
+  baselineDraft: string;
+};
 export type DraftPlan = {
   task: string;
   mode: DraftMode;
   target: DraftTarget;
+  source: DraftSource;
   content: string;
   commandLabels: string[];
   safetyLabel: string;
@@ -67,6 +107,17 @@ function isRecord(value: unknown): value is UnknownRecord {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+const draftModes: DraftMode[] = ["analysis", "fix", "migration", "general"];
+const draftSources: DraftSource[] = ["deterministic", "llm-strengthened", "fallback"];
+
+function isDraftMode(value: unknown): value is DraftMode {
+  return typeof value === "string" && draftModes.includes(value as DraftMode);
+}
+
+function isDraftSource(value: unknown): value is DraftSource {
+  return typeof value === "string" && draftSources.includes(value as DraftSource);
+}
+
 function parseRalphFrontmatter(raw: string): UnknownRecord {
   const parsed: unknown = parseYaml(raw);
   return isRecord(parsed) ? parsed : {};
@@ -89,6 +140,28 @@ function toStringArray(value: unknown): string[] {
   return Array.isArray(value) ? value.map((item) => String(item)) : [];
 }
 
+function parseStringArray(value: unknown): { values: string[]; invalidEntries?: number[] } {
+  if (!Array.isArray(value)) return { values: [] };
+
+  const invalidEntries: number[] = [];
+  const values = value.flatMap((item, index) => {
+    if (typeof item !== "string") {
+      invalidEntries.push(index);
+      return [];
+    }
+    return [item];
+  });
+
+  return { values, invalidEntries: invalidEntries.length > 0 ? invalidEntries : undefined };
+}
+
+function isUniversalProtectedGlob(pattern: string): boolean {
+  const trimmed = pattern.trim().replace(/\/+$/, "");
+  if (!trimmed) return true;
+  if (/^\*+$/.test(trimmed)) return true;
+  return /^(?:\*\*?\/)+\*\*?$/.test(trimmed);
+}
+
 function normalizeRawRalph(raw: string): string {
   return raw.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
 }
@@ -97,8 +170,159 @@ function matchRalphMarkdown(raw: string): RegExpMatchArray | null {
   return normalizeRawRalph(raw).match(/^(?:\s*<!--[\s\S]*?-->\s*)*---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
 }
 
-function hasRalphFrontmatter(raw: string): boolean {
-  return matchRalphMarkdown(raw) !== null;
+
+function validateRawGuardrailsShape(rawFrontmatter: UnknownRecord): string | null {
+  if (!Object.prototype.hasOwnProperty.call(rawFrontmatter, "guardrails")) {
+    return null;
+  }
+
+  const guardrails = rawFrontmatter.guardrails;
+  if (!isRecord(guardrails)) {
+    return "Invalid RALPH frontmatter: guardrails must be a YAML mapping";
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(guardrails, "block_commands") &&
+    !Array.isArray(guardrails.block_commands)
+  ) {
+    return "Invalid RALPH frontmatter: guardrails.block_commands must be a YAML sequence";
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(guardrails, "protected_files") &&
+    !Array.isArray(guardrails.protected_files)
+  ) {
+    return "Invalid RALPH frontmatter: guardrails.protected_files must be a YAML sequence";
+  }
+  return null;
+}
+
+function validateRawRequiredOutputsShape(rawFrontmatter: UnknownRecord): string | null {
+  if (!Object.prototype.hasOwnProperty.call(rawFrontmatter, "required_outputs")) {
+    return null;
+  }
+
+  const requiredOutputs = rawFrontmatter.required_outputs;
+  if (!Array.isArray(requiredOutputs)) {
+    return "Invalid RALPH frontmatter: required_outputs must be a YAML sequence";
+  }
+  for (const [index, output] of requiredOutputs.entries()) {
+    if (typeof output !== "string") {
+      return `Invalid RALPH frontmatter: required_outputs[${index}] must be a YAML string`;
+    }
+  }
+  return null;
+}
+
+function validateRawArgsShape(rawFrontmatter: UnknownRecord): string | null {
+  if (!Object.prototype.hasOwnProperty.call(rawFrontmatter, "args")) {
+    return null;
+  }
+
+  const args = rawFrontmatter.args;
+  if (!Array.isArray(args)) {
+    return "Invalid RALPH frontmatter: args must be a YAML sequence";
+  }
+  for (const [index, arg] of args.entries()) {
+    if (typeof arg !== "string") {
+      return `Invalid RALPH frontmatter: args[${index}] must be a YAML string`;
+    }
+  }
+  return null;
+}
+
+function validateRawCommandEntryShape(command: unknown, index: number): string | null {
+  if (!isRecord(command)) {
+    return `Invalid RALPH frontmatter: commands[${index}] must be a YAML mapping`;
+  }
+  if (Object.prototype.hasOwnProperty.call(command, "name") && typeof command.name !== "string") {
+    return `Invalid RALPH frontmatter: commands[${index}].name must be a YAML string`;
+  }
+  if (Object.prototype.hasOwnProperty.call(command, "run") && typeof command.run !== "string") {
+    return `Invalid RALPH frontmatter: commands[${index}].run must be a YAML string`;
+  }
+  if (Object.prototype.hasOwnProperty.call(command, "timeout") && typeof command.timeout !== "number") {
+    return `Invalid RALPH frontmatter: commands[${index}].timeout must be a YAML number`;
+  }
+  return null;
+}
+
+function validateRawFrontmatterShape(rawFrontmatter: UnknownRecord): string | null {
+  if (Object.prototype.hasOwnProperty.call(rawFrontmatter, "commands")) {
+    const commands = rawFrontmatter.commands;
+    if (!Array.isArray(commands)) {
+      return "Invalid RALPH frontmatter: commands must be a YAML sequence";
+    }
+    for (const [index, command] of commands.entries()) {
+      const commandError = validateRawCommandEntryShape(command, index);
+      if (commandError) return commandError;
+    }
+  }
+
+  if (
+    Object.prototype.hasOwnProperty.call(rawFrontmatter, "required_outputs")
+  ) {
+    const requiredOutputsError = validateRawRequiredOutputsShape(rawFrontmatter);
+    if (requiredOutputsError) {
+      return requiredOutputsError;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(rawFrontmatter, "args")) {
+    const argsError = validateRawArgsShape(rawFrontmatter);
+    if (argsError) {
+      return argsError;
+    }
+  }
+
+  if (
+    Object.prototype.hasOwnProperty.call(rawFrontmatter, "max_iterations") &&
+    (typeof rawFrontmatter.max_iterations !== "number" || !Number.isFinite(rawFrontmatter.max_iterations))
+  ) {
+    return "Invalid RALPH frontmatter: max_iterations must be a YAML number";
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(rawFrontmatter, "inter_iteration_delay") &&
+    (typeof rawFrontmatter.inter_iteration_delay !== "number" || !Number.isFinite(rawFrontmatter.inter_iteration_delay))
+  ) {
+    return "Invalid RALPH frontmatter: inter_iteration_delay must be a YAML number";
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(rawFrontmatter, "timeout") &&
+    (typeof rawFrontmatter.timeout !== "number" || !Number.isFinite(rawFrontmatter.timeout))
+  ) {
+    return "Invalid RALPH frontmatter: timeout must be a YAML number";
+  }
+
+  return null;
+}
+
+function parseStrictRalphMarkdown(raw: string): { parsed: ParsedRalph; rawFrontmatter: UnknownRecord } | { error: string } {
+  const normalized = normalizeRawRalph(raw);
+  const match = matchRalphMarkdown(normalized);
+  if (!match) return { error: "Missing RALPH frontmatter" };
+
+  let parsedYaml: unknown;
+  try {
+    parsedYaml = parseYaml(match[1]);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: `Invalid RALPH frontmatter: ${message}` };
+  }
+
+  if (!isRecord(parsedYaml)) {
+    return { error: "Invalid RALPH frontmatter: Frontmatter must be a YAML mapping" };
+  }
+
+  const guardrailsError = validateRawGuardrailsShape(parsedYaml);
+  if (guardrailsError) {
+    return { error: guardrailsError };
+  }
+
+  const rawShapeError = validateRawFrontmatterShape(parsedYaml);
+  if (rawShapeError) {
+    return { error: rawShapeError };
+  }
+
+  return { parsed: parseRalphMarkdown(normalized), rawFrontmatter: parsedYaml };
 }
 
 function normalizeMissingMarkdownTarget(absoluteTarget: string): { dirPath: string; ralphPath: string } {
@@ -117,7 +341,7 @@ function summarizeSafetyLabel(guardrails: Frontmatter["guardrails"]): string {
   } else if (guardrails.blockCommands.length > 0) {
     labels.push(`blocks ${guardrails.blockCommands.length} command pattern${guardrails.blockCommands.length === 1 ? "" : "s"}`);
   }
-  if (guardrails.protectedFiles.some((pattern) => pattern.includes(".env") || pattern.includes("secret"))) {
+  if (guardrails.protectedFiles.some((pattern) => pattern === SECRET_PATH_POLICY_TOKEN || isSecretBearingPath(pattern))) {
     labels.push("blocks write/edit to secret files");
   } else if (guardrails.protectedFiles.length > 0) {
     labels.push(`blocks write/edit to ${guardrails.protectedFiles.length} file glob${guardrails.protectedFiles.length === 1 ? "" : "s"}`);
@@ -125,8 +349,55 @@ function summarizeSafetyLabel(guardrails: Frontmatter["guardrails"]): string {
   return labels.length > 0 ? labels.join(" and ") : "No extra safety rules";
 }
 
-function summarizeFinishLabel(maxIterations: number): string {
-  return `Stop after ${maxIterations} iterations or /ralph-stop`;
+function summarizeFinishLabel(frontmatter: Frontmatter): string {
+  const requiredOutputs = frontmatter.requiredOutputs ?? [];
+  const labels = [`Stop after ${frontmatter.maxIterations} iterations or /ralph-stop`];
+  if (requiredOutputs.length > 0) {
+    labels.push(`required outputs: ${requiredOutputs.join(", ")}`);
+  }
+  return labels.join("; ");
+}
+
+function summarizeFinishBehavior(frontmatter: Frontmatter): string[] {
+  const requiredOutputs = frontmatter.requiredOutputs ?? [];
+  const lines = [
+    `- Stop after ${frontmatter.maxIterations} iterations or /ralph-stop`,
+    `- Stop if an iteration exceeds ${frontmatter.timeout}s`,
+  ];
+
+  if (frontmatter.completionPromise) {
+    if (requiredOutputs.length > 0) {
+      lines.push(`- Required outputs must exist before stopping: ${requiredOutputs.join(", ")}`);
+    }
+    lines.push("- OPEN_QUESTIONS.md must have no remaining P0/P1 items before stopping.");
+    lines.push(`- Stop early on <promise>${frontmatter.completionPromise}</promise>`);
+  }
+
+  return lines;
+}
+
+function isSafeCompletionPromise(value: string): boolean {
+  return !/[\r\n<>]/.test(value);
+}
+
+function validateRequiredOutputEntry(value: string): string | null {
+  const trimmed = value.trim();
+  if (
+    !trimmed ||
+    trimmed !== value ||
+    /[\u0000-\u001f\u007f]/.test(value) ||
+    trimmed === "." ||
+    trimmed === ".." ||
+    trimmed.startsWith("/") ||
+    /^[A-Za-z]:[\\/]/.test(trimmed) ||
+    trimmed.includes("\\") ||
+    trimmed.endsWith("/") ||
+    trimmed.endsWith("\\") ||
+    trimmed.split("/").some((segment) => segment === "." || segment === "..")
+  ) {
+    return `Invalid required_outputs entry: ${value} must be a relative file path`;
+  }
+  return null;
 }
 
 function isRalphMarkdownPath(path: string): boolean {
@@ -212,7 +483,7 @@ function escapeHtmlCommentMarkers(text: string): string {
 }
 
 export function defaultFrontmatter(): Frontmatter {
-  return { commands: [], maxIterations: 50, timeout: 300, guardrails: { blockCommands: [], protectedFiles: [] } };
+  return { commands: [], maxIterations: 50, interIterationDelay: 0, timeout: 300, requiredOutputs: [], guardrails: { blockCommands: [], protectedFiles: [] } };
 }
 
 export function parseRalphMarkdown(raw: string): ParsedRalph {
@@ -230,20 +501,25 @@ export function parseRalphMarkdown(raw: string): ParsedRalph {
     }
     return [parsed];
   });
+  const parsedArgs = parseStringArray(yaml.args);
   const guardrails = isRecord(yaml.guardrails) ? yaml.guardrails : {};
 
   return {
     frontmatter: {
       commands,
+      ...(parsedArgs.values.length > 0 ? { args: parsedArgs.values } : {}),
       maxIterations: Number(yaml.max_iterations ?? 50),
+      interIterationDelay: Number(yaml.inter_iteration_delay ?? 0),
       timeout: Number(yaml.timeout ?? 300),
       completionPromise:
         typeof yaml.completion_promise === "string" && yaml.completion_promise.trim() ? yaml.completion_promise : undefined,
+      requiredOutputs: toStringArray(yaml.required_outputs),
       guardrails: {
         blockCommands: toStringArray(guardrails.block_commands),
         protectedFiles: toStringArray(guardrails.protected_files),
       },
       invalidCommandEntries: invalidCommandEntries.length > 0 ? invalidCommandEntries : undefined,
+      ...(parsedArgs.invalidEntries ? { invalidArgEntries: parsedArgs.invalidEntries } : {}),
     },
     body: match[2] ?? "",
   };
@@ -253,11 +529,40 @@ export function validateFrontmatter(fm: Frontmatter): string | null {
   if ((fm.invalidCommandEntries?.length ?? 0) > 0) {
     return `Invalid command entry at index ${fm.invalidCommandEntries![0]}`;
   }
-  if (!Number.isFinite(fm.maxIterations) || !Number.isInteger(fm.maxIterations) || fm.maxIterations <= 0) {
-    return "Invalid max_iterations: must be a positive finite integer";
+  if ((fm.invalidArgEntries?.length ?? 0) > 0) {
+    return `Invalid args entry at index ${fm.invalidArgEntries![0]}`;
+  }
+  if (!Number.isFinite(fm.maxIterations) || !Number.isInteger(fm.maxIterations) || fm.maxIterations < 1 || fm.maxIterations > 50) {
+    return "Invalid max_iterations: must be between 1 and 50";
+  }
+  if (!Number.isFinite(fm.interIterationDelay) || !Number.isInteger(fm.interIterationDelay) || fm.interIterationDelay < 0) {
+    return "Invalid inter_iteration_delay: must be a non-negative integer";
   }
-  if (!Number.isFinite(fm.timeout) || fm.timeout <= 0) {
-    return "Invalid timeout: must be a positive finite number";
+  if (!Number.isFinite(fm.timeout) || fm.timeout <= 0 || fm.timeout > 300) {
+    return "Invalid timeout: must be greater than 0 and at most 300";
+  }
+  if (fm.completionPromise !== undefined && !isSafeCompletionPromise(fm.completionPromise)) {
+    return "Invalid completion_promise: must be a single-line string without line breaks or angle brackets";
+  }
+  const args = fm.args ?? [];
+  const seenArgNames = new Set<string>();
+  for (const arg of args) {
+    if (!arg.trim()) {
+      return "Invalid arg: name is required";
+    }
+    if (!/^\w[\w-]*$/.test(arg)) {
+      return `Invalid arg name: ${arg} must match ^\\w[\\w-]*$`;
+    }
+    if (seenArgNames.has(arg)) {
+      return "Invalid args: names must be unique";
+    }
+    seenArgNames.add(arg);
+  }
+  for (const output of fm.requiredOutputs ?? []) {
+    const requiredOutputError = validateRequiredOutputEntry(output);
+    if (requiredOutputError) {
+      return requiredOutputError;
+    }
   }
   for (const pattern of fm.guardrails.blockCommands) {
     try {
@@ -266,20 +571,118 @@ export function validateFrontmatter(fm: Frontmatter): string | null {
       return `Invalid block_commands regex: ${pattern}`;
     }
   }
+  for (const pattern of fm.guardrails.protectedFiles) {
+    if (isUniversalProtectedGlob(pattern)) {
+      return `Invalid protected_files glob: ${pattern}`;
+    }
+  }
   for (const cmd of fm.commands) {
     if (!cmd.name.trim()) {
       return "Invalid command: name is required";
     }
+    if (!/^\w[\w-]*$/.test(cmd.name)) {
+      return `Invalid command name: ${cmd.name} must match ^\\w[\\w-]*$`;
+    }
     if (!cmd.run.trim()) {
       return `Invalid command ${cmd.name}: run is required`;
     }
-    if (!Number.isFinite(cmd.timeout) || cmd.timeout <= 0) {
-      return `Invalid command ${cmd.name}: timeout must be positive`;
+    if (!Number.isFinite(cmd.timeout) || cmd.timeout <= 0 || cmd.timeout > 300) {
+      return `Invalid command ${cmd.name}: timeout must be greater than 0 and at most 300`;
+    }
+    if (cmd.timeout > fm.timeout) {
+      return `Invalid command ${cmd.name}: timeout must not exceed top-level timeout`;
     }
   }
   return null;
 }
 
+function parseCompletionPromiseValue(yaml: UnknownRecord): { present: boolean; value?: string; invalid: boolean } {
+  if (!Object.prototype.hasOwnProperty.call(yaml, "completion_promise")) {
+    return { present: false, invalid: false };
+  }
+  const value = yaml.completion_promise;
+  if (typeof value !== "string" || !value.trim() || !isSafeCompletionPromise(value)) {
+    return { present: true, invalid: true };
+  }
+  return { present: true, value, invalid: false };
+}
+
+export function acceptStrengthenedDraft(request: DraftRequest, strengthenedDraft: string): DraftPlan | null {
+  const baseline = parseStrictRalphMarkdown(request.baselineDraft);
+  const strengthened = parseStrictRalphMarkdown(strengthenedDraft);
+  if ("error" in baseline || "error" in strengthened) {
+    return null;
+  }
+
+  const validationError = validateFrontmatter(strengthened.parsed.frontmatter);
+  if (validationError) {
+    return null;
+  }
+
+  const baselineRequiredOutputs = baseline.parsed.frontmatter.requiredOutputs ?? [];
+  const strengthenedRequiredOutputs = strengthened.parsed.frontmatter.requiredOutputs ?? [];
+  if (baselineRequiredOutputs.join("\n") !== strengthenedRequiredOutputs.join("\n")) {
+    return null;
+  }
+
+  const baselineArgs = baseline.parsed.frontmatter.args ?? [];
+  const strengthenedArgs = strengthened.parsed.frontmatter.args ?? [];
+  if (baselineArgs.join("\n") !== strengthenedArgs.join("\n")) {
+    return null;
+  }
+
+  const baselineCompletion = parseCompletionPromiseValue(baseline.rawFrontmatter);
+  const strengthenedCompletion = parseCompletionPromiseValue(strengthened.rawFrontmatter);
+  if (baselineCompletion.invalid || strengthenedCompletion.invalid) {
+    return null;
+  }
+  if (baselineCompletion.present !== strengthenedCompletion.present || baselineCompletion.value !== strengthenedCompletion.value) {
+    return null;
+  }
+
+  if (baseline.parsed.frontmatter.maxIterations < strengthened.parsed.frontmatter.maxIterations) {
+    return null;
+  }
+  if (baseline.parsed.frontmatter.timeout < strengthened.parsed.frontmatter.timeout) {
+    return null;
+  }
+  if (
+    baseline.parsed.frontmatter.guardrails.blockCommands.join("\n") !== strengthened.parsed.frontmatter.guardrails.blockCommands.join("\n") ||
+    baseline.parsed.frontmatter.guardrails.protectedFiles.join("\n") !== strengthened.parsed.frontmatter.guardrails.protectedFiles.join("\n")
+  ) {
+    return null;
+  }
+
+  const baselineCommands = new Map(baseline.parsed.frontmatter.commands.map((command) => [command.name, command]));
+  const seenCommands = new Set<string>();
+  for (const command of strengthened.parsed.frontmatter.commands) {
+    if (seenCommands.has(command.name)) {
+      return null;
+    }
+    seenCommands.add(command.name);
+
+    const baselineCommand = baselineCommands.get(command.name);
+    if (!baselineCommand || baselineCommand.run !== command.run) {
+      return null;
+    }
+    if (command.timeout > baselineCommand.timeout || command.timeout > strengthened.parsed.frontmatter.timeout) {
+      return null;
+    }
+  }
+
+  for (const placeholder of strengthened.parsed.body.matchAll(/\{\{\s*commands\.(\w[\w-]*)\s*\}\}/g)) {
+    if (!seenCommands.has(placeholder[1])) {
+      return null;
+    }
+  }
+
+  if (collectArgPlaceholderNames(strengthened.parsed.body).length > 0) {
+    return null;
+  }
+
+  return renderDraftPlan(request.task, request.mode, request.target, strengthened.parsed.frontmatter, "llm-strengthened", strengthened.parsed.body);
+}
+
 export function findBlockedCommandPattern(command: string, blockPatterns: string[]): string | undefined {
   for (const pattern of blockPatterns) {
     try {
@@ -291,13 +694,231 @@ export function findBlockedCommandPattern(command: string, blockPatterns: string
   return undefined;
 }
 
+function hasRuntimeArgToken(text: string): boolean {
+  return /(?:^|\s)--arg(?:\s|=)/.test(text);
+}
+
+function parseRuntimeArgEntry(token: string): { entry?: RuntimeArg; error?: string } {
+  const equalsIndex = token.indexOf("=");
+  if (equalsIndex < 0) {
+    return { error: "Invalid --arg entry: name=value is required" };
+  }
+
+  const name = token.slice(0, equalsIndex).trim();
+  const value = token.slice(equalsIndex + 1);
+  if (!name) {
+    return { error: "Invalid --arg entry: name is required" };
+  }
+  if (!value) {
+    return { error: "Invalid --arg entry: value is required" };
+  }
+
+  return { entry: { name, value } };
+}
+
+function parseExplicitPathRuntimeArgs(rawTail: string): { runtimeArgs: RuntimeArg[]; error?: string } {
+  const runtimeArgs: RuntimeArg[] = [];
+  const trimmed = rawTail.trim();
+  if (!trimmed) {
+    return { runtimeArgs };
+  }
+
+  const syntaxError = "Invalid --arg syntax: values must be a single token and no trailing text is allowed";
+  let index = 0;
+
+  while (index < trimmed.length) {
+    while (index < trimmed.length && /\s/.test(trimmed[index])) {
+      index += 1;
+    }
+    if (index >= trimmed.length) {
+      break;
+    }
+
+    if (!trimmed.startsWith("--arg", index) || (trimmed[index + 5] !== undefined && !/\s/.test(trimmed[index + 5]))) {
+      return { runtimeArgs, error: syntaxError };
+    }
+    index += 5;
+
+    while (index < trimmed.length && /\s/.test(trimmed[index])) {
+      index += 1;
+    }
+    if (index >= trimmed.length) {
+      return { runtimeArgs, error: "Invalid --arg entry: name=value is required" };
+    }
+
+    const nameStart = index;
+    while (index < trimmed.length && trimmed[index] !== "=" && !/\s/.test(trimmed[index])) {
+      index += 1;
+    }
+
+    const name = trimmed.slice(nameStart, index).trim();
+    if (!name) {
+      return { runtimeArgs, error: "Invalid --arg entry: name is required" };
+    }
+    if (index >= trimmed.length || trimmed[index] !== "=") {
+      return { runtimeArgs, error: "Invalid --arg entry: name=value is required" };
+    }
+    index += 1;
+
+    if (index >= trimmed.length || /\s/.test(trimmed[index])) {
+      return { runtimeArgs, error: "Invalid --arg entry: value is required" };
+    }
+
+    let value = "";
+    const quote = trimmed[index];
+    if (quote === "'" || quote === '"') {
+      index += 1;
+      while (index < trimmed.length && trimmed[index] !== quote) {
+        value += trimmed[index];
+        index += 1;
+      }
+      if (index >= trimmed.length) {
+        return { runtimeArgs, error: syntaxError };
+      }
+      if (index + 1 < trimmed.length && !/\s/.test(trimmed[index + 1])) {
+        return { runtimeArgs, error: syntaxError };
+      }
+      index += 1;
+    } else {
+      while (index < trimmed.length && !/\s/.test(trimmed[index])) {
+        const char = trimmed[index];
+        if (char === "'" || char === '"') {
+          return { runtimeArgs, error: syntaxError };
+        }
+        value += char;
+        index += 1;
+      }
+    }
+
+    const parsed = parseRuntimeArgEntry(`${name}=${value}`);
+    if (parsed.error) {
+      return { runtimeArgs, error: parsed.error };
+    }
+
+    const entry = parsed.entry;
+    if (!entry) {
+      return { runtimeArgs, error: "Invalid --arg entry: name=value is required" };
+    }
+
+    if (runtimeArgs.some((existing) => existing.name === entry.name)) {
+      return { runtimeArgs, error: `Duplicate --arg: ${entry.name}` };
+    }
+
+    runtimeArgs.push(entry);
+
+    while (index < trimmed.length && /\s/.test(trimmed[index])) {
+      index += 1;
+    }
+    if (index < trimmed.length && !trimmed.startsWith("--arg", index)) {
+      return { runtimeArgs, error: syntaxError };
+    }
+  }
+
+  return { runtimeArgs };
+}
+
+function parseExplicitPathCommandArgs(valueWithArgs: string): CommandArgs {
+  const argMatch = valueWithArgs.match(/(?:^|\s)--arg(?:\s|=|[^\s=]*=|$)/);
+  const argIndex = argMatch?.index ?? valueWithArgs.length;
+  const value = argMatch ? valueWithArgs.slice(0, argIndex).trim() : valueWithArgs.trim();
+  const parsedArgs = parseExplicitPathRuntimeArgs(argMatch ? valueWithArgs.slice(argIndex).trim() : "");
+  return { mode: "path", value, runtimeArgs: parsedArgs.runtimeArgs, error: parsedArgs.error ?? undefined };
+}
+
 export function parseCommandArgs(raw: string): CommandArgs {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("--task=")) return { mode: "task", value: trimmed.slice("--task=".length).trim() };
-  if (trimmed.startsWith("--path=")) return { mode: "path", value: trimmed.slice("--path=".length).trim() };
-  if (trimmed.startsWith("--task ")) return { mode: "task", value: trimmed.slice("--task ".length).trim() };
-  if (trimmed.startsWith("--path ")) return { mode: "path", value: trimmed.slice("--path ".length).trim() };
-  return { mode: "auto", value: trimmed };
+  const cleaned = raw.trim();
+
+  if (cleaned.startsWith("--task=")) {
+    const value = cleaned.slice("--task=".length).trim();
+    if (hasRuntimeArgToken(value)) {
+      return { mode: "task", value, runtimeArgs: [], error: "--arg is only supported with /ralph --path" };
+    }
+    return { mode: "task", value, runtimeArgs: [], error: undefined };
+  }
+  if (cleaned.startsWith("--task ")) {
+    const value = cleaned.slice("--task ".length).trim();
+    if (hasRuntimeArgToken(value)) {
+      return { mode: "task", value, runtimeArgs: [], error: "--arg is only supported with /ralph --path" };
+    }
+    return { mode: "task", value, runtimeArgs: [], error: undefined };
+  }
+  if (cleaned.startsWith("--path=")) {
+    return parseExplicitPathCommandArgs(cleaned.slice("--path=".length).trimStart());
+  }
+  if (cleaned.startsWith("--path ")) {
+    return parseExplicitPathCommandArgs(cleaned.slice("--path ".length).trimStart());
+  }
+  return { mode: "auto", value: cleaned, runtimeArgs: [], error: undefined };
+}
+
+export function runtimeArgEntriesToMap(entries: RuntimeArg[]): { runtimeArgs: RuntimeArgs; error?: string } {
+  const runtimeArgs = Object.create(null) as RuntimeArgs;
+  for (const entry of entries) {
+    if (!entry.name.trim()) {
+      return { runtimeArgs, error: "Invalid --arg entry: name is required" };
+    }
+    if (!entry.value.trim()) {
+      return { runtimeArgs, error: "Invalid --arg entry: value is required" };
+    }
+    if (!/^\w[\w-]*$/.test(entry.name)) {
+      return { runtimeArgs, error: `Invalid --arg name: ${entry.name} must match ^\\w[\\w-]*$` };
+    }
+    if (Object.prototype.hasOwnProperty.call(runtimeArgs, entry.name)) {
+      return { runtimeArgs, error: `Duplicate --arg: ${entry.name}` };
+    }
+    runtimeArgs[entry.name] = entry.value;
+  }
+  return { runtimeArgs };
+}
+
+function collectArgPlaceholderNames(source: string): string[] {
+  const names = new Set<string>();
+  for (const match of source.matchAll(/\{\{\s*args\.(\w[\w-]*)\s*\}\}/g)) {
+    names.add(match[1]);
+  }
+  return [...names];
+}
+
+function validateBodyArgsAgainstContract(body: string, declaredArgs: string[] | undefined): string | null {
+  const declaredSet = new Set(declaredArgs ?? []);
+  for (const name of collectArgPlaceholderNames(body)) {
+    if (!declaredSet.has(name)) {
+      return `Undeclared arg placeholder: ${name}`;
+    }
+  }
+  return null;
+}
+
+export function validateRuntimeArgs(frontmatter: Frontmatter, body: string, commands: CommandDef[], runtimeArgs: RuntimeArgs): string | null {
+  const declaredArgs = frontmatter.args ?? [];
+  const declaredSet = new Set(declaredArgs);
+
+  for (const name of Object.keys(runtimeArgs)) {
+    if (!declaredSet.has(name)) {
+      return `Undeclared arg: ${name}`;
+    }
+  }
+
+  for (const name of declaredArgs) {
+    if (!Object.prototype.hasOwnProperty.call(runtimeArgs, name)) {
+      return `Missing required arg: ${name}`;
+    }
+  }
+
+  for (const name of collectArgPlaceholderNames(body)) {
+    if (!declaredSet.has(name)) {
+      return `Undeclared arg placeholder: ${name}`;
+    }
+  }
+  for (const command of commands) {
+    for (const name of collectArgPlaceholderNames(command.run)) {
+      if (!declaredSet.has(name)) {
+        return `Undeclared arg placeholder: ${name}`;
+      }
+    }
+  }
+
+  return null;
 }
 
 export function looksLikePath(value: string): boolean {
@@ -415,8 +1036,9 @@ export function inspectRepo(cwd: string): RepoSignals {
 
   try {
     const entries = readdirSync(cwd, { withFileTypes: true }).slice(0, 50);
-    topLevelDirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).slice(0, 10);
-    topLevelFiles = entries.filter((entry) => entry.isFile()).map((entry) => entry.name).slice(0, 10);
+    const filteredEntries = entries.filter((entry) => !isSecretBearingTopLevelName(entry.name));
+    topLevelDirs = filteredEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).slice(0, 10);
+    topLevelFiles = filteredEntries.filter((entry) => entry.isFile()).map((entry) => entry.name).slice(0, 10);
   } catch {
     // ignore bounded inspection failures
   }
@@ -431,21 +1053,70 @@ export function inspectRepo(cwd: string): RepoSignals {
   };
 }
 
-export function suggestedCommandsForMode(mode: DraftMode, signals: RepoSignals): CommandDef[] {
+export function buildRepoContext(signals: RepoSignals): RepoContext {
+  const topLevelDirs = filterSecretBearingTopLevelNames(signals.topLevelDirs);
+  const topLevelFiles = filterSecretBearingTopLevelNames(signals.topLevelFiles);
+
+  return {
+    summaryLines: [
+      `package manager: ${signals.packageManager ?? "unknown"}`,
+      `test command: ${signals.testCommand ?? "none"}`,
+      `lint command: ${signals.lintCommand ?? "none"}`,
+      `git repository: ${signals.hasGit ? "present" : "absent"}`,
+      `top-level dirs: ${topLevelDirs.length > 0 ? topLevelDirs.join(", ") : "none"}`,
+      `top-level files: ${topLevelFiles.length > 0 ? topLevelFiles.join(", ") : "none"}`,
+    ],
+    selectedFiles: topLevelFiles.slice(0, 10).map((path) => ({
+      path,
+      content: "",
+      reason: "top-level file",
+    })),
+  };
+}
+
+function normalizeSelectedFile(file: unknown): RepoContextSelectedFile {
+  if (isRecord(file)) {
+    return {
+      path: String(file.path ?? ""),
+      content: String(file.content ?? ""),
+      reason: String(file.reason ?? "selected file"),
+    };
+  }
+  if (typeof file === "string") {
+    return { path: file, content: "", reason: "selected file" };
+  }
+  return { path: String(file), content: "", reason: "selected file" };
+}
+
+function normalizeRepoContext(repoContext: RepoContext | undefined, signals: RepoSignals): RepoContext {
+  if (repoContext && Array.isArray(repoContext.summaryLines) && Array.isArray(repoContext.selectedFiles)) {
+    return {
+      summaryLines: repoContext.summaryLines.map((line) => String(line)),
+      selectedFiles: repoContext.selectedFiles.map((file) => normalizeSelectedFile(file)),
+    };
+  }
+  return buildRepoContext(signals);
+}
+
+export function buildCommandIntent(mode: DraftMode, signals: RepoSignals): CommandIntent[] {
   if (mode === "analysis") {
-    const commands: CommandDef[] = [{ name: "repo-map", run: "find . -maxdepth 2 -type f | sort | head -n 120", timeout: 20 }];
-    if (signals.hasGit) commands.unshift({ name: "git-log", run: "git log --oneline -10", timeout: 20 });
+    const commands: CommandIntent[] = [{ name: "repo-map", run: "find . -maxdepth 2 -type f | sort | head -n 120", timeout: 20, source: "heuristic" }];
+    if (signals.hasGit) commands.unshift({ name: "git-log", run: "git log --oneline -10", timeout: 20, source: "heuristic" });
     return commands;
   }
 
-  const commands: CommandDef[] = [];
-  if (signals.testCommand) commands.push({ name: "tests", run: signals.testCommand, timeout: 120 });
-  if (signals.lintCommand) commands.push({ name: "lint", run: signals.lintCommand, timeout: 90 });
-  if (signals.hasGit) commands.push({ name: "git-log", run: "git log --oneline -10", timeout: 20 });
-  if (commands.length === 0) commands.push({ name: "repo-map", run: "find . -maxdepth 2 -type f | sort | head -n 120", timeout: 20 });
+  const commands: CommandIntent[] = [];
+  if (signals.testCommand) commands.push({ name: "tests", run: signals.testCommand, timeout: 120, source: "repo-signal" });
+  if (signals.lintCommand) commands.push({ name: "lint", run: signals.lintCommand, timeout: 90, source: "repo-signal" });
+  if (signals.hasGit) commands.push({ name: "git-log", run: "git log --oneline -10", timeout: 20, source: "heuristic" });
+  if (commands.length === 0) commands.push({ name: "repo-map", run: "find . -maxdepth 2 -type f | sort | head -n 120", timeout: 20, source: "heuristic" });
   return commands;
 }
 
+export function suggestedCommandsForMode(mode: DraftMode, signals: RepoSignals): CommandDef[] {
+  return buildCommandIntent(mode, signals).map(({ source: _source, ...command }) => command);
+}
+
 function formatCommandLabel(command: CommandDef): string {
   return `${command.name}: ${command.run}`;
 }
@@ -455,68 +1126,157 @@ function extractVisibleTask(body: string): string | undefined {
   return match?.[1]?.trim() || undefined;
 }
 
-export function generateDraft(task: string, target: DraftTarget, signals: RepoSignals): DraftPlan {
-  const mode = classifyTaskMode(task);
-  const commands = suggestedCommandsForMode(mode, signals);
-  const metadata: DraftMetadata = { generator: "pi-ralph-loop", version: 1, task, mode };
+function buildDraftFrontmatter(mode: DraftMode, commands: CommandDef[]): Frontmatter {
   const guardrails = {
     blockCommands: ["git\\s+push"],
-    protectedFiles: mode === "analysis" ? [] : [".env*", "**/secrets/**"],
+    protectedFiles: mode === "analysis" ? [] : [SECRET_PATH_POLICY_TOKEN],
+  };
+  return {
+    commands,
+    maxIterations: mode === "analysis" ? 12 : mode === "migration" ? 30 : 25,
+    interIterationDelay: 0,
+    timeout: 300,
+    requiredOutputs: [],
+    guardrails,
   };
-  const maxIterations = mode === "analysis" ? 12 : mode === "migration" ? 30 : 25;
+}
+
+function renderDraftBody(task: string, mode: DraftMode, commands: CommandDef[]): string {
+  const commandSections = commands.map((command) => bodySection(command.name === "git-log" ? "Recent git history" : `Latest ${command.name} output`, `{{ commands.${command.name} }}`));
+  return mode === "analysis"
+    ? [
+        `Task: ${escapeHtmlCommentMarkers(task)}`,
+        "",
+        ...commandSections,
+        "",
+        "Start with read-only inspection. Avoid edits and commits until you have a clear plan.",
+        "Map the architecture, identify entry points, and summarize the important moving parts.",
+        "End each iteration with concrete findings, open questions, and the next files to inspect.",
+        "Iteration {{ ralph.iteration }} of {{ ralph.name }}.",
+      ].join("\n")
+    : [
+        `Task: ${escapeHtmlCommentMarkers(task)}`,
+        "",
+        ...commandSections,
+        "",
+        mode === "fix" ? "If tests or lint are failing, fix those failures before starting new work." : "Make the smallest safe change that moves the task forward.",
+        "Prefer concrete, verifiable progress. Explain why your change works.",
+        "Iteration {{ ralph.iteration }} of {{ ralph.name }}.",
+      ].join("\n");
+}
+
+function commandIntentsToCommands(commandIntents: CommandIntent[]): CommandDef[] {
+  return commandIntents.map(({ source: _source, ...command }) => command);
+}
+
+function renderDraftPlan(task: string, mode: DraftMode, target: DraftTarget, frontmatter: Frontmatter, source: DraftSource, body: string): DraftPlan {
+  const metadata: DraftMetadata = { generator: "pi-ralph-loop", version: 2, source, task, mode };
+  const requiredOutputs = frontmatter.requiredOutputs ?? [];
   const frontmatterLines = [
-    ...renderCommandsYaml(commands),
-    `max_iterations: ${maxIterations}`,
-    "timeout: 300",
+    ...renderCommandsYaml(frontmatter.commands),
+    `max_iterations: ${frontmatter.maxIterations}`,
+    `inter_iteration_delay: ${frontmatter.interIterationDelay}`,
+    `timeout: ${frontmatter.timeout}`,
+    ...(requiredOutputs.length > 0
+      ? ["required_outputs:", ...requiredOutputs.map((output) => `  - ${yamlQuote(output)}`)]
+      : []),
+    ...(frontmatter.completionPromise ? [`completion_promise: ${yamlQuote(frontmatter.completionPromise)}`] : []),
     "guardrails:",
-    "  block_commands:",
-    ...guardrails.blockCommands.map((pattern) => `    - ${yamlQuote(pattern)}`),
-    "  protected_files:",
-    ...guardrails.protectedFiles.map((pattern) => `    - ${yamlQuote(pattern)}`),
+    ...(frontmatter.guardrails.blockCommands.length > 0
+      ? ["  block_commands:", ...frontmatter.guardrails.blockCommands.map((pattern) => `    - ${yamlQuote(pattern)}`)]
+      : ["  block_commands: []"]),
+    ...(frontmatter.guardrails.protectedFiles.length > 0
+      ? ["  protected_files:", ...frontmatter.guardrails.protectedFiles.map((pattern) => `    - ${yamlQuote(pattern)}`)]
+      : ["  protected_files: []"]),
   ];
 
-  const commandSections = commands.map((command) => bodySection(command.name === "git-log" ? "Recent git history" : `Latest ${command.name} output`, `{{ commands.${command.name} }}`));
-  const body =
-    mode === "analysis"
-      ? [
-          `Task: ${escapeHtmlCommentMarkers(task)}`,
-          "",
-          ...commandSections,
-          "",
-          "Start with read-only inspection. Avoid edits and commits until you have a clear plan.",
-          "Map the architecture, identify entry points, and summarize the important moving parts.",
-          "End each iteration with concrete findings, open questions, and the next files to inspect.",
-          "Iteration {{ ralph.iteration }} of {{ ralph.name }}.",
-        ].join("\n")
-      : [
-          `Task: ${escapeHtmlCommentMarkers(task)}`,
-          "",
-          ...commandSections,
-          "",
-          mode === "fix"
-            ? "If tests or lint are failing, fix those failures before starting new work."
-            : "Make the smallest safe change that moves the task forward.",
-          "Prefer concrete, verifiable progress. Explain why your change works.",
-          "Iteration {{ ralph.iteration }} of {{ ralph.name }}.",
-        ].join("\n");
-
   return {
     task,
     mode,
     target,
+    source,
     content: `${metadataComment(metadata)}\n${yamlBlock(frontmatterLines)}\n\n${body}`,
-    commandLabels: commands.map(formatCommandLabel),
-    safetyLabel: summarizeSafetyLabel(guardrails),
-    finishLabel: summarizeFinishLabel(maxIterations),
+    commandLabels: frontmatter.commands.map(formatCommandLabel),
+    safetyLabel: summarizeSafetyLabel(frontmatter.guardrails),
+    finishLabel: summarizeFinishLabel(frontmatter),
+  };
+}
+
+export function generateDraftFromRequest(request: Omit<DraftRequest, "baselineDraft">, source: DraftSource): DraftPlan {
+  const commands = commandIntentsToCommands(request.commandIntent);
+  const frontmatter = buildDraftFrontmatter(request.mode, commands);
+  return renderDraftPlan(request.task, request.mode, request.target, frontmatter, source, renderDraftBody(request.task, request.mode, commands));
+}
+
+export function buildDraftRequest(task: string, target: DraftTarget, repoSignals: RepoSignals, repoContext?: RepoContext): DraftRequest {
+  const mode = classifyTaskMode(task);
+  const commandIntents = buildCommandIntent(mode, repoSignals);
+  const request: Omit<DraftRequest, "baselineDraft"> = {
+    task,
+    mode,
+    target,
+    repoSignals,
+    repoContext: normalizeRepoContext(repoContext, repoSignals),
+    commandIntent: commandIntents,
   };
+  return { ...request, baselineDraft: generateDraftFromRequest(request, "deterministic").content };
+}
+
+export function normalizeStrengthenedDraft(request: DraftRequest, strengthenedDraft: string, scope: DraftStrengtheningScope): DraftPlan {
+  const baseline = parseRalphMarkdown(request.baselineDraft);
+  const strengthened = parseStrictRalphMarkdown(strengthenedDraft);
+
+  if (scope === "body-only") {
+    if (
+      "error" in strengthened ||
+      validateFrontmatter(strengthened.parsed.frontmatter) ||
+      validateBodyArgsAgainstContract(strengthened.parsed.body, baseline.frontmatter.args)
+    ) {
+      return renderDraftPlan(request.task, request.mode, request.target, baseline.frontmatter, "llm-strengthened", baseline.body);
+    }
+
+    return renderDraftPlan(request.task, request.mode, request.target, baseline.frontmatter, "llm-strengthened", strengthened.parsed.body);
+  }
+
+  const accepted = acceptStrengthenedDraft(request, strengthenedDraft);
+  if (accepted) {
+    return accepted;
+  }
+
+  return renderDraftPlan(request.task, request.mode, request.target, baseline.frontmatter, "llm-strengthened", baseline.body);
+}
+
+export function hasFakeRuntimeEnforcementClaim(text: string): boolean {
+  return /read[-\s]?only enforced|write protection is enforced/i.test(text);
+}
+
+export function isWeakStrengthenedDraft(baselineBody: string, analysisText: string, strengthenedBody: string): boolean {
+  return baselineBody.trim() === strengthenedBody.trim() || hasFakeRuntimeEnforcementClaim(analysisText) || hasFakeRuntimeEnforcementClaim(strengthenedBody);
+}
+
+export function generateDraft(task: string, target: DraftTarget, signals: RepoSignals): DraftPlan {
+  const request = buildDraftRequest(task, target, signals);
+  return generateDraftFromRequest(request, "deterministic");
 }
 
 export function extractDraftMetadata(raw: string): DraftMetadata | undefined {
   const match = raw.match(/^<!-- pi-ralph-loop: (.+?) -->/);
   if (!match) return undefined;
+
   try {
-    const parsed = JSON.parse(decodeDraftMetadata(match[1])) as DraftMetadata;
-    return parsed?.generator === "pi-ralph-loop" ? parsed : undefined;
+    const parsed: unknown = JSON.parse(decodeDraftMetadata(match[1]));
+    if (!isRecord(parsed) || parsed.generator !== "pi-ralph-loop") return undefined;
+    if (!isDraftMode(parsed.mode) || typeof parsed.task !== "string") return undefined;
+
+    if (parsed.version === 1) {
+      return { generator: "pi-ralph-loop", version: 1, task: parsed.task, mode: parsed.mode };
+    }
+
+    if (parsed.version === 2 && isDraftSource(parsed.source)) {
+      return { generator: "pi-ralph-loop", version: 2, source: parsed.source, task: parsed.task, mode: parsed.mode };
+    }
+
+    return undefined;
   } catch {
     return undefined;
   }
@@ -534,20 +1294,19 @@ export type DraftContentInspection = {
 
 export function inspectDraftContent(raw: string): DraftContentInspection {
   const metadata = extractDraftMetadata(raw);
-  const normalized = normalizeRawRalph(raw);
+  const parsed = parseStrictRalphMarkdown(raw);
 
-  if (!hasRalphFrontmatter(normalized)) {
-    return { metadata, error: "Missing RALPH frontmatter" };
+  if ("error" in parsed) {
+    return { metadata, error: parsed.error };
   }
 
-  try {
-    const parsed = parseRalphMarkdown(normalized);
-    const error = validateFrontmatter(parsed.frontmatter);
-    return error ? { metadata, parsed, error } : { metadata, parsed };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { metadata, error: `Invalid RALPH frontmatter: ${message}` };
+  const rawCompletionPromise = parseCompletionPromiseValue(parsed.rawFrontmatter);
+  if (rawCompletionPromise.invalid) {
+    return { metadata, parsed: parsed.parsed, error: "Invalid completion_promise: must be a single-line string without line breaks or angle brackets" };
   }
+
+  const error = validateFrontmatter(parsed.parsed.frontmatter);
+  return error ? { metadata, parsed: parsed.parsed, error } : { metadata, parsed: parsed.parsed };
 }
 
 export function validateDraftContent(raw: string): string | null {
@@ -576,9 +1335,8 @@ export function buildMissionBrief(plan: DraftPlan): string {
   }
 
   const parsed = inspection.parsed!;
-  const mode = inspection.metadata?.mode ?? "general";
   const commandLabels = parsed.frontmatter.commands.map(formatCommandLabel);
-  const finishLabel = summarizeFinishLabel(parsed.frontmatter.maxIterations);
+  const finishBehavior = summarizeFinishBehavior(parsed.frontmatter);
   const safetyLabel = summarizeSafetyLabel(parsed.frontmatter.guardrails);
 
   return [
@@ -595,7 +1353,7 @@ export function buildMissionBrief(plan: DraftPlan): string {
     ...commandLabels.map((label) => `- ${label}`),
     "",
     "Finish behavior",
-    `- ${finishLabel}`,
+    ...finishBehavior,
     "",
     "Safety",
     `- ${safetyLabel}`,
@@ -611,20 +1369,77 @@ export function shouldStopForCompletionPromise(text: string, expected: string):
   return extractCompletionPromise(text) === expected.trim();
 }
 
-export function resolvePlaceholders(body: string, outputs: CommandOutput[], ralph: { iteration: number; name: string }): string {
+function shellQuote(value: string): string {
+  return "'" + value.split("'").join("'\\''") + "'";
+}
+
+export function replaceArgsPlaceholders(text: string, runtimeArgs: RuntimeArgs, shellSafe = false): string {
+  return text.replace(/\{\{\s*args\.(\w[\w-]*)\s*\}\}/g, (_, name) => {
+    if (!Object.prototype.hasOwnProperty.call(runtimeArgs, name)) {
+      throw new Error(`Missing required arg: ${name}`);
+    }
+    const value = runtimeArgs[name];
+    return shellSafe ? shellQuote(value) : value;
+  });
+}
+
+export function resolvePlaceholders(
+  body: string,
+  outputs: CommandOutput[],
+  ralph: { iteration: number; name: string; maxIterations: number },
+  runtimeArgs: RuntimeArgs = {},
+): string {
   const map = new Map(outputs.map((o) => [o.name, o.output]));
-  return body
-    .replace(/\{\{\s*commands\.(\w[\w-]*)\s*\}\}/g, (_, name) => map.get(name) ?? "")
-    .replace(/\{\{\s*ralph\.iteration\s*\}\}/g, String(ralph.iteration))
-    .replace(/\{\{\s*ralph\.name\s*\}\}/g, ralph.name);
+  const resolved = replaceArgsPlaceholders(
+    body
+      .replace(/\{\{\s*ralph\.iteration\s*\}\}/g, String(ralph.iteration))
+      .replace(/\{\{\s*ralph\.name\s*\}\}/g, ralph.name)
+      .replace(/\{\{\s*ralph\.max_iterations\s*\}\}/g, String(ralph.maxIterations)),
+    runtimeArgs,
+  );
+  return resolved.replace(/\{\{\s*commands\.(\w[\w-]*)\s*\}\}/g, (_, name) => map.get(name) ?? "");
+}
+
+export function resolveCommandRun(run: string, runtimeArgs: RuntimeArgs): string {
+  return replaceArgsPlaceholders(run, runtimeArgs, true);
 }
 
-export function renderRalphBody(body: string, outputs: CommandOutput[], ralph: { iteration: number; name: string }): string {
-  return resolvePlaceholders(body, outputs, ralph).replace(/<!--[\s\S]*?-->/g, "");
+export function renderRalphBody(
+  body: string,
+  outputs: CommandOutput[],
+  ralph: { iteration: number; name: string; maxIterations: number },
+  runtimeArgs: RuntimeArgs = {},
+): string {
+  return resolvePlaceholders(body, outputs, ralph, runtimeArgs).replace(/<!--[\s\S]*?-->/g, "");
 }
 
-export function renderIterationPrompt(body: string, iteration: number, maxIterations: number): string {
-  return `[ralph: iteration ${iteration}/${maxIterations}]\n\n${body}`;
+export function renderIterationPrompt(
+  body: string,
+  iteration: number,
+  maxIterations: number,
+  completionGate?: { completionPromise?: string; requiredOutputs?: string[]; failureReasons?: string[]; rejectionReasons?: string[] },
+): string {
+  if (!completionGate) {
+    return `[ralph: iteration ${iteration}/${maxIterations}]\n\n${body}`;
+  }
+
+  const requiredOutputs = completionGate.requiredOutputs ?? [];
+  const failureReasons = completionGate.failureReasons ?? [];
+  const rejectionReasons = completionGate.rejectionReasons ?? [];
+  const completionPromise = completionGate.completionPromise ?? "DONE";
+  const gateLines = [
+    "[completion gate]",
+    `- Required outputs must exist before stopping${requiredOutputs.length > 0 ? `: ${requiredOutputs.join(", ")}` : "."}`,
+    "- OPEN_QUESTIONS.md must have no remaining P0/P1 items before stopping.",
+    "- Label inferred claims as HYPOTHESIS.",
+    ...(rejectionReasons.length > 0
+      ? ["[completion gate rejection]", `- Still missing: ${rejectionReasons.join("; ")}`]
+      : []),
+    ...(failureReasons.length > 0 ? [`- Previous gate failures: ${failureReasons.join("; ")}`] : []),
+    `- Emit <promise>${completionPromise}</promise> only when the gate is truly satisfied.`,
+  ];
+
+  return `[ralph: iteration ${iteration}/${maxIterations}]\n\n${body}\n\n${gateLines.join("\n")}`;
 }
 
 export function shouldWarnForBashFailure(output: string): boolean {