@ktpartners/dgs-platform 2.6.3 → 2.7.1

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

@@ -14,6 +14,7 @@ Orchestrator coordinates, not executes. Each subagent loads the full execute-pla
 
 <required_reading>
 Read STATE.md before any operation to load project context.
+@~/.claude/deliver-great-systems/references/sync-hooks.md
 </required_reading>
 
 <process>
@@ -26,7 +27,7 @@ INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init execute
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`.
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `base_branch`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `author`, `phase_req_ids`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull`.
 
 **Load execution tier context:**
 
@@ -62,6 +63,60 @@ Set `NON_INTERACTIVE = true` if `--non-interactive` flag present OR `--auto` fla
 
 `NON_INTERACTIVE` controls checkpoint auto-approval and verification auto-resolve.
 `AUTO_MODE` controls auto-advance via transition.md only (offer_next step).
+
+**Sync initialization:**
+
+Set `WORKFLOW_NAME = "execute-phase"`.
+Initialize `SYNC_WARNINGS = []` (accumulates mid-workflow push warnings for end-of-workflow summary).
+
+Determine effective sync mode for this workflow:
+- If `NON_INTERACTIVE` is true, treat sync as auto mode regardless of config setting (no prompting in auto/job mode).
+- Otherwise use `sync_push` and `sync_pull` values from init JSON.
+- Store as `EFFECTIVE_SYNC_PULL` and `EFFECTIVE_SYNC_PUSH`.
+</step>
+
+<step name="sync_before">
+Pre-workflow pull. Execute BEFORE any DGS state modifications (before branching).
+
+Follow the sync-hooks pre-workflow pull pattern with `WORKFLOW_NAME = "execute-phase"`:
+
+```bash
+SYNC_CHECK=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "execute-phase" --check-only)
+```
+
+Parse `SYNC_CHECK` JSON.
+
+**If `first_run_hint` is not null:** Display it as a one-liner.
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "execute-phase" --mark-hint-shown
+```
+
+**If `should_pull` is false:** Skip pull entirely.
+
+**If `stale.stale` is true and mode is `"off"`:** Display:
+`Warning: origin/{branch} is {commitsBehind} commits ahead. Consider pulling.`
+
+**If `should_pull` is true:**
+
+- **If `EFFECTIVE_SYNC_PULL` is `"auto"` OR `suppressed` is true:** Pull silently:
+  ```bash
+  PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "execute-phase")
+  ```
+  If `action` is `"aborted"`: report `diagnosis` and halt workflow before any branching or state changes.
+
+- **If `EFFECTIVE_SYNC_PULL` is `"prompt"` and `suppressed` is false:**
+  Use AskUserQuestion: `Pull from remote before starting? [Y/n]`
+  - If Yes (or empty/default):
+    ```bash
+    node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "execute-phase" --record-yes
+    PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "execute-phase")
+    ```
+    If `action` is `"aborted"`:
+    - Display diagnosis
+    - AskUserQuestion: `Continue without pulling? [y/N]`
+    - If No (default): halt workflow
+    - If Yes: continue with warning
+  - If No: skip pull, continue
 </step>
 
 <step name="handle_branching">
@@ -228,7 +283,21 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    - Bad: "Wave 2 complete. Proceeding to Wave 3."
    - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
 
-5. **Handle failures:**
+5. **Mid-workflow push (sync_mid_push):**
+
+   After each wave completes successfully, push if sync is configured.
+
+   Only if `EFFECTIVE_SYNC_PUSH` is not `"off"` and `cadence_push` is true:
+   ```bash
+   PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "execute-phase" --mid-workflow)
+   ```
+   Parse result JSON. Mid-workflow pushes are always silent (no prompt -- user consented at workflow start).
+
+   - If `action` is `"warning"`: append `message` to `SYNC_WARNINGS` accumulator
+   - If `action` is `"pushed"`: continue silently. If `message` mentions new remote branch, log: `Created remote branch: {branch}`
+   - Push failure does NOT halt execution -- warnings are accumulated for end-of-workflow summary
+
+6. **Handle failures:**
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a DGS or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (SUMMARY.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
@@ -239,9 +308,9 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    **If `NON_INTERACTIVE` is false (interactive mode):**
    For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
 
-6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
+7. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
-7. **Proceed to next wave.**
+8. **Proceed to next wave.**
 </step>
 
 <step name="checkpoint_handling">
@@ -462,6 +531,44 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-
 ```
 </step>
 
