ralph-prd 1.0.4 → 1.0.6

package/README.md

@@ -22,12 +22,12 @@ cd your-project && ../ralph-prd/install.sh
 
 This installs:
 - `.claude/ralph/` — the phased runner
-- `.claude/skills/` — 6 Claude Code skills for the full PRD-to-ship workflow
+- `.claude/skills/` — 7 Claude Code skills fetched from [`tahaJemmali/skills`](https://github.com/tahaJemmali/skills) via `npx skills add`
 - On first install, adds `.claude/ralph/` and `.claude/skills/` to `.gitignore` (skipped if `.claude/` already exists, so shared setups are respected)
 
 ### Updating
 
-To update Ralph in any repo, just re-run the install command:
+To update Ralph and re-fetch skills, just re-run the install command:
 
 ```bash
 npx ralph-prd
@@ -35,6 +35,12 @@ npx ralph-prd
 
 Ralph also checks for updates automatically on every run. If a newer version is available, you'll see a notice in the console output.
 
+To update only the skills without reinstalling:
+
+```bash
+node .claude/ralph/ralph-claude.mjs --update-skills
+```
+
 ## Requirements
 
 - Node.js 18+
@@ -88,6 +94,7 @@ 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
+  --update-skills    Re-fetch skills from tahaJemmali/skills and exit
   --version, -v      Print installed version and exit
 ```
 
@@ -114,10 +121,13 @@ node .claude/ralph/ralph-claude.mjs docs/auth-rework/plan.md --send-it
 | `/grill-me` | Stress-test a plan by walking every branch of the decision tree |
 | `/write-a-prd` | Interview-driven PRD creation with codebase exploration |
 | `/prd-to-plan` | Turn a PRD into phased vertical-slice implementation plan |
+| `/reality-check` | Brutally honest architectural critique and assumption stress-test |
 | `/review-changes` | Review recent changes against project guidelines |
 | `/repo-doc-maintainer` | Decide if AGENTS.md or docs need updating after changes |
 | `/ship-check` | End-of-task validation: review + doc maintenance check |
 
+Skills are fetched from [`tahaJemmali/skills`](https://github.com/tahaJemmali/skills) during install. You can also install or update them independently with `npx skills add tahaJemmali/skills`.
+
 ## Multi-Repo Support
 
 Create `ralph.config.yaml` in `.claude/ralph/` for monorepo setups:
@@ -181,6 +191,10 @@ Ralph validates the plan structure before execution and checks off criteria as p
 - **macOS notifications** — get notified when phases complete or fail
 - **Safety** — optional `blocked-commands.txt` and `blocked-paths.txt` restrict what Claude can do
 
+## Acknowledgments
+
+Three of the skills in this repo — [`/grill-me`](https://skills.sh/mattpocock/skills/grill-me), [`/write-a-prd`](https://skills.sh/mattpocock/skills/write-a-prd), and [`/prd-to-plan`](https://skills.sh/mattpocock/skills/prd-to-plan) — are based on [Matt Pocock](https://github.com/mattpocock)'s work. Matt generously gave his blessing to include them here. If you find these useful, go check out his cohort and give him a star.
+
 ## License
 
 MIT

package/bin/install.mjs

@@ -3,12 +3,14 @@
 /**
  * ralph-prd installer — called via `npx ralph-prd` or `npx ralph-prd init`
  *
- * Copies ralph/ and skills/ into .claude/ of the current project.
+ * Copies ralph/ into .claude/ of the current project, then fetches skills
+ * from the skills repo via `npx skills add tahaJemmali/skills`.
  */
 
-import { existsSync, mkdirSync, cpSync, rmSync, readdirSync, readFileSync, writeFileSync } from 'fs';
-import { resolve, dirname, basename } from 'path';
+import { existsSync, mkdirSync, cpSync, rmSync, readFileSync, writeFileSync } from 'fs';
+import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -60,35 +62,46 @@ 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/`);
 
-// Copy skills
-const skillsSrc = resolve(PKG_ROOT, 'skills');
-const skillsDst = resolve(claudeDir, 'skills');
-mkdirSync(skillsDst, { recursive: true });
-
-for (const skillName of readdirSync(skillsSrc)) {
-  const src = resolve(skillsSrc, skillName);
-  const dst = resolve(skillsDst, skillName);
-  if (existsSync(dst)) {
-    info(`Updating existing skill: ${skillName}`);
-    rmSync(dst, { recursive: true });
-  }
-  cpSync(src, dst, { recursive: true });
-  ok(`Installed skill: ${skillName}`);
+// Install skills via skills.sh
+info('Installing skills from tahaJemmali/skills…');
+const REQUIRED_SKILLS = [
+  'grill-me',
+  'write-a-prd',
+  'prd-to-plan',
+  'reality-check',
+  'ship-check',
+  'review-changes',
+  'repo-doc-maintainer',
+];
+const skillsResult = spawnSync(
+  'npx',
+  ['skills', 'add', 'tahaJemmali/skills', ...REQUIRED_SKILLS.flatMap(s => ['--skill', s]), '-a', 'claude-code', '-y'],
+  { cwd: projectRoot, stdio: 'inherit', encoding: 'utf8' },
+);
+if (skillsResult.status !== 0) {
+  fail('Skills installation failed — aborting. ralph-prd requires all skills to be installed.\n  Retry by running: npx ralph-prd');
 }
+ok('Installed skills -> .claude/skills/');
+
+const gitignorePath = resolve(projectRoot, '.gitignore');
+let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+const lines = gitignoreContent.split('\n').map(l => l.trim());
 
-// Only add to .gitignore on first install — if .claude/ already existed,
+// skills-lock.json is always a generated file — add to gitignore unconditionally.
+const alwaysIgnore = ['skills-lock.json'];
+const alwaysMissing = alwaysIgnore.filter(e => !lines.includes(e));
+
+// Only add .claude/ entries on first install — if .claude/ already existed,
 // the user may be sharing it via git intentionally.
-if (isFirstInstall) {
-  const gitignorePath = resolve(projectRoot, '.gitignore');
-  const ignoreEntries = ['.claude/ralph/', '.claude/skills/'];
-  let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-  const missing = ignoreEntries.filter(entry => !gitignoreContent.split('\n').some(line => line.trim() === entry));
-  if (missing.length > 0) {
-    const block = (gitignoreContent.length > 0 && !gitignoreContent.endsWith('\n') ? '\n' : '') +
-      '\n# ralph-prd (installed via npx ralph-prd)\n' + missing.join('\n') + '\n';
-    writeFileSync(gitignorePath, gitignoreContent + block, 'utf8');
-    ok(`Added ${missing.join(', ')} to .gitignore`);
-  }
+const conditionalIgnore = isFirstInstall ? ['.claude/ralph/', '.claude/skills/'] : [];
+const conditionalMissing = conditionalIgnore.filter(e => !lines.includes(e));
+
+const missing = [...alwaysMissing, ...conditionalMissing];
+if (missing.length > 0) {
+  const block = (gitignoreContent.length > 0 && !gitignoreContent.endsWith('\n') ? '\n' : '') +
+    '\n# ralph-prd (installed via npx ralph-prd)\n' + missing.join('\n') + '\n';
+  writeFileSync(gitignorePath, gitignoreContent + block, 'utf8');
+  ok(`Added ${missing.join(', ')} to .gitignore`);
 }
 
 // Summary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-prd",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "AI-powered phased implementation runner for Claude Code — from PRD to shipped code",
   "bin": {
     "ralph-prd": "./bin/install.mjs"
@@ -23,7 +23,6 @@
   "files": [
     "bin/",
     "ralph/",
-    "skills/",
     "install.sh",
     "README.md"
   ],

package/ralph/lib/config.mjs

@@ -23,12 +23,13 @@ function isGitRepo(dirPath) {
 
 /**
  * @typedef {Object} RalphFlags
- * @property {boolean}     iDidThis    - Claude skips self-commit; separate commit step runs instead
- * @property {boolean}     sendIt      - Push branch and open a PR after all phases complete
- * @property {boolean}     waitForIt   - Pause for user confirmation before each commit step
- * @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}     iDidThis       - Claude skips self-commit; separate commit step runs instead
+ * @property {boolean}     sendIt         - Push branch and open a PR after all phases complete
+ * @property {boolean}     waitForIt      - Pause for user confirmation before each commit step
+ * @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
  */
 
 /**
@@ -59,7 +60,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' };
+  const flags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, logLevel: 'necessary', skipShipCheck: false };
   const hooks = { afterCommit: null };
   let section = null;
   let current = null;
@@ -159,7 +160,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 };
+  const defaultFlags = { iDidThis: false, sendIt: false, waitForIt: false, maxRepairs: 3, onlyPhase: null, skipShipCheck: false };
   const defaultHooks = { afterCommit: null };
 
   if (!existsSync(configPath)) {

package/ralph/lib/ship-checker.mjs

@@ -0,0 +1,319 @@
+/**
+ * lib/ship-checker.mjs
+ *
+ * Ship-Check coordinator — runs after commit, before markPhaseComplete.
+ *
+ * Flow:
+ *   1. Read .claude/skills/ship-check/SKILL.md, strip YAML frontmatter.
+ *   2. Build ship-check prompt: skill body + phase context + repo state.
+ *   3. Run ship-check session via transport.
+ *   4. Parse VERDICT: APPROVED or VERDICT: REMARKS (case-insensitive).
+ *   5. APPROVED  → return normally.
+ *   6. REMARKS   → extract findings, run one repair session, re-run ship-check.
+ *   7. Second REMARKS → throw ShipCheckError with findings attached.
+ *
+ * Public API:
+ *   class ShipCheckError extends Error
+ *     .phaseName: string
+ *     .findings:  string
+ *
+ *   runShipCheck({
+ *     phase, repoState, logWriter, phaseNum, startTaskNum, send,
+ *     _skillsBase  // optional base dir override for testing
+ *   }) → Promise<{ nextTaskNum: number }>
+ *   throws ShipCheckError on second REMARKS verdict
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// ─── Error type ───────────────────────────────────────────────────────────────
+
+export class ShipCheckError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} phaseName
+   * @param {string} findings
+   */
+  constructor(message, phaseName, findings) {
+    super(message);
+    this.name = 'ShipCheckError';
+    this.phaseName = phaseName;
+    this.findings = findings;
+  }
+}
+
+// ─── SKILL.md loading ─────────────────────────────────────────────────────────
+
+const SKILL_REL_PATH = join('.claude', 'skills', 'ship-check', 'SKILL.md');
+
+/**
+ * Strip YAML frontmatter (--- ... ---) from skill content and return the body.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function stripFrontmatter(content) {
+  if (!content.startsWith('---')) return content;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return content;
+  return content.slice(end + 4).trimStart();
+}
+
+/**
+ * Read and parse the ship-check SKILL.md.
+ *
+ * @param {string} baseDir - Repo root (or test override via _skillsBase)
+ * @returns {string} Skill body with frontmatter stripped
+ * @throws {Error} with a clear message if the file is missing
+ */
+function loadSkill(baseDir) {
+  const skillPath = join(baseDir, SKILL_REL_PATH);
+  let raw;
+  try {
+    raw = readFileSync(skillPath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Ship-check skill not found at ${skillPath}. ` +
+      `Create ${SKILL_REL_PATH} in your repository to enable ship-check. ` +
+      `(${err.code})`
+    );
+  }
+  return stripFrontmatter(raw);
+}
+
+// ─── Verdict parsing ──────────────────────────────────────────────────────────
+
+/**
+ * Scan response text for the first VERDICT line and extract findings on REMARKS.
+ *
+ * Findings may be delimited by FINDINGS_START / FINDINGS_END; if the model
+ * omits the delimiters, everything after the VERDICT line is used as findings.
+ *
+ * @param {string} text
+ * @returns {{ verdict: 'APPROVED'|'REMARKS'|'UNKNOWN', findings: string }}
+ */
+function parseVerdict(text) {
+  const lines = text.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].trim().match(/^VERDICT:\s+(APPROVED|REMARKS)$/i);
+    if (!match) continue;
+
+    const verdict = match[1].toUpperCase();
+
+    if (verdict === 'APPROVED') {
+      return { verdict: 'APPROVED', findings: '' };
+    }
+
+    // REMARKS — collect findings
+    const findingsLines = [];
+    let inFindings = false;
+
+    for (let j = i + 1; j < lines.length; j++) {
+      const t = lines[j].trim();
+      if (t === 'FINDINGS_START') { inFindings = true; continue; }
+      if (t === 'FINDINGS_END') break;
+      if (inFindings) findingsLines.push(lines[j]);
+    }
+
+    // Fallback: no delimiters — take everything after the verdict line
+    if (findingsLines.length === 0) {
+      for (let j = i + 1; j < lines.length; j++) {
+        findingsLines.push(lines[j]);
+      }
+    }
+
+    return { verdict: 'REMARKS', findings: findingsLines.join('\n').trim() };
+  }
+
+  return { verdict: 'UNKNOWN', findings: '' };
+}
+
+// ─── Prompt builders ──────────────────────────────────────────────────────────
+
+/**
+ * Build the ship-check prompt by combining the skill body with phase context
+ * and the current repository state.
+ *
+ * @param {string} skillBody - Skill content with frontmatter stripped
+ * @param {import('./plan-parser.mjs').Phase} phase
+ * @param {string} repoState - Pre-computed git status / diff summary
+ * @returns {string}
+ */
+function buildShipCheckPrompt(skillBody, phase, repoState) {
+  return [
+    skillBody,
+    '',
+    '---',
+    '',
+    `## Phase under review: ${phase.title}`,
+    '',
+    phase.body.trim(),
+    '',
+    '## Current repository state',
+    '',
+    repoState,
+  ].join('\n');
+}
+
+/**
+ * Build the repair prompt sent after a REMARKS verdict.
+ *
+ * @param {import('./plan-parser.mjs').Phase} phase
+ * @param {string} repoState
+ * @param {string} findings - Findings text from the ship-check session
+ * @returns {string}
+ */
+function buildRepairPrompt(phase, repoState, findings) {
+  return [
+    `The ship-check reviewer found issues with the implementation of phase "${phase.title}".`,
+    'Please address the following remarks, then the phase will be re-checked.',
+    '',
+    '## Reviewer findings',
+    '',
+    findings || '(No specific findings provided.)',
+    '',
+    '## Phase being reviewed',
+    '',
+    phase.body.trim(),
+    '',
+    '## Current repository state',
+    '',
+    repoState,
+  ].join('\n');
+}
+
+// ─── Session helper ───────────────────────────────────────────────────────────
+
+/**
+ * Open a step log, send a prompt, stream the response, close the log.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.stepName
+ * @param {string}   opts.phaseName
+ * @param {string}   opts.prompt
+ * @param {import('./log-writer.mjs').LogWriter} opts.logWriter
+ * @param {number}   opts.phaseNum
+ * @param {number}   opts.taskNum
+ * @param {Function} opts.send
+ * @returns {Promise<string>} full response text
+ */
+async function runSession({ stepName, phaseName, prompt, logWriter, phaseNum, taskNum, send }) {
+  const step = logWriter.openStep(phaseNum, taskNum, stepName, phaseName);
+  step.writeHeader();
+
+  const started = Date.now();
+  let fullText = '';
+
+  try {
+    fullText = await send(prompt, {
+      onChunk(text) {
+        step.writeChunk(text);
+      },
+    });
+    step.writeFooter(true, Date.now() - started);
+  } catch (err) {
+    step.writeChunk(`\n\n[error] ${err.message}\n`);
+    step.writeFooter(false, Date.now() - started);
+    throw err;
+  }
+
+  return fullText;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run the full ship-check (+ optional repair) cycle for a single phase.
+ *
+ * Sessions written (each gets its own step log):
+ *   startTaskNum+0  ship-check          (initial check)
+ *   startTaskNum+1  ship-check-repair   (only on first REMARKS)
+ *   startTaskNum+2  ship-check-re       (re-check after repair)
+ *
+ * @param {object}   opts
+ * @param {import('./plan-parser.mjs').Phase} opts.phase
+ * @param {string}   opts.repoState - Pre-computed repo state string
+ * @param {import('./log-writer.mjs').LogWriter} opts.logWriter
+ * @param {number}   opts.phaseNum
+ * @param {number}   opts.startTaskNum
+ * @param {Function} opts.send
+ * @param {string}  [opts._skillsBase] - Base dir for SKILL.md lookup (testing only)
+ * @returns {Promise<{ nextTaskNum: number }>}
+ * @throws {ShipCheckError} when re-check also returns REMARKS
+ */
+export async function runShipCheck({
+  phase,
+  repoState,
+  logWriter,
+  phaseNum,
+  startTaskNum,
+  send,
+  _skillsBase = process.cwd(),
+}) {
+  const skillBody = loadSkill(_skillsBase);
+  let taskNum = startTaskNum;
+
+  // ── Initial ship-check ─────────────────────────────────────────────────────
+
+  const initialPrompt = buildShipCheckPrompt(skillBody, phase, repoState);
+
+  const initialText = await runSession({
+    stepName: 'ship-check',
+    phaseName: phase.title,
+    prompt: initialPrompt,
+    logWriter,
+    phaseNum,
+    taskNum: taskNum++,
+    send,
+  });
+
+  const { verdict: initialVerdict, findings: initialFindings } = parseVerdict(initialText);
+
+  if (initialVerdict === 'APPROVED') {
+    return { nextTaskNum: taskNum };
+  }
+
+  const findings = initialFindings;
+
+  // ── Repair session ─────────────────────────────────────────────────────────
+
+  const repairPrompt = buildRepairPrompt(phase, repoState, findings);
+
+  await runSession({
+    stepName: 'ship-check-repair',
+    phaseName: phase.title,
+    prompt: repairPrompt,
+    logWriter,
+    phaseNum,
+    taskNum: taskNum++,
+    send,
+  });
+
+  // ── Re-check ───────────────────────────────────────────────────────────────
+
+  const reCheckText = await runSession({
+    stepName: 'ship-check-re',
+    phaseName: phase.title,
+    prompt: buildShipCheckPrompt(skillBody, phase, repoState),
+    logWriter,
+    phaseNum,
+    taskNum: taskNum++,
+    send,
+  });
+
+  const { verdict: reVerdict, findings: reFindings } = parseVerdict(reCheckText);
+
+  if (reVerdict === 'APPROVED') {
+    return { nextTaskNum: taskNum };
+  }
+
+  // ── Second REMARKS → hard stop ─────────────────────────────────────────────
+
+  throw new ShipCheckError(
+    `Phase "${phase.title}" failed ship-check after one repair attempt. No further action will be taken.`,
+    phase.title,
+    reFindings || findings
+  );
+}

package/ralph/lib/verifier.mjs

@@ -62,7 +62,7 @@ export class VerificationError extends Error {
  * @param {import('./config.mjs').Repo[]} repos
  * @returns {string}
  */
-function gatherRepoState(repos) {
+export function gatherRepoState(repos) {
   const primaryRepos = repos.filter(r => !r.writableOnly);
   const parts = [];
 

package/ralph/ralph-claude.mjs

@@ -23,8 +23,9 @@ import { prepareBranch, scanChangedRepos, GitCoordinatorError } from './lib/git-
 import { LogWriter } from './lib/log-writer.mjs';
 import { loadSafetyHeader } from './lib/safety.mjs';
 import { runImplementation, PhaseExecutorError } from './lib/phase-executor.mjs';
-import { runVerificationLoop, VerificationError } from './lib/verifier.mjs';
+import { runVerificationLoop, VerificationError, gatherRepoState } from './lib/verifier.mjs';
 import { runCommitStep, CommitError } from './lib/committer.mjs';
+import { runShipCheck, ShipCheckError } from './lib/ship-checker.mjs';
 import { mutateCheckboxes } from './lib/plan-mutator.mjs';
 import { deriveBranchName } from './lib/utils.mjs';
 
@@ -91,6 +92,36 @@ if (args.includes('--version') || args.includes('-v')) {
   process.exit(0);
 }
 
+// ─── --update-skills ──────────────────────────────────────────────────────────
+// Re-fetch skills from the skills repo and exit. Useful after an upgrade.
+
+if (args.includes('--update-skills')) {
+  console.log('[ralph] Updating skills via npx skills add tahaJemmali/skills…');
+  const result = spawnSync('npx', ['skills', 'add', 'tahaJemmali/skills'], {
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    console.error('[ralph] Failed to update skills. See output above.');
+    process.exit(1);
+  }
+  console.log('[ralph] Skills updated.');
+  process.exit(0);
+}
+
+// ─── Skills preflight ─────────────────────────────────────────────────────────
+// Fail fast if skills are not installed — gives a clear actionable message.
+
+const skillsDir = resolve(__dirname, '..', 'skills');
+if (!existsSync(skillsDir)) {
+  console.error(
+    '[ralph] Skills not installed. Run: npx ralph-prd to reinstall.\n' +
+    '[ralph] If you recently upgraded ralph-prd, re-run the installer to fetch\n' +
+    '[ralph] skills from the new source: npx ralph-prd'
+  );
+  process.exit(1);
+}
+
 const planArg = args.find(a => !a.startsWith('--'));
 const isDryRun = args.includes('--dry-run');
 const isReset = args.includes('--reset');
@@ -101,6 +132,8 @@ const iDidThisArg = args.includes('--i-did-this');
 const sendItArg = args.includes('--send-it');
 // Pause and wait for your eyes before each commit. Trust issues? Fair enough.
 const waitForItArg = args.includes('--wait-for-it');
+// Skip the post-commit ship-check step. Use when you don't have a ship-check skill.
+const skipShipCheckArg = args.includes('--skip-ship-check');
 // Run only one specific phase (1-based), force re-run even if already complete.
 const onlyPhaseArg = (() => {
   const idx = args.indexOf('--only-phase');
@@ -121,7 +154,7 @@ const logLevelArg = (() => {
 if (!planArg) {
   console.error(
     'Usage: node ralph-claude.mjs <plan-file.md> ' +
-    '[--reset|--dry-run|--i-did-this|--send-it|--wait-for-it|--only-phase N|--log-level none|necessary|dump|--version]'
+    '[--reset|--dry-run|--i-did-this|--send-it|--wait-for-it|--skip-ship-check|--only-phase N|--log-level none|necessary|dump|--update-skills|--version]'
   );
   process.exit(1);
 }
@@ -315,6 +348,7 @@ async function main() {
   const iDidThis = iDidThisArg || configFlags.iDidThis;
   const sendIt = sendItArg || configFlags.sendIt;
   const waitForIt = waitForItArg || configFlags.waitForIt;
+  const skipShipCheck = skipShipCheckArg || configFlags.skipShipCheck;
   const onlyPhase = onlyPhaseArg ?? configFlags.onlyPhase ?? null;
   const logLevel = logLevelArg ?? configFlags.logLevel ?? 'necessary';
 
@@ -658,6 +692,40 @@ async function main() {
       console.log('ok');
     }
 
+    // ── Ship-check ────────────────────────────────────────────────────────────
+    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)`);
+      } 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');
+          console.error(`\nUnexpected error during ship-check: ${err.message}`);
+        }
+        console.error(`Logs: ${logsDir}`);
+        notify('Ralph — failed', `Ship-check failed for "${phase.title}"`);
+        process.exit(1);
+      }
+    }
+
     // ── Checkbox mutation + state persistence ────────────────────────────────
     // Skip state writes when --only-phase is active (it's a force re-run, not a progression).
     if (onlyPhase === null) {

package/ralph/ralph.config.sample.yaml

@@ -7,12 +7,12 @@
 # ── Repositories ──────────────────────────────────────────────────────────────
 # List every git repo Ralph is allowed to read and write.
 # Paths are relative to this config file.
+# repos:
+#   - name: backend
+#     path: ../backend
+#   - name: frontend
+#     path: ../frontend
 
-repos:
-  - name: backend
-    path: ../../ebchat-saas-backend
-  - name: dashboard
-    path: ../../ebchat-saas-dashboard
 
 # ── Extra writable directories ────────────────────────────────────────────────
 # Directories that are not git roots but Ralph may write to (e.g. shared docs).
@@ -48,3 +48,8 @@ flags:
   #   necessary — verdicts (pass/fail), missed criteria, phase progress (default)
   #   dump      — full streamed model output (verbose)
   logLevel: necessary
+
+  # Skip the post-commit ship-check step for every phase. Set to true if you
+  # have not installed a ship-check skill or want to disable the review gate.
+  # CLI equivalent: --skip-ship-check
+  skipShipCheck: false