@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -26,6 +26,8 @@ Parse `$ARGUMENTS` for:
 - `--dry-run` flag → store as `$DRY_RUN` (true/false)
 - `--full` flag → store as `$FULL_MODE` (true/false)
 - `--discuss` flag → store as `$DISCUSS_MODE` (true/false)
+- `--main` flag → store as `$FORCE_MAIN` (true/false)
+- `--debug` flag → store as `$DEBUG_MODE` (true/false)
 - Remaining text (after stripping all flags) → use as `$DESCRIPTION` if non-empty
 
 If `$DESCRIPTION` is empty after parsing, prompt user interactively:
@@ -82,6 +84,108 @@ If `$FULL_MODE` only:
 
 ---
 
+**Step 1.5: Detect quick mode and handle worktree lifecycle**
+
+This step runs for BOTH fast and non-fast paths. For `$FAST_MODE`, it performs mode detection ONLY (no worktree creation) so the fast path can route commits correctly based on the active context.
+
+Determine the effective mode flag:
+- If `$DEBUG_MODE`: set `$QUICK_MODE_FLAG = 'debug'`
+- If `$FULL_MODE`: set `$QUICK_MODE_FLAG = 'full'`
+- Otherwise: set `$QUICK_MODE_FLAG = null`
+
+Detect whether this is a product-level or milestone-context quick:
+
+```bash
+QUICK_DETECT=$(node -e "
+  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const r = q.detectQuickMode(process.cwd(), ${FORCE_MAIN:-false});
+  process.stdout.write(JSON.stringify(r));
+")
+```
+
+Parse `QUICK_DETECT` for `mode` field.
+
+**If mode is 'product':**
+
+**If NOT `$FAST_MODE`:**
+
+Check the one-active-quick guard and create worktree:
+
+```bash
+QUICK_START=$(node -e "
+  const q = require('$HOME/.claude/deliver-great-systems/bin/lib/quick.cjs');
+  const r = q.startProductQuick(process.cwd(), '${DESCRIPTION}', ${QUICK_MODE_FLAG ? \"'\" + QUICK_MODE_FLAG + \"'\" : 'null'});
+  process.stdout.write(JSON.stringify(r));
+")
+```
+
+Parse `QUICK_START` result.
+
+If `success` is false (guard triggered or creation failed):
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+${error message from QUICK_START}
+```
+End workflow.
+
+If `success` is true:
+Set `$QUICK_CONTEXT = 'product'`
+Set `$QUICK_SLUG` from result `slug`
+Set `$QUICK_REPOS` from result `repos` (object mapping repoName -> worktreePath, may be empty `{}`)
+Display: `Product-level quick created: ${QUICK_SLUG}`
+
+**If `$FAST_MODE`:**
+
+Skip worktree creation entirely. Fast in product mode commits directly to `base_branch` in the main checkout.
+
+Set `$QUICK_CONTEXT = 'product'`
+Set `$QUICK_REPO_CWD = null` (unset — git ops run in planning-root cwd)
+Display: `Fast: product-level (no milestone) — committing to base_branch in main checkout.`
+
+**If mode is 'milestone-context':**
+
+Set `$QUICK_CONTEXT = 'milestone-context'`
+Set `$MILESTONE_SLUG` from `activeMilestone` in detect result
+
+**If `$FAST_MODE`:** Resolve the milestone worktree directory for the active repo so fast commits land on the milestone branch:
+
+```bash
+QUICK_REPO_CWD=$(node -e "
+  const fs = require('fs');
+  const path = require('path');
+  const localPath = path.join(process.cwd(), 'config.local.json');
+  const local = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+  const { loadConfig } = require('$HOME/.claude/deliver-great-systems/bin/lib/core.cjs');
+  const cfg = loadConfig(process.cwd());
+  const proj = cfg.current_project;
+  const wt = (local.projects && local.projects[proj] && local.projects[proj].worktrees && local.projects[proj].worktrees['${MILESTONE_SLUG}']) || {};
+  const repos = Object.entries(wt.repos || {});
+  if (repos.length === 0) process.exit(1);
+  // Multi-repo: prefer the worktree with pending edits. Single-repo: the
+  // only entry. Fall back to the first entry if no diffs are detected.
+  const { execSync } = require('child_process');
+  let pick = repos[0][1];
+  for (const [name, dir] of repos) {
+    try {
+      const diff = execSync('git -C \"' + dir + '\" diff --stat', { encoding: 'utf-8' }).trim();
+      if (diff.length > 0) { pick = dir; break; }
+    } catch {}
+  }
+  process.stdout.write(pick);
+")
+```
+
+Display: `Fast: milestone-context (${MILESTONE_SLUG}) — committing to milestone branch in worktree ${QUICK_REPO_CWD}.`
+
+**If NOT `$FAST_MODE`:** Leave `$QUICK_REPO_CWD` unset. Display: `Working in milestone context (${MILESTONE_SLUG}). Changes will be part of the milestone.`
+
+No worktree creation. No guard check. Continue to Step 2.
+
+---
+
 **Step 2: Initialize**
 
 ```bash
@@ -136,14 +240,138 @@ Switching to /dgs:quick...
 ```
 Then continue from Step 3 as normal quick mode (skip the rest of the fast path).
 
+**F1.5-pre. Pre-edit dirt check (REL-06; runs only when `$FAST_MODE` is true)**
+
+Before any F2 edits, run a dirty-tree check across the planning root and all registered sub-repos. Pre-existing dirt that the user didn't initiate inside this fast-task would otherwise be swept into the F5 commit under a misleading message (the original idea-#27 footgun). Fail loudly with `pre-existing-dirt` exit-code label in non-interactive mode; ask to confirm in interactive mode.
+
+```bash
+DIRT_JSON=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" fast-route 2>/dev/null)
+PRE_DIRTY=$(echo "$DIRT_JSON" | jq -r '
+  ((.survey.planningRoot.dirty // false) as $pr |
+   ([.survey.subRepos[]? | select(.dirty == true) | .path] | length) as $sr |
+   if ($pr or ($sr > 0)) then "true" else "false" end)
+')
+```
+
+If `$PRE_DIRTY == "true"`:
+
+- **Non-interactive mode (no TTY):** Print the dirty paths from `$DIRT_JSON` and exit non-zero with label `pre-existing-dirt`:
+  ```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║  PRE-EXISTING DIRT DETECTED                                  ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+  /dgs:fast cannot proceed — the following repos have uncommitted changes
+  that pre-date this invocation:
+    - <planning root>: <paths>
+    - <sub-repo>: <paths>
+
+  Commit, stash, or `git restore` the listed paths and re-run, or use
+  /dgs:quick if these changes are part of the same intent.
+
+  exit-code label: pre-existing-dirt
+  ```
+  End workflow. Do NOT proceed to F1.5.
+
+- **Interactive mode:** Surface the dirty paths and prompt:
+  ```
+  AskUserQuestion(
+    header: "Pre-existing dirt",
+    question: "The following repos are dirty before this fast invocation: <paths>. Proceed anyway, or stop?",
+    options: [
+      { label: "Proceed", description: "Continue with /dgs:fast — dirty paths will NOT be included in this commit (only $FAST_EDITED_FILES will be staged)" },
+      { label: "Stop", description: "Exit /dgs:fast — manually clean the working tree first" }
+    ]
+  )
+  ```
+  If "Stop": exit non-zero with label `pre-existing-dirt`. If "Proceed": continue to F1.5. Submodule warnings (per `decision.warnings`) are surfaced but do NOT block in either mode.
+
+After F1.5-pre passes (clean state, OR user confirmed "Proceed"), continue to F1.5 cross-repo rejection guard.
+
+**F1.5. Cross-repo rejection guard (product fast only)**
+
+This guard is a pre-edit fail-fast check that prevents ambiguous multi-repo
+fast invocations from reaching F2/F5. Since v23.2 / REL-05, F5 invokes
+`dgs-tools fast-route` to pick the correct `--repo-cwd` post-edit, and F2
+passes the tracked file list via the explicit `--files` argument so the
+commit is scoped to the paths actually edited rather than a tree sweep.
+That means a /dgs:fast edit confined to a single sibling repo (with
+planning-root clean) is now safe and supported — F5 will route to that
+repo via `--repo-cwd`. What's NOT safe is an edit that spans multiple
+buckets: planning-root + a sibling, or two distinct siblings. Those would
+fail at F5 with `multi-repo-dirt` anyway; F1.5 catches them earlier with
+a clearer, edit-source-aware message before any disk writes happen.
+
+**Activation condition:** this guard runs **only** when `$QUICK_CONTEXT == 'product'` AND `$FAST_MODE` is true. Skip it entirely (early return, no side effects) in any other combination:
+- Milestone-context fast routes commits through `$QUICK_REPO_CWD` via `--repo-cwd`, which is already correct — guard not needed.
+- Non-fast paths use worktrees and planner/executor discipline — guard not needed.
+
+When the activation condition holds (`$QUICK_CONTEXT == 'product'` and `$FAST_MODE` is true), run the guard **before** any Read/Edit/Write in F2:
+
+1. **Enumerate sibling repo roots** from both sources (deduplicate by absolute path):
+
+   a. `config.local.json` → `projects.${current_project}.worktrees.*.repos` is a map of `repoName -> absolute worktree path`. Every value in every worktree's `repos` map is a sibling repo root.
+
+   b. `REPOS.md` → the markdown table has a `Path` column (typically relative like `../repo-name`). For each entry, resolve the path relative to planning-root cwd to get the absolute sibling repo root.
+
+2. **Determine the absolute path(s) you are about to edit.** Analyze `$DESCRIPTION` plus any codebase exploration needed to locate the target. For each intended edit, build the absolute path.
+
+3. **Check each intended edit against the sibling roots.** Normalize paths (resolve symlinks, strip trailing slashes) and test whether the edit path starts with any sibling repo root. Edits whose absolute path lies under the planning-root cwd itself are always allowed — only flag paths that live under a *registered sibling* repo root.
+
+4. **Partition intended edits into buckets.** For the set of intended-edit absolute paths from step 2:
+   - **planning-root bucket:** paths under the planning-root cwd that do NOT lie under any registered sibling root.
+   - **sibling-repo bucket(s):** paths whose absolute path starts with a sibling repo root (one bucket per matched sibling root, keyed by absolute root path).
+
+   Count the non-empty buckets:
+
+   - **0 non-empty buckets** (no edits inferred yet): proceed to F2; the guard re-checks via F5's post-edit `fast-route` if anything unexpected lands.
+   - **1 non-empty bucket** = planning-root only: ALLOWED. Continue to F2.
+   - **1 non-empty bucket** = exactly one sibling repo: ALLOWED. Continue to F2. F5's `fast-route` will route the commit through that sibling via `--repo-cwd`. Note in your edit plan which sibling you're targeting so RELATIVE_FILES computation in F5 uses the right STAGE_DIR.
+   - **2 or more non-empty buckets** (planning-root + sibling, OR sibling + sibling): BLOCKED. Fail fast with the error block below; do NOT proceed to F2.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  AMBIGUOUS MULTI-REPO FAST                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+/dgs:quick --fast in product context supports edits confined to a single
+bucket (planning-root only, OR exactly one sibling repo). The intended
+edits span multiple buckets, which fast-mode cannot auto-route:
+
+  planning-root edits:
+${planning_root_paths_or_"(none)"}
+
+  sibling-repo edits:
+${for each non-empty sibling bucket: "  - ${matched_sibling_root}: ${paths}"}
+
+Options:
+  1. Split into separate /dgs:fast invocations, one per bucket. Run them
+     sequentially; each invocation auto-routes to the correct cwd.
+  2. If this multi-repo work is part of an active milestone, re-invoke
+     under milestone-context (the milestone worktree routes via
+     --repo-cwd against the registered repo).
+  3. Use /dgs:quick (full planner+executor) for genuinely cross-repo work
+     that must commit atomically across repos.
+
+End workflow. Do not proceed to F2.
+```
+
+5. If exactly one bucket is non-empty (or none yet), continue to F2.
+
 **F2. Make edits**
 
+By the time F2 runs, the F1.5 cross-repo guard has already passed (in product-fast) or been skipped (in milestone-context fast / non-fast) — every path you touch below is guaranteed to land in the correct repo.
+
 Read the relevant file(s) based on `$DESCRIPTION`, make the requested changes directly using Read/Edit/Write tools. No planner, no executor — the orchestrator acts as the implementer.
 
+Track every file you edit in a shell array `$FAST_EDITED_FILES` (absolute paths as used with Read/Edit/Write). Initialize to empty before the first edit. Append each path exactly once (deduplicate before F5). This array is the authoritative file list for F5's commit — it replaces the default fallback behaviour of `cmdCommit` (which would otherwise stage `['.']` in `gitCwd` and sweep unrelated dirty state).
+
+If `$QUICK_CONTEXT` is `'milestone-context'`, relevant files live under `$QUICK_REPO_CWD` (the milestone worktree). Prefix Read/Edit/Write absolute paths with that directory — the main-checkout paths will be on `base_branch` and miss in-progress milestone work.
+
 If `$DRY_RUN`:
   After making edits but BEFORE committing, show the diff:
   ```bash
-  git diff
+  git -C "${QUICK_REPO_CWD:-.}" diff
   ```
   Then ask:
   ```
@@ -158,7 +386,7 @@ If `$DRY_RUN`:
   ```
   If user chooses "No, discard":
     ```bash
-    git checkout -- .
+    git -C "${QUICK_REPO_CWD:-.}" checkout -- .
     ```
     Display: "Changes discarded."
     Skip to completion output with message: "Dry run complete — no changes applied."
@@ -166,9 +394,9 @@ If `$DRY_RUN`:
 
 **F3. Post-edit scope check**
 
-After edits are made, check actual scope:
+After edits are made, check actual scope (run in the worktree when milestone-context):
 ```bash
-git diff --stat
+git -C "${QUICK_REPO_CWD:-.}" diff --stat
 ```
 
 Parse the output to count:
@@ -205,15 +433,68 @@ Analyze the description and the actual changes (`git diff`) to infer a conventio
 
 Commit message is NOT shown to user before committing — just commit silently.
 
-**F5. Commit**
+**F5. Commit (REL-05 routing-aware)**
+
+When `$QUICK_REPO_CWD` is set (milestone-context), route git operations through the worktree via `--repo-cwd`. Config (commit_docs, sync_push, current_project, worktree map) is still loaded from the planning-root cwd.
+
+For product-context fast (`$QUICK_CONTEXT == 'product'`, `$QUICK_REPO_CWD` empty), invoke the routing-decision helper to determine the correct `--repo-cwd`:
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "${commit_message}" --push
+DIRT_JSON=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" fast-route 2>/dev/null)
+ROUTE_ACTION=$(echo "$DIRT_JSON" | jq -r '.decision.action')
+ROUTE_REPO=$(echo "$DIRT_JSON" | jq -r '.decision.repoCwd // empty')
+ROUTE_EXIT=$(echo "$DIRT_JSON" | jq -r '.decision.exitCode // empty')
+ROUTE_MSG=$(echo "$DIRT_JSON" | jq -r '.decision.message // empty')
 ```
 
-Get the short hash:
+Cases:
+
+- `$ROUTE_ACTION == 'fail'` AND `$ROUTE_EXIT == 'multi-repo-dirt'`:
+  ```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║  MULTI-REPO DIRT DETECTED                                    ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+  $ROUTE_MSG
+
+  exit-code label: multi-repo-dirt
+  ```
+  End workflow with non-zero exit; do NOT commit.
+
+- `$ROUTE_ACTION == 'route-to-sub-repo'`: commit with `--repo-cwd $ROUTE_REPO`.
+- `$ROUTE_ACTION == 'route-to-planning-root'`: commit in planning-root cwd (existing behaviour).
+
+Pass the tracked file list via `--files` so `cmdCommit` does not fall back to its `['.']` default (which would stage the entire `gitCwd` tree and sweep in unrelated dirty state — see the 260422-q7f incident). Surface any submodule warnings from `decision.warnings` to the user (display, do NOT block).
+
 ```bash
-git rev-parse --short HEAD
+# Convert $FAST_EDITED_FILES (absolute paths) to paths relative to the
+# routed staging directory. Paths outside the staging directory should not appear
+# — the F1.5 cross-repo guard rejects them before F2.
+if [ -n "$QUICK_REPO_CWD" ]; then
+  STAGE_DIR="$QUICK_REPO_CWD"
+elif [ "$ROUTE_ACTION" = "route-to-sub-repo" ]; then
+  STAGE_DIR="$ROUTE_REPO"
+else
+  STAGE_DIR="$(pwd)"
+fi
+RELATIVE_FILES=()
+for f in "${FAST_EDITED_FILES[@]}"; do
+  # Strip STAGE_DIR prefix + leading slash to get the repo-relative path
+  RELATIVE_FILES+=( "${f#${STAGE_DIR}/}" )
+done
+
+if [ -n "$QUICK_REPO_CWD" ]; then
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "${commit_message}" --push --repo-cwd "$QUICK_REPO_CWD" --files "${RELATIVE_FILES[@]}"
+elif [ "$ROUTE_ACTION" = "route-to-sub-repo" ]; then
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "${commit_message}" --push --repo-cwd "$ROUTE_REPO" --files "${RELATIVE_FILES[@]}"
+else
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "${commit_message}" --push --files "${RELATIVE_FILES[@]}"
+fi
+```
+
+Get the short hash (from the routed staging directory):
+```bash
+git -C "${STAGE_DIR}" rev-parse --short HEAD
 ```
 
 Store as `$COMMIT_HASH`.
@@ -260,17 +541,26 @@ If archival occurred (result contains `"archived": true`), `quick/HISTORY.md` wa
 
 **F6c. Commit tracking (fast path only)**
 
-Commit STATE.md and HISTORY.md together so archival data is persisted:
+Commit STATE.md and HISTORY.md together so archival data is persisted. Uses `dgs-tools quick finalize --fast` — a single CLI call that stages both files (HISTORY.md optional) and commits with message `docs(quick-${quick_id}): track fast task`.
 
 ```bash
-FILE_LIST="${state_path}"
-if [ -f "${project_root}/quick/HISTORY.md" ]; then
-  FILE_LIST="${FILE_LIST} ${project_root}/quick/HISTORY.md"
+if [ -n "$QUICK_REPO_CWD" ]; then
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" quick finalize ${quick_id} \
+    --quick-dir "${quick_dir}" \
+    --state-path "${state_path}" \
+    --fast \
+    --push \
+    --repo-cwd "$QUICK_REPO_CWD" 2>/dev/null || true
+else
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" quick finalize ${quick_id} \
+    --quick-dir "${quick_dir}" \
+    --state-path "${state_path}" \
+    --fast \
+    --push 2>/dev/null || true
 fi
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): track fast task" --push --files ${FILE_LIST} 2>/dev/null || true
 ```
 
-The `|| true` handles the case where nothing changed (e.g., STATE.md wasn't modified).
+The `|| true` handles the case where nothing changed (e.g., STATE.md wasn't modified) — `quick finalize` returns `commit_reason: 'nothing_to_commit'` cleanly in that scenario.
 
 **F7. Output**
 
@@ -301,10 +591,10 @@ mkdir -p "${task_dir}"
 
 **Step 4: Create quick task directory**
 
-Create the directory for this quick task:
+Use `task_dir` from init output — do NOT build the path manually:
 
 ```bash
-QUICK_DIR="${project_root}/quick/${quick_id}-${slug}"
+QUICK_DIR="${task_dir}"
 mkdir -p "$QUICK_DIR"
 ```
 
@@ -616,6 +906,12 @@ Task(
   prompt="
 Execute quick task ${quick_id}.
 
+${QUICK_CONTEXT === 'product' && QUICK_REPOS && Object.keys(QUICK_REPOS).length > 0 ? `
+<worktree_context>
+This quick task is executing in a git worktree. Work in these directories — do NOT use the main checkout paths:
+${Object.entries(QUICK_REPOS).map(([name, dir]) => '- ' + name + ': ' + dir).join('\n')}
+</worktree_context>
+` : ''}
 <files_to_read>
 - ${QUICK_DIR}/${quick_id}-PLAN.md (Plan)
 - ${state_path} (Project state)
@@ -751,6 +1047,10 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state archive-quick
 
 If archival occurred, `quick/HISTORY.md` was created or updated. Include it in Step 8's commit file list.
 
+**7c3. Milestone-context quick tracking**
+
+If `$QUICK_CONTEXT` is 'milestone-context', note this in the Directory column of the table row. Instead of a directory link, use: `milestone (${MILESTONE_SLUG})`.
+
 **7d. Update "Last activity" line:**
 
 Use `date` from init:
@@ -764,20 +1064,18 @@ Use Edit tool to make these changes atomically
 
 **Step 8: Final commit and completion**
 
-Stage and commit quick task artifacts:
-
-Build file list:
-- `${QUICK_DIR}/${quick_id}-PLAN.md`
-- `${QUICK_DIR}/${quick_id}-SUMMARY.md`
-- `${state_path}`
-- `${project_root}/quick/HISTORY.md` (if it exists — may have been created by archival)
-- If `$DISCUSS_MODE` and context file exists: `${QUICK_DIR}/${quick_id}-CONTEXT.md`
-- If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
+Commit all quick task artifacts atomically via `dgs-tools quick finalize`. This single CLI call stages and commits PLAN, SUMMARY, STATE, and any optional artifacts present on disk (CONTEXT, VERIFICATION, HISTORY) in one commit — no file-list assembly needed.
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --push --files ${file_list}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" quick finalize ${quick_id} \
+  --quick-dir "${quick_dir}" \
+  --state-path "${state_path}" \
+  --description "${DESCRIPTION}" \
+  --push
 ```
 
+Missing optional artifacts are skipped gracefully (no error if CONTEXT.md, VERIFICATION.md, or HISTORY.md do not exist).
+
 Get final commit hash:
 ```bash
 commit_hash=$(git rev-parse --short HEAD)
@@ -841,4 +1139,8 @@ Ready for next task: /dgs:quick
 - [ ] (--fast) Scope warning shown when >3 files or >30 lines affected
 - [ ] (--fast) (--dry-run) Changes shown as diff, user asked to apply or discard
 - [ ] (--fast) Minimal output: "Done: {message} [{hash}]"
+- [ ] (--fast) F5 commit passes `--files` with the exact list of paths edited during F2 (no fallback to `cmdCommit`'s `['.']` default)
+- [ ] (--fast) Product-context fast rejects edits targeting sibling repos registered in `config.local.json` worktrees or `REPOS.md`, with an actionable error before F2 begins
+- [ ] (--fast) F1.5-pre pre-edit dirt check runs BEFORE F1.5; pre-existing dirt fails with `pre-existing-dirt` exit-code label in non-interactive mode (REL-06)
+- [ ] (--fast) F5 commit routes via fast-route decision: single-sub-repo dirty → `--repo-cwd <sub>`; multi-dirty → fails with `multi-repo-dirt` exit-code label; submodule warnings surface but don't block (REL-05)
 </success_criteria>

package/deliver-great-systems/workflows/refine-spec.md

@@ -125,7 +125,7 @@ Context is used to inform the conversation -- for example, when discussing imple
 
 3. Load source idea docs:
    Read the spec's frontmatter to find `source_ideas` (array of idea filenames). For each source idea:
-   a. Derive the idea docs path (same pattern as write-spec: strip prefix/suffix for slug, check `${project_root}/ideas/pending/{slug}/docs/` or done/rejected paths)
+   a. Derive the idea docs path: strip prefix/suffix for slug, check `${project_root}/docs/ideas/{slug}/`
    b. If docs/ directory exists, read all files using the same pattern above
    c. Idea docs are loaded first (source material), then spec docs (refinements). If too many, cap spec docs.