@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/references/agent-step-reliability.md

@@ -0,0 +1,60 @@
+# Agent-Step Reliability
+
+Reference for the silent-skip diagnostic pattern and the canonical fail-loudly contract that DGS workflows and agents in milestone v23.2 ("Agent-Step Reliability") and beyond must satisfy.
+
+## The silent-skip diagnostic pattern
+
+A workflow or agent step that should commit something — or copy a value from an upstream source — silently doesn't. Five concrete instances surfaced during v23.1 (ideas #25-#29 in `projects/gsd/ideas/done/`).
+
+Symptoms: the step's caller logs success; the user discovers the gap later via `git status`, audit reports, or noticing a fresh clone is missing files. Because the operation appears to have succeeded, no remediation message reaches the user at the moment the failure occurs — only at debug time, possibly milestones later.
+
+Family signature: any "must happen" side-effect step where the agent or workflow has shell access but the success of the side-effect is **not verified in the same control-flow scope**. The classic instance is a `commit --files <list>` invocation whose `<list>` was not derived from the prior scaffold step's actual writes — so the commit "succeeds" while the scaffolded files remain untracked. The same shape applies to copy-from-upstream steps (e.g., a SUMMARY writer that fails to copy the PLAN's `requirements` array into `requirements_completed`).
+
+The silent-skip label refers to the silent absence of a side-effect that the surrounding workflow assumed had happened. Recognising the family signature is the first defence against re-introducing it in new workflows.
+
+## Rejected anti-features (with rationale)
+
+The following four solutions were considered during the v23.2 spec rounds and explicitly rejected. They are documented here so future contributors do not propose them again without reading the rationale.
+
+- **File locking / concurrent-orchestrator handling.** DGS is single-user, single-shell. No parallel orchestrators ever run on the same phase directory. Adding lock files, advisory locks, or coordination primitives would solve a problem we do not have, at the cost of new failure modes (stale locks after crashes, lock-contention spurious failures). (Source: spec round 3 disposition #3.)
+- **Generic agent-output verification framework.** Out of scope for this milestone — would be a much larger investment (declarative output schemas, schema registry, runtime validators, error-mapping infrastructure). Targeted per-step assertions only: each known offender gets a precise post-condition check at the exact place its silent-skip manifested. The targeted approach matches actual recurrence patterns and keeps the feature surface small. (Source: spec Non-Goals.)
+- **Database-backed state model.** State remains Markdown-in-Git per `codebase/ARCHITECTURE.md` ("State is always Markdown-in-Git. No database, no long-lived process."). Git status — what is committed, what is staged, what is untracked — IS the source of truth for whether a step's side-effect happened. A separate database would only duplicate that ground truth and introduce divergence bugs.
+- **Auto-fixing existing untracked artifacts in already-completed milestones.** Forward-looking only; auto-fix risks unintended side-effects on already-archived state and adds maintenance burden disproportionate to value vs catching new instances early. Historical untracked artifacts are addressed by ad-hoc quick tasks (e.g., the v23.1 audit cleanup) when discovered, not by automated sweeps over archived milestones. (Source: spec Non-Goals + round 1 disposition #3.)
+
+## Canonical fail-loudly contract
+
+Failures in the silent-skip family MUST satisfy ALL of the following four properties (the "operational definition of fail loudly", taken verbatim from the spec Goals):
+
+1. **Exit non-zero with a documented label** — the failure produces a non-zero process exit AND emits a named label (see the "Named exit-code labels" registry in `references/workflow-conventions.md`). Labels — not numeric codes — are what users grep for in remediation messages and search documentation by.
+2. **Leave the working tree in the same state as before the offending step** — no partial commits, no half-written scaffolds, no orphan staged files. Either the step's full intent landed in HEAD, or none of it did.
+3. **Print a 1-3 line user-facing message including the recommended remediation command** — concise, actionable, and pointing at a single next command the user can run to recover (e.g., `Run: dgs-tools commit --files <missing-paths>`).
+4. **Be discoverable in `dgs-tools health`** — so a user who lost the live output (closed terminal, lost session) can reproduce the diagnosis later via the standing health check.
+
+(Health-check coverage for the AGENT-13 family lands in phases 156 + 158 of milestone v23.2.)
+
+## Named exit-code labels (silent-skip family)
+
+### `summary-frontmatter-mismatch`
+
+**Source:** REL-08 (idea #28 closure, Phase 157).
+**Where it fires:** `dgs-tools final-commit-precondition` CLI; invoked at the top of the executor's `<final_commit>` step (step 0) before any commit attempt.
+**What it checks:** PLAN.md frontmatter `requirements:` is non-empty AND the to-be-written SUMMARY.md frontmatter `requirements_completed:` is empty (canonical key — the legacy hyphen variant is also accepted via the dual-read in `cmdSummaryExtract`, but new SUMMARYs must use underscore).
+
+**On fire:**
+- Exit non-zero with the label in stderr.
+- 1-3 line user-facing message naming the missing IDs and the recommended remediation ("Re-run executor or manually populate before committing.").
+- Working tree is unchanged from when the executor started `<final_commit>`.
+- Discoverable via `/dgs:health` (downstream — REL-08 ships the gate; the health surfacing is a future enhancement).
+
+**Remediation:**
+1. Inspect the to-be-written SUMMARY.md against the PLAN.md `requirements:` field.
+2. If the executor produced an empty `requirements_completed` despite non-empty PLAN, the writer regression has fired — re-run the executor (which now uses the canonical writer in `bin/lib/summary-frontmatter.cjs`).
+3. If you intentionally want to mark the plan complete without claiming the requirements, either remove the PLAN.md `requirements:` field OR proceed with a manual edit and re-invoke the precondition.
+
+**Related companion:** `plan-commit-incomplete` (REL-01, Phase 156) — same fail-loudly shape applied to the planner's `git_commit` step.
+
+## See also
+
+- `references/workflow-conventions.md` — the `scaffolded_files` contract and the named exit-code label registry that operationalise this reference.
+- `references/conflict-resolution.md` — broader DGS conflict-handling patterns; complementary to the silent-skip family but distinct (conflicts are loud failures already).
+- `specs/spec-agent-step-reliability-detect-and-prevent-silently-skipped-commit-steps.md` — the source spec that derived this reference (milestone v23.2).

package/deliver-great-systems/references/conflict-resolution.md

@@ -64,3 +64,7 @@ Conflict Resolution Summary:
 - {S} semantic warnings
 - Report: {path to RESOLUTION-REPORT.md}
 ```
+
+## See also
+
+- [Agent-Step Reliability](agent-step-reliability.md) — silent-skip diagnostic pattern; rejected anti-features; canonical fail-loudly contract.

package/deliver-great-systems/references/context-tiers.md

@@ -25,6 +25,8 @@ includes_tier: null
 files:
   - path: "PROJECT.md"
     category: "project"
+  - path: "docs/product/PRODUCT-SUMMARY.md"
+    category: "product"
   - path: "STATE.md"
     category: "state"
   - path: "config.json"
@@ -46,6 +48,8 @@ files:
     category: "requirements"
   - path: "REPOS.md"
     category: "repos"
+  - path: "docs/product/ARCHITECTURE.md"
+    category: "product-architecture"
 dynamic:
   - type: "glob"
     pattern: "codebase/**/*.md"

package/deliver-great-systems/references/package-scan-config.md

@@ -0,0 +1,151 @@
+# Package Scan Configuration
+
+User-facing reference for `/dgs:package-scan` configuration keys, tool installation, and report placement.
+
+## Shared config keys (`config.json`)
+
+### `testing.packages.tool`
+Tool cascade selection.
+
+- **Values:** `auto` (default), `snyk`, `osv`, `native`
+- **Default:** `auto` — cascade Snyk → OSV-Scanner → ecosystem-native tool based on availability
+- **When to pin:** lock to `snyk` in CI, or to `osv` when Snyk is unavailable, to catch regressions loudly rather than silently falling back. Pinned tool unavailable = scan fails with install hint (does NOT fall through the cascade).
+
+Set via: `dgs-tools config-set testing.packages.tool snyk`
+
+### `testing.packages.severity_threshold`
+Minimum severity to include in the report.
+
+- **Values:** `critical`, `high`, `medium`, `low`
+- **Default:** `low` (include everything)
+- **Filtering lands in Phase 153.** The key already exists (Phase 150) and is validated at set-time, but the filtering behaviour is P1.
+
+Set via: `dgs-tools config-set testing.packages.severity_threshold high`
+
+### `testing.packages.include_dev_dependencies`
+Whether to scan devDependencies (npm / pip / etc.).
+
+- **Values:** `true`, `false`
+- **Default:** `true`
+- **Effect on tool argv:** Snyk → adds `--production` flag when false; npm-audit → adds `--omit=dev`; other ecosystems' tools behave idiomatically.
+
+Set via: `dgs-tools config-set testing.packages.include_dev_dependencies false`
+
+### `testing.packages.timeout_seconds`
+Per-scan-invocation timeout.
+
+- **Values:** integer between 10 and 3600
+- **Default:** `300` (5 minutes)
+
+Set via: `dgs-tools config-set testing.packages.timeout_seconds 600`
+
+### `testing.packages.snyk_org`
+Snyk org UUID. When set and the tool is Snyk, the scan argv gets `--org=<ID>` appended so multi-org Snyk accounts resolve to the correct organization without needing `SNYK_CFG_ORG` exported.
+
+- **Values:** Snyk org UUID string (e.g., `5cb2d43f-6064-4fe2-80f8-4a14cef84a5a`), or `null` to omit.
+- **Default:** `null` (no `--org` flag appended; Snyk uses the account's default org).
+- **Precedence:** `config.local.json` wins over `config.json` (consistent with `snyk_token`).
+- **Report visibility:** the chosen `snyk_org` is emitted in the report YAML frontmatter as `snyk_org: "<ID>"` for auditability.
+
+Set via: `dgs-tools config-set testing.packages.snyk_org <UUID>` (shared) or `dgs-tools config-local-set testing.packages.snyk_org <UUID>` (per-machine override).
+
+## Local-only config keys (`config.local.json`)
+
+### `testing.packages.snyk_token`
+Snyk API token. **Never commit to `config.json`** — this key is gitignored.
+
+Set via: `dgs-tools config-local-set testing.packages.snyk_token <your-token>`
+
+Get your token from: https://app.snyk.io/account
+
+## Tool installation
+
+### Snyk
+- Install: `npm install -g snyk`
+- Authenticate: either `snyk auth` (interactive browser, stores credential in `~/.config/configstore/snyk.json`) OR `dgs-tools config-local-set testing.packages.snyk_token <token>` OR set `SNYK_TOKEN=<token>` in your shell env.
+- Priority order: `config.local.json testing.packages.snyk_token` → `SNYK_TOKEN` env → `snyk config get api` → `snyk whoami` (configstore-OAuth from `snyk auth`) → none.
+- The fourth probe (`snyk whoami`) detects users who authenticated via the browser-OAuth flow without setting a token; DGS then lets the Snyk CLI consult its own configstore at invocation time (no token is read by DGS).
+
+### OSV-Scanner
+- Install: https://github.com/google/osv-scanner/releases (single binary)
+- No authentication required.
+- Covers all ecosystems in one invocation via `osv-scanner --json -r .`.
+
+### Native fallbacks
+- Node.js: `npm` (bundled with Node)
+- Python: `pip install pip-audit`
+- Go: `go install golang.org/x/vuln/cmd/govulncheck@latest`
+- Ruby: `gem install bundler-audit`
+- Java: no standard native tool (scan falls back to `no_native_tool_for_ecosystem` outcome — use Snyk or OSV-Scanner for Maven/Gradle).
+
+## Report placement
+
+`/dgs:package-scan` writes its report file to one of three locations, resolved in this order:
+
+1. **Active phase** — when `config.local.json execution.active_context` points at a valid phase directory, report lands at `{phase-dir}/{phase}-PACKAGE-SCAN.md`.
+2. **Active milestone** — when a milestone slug is the active context (no phase), report lands at `{planning-root}/milestones/v{X}.{Y}-PACKAGE-SCAN.md`.
+3. **No active context** — report lands at `{planning-root}/PACKAGE-SCAN-{YYYY-MM-DD-HHmm}.md` (timestamped).
+
+The report is atomically committed via `dgs-tools commit --files <report-path>`.
+
+## Report format
+
+### Frontmatter fields
+- `type: package-scan` (constant)
+- `date: YYYY-MM-DD` (UTC)
+- `tool: snyk|osv-scanner|npm-audit|pip-audit|govulncheck|bundler-audit|mixed|none`
+- `repos_scanned: <int>`
+- `critical | high | medium | low: <int>` (severity counts)
+- `duration: <int>` (seconds)
+- `findings: [...]` (canonical entries)
+
+### Findings array entry
+Each entry has: `id` (`pkg-NNN`), `test_source`, `gap_type`, `severity`, `resource_id` (`pkg@version`), `repo`, `manifest_path`, `title`, `description`, `remediation`, `reference`, `cve`, `cvss`, `dependency_chain`, `chain_available`, `direct_or_transitive`, `tool`.
+
+### Body
+- Per-repo × severity summary table
+- Per-severity sections (Critical → High → Medium → Low) with CVE, CVSS, dependency chain, fix command, and reference URL per finding
+- `## Diagnostics` section when the scan emitted any (e.g., a pinned tool was unavailable for a specific ecosystem)
+
+## Private package / URL warning
+
+When Snyk is the tool, scan output may include org-identifying URL parameters. The report itself includes a one-line warning. Active redaction is a future enhancement (Phase 153).
+
+## Gap-planner integration contract (PKG-29)
+
+The report's YAML frontmatter `findings` array is the data contract between `/dgs:package-scan`
+and `/dgs:plan-test-gaps`. Every entry carries the canonical ordered key-set (see §5a of the
+test-gate spec) including `gap_type` and `repo`. The gap-planner:
+
+1. Reads the frontmatter via a hand-rolled YAML parser (`_parseEmittedYaml` in
+   `package-scan-report.cjs`).
+2. Groups findings by `gap_type` first (`dependency-security` vs `dependency-licence`), then by
+   `repo`.
+3. Generates one fix phase per (repo, gap_type) pair.
+
+Cross-repo deduplication happens in the REPORT BODY (Cross-Repo Summary + Dependency Overlap
+sections) — the YAML frontmatter retains one finding per repo so the gap-planner can slot work
+into per-repo fix phases without inferring repo membership from aggregated summaries.
+
+## Plan provenance (PKG-33)
+
+Each finding optionally carries `introduced_in_commit` (7-char SHA) and `introduced_in_plan`
+(DGS plan-id like `152-03`). The `package-scan-provenance.cjs` module runs
+`git log --format=%H%x00%s -S <package_name> -- <manifest_path>` in each repo directory and
+extracts the plan-id from the OLDEST commit's subject via regex `/\b(\d{3}-\d{2})\b/`.
+
+**Commit-message convention:** DGS atomic commits follow `type(NNN-NN): subject` (e.g.
+`feat(149-01): implement scanner`). The regex matches the `NNN-NN` pattern in any position of
+the commit subject, including inline mentions like `Merge branch feature/149-01-foo`.
+
+**Resolution failures:** when git is unavailable, the directory is not a git repo, the manifest
+file has no history, or the commit subject contains no plan-id, the fields are `null` and the
+body renders `**Introduced in:** unknown`.
+
+**Performance:** lookups are memoised per (repoDir, manifestPath, packageName) within a single
+scan; the same dependency appearing in multiple workspaces costs one git subprocess call.
+
+## See also
+- Spec: `specs/spec-package-dependency-scanning.md`
+- Architecture: `projects/gsd/research/ARCHITECTURE.md`
+- Pitfalls: `projects/gsd/research/PITFALLS.md`

package/deliver-great-systems/references/questioning.md

@@ -12,20 +12,6 @@ Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
 
 </philosophy>
 
-<the_goal>
-
-By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-
-- **Research** needs: what domain to research, what the user already knows, what unknowns exist
-- **Requirements** needs: clear enough vision to scope v1 features
-- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
-- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-
-A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-</the_goal>
-
 <how_to_question>
 
 **Start open.** Let them dump their mental model. Don't interrupt with structure.
@@ -130,22 +116,6 @@ Four things. If they volunteer more, capture it.
 
 </context_checklist>
 
-<decision_gate>
-
-When you could write a clear PROJECT.md, offer to proceed:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-</decision_gate>
-
 <anti_patterns>
 
 - **Checklist walking** — Going through domains regardless of what they said

package/deliver-great-systems/references/spec-review-loop.md

@@ -28,8 +28,7 @@ payload = {
     'messages': [
         {'role': 'system', 'content': 'You are a senior product manager reviewing a PRD spec. Provide specific, actionable feedback organized by section. For each item, indicate severity: [critical], [important], or [suggestion]. If the spec is solid, respond with only: LGTM - no changes needed.'},
         {'role': 'user', 'content': 'Review this PRD spec:\n\n' + spec}
-    ],
-    'temperature': 0.3
+    ]
 }
 json.dump(payload, open('/tmp/dgs-review-openai.json', 'w'))
 " < "$SPEC_FILE"

package/deliver-great-systems/references/workflow-conventions.md

@@ -0,0 +1,29 @@
+# Workflow Conventions
+
+Canonical conventions DGS workflows and their helper CLI commands MUST follow. Authoritative for the milestone v23.2 "Agent-Step Reliability" family of contracts.
+
+## The scaffolded_files contract (AGENT-13)
+
+Any CLI command in `bin/lib/*.cjs` that **scaffolds files** — that is, writes new files to disk on behalf of the caller — MUST emit a `scaffolded_files: []` array in its raw JSON output. Each entry is a path relative to the planning root. The list MUST be derived from the actual files written by the run; it MUST NOT be hardcoded. If a future scaffolding addition extends what the CLI writes, the array automatically widens — the workflow consumer needs no code change.
+
+Any `workflows/*.md` that invokes such a CLI command MUST consume the returned `scaffolded_files` array and pass it to a subsequent `node $TOOLS commit ... --files <scaffolded_files>` invocation in the same workflow. Capturing the JSON without forwarding the paths to a commit step is exactly the silent-skip pattern this contract exists to prevent (see `references/agent-step-reliability.md`).
+
+This contract is enforced by `tests/workflow-conventions.test.cjs`, which runs in default `npm test`. The test fails the build if a workflow invokes a known scaffold-emitting CLI command but does not consume the returned `scaffolded_files` array in a subsequent commit step. A meta-assertion within the same test file guards against silent disablement or relocation of the lint.
+
+## Named exit-code labels (registry)
+
+Workflows and CLI commands in the AGENT-13 family fail loudly with **named labels** — never with bare numeric exit codes — so users can search documentation, remediation messages, and `dgs-tools health` output by label. The labels are stable identifiers.
+
+| Label | Owner | Meaning | Doc reference |
+| --- | --- | --- | --- |
+| `plan-commit-incomplete` | `/dgs:plan-phase` orchestrator | Planner-reported `created_files` not all present in HEAD after commit | `references/agent-step-reliability.md` |
+| `multi-repo-dirt` | `/dgs:fast` orchestrator | Multiple sub-repos dirty (or planning-root + sub-repo both have new files) | `references/agent-step-reliability.md` |
+| `pre-existing-dirt` | `/dgs:fast` orchestrator | Working tree dirty before fast-mode edit step | `references/agent-step-reliability.md` |
+| `summary-frontmatter-mismatch` | `/dgs:execute-plan` (executor pre-commit precondition) | PLAN `requirements` non-empty AND about-to-be-written SUMMARY `requirements_completed` empty | `references/agent-step-reliability.md` |
+
+Future labels in this family must be added to this table when introduced.
+
+## See also
+
+- `references/agent-step-reliability.md` — the silent-skip diagnostic pattern, rejected anti-features, and canonical fail-loudly contract that this conventions doc operationalises.
+- `specs/spec-agent-step-reliability-detect-and-prevent-silently-skipped-commit-steps.md` — the source spec that derived these conventions (milestone v23.2).

package/deliver-great-systems/skills/dgs-tests/package-scan.md

@@ -0,0 +1,44 @@
+---
+name: package-scan
+display_name: Package Scanning
+description: Checks project dependencies for known vulnerabilities and licence compliance issues
+command: /dgs:package-scan
+enabled: true
+execution_order: 10
+prerequisites:
+  - check: "find . -maxdepth 3 \\( -name 'package.json' -o -name 'package-lock.json' -o -name 'yarn.lock' -o -name 'requirements.txt' -o -name 'Pipfile.lock' -o -name 'poetry.lock' -o -name 'pyproject.toml' -o -name 'go.mod' -o -name 'Gemfile.lock' -o -name 'pom.xml' \\) 2>/dev/null | head -1 | grep -q ."
+    description: "At least one recognised manifest file exists in any repo or at the product root"
+    type: file_exists
+config_key: testing.packages
+finding_prefix: pkg
+---
+
+# Package Scan — Test Type Plugin
+
+This skill registers `/dgs:package-scan` as a built-in test type for the DGS test-gate pipeline. It ships inert in v23.1 — the skill-discovery engine (`skills.cjs`) lands in the future test-gate milestone. The frontmatter above conforms to the Test Type Plugin Contract defined in `orig-specs/dgs-test-gate-spec.md` §5a so the discovery engine can consume this file unchanged when it arrives.
+
+## What this test type does
+
+Scans every registered repo plus the product root for dependency vulnerabilities and licence compliance issues. Uses a tool cascade (Snyk if authenticated → OSV-Scanner if on PATH → ecosystem-native tools). Produces a canonical findings array consumable by the gate's gap-planner.
+
+## How to run standalone
+
+Run the standalone command directly:
+
+```
+/dgs:package-scan
+```
+
+Configuration keys live under `testing.packages.*` in `{planning-root}/config.json` (see `deliver-great-systems/references/package-scan-config.md`).
+
+## Prerequisites
+
+The `prerequisites[].check` command returns exit 0 when at least one recognised manifest file is discoverable from the current working directory (depth 3 by default — sufficient for product root + direct child repos + workspace roots). The canonical, code-reachable equivalent lives in `deliver-great-systems/bin/lib/package-scan-skill.cjs` `checkPrerequisites(cwd)` — Phase 152+ consumers should prefer the module API over the shell check because the module iterates REPOS.md explicitly.
+
+## Finding contract
+
+Every finding this type produces conforms to the canonical shape in `orig-specs/dgs-test-gate-spec.md` §5a Canonical Finding Output Format, with the package-specific extensions (manifest_path, cve, cvss, dependency_chain, chain_available, direct_or_transitive, tool) appended. The `finding_prefix` is `pkg`; every id follows the form `pkg-NNN` (zero-padded 3-digit, orchestrator-assigned). Licence-violation findings derive their id as `pkg-NNN-lic`.
+
+## Versioning
+
+This skill contract is pinned to test-gate-spec §5a v1.0. If the spec's frontmatter schema changes, this file must be updated to match before the future `skills.cjs` discovery engine is deployed.

package/deliver-great-systems/templates/REVIEW.md

@@ -0,0 +1,35 @@
+# Review: {title}
+
+{stats_banner}
+
+## Goal
+
+{goal}
+
+## What Was Built
+
+{what_was_built}
+
+## Code Changes
+
+{code_changes}
+
+## Aggregate Statistics
+
+{aggregate_stats}
+
+## Verification
+
+{verification}
+
+## Risk Flags
+
+{risk_flags}
+
+## Overall
+
+{overall}
+
+---
+*Generated: {date}*
+*Mode: {mode}*

package/deliver-great-systems/templates/VALIDATION.md

@@ -48,7 +48,7 @@ verified_by: ""             # Author who initiated verification (set from init a
 
 ---
 
-## Wave 0 Requirements
+## Wave 0 Task Requirements
 
 - [ ] `{tests/test_file.py}` — stubs for REQ-{XX}
 - [ ] `{tests/conftest.py}` — shared fixtures

package/deliver-great-systems/templates/claude-md.md

@@ -46,12 +46,28 @@ When the request involves creating, modifying, or deleting code or configuration
 - Route through `/dgs:debug`
 - Example: "The tests started failing after yesterday's merge"
 
+**Is there an active milestone?** Check if the work relates to the milestone scope.
+- **Yes, related to milestone:** Route through `/dgs:quick` (milestone-context -- works in milestone worktree, no separate lifecycle)
+- **Yes, but unrelated to milestone:** Route through `/dgs:quick --main` (product-level -- creates separate worktree off main)
+- **No active milestone:** Route through `/dgs:quick` (product-level -- creates ephemeral worktree)
+
+**Is it a trivial 1-line fix?** Route through `/dgs:fast` (always direct to main, zero overhead)
+
 **When ambiguous, default to the smaller command.** Prefer `/dgs:fast` or `/dgs:quick` over `/dgs:execute-phase`.
 
 Before invoking, mention briefly: "Small fix, routing through `/dgs:fast`." -- command name and short reason.
 
 These routing rules apply whether the change is user-initiated or discovered by Claude during other work.
 
+**Quick task lifecycle:**
+- `/dgs:complete-quick` -- Merge quick work to main (rebase + merge + cleanup)
+- `/dgs:abandon-quick` -- Discard quick work without merging
+- These apply to product-level quicks only. Milestone-context quicks merge with the milestone.
+
+**Quick outgrew its scope?** Do NOT try to promote a quick to a milestone. Complete it (`/dgs:complete-quick`) or abandon it (`/dgs:abandon-quick`), then start a proper milestone for the larger work.
+
+**Need a product-level quick during milestone work?** Use `/dgs:quick --main "title"` to force a product-level quick that works off main, independent of the active milestone.
+
 ## 4. Override Requested? Acknowledge and Proceed
 
 The user can bypass DGS routing by including one of these phrases in their request:
@@ -72,3 +88,14 @@ When the user mentions work for later (not for immediate execution):
 - Specific tasks to remember: `/dgs:add-todo`
 
 These capture without executing.
+
+## 6. Completion Gates? Stop and Report
+
+Never take these actions without explicit user instruction:
+
+- **`/dgs:quick-complete`** or **`/dgs:quick-abandon`** -- merging or discarding a quick task is the user's decision
+- **`/dgs:complete-milestone`** -- milestone completion involves branch merging, tagging, and archival
+- **`--force`** flags on any command -- force flags bypass safety checks (e.g., four-eyes governance)
+- **`git push --force`**, **`git reset --hard`**, or other destructive git operations
+
+When a gate blocks execution (e.g., four-eyes enforcement, missing REVIEW.md), **stop and report the error**. Tell the user what command to run with what flag. Do not retry with the bypass flag yourself.

package/deliver-great-systems/templates/package-scan-report.md

@@ -0,0 +1,108 @@
+# Package Scan Report Template
+
+> Reference: the output format `/dgs:package-scan` produces.
+> This file is documentation — the emitter composes programmatically, not via template substitution.
+
+## Frontmatter + Body Skeleton
+
+```markdown
+---
+type: package-scan
+date: {{YYYY-MM-DD}}
+tool: {{snyk|osv-scanner|npm-audit|pip-audit|govulncheck|bundler-audit|mixed|none}}
+repos_scanned: {{N}}
+critical: {{N}}
+high: {{N}}
+medium: {{N}}
+low: {{N}}
+duration: {{seconds}}
+findings:
+  - id: "pkg-001"
+    test_source: "package-scan"
+    gap_type: "dependency-security"
+    severity: "critical"
+    resource_id: "{{package}}@{{version}}"
+    repo: "{{repo-name}}"
+    manifest_path: "{{manifest-path-or-null}}"
+    title: "{{title}}"
+    description: "{{description-or-null}}"
+    remediation: "{{remediation-or-null}}"
+    reference: "{{reference-url-or-null}}"
+    cve: "{{CVE-id-or-null}}"
+    cvss: {{score-or-null}}
+    dependency_chain:
+      - "{{dep1}}"
+      - "{{dep2}}"
+    chain_available: true
+    direct_or_transitive: "{{direct-or-transitive}}"
+    tool: "{{scanner-tool}}"
+---
+
+# Package Scan Report
+
+## Summary
+
+| Repo | Ecosystem | Tool | Critical | High | Medium | Low | Status |
+|------|-----------|------|----------|------|--------|-----|--------|
+| {{repo}} | {{node|python|go|ruby|java|yarn}} | {{tool}} | {{N}} | {{N}} | {{N}} | {{N}} | ok |
+| {{repo}} | {{ecosystem}} | — | — | — | — | — | skipped (no manifests) |
+
+## Critical
+
+### {{repo}}: {{package}}@{{version}} — {{title}}
+- **CVE:** {{CVE-id-or-'unavailable'}}
+- **CVSS:** {{score-or-'unavailable'}}
+- **Tool:** {{scanner-tool}}
+- **Manifest:** `{{manifest-path}}` (or `repo root`)
+- **Direct/Transitive:** {{direct-or-transitive-or-'unknown'}}
+- **Dependency chain:** {{a → b → c}} (or `unavailable (chain_available: false — recommend Snyk for full chain analysis)`)
+- **Fix:** {{remediation-or-'no upgrade path available — manual review required'}}
+- **Reference:** {{URL-or-'unavailable'}}
+
+> {{description-blockquote-if-present}}
+
+## High
+(per-finding format same as Critical)
+
+## Medium
+(per-finding format same as Critical)
+
+## Low
+(per-finding format same as Critical)
+
+## Diagnostics
+(present only when runResult.diagnostics is non-empty)
+- {{diagnostic.kind}}: {{diagnostic.message-or-hint}}
+```
+
+## Field reference
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | string | `pkg-NNN` (zero-padded, assigned by orchestrator at merge time) |
+| `test_source` | string | Always `"package-scan"` (constant) |
+| `gap_type` | string | `"dependency-security"` or `"dependency-licence"` (Phase 153 extends to licence) |
+| `severity` | string | `critical|high|medium|low` (null/unknown collapses to `medium` — conservative bias) |
+| `resource_id` | string | `{{package_name}}@{{installed_version}}` (omit `@` if version empty) |
+| `repo` | string | Repo name from REPOS.md (or `_product_root`) |
+| `manifest_path` | string\|null | Relative POSIX path of manifest that produced the finding (null when scanning repo root) |
+| `title` | string | Vulnerability title from scanner |
+| `description` | string\|null | Vulnerability description (may be multi-line) |
+| `remediation` | string\|null | Fix command from scanner |
+| `reference` | string\|null | Advisory URL |
+| `cve` | string\|null | CVE identifier |
+| `cvss` | number\|null | CVSS score (v3 preferred) |
+| `dependency_chain` | array\|null | e.g., `[your-app, auth-lib, lodash]` |
+| `chain_available` | boolean | `false` when the scanner didn't provide a chain (OSV / native) |
+| `direct_or_transitive` | string\|null | `direct` or `transitive` |
+| `tool` | string | Scanner that produced this finding (for disambiguation when frontmatter `tool` is `mixed`) |
+
+## Placement cascade
+
+1. Active phase → `{phase-dir}/{phase-number}-PACKAGE-SCAN.md`
+2. Active milestone → `{planning-root}/milestones/v{X}.{Y}-PACKAGE-SCAN.md`
+3. No active context → `{planning-root}/PACKAGE-SCAN-{YYYY-MM-DD-HHmm}.md`
+
+## Related
+- `deliver-great-systems/references/package-scan-config.md` — config reference
+- `specs/spec-package-dependency-scanning.md` — the source spec