@ktpartners/dgs-platform 3.0.4 → 3.3.1

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

@@ -88,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

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

@@ -1,186 +1,22 @@
 # PROJECT.md Template
 
-Template for `PROJECT.md` (in planning root) — the living project context document.
-
-> **Layout-agnostic:** Workflows access PROJECT.md via `${project_path}` from init output. Works in both standard and root layouts.
+Thin skeleton for `PROJECT.md` (in `${project_path}`). Projects are holders —
+product-level vision lives in `docs/product/PRODUCT-SUMMARY.md` (Tier 1), and
+product architecture lives in `docs/product/ARCHITECTURE.md` (Tier 2).
 
 <template>
 
 ```markdown
 # [Project Name]
 
-## What This Is
-
-[Current accurate description — 2-3 sentences. What does this product do and who is it for?
-Use the user's language and framing. Update whenever reality drifts from this description.]
-
-## Core Value
-
-[The ONE thing that matters most. If everything else fails, this must work.
-One sentence that drives prioritization when tradeoffs arise.]
-
-## Requirements
-
-### Validated
-
-<!-- Shipped and confirmed valuable. -->
-
-(None yet — ship to validate)
-
-### Active
-
-<!-- Current scope. Building toward these. -->
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-
-## Context
-
-[Background information that informs implementation:
-- Technical environment or ecosystem
-- Relevant prior work or experience
-- User research or feedback themes
-- Known issues to address]
-
-## Constraints
-
-- **[Type]**: [What] — [Why]
-- **[Type]**: [What] — [Why]
-
-Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
-
-## Key Decisions
-
-<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
-
----
-*Last updated: [date] after [trigger]*
+<One-line purpose — fill in to anchor this project.>
 ```
 
 </template>
 
-<guidelines>
-
-**What This Is:**
-- Current accurate description of the product
-- 2-3 sentences capturing what it does and who it's for
-- Use the user's words and framing
-- Update when the product evolves beyond this description
-
-**Core Value:**
-- The single most important thing
-- Everything else can fail; this cannot
-- Drives prioritization when tradeoffs arise
-- Rarely changes; if it does, it's a significant pivot
-
-**Requirements — Validated:**
-- Requirements that shipped and proved valuable
-- Format: `- ✓ [Requirement] — [version/phase]`
-- These are locked — changing them requires explicit discussion
-
-**Requirements — Active:**
-- Current scope being built toward
-- These are hypotheses until shipped and validated
-- Move to Validated when shipped, Out of Scope if invalidated
-
-**Requirements — Out of Scope:**
-- Explicit boundaries on what we're not building
-- Always include reasoning (prevents re-adding later)
-- Includes: considered and rejected, deferred to future, explicitly excluded
-
-**Context:**
-- Background that informs implementation decisions
-- Technical environment, prior work, user feedback
-- Known issues or technical debt to address
-- Update as new context emerges
-
-**Constraints:**
-- Hard limits on implementation choices
-- Tech stack, timeline, budget, compatibility, dependencies
-- Include the "why" — constraints without rationale get questioned
-
-**Key Decisions:**
-- Significant choices that affect future work
-- Add decisions as they're made throughout the project
-- Track outcome when known:
-  - ✓ Good — decision proved correct
-  - ⚠️ Revisit — decision may need reconsideration
-  - — Pending — too early to evaluate
-
-**Last Updated:**
-- Always note when and why the document was updated
-- Format: `after Phase 2` or `after v1.0 milestone`
-- Triggers review of whether content is still accurate
-
-</guidelines>
-
-<evolution>
-
-PROJECT.md evolves throughout the project lifecycle.
-
-**After each phase transition:**
-1. Requirements invalidated? → Move to Out of Scope with reason
-2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
-
-**After each milestone:**
-1. Full review of all sections
-2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
-
-</evolution>
-
-<brownfield>
-
-For existing codebases:
-
-1. **Map codebase first** via `/dgs:map-codebase`
-
-2. **Infer Validated requirements** from existing code:
-   - What does the codebase actually do?
-   - What patterns are established?
-   - What's clearly working and relied upon?
-
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
-   - Validated = inferred from existing code
-   - Active = user's goals for this work
-   - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
-
-</brownfield>
-
 <state_reference>
 
