@leeovery/claude-technical-workflows 2.1.40 → 2.1.41

package/README.md

@@ -212,7 +212,7 @@ npx claude-manager remove @leeovery/claude-technical-workflows && npm rm @leeove
 Documents are stored in your project using a **phase-first** organisation. Early phases use flat files; later phases use topic directories with multiple files for tracking and analysis.
 
 ```
-docs/workflow/
+.workflows/
 ├── research/                          # Phase 1 — flat, semantically named
 │   ├── exploration.md
 │   ├── competitor-analysis.md

package/agents/implementation-analysis-architecture.md

@@ -38,7 +38,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent and boundaries
 4. **Read all implementation files** — understand the full picture
 5. **Analyze architecture** — evaluate how the pieces compose as a whole
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`
+6. **Write findings** to `.workflows/implementation/{topic}/analysis-architecture-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -52,7 +52,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`:
+Write to `.workflows/implementation/{topic}/analysis-architecture-c{cycle-number}.md`:
 
 ```
 AGENT: architecture

package/agents/implementation-analysis-duplication.md

@@ -34,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent
 4. **Read all implementation files** — build a mental map of the full codebase
 5. **Analyze for duplication** — compare patterns across files, identify extraction candidates
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`
+6. **Write findings** to `.workflows/implementation/{topic}/analysis-duplication-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -48,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`:
+Write to `.workflows/implementation/{topic}/analysis-duplication-c{cycle-number}.md`:
 
 ```
 AGENT: duplication

package/agents/implementation-analysis-standards.md

@@ -34,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read code-quality.md** — understand quality standards
 4. **Read all implementation files** — map each file back to its spec requirements
 5. **Compare implementation against spec** — check every decision point
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`
+6. **Write findings** to `.workflows/implementation/{topic}/analysis-standards-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -48,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`:
+Write to `.workflows/implementation/{topic}/analysis-standards-c{cycle-number}.md`:
 
 ```
 AGENT: standards

package/agents/implementation-analysis-synthesizer.md

@@ -20,13 +20,13 @@ You receive via the orchestrator's prompt:
 
 ## Your Process
 
-1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication-c{cycle-number}.md`, `analysis-standards-c{cycle-number}.md`, and `analysis-architecture-c{cycle-number}.md`
+1. **Read all findings files** from `.workflows/implementation/{topic}/` — look for `analysis-duplication-c{cycle-number}.md`, `analysis-standards-c{cycle-number}.md`, and `analysis-architecture-c{cycle-number}.md`
 2. **Deduplicate** — same issue found by multiple agents → one finding, note all sources
 3. **Group related findings** — multiple findings about the same pattern become one task (e.g., 3 duplication findings about the same helper pattern = 1 "extract helper" task)
 4. **Filter** — discard low-severity findings unless they cluster into a pattern. Never discard high-severity.
 5. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
-6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report-c{cycle-number}.md`
-7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md` with `status: pending` for each task
+6. **Write report** — output to `.workflows/implementation/{topic}/analysis-report-c{cycle-number}.md`
+7. **Write staging file** — if actionable tasks exist, write to `.workflows/implementation/{topic}/analysis-tasks-c{cycle-number}.md` with `status: pending` for each task
 
 ## Report Format
 

package/agents/implementation-analysis-task-writer.md

@@ -32,7 +32,7 @@ You receive via the orchestrator's prompt:
 
 ## Update the Plan Index File
 
