@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/workflows/edit-phase.md

@@ -0,0 +1,295 @@
+<purpose>
+Edit any field of an existing phase in ROADMAP.md in place. The phase number and position are always preserved. Guarded against in-progress and completed phases unless --force is passed. Validates depends_on references before writing. Shows a diff and requests confirmation before writing.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: phase number to edit (integer or decimal)
+- Optional flag: --force (allow editing in_progress/completed phases)
+
+Examples:
+  `/gsd-edit-phase 5`       → phase = 5, force = false
+  `/gsd-edit-phase 5 --force` → phase = 5, force = true
+  `/gsd-edit-phase 12.1`    → phase = 12.1, force = false
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /gsd-edit-phase <phase-number> [--force]
+Example: /gsd-edit-phase 5
+Example: /gsd-edit-phase 5 --force
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.phase-op "${target}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Check `roadmap_exists` from init JSON. If false:
+```
+ERROR: No roadmap found (.planning/ROADMAP.md)
+Run /gsd:new-project to initialize.
+```
+Exit.
+</step>
+
+<step name="load_phase">
+Read the current phase section from ROADMAP.md:
+
+```bash
+PHASE_DATA=$(gsd_run query roadmap get-phase "${target}")
+```
+
+Parse the JSON result. If `found` is false:
+
+```
+ERROR: Phase {target} not found in ROADMAP.md
+
+Available phases can be seen with /gsd:progress.
+```
+
+Exit.
+
+Extract from the result:
+- `phase_name` — the phase title
+- `goal` — the phase goal/description
+- `success_criteria` — array of criteria
+- `section` — full raw section text (preserves depends_on, requirements, plans, etc.)
+
+Also parse the full section text to extract additional fields not in the SDK result:
+- `depends_on` — from `**Depends on:** ...` or `**Depends on**: ...` line
+- `requirements` — from `**Requirements:** ...` block if present
+</step>
+
+<step name="check_phase_status">
+Determine the phase status from disk. Compare against STATE.md current phase:
+
+```bash
+ANALYZE=$(gsd_run query roadmap analyze)
+```
+
+Find the phase entry in the `phases` array. Extract `disk_status`.
+
+Map disk_status to a user-friendly status:
+- `complete` → status = `completed`
+- `planned` or `partial` → status = `in_progress`
+- `empty`, `no_directory`, `discussed`, `researched` → status = `future`
+
+If status is `in_progress` or `completed` AND `--force` was NOT passed:
+
+```
+ERROR: Cannot edit Phase {target} — status is {status}
+
+Editing an in-progress or completed phase may invalidate executed plans.
+
+To edit anyway, run:
+  /gsd-edit-phase {target} --force
+```
+
+Exit.
+
+If `--force` was passed and status is `in_progress` or `completed`, continue with a warning printed to the user:
+
+```
+WARNING: Editing Phase {target} which is {status}. Proceeding due to --force.
+```
+</step>
+
+<step name="present_current_values">
+Display the current phase fields clearly:
+
+```
+Current values for Phase {target}: {phase_name}
+
+Title:            {phase_name}
+Goal:             {goal}
+Depends on:       {depends_on or "(none)"}
+Requirements:     {requirements or "(none)"}
+Success Criteria:
+  1. {criterion_1}
+  2. {criterion_2}
+  ...
+```
+
+Then ask the user what they want to change:
+
+```
+What would you like to do?
+
+  [1] Edit specific fields (title, goal, depends_on, requirements, success_criteria)
+  [2] Regenerate all fields from a clarified intent
+  [3] Cancel
+
+Enter choice (1, 2, or 3):
+```
+
+Wait for user input.
+</step>
+
+<step name="collect_edits">
+
+**If user chose [3] Cancel:** Exit cleanly.
+
+**If user chose [1] Edit specific fields:**
+
+Ask which fields to edit. For each field the user wants to change, prompt for the new value. Only fields the user explicitly answers become updates; empty answers preserve the existing value.
+
+```
+Which fields do you want to update? (comma-separated or "all")
+Options: title, goal, depends_on, requirements, success_criteria
+```
+
+For each selected field, ask:
+
+```
+New value for {field} [current: {current_value}]:
+```
+
+Build an `updates` map of {field → new_value} for non-empty answers.
+
+**If user chose [2] Regenerate all from clarified intent:**
+
+Ask the user:
+
+```
+Describe the revised intent for Phase {target} (replace the current description):
+```
+
+Wait for user input. Use the clarified intent to rewrite all fields:
+- Generate a clear, concise `title` from the intent
+- Write a complete `goal` statement
+- Produce updated `requirements` if the original had them
+- Generate `success_criteria` (3-5 measurable criteria)
+- Preserve `depends_on` unless the user explicitly mentioned changing it
+</step>
+
+<step name="validate_depends_on">
+If `depends_on` is being updated (or preserved as non-empty), validate that every referenced phase number exists in ROADMAP.md:
+
+```bash
+ALL_PHASES=$(gsd_run query roadmap analyze)
+```
+
+Parse the `phases` array to get all valid phase numbers.
+
+For each phase number referenced in `depends_on`:
+- Normalize it (strip whitespace, "Phase" prefix if present)
+- Check it is in the valid phase numbers set
+- It must not reference itself (phase {target})
+
+If any reference is invalid:
+
+```
+ERROR: depends_on references invalid phase(s): {bad_refs}
+
+Valid phase numbers: {valid_list}
+
+Fix the depends_on field and try again.
+```
+
+Exit (do not write).
+</step>
+
+<step name="show_diff_and_confirm">
+Build the updated phase section by applying the changes to the original `section` text:
+
+- For `title`: replace the heading text after `Phase {N}:`
+- For `goal`: replace the `**Goal:**` line value
+- For `depends_on`: replace or add the `**Depends on:**` line
+- For `requirements`: replace or add the requirements block
+- For `success_criteria`: replace the numbered list under `**Success Criteria**:`
+- For full regeneration: rebuild the entire section from the new field values
+
+Show a unified-style diff of old vs. new:
+
+```
+Proposed changes to Phase {target}:
+
+--- current
++++ updated
+@@ ...
+- **Goal:** {old_goal}
++ **Goal:** {new_goal}
+...
+
+Apply these changes? (y/n):
+```
+
+Wait for confirmation. If the user says `n`, exit without writing.
+</step>
+
+<step name="write_updated_phase">
+Write the updated phase back in place in ROADMAP.md.
+
+Read the full ROADMAP.md content, locate the phase section by its header (`## Phase {N}:` or `### Phase {N}:`), and replace exactly the old section text with the new section text. All content before and after the section (including other phases, milestone headers, and the summary checklist) must be left unchanged.
+
+After writing ROADMAP.md, update STATE.md Roadmap Evolution:
+
+```bash
+gsd_run query state.add-roadmap-evolution \
+  --phase {target} \
+  --action edited \
+  --note "edited fields: {changed_field_list}"
+```
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} updated in ROADMAP.md.
+
+Fields changed: {changed_field_list}
+
+---
+
+## What's Next
+
+- `/gsd:progress` — view updated roadmap
+- `/gsd:plan-phase {target}` — re-plan this phase (if needed)
+- `/gsd:discuss-phase {target}` — discuss implementation approach
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+- Don't renumber the phase — number and position must be preserved exactly
+- Don't modify other phases when editing one
+- Don't skip depends_on validation (invalid references block writes)
+- Don't write without showing a diff and getting confirmation
+- Don't edit in_progress/completed phases without --force
+- Don't use raw Write on ROADMAP.md without reading it first; always replace section in place
+- Don't modify the phase directory structure — only ROADMAP.md changes
+- Don't commit the change — that's the user's decision
+</anti_patterns>
+
+<success_criteria>
+Edit-phase is complete when:
+
+- [ ] Phase {target} found and loaded from ROADMAP.md
+- [ ] Status check performed; in_progress/completed blocked without --force
+- [ ] Current values presented to user
+- [ ] User chose edit mode (specific fields or full regeneration)
+- [ ] depends_on references validated; invalid references blocked
+- [ ] Diff shown and confirmed by user
+- [ ] Updated phase written back in place; number, position, and status preserved
+- [ ] STATE.md Roadmap Evolution updated
+- [ ] User informed of next steps
+</success_criteria>

