@hanzlaa/rcode 4.13.0 → 4.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.13.0",
+  "version": "4.14.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-project-researcher.md

@@ -21,7 +21,7 @@ Your files feed the roadmap:
 | File | How Roadmap Uses It |
 |------|---------------------|
 | `SUMMARY.md` | Phase structure recommendations, ordering rationale |
-| `STACK.md` | Technology decisions for the project |
+| `STACK.md` | Technology **suggestions** for the project, with the premise behind each |
 | `FEATURES.md` | What to build in each phase |
 | `ARCHITECTURE.md` | System structure, component boundaries |
 | `PITFALLS.md` | What phases need deeper research flags |
@@ -125,3 +125,21 @@ Log each pass as:
 ## Examples
 
 See `.rcode/agents-rules/project-researcher/detailed-guide.md` for full worked examples (happy path, edge case, negative).
+
+## STACK.md is a suggestion, never a decision
+
+You do not choose the stack. You surface options and the trade-off, and the user
+decides at the stack gate (`new-project-research-decision.md` step 6b).
+
+Write STACK.md accordingly:
+
+- **Every recommendation carries its premise** — the one condition that makes it
+  right. Not "WordPress is popular for content sites" but "WordPress IF a
+  non-technical person will update content with no dev retainer."
+- **Name the closest alternative and when it wins.** A recommendation with no
+  alternative is a decision wearing a recommendation's clothes.
+- **Never write "Locked", "Final", or "Decided"** in STACK.md. You have no
+  authority to lock anything; only a user answer at the gate does that.
+
+A premise you cannot state is a recommendation you have not justified. Say you
+don't have enough to recommend one rather than picking the familiar option.

package/rcode/bin/lib/roadmap.cjs

@@ -127,28 +127,69 @@ function extractPhases(content) {
   return phases;
 }
 
