@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/references/conflict-resolution.md

@@ -0,0 +1,66 @@
+# Conflict Resolution Protocol
+
+Reference document for automated merge conflict resolution during milestone completion.
+
+## Resolution Flow
+
+When `git merge` (squash or no-ff) returns non-zero exit code:
+
+1. **Detect** -- Run `dgs-tools conflict-agent run --phase-dir <phase-dir>` to get conflict inventory and attempt automated resolution
+2. **Assess** -- Parse the agent's JSON output: `resolved_count`, `escalated_count`, `verified`, `semantic_warnings`
+3. **Escalate** -- For each escalated (LOW-confidence) conflict, present to user for approval
+4. **Verify** -- After all resolutions applied, run post-resolution verification
+5. **Record** -- Resolution report committed as part of merge commit (atomic with resolution)
+6. **Continue** -- Complete the merge commit and proceed to next branch (if phase strategy)
+
+## Escalation Protocol
+
+When the agent flags a conflict as LOW confidence or escalated:
+
+1. Show the user:
+   - The conflict diff (ours vs theirs)
+   - Plan context for both sides (what each branch intended)
+   - The agent's proposed resolution (if any)
+   - Confidence assessment and reasoning
+
+2. User actions:
+   - **Accept** -- Apply the proposed resolution as-is
+   - **Reject with hint** -- User provides guidance text; agent retries with that context
+   - **Abort this file** -- Leave this file's conflicts unresolved; abort this specific branch merge, continue with remaining branches
+
+3. Retry limit: Maximum 2 retries with user guidance per file. After 2 failed retries, abort that branch merge and move to the next.
+
+## Cascading Context
+
+For phase branching strategy with sequential merges:
+
+- After each branch merge, extract learnings (files resolved, strategies used, domain changes)
+- Pass accumulated learnings to the next branch's resolution
+- If a conflict involves a file already resolved in a previous merge, boost confidence using prior resolution context
+
+## Semantic Warnings
+
+After all conflict markers are resolved (including clean merges):
+
+- Check which files were modified by both branches without conflict markers
+- Flag files where both branches touched the same domain/function area
+- Emit warnings in the resolution report -- advisory only, does not block the merge
+
+## Confidence Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| HIGH | One-sided addition, clear structural combine, plan context confirms | Silent -- resolve automatically |
+| MEDIUM | Superset pattern, partial plan context, cascading boost | Silent -- resolve automatically, note in report |
+| LOW | Divergent changes, contradictory intent, no clear winner | Escalate -- present to user for approval |
+
+## Summary Output
+
+After all merges complete, show:
+```
+Conflict Resolution Summary:
+- {N} files resolved ({H} HIGH, {M} MEDIUM, {L} LOW)
+- {E} files escalated to user
+- {S} semantic warnings
+- Report: {path to RESOLUTION-REPORT.md}
+```

package/deliver-great-systems/references/context-tiers.md

