@hanzlaa/rcode 4.8.0 → 4.9.1

package/rcode/workflows/execute-sprint.md

@@ -198,11 +198,10 @@ Deviations are normal — handle via rules below.
    - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary.
    - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation.
    - **Task completion precedence (when signals conflict):**
-     1. `<verify><automated>` — machine-executable shell commands. **Highest authority.** If these pass, the task is done. If these fail, the task is NOT done — regardless of what `<acceptance_criteria>` says.
+     1. `<verify><automated>` — machine-executable shell commands. **Highest authority.** If these pass, the task is done. If these fail, the task is NOT done — regardless of what `<done>` says.
      2. `<done>` — single observable sentence. Use as the human-readable confirmation once automated checks pass.
-     3. `<acceptance_criteria>` — prose checklist. **Lowest authority.** Use as a guide during implementation, but automated results override prose judgments.
-     - If `<verify><automated>` is absent: fall back to `<done>`, then `<acceptance_criteria>`.
-   - **MANDATORY acceptance_criteria check:** After completing each task, if it has `<acceptance_criteria>`, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later".
+     - If `<verify><automated>` is absent: fall back to `<done>` alone. `<evidence>` (grep hits, line ranges, or a creates-justification recorded by the planner per issue #649) is supporting grounding, not a completion signal to re-check here — the real plan schema (planner-playbook.md, sprint.md) has no such tag.
+   - **MANDATORY completion check:** After completing each task, confirm `<verify><automated>` passes (or, if absent, that the task's `<done>` sentence is observably true). Use grep, file reads, or CLI commands to confirm. If any check fails, fix the implementation before proceeding. Do not skip this or mark it as "will verify later".
 3. Run `<verification>` checks
 4. Confirm `<success_criteria>` met
 5. Document deviations in Summary

package/rcode/workflows/execute-waves.md

@@ -73,45 +73,38 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
 
    **Classify plan and select subagent_type (BEFORE spawning, once per plan):**
 
-   Reuse the `files_modified` list already parsed in step 1's intra-wave overlap check for this
-   plan — do not re-read the plan file to get it again.
+   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.
 
-   ```
-   FRONTEND_GLOBS = ["*.tsx", "*.jsx", "*.css"] + paths containing "client" or "ui"
-   BACKEND_GLOBS  = paths containing "api", "server", "db", or "service"
-
-   touches_frontend = any(file matches FRONTEND_GLOBS for file in files_modified)
-   touches_backend  = any(file matches BACKEND_GLOBS for file in files_modified)
-
-   if touches_frontend and touches_backend:
-     classification = "full-stack"
-   elif touches_frontend:
-     classification = "frontend"
-   elif touches_backend:
-     classification = "backend"
-   else:
-     classification = "other"   # files_modified empty/absent, or no glob matched
-   ```
-
-   **If `classification` is `"other"`** (ambiguous, or `files_modified` empty/absent), fall back
-   to keyword-matching the plan's `<objective>` text before giving up:
-   - Frontend keywords (React, component, UI, CSS, Tailwind, frontend, client-side, accessibility, a11y) → `classification = "frontend"`
-   - Backend keywords (API, endpoint, database, schema, service, queue, backend, server-side) → `classification = "backend"`
-   - Neither matches (pure docs/config/infra plan) → `classification` stays `"other"`
+   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):
 
-   **Route to `subagent_type`:**
+   ```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}
+   ```
 
-   | classification | subagent_type |
-   |---|---|
-   | frontend | rcode-haitham |
-   | backend | rcode-yousef |
-   | full-stack | rcode-hanzla |
-   | other | 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:
@@ -139,7 +132,7 @@ Execute each selected wave in sequence. Within a wave: parallel if `PARALLELIZAT
    Task(
      subagent_type="{subagent_type}",
      description="Execute plan {plan_number} of phase {phase_number}",
-     model="{executor_model}",
+     model="${EXECUTOR_MODEL}",
      isolation="worktree",
      prompt="
        <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>
@@ -98,7 +98,41 @@ CONFIG_MODE=$(node .rcode/bin/rcode-tools.cjs config-get mode 2>/dev/null || ech
 
 **If `CONFIG_MODE == "yolo"` or `$ARGUMENTS` contains `--auto`:** Skip the menu. Auto-select **A) Autonomous run** and print one line: `▶ Auto-selecting Autonomous run (yolo mode). /rcode-settings set mode guided to change.`
 
-Otherwise, offer three modes via AskUserQuestion. Each option names the tradeoff explicitly:
+**herdr availability check (cached).** Before offering options, determine whether a 4th
+option (**D) herdr multi-agent orchestration**) should be shown. This uses the same
+cached-boolean idiom as `workflow._auto_chain_active` above — read with a safe default,
+write back once resolved, and skip the live check on subsequent runs:
+
+```bash
+HERDR_NAMED_EXPLICITLY=$([[ "$ARGUMENTS" =~ herdr ]] && echo true || echo false)
+
+HERDR_CHECKED=$(node .rcode/bin/rcode-tools.cjs config-get workflow._herdr_checked 2>/dev/null || echo "false")
+HERDR_CHECKED=${HERDR_CHECKED:-false}  # config-get exits 0 with empty output when key absent
+
+if [[ "$HERDR_CHECKED" != "true" || "$HERDR_NAMED_EXPLICITLY" == "true" ]]; then
+  # Live re-check: first time ever, OR user named herdr explicitly this run
+  # (herdr may have been installed since the last negative cache hit).
+  if command -v herdr >/dev/null 2>&1; then
+    HERDR_AVAILABLE=true
+  else
+    HERDR_AVAILABLE=false
+  fi
+  node .rcode/bin/rcode-tools.cjs config-set workflow._herdr_available "$HERDR_AVAILABLE" 2>/dev/null
+  node .rcode/bin/rcode-tools.cjs config-set workflow._herdr_checked true 2>/dev/null
+else
+  # Cached negative (or positive) result from a prior run — skip the check entirely.
+  HERDR_AVAILABLE=$(node .rcode/bin/rcode-tools.cjs config-get workflow._herdr_available 2>/dev/null || echo "false")
+  HERDR_AVAILABLE=${HERDR_AVAILABLE:-false}
+fi
+```
+
+Do **not** re-run `command -v herdr` on every invocation once `_herdr_checked` is `true` —
+that defeats the point of caching. The only exception is `HERDR_NAMED_EXPLICITLY`: if the
+user's request names herdr by name (e.g. "use herdr for this", "orchestrate via herdr"),
+always re-check live regardless of the cached value, since herdr may have been installed
+since the negative result was cached.
+
+Otherwise, offer modes via AskUserQuestion. Each option names the tradeoff explicitly:
 
 **A) Autonomous run** — Spawn subagent per plan in sequence/parallel per
     wave rules. Checkpoints still pause for user. Fastest wall-clock.
@@ -112,9 +146,31 @@ Otherwise, offer three modes via AskUserQuestion. Each option names the tradeoff
     later waves in a separate session. Good for staged rollout / review
     gates.
 
+**D) herdr multi-agent orchestration** (only shown if `HERDR_AVAILABLE == "true"`) —
+    Fan this phase's plans out to parallel `herdr` panes/tabs, each running its own
+    Claude agent in an isolated git worktree, then merge their work back. Be specific
+    about the tradeoff, not a one-liner: separate terminal panes you can watch
+    independently, genuinely parallel wall-clock (not wave-sequenced), noticeably
+    higher token cost than A/B/C since each pane runs a full agent session, and a
+    merge step at the end. Best fit is plans that are truly independent (no shared
+    `files_modified`, no cross-plan sequencing) — for plans with overlaps or a single
+    linear wave, herdr adds coordination overhead for no benefit; prefer A or C instead.
+    Selecting this option invokes the `rcode-herdr-orchestration` skill — it does not
+    replace this workflow's execution, it's a different way to run the same plans.
+
+    **Never auto-select D, even in yolo/`--auto` mode.** Orchestrating via herdr requires
+    explicit user confirmation on this turn — if `CONFIG_MODE == "yolo"` skipped the menu
+    above, herdr is simply not offered this run; the autonomous-run auto-selection must
+    never silently switch into herdr mode.
+
 Include a recommendation line: "My recommendation: {letter} because {reason
 in one clause}." Then ask which option to proceed with — do NOT silently
-pick one.
+pick one. If the user selects D, confirm once more in plain language what
+will happen (parallel panes, worktrees, higher cost) before invoking
+`Skill(skill="rcode-herdr-orchestration", ...)` — do not invoke it on the same
+turn as the AskUserQuestion answer without that confirmation being part of
+the answer itself (i.e. selecting the option IS the confirmation only if its
+label made the tradeoff explicit, which it does above).
 </three_options>
 
 <output_format>
@@ -238,14 +294,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.
@@ -265,16 +323,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.
@@ -352,7 +411,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"
 ```
@@ -361,7 +420,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)"
 