-The Plan Index File (`docs/workflow/planning/{topic}/plan.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
+The Plan Index File (`.workflows/planning/{topic}/plan.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
 
 Append at the end of the Plan Index File body, following the **Phase Entry** and **Task Table** templates from plan-index-schema:
 

package/agents/implementation-task-executor.md

@@ -36,6 +36,9 @@ You are stateless — each invocation starts fresh. The full task content is alw
    - Read files and tests related to the task's domain
    - Identify patterns, conventions, and structures you'll need to follow or extend
    - Check for existing code that the task builds on or integrates with
+   - Find similar implementations — if the task is "add endpoint X", find existing endpoints and follow the same pattern
+   - Understand inputs, outputs, and callers of any code you'll modify
+   - Note the testing approach used in this area — use the same patterns
 6. **Execute TDD cycle** — follow the process in tdd-workflow.md for each acceptance criterion and test case.
 7. **Verify all acceptance criteria met** — every criterion from the task must be satisfied
 8. **Return structured result**

package/agents/planning-phase-designer.md

@@ -17,8 +17,9 @@ You receive file paths via the orchestrator's prompt:
 2. **Specification path** — The validated specification to plan from
 3. **Cross-cutting spec paths** (if any) — Architectural decisions that influence planning
 4. **phase-design.md** — Phase design principles
-5. **task-design.md** — Task design principles (for phase granularity awareness)
-6. **plan-index-schema.md** — Canonical plan index structure
+5. **Context-specific phase design** — Work-type guidance (greenfield, feature, or bugfix)
+6. **task-design.md** — Task design principles (for phase granularity awareness)
+7. **plan-index-schema.md** — Canonical plan index structure
 
 On **amendment**, you also receive:
 - **Previous output** — Your prior phase structure
@@ -30,9 +31,10 @@ On **amendment**, you also receive:
 2. Read the specification in full, following the ingestion protocol
 3. Read any cross-cutting specifications
 4. Read `phase-design.md` — absorb the phase design principles
-5. Read `task-design.md` — understand task granularity (needed to judge phase scope)
-6. Read `plan-index-schema.md` — understand the plan index structure
-7. Design the phase structure
+5. Read the context-specific phase design guidance
+6. Read `task-design.md` — understand task granularity (needed to judge phase scope)
+7. Read `plan-index-schema.md` — understand the plan index structure
+8. Design the phase structure
 
 If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
 
@@ -59,7 +61,7 @@ Continue for all phases.
 
 ## Rules
 
-1. **Walking skeleton first** — Phase 1 is always the thinnest end-to-end slice
+1. **Strongest foundation first** — Phase 1 establishes the pattern for subsequent phases. Follow the Phase 1 strategy from the loaded context guidance.
 2. **Vertical phases** — each phase delivers working functionality, not technical layers
 3. **Clear acceptance** — every criterion is pass/fail verifiable
 4. **No forward references** — no phase depends on something not yet built

package/agents/planning-task-designer.md

@@ -17,9 +17,10 @@ You receive file paths via the orchestrator's prompt:
 2. **Specification path** — The validated specification to plan from
 3. **Cross-cutting spec paths** (if any) — Architectural decisions that influence planning
 4. **task-design.md** — Task design principles
-5. **All approved phases** — The complete phase structure (from the Plan Index File)
-6. **Target phase number** — Which phase to break into tasks
-7. **plan-index-schema.md** — Canonical plan index structure
+5. **Context-specific task design** — Work-type guidance (greenfield, feature, or bugfix)
+6. **All approved phases** — The complete phase structure (from the Plan Index File)
+7. **Target phase number** — Which phase to break into tasks
+8. **plan-index-schema.md** — Canonical plan index structure
 
 On **amendment**, you also receive:
 - **Previous output** — Your prior task list
@@ -31,9 +32,10 @@ On **amendment**, you also receive:
 2. Read the specification in full, following the ingestion protocol
 3. Read any cross-cutting specifications
 4. Read `task-design.md` — absorb the task design principles
-5. Read the approved phases — understand the full plan structure and where this phase fits
-6. Read `plan-index-schema.md` — understand the plan index structure
-7. Design the task list for the target phase
+5. Read the context-specific task design guidance
+6. Read the approved phases — understand the full plan structure and where this phase fits
+7. Read `plan-index-schema.md` — understand the plan index structure
+8. Design the task list for the target phase
 
 If this is an **amendment**: read your previous output and the user's feedback, then revise accordingly.
 

package/agents/review-findings-synthesizer.md

@@ -26,8 +26,8 @@ You receive via the orchestrator's prompt:
 4. **Group related findings** — multiple findings about the same concern become one task (e.g., 3 QA findings about missing error handling in the same module = 1 "add error handling" task)
 5. **Filter** — discard low-severity non-blocking findings unless they cluster into a pattern. Never discard high-severity or blocking findings.
 6. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
-7. **Write report** — output to `docs/workflow/implementation/{topic}/review-report-c{cycle}.md`
-8. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/review-tasks-c{cycle}.md` with `status: pending` for each task
+7. **Write report** — output to `.workflows/implementation/{topic}/review-report-c{cycle}.md`
+8. **Write staging file** — if actionable tasks exist, write to `.workflows/implementation/{topic}/review-tasks-c{cycle}.md` with `status: pending` for each task
 
 ## Report Format
 

package/agents/review-task-verifier.md

@@ -87,7 +87,7 @@ Review the implementation as a senior architect would:
 
 ## Output File Format
 
-Write to `docs/workflow/review/{topic}/r{N}/qa-task-{index}.md`:
+Write to `.workflows/review/{topic}/r{N}/qa-task-{index}.md`:
 
 ```
 TASK: [Task name/description]

package/hooks/workflows/compact-recovery.sh

@@ -21,7 +21,7 @@ if [ -z "$session_id" ]; then
   exit 0
 fi
 
-SESSION_FILE="$PROJECT_DIR/docs/workflow/.cache/sessions/${session_id}.yaml"
+SESSION_FILE="$PROJECT_DIR/.workflows/.cache/sessions/${session_id}.yaml"
 
 if [ ! -f "$SESSION_FILE" ]; then
   exit 0

package/hooks/workflows/session-cleanup.sh

@@ -17,7 +17,7 @@ fi
 session_id=$(cat | grep -o '"session_id" *: *"[^"]*"' | sed 's/.*: *"//;s/"//')
 
 if [ -n "$session_id" ]; then
-  session_file="$PROJECT_DIR/docs/workflow/.cache/sessions/${session_id}.yaml"
+  session_file="$PROJECT_DIR/.workflows/.cache/sessions/${session_id}.yaml"
   if [ -f "$session_file" ]; then
     rm -f "$session_file"
   fi

package/hooks/workflows/write-session-state.sh

@@ -42,7 +42,7 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-SESSIONS_DIR="$PROJECT_DIR/docs/workflow/.cache/sessions"
+SESSIONS_DIR="$PROJECT_DIR/.workflows/.cache/sessions"
 mkdir -p "$SESSIONS_DIR"
 
 SESSION_FILE="$SESSIONS_DIR/${CLAUDE_SESSION_ID}.yaml"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.40",
+  "version": "2.1.41",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/begin-implementation/SKILL.md

@@ -117,7 +117,7 @@ Environment: No special setup required.
 > *Output the next fenced block as a code block:*
 
 ```
-Environment setup file found: docs/workflow/environment-setup.md
+Environment setup file found: .workflows/environment-setup.md
 ```
 
 → Proceed to **Step 4**.
@@ -133,8 +133,8 @@ Are there any environment setup instructions I should follow before implementati
 
 **STOP.** Wait for user response.
 
-- If the user provides instructions, save them to `docs/workflow/environment-setup.md`, commit
-- If the user says no/none, create `docs/workflow/environment-setup.md` with "No special setup required." and commit
+- If the user provides instructions, save them to `.workflows/environment-setup.md`, commit
+- If the user says no/none, create `.workflows/environment-setup.md` with "No special setup required." and commit
 
 → Proceed to **Step 4**.
 
@@ -150,10 +150,10 @@ Construct the handoff and invoke the [technical-implementation](../technical-imp
 
 ```
 Implementation session for: {topic}
-Plan: docs/workflow/planning/{topic}/plan.md
+Plan: .workflows/planning/{topic}/plan.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
-Specification: docs/workflow/specification/{topic}/specification.md (exists: {true|false})
+Specification: .workflows/specification/{topic}/specification.md (exists: {true|false})
 Implementation tracking: {exists | new} (status: {status})
 Dependencies: {All satisfied | notes}
 Environment: {Setup required | No special setup required}

package/skills/begin-planning/SKILL.md

@@ -82,7 +82,8 @@ Construct the handoff and invoke the [technical-planning](../technical-planning/
 
 ```
 Planning session for: {topic}
-Specification: docs/workflow/specification/{topic}/specification.md
+Specification: .workflows/specification/{topic}/specification.md
+Work type: feature
 Additional context: {summary of user's answer from Step 3, or "none"}
 Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
 Recommended output format: {common_format from discovery if non-empty, otherwise "none"}

package/skills/begin-review/SKILL.md

@@ -80,7 +80,7 @@ Construct the handoff and invoke the [technical-review](../technical-review/SKIL
 Review session
 Plans to review:
   - topic: {topic}
-    plan: docs/workflow/planning/{topic}/plan.md
+    plan: .workflows/planning/{topic}/plan.md
     format: {format}
     plan_id: {plan_id} (if applicable)
     specification: {specification} (exists: {true|false})

package/skills/continue-feature/references/detect-phase.md

@@ -14,22 +14,22 @@ Either use the `next_phase` from discovery output (if discovery was run), or com
 
 Check artifacts in this order (first match wins):
 
-1. Check `docs/workflow/review/{topic}/r*/review.md`
+1. Check `.workflows/review/{topic}/r*/review.md`
    - If any review exists → next_phase is **"done"**
 
-2. Read `docs/workflow/implementation/{topic}/tracking.md`
+2. Read `.workflows/implementation/{topic}/tracking.md`
    - If exists with `status: completed` → next_phase is **"review"**
    - If exists with `status: in-progress` → next_phase is **"implementation"**
 
-3. Read `docs/workflow/planning/{topic}/plan.md`
+3. Read `.workflows/planning/{topic}/plan.md`
    - If exists with `status: concluded` → next_phase is **"implementation"**
    - If exists with other status → next_phase is **"planning"**
 
-4. Read `docs/workflow/specification/{topic}/specification.md`
+4. Read `.workflows/specification/{topic}/specification.md`
    - If exists with `status: concluded` → next_phase is **"planning"**
    - If exists with other status → next_phase is **"specification"**
 
-5. Check `docs/workflow/discussion/{topic}.md`
+5. Check `.workflows/discussion/{topic}.md`
    - If exists with `status: concluded` → next_phase is **"specification"**
    - If exists with other status → next_phase is **"discussion"**
 

package/skills/continue-feature/references/invoke-implementation.md

@@ -20,7 +20,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-implementation/SKILL.md" \
-  "docs/workflow/implementation/{topic}/tracking.md" \
+  ".workflows/implementation/{topic}/tracking.md" \
   --pipeline "This session is part of the feature pipeline. After implementation completes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
@@ -30,7 +30,7 @@ Invoke the [begin-implementation](../../begin-implementation/SKILL.md) skill:
 
 ```
 Implementation pre-flight for: {topic}
-Plan: docs/workflow/planning/{topic}/plan.md
+Plan: .workflows/planning/{topic}/plan.md
 
 PIPELINE CONTINUATION — When implementation completes (tracking status: completed),
 you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).

package/skills/continue-feature/references/invoke-planning.md

@@ -20,7 +20,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-planning/SKILL.md" \
-  "docs/workflow/planning/{topic}/plan.md" \
+  ".workflows/planning/{topic}/plan.md" \
   --pipeline "This session is part of the feature pipeline. After the plan concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
@@ -30,7 +30,7 @@ Invoke the [begin-planning](../../begin-planning/SKILL.md) skill:
 
 ```
 Planning pre-flight for: {topic}
-Specification: docs/workflow/specification/{topic}/specification.md
+Specification: .workflows/specification/{topic}/specification.md
 
 PIPELINE CONTINUATION — When planning concludes (plan status: concluded),
 you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).

package/skills/continue-feature/references/invoke-review.md

@@ -20,7 +20,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-review/SKILL.md" \
-  "docs/workflow/review/{topic}/r{N}/review.md" \
+  ".workflows/review/{topic}/r{N}/review.md" \
   --pipeline "This session is part of the feature pipeline. After the review concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
@@ -30,7 +30,7 @@ Invoke the [begin-review](../../begin-review/SKILL.md) skill:
 
 ```
 Review pre-flight for: {topic}
-Plan: docs/workflow/planning/{topic}/plan.md
+Plan: .workflows/planning/{topic}/plan.md
 
 PIPELINE CONTINUATION — When review concludes,
 you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).

package/skills/continue-feature/references/invoke-specification.md

@@ -10,7 +10,7 @@ Invoke the specification skill for this topic.
 
 The specification needs source material. Check what's available:
 
-1. **Discussion document**: `docs/workflow/discussion/{topic}.md`
+1. **Discussion document**: `.workflows/discussion/{topic}.md`
    - If exists and concluded → use as primary source
    - If exists and in-progress → this shouldn't happen (detect-phase would have routed to discussion)
 
@@ -30,7 +30,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-specification/SKILL.md" \
-  "docs/workflow/specification/{topic}/specification.md" \
+  ".workflows/specification/{topic}/specification.md" \
   --pipeline "This session is part of the feature pipeline. After the specification concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
@@ -42,7 +42,7 @@ Invoke the [technical-specification](../../technical-specification/SKILL.md) ski
 Specification session for: {topic}
 
 Source material:
-- Discussion: docs/workflow/discussion/{topic}.md
+- Discussion: .workflows/discussion/{topic}.md
 
 Topic name: {topic}
 

package/skills/continue-feature/scripts/discovery.sh

@@ -11,11 +11,11 @@
 
 set -eo pipefail
 
-DISC_DIR="docs/workflow/discussion"
-SPEC_DIR="docs/workflow/specification"
-PLAN_DIR="docs/workflow/planning"
-IMPL_DIR="docs/workflow/implementation"
-REVIEW_DIR="docs/workflow/review"
+DISC_DIR=".workflows/discussion"
+SPEC_DIR=".workflows/specification"
+PLAN_DIR=".workflows/planning"
+IMPL_DIR=".workflows/implementation"
+REVIEW_DIR=".workflows/review"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>

package/skills/link-dependencies/SKILL.md

@@ -24,8 +24,8 @@ Use simple, individual commands. Never combine multiple operations into bash loo
 
 Scan the codebase for existing plans:
 
-1. **Find plan files**: Look in `docs/workflow/planning/`
-   - Run `ls docs/workflow/planning/` to list plan files
+1. **Find plan files**: Look in `.workflows/planning/`
+   - Run `ls .workflows/planning/` to list plan files
    - Each topic is a directory containing `plan.md`
 
 2. **Extract plan metadata**: For each plan file
@@ -39,7 +39,7 @@ Scan the codebase for existing plans:
 ```
 Dependency Linking
 
-No plans found in docs/workflow/planning/
+No plans found in .workflows/planning/
 
 There are no plans to link. Create plans first.
 ```
@@ -122,7 +122,7 @@ Key:
 
 For each unresolved dependency:
 
-1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}/plan.md` exist?
+1. **Search for matching plan**: Does `.workflows/planning/{dependency-topic}/plan.md` exist?
    - If no match: Mark as "no plan exists" - cannot resolve yet
 
 2. **If plan exists**: Load the format's reading reference
@@ -174,7 +174,7 @@ Unresolved (no matching plan exists):
   • {source} → {target}: {description}
 
 Updated files:
-  • docs/workflow/planning/{topic}/plan.md
+  • .workflows/planning/{topic}/plan.md
 ```
 
 If any dependencies remain unresolved:

package/skills/migrate/SKILL.md

@@ -39,7 +39,7 @@ Return control silently - no user interaction needed.
 ## Notes
 
 - This skill is run automatically at the start of every workflow skill
-- Migrations are tracked in `docs/workflow/.state/migrations` (one migration ID per line)
+- Migrations are tracked in `.workflows/.state/migrations` (one migration ID per line)
 - The orchestrator skips entire migrations once recorded — individual scripts don't track
 - To force re-running all migrations, delete the tracking file
 - Each migration is idempotent - safe to run multiple times

package/skills/migrate/scripts/migrate.sh

@@ -9,7 +9,7 @@
 #   ./scripts/migrate.sh
 #
 # Tracking:
-#   Migrations are tracked in docs/workflow/.state/migrations
+#   Migrations are tracked in .workflows/.state/migrations
 #   Format: "migration_id" per line (e.g., "001", "002")
 #   The orchestrator checks/records migration IDs — individual scripts don't track.
 #   Delete the log file to force re-running all migrations.
@@ -24,28 +24,65 @@ set -eo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 MIGRATIONS_DIR="$SCRIPT_DIR/migrations"
-TRACKING_FILE="docs/workflow/.state/migrations"
 
-# Track counts for final report
-FILES_UPDATED=0
-FILES_SKIPPED=0
-MIGRATIONS_RUN=0
+# === LEGACY TRACKING SUPPORT (remove after 2026-06) ===
+#
+# Handles tracking file discovery across historical locations and formats.
+# Once all users have run migration 011, replace this section with:
+#   TRACKING_FILE=".workflows/.state/migrations"
+#   mkdir -p "$(dirname "$TRACKING_FILE")"
+
+find_tracking_file() {
+    for candidate in \
+        ".workflows/.state/migrations" \
+        "docs/workflow/.state/migrations" \
+        "docs/workflow/.cache/migrations" \
+        "docs/workflow/.cache/migrations.log"
+    do
+        [ -f "$candidate" ] && echo "$candidate" && return
+    done
+    echo ".workflows/.state/migrations"
+}
 
-# Ensure state directory exists
-mkdir -p "$(dirname "$TRACKING_FILE")"
+normalize_tracking_format() {
+    local file="$1"
+    [ ! -f "$file" ] && return
+    # Old: "docs/workflow/discussion/auth.md: 001" → New: "001"
+    if grep -q ': [0-9]' "$file" 2>/dev/null; then
+        grep -oE '[0-9]+$' "$file" | sort -u > "${file}.tmp"
+        mv "${file}.tmp" "$file"
+    fi
+}
 
-# Self-healing: merge entries from old locations into .state/migrations
-OLD_CACHE_LOG="docs/workflow/.cache/migrations.log"
-OLD_CACHE_FILE="docs/workflow/.cache/migrations"
-if [ -f "$OLD_CACHE_LOG" ] || [ -f "$OLD_CACHE_FILE" ]; then
-    { cat "$OLD_CACHE_LOG" 2>/dev/null || true; cat "$OLD_CACHE_FILE" 2>/dev/null || true; cat "$TRACKING_FILE" 2>/dev/null || true; } | sort -u > "${TRACKING_FILE}.tmp"
-    mv "${TRACKING_FILE}.tmp" "$TRACKING_FILE"
-    rm -f "$OLD_CACHE_LOG" "$OLD_CACHE_FILE"
-fi
+stabilize_tracking_location() {
+    local file="$1"
+    local stable="docs/workflow/.state/migrations"
+    # If tracking is at a legacy .cache/ location, move to .state/ so it survives migration 010
+    case "$file" in
+        docs/workflow/.cache/*)
+            mkdir -p "$(dirname "$stable")"
+            mv "$file" "$stable"
+            echo "$stable"
+            ;;
+        *)
+            echo "$file"
+            ;;
+    esac
+}
 
-# Touch tracking file if it doesn't exist
+TRACKING_FILE=$(find_tracking_file)
+normalize_tracking_format "$TRACKING_FILE"
+TRACKING_FILE=$(stabilize_tracking_location "$TRACKING_FILE")
+mkdir -p "$(dirname "$TRACKING_FILE")"
 touch "$TRACKING_FILE"
 
+# === END LEGACY TRACKING SUPPORT ===
+
+# Track counts for final report
+FILES_UPDATED=0
+FILES_SKIPPED=0
+MIGRATIONS_RUN=0
+
 #
 # Helper function: Report a file update (for migration scripts to call)
 # Usage: report_update "filepath" "description"
@@ -88,14 +125,6 @@ if [ ${#MIGRATION_SCRIPTS[@]} -eq 0 ]; then
     exit 0
 fi
 
-# One-time: convert old per-file format to per-migration format
-# Old: "docs/workflow/discussion/auth.md: 001" → extracts "001"
-# New: "001" → already correct
-if grep -q ': [0-9]' "$TRACKING_FILE" 2>/dev/null; then
-    grep -oE '[0-9]+$' "$TRACKING_FILE" | sort -u > "${TRACKING_FILE}.tmp"
-    mv "${TRACKING_FILE}.tmp" "$TRACKING_FILE"
-fi
-
 for script in "${MIGRATION_SCRIPTS[@]}"; do
     # Extract migration ID from filename (e.g., "001" from "001-discussion-frontmatter.sh")
     migration_id=$(basename "$script" .sh | grep -oE '^[0-9]+')
@@ -115,6 +144,8 @@ for script in "${MIGRATION_SCRIPTS[@]}"; do
     # shellcheck source=/dev/null
     source "$script"
 
+    # Re-find tracking file (migration 011 moves it)
+    TRACKING_FILE=$(find_tracking_file)
     echo "$migration_id" >> "$TRACKING_FILE"
     MIGRATIONS_RUN=$((MIGRATIONS_RUN + 1))
 done