@ktpartners/dgs-platform 2.7.1 → 2.7.3

package/commands/dgs/capture-principle.md

@@ -124,7 +124,7 @@ Use today's date for the `Added` field.
 
 If `commit_docs` is true:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --files .planning/docs/product/DESIGN-PRINCIPLES.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: capture design principle - {title}" --push --files .planning/docs/product/DESIGN-PRINCIPLES.md
 ```
 
 If `commit_docs` is false, just save the file without committing.

package/deliver-great-systems/bin/dgs-tools.cjs

@@ -699,6 +699,7 @@ async function main() {
 
       // Existing single-repo commit logic
       const amend = args.includes('--amend');
+      const push = args.includes('--push');
       const message = args[1];
       // Parse --files flag (collect args after --files, stopping at other flags)
       const filesIndex = args.indexOf('--files');
@@ -706,7 +707,7 @@ async function main() {
       // Parse --phase-dir flag (available for context, passed through if supported)
       const phaseDirIdx = args.indexOf('--phase-dir');
       const phaseDir = phaseDirIdx !== -1 ? args[phaseDirIdx + 1] : null;
-      commands.cmdCommit(cwd, message, files, raw, amend);
+      commands.cmdCommit(cwd, message, files, raw, amend, push);
       break;
     }
 

package/deliver-great-systems/bin/lib/commands.cjs

@@ -214,7 +214,7 @@ function cmdResolveModel(cwd, agentType, raw) {
   output(result, raw, model);
 }
 
-function cmdCommit(cwd, message, files, raw, amend) {
+function cmdCommit(cwd, message, files, raw, amend, push) {
   if (!message && !amend) {
     error('commit message required');
   }
@@ -259,6 +259,27 @@ function cmdCommit(cwd, message, files, raw, amend) {
   const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
   const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
   const result = { committed: true, hash, reason: 'committed' };
+
+  // Handle push if requested
+  if (push) {
+    const syncPush = config.sync_push || 'off';
+
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushResult = pushAll(cwd, { force: true });
+        result.pushed = pushResult.ok;
+        result.push_result = pushResult;
+      } catch (err) {
+        result.pushed = false;
+        result.push_result = { ok: false, error: err.message };
+      }
+    } else if (syncPush === 'prompt') {
+      result.needs_push = true;
+    }
+    // 'off' or any other value: no push fields added
+  }
+
   output(result, raw, hash || 'committed');
 }
 

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

@@ -0,0 +1,325 @@
+/**
+ * Tests for commands.cjs — cmdCommit --push behavior
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ * Tests use real temp git repos with mocked pushAll to verify push integration.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { createTempProject } = require('./test-helpers.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Capture JSON output from cmdCommit by intercepting console.log.
+ * cmdCommit calls output() which calls console.log(JSON.stringify(...)).
+ */
+function captureCommitOutput(fn) {
+  const logs = [];
+  const origLog = console.log;
+  console.log = (...args) => logs.push(args.join(' '));
+  try {
+    fn();
+  } finally {
+    console.log = origLog;
+  }
+  // Parse the last JSON output line
+  for (let i = logs.length - 1; i >= 0; i--) {
+    try {
+      return JSON.parse(logs[i]);
+    } catch { /* not JSON, skip */ }
+  }
+  return null;
+}
+
+/**
+ * Set up a temp project with git, write a file, and return the fixture.
+ */
+function setupGitFixture(syncPush) {
+  const configOverrides = {};
+  if (syncPush) {
+    configOverrides.git = { sync_push: syncPush };
+  }
+  const fixture = createTempProject({
+    withGit: true,
+    withConfig: configOverrides,
+  });
+  return fixture;
+}
+
+/**
+ * Write a new file and stage it so there's something to commit.
+ */
+function writeAndStageFile(cwd, name, content) {
+  const filePath = path.join(cwd, name);
+  fs.writeFileSync(filePath, content || `content-${Date.now()}`);
+  execSync(`git add "${name}"`, { cwd, stdio: 'pipe' });
+}
+
+/**
+ * Mock pushAll on the sync.cjs module exports.
+ * Since cmdCommit does a lazy require('./sync.cjs') and destructures pushAll,
+ * we need to replace it on the cached module BEFORE cmdCommit runs.
+ */
+function mockPushAll(mockFn) {
+  const syncPath = require.resolve('./sync.cjs');
+  const syncModule = require(syncPath);
+  const original = syncModule.pushAll;
+  syncModule.pushAll = mockFn;
+  return () => { syncModule.pushAll = original; };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('cmdCommit with push=false (default behavior)', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('auto');
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('commits without push fields when push is false', () => {
+    writeAndStageFile(fixture.cwd, 'test-no-push.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit no push', [], true, false, false);
+    });
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.equal(result.reason, 'committed');
+    assert.equal(result.pushed, undefined, 'pushed should not be set');
+    assert.equal(result.push_result, undefined, 'push_result should not be set');
+    assert.equal(result.needs_push, undefined, 'needs_push should not be set');
+  });
+
+  it('commits without push fields when push is undefined', () => {
+    writeAndStageFile(fixture.cwd, 'test-no-push-undef.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit no push undef', [], true, false);
+    });
+    assert.equal(result.committed, true);
+    assert.equal(result.pushed, undefined);
+    assert.equal(result.needs_push, undefined);
+  });
+});
+
+describe('cmdCommit with push=true, sync_push=auto, pushAll succeeds', () => {
+  let fixture;
+  let commands;
+  let restorePushAll;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('auto');
+    restorePushAll = mockPushAll(() => ({
+      ok: true,
+      results: [{ repo: 'test', status: 'pushed', commits: 1, message: 'Pushed 1 commit' }],
+      summary: '1 pushed',
+    }));
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    restorePushAll();
+    fixture.cleanup();
+  });
+
+  it('returns pushed=true and push_result with ok=true', () => {
+    writeAndStageFile(fixture.cwd, 'test-auto-push-ok.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit auto push ok', [], true, false, true);
+    });
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.equal(result.pushed, true);
+    assert.ok(result.push_result);
+    assert.equal(result.push_result.ok, true);
+    assert.equal(result.needs_push, undefined, 'needs_push should not be set in auto mode');
+  });
+});
+
+describe('cmdCommit with push=true, sync_push=auto, pushAll fails', () => {
+  let fixture;
+  let commands;
+  let restorePushAll;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('auto');
+    restorePushAll = mockPushAll(() => ({
+      ok: false,
+      results: [{ repo: 'test', status: 'failed', commits: null, message: 'Push rejected' }],
+      summary: '1 failed',
+    }));
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    restorePushAll();
+    fixture.cleanup();
+  });
+
+  it('returns committed=true, pushed=false, push_result with ok=false', () => {
+    writeAndStageFile(fixture.cwd, 'test-auto-push-fail.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit auto push fail', [], true, false, true);
+    });
+    assert.equal(result.committed, true, 'commit must succeed even if push fails');
+    assert.ok(result.hash);
+    assert.equal(result.pushed, false);
+    assert.ok(result.push_result);
+    assert.equal(result.push_result.ok, false);
+  });
+});
+
+describe('cmdCommit with push=true, sync_push=auto, pushAll throws', () => {
+  let fixture;
+  let commands;
+  let restorePushAll;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('auto');
+    restorePushAll = mockPushAll(() => {
+      throw new Error('Network unreachable');
+    });
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    restorePushAll();
+    fixture.cleanup();
+  });
+
+  it('returns committed=true, pushed=false, push_result with error message', () => {
+    writeAndStageFile(fixture.cwd, 'test-auto-push-throw.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit auto push throw', [], true, false, true);
+    });
+    assert.equal(result.committed, true, 'commit must succeed even if pushAll throws');
+    assert.ok(result.hash);
+    assert.equal(result.pushed, false);
+    assert.ok(result.push_result);
+    assert.equal(result.push_result.ok, false);
+    assert.ok(result.push_result.error.includes('Network unreachable'));
+  });
+});
+
+describe('cmdCommit with push=true, sync_push=prompt', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('prompt');
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns needs_push=true, no pushed or push_result fields', () => {
+    writeAndStageFile(fixture.cwd, 'test-prompt-push.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit prompt push', [], true, false, true);
+    });
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.equal(result.needs_push, true);
+    assert.equal(result.pushed, undefined, 'pushed should not be set in prompt mode');
+    assert.equal(result.push_result, undefined, 'push_result should not be set in prompt mode');
+  });
+});
+
+describe('cmdCommit with push=true, sync_push=off', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('off');
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns no push-related fields (same as push=false)', () => {
+    writeAndStageFile(fixture.cwd, 'test-off-push.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit off push', [], true, false, true);
+    });
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.equal(result.pushed, undefined, 'pushed should not be set when sync_push=off');
+    assert.equal(result.push_result, undefined, 'push_result should not be set when sync_push=off');
+    assert.equal(result.needs_push, undefined, 'needs_push should not be set when sync_push=off');
+  });
+});
+
+describe('cmdCommit with push=true but nothing to commit', () => {
+  let fixture;
+  let commands;
+  let pushAllCalled;
+  let restorePushAll;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('auto');
+    pushAllCalled = false;
+    restorePushAll = mockPushAll(() => {
+      pushAllCalled = true;
+      return { ok: true, results: [], summary: '' };
+    });
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    restorePushAll();
+    fixture.cleanup();
+  });
+
+  it('does not attempt push when commit has nothing to commit', () => {
+    // Don't write any new file -- nothing to commit
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test nothing to commit', [], true, false, true);
+    });
+    assert.equal(result.committed, false);
+    assert.equal(result.reason, 'nothing_to_commit');
+    assert.equal(pushAllCalled, false, 'pushAll should not be called when nothing to commit');
+    assert.equal(result.pushed, undefined);
+    assert.equal(result.needs_push, undefined);
+  });
+});
+
+describe('cmdCommit with push=true, sync_push unset (defaults to off)', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    // No sync_push in config -- should default to 'off'
+    fixture = setupGitFixture(undefined);
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns no push-related fields when sync_push is not configured', () => {
+    writeAndStageFile(fixture.cwd, 'test-unset-push.txt');
+    const result = captureCommitOutput(() => {
+      commands.cmdCommit(fixture.cwd, 'test commit unset push', [], true, false, true);
+    });
+    assert.equal(result.committed, true);
+    assert.equal(result.pushed, undefined);
+    assert.equal(result.push_result, undefined);
+    assert.equal(result.needs_push, undefined);
+  });
+});

package/deliver-great-systems/bin/lib/init.cjs

@@ -9,7 +9,7 @@ const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInte
 const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 const { getPlanningRoot, PROJECTS_DIR } = require('./paths.cjs');
 const { parseReposMd, validateReposMdEager } = require('./repos.cjs');
-const { getCadence } = require('./sync.cjs');
+const { getCadence, pullAll } = require('./sync.cjs');
 
 /**
  * Safely resolve the current git author string.
@@ -25,6 +25,67 @@ function resolveAuthorSafe(cwd) {
   }
 }
 
+// ─── Sync Pull Helper ────────────────────────────────────────────────────────
+
+/**
+ * Apply sync pull logic to an init result object.
+ *
+ * Enriches the result with `needs_pull` and optionally `pull_result` based on
+ * the sync_pull config and cadence_pull for this workflow. This moves pull
+ * orchestration into init itself so workflows get pull state in their JSON
+ * without needing to manually orchestrate sync commands.
+ *
+ * Modes:
+ *   - cadence_pull=false OR sync_pull="off": sets needs_pull=false, no pull
+ *   - sync_pull="prompt": sets needs_pull=true, no pull (workflow prompts user)
+ *   - sync_pull="auto": executes pullAll, sets needs_pull=false, adds pull_result
+ *
+ * CRITICAL: Never throws — init must always return its JSON.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} workflowName - Workflow name for logging
+ * @param {Object} result - The init result object to enrich (mutated in place)
+ */
+function applySyncPull(cwd, workflowName, result) {
+  const syncPull = result.sync_pull;
+  const cadencePull = result.cadence_pull;
+
+  // No pull: cadence says no, or mode is off
+  if (!cadencePull || syncPull === 'off') {
+    result.needs_pull = false;
+    return;
+  }
+
+  // Prompt mode: signal that pull is needed but don't execute
+  if (syncPull === 'prompt') {
+    result.needs_pull = true;
+    return;
+  }
+
+  // Auto mode: execute pull immediately
+  if (syncPull === 'auto') {
+    result.needs_pull = false;
+    try {
+      const pullResult = pullAll(cwd, { force: true });
+      result.pull_result = {
+        action: pullResult.ok ? 'pulled' : 'failed',
+        ok: pullResult.ok,
+        summary: pullResult.summary,
+      };
+    } catch (err) {
+      result.pull_result = {
+        action: 'failed',
+        ok: false,
+        summary: err.message,
+      };
+    }
+    return;
+  }
+
+  // Unknown mode: treat as off
+  result.needs_pull = false;
+}
+
 // ─── v2 Project Context Resolution ──────────────────────────────────────────
 
 /**
@@ -232,6 +293,7 @@ function cmdInitExecutePhase(cwd, phase, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'execute-phase', result);
   output(result, raw);
 }
 
@@ -327,6 +389,7 @@ function cmdInitPlanPhase(cwd, phase, raw) {
     } catch {}
   }
 
+  applySyncPull(cwd, 'plan-phase', result);
   output(result, raw);
 }
 
@@ -406,6 +469,7 @@ function cmdInitNewProject(cwd, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'new-project', result);
   output(result, raw);
 }
 
@@ -454,6 +518,7 @@ function cmdInitNewMilestone(cwd, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'new-milestone', result);
   output(result, raw);
 }
 
@@ -521,6 +586,7 @@ function cmdInitQuick(cwd, description, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'quick', result);
   output(result, raw);
 }
 
@@ -569,6 +635,7 @@ function cmdInitResume(cwd, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'resume-work', result);
   output(result, raw);
 }
 
@@ -612,6 +679,7 @@ function cmdInitVerifyWork(cwd, phase, raw) {
     guard: ctx.guard,
   };
 
+  applySyncPull(cwd, 'verify-work', result);
   output(result, raw);
 }
 
@@ -655,6 +723,7 @@ function cmdInitAuditPhase(cwd, phase, raw) {
     guard: ctx.guard,
   };
 
+  applySyncPull(cwd, 'audit-phase', result);
   output(result, raw);
 }
 
@@ -755,6 +824,7 @@ function cmdInitPhaseOp(cwd, phase, raw, workflow) {
     } catch {}
   }
 
+  applySyncPull(cwd, workflow || 'plan-phase', result);
   output(result, raw);
 }
 
@@ -834,6 +904,7 @@ function cmdInitTodos(cwd, area, raw, workflow) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, workflow || 'check-todos', result);
   output(result, raw);
 }
 
@@ -927,6 +998,7 @@ function cmdInitMilestoneOp(cwd, raw, workflow) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, workflow || 'complete-milestone', result);
   output(result, raw);
 }
 
@@ -1033,6 +1105,7 @@ function cmdInitMapCodebase(cwd, onlyRepo, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'map-codebase', result);
   output(result, raw);
 }
 
@@ -1149,6 +1222,7 @@ function cmdInitProgress(cwd, raw) {
     v2_hint: ctx.v2_hint || null,
   };
 
+  applySyncPull(cwd, 'progress', result);
   output(result, raw);
 }
 
@@ -1166,4 +1240,5 @@ module.exports = {
   cmdInitMilestoneOp,
   cmdInitMapCodebase,
   cmdInitProgress,
+  applySyncPull,
 };

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

@@ -1210,6 +1210,179 @@ describe('branch_name with {project} resolution', () => {
 
 // ─── Backward Compatibility ──────────────────────────────────────────────────
 
+// ─── Sync Pull: needs_pull field tests ────────────────────────────────────────
+
+// Helper: v1 fixture with custom git.sync_pull setting
+function v1FixtureWithSyncPull(syncPull) {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({ git: { sync_pull: syncPull } }),
+    '.planning/STATE.md': '# State',
+    '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n',
+    '.planning/REQUIREMENTS.md': '# Requirements',
+    '.planning/PROJECT.md': '# Project',
+    '.planning/phases/01-test-phase/01-CONTEXT.md': '# Context',
+    '.planning/phases/01-test-phase/01-01-PLAN.md': '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan',
+  });
+}
+
+describe('init commands include needs_pull field (sync_pull off)', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('init execute-phase returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init plan-phase returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'plan-phase 1');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init quick returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'quick "test task"');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init progress returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'progress');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init new-project returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'new-project');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init resume returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'resume');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init milestone-op returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'milestone-op');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init map-codebase returns needs_pull false when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('no pull_result when sync_pull is off', () => {
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.equal(result.pull_result, undefined);
+  });
+});
+
+describe('init with sync_pull prompt returns needs_pull true', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = v1FixtureWithSyncPull('prompt');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('init execute-phase returns needs_pull true when sync_pull is prompt and cadence says pull', () => {
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.equal(result.needs_pull, true);
+    assert.equal(result.pull_result, undefined);
+  });
+
+  it('init plan-phase returns needs_pull true when sync_pull is prompt', () => {
+    const result = runInit(fixture.cwd, 'plan-phase 1');
+    assert.equal(result.needs_pull, true);
+    assert.equal(result.pull_result, undefined);
+  });
+
+  it('init quick returns needs_pull true when sync_pull is prompt', () => {
+    const result = runInit(fixture.cwd, 'quick "test task"');
+    assert.equal(result.needs_pull, true);
+    assert.equal(result.pull_result, undefined);
+  });
+
+  it('init resume returns needs_pull true when sync_pull is prompt (cadence_pull is true for resume-work)', () => {
+    const result = runInit(fixture.cwd, 'resume');
+    assert.equal(result.needs_pull, true);
+    assert.equal(result.pull_result, undefined);
+  });
+});
+
+describe('init with sync_pull auto but no remote returns pull_result', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = v1FixtureWithSyncPull('auto');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('init execute-phase returns needs_pull false and pull_result when sync_pull is auto', () => {
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.equal(result.needs_pull, false);
+    assert.ok(result.pull_result, 'pull_result should be an object');
+    assert.ok('action' in result.pull_result, 'pull_result should have action field');
+    assert.ok('ok' in result.pull_result, 'pull_result should have ok field');
+    assert.ok('summary' in result.pull_result, 'pull_result should have summary field');
+  });
+
+  it('pull_result never causes init to throw', () => {
+    // This should not throw even though the fixture has no git remote
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.ok(result, 'init should return result even when pull has no remote');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init plan-phase returns pull_result when sync_pull is auto', () => {
+    const result = runInit(fixture.cwd, 'plan-phase 1');
+    assert.equal(result.needs_pull, false);
+    assert.ok(result.pull_result, 'pull_result should be an object');
+  });
+});
+
+describe('init with cadence_pull false skips pull regardless of sync mode', () => {
+  let fixture;
+
+  beforeEach(() => {
+    // map-codebase has cadence { pull: false, push: true }
+    fixture = v1FixtureWithSyncPull('prompt');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('init map-codebase returns needs_pull false because cadence_pull is false', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.cadence_pull, false, 'map-codebase cadence should have pull: false');
+    assert.equal(result.needs_pull, false);
+  });
+
+  it('init map-codebase returns no pull_result even with sync_pull auto', () => {
+    // Change to auto mode
+    const autoFixture = v1FixtureWithSyncPull('auto');
+    try {
+      const result = runInit(autoFixture.cwd, 'map-codebase');
+      assert.equal(result.needs_pull, false);
+      assert.equal(result.pull_result, undefined, 'No pull_result when cadence_pull is false');
+    } finally {
+      autoFixture.cleanup();
+    }
+  });
+});
+
 describe('backward compatibility: v1 output is superset of old shape', () => {
   let fixture;
 

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

@@ -72,7 +72,7 @@ Parse the JSON result to get `id`, `filename`, `path`.
 
 <step name="git_commit">
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add #${id} - ${title}" --files ${project_root}/ideas/pending/${filename} ${project_root}/ideas/manifest.json
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add #${id} - ${title}" --push --files ${project_root}/ideas/pending/${filename} ${project_root}/ideas/manifest.json
 ```
 </step>
 