@@ -527,7 +586,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
@@ -745,10 +804,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
@@ -761,7 +820,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.

package/rcode/workflows/init.md

@@ -42,6 +42,12 @@ Run detection in parallel:
 test -f .rcode/config.yaml && echo "rcode-configured: yes" || echo "rcode-configured: no"
 test -f .rcode/state.json && echo "state-present: yes" || echo "state-present: no"
 test -f .rcode/JOURNEY.md && echo "rihla-present: yes" || echo "rihla-present: no"
+# #1028: config.yaml is written by the installer itself, so it exists on the
+# very first /rcode-init run after a fresh install — not just on a genuine
+# "returning" session. state.json's installer-seeded _seeded_stub marker
+# (cleared once a real init/new-project run completes) is what actually
+# distinguishes "normal first brownfield run" from "prior init was interrupted".
+grep -q '"_seeded_stub"[[:space:]]*:[[:space:]]*true' .rcode/state.json 2>/dev/null && echo "seeded-stub: yes" || echo "seeded-stub: no"
 
 # Project presence
 # Use git rev-parse instead of test -d .git — in git worktrees .git is a FILE not a dir
@@ -83,12 +89,20 @@ If `state === "returning"` and `--reset` not passed:
   Or run with --reset to reconfigure.
   ```
 
-- If `rihla-present: no` — JOURNEY.md is missing from a partial prior init. Do NOT stop. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
+- If `rihla-present: no` and `seeded-stub: yes` — this is the normal, expected first `/rcode-init` run on a brownfield project: `config.yaml` was seeded by the installer, but no real init has happened yet. Nothing was broken; do NOT use "recovery" language. Print a plain first-run notice and continue to Steps 4 and 4b to write the baseline:
+
+  ```
+  ✓ rcode is configured. Writing the JOURNEY.md baseline now...
+  ```
+
+  Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
+
+- If `rihla-present: no` and `seeded-stub: no` — a genuine prior init/new-project run completed (the stub marker was cleared) but JOURNEY.md is missing, meaning that prior run was interrupted before writing it. This is an actual recovery case. Print a recovery notice and continue to Steps 4 and 4b to write the missing baseline:
 
   ```
   ✓ rcode is already configured here.
 
