@hanzlaa/rcode 4.7.3 → 4.9.0

package/rcode/workflows/execute-waves.md

@@ -71,6 +71,40 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    For 200k models, this keeps orchestrator context lean (~10-15%).
    For 1M+ models (Opus 4.6, Sonnet 4.6), richer context can be passed directly.
 
+   **Classify plan and select subagent_type (BEFORE spawning, once per plan):**
+
+   This used to be prose pseudocode the orchestrating LLM was expected to hand-apply
+   (FRONTEND_GLOBS/BACKEND_GLOBS matching + keyword fallback). A live execution run showed
+   that computation was never actually carried out — a plan whose `files_modified` clearly
+   matched the backend glob rule (a path containing `db`) still fell back to `rcode-executor`.
+   Classification is now a deterministic CLI call — do not hand-compute it.
+
+   Call `classify-plan` with the phase and this plan's id (it reads `files_modified` and the
+   `<objective>` directly from the plan's SPRINT.md, so no need to re-parse step 1's overlap
+   data yourself):
+
+   ```bash
+   CLASSIFY_JSON=$(node ".rcode/bin/rcode-tools.cjs" classify-plan "$PHASE" "$PLAN_ID" 2>/dev/null)
+   SUBAGENT_TYPE=$(echo "$CLASSIFY_JSON" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{console.log(JSON.parse(d).subagent_type)}catch{console.log('rcode-executor')}})")
+   SUBAGENT_TYPE=${SUBAGENT_TYPE:-rcode-executor}
+   ```
+
+   Use the literal `subagent_type` value returned — do not second-guess or override it.
+
+   This decision is computed once per plan, before that plan's Task() spawn(s) below, and the
+   resulting `subagent_type` value is used in the Task() call template (worktree and sequential
+   modes both reuse this same value — see "Sequential mode" further below).
+
+   **Resolve executor model (once per wave, before spawning):**
+
+   `executor_model` from `init` is the raw `model_profile` string (e.g. `balanced`), not a
+   resolved model id — it must be passed through `resolve-model` first, the same way
+   `code_review_gate` in execute.md resolves `REVIEWER_MODEL` before its Task() spawn.
+   ```bash
+   EXECUTOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model executor 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{console.log(JSON.parse(d).model)}catch{console.log('')}})" || echo "sonnet")
+   EXECUTOR_MODEL=${EXECUTOR_MODEL:-sonnet}
+   ```
+
    **Worktree mode** (`USE_WORKTREES` is not `false`):
 
    Before spawning, capture the current HEAD:
