@ktpartners/dgs-platform 2.6.3 → 2.7.1

package/deliver-great-systems/bin/lib/test-helpers.cjs

@@ -136,13 +136,23 @@ function createTempProject(options) {
   var projectRoot;
 
   if (layout === 'root') {
-    // Root layout: planning files live at repo root, dgs.config.json at root
+    // Root layout: planning files live at repo root
     planningDir = cwd;
     projectRoot = '.';
 
-    // Write dgs.config.json at repo root with planningRoot: '.'
-    var rootConfigData = Object.assign({ planningRoot: '.' }, withConfig);
-    writeFile(cwd, 'dgs.config.json', JSON.stringify(rootConfigData));
+    // Split withConfig into shared and local keys
+    var rootLocalKeys = { planningRoot: '.' };
+    var rootSharedKeys = {};
+    var LOCAL_KEY_SET = new Set(['current_project', 'planningRoot', 'v2_hint_shown', 'sync_hint_shown']);
+    for (var k in withConfig) {
+      if (LOCAL_KEY_SET.has(k)) {
+        rootLocalKeys[k] = withConfig[k];
+      } else {
+        rootSharedKeys[k] = withConfig[k];
+      }
+    }
+    writeFile(cwd, 'config.local.json', JSON.stringify(rootLocalKeys));
+    writeFile(cwd, 'config.json', JSON.stringify(rootSharedKeys));
 
     // Project files at root
     writeFile(cwd, 'PROJECT.md', '# Project: ' + projectName + '\n');
@@ -176,9 +186,19 @@ function createTempProject(options) {
     projectRoot = path.join('.planning', PROJECTS_DIR, project);
     var absProjectRoot = path.join(cwd, '.planning', PROJECTS_DIR, project);
 
-    // Product-level config
-    var configData = Object.assign({ current_project: project }, withConfig);
-    writeFile(cwd, '.planning/config.json', JSON.stringify(configData));
+    // Product-level config: split into shared and local
+    var v2LocalKeys = { current_project: project };
+    var v2SharedKeys = {};
+    var LOCAL_KEY_SET_V2 = new Set(['current_project', 'planningRoot', 'v2_hint_shown', 'sync_hint_shown']);
+    for (var ck in withConfig) {
+      if (LOCAL_KEY_SET_V2.has(ck)) {
+        v2LocalKeys[ck] = withConfig[ck];
+      } else {
+        v2SharedKeys[ck] = withConfig[ck];
+      }
+    }
+    writeFile(cwd, '.planning/config.json', JSON.stringify(v2SharedKeys));
+    writeFile(cwd, '.planning/config.local.json', JSON.stringify(v2LocalKeys));
 
     // v2 markers
     var projectsMd = '# Projects\n\n## Active\n\n';
@@ -208,8 +228,8 @@ function createTempProject(options) {
     }
 
     if (withTodos) {
-      fs.mkdirSync(path.join(cwd, '.planning', PROJECTS_DIR, project, 'todos', 'pending'), { recursive: true });
-      fs.mkdirSync(path.join(cwd, '.planning', PROJECTS_DIR, project, 'todos', 'completed'), { recursive: true });
+      fs.mkdirSync(path.join(cwd, '.planning', 'todos', 'pending'), { recursive: true });
+      fs.mkdirSync(path.join(cwd, '.planning', 'todos', 'completed'), { recursive: true });
     }
 
     if (withResearch) {
@@ -221,9 +241,21 @@ function createTempProject(options) {
     planningDir = path.join(cwd, '.planning');
     projectRoot = '.planning';
 
-    // config.json
-    var v1ConfigData = Object.assign({}, withConfig);
-    writeFile(cwd, '.planning/config.json', JSON.stringify(v1ConfigData));
+    // Split withConfig into shared and local
+    var v1SharedKeys = {};
+    var v1LocalKeys = {};
+    var LOCAL_KEY_SET_V1 = new Set(['current_project', 'planningRoot', 'v2_hint_shown', 'sync_hint_shown']);
+    for (var vk in withConfig) {
+      if (LOCAL_KEY_SET_V1.has(vk)) {
+        v1LocalKeys[vk] = withConfig[vk];
+      } else {
+        v1SharedKeys[vk] = withConfig[vk];
+      }
+    }
+    writeFile(cwd, '.planning/config.json', JSON.stringify(v1SharedKeys));
+    if (Object.keys(v1LocalKeys).length > 0) {
+      writeFile(cwd, '.planning/config.local.json', JSON.stringify(v1LocalKeys));
+    }
 
     // Project files
     writeFile(cwd, '.planning/PROJECT.md', '# Project: ' + projectName + '\n');

package/deliver-great-systems/references/git-integration.md

@@ -248,3 +248,84 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 - "Commit noise" irrelevant when consumer is Claude, not humans
 
 </commit_strategy_rationale>
+
+<remote_sync>
+
+## Remote Synchronisation
+
+DGS can automatically pull from and push to remotes for all registered repos. Behaviour is controlled by two config keys (`git.sync_push` and `git.sync_pull`) and a per-workflow cadence table.
+
+### Sync Modes
+
+| Mode | Pull behaviour | Push behaviour | Best for |
+|------|---------------|----------------|----------|
+| `off` | No pull, no prompt | No push, no prompt | Solo developers, no remote, or manual git users |
+| `prompt` | Asks before pulling (Y default) | Asks before pushing (Y default) | Teams learning DGS, cautious users |
+| `auto` | Pulls silently before work | Pushes silently after work | Established teams, CI/CD pipelines, job execution |
+
+Fresh installs default to `prompt`. Existing users upgrading get `off` (zero behaviour change).
+
+### Per-Workflow Cadence
+
+Not every workflow needs sync. A cadence table in `sync.cjs` classifies each workflow:
+
+| Pattern | Count | Examples |
+|---------|-------|---------|
+| Pull + Push | 35 | execute-phase, plan-phase, write-spec, run-job |
+| Push only | 17 | pause-work, add-idea, import-spec, map-codebase |
+| Pull only | 4 | resume-work, progress, find-related-ideas |
+| No sync | 14 | help, list-ideas, search, debug |
+
+A workflow syncs only when BOTH conditions are true: the cadence table says it should AND the user's config mode is not `off`.
+
+Full per-workflow detail: see `references/sync-cadence.md`.
+
+### Failure Handling
+
+**Pull failure:**
+- Aborts the workflow BEFORE any DGS state is modified
+- Reports which repo failed and why (dirty state, non-fast-forward, auth error, network timeout)
+- In `prompt` mode, offers to continue without pulling
+- Uses `--ff-only` -- non-fast-forward situations require manual resolution
+
+**Push failure:**
+- Does NOT abort -- work is already committed locally
+- Reports a warning with the failing repo name and error
+- Mid-workflow pushes (execute-phase after each plan) retry: 1 retry in prompt mode, 3 in auto mode
+
+**Pre-flight checks (block sync if detected):**
+- Dirty working tree (uncommitted changes)
+- Mid-merge, mid-rebase, or mid-cherry-pick state
+- Detached HEAD
+- Each check names the affected repo with an actionable fix
+
+### Workflow Integration
+
+Workflows use sync hooks at their boundaries:
+
+1. **Before work:** Check cadence + mode, pull if applicable, abort on failure
+2. **After work:** Check cadence + mode, push if applicable, warn on failure
+3. **Mid-workflow:** `execute-phase` pushes after each plan; `run-job` pushes after each phase (silent, no prompt)
+
+**Prompt fatigue mitigation:** In `prompt` mode, a "Yes" answer suppresses re-prompting for 5 minutes across all workflows. Suppression uses temp files for cross-process persistence.
+
+**Stale-state warning:** In `off` mode, if the planning repo's remote is ahead, a one-liner warning is displayed before continuing.
+
+**First-run hint:** When a remote exists but sync is `off`, a one-time hint suggests enabling sync via `/dgs:settings`.
+
+### Configuration
+
+```bash
+# Set both directions at once
+dgs-tools config-set git.sync prompt
+
+# Set independently
+dgs-tools config-set git.sync_push auto
+dgs-tools config-set git.sync_pull prompt
+
+# Or use /dgs:settings for interactive toggle
+```
+
+Valid values: `off`, `prompt`, `auto`.
+
+</remote_sync>

package/deliver-great-systems/references/planning-config.md

@@ -2,39 +2,110 @@
 
 Configuration options for planning directory behavior.
 
-> **v2 Multi-Project:** Config file (`dgs.config.json`) is always product-level — not project-scoped. In v2 setups, project-specific paths (STATE.md, ROADMAP.md, phases/) resolve to `<project-slug>/` within the planning root via init commands, but config stays at the product root.
+> **v2 Multi-Project:** Config file (`config.json`) is always product-level -- not project-scoped. In v2 setups, project-specific paths (STATE.md, ROADMAP.md, phases/) resolve to `<project-slug>/` within the planning root via init commands, but config stays at the product root.
+
+## Two-File Config Layout
+
+DGS splits configuration across two files, both resolved via `getPlanningRoot()`:
+
+| File | Tracked | Purpose | Keys |
+|------|---------|---------|------|
+| `config.json` | Yes (shared) | Team settings: model profile, workflow flags, git config, sync config, parallelization | All `VALID_CONFIG_KEYS` |
+| `config.local.json` | No (gitignored) | Per-machine state: which project is active, where planning lives | `current_project`, `planningRoot`, `v2_hint_shown`, `sync_hint_shown` |
+
+`loadConfig()` in `core.cjs` merges both files -- local overrides shared. `writeConfigField()` in `config.cjs` routes writes to the correct file based on `isLocalKey()`.
+
+**Migration:** On first read, if only `dgs.config.json` exists, `_migrateLegacyConfig()` splits it into the two-file layout automatically.
 
 <config_schema>
+
+## Config Schema
+
+Complete JSON example with all sections (fresh-install defaults):
+
 ```json
-"workflow": {
-  "research": true,
-  "plan_check": true,
-  "verifier": true,
-  "auto_advance": false,
-  "nyquist_validation": true,
-  "codereview": false
-},
-"planning": {
+{
+  "model_profile": "balanced",
   "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "base_branch": "main",
-  "branching_strategy": "none",
-  "phase_branch_template": "dgs/{project}/phase-{phase}-{slug}",
-  "milestone_branch_template": "dgs/{project}/{milestone}-{slug}"
+  "search_gitignored": false,
+  "parallelization": true,
+  "brave_search": false,
+  "granularity": "standard",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "discipline": true
+  },
+  "git": {
+    "base_branch": "main",
+    "branching_strategy": "none",
+    "phase_branch_template": "dgs/{project}/phase-{phase}-{slug}",
+    "milestone_branch_template": "dgs/{project}/{milestone}-{slug}",
+    "sync_push": "prompt",
+    "sync_pull": "prompt"
+  }
 }
 ```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `workflow.codereview` | `false` | Spawn 3-pass multi-agent code reviewer after plan execution. Auto-fixes low-risk issues in separate commit. |
-| `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.base_branch` | `"main"` | Integration target branch for code repo branching operations (branch creation and merge) |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"dgs/{project}/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"dgs/{project}/{milestone}-{slug}"` | Branch template for milestone strategy |
+## Config Schema Table
+
+### Top-Level Keys
+
+| Key | Default (fresh) | Default (upgrade) | Values | Description |
+|-----|-----------------|-------------------|--------|-------------|
+| `mode` | -- | -- | `interactive`, `non-interactive` | Execution mode; set by orchestration workflows, not user-facing |
+| `model_profile` | `"balanced"` | `"balanced"` | `"speed"`, `"balanced"`, `"quality"` | Selects model tier for planning/execution agents |
+| `commit_docs` | `true` | `true` | `true`, `false` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | `false` | `true`, `false` | Add `--no-ignore` to broad rg searches |
+| `parallelization` | `true` | `true` | `true`, `false` | Enable parallel plan execution within a phase |
+| `brave_search` | auto-detected | `false` | `true`, `false` | Whether Brave Search API is available (auto-detected from `$BRAVE_API_KEY` or `~/.dgs/brave_api_key`) |
+| `granularity` | `"standard"` | `"standard"` | `"coarse"`, `"standard"`, `"fine"` | Planning granularity level (maps from deprecated `depth`) |
+
+### Workflow Keys (`workflow.*`)
+
+| Key | Default (fresh) | Default (upgrade) | Values | Description |
+|-----|-----------------|-------------------|--------|-------------|
+| `workflow.research` | `true` | `true` | `true`, `false` | Run research phase before planning |
+| `workflow.plan_check` | `true` | `true` | `true`, `false` | Run plan-check validation after planning |
+| `workflow.verifier` | `true` | `true` | `true`, `false` | Run auto-verifier after plan execution |
+| `workflow.nyquist_validation` | `true` | `true` | `true`, `false` | Validate plan coverage meets Nyquist sampling threshold |
+| `workflow.discipline` | `true` | `true` | `true`, `false` | Enforce `/dgs:` command routing discipline |
+| `workflow.ui_phase` | -- | -- | `true`, `false` | Enable UI-specific phase handling |
+| `workflow.ui_safety_gate` | -- | -- | `true`, `false` | Enable safety gate before UI changes |
+| `workflow._auto_chain_active` | -- | -- | `true`, `false` | Internal: tracks whether auto-chain execution is in progress |
+
+### Git Keys (`git.*`)
+
+| Key | Default (fresh) | Default (upgrade) | Values | Description |
+|-----|-----------------|-------------------|--------|-------------|
+| `git.base_branch` | `"main"` | `"main"` | any branch name | Integration target branch for code repo branching operations |
+| `git.branching_strategy` | `"none"` | `"none"` | `"none"`, `"phase"`, `"milestone"` | Git branching approach for code repos |
+| `git.phase_branch_template` | `"dgs/{project}/phase-{phase}-{slug}"` | `"dgs/{project}/phase-{phase}-{slug}"` | template string | Branch name template for phase strategy |
+| `git.milestone_branch_template` | `"dgs/{project}/{milestone}-{slug}"` | `"dgs/{project}/{milestone}-{slug}"` | template string | Branch name template for milestone strategy |
+| `git.sync_push` | `"prompt"` | `"off"` | `"off"`, `"prompt"`, `"auto"` | Remote push mode -- controls whether and how DGS pushes after workflows |
+| `git.sync_pull` | `"prompt"` | `"off"` | `"off"`, `"prompt"`, `"auto"` | Remote pull mode -- controls whether and how DGS pulls before workflows |
+| `git.sync` | -- (virtual) | -- (virtual) | `"off"`, `"prompt"`, `"auto"` | Virtual shorthand -- writes both `sync_push` and `sync_pull` simultaneously; never stored in config |
+
+### Alias Keys (`planning.*`)
+
+| Key | Alias for | Description |
+|-----|-----------|-------------|
+| `planning.commit_docs` | `commit_docs` | Alias for the top-level `commit_docs` key |
+| `planning.search_gitignored` | `search_gitignored` | Alias for the top-level `search_gitignored` key |
+
+### Local Keys (`config.local.json`)
+
+These keys are stored in `config.local.json` (gitignored, per-machine):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `current_project` | -- | Active project slug for multi-project setups |
+| `planningRoot` | -- | Absolute path to planning root (when non-standard) |
+| `v2_hint_shown` | -- | Whether the v2 migration hint has been shown |
+| `sync_hint_shown` | -- | Whether the sync first-run hint has been shown |
+
 </config_schema>
 
 <commit_docs_behavior>
@@ -74,7 +145,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: update state" --files ${state_path}
 ```
 
-The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
+The CLI checks `commit_docs` config and gitignore status internally -- no manual conditionals needed.
 
 </commit_docs_behavior>
 
@@ -132,7 +203,7 @@ To use uncommitted mode:
 
 **Base Branch:**
 
-All branching operations on code repos (branch creation in `execute-phase`, merge in `complete-milestone`) use `git.base_branch` as the starting point instead of hardcoded `main`. Default is `main`. Set during `/dgs:init-product` or change via `/dgs:settings`. The product folder repo always uses `main` — only sibling code repos registered in REPOS.md use the configured base branch.
+All branching operations on code repos (branch creation in `execute-phase`, merge in `complete-milestone`) use `git.base_branch` as the starting point instead of hardcoded `main`. Default is `main`. Set during `/dgs:init-product` or change via `/dgs:settings`. The product folder repo always uses `main` -- only sibling code repos registered in REPOS.md use the configured base branch.
 
 **When `git.branching_strategy: "none"` (default):**
 - All work commits to current branch
@@ -179,7 +250,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Branch creation:**
 
 ```bash
-# For phase strategy (code repos — product folder always uses main)
+# For phase strategy (code repos -- product folder always uses main)
 if [ "$BRANCHING_STRATEGY" = "phase" ]; then
   PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
   BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{project}/$PROJECT_SLUG/g" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
@@ -189,7 +260,7 @@ if [ "$BRANCHING_STRATEGY" = "phase" ]; then
   git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
 fi
 
-# For milestone strategy (code repos — product folder always uses main)
+# For milestone strategy (code repos -- product folder always uses main)
 if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
   MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
   BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{project}/$PROJECT_SLUG/g" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
@@ -209,7 +280,7 @@ fi
 | Delete without merging | `git branch -D` | Discard branch work |
 | Keep branches | (none) | Manual handling later |
 
-Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+Squash merge is recommended -- keeps main branch history clean while preserving the full development history in the branch (until deleted).
 
 **Use cases:**
 
@@ -221,4 +292,56 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+<sync_behavior>
+
+## Remote Synchronisation Config
+
+DGS can automatically pull from and push to remotes for all registered repos. Behaviour is controlled by two config keys: `git.sync_push` and `git.sync_pull`.
+
+### Three Modes
+
+| Mode | Pull behaviour | Push behaviour | Best for |
+|------|---------------|----------------|----------|
+| `off` | No pull, no prompt | No push, no prompt | Solo developers, no remote, or manual git users |
+| `prompt` | Asks before pulling (Y default) | Asks before pushing (Y default) | Teams learning DGS, cautious users |
+| `auto` | Pulls silently before work | Pushes silently after work | Established teams, CI/CD pipelines, job execution |
+
+### Default Behaviour
+
+- **Fresh installs** default to `prompt` -- the recommended mode for teams. New users get sync out of the box with a confirmation step.
+- **Existing users upgrading** default to `off` -- zero behaviour change. The `loadConfig()` defaults in `core.cjs` ensure that users who upgrade from pre-v17.0 never see unexpected sync activity.
+
+### Virtual Shorthand: `git.sync`
+
+`git.sync` is a convenience shorthand that writes both `sync_push` and `sync_pull` simultaneously:
+
+```bash
+dgs-tools config-set git.sync auto   # sets both sync_push AND sync_pull to "auto"
+```
+
+The `git.sync` key is never stored in `config.json` -- it expands at write time only. Reading config always returns `sync_push` and `sync_pull` individually.
+
+### Per-Workflow Cadence
+
+Not every workflow pulls and pushes. A cadence table in `sync.cjs` classifies each workflow by whether it should pull, push, both, or neither. A workflow syncs only when both conditions are true: the cadence table says it should AND the user's config mode is not `off`.
+
+Full per-workflow detail: see `references/sync-cadence.md`.
+
+### Configuration
+
+```bash
+# Set both directions at once
+dgs-tools config-set git.sync prompt
+
+# Set independently
+dgs-tools config-set git.sync_push auto
+dgs-tools config-set git.sync_pull prompt
+
+# Or use /dgs:settings for interactive toggle
+```
+
+Valid values: `off`, `prompt`, `auto`. Invalid values are rejected at `config-set` time.
+
+</sync_behavior>
+
 </planning_config>

package/deliver-great-systems/references/sync-cadence.md

@@ -0,0 +1,191 @@
+# Sync Cadence Table
+
+When each DGS workflow should pull from and push to remotes.
+
+**Source of truth:** The authoritative cadence classification lives in the `CADENCE_TABLE` constant in `bin/lib/sync.cjs`. This document explains the reasoning behind each classification and provides quick-reference views -- it is documentation only. `sync.cjs` does not parse this file.
+
+## Flag Semantics
+
+Each workflow has two boolean flags:
+
+- **`cadence_pull`** -- Whether the workflow *should* pull before starting. Ensures the agent works on the latest shared state.
+- **`cadence_push`** -- Whether the workflow *should* push after completing. Shares new artifacts with other team members.
+
+These flags express **intent** ("this workflow benefits from syncing"). The user's configuration determines **behavior**:
+
+- `git.sync_pull` and `git.sync_push` are mode strings: `off`, `prompt`, or `auto`.
+- A workflow syncs only when both conditions are true: the cadence flag says "should sync" AND the user config is not `off`.
+- Resolution: `if (cadence_pull && sync_pull !== 'off') { /* perform pull */ }`
+
+---
+
+## Primary Table: By Workflow Category
+
+### Phase Lifecycle
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| execute-phase | Yes | Yes | Reads ROADMAP/STATE/REQUIREMENTS; writes PLAN execution artifacts, SUMMARY, STATE |
+| plan-phase | Yes | Yes | Reads ROADMAP/CONTEXT/prior SUMMARYs; writes PLAN files |
+| discuss-phase | Yes | Yes | Reads phase context; writes CONTEXT.md with decisions |
+| research-phase | Yes | Yes | Reads phase scope; writes RESEARCH.md |
+| pause-work | No | Yes | Records pause state in STATE.md; does not need latest state to pause |
+| resume-work | Yes | No | Reads STATE.md to restore context; does not produce new artifacts |
+
+### Job Orchestration
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| run-job | Yes | Yes | Reads job definitions; writes execution results |
+| create-milestone-job | Yes | Yes | Reads milestone/roadmap state; writes job definition |
+| cancel-job | Yes | Yes | Reads job state; writes cancellation status |
+| rollback-job | Yes | Yes | Reads job state; writes rollback artifacts |
+
+### Milestone Lifecycle
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| new-milestone | Yes | Yes | Reads current state; writes new ROADMAP/milestone structure |
+| complete-milestone | Yes | Yes | Reads milestone state; writes completion status and audit |
+| audit-milestone | Yes | Yes | Reads planning state for audit; produces MILESTONE-AUDIT.md which captures the audit outcome for the team. Even clean audits produce artifacts useful to other team members. |
+| plan-milestone-gaps | Yes | Yes | Reads audit results; writes gap-filling phase plans |
+| cleanup | Yes | Yes | Reads completed state; writes archive/cleanup artifacts |
+
+### Ideas Pipeline
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| add-idea | No | Yes | Creates new idea file; does not need latest state to capture an idea |
+| discuss-idea | Yes | Yes | Reads idea and related context; writes discussion notes |
+| develop-idea | Yes | Yes | Reads idea context; writes developed idea with detail |
+| research-idea | Yes | Yes | Reads idea for research direction; writes research findings |
+| find-related-ideas | Yes | No | Reads all ideas for comparison; produces display output only |
+| consolidate-ideas | Yes | Yes | Reads multiple ideas; writes consolidated idea |
+| undo-consolidation | Yes | Yes | Reads consolidation state; writes restoration |
+| reject-idea | No | Yes | Writes rejection status; does not need latest state |
+| restore-idea | No | Yes | Writes restoration status; does not need latest state |
+| update-idea | No | Yes | Writes idea updates; single-idea operation does not need full sync |
+
+### Specs Pipeline
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| write-spec | Yes | Yes | Reads requirements/ideas for spec context; writes spec document |
+| refine-spec | Yes | Yes | Reads spec and review feedback; writes refined spec |
+| approve-spec | Yes | Yes | Reads spec for approval; writes approval status |
+| import-spec | No | Yes | Creates spec from external input; does not need latest state |
+
+### Quick/Fast Tasks
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| quick | Yes | Yes | Reads project state for context; writes task artifacts and STATE updates |
+| fast | Yes | Yes | Reads project state for context; writes task artifacts |
+| add-todo | Yes | Yes | Reads existing todos; writes new todo file |
+| check-todos | Yes | Yes | Reads todo state; writes completion status updates |
+
+### Project Management
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| new-project | Yes | Yes | Reads existing projects; writes new project structure |
+| init-product | Yes | Yes | Reads config; writes initial product scaffold |
+| complete-project | No | Yes | Writes completion status; single-project operation |
+| reactivate-project | No | Yes | Writes reactivation status; single-project operation |
+| switch-project | No | Yes | Writes project switch state; local operation |
+
+### Roadmap Structure
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| add-phase | Yes | Yes | Reads ROADMAP for placement; writes new phase entry |
+| insert-phase | Yes | Yes | Reads ROADMAP for insertion point; writes phase and renumbers |
+| remove-phase | Yes | Yes | Reads ROADMAP for target; writes removal and renumbers |
+
+### Verification and Testing
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| audit-phase | Yes | Yes | Reads phase artifacts for audit; produces UAT verification artifacts. Even clean audits (no gaps found) generate UAT records that are useful to other team members for tracking verification history. |
+| validate-phase | Yes | Yes | Reads phase for validation; writes validation results |
+| verify-work | Yes | Yes | Reads work artifacts; writes verification results |
+| add-tests | Yes | Yes | Reads code for test targets; writes test files |
+
+### Configuration
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| settings | Yes | Yes | Reads current config; writes updated config |
+| set-profile | No | Yes | Writes profile change; local preference |
+| add-repo | No | Yes | Writes REPOS.md entry; local operation |
+| remove-repo | No | Yes | Writes REPOS.md removal; local operation |
+| add-doc | No | Yes | Writes DOCS.md entry; local operation |
+| remove-doc | No | Yes | Writes DOCS.md removal; local operation |
+| capture-principle | No | Yes | Writes principle to CLAUDE.md; local capture |
+| map-codebase | No | Yes | Writes codebase map; does not need remote state |
+| reapply-patches | No | Yes | Writes patched files; local operation |
+
+### Progress and Display
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| progress | Yes | No | Reads STATE.md for display; does not write durable artifacts. Stale progress data is misleading, so pulling ensures the displayed metrics reflect actual team state. |
+| list-phase-assumptions | Yes | No | Reads phase context for display; does not write artifacts |
+
+### No Sync
+
+| Command | Pull | Push | Reason |
+|---------|------|------|--------|
+| help | No | No | Pure display; reads no project state |
+| join-discord | No | No | Opens external URL; no project interaction |
+| list-ideas | No | No | Shows local idea state for instant response. Users can pull manually before listing if freshness matters. |
+| list-specs | No | No | Shows local spec state for instant response |
+| list-docs | No | No | Shows local doc state for instant response |
+| list-jobs | No | No | Shows local job state for instant response |
+| list-projects | No | No | Shows local project state for instant response |
+| search | No | No | Searches local content; read-only |
+| overlap-check | No | No | Analyzes local content; read-only |
+| health | No | No | Checks local installation health; read-only |
+| update | No | No | Updates DGS package; not a project operation |
+| debug | No | No | Diagnostic/exploratory in unknown or broken state. Pulling in a broken context could worsen the situation by introducing merge conflicts or overwriting local diagnostic changes. Users can manually push after a successful debug resolution. |
+| node-repair | No | No | Repairs Node.js installation; not a project operation |
+| sync-upstream | No | No | Manages DGS package updates; separate from project sync |
+
+---
+
+## Summary: By Sync Pattern
+
+### Pull + Push (35 commands)
+
+Workflows that read shared state AND produce artifacts worth sharing.
+
+add-phase, add-tests, add-todo, approve-spec, audit-milestone, audit-phase, cancel-job, check-todos, cleanup, complete-milestone, consolidate-ideas, create-milestone-job, develop-idea, discuss-idea, discuss-phase, execute-phase, fast, init-product, insert-phase, new-milestone, new-project, plan-milestone-gaps, plan-phase, quick, refine-spec, remove-phase, research-idea, research-phase, rollback-job, run-job, settings, undo-consolidation, validate-phase, verify-work, write-spec
+
+### Push Only (17 commands)
+
+Workflows that produce artifacts but do not need the latest remote state to operate correctly.
+
+add-doc, add-idea, add-repo, capture-principle, complete-project, import-spec, map-codebase, pause-work, reactivate-project, reapply-patches, reject-idea, remove-doc, remove-repo, restore-idea, set-profile, switch-project, update-idea
+
+### Pull Only (4 commands)
+
+Workflows that read shared state for display or analysis but do not produce durable artifacts.
+
+find-related-ideas, list-phase-assumptions, progress, resume-work
+
+### No Sync (14 commands)
+
+Informational, diagnostic, or infrastructure workflows with no project sync benefit.
+
+debug, health, help, join-discord, list-docs, list-ideas, list-jobs, list-projects, list-specs, node-repair, overlap-check, search, sync-upstream, update
+
+---
+
+## Maintenance
+
+When adding a new DGS workflow, update two places:
+
+1. **`CADENCE_TABLE` in `bin/lib/sync.cjs`** -- Add one line with `{ pull: boolean, push: boolean }`.
+2. **This document** -- Add the workflow to the appropriate category table (with reasoning) and to the correct summary group (alphabetically).
+
+The cadence table in `sync.cjs` is the machine-readable source of truth. This document is the human-readable companion that explains the "why" behind each classification.