@ktpartners/dgs-platform 2.9.0 → 3.0.4

package/deliver-great-systems/workflows/create-milestone-job.md

@@ -24,7 +24,7 @@ Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, c
 Parse `$ARGUMENTS` to extract version and flags.
 
 - **Version:** First non-flag argument (e.g., `v6`, `v6.0`). If omitted, auto-detection happens in the preview step.
-- **--no-check flag:** If present, omit audit-milestone and complete-milestone steps from the generated job.
+- **--no-check flag:** If present, omit the audit-milestone step from the generated job.
 
 ```bash
 # Pseudocode for argument parsing:
@@ -97,7 +97,7 @@ Present in this format:
 5. execute-phase 52
 6. verify-work 52
 ...
-N. complete-milestone v6.0
+N. audit-milestone v6.0
 
 Create this job? (yes/no)
 ```
@@ -123,13 +123,13 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs create-milestone VER
 2. Commit the job file:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs(50): create milestone job {version}" --files jobs/pending/milestone-{version}.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs(50): create milestone job {version}" --files jobs/milestone-{version}.md
 ```
 
 3. Display success and next steps:
 
 ```
-Job created: jobs/pending/milestone-{version}.md
+Job created: jobs/milestone-{version}.md
 
 ---
 

package/deliver-great-systems/workflows/develop-idea.md

@@ -89,7 +89,7 @@ Also check for prior research document:
 ```bash
 # Derive slug from filename (strip id prefix and .md suffix)
 SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
-RESEARCH_DOC="${project_root}/docs/ideas/pending/${SLUG}-research.md"
+RESEARCH_DOC="${project_root}/docs/ideas/${SLUG}-research.md"
 ```
 If the research document file exists, read it for prior research context.
 
@@ -281,7 +281,7 @@ Per CONTEXT.md: idea body is NOT updated on partial save.
 <step name="discussion_commit">
 Commit the updated idea file immediately after discussion:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: discuss idea #${id} — ${title}" --files ${project_root}/ideas/${state}/${filename}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: discuss idea #${id} — ${title}" --files ${project_root}/ideas/${filename}
 ```
 
 **If `partial = true`** (user exited mid-discussion):
@@ -392,10 +392,10 @@ Create (or overwrite) the research document.
 
 Ensure directory exists:
 ```bash
-mkdir -p ${project_root}/docs/ideas/pending
+mkdir -p ${project_root}/docs/ideas
 ```
 
-Write the research document to `${project_root}/docs/ideas/pending/${SLUG}-research.md` using the Write tool.
+Write the research document to `${project_root}/docs/ideas/${SLUG}-research.md` using the Write tool.
 
 Document structure:
 ```markdown
@@ -456,7 +456,7 @@ Build the entry JSON:
   "summary": "{Actionable summary paragraph}",
   "keyFindings": "- {finding 1}\n- {finding 2}\n- {finding 3}",
   "recommendation": "{Strong recommendation or neutral options presentation}",
-  "documentLink": "${project_root}/docs/ideas/pending/${SLUG}-research.md",
+  "documentLink": "${project_root}/docs/ideas/${SLUG}-research.md",
   "outcome": "{Recommended next step: 'Ready for spec', 'Needs more discussion', 'Not feasible', etc.}"
 }
 ```
@@ -472,7 +472,7 @@ Parse the JSON result to confirm success.
 <step name="research_commit">
 Commit both the research document and the updated idea file:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: research idea #${id} -- ${title}" --files ${project_root}/docs/ideas/pending/${SLUG}-research.md ${project_root}/ideas/${state}/${filename}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: research idea #${id} -- ${title}" --files ${project_root}/docs/ideas/${SLUG}-research.md ${project_root}/ideas/${filename}
 ```
 </step>
 