@@ -96,15 +130,17 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
    ```
    Task(
-     subagent_type="rcode-executor",
+     subagent_type="{subagent_type}",
      description="Execute plan {plan_number} of phase {phase_number}",
-     model="{executor_model}",
+     model="${EXECUTOR_MODEL}",
      isolation="worktree",
      prompt="
        <objective>
        Execute plan {plan_number} of phase {phase_number}-{phase_name}.
        Commit each task atomically. Create SUMMARY.md.
        Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
+
+       Routing note: this plan touches {classification} paths → dispatched to {subagent_type} (see step 3's classification logic in execute-waves.md).
        </objective>
 
        <!--

package/rcode/workflows/execute.md

@@ -35,11 +35,12 @@ route back to the user.
 4. **Branch check**: confirm current git branch is appropriate
    for the work. Two checks, both blocking:
 
-   a. **Not on main/master without consent**: if `git branch --show-current`
-      returns `main` or `master`, refuse to execute. Suggest:
-      `git switch -c <phase>-<plan>-<slug>` (e.g. `git switch -c 8-1-aria`).
-      User can override only by passing `--allow-main` to /rcode-execute and
-      explicitly typing the override on this turn.
+   a. **Not on main/master without consent** (skip entirely when `git.branching_strategy`
+      config is `none` — check via `node .rcode/bin/rcode-tools.cjs config-get
+      git.branching_strategy`): if `git branch --show-current` returns `main` or
+      `master`, refuse to execute. Suggest: `git switch -c <phase>-<plan>-<slug>`
+      (e.g. `git switch -c 8-1-aria`). User can override only by passing `--on-main`
+      to /rcode-execute and explicitly typing the override on this turn.
 
    b. **Working tree clean enough**: if `git status --porcelain` shows
       modified files unrelated to this phase's `files_modified` frontmatter,
@@ -49,8 +50,7 @@ route back to the user.
 
    The branch name should align with the phase/plan IDs from state — check
    `workflow.branch_pattern` config (default `<phase>-<plan>-<slug>`).
-5. **Worktree config**: read `workflow.use_worktrees` — if true + parallelization
-   is true + no file overlaps, plans in a wave run parallel via worktrees
+5. **Worktree config**: read `workflow.use_worktrees` — if true + no file overlaps, plans in a wave run parallel via worktrees. (`parallelization` is not a real field in `init execute`'s output — see the "initialize" step below; don't gate on it.)
 </pre_flight>
 
 <insight_block>
@@ -178,12 +178,13 @@ via filesystem and git state.
 </runtime_compatibility>
 
 <required_reading>
-@.rcode/references/auto-init-guard.md
-@.rcode/references/output-format.md
+<!-- If chained from plan.md's --auto (Skill(), same context), these 3 are already loaded — see AUDIT-workflow-complexity.md finding 3. -->
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/auto-init-guard.md'}
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/output-format.md'}
 @.rcode/references/git-preflight.md
 Read STATE.md before any operation to load project context.
 
-@.rcode/references/karpathy-guidelines.md
+${AUTO_CHAINED_FROM_PLAN ? '' : '@.rcode/references/karpathy-guidelines.md'}
 @.rcode/references/execution-protocol.md
 <!-- Read .rcode/references/agent-contracts.md only if debugging agent contract violations -->
 <!-- Read .rcode/references/context-budget.md only if context degradation guidance is needed -->
@@ -204,8 +205,11 @@ Always use the exact name from this list — do not fall back to 'general-purpos
 - rcode-integration-checker — Checks cross-phase integration
 - rcode-nyquist-auditor — Validates verification coverage
 - rcode-ux-designer — Researches UI/UX approaches
-- rcode-ui-auditor — Reviews UI implementation quality
 - rcode-ui-auditor — Audits UI against design requirements
+- rcode-hanzla — Senior Full-Stack Engineer — full-stack plans spanning both frontend and backend
+- rcode-yousef — Senior Backend Engineer — backend-only plans (API, DB, services, queues)
+- rcode-haitham — Senior Frontend Engineer — frontend-only plans (React/Next.js/Tailwind/CSS/RTL/a11y)
+- rcode-omar — Software Engineer (generalist) — fallback for cross-stack or small ambiguous plans when Hanzla isn't the clear fit
 </available_agent_types>
 
 <process>
@@ -234,14 +238,16 @@ If `INIT` is empty or `INIT.ok` is false, print error and exit:
 Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+Parse JSON for these real, top-level fields: `executor_model`, `verifier_model`, `phase_dir`, `plans`, `state_exists`, `response_language`. Fields commonly assumed to exist but that are NOT top-level (verified live this session against `init execute`'s real output, `cmdInitExecute` in rcode-tools.cjs): `branching_strategy` is nested under `config.branching_strategy`; `commit_docs` doesn't exist (closest real value is `config.commit_planning`, a `"true"`/`"false"` string); `parallelization` has no source anywhere (not top-level, not under `config`, not in `phase-plan-index`'s output either); `branch_name` isn't returned (the `handle_branching` step below now computes it from config instead); `phase_name` isn't derivable either (`phase_dir`'s basename is a slug, not the human-readable name — read ROADMAP.md if a step needs it); `incomplete_plans`/`incomplete_count` don't exist (`plans[]` items only carry `{path, depends_on, wave, plan}`, no completion field); `roadmap_exists`/`phase_req_ids` are returned only by the separate `init sprint-plan` command, not `init execute`.
+Derivable, not literal: `phase_found` as `phase_dir !== null`; `phase_number` as the `target` field (the raw phase argument as passed, e.g. `"45"`); `phase_slug` from `phase_dir`'s basename (the part after the first `-`); `plan_count` as `plans.length`. Downstream `${PHASE_NUMBER}`/`${PLAN_COUNT}` references later in this workflow (snapshot tag, review prompts, `phase complete`, etc.) resolve from `target`/`plans.length` per these derivations; `${PHASE_NAME}` and `${INCOMPLETE_COUNT}` have no source here — read `PHASE_NAME` from ROADMAP.md if a later step needs it, and treat `INCOMPLETE_COUNT` as unknown until `phase-plan-index` runs in `discover_and_group_plans` (which does return a real per-plan `has_summary` completion signal).
 
 **If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
 Read worktree config:
 
 ```bash
