@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/CHANGELOG.md

@@ -8,6 +8,102 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.4] - 2026-04-07
+
+### Added
+- **Frontmatter status model (v20.0)** — Ideas, todos, and jobs now carry a `status` field in YAML frontmatter with validated constants (`IDEA_STATUSES`, `TODO_STATUSES`, `JOB_STATUSES`), round-trip integrity, and `set-status` CLI commands
+- **Flat-first scanning** — `findIdeaFile`, `findJobFile`, and list commands scan flat directories first using frontmatter status for filtering, with legacy subdirectory fallback and stderr migration warnings
+- **Flat status migration** — `dgs-tools migrate --layout flat` with `--dry-run` (default) and `--apply` modes; auto-detects legacy layout on CLI startup; flattens ideas/todos/jobs/research docs; validates file counts; produces atomic git commit; sets `flat_status_migration_done` config flag
+- **GATE test** — Grep-based test that fails if `git mv`, `renameSync`, or `unlinkSync` patterns appear in state transition code paths, permanently enforcing the no-file-move invariant
+
+### Changed
+- **State transitions rewritten** — All 9 directory-move operations (reject, restore, consolidate, undo-consolidate, complete-todo, cancel-job, move-job, specs-finalize) replaced with frontmatter `status` edits; files stay in flat directories
+- **New items created flat** — `cmdIdeasCreate`, `cmdCreateTodo`, and job creation write directly to `ideas/`, `todos/`, `jobs/` with `status` field in frontmatter
+- **Specs decoupled from ideas** — `cmdSpecsFinalize` calls `setIdeaStatus()` instead of 40+ lines of `git mv` logic; research doc moves removed
+- **13 workflow files updated** — write-spec, approve-spec, research-idea, develop-idea, discuss-idea, add-idea, consolidate-ideas, refine-spec, check-todos, create-milestone-job, cancel-job, help, resume-project all reference flat directories and frontmatter status
+- **approve-spec simplified** — Reads `source_ideas` from spec frontmatter and calls `ideas set-status done` for each source idea during approval; single atomic commit
+
+## [3.0.3] - 2026-04-06
+
+### Fixed
+- **v2 multi-project path resolution (7 bugs)** — `cmdMilestoneComplete`, `requirementsMarkCompleteInternal`, `getMilestonePhaseFilter`, `buildStateFrontmatter`, `cmdProgressRender`, `cmdHistoryDigest`, and `updateRepoStatus` now resolve ROADMAP.md, REQUIREMENTS.md, STATE.md, and phases/ from the project root instead of the planning root; backward-compatible for single-project setups
+- **Milestone jobs no longer auto-run `complete-milestone`** — `generateMilestoneSteps` now ends with `audit-milestone` as the final step; `complete-milestone` requires manual intervention (branch review, tag push, conflict resolution) and must be run after the job completes
+- **Ideas CLI error message** — `dgs-tools ideas` now lists available subcommands when an unknown one is used, matching all other dispatchers
+- **Duplicate `getMilestonePhaseFilter` in state.cjs** — removed duplicate function definition; now imports the canonical version from core.cjs
+
+## [3.0.2] - 2026-04-05
+
+### Added
+- **`phase finalize` CLI** — new `dgs-tools phase finalize <phase>` wraps `phase complete` + atomic commit of ROADMAP.md, STATE.md, REQUIREMENTS.md, and VERIFICATION.md in a single call; eliminates the skip-prone 2-step pattern in `execute-phase` workflow
+- **`plan finalize` CLI** — new `dgs-tools plan finalize <phase> <plan>` wraps state/roadmap/requirements updates + atomic commit of PLAN.md, SUMMARY.md, and tracking files in a single call; eliminates the 4-step pattern in `execute-plan` workflow
+- **W009 health check** — `/dgs:health` now detects uncommitted tracking files (ROADMAP.md, STATE.md, REQUIREMENTS.md, VERIFICATION.md) in completed phases and flags them
+- **phase.test.cjs** — new test suite (13 tests) covering finalize CLI atomic-commit behavior, commit message format, and graceful handling of missing files
+
+### Changed
+- **execute-phase workflow** — `update_roadmap` step collapsed from `phase complete` + separate commit into a single `phase finalize --push` call
+- **execute-plan workflow** — `update_state`/`update_roadmap`/`update_requirements`/`git_commit_metadata` 4-step chain collapsed into a single `finalize_plan` step
+
+## [3.0.1] - 2026-04-05
+
+### Added
+
+- **Product-level quick archival** — `state archive-quick-tasks` now dual-scans product + project STATE.md; new `listProjectsReadonly` helper in `bin/lib/projects.cjs` enumerates projects without mutation.
+- **`--repo-cwd` flag on `dgs-tools commit`** — allows commits to target a specific repo cwd, enabling context-aware commit routing.
+- **`--all` flag on `/dgs:progress`** — new cross-project product dashboard; adds `cmdInitProgressAll` returning product-wide JSON and `workflows/progress-all.md` workflow.
+
+### Changed
+
+- **Product-level routing for quick artifacts** — quick tasks and STATE tracking at product scope now route to the planning root rather than project subdirectories.
+- **`/dgs:fast` is now context-aware** — commits land in the active milestone worktree when milestone-context is active, otherwise on `base_branch` in the main checkout.
+- **Commands inherit session model** — reverted `model:` frontmatter from 55 command files so commands use the session's active model instead of pinning.
+
+### Fixed
+
+- **Slug trailing hyphens** — sanitizers in `quick.cjs`, `worktrees.cjs`, and `init.cjs` now strip trailing hyphens after length-capping.
+
+## [3.0.0] - 2026-03-31
+
+### Changed
+- **BREAKING: Git Worktrees replace branch-based isolation (v19.0)** — code repos now use worktrees for milestone and quick task isolation instead of git branches; `branching_strategy` config removed; `execute-phase` creates worktrees on demand; `complete-milestone` uses rebase-before-merge completion flow
+- **Quick workflows worktree-aware** — `/dgs:quick` detects worktree vs branch context; new `/dgs:quick-complete` (rebase-merge-cleanup) and `/dgs:quick-abandon` (discard worktree) commands
+- **Code context resolution** — new `resolveCodeContext()` replaces direct repo path lookups; all code-aware workflows wired through unified resolution
+- **Phase archival mandatory** — `complete-milestone` always archives phase directories (no interactive prompt); phases are in git history so no data loss
+
+### Added
+- **Worktree lifecycle module** (`worktrees.cjs`) — create, list, remove, clean operations with full test coverage
+- **REPOS.md setup column** — optional `setup` column for per-repo setup scripts; scripts receive worktree path as `$2`
+- **Branching config migration** — automatic migration from legacy `branching_strategy` config with detection and cleanup
+- **Worktree health checks** — `checkWorktreeHealth()` validates worktree state before operations
+- **Rebase-and-merge completion** — `rebaseAndMerge()` for clean worktree integration back to base branch
+- **Planning repo completion** — `markMilestoneComplete()` handles planning repo state during milestone completion
+- **Entry point wiring check** — planner agent now traces backwards from new features to existing navigation flows; plan-checker validates wiring tasks exist (Dimension 8)
+- **getMilestoneInfo project-scoped resolution** — tries project-scoped ROADMAP.md first, falls back to planning root; adds bullet-list format regex matching
+
+### Fixed
+- **getMilestoneInfo returning defaults** — was reading ROADMAP.md from planning root instead of project-scoped path, silently returning `v1.0`/`milestone` in v2 layouts
+- **Phase add milestone summary range** — adding a phase now correctly updates the milestone summary range in ROADMAP.md
+
+### Documentation
+- **GIT-WORKFLOW.md** — comprehensive guide for worktree-based development workflow
+- **USER-GUIDE.md** — quick workflows section, worktree troubleshooting, complete-milestone updates
+- **README.md** — updated for worktree features and mandatory phase archival
+- **Pluggable Checker Skills spec** (v1.4) — standard checker contract, four hook points, fix cycle, two-location discovery, findings persistence, sequential-by-priority execution
+- **Test-gate specs rewritten** — all four testing specs (test-gate, package-scan, security-scan, scenario-test) redesigned for pluggable test type architecture with convention-based discovery from `.claude/skills/dgs-tests/`
+
+## [2.9.0] - 2026-03-25
+
+### Changed
+- **new-project/new-milestone split** — `/dgs:new-project` now only handles questioning and PROJECT.md creation; all milestone-scoped work (research, requirements, roadmap, STATE.md) moves to `/dgs:new-milestone`, which now handles both first and subsequent milestones
+- **Codereview gate moved to orchestrator** — code review execution moved from `dgs-executor` (which lacks Task tool) to `execute-phase` orchestrator where Task spawning is available; skips in non-interactive/job mode with log message
+- **Map-codebase staleness gate** — in `--auto` mode (job runs), checks git history since last map; skips if no changes, narrows to single repo if only one changed; `--force` flag bypasses
+
+### Added
+- **Job file commit+push on status changes** — `run-job` now commits and pushes the job file after every step status update (in-progress, completed, failed, move operations), making job progress visible on remote in real time
+- **First-milestone guards in new-milestone** — handles missing MILESTONES.md/STATE.md gracefully with v1.0 default, phase-1 numbering, greenfield research framing, and STATE.md creation
+
+### Fixed
+- **Codereview silent failure in job mode** — codereview was silently skipped in job mode because the executor agent lacked Task/Agent tools needed to spawn the 9 review subagents
+
 ## [2.8.0] - 2026-03-25
 
 ### Changed

