ralph-prd 1.0.8 → 1.0.11

package/README.md

@@ -94,8 +94,10 @@ Options:
   --i-did-this       Skip Claude self-commit; run separate commit step
   --send-it          Push branch + open PR when all phases complete
   --wait-for-it           Pause before each commit for review
-  --skip-ship-check       Skip the post-commit ship-check step
-  --skip-on-verify-fail   Skip verification and continue instead of hard-stopping when all repair attempts fail
+  --skip-ship-check            Skip the post-commit ship-check step entirely
+  --ship-check-retries=N       Retry ship-check up to N times per phase before giving up (default 1)
+  --skip-on-ship-check-fail    Log and continue when all ship-check retries fail instead of hard-stopping
+  --skip-on-verify-fail        Skip verification and continue instead of hard-stopping when all repair attempts fail
   --update-skills         Re-fetch skills from tahaJemmali/skills and exit
   --version, -v      Print installed version and exit
 ```
@@ -147,6 +149,9 @@ writableDirs:
 flags:
   maxRepairs: 3
   sendIt: false
+  skipShipCheck: false
+  shipCheckRetries: 1
+  skipOnShipCheckFail: true
   skipOnVerifyFail: false
 
 hooks:

package/bin/install.mjs

@@ -7,7 +7,7 @@
  * from the skills repo via `npx skills add tahaJemmali/skills`.
  */
 
-import { existsSync, mkdirSync, cpSync, rmSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, cpSync, rmSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
@@ -62,6 +62,14 @@ const pkg = JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8'));
 writeFileSync(resolve(ralphDst, '.ralph-version'), pkg.version + '\n', 'utf8');
 ok(`Installed ralph runner v${pkg.version} -> .claude/ralph/`);
 
+// Create default ralph.config.yaml if it doesn't exist yet
+const configDst = resolve(ralphDst, 'ralph.config.yaml');
+const configSrc = resolve(ralphDst, 'ralph.config.sample.yaml');
+if (!existsSync(configDst) && existsSync(configSrc)) {
+  copyFileSync(configSrc, configDst);
+  ok('Created default ralph.config.yaml -> .claude/ralph/ralph.config.yaml');
+}
+
 // Install skills via skills.sh
 info('Installing skills from tahaJemmali/skills…');
 const REQUIRED_SKILLS = [
@@ -111,6 +119,7 @@ console.log('');
 info(`Installed to: ${claudeDir}`);
 info('');
 info('Quick start:');
+info('  0. Configure:      edit .claude/ralph/ralph.config.yaml');
 info('  1. Write a PRD:    claude then /write-a-prd');
 info('  2. Create a plan:  claude then /prd-to-plan');
 info('  3. Execute:        node .claude/ralph/ralph-claude.mjs docs/<feature>/plan.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-prd",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "description": "AI-powered phased implementation runner for Claude Code — from PRD to shipped code",
   "bin": {
     "ralph-prd": "./bin/install.mjs"

package/ralph/lib/config.mjs

@@ -29,8 +29,10 @@ function isGitRepo(dirPath) {
  * @property {number}      maxRepairs     - Max repair attempts per phase before hard-stopping (default 3)
  * @property {number|null} onlyPhase      - When set, only this 1-based phase index is run (force re-run)
  * @property {string}      logLevel       - "none" | "necessary" | "dump" (default "necessary")
- * @property {boolean}     skipShipCheck       - Skip the post-commit ship-check step for every phase
- * @property {boolean}     skipOnVerifyFail    - Skip verification and continue instead of hard-stopping when all repair attempts fail
+ * @property {boolean}     skipShipCheck          - Skip the post-commit ship-check step for every phase
+ * @property {number}      shipCheckRetries       - Max ship-check attempts per phase before giving up (default 1)
+ * @property {boolean}     skipOnShipCheckFail    - When true, log and continue after all retries fail instead of hard-stopping
+ * @property {boolean}     skipOnVerifyFail       - Skip verification and continue instead of hard-stopping when all repair attempts fail
  */
 
 /**
@@ -61,7 +63,7 @@ function isGitRepo(dirPath) {
 function parseConfigYaml(content) {
   const repos = [];
   const writableDirs = [];
-  const flags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, logLevel: 'necessary', skipShipCheck: false, skipOnVerifyFail: false };
+  const flags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, logLevel: 'necessary', skipShipCheck: false, shipCheckRetries: 1, skipOnShipCheckFail: true, skipOnVerifyFail: false };
   const hooks = { afterCommit: null };
   let section = null;
   let current = null;
@@ -116,9 +118,9 @@ function parseConfigYaml(content) {
         const [, key, val] = match;
         if (!(key in flags)) continue;
         const trimmedVal = val.trim();
-        if (key === 'maxRepairs') {
+        if (key === 'maxRepairs' || key === 'shipCheckRetries') {
           const n = parseInt(trimmedVal, 10);
-          if (!isNaN(n) && n > 0) flags.maxRepairs = n;
+          if (!isNaN(n) && n > 0) flags[key] = n;
         } else if (key === 'onlyPhase') {
           const n = parseInt(trimmedVal, 10);
           if (!isNaN(n) && n > 0) flags.onlyPhase = n;
@@ -161,7 +163,7 @@ function parseConfigYaml(content) {
  */
 export function resolveRepos(runnerDir) {
   const configPath = join(runnerDir, CONFIG_FILENAME);
-  const defaultFlags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, skipShipCheck: false, skipOnVerifyFail: false };
+  const defaultFlags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, skipShipCheck: false, shipCheckRetries: 1, skipOnShipCheckFail: true, skipOnVerifyFail: false };
   const defaultHooks = { afterCommit: null };
 
   if (!existsSync(configPath)) {

package/ralph/ralph-claude.mjs

@@ -351,6 +351,7 @@ async function main() {
   const sendIt = sendItArg || configFlags.sendIt;
   const waitForIt = waitForItArg || configFlags.waitForIt;
   const skipShipCheck = skipShipCheckArg || configFlags.skipShipCheck;
+  const skipOnShipCheckFail = configFlags.skipOnShipCheckFail;
   const skipOnVerifyFail = skipOnVerifyFailArg || configFlags.skipOnVerifyFail;
   const onlyPhase = onlyPhaseArg ?? configFlags.onlyPhase ?? null;
   const logLevel = logLevelArg ?? configFlags.logLevel ?? 'necessary';
@@ -706,61 +707,87 @@ async function main() {
     if (skipShipCheck) {
       console.log(`  [${ts()}] ship-check… skipped`);
     } else {
-      const repoState = gatherRepoState(repos);
-      const shipCheckStart = Date.now();
-      process.stdout.write(`  [${ts()}] ship-check… `);
-      try {
-        ({ nextTaskNum: taskNum } = await runShipCheck({
-          phase,
-          repoState,
-          logWriter,
-          phaseNum,
-          startTaskNum: taskNum,
-          send,
-        }));
-        const dur = ((Date.now() - shipCheckStart) / 1000).toFixed(1);
-        console.log(`VERDICT: APPROVED (${dur}s)`);
-
-        // Ship-check repair may have modified files — commit any leftovers.
-        const postShipChanges = await scanChangedRepos(repos);
-        if (postShipChanges.length > 0) {
-          process.stdout.write(`  [${ts()}] post-ship-check commit… `);
-          try {
-            const { nextTaskNum, anyCommitted } = await runCommitStep({
-              phase,
-              repos,
-              safetyHeader,
-              logWriter,
-              phaseNum,
-              taskNum,
-              send,
-            });
-            taskNum = nextTaskNum;
-            console.log(anyCommitted ? 'ok' : 'skipped (no changes)');
-          } catch (err) {
+      const maxAttempts = configFlags.shipCheckRetries ?? 1;
+      let shipCheckPassed = false;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const repoState = gatherRepoState(repos);
+        const shipCheckStart = Date.now();
+        const attemptSuffix = maxAttempts > 1 ? ` (attempt ${attempt}/${maxAttempts})` : '';
+        process.stdout.write(`  [${ts()}] ship-check${attemptSuffix}… `);
+
+        try {
+          ({ nextTaskNum: taskNum } = await runShipCheck({
+            phase,
+            repoState,
+            logWriter,
+            phaseNum,
+            startTaskNum: taskNum,
+            send,
+          }));
+          const dur = ((Date.now() - shipCheckStart) / 1000).toFixed(1);
+          console.log(`VERDICT: APPROVED (${dur}s)`);
+          shipCheckPassed = true;
+
+          // Ship-check repair may have modified files — commit any leftovers.
+          const postShipChanges = await scanChangedRepos(repos);
+          if (postShipChanges.length > 0) {
+            process.stdout.write(`  [${ts()}] post-ship-check commit… `);
+            try {
+              const { nextTaskNum, anyCommitted } = await runCommitStep({
+                phase,
+                repos,
+                safetyHeader,
+                logWriter,
+                phaseNum,
+                taskNum,
+                send,
+              });
+              taskNum = nextTaskNum;
+              console.log(anyCommitted ? 'ok' : 'skipped (no changes)');
+            } catch (err) {
+              console.log('failed');
+              const msg = err instanceof CommitError
+                ? `Phase "${err.phaseName}" post-ship-check commit failed: ${err.message}`
+                : `Unexpected error during post-ship-check commit: ${err.message}`;
+              console.error(`\n${msg}`);
+              console.error(`Logs: ${logsDir}`);
+              notify('Ralph — failed', msg);
+              process.exit(1);
+            }
+          }
+          break;
+        } catch (err) {
+          const dur = ((Date.now() - shipCheckStart) / 1000).toFixed(1);
+          if (err instanceof ShipCheckError) {
+            console.log(`VERDICT: REMARKS (${dur}s)`);
+            console.error(`\nShip-check failed for phase "${err.phaseName}":`);
+            if (err.findings) console.error(err.findings);
+          } else {
             console.log('failed');
-            const msg = err instanceof CommitError
-              ? `Phase "${err.phaseName}" post-ship-check commit failed: ${err.message}`
-              : `Unexpected error during post-ship-check commit: ${err.message}`;
-            console.error(`\n${msg}`);
+            console.error(`\nUnexpected error during ship-check: ${err.message}`);
             console.error(`Logs: ${logsDir}`);
-            notify('Ralph — failed', msg);
+            notify('Ralph — failed', `Ship-check failed for "${phase.title}"`);
             process.exit(1);
           }
+
+          if (attempt < maxAttempts) {
+            console.error(`  Retrying ship-check (${attempt}/${maxAttempts} attempts used)…`);
+          }
         }
-      } catch (err) {
-        const dur = ((Date.now() - shipCheckStart) / 1000).toFixed(1);
-        if (err instanceof ShipCheckError) {
-          console.log(`VERDICT: REMARKS (${dur}s)`);
-          console.error(`\nShip-check failed for phase "${err.phaseName}":`);
-          if (err.findings) console.error(err.findings);
+      }
+
+      if (!shipCheckPassed) {
+        const attempts = `${maxAttempts} attempt${maxAttempts === 1 ? '' : 's'}`;
+        console.error(`\nShip-check did not pass after ${attempts} for phase "${phase.title}".`);
+        console.error(`Logs: ${logsDir}`);
+        if (skipOnShipCheckFail) {
+          console.error(`Continuing anyway (skipOnShipCheckFail: true).`);
+          notify('Ralph — ship-check skipped', `"${phase.title}" ship-check failed after ${attempts} — continuing`);
         } else {
-          console.log('failed');
-          console.error(`\nUnexpected error during ship-check: ${err.message}`);
+          notify('Ralph — failed', `Ship-check failed for "${phase.title}" after ${attempts}`);
+          process.exit(1);
         }
-        console.error(`Logs: ${logsDir}`);
-        notify('Ralph — failed', `Ship-check failed for "${phase.title}"`);
-        process.exit(1);
       }
     }
 

package/ralph/ralph.config.sample.yaml

@@ -54,6 +54,16 @@ flags:
   # CLI equivalent: --skip-ship-check
   skipShipCheck: false
 
+  # Max ship-check attempts per phase before giving up. On final failure,
+  # behaviour is controlled by skipOnShipCheckFail below.
+  # CLI equivalent: --ship-check-retries=N
+  shipCheckRetries: 1
+
+  # When true, log and continue if ship-check fails after all retries instead
+  # of hard-stopping. Defaults to true.
+  # CLI equivalent: --skip-on-ship-check-fail
+  skipOnShipCheckFail: true
+
   # When all repair attempts are exhausted, skip verification and continue to
   # the commit step instead of hard-stopping. Useful when the acceptance
   # criteria require external credentials or manual steps that the agent cannot