package/deliver-great-systems/workflows/add-todo.md

@@ -123,7 +123,7 @@ If STATE.md exists (use `state_path` from init):
 Commit the todo and any updated state:
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: capture todo - [title]" --files ${pending_dir}/[filename] ${state_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: capture todo - [title]" --push --files ${pending_dir}/[filename] ${state_path}
 ```
 
 Tool respects `commit_docs` config and gitignore automatically.

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

@@ -162,7 +162,7 @@ Perform the approval state transition and audit trail update.
 
 4. Commit the changes:
    ```bash
-   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: approve $SPEC_ID v$VERSION" --files "$SPEC_FILE_PATH"
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: approve $SPEC_ID v$VERSION" --push --files "$SPEC_FILE_PATH"
    ```
 </step>
 

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

@@ -278,7 +278,7 @@ When `RERUN_FAILED_MODE` is true, the structural verifier also reruns, but only
 **Commit the UAT file:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "[AUDIT] audit(${PHASE_ARG}): ${test_failures} test failures, ${structural_gaps} structural gaps" --files "${uat_path}" "${log_path}"
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "[AUDIT] audit(${PHASE_ARG}): ${test_failures} test failures, ${structural_gaps} structural gaps" --push --files "${uat_path}" "${log_path}"
 ```
 </step>
 

