ralph-cli-sandboxed 0.6.2 → 0.6.4

package/docs/RALPH-SETUP-TEMPLATE.md

@@ -89,29 +89,30 @@ Set up a Ralph CLI project based on the configuration above.
 
 | Stack | language | checkCommand | testCommand |
 |-------|----------|--------------|-------------|
-| Node/TS (pnpm) | `typescript` | `pnpm lint && pnpm build` | `pnpm test` |
-| Node/TS (npm) | `node` | `npm run lint && npm run build` | `npm test` |
-| Node/TS (bun) | `typescript` | `bun run lint && bun run build` | `bun test` |
-| Python (pip) | `python` | `mypy . && ruff check .` | `pytest` |
-| Python (poetry) | `python` | `poetry run mypy . && poetry run ruff check .` | `poetry run pytest` |
-| Python (uv) | `python` | `uv run mypy . && uv run ruff check .` | `uv run pytest` |
-| Go | `go` | `go build ./... && go vet ./...` | `go test ./...` |
-| Rust | `rust` | `cargo build && cargo clippy` | `cargo test` |
-
-### Required Domains by Tech Stack
-
-| Stack | Package Registry Domains |
-|-------|--------------------------|
-| Node.js | `registry.npmjs.org`, `github.com` |
-| Python | `pypi.org`, `files.pythonhosted.org`, `github.com` |
-| Go | `proxy.golang.org`, `sum.golang.org`, `github.com` |
-| Rust | `crates.io`, `static.crates.io`, `github.com` |
+| Node/TS (npm) | `node` | `npm run typecheck` | `npm test` |
+| Node/TS (bun) | `bun` | `bun check` | `bun test` |
+| Python | `python` | `mypy .` | `pytest` |
+| Go | `go` | `go build ./...` | `go test ./...` |
+| Rust | `rust` | `cargo check` | `cargo test` |
+
+### Firewall Domains
+
+The Docker firewall allows these domains by default: `github.com`, `api.github.com`, `raw.githubusercontent.com`, `registry.npmjs.org`, `api.anthropic.com`.
+
+Add additional domains to `docker.firewall.allowedDomains` in `.ralph/config.json` based on your stack:
+
+| Stack | Recommended Additions |
+|-------|----------------------|
+| Python | `pypi.org`, `files.pythonhosted.org` |
+| Go | `proxy.golang.org`, `sum.golang.org` |
+| Rust | `crates.io`, `static.crates.io` |
 
 ### API Provider Domains
 
+Add these to `docker.firewall.allowedDomains` if using external APIs:
+
 | Provider | Domains |
 |----------|---------|
-| Anthropic Claude | `api.anthropic.com` |
 | OpenAI | `api.openai.com` |
 | Google AI | `generativelanguage.googleapis.com` |
 | AWS | `*.amazonaws.com` |
@@ -124,6 +125,8 @@ Set up a Ralph CLI project based on the configuration above.
 
 ### Notifications Config
 
+Supported providers: `ntfy`, `pushover`, `gotify`, `command`.
+
 Using ntfy (recommended - no install needed):
 ```json
 {
@@ -137,6 +140,32 @@ Using ntfy (recommended - no install needed):
 }
 ```
 