-  JOURNEY.md baseline is missing — completing the scan step now...
+  JOURNEY.md baseline is missing from a prior interrupted init — completing it now...
   ```
 
   Skip Steps 2 and 3 (config already exists). Jump directly to Step 4.
@@ -279,10 +293,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
@@ -290,12 +304,12 @@ node .rcode/bin/rcode-tools.cjs context refresh >/dev/null 2>&1 || true
 `generate-claude-md` (the command routing rule + project rules block every agent needs at session start) previously only ran via the `/rcode-new-project` roadmap flow — a project set up with `/rcode-init` alone (the common "add rcode to an existing codebase" path) never got it, so agents had no ambient instruction to check `do.md` before acting ad-hoc. Close that gap here, unconditionally (not just on `fresh`):
 
 ```bash
-if [ ! -f CLAUDE.md ]; then
+if [ ! -f CLAUDE.md ] || [ ! -f AGENTS.md ]; then
   node .rcode/bin/rcode-tools.cjs generate-claude-md
 fi
 ```
 
-Never pass `--force` here — an existing `CLAUDE.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. Silent no-op when `CLAUDE.md` already exists.
+Never pass `--force` here — an existing `CLAUDE.md` or `AGENTS.md` is the user's own file (or was already generated by a prior init/new-project run) and must not be overwritten. `cmdGenerateClaudeMd` gates each file's write on that file's own existence, so this backfills whichever one is missing (#1025). Silent no-op when both files already exist.
 
 ## Step 5 — Suggest the next step
 
@@ -327,6 +341,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/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)

package/rcode/workflows/plan.md

