@pennyfarthing/core 11.2.0 → 11.2.2

package/packages/core/dist/cli/commands/doctor.js

@@ -1,16 +1,17 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync, chmodSync, statSync, readlinkSync, symlinkSync, unlinkSync, mkdirSync, renameSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync, chmodSync, statSync, readlinkSync, symlinkSync, unlinkSync, mkdirSync, renameSync, copyFileSync } from 'fs';
 import { join, relative, dirname } from 'path';
 import YAML from 'yaml';
 import { spawnSync } from 'child_process';
 import fsExtra from 'fs-extra';
-const { removeSync, ensureDirSync } = fsExtra;
+const { removeSync, ensureDirSync, copySync } = fsExtra;
 import { logger } from '../utils/logger.js';
 import { readManifest } from '../utils/manifest.js';
-import { pathExists, isDirectory, isSymlink, fileMatchesHash } from '../utils/files.js';
-import { getPackageVersion } from '../utils/version.js';
+import { pathExists, isDirectory, isSymlink, fileMatchesHash, filesMatch } from '../utils/files.js';
+import { getPackageVersion, getAssetsPath } from '../utils/version.js';
 import { findNodeModulesPath } from '../utils/node-modules.js';
 import { ALL_SYMLINKS, CORE_AGENTS } from '../utils/constants.js';
 import { getPfVersion, installPfCli } from '../utils/python.js';
