@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/workflows/new-project.md

@@ -1,5 +1,5 @@
 <purpose>
-Initialize a new project through questioning and PROJECT.md creation. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. Run /dgs:new-milestone after to start your first milestone.
+Initialize a new project as a thin skeleton (name + one-line placeholder). Projects are holders — specs and milestones carry the real work. Run `/dgs:write-spec` next to capture what you're building, then `/dgs:new-milestone --auto <spec-id>` to start the first milestone.
 </purpose>
 
 <context_tier>planning</context_tier>
@@ -8,49 +8,6 @@ Initialize a new project through questioning and PROJECT.md creation. This is th
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
-<auto_mode>
-## Auto Mode Detection
-
-Check if `--auto` flag is present in $ARGUMENTS.
-
-**If auto mode:**
-- Skip brownfield mapping offer (assume greenfield)
-- Skip deep questioning (extract context from provided document)
-- Config: Use existing product config from init-product
-- After config: run Step 2b (parse spec), Step 2c (repo cross-check), write PROJECT.md
-- End with completion output directing to `/dgs:new-milestone --auto <spec-id>`
-
-**Document requirement:**
-Auto mode requires an idea document or spec reference — either:
-- File reference: `/dgs:new-project --auto @prd.md`
-- Pasted/written text in the prompt
-- Spec ID: `/dgs:new-project --auto <spec-id>`
-- Spec file path: `/dgs:new-project --auto @${project_root}/specs/X.md`
-
-If no document content provided, error:
-
-```
-Error: --auto requires an idea document or spec reference.
-
-Usage:
-  /dgs:new-project --auto @your-idea.md           # From idea document
-  /dgs:new-project --auto [paste or write idea]    # From freeform text
-  /dgs:new-project --auto <spec-id>                # From finalized spec
-  /dgs:new-project --auto @${project_root}/specs/X.md    # From spec file path
-
-The argument should be an idea document, freeform text, or a finalized spec.
-```
-
-**Spec-driven mode:**
-
-If the `--auto` argument references a spec file path or spec ID:
-1. Read the spec file (either from the provided path or by looking up via `node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs list --status final`)
-2. Validate the spec has `status: final` — if not, error: "Spec must be finalized before creating a project. Run /dgs:write-spec to complete it."
-3. Enter spec-driven flow (Steps 2b-2c below) instead of the standard auto flow
-
-**Detection:** If the argument after `--auto` contains `spec-` or ends with `.md` and exists in `${project_root}/specs/`, treat it as a spec reference. Otherwise, treat as a freeform document (existing behavior).
-</auto_mode>
-
 <process>
 
 ## 1. Setup
@@ -58,10 +15,24 @@ If the `--auto` argument references a spec file path or spec ID:
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
 ```bash
-INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project)
+# Extract the first non-flag token from $ARGUMENTS as the project slug/name.
+# If none, fall back to legacy no-arg behaviour (resolves against current_project).
+SLUG_ARG=""
+for tok in $ARGUMENTS; do
+  case "$tok" in
+    --*) ;;  # skip flags like --auto (handled later)
+    *) SLUG_ARG="$tok"; break ;;
+  esac
+done
+
+if [ -n "$SLUG_ARG" ]; then
+  INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project "$SLUG_ARG")
+else
+  INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init new-project)
+fi
 ```
 
-Parse JSON for: `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`.
+Parse JSON for: `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `state_path`, `requested_slug`, `current_project`.
 
 Load planning-tier context files:
 
@@ -69,7 +40,11 @@ Load planning-tier context files:
 TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
 ```
 
-**If `project_exists` is true:** Error — project already initialized. Use `/dgs:progress`.
+**If `project_exists` is true:** A project already exists at `${project_path}`.
+- If you intended to work on it: run `/dgs:progress` (or `/dgs:switch-project <slug>` if it differs from the active project).
+- If you intended to create a *different* project: re-invoke as `/dgs:new-project <new-slug>` with a slug that doesn't yet exist.
+
+Exit the command.
 
 **Config validation:** If `project_exists` is false, check that config has workflow preferences:
 
@@ -90,8 +65,6 @@ git init
 
 ## 2. Brownfield Offer
 
-**If auto mode:** Skip to Step 4 (assume greenfield, synthesize PROJECT.md from provided document).
-
 **If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
 
 Use AskUserQuestion:
@@ -109,300 +82,65 @@ Exit command.
 
 **If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
 
