odd-studio 3.6.0 → 3.7.4

package/hooks/odd-studio.sh

@@ -12,16 +12,13 @@
 #     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
-#     store-validate   mcp__odd-flow__memory_store — creates ready marker
-#     sync-validate    mcp__odd-flow__coordination_sync — creates agents-ready marker
+#     session-save     Bash     — updates last-commit metadata after git commit
+#     store-validate   mcp__odd-flow__memory_store — touches brief-stored marker
+#     sync-validate    mcp__odd-flow__coordination_sync — activates swarm markers
 #     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
+#     security-quality Write|Edit — security baseline warnings (non-blocking)
 #     brief-quality    Write    — session brief quality check
 #     outcome-quality  Write    — outcome/persona quality check
 #
@@ -85,7 +82,7 @@ is_source_file() {
     return 1
   fi
   # Non-source locations — allow
-  if echo "$fp" | grep -qE '(\.odd/|docs/|memory/|MEMORY\.md|CLAUDE\.md|\.odd-flow)'; then
+  if echo "$fp" | grep -qE '(\.odd/|docs/|memory/|MEMORY\.md|CLAUDE\.md|\.odd-flow|\.claude/)'; then
     return 1
   fi
   # Hook/skill/script files — allow
@@ -176,6 +173,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
@@ -223,11 +226,7 @@ verify-gate)
     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
+  # Checkpoint pre-check removed in v3.7.3 (see checkpoint-gate note below).
 
   VERIFIED_CONFIRMED=$(get_state_field "verificationConfirmed")
   if [ "$VERIFIED_CONFIRMED" != "true" ]; then
@@ -239,27 +238,12 @@ verify-gate)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PreToolUse: Bash — blocks commit while checkpoint is dirty
+# 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.
 # ─────────────────────────────────────────────────────────────────────────────
-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
@@ -272,7 +256,7 @@ confirm-gate)
   NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
   echo "$NEW_CONTENT" | grep -qE '"briefConfirmed"\s*:\s*true' || exit 0
 
-  if [ ! -f ".odd/.odd-flow-brief-stored" ] && [ ! -f ".odd/.odd-flow-state-ready" ]; then
+  if [ ! -f ".odd/.odd-flow-brief-stored" ]; then
     echo "ODD STUDIO [confirm-gate]: Brief not stored in odd-flow memory. Store it first." >&2
     exit 2
   fi
@@ -280,26 +264,12 @@ confirm-gate)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PreToolUse: Bash — blocks git commit without odd-flow state stored
+# 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.
 # ─────────────────────────────────────────────────────────────────────────────
-commit-gate)
-  [ "$TOOL_NAME" = "Bash" ] || exit 0
-  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
-  echo "$COMMAND" | grep -qE 'git\s+commit' || exit 0
-  [ "$CURRENT_PHASE" = "build" ] || exit 0
-
-  if [ ! -f ".odd/.odd-flow-state-ready" ]; then
-    echo "" >&2
-    echo "ODD STUDIO [commit-gate]: Commit blocked — odd-flow state not stored." >&2
-    echo "Call mcp__odd-flow__memory_store key=odd-project-state first." >&2
-    echo "" >&2
-    exit 2
-  fi
-
-  # Marker consumed — next commit requires a fresh store
-  rm -f ".odd/.odd-flow-state-ready"
-  exit 0
-  ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
 # UserPromptSubmit — warns every turn if build phase without swarm
@@ -307,24 +277,11 @@ commit-gate)
 swarm-guard)
   [ "$CURRENT_PHASE" = "build" ] || exit 0
 
-  # Gate 1: Dirty state (commit without odd-flow store)
-  if [ -f ".odd/.odd-flow-state-dirty" ]; then
-    echo ""
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-    echo "ODD STUDIO — STATE NOT SAVED TO ODD-FLOW"
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-    echo ""
-    echo "  A git commit was made but .odd/state.json was NOT stored to odd-flow."
-    echo "  DO THIS NOW:"
-    echo "  1. mcp__odd-flow__memory_store key=odd-project-state namespace=odd-project upsert=true value=<.odd/state.json>"
-    echo "  2. Bash: rm -f .odd/.odd-flow-state-dirty"
-    echo ""
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-    echo ""
-    exit 0
-  fi
+  # Suppress all warnings during active debug session — reduced ceremony is the point
+  DEBUG_SESSION=$(get_state_field "debugSession")
+  [ "$DEBUG_SESSION" = "true" ] && exit 0
 
