odd-studio 3.5.1 → 3.7.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "odd-studio",
   "description": "Outcome-Driven Development — a planning and build harness for domain experts building serious software with AI. Installs the /odd skill, safety hooks, and project scaffolding into Claude Code.",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "author": {
     "name": "ODD Studio"
   },
@@ -9,6 +9,7 @@
     "odd",
     "odd-plan",
     "odd-build",
+    "odd-debug",
     "odd-swarm",
     "odd-status",
     "odd-deploy"
@@ -19,11 +20,14 @@
     "swarm-write",
     "verify-gate",
     "confirm-gate",
+    "checkpoint-gate",
     "commit-gate",
     "session-save",
     "store-validate",
     "sync-validate",
     "code-quality",
+    "security-quality",
+    "checkpoint-validate",
     "brief-quality",
     "outcome-quality",
     "swarm-guard"

package/README.md

@@ -43,7 +43,7 @@ npx odd-studio init --agent codex
 ```
 
 In Codex, start ODD with a natural-language kickoff such as `use ODD`, `start ODD`, or `begin ODD`.
-For a state check, use `ODD status`. To continue building, use `ODD build`.
+For a state check, use `ODD status`. To continue building, use `ODD build`. To debug without leaving the active outcome flow, use `ODD debug`.
 ODD now ships Codex skill-discovery metadata so these prompts can match the plugin directly instead of relying only on `AGENTS.md`.
 
 If this project was originally set up for Claude Code or OpenCode and you want to add Codex later, run:
@@ -150,11 +150,13 @@ 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 |
+| Security baseline | After writing source files | Flags hardcoded secrets, insecure auth/session patterns, and unsafe rendering/network shortcuts |
 | Session save | After git commit | Auto-saves project state for session continuity |
 
 **Claude Code:** Implemented as shell hooks registered in `.claude/settings.local.json` (project-local).
@@ -174,6 +176,8 @@ When you're ready to build, ODD Studio initialises a odd-flow swarm — a team o
 
 odd-flow MCP is configured automatically in your project-local agent config — `.mcp.json` for Claude Code, `opencode.json` for OpenCode, and `plugins/odd-studio/.mcp.json` for Codex. Every agent knows the full project state, regardless of which sessions they were spawned in.
 
+When verification fails, use `*debug` instead of leaving the ODD flow. ODD Studio records the failure, selects an explicit debug strategy, keeps the outcome active, and routes the work back into verification once the defect is fixed.
+
 ---
 
 ## Using OpenCode with local models
@@ -272,6 +276,7 @@ These are the top-level direct commands you can invoke in Claude Code or OpenCod
 | `/odd` | Start or resume an ODD project — the main planning and build orchestrator |
 | `/odd-plan` | Start or continue the planning phase (personas, outcomes, contracts, Master Implementation Plan) |
 | `/odd-build` | Start or continue a build session — reads project state and executes the build protocol |
+| `/odd-debug` | Start or continue controlled debugging inside the active outcome — chooses `ui-behaviour`, `full-stack`, `auth-security`, `integration-contract`, `background-process`, or `performance-state` before any fix |
 | `/odd-status` | Show full project state, phase progress, and what comes next |
 | `/odd-swarm` | Build all independent outcomes in the current phase simultaneously using odd-flow parallel agents |
 | `/odd-deploy` | Verify all outcomes are confirmed, then deploy the current phase to production |
@@ -285,6 +290,7 @@ Once ODD is active, you can use these sub-commands in Claude Code, OpenCode, or
 *persona       Work on personas with Diana
 *outcome       Write outcomes with Marcus
 *contracts     Map contracts with Theo
+*debug         Keep a failing build inside ODD and route it through an explicit debug strategy
 *phase-plan    Jump to implementation planning with Rachel
 *ui            Load UI excellence layer briefing
 *agent         Create a custom agent for a domain-specific concern
@@ -296,6 +302,27 @@ Once ODD is active, you can use these sub-commands in Claude Code, OpenCode, or
 *reset         Clear state and start over (asks for confirmation)
 ```
 
