plugins/ralph-speckit/commands/implement.md (1)

477-477: Update termination wording to reflect stop-hook control.

Line 477 states "This signal terminates the Ralph Loop loop." If the PR is removing the Ralph Loop dependency and moving to internal stop-hook control, this wording should be updated.

Suggested revision

-This signal terminates the Ralph Loop loop.
+This signal tells the stop-hook to end the execution loop.

.github/workflows/test.yml (1)

54-72: Install jq explicitly in lint-json for reproducibility.

lint-json assumes jq exists on the runner; installing it avoids failures if the base image changes.

♻️ Suggested update

   lint-json:
     name: Lint JSON
     runs-on: ubuntu-latest

     steps:
       - name: Checkout
         uses: actions/checkout@v4

+      - name: Install jq
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq
+
       - name: Validate plugin.json
         run: |
           jq empty plugins/ralph-specum/.claude-plugin/plugin.json

plugins/ralph-specum/tests/stop-watcher.bats (1)

27-31: Potential issue: run_hook doesn't capture stderr.

The helper pipes input to the script but doesn't capture stderr. If stop-watcher.sh writes errors to stderr, they won't be visible in test output, making debugging harder.

Consider capturing stderr for better diagnostics

 # Helper to run stop-watcher with test input
 run_hook() {
     local input="$1"
-    echo "$input" | "$STOP_WATCHER"
+    echo "$input" | "$STOP_WATCHER" 2>&1
 }

specs/ralph-integration-research/requirements.md (1)

121-129: Minor clarification needed in Out of Scope section.

Line 128 states "Migration tooling for existing users (v2.0 users already have ralph-loop)" but since v3.0 removes ralph-loop, existing v2.0 users will need to transition. The migration guide in MIGRATION.md addresses this, but this out-of-scope item could be clearer.

Consider rewording for clarity

-- Migration tooling for existing users (v2.0 users already have ralph-loop)
+- Automated migration tooling (manual steps documented in MIGRATION.md)

specs/ralph-integration-research/design.md (1)

515-516: Consider adding language identifiers to code blocks.

The code blocks on lines 515 and 533 are missing language specifiers. While these contain pseudo-formulas rather than executable code, you could use a generic identifier like text or plaintext to satisfy the linter.

♻️ Proposed fix

 ### Prioritization Formula
 
-```
+```text
 Priority Score = (Dep_Weight × Unblocks_Count)
                + (Risk_Weight × Uncertainty_Score)
                + (Value_Weight × Impact_Score)

And similarly for line 533:

```diff
 ### Scoring Algorithm
 
-```
+```text
 1. Build dependency graph from task descriptions
 2. For each task:
    a. Count tasks it unblocks (Unblocks_Count)

Also applies to: 533-534

plugins/ralph-specum/commands/implement.md (3)

45-49: Clarify stop-hook behavior in comment.

The comment on line 49 says "The stop-hook will inject this prompt when blocking exit," but the stop-hook actually injects a message that references the file path (see design.md line 225). The agent must read the file themselves. Consider clarifying to: "The stop-hook will reference this file path when blocking exit, instructing the agent to read and follow these instructions."

♻️ Proposed clarification

 Write the ENTIRE coordinator prompt (from section below) to `./specs/$spec/.coordinator-prompt.md`.
 
-This file contains the full instructions for task execution. The stop-hook will inject this prompt when blocking exit.
+This file contains the full instructions for task execution. The stop-hook will reference this file path when blocking exit, instructing the agent to read and follow these instructions.

---

72-79: Update state schema documentation to include new fields.

The state schema example on lines 72-79 is missing the newly added globalIteration and maxGlobalIterations fields (initialized on lines 40-41). While the coordinator doesn't directly use these fields (they're for stop-hook iteration tracking), the documentation should reflect the complete state file structure for accuracy.

♻️ Proposed update to match complete schema

 ```json
 {
   "phase": "execution",
   "taskIndex": <current task index, 0-based>,
   "totalTasks": <total task count>,
   "taskIteration": <retry count for current task>,
-  "maxTaskIterations": <max retries>
+  "maxTaskIterations": <max retries>,
+  "globalIteration": <current global iteration>,
+  "maxGlobalIterations": <max global iterations before forced stop>
 }

Add a note below the schema:

