5-phase-workflow 1.4.1 → 1.4.3

package/src/commands/5/update.md

@@ -0,0 +1,17 @@
+---
+name: 5:update
+description: Update the 5-Phase Workflow to the latest version
+allowed-tools: Bash
+context: inherit
+user-invocable: true
+---
+
+# Update 5-Phase Workflow
+
+Run the upgrade command to update to the latest version:
+
+```bash
+npx 5-phase-workflow --upgrade
+```
+
+After the upgrade completes, confirm the new version was installed by checking `.claude/.5/version.json`.

package/src/hooks/check-updates.js

@@ -53,24 +53,21 @@ async function checkForUpdates(workspaceDir) {
 
   // Update last check time
   versionData.updateCheckLastRun = new Date().toISOString();
-  fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
 
   // Compare versions
   const installed = versionData.installedVersion;
   const latestVersion = await getLatestVersion();
 
-  if (!latestVersion || installed === latestVersion) {
-    // No update available
-    process.exit(0);
-  }
-
-  // Check if update is available (installed < latest)
-  if (compareVersions(installed, latestVersion) < 0) {
-    // Show update notification
-    console.log(`\n\x1b[34mℹ\x1b[0m Update available: ${installed} → ${latestVersion}`);
-    console.log(`  Run: \x1b[1mnpx 5-phase-workflow --upgrade\x1b[0m\n`);
+  if (latestVersion && compareVersions(installed, latestVersion) < 0) {
+    // Update available — persist for statusline to display
+    versionData.latestAvailableVersion = latestVersion;
+  } else {
+    // No update (or network failure) — clear any stale value
+    versionData.latestAvailableVersion = null;
   }
 
+  // Single consolidated write
+  fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
   process.exit(0);
 }
 

package/src/hooks/plan-guard.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+// Plan Guard - PreToolUse Hook
+// Prevents LLM breakout from planning phases by blocking:
+// - Task agents other than Explore (when not in implementation mode)
+// - Write operations outside .5/ (when not in implementation mode)
+//
+// Planning mode is detected by absence of any state.json in .5/features/.
+// Once state.json exists (created in Phase 3), the feature has passed planning
+// and all tools are allowed (implementation, verification, review phases).
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || '';
+
+    // Short-circuit: only check Task and Write tools
+    if (toolName !== 'Task' && toolName !== 'Write') {
+      process.exit(0);
+    }
+
+    const workspaceDir = data.cwd || data.workspace?.current_dir || process.cwd();
+    const toolInput = data.tool_input || {};
+
+    // Check if any feature is in implementation mode
+    if (isImplementationMode(workspaceDir)) {
+      process.exit(0); // All tools allowed during implementation
+    }
+
+    // Planning mode enforcement
+    if (toolName === 'Task') {
+      const agentType = toolInput.subagent_type || '';
+      if (agentType && agentType !== 'Explore') {
+        process.stderr.write(
+          `BLOCKED: Only Explore agents are allowed during planning phases. ` +
+          `Attempted: subagent_type="${agentType}". ` +
+          `To use other agent types, start implementation with /5:implement-feature.`
+        );
+        process.exit(2);
+      }
+    }
+
+    if (toolName === 'Write') {
+      const filePath = toolInput.file_path || '';
+      if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
+        process.stderr.write(
+          `BLOCKED: Writing outside .5/ is not allowed during planning phases. ` +
+          `Attempted: "${filePath}". ` +
+          `Planning commands may only write to .5/features/. ` +
+          `To write source files, start implementation with /5:implement-feature.`
+        );
+        process.exit(2);
+      }
+    }
+
+    process.exit(0);
+  } catch (e) {
+    // Silent failure - don't block on parse errors
+    process.exit(0);
+  }
+});
+
+function isInsideDotFive(filePath, workspaceDir) {
+  const resolved = path.resolve(workspaceDir, filePath);
+  const dotFiveDir = path.join(workspaceDir, '.5');
+  const claudeDotFiveDir = path.join(workspaceDir, '.claude', '.5');
+  return resolved.startsWith(dotFiveDir + path.sep) ||
+         resolved.startsWith(claudeDotFiveDir + path.sep) ||
+         resolved === dotFiveDir ||
+         resolved === claudeDotFiveDir;
+}
+
+function isImplementationMode(workspaceDir) {
+  // If any state.json exists, the feature has passed planning phases.
+  // state.json is created in Phase 3 (implement-feature) and persists
+  // through Phase 4 (verify) and Phase 5 (review) with status "completed".
+  const featuresDir = path.join(workspaceDir, '.claude', '.5', 'features');
+
+  if (!fs.existsSync(featuresDir)) {
+    return false;
+  }
+
+  try {
+    const features = fs.readdirSync(featuresDir, { withFileTypes: true });
+    for (const entry of features) {
+      if (!entry.isDirectory()) continue;
+      const stateFile = path.join(featuresDir, entry.name, 'state.json');
+      if (fs.existsSync(stateFile)) {
+        return true;
+      }
+    }
+  } catch (e) {
+    // Can't read features dir - assume planning mode (safe default)
+  }
+
+  return false;
+}

package/src/hooks/statusline.js

@@ -43,11 +43,36 @@ process.stdin.on('end', () => {
     // Shorten directory path for display
     const shortDir = dir.replace(os.homedir(), '~');
 
-    // Build and output statusline: model | directory | context
-    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}`;
+    // Check for available update
+    let updateIndicator = '';
+    try {
+      const versionFile = path.join(dir, '.claude', '.5', 'version.json');
+      const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+      const latest = versionData.latestAvailableVersion;
+      const installed = versionData.installedVersion;
+      if (latest && installed && compareVersions(installed, latest) < 0) {
+        updateIndicator = ` | \x1b[33m↑${latest} → /5:update\x1b[0m`;
+      }
+    } catch (e) {
+      // No version file or parse error — no indicator
+    }
+
+    // Build and output statusline: model | directory | context | update
+    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}${updateIndicator}`;
     process.stdout.write(statusline);
 
   } catch (e) {
     // Silent fail - don't break statusline on parse errors
   }
-});
+});
+
+// Compare semver versions: returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (parts1[i] > parts2[i]) return 1;
+    if (parts1[i] < parts2[i]) return -1;
+  }
+  return 0;
+}

package/src/settings.json

@@ -15,6 +15,18 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/plan-guard.js",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }