@hanzlaa/rcode 3.4.32 → 3.5.0

package/rihal/bin/rihal-tools.cjs

@@ -901,6 +901,11 @@ function cmdInitExecute(rawArgs) {
     plan_path: planPath,
     phase_dir: phaseDir,
     plans,
+    // Surface response_language at top level so workflows don't have to drill
+    // into config — matches cmdInit's contract (#721). null means English.
+    response_language: config.response_language || config.language || null,
+    executor_model: config.executor_model || config.model_profile || null,
+    verifier_model: config.verifier_model || config.model_profile || null,
     config,
     paths: {
       project_root: PROJECT_ROOT,
@@ -989,6 +994,11 @@ function cmdState(subArgs) {
     function isProcessAlive(pid) {
       try { process.kill(pid, 0); return true; } catch { return false; }
     }
+    // #8 — stamp schema_version on every write so legacy state files
+    // (no field) auto-gain the explicit tag. Never demotes an existing
+    // higher version — only fills the missing case. Bumping the version
+    // is the migrator's job, not this helper.
+    if (typeof state.schema_version !== 'number') state.schema_version = 1;
 
     // Issue #681: auto-clear the install-time _seeded_stub marker once the
     // state has graduated to a real project (project field set + at least one
@@ -1048,6 +1058,11 @@ function cmdState(subArgs) {
     const now = new Date().toISOString();
     return {
       version: '1',
+      // #8 — explicit schema_version field for future migration framework.
+      // Bump when the shape changes. `state schema-status` / `state migrate-schema`
+      // read this. Existing state files without the field are treated as v1
+      // (backwards-compat — never crash on legacy state).
+      schema_version: 1,
       project: projectName || path.basename(PROJECT_ROOT),
       created: now,
       updated: now,
@@ -1137,7 +1152,21 @@ function cmdState(subArgs) {
     state.current_plan = 0;
     if (!state.phases) state.phases = [];
     if (!state.phases.some(p => p.name === name)) {
-      state.phases.push({ name, started: new Date().toISOString(), completed: null, plan_count: 0 });
+      // Derive a stable number from the name's leading digits (e.g., "20-foo" → 20)
+      // so downstream lookups by p.number / p.id in sprint add etc. resolve correctly.
+      // Falls back to next sequential position when name has no leading digit.
+      const leadingNum = String(name).match(/^(\d+)/);
+      const number = leadingNum
+        ? parseInt(leadingNum[1], 10)
+        : (state.phases.length + 1);
+      state.phases.push({
+        number,
+        id: String(number),
+        name,
+        started: new Date().toISOString(),
+        completed: null,
+        plan_count: 0,
+      });
     }
     return writeState(state);
   }
@@ -1203,6 +1232,178 @@ function cmdState(subArgs) {
     return writeStateCompact(state, { sprint_id: sprintId, phase: padPhase });
   }
 
+  // --- logs prune [--dir <path>] [--older-than <days>] [--dry-run] ---
+  // Prune dated session-* artifacts (#13). Defaults:
+  //   dir         = .rihal/progress/
+  //   pattern     = session-*.md
+  //   older-than  = 90 days
+  //   dry-run     = true (so accidental invocation never deletes)
+  // No-op if the directory doesn't exist — prints a friendly message.
+  // File age is determined by mtime, not filename.
+  if (sub === 'logs' && subArgs[1] === 'prune') {
+    const flags = parseFlags(2);
+    const dryRun = ('dry-run' in flags) || !subArgs.includes('--no-dry-run');
+    const dir = flags.dir
+      ? path.resolve(PROJECT_ROOT, flags.dir)
+      : path.join(RIHAL_DIR, 'progress');
+    const olderDays = parseInt(flags['older-than'] || '90', 10);
+    const pattern = flags.pattern || 'session-*.md';
+    const cutoff = Date.now() - olderDays * 24 * 60 * 60 * 1000;
+
+    if (!fs.existsSync(dir)) {
+      return {
+        ok: true,
+        dry_run: dryRun,
+        pruned: 0,
+        message: `No logs directory at ${path.relative(PROJECT_ROOT, dir)} — nothing to prune.`,
+      };
+    }
+
+    // Translate the glob pattern to a RegExp (only the * wildcard for safety).
+    const reSrc = '^' + pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$';
+    const fileRe = new RegExp(reSrc);
+
+    const toPrune = [];
+    for (const entry of fs.readdirSync(dir)) {
+      if (!fileRe.test(entry)) continue;
+      const full = path.join(dir, entry);
+      let stat;
+      try { stat = fs.statSync(full); } catch (_) { continue; }
+      if (!stat.isFile()) continue;
+      if (stat.mtimeMs < cutoff) {
+        toPrune.push({
+          file: path.relative(PROJECT_ROOT, full),
+          age_days: Math.floor((Date.now() - stat.mtimeMs) / (24 * 60 * 60 * 1000)),
+          bytes: stat.size,
+        });
+      }
+    }
+
+    if (!dryRun) {
+      for (const item of toPrune) {
+        try { fs.unlinkSync(path.join(PROJECT_ROOT, item.file)); }
+        catch (e) { item.error = e.message; }
+      }
+    }
+
+    return {
+      ok: true,
+      dry_run: dryRun,
+      dir: path.relative(PROJECT_ROOT, dir),
+      pattern,
+      older_than_days: olderDays,
+      pruned: dryRun ? 0 : toPrune.filter(t => !t.error).length,
+      would_prune: dryRun ? toPrune.length : 0,
+      details: toPrune,
+    };
+  }
+
+  // --- sprint init-all [--file <path>] [--dry-run] ---
+  // Bulk-initialize sprints by parsing .planning/sprints.md (#11).
+  // Supported formats: markdown table with `| Sprint | Phase | Goal |` columns,
+  // OR a simple "## Sprint N — Phase X — Goal" heading list. Skips rows whose
+  // sprint id already exists for that phase (idempotent). No-op when the
+  // file is absent — prints a helpful message rather than failing.
+  if (sub === 'sprint' && subArgs[1] === 'init-all') {
+    const flags = parseFlags(2);
+    const dryRun = ('dry-run' in flags) || subArgs.includes('--dry-run');
+    const filePath = flags.file || path.join(PLANNING_DIR, 'sprints.md');
+    if (!fs.existsSync(filePath)) {
+      return {
+        ok: true,
+        created: 0,
+        message: `No sprints.md found at ${path.relative(PROJECT_ROOT, filePath)}. Write one with rows like '| 1 | 3 | Migrate auth module |' to bulk-initialize sprints.`,
+      };
+    }
+    const text = fs.readFileSync(filePath, 'utf8');
+    const rows = [];
+
+    // Parse markdown-table form: skip header + separator rows, accept any
+    // row with at least 3 pipe-delimited cells (sprint, phase, goal).
+    const lines = text.split(/\r?\n/);
+    let inTable = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|')) { inTable = false; continue; }
+      // Separator row like |---|---|---|
+      if (/^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?$/.test(trimmed)) { inTable = true; continue; }
+      const cells = trimmed.replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim());
+      if (cells.length < 3) continue;
+      // Header detection: skip if first cell is non-numeric AND we haven't seen separator yet
+      if (!inTable && !/^\d/.test(cells[0])) continue;
+      // Tolerate extra columns; first three are sprint, phase, goal.
+      const sprintNum = parseInt(cells[0], 10);
+      const phaseRef = cells[1];
+      const goal = cells[2];
+      if (!Number.isFinite(sprintNum) || !phaseRef || !goal) continue;
+      rows.push({ sprint: sprintNum, phase: phaseRef, goal });
+    }
+
+    // Fallback: parse "## Sprint N — Phase X — Goal" heading form.
+    if (rows.length === 0) {
+      const hRe = /^#{2,3}\s*Sprint\s+(\d+)\s*[—\-:]\s*Phase\s+([\d.]+)\s*[—\-:]\s*(.+)$/gim;
+      let m;
+      while ((m = hRe.exec(text)) !== null) {
+        rows.push({ sprint: parseInt(m[1], 10), phase: m[2], goal: m[3].trim() });
+      }
+    }
+
+    if (rows.length === 0) {
+      return {
+        ok: true,
+        created: 0,
+        message: `sprints.md parsed but no rows recognized. Expected '| sprint | phase | goal |' table or '## Sprint N — Phase X — Goal' headings.`,
+      };
+    }
+
+    const state = readState() || defaultState();
+    const created = [];
+    const skipped = [];
+    for (const row of rows) {
+      const phaseIdx = state.phases.findIndex(p =>
+        String(p.number) === String(row.phase) ||
+        String(p.id) === String(row.phase) ||
+        p.name === row.phase
+      );
+      if (phaseIdx === -1) {
+        skipped.push({ ...row, reason: `phase ${row.phase} not found` });
+        continue;
+      }
+      const phase = state.phases[phaseIdx];
+      if (!phase.sprints) phase.sprints = [];
+      const phaseNum = phase.number != null ? phase.number
+        : phase.id != null ? (parseInt(phase.id, 10) || (phaseIdx + 1))
+        : phaseIdx + 1;
+      const sprintId = `${phaseNum}.${row.sprint}`;
+      if (phase.sprints.some(s => s.id === sprintId || s.number === row.sprint)) {
+        skipped.push({ ...row, reason: `sprint ${sprintId} already exists` });
+        continue;
+      }
+      const sprint = {
+        id: sprintId,
+        number: row.sprint,
+        goal: row.goal,
+        status: 'planned',
+        velocity_target: null,
+        velocity_actual: null,
+        started_at: null,
+        completed_at: null,
+        stories: [],
+      };
+      if (!dryRun) phase.sprints.push(sprint);
+      created.push({ sprint_id: sprintId, phase: String(phaseNum), goal: row.goal });
+    }
+    if (!dryRun && created.length > 0) writeState(state);
+    return {
+      ok: true,
+      dry_run: dryRun,
+      created: created.length,
+      skipped: skipped.length,
+      file: path.relative(PROJECT_ROOT, filePath),
+      details: { created, skipped },
+    };
+  }
+
   // --- sprint list [--phase NN] ---
   if (sub === 'sprint' && subArgs[1] === 'list') {
     const flags = parseFlags(2);
@@ -2276,6 +2477,112 @@ function cmdState(subArgs) {
     return { ok: true, migrated: migratedCount, message: `Migrated ${migratedCount} PLAN.md files with IDs` };
   }
 
+  // =====================================================================
+  // state migrate-plan-names: normalise plan filenames to no-leading-zeros (#657)
+  //
+  // Renames <N>-0K-SPRINT.md → <N>-K-SPRINT.md so the K (plan index) honours
+  // the project's no-leading-zeros rule. The N (phase prefix) is preserved
+  // because phase directories use leading zeros for ls sort order.
+  //
+  // Reports planned actions and exits without touching disk when --dry-run.
+  // Updates state.json plan IDs if the renamed file is referenced there.
+  // Does NOT rewrite ROADMAP / SUMMARY backrefs — workflows glob *-SPRINT.md
+  // which still matches. Backref cleanup is a follow-up if needed.
+  // =====================================================================
+  if (sub === 'migrate-plan-names') {
+    const flags = parseFlags(1);
+    // parseFlags sets valueless flags to '' (empty string). Detect presence
+    // by key existence, not truthiness, so --dry-run works as a bare flag.
+    const dryRun = ('dry-run' in flags) || subArgs.includes('--dry-run');
+    const renames = [];
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    if (!fs.existsSync(phasesDir)) {
+      return { ok: true, renamed: 0, dry_run: dryRun, message: '.planning/phases not found' };
+    }
+    for (const entry of fs.readdirSync(phasesDir)) {
+      const phaseDir = path.join(phasesDir, entry);
+      if (!fs.statSync(phaseDir).isDirectory()) continue;
+      for (const file of fs.readdirSync(phaseDir)) {
+        // Match: <N>-0K-SPRINT.md where K starts with '0' AND has at least one
+        // more digit (so single-digit "0" wouldn't match — there is no plan 0).
+        const m = file.match(/^(\d+)-0(\d+)-SPRINT\.md$/);
+        if (!m) continue;
+        const phasePrefix = m[1];
+        const planNum = m[2]; // already stripped leading zero
+        const oldName = file;
+        const newName = `${phasePrefix}-${planNum}-SPRINT.md`;
+        const oldPath = path.join(phaseDir, oldName);
+        const newPath = path.join(phaseDir, newName);
+        if (fs.existsSync(newPath)) {
+          renames.push({ phase_dir: entry, from: oldName, to: newName, status: 'skip-target-exists' });
+          continue;
+        }
+        renames.push({ phase_dir: entry, from: oldName, to: newName, status: dryRun ? 'would-rename' : 'renamed' });
+        if (!dryRun) fs.renameSync(oldPath, newPath);
+      }
+    }
+    // Update state.json plan IDs (e.g., "20.01" → "20.1") if the entries exist.
+    let stateUpdates = 0;
+    if (!dryRun) {
+      const state = readState();
+      if (state && Array.isArray(state.phases)) {
+        for (const phase of state.phases) {
+          if (!Array.isArray(phase.plans)) continue;
+          for (const plan of phase.plans) {
+            if (typeof plan.id !== 'string') continue;
+            const newId = plan.id.replace(/^(\d+)\.0(\d+)$/, '$1.$2');
+            if (newId !== plan.id) {
+              plan.id = newId;
+              if (plan.plan) plan.plan = String(plan.plan).replace(/^0(\d+)$/, '$1');
+              stateUpdates++;
+            }
+          }
+        }
+        if (stateUpdates > 0) writeState(state);
+      }
+    }
+    return {
+      ok: true,
+      dry_run: dryRun,
+      renamed: renames.filter(r => r.status === 'renamed').length,
+      would_rename: renames.filter(r => r.status === 'would-rename').length,
+      skipped: renames.filter(r => r.status === 'skip-target-exists').length,
+      state_plan_ids_updated: stateUpdates,
+      details: renames,
+    };
+  }
+
+  // =====================================================================
+  // state schema-status: report current vs expected schema_version (#8).
+  // Read-only. Surfaces stale state files so users know when to run
+  // `state migrate-schema`.
+  // =====================================================================
+  if (sub === 'schema-status') {
+    const CURRENT_SCHEMA_VERSION = 1;
+    if (!fs.existsSync(statePath)) {
+      return { ok: false, error: 'state.json not found' };
+    }
+    let state;
+    try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+    catch (e) { return { ok: false, error: `Invalid JSON: ${e.message}` }; }
+    const recorded = state.schema_version;
+    // Treat missing schema_version as v1 (legacy state files). Never crash.
+    const effective = typeof recorded === 'number' ? recorded : 1;
+    return {
+      ok: true,
+      file: path.relative(PROJECT_ROOT, statePath),
+      schema_version: effective,
+      current_version: CURRENT_SCHEMA_VERSION,
+      drift: effective !== CURRENT_SCHEMA_VERSION,
+      explicit: typeof recorded === 'number',
+      message: typeof recorded === 'number'
+        ? (effective === CURRENT_SCHEMA_VERSION
+            ? 'Up to date.'
+            : `state.json is at v${effective}, current is v${CURRENT_SCHEMA_VERSION}. Run: rihal-tools state migrate-schema`)
+        : 'state.json has no schema_version field — treated as v1. Next write will stamp the explicit field.',
+    };
+  }
+
   // =====================================================================
   // state migrate-schema: normalise phases array to current schema
   // Handles 3 known schema variants in the wild:
@@ -2286,11 +2593,16 @@ function cmdState(subArgs) {
   // for entries that have a SUMMARY.md path or missing status).
   // =====================================================================
   if (sub === 'migrate-schema') {
+    // Closes #735. Full normalizer: phases array + all top-level array fields.
     const state = readState();
     if (!state) return { ok: false, error: 'state.json not found or empty' };
-    if (!Array.isArray(state.phases)) return { ok: false, error: 'state.phases is not an array' };
+    if (!Array.isArray(state.phases)) {
+      state.phases = [];
+    }
 
     let changed = 0;
+
+    // 1. Normalize phases entries
     state.phases = state.phases.map((p) => {
       const updated = Object.assign({}, p);
 
@@ -2321,10 +2633,42 @@ function cmdState(subArgs) {
       return updated;
     });
 
+    // 2. Ensure all required top-level arrays are present (never crash on legacy state).
+    const requiredArrays = [
+      'velocity_history', 'executions', 'decisions',
+      'blockers', 'council_sessions', 'workstreams',
+    ];
+    for (const key of requiredArrays) {
+      if (!Array.isArray(state[key])) {
+        state[key] = [];
+        changed++;
+      }
+    }
+
+    // 3. Ensure required scalar fields
+    if (!state.project) { state.project = path.basename(PROJECT_ROOT); changed++; }
+    if (!state.created) { state.created = state.updated || new Date().toISOString(); changed++; }
+    if (state.current_phase === undefined) { state.current_phase = null; changed++; }
+    if (state.current_plan  === undefined) { state.current_plan  = 0;    changed++; }
+    if (state.current_sprint === undefined) { state.current_sprint = null; changed++; }
+    if (state.last_session   === undefined) { state.last_session  = null; changed++; }
+    if (state.active_workstream === undefined) { state.active_workstream = null; changed++; }
+
+    // 4. Bump schema_version if still at implicit v1 and we made structural changes
+    if (typeof state.schema_version !== 'number') {
+      state.schema_version = 1;
+      changed++;
+    }
+
     if (changed > 0) {
       writeState(state);
     }
-    return { ok: true, changed, message: `Schema migration complete — ${changed} field(s) normalised across ${state.phases.length} phase entries` };
+    return {
+      ok: true, changed,
+      schema_version: state.schema_version,
+      phase_count: state.phases.length,
+      message: `Schema migration complete — ${changed} field(s) normalised (${state.phases.length} phases)`,
+    };
   }
 
   // =====================================================================
@@ -2980,7 +3324,205 @@ function cmdPhase(subArgs) {
     };
   }
 
-  throw new Error(`Unknown phase subcommand: ${sub || '(none)'}. Valid: add`);
+  if (sub === 'set-status') {
+    const phaseRef = subArgs[1];
+    const newStatus = subArgs[2];
+    if (!phaseRef) throw new Error('phase set-status requires <phase_number> <status>');
+    if (!newStatus) throw new Error('phase set-status requires <status> (e.g., executed, complete, blocked)');
+    const validStatuses = ['planned', 'in_progress', 'executed', 'complete', 'blocked'];
+    if (!validStatuses.includes(newStatus)) {
+      throw new Error(`Invalid status "${newStatus}". Valid: ${validStatuses.join(', ')}`);
+    }
+
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+    if (!fs.existsSync(statePath)) {
+      throw new Error(`state.json not found at ${statePath} — run 'rihal-tools state init' first`);
+    }
+    let state;
+    try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+    catch (e) { throw new Error(`Invalid JSON in state.json: ${e.message}`); }
+    if (!state.phases) state.phases = [];
+
+    const phaseIdx = state.phases.findIndex(p =>
+      String(p.number) === String(phaseRef) ||
+      String(p.id) === String(phaseRef) ||
+      p.name === phaseRef
+    );
+    if (phaseIdx === -1) {
+      throw new Error(`Phase "${phaseRef}" not found in state.phases (looked up by number, id, and name)`);
+    }
+    const previous = state.phases[phaseIdx].status || null;
+    state.phases[phaseIdx].status = newStatus;
+    state.phases[phaseIdx].status_updated = new Date().toISOString();
+
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+    return { ok: true, phase: phaseRef, previous_status: previous, new_status: newStatus };
+  }
+
+  // =====================================================================
+  // phase next-range [count] — return next N contiguous free phase numbers.
+  // Closes #730. Enables bulk-scaffold and parallel planning workflows
+  // to reserve a block of numbers atomically before creating directories.
+  // =====================================================================
+  if (sub === 'next-range') {
+    const count = Math.max(1, parseInt(subArgs[1] || '1', 10));
+    if (Number.isNaN(count) || count < 1 || count > 200) {
+      throw new Error('phase next-range count must be a positive integer ≤ 200');
+    }
+
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+
+    let maxNum = 0;
+    if (fs.existsSync(phasesDir)) {
+      for (const entry of fs.readdirSync(phasesDir)) {
+        const m = entry.match(/^(\d+)/);
+        if (m) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+      }
+    }
+    if (fs.existsSync(roadmapPath)) {
+      const text = fs.readFileSync(roadmapPath, 'utf8');
+      const pipeRe = /^\|\s*(\d+)\s*\|/gm;
+      let m;
+      while ((m = pipeRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+      const headRe = /^#{2,4}\s*Phase\s+(\d+)\b/gm;
+      while ((m = headRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+    }
+    if (fs.existsSync(statePath)) {
+      try {
+        const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+        for (const p of (state.phases || [])) {
+          const n = parseInt(String(p.number || ''), 10);
+          if (!Number.isNaN(n)) maxNum = Math.max(maxNum, n);
+        }
+      } catch {}
+    }
+
+    const first = maxNum + 1;
+    const last  = maxNum + count;
+    const range = [];
+    for (let i = first; i <= last; i++) range.push(i);
+    return { ok: true, first, last, count, range };
+  }
+
+  // =====================================================================
+  // phase scaffold-milestone --names "n1|n2|n3" [--start N]
+  // Closes #731. Bulk-creates phase folders for a milestone in one call.
+  // Names are pipe-separated (| avoids shell quoting issues with commas).
+  // --start N overrides the computed first number (defaults to next-range).
+  // =====================================================================
+  if (sub === 'scaffold-milestone') {
+    const remaining = subArgs.slice(1);
+    let rawNames = null;
+    let startOverride = null;
+
+    for (let i = 0; i < remaining.length; i++) {
+      if (remaining[i] === '--names' && remaining[i + 1]) {
+        rawNames = remaining[++i];
+      } else if (remaining[i] === '--start' && remaining[i + 1]) {
+        startOverride = parseInt(remaining[++i], 10);
+        if (Number.isNaN(startOverride)) throw new Error('--start requires an integer');
+      }
+    }
+    if (!rawNames) throw new Error('phase scaffold-milestone requires --names "name1|name2|..."');
+
+    const names = rawNames.split('|').map(n => n.trim()).filter(Boolean);
+    if (!names.length) throw new Error('--names must contain at least one non-empty name');
+
+    // Compute starting number via same logic as next-range / phase add
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+
+    let maxNum = 0;
+    if (fs.existsSync(phasesDir)) {
+      for (const entry of fs.readdirSync(phasesDir)) {
+        const m = entry.match(/^(\d+)/);
+        if (m) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+      }
+    }
+    if (fs.existsSync(roadmapPath)) {
+      const text = fs.readFileSync(roadmapPath, 'utf8');
+      const pipeRe = /^\|\s*(\d+)\s*\|/gm;
+      let m;
+      while ((m = pipeRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+      const headRe = /^#{2,4}\s*Phase\s+(\d+)\b/gm;
+      while ((m = headRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+    }
+    let state = { phases: [] };
+    if (fs.existsSync(statePath)) {
+      try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch {}
+    }
+    if (!Array.isArray(state.phases)) state.phases = [];
+    for (const p of state.phases) {
+      const n = parseInt(String(p.number || ''), 10);
+      if (!Number.isNaN(n)) maxNum = Math.max(maxNum, n);
+    }
+
+    const firstNum = startOverride !== null ? startOverride : maxNum + 1;
+    const created  = [];
+
+    for (let i = 0; i < names.length; i++) {
+      const phaseName = names[i];
+      const number = String(firstNum + i);
+      const slug = phaseName
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+      if (!slug) {
+        throw new Error(`Name at index ${i} ("${phaseName}") produces an empty slug`);
+      }
+      if (state.phases.some(p => String(p.number) === number)) {
+        throw new Error(`Phase ${number} already exists in state.json (would collide at index ${i})`);
+      }
+
+      const dirName  = `${number}-${slug}`;
+      const directory = path.join(phasesDir, dirName);
+      if (fs.existsSync(directory)) {
+        throw new Error(`Directory already exists: ${path.relative(PROJECT_ROOT, directory)}`);
+      }
+      fs.mkdirSync(directory, { recursive: true });
+
+      // Append ROADMAP entry
+      if (fs.existsSync(roadmapPath)) {
+        const entry = `## Phase ${number} — ${phaseName}\n\n` +
+          `**Goal:** _TBD — fill in via /rihal-discuss-phase ${number} or edit directly._\n\n` +
+          `**Status:** Planned\n\n` +
+          `**Plans:**\n- _TBD_\n\n` +
+          `**Acceptance:** _TBD_\n\n---\n`;
+        let text = fs.readFileSync(roadmapPath, 'utf8');
+        const backlogMatch = text.match(/^##\s+Backlog\b/m);
+        if (backlogMatch) {
+          text = text.slice(0, backlogMatch.index) + entry + '\n' + text.slice(backlogMatch.index);
+        } else {
+          if (!text.endsWith('\n')) text += '\n';
+          text += '\n' + entry;
+        }
+        fs.writeFileSync(roadmapPath, text);
+      }
+
+      state.phases.push({
+        number, name: phaseName, slug,
+        goal: '', status: 'planned',
+        created: new Date().toISOString(),
+        started: null, completed: null, plan_count: 0,
+      });
+      created.push({ number, name: phaseName, directory: path.relative(PROJECT_ROOT, directory) });
+    }
+
+    state.updated = new Date().toISOString();
+    if (typeof state.schema_version !== 'number') state.schema_version = 1;
+    const stateDir = path.dirname(statePath);
+    if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+
+    return { ok: true, count: created.length, phases: created };
+  }
+
+  throw new Error(`Unknown phase subcommand: ${sub || '(none)'}. Valid: add, set-status, next-range, scaffold-milestone`);
 }
 
 /**
@@ -3059,7 +3601,7 @@ function cmdCommit(argv) {
   }
 
   // Stage files if --files provided; otherwise commit whatever is staged.
-  const { execSync } = require('child_process');
+  const { execSync, execFileSync } = require('child_process');
   if (files.length > 0) {
     // Validate each path exists before staging
     for (const f of files) {
@@ -3072,10 +3614,9 @@ function cmdCommit(argv) {
     // stderr to detect the gitignore warning explicitly (#566).
     let gitAddStderr = '';
     try {
-      const addResult = execSync(
-        `git add ${files.map(f => `"${f.replace(/"/g, '\\"')}"`).join(' ')}`,
-        { cwd: PROJECT_ROOT, stdio: 'pipe' }
-      );
+      // execFileSync argument array: filenames pass as literal argv entries — no
+      // shell, so a filename with ; $() backticks or spaces cannot inject (#754).
+      execFileSync('git', ['add', ...files], { cwd: PROJECT_ROOT, stdio: 'pipe' });
     } catch (e) {
       gitAddStderr = (e.stderr ? e.stderr.toString() : '') + (e.stdout ? e.stdout.toString() : '');
       if (gitAddStderr.includes('ignored by one of your .gitignore') || gitAddStderr.includes('use -f if')) {
@@ -3101,7 +3642,7 @@ function cmdCommit(argv) {
       if (stagedAfterAdd.some(s => s === norm || s.endsWith('/' + norm) || norm.endsWith(s))) return false;
       // Not in staged diff — check if it's tracked (unchanged) vs untracked/gitignored
       try {
-        execSync(`git ls-files --error-unmatch "${f}"`, { cwd: PROJECT_ROOT, stdio: 'pipe' });
+        execFileSync('git', ['ls-files', '--error-unmatch', f], { cwd: PROJECT_ROOT, stdio: 'pipe' });
         return false; // tracked and unchanged — that's fine
       } catch {
         return true; // not tracked — likely gitignored
@@ -4183,6 +4724,53 @@ function cmdDocsAudit(args) {
   return { has_requirements: true, total: rows.length, gaps };
 }
 
+/**
+ * cmdWorkflowConfigAudit — scan workflow files for stale config.json refs.
+ * Closes #733. Reports every workflow that references .planning/config.json
+ * (legacy location) instead of .rihal/config.yaml (current location).
+ * Read-only. Fix guidance is printed per-file.
+ */
+function cmdWorkflowConfigAudit() {
+  // Check both installed (.rihal/workflows) and source (rihal/workflows) locations
+  const candidates = [
+    path.join(RIHAL_DIR, 'workflows'),
+    path.join(PROJECT_ROOT, 'rihal', 'workflows'),
+  ];
+  const workflowsDir = candidates.find(d => fs.existsSync(d));
+  if (!workflowsDir) {
+    return { ok: true, audited: 0, hits: [], message: 'No workflows directory found (checked .rihal/workflows and rihal/workflows)' };
+  }
+  const files = fs.readdirSync(workflowsDir).filter(f => f.endsWith('.md'));
+  const JSON_RE = /\.planning\/config\.json|planning\/config\.json/g;
+  const hits = [];
+
+  for (const fname of files) {
+    const fpath = path.join(workflowsDir, fname);
+    const text  = fs.readFileSync(fpath, 'utf8');
+    const lines = text.split('\n');
+    const matches = [];
+    lines.forEach((line, idx) => {
+      if (JSON_RE.test(line)) {
+        matches.push({ line: idx + 1, content: line.trim().slice(0, 120) });
+      }
+      JSON_RE.lastIndex = 0; // reset stateful regex
+    });
+    if (matches.length) {
+      hits.push({ file: fname, count: matches.length, refs: matches });
+    }
+  }
+
+  return {
+    ok: true,
+    audited: files.length,
+    stale_count: hits.length,
+    hits,
+    fix_guidance: hits.length > 0
+      ? 'Replace .planning/config.json with .rihal/config.yaml. Use `node rihal-tools.cjs config-get <key>` or readConfig() to read values.'
+      : 'No stale config.json references found.',
+  };
+}
+
 /** init chain — context blob for /rihal-chain workflow. */
 function cmdInitChain(rawArgs) {
   const config = readConfig();
@@ -4611,6 +5199,95 @@ function cmdNotesCount() {
  * Placeholder URLs (containing `<PLACEHOLDER`) are skipped with a clear
  * message — useful in v2.0 before M5 lands real Rihal repo URLs.
  */
+
+/**
+ * cmdHandoff — cross-skill continuation token system. Closes #741.
+ *
+ * Enables one workflow to write a structured "where I left off" token
+ * that the next skill/workflow reads at startup — bridging the context
+ * gap between chained agents.
+ *
+ * Subcommands:
+ *   handoff write --from <skill> --to <skill> --phase <N> [--plan <M>] [--context "..."]
+ *       Write a handoff token to ~/.rihal/handoffs/{from}-{to}-{date}.json
+ *       and also to .rihal/handoff-latest.json for easy pickup by the next agent.
+ *
+ *   handoff read [--from <skill>]
+ *       Read the most recent handoff targeting the current (or specified) skill.
+ *       Returns JSON with: from, to, phase, plan, context, written_at.
+ *       Exits 0 even when no handoff exists (returns {found: false}).
+ *
+ *   handoff clear
+ *       Remove .rihal/handoff-latest.json (signal that the handoff was consumed).
+ */
+function cmdHandoff(args) {
+  const os_mod      = require('os');
+  const sub         = (args[0] || 'help').trim();
+  const handoffsDir = path.join(os_mod.homedir(), '.rihal', 'handoffs');
+  const latestPath  = path.join(RIHAL_DIR, 'handoff-latest.json');
+
+  if (sub === 'write') {
+    const fromVal    = args[args.indexOf('--from') + 1]    || null;
+    const toVal      = args[args.indexOf('--to') + 1]      || null;
+    const phaseVal   = args[args.indexOf('--phase') + 1]   || null;
+    const planVal    = args[args.indexOf('--plan') + 1]     || null;
+    const ctxIdx     = args.indexOf('--context');
+    const contextVal = ctxIdx !== -1 ? args.slice(ctxIdx + 1).join(' ') : null;
+    if (!fromVal || !toVal) throw new Error('handoff write requires --from <skill> and --to <skill>');
+
+    const token = {
+      from: fromVal, to: toVal,
+      phase: phaseVal || null, plan: planVal || null,
+      context: contextVal || null,
+      written_at: new Date().toISOString(),
+    };
+
+    try { fs.mkdirSync(handoffsDir, { recursive: true }); } catch {}
+    const date   = new Date().toISOString().slice(0, 10);
+    const fname  = `${fromVal}-${toVal}-${date}.json`;
+    const fpath  = path.join(handoffsDir, fname);
+    fs.writeFileSync(fpath, JSON.stringify(token, null, 2) + '\n');
+    // Also write the "latest" shortcut into the project .rihal dir
+    try {
+      fs.mkdirSync(RIHAL_DIR, { recursive: true });
+      fs.writeFileSync(latestPath, JSON.stringify(token, null, 2) + '\n');
+    } catch {}
+
+    return { ok: true, token, written_to: [path.relative(PROJECT_ROOT, fpath), path.relative(PROJECT_ROOT, latestPath)] };
+  }
+
+  if (sub === 'read') {
+    const fromFilter = args[args.indexOf('--from') + 1] || null;
+    // Prefer .rihal/handoff-latest.json (written by the most recent handoff write)
+    if (fs.existsSync(latestPath)) {
+      try {
+        const token = JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+        if (!fromFilter || token.from === fromFilter) {
+          return { found: true, token, source: path.relative(PROJECT_ROOT, latestPath) };
+        }
+      } catch {}
+    }
+    // Fallback: scan ~/.rihal/handoffs/ for most recent matching file
+    try {
+      const files = fs.readdirSync(handoffsDir)
+        .filter(f => f.endsWith('.json') && (!fromFilter || f.startsWith(fromFilter + '-')))
+        .sort().reverse();
+      if (files.length) {
+        const token = JSON.parse(fs.readFileSync(path.join(handoffsDir, files[0]), 'utf8'));
+        return { found: true, token, source: files[0] };
+      }
+    } catch {}
+    return { found: false, token: null };
+  }
+
+  if (sub === 'clear') {
+    try { fs.unlinkSync(latestPath); } catch {}
+    return { ok: true, cleared: path.relative(PROJECT_ROOT, latestPath) };
+  }
+
+  return { ok: false, error: `Unknown handoff subcommand: ${sub}. Valid: write, read, clear` };
+}
+
 function cmdBrain(args) {
   const sub = args[0] || 'help';
   // sources.yaml lives under .rihal/brain/ in user installs (v2.2+).
@@ -4803,32 +5480,103 @@ function cmdBrain(args) {
     }
 
     // External git source — use sparse checkout into a tmp dir then copy.
+    // #170 — global brain cache at ~/.rihal/brain-cache/<sha1(repo+branch+paths)>/.
+    // Same source pulled from N projects = N clones today, 1 clone + N copies
+    // after this change. Cache TTL is configurable per source (defaults to 6h).
     const { execSync } = require('child_process');
+    const crypto = require('crypto');
     const os = require('os');
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rihal-brain-'));
     const branch = s.branch || cfg.defaults?.branch || 'main';
+    const sparsePaths = Array.isArray(s.paths) ? s.paths : [];
+
+    // Cache key = sha1(repo + branch + sparsePaths joined). Changing any of
+    // those gets a fresh cache slot. Different projects pulling the same
+    // (repo, branch, paths) tuple share one cached download.
+    const cacheKey = crypto
+      .createHash('sha1')
+      .update(`${repo}\n${branch}\n${sparsePaths.sort().join(',')}`)
+      .digest('hex')
+      .slice(0, 16);
+    const cacheRoot = path.join(os.homedir(), '.rihal', 'brain-cache');
+    const cacheDir = path.join(cacheRoot, cacheKey);
+    const cacheManifest = path.join(cacheDir, '.cache-manifest.json');
+
+    // Parse cache_ttl: accept '6h', '15m', '2d', or seconds as bare number.
+    function parseTtlSeconds(raw, fallback) {
+      if (raw == null || raw === '') return fallback;
+      const s = String(raw).trim();
+      const m = s.match(/^(\d+)([smhd]?)$/i);
+      if (!m) return fallback;
+      const n = parseInt(m[1], 10);
+      switch ((m[2] || 's').toLowerCase()) {
+        case 'd': return n * 86400;
+        case 'h': return n * 3600;
+        case 'm': return n * 60;
+        default:  return n;
+      }
+    }
+    const ttlSeconds = parseTtlSeconds(s.cache_ttl || cfg.defaults?.cache_ttl, 6 * 3600);
+
+    function readCacheManifest() {
+      if (!fs.existsSync(cacheManifest)) return null;
+      try { return JSON.parse(fs.readFileSync(cacheManifest, 'utf8')); }
+      catch { return null; }
+    }
+    function isCacheFresh(manifest) {
+      if (!manifest || typeof manifest.pulled_at !== 'string') return false;
+      const ageMs = Date.now() - Date.parse(manifest.pulled_at);
+      return Number.isFinite(ageMs) && (ageMs / 1000) < ttlSeconds;
+    }
+    function copyTree(src, dst) {
+      for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+        if (e.name === '.git' || e.name === '.cache-manifest.json') continue;
+        const sp = path.join(src, e.name);
+        const dp = path.join(dst, e.name);
+        if (e.isDirectory()) { fs.mkdirSync(dp, { recursive: true }); copyTree(sp, dp); }
+        else if (e.isFile()) fs.copyFileSync(sp, dp);
+      }
+    }
+
+    const destPath = resolveDest(s.dest);
     try {
+      // Cache hit path — copy from ~/.rihal/brain-cache/<key>/ directly.
+      const cached = readCacheManifest();
+      if (cached && isCacheFresh(cached)) {
+        fs.mkdirSync(destPath, { recursive: true });
+        copyTree(cacheDir, destPath);
+        report.pulled.push({ name: s.name, kind: 'git', repo, branch, cache: 'hit', cache_key: cacheKey });
+        continue;
+      }
+
+      // Cache miss — clone, then warm the cache for next time.
       execSync(
         `git clone --depth=1 --filter=blob:none --sparse --branch="${branch}" "${repo}" "${tmp}"`,
         { stdio: 'pipe' }
       );
-      const paths = Array.isArray(s.paths) ? s.paths : [];
-      execSync(`git -C "${tmp}" sparse-checkout set ${paths.map(p => `"${p}"`).join(' ')}`, { stdio: 'pipe' });
+      execSync(`git -C "${tmp}" sparse-checkout set ${sparsePaths.map(p => `"${p}"`).join(' ')}`, { stdio: 'pipe' });
+
+      // Warm cache before destination copy so a copy failure to dest still
+      // saves the next pull. Replace any stale slot atomically.
+      try {
+        fs.rmSync(cacheDir, { recursive: true, force: true });
+        fs.mkdirSync(cacheDir, { recursive: true });
+        copyTree(tmp, cacheDir);
+        const commitSha = (() => {
+          try { return execSync(`git -C "${tmp}" rev-parse HEAD`, { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim(); }
+          catch { return null; }
+        })();
+        fs.writeFileSync(cacheManifest, JSON.stringify({
+          repo, branch, paths: sparsePaths,
+          pulled_at: new Date().toISOString(),
+          commit_sha: commitSha,
+          ttl_seconds: ttlSeconds,
+        }, null, 2));
+      } catch (_) { /* cache warming is best-effort */ }
 
-      const destPath = resolveDest(s.dest);
       fs.mkdirSync(destPath, { recursive: true });
-      // Copy everything the sparse checkout materialized.
-      function copyTree(src, dst) {
-        for (const e of fs.readdirSync(src, { withFileTypes: true })) {
-          if (e.name === '.git') continue;
-          const sp = path.join(src, e.name);
-          const dp = path.join(dst, e.name);
-          if (e.isDirectory()) { fs.mkdirSync(dp, { recursive: true }); copyTree(sp, dp); }
-          else if (e.isFile()) fs.copyFileSync(sp, dp);
-        }
-      }
       copyTree(tmp, destPath);
-      report.pulled.push({ name: s.name, kind: 'git', repo, branch });
+      report.pulled.push({ name: s.name, kind: 'git', repo, branch, cache: 'miss', cache_key: cacheKey });
     } catch (e) {
       report.errors.push({ name: s.name, error: String(e.message || e).slice(0, 200) });
     } finally {
@@ -5445,6 +6193,61 @@ function cmdValidateRoadmap() {
   };
 }
 
+/**
+ * cmdRoadmapDetectStructure — detect monolithic vs per-milestone ROADMAP layout.
+ * Closes #734. Reports which convention is in use so workflows can branch correctly
+ * instead of assuming a single ROADMAP.md.
+ *
+ * Conventions detected:
+ *   monolithic   — .planning/ROADMAP.md (single file, all milestones)
+ *   per-milestone — .planning/ROADMAP-M{N}.md or .planning/milestones/{N}-*.md
+ *   hybrid        — both patterns present
+ *   absent        — no ROADMAP files found at all
+ */
+function cmdRoadmapDetectStructure() {
+  const planningDir = path.join(PROJECT_ROOT, '.planning');
+  const monoPath    = path.join(planningDir, 'ROADMAP.md');
+  const hasMono     = fs.existsSync(monoPath);
+
+  let perMilestoneFiles = [];
+  try {
+    const files = fs.readdirSync(planningDir);
+    // ROADMAP-M1.md, ROADMAP-M2.md, ROADMAP-milestone-name.md
+    perMilestoneFiles = files.filter(f => /^ROADMAP-[A-Za-z0-9].*\.md$/.test(f) && f !== 'ROADMAP.md');
+  } catch {}
+
+  let milestoneDirFiles = [];
+  const msDir = path.join(planningDir, 'milestones');
+  if (fs.existsSync(msDir)) {
+    try { milestoneDirFiles = fs.readdirSync(msDir).filter(f => f.endsWith('.md')); } catch {}
+  }
+
+  const hasPerMilestone = perMilestoneFiles.length > 0 || milestoneDirFiles.length > 0;
+
+  let structure;
+  if (hasMono && hasPerMilestone) structure = 'hybrid';
+  else if (hasMono)               structure = 'monolithic';
+  else if (hasPerMilestone)       structure = 'per-milestone';
+  else                            structure = 'absent';
+
+  return {
+    ok: true,
+    structure,
+    monolithic_file: hasMono ? '.planning/ROADMAP.md' : null,
+    per_milestone_files: [
+      ...perMilestoneFiles.map(f => `.planning/${f}`),
+      ...milestoneDirFiles.map(f => `.planning/milestones/${f}`),
+    ],
+    recommendation: structure === 'monolithic'
+      ? 'Standard layout. Use /rihal-plan and /rihal-execute normally.'
+      : structure === 'per-milestone'
+      ? 'Per-milestone layout detected. Pass the specific ROADMAP file to rihal-roadmapper with --roadmap <path>.'
+      : structure === 'hybrid'
+      ? 'Mixed layout. Consolidate to one convention to avoid workflow confusion.'
+      : 'No ROADMAP found. Run /rihal-new-project or /rihal-new-milestone first.',
+  };
+}
+
 /**
  * cmdMilestoneHealth — gauge for the current milestone (issue #718).
  *
@@ -5735,6 +6538,9 @@ async function main() {
       case 'docs-audit':
         result = cmdDocsAudit(args);
         break;
+      case 'workflow-config-audit':
+        result = cmdWorkflowConfigAudit();
+        break;
       case 'frontmatter':
         if (args[0] === 'get') { cmdFrontmatterGet(args.slice(1)); return; }
         else { console.error('Unknown frontmatter subcommand. Valid: get'); process.exit(1); }
@@ -5835,6 +6641,51 @@ async function main() {
         result = cfg.cmdSet(PROJECT_ROOT, args[0], args.slice(1).join(' '));
         break;
       }
+      case 'config-check-yolo': {
+        // Closes #739. Evaluate whether yolo mode is active for a given scope.
+        // Usage: config-check-yolo [--phase <N>] [--workflow <name>]
+        // Returns JSON: { active: bool, mode, scope, expires_at, reason }
+        const cfg = require(path.join(__dirname, 'lib', 'config.cjs'));
+        const phaseArg    = args[args.indexOf('--phase') + 1]    || null;
+        const workflowArg = args[args.indexOf('--workflow') + 1] || null;
+        const mode        = cfg.cmdGet(PROJECT_ROOT, 'mode') || 'guided';
+        if (mode !== 'yolo') {
+          result = { active: false, mode, scope: null, expires_at: null, reason: 'mode is not yolo' };
+          break;
+        }
+        // Check optional yolo_scope restriction
+        const scopeRaw = cfg.cmdGet(PROJECT_ROOT, 'yolo_scope') || null;
+        if (scopeRaw) {
+          const scope = String(scopeRaw).trim();
+          // scope format: "phase:N" | "workflow:name" | "global"
+          if (scope.startsWith('phase:') && phaseArg) {
+            const allowedPhase = scope.slice('phase:'.length).trim();
+            if (String(phaseArg) !== allowedPhase) {
+              result = { active: false, mode, scope, expires_at: null, reason: `yolo_scope restricts to phase ${allowedPhase}, current is ${phaseArg}` };
+              break;
+            }
+          } else if (scope.startsWith('workflow:') && workflowArg) {
+            const allowedWf = scope.slice('workflow:'.length).trim();
+            if (workflowArg !== allowedWf) {
+              result = { active: false, mode, scope, expires_at: null, reason: `yolo_scope restricts to workflow ${allowedWf}, current is ${workflowArg}` };
+              break;
+            }
+          }
+        }
+        // Check optional TTL
+        const ttlRaw = cfg.cmdGet(PROJECT_ROOT, 'yolo_ttl') || null;
+        let expiresAt = null;
+        if (ttlRaw) {
+          expiresAt = ttlRaw;
+          const expiry = new Date(ttlRaw);
+          if (!Number.isNaN(expiry.getTime()) && Date.now() > expiry.getTime()) {
+            result = { active: false, mode, scope: scopeRaw, expires_at: ttlRaw, reason: `yolo_ttl expired at ${ttlRaw}` };
+            break;
+          }
+        }
+        result = { active: true, mode, scope: scopeRaw || 'global', expires_at: expiresAt, reason: 'yolo active' };
+        break;
+      }
       case 'verify': {
         const verify = require(path.join(__dirname, 'lib', 'verify.cjs'));
         result = verify.dispatch(PROJECT_ROOT, args);
@@ -5844,6 +6695,10 @@ async function main() {
         result = cmdBrain(args);
         break;
       }
+      case 'handoff': {
+        result = cmdHandoff(args);
+        break;
+      }
       case 'progress': {
         result = cmdProgress(args);
         break;
@@ -5872,6 +6727,9 @@ async function main() {
       case 'validate-roadmap':
         result = cmdValidateRoadmap();
         break;
+      case 'roadmap-detect-structure':
+        result = cmdRoadmapDetectStructure();
+        break;
       case 'milestone-health':
         result = cmdMilestoneHealth();
         break;
@@ -5893,6 +6751,9 @@ async function main() {
         console.log('  list-agents                                  → list all available Rihal agents');
         console.log('  state <subcommand> [args]                    → manage .rihal/state.json');
         console.log('  phase add <name> [--decimal <parent>]        → add phase (integer to current milestone, or --decimal slots under parent as parent.M)');
+        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('  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)');
         console.log('  generate-claude-md [--force]                 → bootstrap a project CLAUDE.md scaffold (refuses to overwrite without --force)');
@@ -5918,6 +6779,12 @@ async function main() {
         console.log('  roadmap <get-phase|list-phases|update-plan-progress|clear>  → .planning/ROADMAP.md operations');
         console.log('  config-get <dotted.key>                      → read scalar from .rihal/config.yaml');
         console.log('  config-set <dotted.key> <value>              → atomically set a value in .rihal/config.yaml');
+        console.log('  config-check-yolo [--phase N] [--workflow W] → check if yolo mode is active for scope (#739)');
+        console.log('  handoff write --from <skill> --to <skill> --phase N [--context "..."] → write cross-skill handoff token (#741)');
+        console.log('  handoff read [--from <skill>]               → read most recent handoff for this skill (#741)');
+        console.log('  handoff clear                               → consume (clear) the latest handoff token (#741)');
+        console.log('    yolo_scope config keys: "global" | "phase:N" | "workflow:name"');
+        console.log('    yolo_ttl config key: ISO timestamp — yolo auto-expires after this time');
         console.log('  verify schema-drift <phase> [--block]        → detect schema vs migration drift across phase commits');
         console.log('  resolve-model <profile>                      → resolve model name from profile');
         console.log('  version                                      → print rihal-tools version');