@@ -490,8 +490,8 @@ Research: ${recommendation}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
-- ${project_root}/docs/ideas/pending/${SLUG}-research.md
+- ${project_root}/ideas/${filename}
+- ${project_root}/docs/ideas/${SLUG}-research.md
 ```
 
 **If only discussion ran** (research skipped by decision routing, user choice, or partial exit):
@@ -503,7 +503,7 @@ Decision: ${decision}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
+- ${project_root}/ideas/${filename}
 ```
 
 **If only research ran** (user chose "Just research" in assess_history):
@@ -516,8 +516,8 @@ Research: ${recommendation}
 Next step: ${contextAwareNextStep}
 
 Files:
-- ${project_root}/ideas/${state}/${filename}
-- ${project_root}/docs/ideas/pending/${SLUG}-research.md
+- ${project_root}/ideas/${filename}
+- ${project_root}/docs/ideas/${SLUG}-research.md
 ```
 
 **Context-aware next step logic:**

package/deliver-great-systems/workflows/diagnose-issues.md

@@ -33,6 +33,20 @@ TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" contex
 ```
 
 Store the file list for passing to debug sub-agents in `<files_to_read>` blocks.
+
+**Worktree-aware code directory resolution (resolveCodeContext):**
+
+For each registered code repo, resolve the correct working directory. When a milestone or quick worktree is active, debug investigation must target the worktree directory, not the main checkout, so the debugger examines the correct code and can reproduce issues in the right context.
+
+```javascript
+// In the agent's execution context, use resolveCodeContext to determine the code directory:
+const { resolveCodeContext } = require('./bin/lib/context.cjs');
+const ctx = resolveCodeContext(planningRoot, repoName);
+// ctx.type: 'main' | 'milestone' | 'quick'
+// ctx.directory: absolute path to the correct working directory
+```
+
+Pass `ctx.directory` to debug sub-agents so they investigate code in the correct location.
 </step>
 
 <step name="parse_gaps">

package/deliver-great-systems/workflows/discuss-idea.md

@@ -86,7 +86,7 @@ IDEA_DOCS_DIR="${IDEA_DIR}/docs"
 If a flat structure is used (ideas stored as files, not directories), derive from the filename:
 ```bash
 IDEA_SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
-IDEA_DOCS_DIR="$(dirname "$(dirname "${path}")")/docs/ideas/pending/${IDEA_SLUG}"
+IDEA_DOCS_DIR="$(dirname "$(dirname "${path}")")/docs/ideas/${IDEA_SLUG}"
 ```
 
 Check both paths. Use whichever exists.

package/deliver-great-systems/workflows/execute-phase.md

@@ -9,7 +9,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 </core_principle>
 
 <hard_boundary>
-**CRITICAL SCOPE CONSTRAINT:** You execute ONLY the single phase specified in $ARGUMENTS. After that phase completes (plans executed, verification done, roadmap updated), you MUST STOP. Do NOT read the roadmap to discover subsequent phases. Do NOT execute transition.md unless `--auto` flag is present. Do NOT advance to phase N+1. Violating this boundary causes duplicate work and corrupts job state.
+**CRITICAL SCOPE CONSTRAINT:** You execute ONLY the single phase specified in $ARGUMENTS. After that phase finishes (plans executed, verification done, roadmap updated), you MUST STOP. Do NOT read the roadmap to discover subsequent phases. Do NOT execute transition.md unless `--auto` flag is present. Do NOT advance to phase N+1. Violating this boundary causes duplicate work and corrupts job state.
 </hard_boundary>
 
 <required_reading>
@@ -27,7 +27,7 @@ INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init execute
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`.
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`, `milestone_slug`, `milestone_version`, `milestone_name`.
 
 **Load execution tier context:**
 
@@ -119,34 +119,122 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull
   - If No: skip pull, continue
 </step>
 
-<step name="handle_branching">
-Check `branching_strategy` from init:
+<step name="handle_worktree">
+Check if this phase is part of a milestone with code repos registered in REPOS.md.
 
