@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/CHANGELOG.md

@@ -8,6 +8,203 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-05-15
+
+### Added
+- **`/dgs:research-idea` now spawns a dedicated `dgs-idea-researcher` subagent** — the five research dimensions (web search, codebase analysis, landscape survey, approach identification, feasibility assessment) plus document write previously ran inline in the orchestrator. They now execute inside a dedicated subagent so (a) the `MODEL_PROFILES` entry takes effect (per-profile model selection: opus/sonnet/haiku for quality/balanced/budget), and (b) the orchestrator's context stays clean after research returns. New `agents/dgs-idea-researcher.md` (447 lines) mirrors `dgs-phase-researcher` structure. Workflow `research-idea.md` shrinks from 325 → 263 lines: 7 inline `<step>` blocks replaced with one `Task()` spawn. `commands/dgs/research-idea.md` gains `Task` in `allowed-tools`. `MODEL_PROFILES` table gains the `dgs-idea-researcher` row; 4 new tiering tests in `core.test.cjs`. Side fix: the workflow previously wrote research docs to `docs/ideas/{slug}-research.md` but the command file and `bin/lib/docs.cjs` used `docs/ideas/pending/{slug}-research.md` — workflow now consistent with both (quick-260515-dc5).
+
+## [3.2.3] - 2026-05-07
+
+### Fixed
+- **`detectQuickMode` no longer routes quicks via stale milestone entries** — `bin/lib/quick.cjs:detectQuickMode` previously returned `milestone-context` whenever `worktrees[active_context].type === 'milestone'`, even when the milestone's on-disk worktree had long been removed (e.g. by an interrupted `/dgs:complete-milestone` or partial `worktrees remove`). Result: subsequent product-level quicks were silently re-routed to `projects/<proj>/quick/` and updated the project STATE.md instead of the product-level one, with no UX surface to explain why. Now mirrors the stale-defence in `getActiveQuick`: a milestone entry only steers routing when at least one path in `entry.repos` exists on disk. Stale entries are NOT auto-cleared (milestone state is heavier than quick state and may carry context worth inspecting; users can run `dgs-tools worktrees remove <slug>`). Adds 3 regression tests to `quick.test.cjs` and widens 1 pre-existing test that incorrectly asserted milestone-context with `repos: {}` (quick-260507-pdp).
+
+## [3.2.2] - 2026-05-07
+
+### Fixed
+- **`startProductQuick` slug truncation mismatch** — fixed silent bug where descriptions producing a 40-char `descSlug` (total 51-char slug) caused `startProductQuick` to read back worktree state under the original slug while `cmdWorktreesCreate` had written it under a 50-char-truncated slug. Result: `repos = {}` was returned despite a successful worktree creation, the executor's `<worktree_context>` block was omitted, and code commits silently landed on the registered repo's `main` branch instead of the `quick/<slug>` worktree branch. `startProductQuick` now applies the same `slice(0, 50).replace(/-+$/, '')` truncation as `worktrees.cjs` and uses the canonical truncated slug for the execSync arg, the worktrees[] read-back, the `active_context` write, and the returned `slug` field. Adds regression test in `quick.test.cjs`. Affected long-description product-level quicks across multiple products (quick-260507-kq9).
+
+## [3.2.1] - 2026-04-28
+
+### Changed
+- **`/dgs:init-product` applies recommended defaults non-interactively** — Removes "Configure during init-product" prompts; init-product now applies sensible defaults that can be tweaked later via /dgs:settings (quick-260428-lak).
+- **`/dgs:new-project` is slug-aware** — `init new-project` now accepts a slug from `$ARGUMENTS` so the workflow can pass it through end-to-end (quick-260428-blx); adds multi-project end-to-end smoke test.
+- **Project discovery switched from STATE.md to PROJECT.md** — `/dgs:switch-project` and renderers now resolve the active project via PROJECT.md (quick-260428-d22).
+- **`/dgs:new-milestone` version selection consistent across modes** — Same prompts and defaults whether invoked interactively or via `--auto` (quick-260428-cq3).
+- **`/dgs:settings` no longer shows stale branching template prompts** — Removed dead prompts left behind by the milestone branching change (quick-260428-emk).
+- **F1.5 cross-repo guard narrowed** — quick-task pre-edit dirt check now only flags repos that actually intersect the planned change set, not all registered repos (quick-260427-aeb); adds regression test.
+
+### Fixed
+- **Quick task `task_dir` alignment** — `cmdInitQuick` now derives `descSlug` from `getActiveQuick().slug` so the task directory name matches the worktree slug (quick-260428-k7f); adds parity regression test.
+
+### Removed
+- **`/dgs:write-spec` "create new project from spec" routing option** — Removes a backwards routing path that conflicted with the project-first model.
+
+## [3.2.0] - 2026-04-26
+
+### Added
+- **Agent-Step Reliability milestone (v23.2)** — 15 reliability requirements (REL-01..REL-15) closed across 4 phases (155–158); see `specs/spec-agent-step-reliability.md`. Highlights below.
+- **Workflow conventions reference** — new `references/workflow-conventions.md` publishes the AGENT-13 must-commit contract (commands that scaffold files MUST return them, callers MUST commit them) plus a named-exit-code label registry consumed by every later phase (REL-13/14/15).
+- **Agent-step diagnostic reference** — new `references/agent-step-reliability.md` documents the named-exit-code patterns (`summary-frontmatter-mismatch`, `pre-existing-dirt`, `multi-repo-dirt`, `untracked-phase-artifacts`, `untracked-scaffolding`, `summary-frontmatter-empty-but-verified`) and is cross-linked from conflict-resolution, planner, and executor agents (REL-15).
+- **`scaffolded_files` contract proven end-to-end** — `cmdReposInitProduct` returns a `scaffolded_files` JSON array of `.gitkeep` paths; `init-product` workflow consumes via `jq` + word-split into `dgs-tools commit --files`; lint test asserts every scaffolding workflow follows the pattern (REL-09/13/14).
+- **`commit-verify-plan` CLI subcommand** — new `verifyPlanCommit` helper plus `dgs-tools commit-verify-plan` for orchestrator-side verification that planner-emitted PLAN.md files were actually committed; `dgs-planner` no longer commits its own output, instead emitting a machine-readable `### Created Files` block consumed by `plan-phase` Step 9.5 (REL-01).
+- **`compute-phase-sweep` CLI subcommand** — new `computePhaseSweep` helper plus `dgs-tools compute-phase-sweep` scoped to the current phase dir (NOT planning root) feeds the executor's final-commit `### Modified Files` contract (REL-02).
+- **`final-commit-precondition` CLI subcommand** — gates the executor `<final_commit>` step on canonical SUMMARY frontmatter, emitting `summary-frontmatter-mismatch` named exit when the writer-vs-reader keys diverge (REL-08).
+- **`bin/lib/summary-frontmatter.cjs` writer module** — single source of truth for the canonical `requirements_completed:` key; template, agent prompt, workflow, reader (`cmdSummaryExtract` dual-read for backward compat), and frontmatter schema all converge on it (REL-07).
+- **`bin/lib/audit-tolerance.cjs::applyMatrix`** — `audit-milestone` Section 5d matrix that resolves `summary-frontmatter-empty-but-verified` as distinct from real partial completions; new `--strict-audit` flag preserves the prior strict behaviour (REL-10).
+- **`/dgs:health` Check 10 — `untracked-phase-artifacts`** — walker flags PLAN/SUMMARY/CONTEXT/VERIFICATION artifacts left untracked under completed phase dirs (REL-11).
+- **`/dgs:health` Check 11 — `untracked-scaffolding`** — walker flags `.gitkeep`-style scaffolding files left untracked (REL-12).
+- **`bin/lib/fast-routing.cjs` helper module** — exports `surveyDirty`, `decideRouting`, `enumerateSubmodules`, `enumerateRegisteredRepos`; new `dgs-tools fast-route` CLI subcommand (REL-05/06).
+- **`workflows/quick.md` pre-edit dirt check + routing-aware commit** — F1.5-pre surveys repo state before edits, F5 emits `pre-existing-dirt` / `multi-repo-dirt` named exits when surroundings would taint the commit (REL-05/06).
+- **`agents/dgs-plan-checker.md` Dimension 10** — semantic plan-number validity check (catches `plan: 0`, `plan: 0a`, `plan: 1.5`); ships as soft-fail per Q4 baseline (REL-04).
+- **`tests/workflow-conventions.test.cjs`** — lints every workflow against the AGENT-13 contract with curated `SCAFFOLDING_CLI_PATTERNS` allow-list and a meta-test guarding the lint itself (REL-13/14).
+- **`tests/repos.test.cjs`** — coverage for REL-09 + REL-14 via the `createIsolatedTempProject` helper.
+- **Snyk OAuth detection** — `cmdPackageScan` now probes the configstore for OAuth-authenticated Snyk sessions in addition to API-token mode.
+- **`testing.packages.snyk_org` config key** — multi-org Snyk accounts can now pin scans to a specific organisation.
+- **Package/Dependency scanning (v23.1)** — `/dgs:package-scan` slash command that scans every registered repo plus the product root for known vulnerabilities and licence issues. Cascade: Snyk (if `testing.packages.snyk_token` set or `SNYK_TOKEN` env present) → OSV-Scanner (if `osv-scanner` on PATH) → ecosystem-native tools (`npm audit`, `pip-audit`, `govulncheck`, `bundler-audit`). Ecosystems: Node.js, Python, Go, Ruby, Java (Maven; Gradle treated as single-module).
+  - **Monorepo-aware scanning** — Detects npm/pnpm/Yarn workspaces, Maven multi-module layouts, and Go workspaces (`go.work`); emits one scannable target per workspace with `manifest_path` attribution through to findings (PKG-31).
+  - **Canonical finding contract** — Findings normalised to the test-gate plugin shape (`id`, `test_source`, `gap_type`, `severity`, `resource_id`, `repo`, `manifest_path`, `title`, `description`, `remediation`, `reference`, plus tool, CVE, CVSS, dependency chain). Forward-compatible with `/dgs:plan-test-gaps`.
+  - **Report generation** — Report placed under the active phase dir (`{phase}-PACKAGE-SCAN.md`), active milestone dir (`v{X}.{Y}-PACKAGE-SCAN.md`), or timestamped at the project root. YAML frontmatter carries severity counts + findings array; body renders per-repo × severity summary + per-severity sections.
+  - **CLI flags** — `--threshold critical|high|medium|low` (filter), `--repo <name>` (single-repo mode), `--json` (machine-readable output), `--include-dev-deps` / `--no-include-dev-deps` (toggle devDependencies).
+  - **Licence Compliance section** — Snyk-only licence enumeration with GPL/AGPL/SSPL flagging; non-Snyk scans emit a "licence scan incomplete — use Snyk" note.
+  - **Cross-repo deduplication and version overlap** — Report body presents a shared vulnerable package across repos once, and flags repos using different versions of the same package.
+  - **`.snyk` policy passthrough** — Snyk ignores/suppressions are honoured when `.snyk` is present in a repo.
+  - **Plan provenance (DGS-unique)** — Each finding optionally records `introduced_in_commit` (7-char SHA) and `introduced_in_plan` (DGS plan-id like `152-03`) via `git log -S <package> -- <manifest>` on the manifest file.
+  - **Skill file for test-gate discovery** — Inert `deliver-great-systems/skills/dgs-tests/package-scan.md` matches the test-gate plugin frontmatter so a future `skills.cjs` discovery engine consumes it unchanged.
+  - **Config keys** — `testing.packages.tool` (auto|snyk|osv|native), `testing.packages.severity_threshold`, `testing.packages.include_dev_dependencies`, `testing.packages.timeout_seconds` (validated in `config.cjs`); `testing.packages.snyk_token` routes to `config.local.json` only (gitignored).
+  - **Spec reference** — `specs/spec-package-dependency-scanning.md` v1.1 (final, approved 2026-04-17). See also `deliver-great-systems/references/package-scan-config.md` for the full config reference.
+- **Documentation surfaces gained Testing & Dependency Scanning sections** — COMMAND-REFERENCE, CONFIGURATION-GUIDE, USER-GUIDE, and the `help` workflow now document the v23.1 package-scan feature set.
+
+### Changed
+- **`dgs-planner` no longer commits its own output** — orchestrator owns the commit step; planner emits `### Created Files` and `plan-phase` Step 9.5 reads, commits, then verifies via `commit-verify-plan` (REL-01).
+- **`dgs-executor` final commit uses scoped phase-dir sweep** — replaces broad planning-root sweep so the very fix that closes idea #26 cannot reintroduce idea #27-class misrouting; consumes `### Modified Files` contract (REL-02).
+- **`templates/VALIDATION.md` heading renamed** — "Wave 0 Task Requirements" replaces the prior name; `agents/dgs-planner.md` carries the canonical Wave 0 / plan-numbering rules block (REL-03).
+- **`audit-milestone` partial-completion handling** — Section 5d matrix tolerates `summary-frontmatter-empty-but-verified` by default; opt back into strict mode with `--strict-audit` (REL-10).
+- **`/dgs:execute-phase` job-mode inline fallback** — `execute_waves` and `verify_phase_goal` now branch on `NON_INTERACTIVE` and follow `execute-plan.md` inline instead of spawning `dgs-executor` / `dgs-verifier` subagents via the Task tool. Eliminates false-FAILED reports when `run-job` nests Task contexts (idea #30, quick 260426-dz8).
+- **`/dgs:new-project` simplified to thin-skeleton flow** — questioning + minimal `PROJECT.md` only; product docs hoist into tiers and `PROJECT.md` checks relaxed; consumer workflows aligned with the thin-skeleton shape (idea #25/27, quick 260424-iji).
+
+### Fixed
+- **Licence-section message when Snyk returns no licence findings** — corrected from a misleading absence-of-data string to an explicit "no licence findings" line.
+- **Package-scan milestone report path** — resolves from the worktree's `milestone_version` field; supporting fix adds `milestone_version` to milestone worktree entries so the report lands in the correct milestone dir.
+- **OpenAI spec-review payload** — `temperature` param dropped because gpt-5 rejects it.
+
+## [3.1.2] - 2026-04-14
+
+### Fixed
+- **plan-phase auto-discovers source spec** — When no CONTEXT.md exists and no `--prd` flag is passed, plan-phase now checks PROJECT.md for a `**Source Spec:**` reference and auto-generates CONTEXT.md via the PRD Express Path. Closes the gap where spec-driven milestones (created via `new-milestone --auto`) lost their spec context during job execution because `run-job` doesn't pass `--prd` to plan-phase steps.
+
+## [3.1.1] - 2026-04-14
+
+### Fixed
+- **Codereview gate running git log in wrong repo** — `execute-phase.md` step 5 now derives `CODE_REPO_PATH` from `$WORKTREE_REPOS` and runs the `FIRST_TASK_COMMIT` git log via `git -C "${CODE_REPO_PATH}"` against the code repo instead of the planning repo. Passes `CODE_REPO_PATH` as a new input to the spawned codereview subagent. `codereview.md` routes all `git log`, `git diff`, `git diff --name-only`, `git add`, and `git commit` through `git -C "${CODE_REPO_PATH}"`. Prevents cross-repo staging of `CODEREVIEW.md` in the auto-fix commit. No CODEREVIEW.md files had been produced since v18.0 (Mar 25) due to this bug.
+- **Quick finalize missing numbered artifact files** — `cmdQuickFinalize` now uses a regex-based directory sweep (`fs.readdirSync` + pattern match) instead of a hardcoded candidate list to stage quick task artifacts. Both flat (`{quickId}-SUMMARY.md`) and numbered (`{quickId}-01-SUMMARY.md`) naming conventions are now picked up. Sweeps PLAN, SUMMARY, CONTEXT, VERIFICATION, CODEREVIEW, DEBUG-LOG, and RESEARCH artifacts. Includes 2 regression tests.
+- **Planner quick-mode SUMMARY naming** — `dgs-planner.md` output template now documents the flat quick-mode form (`{quickId}-SUMMARY.md`) so planners stop instructing executors to write the numbered phase-style form for quick tasks
+
+## [3.1.0] - 2026-04-09
+
+### Added
+- **Milestone diff report (v22.0)** — New `review.cjs` module with `generateDiffReport()` that auto-generates structured REVIEW.md at milestone and quick task completion gates
+- **REVIEW.md template** — Six-section template: Goal, What Was Built, Code Changes (per-repo), Verification, Risk Flags, Overall; quick-scan stats banner at top
+- **Per-file detail** — Files grouped into New/Modified/Deleted/Moved categories with line counts (`+45 -12`); git rename detection via `-M` flag; config file subsection with per-file risk annotations
+- **Risk detection engine** — Four auto-detected risk categories: large changes (>100 lines), dependency changes (new/updated/removed with version ranges), tech debt indicators (TODO/FIXME/HACK on new lines, test file deletions), UAT items marked human_needed
+- **Detailed mode (`--detailed`)** — LLM subagent reads diff hunks and produces per-file analysis (what + why) and cross-repo narrative; batched per repo; graceful fallback to default mode on failure or context overflow
+- **Aggregate statistics** — Cross-repo summary section for multi-repo reports with per-repo breakdown table; single-repo reports skip redundant aggregate
+- **Minor file collapse** — Repos with >50 changed files collapse files with <5 lines into a summary line; config files and risk-flagged files never collapsed
+- **CLI commands** — `dgs-tools jobs generate-review [version]` for milestones; `dgs-tools quick generate-review [slug]` for quick tasks; both support `--detailed` and `--raw`
+- **`/dgs:diff-report` command** — Standalone on-demand report generation with context-aware auto-detection (quick task priority, milestone fallback), explicit targeting, and `--detailed` passthrough
+- **Workflow integration** — Review generation as final step of `audit-milestone`; inline generation in `complete-quick` before rebase-and-merge; fast-forward detection for zero-change quick tasks; `complete-milestone` warns if REVIEW.md missing
+- **Four-eyes completion governance (v21.0)** — Contributor detection from PLAN.md/SUMMARY.md metadata, configurable enforcement (off/warn/enforce), completion gates in complete-milestone and quick-complete with --force bypass and audit logging
+- **Workflow discipline enforcement hook** — PreToolUse hook on Edit/Write denies calls unless a `/dgs:*` command is active; marker file tracks active command per session; only enforces in DGS planning folders (checks `config.json` `product_name`); memory paths allowlisted
+- **Four-eyes setting in `/dgs:settings`** — New `workflow.four_eyes` toggle (off/warn/enforce) exposed in settings workflow; `config-set` supports the key; branching strategy removed from settings (hardcoded to milestone)
+- **Cross-LLM review in `/dgs:import-spec`** — Imported specs now go through the same parallel OpenAI/Gemini review loop as `/dgs:write-spec`; review runs in-memory before user presentation; review history persisted on save
+
+### Fixed
+- **Project completion guard** — `markMilestoneComplete` sets status to `milestone_shipped` instead of `complete`; `buildStateFrontmatter` uses exact match for `completed` status instead of `includes('complete')` which falsely triggered on "Phase X execution complete"
+- **`reactivateProject` commits PROJECTS.md** — Reactivation now commits both STATE.md and PROJECTS.md so the change persists
+- **Quick workflow `task_dir`** — Step 4 and `--quick-dir` arguments now use `task_dir`/`quick_dir` from init output instead of manually building paths from `project_root`
+- **CLAUDE.md Section 6** — New "Completion Gates" section in template: Claude must stop and report at gates (`quick-complete`, `complete-milestone`, `--force`), never auto-bypass
+
+## [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

package/README.md

@@ -42,6 +42,10 @@ 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.
+- **Four-eyes completion governance** — configurable check ensuring the person completing a milestone or quick task is different from the contributors. Off by default; `warn` mode logs, `enforce` mode blocks. See the [Multi-User Guide](docs/MULTI_USER_APPROACH_GUIDE.md#completion-governance-four-eyes) for setup.
+
+> **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.
 
@@ -351,6 +355,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
 
 ```
@@ -581,6 +607,12 @@ See the [User Guide](docs/USER-GUIDE.md#context-tiers) for the complete command-
 |---------|--------------|
 | `/dgs:map-codebase [<repo-name>]` | Map registered repos, synthesize unified codebase docs |
 
+### Testing & Dependency Scanning
+
+| Command | What it does |
+|---------|--------------|
+| `/dgs:package-scan [--threshold critical\|high\|medium\|low] [--repo <name>] [--json] [--include-dev-deps\|--no-include-dev-deps]` | Scan every registered repo + product root for known dependency vulnerabilities and licence issues. Cascades Snyk → OSV-Scanner → ecosystem-native tool (`npm audit`, `pip-audit`, `govulncheck`, `bundler-audit`). Report is committed to the active phase dir, active milestone dir, or a timestamped project-root file. See `deliver-great-systems/references/package-scan-config.md` for config keys and installation. |
+
 ### Phase Management
 
 | Command | What it does |
@@ -649,7 +681,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) |
@@ -668,7 +700,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`, 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. Recommended defaults are applied automatically by `/dgs:init-product`. Update any setting 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-executor.md

@@ -24,6 +24,8 @@ Your job: Execute the plan completely, commit each task, create SUMMARY.md, upda
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
+Reliability contract: see `references/agent-step-reliability.md` for the silent-skip diagnostic pattern, rejected anti-features, and the fail-loudly contract this agent's commit/output steps must satisfy.
 </role>
 
 <project_context>
@@ -370,6 +372,28 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 ```
 
 **5. Record hash:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY.
+
+**6. Post-commit dirty sweep:** After the task commit lands, run `git status --porcelain` in every gitCwd the task touched (resolve via `<repos>` + REPOS.md per `<file_path_resolution>` above — call `resolveRepoRelativePath(cwd, repoName, '.', repos).repoAbsPath` once per distinct repoName; default to the planning root when no `<repos>` tag). The `dirty_after` field on the commit JSON result from `dgs-tools.cjs commit` already surfaces this list for the repo the commit ran in — use it directly to avoid a redundant porcelain call.
+
+For each dirty path, classify:
+
+- **SWEEP** (`*.tfvars`/`*.tf` fmt reflows, pure-whitespace diffs 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`/`let`/`var`/`if`/`for`/`return`/`await`/`async`/`import`/`export`/`class`/`function`): stage it and create a follow-up commit `chore({phase}-{plan}-reflow): verify-step side effects` with one bullet per file describing its category. Log under a "Post-verify reflows" section in SUMMARY.md (task number, commit hash, files).
+
+  **SWEEP example** (narrowing `User | null` → `User` in an existing annotation — only the type annotation changed, statement structure is identical):
+  ```diff
+  -  const currentUser: User | null = getUser();
+  +  const currentUser: User = getUser();
+  ```
+
+  **FAIL example** (adding `await` is a statement-structure change, not a type narrowing):
+  ```diff
+  -  const x = fetchUser();
+  +  const x = await fetchUser();
+  ```
+
+- **FAIL** (added/removed statements, new imports, new function bodies, or any logic change in a file NOT in the plan's `files_modified` frontmatter): halt the task. Record under "Deferred Issues" in SUMMARY.md with a `git diff` excerpt (first 20 lines) and which rule fired. Treat as a Rule 3 blocking issue and auto-fix per the existing deviation-rules process (fix attempt limit applies — after 3 attempts, document and continue).
+
+Default to SWEEP. False negatives lose work (the field-copilot incident left formatter reflows uncommitted for days); false positives cost one follow-up commit.
 </task_commit_protocol>
 
 <post_task_type_check>
@@ -407,7 +431,9 @@ After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `${phase_dir}/`.
 
 **Use template:** @~/.claude/deliver-great-systems/templates/summary.md
 
-**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date).
+**Frontmatter:** phase, plan, subsystem, tags, dependency graph (requires/provides/affects), tech-stack (added/patterns), key-files (created/modified), decisions, metrics (duration, completed date), `requirements_completed`.
+
+**`requirements_completed` (REL-07, canonical key — underscore):** MUST be populated by reading the PLAN.md frontmatter `requirements:` field and copying the values VERBATIM. The pre-commit precondition (REL-08) will abort the executor with `summary-frontmatter-mismatch` if PLAN `requirements:` is non-empty and SUMMARY `requirements_completed:` is empty. The executor MUST NEVER use the legacy hyphen variant for new SUMMARYs — that variant is only read by `cmdSummaryExtract` for backwards-compat with archived v23.1 SUMMARYs.
 
 If `author` is provided in the execution context (from orchestrator `<author>` tag or init JSON), include `executed_by: {author}` in SUMMARY.md frontmatter after the `completed` field.
 
@@ -510,11 +536,81 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" state add-blocker "
 </state_updates>
 
 <final_commit>
+**0. PRE-commit precondition (REL-08).** BEFORE staging anything, run the precondition gate:
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" final-commit-precondition \
+  --plan ${plan_path} \
+  --summary ${summary_path}
+```
+
+If exit code is non-zero AND stderr contains `summary-frontmatter-mismatch`: HALT immediately. Do NOT proceed to step 1 (pre-commit phase-dir sweep). Surface the stderr to the orchestrator. The working tree must be unchanged from when this step started — the precondition only reads files; if you've already modified files in earlier `<task_commit_protocol>` runs, those modifications stay. Do NOT attempt to "fix" the SUMMARY by editing it here — abort and let the orchestrator re-spawn the executor with corrected state.
+
+**Why this gate exists (REL-08, idea #28):** Before this gate, the executor sometimes wrote a SUMMARY with empty `requirements_completed` despite PLAN declaring requirements (Phase 150 in v23.1, all 3 plans). The audit cross-reference then produced 12 false-positive `partial` entries. The gate makes the failure mode loud BEFORE any commit lands, per the fail-loudly contract.
+
+**1. Pre-commit phase-dir sweep (REL-02).** Always sweep the current
+phase directory regardless of `files_modified` content — but scope the
+sweep, never blindly. Invoke the orchestrator helper:
+
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files ${phase_dir}/{phase}-{plan}-SUMMARY.md ${state_path} ${roadmap_path} ${requirements_path}
+SWEEP_JSON=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" \
+  compute-phase-sweep \
+  --phases-dir "${phases_dir}" \
+  --phase-dir "${phase_dir}" \
+  --modified-files "${modified_files[@]}" \
+  --raw)
+SWEEP_FILES=( $(echo "$SWEEP_JSON" | jq -r '.swept[]') )
+DROPPED=( $(echo "$SWEEP_JSON" | jq -r '.dropped[]') )
 ```
 
-Separate from per-task commits — captures execution results only.
+The helper takes the UNION of (a) `git status --porcelain` paths under
+`${phases_dir}/${phase_dir}` and (b) the executor-reported
+`modified_files` list, then filters to the phase-dir scope only. Paths
+outside the scope (sibling phases, `ideas/`, `specs/`, project root)
+are dropped — they MUST NOT enter the commit. If any path was dropped,
+log it under "Post-verify reflows" → "Dropped (out-of-scope)" with the
+path and a note that REL-02 enforces the scope guarantee.
+
+Note: this scope is for the planning-root phase dir. Cross-repo sweeps
+for sub-repos remain unchanged (multi-repo `files_modified` entries
+with `repoName:` prefix route through `resolveRepoRelativePath` as
+before; the helper drops them from the planning-root sweep
+automatically).
+
+For multi-repo plans, after the planning-root phase-dir sweep above,
+also iterate the distinct repoName values from the plan's
+`files_modified` frontmatter and run `git status --porcelain` in each
+sibling repo's gitCwd (resolved via `resolveRepoRelativePath(cwd,
+repoName, '.', repos).repoAbsPath`) to capture any reflows under
+sibling repos. Append those paths (with the appropriate repoName:
+prefix) to the list you are about to pass to `--files`.
+
+**2. SUMMARY logging.** If any dirty paths were discovered in step 1, append a section to SUMMARY.md:
+
+```markdown
+## Post-verify reflows
+
+These files were rewritten by verify-step tooling (formatters, type checkers) after their owning task committed and were swept into the final metadata commit:
+
+| File | Repo | Category |
+|------|------|----------|
+| terraform/env.tfvars | infra | fmt reflow |
+| src/patch-lock.test.ts | app | ts narrowing |
+```
+
+Classify each path using the same SWEEP heuristic as step 6 of `<task_commit_protocol>`. If any path hits the FAIL category (added statements / new imports / logic change in an out-of-scope file), STOP: do not finalize. Record it under "Deferred Issues" in SUMMARY.md with a `git diff` excerpt and treat as a blocking issue per the existing deviation-rules fix-attempt-limit policy. Reaching the final commit with FAIL-category dirt is itself a bug — the per-task sweep should have caught it — so surfacing it loudly is the point of the safety net.
+
+**3. Commit.**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" \
+  --files ${phase_dir}/{phase}-{plan}-SUMMARY.md ${state_path} ${roadmap_path} ${requirements_path} \
+  ${SWEEP_FILES[@]}
+```
+
+Inspect the JSON return — `dirty_after` should be `[]` after this commit. If it is non-empty, something reflowed AFTER the porcelain check (rare but possible with editor autosave or long-running watchers); log it under "Post-verify reflows" and create one more `chore({phase}-{plan}-reflow): trailing side effects` commit to clean up.
+
+Separate from per-task commits — captures execution results AND any reflow artifacts the per-task sweep missed.
 </final_commit>
 <completion_format>
 ```markdown
@@ -529,8 +625,33 @@ Separate from per-task commits — captures execution results only.
 - {hash}: {message}
 
 **Duration:** {time}
+
+### Modified Files
+
+- projects/gsd/phases/{phase_dir}/{phase}-{plan}-SUMMARY.md
+- <other files this plan touched>
 ```
 
+## Co-requirement: modified_files in plan-completion output (REL-02)
+
+The `## PLAN COMPLETE` block above MUST include a machine-readable
+`### Modified Files` bullet list of every file the plan touched,
+parallel to the `dgs-planner` agent's `### Created Files` (REL-01).
+Format: a markdown bullet list under a `### Modified Files` heading,
+one path per line, planning-root-relative (for planning-root files) or
+`repoName:path` (for sibling-repo files).
+
+Entries: the same paths that appear in the plan's `files_modified:`
+frontmatter PLUS any additional files this execution touched (e.g.,
+post-verify reflow files surfaced by sweep step 1, deviation-fix
+files added under deviation rules 1–3, dependency manifests touched
+by Rule-3 blocking fixes).
+
+The orchestrator (and any future cross-cutting verifier) consumes this
+list as the source-of-truth complement to git-discovered paths in
+`compute-phase-sweep`. Together, the helper and the contract make
+under-reporting and over-reporting both detectable.
+
 Include ALL commits (previous + new if continuation agent).
 </completion_format>