@@ -49,8 +49,8 @@ Read all files referenced by the invoking prompt's execution_context before star
 ${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/karpathy-guidelines.md
 <!-- Read .rcode/references/agent-contracts.md only if defining or debugging agent contracts -->
-<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic -->
-@.rcode/references/thinking-models-planning.md
+<!-- Read .rcode/references/gates.md only if implementing or troubleshooting gate logic; thinking-models-planning.md (127 lines) only if features.thinking_partner is enabled -->
+${THINKING_PARTNER_ENABLED === 'true' ? '@.rcode/references/thinking-models-planning.md' : ''}
 </required_reading>
 
 <available_agent_types>

package/rcode/workflows/scaffold-skill.md

@@ -117,6 +117,21 @@ if [ -n "$fails" ]; then
 fi
 ```
 
+## Step 3.5 — Prove It Moved the Needle
+
+Passing the 5-component check in Step 3 only proves the file has the right shape — a triggers block, an Overview, a Workflow, an Output Format, and Examples. It says nothing about whether loading the skill actually changes what an agent does. A skill can be structurally perfect and still be a no-op in practice: the model reads it, nods along, and then falls back to its untrained default the moment a real scenario hits.
+
+Do not mark a new or edited skill as ready to ship until you've run this gate:
+
+1. **Write the pressure scenario.** Take the exact situation the skill's triggers describe — the moment the skill is supposed to change the agent's behavior — and phrase it as a concrete task an agent could be handed cold, with no mention of the skill.
+2. **Run the control.** Spawn a fresh subagent with no memory of this conversation and the skill NOT loaded (do not mention it, do not point at its path). Give it the pressure scenario. Record what it does by default — this is almost always the suboptimal or wrong behavior the skill exists to correct.
+3. **Run the treatment.** Spawn a second fresh subagent, same scenario, this time with the skill loaded (either by having it available for the model to invoke, or by including its content directly in the prompt). Record what it does.
+4. **Compare.** The treatment run must diverge from the control run in the specific direction the skill claims to produce. "Both agents produced fine-looking output" is not a pass — the question is whether the skill was the reason for the difference. If the two runs land on the same behavior, the skill has no measurable effect yet, no matter how clean its markdown is.
+
+If the comparison shows no behavioral difference, the skill is not done. Go back and sharpen the Workflow section, the triggers, or the examples — whichever part failed to actually steer the model — and rerun this gate. Do not ship on structural compliance alone.
+
+Skip this gate only when scaffolding a brand-new, still-empty skill (Step 2's placeholders haven't been filled in yet — there's no behavior to test). Once real content replaces the placeholders, this gate becomes mandatory before the skill is considered ready.
+
 ## Step 4 — Confirm and Next Up
 
 Print:
@@ -127,13 +142,16 @@ Print:
 
   All 5 required components are present (triggers, Overview, Workflow,
   Output Format, Examples). The placeholders need real content before
-  the skill becomes useful.
+  the skill becomes useful — and once they're filled in, run Step 3.5
+  (Prove It Moved the Needle) before calling the skill done.
 
 ▶ Next Up
   $EDITOR rcode/skills/actions/<group>/rcode-<NAME>/SKILL.md
                                                   # fill in placeholders
   npx @hanzlaa/rcode install --force              # install to .claude/skills/
   node --test test/compliance.test.cjs            # verify compliance
+                                                  # then: control vs. treatment
+                                                  # subagent run (Step 3.5)
 ```
 
 ## Next Up

package/rcode/workflows/scan.md

@@ -14,10 +14,12 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 ## Step 0 — Usage check
 
-If `$ARGUMENTS` is empty or contains only `--help` or `-h`:
+If `$ARGUMENTS` contains `--help` or `-h`:
 - Print the usage block below
 - STOP — do not proceed
 
+If `$ARGUMENTS` is empty, do NOT stop — proceed to Step 1, which defaults focus to `tech+arch`.
+
 **Usage:**
 ```
 /rcode-scan [--focus tech|arch|quality|concerns|tech+arch] [--refresh] [--reset]
@@ -339,6 +341,25 @@ This file tracks structural changes between scans. Each entry is auto-written by
 
 This file is **read by future `/rcode-scan --refresh` runs** as additional anchor context — the memory bank is self-improving across scans.
 
+## Step 6.6: Propagate scan findings into PROJECT.md / STATE.md stubs
+
+After the RETURNED banner, check whether `.planning/PROJECT.md` and `.planning/STATE.md` are still install stubs (contain the `<!-- INSTALL STUB` banner). If real, non-stub content already exists, skip this step entirely — never overwrite user-authored planning docs.
+
+```bash
+grep -q '<!-- INSTALL STUB' .planning/PROJECT.md 2>/dev/null && echo "PROJECT_IS_STUB"
+grep -q '<!-- INSTALL STUB' .planning/STATE.md 2>/dev/null && echo "STATE_IS_STUB"
+```
+
+If `PROJECT.md` is a stub: replace its `**One-line:**` sentence with a brief, grounded one-line summary derived from the scan output just written (e.g. from STACK.md/ARCHITECTURE.md's opening lines — language, framework, primary purpose). Keep the rest of the stub structure (Vision/Stack sections) intact; do not attempt a full rewrite. Use Read then Edit — never blind-overwrite.
+
+If `STATE.md` is a stub: update `**Current phase:**` line to read:
+```
+**Current phase:** none — existing project scanned, see .planning/codebase/ — no phases planned yet
+```
+and add one line under `## Next Action` noting the scan already ran: `Codebase scanned via /rcode-scan — run /rcode-new-project or /rcode-add-phase to plan phases.`
+
+This is a minimal, targeted edit — not a full PROJECT.md content-generation system. The goal is closing the "user opens STATE.md and sees zero acknowledgment a scan already ran" gap.
+
 ## Step 7: Final cue (orchestrator-level, after RETURNED banner)
 
 The RETURNED banner above is Dalil's voice. After it, the orchestrator may add ONE neutral cue line if the user might want a deeper scan:

package/rcode/workflows/secure-phase.md

@@ -3,7 +3,8 @@ Verify threat mitigations for a completed phase. Confirm SPRINT.md threat regist
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 </required_reading>
 
 <available_agent_types>
@@ -50,6 +51,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`,
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-security-auditor --raw)
 SECURITY_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.security_enforcement --raw 2>/dev/null || echo "true")
+
+# Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
+PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
+  .planning/phases/*${phase_number}*/*-CONTEXT.md \
+  .planning/ROADMAP.md 2>/dev/null | head -1)
 ```
 
 If `SECURITY_CFG` is `false`: exit with "Security enforcement disabled. Enable via /rcode-settings."

package/rcode/workflows/validate-phase.md

@@ -3,7 +3,8 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd
 </purpose>
 
 <required_reading>
-@.rcode/references/ui-brand.md
+<!-- ui-brand.md (254 lines): only load when the phase goal/CONTEXT.md contains UI signals — mirrors plan.md:49's PHASE_GOAL_HAS_UI pattern -->
+${PHASE_GOAL_HAS_UI ? '@.rcode/references/ui-brand.md' : ''}
 @.rcode/references/karpathy-guidelines.md
 </required_reading>
 
@@ -32,6 +33,11 @@ Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
 ```bash
 AUDITOR_MODEL=$(node ".rcode/bin/rcode-tools.cjs" resolve-model rcode-nyquist-auditor --raw)
 NYQUIST_CFG=$(node ".rcode/bin/rcode-tools.cjs" config-get workflow.nyquist_validation --raw)
+
+# Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
+PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
+  .planning/phases/*${phase_number}*/*-CONTEXT.md \
+  .planning/ROADMAP.md 2>/dev/null | head -1)
 ```
 
 If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /rcode-settings."

package/server/lib/html/client/components/Sidebar.js

@@ -63,11 +63,14 @@ export function Sidebar({ activeView, projectName }) {
   const name = project.name || projectName || 'No project';
   const user = (project.user && project.user.name) ? project.user : null;
 
-  // Full store subscription for live health badge counts.
+  // Full store subscription for live health badge counts. Derived from
+  // activeSessions (the /api/sessions poll) — same source of truth as the
+  // OrchPanel footer and NotifyCenter — not the static store.blockers list
+  // (PROJECT.md-backed, unrelated to live orchestrator state; see #965).
   // Re-renders on every setState (sessions poll every 4 s, state refresh every 30 s).
-  const { activeSessions, blockers } = useStore();
-  const sessionCount = (activeSessions || []).filter(s => s.status === 'running').length;
-  const blockerCount = (blockers || []).length;
+  const { activeSessions } = useStore();
+  const sessionCount = (activeSessions || []).filter(s => s.status === 'running' && !s.waiting).length;
+  const blockerCount = (activeSessions || []).filter(s => s.status === 'blocked' || s.waiting).length;
 
   return html`
     <aside class="sidebar" id="sidebar">
@@ -93,7 +96,7 @@ export function Sidebar({ activeView, projectName }) {
         </span>
         <span
           class=${'health-badge' + (blockerCount > 0 ? ' health-badge--alert' : ' health-badge--zero')}
-          title=${blockerCount + ' blocker' + (blockerCount === 1 ? '' : 's')}
+          title=${blockerCount + ' blocked orchestration session' + (blockerCount === 1 ? '' : 's')}
         >
           <${Icon} name="alert-triangle" size=${12} />
           ${blockerCount} blocked