package/README.md

@@ -42,6 +42,9 @@ DGS extends GSD with:
 - **Product-level management** — multiple projects and repositories under one planning structure
 - **Ideas and specs pipeline** — capture ideas, develop them into formal PRDs, run cross-LLM review with OpenAI and Gemini before committing to a project
 - **Multi-repo orchestration** — plans reference repos by name, execution resolves paths at runtime, branches stay scoped per project
+- **Git worktree isolation** — milestone work runs in dedicated worktrees, keeping the main checkout clean. Three work modes: fast (direct to main), quick (ephemeral worktree), milestone (dedicated worktree). Zero branch management overhead.
+
+> **v19.0:** Worktree-based isolation replaces the old `branching_strategy` config. Existing configs are migrated automatically — no action needed.
 
 The complexity stays in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that produce consistent, verified results.
 
@@ -194,7 +197,7 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 
 DGS operates at the **product** level. A product contains one or more **projects**, each with its own milestones and phases. Ideas and specs live at the product level and feed into project or milestone creation.
 
-> **Already have code?** Run `/dgs:map-codebase` first. It spawns parallel agents per registered repo to analyze stack, architecture, structure, conventions, testing, integrations, and concerns. Per-repo maps are synthesized into unified top-level files. Then `/dgs:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns. Update a single repo after changes with `/dgs:map-codebase <repo-name>`.
+> **Already have code?** Run `/dgs:map-codebase` first. It spawns parallel agents per registered repo to analyze stack, architecture, structure, conventions, testing, integrations, and concerns. Per-repo maps are synthesized into unified top-level files. Then `/dgs:new-project` captures your project identity — goals, constraints, and scope. `/dgs:new-milestone` takes it from there with research, requirements, and roadmap. Update a single repo after changes with `/dgs:map-codebase <repo-name>`.
 
 ### 1. Set Up Product
 
@@ -236,18 +239,21 @@ If you have OpenAI or Gemini API keys configured, the spec goes through a **cros
 
 ```
 /dgs:new-project