+### When verification fails
+
+Stay inside the ODD flow:
+
+1. Describe the failure in domain language
+2. Run `*debug` inside `/odd`, or use `/odd-debug` in Claude Code or OpenCode, or say `ODD debug` in Codex
+3. Let ODD Studio classify the failure before fixing it:
+   - `ui-behaviour`
+   - `full-stack`
+   - `auth-security`
+   - `integration-contract`
+   - `background-process`
+   - `performance-state`
+4. Verify again only after the fix returns the build to `verify` mode
+
+Example:
+
+> “The creator saves the price change, but the course page still shows the old amount.”
+
+That should route to `full-stack`, because the defect crosses UI action, server handling, and persisted state. The harness now blocks quick fixes until the failure has been classified and the debug mode is recorded in `.odd/state.json`.
+
 ---
 
 ## CLI commands

package/bin/commands/status.js

@@ -22,7 +22,15 @@ export function registerStatus(program, deps) {
       const state = await fs.readJson(stateFile);
       console.log(chalk.bold('  Project: ') + chalk.cyan(state.projectName || 'unnamed'));
       console.log(chalk.bold('  Phase:   ') + (state.currentPhase || 'Not started'));
+      console.log(chalk.bold('  Mode:    ') + (state.buildMode || 'idle'));
       console.log(chalk.bold('  Step:    ') + (state.currentStep || 'Not started'));
+      if (state.buildMode === 'debug') {
+        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/commands/upgrade.js

@@ -4,6 +4,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import ora from 'ora';
+import { mergeStateWithDefaults } from '../../scripts/state-schema.js';
 
 export function registerUpgrade(program, deps) {
   const { print, PACKAGE_ROOT } = deps;
@@ -33,6 +34,7 @@ export function registerUpgrade(program, deps) {
       if (isOpenCode) await upgradeOpenCode(PACKAGE_ROOT, targetDir);
       if (isCodex) await upgradeCodex(PACKAGE_ROOT, targetDir);
       await upgradeMcp(agent, targetDir);
+      await upgradeStateSchema(targetDir);
       print.blank();
       print.ok('Upgrade complete.');
       print.blank();
@@ -83,6 +85,14 @@ async function upgradeMcp(agent, targetDir) {
   });
 }
 
+async function upgradeStateSchema(targetDir) {
+  await runSpinner('Updating local ODD state schema...', 'ODD state schema updated', async () => {
+    const stateFile = path.resolve(targetDir, '.odd', 'state.json');
+    const state = mergeStateWithDefaults(await fs.readJson(stateFile));
+    await fs.writeJson(stateFile, state, { spaces: 2 });
+  });
+}
+
 async function runSpinner(text, successMessage, task) {
   const spinner = ora({ text, indent: 4 }).start();
   try {

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.5.1
+const pkg = require('../package.json'); // v3.6.0
 
 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.5.1",
+  "version": "3.6.0",
   "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

@@ -34,6 +34,10 @@
       {
         "matcher": "Bash",
         "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh checkpoint-gate"
+          },
           {
             "type": "command",
             "command": "./hooks/odd-studio.sh commit-gate"
@@ -55,6 +59,10 @@
       {
         "matcher": "Bash",
         "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh checkpoint-validate"
+          },
           {
             "type": "command",
             "command": "./hooks/odd-studio.sh session-save"
@@ -86,6 +94,10 @@
             "type": "command",
             "command": "./hooks/odd-studio.sh code-quality"
           },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh security-quality"
+          },
           {
             "type": "command",
             "command": "./hooks/odd-studio.sh brief-quality"
@@ -102,6 +114,10 @@
           {
             "type": "command",
             "command": "./hooks/odd-studio.sh code-quality"
+          },
+          {
+            "type": "command",
+            "command": "./hooks/odd-studio.sh security-quality"
           }
         ]
       }

package/hooks/odd-studio.sh

@@ -12,13 +12,17 @@
 #     swarm-write      Write|Edit — blocks source writes without swarm + agent token
 #     verify-gate      Edit|Write — blocks marking outcomes verified without checklist
 #     confirm-gate     Edit|Write — blocks briefConfirmed without odd-flow store
+#     checkpoint-gate  Bash     — blocks commits until a fresh Checkpoint scan clears the latest source changes
 #     commit-gate      Bash     — blocks git commit without odd-flow state stored
 #
 #   PostToolUse (exit 0 + stderr = coaching):
 #     session-save     Bash     — auto-save state after git commit
+#     state-dirty-mark Write|Edit — marks state.json edits as needing odd-flow store
 #     store-validate   mcp__odd-flow__memory_store — creates ready marker
 #     sync-validate    mcp__odd-flow__coordination_sync — creates agents-ready marker
 #     code-quality     Write|Edit — code elegance check
+#     security-quality Write|Edit — security baseline check + checkpoint dirty marker
+#     checkpoint-validate Bash    — marks checkpoint clear after a successful scan
 #     brief-quality    Write    — session brief quality check
 #     outcome-quality  Write    — outcome/persona quality check
 #
@@ -59,6 +63,7 @@ get_state_field() {
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
 CURRENT_PHASE=$(get_state_field "currentPhase")
+BUILD_MODE=$(get_state_field "buildMode")
 
 # Helper: check marker file exists and is not stale
 # Default TTL is 24 hours (86400s) — build sessions can last many hours
@@ -172,6 +177,12 @@ swarm-write)
     exit 2
   fi
 
+  # Debug session bypass: orchestrator writes allowed when *debug mode is active
+  DEBUG_SESSION=$(get_state_field "debugSession")
+  if [ "$DEBUG_SESSION" = "true" ]; 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
@@ -213,6 +224,18 @@ verify-gate)
     [ "$NEW_HAS" -gt "$OLD_HAS" ] || exit 0
   fi
 
+  if [ "$BUILD_MODE" = "debug" ]; then
+    echo "ODD STUDIO [verify-gate]: Cannot mark outcomes verified while debug mode is active." >&2
+    echo "Return buildMode to verify first, then run the verification walkthrough again." >&2
+    exit 2
+  fi
+
+  if [ -f ".odd/.checkpoint-dirty" ] || [ ! -f ".odd/.checkpoint-clear" ]; then
+    echo "ODD STUDIO [verify-gate]: Verification blocked — a fresh Checkpoint scan has not cleared the latest source changes." >&2
+    echo "Run: npx @darrenjcoxon/vibeguard --security-only -o json" >&2
+    exit 2
+  fi
+
   VERIFIED_CONFIRMED=$(get_state_field "verificationConfirmed")
   if [ "$VERIFIED_CONFIRMED" != "true" ]; then
     echo "ODD STUDIO [verify-gate]: Cannot mark NEW outcomes as verified." >&2
@@ -222,6 +245,29 @@ verify-gate)
   exit 0
   ;;
 
+# ─────────────────────────────────────────────────────────────────────────────
+# PreToolUse: Bash — blocks commit while checkpoint is dirty
+# ─────────────────────────────────────────────────────────────────────────────
+checkpoint-gate)
+  [ "$TOOL_NAME" = "Bash" ] || exit 0
+  [ "$CURRENT_PHASE" = "build" ] || exit 0
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+  echo "$COMMAND" | grep -qE 'git\s+commit' || exit 0
+
+  if [ "$BUILD_MODE" = "debug" ]; then
+    echo "ODD STUDIO [checkpoint-gate]: Commit blocked — debug mode is active." >&2
+    echo "Resolve the failure, return to verify mode, then commit only after verification passes." >&2
+    exit 2
+  fi
+
+  if [ -f ".odd/.checkpoint-dirty" ] || [ ! -f ".odd/.checkpoint-clear" ]; then
+    echo "ODD STUDIO [checkpoint-gate]: Commit blocked — latest source changes have not passed Checkpoint." >&2
+    echo "Run: npx @darrenjcoxon/vibeguard --security-only -o json" >&2
+    exit 2
+  fi
+  exit 0
+  ;;
+
 # ─────────────────────────────────────────────────────────────────────────────
 # PreToolUse: Edit|Write — blocks briefConfirmed without odd-flow store
 # ─────────────────────────────────────────────────────────────────────────────