-**"none":** Skip, continue on current branch.
+**If no REPOS.md or no code repos:** Skip worktree creation entirely. Log: `No code repos registered — skipping worktree setup.` Continue to validate_phase.
+
+**If REPOS.md has code repos and `milestone_slug` is present:**
+
+Use `milestone_slug` from init JSON (already sanitized).
+
+**1. Check for existing worktree:**
 
-**"phase" or "milestone":** Use pre-computed `branch_name` from init for the product folder:
 ```bash
-git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+WORKTREE_LIST=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees list 2>/dev/null)
 ```
 
-All subsequent commits go to this branch. User handles merging.
+Parse the JSON array. Look for an entry matching `milestone_slug`.
 
-**Code repo branching (base_branch):**
+**If worktree exists with `setup_complete: true` for all repos:**
+```
+Using existing milestone worktree for ${MILESTONE_SLUG}
+```
+Skip to step 3 (set active_context).
 
-The product folder's own branch is always created from the current HEAD (typically `main`). The `base_branch` from init JSON applies only to code repos registered in REPOS.md.
+**If worktree exists but `setup_complete: false` for any repo:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-When branching is enabled and REPOS.md lists code repos, `createRepoBranches` (via `dgs-tools.cjs`) uses `base_branch` to:
-1. Pre-check all code repos upfront — verify the base branch exists in every registered repo before creating any branches
-2. Fetch the base branch from remote in each repo (`git fetch origin "$BASE_BRANCH"`)
-3. Create feature branches from the base branch (`git checkout "$BASE_BRANCH" && git checkout -b "$BRANCH_NAME"`)
+Worktree setup incomplete for milestone '${MILESTONE_SLUG}'.
+Repo(s) with failed setup need manual intervention.
 