+/dgs:new-milestone
 ```
 
-One command, one flow. The system:
+Two commands, one setup. First, `/dgs:new-project` asks questions until it understands your idea completely — goals, constraints, tech preferences, edge cases — then creates `PROJECT.md`.
 
-1. **Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
-2. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
-3. **Requirements** — Extracts what's v1, v2, and out of scope
-4. **Roadmap** — Creates phases mapped to requirements
+Then `/dgs:new-milestone` takes over:
+
+1. **Research** — Spawns parallel agents to investigate the domain (optional but recommended)
+2. **Requirements** — Extracts what's v1, v2, and out of scope
+3. **Roadmap** — Creates phases mapped to requirements
 
 You approve the roadmap. Now you're ready to build.
 
-**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+**`new-project` creates:** `PROJECT.md`
+**`new-milestone` creates:** `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `research/`
 
 ---
 
@@ -348,6 +354,28 @@ This is why "vertical slices" (Plan 01: User feature end-to-end) parallelize bet
 
 ---
 
+### Working with Worktrees
+
+Code repos are isolated using git worktrees. Each milestone gets its own directory — the main checkout stays clean for quick fixes.
+
+```
+# During milestone work, your repo layout looks like:
+~/dev/myapp/                     # main checkout (on main, always clean)
+~/dev/myapp--gsd-v19/            # milestone worktree (dedicated branch)
+```
+
+**Three work modes:**
+
+| Mode | Command | Branch Management |
+|------|---------|-------------------|
+| Fast | `dgs:fast` | Direct to main — no worktree, no branch |
+| Quick | `dgs:quick` | Ephemeral worktree — auto-cleanup on complete |
+| Milestone | `execute-phase` | Dedicated worktree — persists across phases |
+
+When a milestone or quick fix finishes, DGS rebases onto main and cleans up automatically. See [How Git is Used](docs/GIT-WORKFLOW.md) for the full model.
+
+---
+
 ### 7. Verify Work
 
 ```
@@ -393,7 +421,7 @@ When all phases are done, `/dgs:complete-milestone` archives the milestone and t
 
 **Automated alternative:** Instead of running each phase command manually, use `/dgs:create-milestone-job` to generate a build job and `/dgs:run-job` to execute the entire milestone pipeline automatically with subagent isolation per step. See the [User Guide](docs/USER-GUIDE.md#milestone-jobs) for details.
 
-Then `/dgs:new-milestone` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
+Then `/dgs:new-milestone` starts the next cycle. This is the same command used after `new-project` — it handles research, requirements, and roadmap for each version. You describe what you want to build next, it researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
 
 ---
 
@@ -460,7 +488,7 @@ DGS handles it for you:
 | `REQUIREMENTS.md` | Scoped v1/v2 requirements with phase traceability |
 | `ROADMAP.md` | Where you're going, what's done |
 | `STATE.md` | Decisions, blockers, position — memory across sessions |
-| `docs/product/` | Product-level documents (architecture, summary) — loaded as context by write-spec, plan-phase, new-project, new-milestone |
+| `docs/product/` | Product-level documents (architecture, summary) — loaded as context by write-spec, plan-phase, new-milestone |
 | `codebase/` | Per-repo maps + unified synthesis from `/dgs:map-codebase` |
 | `research/` | Ecosystem knowledge (stack, features, architecture, pitfalls) |
 | `PLAN.md` | Atomic task with XML structure, verification steps |
@@ -554,7 +582,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 
 | Command | What it does |
 |---------|--------------|
-| `/dgs:new-project [--auto]` | Full initialization: questions → research → requirements → roadmap |
+| `/dgs:new-project [--auto]` | Project identity: questioning → PROJECT.md |
 | `/dgs:discuss-phase [N] [--auto]` | Capture implementation decisions before planning |
 | `/dgs:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
 | `/dgs:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
@@ -562,7 +590,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 | `/dgs:audit-phase <phase> [--rerun-failed]` | Automated phase verification: test execution + structural inspection |
 | `/dgs:audit-milestone` | Verify milestone achieved its definition of done |
 | `/dgs:complete-milestone` | Archive milestone, tag release |
-| `/dgs:new-milestone [name]` | Start next version: questions → research → requirements → roadmap |
+| `/dgs:new-milestone [name]` | Start milestone: research → requirements → roadmap (first or subsequent) |
 
 ### Navigation
 
@@ -646,7 +674,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 | `/dgs:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
 | `/dgs:add-todo [desc]` | Capture idea for later |
 | `/dgs:check-todos [area]` | List pending todos, optionally filtered by area |
