odd-studio 3.7.4 → 3.7.6

package/README.md

@@ -72,7 +72,6 @@ That single command:
 - Scaffolds your project structure (`docs/`, `.odd/`, instruction files)
 - Installs the ODD harness into the matching project-local agent surface (`.claude/`, `.opencode/`, or `plugins/odd-studio/`)
 - Configures odd-flow MCP server for cross-session memory in the matching agent config
-- Optionally installs Checkpoint security scanning (you'll be asked)
 - Initialises git with an initial commit
 
 **Then open your project in your AI coding agent and start ODD:**
@@ -150,9 +149,7 @@ ODD Studio installs safety gates that run automatically throughout your build. T
 | Brief gate | Before agent spawning | Blocks build agents until the session brief is confirmed |
 | Swarm write gate | Before file writes | Blocks writes during swarm builds unless from an assigned agent |
 | Verify gate | Before state edits | Blocks premature outcome confirmation |
-| Checkpoint gate | Before confirm/commit | Blocks verification and commits until a fresh security scan clears the latest build changes |
 | odd-flow build gate | Before agent spawning | Blocks builds without odd-flow sync |
-| odd-flow commit gate | Before git commit | Blocks commits during build without odd-flow sync |
 | Outcome quality | After writing outcomes | Checks all 6 fields present; flags banned technical vocabulary |
 | Persona quality | After writing personas | Checks all 7 dimensions are present |
 | Code elegance | After writing source files | Checks file length against ODD limits |

package/bin/commands/init.js

@@ -29,7 +29,7 @@ export function registerInit(program, deps) {
       const targetDir = projectName ? path.resolve(process.cwd(), projectName) : process.cwd();
       const resolvedName = projectName || path.basename(process.cwd());
       const agentLabel = getAgentLabel(agent);
-      const totalSteps = 5;
+      const totalSteps = 4;
 
       console.log(chalk.bold(`  Setting up: ${chalk.cyan(resolvedName)}`) + chalk.dim(` (${agentLabel})\n`));
 
@@ -47,7 +47,6 @@ export function registerInit(program, deps) {
 
       await installSkills({ PACKAGE_ROOT, isClaude, isOpenCode, options, print, targetDir, totalSteps });
       await installHooks({ PACKAGE_ROOT, isClaude, isOpenCode, isCodex, options, print, targetDir, totalSteps });
-      await maybeInstallCheckpoint({ options, print, targetDir, totalSteps });
       await configureMcp({ agent, options, print, targetDir, totalSteps });
 
       print.blank();
@@ -142,51 +141,14 @@ async function installHooks(context) {
   }
 }
 
-async function maybeInstallCheckpoint({ options, print, targetDir, totalSteps }) {
-  let installCheckpoint = false;
-  if (!options.yes) {
-    const { default: inquirer } = await import('inquirer');
-    const answer = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'checkpoint',
-      message: 'Install Checkpoint security scanning into this project?',
-      default: false,
-    }]);
-    installCheckpoint = answer.checkpoint;
-  }
-
-  if (!installCheckpoint) {
-    print.step(4, totalSteps, 'Skipping Checkpoint security scanning');
-    print.info('Enable later: npx @darrenjcoxon/vibeguard --install-tools');
-    return;
-  }
-
-  print.step(4, totalSteps, 'Installing Checkpoint security scanning...');
-  const spinner = ora({ text: '', indent: 4 }).start();
-  try {
-    const { execFileSync } = await import('child_process');
-    execFileSync('npx', ['-y', '@darrenjcoxon/vibeguard', '--install-tools'], {
-      cwd: targetDir,
-      stdio: 'inherit',
-      timeout: 60000,
-    });
-    spinner.stop();
-    print.ok('Checkpoint security tools installed');
-  } catch {
-    spinner.stop();
-    print.warn('Checkpoint tools could not be installed');
-    print.info('Run: npx @darrenjcoxon/vibeguard --install-tools  to enable later');
-  }
-}
-
 async function configureMcp({ agent, options, print, targetDir, totalSteps }) {
   if (options.skipMcp) {
-    print.step(5, totalSteps, 'Skipping odd-flow MCP server (--skip-mcp)');
+    print.step(4, totalSteps, 'Skipping odd-flow MCP server (--skip-mcp)');
     print.info('odd-flow swarm coordination will not be available.');
     return;
   }
 
-  print.step(5, totalSteps, 'Configuring odd-flow memory server...');
+  print.step(4, totalSteps, 'Configuring odd-flow memory server...');
   const spinner = ora({ text: '', indent: 4 }).start();
   try {
     const { default: setupMcp } = await import('../../scripts/setup-mcp.js');

package/bin/commands/status.js

@@ -28,9 +28,6 @@ export function registerStatus(program, deps) {
         console.log(chalk.bold('  Debug:   ') + (state.debugStrategy || 'strategy not set'));
         console.log(chalk.bold('  Target:  ') + (state.debugTarget || 'target not set'));
       }
-      if (state.currentPhase === 'build') {
-        console.log(chalk.bold('  Checkpoint: ') + (state.checkpointStatus || 'unknown'));
-      }
       print.blank();
 
       if (state.personas?.length) {

package/bin/odd-studio.js

@@ -15,7 +15,7 @@ import { registerUninstall } from './commands/uninstall.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
-const pkg = require('../package.json'); // v3.6.0
+const pkg = require('../package.json');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const deps = { PACKAGE_ROOT, print };

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.6.0",
+  "version": "3.7.6",
   "description": "Outcome-Driven Development planning and build harness for domain experts building serious software with AI.",
   "author": {
     "name": "ODD Studio"

package/codex-plugin/hooks.json

@@ -15,7 +15,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write",
         "hooks": [
           {
             "type": "command",
@@ -32,15 +32,19 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Edit",
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/odd-studio.sh checkpoint-gate"
+            "command": "./hooks/odd-studio.sh swarm-write"
           },
           {
             "type": "command",
-            "command": "./hooks/odd-studio.sh commit-gate"
+            "command": "./hooks/odd-studio.sh verify-gate"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh confirm-gate"
           }
         ]
       }
@@ -57,12 +61,26 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Write",
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/odd-studio.sh checkpoint-validate"
-          },
+            "command": "./hooks/odd-studio.sh plan-complete-gate"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh plan-complete-gate"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
           {
             "type": "command",
             "command": "./hooks/odd-studio.sh session-save"

package/hooks/odd-studio.sh

@@ -136,6 +136,12 @@ build-gate)
   [ "$TOOL_NAME" = "Agent" ] || exit 0
   [ "$CURRENT_PHASE" = "build" ] || exit 0
 
+  # Quick-fix bypass: orchestrator can dispatch agents for small fixes without full swarm init.
+  # Marker has 1h TTL and must be explicitly created via `touch .odd/.odd-quick-fix`.
+  if marker_valid ".odd/.odd-quick-fix" 3600; then
+    exit 0
+  fi
+
   # Allow brief-generation and sync agents through
   AGENT_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' | head -c 300)
   if echo "$AGENT_PROMPT" | grep -qiE '(session.brief|session-brief|generate.*brief|odd-sync|fix.*hook|update.*hook)'; then
@@ -179,6 +185,13 @@ swarm-write)
     exit 0
   fi
 
+  # Quick-fix bypass: orchestrator can edit source directly for small fixes.
+  # Marker has 1h TTL and must be explicitly created via `touch .odd/.odd-quick-fix`.
+  # Use for single-file typo/type fixes where full swarm ceremony is overkill.
+  if marker_valid ".odd/.odd-quick-fix" 3600; then
+    exit 0
+  fi
+
   # Gate 2: Agent write token must be fresh (120s TTL)
   # Only Task agents create this token — the orchestrator must NOT.
   if ! marker_valid ".odd/.odd-flow-agent-token" 120; then
@@ -226,8 +239,6 @@ verify-gate)
     exit 2
   fi
 
