@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/deliver-great-systems/workflows/run-job.md

@@ -293,7 +293,7 @@ Loop through steps starting from `nextStepIndex`.
 
    **Mid-workflow push (after phase-completing steps):**
 
-   After a step completes successfully, check if the step's command is a phase-completing workflow: `execute-phase`, `verify-work`, `audit-phase`, `audit-milestone`, `plan-phase`, `plan-milestone-gaps`, or `complete-milestone`.
+   After a step completes successfully, check if the step's command is a phase-completing workflow: `execute-phase`, `verify-work`, `audit-phase`, `audit-milestone`, `plan-phase`, `plan-milestone-gaps`, `validate-phase`, or `complete-milestone`.
 
    If so, and `sync_push` is not `"off"` and `cadence_push` is true:
    ```bash
@@ -359,11 +359,11 @@ After an `audit-milestone` step completes successfully, check the audit outcome.
 
 Note: --no-check jobs never trigger this code path because they have no audit-milestone step. The `check: false` header means no `audit-milestone` step is generated by `generateMilestoneSteps`, so handle_audit_result is never reached.
 
-Note: The original complete-milestone step (if present) remains at its position after the original
-audit step. Gap-fix steps (including re-audit) are inserted between the original audit step and
-complete-milestone. When the re-audit passes, the loop naturally reaches complete-milestone.
-If the re-audit finds MORE gaps, another cycle inserts steps after THAT re-audit, further
-deferring complete-milestone. This is correct -- complete-milestone only runs after a clean audit.
+Note: audit-milestone is the last step of milestone jobs. complete-milestone is never
+auto-run because it requires manual intervention (branch review, tag push, merge conflict
+resolution). After audit passes, the job ends and the user runs /dgs:complete-milestone
+manually. Gap-fix steps are inserted after the original audit step; when a re-audit passes,
+the job completes and the user still runs complete-milestone manually.
 
 1. **Read audit status:**
    ```bash
@@ -378,9 +378,9 @@ deferring complete-milestone. This is correct -- complete-milestone only runs af
      ```
    - If `GAP_FIX_CYCLE == 0` (audit passed first time): Display clean banner:
      ```
-     Audit passed -- no gaps found. Proceeding to complete milestone.
+     Audit passed -- no gaps found. Run /dgs:complete-milestone manually to archive.
      ```
-   - Continue to the next step (should be `complete-milestone`).
+   - Job completes after this step. User runs /dgs:complete-milestone manually when ready.
 
 3. **If `gaps_found`:**
 

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

@@ -12,6 +12,14 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd
 
 ## 0. Initialize
 
+**Parse `--scaffold` flag:**
+
+```
+Parse `--scaffold` flag from PHASE_ARG (e.g., `/dgs:validate-phase 16 --scaffold`).
+Set `SCAFFOLD_MODE = true` if `--scaffold` is present, `false` otherwise.
+Strip `--scaffold` from PHASE_ARG before passing to `init phase-op`.
+```
+
 ```bash
 INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init phase-op "${PHASE_ARG}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
@@ -83,10 +91,14 @@ Classify each requirement:
 
 Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
 
-No gaps → skip to Step 6, set `nyquist_compliant: true`.
+**Scaffold mode:** If `SCAFFOLD_MODE` is true, override all gap statuses to `PENDING_REVIEW` (not MISSING, not manual-only -- a distinct scaffold status meaning "gap identified but not yet triaged").
+
+No gaps → skip to Step 6, set `nyquist_compliant: true`. In scaffold mode, this still produces a VALIDATION.md (with all requirements COVERED or PENDING_REVIEW).
 
 ## 4. Present Gap Plan
 
+**Scaffold mode:** If `SCAFFOLD_MODE` is true, skip this step entirely (do not call AskUserQuestion). Proceed directly to Step 6.
+
 Call AskUserQuestion with gap table and options:
 1. "Fix all gaps" → Step 5
 2. "Skip — mark manual-only" → add to Manual-Only, Step 6
@@ -94,6 +106,8 @@ Call AskUserQuestion with gap table and options:
 
 ## 5. Spawn dgs-nyquist-auditor
 