-USE_WORKTREES=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.use_worktrees 2>/dev/null || echo "true")
+USE_WORKTREES=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.use_worktrees 2>/dev/null)
+USE_WORKTREES=${USE_WORKTREES:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 ```
 
 When `USE_WORKTREES` is `false`, all executor agents run without `isolation="worktree"` — they execute sequentially on the main working tree instead of in parallel worktrees.
@@ -261,16 +267,17 @@ When `CONTEXT_WINDOW >= 500000` (1M-class models), subagent prompts include rich
 - Verifier agents receive all SPRINT.md, SUMMARY.md, CONTEXT.md files plus REQUIREMENTS.md
 - This enables cross-phase awareness and history-aware verification
 
-**If `phase_found` is false:** Error — phase directory not found. Run `/rcode-status` to inspect state or `/rcode-plan {N}` to create the phase.
-**If `plan_count` is 0:** Error — no plans found in phase. Run `/rcode-plan {N}` to generate plans or `/rcode-help` for the command surface.
+**If `phase_dir` is `null` (derived `phase_found` false):** Error — phase directory not found. Run `/rcode-status` to inspect state or `/rcode-plan {N}` to create the phase.
+**If `plans.length` is 0 (derived `plan_count` 0):** Error — no plans found in phase. Run `/rcode-plan {N}` to generate plans or `/rcode-help` for the command surface.
 **If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
 
-When `parallelization` is false, plans within a wave execute sequentially.
+`parallelization` is not a real field in `init execute`'s output (see the "initialize" step's field notes above) — this line currently documents behavior with no data source; don't treat it as a working toggle until a real source is wired in.
 
 **Runtime detection for Copilot:**
 Check if the current runtime is Copilot by testing for the `@rcode-executor` agent pattern
 or absence of the `Task()` subagent API. If running under Copilot, force sequential inline
-execution regardless of the `parallelization` setting — Copilot's subagent completion
+execution unconditionally (there is no real `parallelization` toggle to override — see the
+"initialize" step's field notes above) — Copilot's subagent completion
 signals are unreliable (see `<runtime_compatibility>`). Set `COPILOT_SEQUENTIAL=true`
 internally and skip the `execute_waves` step in favor of `check_interactive_mode`'s
 inline path for each plan.
@@ -335,46 +342,10 @@ Write these answers inline before continuing. If a blocking anti-pattern cannot
 
 **If `--interactive` flag present:** Switch to interactive execution mode.
 
-Interactive mode executes plans sequentially **inline** (no subagent spawning) with user
-checkpoints between tasks. The user can review, modify, or redirect work at any point.
-
-**Interactive execution flow:**
-
-1. Load plan inventory as normal (discover_and_group_plans)
-2. For each plan (sequentially, ignoring wave grouping):
-
-   a. **Present the plan to the user:**
-      ```
-      ## Plan {plan_id}: {plan_name}
-
-      Objective: {from plan file}
-      Tasks: {task_count}
-
-      Options:
-      - Execute (proceed with all tasks)
-      - Review first (show task breakdown before starting)
-      - Skip (move to next plan)
-      - Stop (end execution, save progress)
-      ```
-
-   b. **If "Review first":** Read and display the full plan file. Ask again: Execute, Modify, Skip.
-
-   c. **If "Execute":** Read and follow `.rcode/workflows/execute-sprint.md` **inline**
-      (do NOT spawn a subagent). Execute tasks one at a time.
-
-   d. **After each task:** Pause briefly. If the user intervenes (types anything), stop and address
-      their feedback before continuing. Otherwise proceed to next task.
-
-   e. **After plan complete:** Show results, commit, create SUMMARY.md, then present next plan.
-      **Overwrite guard:** If the SUMMARY.md file already exists from a previous run, delete it first with `rm -f <path>` before writing the new version. Never append to or skip an existing SUMMARY.md — always overwrite with the current sprint's completion data.
-
-3. After all plans: proceed to verification (same as normal mode).
-
-**Benefits of interactive mode:**
-- No subagent overhead — dramatically lower token usage
-- User catches mistakes early — saves costly verification cycles
-- Maintains rcode's planning/tracking structure
-- Best for: small phases, bug fixes, verification gaps, learning rcode
+```bash
+INTERACTIVE_MODE=$([[ "$ARGUMENTS" =~ (^|[[:space:]])--interactive($|[[:space:]]) ]] && echo true || echo false)
+```
+${INTERACTIVE_MODE === 'true' ? '@.rcode/references/execute-interactive-mode.md' : ''}
 
 **Skip to handle_branching step** (interactive plans execute inline after grouping).
 </step>
@@ -384,7 +355,7 @@ Check `branching_strategy` from init:
 
 **"none":** Skip, continue on current branch.
 
-**"phase" or "milestone":** Use pre-computed `branch_name` from init:
+**"phase" or "milestone":** `init execute` does not return `branch_name` (see the "initialize" step's field notes above) — compute `BRANCH_NAME` from `workflow.branch_pattern` config (default `<phase>-<plan>-<slug>`) before running:
 ```bash
 git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
 ```
@@ -393,7 +364,7 @@ All subsequent commits go to this branch. User handles merging.
 </step>
 
 <step name="validate_phase">
-From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
+From init JSON: `phase_dir` (real); `plan_count` derives as `plans.length`; `incomplete_count` has no source at this point (see the "initialize" step's field notes) — treat as unknown until `phase-plan-index` runs.
 
 Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
 
@@ -434,10 +405,8 @@ Report:
 ```
 </step>
 
-
 @rcode/workflows/execute-waves.md
 
-
 <step name="checkpoint_handling">
 Plans with `autonomous: false` require user interaction.
 
@@ -561,7 +530,7 @@ Selected wave finished successfully. This phase still has incomplete plans, so p
 <step name="run_verify_commands">
 **Run per-task `<verify>` shell commands from all completed SPRINT.md plans.**
 
-After all executor agents finish, extract and run any `<verify>` blocks defined in plan tasks. These are the machine-executable counterpart to `<acceptance_criteria>` prose.
+After all executor agents finish, extract and run any `<verify>` blocks defined in plan tasks. These are the machine-executable proof that a task's `<done>` criteria are met — the plan schema has no such tag; `<verify><automated>` plus `<evidence>` grounding are what the planner and executor actually emit and enforce.
 
 ```bash
 # Extract all <verify> blocks from all SPRINT.md files for this phase
@@ -646,7 +615,7 @@ generated: <ISO timestamp>
 Group findings by severity. For each finding include: file path, line reference, description, recommended fix.
 
 ${REVIEWER_SKILLS}",
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="${REVIEWER_MODEL}"
 )
 ```
@@ -740,59 +709,16 @@ Only when the gate is clean or the user overrides do we proceed to close_parent_
 
 **Skip if** phase number has no decimal (e.g., `3`, `04`) — only applies to gap-closure phases like `4.1`, `03.1`.
 
-**1. Detect decimal phase and derive parent:**
-```bash
-# Check if phase_number contains a decimal
-if [[ "$PHASE_NUMBER" == *.* ]]; then
-  PARENT_PHASE="${PHASE_NUMBER%%.*}"
-fi
-```
-
-**2. Find parent UAT file:**
-```bash
-PARENT_INFO=$(node ".rcode/bin/rcode-tools.cjs" find-phase "${PARENT_PHASE}" --raw)
-# Extract directory from PARENT_INFO JSON, then find UAT file in that directory
-```
-
-**If no parent UAT found:** Skip this step (gap-closure may have been triggered by VERIFICATION.md instead).
-
-**3. Update UAT gap statuses:**
-
-Read the parent UAT file's `## Gaps` section. For each gap entry with `status: failed`:
-- Update to `status: resolved`
-
-**4. Update UAT frontmatter:**
-
-If all gaps now have `status: resolved`:
-- Update frontmatter `status: diagnosed` → `status: resolved`
-- Update frontmatter `updated:` timestamp
-
-**5. Resolve referenced debug sessions:**
-
-For each gap that has a `debug_session:` field:
-- Read the debug session file
-- Update frontmatter `status:` → `resolved`
-- Update frontmatter `updated:` timestamp
-- Move to resolved directory:
 ```bash
-mkdir -p .planning/debug/resolved
-mv .planning/debug/{slug}.md .planning/debug/resolved/
-```
-
-**6. Commit updated artifacts:**
-```bash
-node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-${PARENT_PHASE}): resolve UAT gaps and debug sessions after ${PHASE_NUMBER} gap closure" --files .planning/phases/*${PARENT_PHASE}*/*-UAT.md .planning/debug/resolved/*.md
+IS_GAP_CLOSURE_PHASE=$([[ "$PHASE_NUMBER" == *.* ]] && echo true || echo false)
 ```
+${IS_GAP_CLOSURE_PHASE === 'true' ? '@.rcode/references/execute-close-parent-artifacts.md' : ''}
 </step>
 
-
 @rcode/workflows/execute-regression-gates.md
 
-
-
 @rcode/workflows/execute-verify-phase-goal.md
 
-
 <step name="uat_gate" priority="blocker">
 **UAT gate:**
 
@@ -822,10 +748,10 @@ fi
    ```
    ⚠ Phase {X} EXECUTED but not yet verified.
 
-   The following acceptance criteria require human verification before
+   The following task completion criteria require human verification before
    the phase can advance to `status: complete`:
 
-   {list AC items from SPRINT.md}
+   {list each task's <done> sentence from SPRINT.md}
 
    Recommended next steps:
    /rcode-add-tests {X} — generate unit + E2E tests before UAT
@@ -838,7 +764,7 @@ fi
 **If `VERIFICATION_STATUS` is `fail`:**
 
 1. Mark the phase as `status: executed` (so /rcode-plan --gaps can run a closure cycle).
-2. Surface the failed AC items.
+2. Surface the tasks whose `<done>` criteria failed human verification.
 3. STOP. Don't mark complete on a failing verification.
 
 **Only when `VERIFICATION_STATUS` is `pass`** — proceed to `update_roadmap` below.
@@ -899,24 +825,13 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-{X}): complete phase execut
 <step name="auto_copy_learnings">
 **Auto-copy phase learnings to global store (when enabled).**
 
-This step runs AFTER phase completion and SUMMARY.md is written. It copies any LEARNINGS.md
-entries from the completed phase to the global learnings store at `.rcode/knowledge/`.
-
 **Check config gate:**
 ```bash
 GL_ENABLED=$(node ".rcode/bin/rcode-tools.cjs" config-get features.global_learnings --raw 2>/dev/null || echo "false")
 ```
 
 **If `GL_ENABLED` is not `true`:** Skip this step entirely (feature disabled by default).
-
-**If enabled:**
-
-1. Check if LEARNINGS.md exists in the phase directory (use the `phase_dir` value from init context)
-2. If found, copy to global store:
-```bash
-node ".rcode/bin/rcode-tools.cjs" learnings copy 2>/dev/null || echo "⚠ Learnings copy failed — continuing"
-```
-Copy failure must NOT block phase completion.
+${GL_ENABLED === 'true' ? '@.rcode/references/execute-auto-copy-learnings.md' : ''}
 </step>
 
 <step name="update_project_md">
@@ -947,21 +862,10 @@ node ".rcode/bin/rcode-tools.cjs" commit "docs(phase-{X}): evolve PROJECT.md aft
 Silent no-op if no webhook URLs are in `.rcode/config.yaml`. Failures are reported but never block the workflow.
 
 ```bash
-node ".rcode/bin/rcode-tools.cjs" notify send \
-  --title "Phase ${phase_number} complete — ${phase_name}" \
-  --body "$(basename "$PWD") · $(git rev-parse --short HEAD) · ${incomplete_count:-0} plan(s) remaining" \
-  --event "execute-done" 2>/dev/null || true
+WEBHOOK_CONFIGURED=$(node ".rcode/bin/rcode-tools.cjs" config-get slack_webhook_url 2>/dev/null; node ".rcode/bin/rcode-tools.cjs" config-get discord_webhook_url 2>/dev/null; node ".rcode/bin/rcode-tools.cjs" config-get teams_webhook_url 2>/dev/null)
+WEBHOOK_CONFIGURED=$([ -n "$WEBHOOK_CONFIGURED" ] && echo true || echo false)
 ```
-
-Users configure webhooks by editing `.rcode/config.yaml`:
-
-```yaml
-slack_webhook_url: "https://hooks.slack.com/services/..."
-discord_webhook_url: "https://discord.com/api/webhooks/..."
-teams_webhook_url: "https://outlook.office.com/webhook/..."
-```
-
-Then verify with `/rcode-notify-test`.
+${WEBHOOK_CONFIGURED === 'true' ? '@.rcode/references/execute-notify-webhooks.md' : ''}
 </step>
 
 <step name="generate_tests">
@@ -1075,7 +979,7 @@ For 1M+ context models, consider:
 </context_efficiency>
 
 <failure_handling>
-- **classifyHandoffIfNeeded false failure:** Agent reports "failed" but error is `classifyHandoffIfNeeded is not defined` → Claude Code bug, not rcode. Spot-check (SUMMARY exists, commits present) → if pass, treat as success
+- See the classifyHandoffIfNeeded workaround in execute-waves.md (already @-included above).
 - **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
 - **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
 - **All agents in wave fail:** Systemic issue → stop, report for investigation

package/rcode/workflows/init.md

@@ -279,10 +279,10 @@ if [ -s .rcode/context/active.md ] && ! grep -q "Run \`/rcode" .rcode/context/ac
 fi
 ```
 
-After writing both files, refresh the memory bank fingerprint so staleness checks see the project as fresh:
+After writing both files, refresh the memory bank fingerprint so staleness checks see the project as fresh. `context refresh` reads `.rcode/sources.yaml`, but nothing in rcode ever creates that file (the installer only scaffolds the unrelated `.rcode/brain/sources.yaml`, used by `brain pull`) — so on every fresh project this call is a guaranteed no-op. Skip it when the file is known not to exist rather than spending a call to learn that (#1018):
 
 ```bash
-node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
+test -f .rcode/sources.yaml && node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
 ```
 
 ## Step 4c — Scaffold CLAUDE.md / AGENTS.md if missing
@@ -327,6 +327,14 @@ Or strategic question about the codebase:
 /rcode-council {your question}
 ```
 
+**In all three cases, append this tip:**
+```
+Tip: run /rcode-enable-hooks to turn on a one-line project status primer at
+the start of every session, plus 9 other opt-in guardrails (read-before-edit
+checks, dangerous-command blocking, auto-formatting). Off by default so a
+fresh install never surprises you.
+```
+
 **If `returning` with `--reset`:**
 ```
 ✓ rcode reconfigured. Prior state preserved in state.json.

package/rcode/workflows/lens-audit.md

@@ -196,7 +196,7 @@ FINDINGS[security] = merge(PRIMARY, SECONDARY)
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Audit-only — do NOT optimize anything. {CONTEXT}
   
@@ -288,7 +288,7 @@ FINDINGS[extensibility] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-dep-auditor",
   model="{lens_model}",
   prompt="Audit-only — do NOT install or update packages. {CONTEXT}
   
@@ -419,7 +419,7 @@ FINDINGS[documentation] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-cross-platform-auditor",
   model="{lens_model}",
   prompt="Cross-platform audit — do NOT fix scripts. {CONTEXT}
   
@@ -446,7 +446,7 @@ FINDINGS[cross-platform] = RESULT
 
 ```
 PRIMARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Karpathy 4-principle audit — do NOT fix code. {CONTEXT}
   
@@ -516,7 +516,7 @@ FINDINGS[sxo] = RESULT
 
 ```
 RESULT = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-observability-auditor",
   model="{lens_model}",
   prompt="Observability audit — do NOT add instrumentation. {CONTEXT}
   
@@ -559,7 +559,7 @@ PRIMARY = Task(
 )
 
 SECONDARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="Variable naming audit in recent code changes. {CONTEXT}
   
@@ -619,7 +619,7 @@ FINDINGS[coverage] = merge(PRIMARY, SECONDARY)
 
 ```
 PRIMARY = Task(
-  subagent_type="rcode-code-reviewer",
+  subagent_type="rcode-reviewer",
   model="{lens_model}",
   prompt="YAGNI / over-engineering audit — do NOT fix code. {CONTEXT}
 

package/rcode/workflows/plan-research-validation.md

@@ -157,9 +157,12 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 > Skip if `workflow.security_enforcement` is explicitly `false`. Absent = enabled.
 
 ```bash
-SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
-SECURITY_ASVS=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null || echo "1")
-SECURITY_BLOCK=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null || echo "high")
+SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null)
+SECURITY_CFG=${SECURITY_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+SECURITY_ASVS=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_asvs_level --raw 2>/dev/null)
+SECURITY_ASVS=${SECURITY_ASVS:-1}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+SECURITY_BLOCK=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_block_on --raw 2>/dev/null)
+SECURITY_BLOCK=${SECURITY_BLOCK:-high}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 ```
 
 **If `SECURITY_CFG` is `false`:** Skip to step 5.6.
@@ -183,8 +186,10 @@ Continue to step 5.6. Security config is passed to the planner in step 8.
 > Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.rcode/config.yaml`. If keys are absent, treat as enabled.
 
 ```bash
-UI_PHASE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
+UI_PHASE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_phase 2>/dev/null)
+UI_PHASE_CFG=${UI_PHASE_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
+UI_GATE_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null)
+UI_GATE_CFG=${UI_GATE_CFG:-true}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 ```
 
 **If both are `false`:** Skip to step 6.