-  # Checkpoint pre-check removed in v3.7.3 (see checkpoint-gate note below).
-
   VERIFIED_CONFIRMED=$(get_state_field "verificationConfirmed")
   if [ "$VERIFIED_CONFIRMED" != "true" ]; then
     echo "ODD STUDIO [verify-gate]: Cannot mark NEW outcomes as verified." >&2
@@ -237,14 +248,6 @@ verify-gate)
   exit 0
   ;;
 
-# ─────────────────────────────────────────────────────────────────────────────
-# checkpoint-gate — REMOVED in v3.7.3
-# Vibeguard/Checkpoint was treating dependency-lockfile CVEs as equivalent to
-# code vulnerabilities, making every commit impossible while any transitive
-# dep had an open advisory. Re-introduce only with a scoped scanner that
-# ignores lockfile-only findings.
-# ─────────────────────────────────────────────────────────────────────────────
-
 # ─────────────────────────────────────────────────────────────────────────────
 # PreToolUse: Edit|Write — blocks briefConfirmed without odd-flow store
 # ─────────────────────────────────────────────────────────────────────────────
@@ -263,14 +266,6 @@ confirm-gate)
   exit 0
   ;;
 
-# ─────────────────────────────────────────────────────────────────────────────
-# commit-gate — REMOVED in v3.7.4
-# The dirty/ready marker treadmill was creating more friction than value.
-# State persistence to odd-flow is now the orchestrator's responsibility at
-# genuine persistence points (session end, outcome verified) rather than a
-# hard-block on every commit.
-# ─────────────────────────────────────────────────────────────────────────────
-
 # ─────────────────────────────────────────────────────────────────────────────
 # UserPromptSubmit — warns every turn if build phase without swarm
 # ─────────────────────────────────────────────────────────────────────────────
