@ktpartners/dgs-platform 2.9.0 → 3.3.0

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/discuss-phase.md

@@ -183,7 +183,8 @@ Read prior phase context to avoid re-asking decided questions and maintain consi
 **Step 1: Project-level files**
 
 Project-level files (PROJECT.md, REQUIREMENTS.md, STATE.md, ROADMAP.md, REPOS.md, and codebase docs) are already loaded via the planning-tier `load-tier` call in the initialize step. Extract from those:
-- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
+- **docs/product/PRODUCT-SUMMARY.md** — Vision, principles, non-negotiables (product-level)
+- **PROJECT.md** — Project identity (thin skeleton: name + one-liner)
 - **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
 - **STATE.md** — Current progress, any flags or session notes
 
@@ -204,7 +205,7 @@ Structure the extracted information:
 ```
 <prior_decisions>
 ## Project-Level
-- [Key principle or constraint from PROJECT.md]
+- [Key principle or constraint from docs/product/PRODUCT-SUMMARY.md]
 - [Requirement that affects this phase from REQUIREMENTS.md]
 
 ## From Prior Phases

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:**
+
+```bash
+WORKTREE_LIST=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" worktrees list 2>/dev/null)
+```
+
+Parse the JSON array. Look for an entry matching `milestone_slug`.
+
+**If worktree exists with `setup_complete: true` for all repos:**
+```
+Using existing milestone worktree for ${MILESTONE_SLUG}
+```
+Skip to step 3 (set active_context).
+
+**If worktree exists but `setup_complete: false` for any repo:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Worktree setup incomplete for milestone '${MILESTONE_SLUG}'.
+Repo(s) with failed setup need manual intervention.
+
+**To fix:** dgs-tools worktrees setup ${MILESTONE_SLUG}
+Then re-run: /dgs:execute-phase ${PHASE}
+```
+**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)
+```
+
+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:**
 
-**"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"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-local-set execution.active_context "${MILESTONE_SLUG}"
 ```
 
-All subsequent commits go to this branch. User handles merging.
+Read the worktree repos map from config.local.json so it can be passed to executor agents:
 
-**Code repo branching (base_branch):**
+```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:**
 
-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.
+For each code repo registered in REPOS.md, verify the worktree is healthy:
 
-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"`)
+```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 the base branch does not exist in any code repo, the operation fails with a clear error before any branches are created:
+If branch is wrong or uncommitted changes exist, **warn** but continue (quick sanity check, not a full health audit):
 ```
-Error: Base branch '{base_branch}' does not exist in repo '{repo_name}'.
-Create the branch or update git.base_branch in config.
+⚠ Worktree health warning for ${REPO_NAME}:
+  - Expected branch: milestone/${MILESTONE_SLUG}, actual: ${BRANCH}
+  - Has uncommitted changes
+Continuing anyway — review worktree state after execution.
 ```
 
-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).
+**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">
@@ -202,7 +290,34 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **Spawn executor agents:**
+2. **Execute plans for this wave:**
+
+   **If `NON_INTERACTIVE` is true (job mode — inline execution):**
+
+   The Task tool is not available in nested Task contexts (run-job spawns execute-phase, which would otherwise spawn dgs-executor — Claude Code structural limitation). Run plans inline within the current orchestrator context instead.
+
+   For each plan in the wave, **in document order** (plans within a wave still execute in the order they appear in the wave's plan list — even if `parallelization` is true, inline mode runs them sequentially because there is no parallel-Task harness):
+
+   a. Read `~/.claude/deliver-great-systems/workflows/execute-plan.md` and follow its steps inline for this plan, supplying:
+      - The plan path: `{phase_dir}/{plan_id}-PLAN.md`
+      - The state path: ${state_path} (resolved by init)
+      - The phase context file (if present): `{phase_dir}/{padded_phase}-CONTEXT.md`
+      - Project conventions: `./CLAUDE.md` (if exists) and `.claude/skills/` or `.agents/skills/` (if either exists)
+      - Tier files from $TIER_FILES (computed in initialize step)
+      - Author: ${author}
+      - Worktree context: when $WORKTREE_REPOS is non-empty, treat the worktree directories as the repo cwds for all task commits and file operations (do NOT use the main checkout paths).
+
+   b. Treat segmented plans (Pattern B in execute-plan.md `parse_segments`) as Pattern C / main-context for inline mode — i.e. execute every task in the orchestrator's current context. Do NOT spawn nested Tasks. Checkpoint tasks (`type="checkpoint:*"`) are auto-resolved per the `checkpoint_handling` step's `NON_INTERACTIVE`-true rules (human-verify → auto-approve, decision → first option, human-action → FAIL the step).
+
+   c. Preserve all execute-plan semantics: atomic per-task commits via `dgs-tools.cjs commit`, deviation handling per `<deviation_rules>` (Rules 1–3 auto, Rule 4 logged as deviation since no user is available — record under "Deferred Issues" in SUMMARY.md), authentication gates (in job mode, treat any auth gate as a hard failure — log and halt the wave), and run all of: `record_start_time`, `parse_segments`, `load_prompt`, `preflight_check`, `execute`, `record_completion_time`, `generate_user_setup`, `create_summary`, `update_current_position`, `extract_decisions_and_issues`, `update_session_continuity`, `issues_review_gate`, `finalize_plan`, `update_codebase_map`.
+
+   d. **Skip the `offer_next` step from execute-plan.md.** Wave/phase advancement is the responsibility of this `execute_waves` step in execute-phase.md, not the inline plan loop.
+
+   e. After each plan completes, run the same spot-checks defined in step 4 below (SUMMARY.md exists, git commits present, no `## Self-Check: FAILED` marker). If a plan fails the spot-check, log `[INLINE-EXEC] Plan {plan_id} failed spot-check -- halting wave` and halt the wave (do NOT continue to subsequent plans in the same wave).
+
+   f. After all plans in the wave complete successfully, fall through to step 4 (Report completion).
+
+   **If `NON_INTERACTIVE` is false (interactive mode — Task spawning):**
 
    Pass paths only — executors read files themselves with their fresh 200k context.
    This keeps orchestrator context lean (~10-15%).
