@lnilluv/pi-ralph-loop 0.1.1 → 0.1.4-dev.0

package/.github/workflows/ci.yml

@@ -17,13 +17,16 @@ jobs:
       - name: Checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
 
-      - name: Setup Node.js 22
+      - name: Setup Node.js 22.22.1
         uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
         with:
-          node-version: 22
+          node-version: 22.22.1
 
       - name: Install dependencies
         run: npm ci --ignore-scripts
 
+      - name: Test
+        run: npm test
+
       - name: Typecheck
         run: npm run typecheck

package/.github/workflows/release.yml

@@ -24,15 +24,18 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup Node.js 22
+      - name: Setup Node.js 24.14.1
         uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
         with:
-          node-version: 22
+          node-version: 24.14.1
           registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: npm ci --ignore-scripts
 
+      - name: Test
+        run: npm test
+
       - name: Typecheck
         run: npm run typecheck
 
@@ -119,11 +122,11 @@ jobs:
 
       - name: Publish (main)
         if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
-        run: npx npm@11 publish --access public --provenance
+        run: npx -y npm@11.12.1 publish --access public --provenance
 
       - name: Publish (dev prerelease)
         if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'dev'
-        run: npx npm@11 publish --access public --provenance --tag dev
+        run: npx -y npm@11.12.1 publish --access public --provenance --tag dev
 
       - name: Commit version bump and tag
         if: steps.bump.outputs.should_release == 'true'

package/README.md

@@ -10,12 +10,14 @@ pi install npm:@lnilluv/pi-ralph-loop
 
 ## Quick start
 
+### Run an existing task folder
+
 ```md
 # my-task/RALPH.md
 ---
 commands:
   - name: tests
-    run: npm test -- --runInBand
+    run: npm test
     timeout: 60
 ---
 Fix failing tests using this output:
@@ -23,11 +25,61 @@ Fix failing tests using this output:
 {{ commands.tests }}
 ```
 
-Run `/ralph my-task` in pi.
+Run:
+
+```text
+/ralph my-task
+```
+
+### Draft a loop from natural language
+
+```text
+/ralph reverse engineer this app
+```
+
+pi drafts `./reverse-engineer-this-app/RALPH.md`, shows a short Mission Brief, lets you edit the file, and only starts after you confirm.
+
+### Draft without starting
+
+```text
+/ralph-draft fix flaky auth tests
+```
+
+That saves the draft but does not launch the loop.
+
+### Smart drafting
+
+Smart drafting sends the selected repo excerpts from the current repo context to the currently selected active pi model, including models chosen with `/model` or by cycling within `/scoped-models`. It excludes common secret-bearing paths from that context, and non-analysis drafts use the shared `policy:secret-bearing-paths` token so runtime write protection stays aligned with the same policy. It does not switch models automatically. If no active authenticated model is available, drafting falls back to the deterministic path.
 
 ## How it works
 
-On each iteration, pi-ralph reads `RALPH.md`, runs the configured commands, injects their output into the prompt through `{{ commands.<name> }}` placeholders, starts a fresh session, sends the prompt, and waits for completion. Failed test output appears in the next iteration, which creates a self-healing loop.
+On each iteration, pi-ralph reads `RALPH.md`, runs the configured commands, injects their output into the prompt through `{{ commands.<name> }}` placeholders, starts a fresh session, sends the prompt, and waits for completion. Failed command output appears in the next iteration, which creates a self-healing loop.
+
+## Smart `/ralph` behavior
+
+`/ralph` is path-first:
+
+- task folder with `RALPH.md` -> runs it
+- direct `RALPH.md` path -> runs it
+- no args in a folder without `RALPH.md` -> asks what the loop should work on, drafts `./RALPH.md`, then asks before starting
+- natural-language task -> drafts `./<slug>/RALPH.md`, then asks before starting
+- unresolved path-like input like `foo/bar` or `notes.md` -> offers recovery choices and normalizes missing markdown targets to `./<folder>/RALPH.md`
+- arbitrary markdown files like `README.md` -> rejected instead of auto-run
+
+### Explicit flags
+
+Use these when you want to skip heuristics:
+
+```text
+/ralph --path my-task
+/ralph --task "reverse engineer the billing flow"
+/ralph-draft --path my-task
+/ralph-draft --task "fix flaky auth tests"
+```
+
+### Interactive review
+
+Draft flows require an interactive UI because the extension uses a Mission Brief and editor dialog before saving or starting. In non-interactive contexts, pass an existing task folder or `RALPH.md` path instead.
 
 ## RALPH.md format
 
@@ -35,12 +87,14 @@ On each iteration, pi-ralph reads `RALPH.md`, runs the configured commands, inje
 ---
 commands:
   - name: tests
-    run: npm test -- --runInBand
+    run: npm test
     timeout: 90
   - name: lint
     run: npm run lint
     timeout: 60
 max_iterations: 25
+timeout: 300
+completion_promise: "DONE"
 guardrails:
   block_commands:
     - "rm\\s+-rf\\s+/"
@@ -51,12 +105,15 @@ guardrails:
 ---
 You are fixing flaky tests in the auth module.
 
+<!-- This comment is stripped before sending to the agent -->
+
 Latest test output:
 {{ commands.tests }}
 
 Latest lint output:
 {{ commands.lint }}
 