@@ -331,10 +326,6 @@ session-save)
   exit 0
   ;;
 
-# ─────────────────────────────────────────────────────────────────────────────
-# checkpoint-validate — REMOVED in v3.7.3 (see checkpoint-gate note above)
-# ─────────────────────────────────────────────────────────────────────────────
-
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: Write|Edit state.json — blocks phase transition without Steps 9, 9b, 9d
 # ─────────────────────────────────────────────────────────────────────────────
@@ -376,17 +367,9 @@ plan-complete-gate)
   exit 0
   ;;
 
-# ─────────────────────────────────────────────────────────────────────────────
-# state-dirty-mark — REMOVED in v3.7.4 (dirty/ready treadmill eliminated)
-# ─────────────────────────────────────────────────────────────────────────────
-
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: mcp__odd-flow__memory_store — brief-stored marker only
 # ─────────────────────────────────────────────────────────────────────────────
-# v3.7.4: the state-ready / dirty treadmill has been removed. This hook now
-# only creates the brief-stored marker after a session brief is persisted.
-# odd-project-state stores are logged but do not touch any marker — state
-# persistence is no longer gated by a marker state machine.
 store-validate)
   [ "$TOOL_NAME" = "mcp__odd-flow__memory_store" ] || exit 0
   [ "$CURRENT_PHASE" = "build" ] || exit 0
@@ -489,7 +472,6 @@ code-quality)
 
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: Write|Edit — security baseline warnings (stderr, non-blocking)
-# Checkpoint dirty-marking was removed in v3.7.3 along with checkpoint-gate.
 # ─────────────────────────────────────────────────────────────────────────────
 security-quality)
   [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ] || exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.7.4",
