@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,563 @@
+<required_reading>
+
+**Read these files NOW** (paths resolved via init phase-op in load_project_state step):
+
+1. STATE.md (via `${state_path}`)
+2. PROJECT.md (via `${project_root}/PROJECT.md`)
+3. ROADMAP.md (via `${roadmap_path}`)
+4. Current phase's plan files (`${phase_dir}/*-PLAN.md`)
+5. Current phase's summary files (`${phase_dir}/*-SUMMARY.md`)
+
+</required_reading>
+
+<purpose>
+
+Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
+
+"Planning next phase" = "current phase is done"
+
+</purpose>
+
+<context_tier>execution</context_tier>
+
+<process>
+
+<step name="load_project_state" priority="first">
+
+Initialize project context and resolve paths:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init phase-op "${current_phase}")
+```
+
+Parse JSON for: `state_path`, `roadmap_path`, `requirements_path`, `phase_dir`, `phase_number`, `phase_name`, `project_root`.
+
+**Load execution tier context:**
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier execution --phase "${current_phase}" --raw 2>/dev/null)
+```
+
+Before transition, read project state:
+
+```bash
+cat ${state_path} 2>/dev/null
+cat ${project_root}/PROJECT.md 2>/dev/null
+```
+
+Parse current position to verify we're transitioning the right phase.
+Note accumulated context that may need updating after transition.
+
+</step>
+
+<step name="verify_completion">
+
+Check current phase has all plan summaries:
+
+```bash
+ls ${phase_dir}/*-PLAN.md 2>/dev/null | sort
+ls ${phase_dir}/*-SUMMARY.md 2>/dev/null | sort
+```
+
+**Verification logic:**
+
+- Count PLAN files
+- Count SUMMARY files
+- If counts match: all plans complete
+- If counts don't match: incomplete
+
+<config-check>
+
+```bash
+cat ${config_path} 2>/dev/null
+```
+
+</config-check>
+
+**If all plans complete:**
+
+<if mode="yolo">
+
+```
+⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
+Phase [X] complete — all [Y] plans finished.
+
+Proceeding to mark done and advance...
+```
+
+Proceed directly to cleanup_handoff step.
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
+
+Wait for confirmation before proceeding.
+
+</if>
+
+**If plans incomplete:**
+
+**SAFETY RAIL: always_confirm_destructive applies here.**
+Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.
+
+Present:
+
+```
+Phase [X] has incomplete plans:
+- {phase}-01-SUMMARY.md ✓ Complete
+- {phase}-02-SUMMARY.md ✗ Missing
+- {phase}-03-SUMMARY.md ✗ Missing
+
+⚠️ Safety rail: Skipping plans requires confirmation (destructive action)
+
+Options:
+1. Continue current phase (execute remaining plans)
+2. Mark complete anyway (skip remaining plans)
+3. Review what's left
+```
+
+Wait for user decision.
+
+</step>
+
+<step name="cleanup_handoff">
+
+Check for lingering handoffs:
+
+```bash
+ls ${phase_dir}/.continue-here*.md 2>/dev/null
+```
+
+If found, delete them — phase is complete, handoffs are stale.
+
+</step>
+
+<step name="update_roadmap_and_state">
+
+**Delegate ROADMAP.md and STATE.md updates to dgs-tools:**
+
+```bash
+TRANSITION=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase complete "${current_phase}")
+```
+
+The CLI handles:
+- Marking the phase checkbox as `[x]` complete with today's date
+- Updating plan count to final (e.g., "3/3 plans complete")
+- Updating the Progress table (Status → Complete, adding date)
+- Advancing STATE.md to next phase (Current Phase, Status → Ready to plan, Current Plan → Not started)
+- Detecting if this is the last phase in the milestone
+
+Extract from result: `completed_phase`, `plans_executed`, `next_phase`, `next_phase_name`, `is_last_phase`.
+
+</step>
+
+<step name="archive_prompts">
+
+If prompts were generated for the phase, they stay in place.
+The `completed/` subfolder pattern from create-meta-prompts handles archival.
+
+</step>
+
+<step name="evolve_project">
+
+Evolve PROJECT.md to reflect learnings from completed phase.
+
+**Read phase summaries:**
+
+```bash
+cat ${phase_dir}/*-SUMMARY.md
+```
+
+**Assess requirement changes:**
+
+1. **Requirements validated?**
+   - Any Active requirements shipped in this phase?
+   - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
+
+2. **Requirements invalidated?**
+   - Any Active requirements discovered to be unnecessary or wrong?
+   - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
+
+3. **Requirements emerged?**
+   - Any new requirements discovered during building?
+   - Add to Active: `- [ ] [New requirement]`
+
+4. **Decisions to log?**
+   - Extract decisions from SUMMARY.md files
+   - Add to Key Decisions table with outcome if known
+
+5. **"What This Is" still accurate?**
+   - If the product has meaningfully changed, update the description
+   - Keep it current and accurate
+
+**Update PROJECT.md:**
+
+Make the edits inline. Update "Last updated" footer:
+
+```markdown
+---
+*Last updated: [date] after Phase [X]*
+```
+
+**Example evolution:**
+
+Before:
+
+```markdown
+### Active
+
+- [ ] JWT authentication
+- [ ] Real-time sync < 500ms
+- [ ] Offline mode
+
+### Out of Scope
+
+- OAuth2 — complexity not needed for v1
+```
+
+After (Phase 2 shipped JWT auth, discovered rate limiting needed):
+
+```markdown
+### Validated
+
+- ✓ JWT authentication — Phase 2
+
+### Active
+
+- [ ] Real-time sync < 500ms
+- [ ] Offline mode
+- [ ] Rate limiting on sync endpoint
+
+### Out of Scope
+
+- OAuth2 — complexity not needed for v1
+```
+
+**Step complete when:**
+
+- [ ] Phase summaries reviewed for learnings
+- [ ] Validated requirements moved from Active
+- [ ] Invalidated requirements moved to Out of Scope with reason
+- [ ] Emerged requirements added to Active
+- [ ] New decisions logged with rationale
+- [ ] "What This Is" updated if product changed
+- [ ] "Last updated" footer reflects this transition
+
+</step>
+
+<step name="update_current_position_after_transition">
+
+**Note:** Basic position updates (Current Phase, Status, Current Plan, Last Activity) were already handled by `dgs-tools phase complete` in the update_roadmap_and_state step.
+
+Verify the updates are correct by reading STATE.md. If the progress bar needs updating, use:
+
+```bash
+PROGRESS=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" progress bar --raw)
+```
+
+Update the progress bar line in STATE.md with the result.
+
+**Step complete when:**
+
+- [ ] Phase number incremented to next phase (done by phase complete)
+- [ ] Plan status reset to "Not started" (done by phase complete)
+- [ ] Status shows "Ready to plan" (done by phase complete)
+- [ ] Progress bar reflects total completed plans
+
+</step>
+
+<step name="update_project_reference">
+
+Update Project Reference section in STATE.md.
+
+```markdown
+## Project Reference
+
+See: ${project_root}/PROJECT.md (updated [today])
+
+**Core value:** [Current core value from PROJECT.md]
+**Current focus:** [Next phase name]
+```
+
+Update the date and current focus to reflect the transition.
+
+</step>
+
+<step name="review_accumulated_context">
+
+Review and update Accumulated Context section in STATE.md.
+
+**Decisions:**
+
+- Note recent decisions from this phase (3-5 max)
+- Full log lives in PROJECT.md Key Decisions table
+
+**Blockers/Concerns:**
+
+- Review blockers from completed phase
+- If addressed in this phase: Remove from list
+- If still relevant for future: Keep with "Phase X" prefix
+- Add any new concerns from completed phase's summaries
+
+**Example:**
+
+Before:
+
+```markdown
+### Blockers/Concerns
+
+- ⚠️ [Phase 1] Database schema not indexed for common queries
+- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
+```
+
+After (if database indexing was addressed in Phase 2):
+
+```markdown
+### Blockers/Concerns
+
+- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
+```
+
+**Step complete when:**
+
+- [ ] Recent decisions noted (full log in PROJECT.md)
+- [ ] Resolved blockers removed from list
+- [ ] Unresolved blockers kept with phase prefix
+- [ ] New concerns from completed phase added
+
+</step>
+
+<step name="update_session_continuity_after_transition">
+
+Update Session Continuity section in STATE.md to reflect transition completion.
+
+**Format:**
+
+```markdown
+Last session: [today]
+Stopped at: Phase [X] complete, ready to plan Phase [X+1]
+Resume file: None
+```
+
+**Step complete when:**
+
+- [ ] Last session timestamp updated to current date and time
+- [ ] Stopped at describes phase completion and next phase
+- [ ] Resume file confirmed as None (transitions don't use resume files)
+
+</step>
+
+<step name="offer_next_phase">
+
+**MANDATORY: Verify milestone status before presenting next steps.**
+
+**Use the transition result from `dgs-tools phase complete`:**
+
+The `is_last_phase` field from the phase complete result tells you directly:
+- `is_last_phase: false` → More phases remain → Go to **Route A**
+- `is_last_phase: true` → Milestone complete → Go to **Route B**
+
+The `next_phase` and `next_phase_name` fields give you the next phase details.
+
+If you need additional context, use:
+```bash
+ROADMAP=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" roadmap analyze)
+```
+
+This returns all phases with goals, disk status, and completion info.
+
+---
+
+**Route A: More phases remain in milestone**
+
+Read ROADMAP.md to get the next phase's name and goal.
+
+**Check if next phase has CONTEXT.md:**
+
+Use dgs-tools to resolve the next phase directory (from `next_phase` returned by phase complete):
+```bash
+NEXT_PHASE_INFO=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init phase-op "${next_phase}")
+# Parse next_phase_dir from JSON, then:
+ls ${next_phase_dir}/*-CONTEXT.md 2>/dev/null
+```
+
+**If next phase exists:**
+
+<if mode="yolo">
+
+**If CONTEXT.md exists:**
+
+```
+Phase [X] marked complete.
+
+Next: Phase [X+1] — [Name]
+
+⚡ Auto-continuing: Plan Phase [X+1] in detail
+```
+
+Exit skill and invoke SlashCommand("/dgs:plan-phase [X+1] --auto")
+
+**If CONTEXT.md does NOT exist:**
+
+```
+Phase [X] marked complete.
+
+Next: Phase [X+1] — [Name]
+
+⚡ Auto-continuing: Discuss Phase [X+1] first
+```
+
+Exit skill and invoke SlashCommand("/dgs:discuss-phase [X+1] --auto")
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+**If CONTEXT.md does NOT exist:**
+
+```
+## ✓ Phase [X] Complete
+
+---
+
+## ▶ Next Up
+
+**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
+
+`/dgs:discuss-phase [X+1]` — gather context and clarify approach
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/dgs:plan-phase [X+1]` — skip discussion, plan directly
+- `/dgs:research-phase [X+1]` — investigate unknowns
+
+---
+```
+
+**If CONTEXT.md exists:**
+
+```
+## ✓ Phase [X] Complete
+
+---
+
+## ▶ Next Up
+
+**Phase [X+1]: [Name]** — [Goal from ROADMAP.md]
+<sub>✓ Context gathered, ready to plan</sub>
+
+`/dgs:plan-phase [X+1]`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/dgs:discuss-phase [X+1]` — revisit context
+- `/dgs:research-phase [X+1]` — investigate unknowns
+
+---
+```
+
+</if>
+
+---
+
+**Route B: Milestone complete (all phases done)**
+
+**Clear auto-advance chain flag** — milestone boundary is the natural stopping point:
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-set workflow._auto_chain_active false
+```
+
+<if mode="yolo">
+
+```
+Phase {X} marked complete.
+
+🎉 Milestone {version} is 100% complete — all {N} phases finished!
+
+⚡ Auto-continuing: Complete milestone and archive
+```
+
+Exit skill and invoke SlashCommand("/dgs:complete-milestone {version}")
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_transition true">
+
+```
+## ✓ Phase {X}: {Phase Name} Complete
+
+🎉 Milestone {version} is 100% complete — all {N} phases finished!
+
+---
+
+## ▶ Next Up
+
+**Complete Milestone {version}** — archive and prepare for next
+
+`/dgs:complete-milestone {version}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review accomplishments before archiving
+
+---
+```
+
+</if>
+
+</step>
+
+</process>
+
+<implicit_tracking>
+Progress tracking is IMPLICIT: planning phase N implies phases 1-(N-1) complete. No separate progress step—forward motion IS progress.
+</implicit_tracking>
+
+<partial_completion>
+
+If user wants to move on but phase isn't fully complete:
+
+```
+Phase [X] has incomplete plans:
+- {phase}-02-PLAN.md (not executed)
+- {phase}-03-PLAN.md (not executed)
+
+Options:
+1. Mark complete anyway (plans weren't needed)
+2. Defer work to later phase
+3. Stay and finish current phase
+```
+
+Respect user judgment — they know if work matters.
+
+**If marking complete with incomplete plans:**
+
+- Update ROADMAP: "2/3 plans complete" (not "3/3")
+- Note in transition message which plans were skipped
+
+</partial_completion>
+
+<success_criteria>
+
+Transition is complete when:
+
+- [ ] Current phase plan summaries verified (all exist or user chose to skip)
+- [ ] Any stale handoffs deleted
+- [ ] ROADMAP.md updated with completion status and plan count
+- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
+- [ ] STATE.md updated (position, project reference, context, session)
+- [ ] Progress table updated
+- [ ] User knows next steps
+
+</success_criteria>

package/deliver-great-systems/workflows/undo-consolidation.md

@@ -0,0 +1,155 @@
+<purpose>
+Undo a previous idea consolidation. Validates the target idea is a consolidated result (has consolidated_from), displays the affected ideas for confirmation, calls the CLI for the atomic undo operation (restore sources to pending, delete consolidated result, git commit), and shows the result.
+</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 the consolidated idea ID.
+
+- Extract the numeric positional argument as the idea ID (e.g., `/dgs:undo-consolidation 5` -> id=5)
+
+If no ID provided, find pending ideas that have `consolidated_from` and prompt for selection:
+
+```bash
+ALL=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending --raw)
+```
+
+Parse the JSON `ideas` array. For each idea, read the idea file and check if it has `consolidated_from` in its frontmatter.
+
+**If no consolidated ideas found:**
+```
+No consolidated ideas found. Nothing to undo.
+```
+Exit workflow.
+
+**If consolidated ideas exist:** Display them as a numbered list showing ID, title, and sources:
+
+```
+## Consolidated Ideas
+
+| # | ID | Title | Consolidated From |
+|---|-----|-------|-------------------|
+| 1 | 005 | Improve API resilience | #001, #003, #017 |
+```
+
+Use AskUserQuestion: "Which consolidated idea would you like to undo? (enter the idea ID)"
+
+Parse the response as the idea ID.
+</step>
+
+<step name="validate_and_display">
+Find the consolidated idea and display its details.
+
+```bash
+ALL=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --all --raw)
+```
+
+Parse the JSON result. Find the idea matching the provided ID.
+
+**If not found:** Error "Idea #{id} not found." and exit.
+
+Read the idea file to get its full content. Check that it has `consolidated_from` in its frontmatter.
+
+**If no `consolidated_from`:** Error "Idea #{id} is not a consolidated idea (no consolidated_from field). Nothing to undo." and exit.
+
+Extract the `consolidated_from` array (list of source idea IDs).
+
+Display:
+```
+## Undo Consolidation
+
+**Idea to remove:** #{id} --- {title}
+**Created from:** #{source1}, #{source2}, #{source3}
+
+The following source ideas will be restored to pending:
+```
+
+For each source ID in `consolidated_from`, find the source idea in the full list (it should be in `consolidated/` state) and display:
+```
+- #{sourceId} --- {sourceTitle} (currently in consolidated/)
+```
+
+If a source idea cannot be found, note it as missing:
+```
+- #{sourceId} --- (not found -- may have been manually deleted)
+```
+</step>
+
+<step name="confirm">
+Ask the user for confirmation before proceeding.
+
+Use AskUserQuestion:
+- question: "This will:\n- Delete idea #{id} ({title})\n- Restore {N} source ideas to pending\n\nProceed? (yes/no)"
+
+**If no (or cancel):**
+```
+Undo cancelled. No changes made.
+```
+Exit workflow.
+
+**If yes:** Proceed to execute_undo step.
+</step>
+
+<step name="execute_undo">
+Call the CLI to perform the atomic undo operation.
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas undo-consolidation --id ${ID} --raw
+```
+
+Parse the JSON result. The CLI returns:
+```json
+{
+  "undone_idea_id": 5,
+  "title": "Improve API resilience",
+  "restored_ids": ["001", "003", "017"],
+  "deleted_file": "005-improve-api-resilience.md"
+}
+```
+
+If the CLI returns an error, display it and exit.
+</step>
+
+<step name="confirm_output">
+Display the result of the undo operation.
+
+```
+## Undo Complete
+
+**Deleted:** #{id} --- {title}
+**Restored to pending:** #{source1}, #{source2}, #{source3}
+**Git commit:** ideas: undo consolidation #{id} - {title}
+
+The source ideas are back in pending/ state. Their consolidated_into references have been removed.
+You can redo this consolidation with /dgs:consolidate-ideas {source1} {source2} {source3}
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Argument parsed correctly (consolidated idea ID)
+- [ ] Interactive selection works when no ID provided
+- [ ] Idea validated as a consolidated result (has consolidated_from)
+- [ ] Source ideas displayed with their current state
+- [ ] User confirmation required before proceeding
+- [ ] CLI called for atomic undo operation
+- [ ] Confirmation output shows deleted idea and restored sources
+</success_criteria>