package/deliver-great-systems/workflows/complete-milestone.md

@@ -1211,7 +1211,7 @@ git push origin v[X.Y]
 Commit milestone completion.
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: complete v[X.Y] milestone" --files ${project_root}/milestones/v[X.Y]-ROADMAP.md ${project_root}/milestones/v[X.Y]-REQUIREMENTS.md ${project_root}/v[X.Y]-MILESTONE-AUDIT.md ${project_root}/MILESTONES.md ${project_path} ${state_path}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: complete v[X.Y] milestone" --push --files ${project_root}/milestones/v[X.Y]-ROADMAP.md ${project_root}/milestones/v[X.Y]-REQUIREMENTS.md ${project_root}/v[X.Y]-MILESTONE-AUDIT.md ${project_root}/MILESTONES.md ${project_path} ${state_path}
 ```
 ```
 

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

@@ -527,8 +527,10 @@ The CLI handles:
 Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-{X}): complete phase execution" --files ${roadmap_path} ${state_path} ${requirements_path} ${phase_dir}/*-VERIFICATION.md
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(phase-{X}): complete phase execution" --push --files ${roadmap_path} ${state_path} ${requirements_path} ${phase_dir}/*-VERIFICATION.md
 ```
+
+Parse the commit result JSON. If `needs_push` is true (sync_push is "prompt" mode), handle push prompting via the existing sync_after step. If `pushed` is true, the push already happened atomically with the commit -- skip the sync_after push for this commit (avoid double-push). If `pushed` is false and `push_result` exists, log the push warning but do not halt.
 </step>
 
 <step name="sync_after">

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

@@ -264,7 +264,7 @@ Original: will be saved to ${project_root}/{attachment_path}
 
    **Execute the commit:**
    ```bash