```markdown
Note: `globalIteration` and `maxGlobalIterations` are managed by the stop-hook for loop safety and are not directly used by the coordinator.

---

426-438: Consider adding language specifier for output message block.

The code block starting on line 426 is missing a language specifier, which triggers a markdown linter warning. You can add text or markdown to satisfy the linter:

♻️ Proposed fix

 ## Output on Start
 
-```
+```text
 Starting execution for '$spec'

plugins/ralph-specum/skills/smart-ralph/SKILL.md (1)

108-110: Clarify the coordinator prompt file path.

The path <spec-path>/.coordinator-prompt.md uses a placeholder. For better clarity, consider specifying the actual path pattern (e.g., .specify/specs/<feature-name>/.coordinator-prompt.md) to help users understand where to find or debug coordinator prompt files.

📝 Suggested clarification

 ### Coordinator Prompt File
 
 Write coordinator prompt to file for stop-hook injection:
 - Stop-hook injects continuation prompt referencing this file
 - Enables complex multi-line coordinator instructions
-- Path: `<spec-path>/.coordinator-prompt.md`
+- Path: `.specify/specs/<feature-name>/.coordinator-prompt.md`

specs/ralph-integration-research/research.md (1)

109-114: Add language identifiers to fenced code blocks.

The code blocks at lines 110-114 and 163-171 lack language identifiers, which triggers markdownlint MD040. Adding text as the language identifier improves rendering consistency.

plugins/ralph-specum/hooks/scripts/stop-watcher.sh (1)

88-93: Orphaned temp files not cleaned on max iterations path.

When max iterations is reached (lines 88-93), the state file is deleted but orphaned .progress-task-*.md files are not cleaned up, unlike the completion path (line 83). Consider adding the same cleanup for consistency.

♻️ Proposed fix

 # Safety limit check (FR-7, FR-8)
 if [ "$GLOBAL_ITER" -ge "$MAX_ITER" ]; then
     echo "[ralph-specum] Max iterations ($MAX_ITER) reached for: $SPEC_NAME" >&2
     rm -f "$STATE_FILE" 2>/dev/null || true
+    # Cleanup orphaned temp progress files
+    find "$CWD/specs/$SPEC_NAME" -name ".progress-task-*.md" -mmin +60 -delete 2>/dev/null || true
     exit 0
 fi

specs/ralph-integration-research/tasks.md (1)

233-240: Consider adding jq availability documentation.

The notes section mentions "Consider adding jq availability warning in implement.md" as a production TODO. Given that the stop-hook silently exits when jq is unavailable (line 22 of stop-watcher.sh), documenting this dependency in user-facing docs would help users understand why execution might not block as expected.

Would you like me to draft the jq availability warning text for implement.md?

specs/ralph-integration-research/design.md (1)

216-218: Design pseudocode differs from final implementation.

The atomic update in the design pseudocode (lines 216-218) doesn't include the jq exit-status guard that was added to the actual implementation following a previous review. Consider updating the design doc to reflect the final, safer implementation pattern for future reference.

📝 Suggested update to match implementation

 # 10. Update iteration counter
-jq ".globalIteration = $((GLOBAL_ITER + 1))" "$STATE_FILE" > "$STATE_FILE.tmp"
-mv "$STATE_FILE.tmp" "$STATE_FILE"
+if jq ".globalIteration = $((GLOBAL_ITER + 1))" "$STATE_FILE" > "$STATE_FILE.tmp" 2>/dev/null; then
+    mv "$STATE_FILE.tmp" "$STATE_FILE"
+else
+    rm -f "$STATE_FILE.tmp"
+fi

plugins/ralph-specum/commands/implement.md (1)

230-236: Parallel Task tool calls should not concurrently edit tasks.md.

The parallel execution section still instructs each Task tool call to mark tasks in tasks.md, which risks conflicts and lost updates when multiple tasks run concurrently. Prefer having the coordinator update tasks.md after all parallel tasks finish, and keep per-task output isolated to temp progress files.

♻️ Suggested doc tweak to avoid concurrent edits

- For each task index in parallelGroup.taskIndices, create a Task tool call with:
- - Unique progressFile: `.progress-task-$taskIndex.md`
- - Full task block from tasks.md
- - Same instructions as sequential but writing to temp progress file
+ For each task index in parallelGroup.taskIndices, create a Task tool call with:
+ - Unique progressFile: `.progress-task-$taskIndex.md`
+ - Full task block from tasks.md
+ - Same instructions as sequential but writing to temp progress file
+ - DO NOT edit tasks.md in parallel tasks; coordinator will apply checkmarks after merge

Based on learnings, ensure task progress persists correctly and task checkmarks are applied deterministically.

Also applies to: 257-267