-| `/dgs:cleanup` | Archive accumulated phase directories |
+| `/dgs:cleanup` | Archive completed quick task directories |
 | `/dgs:debug [desc]` | Systematic debugging with persistent state |
 | `/dgs:fast <desc> [--dry-run]` | Trivial edit with single atomic commit — no subagents |
 | `/dgs:quick [--fast\|--full]` | Execute ad-hoc task with DGS guarantees (`--fast` skips subagents; `--full` adds plan-checking and verification) |
@@ -665,7 +693,7 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 
 ## Configuration
 
-DGS stores product-level settings in `.planning/config.json`. This file is shared across all projects in the product. Configure during `/dgs:init-product` or `/dgs:new-project`, and update later with `/dgs:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
+DGS stores product-level settings in `.planning/config.json`. This file is shared across all projects in the product. Configure during `/dgs:init-product`, and update later with `/dgs:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference).
 
 ### Core Settings
 

package/agents/dgs-plan-checker.md

@@ -314,7 +314,33 @@ issue:
   fix_hint: "Remove search task - belongs in future phase per user decision"
 ```
 
-## Dimension 8: Nyquist Compliance
+## Dimension 8: Entry Point Wiring
+
+**Question:** Do new pages, endpoints, or components have tasks that wire them into existing user flows?
+
+**Process:**
+1. Identify tasks that create new pages, routes, endpoints, or UI components
+2. For each, check whether another task updates existing navigation, redirects, links, or routes to reach the new feature
+3. If a new feature has no wiring task, flag it — the feature will be unreachable from existing flows
+
+**Red flags:**
+- New page created but no existing navigation/redirect updated to link to it
+- New endpoint added but no existing client code updated to call it
+- New component built but no existing page renders it
+
+**Example issue:**
+```yaml
+issue:
+  dimension: entry_point_wiring
+  severity: warning
+  description: "Task 2 creates onboarding page at /tenants/[id]/onboarding but no task updates the tenant creation flow to redirect there"
+  plan: "02"
+  task: 2
+  new_feature: "/tenants/[id]/onboarding"
+  fix_hint: "Add a task to update the existing tenant creation modal to redirect to the onboarding page after save"
+```
+
+## Dimension 9: Nyquist Compliance
 
 Skip if: `workflow.nyquist_validation` is explicitly set to `false` in config.json (absent key = enabled), phase has no RESEARCH.md, or RESEARCH.md has no "Validation Architecture" section. Output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
 
@@ -356,10 +382,10 @@ For each `<automated>MISSING</automated>` reference:
 - Wave 0 plan must execute before dependent task
 - Missing match → **BLOCKING FAIL**
 
-### Dimension 8 Output
+### Dimension 9 Output
 
 ```