+// Requirement IDs come in two shapes and BOTH are real:
+//   REQ-AUTH, REQ-FOO-BAR   — the documented convention
+//   FOUND-01, RENT-04, OBJ-06, AUTHZ-04 — what projects actually write
+// This must stay in step with extractReqIds() in rcode-tools.cjs. Two copies of
+// this pattern already drifted once: one was widened for domain prefixes and
+// this one was not, so `roadmap get-phase` kept returning requirements: [] on
+// every domain-prefixed project.
+const REQ_ID_RE = /\bREQ-[A-Z0-9][A-Z0-9-]*\b|\b[A-Z][A-Z0-9]{1,15}-\d+[a-z]?\b/g;
+
+/**
+ * Build a matcher for a labelled block, tolerant of how the label is actually
+ * written. Roadmapper emits `**Success criteria:**` (colon inside the bold,
+ * lowercase c) while the old parser demanded `**Success Criteria**:` (colon
+ * outside). Two rcode components disagreeing about rcode's own format is what
+ * made get-phase unable to read its own roadmapper's output.
+ *
+ * Accepts: **Label:**  |  **Label**:  |  ## Label  |  Label:
+ * Returns { inline, list } — inline is same-line content, list is the block
+ * of bullet/numbered lines that follows. Callers use whichever is present.
+ */
+function matchLabelledBlock(section, label) {
+  const l = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // [ \t]* everywhere the match must NOT cross a line. Using \s* here let the
+  // label matcher swallow the newline, so the first bullet of the following
+  // list was captured as "inline" and its description text was thrown away —
+  // `- CITY-02 per-city page exists` came back as just `CITY-02`.
+  const re = new RegExp(
+    '(?:\\*\\*[ \\t]*' + l + '[ \\t]*:?[ \\t]*\\*\\*[ \\t]*:?|#{1,4}[ \\t]*' + l + '[ \\t]*:?|^[ \\t]*' + l + '[ \\t]*:)' +
+    '([^\\n]*)\\n((?:[ \\t]*(?:\\d+\\.|[-*])[ \\t]+[^\\n]+\\n?)*)',
+    'im'
+  );
+  const m = section.match(re);
+  if (!m) return null;
+  return { inline: (m[1] || '').trim(), list: m[2] || '' };
+}
+
+function splitListBlock(block) {
+  return String(block).split('\n')
+    .map((l) => l.replace(/^[ \t]*(?:\d+\.|[-*])[ \t]+/, '').trim())
+    .filter(Boolean);
+}
+
 function parseRequirements(section) {
-  // Matches both bold-style (**Requirements:**) and heading-style (### Requirements)
-  // followed by a list block.
-  const listMatch = section.match(/(?:\*\*Requirements(?::\*\*|\*\*:)|#{1,4}\s*Requirements\s*:?)[^\n]*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (listMatch) {
-    return listMatch[1].split('\n')
-      .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-      .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Requirements');
+  if (block) {
+    // A following list block wins; otherwise take the same-line value, which is
+    // how roadmapper writes it: `**Requirements:** FOUND-01, FOUND-02, RENT-04`.
+    const fromList = splitListBlock(block.list);
+    if (fromList.length > 0) return fromList;
+    if (block.inline) {
+      const ids = block.inline.match(REQ_ID_RE);
+      if (ids && ids.length > 0) return [...new Set(ids)];
+      return block.inline.split(/\s*,\s*/).map(x => x.trim()).filter(Boolean);
+    }
   }
 
-  // Also capture REQ-IDs from inline lines like:
-  //   **REQs:** REQ-004, REQ-010, REQ-020
-  //   Requirements: REQ-001, REQ-002
-  //   **Covers:** REQ-001, REQ-003
-  // Collect every line in the section that contains REQ-\d+ patterns.
+  // Last resort: sweep the whole section for requirement IDs on any line
+  // (covers `**REQs:**`, `**Covers:**`, and prose mentions).
   const seen = new Set();
   const out = [];
-  const reqIdRe = /\bREQ-[A-Z0-9][A-Z0-9-]*\b/g;
   for (const line of section.split('\n')) {
-    if (!/REQ-/i.test(line)) continue;
-    const ids = line.match(reqIdRe) || [];
-    for (const id of ids) {
+    const matches = line.match(REQ_ID_RE) || [];
+    for (const id of matches) {
       if (!seen.has(id)) { seen.add(id); out.push(id); }
     }
   }
@@ -156,12 +197,11 @@ function parseRequirements(section) {
 }
 
 function parseSuccessCriteria(section) {
-  // Matches both bold-style (**Success Criteria:**) and heading-style (### Success Criteria)
-  const match = section.match(/(?:\*\*Success Criteria\*\*[^\n]*:|#{1,4}\s*Success Criteria\s*:?)\s*\n((?:\s*(?:\d+\.|[-*])\s+[^\n]+\n?)+)/i);
-  if (!match) return [];
-  return match[1].split('\n')
-    .map((l) => l.replace(/^\s*(?:\d+\.|[-*])\s+/, '').trim())
-    .filter(Boolean);
+  const block = matchLabelledBlock(section, 'Success criteria');
+  if (!block) return [];
+  const fromList = splitListBlock(block.list);
+  if (fromList.length > 0) return fromList;
+  return block.inline ? [block.inline] : [];
 }
 
 function parsePlans(section) {

package/rcode/bin/rcode-tools.cjs

@@ -193,7 +193,13 @@ function extractReqIds(requirements) {
   if (!Array.isArray(requirements) || requirements.length === 0) return [];
   const seen = new Set();
   const out = [];
-  const re = /\bREQ-[A-Z0-9][A-Z0-9-]*\b/g;
+  // Two shapes, because real projects rarely use the REQ- prefix:
+  //   REQ-AUTH, REQ-FOO-BAR   — the documented convention
+  //   FOUND-01, RENT-04, AUTHZ-04, OBJ-06, CITY-02 — what projects actually write
+  // Matching only the first shape returned an empty phase_req_ids on every
+  // domain-prefixed project, and plan.md's Requirements Coverage Gate skips
+  // itself when that array is empty. The gate was silently off, not passing.
+  const re = /\bREQ-[A-Z0-9][A-Z0-9-]*\b|\b[A-Z][A-Z0-9]{1,15}-\d+[a-z]?\b/g;
   for (const line of requirements) {
     const matches = String(line).match(re) || [];
     for (const m of matches) {
@@ -1414,6 +1420,26 @@ function cmdState(subArgs) {
   // --- set-phase ---
   if (sub === 'set-phase') {
     const name = subArgs[1];
+    // A flag-looking argument is never a phase name. Without this,
+    // `state set-phase --phase 99 --status complete` created a phase literally
+    // NAMED "--phase", set current_phase to "--phase", and returned ok:true.
+    // Silent state corruption reported from a live project.
+    if (typeof name === 'string' && name.startsWith('--')) {
+      throw new Error(
+        `set-phase takes a phase NAME as a positional argument, not flags. ` +
+        `Got "${name}". Did you mean:\n` +
+        `  state set-phase "Phase name"        (set the current phase pointer)\n` +
+        `  phase complete <N>                  (mark a phase complete)\n` +
+        `  state planned-phase --phase <N>     (record a phase as planned)`
+      );
+    }
+    const strayFlags = subArgs.slice(2).filter(a => typeof a === 'string' && a.startsWith('--'));
+    if (strayFlags.length > 0) {
+      throw new Error(
+        `set-phase does not accept flags (${strayFlags.join(', ')}). It sets the ` +
+        `current-phase pointer only. Use 'phase complete <N>' to change a phase's status.`
+      );
+    }
     if (!name) throw new Error('set-phase requires a phase name argument');
     const state = readState() || defaultState();
     // Fix #854 — mark the previously active phase as completed before switching.
@@ -3256,6 +3282,29 @@ function cmdState(subArgs) {
   // instead. Its stale-executing-phase hygiene warning was ported there.
   // Kept only for backward compatibility with anyone scripting against it
   // directly; do not wire new callers to this — use `phase complete`.
+  // Records what the user actually authorized this session — 'plan', 'build',
+  // 'research', 'audit'. `resume-work` reads it so "resume" restores POSITION
+  // AND SCOPE, not position alone. Without it, a resume after a planning
+  // session reads as "keep going" and starts building work nobody asked for.
+  if (sub === 'set-intent') {
+    const flags = parseFlags(1);
+    const intent = flags.intent || subArgs[1];
+    const ALLOWED = ['plan', 'build', 'research', 'audit', 'review'];
+    if (!intent) throw new Error(`set-intent requires an intent (${ALLOWED.join('|')})`);
+    if (!ALLOWED.includes(intent)) {
+      throw new Error(`unknown intent "${intent}" — expected one of: ${ALLOWED.join(', ')}`);
+    }
+    const state = readState() || defaultState();
+    const previous = state.last_intent ? state.last_intent.intent : null;
+    state.last_intent = {
+      intent,
+      recorded_at: new Date().toISOString(),
+      source: flags.source || 'workflow',
+    };
+    writeState(state);
+    return { ok: true, intent, previous };
+  }
+
   if (sub === 'complete-phase') {
     const flags = parseFlags(1);
     if (!flags.phase) throw new Error('complete-phase requires --phase <N>');
@@ -3582,6 +3631,32 @@ function cmdState(subArgs) {
         }
 
         if (existingIdx >= 0) {
+          // Identity check BEFORE anything is carried over. Sync matched this
+          // entry by NUMBER, but a number is a slot, not an identity. When a
+          // roadmap is replaced, slot 3 can go from "Location Template" to
+          // "Competitor Gap Analysis" — two unrelated pieces of work. Carrying
+          // the old status across told a live project that competitor analysis
+          // was "complete" when it had never been started, and only a manual
+          // disk audit caught it.
+          const priorName = String(state.phases[existingIdx].name || '').trim();
+          const incomingName = String(phaseName || '').trim();
+          const normName = (n) => n.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+          const identityChanged = priorName && incomingName
+            && normName(priorName) !== normName(incomingName);
+          if (identityChanged) {
+            // Different work in the same slot. Drop the inherited status and
+            // completion, and let the disk-derived pass below decide afresh.
+            state.phases[existingIdx].status = 'planned';
+            delete state.phases[existingIdx].completed;
+            delete state.phases[existingIdx].started;
+            parsed.identity_changed = parsed.identity_changed || [];
+            parsed.identity_changed.push({
+              phase: phaseNum,
+              was: priorName,
+              now: incomingName,
+              carried_status_dropped: true,
+            });
+          }
           // Backfill both id and number so future readers using either schema find it.
           state.phases[existingIdx].number = state.phases[existingIdx].number || phaseNum;
           state.phases[existingIdx].id = state.phases[existingIdx].id || phaseNum;
@@ -4468,6 +4543,70 @@ function cmdPhase(subArgs) {
   // Closes #731. No --names arg required — reads the ROADMAP table directly.
   // Only creates directories; does NOT create .md files inside them.
   // =====================================================================
+  // phase rename-dir <N> — align a phase directory's slug with its ROADMAP name.
+  // Dry-run by default: renaming a directory moves artifacts and, without git mv,
+  // detaches their history. There was no mechanism for this at all, so a roadmap
+  // rewrite left every directory carrying the name of whatever it used to be.
+  if (sub === 'rename-dir') {
+    // cmdPhase has no shared flag parser (parseFlags is local to cmdState), so
+    // read the two flags this needs directly.
+    const argvIdx = subArgs.findIndex((a, i) => i > 0 && !String(a).startsWith('--'));
+    const phaseFlagIdx = subArgs.indexOf('--phase');
+    const target = argvIdx > 0 ? subArgs[argvIdx]
+      : (phaseFlagIdx !== -1 ? subArgs[phaseFlagIdx + 1] : null);
+    if (!target) throw new Error('phase rename-dir requires a phase number');
+    const apply = subArgs.includes('--apply');
+
+    const found = cmdFindPhase([String(target)]);
+    if (!found.exists) throw new Error(`No phase directory on disk for phase ${target}`);
+
+    const roadmapLib = require(path.join(__dirname, 'lib', 'roadmap.cjs'));
+    const rp = roadmapLib.dispatch(PROJECT_ROOT, ['get-phase', String(target)]);
+    if (!rp || !rp.found || !rp.name) {
+      throw new Error(`Phase ${target} not found in ROADMAP.md — nothing to rename toward`);
+    }
+
+    const slugify = (t) => String(t).toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').replace(/-+/g, '-');
+    const newSlug = slugify(rp.name);
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const oldDirName = path.basename(found.dir);
+    const newDirName = `${target}-${newSlug}`;
+
+    if (oldDirName === newDirName) {
+      return { ok: true, renamed: false, reason: 'directory already matches the roadmap name', dir: found.dir };
+    }
+    const newPath = path.join(phasesDir, newDirName);
+    if (fs.existsSync(newPath)) {
+      throw new Error(`Target directory already exists: ${newDirName}. Resolve by hand — two phase dirs for one number is worse than a stale name.`);
+    }
+
+    if (!apply) {
+      return {
+        ok: true,
+        renamed: false,
+        dry_run: true,
+        from: oldDirName,
+        to: newDirName,
+        note: 'Dry run. Re-run with --apply to rename. Check first that the artifacts in this directory belong to the phase the roadmap now describes — if the phase was REPLACED rather than renamed, renaming hides that instead of fixing it.',
+      };
+    }
+
+    // Prefer `git mv` so the artifacts keep their history.
+    const oldPath = path.join(phasesDir, oldDirName);
+    let method = 'fs';
+    const { spawnSync } = require('child_process');
+    const gitMv = spawnSync('git', ['mv', oldPath, newPath], { cwd: PROJECT_ROOT, encoding: 'utf8' });
+    if (gitMv.status === 0) { method = 'git mv'; }
+    else { fs.renameSync(oldPath, newPath); }
+
+    return {
+      ok: true, renamed: true, method,
+      from: oldDirName, to: newDirName,
+      warning: 'Any file referencing the old path (SPRINT frontmatter, SUMMARY links, notes) still points at it. Grep for the old slug.',
+    };
+  }
+
   if (sub === 'scaffold-all') {
     const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
     const phasesDir   = path.join(PLANNING_DIR, 'phases');
@@ -5801,11 +5940,52 @@ function cmdFindPhase(args) {
     .map((d) => path.relative(PROJECT_ROOT, path.join(phasesDir, d)));
   if (!exact) return { number: target, exists: false, dir: null, slug: null, decimal_children };
   const slugMatch = exact.match(/^\d+(?:\.\d+)?[-](.+)$/);
+  const slug = slugMatch ? slugMatch[1] : '';
+
+  // Name drift: the directory keeps the slug it was created with, but ROADMAP.md
+  // can be rewritten under it. Resolving to the existing directory is correct —
+  // that is where the artifacts and the git history live, and auto-renaming would
+  // orphan both. Staying SILENT about the divergence is not: an agent reading
+  // `slug: foundation-contact-loop` while the roadmap says "Rentable Contact
+  // Layer" has no way to tell whether it is looking at the same work.
+  // Same class as the phase-identity drift in `state sync --from-disk`.
+  let name_drift = null;
+  try {
+    const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+    if (slug && fs.existsSync(roadmapPath)) {
+      const roadmapLib = require(path.join(__dirname, 'lib', 'roadmap.cjs'));
+      const rp = roadmapLib.dispatch(PROJECT_ROOT, ['get-phase', String(target)]);
+      const roadmapName = rp && rp.found ? String(rp.name || '') : '';
+      if (roadmapName) {
+        const slugify = (t) => String(t).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        const fromRoadmap = slugify(roadmapName);
+        // Compare on word sets, not exact slugs — a truncated or reordered slug
+        // is normal, a different subject is the signal.
+        const words = (t) => new Set(String(t).split('-').filter(w => w.length > 3));
+        const dirWords = words(slug);
+        const roadWords = words(fromRoadmap);
+        const shared = [...dirWords].filter(w => roadWords.has(w)).length;
+        if (dirWords.size > 0 && roadWords.size > 0 && shared === 0) {
+          name_drift = {
+            dir_slug: slug,
+            roadmap_name: roadmapName,
+            note: 'Directory name and ROADMAP name share no significant words. '
+                + 'The phase may have been replaced under the same number. '
+                + 'The directory is NOT auto-renamed: its artifacts and git history '
+                + 'belong to whatever was built there. Confirm they are the same work '
+                + 'before planning or executing against it.',
+          };
+        }
+      }
+    }
+  } catch { /* drift detection is advisory — never fail a lookup over it */ }
+
   return {
     number: target,
     exists: true,
     dir: path.relative(PROJECT_ROOT, path.join(phasesDir, exact)),
-    slug: slugMatch ? slugMatch[1] : '',
+    slug,
+    name_drift,
     decimal_children,
   };
 }
@@ -7434,6 +7614,7 @@ async function main() {
         console.log('  phase next-range [count]                     → return next N contiguous free phase numbers (#730)');
         console.log('  phase scaffold-milestone --names "n1|n2|..." → bulk-create phase folders for a milestone (#731)');
         console.log('  phase scaffold-all                           → create missing phase folders for all phases in ROADMAP.md (#731)');
+        console.log('  phase rename-dir <N> [--apply]               → align a phase dir slug with its ROADMAP name (dry-run by default)');
         console.log('  workflow-config-audit                        → find workflows still referencing .planning/config.json (#733)');
         console.log('  commit "<msg>" [--files p1 p2 ...]          → atomic git commit with conventional-commits validation (no AI attribution, no --no-verify, no auto-push)');
         console.log('  commit-to-subrepo --subrepo <p> "<msg>"     → atomic commit inside a git subrepo (same validation as commit)');
@@ -7524,7 +7705,7 @@ async function main() {
         console.log('  state story list [--sprint <NN.S>] [--status <status>]');
         return;
       default: {
-        const stateSubs = ['read','get','init','set-phase','advance-plan','snapshot','update-progress','record-execution','record-council','record-chain','add-decision','decisions-global','add-blocker','resolve-blocker','record-session','set-ids-in-state','migrate-ids','migrate-schema','next-phase-id','next-plan-id','next-task-id','resolve-id','workstream-create','workstream-switch','workstream-list','workstream-status','workstream-complete','workstream-validate','insert-phase','planned-phase','begin-phase','complete-phase','reset'];
+        const stateSubs = ['read','get','init','set-phase','advance-plan','snapshot','update-progress','record-execution','record-council','record-chain','add-decision','decisions-global','add-blocker','resolve-blocker','record-session','set-ids-in-state','migrate-ids','migrate-schema','next-phase-id','next-plan-id','next-task-id','resolve-id','workstream-create','workstream-switch','workstream-list','workstream-status','workstream-complete','workstream-validate','insert-phase','planned-phase','begin-phase','complete-phase','set-intent','reset'];
         // Issue #656 — top-level aliases for intuitive guesses.
         const intuitionAliases = {
           blocker: 'state resolve-blocker',

package/rcode/references/agent-shared-rules.md

@@ -41,6 +41,42 @@ on what it touches, so a high score is corroboration and a zero score is no
 information. When your reading disagrees with the score, your reading wins, and
 you name the file or decision that made you override.
 
+**Elicitation is not authoring — hand the pen back.** When gathering what the user
+wants, the moment you catch yourself naming the stack, picking the MVP cut, or
+proposing the phase breakdown, stop and hand it back to them. Infer-and-confirm
+("I'm assuming the maintainer is you, not a client — right?") is fine; presenting
+your conclusion as a finding is not. Every inferred value that reaches an artifact
+carries an inline `[ASSUMPTION]` tag, and every tag gets walked with the user
+before that artifact is final. An untriaged assumption in a finished document is a
+decision nobody made.
+
+**Never decide the stack for the user.** Technology choice — language, framework,
+CMS, database, hosting model — is the user's call, always. Research produces a
+suggestion; only the user turns it into a decision. Present it with the ONE reason
+that actually drove it, in their terms, and offer three ways out: confirm it, name
+their own, or ask for more comparison. Then stop. No default, no auto-selection,
+no "the obvious choice for this domain" — a wrong stack is the single most
+expensive thing in a project to reverse.
+
+**Write the premise into the decision, and re-open it when the premise dies.** "X
+because a non-technical client updates content themselves" stays true only while
+there is a non-technical client. When the project pivots, every decision whose
+stated reason the pivot invalidated goes back to the user. A decision whose reason
+has expired is not locked, it is stale — and treating it as locked is how a
+codebase gets built twice.
+
+**Planning never authorizes building.** If the user asked you to plan, design,
+research, or audit, the deliverable is the plan, the design, the findings — not
+the implementation. Finishing the plan and continuing into code is not
+thoroughness, it is doing work nobody approved, and it costs more to unwind than
+it saved. The same applies to an ambiguous continuation like "resume", "carry
+on", or "next": it restores POSITION, never SCOPE. When the standing instruction
+was to plan, a resume continues planning.
+
+If you believe the next step is obvious and valuable, say so in one line and stop.
+The user typing the next command takes two seconds; undoing an unrequested build
+took a whole session.
+
 ---
 
 ## Redirect protocol

package/rcode/references/planner-playbook.md

@@ -154,6 +154,17 @@ autonomous: true|false
 files_modified: [...]
 requirements: [...]
 must_haves: {truths, artifacts, key_links}
+
+**`truths` are copied from the requirement's Consequences, not invented.** For
+each requirement this plan claims, read its `**Consequences (testable):**` list in
+REQUIREMENTS.md and carry those lines into `must_haves.truths` verbatim. You are
+transcribing a decision someone already made, not making a new one.
+
+Invent a truth only when the requirement has no consequences recorded — and when
+you do, say so in the plan (`[DERIVED]` prefix on that truth) so the verifier
+knows it is checking your reconstruction rather than the requirement's own
+criteria. A phase full of `[DERIVED]` truths is a signal the requirements were
+never finished, not a signal to proceed quietly.
 ---
 
 ## Sprint {phase}.{plan}: {one-line sprint goal, plain English, no jargon}

package/rcode/references/questioning.md

@@ -105,10 +105,108 @@ A well-paced Socratic conversation follows a natural arc:
    ↓ Proceed to planning or revisit if gaps remain
 ```
 
-Each phase should feel **natural, conversational**, not like a checklist. If the user volunteers information, use it; don't force a predetermined sequence.
+Each phase should feel **natural, conversational**, not like a checklist. If the user volunteers information, use it; don't force a predetermined sequence. **This is a rule about TONE, not about coverage** — the decisions in the Mandatory decision set below still all get resolved, in whatever order the conversation makes natural.
 
 ---
 
+## Working mode — offer it, don't read it from config
+
+**Before any planning questions, ask how the user wants to work.** This is a
+per-run choice presented to them, never a config flag read silently:
+
+- **Fast path** — batch the remaining gaps into one or two consolidated
+  questions, then draft the full artifact, marking every inferred value with an
+  `[ASSUMPTION]` tag inline. The user reviews and iterates. Initial quality
+  depends on how much they gave upfront.
+- **Coaching path** — walk the decisions together, section by section.
+
+Why it must be asked: a user who never enabled autonomous mode should never be
+*treated* as if they had. Confirmed live — a user asked for a project to be
+planned, was never offered this choice, got no defined questions, and received a
+plan built on assumptions they never saw. "You didn't turn on yolo" is not a
+defence when nothing ever asked.
+
+Auto/yolo mode picks Fast path automatically. Everything else asks.
+
+## Stakes calibration — one probe, before anything else
+
+Ask once, early: **is this a hobby/solo thing, an internal tool, or a launch?**
+Then scale rigor to the answer. rcode's pipeline is built for the launch case and
+applying it whole to a weekend project is its own kind of failure — the user
+abandons the process rather than the project.
+
+| Stakes | Depth |
+|---|---|
+| Hobby / solo | Minimal artifacts. Reviewer gates run quietly or not at all |
+| Internal tool | Normal pipeline, lighter review |
+| Launch / production | Full pipeline, all gates, nothing skipped |
+
+## Elicitation, not direction — the hand-back rule
+
+Discovery pulls the user's vision out. It does not insert yours.
+
+**When you catch yourself naming the stack, picking the MVP cut, or proposing the
+phase breakdown — stop. You have crossed from asking into authoring. Hand the pen
+back.**
+
+Infer-and-confirm is fine: *"I'm assuming the maintainer is you, not a client —
+right?"* Quizzing the user through a tree of your own options is not, and neither
+is presenting your conclusion as the finding.
+
+This is the rule that would have prevented the most expensive failure in rcode's
+own history: a session picked a stack, phased a roadmap around it, and built on
+it, having never handed the pen back once.
+
+## Mandatory decision set — tone is conversational, coverage is not
+
+The "don't feel like a checklist" rule above governs **tone**. It does not govern
+**coverage**. There is a set of decisions that shape everything downstream, and
+each one must be either answered by the user or recorded as an assumption with
+its reason. Silently deciding one on the user's behalf is not conversational
+skill, it is skipping the question.
+
+Confirmed live: a user asked for a project to be planned, was never asked a
+single defined question, and got a stack, a roadmap, and an implementation built
+on a premise they had never confirmed. When the premise turned out to be wrong
+the whole build was thrown away. Nothing in this file forced the question,
+because this file told the asker to avoid predetermined sequences.
+
+Every one of these must be resolved before PROJECT.md is written:
+
+| Decision | Why it cannot be assumed |
+|---|---|
+| **Who maintains this after launch** | Drives the stack more than any technical factor. "Non-technical client" and "you, the technical owner" give opposite answers |
+| **Stack** | Most expensive thing in the project to reverse. Never decided for the user — see the stack gate |
+| **Who the users are, and whether there are roles** | Auth, permissions, and data model all hang off it |
+| **What is explicitly OUT of scope for v1** | An unstated exclusion reappears later as a gap |
+| **What already exists** | Greenfield vs brownfield changes every phase |
+| **What "done" means for the first milestone** | Without it there is no way to verify anything |
+| **Any hard constraint** — budget, deadline, hosting, compliance, locale | These invalidate otherwise-correct plans |
+
+**How to run it without sounding like a form:** weave them into the conversation
+in whatever order the user's own answers suggest — that part stays conversational.
+But **track them, and before you write PROJECT.md, state which ones the user
+actually answered and which you are assuming, with the assumption spelled out.**
+
+```
+Before I write this up — you answered: maintainer (you), scope (city pages only),
+users (visitors, no login).
+I'm assuming: no deadline, hosting undecided, English only.
+Correct any of those, or say go.
+```
+
+**Tag assumptions in the artifact itself, not just in chat.** Every inferred value
+written into PROJECT.md, REQUIREMENTS.md, or ROADMAP.md carries an inline
+`[ASSUMPTION]` marker. A summary the user scrolled past is not consent; a tag in
+the document survives the conversation and can be triaged later.
+
+Before any artifact is marked final, **walk every `[ASSUMPTION]` tag with the
+user**: confirm it, correct it, or defer it with an owner. An untriaged assumption
+in a finalised document is a decision nobody made.
+
+That block is not optional and auto mode does not remove it. An assumption the
+user never saw is indistinguishable from a decision you made for them.
+
 ## Context Checklist
 
 After Socratic questioning, verify these dimensions were covered:
@@ -122,7 +220,7 @@ After Socratic questioning, verify these dimensions were covered:
 - [ ] **Auth/identity** — SSO, local accounts, guest access, or a specific IdP?
 - [ ] **Locale/i18n** — Which languages/regions must be supported, RTL needed?
 
-If gaps remain after natural conversation, weave questions naturally. Don't suddenly shift to checklist mode.
+If gaps remain after natural conversation, weave questions naturally. Don't suddenly shift to checklist mode — but do NOT let "not a checklist" become "never asked". Anything from the Mandatory decision set still unresolved gets asked outright before you move on, plainly, rather than silently assumed.
 
 ---
 

package/rcode/references/roadmapper-playbook.md

@@ -145,6 +145,20 @@ Read only when the current task needs the detail. Don't preemptively load.
 ## Workflow
 
 1. **Read context** — REQUIREMENTS.md, FEATURES.md, ARCHITECTURE.md, STACK.md, RESEARCH.md (per `<files_to_read>`).
+   **STACK.md is a suggestion until a `state add-decision` entry shows the user
+   confirmed it.** If no such entry exists, do not build the roadmap around that
+   stack — say the stack is unconfirmed and route back to the stack gate. A
+   roadmap phased around an unconfirmed stack is what makes the wrong choice
+   expensive: by the time anyone questions it, every phase depends on it.
+   If the project has pivoted since the stack was chosen, check whether the
+   premise recorded with that decision still holds. If it does not, the decision
+   is stale, not locked.
+   **Read PROJECT.md's Glossary and use its terms verbatim** in phase names and
+   goals. A roadmap that renames the domain's nouns forces every downstream
+   agent to guess which concept a phase is about.
+   **Read PROJECT.md's Out of Scope (Non-Goals) before phasing.** A phase whose
+   goal reaches into a declared non-goal is scope creep with a plan attached —
+   flag it rather than quietly phasing it.
 2. **Cluster requirements** — group related requirements into natural delivery units.
 3. **Derive phases** — name each phase by what the user can DO after it, not what was built.
 3b. **Declare the Information Architecture** (UI projects only) — before phases are finalized, explicitly decide the app's eventual final-state IA, not per-phase: enumerate the top-level sections (e.g. Dashboard / Operations / Reports / Admin), pick sidebar vs topbar vs tabs, state max nesting depth (e.g. 2 levels: section > subsection), and group every planned phase's screens under one of those sections. Persist this as an `IA.md` (or a "## Information Architecture" section in ROADMAP.md). A flat list of nav links that grows by one item per phase is not an IA decision — it's the failure mode this step exists to prevent. Later phases must slot new routes under an existing top-level section or explicitly propose adding one, never silently append a new sidebar item.

package/rcode/references/verifier-playbook.md

@@ -41,6 +41,18 @@ Before verifying, discover project context:
 4. **Verify observable truths** — for each truth, status ✓ VERIFIED / ✗ FAILED / ? UNCERTAIN.
 5. **Verify artifacts (4 levels)** — exists, substantive, wired, data-flows. Use `rcode-tools.cjs verify artifacts`.
 6. **Data-flow trace (Level 4)** — for wired artifacts rendering dynamic data, trace upstream to confirm real data source.
+6e. **Check the requirement's own consequences, not your reconstruction of them.**
+For every requirement this phase claims, read its `**Consequences (testable):**`
+list in REQUIREMENTS.md and verify those. Where a plan's truth carries a
+`[DERIVED]` prefix, the requirement had none recorded and you are checking an
+invented criterion — say so in VERIFICATION.md. A phase that passes only against
+derived criteria has not been verified against what anyone actually asked for.
+
+6d. **Unconfirmed assumptions are verification gaps.** Read PROJECT.md's
+Assumptions Index. Any row still `unconfirmed` that this phase's must-haves
+depend on is a gap, not a formality — the phase was built on something nobody
+agreed to. Name it in VERIFICATION.md rather than passing over it.
+
 6c. **Production reachability (Level 5b) — EVERY phase, including backend-only.**
 For each non-UI module this phase delivered, list its importers and classify them
 production vs test. If every importer is a test file, the phase shipped dead code

package/rcode/workflows/execute.md

@@ -37,6 +37,12 @@ Bypassing it produces a built project with no execution trace, no SUMMARY.md, an
 a dashboard frozen at `planned`. See issue #915.
 
 <pre_flight>
+0a. **Record the authorized scope** — the user ran an execute command, so building
+    is authorized from here:
+    ```bash
+    node ".rcode/bin/rcode-tools.cjs" state set-intent build --source execute.md
+    ```
+
 **Mandatory before execution begins.** Run these checks first and surface
 findings BEFORE any subagents are spawned. If any check fails, stop and
 route back to the user.

package/rcode/workflows/new-project-define-requirements.md

@@ -111,6 +111,41 @@ Create `.planning/REQUIREMENTS.md` with:
 
 **REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
 
+**Every requirement carries its testable consequences.** This is the shape:
+
+```markdown
+- [ ] **AUTH-01**: User can log in with email and password and stay logged in
+      across sessions.
+  - **Consequences (testable):**
+    - A valid credential pair returns a session cookie with a 30-day expiry
+    - An invalid password returns 401 and does not reveal whether the email exists
+    - A logged-in user reloading the page stays logged in
+```
+
+**Why the consequences live here and not in the plan.** rcode's verifier derives
+`must_haves` at verification time, long after the requirement was written — so it
+is guessing at what "done" meant for a requirement someone else authored. That
+guess is where verification quietly goes wrong: a phase passes because the
+verifier's invented criterion was met, not the one the requirement intended.
+
+Writing the consequences with the requirement moves that decision to the moment
+the person actually knows the answer. The planner then copies them into
+`must_haves.truths` instead of inventing them, and the verifier checks the
+requirement's own criteria rather than its own reconstruction.
+
+A requirement whose consequences you cannot state is a requirement you have not
+finished writing. "Handle authentication properly" has no consequences because it
+has no meaning — that is the signal to push for specificity, not to move on.
+
+**Scope dial:** hobby/solo — one consequence per requirement is usually enough,
+and it can be a sentence. Internal tool — the happy path plus the one failure
+mode that matters. Launch — every condition a reviewer would ask about, including
+the negative cases.
+
+**Do not change the traceability table's shape.** `requirements mark-complete`
+rewrites the status cell of a `| ID | ... | status |` row; consequences are nested
+under the requirement in the list above, not added as table columns.
+
 **Requirement quality criteria:**
 
 Good requirements are:
@@ -119,6 +154,7 @@ Good requirements are:
 - **User-centric:** "User can X"
 - **Atomic:** One capability per requirement
 - **Independent:** Minimal dependencies on other requirements
+- **Consequential:** you can name what must be true for it to be done
 
 Reject vague requirements. Push for specificity:
 

package/rcode/workflows/new-project-research-decision.md

@@ -243,7 +243,67 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
-**If "Skip research":** Continue to Step 7.
+## 6b. Stack confirmation gate — HARD STOP
+
+**The stack is never decided for the user. Not by research, not by a
+recommendation, not by "the obvious choice for this domain."** Research produces
+a *suggestion*; only the user turns it into a decision.
+
+This gate runs whether research ran or was skipped. If research was skipped, ask
+with no recommendation attached — you have no grounds for one.
+
+```
+AskUserQuestion:
+  header: "Stack"
+  question: "Research suggests {STACK} because {the one reason that actually drove it}. Confirm?"
+  options:
+    - label: "Confirm {STACK}"
+      description: "{the trade-off the user is accepting, stated plainly}"
+    - label: "I'll choose the stack"
+      description: "Tell me what to build on and I'll record that instead."
+    - label: "Research more first"
+      description: "Compare against {the closest alternative} before deciding."
+```
+
+**Nothing proceeds until the user answers.** Not requirements, not the roadmap,
+not a single file. An unanswered question is not a confirmation, and neither is
+silence, `--auto`, or `auto_advance`. **Auto mode does NOT bypass this gate** —
+every other question in this workflow has an auto default; this one does not,
+because a wrong stack is the most expensive thing in the project to reverse.
+
+State the reason the suggestion exists, in one sentence, in the user's terms.
+"Research recommends WordPress" is not a reason. "WordPress because a
+non-technical client will update content themselves, with no dev retainer" is —
+and stated that way the user can see immediately whether the premise is true.
+
+Record the answer with `state add-decision`, including the premise it rests on:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state add-decision \
+  "Stack: {chosen}. Premise: {the one reason}. Confirmed by user {date}."
+```
+
+### The premise is part of the decision
+
+**A stack decision is only valid while its premise holds.** Write the premise
+into the decision, then re-open the decision the moment the premise changes.
+
+Confirmed live: a site was scoped for a non-technical client, so research picked
+WordPress and the roadmap locked it. The project later pivoted to a model with no
+client at all — the maintainer was the technical owner. Every planning doc was
+rewritten for the pivot and the stack stayed "Locked", because nothing in the
+loop treats a locked decision as re-openable. A PHP theme got built and then
+migrated wholesale to a static generator to undo it.
+
+**On any pivot, re-run this gate** for every decision whose stated premise the
+pivot invalidated. A decision whose reason has expired is not locked, it is
+stale.
+
+**If "Research more first":** run the comparison against the named alternative,
+then return to this gate. Do not proceed past it.
+
+**If "Skip research":** Continue to Step 6b — you still need the stack gate,
+you just have no suggestion to offer.
 
 
 ## Next Up

package/rcode/workflows/new-project.md

@@ -475,7 +475,12 @@ Proceed to Step 4 (skip Steps 3 and 5).
 
 ## 3. Deep Questioning
 
-**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
+**If auto mode:** extract project context from the provided document instead of
+asking. **You still owe the user the Mandatory decision set** — resolve each item
+from the document where it answers one, and where it does not, list what you are
+assuming before Step 4 writes PROJECT.md. Auto mode removes the conversation, not
+the accountability. If the document leaves the maintainer or the stack unanswered,
+stop and ask those two regardless of mode.
 
 **Display stage banner:**
 
@@ -491,6 +496,20 @@ Ask inline (freeform, NOT AskUserQuestion):
 
 "What do you want to build?"
 
+**Then, before any deeper questioning, run two short probes from
+`@.rcode/references/questioning.md` — in this order:**
+
+1. **Stakes calibration** — hobby/solo, internal tool, or launch? Scale every
+   artifact and gate below to the answer. Do not run the launch-grade pipeline on
+   a weekend project.
+2. **Working mode** — Fast path (batched questions, draft with `[ASSUMPTION]`
+   tags) or Coaching path (walk the decisions together)? **Ask it. Never infer it
+   from `auto_advance`, from how detailed their opening message was, or from your
+   own read of their hurry.** Only `--auto`/yolo picks Fast path without asking.
+
+These two answers govern the rest of this workflow. Record them with
+`state add-decision` so a later resume does not re-guess them.
+
 Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
 
 **Research-before-questions mode:** Check if `workflow.research_before_questions` is enabled in `.rcode/config.yaml` (via `node .rcode/bin/rcode-tools.cjs config-get workflow.research_before_questions`). When enabled, before asking follow-up questions about a topic:
@@ -527,6 +546,11 @@ Mentally check the context checklist. If gaps remain, weave questions naturally.
 
 **Decision gate:**
 
+**Before the decision gate, show your coverage.** State plainly which items of the
+Mandatory decision set (`@.rcode/references/questioning.md`) the user actually
+answered and which you are assuming, with each assumption spelled out in one line.
+An assumption the user never saw is a decision you made for them.
+
 When you could write a clear PROJECT.md, use AskUserQuestion:
 
 - header: "Ready?"
@@ -601,16 +625,61 @@ Synthesize all context into `.planning/PROJECT.md`. If `.rcode/templates/project
 - [ ] {Requirement 2}
 - [ ] {Requirement 3}
 
-### Out of Scope
+### Out of Scope (Non-Goals)
+
+*What this project is NOT and will NOT do. This does outsized work downstream —
+it is what prevents the "let me also add this nearby thing" failure at every
+level: phase, sprint, task, and code. An unstated exclusion reappears later as a
+gap; a stated one ends the argument before it starts.*
 
 - {Exclusion 1} — {why}
 - {Exclusion 2} — {why}
 
+**Scope dial:** hobby/solo — the two or three things you keep being tempted by.
+Internal tool — plus anything a stakeholder has already asked for and been told
+no. Launch — plus the "we are not becoming X" statements about the product's
+identity.
+
+## Glossary
+
+*Every domain noun this project uses, defined once. Downstream agents and
+documents use these terms verbatim — introducing a synonym anywhere is a
+discipline violation, because two names for one thing is how a codebase ends up
+with two implementations of it.*
+
+- **{Term}** — {definition}. {relationship to other terms, cardinality if it matters}
+
+**Scope dial:** hobby/solo — only terms that are genuinely ambiguous, often 2-3.
+Internal tool — every domain noun. Launch — every domain noun plus the ones the
+team argues about.
+
 ## Key Decisions
 
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| {Choice} | {Why} | — Pending |
+| Decision | Premise (what makes it right) | Rationale | Outcome |
+|----------|-------------------------------|-----------|---------|
+| {Choice} | {the condition this rests on} | {Why} | — Pending |
+
+*The **Premise** column is load-bearing. A decision is valid only while its
+premise holds — when the project pivots, every decision whose premise the pivot
+invalidated goes back to the user. A decision whose reason has expired is not
+locked, it is stale.*
+
+## Assumptions Index
+
+*Every `[ASSUMPTION]` tag in this document and in REQUIREMENTS.md, gathered here
+for explicit confirmation. An assumption the user never saw is a decision nobody
+made.*
+
+| # | Assumption | Where | Status |
+|---|-----------|-------|--------|
+| A-1 | {what was inferred} | §{section} | unconfirmed |
+
+**This table is walked with the user before the document is treated as settled.**
+Each row ends as confirmed, corrected, or deferred with an owner. Auto mode does
+not skip the walk; it defers it to the first interactive turn.
+
+**Scope dial:** the table exists at every stakes level. Hobby/solo may resolve it
+in one exchange; launch resolves it row by row.
 
 ## Constraints
 
@@ -628,19 +697,39 @@ This document evolves at phase transitions and milestone boundaries.
 1. Requirements invalidated? → Move to Out of Scope with reason
 2. Requirements validated? → Move to Validated with phase reference
 3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
+4. Decisions to log? → Add to Key Decisions, WITH its premise
 5. "What This Is" still accurate? → Update if drifted
+6. New domain nouns introduced? → Add to Glossary in the same pass
+7. Any `[ASSUMPTION]` resolved or added? → Update the Assumptions Index
+8. Did anything invalidate a recorded premise? → That decision reopens
 
 **After each milestone** (via `/rcode-complete-milestone`):
 1. Full review of all sections
 2. Core Value check — still the right priority?
 3. Audit Out of Scope — reasons still valid?
 4. Update Context with current state
+5. Assumptions Index — any row still `unconfirmed` after a whole milestone is a
+   finding, not a formality. Resolve or escalate it
+6. Key Decisions — check every premise still holds
 
 ---
 *Last updated: {date} after initialization*
 ```
 
+**Scale every section to the stakes answer from Step 3.** The template is one
+document that serves a weekend project and a launch; the scope dials on each
+section say how. Running the launch-grade depth on a hobby project is its own
+failure — the user abandons the process, not the project.
+
+| Stakes | PROJECT.md target |
+|---|---|
+| Hobby / solo | About a page. Glossary only where terms are ambiguous |
+| Internal tool | Two to four pages. Every section present, lightly filled |
+| Launch | As long as the requirements and concerns need |
+
+Never pad a section to look thorough, and never drop one silently — if a section
+genuinely does not apply, say so in one line where it would have been.
+
 **For greenfield projects:** Initialize requirements as hypotheses (all Active).
 
 **For brownfield projects (codebase map exists):** Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`. Identify what the codebase already does — these become the initial Validated set.

package/rcode/workflows/plan.md

@@ -100,6 +100,15 @@ drafting tasks inline, the run has lost its orchestrator — spawn the planner
 instead. A SPRINT.md with no planner `Task()` behind it is the failure this rule
 exists to prevent (see step 8).
 
+## 0.4. Record the authorized scope
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" state set-intent plan --source plan.md
+```
+
+This is what the user asked for on THIS invocation, and it is what `resume-work`
+will restore later. Planning does not authorize building — see step 15.
+
 ## 0.5. Project-Status Preflight
 
 ```bash
@@ -306,11 +315,11 @@ If `TEXT_MODE` is true, present as a plain-text numbered list:
 ```
 No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included.
 
-1. Continue without context — Plan using research + requirements only
 [If DISCUSS_MODE is "assumptions":]
-2. Gather context (assumptions mode) — Analyze codebase and surface assumptions before planning
+1. Gather context (assumptions mode) [recommended] — Analyze codebase and surface assumptions before planning
 [If DISCUSS_MODE is "discuss" or unset:]
-2. Run discuss-phase first — Capture design decisions before planning
+1. Run discuss-phase first [recommended] — Capture design decisions before planning
+2. Continue without context — Plan using research + requirements only; your design preferences will not be in the plan
 
 Enter number:
 ```
@@ -319,11 +328,13 @@ Otherwise use AskUserQuestion:
 - header: "No context"
 - question: "No CONTEXT.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?"
 - options:
-  - "Continue without context" — Plan using research + requirements only
+  (Recommended option FIRST — rcode was recommending the skip, which is how phases
+  got planned with the user's design decisions never captured.)
   If `DISCUSS_MODE` is `"assumptions"`:
-  - "Gather context (assumptions mode)" — Analyze codebase and surface assumptions before planning
+  - "Gather context (assumptions mode) (Recommended)" — Analyze codebase and surface assumptions before planning
   If `DISCUSS_MODE` is `"discuss"` (or unset):
-  - "Run discuss-phase first" — Capture design decisions before planning
+  - "Run discuss-phase first (Recommended)" — Capture design decisions before planning
+  - "Continue without context" — Plan using research + requirements only; your design preferences will not be in the plan
 
 If "Continue without context": Proceed to step 5.
 If "Run discuss-phase first":
@@ -926,7 +937,30 @@ Returns (else branch only):
 
 After plans pass the checker (or checker is skipped), verify that all phase requirements are covered by at least one plan.
 
-**Skip if:** `phase_req_ids` is null, `TBD`, or an empty array/list (no requirements mapped to this phase) — `[[ -z "$phase_req_ids" || "$phase_req_ids" == "TBD" || "$phase_req_ids" == "[]" || "$phase_req_ids" == "null" ]]` — proceed to step 14.
+**If `phase_req_ids` is empty, the gate does NOT silently skip — it reports why.**
+An empty array has two very different causes and they must not look the same:
+
+1. This phase genuinely maps to no requirements. Fine, say so and continue.
+2. REQUIREMENTS.md HAS a traceability table and nothing parsed out of it. That is
+   a broken gate reporting as a passing one.
+
+Distinguish them before proceeding:
+
+```bash
+if [ -f .planning/REQUIREMENTS.md ] && grep -qE '\b[A-Z][A-Z0-9]{1,15}-[0-9]+\b' .planning/REQUIREMENTS.md; then
+  echo "⚠ Requirements coverage gate SKIPPED but REQUIREMENTS.md contains requirement IDs."
+  echo "  phase_req_ids came back empty — the phase→requirement mapping in ROADMAP.md"
+  echo "  is missing or unparseable, so nothing is verifying coverage for this phase."
+  echo "  Fix the phase's **Requirements:** line in ROADMAP.md, then re-run."
+fi
+```
+
+Surface that warning to the user; do not bury it. Confirmed live: a project's
+requirement IDs were all domain-prefixed (`FOUND-01`, `RENT-04`), the extractor
+only matched `REQ-*`, and this gate skipped itself on every phase while
+appearing to pass.
+
+Then proceed to step 14 when the array really is empty.
 
 **Step 1: Extract requirement IDs claimed by plans**
 ```bash
@@ -1028,7 +1062,34 @@ if ([[ "$ARGUMENTS" =~ --auto ]] || [[ "$ARGUMENTS" =~ --chain ]]) && [[ "$AUTO_
 fi
 ```
 
-**If `--auto` or `--chain` flag present OR `AUTO_CHAIN` is true OR `AUTO_CFG` is true:**
+**`AUTO_CFG` alone is NOT sufficient.** A persistent `workflow.auto_advance: true`
+in settings must never silently turn "plan this" into "plan and build this". The
+user's invocation is their declared scope: they typed a planning command, so
+planning is what was authorized. A config flag set weeks ago is not consent for
+this build.
+
+Confirmed live: a user asked for a project to be planned, `auto_advance` was on,
+and the session planned and then built a WordPress theme, then migrated the whole
+thing to Astro to undo its own stack choice. The user's words were "plan karo".
+Nothing in the loop stopped at the boundary they actually drew.
+
+**If `AUTO_CFG` is true but neither `--auto`/`--chain` nor `AUTO_CHAIN` is set:**
+ask before advancing, and default to stopping:
+
+```
+AskUserQuestion:
+  question: "Plans are ready. auto_advance is on in your config — execute phase {N} now?"
+  options:
+    - label: "Stop here (Recommended)"
+      description: "Plans written and verified. Review them, then run /rcode-execute {N} when ready."
+    - label: "Execute now"
+      description: "Chain straight into execution, as auto_advance requests."
+```
+
+In `--text` mode present this as a numbered list. If the user does not answer,
+STOP — an unanswered question is not approval.
+
+**If `--auto` or `--chain` flag present OR `AUTO_CHAIN` is true:**
 
 Display banner:
 ```
@@ -1156,6 +1217,7 @@ ${WINDOWS === 'true' ? '@.rcode/references/plan-windows-troubleshooting.md' : ''
 - [ ] Phase directory created if needed
 - [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
 - [ ] Research completed (unless --skip-research or --gaps or exists)
+- [ ] Auto-advance fired only on an explicit `--auto`/`--chain` or an answered confirmation, never on `auto_advance` config alone
 - [ ] Specialist review panel spawned (Waleed + Fatima + domain agents) and its blocking issues fed into the revision loop, or `workflow.specialist_review: false` recorded
 - [ ] rcode-phase-researcher spawned with CONTEXT.md
 - [ ] Existing plans checked

package/rcode/workflows/resume-work.md

@@ -197,6 +197,24 @@ Based on project state, determine the most logical next action:
 </step>
 
 <step name="offer_options">
+**"Resume" restores position, never scope.** It tells you WHERE the work stopped;
+it does not tell you what the user authorized. Present options and wait — do not
+pick one and start.
+
+The failure this prevents: a user asks for a project to be planned, the session
+plans it, the user later types "resume", and the session reads that as "keep
+going" and starts building. The standing instruction was still "plan". Confirmed
+live, and the cleanup cost more than the work.
+
+Two rules:
+
+- **Never begin implementation from a resume.** If the state says the phase is
+  ready to execute, that is an option to OFFER, not an action to take. Execution
+  starts when the user runs `/rcode-execute`, not when a menu suggests it.
+- **Say what the last authorized scope was**, if the state records one (see
+  `state read` → `last_intent`, written by plan.md and execute.md). If it does not, say that plainly rather than
+  inferring one: `Last recorded scope: unknown — tell me plan or build.`
+
 Present contextual options based on project state:
 
 ```