@@ -217,6 +332,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 +414,28 @@ 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.
+   **Derive code repo path:**
+
+   The gate's git log and the spawned codereview subagent must run against the **code repo** (where task commits live), not the planning repo. Derive `CODE_REPO_PATH` from `$WORKTREE_REPOS` (populated in `handle_worktree`, step 3):
+
+   ```bash
+   CODE_REPO_PATH=$(WORKTREE_REPOS="$WORKTREE_REPOS" node -e "
+     const repos = JSON.parse(process.env.WORKTREE_REPOS || '{}');
+     const names = Object.keys(repos);
+     if (names.length === 0) { process.stdout.write(''); }
+     else { process.stdout.write(repos[names[0]]); }
+   ")
+   ```
+
+   If `CODE_REPO_PATH` is empty (no milestone worktree registered — e.g. phase executed without a worktree), skip the codereview gate entirely for this wave with the message:
+   ```
+   No code repo registered for this phase — skipping code review for wave.
+   ```
+   and proceed to the next step.
+
+   **Multi-repo note:** when `WORKTREE_REPOS` has more than one entry, this uses the first entry. Multi-repo codereview is a known limitation (TODO: loop over entries once a real multi-repo project exists).
 
-   **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:
 
@@ -311,7 +450,7 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    Compute diff reference for the plan's task commits:
    ```bash
-   FIRST_TASK_COMMIT=$(git log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+   FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
    ```
 
    If FIRST_TASK_COMMIT is empty (no task commits found), skip codereview for this plan with message: "No task commits found for {phase}-{plan}, skipping code review."
@@ -328,7 +467,10 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
      - PLAN: ${PLAN}
      - PLAN_PATH: ${phase_dir}/{phase}-{plan}-PLAN.md
      - PHASE_DIR: ${phase_dir}
+     - CODE_REPO_PATH: ${CODE_REPO_PATH}
      - DIFF_REF: ${FIRST_TASK_COMMIT}^..HEAD
+     - PROJECT_ROOT: ${project_root}
+     - PLANNING_ROOT: $(pwd)
      ",
      model="{executor_model}"
    )
@@ -488,6 +630,42 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-
 <step name="verify_phase_goal">
 Verify phase achieved its GOAL, not just completed tasks.
 