+import { LEGACY_HOOK_MIGRATIONS, migrateHookPaths } from '../utils/settings.js';
 export async function doctorCommand(options) {
     const projectRoot = process.cwd();
     // Handle dogfood mode - run checks for framework/orchestrator development
@@ -47,6 +48,7 @@ export async function doctorCommand(options) {
     // Run checks
     results.push(...checkInstallation(projectRoot, manifest));
     results.push(...checkCoreFiles(projectRoot, manifest));
+    results.push(...checkCommandsAndSkills(projectRoot, nodeModulesPath));
     results.push(...checkUserFiles(projectRoot));
     results.push(...checkDirectories(projectRoot));
     results.push(...checkHooks(projectRoot));
@@ -54,6 +56,7 @@ export async function doctorCommand(options) {
     results.push(...checkFileLayout(projectRoot));
     results.push(...checkLegacyFiles(projectRoot));
     results.push(checkLegacyStatuslinePath(projectRoot));
+    results.push(checkLegacyHookCommands(projectRoot));
     results.push(...checkCyclist(projectRoot));
     results.push(checkPfCli(nodeModulesPath));
     // Output results
@@ -64,7 +67,8 @@ export async function doctorCommand(options) {
     // Display results by category
     const categories = [
         { name: 'Installation', filter: (r) => r.name.startsWith('manifest') },
-        { name: 'Core Files', filter: (r) => r.name.startsWith('core/') },
+        { name: 'Core Files', filter: (r) => r.name.startsWith('core/') && r.name !== 'core/commands' && r.name !== 'core/skills' },
+        { name: 'Commands & Skills', filter: (r) => r.name === 'core/commands' || r.name === 'core/skills' },
         { name: 'User Files', filter: (r) => r.name.startsWith('project/') || r.name.startsWith('persona') || r.name.startsWith('settings') },
         { name: 'Directories', filter: (r) => r.name.startsWith('dir/') },
         { name: 'Hooks', filter: (r) => r.name.startsWith('hook/') },
@@ -188,6 +192,211 @@ function checkCoreFiles(projectRoot, manifest) {
     }
     return results;
 }
+/**
+ * Check commands and skills are properly copied (not symlinked) and up to date.
+ * Commands and skills are file copies since v11.3.0 to avoid node_modules drift.
+ */
+function checkCommandsAndSkills(projectRoot, _nodeModulesPath) {
+    const results = [];
+    // Use assetsPath for source resolution (correct pf-* prefix in dogfood)
+    let assetsPath = null;
+    try {
+        assetsPath = getAssetsPath();
+    }
+    catch { /* no assets available */ }
+    if (!assetsPath) {
+        // Can't check freshness without assets, but check dirs exist
+        const commandsDir = join(projectRoot, '.claude/commands');
+        const skillsDir = join(projectRoot, '.claude/skills');
+        results.push({
+            name: 'core/commands',
+            status: pathExists(commandsDir) ? 'pass' : 'fail',
+            detail: pathExists(commandsDir) ? undefined : 'Missing .claude/commands/'
+        });
+        results.push({
+            name: 'core/skills',
+            status: pathExists(skillsDir) ? 'pass' : 'fail',
+            detail: pathExists(skillsDir) ? undefined : 'Missing .claude/skills/'
+        });
+        return results;
+    }
+    // Check commands
+    const commandsDir = join(projectRoot, '.claude/commands');
+    const builtInCommandsPath = join(assetsPath, 'commands');
+    if (!pathExists(commandsDir)) {
+        results.push({
+            name: 'core/commands',
+            status: 'fail',
+            detail: 'Missing .claude/commands/ — run pennyfarthing update'
+        });
+    }
+    else if (pathExists(builtInCommandsPath)) {
+        const sourceCommands = readdirSync(builtInCommandsPath).filter(f => f.endsWith('.md') && f.startsWith('pf-'));
+        const installedEntries = readdirSync(commandsDir).filter(f => f.startsWith('pf-'));
+        let staleCount = 0;
+        let symlinkCount = 0;
+        // Check for stale symlinks (legacy) or stale copies
+        for (const cmd of sourceCommands) {
+            const installedPath = join(commandsDir, cmd);
+            const sourcePath = join(builtInCommandsPath, cmd);
+            if (!pathExists(installedPath)) {
+                staleCount++;
+            }
+            else if (isSymlink(installedPath)) {
+                symlinkCount++;
+            }
+            else if (!filesMatch(installedPath, sourcePath)) {
+                staleCount++;
+            }
+        }
+        if (symlinkCount > 0) {
+            results.push({
+                name: 'core/commands',
+                status: 'warn',
+                detail: `${symlinkCount} command(s) are symlinks — should be copies. Run pennyfarthing update`,
+                fix: () => {
+                    refreshCommandsCopy(projectRoot, builtInCommandsPath);
+                }
+            });
+        }
+        else if (staleCount > 0) {
+            results.push({
+                name: 'core/commands',
+                status: 'warn',
+                detail: `${staleCount} command(s) out of date — run pennyfarthing update`,
+                fix: () => {
+                    refreshCommandsCopy(projectRoot, builtInCommandsPath);
+                }
+            });
+        }
+        else {
+            results.push({
+                name: 'core/commands',
+                status: 'pass',
+                detail: `${installedEntries.length} commands`
+            });
+        }
+    }
+    // Check skills
+    const skillsDir = join(projectRoot, '.claude/skills');
+    const builtInSkillsPath = join(assetsPath, 'skills');
+    if (!pathExists(skillsDir)) {
+        results.push({
+            name: 'core/skills',
+            status: 'fail',
+            detail: 'Missing .claude/skills/ — run pennyfarthing update'
+        });
+    }
+    else if (pathExists(builtInSkillsPath)) {
+        const sourceSkills = readdirSync(builtInSkillsPath).filter(f => {
+            const fullPath = join(builtInSkillsPath, f);
+            return isDirectory(fullPath) && f.startsWith('pf-');
+        });
+        const installedEntries = readdirSync(skillsDir).filter(f => f.startsWith('pf-'));
+        let missingCount = 0;
+        let symlinkCount = 0;
+        for (const skill of sourceSkills) {
+            const installedPath = join(skillsDir, skill);
+            if (!pathExists(installedPath)) {
+                missingCount++;
+            }
+            else if (isSymlink(installedPath)) {
+                symlinkCount++;
+            }
+        }
+        if (symlinkCount > 0) {
+            results.push({
+                name: 'core/skills',
+                status: 'warn',
+                detail: `${symlinkCount} skill(s) are symlinks — should be copies. Run pennyfarthing update`,
+                fix: () => {
+                    refreshSkillsCopy(projectRoot, builtInSkillsPath);
+                }
+            });
+        }
+        else if (missingCount > 0) {
+            results.push({
+                name: 'core/skills',
+                status: 'warn',
+                detail: `${missingCount} skill(s) missing — run pennyfarthing update`,
+                fix: () => {
+                    refreshSkillsCopy(projectRoot, builtInSkillsPath);
+                }
+            });
+        }
+        else {
+            results.push({
+                name: 'core/skills',
+                status: 'pass',
+                detail: `${installedEntries.length} skills`
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Fix function: refresh commands by cleaning managed entries and copying fresh
+ */
+function refreshCommandsCopy(projectRoot, builtInCommandsPath) {
+    const commandsDir = join(projectRoot, '.claude/commands');
+    ensureDirSync(commandsDir);
+    // Clean all pf-* entries (symlinks or files)
+    const entries = readdirSync(commandsDir).filter(f => f.startsWith('pf-'));
+    for (const entry of entries) {
+        const entryPath = join(commandsDir, entry);
+        try {
+            unlinkSync(entryPath);
+        }
+        catch {
+            // Already gone
+        }
+    }
+    // Copy fresh from source
+    const sourceCommands = readdirSync(builtInCommandsPath).filter(f => f.endsWith('.md') && f.startsWith('pf-'));
+    for (const cmd of sourceCommands) {
+        const sourcePath = join(builtInCommandsPath, cmd);
+        const destPath = join(commandsDir, cmd);
+        try {
+            copyFileSync(sourcePath, destPath);
+        }
+        catch (e) {
+            logger.warning(`Could not copy command ${cmd}: ${e}`);
+        }
+    }
+}
+/**
+ * Fix function: refresh skills by cleaning managed entries and copying fresh
+ */
+function refreshSkillsCopy(projectRoot, builtInSkillsPath) {
+    const skillsDir = join(projectRoot, '.claude/skills');
+    ensureDirSync(skillsDir);
+    // Clean all pf-* entries (symlinks or directories)
+    const entries = readdirSync(skillsDir).filter(f => f.startsWith('pf-'));
+    for (const entry of entries) {
+        const entryPath = join(skillsDir, entry);
+        try {
+            removeSync(entryPath);
+        }
+        catch {
+            // Already gone
+        }
+    }
+    // Copy fresh from source
+    const sourceSkills = readdirSync(builtInSkillsPath).filter(f => {
+        const fullPath = join(builtInSkillsPath, f);
+        return isDirectory(fullPath) && f.startsWith('pf-');
+    });
+    for (const skill of sourceSkills) {
+        const sourcePath = join(builtInSkillsPath, skill);
+        const destPath = join(skillsDir, skill);
+        try {
+            copySync(sourcePath, destPath, { overwrite: true });
+        }
+        catch (e) {
+            logger.warning(`Could not copy skill ${skill}: ${e}`);
+        }
+    }
+}
 /**
  * Check symlinks for symlink installation mode
  */
@@ -321,6 +530,9 @@ function checkUserFiles(projectRoot) {
         // Check SessionStart hooks are configured (critical for PROJECT_ROOT)
         const hookCheck = checkSessionStartHooks(projectRoot, installationType);
         results.push(hookCheck);
+        // Check OTEL auto-configuration (WheelHub auto-start + telemetry env vars)
+        const otelCheck = checkOtelAutoStart(projectRoot, installationType);
+        results.push(otelCheck);
         // Check auto-load-sm hook is configured (auto-invokes /sm on new sessions)
         const autoLoadSmCheck = checkAutoLoadSmHook(projectRoot);
         results.push(autoLoadSmCheck);
@@ -441,11 +653,11 @@ function checkSessionStartHooks(projectRoot, installationType) {
                 }
             };
         }
-        // Check if session-start.sh is configured
+        // Check if session-start hook is configured (pf hooks or legacy .sh)
         const hasSessionStartHook = settings.hooks.SessionStart.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('session-start.sh'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start') || h.command?.includes('session-start.sh'));
             }
             return false;
         });
@@ -453,7 +665,7 @@ function checkSessionStartHooks(projectRoot, installationType) {
             return {
                 name: 'settings/session-start-hook',
                 status: 'fail',
-                detail: 'session-start.sh not configured - PROJECT_ROOT will be undefined',
+                detail: 'session-start hook not configured - PROJECT_ROOT will be undefined',
                 fix: () => {
                     addSessionStartHooks(projectRoot, installationType);
                 }
@@ -473,6 +685,96 @@ function checkSessionStartHooks(projectRoot, installationType) {
         };
     }
 }
+/**
+ * Check that session-start hook uses `pf hooks session-start` (Python version)
+ * which handles WheelHub auto-start + OTEL env var configuration.
+ * Legacy .sh hooks only set 2 of 5 required OTEL vars, breaking telemetry.
+ */
+function checkOtelAutoStart(projectRoot, installationType) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (!settings.hooks?.SessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'No SessionStart hooks — WheelHub auto-start and OTEL not configured',
+            };
+        }
+        // Check if `pf hooks session-start` is used (Python version with full OTEL support)
+        const hasPfHooksSessionStart = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks session-start') || h.command?.includes('pf hooks session-start'));
+            }
+            return false;
+        });
+        if (hasPfHooksSessionStart) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'pass',
+                detail: undefined,
+            };
+        }
+        // Check if using legacy .sh (only sets 2 of 5 OTEL vars)
+        const hasLegacySh = settings.hooks.SessionStart.some((entry) => {
+            if (typeof entry === 'object' && entry !== null) {
+                const hookEntry = entry;
+                return hookEntry.hooks?.some(h => h.command?.includes('session-start.sh'));
+            }
+            return false;
+        });
+        if (hasLegacySh) {
+            return {
+                name: 'settings/otel-auto-start',
+                status: 'warn',
+                detail: 'Using legacy session-start.sh — missing WheelHub auto-start and 3 OTEL env vars. Migrate to `pf hooks session-start`',
+                fix: () => {
+                    migrateSessionStartToPfHooks(projectRoot);
+                },
+            };
+        }
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'session-start hook not found — WheelHub auto-start and OTEL not configured',
+            fix: () => {
+                addSessionStartHooks(projectRoot, installationType);
+            },
+        };
+    }
+    catch {
+        return {
+            name: 'settings/otel-auto-start',
+            status: 'warn',
+            detail: 'Could not parse settings.local.json',
+        };
+    }
+}
+/**
+ * Migrate legacy session-start.sh hooks to `pf hooks session-start`
+ */
+function migrateSessionStartToPfHooks(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (Array.isArray(settings.hooks?.SessionStart)) {
+            for (const entry of settings.hooks.SessionStart) {
+                if (typeof entry === 'object' && entry !== null && Array.isArray(entry.hooks)) {
+                    for (const h of entry.hooks) {
+                        if (h.command?.includes('session-start.sh')) {
+                            h.command = '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start';
+                        }
+                    }
+                }
+            }
+        }
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+    }
+    catch {
+        // Silent fail — doctor will re-report on next run
+    }
+}
 /**
  * Check that auto-load-sm hook is configured in SessionStart
  * This auto-invokes /sm agent on new session start
@@ -619,11 +921,11 @@ function checkStopHook(projectRoot, installationType) {
                 }
             };
         }
-        // Check if question-reflector-check is configured
+        // Check if reflector-check hook is configured (pf hooks or legacy .sh)
         const hasReflectorHook = settings.hooks.Stop.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('question-reflector-check'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks reflector-check') || h.command?.includes('pf hooks reflector-check') || h.command?.includes('question-reflector-check'));
             }
             return false;
         });
@@ -631,7 +933,7 @@ function checkStopHook(projectRoot, installationType) {
             return {
                 name: 'settings/stop-hook',
                 status: 'warn',
-                detail: 'question-reflector-check not configured',
+                detail: 'reflector-check hook not configured',
                 fix: () => {
                     addStopHook(projectRoot, installationType);
                 }
@@ -670,11 +972,11 @@ function checkContextCircuitBreaker(projectRoot, installationType) {
                 }
             };
         }
-        // Check if context-circuit-breaker is configured
+        // Check if context-breaker hook is configured (pf hooks or legacy .sh)
         const hasCircuitBreaker = settings.hooks.PreToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('context-circuit-breaker'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks context-breaker') || h.command?.includes('pf hooks context-breaker') || h.command?.includes('context-circuit-breaker'));
             }
             return false;
         });
@@ -682,7 +984,7 @@ function checkContextCircuitBreaker(projectRoot, installationType) {
             return {
                 name: 'settings/context-circuit-breaker',
                 status: 'warn',
-                detail: 'context-circuit-breaker not configured - context exhaustion protection disabled',
+                detail: 'context-breaker hook not configured - context exhaustion protection disabled',
                 fix: () => {
                     addContextCircuitBreaker(projectRoot, installationType);
                 }
@@ -705,15 +1007,14 @@ function checkContextCircuitBreaker(projectRoot, installationType) {
 /**
  * Fix function: Add context-circuit-breaker hook to PreToolUse in settings.local.json
  */