-If the base branch does not exist in any code repo, the operation fails with a clear error before any branches are created:
+**To fix:** dgs-tools worktrees setup ${MILESTONE_SLUG}
+Then re-run: /dgs:execute-phase ${PHASE}
 ```
-Error: Base branch '{base_branch}' does not exist in repo '{repo_name}'.
-Create the branch or update git.base_branch in config.
+**STOP.** Do not proceed with phase execution.
+
+**If no worktree exists:**
+
+**2. Create milestone worktree:**
+
+```bash
+CREATE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees create "${MILESTONE_SLUG}" --type milestone)
 ```
 
-The `base_branch` value is passed from init JSON to `createRepoBranches` automatically — the two-pass validation (verify all repos, then create all branches) is handled by the library function (see Plan 01, Task 3).
+Parse JSON output. Check each repo:
+- If all repos have `setup_complete: true` (or no setup command): continue.
+- If any repo has `setup_complete: false`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Setup failed for one or more repos during worktree creation.
+Phase cannot start until setup succeeds.
+
+**To fix:** dgs-tools worktrees setup ${MILESTONE_SLUG}
+Then re-run: /dgs:execute-phase ${PHASE}
+```
+**STOP.** Do not proceed.
+
+Note: The worktree directory and branch are kept (not removed) so the user can fix and re-run setup.
+
+**3. Set active_context and capture worktree repos:**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-local-set execution.active_context "${MILESTONE_SLUG}"
+```
+
+Read the worktree repos map from config.local.json so it can be passed to executor agents:
+
+```bash
+WORKTREE_REPOS=$(node -e "
+  const fs = require('fs');
+  const cfg = JSON.parse(fs.readFileSync('config.local.json', 'utf-8'));
+  const project = cfg.current_project;
+  const repos = (cfg.projects && cfg.projects[project] && cfg.projects[project].worktrees && cfg.projects[project].worktrees['${MILESTONE_SLUG}'] && cfg.projects[project].worktrees['${MILESTONE_SLUG}'].repos) || {};
+  process.stdout.write(JSON.stringify(repos));
+")
+```
+
+Store `$WORKTREE_REPOS` (JSON object mapping repoName -> worktreePath) for use in executor prompts.
+
+**4. Verify worktree health:**
+
+For each code repo registered in REPOS.md, verify the worktree is healthy:
+
+```bash
+HEALTH=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees health "${MILESTONE_SLUG}" 2>/dev/null || echo '{"healthy":true,"issues":[]}')
+```
+
+If the `worktrees health` subcommand is not available, perform inline checks:
+
+For each repo in the worktree:
+```bash
+# Check branch
+BRANCH=$(git -C "${WORKTREE_PATH}" rev-parse --abbrev-ref HEAD 2>/dev/null)
+# Check clean state
+STATUS=$(git -C "${WORKTREE_PATH}" status --porcelain 2>/dev/null)
+```
+
+If branch is wrong or uncommitted changes exist, **warn** but continue (quick sanity check, not a full health audit):
+```
+⚠ Worktree health warning for ${REPO_NAME}:
+  - Expected branch: milestone/${MILESTONE_SLUG}, actual: ${BRANCH}
+  - Has uncommitted changes
+Continuing anyway — review worktree state after execution.
+```
+
+**5. Do NOT clear active_context after phase completion.**
+
+The milestone worktree persists across all phases within the milestone until `complete-milestone` is run. active_context is NOT cleared in the post-execution steps of this workflow.
+
+**Note on backward compatibility:**
+The old `branching_strategy` check and `createRepoBranches` code path is removed. If `branching_strategy` is set to "phase" or "milestone" in an older config, the worktree path runs instead.
 </step>
 
 <step name="validate_phase">
@@ -217,6 +305,13 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
        Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
        </objective>
 
+       ${WORKTREE_REPOS && WORKTREE_REPOS !== '{}' ? `
+       <worktree_context>
+       This phase is executing in a git worktree. Work in these directories — do NOT use the main checkout paths:
+       ${Object.entries(JSON.parse(WORKTREE_REPOS)).map(([name, dir]) => '- ' + name + ': ' + dir).join('\n       ')}
+       </worktree_context>
+       ` : ''}
+
        <execution_context>
        @~/.claude/deliver-great-systems/workflows/execute-plan.md
        @~/.claude/deliver-great-systems/templates/summary.md
@@ -292,11 +387,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If `CODEREVIEW` is not `true`: skip silently, proceed to next step.
 
-   **If `NON_INTERACTIVE` is true:**
-   Log: `[AUTO-RESOLVE] Code review enabled but skipping in non-interactive mode (codereview requires interactive Task spawning)`
-   Skip codereview, proceed to next step.
-
-   **If `NON_INTERACTIVE` is false (interactive mode) AND `CODEREVIEW` is `true`:**
+   The codereview workflow is non-interactive by design — it auto-fixes low-risk issues and logs CRITICAL/HIGH findings as deviations to SUMMARY.md rather than prompting. It runs in both interactive and job modes.
 
    For each plan that completed successfully in this wave:
 
@@ -570,10 +661,10 @@ Gap closure cycle: `/dgs:plan-phase {X} --gaps` reads VERIFICATION.md → create
 </step>
 
 <step name="update_roadmap">
-**Mark phase complete and update all tracking files:**
+**Mark phase done, commit tracking files, and push — all atomically:**
 
 ```bash
