@ktpartners/dgs-platform 3.0.4 → 3.3.0

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
 ```

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

@@ -201,6 +201,60 @@ This is the core AI conversion step. Restructure `SOURCE_CONTENT` into a 9-secti
 Store the full converted PRD as `CONVERTED_PRD`.
 </step>
 
+<step name="run_cross_llm_review">
+Run cross-LLM review on the converted PRD before presenting to the user. This matches the review pattern from write-spec.
+
+Load the review loop reference for detailed API call mechanics:
+@~/.claude/deliver-great-systems/references/spec-review-loop.md
+
+**1. Load review config:**
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs review-config
+```
+
+Parse JSON result. If `has_any_key = false`: warn "No review API keys configured. Edit review-keys.json in your planning root to add OpenAI or Gemini keys. Skipping review." and proceed directly to `present_and_review`.
+
+**2. Initialize tracking:**
+
+- `round = 0`
+- `total_tokens = { openai: { prompt: 0, completion: 0 }, gemini: { prompt: 0, completion: 0 } }`
+- `rejected_items_history = []`
+- `REVIEW_HISTORY = ""`
+
+**3. Loop** (while round < max_rounds):
+
+   a. Increment round.
+   b. Send `CONVERTED_PRD` to available reviewers in parallel using the API call patterns from the reference doc. Issue both curl commands via parallel Bash tool calls.
+   c. Handle failures per reference doc error handling rules (retry once, then mark failed).
+   d. Parse feedback items from each reviewer's response. Each item: section, severity, feedback text, reviewer name.
+   e. **Auto-reject Non-Goal contradictions:** read the `## Non-Goals` section of `CONVERTED_PRD`, reject any feedback that suggests adding something explicitly listed as a Non-Goal. Disposition: `rejected-non-goal`.
+   f. **Check convergence:** compare rejected items against `rejected_items_history`. If an item (or substantially similar item) was rejected in the previous round too, move the concern to `## Open Questions` tagged as "From review: [concern]". Disposition: `moved-to-open-questions`.
+   g. **Apply accepted feedback:** Claude reads each remaining item and decides whether to apply it by modifying `CONVERTED_PRD`. Disposition: `accepted` (with change description) or `no-action` (with reason).
+   h. Build round history entry with all dispositions in the review history table format.
+   i. Append round history to `REVIEW_HISTORY` string.
+   j. Update token totals from response usage metadata.
+   k. **Check exit conditions:**
+      - No changes applied (all items rejected, no-action, or moved-to-open-questions) -> EXIT
+      - Green-only (all reviewers responded "LGTM" or no actionable feedback) -> EXIT
+      - Max rounds reached -> EXIT
+   If none met: continue to next round.
+
+**4. Display token/cost summary:**
+
+```
+Review complete (N rounds).
+Tokens: OpenAI [X prompt + Y completion] | Gemini [X prompt + Y completion]
+Estimated cost: ~$X.XX
+```
+
+**5. Append review history to CONVERTED_PRD:**
+
+If `REVIEW_HISTORY` is non-empty, append it to `CONVERTED_PRD` as a `## Review History` section at the end. This ensures the review history is included when the spec is saved.
+
+**Note:** Unlike write-spec, there is no spec file on disk yet. The review operates entirely on the in-memory `CONVERTED_PRD` string. The review history is appended to the content and persisted when the user chooses "save" in the next step.
+</step>
+
 <step name="present_and_review">
 Present the converted PRD for user review and handle the review loop.
 
@@ -217,7 +271,7 @@ Present the converted PRD for user review and handle the review loop.
 {CONVERTED_PRD}
 
 ---
-Original: will be saved to ${project_root}/{attachment_path}
+Original: will be saved to {attachment_path} (relative to planning root)
 {If IDEA_IDS is non-empty: "Linking to: " followed by comma-separated IDEA_DISPLAY entries, e.g., "Linking to: IDEA-1 (Phase 0 Foundation Infrastructure), IDEA-3 (Other Idea)"}
 
 **Review options:**