-   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --files ${project_root}/specs/spec-{slug}.md ${project_root}/{attachment_path} ${project_root}/specs/spec-{slug}/docs/INDEX.md ${project_root}/specs/spec-{slug}/docs/.names.json
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: import {id} - {title} (from {original-filename})" --push --files ${project_root}/specs/spec-{slug}.md ${project_root}/{attachment_path} ${project_root}/specs/spec-{slug}/docs/INDEX.md ${project_root}/specs/spec-{slug}/docs/.names.json
    ```
    The `dgs-tools.cjs commit` helper with `--files` stages only the specified files and commits them. This ensures other unstaged/uncommitted changes in the working tree are not included. The `.names.json` file is included because `docs add` creates it as internal metadata for INDEX rebuilds.
 

package/deliver-great-systems/workflows/new-milestone.md

@@ -129,7 +129,7 @@ Last activity: [today] — Milestone v[X.Y] started (from spec [spec-id])
 ### Commit
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name] (from spec)" --files ${project_path} ${state_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name] (from spec)" --push --files ${project_path} ${state_path}
 ```
 
 ### Link Spec to Milestone
@@ -143,7 +143,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id
 Include the updated spec file in a commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v$VERSION" --files ${project_root}/specs/$SPEC_FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v$VERSION" --push --files ${project_root}/specs/$SPEC_FILENAME
 ```
 
 ### Continue to Step 7
@@ -216,7 +216,7 @@ Keep Accumulated Context section from previous milestone.
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files ${project_path} ${state_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --push --files ${project_path} ${state_path}
 ```
 
 ## 7. Load Context and Resolve Models