-function addContextCircuitBreaker(projectRoot, installationType) {
+function addContextCircuitBreaker(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
     const requiredHook = {
         matcher: 'Edit|Write|Bash|Task',
         hooks: [
             {
                 type: 'command',
-                command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/context-circuit-breaker.sh`
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
             }
         ]
     };
@@ -794,15 +1095,14 @@ function checkSchemaValidationHook(projectRoot, installationType) {
 /**
  * Fix function: Add schema-validation hook to PreToolUse in settings.local.json
  */
-function addSchemaValidationHook(projectRoot, installationType) {
+function addSchemaValidationHook(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
     const requiredHook = {
         matcher: 'Write',
         hooks: [
             {
                 type: 'command',
-                command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/schema-validation.sh`
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
             }
         ]
     };
@@ -848,11 +1148,11 @@ function checkPostToolUseHook(projectRoot, installationType) {
                 }
             };
         }
-        // Check if bell-mode-hook is configured
+        // Check if bell-mode hook is configured (pf hooks or legacy .sh)
         const hasBellModeHook = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('bell-mode-hook'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks bell-mode') || h.command?.includes('pf hooks bell-mode') || h.command?.includes('bell-mode-hook'));
             }
             return false;
         });
@@ -860,7 +1160,7 @@ function checkPostToolUseHook(projectRoot, installationType) {
             return {
                 name: 'settings/post-tool-use-hook',
                 status: 'warn',
-                detail: 'bell-mode-hook not configured - bell mode will not work',
+                detail: 'bell-mode hook not configured - bell mode will not work',
                 fix: () => {
                     addPostToolUseHook(projectRoot, installationType);
                 }
@@ -884,15 +1184,14 @@ function checkPostToolUseHook(projectRoot, installationType) {
  * Fix function: Add PostToolUse hook to settings.local.json
  * Required for bell mode to inject queued messages via additionalContext
  */
-function addPostToolUseHook(projectRoot, installationType) {
+function addPostToolUseHook(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
     const requiredHook = {
         matcher: '',
         hooks: [
             {
                 type: 'command',
-                command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/bell-mode-hook.sh`
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
             }
         ]
     };
@@ -938,11 +1237,11 @@ function checkSprintYamlValidationHook(projectRoot, installationType) {
                 }
             };
         }
-        // Check if sprint-yaml-validation is configured
+        // Check if sprint-yaml hook is configured (pf hooks or legacy .sh)
         const hasSprintYamlValidation = settings.hooks.PostToolUse.some((entry) => {
             if (typeof entry === 'object' && entry !== null) {
                 const hookEntry = entry;
-                return hookEntry.hooks?.some(h => h.command?.includes('sprint-yaml-validation'));
+                return hookEntry.hooks?.some(h => h.command?.includes('pf.sh hooks sprint-yaml') || h.command?.includes('pf hooks sprint-yaml') || h.command?.includes('sprint-yaml-validation'));
             }
             return false;
         });
@@ -950,7 +1249,7 @@ function checkSprintYamlValidationHook(projectRoot, installationType) {
             return {
                 name: 'settings/sprint-yaml-validation',
                 status: 'warn',
-                detail: 'sprint-yaml-validation not configured - sprint YAML errors may break SprintPanel',
+                detail: 'sprint-yaml hook not configured - sprint YAML errors may break SprintPanel',
                 fix: () => {
                     addSprintYamlValidationHook(projectRoot, installationType);
                 }
@@ -974,15 +1273,14 @@ function checkSprintYamlValidationHook(projectRoot, installationType) {
  * Fix function: Add sprint-yaml-validation hook to PostToolUse in settings.local.json
  * Validates sprint YAML files after Edit/Write for Cyclist SprintPanel compatibility
  */
-function addSprintYamlValidationHook(projectRoot, installationType) {
+function addSprintYamlValidationHook(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
     const requiredHook = {
         matcher: 'Edit|Write',
         hooks: [
             {
                 type: 'command',
-                command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/sprint-yaml-validation.sh`
+                command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
             }
         ]
     };
@@ -1012,18 +1310,28 @@ function addSprintYamlValidationHook(projectRoot, installationType) {
 /**
  * Fix function: Add Stop hook to settings.local.json
  */
-function addStopHook(projectRoot, installationType) {
+function addStopHook(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
-    const requiredHook = {
-        matcher: '',
-        hooks: [
-            {
-                type: 'command',
-                command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/question-reflector-check.sh`
-            }
-        ]
-    };
+    const requiredHooks = [
+        {
+            matcher: '',
+            hooks: [
+                {
+                    type: 'command',
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
+                }
+            ]
+        },
+        {
+            matcher: '',
+            hooks: [
+                {
+                    type: 'command',
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
+                }
+            ]
+        }
+    ];
     let settings = {};
     if (pathExists(settingsPath)) {
         try {
@@ -1039,11 +1347,11 @@ function addStopHook(projectRoot, installationType) {
     }
     const hooks = settings.hooks;
     if (!hooks.Stop) {
-        hooks.Stop = [requiredHook];
+        hooks.Stop = requiredHooks;
     }
     else if (Array.isArray(hooks.Stop)) {
-        // Prepend the required hook
-        hooks.Stop = [requiredHook, ...hooks.Stop];
+        // Prepend the required hooks
+        hooks.Stop = [...requiredHooks, ...hooks.Stop];
     }
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
 }
@@ -1060,15 +1368,14 @@ function getScriptBasePath(installationType) {
 /**
  * Fix function: Add SessionStart hooks to settings.local.json
  */
-function addSessionStartHooks(projectRoot, installationType) {
+function addSessionStartHooks(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
     const requiredHooks = [
         {
             hooks: [
                 {
                     type: 'command',
-                    command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/session-start.sh`
+                    command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                 }
             ]
         },
@@ -1117,10 +1424,9 @@ function addSessionStartHooks(projectRoot, installationType) {
  * Create settings.local.json from template
  * This is the critical fix for installations that are missing this file
  */
-function createSettingsLocalJson(projectRoot, installationType) {
+function createSettingsLocalJson(projectRoot, _installationType) {
     const settingsPath = join(projectRoot, '.claude/settings.local.json');
-    const scriptBase = getScriptBasePath(installationType);
-    // Create full settings structure matching the template
+    // Create full settings structure matching the template — uses pf hooks commands
     const settings = {
         permissions: {
             allow: [
@@ -1163,7 +1469,7 @@ function createSettingsLocalJson(projectRoot, installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/session-start.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-start'
                         }
                     ]
                 },
@@ -1185,33 +1491,42 @@ function createSettingsLocalJson(projectRoot, installationType) {
                     ]
                 }
             ],
-            PostToolUse: [
+            Stop: [
                 {
                     matcher: '',
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/bell-mode-hook.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check'
                         }
                     ]
                 },
                 {
-                    matcher: 'Edit|Write',
+                    matcher: '',
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/sprint-yaml-validation.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks session-stop'
                         }
                     ]
                 }
             ],
-            Stop: [
+            PostToolUse: [
                 {
                     matcher: '',
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/question-reflector-check.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode'
+                        }
+                    ]
+                },
+                {
+                    matcher: 'Edit|Write',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml'
                         }
                     ]
                 }
@@ -1222,7 +1537,16 @@ function createSettingsLocalJson(projectRoot, installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/pre-edit-check.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks pre-edit-check'
+                        }
+                    ]
+                },
+                {
+                    matcher: 'Write',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation'
                         }
                     ]
                 },
@@ -1231,7 +1555,7 @@ function createSettingsLocalJson(projectRoot, installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/context-warning.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-warning'
                         }
                     ]
                 },
