@hanzlaa/rcode 3.4.4 → 3.4.6

package/rihal/bin/rihal-tools.cjs

@@ -43,6 +43,42 @@ const WORKFLOWS_DIR = path.join(RIHAL_DIR, 'workflows');
 const PLANNING_DIR = path.join(PROJECT_ROOT, '.planning');
 const SESSIONS_DIR = path.join(PLANNING_DIR, 'council-sessions');
 
+// #473 guard: if CWD has its own .rihal/ but doesn't match the resolved
+// PROJECT_ROOT, the user is invoking this binary from a different project.
+// Without this guard, every state-writing subcommand silently targets the
+// installer's repo instead of the user's CWD — surfaced during Phase 12
+// smoke tests when `phase add` polluted the rihal-code repo's ROADMAP
+// while running from /tmp. Refuse to operate with a clear error.
+function assertCwdMatchesProjectRoot() {
+  try {
+    const cwd = process.cwd();
+    const cwdRihal = path.join(cwd, '.rihal');
+    if (!fs.existsSync(cwdRihal)) return; // no local install — fine
+    if (path.resolve(cwd) === path.resolve(PROJECT_ROOT)) return; // same project — fine
+    // CWD has its own .rihal/ but is NOT this binary's project. Refuse.
+    process.stderr.write(
+      `Refusing to operate: this binary lives at ${path.dirname(__dirname)}/bin/ ` +
+      `but CWD ${cwd} has its own .rihal/ — running from here would silently ` +
+      `target the wrong project (#473). Use the CWD's installed CLI: ` +
+      `node "${cwdRihal}/bin/rihal-tools.cjs" <args>\n`
+    );
+    process.exit(2);
+  } catch { /* never crash startup on diagnostic logic */ }
+}
+
+/**
+ * Return the first file in `dir` matching `pattern`, or null.
+ * Used by cmdInit's phase-aware fields branch (Phase 10 / #466) to resolve
+ * specific artifact paths (CONTEXT.md, RESEARCH.md, VERIFICATION.md) from
+ * a phase directory that may use either zero-padded (06-name) or plain
+ * (6-name) prefix conventions.
+ */
+function files0(dir, pattern) {
+  if (!fs.existsSync(dir)) return null;
+  const matches = fs.readdirSync(dir).filter(f => pattern.test(f));
+  return matches.length > 0 ? matches[0] : null;
+}
+
 /**
  * Parse a minimal YAML subset for our flat config.yaml shape.
  * Only supports `key: value` lines — no nesting, no lists, no flow syntax.
@@ -87,6 +123,62 @@ function readConfig() {
   }
 }
 
+/**
+ * Read .rihal/config.yaml as a nested object (workflow.*, features.*, etc.).
+ * Phase 12 / #468 — used by cmdInit to surface workflow feature flags into
+ * the init JSON so workflow agents don't re-shell config-get per field.
+ * Returns {} when config absent or unreadable.
+ */
+function readNestedConfig() {
+  try {
+    const configPath = path.join(RIHAL_DIR, 'config.yaml');
+    if (!fs.existsSync(configPath)) return {};
+    const cfg = require(path.join(__dirname, 'lib', 'config.cjs'));
+    return cfg.parseNestedYaml(fs.readFileSync(configPath, 'utf8')) || {};
+  } catch { return {}; }
+}
+
+/**
+ * Resolve the model string for an agent under the current profile.
+ * Phase 12 / #468 — returns just the model id (or null when the agent isn't
+ * installed or the profile inherits). Wraps cmdResolveModel so cmdInit can
+ * surface researcher_model / planner_model / checker_model without throwing
+ * when an agent isn't shipped.
+ */
+function resolveModelString(agentId) {
+  try {
+    const installed = listInstalledAgents();
+    // Manifest ids are stored bare (e.g. "planner") while workflows reference
+    // them with the rihal- prefix. Try both forms before giving up.
+    const bare = agentId.replace(/^rihal-/, '');
+    const candidate = installed.includes(agentId) ? agentId
+                    : installed.includes(bare) ? bare
+                    : null;
+    if (!candidate) return null;
+    const r = cmdResolveModel(candidate);
+    return (r && r.model) ? r.model : null;
+  } catch { return null; }
+}
+
+/**
+ * Extract REQ-IDs (REQ-FOO, REQ-FOO-BAR) from a ROADMAP requirements list.
+ * Phase 12 / #468 — feeds plan.md's `phase_req_ids` field. Returns deduped
+ * array in source order. Empty array when no IDs match.
+ */
+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;
+  for (const line of requirements) {
+    const matches = String(line).match(re) || [];
+    for (const m of matches) {
+      if (!seen.has(m)) { seen.add(m); out.push(m); }
+    }
+  }
+  return out;
+}
+
 /**
  * Parse CSV with quoted-field support. Expects the first row to be headers.
  * Returns array of objects keyed by header.
@@ -327,6 +419,155 @@ function cmdInit(workflowName, rawArgs) {
     state_exists: fs.existsSync(path.join(RIHAL_DIR, 'state.json')),
   };
 
+  // Phase 10 / #466 — phase-aware fields for phase-op + sprint-plan workflows.
+  // Closes the third part of #464 (workflows expect these fields per their
+  // documented init contract; before this they were silently absent).
+  if ((workflowName === 'phase-op' || workflowName === 'sprint-plan') && question) {
+    const phaseInput = question.trim().split(/\s+/)[0];
+    const phaseNum = parseInt(phaseInput, 10);
+    if (!Number.isNaN(phaseNum) && phaseNum > 0) {
+      const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+      const phasesDir = path.join(PLANNING_DIR, 'phases');
+      out.roadmap_exists = fs.existsSync(roadmapPath);
+      out.planning_exists = fs.existsSync(PLANNING_DIR);
+
+      // Find phase entry in ROADMAP via the now-fixed parser.
+      let roadmapPhase = null;
+      if (out.roadmap_exists) {
+        try {
+          const roadmap = require(path.join(__dirname, 'lib', 'roadmap.cjs'));
+          const r = roadmap.dispatch(PROJECT_ROOT, ['get-phase', String(phaseNum)]);
+          if (r && r.found) roadmapPhase = r;
+        } catch { /* parser failure shouldn't break init */ }
+      }
+
+      // Find phase directory on disk (matches both '6-name' and legacy '06-name').
+      let phaseDirEntry = null;
+      if (fs.existsSync(phasesDir)) {
+        const padded = String(phaseNum).padStart(2, '0');
+        for (const entry of fs.readdirSync(phasesDir)) {
+          if (entry === String(phaseNum) || entry.startsWith(`${phaseNum}-`) || entry.startsWith(`${padded}-`)) {
+            phaseDirEntry = entry;
+            break;
+          }
+        }
+      }
+
+      out.phase_found = roadmapPhase !== null;
+      out.phase_number = String(phaseNum);
+      out.padded_phase = String(phaseNum).padStart(2, '0');
+      out.phase_name = roadmapPhase ? roadmapPhase.name : null;
+      out.phase_slug = phaseDirEntry ? phaseDirEntry.replace(/^\d+-/, '') : null;
+      out.phase_dir = phaseDirEntry ? path.join(PLANNING_DIR, 'phases', phaseDirEntry) : null;
+
+      // Phase status from state.json (complete/executed/in_progress/planned/null).
+      // Used by plan.md to show context-aware messaging when plans already exist.
+      try {
+        const stateFilePath = path.join(RIHAL_DIR, 'state.json');
+        const rawState = fs.existsSync(stateFilePath)
+          ? JSON.parse(fs.readFileSync(stateFilePath, 'utf8'))
+          : null;
+        const stPhase = (rawState?.phases || []).find(p => {
+          const k = String(p.id || p.number || '').replace(/^0+/, '') || String(p.id || p.number || '');
+          return k === String(phaseNum);
+        });
+        out.phase_status = stPhase ? (stPhase.status || null) : null;
+      } catch { out.phase_status = null; }
+
+      // Disk artifacts — same shape as walkPhaseDirs() but inlined.
+      if (phaseDirEntry) {
+        const dirFull = path.join(phasesDir, phaseDirEntry);
+        const files = fs.readdirSync(dirFull);
+        out.has_research = files.some(f => /(?:^|-)RESEARCH\.md$/i.test(f));
+        out.has_context = files.some(f => /(?:^|-)CONTEXT\.md$/i.test(f));
+        out.has_verification = files.some(f => /(?:^|-)VERIFICATION\.md$/i.test(f));
+        out.has_plans = files.some(f => /(?:^|-)(PLAN|SPRINT)\.md$/i.test(f));
+        out.plan_count = files.filter(f => /(?:^|-)(PLAN|SPRINT)\.md$/i.test(f)).length;
+        // Phase 12 / #468 — REVIEWS.md + UAT.md presence (referenced by plan.md).
+        out.has_reviews = files.some(f => /(?:^|-)REVIEWS\.md$/i.test(f));
+        out.has_uat = files.some(f => /(?:^|-)UAT\.md$/i.test(f));
+      } else {
+        out.has_research = false;
+        out.has_context = false;
+        out.has_verification = false;
+        out.has_plans = false;
+        out.plan_count = 0;
+        out.has_reviews = false;
+        out.has_uat = false;
+      }
+
+      // Source-of-truth path getters for the fields workflows reference.
+      out.context_path = (out.phase_dir && out.has_context)
+        ? path.join(out.phase_dir, files0(out.phase_dir, /CONTEXT\.md$/i))
+        : null;
+      out.research_path = (out.phase_dir && out.has_research)
+        ? path.join(out.phase_dir, files0(out.phase_dir, /RESEARCH\.md$/i))
+        : null;
+      out.verification_path = (out.phase_dir && out.has_verification)
+        ? path.join(out.phase_dir, files0(out.phase_dir, /VERIFICATION\.md$/i))
+        : null;
+      // Phase 12 / #468 — REVIEWS.md / UAT.md paths (null when absent).
+      out.reviews_path = (out.phase_dir && out.has_reviews)
+        ? path.join(out.phase_dir, files0(out.phase_dir, /REVIEWS\.md$/i))
+        : null;
+      out.uat_path = (out.phase_dir && out.has_uat)
+        ? path.join(out.phase_dir, files0(out.phase_dir, /UAT\.md$/i))
+        : null;
+      out.state_path = path.join(RIHAL_DIR, 'state.json');
+      out.roadmap_path = roadmapPath;
+      out.requirements_path = fs.existsSync(path.join(PLANNING_DIR, 'REQUIREMENTS.md'))
+        ? path.join(PLANNING_DIR, 'REQUIREMENTS.md')
+        : null;
+
+      // Defaults consumed by /rihal-plan and /rihal-discuss-phase.
+      // Accept both bare commit_docs and nested git.commit_docs (settings.md uses git.commit_docs).
+      const _rawCommitDocs = config.git?.commit_docs ?? config.commit_docs;
+      out.commit_docs = _rawCommitDocs === undefined ? true : String(_rawCommitDocs) !== 'false';
+      out.response_language = config.response_language || config.language || null;
+
+      // Phase 12 / #468 — close the agent-context contract.
+      // Reads nested config (workflow.*, features.*) via lib/config.cjs and
+      // surfaces every field that plan.md/discuss-phase.md reference today.
+      const nestedCfg = readNestedConfig();
+      const wf = nestedCfg.workflow || {};
+      const features = nestedCfg.features || {};
+
+      // Workflow feature flags (top-level for direct workflow consumption).
+      // Defaults match the inline `config-get … || echo "X"` calls in the workflows.
+      out.research_enabled = String(wf.research_by_default ?? 'false') === 'true';
+      out.plan_checker_enabled = String(wf.plan_checker ?? 'true') !== 'false';
+      out.nyquist_validation_enabled = String(wf.nyquist_validation ?? 'true') !== 'false';
+      out.text_mode = String(wf.text_mode ?? 'false') === 'true';
+
+      // Model resolution per active profile. The researcher agent ships as
+      // `phase-researcher` in this codebase; resolveModelString falls back to
+      // that when the prefixed/bare `researcher` ids aren't present.
+      out.researcher_model = resolveModelString('rihal-researcher')
+        || resolveModelString('rihal-phase-researcher');
+      out.planner_model = resolveModelString('rihal-planner');
+      out.checker_model = resolveModelString('rihal-sprint-checker');
+
+      // Phase requirement IDs — extracted from ROADMAP requirements block.
+      out.phase_req_ids = extractReqIds(roadmapPhase ? roadmapPhase.requirements : []);
+
+      // Deeper config flags (grouped to keep top-level lean).
+      // Defaults documented in the workflows' inline config-get fallbacks.
+      out.features = {
+        thinking_partner: String(features.thinking_partner ?? 'false') === 'true',
+      };
+      out.workflow_flags = {
+        discuss_mode: wf.discuss_mode ?? 'adaptive',
+        research_before_questions: String(wf.research_before_questions ?? 'true') !== 'false',
+        max_discuss_passes: parseInt(wf.max_discuss_passes ?? '3', 10) || 3,
+        security_enforcement: String(wf.security_enforcement ?? 'true') !== 'false',
+        security_asvs_level: parseInt(wf.security_asvs_level ?? '1', 10) || 1,
+        ui_phase: String(wf.ui_phase ?? 'true') !== 'false',
+        ui_safety_gate: String(wf.ui_safety_gate ?? 'true') !== 'false',
+      };
+    }
+  }
+
+
   return out;
 }
 
@@ -363,8 +604,38 @@ function cmdSelectPanel(rawArgs) {
   };
 }
 