+**If `NON_INTERACTIVE` is true (job mode — inline verification):**
+
+The Task tool is not available in nested Task contexts (run-job → execute-phase → would otherwise spawn dgs-verifier). Perform verification inline within the current orchestrator context.
+
+Inline verification procedure:
+
+a. **Load phase context:**
+   - Phase goal: read from `${roadmap_path}` for phase `${PHASE_NUMBER}`.
+   - Phase requirement IDs: `${phase_req_ids}` (from init JSON).
+   - Phase directory: `${phase_dir}`.
+
+b. **Read all plan SUMMARY.md files** in `${phase_dir}` matching `*-SUMMARY.md`. Cross-reference each SUMMARY's `requirements_completed` frontmatter against `${phase_req_ids}`. Every requirement ID listed in the phase MUST be accounted for in at least one SUMMARY.
+
+c. **Read each PLAN.md** in `${phase_dir}` matching `*-PLAN.md` and extract the `must_haves` frontmatter (truths, artifacts, key_links).
+
+d. **Check must_haves against the actual codebase:**
+   - For each artifact: confirm the file exists on disk (use $WORKTREE_REPOS to resolve repo paths when present; otherwise resolve via REPOS.md). If `min_lines` is specified, verify line count.
+   - For each key_link: grep the `from` file for the `pattern`. If pattern is missing, the link is unverified.
+   - For each truth: best-effort verification via grep / file existence; truths that require human UAT are marked `human_needed`.
+
+e. **Cross-reference REQUIREMENTS.md:** every ID in `${phase_req_ids}` MUST appear in REQUIREMENTS.md with a status reflecting completion. Flag any ID missing from REQUIREMENTS.md as a gap.
+
+f. **Determine status:**
+   - `passed` — all artifacts present, all key_links found, all truths automatically verified, all requirement IDs accounted for.
+   - `human_needed` — automated checks pass but ≥1 truth requires human UAT.
+   - `gaps_found` — ≥1 artifact missing, key_link unverified, requirement ID unaccounted for, or truth fails automated verification.
+
+g. **Write `${phase_dir}/${PHASE_NUMBER}-VERIFICATION.md`** with frontmatter including `status:` (one of `passed` / `human_needed` / `gaps_found`), `phase:`, `verified_by: ${author}`, `verified_at: <ISO-8601 timestamp>`, and a `mode: inline` marker (so audits can distinguish inline from Task-based verification). Body sections: must-haves checklist (per plan), requirement-ID cross-check table, gaps list (if any), human_verification list (if status is `human_needed`).
+
+h. Commit the VERIFICATION.md file:
+   ```bash
+   node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-${PHASE_NUMBER}): inline verification" --files ${phase_dir}/${PHASE_NUMBER}-VERIFICATION.md
+   ```
+
+**If `NON_INTERACTIVE` is false (interactive mode — Task spawning):**
+
 ```
 Task(
   prompt="Verify phase {phase_number} goal achievement.
@@ -570,10 +748,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 +760,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 +859,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

@@ -318,6 +318,15 @@ TASK_COMMIT=$(git rev-parse --short HEAD)
 TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 ```
 
+**6. Post-commit dirty sweep:** After recording the task commit hash, run `git status --porcelain` in every gitCwd the task touched. Resolve gitCwds via the task's `<repos>` tag + REPOS.md (one `resolveRepoRelativePath(cwd, repoName, '.', repos).repoAbsPath` per distinct repo); if the task has no `<repos>` tag, the single gitCwd is the planning root (or the `repo-cwd` override when set). The `dirty_after` field in the commit JSON result from `dgs-tools.cjs commit` already surfaces the list for the repo the commit ran in.
+
+Classify each dirty path:
+
+- **SWEEP** (`*.tfvars`/`*.tf` fmt reflows, pure whitespace verified by `git diff -w -- <path>` being empty, type-only narrowings in `*.ts`/`*.tsx` confined to type-position tokens on existing declaration lines — type annotations, `as`-casts, generic params; NOT statement-structure keywords like `const`/`await`/`import`): stage and commit as `chore({phase}-{plan}-reflow): verify-step side effects` with one bullet per file. Log under "Post-verify reflows" in SUMMARY.md.
+- **FAIL** (added/removed statements, new imports, new function bodies, or any logic change in files NOT listed in the plan's `files_modified` frontmatter): halt. Record under "Deferred Issues" with a `git diff` excerpt. Treat as a blocking issue and auto-fix per the existing fix-attempt-limit policy (3 attempts then document and continue).
+
+Default to SWEEP — false negatives lose work.
+
 </task_commit>
 
 <step name="checkpoint_protocol">
@@ -392,7 +401,7 @@ If user_setup exists: create `{phase}-USER-SETUP.md` using template `~/.claude/d
 <step name="create_summary">
 Create `{phase}-{plan}-SUMMARY.md` at `${phase_dir}/`. Use `~/.claude/deliver-great-systems/templates/summary.md`.
 
-**Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim) | duration ($DURATION), completed ($PLAN_END_TIME date).
+**Frontmatter:** phase, plan, subsystem, tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements_completed (**MUST** copy `requirements` array from PLAN.md frontmatter verbatim — pre-commit precondition `dgs-tools final-commit-precondition` aborts the executor on mismatch per REL-08) | duration ($DURATION), completed ($PLAN_END_TIME date).
 
 Include `executed_by: ${author}` (from init JSON) in frontmatter — records who triggered this execution.
 
@@ -452,25 +461,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:
+<step name="finalize_plan">
+**Update state/roadmap/requirements and commit plan metadata atomically.**
 
-```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="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 +473,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">