@@ -268,6 +314,10 @@ commit-gate)
 swarm-guard)
   [ "$CURRENT_PHASE" = "build" ] || exit 0
 
+  # Suppress all warnings during active debug session — reduced ceremony is the point
+  DEBUG_SESSION=$(get_state_field "debugSession")
+  [ "$DEBUG_SESSION" = "true" ] && exit 0
+
   # Gate 1: Dirty state (commit without odd-flow store)
   if [ -f ".odd/.odd-flow-state-dirty" ]; then
     echo ""
@@ -336,6 +386,23 @@ session-save)
   exit 0
   ;;
 
+# ─────────────────────────────────────────────────────────────────────────────
+# PostToolUse: Bash — refresh checkpoint markers after a successful scan
+# ─────────────────────────────────────────────────────────────────────────────
+checkpoint-validate)
+  [ "$TOOL_NAME" = "Bash" ] || exit 0
+  [ "$CURRENT_PHASE" = "build" ] || exit 0
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+  echo "$COMMAND" | grep -qE '@darrenjcoxon/vibeguard|vibeguard' || exit 0
+
+  EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_response.exit_code // .tool_output.exit_code // .exitCode // empty' 2>/dev/null || true)
+  if [ -z "$EXIT_CODE" ] || [ "$EXIT_CODE" = "0" ]; then
+    touch .odd/.checkpoint-clear 2>/dev/null
+    rm -f .odd/.checkpoint-dirty 2>/dev/null
+  fi
+  exit 0
+  ;;
+
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: Write|Edit state.json — blocks phase transition without Steps 9, 9b, 9d
 # ─────────────────────────────────────────────────────────────────────────────