package/get-shit-done/workflows/eval-review.md

@@ -0,0 +1,156 @@
+<purpose>
+Retroactive audit of an implemented AI phase's evaluation coverage. Standalone command that works on any GSD-managed AI phase. Produces a scored EVAL-REVIEW.md with gap analysis and remediation plan.
+
+Use after /gsd:execute-phase to verify that the evaluation strategy from AI-SPEC.md was actually implemented. Mirrors the pattern of /gsd:ui-review and /gsd:validate-phase.
+</purpose>
+
+<required_reading>
+@~/.claude/get-shit-done/references/ai-evals.md
+</required_reading>
+
+<process>
+
+## 0. Initialize
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+INIT=$(gsd_run query init.phase-op "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
+
+```bash
+AUDITOR_MODEL=$(gsd_run query resolve-model gsd-eval-auditor 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+```
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► EVAL AUDIT — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 1. Detect Input State
+
+```bash
+SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
+AI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-AI-SPEC.md 2>/dev/null | head -1)
+EVAL_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-EVAL-REVIEW.md 2>/dev/null | head -1)
+```
+
+**State A** — AI-SPEC.md + SUMMARY.md exist: Full audit against spec
+**State B** — SUMMARY.md exists, no AI-SPEC.md: Audit against general best practices
+**State C** — No SUMMARY.md: Exit — "Phase {N} not executed. Run /gsd:execute-phase {N} first."
+
+
+**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**If `EVAL_REVIEW_FILE` non-empty:** Use AskUserQuestion:
+- header: "Existing Eval Review"
+- question: "EVAL-REVIEW.md already exists for Phase {N}."
+- options:
+  - "Re-audit — run fresh audit"
+  - "View — display current review and exit"
+
+If "View": display file, exit.
+If "Re-audit": continue.
+
+**If State B (no AI-SPEC.md):** Warn:
+```
+No AI-SPEC.md found for Phase {N}.
+Audit will evaluate against general AI eval best practices rather than a phase-specific plan.
+Consider running /gsd:ai-integration-phase {N} before implementation next time.
+```
+Continue (non-blocking).
+
+## 2. Gather Context Paths
+
+Build file list for auditor:
+- AI-SPEC.md (if exists — the planned eval strategy)
+- All SUMMARY.md files in phase dir
+- All PLAN.md files in phase dir
+
+## 3. Spawn gsd-eval-auditor
+
+```
+◆ Spawning eval auditor...
+```
+
+Build prompt:
+
+```markdown
+Read ~/.claude/agents/gsd-eval-auditor.md for instructions.
+
+<objective>
+Conduct evaluation coverage audit of Phase {phase_number}: {phase_name}
+{If AI-SPEC exists: "Audit against AI-SPEC.md evaluation plan."}
+{If no AI-SPEC: "Audit against general AI eval best practices."}
+</objective>
+
+<files_to_read>
+- {summary_paths}
+- {plan_paths}
+- {ai_spec_path if exists}
+</files_to_read>
+
+<input>
+ai_spec_path: {ai_spec_path or "none"}
+phase_dir: {phase_dir}
+phase_number: {phase_number}
+phase_name: {phase_name}
+padded_phase: {padded_phase}
+state: {A or B}
+</input>
+```
+
+Spawn as Task with model `AUDITOR_MODEL`.
+
+## 4. Parse Auditor Result
+
+Read the written EVAL-REVIEW.md. Extract:
+- `overall_score`
+- `verdict` (PRODUCTION READY | NEEDS WORK | SIGNIFICANT GAPS | NOT IMPLEMENTED)
+- `critical_gap_count`
+
+## 5. Display Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► EVAL AUDIT COMPLETE — PHASE {N}: {name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Score: {overall_score}/100
+◆ Verdict: {verdict}
+◆ Critical Gaps: {critical_gap_count}
+◆ Output: {eval_review_path}
+
+{If PRODUCTION READY:}
+  Next step: /gsd:plan-phase (next phase) or deploy
+
+{If NEEDS WORK:}
+  Address critical gaps in EVAL-REVIEW.md, then re-run /gsd:eval-review {N}
+
+{If SIGNIFICANT GAPS or NOT IMPLEMENTED:}
+  Review AI-SPEC.md evaluation plan. Critical eval dimensions are not implemented.
+  Do not deploy until gaps are addressed.
+```
+
+## 6. Commit
+
+**If `commit_docs` is true:**
+```bash
+git add "${EVAL_REVIEW_FILE}"
+git commit -m "docs({phase_slug}): add EVAL-REVIEW.md — score {overall_score}/100 ({verdict})"
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase execution state detected correctly
+- [ ] AI-SPEC.md presence handled (with or without)
+- [ ] gsd-eval-auditor spawned with correct context
+- [ ] EVAL-REVIEW.md written (by auditor)
+- [ ] Score and verdict displayed to user
+- [ ] Appropriate next steps surfaced based on verdict
+- [ ] Committed if commit_docs enabled
+</success_criteria>

package/get-shit-done/workflows/execute-phase/steps/codebase-drift-gate.md

@@ -0,0 +1,82 @@
+# Step: codebase_drift_gate
+
+Post-execution structural drift detection (#2003). Runs after the last wave
+commits, before verification. **Non-blocking by contract:** any internal
+error here MUST fall through and continue to `verify_phase_goal`. The phase
+is never failed by this gate.
+
+```bash
+DRIFT=$(gsd-tools verify codebase-drift 2>/dev/null || echo '{"skipped":true,"reason":"sdk-failed"}')
+```
+
+Parse JSON for: `skipped`, `reason`, `action_required`, `directive`,
+`spawn_mapper`, `affected_paths`, `elements`, `threshold`, `action`,
+`last_mapped_commit`, `message`.
+
+**If `skipped` is true (no STRUCTURE.md, missing git, or any internal error):**
+Log one line — `Codebase drift check skipped: {reason}` — and continue to
+`verify_phase_goal`. Do NOT prompt the user. Do NOT block.
+
+**If `action_required` is false:** Continue silently to `verify_phase_goal`.
+
+**If `action_required` is true AND `directive` is `warn`:**
+Print the `message` field verbatim. The format is:
+
+```text
+Codebase drift detected: {N} structural element(s) since last mapping.
+
+New directories:
+  - {path}
+New barrel exports:
+  - {path}
+New migrations:
+  - {path}
+New route modules:
+  - {path}
+
+Run /gsd:map-codebase --paths {affected_paths} to refresh planning context.
+```
+
+Then continue to `verify_phase_goal`. Do NOT block. Do NOT spawn anything.
+
+**If `action_required` is true AND `directive` is `auto-remap`:**
+
+First load the mapper agent's skill bundle (the executor's `AGENT_SKILLS`
+from step `init_context` is for `gsd-executor`, not the mapper):
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/get-shit-done/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/get-shit-done/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+AGENT_SKILLS_MAPPER=$(gsd_run query agent-skills gsd-codebase-mapper)
+```
+
+Then spawn `gsd-codebase-mapper` agents with the `--paths` hint:
+
+```text
+Agent(
+  subagent_type="gsd-codebase-mapper",
+  description="Incremental codebase remap (drift)",
+  prompt="Focus: arch
+Today's date: {date}
+--paths {affected_paths joined by comma}
+
+Refresh STRUCTURE.md and ARCHITECTURE.md scoped to the listed paths only.
+Stamp last_mapped_commit in each document's frontmatter.
+${AGENT_SKILLS_MAPPER}"
+)
+```
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
+
+If the spawn fails or the agent reports an error: log `Codebase drift
+auto-remap failed: {reason}` and continue to `verify_phase_goal`. The phase
+is NOT failed by a remap failure.
+
+If the remap succeeds: log `Codebase drift auto-remap completed for paths:
+{affected_paths}` and continue to `verify_phase_goal`.
+
+The two relevant config keys (continue on error / failure if either is invalid):
+- `workflow.drift_threshold` (integer, default 3) — minimum drift elements before action
+- `workflow.drift_action` — `warn` (default) or `auto-remap`
+
+This step is fully non-blocking — it never fails the phase, and any
+exception path returns control to `verify_phase_goal`.

package/get-shit-done/workflows/execute-phase/steps/per-plan-worktree-gate.md

@@ -0,0 +1,94 @@
+# Per-plan worktree decision (#2772)
+
+Run this for **each plan in the current wave** before its `Agent()` dispatch. The output `USE_WORKTREES_FOR_PLAN` gates the dispatch branch (worktree mode vs sequential mode) for that plan only — other plans in the same wave can still take the worktree path.
+
+`SUBMODULE_PATHS` is computed once in the `initialize` step (parsed from `.gitmodules`).
+
+`PLAN_FILES` is the whitespace-separated list of paths the plan declared it will touch, extracted from the `phase-plan-index` JSON loaded in `discover_and_group_plans`:
+
+```bash
+# plan_json is the JSON object for this plan from PLAN_INDEX.plans[]
+# files_modified is an array of strings (repo-relative paths or globs)
+PLAN_FILES=$(jq -r '.files_modified // [] | join(" ")' <<<"$plan_json")
+plan_id=$(jq -r '.id' <<<"$plan_json")
+```
+
+Then run the per-plan gate:
+
+```bash
+USE_WORKTREES_FOR_PLAN="$USE_WORKTREES"
+
+if [ -n "$SUBMODULE_PATHS" ] && [ "$USE_WORKTREES_FOR_PLAN" != "false" ]; then
+  if [ -z "$PLAN_FILES" ]; then
+    # Fallback: planned paths are unknown/unparseable — fall back to the safe
+    # behavior (disable worktree isolation for this plan) and log why.
+    echo "[worktree] Plan ${plan_id}: files_modified missing/unparseable — disabling worktree isolation as a safety fallback (submodule project)"
+    USE_WORKTREES_FOR_PLAN=false
+  else
+    # Compute intersection with glob-safe normalization. Both sides are
+    # normalized (strip leading "./", strip trailing "/") and matched
+    # bidirectionally so a globby planned path like "vendor/**/*.c" still
+    # matches submodule "vendor/foo", and "./vendor/foo/bar.c" matches
+    # submodule "vendor/foo".
+    INTERSECT=""
+    set -f  # disable globbing while iterating literal patterns
+    for sm_raw in $SUBMODULE_PATHS; do
+      # Normalize submodule path: strip ./ prefix and trailing /
+      sm="${sm_raw#./}"
+      sm="${sm%/}"
+      [ -z "$sm" ] && continue
+      for pf_raw in $PLAN_FILES; do
+        # Normalize planned path the same way
+        pf="${pf_raw#./}"
+        pf="${pf%/}"
+        [ -z "$pf" ] && continue
+        matched=0
+        # Direction 1: planned path is the submodule or lies inside it
+        case "$pf" in
+          "$sm"|"$sm"/*) matched=1 ;;
+        esac
+        # Direction 2: submodule lies inside the planned path (e.g. plan
+        # declares "vendor" or a glob expanding to a directory containing
+        # the submodule).
+        if [ "$matched" -eq 0 ]; then
+          case "$sm" in
+            "$pf"|"$pf"/*) matched=1 ;;
+          esac
+        fi
+        # Direction 3: planned path uses a glob — strip glob wildcards
+        # and check whether the resulting prefix overlaps the submodule
+        # path in either direction.
+        if [ "$matched" -eq 0 ]; then
+          case "$pf" in
+            *'*'*|*'?'*|*'['*)
+              # Take the literal prefix before the first glob metachar.
+              prefix="${pf%%[*?[]*}"
+              prefix="${prefix%/}"
+              if [ -n "$prefix" ]; then
+                case "$sm" in
+                  "$prefix"|"$prefix"/*) matched=1 ;;
+                esac
+                if [ "$matched" -eq 0 ]; then
+                  case "$prefix" in
+                    "$sm"|"$sm"/*) matched=1 ;;
+                  esac
+                fi
+              fi
+              ;;
+          esac
+        fi
+        if [ "$matched" -eq 1 ]; then
+          INTERSECT="$INTERSECT $pf_raw"
+        fi
+      done
+    done
+    set +f
+    if [ -n "$INTERSECT" ]; then
+      echo "[worktree] Plan ${plan_id}: planned paths intersect submodule paths (${INTERSECT# }) — disabling worktree isolation for this plan"
+      USE_WORKTREES_FOR_PLAN=false
+    fi
+  fi
+fi
+```
+
+After running this for the plan, the dispatch branches in `execute_waves` step 3 MUST gate on `USE_WORKTREES_FOR_PLAN` for the current plan, not on the project-level `USE_WORKTREES`. Track which plans in this wave actually used worktrees (append `plan_id` to a `WAVE_WORKTREE_PLANS` accumulator when `USE_WORKTREES_FOR_PLAN != false`) — the post-wave cleanup step (5.5) uses this to decide whether worktree-merge cleanup is needed at all.