+<step name="sync_after">
+Post-workflow push. Execute AFTER all state modifications and commits are complete.
+
+Follow the sync-hooks post-workflow push pattern with `WORKFLOW_NAME = "execute-phase"`:
+
+Only if `EFFECTIVE_SYNC_PUSH` is not `"off"` and `cadence_push` is true:
+
+```bash
+PUSH_CHECK=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "execute-phase" --check-only)
+```
+
+Parse `PUSH_CHECK` JSON.
+
+**If `should_push` is false:** Skip push. Done.
+
+**If `should_push` is true:**
+
+- **If `EFFECTIVE_SYNC_PUSH` is `"auto"` OR `suppressed` is true:** Push silently:
+  ```bash
+  PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "execute-phase")
+  ```
+  Parse result. Display `summary` if action is `"pushed"`. Display `message` if action is `"warning"`.
+
+- **If `EFFECTIVE_SYNC_PUSH` is `"prompt"` and `suppressed` is false:**
+  Use AskUserQuestion: `Push to remote? [Y/n]`
+  - If Yes (or empty/default):
+    ```bash
+    node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "execute-phase" --record-yes
+    PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "execute-phase")
+    ```
+    Parse result. Display summary.
+  - If No: skip push
+
+**Aggregated push summary:** After the final push, display a combined summary including any accumulated `SYNC_WARNINGS` from mid-workflow pushes. Format:
+- If no warnings: display push summary as-is
+- If warnings accumulated: append `\n{count} mid-workflow push warning(s) -- see above` to the summary
+</step>
+
 <step name="offer_next">
 
 **Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/dgs:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.

package/deliver-great-systems/workflows/init-product.md

@@ -354,7 +354,9 @@ AskUserQuestion([
   },
   "git": {
     "branching_strategy": "none|phase|milestone",
-    "base_branch": "[from earlier question]"
+    "base_branch": "[from earlier question]",
+    "sync_push": "prompt",
+    "sync_pull": "prompt"
   }
 }
 ```
@@ -712,7 +714,9 @@ AskUserQuestion([
   },
   "git": {
     "branching_strategy": "none|phase|milestone",
-    "base_branch": "[from earlier question]"
+    "base_branch": "[from earlier question]",
+    "sync_push": "prompt",
+    "sync_pull": "prompt"
   }
 }
 ```

package/deliver-great-systems/workflows/run-job.md

@@ -8,6 +8,7 @@ The orchestrator stays lean: it reads only the job file and MILESTONE-AUDIT.md (
 
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
+@~/.claude/deliver-great-systems/references/sync-hooks.md
 </required_reading>
 
 <process>
@@ -19,7 +20,10 @@ Load planning context:
 INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
 ```
 
-Extract: `project_root`, `jobs_root` as needed by the workflow.
+Extract: `project_root`, `jobs_root`, `sync_push`, `sync_pull`, `cadence_push`, `cadence_pull` as needed by the workflow.
+
+Set `WORKFLOW_NAME = "run-job"`.
+Initialize `SYNC_WARNINGS = []` (accumulates mid-workflow push warnings).
 
 **Load execution tier context:**
 
@@ -180,6 +184,45 @@ Skipping {completedCount} completed steps, resuming from step {nextStepIndex + 1
 ```
 </step>
 
+<step name="sync_before">
+Pre-workflow pull. Execute BEFORE any job steps run.
+
+Follow the sync-hooks pre-workflow pull pattern with `WORKFLOW_NAME = "run-job"`:
+
+```bash
+SYNC_CHECK=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "run-job" --check-only)
+```
+
+Parse `SYNC_CHECK` JSON.
+
+**If `first_run_hint` is not null:** Display it as a one-liner.
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "run-job" --mark-hint-shown
+```
+
+**If `should_pull` is false:** Skip pull entirely.
+
+**If `stale.stale` is true and mode is `"off"`:** Display:
+`Warning: origin/{branch} is {commitsBehind} commits ahead. Consider pulling.`
+
+**If `should_pull` is true:**
+
+- **If `sync_pull` is `"auto"`:** Pull silently (run-job is always non-interactive):
+  ```bash
+  PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "run-job")
+  ```
+  If `action` is `"aborted"`: report `diagnosis` and halt job before any steps run.
+
+- **If `sync_pull` is `"prompt"` and `suppressed` is false:**
+  Since run-job runs in non-interactive mode, treat prompt mode as auto mode -- pull silently.
+  ```bash
+  PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "run-job")
+  ```
+  If `action` is `"aborted"`: halt job before any steps run with diagnosis.
+
+- **If `suppressed` is true:** Pull silently (recent Yes answer).
+</step>
+
 <step name="execute_steps">
 Initialize tracking variables:
 - `START_TIME` = current timestamp (for elapsed time calculation)
@@ -228,6 +271,20 @@ Loop through steps starting from `nextStepIndex`.
    OK {command} {args_display} ({duration})
    ```
 
