@hanzlaa/rcode 4.8.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/agents/rcode-code-reviewer.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/code-reviewer-playbook.md
 

package/rcode/agents/rcode-docs-auditor.md

@@ -6,7 +6,7 @@ color: yellow
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 @.rcode/references/docs-auditor-playbook.md

package/rcode/agents/rcode-edge-case-hunter.md

@@ -6,7 +6,7 @@ color: red
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-security-adversary.md

@@ -6,7 +6,7 @@ color: red
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-security-auditor.md

@@ -6,7 +6,7 @@ color: purple
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/auditor-shared-checklists.md
 

package/rcode/agents/rcode-sprint-checker.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/sprint-checker-playbook.md
 
 <role>

package/rcode/agents/rcode-verifier.md

@@ -6,7 +6,7 @@ color: green
 ---
 
 @.rcode/references/response-style.md
-@.rcode/references/karpathy-guidelines-full.md
+@.rcode/references/karpathy-guidelines.md
 @.rcode/references/no-unauthorized-git-ops.md
 @.rcode/references/verifier-playbook.md
 

package/rcode/bin/rcode-tools.cjs

@@ -5402,6 +5402,109 @@ function cmdPlanCheckWaveOverlaps(rawArgs) {
   return { phase: phaseArg, phase_dir: path.relative(PROJECT_ROOT, phaseDir), plans_checked: plans.length, conflicts };
 }
 