@@ -0,0 +1,166 @@
+# Context Tiers
+
+> Machine-readable tier definitions for the DGS context loading system.
+> Parsed at runtime by `bin/lib/context.cjs` -- YAML code blocks are the source of truth.
+
+## Tier 0: none
+
+No context loaded. Used by stateless utility commands that need no project awareness.
+
+```yaml
+tier: none
+includes_tier: null
+files: []
+dynamic: []
+scope_flags: {}
+```
+
+## Tier 1: lite
+
+Minimal "where am I" context. Project identity, current state, and configuration.
+
+```yaml
+tier: lite
+includes_tier: null
+files:
+  - path: "PROJECT.md"
+    category: "project"
+  - path: "STATE.md"
+    category: "state"
+  - path: "config.json"
+    category: "config"
+scope_flags: {}
+```
+
+## Tier 2: planning
+
+Full planning awareness. Inherits lite tier and adds roadmap, requirements, repo registry, and all codebase analysis documents.
+
+```yaml
+tier: planning
+includes_tier: lite
+files:
+  - path: "ROADMAP.md"
+    category: "roadmap"
+  - path: "REQUIREMENTS.md"
+    category: "requirements"
+  - path: "REPOS.md"
+    category: "repos"
+dynamic:
+  - type: "glob"
+    pattern: "codebase/**/*.md"
+    category: "codebase"
+scope_flags:
+  idea:
+    - path: "ideas/{idea_file}"
+      category: "idea"
+    - path: "ideas/{idea_dir}/docs/**"
+      category: "idea-docs"
+  spec:
+    - path: "specs/{spec_file}"
+      category: "spec"
+    - path: "specs/{spec_dir}/docs/**"
+      category: "spec-docs"
+```
+
+## Tier 3: execution
+
+Phase-aware context for plan execution. Inherits planning tier and adds phase-specific files via the `--phase` flag.
+
+```yaml
+tier: execution
+includes_tier: planning
+files: []
+dynamic: []
+scope_flags:
+  phase:
+    - path: "phases/{phase_dir}/CONTEXT.md"
+      category: "phase"
+    - path: "phases/{phase_dir}/RESEARCH.md"
+      category: "phase"
+    - path: "phases/{phase_dir}/*-PLAN.md"
+      category: "phase-plan"
+    - path: "phases/{phase_dir}/*-SUMMARY.md"
+      category: "phase-summary"
+    - path: "milestone-summaries"
+      category: "milestone-summary"
+      description: "All SUMMARY.md files from completed phases in the current milestone"
+  idea:
+    - path: "ideas/{idea_file}"
+      category: "idea"
+    - path: "ideas/{idea_dir}/docs/**"
+      category: "idea-docs"
+  spec:
+    - path: "specs/{spec_file}"
+      category: "spec"
+    - path: "specs/{spec_dir}/docs/**"
+      category: "spec-docs"
+```
+
+## Tier 4: verification
+
+Full context for verification and UAT. Inherits execution tier and adds verification artifacts.
+
+```yaml
+tier: verification
+includes_tier: execution
+files:
+  - path: "phases/{phase_dir}/VERIFICATION.md"
+    category: "verification"
+dynamic:
+  - type: "glob"
+    pattern: "UAT*.md"
+    category: "uat"
+scope_flags:
+  phase:
+    - path: "phases/{phase_dir}/CONTEXT.md"
+      category: "phase"
+    - path: "phases/{phase_dir}/RESEARCH.md"
+      category: "phase"
+    - path: "phases/{phase_dir}/*-PLAN.md"
+      category: "phase-plan"
+    - path: "phases/{phase_dir}/*-SUMMARY.md"
+      category: "phase-summary"
+    - path: "milestone-summaries"
+      category: "milestone-summary"
+      description: "All SUMMARY.md files from completed phases in the current milestone"
+  idea:
+    - path: "ideas/{idea_file}"
+      category: "idea"
+    - path: "ideas/{idea_dir}/docs/**"
+      category: "idea-docs"
+  spec:
+    - path: "specs/{spec_file}"
+      category: "spec"
+    - path: "specs/{spec_dir}/docs/**"
+      category: "spec-docs"
+```
+
+## Workflow-to-Tier Mapping
+
+Informational reference for which workflows use which tier.
+
+### Tier 0 -- none (5 workflows)
+
+help, node-repair, set-profile, sync-upstream, update
+
+### Tier 1 -- lite (24 workflows)
+
+add-doc, add-idea, add-todo, cancel-job, check-todos, cleanup, create-milestone-job, health, init-product, list-docs, list-ideas, list-jobs, list-specs, overlap-check, pause-work, progress, reject-idea, remove-doc, restore-idea, resume-project, search, settings, undo-consolidation, update-idea
+
+### Tier 2 -- planning (22 workflows)
+
+add-phase, add-tests, approve-spec, consolidate-ideas, develop-idea, discuss-idea, discuss-phase, find-related-ideas, import-spec, insert-phase, list-phase-assumptions, map-codebase, new-milestone, new-project, plan-milestone-gaps, plan-phase, quick, refine-spec, remove-phase, research-idea, research-phase, write-spec
+
+### Tier 3 -- execution (7 workflows)
+
+audit-phase, diagnose-issues, discovery-phase, execute-phase, execute-plan, run-job, transition
+
+### Tier 4 -- verification (5 workflows)
+
+audit-milestone, complete-milestone, validate-phase, verify-phase, verify-work
+
+---
+
+*Context tiers defined for v15.0 Improved Context Loading*
+*Parsed by: deliver-great-systems/bin/lib/context.cjs*

package/deliver-great-systems/references/continuation-format.md

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/dgs:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/dgs:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/dgs:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/dgs:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/dgs:discuss-phase 2` — gather context first
+- `/dgs:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/dgs:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/dgs:discuss-phase 3` — gather context first
+- `/dgs:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/dgs:plan-phase 3`
+
+**To discuss context first:** `/dgs:discuss-phase 3`
+
+**To research unknowns:** `/dgs:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/dgs:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/dgs:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/dgs:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/dgs:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/deliver-great-systems/references/decimal-phase-calculation.md

@@ -0,0 +1,67 @@
+# Decimal Phase Calculation
+
+> **v2 Multi-Project:** Always use init output variables (`${project_root}`, `${phase_dir}`, `${phases_dir}`) instead of hardcoded paths in workflows. In v2 setups, these resolve to `<project-slug>/phases/` within the planning root.
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using dgs-tools
+
+```bash
+# Get next decimal phase after phase 6
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_INFO=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase next-decimal "${AFTER_PHASE}")
+DECIMAL_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.next')
+BASE_PHASE=$(printf '%s\n' "$DECIMAL_INFO" | jq -r '.base_phase')
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR="${phases_dir}/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `${phases_dir}/06.1-fix-critical-auth-bug/`