-  # Gate 2: Swarm not initialised
+  # Swarm not initialised
   if marker_valid ".odd/.odd-flow-swarm-active" 86400; then
     exit 0
   fi
@@ -369,28 +326,14 @@ session-save)
     } catch(e) {}
   " 2>/dev/null
 
-  # Refresh sync marker + set dirty marker
+  # Refresh phase sync marker. Dirty-marker touching removed in v3.7.4.
   touch .odd/.odd-flow-phase-synced 2>/dev/null
-  touch .odd/.odd-flow-state-dirty 2>/dev/null
   exit 0
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PostToolUse: Bash — refresh checkpoint markers after a successful scan
+# checkpoint-validate — REMOVED in v3.7.3 (see checkpoint-gate note above)
 # ─────────────────────────────────────────────────────────────────────────────
-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
@@ -434,23 +377,27 @@ plan-complete-gate)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PostToolUse: mcp__odd-flow__memory_store — creates ready marker
+# 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
 
   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
+  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)
-      touch .odd/.odd-flow-state-ready 2>/dev/null
-      rm -f .odd/.odd-flow-state-dirty 2>/dev/null
-      ;;
     odd-session-brief-*)
       touch .odd/.odd-flow-brief-stored 2>/dev/null
       ;;
@@ -459,12 +406,22 @@ store-validate)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PostToolUse: mcp__odd-flow__coordination_sync — creates agents-ready marker
+# PostToolUse: mcp__odd-flow__coordination_sync — completes swarm init
 # ─────────────────────────────────────────────────────────────────────────────
+# coordination_sync is the LAST step of the 9-step swarm init sequence.
+# When it fires successfully in build phase, the swarm is initialised — so we
+# create all three markers atomically rather than relying on the orchestrator
+# to remember a stray Bash `touch` step buried in a numbered list.
+#
+# Markers created:
+#   .odd-flow-swarm-active  — gates source writes (24h TTL)
+#   .odd-flow-agents-ready  — unblocks build-gate for Task agents
+#   .odd-flow-phase-synced  — confirms agents have phase context
 sync-validate)
   [ "$TOOL_NAME" = "mcp__odd-flow__coordination_sync" ] || exit 0
   [ "$CURRENT_PHASE" = "build" ] || exit 0
 
+  touch .odd/.odd-flow-swarm-active 2>/dev/null
   touch .odd/.odd-flow-agents-ready 2>/dev/null
   touch .odd/.odd-flow-phase-synced 2>/dev/null
   exit 0
@@ -531,7 +488,8 @@ code-quality)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PostToolUse: Write|Edit — security baseline warnings + checkpoint dirty marker
+# 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
@@ -540,11 +498,6 @@ security-quality)
   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 \

package/hooks/post-commit-hook.sh

@@ -1,39 +1,11 @@
 #!/usr/bin/env bash
-# ODD Studio — git post-commit hook
+# ODD Studio — git post-commit hook (no-op)
 #
-# Install to your project with:
-#   cp .odd/post-commit-hook.sh .git/hooks/post-commit
-#   chmod +x .git/hooks/post-commit
+# This hook existed in earlier versions to set .odd-flow-state-dirty on every
+# build-phase commit so the swarm-guard would nag until state was stored.
+# In v3.7.4 the dirty/ready marker treadmill was removed because it created
+# more friction than value, so this hook is now a no-op kept only for
+# backwards compatibility with projects that have it installed in .git/hooks.
 #