@@ -406,7 +406,7 @@ If "adjust": Return to scoping.
 
 **Commit requirements:**
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files ${project_root}/REQUIREMENTS.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define milestone v[X.Y] requirements" --push --files ${project_root}/REQUIREMENTS.md
 ```
 
 ## 10. Create Roadmap
@@ -485,7 +485,7 @@ Success criteria:
 
 **Commit roadmap** (after approval):
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${project_root}/REQUIREMENTS.md
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --push --files ${roadmap_path} ${state_path} ${project_root}/REQUIREMENTS.md
 ```
 
 ## 10.5. Overlap Check (v2 only)

package/deliver-great-systems/workflows/new-project.md

@@ -420,7 +420,7 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --files ${project_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: initialize project" --push --files ${project_path}
 ```
 
 ## 5. Resolve Model Profile
@@ -829,7 +829,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define v1 requirements" --files ${requirements_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: define v1 requirements" --push --files ${requirements_path}
 ```
 
 ## 8. Create Roadmap
@@ -960,7 +960,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --files ${roadmap_path} ${state_path} ${requirements_path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: create roadmap ([N] phases)" --push --files ${roadmap_path} ${state_path} ${requirements_path}
 ```
 
 ### Link Spec to Milestone (spec-driven mode only)
@@ -974,7 +974,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs link-milestone --id
 Include the updated spec file in a commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --files $SPEC_PATH
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: link $SPEC_ID to v1.0" --push --files $SPEC_PATH
 ```
 
 ## 8.5. Overlap Check (v2 only)

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

@@ -163,7 +163,7 @@ Use full relative paths. Group by topic area.]
 
 5. Commit:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(${padded_phase}): generate context from PRD" --push --files "${phase_dir}/${padded_phase}-CONTEXT.md"
 ```
 
 6. Set `context_content` to the generated CONTEXT.md content and continue to step 5 (Handle Research).

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

@@ -776,7 +776,7 @@ Build file list:
 - If `$FULL_MODE` and verification file exists: `${QUICK_DIR}/${quick_id}-VERIFICATION.md`
 
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --files ${file_list}
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs(quick-${quick_id}): ${DESCRIPTION}" --push --files ${file_list}
 ```
 
 Get final commit hash:

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

@@ -239,7 +239,7 @@ All writes happen here, atomically at the end of the session. No file changes oc
 
 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"
+    node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "refine(spec): $SPEC_SLUG v$NEW_VERSION -- $SUMMARY" --push --files "$SPEC_FILE_PATH"
     ```
 </step>
 

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

@@ -124,12 +124,12 @@ LIST=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --raw)
 Parse to find the idea's state and filename, then commit:
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: update #${id} - ${field}" --files ${path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: update #${id} - ${field}" --push --files ${path}
 ```
 
 For note appends, use:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add note to #${id}" --files ${path}
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "ideas: add note to #${id}" --push --files ${path}
 ```
 </step>
 

package/deliver-great-systems/workflows/verify-work.md

@@ -373,14 +373,14 @@ Clear Current Test section:
 [testing complete]
 ```
 
-Commit the UAT file:
+Commit the UAT file and VERIFICATION.md:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files "${phase_dir}/{phase_num}-UAT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "test({phase_num}): complete UAT - {passed} passed, {issues} issues" --push --files "${phase_dir}/{phase_num}-UAT.md" "${phase_dir}/{phase_num}-VERIFICATION.md"
 ```
 
 If `AUTO_MODE` is true, prefix the commit message with `[AUTO] `:
 ```bash
-node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "[AUTO] test({phase_num}): complete UAT - {passed} passed, {issues} issues" --files "${phase_dir}/{phase_num}-UAT.md"
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "[AUTO] test({phase_num}): complete UAT - {passed} passed, {issues} issues" --push --files "${phase_dir}/{phase_num}-UAT.md" "${phase_dir}/{phase_num}-VERIFICATION.md"
 ```
 
 Present summary:

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

@@ -222,7 +222,7 @@ node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs specs add-log-entry --id
 
 Commit the draft:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --files ${project_root}/specs/$filename
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: draft $id from ideas $idea_ids" --push --files ${project_root}/specs/$filename
 ```
 
 Store `SPEC_ID` and `FILENAME` for subsequent steps.
@@ -289,7 +289,7 @@ Use AskUserQuestion: "Review the draft spec above. Type **approve** to send to r
 
 After approval, commit any changes:
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: revise draft $SPEC_ID" --push --files ${project_root}/specs/$FILENAME
 ```
 </step>
 
@@ -350,7 +350,7 @@ Estimated cost: ~$X.XX
 **6. Commit updated spec:**
 
 ```bash
-node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --files ${project_root}/specs/$FILENAME
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "specs: review $SPEC_ID (N rounds)" --push --files ${project_root}/specs/$FILENAME
 ```
 </step>
 

package/package.json

@@ -4,7 +4,7 @@
   "bugs": {
     "url": "https://github.com/KT-Partners-Ltd/dgs-platform-docs/issues"
   },
-  "version": "2.7.1",
+  "version": "2.7.3",
   "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"