odd-studio 3.6.0 → 3.7.1

package/hooks/odd-studio.sh

@@ -17,6 +17,7 @@
 #
 #   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
@@ -176,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
@@ -307,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 ""
@@ -433,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
 # ─────────────────────────────────────────────────────────────────────────────
@@ -442,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
       ;;

package/package.json

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

@@ -66,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...' },
     ],
   },
   {
@@ -73,6 +74,7 @@ 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...' },
     ],
   },
   {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "odd"
-version: "3.6.0"
+version: "3.7.1"
 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.1.
 
 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.1.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]

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