@ktpartners/dgs-platform 2.9.0 → 3.3.0

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
@@ -222,7 +222,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id
 
 Commit the draft:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --push --files ${project_root}/specs/$filename
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --push --files specs/$filename
 ```
 
 Store `SPEC_ID` and `FILENAME` for subsequent steps.
@@ -289,7 +289,7 @@ Use AskUserQuestion: "Review the draft spec above. Type **approve** to send to r
 
 After approval, commit any changes:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --push --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --push --files specs/$FILENAME
 ```
 </step>
 
@@ -350,7 +350,7 @@ Estimated cost: ~$X.XX
 **6. Commit updated spec:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --push --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --push --files specs/$FILENAME
 ```
 </step>
 
@@ -394,18 +394,16 @@ Source ideas moved to done: $IDEAS_MOVED
 Research documents moved to done: $RESEARCH_DOCS_MOVED (if any)
 
 What would you like to do next?
-1. Create a new project from this spec -> /dgs:new-project
-2. Add a milestone to an existing project -> /dgs:new-milestone
-3. Nothing for now -- the spec is saved and ready when you are
+1. Start a milestone from this spec -> /dgs:new-milestone --auto $SPEC_ID
+2. Nothing for now -- the spec is saved and ready when you are
 ```
 
-In interactive mode, use AskUserQuestion: "Choose 1, 2, or 3 (or just press enter to defer):"
+In interactive mode, use AskUserQuestion: "Choose 1 or 2 (or just press enter to defer):"
 
-- If **1**: Tell user "Run `/dgs:new-project` and reference spec `$FILENAME` during project creation."
-- If **2**: Tell user "Run `/dgs:new-milestone` and reference spec `$FILENAME` during milestone creation."
-- If **3** or empty/enter: Output "Spec saved. You can find it at `${project_root}/specs/$FILENAME`."
+- If **1**: Tell user "Run `/dgs:new-milestone --auto $SPEC_ID` to start a milestone from this spec. If no project exists yet, run `/dgs:new-project` first to create the project holder, then `/dgs:new-milestone --auto $SPEC_ID`."
+- If **2** or empty/enter: Output "Spec saved. You can find it at `specs/$FILENAME` (planning root)."
 
-In `--auto` mode: skip the routing question, just output the summary with the three options listed for reference.
+In `--auto` mode: skip the routing question, just output the summary with the two options listed for reference.
 </step>
 
 </process>