+/**
+ * Deterministic frontend/backend glob check for classify-plan (issue #1021).
+ * Mirrors the FRONTEND_GLOBS / BACKEND_GLOBS rules formerly hand-applied by
+ * the orchestrating LLM in execute-waves.md — kept here as the single source
+ * of truth so both the CLI and the workflow doc describe the same behavior.
+ */
+function matchesFrontendGlob(file) {
+  const f = String(file || '').toLowerCase();
+  if (/\.(tsx|jsx|css)$/.test(f)) return true;
+  return f.includes('client') || f.includes('ui');
+}
+function matchesBackendGlob(file) {
+  const f = String(file || '').toLowerCase();
+  return f.includes('api') || f.includes('server') || f.includes('db') || f.includes('service');
+}
+
+const CLASSIFY_PLAN_ROUTE = { frontend: 'rcode-haitham', backend: 'rcode-yousef', 'full-stack': 'rcode-hanzla', other: 'rcode-executor' };
+
+function classifyPlanFiles(files, objective) {
+  const touchesFrontend = files.some(matchesFrontendGlob);
+  const touchesBackend = files.some(matchesBackendGlob);
+  let classification;
+  if (touchesFrontend && touchesBackend) classification = 'full-stack';
+  else if (touchesFrontend) classification = 'frontend';
+  else if (touchesBackend) classification = 'backend';
+  else classification = 'other';
+
+  if (classification === 'other') {
+    const obj = String(objective || '').toLowerCase();
+    const frontendKeywords = ['react', 'component', 'ui', 'css', 'tailwind', 'frontend', 'client-side', 'accessibility', 'a11y'];
+    const backendKeywords = ['api', 'endpoint', 'database', 'schema', 'service', 'queue', 'backend', 'server-side'];
+    if (frontendKeywords.some((k) => obj.includes(k))) classification = 'frontend';
+    else if (backendKeywords.some((k) => obj.includes(k))) classification = 'backend';
+  }
+  return classification;
+}
+
+/**
+ * classify-plan — deterministic replacement for execute-waves.md's
+ * hand-computed FRONTEND_GLOBS/BACKEND_GLOBS classification (issue #1021).
+ * A live execution run showed the orchestrating LLM never actually carried
+ * out the prose pseudocode, so a plan with a "db"-containing path still fell
+ * back to rcode-executor instead of rcode-yousef.
+ *
+ * Two call shapes:
+ *   classify-plan <phase> <plan-id>              — reads files_modified/objective from the plan's SPRINT.md
+ *   classify-plan --files=a,b,c --objective="..."  — classify an already-parsed list directly
+ */
+function cmdClassifyPlan(args) {
+  const flags = {};
+  const positional = [];
+  for (const t of args) {
+    if (t.startsWith('--files=')) flags.files = t.slice('--files='.length);
+    else if (t.startsWith('--objective=')) flags.objective = t.slice('--objective='.length);
+    else positional.push(t);
+  }
+
+  let files = [];
+  let objective = '';
+
+  if (flags.files !== undefined || flags.objective !== undefined) {
+    files = flags.files ? flags.files.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    objective = flags.objective || '';
+  } else {
+    const [phaseArg, planArg] = positional;
+    if (!phaseArg || !planArg) {
+      throw new Error('Usage: classify-plan <phase> <plan-id>  OR  classify-plan --files=a,b,c --objective="text"');
+    }
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const norm = phaseArg.replace(/^0+/, '') || '0';
+    let phaseDir = null;
+    if (fs.existsSync(phasesDir)) {
+      for (const d of fs.readdirSync(phasesDir)) {
+        const m = d.match(/^(\d+)(?:[-.])/);
+        if (m && (m[1].replace(/^0+/, '') || '0') === norm) { phaseDir = path.join(phasesDir, d); break; }
+      }
+    }
+    if (!phaseDir) throw new Error(`Phase not found: ${phaseArg}`);
+    let planFile = null;
+    for (const file of fs.readdirSync(phaseDir).filter((f) => /-SPRINT\.md$/i.test(f)).sort()) {
+      const stem = file.replace(/-SPRINT\.md$/i, '');
+      if (stem === planArg || stem.endsWith(`-${planArg}`)) { planFile = file; break; }
+      const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
+      const { frontmatter } = parseFrontmatter(text);
+      if ((frontmatter.sprint || frontmatter.plan) === planArg) { planFile = file; break; }
+    }
+    if (!planFile) throw new Error(`Plan not found: ${planArg} in phase ${phaseArg}`);
+    const text = fs.readFileSync(path.join(phaseDir, planFile), 'utf8');
+    const { frontmatter, body } = parseFrontmatter(text);
+    let block = '';
+    if (text.startsWith('---\n')) {
+      const end = text.indexOf('\n---\n', 4);
+      if (end !== -1) block = text.slice(4, end);
+    }
+    files = fmListField(block, 'files_modified');
+    const objMatch = body.match(/^##\s+(?:Objective|Goal)\s*\n+([^\n]+)/mi);
+    objective = objMatch ? objMatch[1].trim() : (frontmatter.goal || '').replace(/^["']|["']$/g, '');
+  }
+
+  const classification = classifyPlanFiles(files, objective);
+  return { classification, subagent_type: CLASSIFY_PLAN_ROUTE[classification], files_checked: files.length };
+}
+
 /** phases list — directory inventory under .planning/phases with optional --type filter and --pick path. */
 function cmdPhasesList(args) {
   const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
@@ -6658,6 +6761,9 @@ async function main() {
       case 'phase-plan-index':
         result = cmdPhasePlanIndex(args.join(' '));
         break;
+      case 'classify-plan':
+        result = cmdClassifyPlan(args);
+        break;
       case 'phases':
         if (args[0] === 'list') { result = cmdPhasesList(args.slice(1)); if (result === undefined) return; }
         else { console.error('Unknown phases subcommand. Valid: list'); process.exit(1); }

package/rcode/references/git-preflight.md

@@ -14,8 +14,11 @@ Run these read-only commands in order. Any failure halts the workflow with the f
 # Check 1: working tree clean
 DIRTY=$(git status --porcelain 2>/dev/null)
 
-# Check 2: not on a protected branch
+# Check 2: not on a protected branch (skipped entirely when `git.branching_strategy`
+# config is `none` — committing directly to main/master is the deliberately configured
+# workflow in that case)
 BRANCH=$(git branch --show-current 2>/dev/null)
+BRANCHING_STRATEGY=$(node .rcode/bin/rcode-tools.cjs config-get git.branching_strategy 2>/dev/null)
 PROTECTED="main master develop v2-prototype"
 
 # Check 3: branch follows naming convention
@@ -35,7 +38,7 @@ fi
 The workflow MUST stop and print the banner below if ANY of:
 
 - `DIRTY` is non-empty AND user did not pass `--allow-dirty`
-- `BRANCH` is in `$PROTECTED` AND user did not pass `--on-main`
+- `BRANCH` is in `$PROTECTED` AND `BRANCHING_STRATEGY` is not `none` AND user did not pass `--on-main`
 - `BRANCH_OK` is `no` AND user did not pass `--allow-dirty` (branch-name lint is advisory if working tree is dirty AND user accepted the dirty override)
 - `OUT_OF_SCOPE` is non-empty AND user did not pass `--allow-scope-drift`
 

package/rcode/references/output-format.md

@@ -42,7 +42,7 @@ Use for major workflow transitions.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► {STAGE NAME}
+ rcode ► {STAGE NAME}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -69,7 +69,7 @@ Use this when a router command dispatches to another command:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► ROUTING
+ rcode ► ROUTING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Input: {user's question or intent}
@@ -328,7 +328,7 @@ Use standard markdown pipe tables with status symbols:
 **Majlis banner** (multi-agent council):
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► MAJLIS CONVENING
+ rcode ► MAJLIS CONVENING
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -354,7 +354,7 @@ the banner, not inside it.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- RCODE ► PLANNING SPRINT 01.1
+ rcode ► PLANNING SPRINT 01.1
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 التخطيط للسباق 01.1 — يرجى الانتظار
 ```
@@ -389,7 +389,7 @@ translated prose goes outside the art, on its own line(s).
 
 - Varying box/banner widths within same output
 - Mixing banner styles (`===`, `---`, `***`)
-- Skipping `RCODE ►` prefix in stage banners
+- Skipping `rcode ►` prefix in stage banners
 - Random emoji (`🚀`, `✨`, `💫`) outside the approved set
 - Missing Next Up block after workflow completions
 - Hardcoding references to other methodologies in rcode's UX

package/rcode/workflows/add-phase.md

@@ -29,11 +29,21 @@ Exit.
 Load phase operation context:
 
 ```bash
-INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "0" 2>/dev/null)
+INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "1" 2>/dev/null)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-If `INIT` is empty or `INIT.ok` is false, print error and exit:
+`init phase-op` only populates the phase-aware fields (`roadmap_exists`,
+`planning_exists`, `phase_found`, ...) when its `question` argument's first
+token parses as an integer `> 0` (rcode-tools.cjs's `phase-op` handler gates
+on `phaseNum > 0`). add-phase has no target phase to pass — it's creating a
+new one — so a placeholder is required. `"0"` fails that guard, silently
+dropping `roadmap_exists` from every response (#1017); `"1"` satisfies it.
+The dummy value only affects unused fields like `phase_found`/`phase_name`
+(harmless here) — `roadmap_exists` itself is purely a file-existence check
+and doesn't depend on phase 1 actually existing.
+
+If `INIT` is empty, print error and exit:
 ```
 Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
 ```
@@ -92,7 +102,13 @@ The CLI handles:
 - Creating the phase directory (`.planning/phases/{NN}-{slug}/`)
 - Inserting the phase entry into ROADMAP.md with Goal, Depends on, and Plans sections
 
-Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`.
+Extract from result: `phase_number`, `padded`, `name`, `slug`, `directory`,
+`milestone_health` (object: `open_phases`, `recommendation`, `threshold_should`,
+`threshold_consider`), `nudge` (present only when `recommendation` isn't
+`healthy` — a ready-to-print one-liner naming the milestone). `phase add`
+computes these via `milestoneCloseNudge()` (issue #942) as part of the same
+call, so `milestone_health_check` below reads them straight off `$RESULT`
+instead of re-deriving them.
 
 **If `BULK_MODE=true`:** after the CLI returns, write the bulk body to `${directory}/TASKS.md` per the structure defined in `detect_task_list`. This step is non-destructive — it only ADDs a TASKS.md file inside the new phase directory.
 </step>
@@ -110,26 +126,30 @@ If "Roadmap Evolution" section doesn't exist, create it.
 </step>
 
 <step name="milestone_health_check">
-After the phase is added, run the milestone-health gauge (issue #718):
+After the phase is added, read the milestone-health gauge (issue #718)
+straight off the `phase add` result captured in `add_phase` — no extra
+subprocess calls. Previously this step spawned a separate `milestone-health`
+call plus 3 `node -e` JSON field extractions to re-derive data that `phase
+add` already returns inline via `milestoneCloseNudge()` (#942); that was
+4 wasted calls per phase-add for data already sitting in `$RESULT` (#1018).
 
-```bash
-HEALTH=$(node ".rcode/bin/rcode-tools.cjs" milestone-health 2>/dev/null)
-RECOMMENDATION=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).recommendation||'unknown')}catch{console.log('unknown')}})")
-OPEN_COUNT=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).open_phases||0)}catch{console.log(0)}})")
-MILESTONE_NAME=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).milestone||'')}catch{console.log('')}})")
+```
+RECOMMENDATION="$RESULT.milestone_health.recommendation"   # e.g. healthy | consider-closing | should-close
+OPEN_COUNT="$RESULT.milestone_health.open_phases"
+NUDGE="$RESULT.nudge"                                       # ready-to-print, names the milestone; absent when healthy
 ```
 
 If `RECOMMENDATION` is `should-close` (≥12 open phases), surface a hard nudge:
 
 ```
-⚠ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases.
+⚠ {NUDGE}
 
 Phase {N} is now in this milestone, but the milestone is well past the
 12-phase threshold for considering closure. Phases are accumulating without
 a milestone boundary — historically this is where roadmaps lose structure.
 
 Recommended next step:
-  /rcode-complete-milestone    close {MILESTONE_NAME} cleanly + archive done phases
+  /rcode-complete-milestone    close the milestone cleanly + archive done phases
   /rcode-new-milestone         start a fresh milestone for ongoing work
 
 If you genuinely want a giant single-milestone roadmap, ignore this and
@@ -139,11 +159,10 @@ continue. The threshold is conservative on purpose.
 If `RECOMMENDATION` is `consider-closing` (8-11 open phases), softer nudge:
 
 ```
-ℹ Milestone health: {MILESTONE_NAME} has {OPEN_COUNT} open phases — getting full.
-   Consider /rcode-complete-milestone before adding more.
+ℹ {NUDGE}
 ```
 
-If `RECOMMENDATION` is `healthy`, say nothing.
+If `RECOMMENDATION` is `healthy` or `milestone_health` is absent (no state.json / no milestone), say nothing.
 </step>
 
 <step name="completion">

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>
@@ -238,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.
@@ -265,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.
@@ -352,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"
 ```
@@ -361,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)"
 
@@ -527,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
@@ -745,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
@@ -761,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.

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.