-## 2a. Auto Mode Config (auto mode only)
-
-**If auto mode:** Use existing product config (set during `/dgs:init-product`). No config questions needed here.
-
-Proceed to Step 4 (skip Step 3).
-
-## 2b. Spec-Driven Project Creation (spec-driven auto mode only)
-
-**Triggered when:** `--auto` argument references a spec file.
-
-### Parse the Spec
-
-Read the spec file and extract:
-- **Title** → becomes project name (slugified for folder name)
-- **Problem** section → project description / core value
-- **Goals** section → project goals
-- **Non-Goals** section → out of scope
-- **Requirements** (P0/P1/P2) → requirements hypotheses for PROJECT.md
-- **User Stories** → inform requirement specificity
-- **Technical Considerations** → inform research/architecture
-- **"Repos likely touched"** or similar section → repos for cross-checking (Step 2c)
-
-### Derive Project Name
-
-Extract from spec title. Slugify for the project folder name. Example: "Review Configuration System" → `review-configuration-system`.
-
-### Write PROJECT.md
-
-Create `${project_path}` with standard template structure, but derived entirely from the spec:
-
-```markdown
-# [Spec Title]
-
-## Vision
-
-[Derived from spec Problem + Goals sections]
-
-## Core Value
-
-[Extracted from the spec's Problem section — the ONE thing this solves]
-
-## Source Spec
-
-`[relative path to spec file]`
-
-## Requirements
-
-### Validated
-
-(None yet — ship to validate)
-
-### Active
-
-[Requirements derived from spec P0 + P1 sections, each as a checkbox item]
-
-### Out of Scope
-
-[From spec Non-Goals + P2 requirements explicitly deferred]
-
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| Spec-driven creation | Auto-generated from [spec id] | — |
-```
-
-**Important:** Transform spec requirements into standard DGS format:
-- Each spec requirement becomes a user-centric statement: "User can X"
-- Group by logical category
-- Do NOT copy verbatim — restructure for project planning context
-- Add a `Source spec: [path]` line to PROJECT.md (per user decision — reference, not copy)
-
-### Commit and Continue
-
-Commit PROJECT.md, then proceed to Done.
-
-**Branch name preview:** After the project folder is created, if `branching_strategy` is not `"none"`, show:
-```
-Branch names will look like: dgs/{project-slug}/phase-03-auth
-```
-
-After PROJECT.md is committed, proceed to Step 5 (Done).
-
-## 2c. Repo Cross-Check (spec-driven mode, v2 only)
-
-**Triggered when:** spec-driven mode AND v2 install (REPOS.md exists).
-
-### Extract Repos from Spec
-
-Parse the spec body for a "Repos likely touched" or "Technical Considerations" section. Extract any repo names mentioned.
-
-### Load Registered Repos
-
-```bash
-REPOS_JSON=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos list --raw)
-```
-
-Parse the JSON to get the list of registered repo names.
-
-### Compare
-
-For each repo name mentioned in the spec:
-- If it exists in REPOS.md registered repos → OK (no action)
-- If NOT registered → add to unregistered list
-
-### Handle Unregistered Repos
+## 3. Write PROJECT.md
 
-If any unregistered repos found, display a blocking warning:
+**Reject `--auto`:**
 
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► REPO CHECK
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Read `$ARGUMENTS`. If it contains `--auto` anywhere, print this error and exit:
 