package/hooks/dist/dgs-enforce-discipline.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// DGS Workflow Discipline Enforcement - PreToolUse + PostToolUse hook
+//
+// Ensures Edit/Write tool calls only happen inside /dgs:* commands.
+// Works via a marker file that tracks active DGS command state:
+//
+// 1. When tool_name is "Skill" and the skill name starts with "dgs:":
+//    - PreToolUse: Write a marker file to /tmp/dgs-active-{session_id}.json
+//    - PostToolUse: Delete the marker, then check for uncommitted DGS files
+//
+// 2. When tool_name is "Edit" or "Write":
+//    - Check for marker file — if present, allow
+//    - Check if target path is in the allowlist — if so, allow
+//    - Check if cwd is a DGS planning folder — if not, allow (non-DGS project)
+//    - Otherwise, deny with explanation
+//
+// Safety net: After every /dgs:* command completes, checks for uncommitted
+// DGS-managed files and auto-commits them. Logs a warning so the upstream
+// workflow bug can be identified and fixed.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Paths where Edit/Write is allowed without a DGS command
+const ALLOWED_PATH_PATTERNS = [
+  /\.claude\/projects\/.*\/memory\//,   // Auto-memory system
+  /\.claude\/.*\/memory\//,             // Memory in any .claude subfolder
+  /\/tmp\//,                            // Temp files
+];
+
+// DGS-managed paths that should be committed (relative to planning root)
+// Used by the safety net to detect orphaned writes after a command completes
+const DGS_MANAGED_PATTERNS = [
+  /^STATE\.md$/,
+  /^PROJECTS\.md$/,
+  /^MILESTONES\.md$/,
+  /^RETROSPECTIVE\.md$/,
+  /^CLAUDE\.md$/,
+  /^config\.json$/,
+  /^projects\/[^/]+\/STATE\.md$/,
+  /^projects\/[^/]+\/ROADMAP\.md$/,
+  /^projects\/[^/]+\/REQUIREMENTS\.md$/,
+  /^projects\/[^/]+\/PROJECT\.md$/,
+  /^projects\/[^/]+\/phases\//,
+  /^projects\/[^/]+\/milestones\//,
+  /^specs\//,
+  /^ideas\//,
+  /^todos\//,
+  /^jobs\//,
+  /^quick\//,
+  /^milestones\//,
+  /^codebase\//,
+];
+
+function getMarkerPath(sessionId) {
+  return path.join(os.tmpdir(), `dgs-active-${sessionId}.json`);
+}
+
+function isDgsProject(cwd) {
+  try {
+    const configPath = path.join(cwd, 'config.json');
+    if (!fs.existsSync(configPath)) return false;
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return content.includes('"product_name"');
+  } catch {
+    return false;
+  }
+}
+
+function isAllowedPath(filePath) {
+  if (!filePath) return false;
+  return ALLOWED_PATH_PATTERNS.some(pattern => pattern.test(filePath));
+}
+
+function getTargetPath(toolName, toolInput) {
+  if (!toolInput) return null;
+  // Edit and Write both use file_path
+  return toolInput.file_path || null;
+}
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+    const hookEvent = data.hook_event_name;
+    const toolName = data.tool_name;
+    const toolInput = data.tool_input || {};
+    const cwd = data.cwd || process.cwd();
+
+    // ── PostToolUse: Clean up marker + safety net when Skill completes ──
+    if (hookEvent === 'PostToolUse') {
+      if (toolName === 'Skill') {
+        const skillName = toolInput.skill || toolInput.name || '';
+        if (skillName.startsWith('dgs:')) {
+          // Delete the active marker
+          const markerPath = getMarkerPath(sessionId);
+          try { fs.unlinkSync(markerPath); } catch { /* already gone */ }
+
+          // Safety net: check for uncommitted DGS-managed files
+          if (isDgsProject(cwd)) {
+            try {
+              const status = execSync('git status --porcelain', { cwd, encoding: 'utf-8', timeout: 5000 });
+              if (status.trim()) {
+                const lines = status.trim().split('\n');
+                const dirty = lines
+                  .map(l => l.slice(3).trim())  // strip status prefix (e.g., " M ", "?? ")
+                  .filter(f => DGS_MANAGED_PATTERNS.some(p => p.test(f)));
+
+                if (dirty.length > 0) {
+                  // Stage and commit orphaned DGS files
+                  for (const f of dirty) {
+                    execSync(`git add "${f}"`, { cwd, stdio: 'pipe', timeout: 5000 });
+                  }
+                  const msg = `chore: auto-commit ${dirty.length} uncommitted DGS file(s) after ${skillName}`;
+                  execSync(`git commit -m "${msg}"`, { cwd, stdio: 'pipe', timeout: 10000 });
+
+                  // Warn via additionalContext so Claude sees it
+                  const result = {
+                    continue: true,
+                    suppressOutput: false,
+                    hookSpecificOutput: {
+                      hookEventName: 'PostToolUse',
+                      additionalContext: `[DGS safety net] Auto-committed ${dirty.length} orphaned file(s) after ${skillName}: ${dirty.join(', ')}. This indicates a missing commit in the ${skillName} workflow — consider fixing upstream.`,
+                    },
+                  };
+                  process.stdout.write(JSON.stringify(result));
+                  process.exit(0);
+                }
+              }
+            } catch { /* git not available or commit failed — don't block */ }
+          }
+        }
+      }
+      process.exit(0);
+    }
+
+    // ── PreToolUse: Skill → write marker ──
+    if (hookEvent === 'PreToolUse' && toolName === 'Skill') {
+      const skillName = toolInput.skill || toolInput.name || '';
+      if (skillName.startsWith('dgs:')) {
+        const markerPath = getMarkerPath(sessionId);
+        const marker = {
+          command: skillName,
+          started: new Date().toISOString(),
+          session_id: sessionId,
+        };
+        fs.writeFileSync(markerPath, JSON.stringify(marker));
+      }
+      process.exit(0);
+    }
+
+    // ── PreToolUse: Edit/Write → check marker ──
+    if (hookEvent === 'PreToolUse' && (toolName === 'Edit' || toolName === 'Write')) {
+      // Not a DGS project? Allow everything.
+      if (!isDgsProject(cwd)) {
+        process.exit(0);
+      }
+
+      // Target path in allowlist? Allow.
+      const targetPath = getTargetPath(toolName, toolInput);
+      if (isAllowedPath(targetPath)) {
+        process.exit(0);
+      }
+
+      // DGS command active? Allow.
+      const markerPath = getMarkerPath(sessionId);
+      if (fs.existsSync(markerPath)) {
+        process.exit(0);
+      }
+
+      // No DGS command active in a DGS project — deny.
+      const result = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: 'DGS workflow discipline: Edit/Write requires an active /dgs:* command. Use /dgs:fast (trivial), /dgs:quick (small), or /dgs:execute-phase (feature). Say "skip DGS" to bypass.',
+        },
+      };
+      process.stdout.write(JSON.stringify(result));
+      process.exit(0);
+    }
+
+    // Any other tool/event — allow
+    process.exit(0);
+  } catch {
+    // Parse error or unexpected input — don't block
+    process.exit(0);
+  }
+});

package/package.json

@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.9.0",
+  "version": "3.3.0",
   "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"

package/scripts/build-hooks.js

@@ -13,6 +13,7 @@ const DIST_DIR = path.join(HOOKS_DIR, 'dist');
 const HOOKS_TO_COPY = [
   'dgs-check-update.js',
   'dgs-context-monitor.js',
+  'dgs-enforce-discipline.js',
   'dgs-statusline.js'
 ];