+**Scaffold mode:** If `SCAFFOLD_MODE` is true, skip this step entirely (do not spawn auditor). Proceed directly to Step 6.
+
 ```
 Task(
   prompt="Read ~/.claude/agents/dgs-nyquist-auditor.md for instructions.\n\n" +
@@ -114,6 +128,8 @@ Handle return:
 
 ## 6. Generate/Update VALIDATION.md
 
+**Scaffold mode:** If `SCAFFOLD_MODE` is true, always use the State B (create) flow regardless of existing VALIDATION.md state. Gaps are marked as `PENDING_REVIEW` in the Per-Task Map.
+
 **State B (create):**
 1. Read template from `~/.claude/deliver-great-systems/templates/VALIDATION.md`
 2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
@@ -134,6 +150,15 @@ Handle return:
 
 ## 7. Commit
 
+**Scaffold mode:** If `SCAFFOLD_MODE` is true:
+- Only commit VALIDATION.md (no test files -- none were generated)
+- Commit message: `docs(phase-${PHASE}): scaffold Nyquist validation`
+- Use: `node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit-docs "docs(phase-${PHASE}): scaffold Nyquist validation"`
+- Do NOT run the `git add {test_files}` / `git commit -m "test(..."` block
+- Skip to Step 8
+
+**Non-scaffold mode:**
+
 ```bash
 git add {test_files}
 git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
@@ -143,6 +168,14 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit-docs "docs(p
 
 ## 8. Results + Routing
 
+**Scaffold mode:** If `SCAFFOLD_MODE` is true, display scaffold-specific output and exit:
+```
+DGS > PHASE {N} VALIDATION SCAFFOLDED
+{M} requirements mapped, {K} gaps pending review.
+> Fill gaps: /dgs:validate-phase {N}
+```
+Display `/clear` reminder. Skip the Compliant/Partial output below.
+
 **Compliant:**
 ```
 DGS > PHASE {N} IS NYQUIST-COMPLIANT
@@ -174,4 +207,9 @@ Display `/clear` reminder.
 - [ ] VALIDATION.md created or updated
 - [ ] Test files committed separately
 - [ ] Results with routing presented
+- [ ] --scaffold flag parsed and controls Steps 4-8
+- [ ] Scaffold mode skips interactive gap plan (Step 4) and auditor (Step 5)
+- [ ] Scaffold mode marks gaps as PENDING_REVIEW
+- [ ] Scaffold mode commits docs-only with scaffold commit message
+- [ ] Scaffold mode displays scaffold-specific results banner
 </success_criteria>

package/deliver-great-systems/workflows/verify-work.md

@@ -63,6 +63,20 @@ REPOS_MD=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" repos li
 ```
 
 Parse JSON for the list of registered repos with paths.
+
+**Worktree-aware code directory resolution (resolveCodeContext):**
+
+For each registered code repo, resolve the correct working directory. When a milestone or quick worktree is active, code operations must target the worktree directory, not the main checkout.
+
+```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
+```
+
+Use `ctx.directory` (or the repo's main checkout path when no worktree is active) for all file reading, test execution, and code verification operations. Do NOT hardcode repo paths from REPOS.md when a worktree may be active.
 </step>
 
 <step name="check_active_session">

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

@@ -103,8 +103,8 @@ Then proceed normally. Only show this tip when ALL selected ideas lack enrichmen
 **Load supporting documents** from each selected idea's `docs/` directory:
 
 For each selected idea:
-a. Derive the idea's docs path: `${project_root}/ideas/pending/{idea_slug}/docs/` where `idea_slug` is derived from the idea filename (strip numeric prefix and .md suffix, e.g., `005-retry-logic.md` -> `retry-logic`).
-   Alternative path: check if ideas use a flat structure where docs are at `${project_root}/docs/ideas/pending/{slug}-*.md`.
+a. Derive the idea's docs path: `${project_root}/docs/ideas/{idea_slug}/` where `idea_slug` is derived from the idea filename (strip numeric prefix and .md suffix, e.g., `005-retry-logic.md` -> `retry-logic`).
+   Alternative path: check for research docs at `${project_root}/docs/ideas/{slug}-*.md`.
 b. If the docs/ directory exists, list all files in it:
    ```bash
    ls "${IDEA_DOCS_DIR}/" 2>/dev/null

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.8.0",
+  "version": "3.0.4",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"