-# Or run: npx odd-studio install-git-hooks
-#
-# Why this exists:
-# odd-session-save.sh (PostToolUse) covers commits made BY Claude.
-# This hook covers commits made by the developer directly in the terminal.
-# Together they ensure .odd-flow-state-dirty is always set after a build-phase commit,
-# regardless of who made it.
-#
-# The dirty marker is cleared only after:
-#   1. mcp__odd-flow__memory_store key=odd-project-state (saves state to odd-flow)
-#   2. rm -f .odd/.odd-flow-state-dirty
-#
-# odd-swarm-guard.sh (UserPromptSubmit) blocks EVERY Claude turn until cleared.
-
-STATE_FILE=".odd/state.json"
-
-if [ ! -f "$STATE_FILE" ]; then
-  exit 0
-fi
-
-CURRENT_PHASE=$(ODD_STATE_FILE="$STATE_FILE" node -e "
-  try {
-    const s = JSON.parse(require('fs').readFileSync(process.env.ODD_STATE_FILE, 'utf8'));
-    console.log(s.currentPhase || '');
-  } catch(e) { console.log(''); }
-" 2>/dev/null)
-
-if [ "$CURRENT_PHASE" = "build" ]; then
-  touch .odd/.odd-flow-state-dirty
-fi
-
+# Safe to delete from .git/hooks/post-commit if you want.
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.6.0",
+  "version": "3.7.4",
   "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/scripts/setup-hooks.js

@@ -48,8 +48,6 @@ 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...' },
     ],
   },
   // ── UserPromptSubmit ────────────────────────────────────────────────────
@@ -79,7 +77,6 @@ const GATES = [
     event: 'PostToolUse',
     matcher: 'Bash',
     gates: [
-      { name: 'checkpoint-validate', timeout: 10, status: 'ODD checkpoint validate...' },
       { name: 'session-save', timeout: 10, status: 'ODD session save...' },
     ],
   },

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "odd"
-version: "3.6.0"
+version: "3.7.4"
 description: "Outcome-Driven Development planning and build coach. Use /odd to start or resume an ODD project — building personas, writing outcomes, mapping contracts, creating a Master Implementation Plan, and directing a odd-flow-powered build. Designed for domain experts who are not developers. Works with Claude Code, OpenCode, and Codex."
 metadata:
   priority: 10
@@ -84,8 +84,15 @@ Before doing anything else, run this state check silently:
 2. Check whether `docs/plan.md` exists.
 3. Attempt to retrieve project state from odd-flow memory:
    - Call `mcp__odd-flow__memory_retrieve` with key `odd-project-state`, namespace `odd-project`
-   - If successful, merge odd-flow state with any local state found in `.odd/state.json`, with odd-flow taking precedence for any field where it has richer data (more personas, outcomes, or a later phase)
-4. **If odd-flow state is richer than local state** (odd-flow has personas/outcomes/approvals that local does not): write the merged state back to `.odd/state.json` immediately using the Write tool. This keeps local state in sync so the next session starts correctly without a mismatch.
+4. **Reconciliation — strict, no silent merging.** If both local and odd-flow state exist, compare them field-by-field. Specifically check `currentBuildPhase`, `currentPhase`, `briefConfirmed`, `sessionBriefCount`, `personas.length`, and `outcomes.length`. If ANY of these disagree:
+   - **STOP.** Do not display the welcome or status message yet.
+   - Show the user a side-by-side diff of the disagreeing fields (local value vs odd-flow value).
+   - Ask explicitly: "Local state and odd-flow state have drifted. Which should I trust as authoritative? Type `local`, `odd-flow`, or `inspect` to see the full diff."
+   - On `local`: store the full local `state.json` to odd-flow with `mcp__odd-flow__memory_store` and proceed.
+   - On `odd-flow`: write the odd-flow value to `.odd/state.json` and proceed.
+   - On `inspect`: print the full diff and ask again.
+   - Do NOT use heuristics like "richer wins" or "later phase wins" — they hide bugs. The user decides.
+5. If local exists and odd-flow does not: store local to odd-flow immediately. If odd-flow exists and local does not: write odd-flow to local immediately.
 
 **If this is a new project** (no state found anywhere), display the welcome message below.
 
@@ -99,7 +106,7 @@ Display this when no existing state is found:
 
 ---
 
-Welcome to ODD Studio v3.6.0.
+Welcome to ODD Studio v3.7.4.
 
 You are about to plan and build something real — using a methodology called Outcome-Driven Development. Before we write a single line of code, we are going to get precise about three things:
 
