@ai-dev-methodologies/rlp-desk 0.3.0 → 0.3.1

package/README.md

@@ -40,9 +40,11 @@ curl -sSL https://raw.githubusercontent.com/ai-dev-methodologies/rlp-desk/main/i
 
 You'll be asked to confirm each item:
 - **Slug** — project identifier
-- **User Stories** — discrete, testable units of work
+- **User Stories** — discrete, testable units with Given/When/Then acceptance criteria
+- **Task Type & Risk Level** — code/visual/content/integration/infra × LOW/MEDIUM/HIGH/CRITICAL
 - **Iteration Unit** — one story per iteration (incremental) or all at once (fast)
 - **Verification Commands** — how to check the work
+- **Ambiguity Gate** — AC quality scoring (IL-2, 0-12 scale, blocks init if < 6)
 - **Models** — which Claude model for Worker/Verifier
 
 ### 3. Run
@@ -97,12 +99,38 @@ for iteration in 1..max_iter:
   8. Update status, report to user, continue or stop
 ```
 
+### Verification Policy (v0.3.0)
+
+RLP Desk enforces a comprehensive verification policy defined in `governance.md`:
+
+**Iron Laws (§1a)** — 4 absolute rules that cannot be violated:
+- **IL-1**: No completion claims without fresh verification evidence
+- **IL-2**: No init without AC quality score ≥ 6 (Ambiguity Gate)
+- **IL-3**: No pass with TODO in any required verification layer
+- **IL-4**: No pass without test count ≥ AC count × 3
+
+**Evidence Gate (§1b)** — 5-step protocol: IDENTIFY → RUN → READ → VERIFY → ONLY THEN claim
+
+**Risk Classification (§1c)** — Proportional verification layers per risk level:
+
+| Risk | Required Layers |
+|------|----------------|
+| LOW | L1 (Unit) + L3 (E2E) |
+| MEDIUM | L1 + L2 (Integration) + L3 |
+| HIGH | L1 + L2 + L3 + L4 (Deploy) |
+| CRITICAL | L1 + L2 + L3 + L4 + mutation testing |
+
+**Execution Traceability (§1f)** — Always-on, not flag-gated:
+- Worker records `execution_steps` in done-claim.json (what was done, in what order, with evidence)
+- Verifier records `reasoning` in verify-verdict.json (why each judgment was made)
+
 ### Circuit Breakers
 
 | Condition | Action |
 |-----------|--------|
 | Context unchanged for 3 iterations | BLOCKED |
 | Same error repeated twice | Upgrade model, retry once, then BLOCKED |
+| 3 consecutive failures | Architecture Escalation (§7¾) → report to user |
 | Max iterations reached | TIMEOUT |
 
 ### Model Routing
@@ -140,6 +168,8 @@ for iteration in 1..max_iter:
 | `--codex-reasoning low\|medium\|high` | high | Reasoning effort for Codex |
 | `--verify-mode per-us\|batch` | per-us | Verification strategy (see below) |
 | `--verify-consensus` | off | Cross-engine consensus verification (see below) |
+| `--debug` | off | Debug logging to `logs/<slug>/debug.log` |
+| `--with-self-verification` | off | Campaign-level post-loop analysis report |
 
 ## Execution Modes
 
@@ -334,6 +364,7 @@ mkdir my-calc && cd my-calc
 - [Architecture](docs/architecture.md) — Design philosophy, Agent() and tmux execution modes
 - [Getting Started](docs/getting-started.md) — Step-by-step tutorial with the calculator example
 - [Protocol Reference](docs/protocol-reference.md) — Full protocol specification
+- [Future Plans](docs/TODO-verification-next.md) — P3 items and upcoming features
 
 ## Contributing
 

package/docs/architecture.md

@@ -48,6 +48,31 @@ RLP Desk supports two modes for running the Leader loop. Both honor the same gov
 | **Agent() — "Smart mode"** (default) | LLM (current session) | Dynamic — Leader reasons about which model to use each iteration | Active Claude Code session | Interactive development, complex routing decisions |
 | **Tmux — "Lean mode"** | Shell script (`run_ralph_desk.zsh`) | Static — set via `WORKER_MODEL`/`VERIFIER_MODEL` env vars | None (runs detached) | Long campaigns, CI, observability, zero-token orchestration |
 
+### Verification Policy Layer
+
+Both modes enforce the same verification policy (governance §1a-§1f):
+
+```
+                    ┌─────────────────────────────────┐
+                    │     Governance (§1a-§1f)         │
+                    │  Iron Laws · Evidence Gate       │
+                    │  Risk Classification · Layers    │
+                    │  Checkpoints · Traceability      │
+                    └──────────┬──────────────────────┘
+                               │ enforced by
+              ┌────────────────┼────────────────┐
+              ▼                ▼                ▼
+         Worker Template  Verifier Template  Leader Loop
+         (Test-First,     (12-step process,  (Contract review,
+          12 Shortcuts,    5 reasoning       Checkpoints,
+          execution_steps) categories)       Escalation)
+```
+
+Key design decisions:
+- **execution_steps** (Worker) and **reasoning** (Verifier) are always-on (§1f), not gated by flags
+- **`--with-self-verification`** adds post-campaign analysis only — does not change loop behavior
+- **Risk-proportional layers**: LOW gets L1+L3, CRITICAL gets L1+L2+L3+L4+mutation
+
 **Agent() mode** is synchronous and simple: each `Agent()` call blocks until the subprocess finishes, then the Leader reads the filesystem. No polling, no signal files, no tmux.
 
 **Tmux mode** trades dynamic routing for visibility and independence. The shell Leader writes prompts to files, sends short trigger commands via `tmux send-keys`, and polls structured JSON signal files (`iter-signal.json`, `verify-verdict.json`) for control flow. It uses proven tmux patterns — write-then-notify, pane ID stability, copy-mode guards, heartbeat monitoring — for reliable, race-free orchestration.

package/docs/getting-started.md

@@ -45,10 +45,12 @@ The brainstorm phase interactively determines:
 |------|---------|
 | **Slug** | `loop-test` |
 | **Objective** | Implement calc.py + test_calc.py |
-| **User Stories** | US-001: calculator functions, US-002: pytest tests |
+| **User Stories** | US-001: calculator functions (Given/When/Then AC format) |
+| **Task Type & Risk** | code, LOW |
 | **Iteration Unit** | One user story per iteration |
 | **Verification** | `python3 -m pytest test_calc.py -v` |
 | **Models** | Worker: sonnet, Verifier: opus |
+| **Ambiguity Gate (IL-2)** | AC quality score ≥ 6 required to proceed |
 | **Max Iterations** | 10 |
 
 On approval, brainstorm offers to run `init` automatically.
@@ -81,9 +83,11 @@ This creates the scaffold:
 Edit `.claude/ralph-desk/plans/prd-loop-test.md` to define your user stories and acceptance criteria. See [`examples/calculator/`](../examples/calculator/.claude/ralph-desk/plans/prd-loop-test.md) for a complete example.
 
 Key sections:
-- **User Stories** with specific, testable acceptance criteria
+- **User Stories** with Given/When/Then acceptance criteria, Task Type, and Risk Level
+- **Boundary Cases** for each US
+- **Verification Layers** (L1-L4 based on risk level per governance §1c)
 - **Technical Constraints** (e.g., "Python 3 + pytest only")
-- **Done When** conditions
+- **Done When** conditions (must reference Evidence Gate §1b)
 
 ## Step 6: Define the Test Spec
 
@@ -147,7 +151,10 @@ If you want to run the loop again:
 ## Tips
 
 - **Start small**: One or two user stories for your first loop
-- **Be specific in acceptance criteria**: "function returns float" is testable; "function works well" is not
+- **Use Given/When/Then**: "Given 10 and 5, When add, Then 15" — not "function works well"
+- **Set risk levels**: LOW for docs/config, MEDIUM for features, HIGH for deploys, CRITICAL for security/finance
 - **Include verification commands**: The verifier needs concrete commands to run
 - **One story per iteration**: Each worker should do one bounded action
 - **Check logs when stuck**: `logs/<slug>/iter-NNN.worker-prompt.md` shows exactly what the worker received
+- **Review done-claims**: Worker's `execution_steps` show exactly what was done and in what order
+- **Review verdict reasoning**: Verifier's `reasoning` shows why each judgment was made

package/docs/protocol-reference.md

@@ -136,24 +136,28 @@ Written by the Worker at the end of every iteration. Provides a structured JSON
 
 ### Done Claim (`<slug>-done-claim.json`)
 
-Written by the Worker when claiming all work is complete:
+Written by the Worker when claiming work is complete. **Must include `execution_steps`** (governance §1f — always-on, not optional):
 
 ```json
 {
-  "iteration": 3,
-  "claimed_at_utc": "2025-01-15T10:30:00Z",
-  "summary": "All user stories implemented and tests passing",
-  "stories_completed": ["US-001", "US-002"],
-  "evidence": {
-    "test_output": "8 passed in 0.05s",
-    "files_created": ["calc.py", "test_calc.py"]
-  }
+  "us_id": "US-001",
+  "claims": ["AC1: add(10,5)=15", "AC2: subtract(10,5)=5"],
+  "execution_steps": [
+    {"step": "write_test", "ac_id": "AC1", "command": null, "exit_code": null, "summary": "wrote tests/test_add.py"},
+    {"step": "verify_red", "ac_id": "AC1", "command": "pytest tests/", "exit_code": 1, "summary": "RED: test fails"},
+    {"step": "implement", "ac_id": "AC1", "command": null, "exit_code": null, "summary": "created add()"},
+    {"step": "verify_green", "ac_id": "AC1", "command": "pytest tests/", "exit_code": 0, "summary": "GREEN: 3 passed"},
+    {"step": "verify_e2e", "ac_id": "AC1", "command": "python -c '...'", "exit_code": 0, "summary": "E2E matches"},
+    {"step": "commit", "ac_id": "AC1", "command": "git commit", "exit_code": 0, "summary": "committed abc1234"}
+  ]
 }
 ```
 
+`execution_steps` must be a JSON array of objects. Step types from §1f vocabulary: `write_test`, `verify_red`, `implement`, `verify_green`, `refactor`, `verify_e2e`, `commit`, `verify`.
+
 ### Verify Verdict (`<slug>-verify-verdict.json`)
 
-Written by the Verifier after independent verification.
+Written by the Verifier after independent verification. **Must include `reasoning`** (governance §1f — always-on, not optional).
 
 **Tmux mode polling:** In tmux mode, after dispatching the Verifier, the shell Leader polls for the existence of `verify-verdict.json` (same pattern as `iter-signal.json`). Once it appears, the Leader reads the `verdict` and `recommended_state_transition` fields via `jq` to decide whether to write a COMPLETE sentinel, continue iterating, or write a BLOCKED sentinel.
 
@@ -172,6 +176,13 @@ Written by the Verifier after independent verification.
       "evidence": "test -f calc.py → exit 0"
     }
   ],
+  "reasoning": [
+    {"check": "IL-1 Evidence Gate", "decision": "pass", "basis": "ran pytest fresh, exit 0"},
+    {"check": "Layer Enforcement", "decision": "pass", "basis": "L1+L3 required and executed"},
+    {"check": "Test Sufficiency", "decision": "pass", "basis": "9 tests / 3 AC = 3.0 ratio"},
+    {"check": "Anti-Gaming", "decision": "pass", "basis": "no tautological tests, no mocking"},
+    {"check": "Worker Process Audit", "decision": "pass", "basis": "verify_red present with exit≠0"}
+  ],
   "missing_evidence": [],
   "issues": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",