@ktpartners/dgs-platform 3.0.4 → 3.3.1

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

@@ -9,7 +9,10 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 - PLAN: plan number
 - PLAN_PATH: path to the PLAN.md file
 - PHASE_DIR: phase directory path
+- CODE_REPO_PATH: absolute path to the code repo where task commits live. All git commands in this workflow MUST run against this repo via `git -C "${CODE_REPO_PATH}"`, because the spawned subagent inherits the orchestrator's cwd (the planning repo), not the code repo.
 - DIFF_REF: git ref range for the code diff (from first task commit to HEAD)
+- PROJECT_ROOT: project root directory path (e.g., projects/gsd). Passed by execute-phase. Used to resolve project-scoped context files.
+- PLANNING_ROOT: planning root directory path (git repo root). Passed by execute-phase. Used as fallback for product-level context files.
 </inputs>
 
 <process>
@@ -18,7 +21,7 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 Compute the diff from 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, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."
@@ -26,13 +29,13 @@ If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${P
 Otherwise, compute the full diff:
 
 ```bash
-REVIEW_DIFF=$(git diff ${FIRST_TASK_COMMIT}^..HEAD)
+REVIEW_DIFF=$(git -C "${CODE_REPO_PATH}" diff ${FIRST_TASK_COMMIT}^..HEAD)
 ```
 
 Store REVIEW_DIFF for use by all review agents. Also store the file list:
 
 ```bash
-CHANGED_FILES=$(git diff --name-only ${FIRST_TASK_COMMIT}^..HEAD)
+CHANGED_FILES=$(git -C "${CODE_REPO_PATH}" diff --name-only ${FIRST_TASK_COMMIT}^..HEAD)
 ```
 
 Display:
@@ -43,11 +46,77 @@ Reviewing ${PHASE}-${PLAN} changes:
 ```
 </step>
 
+<step name="load_context">
+Load project context files for domain-specific review. These files provide architecture rules, coding conventions, and design principles that the review agents use to catch project-specific violations alongside generic code quality issues.
+
+If PROJECT_ROOT is empty or not provided, skip the entire step silently (backward compatibility for codereview spawned without PROJECT_ROOT).
+
+**Context files (in truncation priority order -- first truncated = least valuable):**
+1. `codebase/ARCHITECTURE.md` -- auto-generated codebase structure overview
+2. `codebase/CONVENTIONS.md` -- auto-generated naming/import/error handling patterns
+3. `docs/product/ARCHITECTURE.md` -- hand-written target architecture and domain rules
+4. `docs/product/DESIGN-PRINCIPLES.md` -- hand-written design principles and lessons learned
+
+**Path resolution (dual-path fallback):**
+For each file, try two paths in order:
+1. `${PROJECT_ROOT}/<file>` (v2 project-scoped path)
+2. `${PLANNING_ROOT}/<file>` (v1 product-level / synthesized fallback)
+
+Use the Read tool to load each file. If Read returns an error (file not found), silently skip that file. Do NOT error or warn for individual missing files.
+
+**Build PROJECT_CONTEXT:**
+For each successfully loaded file, prepend a header line:
+```
+--- {filename} ({byte_count} bytes) ---
+{file_content}
+```
+
+Concatenate all loaded file contents into a single `PROJECT_CONTEXT` variable.
+
+**Size guard:**
+After loading all files, measure total byte length of PROJECT_CONTEXT.
+
+If total exceeds 51200 bytes (~50KB):
+- Truncate files in priority order (ARCHITECTURE.md from codebase/ first, then CONVENTIONS.md from codebase/, then docs/product/ARCHITECTURE.md, then docs/product/DESIGN-PRINCIPLES.md last)
+- For each truncated file, cut to fit within the remaining budget and append: `\n[Truncated from {original_bytes} bytes to {truncated_bytes} bytes]`
+- After truncation, log a warning:
+  ```
+  ⚠ Project context truncated to ~50KB:
+    {filename}: truncated from {original} to {truncated} bytes
+  ```
+
+**Logging:**
+Display which context files were loaded:
+
+When at least one file found:
+```
+Project context loaded:
+  codebase/ARCHITECTURE.md: {N} bytes
+  codebase/CONVENTIONS.md: {N} bytes (or "not found")
+  docs/product/ARCHITECTURE.md: {N} bytes (or "not found")
+  docs/product/DESIGN-PRINCIPLES.md: {N} bytes (or "not found")
+  Total: {N} bytes
+```
+
+When no files found:
+```
+Project context: no context files found (skipped)
+```
+</step>
+
 <step name="pass_1_foundational">
 **Pass 1: Foundational Review** -- Spawn 3 parallel Task() subagents.
 
 Each agent receives REVIEW_DIFF and CHANGED_FILES as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 1A: Correctness and Security**
 
 Review REVIEW_DIFF for:
@@ -57,6 +126,7 @@ Review REVIEW_DIFF for:
 - Auth bypass, missing authorization checks
 - Secret exposure (hardcoded keys, tokens, passwords)
 - Race conditions, deadlocks
+- Violations of domain-specific rules from PROJECT_CONTEXT (if provided): architecture constraints, module boundary contracts, security policies declared in project docs
 - Memory leaks, resource cleanup
 
 Output: Structured findings list with fields:
@@ -81,7 +151,7 @@ Review REVIEW_DIFF against the plan's `<context>` file patterns for:
 - Type safety (any usage, missing types, loose generics)
 - Consistency with existing codebase patterns
 
-If a codebase/ map exists at ${project_root}/codebase/, reference CONVENTIONS.md for established patterns.
+Reference the project conventions and patterns from PROJECT_CONTEXT (if provided) when evaluating naming, import patterns, error handling, and code organization. Flag deviations from the project's established conventions documented in PROJECT_CONTEXT.
 
 Output: Structured findings list with fields:
 - id: "1B-{N}"
@@ -113,6 +183,14 @@ Output: Structured findings list with fields:
 
 Each agent receives REVIEW_DIFF, CHANGED_FILES, and all Pass 1 findings as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 2A: Fix Verification**
 
 For each auto-fixable finding from Pass 1 (severity medium or low with a clear fix), propose a concrete code change.
@@ -174,6 +252,14 @@ Output: Structured findings list with fields:
 
 Each agent receives REVIEW_DIFF, CHANGED_FILES, and all findings from Pass 1 and Pass 2 as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 3A: Fresh Eyes**
 
 Re-read REVIEW_DIFF without bias from prior findings. Identify anything missed by the previous 6 agents. Focus on:
@@ -181,6 +267,7 @@ Re-read REVIEW_DIFF without bias from prior findings. Identify anything missed b
 - Edge cases in business logic
 - Assumptions that may not hold in production
 - Missing error messages or unhelpful error messages
+- Violations of design principles stated in PROJECT_CONTEXT (if provided) that previous agents may have missed — compare implementation choices against documented principles and architectural decisions
 
 Output: Net-new findings only (deduplicated against all prior findings). Use fields:
 - id: "3A-{N}"
@@ -367,8 +454,8 @@ Take the proposed fixes from Agent 2A.
 4. Stage all successful fixes and commit:
 
 ```bash
-git add [fixed files]
-git commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
+git -C "${CODE_REPO_PATH}" add [fixed files]
+git -C "${CODE_REPO_PATH}" commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
 
 - [list each fix applied, one per bullet]
 
@@ -409,15 +496,22 @@ No fixes qualified for auto-application (all findings were critical/high severit
 
 Update the frontmatter: set `stats.auto_fixed` to `{FIXES_APPLIED}`.
 
-Include CODEREVIEW.md in the auto-fix commit by adding it to the staged files:
+**Do NOT include CODEREVIEW.md in the auto-fix commit.** CODEREVIEW.md lives in the planning repo under `${PHASE_DIR}`, while the auto-fix commit lives in the code repo. `git -C "${CODE_REPO_PATH}" add ${CODEREVIEW_PATH}` would fail because `${CODEREVIEW_PATH}` is not inside `${CODE_REPO_PATH}`. CODEREVIEW.md will be picked up by the amend-metadata-commit at the bottom of the execute-phase codereview gate (which commits it in the planning repo).
+
+For the auto-fix commit, stage only the code-repo files:
 
-Change the existing `git add [fixed files]` to also include CODEREVIEW.md:
 ```bash
-git add [fixed files] ${CODEREVIEW_PATH}
+git -C "${CODE_REPO_PATH}" add [fixed files]
+git -C "${CODE_REPO_PATH}" commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
+
+- [list each fix applied, one per bullet]
+
+Co-Authored-By: Claude Code Review <noreply@anthropic.com>"
 ```
 
 If no auto-fixes were applied (commit skipped), commit CODEREVIEW.md alone:
 ```bash
+# CODEREVIEW.md lives in the planning repo under ${PHASE_DIR}. This commit intentionally runs in the inherited (planning) cwd — do NOT use git -C "${CODE_REPO_PATH}" here.
 git add ${CODEREVIEW_PATH}
 git commit -m "docs(${PHASE}-${PLAN}): codereview report
 

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

@@ -140,6 +140,24 @@ MUST present 3 options:
 
 If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
 
+**REVIEW.md existence check:**
+
+```bash
+REVIEW_PATH="${project_root}/../milestones/${milestone_version}-REVIEW.md"
+if [ ! -f "$REVIEW_PATH" ]; then
+  # Also check archive directory
+  REVIEW_PATH="${archive_dir}/${milestone_version}-REVIEW.md"
+fi
+```
+
+If REVIEW.md does not exist at either path:
+
+```
+Warning: REVIEW.md not found — run `dgs-tools jobs generate-review` before sharing with reviewers
+```
+
+This is a warning only — REVIEW.md absence does NOT block milestone completion. The report is supplementary context for four-eyes reviewers and can be generated after completion if needed.
+
 <config-check>
 
 ```bash
@@ -603,7 +621,7 @@ Update `${roadmap_path}` — group completed milestone phases:
 **Delegate archival to dgs-tools:**
 
 ```bash
-ARCHIVE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone complete "v[X.Y]" --name "[Milestone Name]")
+ARCHIVE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone complete "v[X.Y]" --name "[Milestone Name]" --archive-phases)
 ```
 
 The CLI handles:
@@ -613,20 +631,21 @@ The CLI handles:
 - Moving audit file to milestones if it exists
 - Creating/appending MILESTONES.md entry with accomplishments from SUMMARY.md files
 - Updating STATE.md (status, last activity)
+- Moving milestone phase directories to `milestones/v[X.Y]-phases/` (planning root)
+- Moving completed quick task directories to `milestones/v[X.Y]-quick/` (those with SUMMARY.md)
 
 Extract from result: `version`, `date`, `phases`, `plans`, `tasks`, `accomplishments`, `archived`.
 
 Verify: `✅ Milestone archived to milestones/`
 
-**Phase archival (mandatory):** After milestone archival completes, archive phase directories. Phase directories are fully committed to git history, so they are always recoverable.
+Verify `archived.phases` is `true` in the result. If false, error: "Phase archival failed — check ${phases_dir} and milestones/ directory."
 
-```bash
-mkdir -p milestones/v[X.Y]-phases
-# For each phase directory in ${phases_dir}/:
-mv ${phases_dir}/{phase-dir} milestones/v[X.Y]-phases/
-```
 Verify: `✅ Phase directories archived to milestones/v[X.Y]-phases/`
 
+Verify `archived.quick` is `true` in the result if completed quick tasks existed. If false but quick dirs were expected, warn: "Quick archival returned false -- check projects/{project}/quick/ directory."
+
+Verify: `completed quick directories archived to milestones/v[X.Y]-quick/`
+
 After archival, the AI still handles:
 - Reorganizing ROADMAP.md with milestone grouping (requires judgment)
 - Full PROJECT.md evolution review (requires understanding)

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

@@ -8,7 +8,44 @@ This workflow is only valid for product-level quicks. If the user is working in
 
 <process>
 
-**Step 1: Validate and execute complete-quick**
+**Step 1: Generate inline review summary**
+
+Before rebase-and-merge, generate a review report while the quick branch still exists with original commits.
+
+```bash
+REVIEW_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" quick generate-review --raw 2>&1)
+REVIEW_EXIT=$?
+```
+
+**If generation succeeds** (`REVIEW_EXIT` is 0):
+
+Parse JSON output for the summary:
+```bash
+REVIEW_PATH=$(echo "$REVIEW_RESULT" | jq -r '.relativePath // empty')
+REVIEW_COMMITS=$(echo "$REVIEW_RESULT" | jq -r '.stats.commits // 0')
+REVIEW_FILES=$(echo "$REVIEW_RESULT" | jq -r '.stats.filesChanged // 0')
+REVIEW_RISKS=$(echo "$REVIEW_RESULT" | jq -r '.stats.riskFlags // 0')
+```
+
+Display the stats banner:
+```
+Review: ${REVIEW_PATH} (${REVIEW_COMMITS} commits, ${REVIEW_FILES} files${REVIEW_RISKS > 0 ? ", ${REVIEW_RISKS} risk flags" : ""})
+```
+
+**If fast-forward detected** (output contains `"fastForward": true`):
+
+Display: `No code changes detected -- review not generated.`
+
+**If generation fails** (`REVIEW_EXIT` is non-zero):
+
+Log warning and continue -- do NOT block task completion:
+```
+Warning: Review generation failed. Continuing with completion.
+```
+
+Review generation failure is non-fatal. The quick task will still complete normally.
+
+**Step 2: Validate and execute complete-quick**
 
 Call the complete-quick CLI command which validates the active quick and executes the full flow:
 
@@ -43,7 +80,7 @@ After resolving conflicts manually, re-run:
 ```
 End workflow.
 
-**Step 2: Display success**
+**Step 3: Display success**
 
 Parse JSON result from RESULT.
 
@@ -59,6 +96,7 @@ Worktree cleaned up. Pushed to origin.
 </process>
 
 <success_criteria>
+- [ ] Review summary generated before rebase-and-merge (or warning logged on failure)
 - [ ] Active product-level quick validated
 - [ ] Rebase-before-merge flow executed via rebaseAndMerge()
 - [ ] Worktree and branch cleaned up

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

@@ -290,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%).
@@ -387,6 +414,27 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    If `CODEREVIEW` is not `true`: skip silently, 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).
+
    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:
@@ -402,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."
@@ -419,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}"
    )
@@ -579,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.

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.
 

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

@@ -12,14 +12,14 @@ Display the complete DGS command reference. Output ONLY the reference content. D
 ## Quick Start
 
 **Single-project (v1):**
-1. `/dgs:new-project` - Create project (questioning + PROJECT.md)
+1. `/dgs:new-project [<name>]` - Create project (thin skeleton)
 2. `/dgs:new-milestone` - First milestone (research, requirements, roadmap)
 3. `/dgs:plan-phase 1` - Create detailed plan for first phase
 4. `/dgs:execute-phase 1` - Execute the phase
 
 **Multi-project / multi-repo (v2):**
 1. `/dgs:init-product` - Set up product folder and register repos
-2. `/dgs:new-project` - Create a project (questioning + PROJECT.md)
+2. `/dgs:new-project [<name>]` - Create a project (thin skeleton)
 3. `/dgs:new-milestone` - First milestone (research, requirements, roadmap)
 4. `/dgs:plan-phase 1` - Plan first phase (repos tracked per task)
 5. `/dgs:execute-phase 1` - Execute (commits per-repo automatically)
@@ -73,22 +73,20 @@ Usage: `/dgs:init-product`
 
 ### Project Initialization
 
-**`/dgs:new-project`**
-Initialize new project through deep questioning. *(Tier 2: planning)*
+**`/dgs:new-project [<name>]`**
+Initialize a new project as a thin skeleton. *(Tier 2: planning)*
 
-One command takes you from idea to project identity:
-- Deep questioning to understand what you're building
-- Optional brownfield mapping for existing codebases
-- PROJECT.md creation with vision, requirements hypotheses, and key decisions
+- Creates `projects/<slug>/PROJECT.md` with title + one-line placeholder
+- Optional brownfield codebase mapping offer for existing code
+- No deep questioning, no `--auto` flag
 
-Creates project artifacts:
-- `PROJECT.md` — vision and requirements
+Projects are holders. Vision and principles live in `docs/product/PRODUCT-SUMMARY.md`
+(loaded via Tier 1). Specs live at the milestone level.
 
-**v2 additions:** Prompts for project name (used as folder slug), prompts for which repos this project touches (from REPOS.md). Artifacts are created under `projects/<project-slug>/`.
+**Next:** `/dgs:write-spec` to capture what you're building, then
+`/dgs:new-milestone --auto <spec-id>` to start the first milestone.
 
-After completion, run `/dgs:new-milestone` to start your first milestone.
-
-Usage: `/dgs:new-project`
+Usage: `/dgs:new-project [<name>]`
 
 **`/dgs:map-codebase [<repo-name>]`**
 Map registered repos with parallel agents to produce structured codebase documentation. *(Tier 2: planning)*
@@ -406,7 +404,7 @@ Usage: `/dgs:check-todos api`
 
 ### Ideas & Specs
 
-`capture ideas → develop idea → write spec → new-project --auto → new-milestone --auto`
+`capture ideas → develop idea → write spec → new-project → new-milestone --auto`
 
 #### Ideas
 
@@ -658,6 +656,41 @@ Create phases to close gaps identified by audit. *(Tier 2: planning)*
 Usage: `/dgs:plan-milestone-gaps`
 Usage: `/dgs:plan-milestone-gaps --auto` (non-interactive gap closure)
 
+**`/dgs:diff-report [version|--quick slug] [--detailed]`**
+Generate a diff report (REVIEW.md) on demand. *(Tier 4: verification)*
+
+- Auto-detects context: active quick task or current milestone
+- Explicit target: version for milestones, `--quick slug` for quick tasks
+- `--detailed` flag invokes LLM-powered per-file analysis
+- Delegates to existing CLI commands (`jobs generate-review` / `quick generate-review`)
+
+Usage: `/dgs:diff-report`, `/dgs:diff-report v21.0`, `/dgs:diff-report --quick my-task --detailed`
+
+### Testing & Dependency Scanning
+
+**`/dgs:package-scan [flags]`**
+Scan every registered repo + product root for dependency vulnerabilities and licence issues. *(Tier 0: none — no STATE.md/ROADMAP.md auto-inject)*
+
+- **Tool cascade:** Snyk → OSV-Scanner → ecosystem-native (`npm audit`, `pip-audit`, `govulncheck`, `bundler-audit`)
+- **Ecosystems:** Node.js, Python, Go, Ruby, Java (Maven; Gradle treated as single-module, PKG-41 deferred)
+- **Monorepo-aware:** npm/pnpm/Yarn workspaces, Maven multi-module, Go workspaces
+- **Report placement:** active phase dir → active milestone dir → timestamped project-root file
+- **Findings in canonical shape** (forward-compatible with `/dgs:plan-test-gaps`)
+
+**Flags:**
+- `--threshold critical|high|medium|low` — filter by severity
+- `--repo <name>` — scan a single registered repo
+- `--json` — emit machine-readable JSON alongside the markdown report
+- `--include-dev-deps` / `--no-include-dev-deps` — toggle devDependencies scanning
+
+**Config keys:** `testing.packages.tool`, `testing.packages.severity_threshold`, `testing.packages.include_dev_dependencies`, `testing.packages.timeout_seconds` (all in `config.json`). `testing.packages.snyk_token` goes to `config.local.json` only.
+
+**Reference doc:** `~/.claude/deliver-great-systems/references/package-scan-config.md` — tool installation steps, Snyk-auth priority, report placement cascade.
+
+Usage: `/dgs:package-scan`
+Usage: `/dgs:package-scan --threshold high --repo api`
+Usage: `/dgs:package-scan --json` (pipe to jq, feed CI, etc.)
+
 ### Milestone Jobs
 
 | Command | What it does | When to use |
@@ -866,7 +899,7 @@ Example config:
 **Starting a new project (v1):**
 
 ```
-/dgs:new-project        # Questioning -> PROJECT.md
+/dgs:new-project        # Thin skeleton PROJECT.md
 /clear
 /dgs:new-milestone      # Research -> requirements -> roadmap
 /clear
@@ -879,7 +912,7 @@ Example config:
 
 ```
 /dgs:init-product       # One-time: register repos, create product structure
-/dgs:new-project        # Questioning -> PROJECT.md
+/dgs:new-project        # Thin skeleton PROJECT.md
 /clear
 /dgs:new-milestone      # Research -> requirements -> roadmap
 /clear
@@ -944,7 +977,7 @@ Example config:
 #   /dgs:research-idea              # Investigate feasibility
 /dgs:write-spec                     # Turn ideas into structured spec
 /clear
-/dgs:new-project --auto @spec.md    # Create project from spec
+/dgs:new-project <name>             # Create project holder
 /clear
 /dgs:new-milestone --auto <spec-id> # First milestone from spec
 ```