@lnilluv/pi-ralph-loop 0.2.1 → 0.3.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 24
+      - name: Setup Node.js 24.14.1
         uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af
         with:
-          node-version: 24
+          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,57 @@ 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.
 
 ## 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,7 +83,7 @@ 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
@@ -75,7 +123,7 @@ Apply the smallest safe fix and explain why it works.
 | `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 enforced on `write`/`edit` tool calls |
 
 ### Placeholders
 
@@ -83,20 +131,21 @@ Apply the smallest safe fix and explain why it works.
 |-------------|-------------|
 | `{{ commands.<name> }}` | Output from the named command |
 | `{{ ralph.iteration }}` | Current 1-based iteration number |
-| `{{ ralph.name }}` | Directory name containing the RALPH.md |
+| `{{ 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.
+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 — but only for sessions created by the loop, so they don't leak into unrelated conversations. 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 are denied.
 
 ### Cross-iteration memory
 
@@ -108,11 +157,11 @@ In the `tool_result` hook, bash outputs are scanned for failure patterns. After
 
 ### Completion promise
 
-When `completion_promise` is set (e.g., `"DONE"`), the loop scans the agent's messages for `<promise>DONE</promise>` after each iteration. If found, the loop stops early — the agent signals it's finished rather than relying solely on `max_iterations`.
+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. This prevents runaway iterations from running forever.
+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
 
@@ -121,20 +170,19 @@ The extension validates `RALPH.md` frontmatter before starting and on each re-pa
 ## 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 | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Guided task drafting | ✓ | ✗ | ✗ | ✗ | separate scaffold |
 | Completion promise | ✓ | ✗ | ✗ | ✗ | ✓ |
 | Iteration timeout | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Session-scoped hooks | ✓ | ✗ | ✗ | ✗ | ✗ |
 | Input validation | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Setup required | RALPH.md | config | RALPH.md | PRD pipeline | RALPH.md |
+| Setup required | task folder or draft flow | config | RALPH.md | PRD pipeline | scaffold + RALPH.md |
 
 ## License
 
 MIT
-# CI provenance test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lnilluv/pi-ralph-loop",
-  "version": "0.2.1",
+  "version": "0.3.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,8 @@
     "url": "git+https://github.com/lnilluv/pi-ralph-loop.git"
   },
   "dependencies": {
-    "yaml": "2.8.3",
-    "minimatch": "10.2.3"
+    "minimatch": "10.2.3",
+    "yaml": "2.8.3"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*"
@@ -29,5 +33,9 @@
     "autonomous",
     "loop"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "typescript": "6.0.2"
+  }
 }