@@ -377,6 +444,19 @@ plan-complete-gate)
   exit 0
   ;;
 
+# ─────────────────────────────────────────────────────────────────────────────
+# PostToolUse: Write|Edit state.json — mark dirty so swarm-guard nags until stored
+# ─────────────────────────────────────────────────────────────────────────────
+# This catches the gap between commit-triggered dirty marking and actual edits.
+# Any edit to state.json (by Claude or by another tool) sets the dirty marker.
+# It's cleared only when mcp__odd-flow__memory_store key=odd-project-state succeeds.
+state-dirty-mark)
+  [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ] || exit 0
+  echo "$FILE_PATH" | grep -q '\.odd/state\.json$' || exit 0
+  touch .odd/.odd-flow-state-dirty 2>/dev/null
+  exit 0
+  ;;
+
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: mcp__odd-flow__memory_store — creates ready marker
 # ─────────────────────────────────────────────────────────────────────────────
@@ -386,12 +466,36 @@ store-validate)
 
   KEY=$(echo "$INPUT" | jq -r '.tool_input.key // empty')
 
-  SUCCESS=$(echo "$INPUT" | jq -r '.tool_response.success // false' 2>/dev/null || echo "false")
-  [ "$SUCCESS" = "true" ] || exit 0
+  # MCP responses may be nested under tool_response or at root — check both
+  if ! echo "$INPUT" | grep -qE '"success"[[:space:]]*:[[:space:]]*true'; then
+    exit 0
+  fi
 
   # Create the right marker based on what was stored
   case "$KEY" in
     odd-project-state)
+      # Reject partial snapshots — the value MUST contain the full state.json shape.
+      # Without this, callers can store {currentBuildPhase: "X"} and silently drift.
+      VALUE=$(echo "$INPUT" | jq -c '.tool_input.value // empty' 2>/dev/null)
+      if [ -n "$VALUE" ] && [ "$VALUE" != "null" ] && [ "$VALUE" != "empty" ]; then
+        MISSING=$(echo "$VALUE" | jq -r '
+          [
+            (if has("personas") then empty else "personas" end),
+            (if has("outcomes") then empty else "outcomes" end),
+            (if has("currentBuildPhase") then empty else "currentBuildPhase" end),
+            (if has("currentPhase") then empty else "currentPhase" end)
+          ] | join(", ")
+        ' 2>/dev/null)
+        if [ -n "$MISSING" ]; then
+          echo "" >&2
+          echo "ODD STUDIO [store-validate]: Partial odd-project-state rejected." >&2
+          echo "Missing required keys: $MISSING" >&2
+          echo "Store the FULL contents of .odd/state.json, not a hand-built object." >&2
+          echo "" >&2
+          # Do NOT clear the dirty marker — the next store must include the full file
+          exit 0
+        fi
+      fi
       touch .odd/.odd-flow-state-ready 2>/dev/null
       rm -f .odd/.odd-flow-state-dirty 2>/dev/null
       ;;
@@ -474,6 +578,43 @@ code-quality)
   exit 0
   ;;
 
