@axiomatic-labs/claudeflow 2.13.24 → 2.13.26

package/lib/hook-overrides.js

@@ -51,7 +51,7 @@ function normalizeHandlerPath(command) {
 }
 
 function defaultOverrides() {
-  return { version: 1, disabledHandlers: [], disabledReminders: [] };
+  return { version: 1, disabledHandlers: [], disabledReminders: [], enforcementDisabled: false };
 }
 
 function readOverrides(projectRoot) {
@@ -61,6 +61,7 @@ function readOverrides(projectRoot) {
     version: data.version || 1,
     disabledHandlers: Array.isArray(data.disabledHandlers) ? data.disabledHandlers : [],
     disabledReminders: Array.isArray(data.disabledReminders) ? data.disabledReminders : [],
+    enforcementDisabled: data.enforcementDisabled === true,
   };
 }
 
@@ -173,6 +174,21 @@ function toggleHookOverride(projectRoot, { event, matcher = '', handler, disable
   return { state: 'enabled' };
 }
 
+// Master enforcement switch. When OFF, the wrapper silences every hook
+// listed in `.claude/hooks/shared/enforcement-catalog.js` regardless of
+// per-handler manual toggles. Per-handler toggles outside the catalog
+// remain in effect — they are independent layers.
+function toggleEnforcementMode(projectRoot, { disable }) {
+  if (typeof disable !== 'boolean') return { state: 'error', reason: 'disable-required' };
+  const overrides = readOverrides(projectRoot);
+  if (overrides.enforcementDisabled === disable) {
+    return { state: 'noop', reason: disable ? 'already-off' : 'already-on' };
+  }
+  overrides.enforcementDisabled = disable;
+  writeOverrides(projectRoot, overrides);
+  return { state: disable ? 'off' : 'on' };
+}
+
 // Toggle a single reminder by id. Same persistence file, same hot-reload
 // semantics — `reload-reminder.js` re-reads overrides on every invocation.
 function toggleReminderOverride(projectRoot, { id, disable }) {
@@ -202,6 +218,7 @@ module.exports = {
   writeOverrides,
   toggleHookOverride,
   toggleReminderOverride,
+  toggleEnforcementMode,
   normalizeHandlerPath,
   matchesOverride,
 };

package/lib/install.js

@@ -334,6 +334,7 @@ function ensureGlobalCli(version) {
         autoInstalled: !needsUpgrade,
         upgraded: needsUpgrade,
         fromVersion: installedVersion || undefined,
+        shellPath: verifyShellCanFindCli(),
       };
     }
     return {
@@ -368,6 +369,67 @@ function readGlobalCliVersion() {
   }
 }
 
+// Returns { ok: boolean | null, binPath?: string, shellRcFile?: string,
+//   nvmDetected?: boolean, suggestedFix?: string }
+//
+// Distinguishes "package installed globally" from "package findable from
+// the user's interactive shell". Catches the common nvm-lazy-load setup
+// where `npm install -g` writes a binary the shell can't see until nvm
+// is sourced — typically discovered only when the user opens a fresh
+// terminal and types `claudeflow` and gets "command not found".
+function verifyShellCanFindCli() {
+  // Skip on Windows; lazy-load + nvm-windows behave differently and the
+  // login-shell trick below is brittle there.
+  if (process.platform === 'win32') return { ok: null };
+
+  const shellPath = process.env.SHELL;
+  if (!shellPath || !fs.existsSync(shellPath)) return { ok: null };
+
+  // Run a non-inherited interactive login shell — that's the closest
+  // simulation of "user opens a new terminal" without polluting the
+  // current process.
+  let foundOnUserPath = null;
+  try {
+    const out = execSync(`${shellPath} -lic 'command -v claudeflow 2>/dev/null'`, {
+      encoding: 'utf8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    foundOnUserPath = out.length > 0;
+  } catch {
+    // Some shells exit non-zero when `command -v` finds nothing — treat
+    // that as "not found" rather than as an inconclusive check.
+    foundOnUserPath = false;
+  }
+
+  if (foundOnUserPath) return { ok: true };
+
+  // Resolve where the binary actually lives so the warning is concrete.
+  let binPath = null;
+  try {
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8', timeout: 5000 }).trim();
+    binPath = path.join(prefix, 'bin', 'claudeflow');
+  } catch {}
+
+  const home = process.env.HOME || '';
+  const nvmDetected = !!process.env.NVM_DIR
+    || fs.existsSync(path.join(home, '.nvm', 'nvm.sh'));
+  const isZsh = shellPath.endsWith('/zsh');
+  const shellRcFile = isZsh ? '~/.zshrc' : (shellPath.endsWith('/bash') ? '~/.bashrc' : '~/.profile');
+
+  // Wrapper-function fix that mirrors the user's existing nvm lazy-load
+  // pattern (e.g., npx, node, npm). Single line, paste into rcFile, done.
+  const wrapperFix = `claudeflow() { unset -f claudeflow; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; claudeflow "$@"; }`;
+
+  return {
+    ok: false,
+    binPath,
+    shellRcFile,
+    nvmDetected,
+    suggestedFix: wrapperFix,
+  };
+}
+
 function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled: false }) {
   const MANIFESTS = ['package.json', 'pyproject.toml', 'Gemfile', 'go.mod', 'Cargo.toml', 'composer.json'];
   const SKIP_DIRS = new Set(['node_modules', 'vendor', '__pycache__', 'dist', 'build', '.next', '.nuxt', '.output', '.claude']);
@@ -401,7 +463,27 @@ function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled:
       `  ${ui.DIM}✓ Upgraded global ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} CLI${cliStatus.fromVersion ? ` from ${cliStatus.fromVersion}` : ''}.${ui.RESET}`
     );
     console.log('');
-  } else if (!cliStatus.available) {
+  }
+
+  // Shell PATH warning — if the global package was installed but the
+  // user's interactive shell can't find the binary (typical with
+  // nvm lazy-load), emit a concrete fix.
+  if (cliStatus.shellPath && cliStatus.shellPath.ok === false) {
+    const sp = cliStatus.shellPath;
+    console.log(`  ${ui.YELLOW}⚠ ${ui.BOLD}claudeflow${ui.RESET}${ui.YELLOW} CLI installed but NOT on your shell PATH.${ui.RESET}`);
+    if (sp.binPath) {
+      console.log(`    ${ui.DIM}Binary lives at: ${sp.binPath}${ui.RESET}`);
+    }
+    if (sp.nvmDetected) {
+      console.log(`    ${ui.DIM}Likely cause: nvm lazy-load. Add this to ${sp.shellRcFile}, then reopen terminal:${ui.RESET}`);
+      console.log(`    ${ui.CYAN}${sp.suggestedFix}${ui.RESET}`);
+    } else {
+      console.log(`    ${ui.DIM}Add the npm prefix bin directory to your PATH in ${sp.shellRcFile}.${ui.RESET}`);
+    }
+    console.log('');
+  }
+
+  if (!cliStatus.available) {
     console.log(`  ${ui.DIM}To get the ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} shell command, run:${ui.RESET}`);
     console.log(`    ${ui.CYAN}npm i -g @axiomatic-labs/claudeflow${ui.RESET}`);
     if (cliStatus.error && cliStatus.error !== 'skipped') {
@@ -434,14 +516,21 @@ function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled:
   }
 
   console.log('');
-  console.log(`  ${ui.BOLD}Commands:${ui.RESET}`);
+  console.log(`  ${ui.BOLD}Slash commands (inside Claude Code):${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-install${ui.RESET}        ${ui.DIM}Route setup automatically for new or existing projects${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-build${ui.RESET}          ${ui.DIM}Execute an approved spec for larger or higher-risk changes${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-design-tokens${ui.RESET}  ${ui.DIM}Create design reference from a site or screenshot${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-create-ui${ui.RESET}      ${ui.DIM}Build pages from visual references${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-checkpoints${ui.RESET}    ${ui.DIM}Auto-save work with git checkpoints${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-add-skill${ui.RESET}      ${ui.DIM}Add new technology skills (e.g. /claudeflow-add-skill stripe)${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-add-tools${ui.RESET}     ${ui.DIM}Discover and install MCP servers + CLI tools${ui.RESET}`);
+  console.log(`  ${ui.CYAN}/claudeflow-add-tools${ui.RESET}      ${ui.DIM}Discover and install MCP servers + CLI tools${ui.RESET}`);
+  console.log('');
+  console.log(`  ${ui.BOLD}Shell commands (outside Claude Code):${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow${ui.RESET}                 ${ui.DIM}Start Claude Code with this project's claudeflow context${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow panel${ui.RESET}           ${ui.DIM}Open the local web dashboard — toggle hooks, reminders, enforcement${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow doctor${ui.RESET}          ${ui.DIM}Diagnose CDP-port and lockfile issues; ${ui.CYAN}--fix${ui.RESET}${ui.DIM} to auto-repair${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow install${ui.RESET}         ${ui.DIM}Refresh the template + global CLI in this project${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow version${ui.RESET}         ${ui.DIM}Show installed framework + CLI versions${ui.RESET}`);
   console.log('');
   console.log(`  ${ui.DIM}Docs: https://claudeflow.dev${ui.RESET}`);
   console.log('');
@@ -1107,4 +1196,6 @@ module.exports = Object.assign(run, {
   mergeClaudeSettings,
   commandExists,
   readGlobalCliVersion,
+  verifyShellCanFindCli,
+  showGettingStarted,
 });

package/lib/panel.js

@@ -25,9 +25,21 @@ const {
   readOverrides,
   toggleHookOverride,
   toggleReminderOverride,
+  toggleEnforcementMode,
   normalizeHandlerPath,
 } = require('./hook-overrides.js');
 
+function loadEnforcementCatalog(cwd) {
+  const p = path.join(cwd, '.claude', 'hooks', 'shared', 'enforcement-catalog.js');
+  if (!fs.existsSync(p)) return null;
+  try {
+    delete require.cache[require.resolve(p)];
+    return require(p);
+  } catch {
+    return null;
+  }
+}
+
 // Lazy-load the reminder catalog from the template hook helper. The path
 // resolves the same way at install time and from the template repo.
 function loadReminderHelpers(cwd) {
@@ -112,6 +124,11 @@ function getHooksInfo(cwd) {
   for (const d of overrides.disabledHandlers || []) {
     disabledIndex.set(`${d.event}|${d.matcher || ''}|${d.handler}`, d);
   }
+  const catalog = loadEnforcementCatalog(cwd);
+  const isEnforcement = catalog && typeof catalog.isEnforcementHook === 'function'
+    ? catalog.isEnforcementHook
+    : () => false;
+  const enforcementDisabled = overrides.enforcementDisabled === true;
 
   // settings.json lists every hook (with each command wrapped through
   // run-with-override.js). The wrapper checks overrides at invocation time,
@@ -133,14 +150,21 @@ function getHooksInfo(cwd) {
         const isEmpty = !handlerPath;
         if (isEmpty) warnings++;
         const key = `${event}|${matcher}|${handlerPath}`;
-        const isDisabled = disabledIndex.has(key);
+        const enforcement = isEnforcement(event, matcher, handlerPath);
+        const masterDisabled = enforcement && enforcementDisabled;
+        const manualDisabled = disabledIndex.has(key);
+        const isDisabled = manualDisabled || masterDisabled;
         if (isDisabled) disabledCount++;
         handlers.push({
           handler: handlerPath || '(empty command)',
           matcher,
           matcherDisplay: matcher || '(any)',
           empty: isEmpty,
+          enforcement,
           disabled: isDisabled,
+          disabledBy: masterDisabled && !manualDisabled ? 'enforcement-master'
+                    : manualDisabled ? 'manual'
+                    : null,
           rawCommand: cmd,
         });
         totalHandlers++;
@@ -244,6 +268,24 @@ function getActiveRunInfo(cwd) {
   };
 }
 
+function getEnforcementInfo(cwd) {
+  const catalog = loadEnforcementCatalog(cwd);
+  const overrides = readOverrides(cwd);
+  if (!catalog || !Array.isArray(catalog.ENFORCEMENT_HOOKS)) {
+    return { available: false, on: !overrides.enforcementDisabled, count: 0 };
+  }
+  return {
+    available: true,
+    on: !overrides.enforcementDisabled,
+    count: catalog.ENFORCEMENT_HOOKS.length,
+    hooks: catalog.ENFORCEMENT_HOOKS.map((h) => ({
+      event: h.event,
+      handler: h.handler,
+      matcher: h.matcher,
+    })),
+  };
+}
+
 function getRemindersInfo(cwd) {
   const helpers = loadReminderHelpers(cwd);
   if (!helpers || typeof helpers.listReminderCatalog !== 'function') {
@@ -288,6 +330,7 @@ function collectStatus(cwd) {
     setupContext: getSetupContextInfo(cwd),
     activeRun: getActiveRunInfo(cwd),
     reminders: getRemindersInfo(cwd),
+    enforcement: getEnforcementInfo(cwd),
     doctor: getDoctorInfo(cwd),
   };
 }
@@ -326,6 +369,19 @@ header .cwd { color: var(--muted); font-family: var(--mono); font-size: 12px; fl
 header .actions { display: flex; gap: 12px; align-items: center; color: var(--muted); font-size: 12px; }
 header button { background: var(--panel-2); border: 1px solid var(--border); color: var(--fg); padding: 6px 12px; border-radius: 6px; cursor: pointer; font: inherit; }
 header button:hover { border-color: var(--accent); }
+.enforce-pill { display: inline-flex; align-items: center; gap: 8px; padding: 5px 12px; border-radius: 999px; border: 1px solid var(--border); background: var(--panel-2); font-size: 12px; transition: all 0.2s; }
+.enforce-pill .enforce-label { color: var(--muted); font-family: var(--mono); letter-spacing: 0.5px; text-transform: uppercase; font-size: 11px; }
+.enforce-pill .enforce-state { font-family: var(--mono); font-weight: 600; font-size: 12px; min-width: 26px; text-align: left; }
+.enforce-pill[data-state="on"] { border-color: rgba(63, 185, 80, 0.5); background: rgba(63, 185, 80, 0.08); }
+.enforce-pill[data-state="on"] .enforce-state { color: var(--ok); }
+.enforce-pill[data-state="off"] { border-color: rgba(248, 81, 73, 0.6); background: rgba(248, 81, 73, 0.12); box-shadow: 0 0 0 1px rgba(248, 81, 73, 0.3); }
+.enforce-pill[data-state="off"] .enforce-state { color: var(--err); }
+.enforce-switch { position: relative; display: inline-block; width: 32px; height: 18px; }
+.enforce-switch input { opacity: 0; width: 0; height: 0; }
+.enforce-slider { position: absolute; cursor: pointer; inset: 0; background: var(--border); border-radius: 999px; transition: background 0.2s; }
+.enforce-slider::before { content: ""; position: absolute; height: 14px; width: 14px; left: 2px; top: 2px; background: var(--fg); border-radius: 50%; transition: transform 0.2s; }
+.enforce-switch input:checked + .enforce-slider { background: var(--ok); }
+.enforce-switch input:checked + .enforce-slider::before { transform: translateX(14px); }
 main { display: flex; min-height: calc(100vh - 56px); }
 nav { width: 220px; flex-shrink: 0; border-right: 1px solid var(--border); background: var(--panel); padding: 12px 0; }
 nav a { display: flex; align-items: center; gap: 10px; padding: 10px 22px; color: var(--fg); text-decoration: none; cursor: pointer; border-left: 3px solid transparent; font-size: 13px; }
@@ -397,6 +453,11 @@ details[open] summary { padding-bottom: 8px; border-bottom: 1px solid var(--bord
   <span class="version" id="version">…</span>
   <span class="cwd" id="cwd">…</span>
   <span class="actions">
+    <span class="enforce-pill" id="enforce-pill" title="Master switch — toggles every blocking enforcement hook (freeze-step-contract, enforce-task-creation, stack-debt-guard, ecosystem-artifacts, workflow-enforcement). Validators and reminders are unaffected.">
+      <span class="enforce-label">Enforcement</span>
+      <label class="enforce-switch"><input type="checkbox" id="enforce-toggle" /><span class="enforce-slider"></span></label>
+      <span class="enforce-state" id="enforce-state">…</span>
+    </span>
     <label class="toggle"><input type="checkbox" id="auto" checked /> auto-refresh 5s</label>
     <button id="refresh">Refresh</button>
   </span>
@@ -486,6 +547,21 @@ async function refresh() {
 function renderHeader() {
   document.getElementById('version').textContent = 'v' + state.version.installed;
   document.getElementById('cwd').textContent = state.cwd;
+  const ef = state.enforcement;
+  const pill = document.getElementById('enforce-pill');
+  const cb = document.getElementById('enforce-toggle');
+  const lbl = document.getElementById('enforce-state');
+  if (ef && ef.available) {
+    pill.style.display = '';
+    pill.dataset.state = ef.on ? 'on' : 'off';
+    cb.checked = ef.on;
+    lbl.textContent = ef.on ? 'ON' : 'OFF';
+    pill.title = ef.on
+      ? 'Enforcement is ON — ' + ef.count + ' blocking hook(s) active. Click to disable all.'
+      : 'Enforcement is OFF — ' + ef.count + ' blocking hook(s) silenced. Reminders + validators still run.';
+  } else {
+    pill.style.display = 'none';
+  }
 }
 
 function severityFor(id) {
@@ -563,6 +639,9 @@ function renderOverview() {
   const rm = s.reminders && s.reminders.available
     ? \`\${s.reminders.activeCount} active · \${s.reminders.disabledCount} disabled\`
     : 'unavailable';
+  const ef = s.enforcement && s.enforcement.available
+    ? (s.enforcement.on ? \`ON (\${s.enforcement.count} blocking hooks)\` : \`OFF — \${s.enforcement.count} blocking hooks silenced\`)
+    : 'unavailable';
   return \`<h2>Overview</h2>
     <p class="sub">Snapshot at \${new Date(s.timestamp).toLocaleTimeString()}</p>
     <div class="card">
@@ -573,6 +652,7 @@ function renderOverview() {
       \${row('Setup context', sc, { kind: s.setupContext.exists ? (s.setupContext.toolingComplete ? 'ok' : 'warn') : 'err', text: s.setupContext.exists ? (s.setupContext.toolingComplete ? '✓' : '!') : '✗' })}
       \${row('Active run', ar, { kind: 'info', text: s.activeRun.active ? '·' : '·' })}
       \${row('Reminders', rm, { kind: s.reminders && s.reminders.available ? (s.reminders.disabledCount ? 'info' : 'ok') : 'err', text: s.reminders && s.reminders.disabledCount ? '·' : '✓' })}
+      \${row('Enforcement', ef, { kind: s.enforcement && s.enforcement.available ? (s.enforcement.on ? 'ok' : 'err') : 'err', text: s.enforcement && s.enforcement.available ? (s.enforcement.on ? '✓' : '✗') : '·' })}
       \${row('Doctor', dc, { kind: s.doctor.issueCount === 0 ? 'ok' : 'warn', text: s.doctor.issueCount === 0 ? '✓' : '!' })}
     </div>\`;
 }
@@ -603,10 +683,13 @@ function renderHooks() {
       const cls = hd.disabled ? 'handler disabled-row' : 'handler';
       const checked = hd.disabled ? '' : 'checked';
       const dataset = \`data-event="\${escapeHtml(ev.event)}" data-matcher="\${escapeHtml(hd.matcher)}" data-handler="\${escapeHtml(hd.handler)}"\`;
-      const status = hd.disabled ? '<span class="badge info">disabled</span>' : '';
+      const enforcementBadge = hd.enforcement ? '<span class="badge warn" title="Member of the enforcement catalog — affected by the master switch">enforcement</span>' : '';
+      const masterBadge = hd.disabledBy === 'enforcement-master' ? '<span class="badge err" title="Silenced by the master Enforcement OFF switch in the header">master OFF</span>' : '';
+      const manualBadge = hd.disabledBy === 'manual' ? '<span class="badge info">disabled</span>' : '';
+      const lockedByMaster = hd.disabledBy === 'enforcement-master';
       return \`<div class="\${cls}">
-        <label class="toggle"><input type="checkbox" class="hook-toggle" \${dataset} \${checked} \${hd.empty ? 'disabled' : ''} />
-          <span>\${escapeHtml(hd.handler)} \${status} \${mark}</span></label>
+        <label class="toggle"><input type="checkbox" class="hook-toggle" \${dataset} \${checked} \${hd.empty || lockedByMaster ? 'disabled' : ''} />
+          <span>\${escapeHtml(hd.handler)} \${enforcementBadge} \${masterBadge} \${manualBadge} \${mark}</span></label>
         <span class="matcher">\${escapeHtml(hd.matcherDisplay)}</span>
       </div>\`;
     }).join('');
@@ -773,6 +856,34 @@ document.addEventListener('toggle', (e) => {
   }
 }, true);
 
+async function toggleEnforcement(disable) {
+  try {
+    const r = await fetch('/api/enforcement/toggle', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ disable }),
+    });
+    const result = await r.json();
+    if (!r.ok || result.state === 'error') {
+      showToast('Toggle failed: ' + (result.reason || result.error || 'unknown'), 'err');
+    } else if (result.state === 'noop') {
+      showToast('Enforcement already in target state', 'ok');
+    } else {
+      showToast(disable
+        ? 'Enforcement OFF — blocking hooks silenced. Validators + reminders still run.'
+        : 'Enforcement ON — full blocking restored.',
+        disable ? 'err' : 'ok');
+    }
+  } catch (e) {
+    showToast('Network error: ' + e.message, 'err');
+  }
+  await refresh();
+}
+
+document.getElementById('enforce-toggle').onchange = (e) => {
+  toggleEnforcement(!e.target.checked);
+};
+
 document.getElementById('refresh').onclick = refresh;
 document.getElementById('auto').onchange = (e) => {
   if (timer) clearInterval(timer);
@@ -842,6 +953,20 @@ function handler(cwd) {
         return send(status, JSON.stringify(result), 'application/json');
       }
 
+      if (req.method === 'POST' && route === '/api/enforcement/toggle') {
+        const raw = await readRequestBody(req);
+        let payload;
+        try { payload = JSON.parse(raw); }
+        catch { return send(400, JSON.stringify({ error: 'invalid json' }), 'application/json'); }
+        const { disable } = payload;
+        if (typeof disable !== 'boolean') {
+          return send(400, JSON.stringify({ error: 'disable required' }), 'application/json');
+        }
+        const result = toggleEnforcementMode(cwd, { disable });
+        const status = result.state === 'error' ? 500 : 200;
+        return send(status, JSON.stringify(result), 'application/json');
+      }
+
       if (req.method === 'POST' && route === '/api/reminders/toggle') {
         const raw = await readRequestBody(req);
         let payload;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.13.24",
+  "version": "2.13.26",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"