yeachan-heo/oh-my-claudecode/ralph

[RALPH - ITERATION {{ITERATION}}/{{MAX}}]

Your previous attempt did not output the completion promise. Continue working on the task.

<Purpose> Ralph is a PRD-driven persistence loop that keeps working on a task until ALL user stories in prd.json have passes: true and are reviewer-verified. It combines session persistence, automatic retry on failure, structured story tracking, and mandatory verification before completion. </Purpose> <Precondition_Feedback_Gate> NON-NEGOTIABLE, runs before any story work and at every verification gate:

1. FIRST ITERATION, before picking a story: run omc ralph verify --write-baseline --session <sessionId> (session id: read OMC_SESSION_ID if set — omc ralph afk exports it — else the one in the Ralph continuation context / active PRD path; use the SAME id for every call in this run). This records the feedback baseline. If the command is unavailable or denied, STOP and report the failure — do not fall back to hand-rolled judgment.
2. EVERY verification gate (story verification, post-deslop re-verification): run omc ralph verify --session <sessionId> and obey the exit code — 0 = pass (baseline-only failures are recorded warnings, never a story failure), 1 = new failures to fix.
3. NEVER hand-roll the feedback diff (running the suite yourself and eyeballing the output is exactly the failure mode this gate exists to prevent).

</Precondition_Feedback_Gate>

<Use_When>

• Task requires guaranteed completion with verification (not just "do your best")
• User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
• Work may span multiple iterations and needs persistence across retries
• Task benefits from structured PRD-driven execution with reviewer sign-off

</Use_When>

<Do_Not_Use_When>

• User wants a full autonomous pipeline from idea to code -- use autopilot instead
• User wants to explore or plan before committing -- use plan skill instead
• User wants a quick one-shot fix -- delegate directly to an executor agent
• User wants manual control over completion -- delegate directly to an executor agent
• User already has an active Claude Code /goal and only wants that native goal loop monitored -- adopt the existing /goal explicitly or use artifact-only Ultragoal notes instead of starting Ralph as a competing persistence loop

</Do_Not_Use_When>

<Why_This_Exists> Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by:

1. Structuring work into discrete user stories with testable acceptance criteria (prd.json)
2. Iterating story-by-story until each one passes
3. Tracking progress and learnings across iterations (progress.txt)
4. Requiring fresh reviewer verification against specific acceptance criteria before completion

</Why_This_Exists>

<PRD_Mode> By default, ralph operates in PRD mode. A scaffold prd.json is auto-generated when ralph starts if none exists. Active transient PRD state is session-scoped at .omc/state/sessions/{sessionId}/prd.json when a session ID is available; legacy project-level prd.json / .omc/prd.json files are read as startup migration inputs.

Startup gate: Ralph always initializes and validates prd.json at startup. Legacy --no-prd text is sanitized from the prompt for backward compatibility, but it no longer bypasses PRD creation or validation.

Deslop opt-out: If {{PROMPT}} contains --no-deslop, skip the mandatory post-review deslop pass entirely. Use this only when the cleanup pass is intentionally out of scope for the run.

Reviewer selection: Pass --critic=architect, --critic=critic, or --critic=codex in the Ralph prompt to choose the completion reviewer for that run. architect remains the default.