+# ─────────────────────────────────────────────────────────────────────────────
+# PostToolUse: Write|Edit — security baseline warnings + checkpoint dirty marker
+# ─────────────────────────────────────────────────────────────────────────────
+security-quality)
+  [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ] || exit 0
+
+  echo "$FILE_PATH" | grep -qiE '\.(ts|tsx|js|jsx|py|svelte|vue)$' || exit 0
+  echo "$FILE_PATH" | grep -qiE '(\.config\.|\.d\.ts|node_modules|\.next|dist/|build/|\.test\.|\.spec\.|__tests__)' && exit 0
+  [ -f "$FILE_PATH" ] || exit 0
+
+  if [ "$CURRENT_PHASE" = "build" ]; then
+    touch .odd/.checkpoint-dirty 2>/dev/null
+    rm -f .odd/.checkpoint-clear 2>/dev/null
+  fi
+
+  ISSUES=""
+
+  grep -qEi '\b(api[_-]?key|secret|token|password)\b[^=\n]{0,40}[:=][[:space:]]*["'\''][^"'\'']{8,}["'\'']' "$FILE_PATH" 2>/dev/null \
+    && ISSUES="$ISSUES\n  - Possible hardcoded secret or credential literal"
+  grep -q 'dangerouslySetInnerHTML' "$FILE_PATH" 2>/dev/null \
+    && ISSUES="$ISSUES\n  - Unsafe HTML rendering detected — prove sanitisation or remove it"
+  grep -qEi '(localStorage|sessionStorage)\.(setItem|getItem)\([^)]*(token|session|auth|jwt)' "$FILE_PATH" 2>/dev/null \
+    && ISSUES="$ISSUES\n  - Client-side token or session storage detected"
+  grep -qEi 'strategy[[:space:]]*:[[:space:]]*["'\'']jwt["'\'']' "$FILE_PATH" 2>/dev/null \
+    && ISSUES="$ISSUES\n  - JWT session shortcut detected — prefer server-managed session state"
+  grep -qEi '(rejectUnauthorized|NODE_TLS_REJECT_UNAUTHORIZED|skipCsrfCheck|verify)[[:space:]]*[:=][[:space:]]*(false|0|["'\'']false["'\''])' "$FILE_PATH" 2>/dev/null \
+    && ISSUES="$ISSUES\n  - Security verification appears disabled"
+
+  if [ -n "$ISSUES" ]; then
+    echo "" >&2
+    echo "ODD SECURITY BASELINE: $(basename "$FILE_PATH")" >&2
+    echo -e "$ISSUES" >&2
+    echo "" >&2
+  fi
+  exit 0
+  ;;
+
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: Write — session brief quality check
 # ─────────────────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.5.1",
+  "version": "3.7.1",
   "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",

package/plugins/plugin-gates.js

@@ -1,5 +1,5 @@
 import { resolve } from 'path';
-import { checkBriefQuality, checkCodeElegance, checkOutcomeQuality, checkPersonaQuality } from './plugin-quality-checks.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, removeMarker, touchMarker } from './plugin-markers.js';
 
@@ -42,6 +42,12 @@ export function createBeforeHook(readState) {
 
     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.' };
       }
@@ -53,6 +59,12 @@ export function createBeforeHook(readState) {
     if (toolName === 'Bash' && state.currentPhase === 'build') {
       const cmd = event.input?.command || '';
       if (/git\s+commit/.test(cmd)) {
+        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.' };
+        }
         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.' };
         }
@@ -70,13 +82,26 @@ export function createAfterHook(readState, readLastCommit, writeState) {
 
     if (toolName === 'Write' && isOutcomeFile(filePath)) warnings.push(...checkOutcomeQuality(filePath));
     if (toolName === 'Write' && isPersonaFile(filePath)) warnings.push(...checkPersonaQuality(filePath));
-    if ((toolName === 'Write' || toolName === 'Edit') && isSrcFile(filePath)) warnings.push(...checkCodeElegance(filePath));
+    if ((toolName === 'Write' || toolName === 'Edit') && isSrcFile(filePath)) {
+      warnings.push(...checkCodeElegance(filePath));
+      warnings.push(...checkSecurityBaseline(filePath));
+    }
     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) {
-        const state = readState();
         if (state) {
           state.lastCommit = readLastCommit();
           state.lastSaved = new Date().toISOString();
@@ -112,9 +137,15 @@ 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.'] };
+    }
 
     const swarmPath = resolve(process.cwd(), '.odd', '.odd-flow-swarm-active');
     if (!markerValid(swarmPath, 3600000)) {

package/plugins/plugin-quality-checks.js

@@ -79,6 +79,26 @@ export function checkCodeElegance(filePath) {
   return warnings;
 }
 
+export function checkSecurityBaseline(filePath) {
+  if (!existsSync(filePath) || !isSrcFile(filePath)) return [];
+  const content = readFileSync(filePath, 'utf8');
+  const warnings = [];
+
+  const riskyPatterns = [
+    [/\b(api[_-]?key|secret|token|password)\b[^=\n]{0,40}[:=]\s*['"`][^'"`\n]{8,}['"`]/i, 'Possible hardcoded secret or credential literal'],
+    [/dangerouslySetInnerHTML/, 'Unsafe HTML rendering detected — prove sanitisation or remove it'],
+    [/(localStorage|sessionStorage)\.(setItem|getItem)\([^)]*(token|session|auth|jwt)/i, 'Client-side token/session storage detected'],
+    [/strategy\s*:\s*['"]jwt['"]/i, 'JWT session shortcut detected — prefer server-managed session state'],
+    [/(rejectUnauthorized|NODE_TLS_REJECT_UNAUTHORIZED|skipCsrfCheck|verify)\s*[:=]\s*(false|0|['"]false['"])/i, 'Security verification appears disabled'],
+  ];
+
+  for (const [pattern, message] of riskyPatterns) {
+    if (pattern.test(content)) warnings.push(message);
+  }
+
+  return warnings;
+}
+
 export function checkBriefQuality(filePath) {
   if (!existsSync(filePath)) return [];
   const content = readFileSync(filePath, 'utf8');

package/scripts/command-definitions.js

@@ -17,6 +17,11 @@ export const COMMANDS = [
     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.',
   },
+  {
+    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.',
+  },
   {
     name: 'odd-swarm',
     description: 'Build all independent outcomes in the current phase simultaneously using odd-flow parallel agents',

package/scripts/scaffold-project.js

@@ -2,6 +2,7 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { mergeStateWithDefaults } from './state-schema.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -59,9 +60,9 @@ export default async function scaffoldProject(targetDir, projectName, agent = 'c
   // Patch .odd/state.json with project name and timestamp
   const stateFile = path.join(targetDir, '.odd', 'state.json');
   if (fs.existsSync(stateFile)) {
-    const state = await fs.readJson(stateFile);
+    const state = mergeStateWithDefaults(await fs.readJson(stateFile));
     state.projectName = projectName;
-    state.initialisedAt = new Date().toISOString();
+    state.initialisedAt = state.initialisedAt || new Date().toISOString();
     await fs.writeJson(stateFile, state, { spaces: 2 });
   }
 

package/scripts/setup-hooks.js

@@ -48,6 +48,7 @@ const GATES = [
     event: 'PreToolUse',
     matcher: 'Bash',
     gates: [
+      { name: 'checkpoint-gate', timeout: 5, status: 'ODD checkpoint gate...' },
       { name: 'commit-gate', timeout: 5, status: 'ODD commit gate...' },
     ],
   },
@@ -65,6 +66,7 @@ const GATES = [
     matcher: 'Write',
     gates: [
       { name: 'plan-complete-gate', timeout: 5, status: 'ODD plan complete gate...' },
+      { name: 'state-dirty-mark', timeout: 5, status: 'ODD state dirty mark...' },
     ],
   },
   {
@@ -72,12 +74,14 @@ const GATES = [
     matcher: 'Edit',
     gates: [
       { name: 'plan-complete-gate', timeout: 5, status: 'ODD plan complete gate...' },
+      { name: 'state-dirty-mark', timeout: 5, status: 'ODD state dirty mark...' },
     ],
   },
   {
     event: 'PostToolUse',
     matcher: 'Bash',
     gates: [
+      { name: 'checkpoint-validate', timeout: 10, status: 'ODD checkpoint validate...' },
       { name: 'session-save', timeout: 10, status: 'ODD session save...' },
     ],
   },
@@ -100,6 +104,7 @@ const GATES = [
     matcher: 'Write',
     gates: [
       { name: 'code-quality', timeout: 5, status: 'ODD code quality...' },
+      { name: 'security-quality', timeout: 5, status: 'ODD security quality...' },
       { name: 'brief-quality', timeout: 5, status: 'ODD brief quality...' },
       { name: 'outcome-quality', timeout: 5, status: 'ODD outcome quality...' },
     ],
@@ -109,6 +114,7 @@ const GATES = [
     matcher: 'Edit',
     gates: [
       { name: 'code-quality', timeout: 5, status: 'ODD code quality...' },
+      { name: 'security-quality', timeout: 5, status: 'ODD security quality...' },
     ],
   },
 ];