-## Dimension 8: Nyquist Compliance
+## Dimension 9: Nyquist Compliance
 
 | Task | Plan | Wave | Automated Command | Status |
 |------|------|------|-------------------|--------|

package/agents/dgs-planner.md

@@ -1111,6 +1111,16 @@ For each task:
 Apply TDD detection heuristic. Apply user setup detection.
 </step>
 
+<step name="wiring_check">
+**Last-mile wiring check.** For each new page, endpoint, component, or feature created by a task:
+
+1. **Entry point analysis:** How does the user reach this today? Search (grep/glob) for existing navigation, redirects, links, or routes that currently handle the flow being extended. If nothing leads to the new feature, add a wiring task (e.g., update an existing modal redirect, add a nav link, wire a route).
+
+2. **Upstream flow scouting:** Include files that currently handle the flow being extended in the plan's `<context>` block — not just files being created. For UI features: identify existing pages, modals, or components that precede the new feature in the user journey.
+
+New features built without wiring into existing flows are unreachable. This check prevents "works in isolation, not connected" gaps.
+</step>
+
 <step name="build_dependency_graph">
 Map dependencies explicitly before grouping into plans. Record needs/creates/has_checkpoint for each task.
 

package/commands/dgs/abandon-quick.md

@@ -0,0 +1,28 @@
+---
+name: dgs:abandon-quick
+description: Abandon active quick task — remove worktree without merging
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Abandon the active product-level quick task.
+
+Remove the worktree directory and branch without merging any changes to main. All committed and uncommitted work in the worktree is discarded.
+
+Requires confirmation before proceeding. This action cannot be undone.
+</objective>
+
+<execution_context>
+@~/.claude/deliver-great-systems/workflows/abandon-quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the abandon-quick workflow from @~/.claude/deliver-great-systems/workflows/abandon-quick.md end-to-end.
+</process>