+   **Mid-workflow push (after phase-completing steps):**
+
+   After a step completes successfully, check if the step's command is a phase-completing workflow: `execute-phase`, `verify-work`, `audit-phase`, `audit-milestone`, `plan-phase`, `plan-milestone-gaps`, or `complete-milestone`.
+
+   If so, and `sync_push` is not `"off"` and `cadence_push` is true:
+   ```bash
+   PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "run-job" --mid-workflow)
+   ```
+   Parse result JSON. Mid-workflow pushes are always silent (no prompt).
+
+   - If `action` is `"warning"`: log warning and continue. Append to `SYNC_WARNINGS`.
+   - If `action` is `"pushed"`: continue silently. If `message` mentions new remote branch, log it.
+   - Push failure does NOT halt job execution.
+
 5. **On failure:** Mark step failed with timestamp and error:
    ```bash
    node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-step "$JOB_PATH" $INDEX failed --timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --error "{error_summary}"
@@ -455,7 +512,21 @@ When all steps are completed (`nextStepIndex` is null after the loop):
    Parse the result. If `found: true`, write the `content` field to `${jobs_root}/completed/job-{version}-SUMMARY.md` using the Write tool.
    Display: `Job summary written to ${jobs_root}/completed/job-{version}-SUMMARY.md`
 
-4. **Display completion banner:**
+4. **Post-workflow push (sync_after):**
+
+   Follow the sync-hooks post-workflow push pattern with `WORKFLOW_NAME = "run-job"`:
+
+   Only if `sync_push` is not `"off"` and `cadence_push` is true:
+   ```bash
+   PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "run-job")
+   ```
+   Parse result. Display `summary` if action is `"pushed"`. Display `message` if action is `"warning"`.
+
+   Since run-job is non-interactive, push silently (auto mode behavior).
+
+   Display aggregated push summary including any accumulated `SYNC_WARNINGS` from mid-workflow pushes.
+
+5. **Display completion banner:**
 
    If `AUTO_RESOLVE_COUNT` is 0:
    ```
@@ -495,4 +566,8 @@ The orchestrator MUST stay lean per EXEC-07:
 - [ ] --dry-run flag displays step preview without executing
 - [ ] Job summary auto-generated on completion (written to completed/)
 - [ ] Job summary auto-generated on failure (written to in-progress/)
+- [ ] Pre-workflow pull executed before job steps start (sync_before)
+- [ ] Mid-workflow push after phase-completing steps (silent, no prompt)
+- [ ] Post-workflow push after job completion (sync_after)
+- [ ] Push failures logged as warnings, do not halt execution
 </success_criteria>

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

@@ -48,6 +48,8 @@ Parse current values (default to `true` if not present):
 - `model_profile` — which model each agent uses (default: `balanced`)
 - `git.branching_strategy` — branching approach (default: `"none"`)
 - `git.base_branch` — integration target branch for code repos (default: `"main"`)
+- `git.sync_push` — remote sync push mode (default: "off" if absent for existing installs)
+- `git.sync_pull` — remote sync pull mode (default: "off" if absent for existing installs)
 - `workflow.discipline` — whether CLAUDE.md workflow routing is active (default: true if absent)
 
 Also detect whether `./CLAUDE.md` exists and contains a DGS section:
@@ -320,6 +322,74 @@ Display: `Kept workflow discipline on.`
 Do not change config or CLAUDE.md.
 </step>
 