-STATE.md references PROJECT.md:
-
-```markdown
-## Project Reference
-
-See: PROJECT.md (updated [date])
-
-**Core value:** [One-liner from Core Value section]
-**Current focus:** [Current phase name]
-```
-
-This ensures Claude reads current PROJECT.md context.
+STATE.md references PROJECT.md by path; the thin skeleton still satisfies
+`dgs-tools health` Check 2 (file exists + top-level heading).
 
 </state_reference>

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

@@ -40,7 +40,9 @@ patterns-established:
   - "Pattern 1: description"
   - "Pattern 2: description"
 
-requirements-completed: []  # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
+requirements_completed: []  # MANDATORY — Copy ALL requirement IDs from this plan's `requirements` frontmatter field VERBATIM. Empty array allowed only when PLAN's `requirements:` is also empty. Pre-commit precondition (REL-08) aborts the executor with `summary-frontmatter-mismatch` if non-empty PLAN paired with empty `requirements_completed`.
+# Canonical key: `requirements_completed` (underscore — pinned by Phase 157 / 157-Q2-FINDINGS.md).
+# The legacy hyphen variant is still readable by `cmdSummaryExtract` for backwards-compat with archived v23.1 SUMMARYs (REL-10 dual-read), but MUST NOT be used for new SUMMARYs.
 
 # Metrics
 duration: Xmin

package/deliver-great-systems/workflows/add-phase.md