-The spec references repos not registered with this product:
 ```
+Error: --auto is no longer supported for /dgs:new-project.
 
-For EACH unregistered repo, use AskUserQuestion:
+Projects are now thin holders. Create specs with /dgs:write-spec and run
+milestones with /dgs:new-milestone --auto <spec-id>.
 
-```
-AskUserQuestion([{
-  question: "Repo '{repo_name}' is not registered. How should we handle it?",
-  header: "Repo",
-  multiSelect: false,
-  options: [
-    { label: "Continue", description: "Proceed without registering this repo" },
-    { label: "Register existing", description: "Register an already-existing repo at this path" },
-    { label: "Create + Register", description: "Create folder, git init, and register" },
-    { label: "Cancel", description: "Stop project creation" }
-  ]
-}])
+Usage: /dgs:new-project [<name>]
 ```
 
-**Handle each choice:**
+**Collect the project name:**
 
-- **Continue:** Skip this repo, proceed to next
-- **Register existing:** Ask for path (suggest `../{repo_name}`), then run:
-  ```bash
-  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "{path}" --name "{repo_name}"
-  ```
-- **Create + Register:**
-  ```bash
-  mkdir -p ../{repo_name}
-  cd ../{repo_name} && git init
-  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs repos add "../{repo_name}" --name "{repo_name}"
-  ```
-- **Cancel:** Stop project creation entirely with message: "Project creation cancelled. Resolve repo registration and try again."
+Strip flags from `$ARGUMENTS`. If any non-flag tokens remain:
+- First token is the slug (already passed to `init new-project` in Step 1).
+- Remaining tokens, joined with spaces, are the human-readable name.
+- If only the slug was supplied (no name tokens), use the slug verbatim as the name.
 
-After all repos handled, continue to Step 2b (or back to the standard flow).
+Otherwise (no non-flag tokens in `$ARGUMENTS`), ask exactly ONE inline freeform question for the name. Per `references/questioning.md`'s `<freeform_rule>`, AskUserQuestion is NOT used for single freeform strings — just prompt inline and read the next user message.
 
-If no unregistered repos OR not v2: skip silently.
+**Concrete implementation (the ONLY path — do not use AskUserQuestion here):**
 
-## 3. Deep Questioning
-
-**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
-
-**Display stage banner:**
+Output the prompt verbatim:
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DGS ► QUESTIONING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Open the conversation:**
-
-Ask inline (freeform, NOT AskUserQuestion):
-
-"What do you want to build?"
-
-Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
-
-**Follow the thread:**
-
-Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
-
-Keep following threads. Each answer opens new threads to explore. Ask about:
-- What excited them
-- What problem sparked this
-- What they mean by vague terms
-- What it would actually look like
-- What's already decided
-
-Consult `questioning.md` for techniques:
-- Challenge vagueness
-- Make abstract concrete
-- Surface assumptions
-- Find edges
-- Reveal motivation
-
-**Check context (background, not out loud):**
-
-As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
-
-**Decision gate:**
-
-When you could write a clear PROJECT.md, use AskUserQuestion:
-
-- 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.
-
-## 4. Write PROJECT.md
-
-**If auto mode:** Synthesize from provided document. No "Ready?" gate was shown — proceed directly to commit.
-
-Synthesize all context into `${project_path}` using the template from `templates/project.md`.
-
-**For greenfield projects:**
-
-Initialize requirements as hypotheses:
-
-```markdown
-## Requirements
-
-### Validated
-
-(None yet — ship to validate)
-
-### Active
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
+What should I name this project? (one freeform line)
 ```
 
-All Active requirements are hypotheses until shipped and validated.
-
-**For brownfield projects (codebase map exists):**
-
-Infer Validated requirements from existing code:
-
-1. Read `${project_root}/codebase/ARCHITECTURE.md` and `STACK.md`
-2. Identify what the codebase already does
-3. These become the initial Validated set
+Then wait for the user's next message and treat the full message content (trimmed) as the project name. Do not ask any follow-ups.
 
-```markdown
-## Requirements
+**Slugify for folder:**
 
-### Validated
+If `$SLUG_ARG` was supplied in Step 1, the slug is already determined (init normalized it via `generateSlugInternal`). Otherwise slugify the collected name (lowercase, spaces→`-`, strip non-alphanumeric except `-`). Either way, `${project_path}` from the init output is the source of truth — write to it.
 
-- ✓ [Existing capability 1] — existing
-- ✓ [Existing capability 2] — existing
-- ✓ [Existing capability 3] — existing
+**Determine `${project_path}`** from init output (already set by `init new-project`).
 
-### Active
+**Write the thin skeleton:**
 
-- [ ] [New requirement 1]
-- [ ] [New requirement 2]
+Write `${project_path}` with exactly:
 
-### Out of Scope
-
-- [Exclusion 1] — [why]
 ```
+# <Project Name>
 
-**Key Decisions:**
-
-Initialize with any decisions made during questioning:
-
-```markdown
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice from questioning] | [Why] | — Pending |
-```
-
-**Last updated footer:**
-
-```markdown
----
-*Last updated: [date] after initialization*
+<One-line purpose — fill in to anchor this project.>
 ```
 
-Do not compress. Capture everything gathered.
+(newline at end of file; no other sections).
 
-**Commit PROJECT.md:**
+**Commit:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --push --files ${project_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project <name>" --push --files ${project_path}
 ```
 
-## 5. Done
+## 4. Done
 
 Present completion summary:
 
@@ -419,41 +157,32 @@ Present completion summary:
 
 ## Next Up
 
-**Start your first milestone:**
+**Capture what you're building as a spec:**
 
-`/dgs:new-milestone`
+`/dgs:write-spec`
 
-<sub>`/clear` first - fresh context window</sub>
-```
+Once your spec is final, run `/dgs:new-milestone --auto <spec-id>` to start the first milestone.
 
-**If spec-driven mode**, add:
-
-```
-**Created from spec:** {spec_id} -- "{spec_title}"
-
-**Start first milestone from this spec:**
-
-`/dgs:new-milestone --auto <spec-id>`
+<sub>`/clear` first - fresh context window</sub>
 ```
 
 </process>
 
 <output>
 
-- `${project_path}`
+- `${project_path}` — thin skeleton PROJECT.md (title + one-liner)
 - `${config_path}` (from init-product, not created here)
 
 </output>
 
 <success_criteria>
 
-- [ ] Planning root directory created
-- [ ] Git repo initialized
-- [ ] Brownfield detection completed
-- [ ] Deep questioning completed (threads followed, not rushed)
-- [ ] PROJECT.md captures full context -- **committed**
+- [ ] Planning root directory created (or detected)
+- [ ] Git repo initialized (if missing)
+- [ ] Brownfield detection offered (if existing code detected)
+- [ ] PROJECT.md created as thin skeleton (title + one-liner only) — **committed**
 - [ ] Product config validated
-- [ ] User knows next step is `/dgs:new-milestone`
+- [ ] User knows next step is `/dgs:write-spec`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
 

package/deliver-great-systems/workflows/package-scan.md

@@ -0,0 +1,59 @@
+<purpose>
+Run the DGS package-dependency-scan pipeline: detect each repo's ecosystem, select a scan tool via the Snyk → OSV-Scanner → native cascade, invoke the tool per target, normalise findings into canonical `pkg-NNN` shape, write a markdown report with YAML frontmatter to the appropriate lifecycle-aware location, and commit it atomically.
+
+The CLI (`dgs-tools package-scan`) is the orchestration surface; this workflow is the slash-command wrapper that invokes the CLI and surfaces the result back to the user.
+</purpose>
+
+<context_tier>none</context_tier>
+
+<process>
+
+<step name="run-scan" priority="first">
+Invoke the package-scan CLI. This composes runScan (scan orchestration), writePackageScanReport (markdown + YAML emission), and an atomic `dgs-tools commit --files` (report committed to the planning repo).
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs package-scan
+```
+
+**Expected output (success):**
+```
+Wrote {report-path} ({N} findings, tool: {tool-string}).
+```
+
+Where `{tool-string}` is `snyk`, `osv-scanner`, `npm-audit`, `pip-audit`, `govulncheck`, `bundler-audit`, `mixed` (different repos used different tools), or `none` (no tool ran — e.g., all repos had no manifests).
+
+**Expected output (pinned tool unavailable):**
+```
+Scan failed: tool_unavailable_on_pin — Install {tool-name}...
+```
+Exit code non-zero; no report written; no commit attempted.
+
+**Expected output (commit failure, report still written):**
+```
+Wrote {report-path} ({N} findings, tool: {tool-string}).
+Commit failed (report still on disk at {path}): <stderr>
+```
+Exit code 0 (scan itself succeeded); user can commit the report manually.
+
+**Report placement** (resolved inside the CLI):
+1. Active phase (`config.local.json execution.active_context` points at a valid phase directory) → `{phase-dir}/{phase-number}-PACKAGE-SCAN.md`
+2. Active milestone (slug only) → `{planning-root}/milestones/v{X}.{Y}-PACKAGE-SCAN.md`
+3. No active context → `{planning-root}/PACKAGE-SCAN-{YYYY-MM-DD-HHmm}.md`
+
+</step>
+
+<step name="present-result">
+Show the user the report path and a one-line summary:
+
+- If exit code 0: `Report written to: {path} — {N} findings`. Suggest `cat {path}` to review.
+- If exit code non-zero: surface the diagnostic and exit the workflow. The user's next action is documented in the scan's stderr (install hint, config fix, etc.).
+
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `dgs-tools package-scan` exits 0 OR exits non-zero with a documented diagnostic (pinned tool unavailable, setup error)
+- [ ] On exit 0: a report file exists at the resolved path AND is committed (or reported as commit-failed with the report still on disk)
+- [ ] User sees the report path and finding count
+</success_criteria>

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

@@ -180,6 +180,23 @@ If `context_path` is not null, display: `Using phase context from: ${context_pat
 
 **If `context_path` is null (no CONTEXT.md exists):**
 
+Before giving up on context, check if the current milestone was created from a spec. Read PROJECT.md and look for a `**Source Spec:**` line:
+
+```bash
+PROJECT_MD="${project_root}/PROJECT.md"
+SOURCE_SPEC=""
+if [ -f "$PROJECT_MD" ]; then
+  SOURCE_SPEC=$(grep -oP '\*\*Source Spec:\*\*\s*`?\K[^`\s]+' "$PROJECT_MD" 2>/dev/null || true)
+fi
+```
+
+Resolve `SOURCE_SPEC` relative to the planning root. If it exists as a file, set `PRD_FILE` to that path and jump to step 3.5 (PRD Express Path) to auto-generate CONTEXT.md from the spec. Log:
+```
+[AUTO-RESOLVE] No CONTEXT.md — found source spec in PROJECT.md, generating via PRD Express Path
+```
+
+**If no source spec found (or file doesn't exist):**
+
 **If `NON_INTERACTIVE` is true:**
 Log: `[AUTO-RESOLVE] No CONTEXT.md — continuing with research and requirements only`
 Continue to step 5 (skip the AskUserQuestion entirely).
@@ -459,10 +476,70 @@ Task(
 
 ## 9. Handle Planner Return
 
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
+- **`## PLANNING COMPLETE`:** Display plan count. **Then run Step 9.5
+  (orchestrator commit + verification) BEFORE proceeding.** If
+  `--skip-verify` or `plan_checker_enabled` is false (from init): skip
+  to step 13. Otherwise: step 10.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
 - **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
 
+## Step 9.5 Commit planner-created files (REL-01)
+
+Per spec AGENT-01, the planner emits a `### Created Files` list under
+`## PLANNING COMPLETE` rather than running the commit itself. This step
+performs the commit in shell-loop control flow where it cannot be
+silently skipped, and verifies every reported file appears in HEAD.
+
+1. **Parse the planner output** for the `### Created Files` markdown
+   bullet list. Tolerant parsing accepts any of these forms:
+   a. `### Created Files` header followed by a bulleted list (canonical)
+   b. `## Created Files` header (drift-tolerant)
+   c. A `created_files:` YAML block (drift-tolerant fallback)
+
+   Extract a string array of paths (one path per bullet, leading `- `
+   stripped). If no list is found OR the list is empty, exit the
+   workflow with exit-code label `plan-commit-incomplete` and the
+   user-facing message:
+
+   ```
+   [plan-commit-incomplete] Plan-phase failed: planner did not emit a
+     Created Files list. Working tree left for inspection.
+     To retry once the underlying issue is resolved:
+       /dgs:plan-phase {PHASE} --skip-research
+   ```
+
+2. **Compose the commit invocation** using `dgs-tools commit-verify-plan`:
+
+   ```bash
+   COMMIT_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" \
+     commit-verify-plan "docs(${padded_phase}): create phase plan" \
+     --files "${created_files[@]}" \
+     --extra-files "${roadmap_path}" \
+     --push --raw)
+   OK=$(echo "$COMMIT_RESULT" | jq -r '.ok')
+   ```
+
+3. **On `OK !== true`** — fail loudly per the spec's clauses (a)–(d)
+   (non-zero exit, working tree unchanged, 1–3 line user-facing
+   message, discoverable via `dgs-tools health`):
+
+   ```bash
+   EXIT_LABEL=$(echo "$COMMIT_RESULT" | jq -r '.exitLabel')
+   REASON=$(echo "$COMMIT_RESULT" | jq -r '.reason')
+   echo "[${EXIT_LABEL}] /dgs:plan-phase failed at the orchestrator commit step (reason: ${REASON})"
+   echo "[${EXIT_LABEL}] Working tree is left for inspection. To diagnose: 'git status' under ${phase_dir}/"
+   echo "[${EXIT_LABEL}] To retry once the underlying issue is resolved: /dgs:plan-phase ${PHASE} --skip-research"
+   exit 1
+   ```
+
+4. **On `OK === true` with `reason === 'skipped_commit_docs_false'`:**
+   log silently (`commit_docs config disabled — skipping commit step`)
+   and continue to step 10 / 13.
+
+5. **On `OK === true` with `reason === 'committed'`:** log
+   `Plans committed: ${HASH} (verified ${N} reported files)` and
+   continue to step 10 / 13.
+
 ## 10. Spawn dgs-plan-checker Agent
 
 ### Discover prior phase SUMMARYs for continuity context (GAP-02)
@@ -691,6 +768,7 @@ Verification: {Passed | Passed with override | Skipped}
 - [ ] Existing plans checked
 - [ ] dgs-planner spawned with CONTEXT.md + RESEARCH.md
 - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
+- [ ] Orchestrator commits planner-reported `created_files` via `dgs-tools commit-verify-plan` (REL-01); on mismatch, exits `plan-commit-incomplete` with working tree unchanged
 - [ ] dgs-plan-checker spawned with CONTEXT.md
 - [ ] Verification passed OR user override OR max iterations with user decision
 - [ ] User sees status between agent spawns