package/rcode/workflows/plan-spawn-planner.md

@@ -114,7 +114,7 @@ ${AGENT_SKILLS_PLANNER}
 <downstream_consumer>
 Output consumed by /rcode-execute. Plans need:
 - Frontmatter (wave, depends_on, autonomous, **files_modified** — aggregated list of all file paths from `<files>` blocks across every task; used by executor for intra-wave parallel-safety overlap detection)
-- Tasks in XML format with read_first, files, acceptance_criteria, verify (with `<automated>` child), and done fields (MANDATORY on every task)
+- Tasks in XML format with read_first, files, evidence, verify (with `<automated>` child), and done fields (MANDATORY on every task)
 - Verification criteria
 - must_haves for goal-backward verification
 - **`## Files Touched`** section (see below) — required on every SPRINT.md
@@ -257,17 +257,13 @@ Every task MUST include these fields — they are NOT optional:
    - Executor checkpoint (knows what to stage after each task)
    - Example: `src/auth/auth.service.ts`, `tests/auth/auth.service.test.ts`
 
-3. **`<acceptance_criteria>`** — Verifiable conditions that prove the task was done correctly. Rules:
-   - Every criterion must be checkable with grep, file read, test command, or CLI output
-   - NEVER use subjective language ("looks correct", "properly configured", "consistent with")
-   - ALWAYS include exact strings, patterns, values, or command outputs that must be present
-   - Examples:
-     - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0`
-     - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK`
-     - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints`
-     - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db`
-
-4. **`<verify>`** — Shell commands that PROVE the acceptance criteria are met. Run by executor after task completes and by verifier during post-execution check. The block MUST contain an `<automated>` child with the exact commands to run (Dimension 8 hard-blocks without it). Rules:
+3. **`<evidence>`** — REQUIRED (issue #649). Must show codebase grounding proving the task is real, not theoretical. At minimum one of:
+   - `grep:` a literal grep/Glob pattern + count of matches that justified this task (e.g. `` `rg '\.alert' apps/web/src` → 13 hits across 9 files ``)
+   - `lines:` exact `path:line-line` ranges of code being modified
+   - `creates:` the file paths being created from scratch (with one-line justification why no existing file fits)
+   A task without `<evidence>` is theoretical and MUST NOT be written. (Matches `rcode/references/planner-playbook.md`'s "Task Anatomy" section — single source of truth for this rule.)
+
+4. **`<verify>`** — Shell commands that PROVE the `<done>` criteria are met. Run by executor after task completes and by verifier during post-execution check. The block MUST contain an `<automated>` child with the exact commands to run (Dimension 8 hard-blocks without it). Rules:
    - `<automated>` commands must exit 0 on success, non-zero on failure
    - Prefer `grep -q` for presence checks, `test -f` for file existence, project test runner for behavior
    - Keep commands short and composable — one check per line
@@ -325,7 +321,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] Tasks are specific and actionable
 - [ ] Every task has `<read_first>` with at least the file being modified
 - [ ] Every task has `<files>` listing exact files this task will modify or create
-- [ ] Every task has `<acceptance_criteria>` with grep-verifiable conditions
+- [ ] Every task has `<evidence>` with grep/lines/creates codebase grounding per issue #649 — not a prose checklist tag (none exists in the real plan schema)
 - [ ] Every task has `<verify>` with an `<automated>` child containing at least one shell command (Dimension 8 blocker)
 - [ ] Every task has `<done>` with a single observable acceptance sentence (Dimension 2 requirement)
 - [ ] Every `<action>` contains concrete values (no "align X with Y" without specifying what)
@@ -351,7 +347,6 @@ Fix issues inline. No sub-agent needed — this is a quick self-check before the
 Task(
   prompt=filled_prompt,
   subagent_type="rcode-planner",
-  model="{model}",
   model="{planner_model}",
   description="Plan Phase {phase}"
 )