-COMPLETION=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase complete "${PHASE_NUMBER}")
+FINALIZE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase finalize "${PHASE_NUMBER}" --push)
 ```
 
 The CLI handles:
@@ -582,14 +673,12 @@ The CLI handles:
 - Updating plan count to final
 - Advancing STATE.md to next phase
 - Updating REQUIREMENTS.md traceability
+- **Committing** ROADMAP.md, STATE.md, REQUIREMENTS.md, and `${phase_dir}/*-VERIFICATION.md` in a single atomic commit
+- Pushing (if sync_push=auto) in the same call
 
-Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
-
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-{X}): complete phase execution" --push --files ${roadmap_path} ${state_path} ${requirements_path} ${phase_dir}/*-VERIFICATION.md
-```
+Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `committed`, `hash`, `pushed`.
 
-Parse the commit result JSON. If `needs_push` is true (sync_push is "prompt" mode), handle push prompting via the existing sync_after step. If `pushed` is true, the push already happened atomically with the commit -- skip the sync_after push for this commit (avoid double-push). If `pushed` is false and `push_result` exists, log the push warning but do not halt.
+Parse the result JSON. If `needs_push` is true (sync_push is "prompt" mode), handle push prompting via the existing sync_after step. If `pushed` is true, the push already happened atomically with the commit — skip the sync_after push for this commit (avoid double-push). If `pushed` is false and `push_result` exists, log the push warning but do not halt.
 </step>
 
 <step name="sync_after">
@@ -683,7 +772,7 @@ Read and follow `~/.claude/deliver-great-systems/workflows/transition.md`, passi
 
 **HARD STOP.** The workflow ends here. Do NOT read transition.md. Do NOT read ROADMAP.md. Do NOT execute any additional phases.
 
-**Use ONLY the `is_last_phase`, `next_phase`, and `next_phase_name` values from the `phase complete` result in the update_roadmap step.** Do NOT read the roadmap or any other file to determine remaining phases — the CLI already computed this.
+**Use ONLY the `is_last_phase`, `next_phase`, and `next_phase_name` values from the `phase finalize` result in the update_roadmap step.** Do NOT read the roadmap or any other file to determine remaining phases — the CLI already computed this.
 
 If `is_last_phase` is `false`:
 ```

package/deliver-great-systems/workflows/execute-plan.md

@@ -452,25 +452,10 @@ Keep STATE.md under 150 lines.
 If SUMMARY "Issues Encountered" ≠ "None": yolo → log and continue. Interactive → present issues, wait for acknowledgment.
 </step>
 
-<step name="update_roadmap">
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" roadmap update-plan-progress "${PHASE}"
-```
-Counts PLAN vs SUMMARY files on disk. Updates progress table row with correct count and status (`In Progress` or `Complete` with date).
-</step>
-
-<step name="update_requirements">
-Mark completed requirements from the PLAN.md frontmatter `requirements:` field:
-
-```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" requirements mark-complete ${REQ_IDS}
-```
-
-Extract requirement IDs from the plan's frontmatter (e.g., `requirements: [AUTH-01, AUTH-02]`). If no requirements field, skip.
-</step>
+<step name="finalize_plan">
+**Update state/roadmap/requirements and commit plan metadata atomically.**
 
-<step name="git_commit_metadata">
-**Multi-repo guard:** If any task used `commit --multi-repo` and returned `success: false`, display a warning before committing planning metadata:
+**Multi-repo guard:** If any task used `commit --multi-repo` and returned `success: false`, display a warning before finalizing:
 
 ```
 Warning: Some repo commits failed. Planning metadata will still be committed to track partial progress.
@@ -479,11 +464,17 @@ Check SUMMARY.md status field for per-repo details.
 
 The planning metadata commit proceeds regardless (to track partial progress), but the warning ensures visibility. The SUMMARY.md `status: partial` field records which repos failed.
 
-Task code already committed per-task. Commit plan metadata:
-
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files ${phase_dir}/{phase}-{plan}-SUMMARY.md ${state_path} ${roadmap_path} ${requirements_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" plan finalize "${PHASE}" "${PLAN}"
 ```
+
+The CLI handles (in one atomic call):
+- `roadmap update-plan-progress` (progress table, status, date, checkbox)
+- `requirements mark-complete` (from PLAN.md `requirements:` frontmatter — auto-extracted)
+- `state update-progress` (global progress bar, idempotent with `record_metrics`)
+- Commits `{phase}-{plan}-PLAN.md`, `{phase}-{plan}-SUMMARY.md`, `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md` with message `docs({phase}-{plan}): complete {plan-name} plan`
+
+The plan name is auto-extracted from the PLAN.md `plan_name` frontmatter field (fallback: "execution"). To override, add `--plan-name "<name>"` to the call.
 </step>
 
 <step name="update_codebase_map">

package/deliver-great-systems/workflows/help.md

@@ -384,7 +384,7 @@ Usage: `/dgs:debug` (resume active session)
 Capture idea or task as todo from current conversation. *(Tier 1: lite)*
 
 - Extracts context from conversation (or uses provided description)
-- Creates structured todo file in the project's todos/pending/ directory
+- Creates structured todo file in the project's todos/ directory
 - Infers area from file paths for grouping
 - Checks for duplicates before creating
 - Updates STATE.md todo count
@@ -468,7 +468,7 @@ Usage: `/dgs:discuss-idea` (shows picker)
 Research an idea's feasibility and technical landscape. *(Tier 2: planning)*
 
 - Five dimensions: web search, codebase analysis, landscape survey, approaches, feasibility
-- Creates research document at `docs/ideas/pending/{slug}-research.md` (relative to planning root)
+- Creates research document at `docs/ideas/{slug}-research.md` (relative to planning root)
 - Appends Research Log to idea file (Summary, Document link, Key Finding, Recommendation)
 - Can run multiple times; each run appends a new entry
 

package/deliver-great-systems/workflows/init-product.md

@@ -206,16 +206,6 @@ AskUserQuestion([
       { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
       { label: "No", description: "Keep planning docs local-only (add to .gitignore)" }
     ]
-  },
-  {
-    header: "Branching",
-    question: "Git branching strategy?",
-    multiSelect: false,
-    options: [
-      { label: "None (Recommended)", description: "Commit to current branch (fine for single projects)" },
-      { label: "Per Phase", description: "Branch per phase, review before merging" },
-      { label: "Per Milestone", description: "Branch per project, merge all at end (for parallel projects)" }
-    ]
   }
 ])
 ```
@@ -282,10 +272,9 @@ AskUserQuestion([
     "discipline": true|false
   },
   "git": {
-    "branching_strategy": "none|phase|milestone",
     "base_branch": "[from earlier question]",
-    "sync_push": "prompt",
-    "sync_pull": "prompt"
+    "sync_push": "auto",
+    "sync_pull": "auto"
   }
 }
 ```
@@ -300,11 +289,6 @@ Smart defaults (not asked): `parallelization: true`, `auto_advance: false`, `nyq
 node /Users/adrian/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "chore: add product config" --files ${config_path}
 ```
 
-**Branch name preview:** If `branching_strategy` is not `"none"`, show:
-```
-Branch names will look like: dgs/{project-slug}/phase-03-auth
-```
-
 **b7. Commit initialized files:**
 
 Use the `files_created` array from the init response to build the commit file list:

package/deliver-great-systems/workflows/new-milestone.md

@@ -44,12 +44,28 @@ The spec must have status: final.
 
 <process>
 
+## 0. Resolve Paths and Models
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
+```
+
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `current_milestone_name`, `project_exists`, `roadmap_exists`, `state_exists`, `project_path`, `roadmap_path`, `state_path`, `current_project`, `project_root`.
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+All subsequent steps use these resolved paths. Never reference PROJECT.md, STATE.md, etc. by bare name — always use `${project_path}`, `${state_path}`, `${project_root}`, etc.
+
 ## 1. Load Context
 
-- Read PROJECT.md (existing project, validated requirements, decisions)
-- Read MILESTONES.md (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
-- Read STATE.md (pending todos, blockers) — if file does not exist, will be created in Step 5
-- Check for MILESTONE-CONTEXT.md (from /dgs:discuss-milestone)
+- Read `${project_path}` (existing project, validated requirements, decisions)
+- Read `${project_root}/MILESTONES.md` (what shipped previously) — if file does not exist, this is the first milestone; skip and use defaults
+- Read `${state_path}` (pending todos, blockers) — if file does not exist, will be created in Step 5
+- Check for `${project_root}/MILESTONE-CONTEXT.md` (from /dgs:discuss-milestone)
 
 ## 1b. Spec-Driven Milestone (auto mode only)
 
@@ -67,7 +83,7 @@ Read the spec file and extract:
 
 ### Determine Milestone Version
 
-Parse MILESTONES.md for last version. If no MILESTONES.md exists (first milestone): default to v1.0 (auto mode: use v1.0 without asking). Suggest next version automatically (e.g., v1.0 → v1.1, or v2.0 for major). In auto mode, use the minor bump without asking.
+Parse `${project_root}/MILESTONES.md` for last version. If no MILESTONES.md exists (first milestone): default to v1.0 (auto mode: use v1.0 without asking). Suggest next version automatically (e.g., v1.0 → v1.1, or v2.0 for major). In auto mode, use the minor bump without asking.
 
 ### Repo Cross-Check (v2 only)
 
@@ -148,7 +164,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC
 
 ### Continue to Step 7
 
-Skip Steps 2-6 (questioning, version determination, update, cleanup, context loading) — they're replaced by spec-driven derivation. Proceed to Step 7 (Load Context and Resolve Models), then:
+Skip Steps 2-6 (questioning, version determination, update, cleanup) — they're replaced by spec-driven derivation. Proceed to Step 8 (Research Decision), then:
 
 - Step 8 (Research Decision): Default to "Research first" in auto mode
 - Step 9 (Define Requirements): Generate from spec instead of interactive scoping:
@@ -166,7 +182,7 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 
 ## 2. Gather Milestone Goals
 
-**If MILESTONE-CONTEXT.md exists:**
+**If `${project_root}/MILESTONE-CONTEXT.md` exists:**
 - Use features and scope from discuss-milestone
 - Present summary for confirmation
 
@@ -177,7 +193,7 @@ Skip Steps 2-6 (questioning, version determination, update, cleanup, context loa
 
 ## 3. Determine Milestone Version
 
-- Parse last version from MILESTONES.md
+- Parse last version from `${project_root}/MILESTONES.md`
 - If no MILESTONES.md exists (first milestone): default to v1.0 and suggest it to user
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
@@ -201,8 +217,8 @@ Update Active requirements section and "Last updated" footer.
 
 ## 5. Update STATE.md
 
-**If STATE.md does not exist (first milestone):** Create it with the structure below.
-**If STATE.md exists:** Update the Current Position section.
+**If `${state_path}` does not exist (first milestone):** Create it with the structure below.
+**If it exists:** Update the Current Position section.
 
 ```markdown
 ## Current Position
@@ -217,25 +233,15 @@ Keep Accumulated Context section from previous milestone.
 
 ## 6. Cleanup and Commit
 
-Delete MILESTONE-CONTEXT.md if exists (consumed).
+Delete `${project_root}/MILESTONE-CONTEXT.md` if exists (consumed).
 
 ```bash
 node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --push --files ${project_path} ${state_path}
 ```
 
-## 7. Load Context and Resolve Models
-
-```bash
-INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-milestone)
-```
-
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
+## 7. Research Decision Gate
 
-Load planning-tier context files:
-
-```bash
-TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
-```
+Paths and models already resolved in Step 0.
 
 ## 8. Research Decision
 
@@ -429,7 +435,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define mile
 ◆ Spawning roadmapper...
 ```
 
-**Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6). If no MILESTONES.md exists (first milestone): start phase numbering at 1.
+**Starting phase number:** Read `${project_root}/MILESTONES.md` for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6). If no MILESTONES.md exists (first milestone): start phase numbering at 1.
 
 ```
 Task(prompt="