+  "version": "3.7.6",
   "description": "Outcome-Driven Development for AI coding agents — a planning and build harness for domain experts building serious software with AI. Works with Claude Code, OpenCode, and Codex.",
   "keywords": [
     "claude-code",
@@ -47,7 +47,6 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.2.0",
-    "inquirer": "^10.0.0",
     "ora": "^8.0.1"
   },
   "devDependencies": {

package/plugins/plugin-gates.js

@@ -1,7 +1,56 @@
+import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
-import { checkBriefQuality, checkCodeElegance, checkOutcomeQuality, checkPersonaQuality, checkSecurityBaseline } from './plugin-quality-checks.js';
-import { isBriefFile, isOutcomeFile, isPersonaFile, isSourceCodePath, isSrcFile } from './plugin-paths.js';
-import { markerExists, markerValid, removeMarker, touchMarker } from './plugin-markers.js';
+import {
+  checkBriefQuality,
+  checkCodeElegance,
+  checkOutcomeQuality,
+  checkPersonaQuality,
+  checkSecurityBaseline,
+} from './plugin-quality-checks.js';
+import {
+  isBriefFile,
+  isOutcomeFile,
+  isPersonaFile,
+  isSourceCodePath,
+  isSrcFile,
+} from './plugin-paths.js';
+import { markerExists, markerValid, touchMarker } from './plugin-markers.js';
+
+const HALF_HOUR = 1800000;
+const TWO_HOURS = 7200000;
+const ONE_DAY = 86400000;
+const ONE_HOUR = 3600000;
+const TWO_MINUTES = 120000;
+
+function readMarker(name) {
+  return resolve(process.cwd(), '.odd', name);
+}
+
+function isVerifiedUpgrade(event, filePath) {
+  if (!filePath.includes('state.json')) return false;
+
+  if (event.tool?.name === 'Write') {
+    const next = event.input?.content || '';
+    const nextCount = (next.match(/"buildStatus"\s*:\s*"verified"/g) || []).length;
+    const prevCount = existsSync(filePath)
+      ? (readFileSync(filePath, 'utf8').match(/"buildStatus"\s*:\s*"verified"/g) || []).length
+      : 0;
+    return nextCount > prevCount;
+  }
+
+  const previous = event.input?.old_string || '';
+  const next = event.input?.new_string || '';
+  return (next.match(/"verified"/g) || []).length > (previous.match(/"verified"/g) || []).length;
+}
+
+function blocksBuildPhaseTransition(newContent) {
+  if (!/"currentPhase"\s*:\s*"build"/.test(newContent)) return false;
+  return (
+    !/"techStackDecided"\s*:\s*true/.test(newContent) ||
+    !/"designApproachDecided"\s*:\s*true/.test(newContent) ||
+    !/"architectureDocGenerated"\s*:\s*true/.test(newContent)
+  );
+}
 
 export function createBeforeHook(readState) {
   return (event) => {
@@ -12,63 +61,58 @@ export function createBeforeHook(readState) {
     const filePath = event.input?.file_path || event.input?.path || '';
 
     if (toolName === 'Agent' && state.currentPhase === 'build') {
-      if (!state.briefConfirmed) {
-        const prompt = (event.input?.prompt || '').slice(0, 200).toLowerCase();
-        if (!prompt.match(/session.brief|session-brief|generate.*brief|write.*brief/)) {
-          return { blocked: true, message: 'ODD BRIEF GATE: Build agents blocked. The session brief has not been confirmed. Run /odd-sync first.' };
-        }
+      const prompt = (event.input?.prompt || '').slice(0, 300).toLowerCase();
+
+      if (!state.briefConfirmed && !prompt.match(/session.brief|session-brief|generate.*brief|write.*brief/)) {
+        return { blocked: true, message: 'ODD BRIEF GATE: Build agents blocked — session brief not confirmed. Generate and confirm the brief first.' };
       }
 
-      if (state.briefConfirmed && !markerValid(resolve(process.cwd(), '.odd', '.odd-flow-phase-synced'), 1800000)) {
+      if (state.briefConfirmed && !markerValid(readMarker('.odd-flow-phase-synced'), HALF_HOUR)) {
         return { blocked: true, message: 'ODD BUILD GATE: Brief confirmed but odd-flow not synced. Run /odd-sync first.' };
       }
 
-      if (state.briefConfirmed && !markerValid(resolve(process.cwd(), '.odd', '.odd-flow-agents-ready'), 7200000)) {
-        const prompt = (event.input?.prompt || '').slice(0, 300).toLowerCase();
-        if (!prompt.match(/session.brief|session-brief|generate.*brief|odd-sync|fix.*hook|update.*hook/)) {
-          return { blocked: true, message: 'ODD BUILD GATE: Task agents blocked — odd-flow swarm not initialised. Run the full swarm init sequence.' };
-        }
+      if (markerValid(readMarker('.odd-quick-fix'), ONE_HOUR)) return;
+
+      if (
+        state.briefConfirmed &&
+        !markerValid(readMarker('.odd-flow-agents-ready'), TWO_HOURS) &&
+        !prompt.match(/session.brief|session-brief|generate.*brief|odd-sync|fix.*hook|update.*hook/)
+      ) {
+        return { blocked: true, message: 'ODD BUILD GATE: Task agents blocked — odd-flow swarm not initialised. Run the full swarm init sequence.' };
       }
     }
 
     if ((toolName === 'Write' || toolName === 'Edit') && state.currentPhase === 'build' && isSourceCodePath(filePath)) {
-      if (!markerValid(resolve(process.cwd(), '.odd', '.odd-flow-swarm-active'), 3600000)) {
+      if (!markerValid(readMarker('.odd-flow-swarm-active'), ONE_DAY)) {
         return { blocked: true, message: `ODD SWARM WRITE GATE: Source writes blocked — no active build session. Run *build first. File: ${filePath}` };
       }
-      if (!markerValid(resolve(process.cwd(), '.odd', '.odd-flow-agent-token'), 120000)) {
-        return { blocked: true, message: `ODD SWARM WRITE GATE: Source writes blocked — no agent write token. Only Task agents can write source code, not the orchestrator. Dispatch work to agents instead. File: ${filePath}` };
+
+      if (state.debugSession || markerValid(readMarker('.odd-quick-fix'), ONE_HOUR)) return;
+
+      if (!markerValid(readMarker('.odd-flow-agent-token'), TWO_MINUTES)) {
+        return { blocked: true, message: `ODD SWARM WRITE GATE: Source writes blocked — no agent write token. Only Task agents can write source code, not the orchestrator. File: ${filePath}` };
       }
     }
 
     if ((toolName === 'Edit' || toolName === 'Write') && filePath.includes('state.json')) {
       const newContent = event.input?.new_string || event.input?.content || '';
-      if (newContent.includes('"verified"') && state.buildMode === 'debug') {
-        return { blocked: true, message: 'ODD VERIFY GATE: Cannot mark outcomes as verified while debug mode is active. Return buildMode to verify first.' };
-      }
-      if (newContent.includes('"verified"') && (markerExists('.checkpoint-dirty') || !markerExists('.checkpoint-clear'))) {
-        return { blocked: true, message: 'ODD CHECKPOINT GATE: Cannot mark outcomes as verified until a fresh Checkpoint scan clears the latest source changes.' };
-      }
-      if (newContent.includes('"verified"') && !state.verificationConfirmed) {
-        return { blocked: true, message: 'ODD VERIFY GATE: Cannot mark outcomes as verified. Walk through the verification checklist first.' };
-      }
-      if (/"briefConfirmed"\s*:\s*true/.test(newContent) && !markerExists('.odd-flow-brief-stored')) {
-        return { blocked: true, message: 'ODD CONFIRM GATE: Brief not stored in odd-flow memory. Store it first.' };
+
+      if (blocksBuildPhaseTransition(newContent)) {
+        return { blocked: true, message: 'ODD PLAN COMPLETE GATE: Finish technical architecture, design approach, and architecture docs before entering build phase.' };
       }
-    }
 
-    if (toolName === 'Bash' && state.currentPhase === 'build') {
-      const cmd = event.input?.command || '';
-      if (/git\s+commit/.test(cmd)) {
+      if (isVerifiedUpgrade(event, filePath)) {
         if (state.buildMode === 'debug') {
-          return { blocked: true, message: 'ODD DEBUG GATE: Commits are blocked while debug mode is active. Finish the fix and return to verification first.' };
-        }
-        if (markerExists('.checkpoint-dirty') || !markerExists('.checkpoint-clear')) {
-          return { blocked: true, message: 'ODD CHECKPOINT GATE: Commit blocked — run Checkpoint and clear the latest source changes first.' };
+          return { blocked: true, message: 'ODD VERIFY GATE: Cannot mark outcomes as verified while debug mode is active. Return to verification first.' };
         }
-        if (!markerExists('.odd-flow-state-ready')) {
-          return { blocked: true, message: 'ODD COMMIT GATE: Commit blocked — odd-flow state not stored. Call mcp__odd-flow__memory_store key=odd-project-state first.' };
+
+        if (!state.verificationConfirmed) {
+          return { blocked: true, message: 'ODD VERIFY GATE: Cannot mark outcomes as verified. Walk through the verification checklist first.' };
         }
-        removeMarker('.odd-flow-state-ready');
+      }
+
+      if (/"briefConfirmed"\s*:\s*true/.test(newContent) && !markerExists('.odd-flow-brief-stored')) {
+        return { blocked: true, message: 'ODD CONFIRM GATE: Brief not stored in odd-flow memory. Store it first.' };
       }
     }
   };
@@ -89,44 +133,26 @@ export function createAfterHook(readState, readLastCommit, writeState) {
     if (toolName === 'Write' && isBriefFile(filePath)) warnings.push(...checkBriefQuality(filePath));
 
     const state = readState();
-    if ((toolName === 'Write' || toolName === 'Edit') && isSrcFile(filePath) && state?.currentPhase === 'build') {
-      touchMarker('.checkpoint-dirty');
-      removeMarker('.checkpoint-clear');
-    }
 
     if (toolName === 'Bash') {
       const cmd = event.input?.command || '';
-      const state = readState();
-      if (state?.currentPhase === 'build' && /@darrenjcoxon\/vibeguard|vibeguard/.test(cmd) && event.exitCode === 0) {
-        touchMarker('.checkpoint-clear');
-        removeMarker('.checkpoint-dirty');
-      }
-      if (/git\s+commit/.test(cmd) && event.exitCode === 0) {
-        if (state) {
-          state.lastCommit = readLastCommit();
-          state.lastSaved = new Date().toISOString();
-          state.lastCommitAt = state.lastSaved;
-          writeState(state);
-          touchMarker('.odd-flow-phase-synced');
-          touchMarker('.odd-flow-state-dirty');
-        }
+      if (/git\s+commit/.test(cmd) && event.exitCode === 0 && state) {
+        state.lastCommit = readLastCommit();
+        state.lastSaved = new Date().toISOString();
+        state.lastCommitAt = state.lastSaved;
+        writeState(state);
+        touchMarker('.odd-flow-phase-synced');
       }
     }
 
-    if (toolName === 'mcp__odd-flow__memory_store') {
-      const state = readState();
-      if (state?.currentPhase === 'build' && event.input?.key === 'odd-project-state') {
-        touchMarker('.odd-flow-state-ready');
-        removeMarker('.odd-flow-state-dirty');
-      }
+    if (toolName === 'mcp__odd-flow__memory_store' && state?.currentPhase === 'build') {
+      if (event.input?.key?.startsWith('odd-session-brief-')) touchMarker('.odd-flow-brief-stored');
     }
 
-    if (toolName === 'mcp__odd-flow__coordination_sync') {
-      const state = readState();
-      if (state?.currentPhase === 'build') {
-        touchMarker('.odd-flow-agents-ready');
-        touchMarker('.odd-flow-phase-synced');
-      }
+    if (toolName === 'mcp__odd-flow__coordination_sync' && state?.currentPhase === 'build') {
+      touchMarker('.odd-flow-swarm-active');
+      touchMarker('.odd-flow-agents-ready');
+      touchMarker('.odd-flow-phase-synced');
     }
 
     if (warnings.length > 0) return { warnings };
@@ -137,20 +163,19 @@ export function createChatHook(readState) {
   return () => {
     const state = readState();
     if (!state || state.currentPhase !== 'build') return;
+
     if (state.buildMode === 'debug') {
-      return { warnings: [`ODD DEBUG MODE: ${state.debugStrategy || 'Choose a strategy'} — keep the work inside the active outcome and return to verification when the fix is ready.`] };
-    }
-    if (markerExists('.odd-flow-state-dirty')) {
-      return { warnings: ['ODD STATE NOT SAVED: A git commit was made but state was not stored to odd-flow. Store it now.'] };
-    }
-    if (markerExists('.checkpoint-dirty')) {
-      return { warnings: ['ODD CHECKPOINT DIRTY: Source changes have not passed a fresh security scan yet. Run Checkpoint before verification or commit.'] };
+      return {
+        warnings: [
+          `ODD DEBUG MODE: ${state.debugStrategy || 'Choose a strategy'} — keep the fix inside the active outcome and return to verification when ready.`,
+        ],
+      };
     }
 
-    const swarmPath = resolve(process.cwd(), '.odd', '.odd-flow-swarm-active');
-    if (!markerValid(swarmPath, 3600000)) {
+    const swarmPath = readMarker('.odd-flow-swarm-active');
+    if (!markerValid(swarmPath, ONE_DAY)) {
       const stale = markerExists('.odd-flow-swarm-active') ? ' (marker expired — re-init required)' : '';
-      return { warnings: [`ODD SWARM GUARD: You are in build phase. The odd-flow swarm must be initialised before any build action.${stale}`] };
+      return { warnings: [`ODD SWARM GUARD: You are in build phase. The odd-flow swarm must be initialised before build work.${stale}`] };
     }
   };
 }

package/scripts/command-definitions.js

@@ -10,76 +10,36 @@ export const COMMANDS = [
   {
     name: 'odd-plan',
     description: 'Start or continue the planning phase — personas, outcomes, contracts, and Master Implementation Plan',
-    body: 'You are executing the ODD Studio `*plan` command.\n\nRead this file now:\n- `.opencode/odd/SKILL.md` — the full ODD Studio coach and planning protocol\n\nThen execute the `*plan` protocol exactly as documented, starting from the state check.',
+    body: 'You are executing the ODD Studio `*plan` command.\n\nRead this file now:\n- `.opencode/odd/odd-plan/SKILL.md` — the planning command guide\n\nThen execute the `*plan` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-build',
     description: 'Start or continue a build session — reads project state and executes the build protocol',
-    body: 'You are executing the ODD Studio `*build` command.\n\nRead these two files now:\n1. `.opencode/odd/SKILL.md` — the full ODD Studio coach and build protocol\n2. `.opencode/odd/docs/build/build-protocol.md` — the Build Protocol detail\n\nThen execute the `*build` protocol exactly as documented in those files, starting from the state check.',
+    body: 'You are executing the ODD Studio `*build` command.\n\nRead this file now:\n- `.opencode/odd/odd-build/SKILL.md` — the build command guide\n\nThen execute the `*build` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-debug',
     description: 'Start or continue an in-flow ODD debugging session — selects the correct debug approach and returns to verification',
-    body: 'You are executing the ODD Studio `*debug` command.\n\nRead these two files now:\n1. `.opencode/odd/SKILL.md` — the full ODD Studio coach and build protocol\n2. `.opencode/odd/docs/build/debug-protocol.md` — the Debug Protocol detail\n\nBefore you inspect code or propose a fix, classify the failure into exactly one strategy:\n- `ui-behaviour` for visible interface-only failures\n- `full-stack` for browser-to-route-to-service-to-data failures\n- `auth-security` for auth, permissions, trust boundaries, uploads, or webhooks\n- `integration-contract` for producer-consumer or contract mismatches\n- `background-process` for jobs, queues, webhooks, or async delivery\n- `performance-state` for stale data, races, caching, or timing-sensitive defects\n\nIf the evidence is mixed, gather more evidence first and then choose the narrowest matching strategy. Do not guess. Do not apply a quick fix. Then execute the `*debug` protocol exactly as documented in those files, starting from the state check and recording the chosen strategy in `.odd/state.json` before any fix is attempted.',
+    body: 'You are executing the ODD Studio `*debug` command.\n\nRead this file now:\n- `.opencode/odd/odd-debug/SKILL.md` — the debug command guide\n\nThen execute the `*debug` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-swarm',
     description: 'Build all independent outcomes in the current phase simultaneously using odd-flow parallel agents',
-    body: 'You are executing the ODD Studio `*swarm` command.\n\nRead these two files now:\n1. `.opencode/odd/SKILL.md` — the full ODD Studio coach and build protocol\n2. `.opencode/odd/docs/build/build-protocol.md` — the Build Protocol detail\n\nThen execute the `*swarm` protocol exactly as documented in those files, starting from the state check.',
+    body: 'You are executing the ODD Studio `*swarm` command.\n\nRead this file now:\n- `.opencode/odd/odd-swarm/SKILL.md` — the swarm command guide\n\nThen execute the `*swarm` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-status',
     description: 'Show full project state, phase progress, and what comes next',
-    body: 'You are executing the ODD Studio `*status` command.\n\nRead this file now:\n- `.opencode/odd/SKILL.md` — the full ODD Studio coach\n\nThen execute the `*status` protocol exactly as documented, starting from the state check.',
+    body: 'You are executing the ODD Studio `*status` command.\n\nRead this file now:\n- `.opencode/odd/odd-status/SKILL.md` — the status command guide\n\nThen execute the `*status` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-deploy',
     description: 'Verify all outcomes are confirmed, then deploy the current phase to production',
-    body: 'You are executing the ODD Studio `*deploy` command.\n\nRead this file now:\n- `.opencode/odd/SKILL.md` — the full ODD Studio coach\n\nThen execute the `*deploy` protocol exactly as documented, starting from the state check.',
+    body: 'You are executing the ODD Studio `*deploy` command.\n\nRead this file now:\n- `.opencode/odd/odd-deploy/SKILL.md` — the deploy command guide\n\nThen execute the `*deploy` protocol exactly as documented, starting from the state check.',
   },
   {
     name: 'odd-sync',
     description: 'Sync ODD project state to odd-flow memory. MUST be run before building.',
-    body: `You are syncing ODD project state to odd-flow memory. Follow these steps exactly:
-
-## Step 1 — Read project state
-
-Read \`.odd/state.json\` and store the full contents in a variable.
-
-## Step 2 — Store state in odd-flow
-
-Call \`mcp__odd-flow__memory_store\` with:
-- **key**: \`odd-project-state\`
-- **namespace**: \`odd-project\`
-- **value**: the full contents of \`.odd/state.json\`
-
-## Step 3 — Read and store the current session brief
-
-Read \`sessionBriefCount\` from state.json. If it is greater than 0, read the file \`docs/session-brief-[N].md\` where N equals the sessionBriefCount value.
-
-If the brief file exists, call \`mcp__odd-flow__memory_store\` with:
-- **key**: \`odd-session-brief-[N]\` (replace [N] with the actual number)
-- **namespace**: \`odd-project\`
-- **value**: the full contents of the session brief file
-
-## Step 4 — Create marker files
-
-Run via shell:
-\`\`\`bash
-touch .odd/.odd-flow-phase-synced
-\`\`\`
-
-If a session brief was stored in Step 3, also run:
-\`\`\`bash
-touch .odd/.odd-flow-brief-stored
-\`\`\`
-
-## Step 5 — Confirm
-
-Report to the user:
-
-> odd-flow synced. Phase [X] state and brief [N] stored. Build agents unlocked.
-
-Replace [X] with \`currentBuildPhase\` from state.json and [N] with the session brief number.`,
+    body: 'You are executing the ODD Studio `*sync` command.\n\nRead this file now:\n- `.opencode/odd/odd-sync/SKILL.md` — the sync command guide\n\nThen execute the sync steps exactly as documented.',
   },
 ];