+<step name="present_sync_settings">
+Read the current sync state:
+
+```bash
+SYNC_PUSH=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-get git.sync_push --raw 2>/dev/null || echo "off")
+SYNC_PULL=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-get git.sync_pull --raw 2>/dev/null || echo "off")
+```
+
+Check if any registered repo has a remote:
+
+```bash
+HAS_REMOTE=$(git remote 2>/dev/null | head -1)
+```
+
+Display current state:
+```
+Git Sync Push: {off/prompt/auto}
+Git Sync Pull: {off/prompt/auto}
+```
+
+Use AskUserQuestion for sync_push:
+```
+AskUserQuestion([{
+  question: "Git sync push mode — when should DGS push to remote after work?",
+  header: "Sync Push",
+  multiSelect: false,
+  options: [
+    { label: "Off", description: "Never push automatically (current behaviour)" },
+    { label: "Prompt", description: "Ask before pushing after each workflow" },
+    { label: "Auto", description: "Push silently after each workflow, report only failures" }
+  ]
+}])
+```
+
+Pre-select the option matching current `SYNC_PUSH` value.
+
+Use AskUserQuestion for sync_pull:
+```
+AskUserQuestion([{
+  question: "Git sync pull mode — when should DGS pull from remote before work?",
+  header: "Sync Pull",
+  multiSelect: false,
+  options: [
+    { label: "Off", description: "Never pull automatically (current behaviour)" },
+    { label: "Prompt", description: "Ask before pulling at start of each workflow" },
+    { label: "Auto", description: "Pull silently before each workflow, abort on failure" }
+  ]
+}])
+```
+
+Pre-select the option matching current `SYNC_PULL` value.
+
+**If user selects a non-off value and HAS_REMOTE is empty:**
+
+Display warning (but still apply the setting):
+```
+Warning: No git remote detected. Sync operations will be skipped until a remote is configured.
+```
+
+Set config values:
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-set git.sync_push "{selected_push_mode}"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" config-set git.sync_pull "{selected_pull_mode}"
+```
+
+Display: `Git sync push: {off/prompt/auto}, pull: {off/prompt/auto}`
+</step>
+
 <step name="present_review_settings">
 Load current review configuration:
 
@@ -368,7 +438,9 @@ Merge new settings into existing config:
   },
   "git": {
     "branching_strategy": "none" | "phase" | "milestone",
-    "base_branch": "main" | user_answer
+    "base_branch": "main" | user_answer,
+    "sync_push": "off" | "prompt" | "auto",
+    "sync_pull": "off" | "prompt" | "auto"
   }
 }
 ```
@@ -416,6 +488,10 @@ Write `~/.dgs/defaults.json` with:
     "nyquist_validation": <current>,
     "codereview": <current>,
     "discipline": <current>
+  },
+  "git": {
+    "sync_push": <current>,
+    "sync_pull": <current>
   }
 }
 ```
@@ -441,6 +517,8 @@ Display:
 | Git Branching        | {None/Per Phase/Per Milestone} |
 | Base Branch          | {main/develop/etc.} |
 | Workflow Discipline  | {On/Off} |
+| Git Sync Push        | {Off/Prompt/Auto} |
+| Git Sync Pull        | {Off/Prompt/Auto} |
 | OpenAI Key           | {set/not set} (edit review-keys.json) |
 | Gemini Key           | {set/not set} (edit review-keys.json) |
 | Saved as Defaults    | {Yes/No} |
@@ -467,4 +545,7 @@ Quick commands:
 - [ ] User shown workflow discipline toggle with current state
 - [ ] Toggle on creates/updates CLAUDE.md with DGS section delimiters
 - [ ] Toggle off removes DGS section with confirmation, preserving user content
+- [ ] User shown git sync push and pull toggles with current state
+- [ ] Sync settings saved to config via config-set
+- [ ] Warning shown when enabling sync without a git remote
 </success_criteria>

package/package.json

@@ -4,7 +4,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.6.3",
+  "version": "2.7.1",
   "description": "Deliver Great Systems Platform — A meta-prompting, context engineering and spec-driven development system for Claude Code and Gemini by KT Partners.",
   "bin": {
     "dgs": "bin/install.js"