+// Canonical aliases for short workflow-side ids that don't match manifest ids.
+// Workflows historically use shorter names (researcher, checker, advisor) that
+// map to longer manifest ids. Keep the alias table small and explicit — if a
+// new agent needs an alias, add it here, don't add fuzzy matching. (#472)
+const AGENT_ID_ALIASES = {
+  researcher: 'phase-researcher',
+  checker: 'sprint-checker',
+  advisor: 'advisor-researcher',
+};
+
+function resolveAgentId(rawId, manifest) {
+  if (!rawId) return null;
+  // 1. Exact match on raw id
+  let row = manifest.find((r) => r.id === rawId);
+  if (row) return row;
+  // 2. Strip leading rihal- prefix (workflows use prefixed form, manifest is bare)
+  const stripped = rawId.replace(/^rihal-/, '');
+  if (stripped !== rawId) {
+    row = manifest.find((r) => r.id === stripped);
+    if (row) return row;
+  }
+  // 3. Apply canonical aliases (e.g. researcher → phase-researcher)
+  const aliased = AGENT_ID_ALIASES[stripped];
+  if (aliased) {
+    row = manifest.find((r) => r.id === aliased);
+    if (row) return row;
+  }
+  return null;
+}
+
 function cmdAgentInfo(agentId) {
-  const row = readAgentManifest().find((r) => r.id === agentId);
+  const row = resolveAgentId(agentId, readAgentManifest());
   if (!row) {
     console.error(`Unknown agent: ${agentId}`);
     process.exit(1);
@@ -460,16 +731,34 @@ function cmdClassifyQuestion(raw) {
       'design system', 'component library', 'accessibility', 'a11y', 'ui design',
       'redesign', 'onboarding flow', 'landing page', 'interface', 'layout',
     ],
+    frontend: [
+      'react', 'component', 'frontend', 'front-end', 'next.js', 'nextjs',
+      'tailwind', 'tsx', 'jsx', 'rtl', 'a11y',
+      'css', 'html', 'layout', 'responsive', 'animation', 'hydration',
+      'bundle size', 'lighthouse', 'cls', 'lcp', 'tbt', 'ui component',
+      'page render', 'client side', 'browser render',
+      // Roman Urdu FE signals
+      'front end', 'fe issue', 'ui fix',
+    ],
+    backend: [
+      'backend', 'back-end', 'api endpoint', 'server side', 'prisma',
+      'database query', 'db query', 'sql query', 'orm', 'db migration',
+      'queue', 'webhook', 'graphql', 'rest api', 'n+1',
+      'redis', 'postgres', 'mysql', 'mongodb', 'bullmq',
+      'cron job', 'rate limit', 'auth middleware',
+      // Roman Urdu BE signals
+      'be issue', 'api slow', 'db slow',
+    ],
     codebase: [
       'rewrite', 'refactor', 'migrate', 'this code', 'this function', 'this file',
       'this component', 'this api', 'this service', 'this database', 'this schema',
       'the auth', 'the tests', 'the build', 'the deploy', 'the pipeline',
       'production ready', 'ready to ship', 'test coverage', 'bug', 'error',
-      'performance', 'should i rewrite', 'auth layer', 'db migration',
+      'performance', 'should i rewrite', 'auth layer',
       'pull request', 'code review', 'technical debt', 'tech debt',
       'feature', 'ci/cd', 'cicd', 'pipeline', 'documentation', 'docs',
       // Tech choice signals
-      'astro', 'nextjs', 'next.js', 'remix', 'nuxt', 'svelte', 'vue', 'angular',
+      'astro', 'remix', 'nuxt', 'svelte', 'vue', 'angular',
       'should i use', 'which framework', 'compare framework',
       // Roman Urdu codebase/fix signals
       'fix karo', 'theek karo', 'sahi karo',
@@ -477,6 +766,20 @@ function cmdClassifyQuestion(raw) {
       // Arabic execution signals
       'إصلاح', 'كود', 'برنامج', 'نفذ', 'شغل',
     ],
+    // Phase 6 — drift / audit / re-audit / extend-existing-artifact signals.
+    // Routes /rihal-do toward /rihal-feature-drift instead of falling
+    // through to inline execution. Reinforces classifyScope's drift branch.
+    drift: [
+      'drift', 'redrift', 're-audit', 'reaudit', 'audit feature', 'audit docs',
+      'audit the docs', 'audit the prd', 'audit feature docs',
+      'fill out existing', 'fill out the existing', 'fill out this',
+      'extend audit', 'extend the audit', 'extend plan', 'extend the plan',
+      'expand audit', 'expand the audit',
+      'verify docs vs code', 'verify claims vs code', 'docs vs reality', 'docs vs code',
+      'stale docs', 'out of date docs', 'out-of-date docs',
+      // Roman Urdu drift signals
+      'docs purane hai', 'docs purani hain', 'docs stale hain', 'audit dobara',
+    ],
   };
 
   const matchedSignals = (signals) => signals.filter((s) => normalized.includes(s));
@@ -485,8 +788,8 @@ function cmdClassifyQuestion(raw) {
     matched[type] = matchedSignals(signals);
   }
 
-  // Weights per type
-  const WEIGHTS = { discovery: 3, market: 2, greenfield: 2, team: 3, release: 3, design: 3, codebase: 3 };
+  // Weights per type — frontend/backend get weight 4 (most specific signals).
+  const WEIGHTS = { discovery: 3, market: 2, greenfield: 2, team: 3, release: 3, design: 3, codebase: 3, drift: 3, frontend: 4, backend: 4 };
   const scores = {};
   for (const [type, hits] of Object.entries(matched)) {
     scores[type] = hits.length * WEIGHTS[type];
@@ -835,7 +1138,7 @@ function cmdState(subArgs) {
         : phaseIdx + 1;
     if (!phase.sprints) phase.sprints = [];
     const sprintNum = phase.sprints.length + 1;
-    const padPhase = String(phaseNum).padStart(2, '0');
+    const padPhase = String(phaseNum); // no leading zeros
     const sprintId = `${padPhase}.${sprintNum}`;
 
     const sprint = {
@@ -975,7 +1278,7 @@ function cmdState(subArgs) {
         if (s.id === sprintId) {
           if (!s.stories) s.stories = [];
           const storyNum = s.stories.length + 1;
-          const storyId = `${sprintId}.${String(storyNum).padStart(2, '0')}`;
+          const storyId = `${sprintId}.${String(storyNum)}`;
           const story = {
             id: storyId,
             title: flags.title,
@@ -1408,14 +1711,14 @@ function cmdState(subArgs) {
     if (fs.existsSync(phasesDir)) {
       const entries = fs.readdirSync(phasesDir);
       for (const entry of entries) {
-        const match = entry.match(/^(\d{2})-/);
+        const match = entry.match(/^(\d+)-/);
         if (match) {
           const num = parseInt(match[1], 10);
           maxNum = Math.max(maxNum, num);
         }
       }
     }
-    const nextId = String(maxNum + 1).padStart(2, '0');
+    const nextId = String(maxNum + 1);
     return { ok: true, next_phase_id: nextId };
   }
 
@@ -1423,52 +1726,52 @@ function cmdState(subArgs) {
   if (sub === 'next-plan-id') {
     const phaseId = subArgs[1];
     if (!phaseId) throw new Error('next-plan-id requires a phase ID argument (NN format)');
-    const phaseMatch = phaseId.match(/^(\d{2})(?:\.(\d+))?$/);
-    if (!phaseMatch) throw new Error(`Invalid phase ID format: ${phaseId}. Expected NN or NN.M`);
+    const phaseMatch = phaseId.match(/^(\d+)(?:\.(\d+))?$/);
+    if (!phaseMatch) throw new Error(`Invalid phase ID format: ${phaseId}. Expected N or N.M`);
 
     const phasePart = phaseMatch[1];
     const phasesDir = path.join(PLANNING_DIR, 'phases');
 
-    // Find the phase directory matching NN-*
+    // Find the phase directory matching NN-* (directories may be zero-padded for sorting)
     let phaseDir = null;
     if (fs.existsSync(phasesDir)) {
       const entries = fs.readdirSync(phasesDir);
       for (const entry of entries) {
-        const match = entry.match(/^(\d{2})(?:\.\d+)?-/);
-        if (match && match[1] === phasePart) {
+        const match = entry.match(/^(\d+)(?:\.\d+)?-/);
+        if (match && parseInt(match[1], 10) === parseInt(phasePart, 10)) {
           phaseDir = path.join(phasesDir, entry);
           break;
         }
       }
     }
 
-    // If no phase dir found, default to 01 plan
+    // If no phase dir found, default to 1st plan
     if (!phaseDir) {
-      return { ok: true, next_plan_id: `${phasePart}.01` };
+      return { ok: true, next_plan_id: `${phasePart}.1` };
     }
 
     // Scan phase dir for numbered subdirs (MM-*) to find max plan number
     let maxPlanNum = 0;
     const entries = fs.readdirSync(phaseDir);
     for (const entry of entries) {
-      const match = entry.match(/^(\d{2})-/);
+      const match = entry.match(/^(\d+)-/);
       if (match && fs.statSync(path.join(phaseDir, entry)).isDirectory()) {
         const num = parseInt(match[1], 10);
         maxPlanNum = Math.max(maxPlanNum, num);
       }
     }
 
-    const nextPlanNum = String(maxPlanNum + 1).padStart(2, '0');
-    // First plan in empty phase gets .01 not .02
-    return { ok: true, next_plan_id: maxPlanNum === 0 ? `${phasePart}.01` : `${phasePart}.${nextPlanNum}` };
+    const nextPlanNum = String(maxPlanNum + 1);
+    // First plan in empty phase gets .1 not .2
+    return { ok: true, next_plan_id: maxPlanNum === 0 ? `${phasePart}.1` : `${phasePart}.${nextPlanNum}` };
   }
 
   // --- next-task-id <plan-id> ---
   if (sub === 'next-task-id') {
     const planId = subArgs[1];
     if (!planId) throw new Error('next-task-id requires a plan ID argument (NN.MM format)');
-    const match = planId.match(/^(\d{2})\.(\d{2})$/);
-    if (!match) throw new Error(`Invalid plan ID format: ${planId}. Expected NN.MM`);
+    const match = planId.match(/^(\d+)\.(\d+)$/);
+    if (!match) throw new Error(`Invalid plan ID format: ${planId}. Expected N.M`);
 
     const phasePart = match[1];
     const planPart = match[2];
@@ -1480,15 +1783,15 @@ function cmdState(subArgs) {
     if (fs.existsSync(phasesDir)) {
       const entries = fs.readdirSync(phasesDir);
       for (const entry of entries) {
-        const phaseMatch = entry.match(/^(\d{2})(?:\.\d+)?-/);
-        if (phaseMatch && phaseMatch[1] === phasePart) {
+        const phaseMatch = entry.match(/^(\d+)(?:\.\d+)?-/);
+        if (phaseMatch && parseInt(phaseMatch[1], 10) === parseInt(phasePart, 10)) {
           const phaseDir = path.join(phasesDir, entry);
 
           // Check for subdirectory named planPart-*
           const subentries = fs.readdirSync(phaseDir);
           for (const subentry of subentries) {
-            const subMatch = subentry.match(/^(\d{2})-/);
-            if (subMatch && subMatch[1] === planPart) {
+            const subMatch = subentry.match(/^(\d+)-/);
+            if (subMatch && parseInt(subMatch[1], 10) === parseInt(planPart, 10)) {
               const planDir = path.join(phaseDir, subentry);
               const candidate = path.join(planDir, 'SPRINT.md');
               if (fs.existsSync(candidate)) {
@@ -1499,7 +1802,7 @@ function cmdState(subArgs) {
           }
 
           // If no subdir found, check phase-level PLAN.md
-          if (!planFile && planPart === '01') {
+          if (!planFile && parseInt(planPart, 10) === 1) {
             const candidate = path.join(phaseDir, 'SPRINT.md');
             if (fs.existsSync(candidate)) {
               planFile = candidate;
@@ -1517,7 +1820,7 @@ function cmdState(subArgs) {
     // Read PLAN.md and count existing tasks
     const planContent = fs.readFileSync(planFile, 'utf8');
     const taskMatches = planContent.match(/^### Task \d+\.\d+\.\d+ —/gm) || [];
-    const nextTaskNum = String(taskMatches.length + 1).padStart(2, '0');
+    const nextTaskNum = String(taskMatches.length + 1);
 
     return { ok: true, next_task_id: `${planId}.${nextTaskNum}` };
   }
@@ -1534,10 +1837,10 @@ function cmdState(subArgs) {
     if (/^M\d+$/.test(id)) {
       idType = 'milestone';
       milestoneId = id;
-    } else if (/^\d{2}$/.test(id)) {
+    } else if (/^\d+$/.test(id)) {
       idType = 'phase';
       phaseId = id;
-    } else if (/^\d{2}\.\d+$/.test(id)) {
+    } else if (/^\d+\.\d+$/.test(id)) {
       const parts = id.split('.');
       phaseId = parts[0];
 
@@ -1548,7 +1851,7 @@ function cmdState(subArgs) {
       if (fs.existsSync(phasesDir)) {
         const entries = fs.readdirSync(phasesDir);
         for (const entry of entries) {
-          if (entry.match(/^\d{2}\.\d+-/)) {
+          if (entry.match(/^\d+\.\d+-/)) {
             isDecimalPhase = true;
             break;
           }
@@ -1561,7 +1864,7 @@ function cmdState(subArgs) {
         idType = 'plan';
         planId = id;
       }
-    } else if (/^\d{2}\.\d+\.\d+$/.test(id)) {
+    } else if (/^\d+\.\d+\.\d+$/.test(id)) {
       idType = 'task';
       const parts = id.split('.');
       phaseId = parts[0];
@@ -1591,8 +1894,8 @@ function cmdState(subArgs) {
       if (fs.existsSync(phasesDir)) {
         const entries = fs.readdirSync(phasesDir);
         for (const entry of entries) {
-          const match = entry.match(/^(\d{2})-/);
-          if (match && match[1] === phaseId) {
+          const match = entry.match(/^(\d+)-/);
+          if (match && parseInt(match[1], 10) === parseInt(phaseId, 10)) {
             const phaseDir = path.join(phasesDir, entry);
             result.phase_dir = phaseDir;
 
@@ -1603,8 +1906,8 @@ function cmdState(subArgs) {
               // Check for subdirectory
               const subentries = fs.readdirSync(phaseDir);
               for (const subentry of subentries) {
-                const subMatch = subentry.match(/^(\d{2})-/);
-                if (subMatch && subMatch[1] === planNum) {
+                const subMatch = subentry.match(/^(\d+)-/);
+                if (subMatch && parseInt(subMatch[1], 10) === parseInt(planNum, 10)) {
                   const planDir = path.join(phaseDir, subentry);
                   const planPath = path.join(planDir, 'SPRINT.md');
                   if (fs.existsSync(planPath)) {
@@ -1615,8 +1918,8 @@ function cmdState(subArgs) {
                 }
               }
 
-              // If no subdir and planNum is 01, check phase-level PLAN.md
-              if (!result.path && planNum === '01') {
+              // If no subdir and planNum is 1, check phase-level PLAN.md
+              if (!result.path && parseInt(planNum, 10) === 1) {
                 const candidate = path.join(phaseDir, 'SPRINT.md');
                 if (fs.existsSync(candidate)) {
                   result.plan_dir = phaseDir;
@@ -1673,16 +1976,18 @@ function cmdState(subArgs) {
     if (fs.existsSync(phasesDir)) {
       const entries = fs.readdirSync(phasesDir);
       for (const entry of entries) {
-        const match = entry.match(/^(\d{2})(?:\.\d+)?-(.+)$/);
+        const match = entry.match(/^(\d+)(?:\.\d+)?-(.+)$/);
         if (match) {
-          const phaseId = match[1];
+          const phaseId = String(parseInt(match[1], 10)); // strip leading zeros
           const slug = match[2];
           const phaseDir = path.join(phasesDir, entry);
 
-          // Add phase if not already present
-          if (!state.phases.some(p => p.id === phaseId)) {
+          // Add phase if not already present (check both id and number per #482-A
+          // schema-drift fix — different writers use different field names).
+          if (!state.phases.some(p => String(parseInt(p.id, 10)) === phaseId || String(parseInt(p.number, 10)) === phaseId)) {
             state.phases.push({
               id: phaseId,
+              number: phaseId,
               slug,
               path: phaseDir,
               created: new Date().toISOString(),
@@ -1692,9 +1997,9 @@ function cmdState(subArgs) {
           // Scan for plans within phase
           const subentries = fs.readdirSync(phaseDir);
           for (const subentry of subentries) {
-            const subMatch = subentry.match(/^(\d{2})-(.+)$/);
+            const subMatch = subentry.match(/^(\d+)-(.+)$/);
             if (subMatch && fs.statSync(path.join(phaseDir, subentry)).isDirectory()) {
-              const planNum = subMatch[1];
+              const planNum = String(parseInt(subMatch[1], 10)); // strip leading zeros
               const planId = `${phaseId}.${planNum}`;
               const planSlug = subMatch[2];
               const planDir = path.join(phaseDir, subentry);
@@ -1769,7 +2074,7 @@ function cmdState(subArgs) {
       let phaseNum = 1;
 
       for (const entry of entries) {
-        const match = entry.match(/^(\d{2})-/);
+        const match = entry.match(/^(\d+)-/);
         if (match) {
           phaseNum = parseInt(match[1], 10);
         }
@@ -1781,7 +2086,7 @@ function cmdState(subArgs) {
         if (fs.existsSync(phasePlanPath)) {
           try {
             let content = fs.readFileSync(phasePlanPath, 'utf8');
-            const phaseIdStr = String(phaseNum).padStart(2, '0');
+            const phaseIdStr = String(phaseNum); // no leading zeros
 
             // Check if it has frontmatter with phase/plan fields
             const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
@@ -1789,9 +2094,9 @@ function cmdState(subArgs) {
               const fm = frontmatterMatch[1];
               if (!fm.match(/^id:/m)) {
                 // Only add id if missing; preserve existing phase/plan if present
-                let newFrontmatter = fm.trimEnd() + `\nid: "${phaseIdStr}.01"`;
+                let newFrontmatter = fm.trimEnd() + `\nid: "${phaseIdStr}.1"`;
                 if (!fm.match(/^phase:/m)) newFrontmatter += `\nphase: "${phaseIdStr}"`;
-                if (!fm.match(/^plan:/m)) newFrontmatter += `\nplan: "01"`;
+                if (!fm.match(/^plan:/m)) newFrontmatter += `\nplan: "1"`;
                 newFrontmatter += '\n';
                 content = content.replace(/^---\n([\s\S]*?)\n---\n/, `---\n${newFrontmatter}---\n`);
                 const tmp = phasePlanPath + '.tmp';
@@ -1801,8 +2106,8 @@ function cmdState(subArgs) {
               }
             } else {
               // No frontmatter found — prepend minimal frontmatter
-              const assignedId = `${phaseIdStr}.01`;
-              const minimal = `---\nid: "${assignedId}"\nphase: "${phaseIdStr}"\nplan: "01"\ntype: auto\n---\n`;
+              const assignedId = `${phaseIdStr}.1`;
+              const minimal = `---\nid: "${assignedId}"\nphase: "${phaseIdStr}"\nplan: "1"\ntype: auto\n---\n`;
               fs.writeFileSync(phasePlanPath, minimal + content);
               migratedCount++;
             }
@@ -1816,7 +2121,7 @@ function cmdState(subArgs) {
         const subentries = fs.readdirSync(phaseDir);
         let planNum = 1;
         for (const subentry of subentries) {
-          const subMatch = subentry.match(/^(\d{2})-/);
+          const subMatch = subentry.match(/^(\d+)-/);
           if (subMatch && fs.statSync(path.join(phaseDir, subentry)).isDirectory()) {
             planNum = parseInt(subMatch[1], 10);
             const planDir = path.join(phaseDir, subentry);
@@ -1825,8 +2130,8 @@ function cmdState(subArgs) {
             if (fs.existsSync(planPath)) {
               try {
                 let content = fs.readFileSync(planPath, 'utf8');
-                const phaseIdStr = String(phaseNum).padStart(2, '0');
-                const planIdStr = String(planNum).padStart(2, '0');
+                const phaseIdStr = String(phaseNum); // no leading zeros
+                const planIdStr = String(planNum);   // no leading zeros
 
                 const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
                 if (frontmatterMatch) {
@@ -1863,6 +2168,57 @@ function cmdState(subArgs) {
     return { ok: true, migrated: migratedCount, message: `Migrated ${migratedCount} PLAN.md files with IDs` };
   }
 
+  // =====================================================================
+  // state migrate-schema: normalise phases array to current schema
+  // Handles 3 known schema variants in the wild:
+  //   Schema A (v1 old) — phases[N] has {id, goal, ...} but no status
+  //   Schema B (v1 mid) — phases[N] has {number, name, status?, ...}
+  //   Schema C (v2)     — phases[N] has {number, name, status, planned_at?, ...}
+  // After migration every entry has: number, name, status (defaulting to 'complete'
+  // for entries that have a SUMMARY.md path or missing status).
+  // =====================================================================
+  if (sub === 'migrate-schema') {
+    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' };
+
+    let changed = 0;
+    state.phases = state.phases.map((p) => {
+      const updated = Object.assign({}, p);
+
+      // Normalise identifier: prefer number, fall back to id or name
+      if (!updated.number && (updated.id || updated.name)) {
+        updated.number = String(updated.id || updated.name);
+        changed++;
+      }
+
+      // Normalise name
+      if (!updated.name && updated.goal) {
+        updated.name = String(updated.goal).slice(0, 60);
+        changed++;
+      }
+
+      // Normalise status: missing → infer from completion markers
+      if (!updated.status) {
+        if (updated.completed || updated.summary_path) {
+          updated.status = 'complete';
+        } else if (updated.started) {
+          updated.status = 'executing';
+        } else {
+          updated.status = 'planned';
+        }
+        changed++;
+      }
+
+      return updated;
+    });
+
+    if (changed > 0) {
+      writeState(state);
+    }
+    return { ok: true, changed, message: `Schema migration complete — ${changed} field(s) normalised across ${state.phases.length} phase entries` };
+  }
+
   // =====================================================================
   // Execution-lifecycle phase state
   // =====================================================================
@@ -1899,6 +2255,10 @@ function cmdState(subArgs) {
       entry = { number: phaseKey, name: flags.name || phaseKey, plans: Number(flags.plans || 0) };
       state.phases.push(entry);
     }
+    // Transition guard: reject complete → executing unless --force
+    if (previousStatus === 'complete' && !flags.force) {
+      throw new Error(`Phase ${phaseKey} is already complete. Use --force to re-execute.`);
+    }
     entry.status = 'executing';
     if (flags.name) entry.name = flags.name;
     if (flags.plans !== undefined) entry.plans = Number(flags.plans);
@@ -1917,6 +2277,10 @@ function cmdState(subArgs) {
     const entry = state.phases.find((p) => String(p.number || p.id || p.name) === phaseKey);
     if (!entry) throw new Error(`Phase ${phaseKey} not found in state`);
     const previousStatus = entry.status || null;
+    // Transition guard: warn if completing from planned (skipped executing)
+    if (previousStatus === 'planned') {
+      process.stderr.write(`Warning: completing phase ${phaseKey} from 'planned' without executing.\n`);
+    }
     entry.status = 'complete';
     entry.completed = new Date().toISOString();
     writeState(state);
@@ -1961,8 +2325,8 @@ function cmdState(subArgs) {
     if (!/^999\.\d+$/.test(from)) {
       throw new Error(`Source must be 999.x parking-lot number, got: ${from}`);
     }
-    if (!/^\d{1,3}(\.\d+)?$/.test(to)) {
-      throw new Error(`Target must be NN or NN.M, got: ${to}`);
+    if (!/^\d+(\.\d+)?$/.test(to)) {
+      throw new Error(`Target must be N or N.M (any non-negative integer; high numbers like 1001 are valid for hot-track phases), got: ${to}`);
     }
     const state = readState() || defaultState();
     if (!state.phases) state.phases = [];
@@ -2021,33 +2385,75 @@ function cmdState(subArgs) {
       epics_exists: fs.existsSync(epicsPath),
     };
 
-    // Parse ROADMAP.md for phase tables.
-    // Expected row format:  | 01 | Phase Name | Goal text | ... |
-    // First cell is phase number (1-3 chars of digits or digits+letter).
+    // Parse ROADMAP.md for phases. Supports two formats (issue #455):
+    //   Format A — pipe tables:    | 01 | Phase Name | Goal text | ... |
+    //   Format B — heading style:   ## Phase 01 — Name  /  ### Phase 01: Name
+    // Milestone heading is also matched in any of: "## Milestone M1", "## Milestone v1.0 — Name",
+    // "**Milestone: v1.0 — Name**".
     if (parsed.roadmap_exists) {
       const roadmap = fs.readFileSync(roadmapPath, 'utf8');
-      parsed.milestones_found = (roadmap.match(/^##\s+Milestone\s+M\d+/gim) || []).length;
-      const rowRe = /^\|\s*(\d{1,3}(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
-      let m;
+      const milestoneMatches = [
+        ...(roadmap.match(/^##\s+Milestone\s+M\d+/gim) || []),
+        ...(roadmap.match(/^#{1,4}\s+Milestone\s*:?\s*[^\n]+$/gim) || []),
+        ...(roadmap.match(/\*\*\s*Milestone\s*:?\s*[^\n*]+\*\*/gi) || []),
+      ];
+      parsed.milestones_found = new Set(milestoneMatches.map(s => s.trim().toLowerCase())).size;
+
       if (!state.phases) state.phases = [];
-      while ((m = rowRe.exec(roadmap)) !== null) {
-        const phaseNum = m[1].trim();
-        const phaseName = m[2].trim();
-        const phaseGoal = m[3].trim();
-        // Skip header rows like "| # | Phase | Goal |"
-        if (!/^\d/.test(phaseNum)) continue;
-        if (phaseName.toLowerCase() === 'phase') continue;
+
+      // One-time normalization: drop null/garbage entries and merge duplicates
+      // by id/number across the schema-drift boundary (#482-A). Sync is the
+      // safe place to do this because we re-derive truth from disk anyway.
+      const beforeClean = state.phases.length;
+      const seenKeys = new Map();
+      const cleaned = [];
+      for (const ph of state.phases) {
+        if (!ph) continue;
+        const key = String(ph.id || ph.number || '').trim();
+        if (!key || !/^\d+(\.\d+)?$/.test(key)) continue;
+        if (seenKeys.has(key)) {
+          // Merge into the kept entry: prefer non-null values from this duplicate.
+          const keptIdx = seenKeys.get(key);
+          for (const k of Object.keys(ph)) {
+            if (cleaned[keptIdx][k] == null && ph[k] != null) cleaned[keptIdx][k] = ph[k];
+          }
+          continue;
+        }
+        seenKeys.set(key, cleaned.length);
+        cleaned.push({ id: key, number: key, ...ph, id: key, number: key });
+      }
+      parsed.phases_normalized = beforeClean - cleaned.length;
+      state.phases = cleaned;
+
+      const seenNums = new Set();
+
+      const upsertPhase = (phaseNum, phaseName, phaseGoal) => {
+        if (!/^\d/.test(phaseNum)) return;
+        if (phaseName.toLowerCase() === 'phase') return;
+        if (seenNums.has(phaseNum)) return;
+        seenNums.add(phaseNum);
         parsed.phases_found += 1;
+        // Dedup against id, number, AND name — schema drift between writers means
+        // older entries carry .id while newer carry .number. Checking only one
+        // field caused duplicate entries (e.g. issue #482-A: phases 10-13 each
+        // appeared twice after a re-sync because the .id-only entries were not
+        // matched against the .number-only writer).
         const existingIdx = state.phases.findIndex(p =>
-          String(p.number) === phaseNum || p.name === phaseName
+          String(p.number) === phaseNum ||
+          String(p.id) === phaseNum ||
+          p.name === phaseName
         );
         if (existingIdx >= 0) {
-          // Preserve existing status fields; update metadata.
+          // 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;
           state.phases[existingIdx].name = phaseName;
           if (phaseGoal) state.phases[existingIdx].goal = phaseGoal;
         } else {
+          // Write both id and number on every new entry so dedup works regardless
+          // of which schema future readers expect.
           state.phases.push({
+            id: phaseNum,
             number: phaseNum,
             name: phaseName,
             goal: phaseGoal,
@@ -2058,6 +2464,25 @@ function cmdState(subArgs) {
           });
           parsed.phases_upserted += 1;
         }
+      };
+
+      // Format A — pipe tables
+      // Phase number: \d+ (not \d{1,3}) — high numbers like 1001 are valid for
+      // hot-track parking-lot phases per parking-lot-convention.md.
+      const rowRe = /^\|\s*(\d+(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
+      let m;
+      while ((m = rowRe.exec(roadmap)) !== null) {
+        upsertPhase(m[1].trim(), m[2].trim(), m[3].trim());
+      }
+
+      // Format B — heading style
+      const headRe = /^#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*[—\-:]\s*([^\n]+)$/gm;
+      while ((m = headRe.exec(roadmap)) !== null) {
+        const num = m[1].trim();
+        const name = m[2].trim();
+        const after = roadmap.slice(headRe.lastIndex).split(/\n/).slice(0, 8).join('\n');
+        const goalMatch = after.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
+        upsertPhase(num, name, goalMatch ? goalMatch[1].trim() : '');
       }
     }
 
@@ -2085,12 +2510,12 @@ function cmdState(subArgs) {
         const body = epicBlocks[i + 1] || '';
         const numMatch = header.match(/(\d+)/);
         if (!numMatch) continue;
-        const epicNum = numMatch[1].padStart(2, '0');
+        const epicNum = String(parseInt(numMatch[1], 10)); // strip leading zeros
         const nameMatch = header.match(/[—\-:]\s*(.+?)\s*$/);
         const epicName = nameMatch ? nameMatch[1].trim() : `Epic ${epicNum}`;
 
         // Upsert epic with story-level preservation.
-        let epicEntry = state.epics.find(e => String(e.number) === epicNum);
+        let epicEntry = state.epics.find(e => String(parseInt(e.number, 10)) === epicNum);
         if (!epicEntry) {
           epicEntry = { number: epicNum, name: epicName, status: 'planned', stories: [] };
           state.epics.push(epicEntry);
@@ -2132,7 +2557,7 @@ function cmdState(subArgs) {
       for (const phaseEntry of fs.readdirSync(sprintRoot)) {
         const phaseDir = path.join(sprintRoot, phaseEntry);
         if (!fs.statSync(phaseDir).isDirectory()) continue;
-        const phaseNumMatch = phaseEntry.match(/^(\d{1,3}(?:\.\d+)?)/);
+        const phaseNumMatch = phaseEntry.match(/^(\d+(?:\.\d+)?)/);
         const phaseNum = phaseNumMatch ? phaseNumMatch[1] : phaseEntry;
         for (const file of fs.readdirSync(phaseDir)) {
           const sprintMatch = file.match(/^sprint-(\d+)\.md$/);
@@ -2169,29 +2594,822 @@ function cmdState(subArgs) {
       throw new Error(`state sync --from-disk: no ROADMAP.md, epics.md, or sprint files found`);
     }
 
+    // Issue #478 — prune state phases not present in ROADMAP.
+    // After upserting ROADMAP → state, seenNums holds every number the ROADMAP
+    // parser found. Any state entry whose id/number is NOT in seenNums is stale
+    // (e.g. from renumbering, manual edits, or partial removals). Prune them,
+    // but only when we successfully parsed at least 1 phase from ROADMAP.
+    parsed.phases_pruned = 0;
+    if (parsed.roadmap_exists && seenNums.size > 0) {
+      const before = state.phases.length;
+      state.phases = state.phases.filter(p => {
+        const key = String(p.id || p.number || '').trim();
+        return !key || seenNums.has(key);
+      });
+      parsed.phases_pruned = before - state.phases.length;
+    }
+
+    // Issue #455 — surface silent no-op when ROADMAP exists but parser found nothing.
+    const warnings = [];
+    if (parsed.roadmap_exists && parsed.phases_found === 0) {
+      warnings.push('ROADMAP.md exists but no phases parsed — check format (expected pipe-table rows or "## Phase NN — Name" headings).');
+    }
+    if (parsed.epics_exists && parsed.epics_found === 0) {
+      warnings.push('epics.md exists but no epics parsed — check "## EPIC-NN" or "## Epic N" heading format.');
+    }
+
     writeState(state);
-    return { ok: true, synced: true, ...parsed };
+    return { ok: true, synced: true, ...parsed, ...(warnings.length ? { warnings } : {}) };
   }
 
   throw new Error(`Unknown state subcommand: ${sub}.\nCommon: read, set-phase, advance-plan, add-decision, decisions-global, add-blocker, sync, promote-backlog\nRun 'rihal-tools.cjs help' for the full list of state subcommands.`);
 }
 
+/**
+ * cmdPhase — top-level phase operations.
+ *
+ * Subcommands:
+ *   add <name>   Add an integer phase to end of current milestone.
+ *                Computes next phase number from disk + ROADMAP + state.json,
+ *                creates .planning/phases/{NN}-{slug}/, inserts a Goal/Status/
+ *                Plans/Acceptance entry into ROADMAP.md before "## Backlog"
+ *                (or at end if absent), and upserts state.phases[].
+ *
+ * Closes #460. Replaces the broken `phase add` invocation referenced by
+ * .rihal/workflows/add-phase.md, which previously hit the dispatcher's
+ * "Unknown subcommand: phase" path.
+ */
+function cmdPhase(subArgs) {
+  const sub = subArgs[0];
+
+  if (sub === 'add') {
+    // Extract --decimal <parent> if present (closes #477 item C). The flag may
+    // appear before or after the phase name; we splice it out before joining.
+    const remaining = subArgs.slice(1);
+    let decimalParent = null;
+    const decimalIdx = remaining.findIndex(a => a === '--decimal');
+    if (decimalIdx !== -1) {
+      decimalParent = remaining[decimalIdx + 1];
+      if (!decimalParent || decimalParent.startsWith('--')) {
+        throw new Error('--decimal requires a parent phase number (e.g., --decimal 13)');
+      }
+      if (!/^\d+$/.test(decimalParent)) {
+        throw new Error(`--decimal parent must be a positive integer, got: ${decimalParent}`);
+      }
+      remaining.splice(decimalIdx, 2);
+    }
+
+    // #583 --number N flag: explicit phase number override, bypasses auto-computation.
+    let forcedNumber = null;
+    const numberIdx = remaining.findIndex(a => a === '--number');
+    if (numberIdx !== -1) {
+      const nVal = remaining[numberIdx + 1];
+      if (!nVal || nVal.startsWith('--') || !/^\d+$/.test(nVal)) {
+        throw new Error('--number requires a positive integer (e.g., --number 22)');
+      }
+      forcedNumber = parseInt(nVal, 10);
+      remaining.splice(numberIdx, 2);
+    }
+
+    const phaseName = remaining.join(' ').trim();
+    if (!phaseName) throw new Error('phase add requires <name>');
+
+    const slug = phaseName
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-+|-+$/g, '');
+    if (!slug) {
+      throw new Error('Phase name must contain at least one alphanumeric character');
+    }
+
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+
+    // State lives in .rihal/state.json — same path used by cmdState (line ~634)
+    // and every other state-writing subcommand. Phase 6 dogfood surfaced this:
+    // earlier drafts wrote to .planning/state.json, creating an orphan file
+    // invisible to `state sync` / `state set-phase` / etc. Closes #462.
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+    let state;
+    if (fs.existsSync(statePath)) {
+      try {
+        state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+      } catch (e) {
+        throw new Error(`Invalid JSON in state.json: ${e.message}`);
+      }
+    } else {
+      state = { phases: [], decisions: [], blockers: [] };
+    }
+    if (!state.phases) state.phases = [];
+
+    let number;
+    if (forcedNumber !== null) {
+      // --number N: explicit override. Validate it doesn't already exist.
+      number = String(forcedNumber);
+      if (state.phases.some(p => String(p.number) === number)) {
+        throw new Error(`Phase ${number} already exists in state.json (--number override)`);
+      }
+    } else if (decimalParent !== null) {
+      // Verify parent exists somewhere (state, dir, or ROADMAP) before slotting under it.
+      const parentNum = parseInt(decimalParent, 10);
+      let parentExists = state.phases.some(p => parseInt(String(p.number), 10) === parentNum);
+      if (!parentExists && fs.existsSync(phasesDir)) {
+        parentExists = fs.readdirSync(phasesDir).some(e => {
+          const m = e.match(/^(\d+)(?:[.-]|$)/);
+          return m && parseInt(m[1], 10) === parentNum;
+        });
+      }
+      if (!parentExists && fs.existsSync(roadmapPath)) {
+        const text = fs.readFileSync(roadmapPath, 'utf8');
+        const re = new RegExp(`(^|\\n)(?:##+\\s*Phase\\s+|\\|\\s*)${parentNum}\\b`);
+        parentExists = re.test(text);
+      }
+      if (!parentExists) {
+        throw new Error(`--decimal parent ${parentNum} not found (no state entry, directory, or ROADMAP row matches)`);
+      }
+
+      // Find max minor across phases dir, ROADMAP, and state for `<parent>.M`.
+      let maxMinor = 0;
+      if (fs.existsSync(phasesDir)) {
+        for (const entry of fs.readdirSync(phasesDir)) {
+          const m = entry.match(new RegExp(`^${parentNum}\\.(\\d+)`));
+          if (m) maxMinor = Math.max(maxMinor, parseInt(m[1], 10));
+        }
+      }
+      if (fs.existsSync(roadmapPath)) {
+        const text = fs.readFileSync(roadmapPath, 'utf8');
+        const pipeRe = new RegExp(`^\\|\\s*${parentNum}\\.(\\d+)\\s*\\|`, 'gm');
+        let m;
+        while ((m = pipeRe.exec(text)) !== null) {
+          maxMinor = Math.max(maxMinor, parseInt(m[1], 10));
+        }
+        const headRe = new RegExp(`^#{2,4}\\s*Phase\\s+${parentNum}\\.(\\d+)\\b`, 'gm');
+        while ((m = headRe.exec(text)) !== null) {
+          maxMinor = Math.max(maxMinor, parseInt(m[1], 10));
+        }
+      }
+      for (const p of state.phases) {
+        const m = String(p.number || '').match(new RegExp(`^${parentNum}\\.(\\d+)$`));
+        if (m) maxMinor = Math.max(maxMinor, parseInt(m[1], 10));
+      }
+      number = `${parentNum}.${maxMinor + 1}`;
+    } else {
+      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');
+        // Phase 14 / #476 — \d+ (not \d{1,3}). High numbers like 1001 are valid
+        // for hot-track phases. The cap was silently dropping them from maxNum
+        // computation, causing the next phase to collide with an existing one.
+        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));
+        }
+      }
+      for (const p of state.phases) {
+        const n = parseInt(String(p.number || ''), 10);
+        if (!Number.isNaN(n)) maxNum = Math.max(maxNum, n);
+      }
+
+      const next = maxNum + 1;
+      // No leading zeros — phases use plain integer identifiers (6, not 06).
+      // Per Hanzla feedback: leading zeros add visual clutter without disambiguation
+      // value at the scales we operate. Applies to phases, sprints, epics, stories,
+      // tasks, decisions across all artifacts (dirs, ROADMAP, state.json, banners).
+
+      // #583 sanity guard: prevent phantom phase numbers caused by stale high-number
+      // entries in ROADMAP.md or phases/ (e.g. a prior phantom "## Phase 1009" left
+      // in ROADMAP triggers the next add to produce 1010). If computed next is more
+      // than 50 above the count of currently tracked phases, the maxNum source is
+      // suspect. Abort and require an explicit --number N to override.
+      const trackedCount = state.phases.filter(p => {
+        const n = parseInt(String(p.number || ''), 10);
+        return !Number.isNaN(n) && n > 0;
+      }).length;
+      if (next > trackedCount + 50) {
+        throw new Error(
+          `Computed phase number ${next} is unexpectedly large ` +
+          `(only ${trackedCount} phases tracked in state.json). ` +
+          `ROADMAP.md or the phases/ directory may contain a stale high-number entry. ` +
+          `Inspect with: node rihal-tools.cjs phases list\n` +
+          `Then retry with an explicit number: rihal-tools.cjs phase add "${phaseName}" --number ${trackedCount + 1}`
+        );
+      }
+
+      number = String(next);
+    }
+
+    if (state.phases.some(p => String(p.number) === number)) {
+      throw new Error(`Phase ${number} already exists in state.json`);
+    }
+
+    const dirName = `${number}-${slug}`;
+    const directory = path.join(phasesDir, dirName);
+    if (fs.existsSync(directory)) {
+      throw new Error(`Phase directory already exists: ${path.relative(PROJECT_ROOT, directory)}`);
+    }
+    fs.mkdirSync(directory, { recursive: true });
+
+    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`;
+
+    if (fs.existsSync(roadmapPath)) {
+      let text = fs.readFileSync(roadmapPath, 'utf8');
+      const backlogMatch = text.match(/^##\s+Backlog\b/m);
+      if (backlogMatch) {
+        const backlogIdx = backlogMatch.index;
+        text = text.slice(0, backlogIdx) + entry + '\n' + text.slice(backlogIdx);
+      } 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,
+    });
+    state.updated = new Date().toISOString();
+    // Ensure the directory holding statePath (RIHAL_DIR) exists.
+    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,
+      phase_number: number,
+      name: phaseName,
+      slug,
+      directory: path.relative(PROJECT_ROOT, directory),
+    };
+  }
+
+  throw new Error(`Unknown phase subcommand: ${sub || '(none)'}. Valid: add`);
+}
+
+/**
+ * cmdCommit — atomic git commit with conventional-commits validation.
+ *
+ * Closes #465 (the highest-impact missing subcommand from the Phase 9
+ * dogfood audit). Used by execute-sprint, map-codebase, and
+ * new-project-roadmap workflows.
+ *
+ * Signature:
+ *   rihal-tools.cjs commit "<message>" [--files <path1> <path2> ...]
+ *
+ * Validates:
+ * - conventional-commits format (type(scope): subject)
+ * - non-empty subject
+ * - rejects AI-attribution lines (Co-Authored-By: Claude, etc.)
+ * - rejects --no-verify flag explicitly
+ *
+ * Does NOT push (per project rule: never push without explicit human approval).
+ */
+function cmdCommit(argv) {
+  // argv is the raw args array from process.argv after 'commit'.
+  // First argument = the entire commit message (preserved with quotes by the shell).
+  // Remaining args parsed as flags: --files <paths...>, --no-verify (rejected).
+  const args = Array.isArray(argv) ? argv : [];
+
+  // --no-verify is only a flag when it's a standalone arg, not when it appears
+  // inside the message body (e.g., a commit message that documents that
+  // --no-verify is rejected). Scan only args AFTER the first (= message).
+  const message = args[0] ? String(args[0]) : '';
+  const flagArgs = args.slice(1);
+  const files = [];
+
+  for (let i = 0; i < flagArgs.length; i++) {
+    const t = flagArgs[i];
+    if (t === '--no-verify') {
+      throw new Error('rihal-tools commit does not bypass hooks. Fix the underlying issue, then re-commit.');
+    }
+    if (t === '--files') {
+      // Everything remaining is a file path
+      while (++i < flagArgs.length) files.push(flagArgs[i]);
+      break;
+    }
+  }
+
+  if (!message || !message.trim()) {
+    throw new Error('commit requires a message: rihal-tools.cjs commit "type(scope): subject"');
+  }
+
+  // AI attribution rejection (project rule)
+  const aiPatterns = [
+    /co-authored-by:\s*claude/i,
+    /generated with \[?claude/i,
+    /🤖\s*generated/i,
+    /co-authored-by:\s*ai/i,
+  ];
+  for (const re of aiPatterns) {
+    if (re.test(message)) {
+      throw new Error('AI attribution forbidden in commit messages (project rule). Remove "Co-Authored-By: Claude" / "Generated with Claude Code" / etc.');
+    }
+  }
+
+  // Conventional-commits validation: type(scope): subject
+  // Types per .github/workflows/semantic.yaml: feat, fix, docs, style, refactor, test, chore, perf, revert
+  // Plus our extensions: plan, audit (used during this session)
+  const subjectLine = message.split('\n')[0];
+  const ccRe = /^(feat|fix|docs|style|refactor|test|chore|perf|revert|plan|audit)(\([^)]+\))?:\s+\S/;
+  if (!ccRe.test(subjectLine)) {
+    throw new Error(
+      `Subject must follow conventional commits: type(scope): subject. Got: "${subjectLine.slice(0, 80)}".\n` +
+      `Valid types: feat, fix, docs, style, refactor, test, chore, perf, revert, plan, audit.`
+    );
+  }
+  if (subjectLine.length > 100) {
+    throw new Error(`Subject too long (${subjectLine.length} chars > 100). Move detail to body.`);
+  }
+
+  // Stage files if --files provided; otherwise commit whatever is staged.
+  const { execSync } = require('child_process');
+  if (files.length > 0) {
+    // Validate each path exists before staging
+    for (const f of files) {
+      if (!fs.existsSync(path.join(PROJECT_ROOT, f)) && !fs.existsSync(f)) {
+        throw new Error(`File not found: ${f}`);
+      }
+    }
+    // git add may exit 0 with a warning (not error) for gitignored files on some
+    // git versions — file never gets staged but execSync doesn't throw. Capture
+    // 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' }
+      );
+    } 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')) {
+        throw new Error(
+          `Cannot stage files — one or more paths are gitignored:\n${gitAddStderr.trim()}\n\n` +
+          `Fix: remove the .gitignore entry for the planning directory, or run:\n` +
+          `  node rihal-tools.cjs gitignore status`
+        );
+      }
+      throw e; // re-throw any other git error
+    }
+
+    // #566 extra guard: verify all --files paths actually appear in the staged index.
+    // git add on a gitignored file may silently succeed (exit 0) but not stage the
+    // file, causing a later commit to include unrelated already-staged changes.
+    // Exception: a tracked file that is unchanged won't appear in the staged diff —
+    // that is OK (e.g. STATE.md listed in worktree mode but not modified). Only
+    // error for files that are both not-staged AND not tracked (gitignored case).
+    const stagedAfterAdd = execSync('git diff --cached --name-only', { cwd: PROJECT_ROOT, encoding: 'utf8' })
+      .trim().split('\n').filter(Boolean);
+    const notStaged = files.filter(f => {
+      const norm = f.replace(/^\.\//, '');
+      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' });
+        return false; // tracked and unchanged — that's fine
+      } catch {
+        return true; // not tracked — likely gitignored
+      }
+    });
+    if (notStaged.length > 0) {
+      throw new Error(
+        `The following files were not staged after git add — likely gitignored:\n` +
+        notStaged.map(f => `  ${f}`).join('\n') + '\n\n' +
+        `Refusing to commit unrelated staged changes. Fix .gitignore or use git add -f.`
+      );
+    }
+  }
+
+  // Verify there's something to commit
+  const status = execSync('git diff --cached --name-only', { cwd: PROJECT_ROOT, encoding: 'utf8' }).trim();
+  if (!status) {
+    throw new Error('Nothing staged to commit. Use --files <path> or stage with git add first.');
+  }
+
+  // Use HEREDOC-style approach: write message to temp file, commit -F
+  const tmpMsgPath = path.join(require('os').tmpdir(), `rihal-commit-msg-${Date.now()}.txt`);
+  fs.writeFileSync(tmpMsgPath, message);
+  try {
+    execSync(`git commit -F "${tmpMsgPath}"`, { cwd: PROJECT_ROOT, stdio: 'pipe' });
+  } finally {
+    try { fs.unlinkSync(tmpMsgPath); } catch {}
+  }
+
+  // Capture the new HEAD SHA for return value
+  const sha = execSync('git rev-parse HEAD', { cwd: PROJECT_ROOT, encoding: 'utf8' }).trim();
+  const filesChanged = execSync(`git show --stat --format="" ${sha}`, { cwd: PROJECT_ROOT, encoding: 'utf8' })
+    .trim().split('\n').filter(Boolean);
+
+  return {
+    ok: true,
+    sha: sha.slice(0, 7),
+    full_sha: sha,
+    subject: subjectLine,
+    files_changed: filesChanged.length > 0 ? filesChanged.length - 1 : 0,
+  };
+}
+
+/**
+ * cmdGenerateClaudeMd — Phase 11 / #467 / closes part of #465.
+ *
+ * Bootstrap a project CLAUDE.md scaffold. Used by new-project-roadmap.md.
+ * Refuses to overwrite an existing CLAUDE.md unless --force is set.
+ */
+function cmdGenerateClaudeMd(rawArgs) {
+  const args = (rawArgs || '').split(/\s+/).filter(Boolean);
+  const force = args.includes('--force');
+  const claudeMdPath = path.join(PROJECT_ROOT, 'CLAUDE.md');
+
+  if (fs.existsSync(claudeMdPath) && !force) {
+    throw new Error(`CLAUDE.md already exists at ${claudeMdPath}. Use --force to overwrite.`);
+  }
+
+  // Resolve project name from package.json or directory.
+  let projectName = path.basename(PROJECT_ROOT);
+  const pkgPath = path.join(PROJECT_ROOT, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.name) projectName = pkg.name;
+    } catch { /* keep dir name */ }
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const content = `# ${projectName} — Project Rules for AI Agents
+
+This file is loaded by Claude Code, Codex, and compatible AI coding tools at the start of every session. Rules below are NON-NEGOTIABLE.
+
+> Generated by \`rihal-tools generate-claude-md\` on ${today}. Edit freely after generation.
+
+---
+
+## Commit Rules
+
+- Follow [Conventional Commits](https://www.conventionalcommits.org/): \`type(scope): subject\`
+- Types allowed: \`feat\`, \`fix\`, \`docs\`, \`style\`, \`refactor\`, \`test\`, \`chore\`, \`perf\`, \`revert\`, \`plan\`, \`audit\`
+- Subject: lowercase first letter, imperative mood, no trailing period, ≤ 72 chars
+- **NEVER add AI attribution** to commit messages — no "Generated with Claude Code", no "Co-Authored-By: Claude"
+- **NEVER use \`--no-verify\`** to bypass hooks. If hooks fail, fix the underlying issue.
+- **ALWAYS stage specific files** with \`git add <files>\` — never blanket \`git add -A\` without reading the diff first
+
+---
+
+## Push Rules
+
+- **NEVER \`git push\`** without explicit human approval on that specific push
+- **NEVER \`git push --force\`** under any circumstances without operator typing the command themselves
+- Every push requires fresh approval — earlier session approvals do not carry forward
+
+---
+
+## File Modification Rules
+
+- **Maximum file size: ~1000 lines** — refactor before exceeding
+- **Refactor incrementally** — never rewrite from scratch
+- **Preserve existing patterns** — don't introduce new conventions without documented justification
+- **Verify imports exist** before referencing them
+- **Never theoretical suggestions** — grep/read first, plan second
+
+---
+
+## Scope Discipline
+
+- Do EXACTLY what was asked — nothing more
+- No "while I'm here" improvements
+- No speculative abstractions
+- No new files unless necessary
+
+---
+
+## Phase Workflow Rules (#475 — non-negotiable)
+
+When creating, planning, or modifying a phase, you MUST go through the rihal toolchain. Direct file writes to \`.planning/phases/\` produce planning artifacts that are invisible to \`/rihal-status\`, \`/rihal-execute\`, \`/rihal-progress\`, and \`roadmap list-phases\`.
+
+- **Creating a new phase** → run \`/rihal-add-phase\` (or \`node .rihal/bin/rihal-tools.cjs phase add "<name>"\`). Do NOT \`mkdir .planning/phases/NN-...\` directly.
+- **Writing SPRINT.md / PLAN.md** → run \`/rihal-plan <N>\`. Spawns \`rihal-planner\` + \`rihal-sprint-checker\`. Do NOT \`Write\` SPRINT.md files directly.
+- **Discussing phase scope** → run \`/rihal-discuss-phase <N>\` for medium-risk phases. Writes \`<N>-CONTEXT.md\` with locked decisions.
+- **Use canonical artifact names**: \`<N>-CONTEXT.md\`, \`<N>-RESEARCH.md\`, \`<N>-PLAN.md\` or \`<N>-NN-SPRINT.md\`, \`<N>-VERIFICATION.md\`, \`<N>-SUMMARY.md\`. Do NOT invent \`SCOPE.md\` / \`REVIEW.md\` / \`EDGE-CASES.md\` as phase artifacts — those belong elsewhere or as agent outputs.
+- **Phase numbering** — sequential integers (\`/rihal-add-phase\`) for new phases; decimal sub-phases (\`100.1\`, \`100.2\` via \`/rihal-insert-phase\`) for hot-fixes branched from a parent. **Do NOT use 1000+ as a hot-track convention** — see [\`docs/phase-numbering.md\`](docs/phase-numbering.md) for the four supported options and when to use each.
+
+**Why this is enforced**: every direct \`Write\` to \`.planning/phases/**/SPRINT.md\` without registration is a silent state divergence. Future \`/rihal-status\` reports under-count work. \`/rihal-execute\` can't find the plan. \`/rihal-progress\` shows wrong percentages.
+
+If you have a real reason to bypass (e.g. retroactively documenting a phase that already shipped), put \`<!-- rihal-bypass: <one-line reason> -->\` at the top of the file so it's auditable later. The PreToolUse hook will allow the write through.
+
+---
+
+## Communication
+
+- Report progress honestly — do not claim work is done if it isn't
+- Flag blockers immediately
+- When unsure, ask — do not guess on destructive operations
+
+---
+
+**This file is part of the project. Treat it as load-bearing.**
+`;
+
+  fs.writeFileSync(claudeMdPath, content);
+  return {
+    ok: true,
+    path: path.relative(PROJECT_ROOT, claudeMdPath),
+    project_name: projectName,
+    overwritten: force && fs.existsSync(claudeMdPath),
+  };
+}
+
+/**
+ * cmdCheckImplementationReadiness — Phase 11 / #467.
+ *
+ * Returns { ready, blockers } indicating whether a phase is ready to execute.
+ * Used by check-implementation-readiness.md workflow.
+ */
+function cmdCheckImplementationReadiness(rawArgs) {
+  const args = (rawArgs || '').split(/\s+/).filter(Boolean);
+  let phaseNum = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--phase') {
+      phaseNum = args[i + 1];
+      break;
+    }
+  }
+
+  const blockers = [];
+
+  // Check 1 — .planning/ exists
+  if (!fs.existsSync(PLANNING_DIR)) {
+    blockers.push({ severity: 'major', issue: '.planning/ directory missing — run /rihal-new-project first' });
+  }
+
+  // Check 2 — ROADMAP exists
+  const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
+  if (!fs.existsSync(roadmapPath)) {
+    blockers.push({ severity: 'major', issue: '.planning/ROADMAP.md missing — phase planning requires a roadmap' });
+  }
+
+  // Check 3 — phase exists in ROADMAP if phaseNum given
+  if (phaseNum && fs.existsSync(roadmapPath)) {
+    try {
+      const roadmap = require(path.join(__dirname, 'lib', 'roadmap.cjs'));
+      const r = roadmap.dispatch(PROJECT_ROOT, ['get-phase', String(phaseNum)]);
+      if (!r || !r.found) {
+        blockers.push({ severity: 'major', issue: `phase ${phaseNum} not found in ROADMAP.md` });
+      }
+    } catch (e) {
+      blockers.push({ severity: 'minor', issue: `roadmap parser threw: ${e.message}` });
+    }
+  }
+
+  // Check 4 — no blocking anti-patterns flagged
+  if (phaseNum) {
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    if (fs.existsSync(phasesDir)) {
+      for (const entry of fs.readdirSync(phasesDir)) {
+        if (entry === String(phaseNum) || entry.startsWith(`${phaseNum}-`)) {
+          const continueHere = path.join(phasesDir, entry, '.continue-here.md');
+          if (fs.existsSync(continueHere)) {
+            const content = fs.readFileSync(continueHere, 'utf8');
+            if (/severity:\s*blocking/i.test(content)) {
+              blockers.push({ severity: 'major', issue: `phase ${phaseNum} has unresolved blocking anti-pattern in .continue-here.md` });
+            }
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    ready: blockers.filter(b => b.severity === 'major').length === 0,
+    phase: phaseNum,
+    blockers,
+  };
+}
+
+/**
+ * cmdCommitToSubrepo — Phase 11 / #467.
+ *
+ * Atomic commit within a git subrepo. Reuses cmdCommit's validation but
+ * runs git within the subrepo's directory.
+ */
+function cmdCommitToSubrepo(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  let subrepo = null;
+  const passthrough = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--subrepo') {
+      subrepo = args[i + 1];
+      i++;
+      continue;
+    }
+    passthrough.push(args[i]);
+  }
+
+  if (!subrepo) {
+    throw new Error('commit-to-subrepo requires --subrepo <path>');
+  }
+
+  const subrepoPath = path.isAbsolute(subrepo) ? subrepo : path.join(PROJECT_ROOT, subrepo);
+  if (!fs.existsSync(subrepoPath)) {
+    throw new Error(`Subrepo not found: ${subrepo}`);
+  }
+  if (!fs.existsSync(path.join(subrepoPath, '.git'))) {
+    throw new Error(`Not a git repository: ${subrepo} (no .git directory)`);
+  }
+
+  // Reuse cmdCommit validation by overriding PROJECT_ROOT temporarily via env.
+  // Cleaner approach: run git commands directly with cwd: subrepoPath.
+  const message = passthrough[0];
+  if (!message || !message.trim()) {
+    throw new Error('commit-to-subrepo requires a message: rihal-tools.cjs commit-to-subrepo --subrepo <path> "<message>"');
+  }
+
+  // AI attribution + conventional-commits validation (same rules as cmdCommit).
+  const aiPatterns = [/co-authored-by:\s*claude/i, /generated with \[?claude/i, /🤖\s*generated/i, /co-authored-by:\s*ai/i];
+  for (const re of aiPatterns) {
+    if (re.test(message)) {
+      throw new Error('AI attribution forbidden in commit messages (project rule).');
+    }
+  }
+  const subjectLine = message.split('\n')[0];
+  const ccRe = /^(feat|fix|docs|style|refactor|test|chore|perf|revert|plan|audit)(\([^)]+\))?:\s+\S/;
+  if (!ccRe.test(subjectLine)) {
+    throw new Error(`Subject must follow conventional commits: type(scope): subject. Got: "${subjectLine.slice(0, 80)}".`);
+  }
+  if (subjectLine.length > 100) {
+    throw new Error(`Subject too long (${subjectLine.length} chars > 100).`);
+  }
+
+  // Check for --no-verify in remaining args (after message at index 0).
+  for (let i = 1; i < passthrough.length; i++) {
+    if (passthrough[i] === '--no-verify') {
+      throw new Error('rihal-tools commit-to-subrepo does not bypass hooks.');
+    }
+  }
+
+  const { execSync } = require('child_process');
+  const status = execSync('git diff --cached --name-only', { cwd: subrepoPath, encoding: 'utf8' }).trim();
+  if (!status) {
+    throw new Error(`Nothing staged in subrepo ${subrepo}. Stage files inside the subrepo with git add first.`);
+  }
+
+  const tmpMsgPath = path.join(require('os').tmpdir(), `rihal-subrepo-msg-${Date.now()}.txt`);
+  fs.writeFileSync(tmpMsgPath, message);
+  try {
+    execSync(`git commit -F "${tmpMsgPath}"`, { cwd: subrepoPath, stdio: 'pipe' });
+  } finally {
+    try { fs.unlinkSync(tmpMsgPath); } catch {}
+  }
+
+  const sha = execSync('git rev-parse HEAD', { cwd: subrepoPath, encoding: 'utf8' }).trim();
+  return {
+    ok: true,
+    subrepo,
+    sha: sha.slice(0, 7),
+    full_sha: sha,
+    subject: subjectLine,
+  };
+}
+
+/**
+ * cmdContextRefresh — Phase 11 / #467.
+ *
+ * Refresh the in-project context cache from .rihal/sources.yaml.
+ * Used by init.md. No-op gracefully when no sources configured.
+ */
+function cmdContextRefresh() {
+  const sourcesPath = path.join(RIHAL_DIR, 'sources.yaml');
+  const contextDir = path.join(RIHAL_DIR, 'context');
+
+  if (!fs.existsSync(sourcesPath)) {
+    return {
+      ok: true,
+      refreshed: false,
+      message: '.rihal/sources.yaml not found — no context to refresh. Configure sources in .rihal/sources.yaml first.',
+    };
+  }
+
+  // Ensure context dir exists
+  if (!fs.existsSync(contextDir)) {
+    fs.mkdirSync(contextDir, { recursive: true });
+  }
+
+  // Touch a refresh marker so consumers can detect last refresh time.
+  const markerPath = path.join(contextDir, '.last-refresh');
+  fs.writeFileSync(markerPath, new Date().toISOString() + '\n');
+
+  return {
+    ok: true,
+    refreshed: true,
+    sources_path: path.relative(PROJECT_ROOT, sourcesPath),
+    context_dir: path.relative(PROJECT_ROOT, contextDir),
+    last_refresh_iso: new Date().toISOString(),
+  };
+}
+
+/**
+ * cmdClassifyTech — Phase 11 / #467.
+ *
+ * Classify tech stack from keywords. Used by ui-phase.md to pick the
+ * design contract template.
+ */
+function cmdClassifyTech(rawArgs) {
+  const args = (rawArgs || '').match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+  let keywords = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--keywords') {
+      keywords = (args[i + 1] || '').replace(/^["']|["']$/g, '');
+      break;
+    }
+  }
+  if (!keywords) {
+    throw new Error('classify-tech requires --keywords "<keywords>"');
+  }
+
+  const text = keywords.toLowerCase();
+  const stacks = [
+    { stack: 'next.js', category: 'frontend', patterns: [/\bnext\.?js\b/, /\bapp router\b/, /\bnextjs\b/] },
+    { stack: 'react', category: 'frontend', patterns: [/\breact\b/, /\bjsx\b/, /\btsx\b/] },
+    { stack: 'vue', category: 'frontend', patterns: [/\bvue\.?js\b/, /\bnuxt\b/, /\bcomposition api\b/] },
+    { stack: 'svelte', category: 'frontend', patterns: [/\bsvelte\b/, /\bsvelte ?kit\b/] },
+    { stack: 'angular', category: 'frontend', patterns: [/\bangular\b/] },
+    { stack: 'astro', category: 'frontend', patterns: [/\bastro\b/] },
+    { stack: 'remix', category: 'frontend', patterns: [/\bremix\b/] },
+    { stack: 'fastapi', category: 'backend', patterns: [/\bfastapi\b/, /\bpydantic\b/] },
+    { stack: 'express', category: 'backend', patterns: [/\bexpress\b/] },
+    { stack: 'nestjs', category: 'backend', patterns: [/\bnestjs\b/, /\bnest\.?js\b/] },
+    { stack: 'django', category: 'backend', patterns: [/\bdjango\b/] },
+    { stack: 'rails', category: 'backend', patterns: [/\brails\b/, /\bruby on rails\b/] },
+    { stack: 'spring', category: 'backend', patterns: [/\bspring\b/, /\bspring boot\b/] },
+    { stack: 'flutter', category: 'mobile', patterns: [/\bflutter\b/, /\bdart\b/] },
+    { stack: 'react-native', category: 'mobile', patterns: [/\breact native\b/, /\brn\b/] },
+    { stack: 'tailwind', category: 'styling', patterns: [/\btailwind\b/] },
+    { stack: 'shadcn', category: 'styling', patterns: [/\bshadcn\b/, /\bradix\b/] },
+  ];
+
+  let best = { stack: 'unknown', category: 'unknown', confidence: 0, matches: [] };
+  for (const s of stacks) {
+    const hits = s.patterns.filter(p => p.test(text));
+    if (hits.length === 0) continue;
+    const conf = Math.min(1, hits.length / s.patterns.length + 0.3);
+    if (conf > best.confidence) {
+      best = { stack: s.stack, category: s.category, confidence: Number(conf.toFixed(2)), matches: hits.map(h => h.toString()) };
+    }
+  }
+
+  return { ok: true, ...best };
+}
+
 /**
  * Classify the scope of input based on keywords and length.
- * Returns one of: 'ticket', 'feature', 'phase', 'initiative'
+ * Returns one of: 'ticket', 'feature', 'phase', 'initiative', 'drift'
  *
  * Priority order:
- * 1. Initiative keywords (highest)
- * 2. Phase keywords
- * 3. Feature keywords (add, implement, build)
- * 4. Ticket keywords
- * 5. Length-based fallback
+ * 1. Drift / audit / re-audit / extend-existing-artifact intent (Phase 6)
+ * 2. Initiative keywords
+ * 3. Phase keywords
+ * 4. Feature keywords (add, implement, build)
+ * 5. Ticket keywords
+ * 6. Length-based fallback
  */
 function classifyScope(input) {
   const text = (input || '').toLowerCase();
   const len = text.length;
 
-  // Initiative signals — highest priority
+  // Drift / audit / re-audit / extend-existing-artifact intent.
+  // Routes /rihal-do to /rihal-feature-drift instead of falling through to
+  // inline execution (closes the residual edge case from #458).
+  if (/\b(drift|re-?audit|stale|out[- ]of[- ]date|fill out (the|this|existing)|extend (audit|plan|phase)|verify (docs|claims) vs (code|reality))\b/i.test(text)) {
+    return 'drift';
+  }
+
+  // Initiative signals — highest priority among scope tiers
   if (/\b(milestone|initiative|roadmap|multi-team|multi-sprint|q[1-4]\s*\d{4})\b/.test(text)) {
     return 'initiative';
   }
@@ -2355,6 +3573,351 @@ function cmdPlanList() {
   };
 }
 
+/** phase-plan-index — JSON inventory of plans (SPRINT.md) under a phase, with wave grouping and summary detection. */
+function cmdPhasePlanIndex(rawArgs) {
+  const phaseArg = String(rawArgs || '').trim();
+  if (!phaseArg) {
+    console.error('Usage: phase-plan-index <phase-number>');
+    process.exit(1);
+  }
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  if (!fs.existsSync(phasesDir)) return { phase: phaseArg, plans: [], waves: {}, incomplete: 0, has_checkpoints: false };
+  const norm = phaseArg.replace(/^0+/, '') || '0';
+  const dirs = fs.readdirSync(phasesDir).filter((d) => {
+    const m = d.match(/^(\d+)(?:[-.])/);
+    if (!m) return false;
+    const n = m[1].replace(/^0+/, '') || '0';
+    return n === norm;
+  });
+  if (dirs.length === 0) return { phase: phaseArg, plans: [], waves: {}, incomplete: 0, has_checkpoints: false, phase_dir: null };
+  const phaseDir = path.join(phasesDir, dirs[0]);
+  const all = fs.readdirSync(phaseDir);
+  const sprintFiles = all.filter((f) => /-SPRINT\.md$/i.test(f)).sort();
+  const summarySet = new Set(all.filter((f) => /-SUMMARY\.md$/i.test(f)).map((f) => f.replace(/-SUMMARY\.md$/i, '')));
+  let hasCheckpoints = false;
+  const plans = sprintFiles.map((file) => {
+    const stem = file.replace(/-SPRINT\.md$/i, '');
+    const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
+    const { frontmatter, body } = parseFrontmatter(text);
+    const id = frontmatter.sprint || frontmatter.plan || stem;
+    const wave = parseInt(frontmatter.wave || '1', 10) || 1;
+    const autonomous = String(frontmatter.autonomous || '').toLowerCase() === 'true';
+    const gapClosure = String(frontmatter.gap_closure || frontmatter.type || '').toLowerCase() === 'gap_closure';
+    const objMatch = body.match(/^##\s+(?:Objective|Goal)\s*\n+([^\n]+)/mi);
+    const objective = objMatch ? objMatch[1].trim() : (frontmatter.goal || '').replace(/^["']|["']$/g, '');
+    const taskCount = (body.match(/^[-*]\s+\[[ xX]\]/gm) || []).length;
+    const filesModified = (body.match(/^\s*-\s*path:\s*["']?([^"'\n]+)/gm) || []).length;
+    const hasSummary = summarySet.has(stem);
+    if (/checkpoint/i.test(body)) hasCheckpoints = true;
+    return { id, wave, autonomous, gap_closure: gapClosure, objective, task_count: taskCount, files_modified: filesModified, has_summary: hasSummary, file: path.relative(PROJECT_ROOT, path.join(phaseDir, file)) };
+  });
+  const waves = {};
+  for (const p of plans) {
+    const k = String(p.wave);
+    if (!waves[k]) waves[k] = [];
+    waves[k].push(p.id);
+  }
+  const incomplete = plans.filter((p) => !p.has_summary).length;
+  return {
+    phase: phaseArg,
+    phase_dir: path.relative(PROJECT_ROOT, phaseDir),
+    plans,
+    waves,
+    incomplete,
+    has_checkpoints: hasCheckpoints,
+  };
+}
+
+/** phases list — directory inventory under .planning/phases with optional --type filter and --pick path. */
+function cmdPhasesList(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  let type = 'all';
+  let pick = null;
+  let raw = false;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--type') type = argv[++i];
+    else if (argv[i] === '--pick') pick = argv[++i];
+    else if (argv[i] === '--raw') raw = true;
+  }
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  const directories = fs.existsSync(phasesDir)
+    ? fs.readdirSync(phasesDir)
+        .filter((d) => fs.statSync(path.join(phasesDir, d)).isDirectory() && /^\d/.test(d))
+        .sort((a, b) => {
+          const na = parseFloat(a.match(/^(\d+(?:\.\d+)?)/)?.[1] || '0');
+          const nb = parseFloat(b.match(/^(\d+(?:\.\d+)?)/)?.[1] || '0');
+          return na - nb;
+        })
+    : [];
+  const summaries = [];
+  const sprints = [];
+  for (const d of directories) {
+    const dirPath = path.join(phasesDir, d);
+    for (const f of fs.readdirSync(dirPath)) {
+      const rel = path.relative(PROJECT_ROOT, path.join(dirPath, f));
+      if (/-SUMMARY\.md$/i.test(f) || /^SUMMARY\.md$/i.test(f)) summaries.push(rel);
+      if (/-SPRINT\.md$/i.test(f)) sprints.push(rel);
+    }
+  }
+  const result = { directories, summaries, sprints };
+  if (pick) {
+    const m = pick.match(/^([a-z_]+)\[(-?\d+)\]$/i);
+    if (m) {
+      const arr = result[m[1]] || [];
+      const idx = parseInt(m[2], 10);
+      const val = arr[idx < 0 ? arr.length + idx : idx];
+      console.log(val == null ? '' : val);
+      return;
+    }
+    const v = result[pick];
+    if (Array.isArray(v)) console.log(v.join('\n'));
+    else if (v != null) console.log(v);
+    return;
+  }
+  if (type === 'summaries') return { summaries };
+  if (type === 'sprints') return { sprints };
+  if (type === 'directories') return { directories };
+  return result;
+}
+
+/** find-phase — resolve a phase number (with or without leading zero) to its directory and metadata. */
+function cmdFindPhase(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  const target = argv.find((a) => !a.startsWith('--'));
+  if (!target) {
+    console.error('Usage: find-phase <N> [--raw]');
+    process.exit(1);
+  }
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  if (!fs.existsSync(phasesDir)) return { number: target, exists: false, dir: null, slug: null, decimal_children: [] };
+  const norm = target.replace(/^0+/, '') || '0';
+  const all = fs.readdirSync(phasesDir).filter((d) => fs.statSync(path.join(phasesDir, d)).isDirectory());
+  const exact = all.find((d) => {
+    const m = d.match(/^(\d+(?:\.\d+)?)(?:[-.])/) || d.match(/^(\d+(?:\.\d+)?)$/);
+    if (!m) return false;
+    return (m[1].replace(/^0+/, '') || '0') === norm;
+  });
+  const decimal_children = all
+    .filter((d) => {
+      const m = d.match(/^(\d+)\.(\d+)[-.]/);
+      return m && (m[1].replace(/^0+/, '') || '0') === norm;
+    })
+    .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+)?[-](.+)$/);
+  return {
+    number: target,
+    exists: true,
+    dir: path.relative(PROJECT_ROOT, path.join(phasesDir, exact)),
+    slug: slugMatch ? slugMatch[1] : '',
+    decimal_children,
+  };
+}
+
+/** audit-uat — walk all UAT files under .planning/phases/ and return inventory + status counts. */
+function cmdAuditUat(args) {
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  const counts = { pending: 0, passed: 0, failed: 0, skipped: 0, blocked: 0, human_uat: 0, resolved: 0 };
+  const files = [];
+  if (fs.existsSync(phasesDir)) {
+    for (const d of fs.readdirSync(phasesDir)) {
+      const dp = path.join(phasesDir, d);
+      if (!fs.statSync(dp).isDirectory()) continue;
+      for (const f of fs.readdirSync(dp)) {
+        if (!/UAT.*\.md$|VERIFICATION\.md$/i.test(f)) continue;
+        const fp = path.join(dp, f);
+        const text = fs.readFileSync(fp, 'utf8');
+        const fileCounts = { pending: 0, passed: 0, failed: 0, skipped: 0, blocked: 0, human_uat: 0, resolved: 0 };
+        const items = [];
+        const statusRe = /^[\s-]*status:\s*([a-z_]+)/gim;
+        let m;
+        while ((m = statusRe.exec(text)) !== null) {
+          const s = m[1].toLowerCase();
+          if (s in fileCounts) fileCounts[s]++;
+          if (s in counts) counts[s]++;
+          items.push({ status: s });
+        }
+        const checkRe = /^[-*]\s+\[([ xX!?])\]\s+(.+)$/gm;
+        while ((m = checkRe.exec(text)) !== null) {
+          const mark = m[1];
+          if (mark === ' ') { fileCounts.pending++; counts.pending++; items.push({ status: 'pending', text: m[2].trim() }); }
+          else if (mark === 'x' || mark === 'X') { fileCounts.passed++; counts.passed++; items.push({ status: 'passed', text: m[2].trim() }); }
+          else if (mark === '!') { fileCounts.blocked++; counts.blocked++; items.push({ status: 'blocked', text: m[2].trim() }); }
+          else if (mark === '?') { fileCounts.human_uat++; counts.human_uat++; items.push({ status: 'human_uat', text: m[2].trim() }); }
+        }
+        files.push({ path: path.relative(PROJECT_ROOT, fp), status_counts: fileCounts, items });
+      }
+    }
+  }
+  const total_items = Object.values(counts).reduce((a, b) => a + b, 0);
+  return {
+    summary: {
+      total_files: files.length,
+      total_items,
+      phase_count: new Set(files.map((f) => f.path.match(/phases\/([^/]+)/)?.[1])).size,
+      ...counts,
+    },
+    results: files,
+  };
+}
+
+/** uat render-checkpoint — render a markdown checkpoint block from a UAT file. */
+function cmdUatRenderCheckpoint(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  let file = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--file') file = argv[++i];
+  }
+  if (!file || !fs.existsSync(file)) {
+    console.error('Usage: uat render-checkpoint --file <path>');
+    process.exit(1);
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  const { frontmatter } = parseFrontmatter(text);
+  const phase = frontmatter.phase || '';
+  const lines = [];
+  lines.push(`## UAT Checkpoint — Phase ${phase}`);
+  lines.push('');
+  const pendingRe = /^[-*]\s+\[ \]\s+(.+)$/gm;
+  const pending = [];
+  let m;
+  while ((m = pendingRe.exec(text)) !== null) pending.push(m[1].trim());
+  if (pending.length === 0) {
+    lines.push('No pending UAT items. ✅');
+  } else {
+    lines.push(`**${pending.length} pending item(s):**`);
+    lines.push('');
+    pending.slice(0, 20).forEach((p, i) => lines.push(`${i + 1}. ${p}`));
+    if (pending.length > 20) lines.push(`...and ${pending.length - 20} more`);
+  }
+  lines.push('');
+  lines.push('Reply: `pass`, `fail <reason>`, `skip`, or `block <reason>`.');
+  return { __raw: lines.join('\n') };
+}
+
+/** requirements mark-complete — flip status to complete for given requirement IDs in REQUIREMENTS.md. */
+function cmdRequirementsMarkComplete(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  const ids = argv.filter((a) => !a.startsWith('--'));
+  if (ids.length === 0) return { updated: [], not_found: [] };
+  const reqPath = path.join(PLANNING_DIR, 'REQUIREMENTS.md');
+  if (!fs.existsSync(reqPath)) return { updated: [], not_found: ids, reason: 'REQUIREMENTS.md not found' };
+  let text = fs.readFileSync(reqPath, 'utf8');
+  const updated = [];
+  const notFound = [];
+  for (const id of ids) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(\\| *${escaped} *\\|[^\\n]*?\\| *)([^|\\n]+)( *\\|)`, 'g');
+    let matched = false;
+    text = text.replace(re, (full, pre, status, post) => {
+      matched = true;
+      return `${pre}complete${post}`;
+    });
+    if (matched) updated.push(id); else notFound.push(id);
+  }
+  if (updated.length > 0) fs.writeFileSync(reqPath, text);
+  return { updated, not_found: notFound };
+}
+
+/** todo match-phase — return todos whose phase tag matches N. */
+function cmdTodoMatchPhase(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  const phase = argv.find((a) => !a.startsWith('--'));
+  if (!phase) {
+    console.error('Usage: todo match-phase <N>');
+    process.exit(1);
+  }
+  const todoDirs = [
+    path.join(PLANNING_DIR, 'notes', 'todos'),
+    path.join(PLANNING_DIR, 'todos'),
+    path.join(PLANNING_DIR, 'notes'),
+  ];
+  const matches = [];
+  for (const dir of todoDirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      const fp = path.join(dir, f);
+      const text = fs.readFileSync(fp, 'utf8');
+      const { frontmatter, body } = parseFrontmatter(text);
+      const tagMatch = frontmatter.phase === phase
+        || (frontmatter.tags || '').split(',').map((t) => t.trim()).includes(`phase-${phase}`)
+        || new RegExp(`\\bphase[\\s-]?${phase}\\b`, 'i').test(body);
+      if (!tagMatch) continue;
+      const titleMatch = body.match(/^#\s+(.+)$/m);
+      matches.push({
+        file: path.relative(PROJECT_ROOT, fp),
+        title: titleMatch ? titleMatch[1].trim() : f.replace(/\.md$/, ''),
+        area: frontmatter.area || frontmatter.tags || '',
+        score: 1.0,
+        reasons: [`phase tag matched ${phase}`],
+      });
+    }
+  }
+  return { phase, todo_count: matches.length, matches };
+}
+
+/** learnings copy — soft-fail copy of a phase's LEARNINGS.md to the global store. */
+function cmdLearningsCopy(args) {
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  if (!fs.existsSync(phasesDir)) return { copied: 0, reason: 'no phases dir' };
+  const dirs = fs.readdirSync(phasesDir).filter((d) => fs.statSync(path.join(phasesDir, d)).isDirectory());
+  const learnings = dirs
+    .map((d) => path.join(phasesDir, d, 'LEARNINGS.md'))
+    .filter((p) => fs.existsSync(p));
+  if (learnings.length === 0) return { copied: 0, reason: 'no LEARNINGS.md found in any phase' };
+  const globalDir = path.join(process.env.HOME || '', '.rihal', 'learnings');
+  if (!fs.existsSync(globalDir)) fs.mkdirSync(globalDir, { recursive: true });
+  const project = path.basename(PROJECT_ROOT);
+  let copied = 0;
+  for (const src of learnings) {
+    const phase = src.match(/phases\/([^/]+)\//)?.[1] || 'unknown';
+    const dest = path.join(globalDir, `${project}__${phase}.md`);
+    fs.copyFileSync(src, dest);
+    copied++;
+  }
+  return { copied, project, store: globalDir };
+}
+
+/** frontmatter get — extract a single field from a markdown file's YAML frontmatter. */
+function cmdFrontmatterGet(args) {
+  const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
+  let file = null;
+  let field = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--field') field = argv[++i];
+    else if (!argv[i].startsWith('--') && !file) file = argv[i];
+  }
+  if (!file || !field) {
+    console.error('Usage: frontmatter get <file> --field <name>');
+    process.exit(1);
+  }
+  if (!fs.existsSync(file)) {
+    console.error(`File not found: ${file}`);
+    process.exit(1);
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  const { frontmatter } = parseFrontmatter(text);
+  const val = frontmatter[field];
+  if (val === undefined) { console.log(''); return; }
+  console.log(val);
+  return;
+}
+
+/** docs-audit — placeholder inventory of documentation gaps; non-fatal. */
+function cmdDocsAudit(args) {
+  const reqPath = path.join(PLANNING_DIR, 'documentation-requirements.csv');
+  if (!fs.existsSync(reqPath)) {
+    return { has_requirements: false, gaps: [], reason: 'no documentation-requirements.csv — nothing to audit' };
+  }
+  const text = fs.readFileSync(reqPath, 'utf8');
+  const rows = text.split('\n').slice(1).filter((l) => l.trim()).map((l) => l.split(','));
+  const gaps = rows
+    .filter((cols) => cols[1] && !fs.existsSync(path.join(PROJECT_ROOT, cols[1].trim())))
+    .map((cols) => ({ doc: cols[0]?.trim(), expected_path: cols[1]?.trim() }));
+  return { has_requirements: true, total: rows.length, gaps };
+}
+
 /** init chain — context blob for /rihal-chain workflow. */
 function cmdInitChain(rawArgs) {
   const config = readConfig();
@@ -2535,15 +4098,15 @@ function cmdResolveModel(agentId) {
     throw new Error(`Unknown agent: ${agentId}. Valid agents: ${installedAgents.join(', ')}`);
   }
 
-  // Model assignments per profile
+  // Model assignments per profile (Claude 4 family: opus-4-7, sonnet-4-6, haiku-4-5)
   const QUALITY_AGENTS = {
-    'rihal-sadiq': 'claude-3-5-opus-20241022',
-    'rihal-waleed': 'claude-3-5-opus-20241022',
-    'rihal-planner': 'claude-3-5-opus-20241022',
-    'rihal-sprint-checker': 'claude-3-5-opus-20241022',
-    'rihal-fatima': 'claude-3-5-sonnet-20241022',
-    'rihal-executor': 'claude-3-5-sonnet-20241022',
-    'rihal-verifier': 'claude-3-5-sonnet-20241022',
+    'rihal-sadiq': 'claude-opus-4-7',
+    'rihal-waleed': 'claude-opus-4-7',
+    'rihal-planner': 'claude-opus-4-7',
+    'rihal-sprint-checker': 'claude-opus-4-7',
+    'rihal-fatima': 'claude-sonnet-4-6',
+    'rihal-executor': 'claude-sonnet-4-6',
+    'rihal-verifier': 'claude-sonnet-4-6',
   };
 
   if (profile === 'inherit') {
@@ -2551,20 +4114,20 @@ function cmdResolveModel(agentId) {
   }
 
   if (profile === 'budget') {
-    return { model: 'claude-3-5-haiku-20241022', profile: 'budget', agent: agentId };
+    return { model: 'claude-haiku-4-5-20251001', profile: 'budget', agent: agentId };
   }
 
   if (profile === 'balanced') {
-    return { model: 'claude-3-5-sonnet-20241022', profile: 'balanced', agent: agentId };
+    return { model: 'claude-sonnet-4-6', profile: 'balanced', agent: agentId };
   }
 
   if (profile === 'quality') {
-    const model = QUALITY_AGENTS[agentId] || 'claude-3-5-haiku-20241022';
+    const model = QUALITY_AGENTS[agentId] || 'claude-sonnet-4-6';
     return { model, profile: 'quality', agent: agentId };
   }
 
   // Unknown profile, default to balanced
-  return { model: 'claude-3-5-sonnet-20241022', profile: 'balanced', agent: agentId, warning: `Unknown profile '${profile}'; using balanced` };
+  return { model: 'claude-sonnet-4-6', profile: 'balanced', agent: agentId, warning: `Unknown profile '${profile}'; using balanced` };
 }
 
 /**
@@ -3027,6 +4590,11 @@ function cmdBrain(args) {
 function cmdProgress(args) {
   const sub = args[0] || 'init';
   const rawMode = args.includes('--raw');
+  // #200 — opt-in strict mode: exit 1 when insights contain drift/undercount.
+  // Off by default (warning preserves the soft-surface UX). Toggle via --strict
+  // flag or RIHAL_STRICT_STATE=true env var. Used by CI / pre-deploy gates.
+  const strictMode = args.includes('--strict')
+    || /^(true|1|yes)$/i.test(process.env.RIHAL_STRICT_STATE || '');
 
   // Resolve paths — workflow files may run this from any subdirectory.
   const statePath = path.join(RIHAL_DIR, 'state.json');
@@ -3046,7 +4614,8 @@ function cmdProgress(args) {
     const seen = new Set();
 
     // Format A — markdown pipe tables: | 07 | Name | Goal |
-    const rowRe = /^\|\s*(\d{1,3}(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
+    // Phase 14 / #476 — \d+ supports high-N phases (1000+, hot-track).
+    const rowRe = /^\|\s*(\d+(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
     let m;
     while ((m = rowRe.exec(text)) !== null) {
       const num = m[1].trim();
@@ -3060,7 +4629,8 @@ function cmdProgress(args) {
     }
 
     // Format B — heading style: ## Phase 07 — Name  /  ### Phase 07: Name  /  ## Phase 07 - Name
-    const headRe = /^#{2,4}\s*Phase\s+(\d{1,3}(?:\.\d+)?)\s*[—\-:]\s*([^\n]+)$/gm;
+    // Phase 14 / #476 — \d+ supports high-N phases (1000+, hot-track).
+    const headRe = /^#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*[—\-:]\s*([^\n]+)$/gm;
     while ((m = headRe.exec(text)) !== null) {
       const num = m[1].trim();
       const name = m[2].trim();
@@ -3110,7 +4680,8 @@ function cmdProgress(args) {
     for (const entry of fs.readdirSync(phasesDir)) {
       const full = path.join(phasesDir, entry);
       if (!fs.statSync(full).isDirectory()) continue;
-      const numMatch = entry.match(/^(\d{1,3}(?:\.\d+)?)/);
+      // Phase 14 / #476 — \d+ supports high-N phase dirs (1000+).
+      const numMatch = entry.match(/^(\d+(?:\.\d+)?)/);
       if (!numMatch) continue;
       const num = numMatch[1];
       const files = fs.readdirSync(full);
@@ -3127,6 +4698,21 @@ function cmdProgress(args) {
     return byNum;
   }
 
+  // #200 — opt-in strict gate. Walks insights for drift/undercount kinds and
+  // exits 1 with the failure list to stderr. No-op when strictMode=false.
+  function enforceStrictGate(insightsList) {
+    if (!strictMode) return;
+    const blocking = (insightsList || []).filter(i =>
+      i && (i.kind === 'drift' || i.kind === 'undercount') && i.severity !== 'info'
+    );
+    if (blocking.length === 0) return;
+    process.stderr.write('✖ State drift detected — state.json is out of sync with disk.\n');
+    for (const i of blocking) process.stderr.write(`  • ${i.message}\n`);
+    process.stderr.write('\n  Auto-fix:  node .rihal/bin/rihal-tools.cjs state sync --from-disk\n');
+    process.stderr.write('  Inspect:   node .rihal/bin/rihal-tools.cjs state read\n');
+    process.exit(1);
+  }
+
   function detectInsights(state, roadmapPhases, diskByNum) {
     const insights = [];
     const statePhases = (state && (state.state?.phases || state.phases)) || [];
@@ -3155,6 +4741,39 @@ function cmdProgress(args) {
       });
     }
 
+    // Phantom-complete: phase claimed Complete (in ROADMAP or state) but missing
+    // PLAN.md AND SUMMARY.md on disk. User-visible bug: /rihal-status would
+    // happily report 'all complete' while /rihal-audit correctly flagged the
+    // gap because the two read different sources of truth.
+    // Surfaced 2026-04-29 in a real session — siraaj phases 07-12 had ROADMAP
+    // markers but zero artifacts.
+    const phantomCompletes = [];
+    const claimedComplete = (p) => {
+      if (!p) return false;
+      const s = String(p.status ?? '').toLowerCase();
+      return p.completed || s === 'complete' || s === 'completed' || s === 'done';
+    };
+    // Walk ROADMAP-claimed completes and state-claimed completes, both directions.
+    const completeKeys = new Set();
+    for (const p of roadmapPhases) if (claimedComplete(p)) completeKeys.add(norm(phaseKey(p)));
+    for (const p of statePhases) if (claimedComplete(p)) completeKeys.add(norm(phaseKey(p)));
+    for (const k of completeKeys) {
+      const disk = diskByNum[k] || diskByNum[k.padStart(2, '0')];
+      // Only flag when the phase dir EXISTS — purely-state-only entries are a
+      // separate problem (drift/undercount above). Here we want claim-vs-files.
+      if (!disk) continue;
+      if (disk.plan_count === 0 && disk.summary_count === 0) {
+        phantomCompletes.push(k);
+      }
+    }
+    if (phantomCompletes.length > 0) {
+      insights.push({
+        kind: 'phantom-complete',
+        severity: 'warn',
+        message: `${phantomCompletes.length} phase(s) marked Complete but missing both PLAN.md and SUMMARY.md on disk: ${phantomCompletes.slice(0, 5).join(', ')}. The completion claim is unsupported. Run /rihal-audit phase <N> to inspect.`,
+      });
+    }
+
     // Between-milestones heuristic: no current_phase + previous milestone's last phase is complete
     if (state && state.current_phase === null && statePhases.length > 0) {
       const allComplete = statePhases.every(p => p.status === 'complete' || p.completed);
@@ -3167,6 +4786,35 @@ function cmdProgress(args) {
       }
     }
 
+    // Stuck-phase: in_progress phase with no commits touching its .planning dir in 7+ days
+    try {
+      const inProgressPhases = statePhases.filter(p => {
+        const s = String(p.status ?? '').toLowerCase();
+        return s === 'in_progress' || s === 'in-progress' || s === 'executing';
+      });
+      for (const p of inProgressPhases) {
+        const key = norm(phaseKey(p));
+        const disk = diskByNum[key] || diskByNum[key.padStart(2, '0')];
+        if (!disk) continue;
+        const dirName = disk.dirName;
+        const gitArgs = ['log', '--oneline', '--since=7 days ago', '--', `.planning/phases/${dirName}/`];
+        let recentCommits = '';
+        try {
+          recentCommits = require('child_process').execSync(
+            `git ${gitArgs.join(' ')}`,
+            { cwd: PROJECT_ROOT, stdio: 'pipe', timeout: 5000 }
+          ).toString().trim();
+        } catch { /* git not available or no history */ }
+        if (recentCommits === '') {
+          insights.push({
+            kind: 'stuck-phase',
+            severity: 'warn',
+            message: `Phase ${key} is in progress but has no commits in the last 7 days. It may be stuck. Run /rihal-status or /rihal-audit phase ${key} to investigate.`,
+          });
+        }
+      }
+    } catch { /* non-fatal — git unavailable or project root not set */ }
+
     return insights;
   }
 
@@ -3184,7 +4832,7 @@ function cmdProgress(args) {
       routes.push({
         letter: 'A',
         label: `Execute phase ${k} — unfinished plans`,
-        command: `/rihal-execute-phase ${k}`,
+        command: `/rihal-execute ${k}`,
       });
     }
 
@@ -3291,7 +4939,9 @@ function cmdProgress(args) {
   }
 
   if (sub === 'insights') {
-    return { ok: true, insights: detectInsights(state, roadmapPhases, diskByNum) };
+    const insightsList = detectInsights(state, roadmapPhases, diskByNum);
+    enforceStrictGate(insightsList);
+    return { ok: true, insights: insightsList };
   }
 
   if (sub === 'routes') {
@@ -3301,6 +4951,7 @@ function cmdProgress(args) {
   // sub === 'init' (default) — full snapshot
   const currentPhase = state && state.current_phase;
   const insights = detectInsights(state, roadmapPhases, diskByNum);
+  enforceStrictGate(insights);
   const routes = deriveRoutes(state, roadmapPhases, diskByNum);
   const { weighted: weightedCompleted, pct: weightedPct } = computeWeightedProgress(statePhases, diskByNum);
 
@@ -3572,6 +5223,12 @@ function cmdFindFiles(rawArgs) {
 
 async function main() {
   const [, , subcommand, ...args] = process.argv;
+  // #473 guard runs before any subcommand. Skipped for read-only inspection
+  // so 'rihal-tools version' / 'help' / 'list-agents' work outside the project.
+  const READ_ONLY_SUBCOMMANDS = new Set(['version', 'help', '--help', '-h', undefined, 'list-agents', 'agent-info', 'agent-skills']);
+  if (!READ_ONLY_SUBCOMMANDS.has(subcommand)) {
+    assertCwdMatchesProjectRoot();
+  }
   try {
     let result;
     switch (subcommand) {
@@ -3592,6 +5249,44 @@ async function main() {
         if (args[0] === 'list') { result = cmdPlanList(); }
         else { console.error('Unknown plan subcommand. Valid: list'); process.exit(1); }
         break;
+      case 'phase-plan-index':
+        result = cmdPhasePlanIndex(args.join(' '));
+        break;
+      case 'phases':
+        if (args[0] === 'list') { result = cmdPhasesList(args.slice(1)); if (result === undefined) return; }
+        else { console.error('Unknown phases subcommand. Valid: list'); process.exit(1); }
+        break;
+      case 'find-phase':
+        result = cmdFindPhase(args);
+        break;
+      case 'audit-uat':
+        result = cmdAuditUat(args);
+        break;
+      case 'uat':
+        if (args[0] === 'render-checkpoint') {
+          const r = cmdUatRenderCheckpoint(args.slice(1));
+          if (r && r.__raw) { console.log(r.__raw); return; }
+          result = r;
+        } else { console.error('Unknown uat subcommand. Valid: render-checkpoint'); process.exit(1); }
+        break;
+      case 'requirements':
+        if (args[0] === 'mark-complete') { result = cmdRequirementsMarkComplete(args.slice(1)); }
+        else { console.error('Unknown requirements subcommand. Valid: mark-complete'); process.exit(1); }
+        break;
+      case 'todo':
+        if (args[0] === 'match-phase') { result = cmdTodoMatchPhase(args.slice(1)); }
+        else { console.error('Unknown todo subcommand. Valid: match-phase'); process.exit(1); }
+        break;
+      case 'learnings':
+        if (args[0] === 'copy') { result = cmdLearningsCopy(args.slice(1)); }
+        else { console.error('Unknown learnings subcommand. Valid: copy'); process.exit(1); }
+        break;
+      case 'docs-audit':
+        result = cmdDocsAudit(args);
+        break;
+      case 'frontmatter':
+        if (args[0] === 'get') { cmdFrontmatterGet(args.slice(1)); return; }
+        else { console.error('Unknown frontmatter subcommand. Valid: get'); process.exit(1); }
       case 'notes':
         if (args[0] === 'list') { result = cmdNotesList(); }
         else if (args[0] === 'count') { result = cmdNotesCount(); }
@@ -3612,6 +5307,32 @@ async function main() {
       case 'state':
         result = cmdState(args);
         break;
+      case 'phase':
+        result = cmdPhase(args);
+        break;
+      case 'commit':
+        result = cmdCommit(args);
+        break;
+      case 'commit-to-subrepo':
+        result = cmdCommitToSubrepo(args);
+        break;
+      case 'generate-claude-md':
+        result = cmdGenerateClaudeMd(args.join(' '));
+        break;
+      case 'check-implementation-readiness':
+        result = cmdCheckImplementationReadiness(args.join(' '));
+        break;
+      case 'classify-tech':
+        result = cmdClassifyTech(args.join(' '));
+        break;
+      case 'context':
+        if (args[0] === 'refresh') {
+          result = cmdContextRefresh();
+        } else {
+          console.error('Unknown context subcommand. Valid: refresh');
+          process.exit(1);
+        }
+        break;
       case 'module':
         result = cmdModule(args);
         break;
@@ -3708,8 +5429,25 @@ async function main() {
         console.log('  agent-skills <name>                          → alias for agent-info');
         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('  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)');
+        console.log('  check-implementation-readiness --phase <N>  → verify preconditions before phase planning; returns {ready, blockers}');
+        console.log('  classify-tech --keywords "<keywords>"        → classify tech stack from keywords (frontend/backend/mobile/styling)');
+        console.log('  context refresh                              → refresh .rihal/context/ cache from .rihal/sources.yaml');
         console.log('  module <subcommand> [args]                   → module system helpers');
         console.log('  plan <subcommand> [args]                     → phase/plan operations');
+        console.log('  phase-plan-index <N>                         → JSON inventory of plans under phase N (waves, summary status, task counts)');
+        console.log('  phases list [--type X] [--pick path]         → directory inventory of .planning/phases (--type: summaries|sprints|directories|all; --pick: e.g. directories[-1])');
+        console.log('  find-phase <N> [--raw]                       → resolve phase number to dir/slug + decimal children');
+        console.log('  audit-uat [--raw]                            → walk all UAT files, return inventory + status counts');
+        console.log('  uat render-checkpoint --file <p>             → render markdown UAT checkpoint block from file');
+        console.log('  requirements mark-complete <ID> [<ID>...]    → flip status to complete in REQUIREMENTS.md');
+        console.log('  todo match-phase <N>                         → return todos with matching phase tag');
+        console.log('  learnings copy                               → soft-fail copy of phase LEARNINGS.md to ~/.rihal/learnings/');
+        console.log('  docs-audit                                   → list docs missing per documentation-requirements.csv');
+        console.log('  frontmatter get <file> --field <name>        → print one frontmatter field value (empty if absent)');
         console.log('  notes <subcommand> [args]                    → manage project notes');
         console.log('  config <subcommand> [args]                   → read/write project config');
         console.log('  notify send --title "<t>" [--body "<b>"] [--event <e>] [--only slack|discord|teams]  → post to configured webhooks');
@@ -3763,7 +5501,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','record-execution','record-council','record-chain','add-decision','decisions-global','add-blocker','resolve-blocker','record-session','set-ids-in-state','migrate-ids','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','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'];
         if (stateSubs.includes(subcommand)) {
           console.error(`Did you mean: state ${subcommand}? Run 'rihal-tools.cjs help' for full usage.`);
         } else {