@ktpartners/dgs-platform 3.0.4 → 3.3.0

package/deliver-great-systems/bin/lib/wave-0-template-rename.test.cjs

@@ -0,0 +1,40 @@
+// deliver-great-systems/bin/lib/wave-0-template-rename.test.cjs
+// REL-03 convergence test scaffold — initially RED. Turns GREEN after plan 02
+// lands the planner-prompt edits and the VALIDATION.md template rename.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '../../..');
+const planner = path.join(repoRoot, 'agents/dgs-planner.md');
+const template = path.join(repoRoot, 'deliver-great-systems/templates/VALIDATION.md');
+
+test('REL-03: VALIDATION template uses heading "Wave 0 Task Requirements"', () => {
+  const content = fs.readFileSync(template, 'utf-8');
+  assert.match(content, /## Wave 0 Task Requirements/, 'template must use new heading');
+});
+
+test('REL-03: VALIDATION template no longer uses "Wave 0 Requirements" as a section heading', () => {
+  const content = fs.readFileSync(template, 'utf-8');
+  // The OLD heading must NOT exist as a section heading (paragraph mentions are OK)
+  assert.doesNotMatch(content, /^## Wave 0 Requirements\s*$/m, 'old heading must be gone');
+});
+
+test('REL-03: planner prompt unambiguously states "Plans are numbered starting at 01"', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Plans are numbered starting at 01/, 'planner must state plan-numbering rule');
+});
+
+test('REL-03: planner prompt explicitly forbids plan: 00 and wave: 0', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Never create a plan with `plan: 00` or `wave: 0`/, 'planner must forbid plan: 00 / wave: 0');
+});
+
+test('REL-03: planner prompt mentions Wave 0 lives as Task 0 inside plan 01', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Wave 0 work lives as Task 0 inside plan 01/, 'planner must locate Wave 0 inside plan 01');
+});
+
+// REL-03 sentinel — flag this file as a Wave-0 RED scaffold for plan 02.

package/deliver-great-systems/bin/lib/worktrees.cjs

@@ -21,6 +21,7 @@ const { execGit, output, error, loadConfig } = require('./core.cjs');
 const { getLocalConfigPath } = require('./config.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { parseReposMd } = require('./repos.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
 
 // ─── Internal helpers ─────────────────────────────────────────────────────────
 
@@ -223,6 +224,27 @@ function _findMainCheckoutPath(cwd, repoName) {
   return _resolveRepoAbsPath(cwd, repo.path);
 }
 
+/**
+ * Read active milestone version from projects/{project}/STATE.md frontmatter.
+ * Returns null on any failure — callers must not throw.
+ * @param {string} cwd
+ * @param {string} project
+ * @returns {string|null}
+ */
+function _readMilestoneVersion(cwd, project) {
+  try {
+    const statePath = path.join(cwd, 'projects', project, 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    const content = fs.readFileSync(statePath, 'utf-8');
+    const fm = extractFrontmatter(content);
+    const v = fm && fm.milestone;
+    if (typeof v === 'string' && /^v\d+(\.\d+)?$/.test(v)) return v;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 // ─── Exported command functions ───────────────────────────────────────────────
 
 /**
@@ -319,11 +341,15 @@ function cmdWorktreesCreate(cwd, args) {
       process.stderr.write('Re-run setup: dgs-tools worktrees setup ' + slug + '\n');
     }
 
-    // Write state
+    // Write state. milestone_version is captured from STATE.md frontmatter at
+    // creation time for milestone-type worktrees; quick worktrees and
+    // unresolvable STATE reads degrade cleanly to null.
+    const milestoneVersion = type === 'milestone' ? _readMilestoneVersion(cwd, project) : null;
     _setWorktreeState(cwd, project, slug, {
       type: type,
       mode: mode,
       setup_complete: setupComplete,
+      milestone_version: milestoneVersion,
       repos: { [repo.name]: worktreePath },
     });
 

package/deliver-great-systems/bin/lib/worktrees.test.cjs

@@ -852,6 +852,82 @@ describe('checkWorktreeHealth', () => {
   });
 });
 
+// ─── cmdWorktreesCreate — milestone_version ──────────────────────────────────
+
+describe('cmdWorktreesCreate — milestone_version', () => {
+  let env;
+  afterEach(() => { if (env) env.cleanup(); });
+
+  it('records milestone_version from STATE.md frontmatter on milestone worktree entries', () => {
+    env = createTestEnv();
+    // Overwrite STATE.md with real frontmatter containing a milestone field
+    fs.writeFileSync(
+      path.join(env.planDir, 'projects', 'tp', 'STATE.md'),
+      '---\nmilestone: v42.0\nstatus: executing\n---\n\n# State\n'
+    );
+    // Commit STATE update so git state is clean (test parity)
+    execSync('git add .', { cwd: env.planDir, stdio: 'pipe' });
+    execSync('git commit -m "state"', { cwd: env.planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+    const result = runCmd(env.planDir, 'worktrees create ms-versioned --type milestone');
+    assert.ok(result.created);
+    assert.equal(result.type, 'milestone');
+
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['ms-versioned'];
+    assert.ok(entry, 'worktree entry should exist');
+    assert.equal(entry.type, 'milestone');
+    assert.equal(entry.milestone_version, 'v42.0', 'milestone_version should be read from STATE.md frontmatter');
+    assert.ok(entry.repos && entry.repos['code-repo'], 'repos field should still be populated');
+  });
+
+  it('falls back to milestone_version: null when STATE.md has no milestone field', () => {
+    env = createTestEnv();
+    // STATE.md with no frontmatter at all (default from createTestEnv)
+    // createTestEnv already writes `# State\nStatus: planning\n` — no frontmatter.
+
+    const result = runCmd(env.planDir, 'worktrees create ms-nofm --type milestone');
+    assert.ok(result.created);
+
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['ms-nofm'];
+    assert.ok(entry, 'worktree entry should exist — creation must not fail on missing frontmatter');
+    assert.equal(entry.type, 'milestone');
+    assert.equal(entry.milestone_version, null, 'milestone_version should be null when no milestone frontmatter');
+  });
+
+  it('falls back to milestone_version: null when STATE.md is missing entirely', () => {
+    env = createTestEnv();
+    // Delete STATE.md
+    fs.rmSync(path.join(env.planDir, 'projects', 'tp', 'STATE.md'));
+
+    const result = runCmd(env.planDir, 'worktrees create ms-nostate --type milestone');
+    assert.ok(result.created, 'creation must succeed even when STATE.md is missing');
+
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['ms-nostate'];
+    assert.ok(entry);
+    assert.equal(entry.milestone_version, null);
+  });
+
+  it('falls back to milestone_version: null when frontmatter milestone value is malformed', () => {
+    env = createTestEnv();
+    fs.writeFileSync(
+      path.join(env.planDir, 'projects', 'tp', 'STATE.md'),
+      '---\nmilestone: not-a-version\n---\n\n# State\n'
+    );
+    execSync('git add .', { cwd: env.planDir, stdio: 'pipe' });
+    execSync('git commit -m "state"', { cwd: env.planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+    const result = runCmd(env.planDir, 'worktrees create ms-malformed --type milestone');
+    assert.ok(result.created);
+
+    const config = readLocalConfig(env.planDir);
+    const entry = config.projects.tp.worktrees['ms-malformed'];
+    assert.equal(entry.milestone_version, null, 'malformed version string should degrade to null');
+  });
+});
+
 // ─── main checkout invariant ─────────────────────────────────────────────────
 
 describe('main checkout invariant', () => {

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

@@ -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.