ralph-code 0.6.1__tar.gz → 0.6.3__tar.gz

{ralph_code-0.6.1/ralph_code.egg-info → ralph_code-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ralph-code
-Version: 0.6.1
+Version: 0.6.3
 Summary: Automated task implementation with Claude Code and Codex
 Author: Ralph Coding
 License: MIT
@@ -37,7 +37,7 @@ Dynamic: requires-python
 
 # ralph-code
 
-Automated task implementation with Claude Code and Codex for "Ralph Coding". What is [Ralph Coding](https://ghuntley.com/ralph/)? It's a method of coding where context rot is avoided by controlling the retention of information. This method involves re-invoking claude or codex for each task, and passing information about the requirements, acceptance testing, and any progress that's made (or roadblocks/challenges faced) through files, rather than retaining all prompts + thinking + response tokens. It tends to result in more requests, some duplicated token work, but fairly consistent performance, and best of all it can largely be done unattended. Recommend Claude Max account or codex equivalent, but be aware that GPT-5 - GPT5.2's slow reasoning and response makes this ponderous, it's fine overnight.
+Automated task implementation with Claude Code and Codex for "Ralph Coding". What is [Ralph Coding](https://ghuntley.com/ralph/)? It's a method of coding where context rot is avoided by controlling the retention of information. This method involves re-invoking claude or codex for each task, and passing information about the requirements, acceptance testing, and any progress that's made (or roadblocks/challenges faced) through files, rather than retaining all prompts + thinking + response tokens. It tends to result in more requests, some duplicated token work, but fairly consistent performance, and best of all it can largely be done unattended. Ralph now defaults to continuing past PRD-to-task conversion instead of pausing there, and non-interactive harness calls are bounded by timeouts and turn caps so stuck agent runs fail fast instead of hanging forever. Recommend Claude Max account or codex equivalent, but be aware that GPT-5 - GPT5.2's slow reasoning and response makes this ponderous, it's fine overnight.
 
 Because LLMs are carrying out the work, we can specify a job of "Find all the python files in the project that directly or indirectly access sqlalchemy objects, and upgrade the code to work with sqlalchemy 2.* This will result in probably a single-task project, but that one task might add 50 other tasks (on per file) to the backlog, which are then processed sequentially."
 
@@ -59,6 +59,21 @@ pip install ralph-code
 ralph [OPTIONS] [DIRECTORY]
 ```
 
+## Recent changes
+
+Version `0.6.3` includes:
+- Safer git integration for staged-file commit checks
+- Correct staged diff generation
+- Deduplicated unstaged file reporting
+- Clearer errors when `git` is not available
+
+Version `0.6.2` includes:
+- Bounded non-interactive harness execution with timeout and turn limits
+- Structured `tasks.json` generation for more reliable PRD conversion
+- Automatic continuation after task generation by default
+- `PRDs/` as the standard task directory, with legacy `PRD/` compatibility
+- Refreshed model catalogs and current defaults
+
 ### Options
 
 - `--debug`: Enable debug logging, logs are saved into the .ralph subdirectory of the project
@@ -66,8 +81,8 @@ ralph [OPTIONS] [DIRECTORY]
 
 ## Usage
 
-First create a task, give a short name for the task (used for the branch commits will be added to), and then give a description. 
-Then you run the ralph-coder, it will produce a .md file of the specifications, which will be broken into small tasks put into a tasks.json file. Each task will be worked on independently. 
+First create a task in `PRDs/`, give a short name for the task (used for the branch commits will be added to), and then give a description.
+Then you run `ralph`, it will produce a `.md` file of the specifications, which will be broken into small tasks put into a `tasks.json` file. Each task will be worked on independently.
 
 ## Requirements
 

{ralph_code-0.6.1 → ralph_code-0.6.3}/README.md

@@ -1,6 +1,6 @@
 # ralph-code
 
-Automated task implementation with Claude Code and Codex for "Ralph Coding". What is [Ralph Coding](https://ghuntley.com/ralph/)? It's a method of coding where context rot is avoided by controlling the retention of information. This method involves re-invoking claude or codex for each task, and passing information about the requirements, acceptance testing, and any progress that's made (or roadblocks/challenges faced) through files, rather than retaining all prompts + thinking + response tokens. It tends to result in more requests, some duplicated token work, but fairly consistent performance, and best of all it can largely be done unattended. Recommend Claude Max account or codex equivalent, but be aware that GPT-5 - GPT5.2's slow reasoning and response makes this ponderous, it's fine overnight.
+Automated task implementation with Claude Code and Codex for "Ralph Coding". What is [Ralph Coding](https://ghuntley.com/ralph/)? It's a method of coding where context rot is avoided by controlling the retention of information. This method involves re-invoking claude or codex for each task, and passing information about the requirements, acceptance testing, and any progress that's made (or roadblocks/challenges faced) through files, rather than retaining all prompts + thinking + response tokens. It tends to result in more requests, some duplicated token work, but fairly consistent performance, and best of all it can largely be done unattended. Ralph now defaults to continuing past PRD-to-task conversion instead of pausing there, and non-interactive harness calls are bounded by timeouts and turn caps so stuck agent runs fail fast instead of hanging forever. Recommend Claude Max account or codex equivalent, but be aware that GPT-5 - GPT5.2's slow reasoning and response makes this ponderous, it's fine overnight.
 
 Because LLMs are carrying out the work, we can specify a job of "Find all the python files in the project that directly or indirectly access sqlalchemy objects, and upgrade the code to work with sqlalchemy 2.* This will result in probably a single-task project, but that one task might add 50 other tasks (on per file) to the backlog, which are then processed sequentially."
 
@@ -22,6 +22,21 @@ pip install ralph-code
 ralph [OPTIONS] [DIRECTORY]
 ```
 
+## Recent changes
+
+Version `0.6.3` includes:
+- Safer git integration for staged-file commit checks
+- Correct staged diff generation
+- Deduplicated unstaged file reporting
+- Clearer errors when `git` is not available
+
+Version `0.6.2` includes:
+- Bounded non-interactive harness execution with timeout and turn limits
+- Structured `tasks.json` generation for more reliable PRD conversion
+- Automatic continuation after task generation by default
+- `PRDs/` as the standard task directory, with legacy `PRD/` compatibility
+- Refreshed model catalogs and current defaults
+
 ### Options
 
 - `--debug`: Enable debug logging, logs are saved into the .ralph subdirectory of the project
@@ -29,8 +44,8 @@ ralph [OPTIONS] [DIRECTORY]
 
 ## Usage
 
-First create a task, give a short name for the task (used for the branch commits will be added to), and then give a description. 
-Then you run the ralph-coder, it will produce a .md file of the specifications, which will be broken into small tasks put into a tasks.json file. Each task will be worked on independently. 
+First create a task in `PRDs/`, give a short name for the task (used for the branch commits will be added to), and then give a description.
+Then you run `ralph`, it will produce a `.md` file of the specifications, which will be broken into small tasks put into a `tasks.json` file. Each task will be worked on independently.
 
 ## Requirements
 

{ralph_code-0.6.1 → ralph_code-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ralph-code"
-version = "0.6.1"
+version = "0.6.3"
 description = "Automated task implementation with Claude Code and Codex"
 readme = "README.md"
 license = {text = "MIT"}

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/__init__.py

@@ -1,6 +1,6 @@
 """ralph-code: Automated task implementation with Claude Code and Codex."""
 
-__version__ = "0.1.0"
+__version__ = "0.6.3"
 __author__ = "Ralph Coding"
 
 from .app import RalphApp, main

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/app.py

@@ -559,7 +559,7 @@ class RalphApp:
         choices: list[Choice] = []
 
         for model_name, label in supported_models:
-            choices.append(Choice(title=model_name, value=model_name))
+            choices.append(Choice(title=f"{model_name} ({label})", value=model_name))
 
         # No models available - show alert and return
         if not choices:

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/config.py

@@ -14,11 +14,13 @@ DEFAULT_CONFIG = {
     "harness": "claude",
     "worker_model": "opus",
     "summary_model": "haiku",
+    "harness_timeout_seconds": 1800,
+    "non_interactive_max_turns": 12,
     "max_iterations": 10,
     "max_story_attempts": 3,
     "auto_spec_without_oversight": True,
     "pause_after_spec": False,
-    "pause_after_tasks": True,
+    "pause_after_tasks": False,
     "wait_on_rate_limit": True,
     "pause_on_completion": True,
     "always_build_tests": False,
@@ -63,7 +65,7 @@ class Config:
         if "worker_model" not in self._config:
             harness = self._config.get("harness", DEFAULT_CONFIG["harness"])
             if harness == "codex":
-                self._config["worker_model"] = "gpt-5.2-codex"
+                self._config["worker_model"] = "gpt-5.3-codex"
             else:
                 self._config["worker_model"] = "opus"
             needs_save = True
@@ -72,7 +74,7 @@ class Config:
         if "summary_model" not in self._config:
             harness = self._config.get("harness", DEFAULT_CONFIG["harness"])
             if harness == "codex":
-                self._config["summary_model"] = "gpt-5.2"
+                self._config["summary_model"] = "gpt-5.1-codex-mini"
             else:
                 self._config["summary_model"] = "haiku"
             needs_save = True
@@ -124,6 +126,26 @@ class Config:
         self._config["summary_model"] = value
         self._save()
 
+    @property
+    def harness_timeout_seconds(self) -> int:
+        """Maximum seconds to wait for a harness subprocess before aborting."""
+        return int(self._config.get("harness_timeout_seconds", 1800))
+
+    @harness_timeout_seconds.setter
+    def harness_timeout_seconds(self, value: int) -> None:
+        self._config["harness_timeout_seconds"] = max(1, value)
+        self._save()
+
+    @property
+    def non_interactive_max_turns(self) -> int:
+        """Maximum agent turns for non-interactive harness runs."""
+        return int(self._config.get("non_interactive_max_turns", 12))
+
+    @non_interactive_max_turns.setter
+    def non_interactive_max_turns(self, value: int) -> None:
+        self._config["non_interactive_max_turns"] = max(1, value)
+        self._save()
+
     @property
     def max_iterations(self) -> int:
         """Maximum iterations for implementation loop."""

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/git_manager.py

@@ -26,6 +26,8 @@ class GitManager:
                 check=check,
             )
             return result
+        except FileNotFoundError as e:
+            raise GitError("Git executable not found on PATH") from e
         except subprocess.CalledProcessError as e:
             raise GitError(f"Git command failed: git {' '.join(args)}\n{e.stderr}")
 
@@ -230,25 +232,33 @@ class GitManager:
 
         return self.commit(message)
 
+    def get_staged_files(self) -> list[str]:
+        """Get list of files currently staged for commit."""
+        result = self._run_git("diff", "--cached", "--name-only")
+        return [f for f in result.stdout.strip().split("\n") if f]
+
     def get_unstaged_files(self) -> list[str]:
         """Get list of files with unstaged changes (modified + untracked).
 
         Returns files that have changes not yet added to the staging area.
         This includes both modified tracked files and new untracked files.
         """
-        files = []
+        files: list[str] = []
+        seen: set[str] = set()
 
         # Get modified but unstaged files
         result = self._run_git("diff", "--name-only")
         for f in result.stdout.strip().split("\n"):
-            if f:
+            if f and f not in seen:
                 files.append(f)
+                seen.add(f)
 
         # Get untracked files
         result = self._run_git("ls-files", "--others", "--exclude-standard")
         for f in result.stdout.strip().split("\n"):
-            if f:
+            if f and f not in seen:
                 files.append(f)
+                seen.add(f)
 
         return files
 
@@ -259,7 +269,7 @@ class GitManager:
 
     def get_diff(self, staged: bool = False) -> str:
         """Get the current diff for stageable files only."""
-        files = self.get_stageable_files()
+        files = self.get_staged_files() if staged else self.get_stageable_files()
         if not files:
             return ""
 

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/harness.py

@@ -46,13 +46,19 @@ HarnessType = Literal["claude", "codex", "custom"]
 # These defaults are used when CLI model querying fails or isn't supported.
 DEFAULT_MODELS: dict[HarnessType, list[tuple[str, str]]] = {
     "claude": [
+        ("default", "Standard"),
         ("haiku", "Light"),
         ("sonnet", "Standard"),
         ("opus", "Standard"),
+        ("sonnet[1m]", "Extended"),
+        ("opusplan", "Planning"),
     ],
     "codex": [
         ("gpt-5.1-codex-mini", "Light"),
+        ("gpt-5.3-codex-spark", "Preview"),
+        ("gpt-5.3-codex", "Standard"),
         ("gpt-5.2-codex", "Standard"),
+        ("gpt-5.1-codex", "Standard"),
         ("gpt-5.1-codex-max", "Standard"),
         ("gpt-5.2", "Standard"),
     ],
@@ -61,13 +67,13 @@ DEFAULT_MODELS: dict[HarnessType, list[tuple[str, str]]] = {
 
 DEFAULT_WORKER_MODEL: dict[HarnessType, str] = {
     "claude": "opus",
-    "codex": "gpt-5.2-codex",
+    "codex": "gpt-5.3-codex",
     "custom": "",
 }
 
 DEFAULT_SUMMARY_MODEL: dict[HarnessType, str] = {
     "claude": "haiku",
-    "codex": "gpt-5.2",
+    "codex": "gpt-5.1-codex-mini",
     "custom": "",
 }
 

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/harness_runner.py

@@ -38,7 +38,7 @@ import time
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Callable
+from typing import Any, Callable
 
 from .config import get_config
 from .harness import Harness, HarnessType
@@ -80,7 +80,7 @@ HARNESS_MODEL_MAPPING: dict[HarnessType, dict[str, str]] = {
     "codex": {
         # Codex maps to OpenAI/Codex model names
         "haiku": "gpt-5.1-codex-mini",
-        "sonnet": "gpt-5.2-codex",
+        "sonnet": "gpt-5.3-codex",
         "opus": "gpt-5.1-codex-max",
     },
     "custom": {
@@ -201,19 +201,22 @@ class HarnessRunner:
         model: str | None = None,
         print_output: bool = True,
         allow_writes: bool = False,
+        output_format: str | None = None,
+        json_schema: dict[str, Any] | None = None,
+        max_turns: int | None = None,
     ) -> list[str]:
         """Build the harness CLI command with harness-specific flags.
 
         This method handles the differences in CLI interfaces between harness types:
 
         Claude CLI:
-            claude --model <model> --print [--dangerously-skip-permissions] -p "<prompt>"
+            claude --model <model> --print [--dangerously-skip-permissions] "<prompt>"
 
         Codex CLI (non-interactive):
             codex exec --model <model> --sandbox <mode> "<prompt>"
 
         Custom (defaults to Claude-like):
-            custom --model <model> --print [--dangerously-skip-permissions] -p "<prompt>"
+            custom --model <model> --print [--dangerously-skip-permissions] "<prompt>"
 
         Args:
             prompt: The prompt text to send to the harness.
@@ -228,6 +231,7 @@ class HarnessRunner:
         harness = self._get_harness()
         model = model or self._config.worker_model
         mapped_model = self._map_model(model)
+        effective_max_turns = max_turns if max_turns is not None else self._config.non_interactive_max_turns
 
         cmd = [harness.path]
 
@@ -239,6 +243,14 @@ class HarnessRunner:
             if print_output:
                 cmd.append("--print")
 
+            cmd.extend(["--max-turns", str(effective_max_turns)])
+
+            if output_format is not None:
+                cmd.extend(["--output-format", output_format])
+
+            if json_schema is not None:
+                cmd.extend(["--json-schema", json.dumps(json_schema)])
+
             if allow_writes:
                 cmd.append("--dangerously-skip-permissions")
 
@@ -283,6 +295,9 @@ class HarnessRunner:
         max_retries: int = 3,
         retry_delay: float = 60.0,
         allow_writes: bool = False,
+        output_format: str | None = None,
+        json_schema: dict[str, Any] | None = None,
+        max_turns: int | None = None,
     ) -> HarnessResponse:
         """
         Run a prompt through the harness CLI.
@@ -297,7 +312,14 @@ class HarnessRunner:
         Returns:
             HarnessResponse with the result
         """
-        cmd = self._build_command(prompt, model, allow_writes=allow_writes)
+        cmd = self._build_command(
+            prompt,
+            model,
+            allow_writes=allow_writes,
+            output_format=output_format,
+            json_schema=json_schema,
+            max_turns=max_turns if max_turns is not None else self._config.non_interactive_max_turns,
+        )
 
         self._log(f"Command: {' '.join(cmd)}")
         self._log(f"Prompt:\n{prompt}\n")
@@ -313,12 +335,16 @@ class HarnessRunner:
                     cwd=self.project_dir,
                     capture_output=True,
                     text=True,
+                    timeout=self._config.harness_timeout_seconds,
                     # Don't catch KeyboardInterrupt - let it propagate
                 )
 
                 output = result.stdout
                 error = result.stderr
 
+                if output_format == "json" and self._get_harness().type == "claude":
+                    output, error = self._extract_claude_json_result(output, error, result.returncode)
+
                 self._log(f"Output:\n{output}\n")
                 if error:
                     self._log(f"Error:\n{error}\n")
@@ -356,6 +382,15 @@ class HarnessRunner:
                     output="",
                     error=error_msg,
                 )
+            except subprocess.TimeoutExpired:
+                timeout = self._config.harness_timeout_seconds
+                error_msg = f"Harness timed out after {timeout}s"
+                self._log(f"Error: {error_msg}")
+                return HarnessResponse(
+                    success=False,
+                    output="",
+                    error=error_msg,
+                )
             except Exception as e:
                 error_msg = str(e)
                 self._log(f"Exception: {error_msg}")
@@ -372,6 +407,77 @@ class HarnessRunner:
             rate_limited=True,
         )
 
+    def _extract_claude_json_result(
+        self, output: str, error: str, returncode: int
+    ) -> tuple[str, str]:
+        """Extract the useful result from Claude's JSON envelope."""
+        stripped = output.strip()
+        if not stripped:
+            return output, error
+
+        try:
+            payload = json.loads(stripped)
+        except json.JSONDecodeError:
+            return output, error
+
+        if isinstance(payload, dict):
+            result = payload.get("result", payload)
+            if isinstance(result, str):
+                normalized_output = result
+            else:
+                normalized_output = json.dumps(result, ensure_ascii=False)
+
+            if returncode != 0 and not error:
+                error_value = payload.get("error") or payload.get("message") or normalized_output
+                error = str(error_value)
+
+            return normalized_output, error
+
+        return output, error
+
+    def run_structured(
+        self,
+        prompt: str,
+        json_schema: dict[str, Any],
+        model: str | None = None,
+        allow_writes: bool = False,
+    ) -> tuple[HarnessResponse, dict[str, Any] | None]:
+        """Run a prompt expecting a schema-validated JSON object."""
+        harness = self._get_harness()
+        response = self.run(
+            prompt,
+            model=model,
+            allow_writes=allow_writes,
+            output_format="json" if harness.type == "claude" else None,
+            json_schema=json_schema if harness.type == "claude" else None,
+        )
+        if not response.success:
+            return response, None
+
+        try:
+            parsed = json.loads(response.output)
+        except json.JSONDecodeError as exc:
+            return (
+                HarnessResponse(
+                    success=False,
+                    output=response.output,
+                    error=f"Structured output was not valid JSON: {exc}",
+                ),
+                None,
+            )
+
+        if not isinstance(parsed, dict):
+            return (
+                HarnessResponse(
+                    success=False,
+                    output=response.output,
+                    error="Structured output was not a JSON object",
+                ),
+                None,
+            )
+
+        return response, parsed
+
     def create_prd(self, task_description: str, learnings: str = "") -> HarnessResponse:
         """
         Create a PRD (Product Requirements Document) for a task using the prd skill format.
@@ -673,25 +779,66 @@ IMPORTANT RULES:
 8. All stories start with passes: false
 9. branchName MUST start with "{branch_prefix}/" (use lowercase letters, numbers, and hyphens only)
 
-Output ONLY valid JSON in the exact format below, nothing else:
-{{
-  "project": "{project_name}",
-  "branchName": "{branch_prefix}/feature-name-here",
-  "description": "Feature description here",
-  "userStories": [
-    {{
-      "id": "US-001",
-      "title": "Story title",
-      "description": "As a [user], I want [feature] so that [benefit]",
-      "acceptanceCriteria": ["criterion 1", "criterion 2", "Typecheck passes"],
-      "priority": 1,
-      "passes": false,
-      "notes": ""
-    }}
-  ]
-}}"""
+Return a JSON object only. Do not wrap it in markdown fences."""
+
+        schema: dict[str, Any] = {
+            "type": "object",
+            "required": ["project", "branchName", "description", "userStories"],
+            "properties": {
+                "project": {"type": "string", "const": project_name},
+                "branchName": {
+                    "type": "string",
+                    "pattern": rf"^{re.escape(branch_prefix)}/[a-z0-9-]+$",
+                },
+                "description": {"type": "string", "minLength": 1},
+                "userStories": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "id",
+                            "title",
+                            "description",
+                            "acceptanceCriteria",
+                            "priority",
+                            "passes",
+                        ],
+                        "properties": {
+                            "id": {"type": "string", "pattern": r"^US-[0-9]{3}$"},
+                            "title": {"type": "string", "minLength": 1},
+                            "description": {"type": "string", "minLength": 1},
+                            "acceptanceCriteria": {
+                                "type": "array",
+                                "minItems": 1,
+                                "items": {"type": "string", "minLength": 1},
+                            },
+                            "priority": {"type": "integer", "minimum": 1},
+                            "passes": {"type": "boolean", "const": False},
+                            "notes": {"type": "string"},
+                        },
+                        "additionalProperties": False,
+                    },
+                },
+            },
+            "additionalProperties": False,
+        }
+
+        response, parsed = self.run_structured(
+            prompt,
+            json_schema=schema,
+            model=self._config.summary_model,
+        )
+        if not response.success or parsed is None:
+            return response
 
-        return self.run(prompt, model=self._config.summary_model)
+        return HarnessResponse(
+            success=True,
+            output=json.dumps(parsed, indent=2, ensure_ascii=False),
+            error=response.error,
+            rate_limited=response.rate_limited,
+            cost=response.cost,
+        )
 
     def implement_story(self, story_prompt: str, context: str = "") -> HarnessResponse:
         """
@@ -739,31 +886,30 @@ After implementation, verify each acceptance criterion is met."""
 GIT DIFF OF CHANGES:
 {git_diff if git_diff else "(No changes detected)"}
 
-Check each acceptance criterion and determine if it has been met.
+	Check each acceptance criterion and determine if it has been met.
 
-IMPORTANT: Distinguish between these scenarios:
-1. PASSES - All acceptance criteria are verifiably met (or irrelevant - see below)
-2. FAILS - One or more criteria are NOT met (implementation is wrong/incomplete)
-3. BLOCKED - Some criteria CANNOT BE VERIFIED due to external factors (permission issues,
-   pre-existing errors unrelated to this change, environment constraints, etc.)
+	IMPORTANT: Distinguish between these scenarios:
+	1. PASSES - All acceptance criteria are verifiably met
+	2. FAILS - One or more criteria are NOT met (implementation is wrong/incomplete)
+	3. BLOCKED - Some criteria CANNOT BE VERIFIED due to external factors (permission issues,
+	   pre-existing errors unrelated to this change, environment constraints, etc.)
 
-HANDLING IRRELEVANT OR NONSENSICAL CRITERIA:
-- If a criterion is based on an erroneous assumption (e.g., "update file X for library Y" but
-  file X doesn't use library Y), treat it as PASSED by virtue of being irrelevant.
-- If a criterion seems nonsensical or impossible, question it and explain why it doesn't apply.
-- These criteria may have been auto-generated by earlier processes and don't reflect reality.
-- Mark such criteria as passed with a note explaining why they're not applicable.
+	HANDLING AMBIGUOUS OR NONSENSICAL CRITERIA:
+	- Do NOT auto-pass criteria as "N/A" or "irrelevant".
+	- If a criterion is based on a bad assumption, contradictory, or impossible to satisfy as written,
+	  mark it as FAILED and explain precisely why.
+	- In "To Complete", include concrete guidance to correct that criterion/story definition.
+	- Use BLOCKED only when verification is impossible due to external constraints, not because criteria are poor.
 
 Respond in this exact format:
 
 STATUS: PASSES or FAILS or BLOCKED
 NOTES:
-**What Passed:**
-- ✅ List each criterion that was clearly met
-- ✅ List criteria that are N/A with explanation (e.g., "N/A - file doesn't use this library")
+	**What Passed:**
+	- ✅ List each criterion that was clearly met
 
-**What Failed:**
-- ❌ List each criterion that was NOT met (implementation issue)
+	**What Failed:**
+	- ❌ List each criterion that was NOT met, including malformed/incorrect criteria
 
 **What Could Not Be Verified:**
 - ⚠️ List criteria that cannot be verified with reasons (e.g., "Tests execution - requires permission")

{ralph_code-0.6.1 → ralph_code-0.6.3}/ralph/prd_manager.py

@@ -38,6 +38,11 @@ def slugify(text: str) -> str:
     return slug[:50]  # Limit length
 
 
+def stable_prd_id(file_path: Path) -> str:
+    """Generate a deterministic PRD ID from file path."""
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, str(file_path.resolve())))
+
+
 @dataclass
 class PRD:
     """Represents a Product Requirements Document."""
@@ -58,7 +63,7 @@ class PRD:
         content = file_path.read_text().strip()
         name = file_path.stem  # filename without extension
         return cls(
-            id=str(uuid.uuid4()),
+            id=stable_prd_id(file_path),
             name=name,
             file_path=file_path,
             is_specced=False,
@@ -119,7 +124,7 @@ class PRD:
             status = "errored"
 
         return cls(
-            id=str(uuid.uuid4()),
+            id=stable_prd_id(file_path),
             name=name,
             file_path=file_path,
             is_specced=True,
@@ -155,11 +160,22 @@ class PRDManager:
 
     def __init__(self, project_dir: Path):
         self.project_dir = project_dir
-        self.prd_dir = project_dir / "PRD"
+        self.prd_dir = self._resolve_prd_dir()
         self._ensure_prd_dir()
         self._prds: list[PRD] = []
         self._load()
 
+    def _resolve_prd_dir(self) -> Path:
+        """Resolve the active PRD directory, supporting the legacy singular path."""
+        plural_dir = self.project_dir / "PRDs"
+        legacy_dir = self.project_dir / "PRD"
+
+        if plural_dir.exists():
+            return plural_dir
+        if legacy_dir.exists():
+            return legacy_dir
+        return plural_dir
+
     def _ensure_prd_dir(self) -> None:
         """Ensure PRD directory exists."""
         self.prd_dir.mkdir(parents=True, exist_ok=True)