package/commands/dgs/add-tests.md

@@ -31,8 +31,8 @@ Output: Test files committed with message `test(phase-{N}): add unit and E2E tes
 <context>
 Phase: $ARGUMENTS
 
-@.planning/STATE.md
-@.planning/ROADMAP.md
+@${state_path}
+@${roadmap_path}
 </context>
 
 <process>

package/commands/dgs/audit-milestone.md

@@ -26,8 +26,8 @@ Version: $ARGUMENTS (optional — defaults to current milestone)
 Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
 
 **Completed Work:**
-Glob: .planning/phases/*/*-SUMMARY.md
-Glob: .planning/phases/*/*-VERIFICATION.md
+Glob: ${project_root}/phases/*/*-SUMMARY.md
+Glob: ${project_root}/phases/*/*-VERIFICATION.md
 </context>
 
 <process>

package/commands/dgs/capture-principle.md

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 
 <objective>
-Extract a design principle from the current conversation context (e.g., a debugging session, root cause analysis, or architectural discussion) and save it to `.planning/docs/product/DESIGN-PRINCIPLES.md`.
+Extract a design principle from the current conversation context (e.g., a debugging session, root cause analysis, or architectural discussion) and save it to `docs/product/DESIGN-PRINCIPLES.md` in the planning repo.
 
 Principles are product-level artifacts — actionable rules distilled from hard-won lessons. They are loaded automatically by any workflow that reads product docs (Planning, Execution, and Verification tiers), preventing the same mistakes from recurring.
 </objective>
@@ -19,27 +19,27 @@ Principles are product-level artifacts — actionable rules distilled from hard-
 <context>
 Arguments: $ARGUMENTS (optional seed text for the principle)
 
-State is resolved in-process via `state load` and git repo root detection.
+State is resolved via `init milestone-op` which provides planning-repo-relative paths.
 </context>
 
 <process>
 
 ## 1. Resolve Target Path
 
-Determine where `DESIGN-PRINCIPLES.md` lives:
+Resolve the planning repo root and product docs path:
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel)
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
 ```
 
-The target is always at `${REPO_ROOT}/.planning/docs/product/DESIGN-PRINCIPLES.md`.
+Extract `commit_docs` and `project_root` from the init JSON.
 
-Load state for commit_docs setting:
+Resolve the product docs directory:
 ```bash
-INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs state load)
+DOCS_DIR=$(node -e "const d = require('$HOME/.claude/deliver-great-systems/bin/lib/docs.cjs'); process.stdout.write(d.resolveDocsDir(process.cwd(), 'product'))")
 ```
 
-Extract `commit_docs` from the init JSON.
+The target is always at `${DOCS_DIR}/DESIGN-PRINCIPLES.md`.
 
 ## 2. Extract Principle from Context
 
@@ -71,7 +71,7 @@ If the user provides edits, incorporate them and re-present. If the user rejects
 
 ## 4. Read Existing DESIGN-PRINCIPLES.md
 