+Iteration {{ ralph.iteration }} of {{ ralph.name }}.
 Apply the smallest safe fix and explain why it works.
 ```
 
@@ -67,19 +124,32 @@ Apply the smallest safe fix and explain why it works.
 | `commands[].run` | string | required | Shell command |
 | `commands[].timeout` | number | `60` | Seconds before kill |
 | `max_iterations` | number | `50` | Stop after N iterations |
+| `timeout` | number | `300` | Per-iteration timeout in seconds; stops the loop if the agent is stuck |
+| `completion_promise` | string | — | Agent signals completion by sending `<promise>DONE</promise>`; loop breaks on match |
 | `guardrails.block_commands` | string[] | `[]` | Regex patterns to block in bash |
-| `guardrails.protected_files` | string[] | `[]` | Glob patterns to block writes |
+| `guardrails.protected_files` | string[] | `[]` | Glob patterns, or the shared `policy:secret-bearing-paths` token, enforced on `write`/`edit` tool calls |
+
+### Placeholders
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{{ commands.<name> }}` | Output from the named command |
+| `{{ ralph.iteration }}` | Current 1-based iteration number |
+| `{{ ralph.name }}` | Directory name containing the `RALPH.md` |
+
+HTML comments (`<!-- ... -->`) are stripped from the prompt body after placeholder resolution, so you can annotate your `RALPH.md` freely. Generated drafts also escape literal `<!--` and `-->` in the visible task line, and the leading metadata comment is URL-encoded so task text can safely contain comment-like sequences.
 
 ## Commands
 
-- `/ralph <path>`: Start the loop from a `RALPH.md` file or directory.
-- `/ralph-stop`: Request a graceful stop after the current iteration.
+- `/ralph [path-or-task]` - Start Ralph from a task folder or `RALPH.md`, or draft a new loop from natural language.
+- `/ralph-draft [path-or-task]` - Draft or edit a Ralph task without starting it.
+- `/ralph-stop` - Request a graceful stop after the current iteration.
 
 ## Pi-only features
 
 ### Guardrails
 
-`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook. Matching bash commands are blocked, and writes/edits to protected file globs are denied.
+`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook — but only for sessions created by the loop, so they don't leak into unrelated conversations. Matching bash commands are blocked, and `write`/`edit` tool calls targeting protected file globs or the shared secret-path policy token are denied.
 
 ### Cross-iteration memory
 
@@ -89,17 +159,33 @@ After each iteration, the extension stores a short summary with iteration number
 
 In the `tool_result` hook, bash outputs are scanned for failure patterns. After three or more failures in the same iteration, the extension appends a stop-and-think warning to push root-cause analysis before another retry.
 
+### Completion promise
+
+When `completion_promise` is set (for example, `"DONE"`), the loop scans the agent's messages for `<promise>DONE</promise>` after each iteration. If found, the loop stops early.
+
+### Iteration timeout
+
+Each iteration has a configurable timeout (default 300 seconds). If the agent is stuck and doesn't become idle within the timeout, the loop stops with a warning.
+
+### Input validation
+
+The extension validates `RALPH.md` frontmatter before starting and on each re-parse: `max_iterations` must be a positive integer, `timeout` must be positive, `block_commands` regexes must compile, and commands must have non-empty names and run strings with positive timeouts.
+
 ## Comparison table
 
 | Feature | **@lnilluv/pi-ralph-loop** | pi-ralph | pi-ralph-wiggum | ralphi | ralphify |
-|---------|------------------------|----------------------|-----------------|--------|----------|
+|---------|----------------------------|----------|-----------------|--------|----------|
 | Command output injection | ✓ | ✗ | ✗ | ✗ | ✓ |
 | Fresh-context sessions | ✓ | ✓ | ✗ | ✓ | ✓ |
 | Mid-turn guardrails | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Cross-iteration memory | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Mid-turn steering | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Live prompt editing | ✓ | ✗ | ✗ | ✗ | ✓ |
-| Setup required | RALPH.md | config | RALPH.md | PRD pipeline | RALPH.md |
+| Guided task drafting | ✓ | ✗ | ✗ | ✗ | separate scaffold |
+| Completion promise | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Iteration timeout | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Session-scoped hooks | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Input validation | ✓ | ✗ | ✗ | ✗ | ✗ |
+| Setup required | task folder or draft flow | config | RALPH.md | PRD pipeline | scaffold + RALPH.md |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lnilluv/pi-ralph-loop",
-  "version": "0.1.1",
+  "version": "0.1.4-dev.0",
   "description": "Pi-native ralph loop — autonomous coding iterations with mid-turn supervision",
   "type": "module",
   "pi": {
@@ -8,7 +8,11 @@
       "./src/index.ts"
     ]
   },
+  "engines": {
+    "node": "22.22.1 || 24.14.1"
+  },
   "scripts": {
+    "test": "node --test --experimental-strip-types $(find tests -type f -name '*.ts' | sort)",
     "typecheck": "tsc --noEmit"
   },
   "repository": {
@@ -16,8 +20,9 @@
     "url": "git+https://github.com/lnilluv/pi-ralph-loop.git"
   },
   "dependencies": {
-    "yaml": "2.8.3",
-    "minimatch": "10.2.3"
+    "@mariozechner/pi-ai": "0.66.1",
+    "minimatch": "10.2.3",
+    "yaml": "2.8.3"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*"
@@ -28,5 +33,9 @@
     "autonomous",
     "loop"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "typescript": "6.0.2"
+  }
 }