@@ -123,7 +130,7 @@ Display this when existing state is found. Replace the bracketed values with act
 
 ---
 
-Welcome back to ODD Studio v3.6.0.
+Welcome back to ODD Studio v3.7.4.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]
@@ -260,11 +267,11 @@ Execute these steps in order:
 
 7. **INITIALISES THE ODD_FLOW SWARM — MANDATORY FIRST ACTION.**
 
-   > **This step happens BEFORE loading any files, BEFORE reading source code, BEFORE planning any build work. Swarm init is not a step buried in a checklist — it is the gate that unlocks everything else. If you have not completed the swarm initialisation sequence (all 9 steps in the odd-flow Swarm Initialisation section below), STOP and do it NOW.**
+   > **This step happens BEFORE loading any files, BEFORE reading source code, BEFORE planning any build work. Swarm init is not a step buried in a checklist — it is the gate that unlocks everything else. If you have not completed the swarm initialisation sequence (all 8 steps in the odd-flow Swarm Initialisation section below), STOP and do it NOW.**
    >
    > The `odd-swarm-guard.sh` hook fires on every user message when in build phase without the swarm marker. If you are reading this and `.odd/.odd-flow-swarm-active` does not exist, the hook is injecting a warning into every response. Do not ignore it. Initialise the swarm now.
 
-   See: **odd-flow Swarm Initialisation** section below. Execute all 9 steps, then proceed.
+   See: **odd-flow Swarm Initialisation** section below. Execute all 8 steps, then proceed.
 
 8. Loads `docs/build/build-protocol.md` and `docs/build/code-excellence.md` into context. The Code Excellence standard is mandatory — the build agent applies the Design-It-Twice protocol to every function, component, and module it writes.
 9. Confirms to the user which phase is being worked on and which outcomes are in scope.
@@ -391,33 +398,9 @@ The verification walkthrough MUST have been completed in the current session. Th
 
 Execute the following steps in order:
 
-**1. Run Checkpoint.**
+**1. Commit the verified state** via git with message: `feat: verified [outcome name] — [phase]`
 
-Execute via Bash: `npx @darrenjcoxon/vibeguard --security-only -o json 2>/dev/null`
-
-Display to the domain expert: "Checkpoint running..."
-
-Parse the JSON output. Look for findings with severity `critical`, `high`, or `secret`.
-
-**If Checkpoint is not installed** (command fails or returns an error): skip silently and display "Checkpoint not installed — type `npx @darrenjcoxon/vibeguard --install-tools` in your terminal to enable security scanning." Then proceed to step 3.
-
-**2. If Checkpoint finds critical, high, or secret findings:**
-
-Do NOT advance to the next outcome.
-
-Translate each finding from technical language to a plain-language fix instruction. Do not show raw scanner output to the domain expert.
-
-Brief the build agent directly with the fix instructions. Do not ask the domain expert to review them.
-
-Display: "Checkpoint found [N] security issue(s) in this outcome. The build agent is fixing them now. This does not affect your verification — the outcome behaves correctly. Once the security fix is complete, Checkpoint will run again automatically."
-
-After the build agent applies fixes, re-run Checkpoint automatically (repeat step 1). Repeat until Checkpoint is clear. Then proceed to step 3.
-
-**3. If Checkpoint is clear:**
-
-Display: "Checkpoint clear."
-
-Commit the verified state via git with message: `feat: verified [outcome name] — [phase]`
+> **Note:** Automated Checkpoint/vibeguard scanning was removed in v3.7.4. The scanner flagged dep-lockfile CVEs as code vulnerabilities and made every commit impossible. Security scanning is reintroduced only with a scanner that can distinguish code findings from lockfile findings. In the meantime, domain experts remain responsible for flagging anything suspicious during the verification walkthrough.
 
 Call `mcp__odd-flow__memory_store` key `odd-outcome-[name]` with status `verified`, namespace `odd-project`.
 
@@ -431,8 +414,6 @@ Display:
 
 **[Outcome name] — verified and committed.**
 
-Checkpoint: clear.
-
 **Next:** [next outcome name and one-sentence description]
 
 Type `*build` to begin, or `*status` to see the full phase progress.