Stale-state detection & reconciliation (#3669): If a PRD is left unfinished by an abnormal/non-Step 8 exit (crash, force-kill, cancel before /oh-my-claudecode:cancel, session end), Ralph surfaces an explicit [STALE PRD WARNING] at startup/resume, in the continuation context, and at session end — with unfinished counts, last-touched age, and stale-pointer signals (PRD branchName merged/gone). Completion is NEVER inferred from PR/branch/merge status alone; git state is a warning signal only. A story is auto-reconciled to passes: true ONLY when the PRD carries configured observable evidence and every check passes:

{
  "reconciliation": {
    "staleAfterMs": 7200000,
    "observableChecks": {
      "US-001": [
        { "type": "fileContains", "path": "src/landed.ts", "pattern": "LANDED_SYMBOL" },
        { "type": "gitGrep", "ref": "origin/dev", "pattern": "LANDED_SYMBOL" }
      ]
    }
  }
}

Check types: fileExists / fileContains (working tree) and gitGrep (content at a ref — this is "verified by content on trunk", never PR status). Stories without configured checks are never auto-marked. Reconciled stories keep architectVerified: false and still require Step 7 reviewer verification before Step 8; every decision is appended to the prd-reconciliation.jsonl audit log and summarized in the story notes.

Repo quality class: The PRD carries a top-level repoQualityClass — prototype, production (default), or library — set during scaffold refinement. If the task does not say, ask the user once when a human is present; when running headless (omc ralph afk) there is nobody to ask, so INFER it from repo signals (CI config and test depth, published-package metadata, publishing docs) and record the inference in the PRD. Only escalate when the signals genuinely conflict. Never silently assume a lower bar than reality. It scales two things: story ordering (architectural and integration stories weigh heavier in production/library) and acceptance strictness — prototype may relax test depth for speed, production applies the full bar, library must add a backward-compatibility check to every story that touches a public surface. The repo itself outranks instructions either way: if existing code contradicts the declared class, surface the contradiction instead of copying the codebase's worst habits.

Feedback commands: The PRD may carry a top-level feedbackCommands array (e.g. ["npm run build", "npm test", "npm run lint"]). When absent, detect them from the repo's package scripts (build / lint / test variants). These are the commands omc ralph verify runs — the single executor of the baseline (Step 1f) and every feedback gate (Steps 4 and 7.6). </PRD_Mode>

<PRD_Criterion_Amendments> Acceptance criteria are the PRD's completion authority: Step 4 verifies EACH active criterion and Step 7 reviews against them. A criterion can stop governing ONLY through the evidence-preserving amendment path — never by silent deletion or by "satisfying" a criterion measurement has refuted.

When implementation proves a criterion empirically false (e.g. a count in the dispatching brief is wrong), amend it:

1. Replace the refuted criterion with the measured correction, or supersede it when no replacement governs.
2. Record the amendment in the story's criterionAmendments ledger. The original criterion text is retained verbatim (never rewritten or deleted) alongside:

• kind: "replaced" or "superseded"
• original: the verbatim refuted criterion (must still be active when the amendment is recorded)
• replacement: the corrected criterion (only for replaced)
• reason: why the original no longer governs
• evidence: the bounded measurement that refuted it (e.g. "enumerated 12 setters, not 16: ...")
• authority: who made the amendment (use the ralph session id)
• timestamp: ISO 8601 timestamp

1. The completion check then verifies only the ACTIVE criteria; the ledger keeps the audit trail so reviewers see why the original no longer governs.

Rules:

• An amendment without bounded evidence, reason, authority, or timestamp is invalid — the PRD fails closed on read rather than being silently weakened.
• An original that is still active cannot be amended; an original can be amended only once.
• Programmatic path: amendCriterion(dir, storyId, { original, replacement, reason, evidence, authority }) and supersedeCriterion(dir, storyId, { original, reason, evidence, authority }).
• Hand-edited PRDs must preserve the same invariants; a contradictory ledger (original still active, or amended twice) makes the PRD invalid.
• This is not a goal-weakening tool: it exists so that "the measurement disagrees with the plan" resolves toward the measurement without the loop losing its grip.

</PRD_Criterion_Amendments>

<Execution_Policy>

• Fire independent agent calls simultaneously -- never wait sequentially for independent work
• Use run_in_background: true for long operations (installs, builds, test suites)
• Always pass the model parameter explicitly when delegating to agents
• Read docs/shared/agent-tiers.md before first delegation to select correct agent tiers
• Deliver the full implementation: no scope reduction, no partial completion, no deleting tests to make them pass
• If a Claude Code /goal is mentioned, treat it as a native session-loop handoff/evidence source only and use the deterministic conflict policies refuse, adopt_existing, and artifact_only rather than non-deterministic warning handling. Ralph remains the OMC loop authority for this run; do not claim /goal independently ran tests or read files, and do not treat evaluator success as a substitute for Ralph reviewer verification.

</Execution_Policy>