+Using pushover:
+```json
+{
+  "notifications": {
+    "provider": "pushover",
+    "pushover": {
+      "user": "your-user-key",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
+Using gotify:
+```json
+{
+  "notifications": {
+    "provider": "gotify",
+    "gotify": {
+      "server": "https://gotify.example.com",
+      "token": "your-app-token"
+    }
+  }
+}
+```
+
 Using custom command:
 ```json
 {
@@ -205,10 +234,14 @@ Log task completions and ralph finished to file:
 ```
 
 Chat commands (send in Telegram):
-- `/run` - Start ralph automation
+- `/run [category]` - Start ralph automation
 - `/status` - Show PRD progress
+- `/stop` - Stop a running ralph process
 - `/add [desc]` - Add new task
 - `/exec [cmd]` - Execute shell command
+- `/action [name]` - Execute a daemon action
+- `/claude [prompt]` - Run Claude Code with a prompt
+- `/branch [subcommand]` - Manage git branches
 - `/help` - Show help
 
 ### PRD Task Categories
@@ -216,12 +249,11 @@ Chat commands (send in Telegram):
 | Category | Use For |
 |----------|---------|
 | `setup` | Project initialization, dependency installation |
-| `config` | Environment variables, configuration files |
 | `feature` | New functionality implementation |
-| `integration` | External API clients, third-party services |
-| `test` | Unit tests, integration tests |
-| `refactor` | Code restructuring without behavior change |
 | `bugfix` | Bug fixes |
+| `ui` | User interface changes |
+| `development` | Development tooling, build configuration |
+| `testing` | Unit tests, integration tests |
 | `docs` | Documentation |
 
 ### PRD Guidelines
@@ -231,7 +263,7 @@ Chat commands (send in Telegram):
 - Include 2-4 concrete steps per task
 - End with a verification step (build, typecheck, test)
 - All tasks start with `"passes": false`
-- Order by dependency: setup -> config -> features -> tests -> docs
+- Order by dependency: setup -> development -> feature -> testing -> docs
 
 ### Sandbox Safety
 

package/docs/SECURITY.md

@@ -20,7 +20,9 @@ When running inside a container, ralph automatically passes the appropriate auto
 | AMP | `--dangerously-allow-all` | ✅ Supported |
 | Aider | `--yes-always` | ✅ Supported |
 | Goose | (none needed) | ✅ Supported |
-| OpenCode | `--yolo` | ❌ Not yet implemented |
+| OpenCode | (none) | ❌ Not yet implemented |
+| Ollama | (none needed) | ✅ Supported |
+| Custom | (none) | ⚙️ User-configured |
 
 For providers without autonomous mode support, you may need to manually approve actions during execution.
 
@@ -64,7 +66,7 @@ For Claude Code users with Pro/Max subscriptions, the `~/.claude` directory is m
 
 ```yaml
 volumes:
-  - ~/.claude:/home/node/.claude:ro
+  - ~/.claude:/home/node/.claude
 ```
 
 This allows the AI agent to use your existing OAuth credentials without exposing API keys.

package/docs/SKILLS.md

@@ -174,11 +174,11 @@ Target project-specific requirements:
 
 ## How Skills Are Applied
 
-When ralph runs an iteration:
+During `ralph docker init`:
 
 1. Skills from `claude.skills` are loaded from config
-2. Skill instructions are injected into the prompt template
-3. Claude receives the combined prompt with all active skill instructions
+2. Each skill is written as a `.claude/commands/<name>.md` file with YAML frontmatter (`description`, `user-invocable`)
+3. Claude Code natively reads these command files and applies the skill instructions
 
 This ensures Claude consistently follows your defined rules across all iterations.
 

package/docs/chat-architecture.md

@@ -47,7 +47,8 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 │  │ └─────────┘ │                    ▼                                        │
 │  └─────────────┘    ┌───────────────────────────────────────┐               │
 │                     │           Command Handler              │               │
-│                     │  run, stop, status, exec, add, claude  │               │
+│                     │  run, stop, status, exec, add, claude, │               │
+│                     │  help, start, action, branch           │               │
 │                     └───────────────────┬───────────────────┘               │
 │                                         │                                    │
 │                                         ▼                                    │
@@ -96,7 +97,7 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    ResponderMatcher                              │
 │                                                                  │
-│  1. Check @mention triggers: @qa, @review, @explain, @code      │
+│  1. Check @mention triggers: @qa, @review, @arch, @explain, @code│
 │  2. Check keyword triggers: !lint, help                          │
 │  3. Fall back to default responder                               │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -111,11 +112,11 @@ The Ralph CLI chat system enables external control of Ralph projects via chat pl
 ┌─────────────────────────────────────────────────────────────────┐
 │                    LLM Responder                                 │
 │                                                                  │
-│  1. Detect git keyword: "last" → git show HEAD                  │
+│  1. Detect git keyword: "last" → git show HEAD --stat --patch   │
 │  2. Fetch git diff content                                       │
 │  3. Build message with diff                                      │
 │  4. Load conversation history (if thread)                        │
-│  5. Send to LLM (Anthropic/OpenAI)                              │
+│  5. Send to LLM (Anthropic/OpenAI/Ollama)                       │
 │  6. Log to .ralph/logs/responder-YYYY-MM-DD.log                 │
 │  7. Return response                                              │
 └─────────────────────────────┬───────────────────────────────────┘
@@ -168,48 +169,54 @@ Reply in thread               history (max 20 messages)
 
 ## Message Queue Format
 
+The messages file stores a direct JSON array (no wrapper object):
+
 ```json
-{
-  "messages": [
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "pending"
-    },
-    {
-      "id": "uuid-1234",
-      "from": "host",
-      "action": "run",
-      "args": ["feature"],
-      "timestamp": 1706789012345,
-      "status": "done",
-      "response": {
-        "success": true,
-        "output": "Ralph run started (category: feature)"
-      }
+[
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "pending"
+  },
+  {
+    "id": "uuid-1234",
+    "from": "host",
+    "action": "run",
+    "args": ["feature"],
+    "timestamp": 1706789012345,
+    "status": "done",
+    "response": {
+      "success": true,
+      "output": "Ralph run started (category: feature)"
     }
-  ]
-}
+  }
+]
 ```
 
+Fields:
+- `from`: `"sandbox"` or `"host"`
+- `args`: optional string array
+- `status`: `"pending"` or `"done"`
+- `response`: optional, contains `success` (boolean), `output` (optional string), and `error` (optional string)
+
 ## Git Diff Keywords
 
 | Keyword | Git Command | Description |
 |---------|-------------|-------------|
 | `diff` / `changes` | `git diff` | Unstaged changes |
 | `staged` | `git diff --cached` | Staged changes |
-| `last` / `last commit` | `git show HEAD` | Last commit |
+| `last` / `last commit` | `git show HEAD --stat --patch` | Last commit |
 | `all` | `git diff HEAD` | All uncommitted |
-| `HEAD~N` | `git show HEAD~N` | N commits ago |
+| `HEAD~N` | `git show HEAD~N --stat --patch` | N commits ago |
 
 ## Responder Types
 
 | Type | Description | Example Trigger |
 |------|-------------|-----------------|
-| `llm` | Send to LLM (Anthropic/OpenAI) | `@qa`, `@review` |
+| `llm` | Send to LLM (Anthropic/OpenAI/Ollama) | `@qa`, `@review` |
 | `claude-code` | Spawn Claude Code CLI | `@code` |
 | `cli` | Run shell command | `!lint` |
 

package/docs/run-state-machine.md

@@ -27,13 +27,21 @@ flowchart TD
     subgraph Analysis ["4. Result Analysis"]
         ExitCheck{Exit Code == 0?}
 
-        ExitCheck -- "No" --> FailurePath[Increment Failure Counter]
-        FailurePath --> CriticalCheck{Failures >= 3?}
+        ExitCheck -- "No" --> FailurePath[Track Failure]
+        FailurePath --> SameCode{Same Exit Code\nas Last Failure?}
+        SameCode -- "Yes" --> IncrementFailures[Increment Consecutive\nFailure Counter]
+        SameCode -- "No" --> ResetToOne[Reset Counter to 1]
+        IncrementFailures --> CriticalCheck{Consecutive\nFailures >= 3?}
+        ResetToOne --> CriticalCheck
         CriticalCheck -- "Yes" --> Abort([Abort: Too Many Errors])
-        CriticalCheck -- "No" --> SignalCheck
+        CriticalCheck -- "No" --> ProgressCheck
 
         ExitCheck -- "Yes" --> SuccessPath[Reset Failure Counter]
-        SuccessPath --> SignalCheck
+        SuccessPath --> ProgressCheck
+
+        ProgressCheck{All Mode:\nProgress Made?}
+        ProgressCheck -- "Yes / Not All Mode" --> SignalCheck
+        ProgressCheck -- "No progress\n3 iterations" --> StallAbort([Abort: No Progress])
 
         SignalCheck{COMPLETE Signal?}
         SignalCheck -- "Yes" --> CompleteModeCheck
@@ -73,5 +81,6 @@ flowchart TD
     style Analysis fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
     style Completion fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
     style Abort fill:#ffebee,stroke:#c62828,color:#c62828
+    style StallAbort fill:#ffebee,stroke:#c62828,color:#c62828
     style End fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {