@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/refine-spec.md

@@ -0,0 +1,275 @@
+<purpose>
+Structured conversational workflow for iteratively refining a spec through dialogue. Loads the spec, presents a summary, then conducts a multi-turn editing session where Claude acts as a collaborative thinking partner -- proposing changes, pushing back on conflicts, and referencing codebase context. All changes are accumulated in working memory and written atomically at the end of the session.
+
+Supports section targeting with `--section` to focus on a single section, version increment on save (+0.1), and warns when refining a final-status spec (which moves it back to draft). Appends a "Refined" entry to the Refinement Log and commits the result.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load planning context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+```
+
+Extract: `project_root`, `config_path` as needed by the workflow.
+
+Load planning-tier context files (spec scope added after slug is parsed):
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+</step>
+
+<step name="parse_arguments">
+Extract the spec slug and optional flags from `$ARGUMENTS`.
+
+**Spec slug extraction:**
+- The first positional argument is the spec slug (required).
+- If no argument is provided, display an error and stop:
+  ```
+  Usage: /dgs:refine-spec <spec-slug> [--section <N>]
+  ```
+- Store the value as `SPEC_SLUG`.
+
+**Section flag extraction:**
+- Scan `$ARGUMENTS` for `--section` followed by a value.
+- If `--section` is present with a value (number or name): store as `SECTION_TARGET`.
+- If `--section` is present with no value: display an error and stop:
+  ```
+  Usage: --section requires a section number or name.
+  ```
+- If `--section` is absent: `SECTION_TARGET` is null (refine entire spec).
+</step>
+
+<step name="load_spec">
+Find the spec and load its full content.
+
+1. Run the validate command to locate the spec and get its identity:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs validate --id "$SPEC_SLUG"
+   ```
+2. Parse the JSON output to extract: `id`, `path`, and frontmatter fields.
+3. Read the spec file directly using the Read tool to get the full content.
+4. Parse the content:
+   - **Status** (after normalization): `draft` or `final`
+   - **Version** (default `0.1` if not present)
+   - **approved_date** (if present)
+   - **Title**
+   - **Body** (everything after frontmatter)
+5. Build a section index from `## ` headings in the body:
+   ```
+   [{ number: 1, name: "Problem", startLine: N, endLine: M }, ...]
+   ```
+   Each section runs from its `## ` heading (inclusive) to the line before the next `## ` heading (exclusive) or end of body.
+</step>
+
+<step name="final_status_warning" condition="status === final">
+If the spec's status is `final`:
+
+1. Display a warning:
+   ```
+   This spec is approved (v{version}, approved {approved_date}). Refinement will move it back to draft.
+   ```
+2. Use AskUserQuestion: "Proceed with refinement? (yes/no)"
+3. If the user declines (answers "no", "n", or "cancel"):
+   - Display: "Refinement cancelled."
+   - Stop execution.
+4. If the user confirms (answers "yes", "y", or any affirmative):
+   - Set `WAS_FINAL = true` for use in the atomic save step.
+
+If the spec's status is `draft`: proceed without warning.
+</step>
+
+<step name="load_context">
+Read all codebase analysis documents:
+
+```bash
+ls ${project_root}/codebase/*.md 2>/dev/null
+```
+
+For each `.md` file found, read it using the Read tool. If the codebase directory does not exist or contains no `.md` files, proceed without codebase context.
+
+Also load product docs:
+
+```bash
+ls ${project_root}/docs/product/*.md 2>/dev/null
+```
+
+Read each markdown file found. If the directory does not exist, proceed without it.
+
+Context is used to inform the conversation -- for example, when discussing implementation notes, Claude can reference real architecture and stack choices.
+
+**Load spec supporting documents:**
+
+1. Derive the spec's docs directory path:
+   ```bash
+   SPEC_DOCS_DIR="$(dirname "${SPEC_FILE_PATH}")/docs"
+   ```
+   Or derive from spec slug: `${project_root}/specs/${SPEC_SLUG}/docs`
+
+2. If the docs/ directory exists, read all files following the docs/ loading pattern:
+   - **Text files** (.md, .txt, .json, .yaml, .yml): Read with Read tool
+   - **Image files** (.png, .jpg, .jpeg, .gif, .svg, .webp): Read with Read tool (multimodal). Cap at 5 images.
+   - **PDF files** (.pdf): Prefer .txt sidecar, fallback to 5 pages of PDF via Read tool
+   - **Other files**: skip silently
+   - If docs/ does not exist: silent skip
+   - If any file is unreadable: skip silently
+
+3. Load source idea docs:
+   Read the spec's frontmatter to find `source_ideas` (array of idea filenames). For each source idea:
+   a. Derive the idea docs path (same pattern as write-spec: strip prefix/suffix for slug, check `${project_root}/ideas/pending/{slug}/docs/` or done/rejected paths)
+   b. If docs/ directory exists, read all files using the same pattern above
+   c. Idea docs are loaded first (source material), then spec docs (refinements). If too many, cap spec docs.
+
+Total file cap: read up to 10 text docs + 5 images across all docs/ directories. If more exist, prioritize spec docs over idea docs (idea docs are source material already incorporated; spec docs are newer refinements).
+</step>
+
+<step name="present_summary">
+Display a summary header for the spec:
+
+```
+## Refining: {title}
+
+Status: {status} | Version: {version} | Sections: {count}
+{If open questions section exists: "Open questions: present"}
+{If milestones linked: "Milestones: {list}"}
+```
+
+**If `--section` is set (section-targeted mode):**
+
+1. Validate the section target exists:
+   - If `SECTION_TARGET` is a number: look up by 1-based index in the section index.
+   - If `SECTION_TARGET` is a name: match by case-insensitive substring against heading text.
+2. If not found:
+   - Display: "Section not found. Available sections:" followed by a numbered list of all sections.
+   - Stop execution.
+3. If the name matches multiple sections: use the first match and inform the user which section was selected.
+4. Display only the targeted section content.
+5. Tell the user: "Focusing on section {N}: {name}"
+6. Ask using AskUserQuestion: "What would you like to change in this section?"
+
+**If no `--section` (full-spec mode):**
+
+1. Display a numbered section list.
+2. Ask using AskUserQuestion: "What would you like to refine? (describe changes, or enter a section number to focus)"
+</step>
+
+<step name="conversational_refinement">
+Enter an interactive dialogue using AskUserQuestion for each turn of conversation.
+
+**Tone: Collaborative thinking partner -- like a cofounder reviewing a spec.**
+
+- Propose specific textual changes with reasoning (e.g., "I'd rephrase this requirement to..." with an explanation of why).
+- Push back when proposed changes conflict with existing requirements or when removing something that seems important.
+- Reference codebase context (from load_context step) when discussing implementation notes or technical decisions.
+- Ask clarifying questions when the user's request is ambiguous.
+- Adapt depth to change scope: quick fix = 1-2 exchanges, major restructuring = many exchanges.
+
+**Accumulation rule:** Claude tracks all agreed changes in working memory. Does NOT write to disk during the conversation. The spec file on disk remains unchanged until the atomic save step.
+
+**Multiple rounds expected.** Continue the conversation until the user indicates they are done.
+
+**Exit signal detection:**
+- User says "done", "save", "that's all", "looks good", "ship it", or similar affirmative completion phrases: proceed to generate_summary step.
+- User says "cancel" or "abort": discard all changes, display "Refinement cancelled. No changes saved." and stop execution.
+- "Cancel" means discard; "done" means save. These are distinct exit signals.
+</step>
+
+<step name="generate_summary">
+Generate a brief (1-2 sentence) summary of what changed during the session.
+
+This summary becomes the `summary` parameter for `add-log-entry` and appears in the commit message.
+
+**Examples:**
+- "Clarified P0 requirements for error handling, added caching non-goal, expanded implementation notes"
+- "Tightened success metrics with quantitative thresholds, removed duplicate user story"
+- "Refined section 5: Requirements -- narrowed P0 scope to three core features"
+
+If a section was targeted via `--section`, note which section in the summary (e.g., "Refined section 5: Requirements -- ...").
+</step>
+
+<step name="atomic_save">
+All writes happen here, atomically at the end of the session. No file changes occur before this step.
+
+1. **Re-read the current spec file from disk** using the Read tool. This ensures we have the latest content, including any frontmatter that may have been modified by other processes.
+
+2. **Detect the format** from the content:
+   - YAML frontmatter: file starts with `---`
+   - Bold-key format: file starts with `**id:**` or similar bold-key lines
+   - Use the detected format for write-back.
+
+3. **Parse the frontmatter** from the re-read content.
+
+4. **Compute the new version:**
+   - Read the current version from frontmatter (default `0.1` if not present).
+   - Strip any `v` prefix if present (e.g., `v0.1` -> `0.1`).
+   - Treat an integer without decimal as `N.0` (e.g., `1` -> `1.0`).
+   - Compute: `(parseFloat(currentVersion) + 0.1).toFixed(1)`.
+   - Store as `NEW_VERSION`.
+
+5. **Update frontmatter fields:**
+   - `version` = `NEW_VERSION`
+   - `status` = `draft` (only if `WAS_FINAL` is true; otherwise leave unchanged)
+   - `updated` = today's date in `YYYY-MM-DD` format
+   - Preserve all other frontmatter fields unchanged (id, title, author, approved_date, milestones, etc.)
+   - Note: `approved_date` is NOT cleared -- per Phase 92 decision, it records when the spec was last approved.
+
+6. **Replace the body with the refined version:**
+   - If `--section` was used: splice the modified section back into the full body at the correct position. All other sections remain exactly as-is. Match section boundaries from the section index built in load_spec.
+   - If no `--section`: replace the entire body with the accumulated changes.
+
+7. **Reconstruct the complete file** using the detected format:
+   - YAML format: `---\n{yaml frontmatter}\n---\n\n{body}`
+   - Bold-key format: `{bold-key lines}\n\n{body}`
+
+8. **Write the file** using the Write tool.
+
+9. **Append the Refinement Log entry:**
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id "$SPEC_SLUG" --date "$(date +%Y-%m-%d)" --version "$NEW_VERSION" --action Refined --summary "$SUMMARY"
+   ```
+
+10. **Commit the changes:**
+    ```bash
+    node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "refine(spec): $SPEC_SLUG v$NEW_VERSION -- $SUMMARY" --files "$SPEC_FILE_PATH"
+    ```
+</step>
+
+<step name="confirmation">
+Display the refinement confirmation:
+
+```
+Spec refined: {title} (v{new-version})
+```
+
+If the spec was moved from final back to draft (i.e., `WAS_FINAL` was true):
+```
+Note: Moved from final back to draft.
+```
+
+Suggest next steps:
+```
+Run /dgs:approve-spec {spec-slug} when you're ready to approve the updated spec.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Spec body updated with agreed changes
+- [ ] Version incremented (minor +0.1)
+- [ ] Refinement Log entry with "Refined" action appended
+- [ ] Section targeting works (--section by number or name)
+- [ ] Final-status specs show demotion warning before proceeding
+- [ ] Cancelled sessions make no file changes
+- [ ] All changes written atomically at save step
+- [ ] Changes committed to git
+</success_criteria>

package/deliver-great-systems/workflows/reject-idea.md

@@ -0,0 +1,109 @@
+<purpose>
+Reject a pending idea by moving it from pending/ to rejected/ state. Confirmation is always required (no --force bypass). An optional rejection reason is prompted and appended to the idea file body for audit history.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="parse_arguments">
+Extract idea ID from arguments (first positional arg).
+
+If no ID provided, list pending ideas and prompt user to select one:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending
+```
+Parse JSON result and display pending ideas. Use AskUserQuestion to let user pick an idea by ID.
+</step>
+
+<step name="find_and_display_idea">
+Find the idea by ID among pending ideas:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending
+```
+
+Parse the JSON result and locate the idea matching the provided ID.
+
+Read the idea file to get its title and first few lines of content:
+```bash
+cat ${path}
+```
+
+Display the idea title and a preview of its content so the user knows what they are rejecting.
+
+If idea not found in pending, error:
+```
+Idea #${id} not found in pending ideas. Only pending ideas can be rejected.
+```
+Stop execution.
+</step>
+
+<step name="confirm">
+Confirmation is always required. There is no --force flag to skip this step.
+
+Use AskUserQuestion:
+- header: "Reject Idea #${id}?"
+- question: "Are you sure you want to reject '${title}'?"
+- options: "Yes, reject it", "No, cancel"
+
+If user selects "No, cancel":
+Output: `Cancelled.`
+Stop execution.
+</step>
+
+<step name="ask_reason">
+Prompt for an optional rejection reason.
+
+Use AskUserQuestion:
+- header: "Rejection Reason"
+- question: "Why are you rejecting this idea? (optional, press Enter to skip)"
+
+Allow empty/skip response. If the user provides a reason, it will be appended to the idea file body by the ideas module.
+</step>
+
+<step name="execute_rejection">
+Execute the rejection via dgs-tools:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas reject --id "${id}" --reason "${reason}"
+```
+
+If no reason was provided, omit the `--reason` flag:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas reject --id "${id}"
+```
+
+The ideas.cjs module handles:
+- Appending rejection reason to the idea file body (if provided)
+- Moving the file from pending/ to rejected/ via git mv
+- Creating an auto-commit for the state transition
+</step>
+
+<step name="confirm_output">
+Output: `Idea #${id} rejected.`
+
+If a reason was provided, also show: `Reason: ${reason}`
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Confirmation required before rejection (no --force bypass)
+- [ ] Rejection reason prompted (optional, can be skipped)
+- [ ] File moved from pending/ to rejected/ via git mv
+- [ ] Reason appended to file body if provided
+- [ ] Git commit created automatically for the state transition
+</success_criteria>

package/deliver-great-systems/workflows/remove-doc.md

@@ -0,0 +1,117 @@
+<purpose>
+Remove a document from its scope or move it between scopes. Removal requires mandatory confirmation (no --force bypass) and cleans up all sidecars (.extracted.txt, .summary.txt) plus updates INDEX.md. Move mode relocates a document with its sidecars between scopes via --move flag.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="parse_arguments">
+Parse `$ARGUMENTS` for required and optional flags:
+
+**Required:**
+- `slug`: first positional argument (the document slug, e.g., `q4-budget.pdf`)
+- `--scope <product|idea|spec>`: the scope containing the document
+- `--scope-id <id>`: (optional for product scope, required for idea/spec)
+
+**Optional move flags:**
+- `--move`: flag indicating move mode instead of remove
+- `--to-scope <product|idea|spec>`: target scope for move
+- `--to-id <id>`: target scope ID for move (required for idea/spec targets)
+
+Determine mode:
+- If `--move` flag detected: set `mode = move`
+  - Validate `--to-scope` is provided (error if missing: "Move requires --to-scope flag.")
+  - Validate `--to-id` is provided if to-scope is idea or spec (error if missing)
+- Otherwise: set `mode = remove`
+
+If slug or --scope not provided, output usage hint and stop:
+```
+Usage: /dgs:remove-doc <slug> --scope <product|idea|spec> [--scope-id <id>]
+       /dgs:remove-doc <slug> --scope <scope> --move --to-scope <scope> --to-id <id>
+```
+</step>
+
+<step name="find_document">
+Verify the document exists in the specified scope:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs docs check-duplicate --scope "$scope" --scope-id "$scope_id" --slug "$slug"
+```
+
+Parse JSON result. If the document is not found (`exists: false`):
+- Output: "Document '{slug}' not found in {scope}." and stop
+
+If found, note the document details for confirmation display.
+</step>
+
+<step name="confirm" condition="mode = remove">
+Mandatory confirmation before removal. There is no --force flag to skip this step.
+
+Use AskUserQuestion:
+- question: "Remove '{slug}' from {scope}? This will delete the file and all sidecars (.extracted.txt, .summary.txt). (yes/no)"
+
+If user says no or cancels:
+- Output: "Cancelled." and stop
+</step>
+
+<step name="execute_remove" condition="mode = remove">
+Remove the document and all sidecars via dgs-tools:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs docs remove --scope "$scope" --scope-id "$scope_id" --slug "$slug"
+```
+
+Parse the result for `files_removed` (list of removed files) and `index_updated` (path to updated INDEX.md).
+
+Then git commit:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: remove ${slug} from ${scope}" --files <removed files and updated INDEX.md>
+```
+
+Output: "Document '{slug}' removed from {scope}."
+</step>
+
+<step name="execute_move" condition="mode = move">
+Move the document and all sidecars between scopes via dgs-tools:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs docs move --slug "$slug" --from-scope "$scope" --from-id "$scope_id" --to-scope "$to_scope" --to-id "$to_id"
+```
+
+Parse the result for `files_moved` (list of moved files) and `indexes_updated` (source and target INDEX.md paths).
+
+Then git commit:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: move ${slug} from ${scope} to ${to_scope}" --files <moved files and updated INDEX.md files>
+```
+
+Output: "Document '{slug}' moved from {scope} to {to_scope}/{to_id}."
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Arguments parsed correctly with mode detection (remove vs move)
+- [ ] Document existence verified before action
+- [ ] Confirmation required for removal (no --force bypass)
+- [ ] Removal deletes document + all sidecars + updates INDEX.md
+- [ ] Move relocates document + sidecars between scopes + updates both INDEX.md files
+- [ ] Git commit created for all affected files
+</success_criteria>

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

@@ -0,0 +1,163 @@
+<purpose>
+Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- Argument is the phase number to remove (integer or decimal)
+- Example: `/dgs:remove-phase 17` → phase = 17
+- Example: `/dgs:remove-phase 16.1` → phase = 16.1
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /dgs:remove-phase <phase-number>
+Example: /dgs:remove-phase 17
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init phase-op "${target}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Load planning-tier context files:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+
+Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
+
+Also read STATE.md and ROADMAP.md content for parsing current position.
+</step>
+
+<step name="validate_future_phase">
+Verify the phase is a future phase (not started):
+
+1. Compare target phase to current phase from STATE.md
+2. Target must be > current phase number
+
+If target <= current phase:
+
+```
+ERROR: Cannot remove Phase {target}
+
+Only future phases can be removed:
+- Current phase: {current}
+- Phase {target} is current or completed
+
+To abandon current work, use /dgs:pause-work instead.
+```
+
+Exit.
+</step>
+
+<step name="confirm_removal">
+Present removal summary and confirm:
+
+```
+Removing Phase {target}: {Name}
+
+This will:
+- Delete: ${project_root}/phases/{target}-{slug}/
+- Renumber all subsequent phases
+- Update: ROADMAP.md, STATE.md
+
+Proceed? (y/n)
+```
+
+Wait for confirmation.
+</step>
+
+<step name="execute_removal">
+**Delegate the entire removal operation to dgs-tools:**
+
+```bash
+RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase remove "${target}")
+```
+
+If the phase has executed plans (SUMMARY.md files), dgs-tools will error. Use `--force` only if the user confirms:
+
+```bash
+RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase remove "${target}" --force)
+```
+
+The CLI handles:
+- Deleting the phase directory
+- Renumbering all subsequent directories (in reverse order to avoid conflicts)
+- Renaming all files inside renumbered directories (PLAN.md, SUMMARY.md, etc.)
+- Updating ROADMAP.md (removing section, renumbering all phase references, updating dependencies)
+- Updating STATE.md (decrementing phase count)
+
+Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
+</step>
+
+<step name="commit">
+Stage and commit the removal:
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: remove phase {target} ({original-phase-name})" --files ${project_root}/
+```
+
+The commit message preserves the historical record of what was removed.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} ({original-name}) removed.
+
+Changes:
+- Deleted: ${project_root}/phases/{target}-{slug}/
+- Renumbered: {N} directories and {M} files
+- Updated: ROADMAP.md, STATE.md
+- Committed: chore: remove phase {target} ({original-name})
+
+---
+
+## What's Next
+
+Would you like to:
+- `/dgs:progress` — see updated roadmap status
+- Continue with current phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't remove completed phases (have SUMMARY.md files) without --force
+- Don't remove current or past phases
+- Don't manually renumber — use `dgs-tools phase remove` which handles all renumbering
+- Don't add "removed phase" notes to STATE.md — git commit is the record
+- Don't modify completed phase directories
+</anti_patterns>
+
+<success_criteria>
+Phase removal is complete when:
+
+- [ ] Target phase validated as future/unstarted
+- [ ] `dgs-tools phase remove` executed successfully
+- [ ] Changes committed with descriptive message
+- [ ] User informed of changes
+</success_criteria>