@@ -700,29 +681,23 @@ Call `mcp__odd-flow__agent_spawn`:
 - Role: qa
 - Instructions: `"Read verification steps per outcome from odd-flow. Run all steps after each outcome completes. Report failures in domain language only. Flag as verified or failed."`
 
-### 8. Activate the Swarm Write Gate
-
-Create the swarm marker file that unlocks source code writes:
+### 8. Sync All Agents — automatically activates the write gate
 
-```bash
-touch .odd/.odd-flow-swarm-active
-```
+Call `mcp__odd-flow__coordination_sync`:
+- Namespace: `odd-project`
+- Message: "Phase [n] build started. All agents: retrieve your assignments from odd-flow memory key odd-project-state and begin execution according to the Build Protocol."
 
-**Why this matters:** The `odd-studio.sh` hook enforces a single-marker system during the build phase. The swarm-active marker must exist for source code writes to succeed:
+**This step is the LAST init action.** When `coordination_sync` succeeds in build phase, the `sync-validate` hook automatically creates all three swarm markers:
 
-1. **`.odd/.odd-flow-swarm-active`** — build session is active (24-hour TTL). Created here at step 8.
+1. **`.odd/.odd-flow-swarm-active`** — gates source writes (24-hour TTL)
+2. **`.odd/.odd-flow-agents-ready`** — unblocks build-gate for Task agents
+3. **`.odd/.odd-flow-phase-synced`** — confirms agents have phase context
 
-Both the main orchestrator AND Task agents can write source code when the swarm-active marker is valid. This removes the friction of the previous two-marker system while still ensuring the build session is properly initialised before any code is written.
+You do NOT manually `touch` these markers. The hook handles it. Steps 1–7 store state and spawn agents in parallel; step 8 finalises and unlocks the build. If the marker is missing after coordination_sync succeeds, the hook is broken — fix the hook, do not manually touch the marker.
 
 The marker TTL is 24 hours (86400 seconds) because build sessions can last many hours. If the marker expires, run `*build` again to refresh it.
 
-### 9. Sync All Agents
-
-Call `mcp__odd-flow__coordination_sync`:
-- Namespace: `odd-project`
-- Message: "Phase [n] build started. All agents: retrieve your assignments from odd-flow memory key odd-project-state and begin execution according to the Build Protocol."
-
-### 10. Confirm to User
+### 9. Confirm to User
 
 Display:
 

package/skill/odd-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "odd-debug"
-version: "1.0.0"
-description: "ODD Studio debug command. Keeps debugging inside the active outcome, selects the correct debug strategy, and routes back to verification instead of drifting outside the ODD flow."
+version: "2.0.0"
+description: "ODD Studio debug command. Activates a lightweight debug session (no full swarm init required), selects the correct debug strategy, and routes back to verification instead of drifting outside the ODD flow."
 metadata:
   priority: 9
   pathPatterns:
@@ -43,18 +43,124 @@ retrieval:
 
 You are executing the ODD Studio `*debug` command.
 
-Read these two files now:
-1. `.claude/skills/odd/SKILL.md` — the full ODD Studio coach and build protocol
-2. `.claude/skills/odd/docs/build/debug-protocol.md` — the Debug Protocol detail
+## What this command does
 
-Then execute the `*debug` protocol exactly as documented in those files, starting from the state check and selecting the explicit debug strategy before any fix is attempted.
+`*debug` activates a lightweight build session optimised for debugging, hotfixes, and security remediation work. It bypasses the full 9-step swarm init that `*build` requires — there is no agent dispatch, no task creation, no swarm spawn. The orchestrator writes code directly.
 
-You must classify the failure into exactly one debug strategy before reading implementation details:
-- `ui-behaviour`
-- `full-stack`
-- `auth-security`
-- `integration-contract`
-- `background-process`
-- `performance-state`
+This is not a shortcut around ODD. The brief-gate, verify-gate, commit-gate, and outcome verification protocol are all still enforced. What is relaxed is the agent-token requirement in `swarm-write` — the requirement that forces every source write through a background Task agent. That requirement exists to enable parallel multi-agent outcome builds. For a single targeted fix it is pure ceremony.
 
