odd-studio 3.7.1 → 3.7.4

package/hooks/odd-studio.sh

@@ -12,17 +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
-#     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
+#     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
 #
@@ -86,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
@@ -230,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
@@ -246,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
@@ -279,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
@@ -287,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
@@ -318,24 +281,7 @@ swarm-guard)
   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 ""
-    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
-
-  # Gate 2: Swarm not initialised
+  # Swarm not initialised
   if marker_valid ".odd/.odd-flow-swarm-active" 86400; then
     exit 0
   fi
@@ -380,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
@@ -445,60 +377,27 @@ plan-complete-gate)
   ;;
 
 # ─────────────────────────────────────────────────────────────────────────────
-# PostToolUse: Write|Edit state.json — mark dirty so swarm-guard nags until stored
+# state-dirty-mark — REMOVED in v3.7.4 (dirty/ready treadmill eliminated)
 # ─────────────────────────────────────────────────────────────────────────────
-# 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
+# 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')
 
-  # 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
-      ;;
     odd-session-brief-*)
       touch .odd/.odd-flow-brief-stored 2>/dev/null
       ;;
@@ -507,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
@@ -579,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
@@ -588,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.7.1",
+  "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 ────────────────────────────────────────────────────
@@ -66,7 +64,6 @@ 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...' },
     ],
   },
   {
@@ -74,14 +71,12 @@ 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...' },
     ],
   },

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "odd"
-version: "3.7.1"
+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
@@ -106,7 +106,7 @@ Display this when no existing state is found:
 
 ---
 
-Welcome to ODD Studio v3.7.1.
+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:
 
@@ -130,7 +130,7 @@ Display this when existing state is found. Replace the bracketed values with act
 
 ---
 
-Welcome back to ODD Studio v3.7.1.
+Welcome back to ODD Studio v3.7.4.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]
@@ -267,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.
@@ -398,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`.
 
@@ -438,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.
@@ -707,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: