@lnilluv/pi-ralph-loop 0.1.4-dev.0 → 0.1.4-dev.1

package/src/ralph.ts

@@ -7,13 +7,19 @@ 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 };
@@ -22,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 }
@@ -131,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");
 }
@@ -139,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 } {
@@ -167,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 {
@@ -254,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 {
@@ -272,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] ?? "",
   };
@@ -295,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.timeout) || fm.timeout <= 0) {
-    return "Invalid timeout: must be a positive finite number";
+  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 || 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 {
@@ -308,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 {
@@ -333,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 {
@@ -555,7 +1134,9 @@ function buildDraftFrontmatter(mode: DraftMode, commands: CommandDef[]): Frontma
   return {
     commands,
     maxIterations: mode === "analysis" ? 12 : mode === "migration" ? 30 : 25,
+    interIterationDelay: 0,
     timeout: 300,
+    requiredOutputs: [],
     guardrails,
   };
 }
@@ -590,15 +1171,23 @@ function commandIntentsToCommands(commandIntents: CommandIntent[]): CommandDef[]
 
 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(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:",
-    ...frontmatter.guardrails.blockCommands.map((pattern) => `    - ${yamlQuote(pattern)}`),
-    "  protected_files:",
-    ...frontmatter.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: []"]),
   ];
 
   return {
@@ -609,7 +1198,7 @@ function renderDraftPlan(task: string, mode: DraftMode, target: DraftTarget, fro
     content: `${metadataComment(metadata)}\n${yamlBlock(frontmatterLines)}\n\n${body}`,
     commandLabels: frontmatter.commands.map(formatCommandLabel),
     safetyLabel: summarizeSafetyLabel(frontmatter.guardrails),
-    finishLabel: summarizeFinishLabel(frontmatter.maxIterations),
+    finishLabel: summarizeFinishLabel(frontmatter),
   };
 }
 
@@ -635,16 +1224,29 @@ export function buildDraftRequest(task: string, target: DraftTarget, repoSignals
 
 export function normalizeStrengthenedDraft(request: DraftRequest, strengthenedDraft: string, scope: DraftStrengtheningScope): DraftPlan {
   const baseline = parseRalphMarkdown(request.baselineDraft);
-  const strengthened = parseRalphMarkdown(strengthenedDraft);
+  const strengthened = parseStrictRalphMarkdown(strengthenedDraft);
 
   if (scope === "body-only") {
-    return renderDraftPlan(request.task, request.mode, request.target, baseline.frontmatter, "llm-strengthened", strengthened.body);
+    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);
   }
 
-  return renderDraftPlan(request.task, request.mode, request.target, strengthened.frontmatter, "llm-strengthened", strengthened.body);
+  const accepted = acceptStrengthenedDraft(request, strengthenedDraft);
+  if (accepted) {
+    return accepted;
+  }
+
+  return renderDraftPlan(request.task, request.mode, request.target, baseline.frontmatter, "llm-strengthened", baseline.body);
 }
 
-function hasFakeRuntimeEnforcementClaim(text: string): boolean {
+export function hasFakeRuntimeEnforcementClaim(text: string): boolean {
   return /read[-\s]?only enforced|write protection is enforced/i.test(text);
 }
 
@@ -692,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 {
@@ -734,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 [
@@ -753,7 +1353,7 @@ export function buildMissionBrief(plan: DraftPlan): string {
     ...commandLabels.map((label) => `- ${label}`),
     "",
     "Finish behavior",
-    `- ${finishLabel}`,
+    ...finishBehavior,
     "",
     "Safety",
     `- ${safetyLabel}`,
@@ -769,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 {