@@ -233,7 +287,7 @@ Original: will be saved to ${project_root}/{attachment_path}
 
 **If "save":**
 1. Generate the slug from `SPEC_TITLE` (lowercase, replace non-alphanumeric with hyphens, trim leading/trailing hyphens).
-2. Check if `${project_root}/specs/spec-{slug}.md` already exists. If it does, use AskUserQuestion to prompt: `A spec with slug '{slug}' already exists. Enter a new title:` -- then regenerate the slug from the new title and re-check. Loop until no conflict.
+2. Check if `specs/spec-{slug}.md` (relative to planning root) already exists. If it does, use AskUserQuestion to prompt: `A spec with slug '{slug}' already exists. Enter a new title:` -- then regenerate the slug from the new title and re-check. Loop until no conflict.
 3. Compute the slugified source filename: take `SOURCE_FILENAME`, lowercase it, replace non-alphanumeric chars (except dots) with hyphens, trim leading/trailing hyphens, preserve file extension. This matches `docs.slugifyFilename()` behaviour.
 4. Compute the attachment path: `specs/spec-{slug}/docs/{slugified-source-filename}` (relative to the planning root).
 5. Call specs create (with --source-ideas when ideas are linked):
@@ -264,7 +318,7 @@ Original: will be saved to ${project_root}/{attachment_path}
 
    **Execute the commit:**
    ```bash
-   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --push --files ${project_root}/specs/spec-{slug}.md ${project_root}/{attachment_path} ${project_root}/specs/spec-{slug}/docs/INDEX.md ${project_root}/specs/spec-{slug}/docs/.names.json
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --push --files specs/spec-{slug}.md {attachment_path} specs/spec-{slug}/docs/INDEX.md specs/spec-{slug}/docs/.names.json
    ```
    The `dgs-tools.cjs commit` helper with `--files` stages only the specified files and commits them. This ensures other unstaged/uncommitted changes in the working tree are not included. The `.names.json` file is included because `docs add` creates it as internal metadata for INDEX rebuilds.
 
@@ -283,8 +337,8 @@ Original: will be saved to ${project_root}/{attachment_path}
      ID: {id}
      Title: {SPEC_TITLE}
      Status: draft
-     File: ${project_root}/{filename path from specs create result}
-     Source: ${project_root}/{attachment_path}
+     File: {filename path from specs create result} (relative to planning root)
+     Source: {attachment_path} (relative to planning root)
      Committed: specs: import {id} - {title} (from {original-filename})
      {If IDEA_IDS is non-empty: "Linked ideas: IDEA-1, IDEA-3 (unchanged state)"}
 
@@ -298,8 +352,8 @@ Original: will be saved to ${project_root}/{attachment_path}
      ID: {id}
      Title: {SPEC_TITLE}
      Status: draft
-     File: ${project_root}/{filename path from specs create result}
-     Source: ${project_root}/{attachment_path}
+     File: {filename path from specs create result} (relative to planning root)
+     Source: {attachment_path} (relative to planning root)
      {If IDEA_IDS is non-empty: "Linked ideas: IDEA-1, IDEA-3 (unchanged state)"}
 
    Next steps:
@@ -360,6 +414,10 @@ Stop execution.
 - [ ] Requirements use explicit language signal mapping (must/critical -> P0, should/important -> P1, could/nice-to-have -> P2) with P1 default
 - [ ] Requirements preserve original identifiers if numbered in source
 - [ ] Implementation Notes reference real files and patterns when codebase context available
+- [ ] Cross-LLM review runs after conversion (when review keys configured)
+- [ ] Review feedback applied to CONVERTED_PRD in-memory before user presentation
+- [ ] Review history appended to spec content and persisted on save
+- [ ] Missing review keys skip review with warning (non-blocking)
 - [ ] Spec title is auto-generated from source content
 - [ ] Full converted PRD is displayed for review with attachment path shown
 - [ ] Linked ideas displayed in review when --ideas provided