-Read `.planning/docs/product/DESIGN-PRINCIPLES.md` at the resolved path.
+Read `${DOCS_DIR}/DESIGN-PRINCIPLES.md`.
 
 If the file does **not** exist, create it with this template:
 
@@ -90,7 +90,7 @@ Actionable design rules distilled from project experience. Loaded automatically
 
 Also ensure the directory exists:
 ```bash
-mkdir -p "${REPO_ROOT}/.planning/docs/product"
+mkdir -p "${DOCS_DIR}"
 ```
 
 If the file exists, read and parse existing principles (look for `### ` headings under `## Principles`).
@@ -124,7 +124,7 @@ Use today's date for the `Added` field.
 
 If `commit_docs` is true:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --push --files .planning/docs/product/DESIGN-PRINCIPLES.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --push --files docs/product/DESIGN-PRINCIPLES.md
 ```
 
 If `commit_docs` is false, just save the file without committing.

package/commands/dgs/cleanup.md

@@ -3,9 +3,9 @@ name: dgs:cleanup
 description: Archive milestone phase directories and clean up completed quick task directories
 ---
 <objective>
-Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`, and remove planning directories for completed quick/fast tasks from `.planning/quick/`.
+Archive phase directories from completed milestones into `${project_root}/milestones/v{X.Y}-phases/`, and remove planning directories for completed quick/fast tasks from `${project_root}/quick/`.
 
-Use when `.planning/phases/` has accumulated directories from past milestones, or `.planning/quick/` has many completed task directories.
+Use when `${project_root}/phases/` has accumulated directories from past milestones, or `${project_root}/quick/` has many completed task directories.
 </objective>
 
 <execution_context>

package/commands/dgs/complete-milestone.md

@@ -25,10 +25,10 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 <context>
 **Project files:**
-- `.planning/ROADMAP.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-- `.planning/PROJECT.md`
+- `${roadmap_path}`
+- `${project_root}/REQUIREMENTS.md`
+- `${state_path}`
+- `${project_path}`
 
 **User input:**
 
@@ -41,7 +41,7 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 0. **Check for audit:**
 
-   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - Look for `${project_root}/v{{version}}-MILESTONE-AUDIT.md`
    - If missing or stale: recommend `/dgs:audit-milestone` first
    - If audit status is `gaps_found`: recommend `/dgs:plan-milestone-gaps` first
    - If audit status is `passed`: proceed to step 1
@@ -82,17 +82,17 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 4. **Archive milestone:**
 
-   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Create `${project_root}/milestones/v{{version}}-ROADMAP.md`
    - Extract full phase details from ROADMAP.md
    - Fill milestone-archive.md template
    - Update ROADMAP.md to one-line summary with link
 
 5. **Archive requirements:**
 
-   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Create `${project_root}/milestones/v{{version}}-REQUIREMENTS.md`
    - Mark all v1 requirements as complete (checkboxes checked)
    - Note requirement outcomes (validated, adjusted, dropped)
-   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+   - Delete `${project_root}/REQUIREMENTS.md` (fresh one created for next milestone)
 
 6. **Update PROJECT.md:**
 
@@ -114,9 +114,9 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 
 <success_criteria>
 
-- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
-- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
-- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- Milestone archived to `${project_root}/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `${project_root}/milestones/v{{version}}-REQUIREMENTS.md`
+- `${project_root}/REQUIREMENTS.md` deleted (fresh for next milestone)
 - ROADMAP.md collapsed to one-line entry
 - PROJECT.md updated with current state
 - Git tag v{{version}} created

package/commands/dgs/complete-quick.md

@@ -0,0 +1,28 @@
+---
+name: dgs:complete-quick
+description: Complete active quick task — rebase, merge to main, push, clean up worktree
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Complete the active product-level quick task.
+
+Rebase the quick branch onto the latest base_branch, fast-forward merge to main, push to remote, and remove the worktree directory and branch.
+
+Only valid for product-level quicks. Milestone-context quicks merge with the milestone via /dgs:complete-milestone.
+</objective>
+
+<execution_context>
+@~/.claude/deliver-great-systems/workflows/complete-quick.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the complete-quick workflow from @~/.claude/deliver-great-systems/workflows/complete-quick.md end-to-end.
+</process>