-If the correct strategy is not yet clear, gather evidence first. Never guess. Never jump straight to a fix.
+**When to use `*debug` instead of `*build`:**
+- Fixing a failing test suite
+- Applying a security patch
+- Investigating and resolving a verification failure
+- Any single-file or few-file change that does not require parallel agent execution
+
+**When to use `*build` instead:**
+- Building a new outcome from scratch
+- Work that benefits from parallel backend + UI + QA agents
+- Phase transitions
+
+---
+
+## Session Activation
+
+Execute these steps before any investigation or fix work. Do them in order.
+
+### Step 1 — State check
+
+Read `.odd/state.json`. Confirm:
+- `currentPhase` is `"build"` — if not, explain that `*debug` requires an active build phase
+- `planApproved` is `true` — if not, route to `*plan`
+
+If either check fails, stop here and explain what is needed.
+
+### Step 2 — Activate the debug session marker
+
+```bash
+touch .odd/.odd-flow-swarm-active
+```
+
+This creates or refreshes the 24-hour build session marker. The `swarm-write` gate will now allow direct orchestrator writes (because `debugSession: true` bypasses Gate 2).
+
+### Step 3 — Set debug session state
+
+Update `.odd/state.json`:
+- `debugSession: true`
+- `buildMode: "debug"`
+- `verificationConfirmed: false`
+- `debugStartedAt: <current ISO timestamp>`
+- `debugSummary: <one-sentence description of the issue — or "unknown" if not yet classified>`
+
+### Step 4 — Store state to odd-flow
+
+Call `mcp__odd-flow__memory_store`:
+- Key: `odd-project-state`
+- Namespace: `odd-project`
+- Value: full contents of `.odd/state.json`
+- upsert: true
+
+This single store call satisfies the `commit-gate` requirement (via `store-validate` hook) for subsequent commits in this session.
+
+### Step 5 — Confirm to user
+
+Display:
+
+---
+
+Debug session active.
+
+Source writes are unlocked. No agent dispatch required.
+Brief gate, verify gate, and commit gate remain enforced.
+
+State stored to odd-flow. Ready to investigate.
+
+---
+
+Then proceed immediately to Strategy Selection below.
+
+---
+
+## Strategy Selection
+
+Read `.odd/state.json` to identify the active outcome and the latest failure. If the failure was described in the user's message, use that. If not yet clear, ask for a one-sentence description.
+
+Choose exactly one debug strategy before inspecting code. State the chosen strategy and the reason.
+
+- Choose `ui-behaviour` when the problem is visible in the interface and you do not yet have evidence of a backend or data fault
+- Choose `full-stack` when the failure crosses a user action, server boundary, and persisted state
+- Choose `auth-security` when access, identity, trust, or validation boundaries might be wrong
+- Choose `integration-contract` when one part of the system expects data or sequencing another part does not produce
+- Choose `background-process` when the failure depends on async handoff, jobs, retries, or event delivery
+- Choose `performance-state` when the issue depends on timing, staleness, cache invalidation, or repeated actions
+
+If more than one strategy seems plausible, do not fix anything yet. Gather one more piece of evidence, then choose the narrowest strategy that still explains the failure.
+
+---
+
+## Fix Protocol
+
+After choosing the strategy, load `docs/build/debug-protocol.md` for the detailed investigation procedure for that strategy.
+
+When the fix is complete:
+
+1. Run the relevant automated checks (tests, lint)
+2. Update `.odd/state.json`:
+   - `debugSession: false`
+   - `buildMode: "verify"`
+   - `debugStrategy: <chosen strategy>`
+   - `debugTarget: <affected file or surface>`
+   - `debugSummary: <resolved — one sentence>`
+3. Call `mcp__odd-flow__memory_store` with key `odd-project-state` to store final state
+4. Return to the verification walkthrough from step one
+
+Setting `debugSession: false` re-enables Gate 2 for subsequent work, returning to full swarm protocol.
+
+---
+
+## Non-negotiable rules
+
+- Never mark an outcome verified during a debug session
+- Never change multiple layers at once before reproducing the fault
+- Never skip the reproduction step
+- Never broaden the strategy after starting unless new evidence proves the original classification wrong
+- Always clear `debugSession: false` when the fix is complete