@@ -76,6 +76,11 @@ Update STATE.md to reflect the new phase:
    ```
 
 If "Roadmap Evolution" section doesn't exist, create it.
+
+3. Commit both ROADMAP.md and STATE.md:
+   ```bash
+   node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: add phase {N} to roadmap" --push --files ${roadmap_path} ${state_path}
+   ```
 </step>
 
 <step name="completion">

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

@@ -45,6 +45,19 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phases list
 - Extract milestone definition of done from ROADMAP.md
 - Extract requirements mapped to this milestone from REQUIREMENTS.md
 
+### Parse `--strict-audit` flag (REL-10)
+
+```bash
+STRICT_AUDIT=$(echo "$ARGUMENTS" | grep -oE -- '--strict-audit' | head -1)
+if [ -n "$STRICT_AUDIT" ]; then
+  STRICT_AUDIT=true
+else
+  STRICT_AUDIT=false
+fi
+```
+
+When `STRICT_AUDIT=true`, the cross-reference matrix in Section 5d preserves the OLD strict behaviour: empty `requirements_completed` → `partial` regardless of VERIFICATION state. When `STRICT_AUDIT=false` (default), Section 5d applies the soft-tolerance via `bin/lib/audit-tolerance.cjs::applyMatrix` and logs the `summary-frontmatter-empty-but-verified` warning under a separate channel (`soft_warnings`) — distinct from real partials.
+
 ## 2. Read All Phase Verifications
 
 For each phase directory, read the VERIFICATION.md:
@@ -143,21 +156,30 @@ done
 
 ### 5d. Status Determination Matrix
 
-For each REQ-ID, determine status using all three sources:
+For each REQ-ID, determine status using all three sources, routed through `bin/lib/audit-tolerance.cjs::applyMatrix(input)` (REL-10):
+
+| VERIFICATION.md Status | SUMMARY Frontmatter | requirements_claimed in VERIFICATION | --strict-audit | → Final Status |
+|------------------------|---------------------|--------------------------------------|----------------|----------------|
+| passed                 | listed              | any                                  | any            | **satisfied** |
+| passed                 | empty               | lists ID                             | false (default) | **satisfied** + soft-warning `summary-frontmatter-empty-but-verified` |
+| passed                 | empty               | lists ID                             | true            | **partial** (preserves old strict behaviour; opt-in via `--strict-audit`) |
+| passed                 | empty               | does NOT list ID                     | any            | **partial** (real partial — tolerance must NOT mask this) |
+| gaps_found             | any                 | any                                  | any            | **unsatisfied** |
+| missing                | listed              | any                                  | any            | **partial** (verification gap) |
+| missing                | missing             | any                                  | any            | **unsatisfied** |
+
+**Soft-warning channel:** Entries with status `satisfied` AND `softWarning: 'summary-frontmatter-empty-but-verified'` are collected in a SEPARATE list under `soft_warnings.summary_frontmatter_empty_but_verified` in the audit JSON output. They are NOT included under `gaps.requirements` — that channel is reserved for real `unsatisfied` and real `partial`. The soft-warning channel is shown as an info-level note in the markdown report.
 
-| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
-|------------------------|---------------------|-----------------|----------------|
-| passed                 | listed              | `[x]`           | **satisfied**  |
-| passed                 | listed              | `[ ]`           | **satisfied** (update checkbox) |
-| passed                 | missing             | any             | **partial** (verify manually) |
-| gaps_found             | any                 | any             | **unsatisfied** |
-| missing                | listed              | any             | **partial** (verification gap) |
-| missing                | missing             | any             | **unsatisfied** |
+**Implementation:** Section 5d invokes `applyMatrix({ verificationStatus, requirementsClaimed, summaryRequirementsCompleted, reqId, strictAudit })` for each REQ-ID. The output `{ status, softWarning }` populates the per-requirement row.
+
+**Removal trigger (REL-10 band-aid):** When 3 consecutive milestones ship with zero `summary-frontmatter-empty-but-verified` warnings, this row should be removed from the matrix and the strict behaviour restored as default.
 
 ### 5e. FAIL Gate and Orphan Detection
 
 **REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.
 
+**Soft-warning entries (`softWarning: 'summary-frontmatter-empty-but-verified'`) MUST NOT force `gaps_found`** — they are `satisfied` with a recoverable provenance gap. They surface in `soft_warnings.summary_frontmatter_empty_but_verified` and in the markdown info-level notes only.
+
 **Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
 
 ## 5.5. Nyquist Compliance Discovery
@@ -207,6 +229,11 @@ gaps:  # Critical blockers
       completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
       verification_status: "passed | gaps_found | missing | orphaned"
       evidence: "{specific evidence or lack thereof}"
+soft_warnings:  # REL-10: recoverable provenance issues — NOT blockers
+  summary_frontmatter_empty_but_verified:
+    - id: "{REQ-ID}"
+      phase: "{phase}"
+      reason: "VERIFICATION.md status: passed and requirements_claimed lists ID; SUMMARY.md requirements_completed is empty"
   integration: [...]
   flows: [...]
 tech_debt:  # Non-critical, deferred
@@ -227,7 +254,35 @@ Plus full markdown report with tables for requirements, phases, integration, tec
 - `gaps_found` — critical blockers exist
 - `tech_debt` — no blockers but accumulated deferred items need review
 
-## 7. Present Results
+## 7. Generate REVIEW.md
+
+After audit scoring completes, generate the milestone review report so it is available before reviewers run complete-milestone.
+
+```bash
+# Generate REVIEW.md using the CLI command — always regenerates even if prior version exists
+REVIEW_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" jobs generate-review "${milestone_version}" --raw 2>&1)
+REVIEW_EXIT=$?
+```
+
+**If generation succeeds** (`REVIEW_EXIT` is 0):
+
+Parse the JSON output to get the file path:
+```bash
+REVIEW_PATH=$(echo "$REVIEW_RESULT" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf-8');try{const j=JSON.parse(d);console.log(j.relativePath||'')}catch{console.log('')}")
+```
+
+Display: `Review report: ${REVIEW_PATH}`
+
+**If generation fails** (`REVIEW_EXIT` is non-zero):
+
+Log warning and continue — do NOT block the audit:
+```
+Warning: Review generation failed: ${REVIEW_RESULT}
+```
+
+The audit report is complete regardless of review generation status. The review report is supplementary context for four-eyes reviewers.
+
+## 8. Present Results
 
 Route by status (see `<offer_next>`).
 
@@ -360,5 +415,6 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 - [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
 - [ ] Nyquist compliance scanned for all milestone phases (if enabled)
 - [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
+- [ ] REVIEW.md generated as final step (or warning logged on failure)
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/deliver-great-systems/workflows/cancel-job.md

@@ -65,7 +65,7 @@ Display the result based on the response:
 
 **If `cancelled: true`:**
 ```
-Job {version} cancelled. {steps_reset} in-progress step(s) reset. Job moved to pending/ -- re-run with /dgs:run-job {version}
+Job {version} cancelled. {steps_reset} in-progress step(s) reset. Job status set to pending -- re-run with /dgs:run-job {version}
 ```
 
 **If `reason: 'not_found'`:**