package/commands/dgs/create-milestone-job.md

@@ -14,7 +14,7 @@ Generate a milestone build job that plans and executes all remaining phases, wit
 
 Purpose: Reads the roadmap, determines which phases still need work, generates the step sequence, shows it for approval, and writes the job file on confirmation.
 
-Output: Job file at `.planning/jobs/pending/milestone-{version}.md` ready for `/dgs:run-job`.
+Output: Job file at `jobs/pending/milestone-{version}.md` ready for `/dgs:run-job`.
 </objective>
 
 <execution_context>
@@ -26,7 +26,7 @@ Arguments: $ARGUMENTS
 
 Flags:
 - `version` (optional): Milestone version (e.g., `v6`). Auto-detects from ROADMAP.md if omitted.
-- `--no-check`: Skip audit-milestone and complete-milestone steps in the generated job.
+- `--no-check`: Skip the audit-milestone step in the generated job.
 
 State is resolved in-workflow via `dgs-tools.cjs jobs milestone-preview` and `jobs create-milestone`.
 </context>

package/commands/dgs/debug.md

@@ -22,7 +22,7 @@ User's issue: $ARGUMENTS
 
 Check for active sessions:
 ```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
+ls ${project_root}/debug/*.md 2>/dev/null | grep -v resolved | head -5
 ```
 </context>
 
@@ -85,7 +85,7 @@ goal: find_and_fix
 </mode>
 
 <debug_file>
-Create: .planning/debug/{slug}.md
+Create: ${project_root}/debug/{slug}.md
 </debug_file>
 ```
 
@@ -130,7 +130,7 @@ Continue debugging {slug}. Evidence is in the debug file.
 
 <prior_state>
 <files_to_read>
-- .planning/debug/{slug}.md (Debug session state)
+- ${project_root}/debug/{slug}.md (Debug session state)
 </files_to_read>
 </prior_state>
 

package/commands/dgs/develop-idea.md

@@ -26,7 +26,7 @@ If discussion concludes that the idea is not viable, research is skipped entirel
 
 When re-running on an idea with prior history, the user is offered a choice: re-do both, just discuss, or just research.
 
-The output is a Discussion Log entry in the idea file, a research document at `.planning/docs/ideas/pending/{slug}-research.md`, and a Research Log entry in the idea file -- all committed at appropriate stages.
+The output is a Discussion Log entry in the idea file, a research document at `${project_root}/docs/ideas/pending/{slug}-research.md`, and a Research Log entry in the idea file -- all committed at appropriate stages.
 </objective>
 
 <execution_context>

package/commands/dgs/fast.md

@@ -1,7 +1,7 @@
 ---
 name: dgs:fast
 description: Make a trivial edit with a single atomic commit — no subagents, no ceremony
-argument-hint: "<description> [--dry-run]"
+argument-hint: "<description> [--dry-run] [--main]"
 allowed-tools:
   - Read
   - Write
@@ -20,6 +20,8 @@ Make a trivial edit and commit it atomically. Fast mode is the lightest DGS comm
 - Warns if scope exceeds 3 files or 30 lines (suggests /dgs:quick instead)
 
 **`--dry-run` flag:** Shows proposed changes as a diff, then asks "Apply these changes?" before committing.
+
+**`--main` flag:** Forces product-level mode even when a milestone is active. Commits to `base_branch` in the main checkout instead of the milestone worktree.
 </objective>
 
 <execution_context>

package/commands/dgs/health.md

@@ -9,7 +9,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <objective>
-Validate `.planning/` directory integrity and jobs directory structure. Reports actionable issues for both planning health and job management health.
+Validate planning directory integrity and jobs directory structure. Reports actionable issues for both planning health and job management health.
 </objective>
 
 <execution_context>