@@ -1240,7 +1564,15 @@ function createSettingsLocalJson(projectRoot, installationType) {
                     hooks: [
                         {
                             type: 'command',
-                            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/hooks/context-circuit-breaker.sh`
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker'
+                        }
+                    ]
+                },
+                {
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks cyclist-pretooluse'
                         }
                     ]
                 }
@@ -1248,7 +1580,7 @@ function createSettingsLocalJson(projectRoot, installationType) {
         },
         statusLine: {
             type: 'command',
-            command: `"$CLAUDE_PROJECT_DIR"/${scriptBase}/misc/statusline.sh`
+            command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
         }
     };
     ensureDirSync(join(projectRoot, '.claude'));
@@ -1809,8 +2141,8 @@ export function checkLegacyStatuslinePath(projectRoot) {
     // or plain paths like .pennyfarthing/scripts/misc/statusline.sh
     const pathMatch = command.match(/(?:\"\$CLAUDE_PROJECT_DIR\"\/)?([^\s"]+)/);
     const currentPath = pathMatch ? pathMatch[1] : command;
-    // Check if it contains the canonical path
-    if (currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
+    // Check if it's the canonical pf hooks command or the legacy .sh path
+    if (command.includes('pf.sh hooks statusline') || command === 'pf hooks statusline' || currentPath.includes('misc/statusline.sh') || command.includes('misc/statusline.sh')) {
         return {
             name: 'settings/statusline-path',
             status: 'pass',
@@ -1831,7 +2163,7 @@ export function checkLegacyStatuslinePath(projectRoot) {
                     const updatedSettings = { ...settings };
                     updatedSettings.statusLine = {
                         type: 'command',
-                        command: `"$CLAUDE_PROJECT_DIR"/${CANONICAL_STATUSLINE_PATH}`
+                        command: '"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh hooks statusline'
                     };
                     writeFileSync(settingsPath, JSON.stringify(updatedSettings, null, 2));
                 }
@@ -1845,6 +2177,82 @@ export function checkLegacyStatuslinePath(projectRoot) {
         detail: 'Configured'
     };
 }
+/**
+ * Check if settings.local.json contains legacy .sh hook commands that should
+ * be migrated to `pf hooks` commands. The .sh scripts still work (they're shims)
+ * but `pf hooks` is the canonical path — faster, no shell indirection.
+ */
+function checkLegacyHookCommands(projectRoot) {
+    const settingsPath = join(projectRoot, '.claude/settings.local.json');
+    if (!pathExists(settingsPath)) {
+        return { name: 'legacy/hook-commands', status: 'pass', detail: 'No settings file' };
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    }
+    catch {
+        return { name: 'legacy/hook-commands', status: 'warn', detail: 'Cannot parse settings.local.json' };
+    }
+    if (!settings.hooks) {
+        return { name: 'legacy/hook-commands', status: 'pass' };
+    }
+    // Count how many hook commands still reference .sh scripts
+    const hooks = settings.hooks;
+    let legacyCount = 0;
+    for (const hookType of ['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse', 'Stop']) {
+        if (!Array.isArray(hooks[hookType]))
+            continue;
+        for (const entry of hooks[hookType]) {
+            if (!entry.hooks)
+                continue;
+            for (const h of entry.hooks) {
+                if (!h.command)
+                    continue;
+                for (const shName of Object.keys(LEGACY_HOOK_MIGRATIONS)) {
+                    if (h.command.includes(shName)) {
+                        legacyCount++;
+                    }
+                }
+            }
+        }
+    }
+    // Also check statusLine
+    const statusLine = settings.statusLine;
+    if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
+        for (const shName of Object.keys(LEGACY_HOOK_MIGRATIONS)) {
+            if (statusLine.command.includes(shName)) {
+                legacyCount++;
+            }
+        }
+    }
+    if (legacyCount === 0) {
+        return { name: 'legacy/hook-commands', status: 'pass' };
+    }
+    return {
+        name: 'legacy/hook-commands',
+        status: 'warn',
+        detail: `${legacyCount} hook(s) still use .sh scripts — should use pf hooks commands`,
+        fix: () => {
+            // Migrate all hook arrays
+            for (const hookType of ['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse', 'Stop']) {
+                if (Array.isArray(hooks[hookType])) {
+                    migrateHookPaths(hooks[hookType]);
+                }
+            }
+            // Migrate statusLine
+            if (statusLine?.command && !statusLine.command.includes('pf.sh hooks statusline') && statusLine.command !== 'pf hooks statusline') {
+                for (const [shName, pfCommand] of Object.entries(LEGACY_HOOK_MIGRATIONS)) {
+                    if (statusLine.command.includes(shName)) {
+                        statusLine.command = pfCommand;
+                        break;
+                    }
+                }
+            }
+            writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+        }
+    };
+}
 /**
  * Check file layout — validate files are at correct .pennyfarthing/ locations.
  * Flags old .claude/ locations with migration instructions.