@ktpartners/dgs-platform 2.6.3 → 2.7.0

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

@@ -0,0 +1,96 @@
+# Sync Hooks
+
+Standard sync pattern for workflow boundaries. @-include this reference from any workflow that needs sync support.
+
+Set `WORKFLOW_NAME` from the workflow's init call before following these steps.
+
+## Pre-Workflow Sync (Pull)
+
+Execute BEFORE the workflow starts any DGS state modifications.
+
+### Step: sync_before
+
+```bash
+SYNC_CHECK=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "${WORKFLOW_NAME}" --check-only)
+```
+
+Parse `SYNC_CHECK` JSON.
+
+**If `first_run_hint` is not null:** Display it as a one-liner to stderr.
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "${WORKFLOW_NAME}" --mark-hint-shown
+```
+
+**If `should_pull` is false:** Skip pull entirely. Continue to workflow.
+
+**If `stale.stale` is true and mode is `"off"`:** Display one-liner:
+`Warning: origin/{branch} is {commitsBehind} commits ahead. Consider pulling.`
+
+**If `should_pull` is true:**
+
+- **If `mode` is `"auto"` OR `suppressed` is true:** Pull silently:
+  ```bash
+  PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "${WORKFLOW_NAME}")
+  ```
+  Parse result. If `action` is `"aborted"`: report `diagnosis` and halt workflow.
+
+- **If `mode` is `"prompt"` and `suppressed` is false:**
+  Prompt user: `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 "${WORKFLOW_NAME}" --record-yes
+    PULL_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-pull "${WORKFLOW_NAME}")
+    ```
+    Parse result. If `action` is `"aborted"`:
+    - Display diagnosis
+    - Prompt: `Continue without pulling? [y/N]`
+    - If No (default): halt workflow
+    - If Yes: continue with warning
+  - If No: skip pull, continue to workflow
+
+## Post-Workflow Sync (Push)
+
+Execute AFTER the workflow completes all state modifications and commits.
+
+### Step: sync_after
+
+```bash
+PUSH_CHECK=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "${WORKFLOW_NAME}" --check-only)
+```
+
+Parse `PUSH_CHECK` JSON.
+
+**If `should_push` is false:** Skip push entirely. Done.
+
+**If `should_push` is true:**
+
+- **If `mode` is `"auto"` OR `suppressed` is true:** Push silently:
+  ```bash
+  PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "${WORKFLOW_NAME}")
+  ```
+  Parse result. Display `summary` if action is `"pushed"`. Display `message` if action is `"warning"`.
+
+- **If `mode` is `"prompt"` and `suppressed` is false:**
+  Prompt user: `Push to remote? [Y/n]`
+  - If Yes (or empty/default):
+    ```bash
+    node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "${WORKFLOW_NAME}" --record-yes
+    PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "${WORKFLOW_NAME}")
+    ```
+    Parse result. Display summary.
+  - If No: skip push, done
+
+## Mid-Workflow Push
+
+For workflows that push at intermediate points (execute-phase after each plan, run-job after each phase).
+
+### Step: sync_mid_push
+
+```bash
+PUSH_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" sync workflow-push "${WORKFLOW_NAME}" --mid-workflow)
+```
+
+Parse result. Mid-workflow pushes are always silent (no prompt). User consented at workflow start.
+
+- If `action` is `"warning"`: accumulate warning for end-of-workflow summary
+- If `action` is `"pushed"`: continue silently (optionally log if `message` mentions new remote branch creation)

package/deliver-great-systems/test/cadence.test.cjs

@@ -0,0 +1,160 @@
+/**
+ * Tests for cadence table — workflow sync classification and init integration
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const fs = require('fs');
+
+const { getCadence, CADENCE_TABLE } = require('../bin/lib/sync.cjs');
+
+// ─── Cadence Table Tests ─────────────────────────────────────────────────────
+
+describe('CADENCE_TABLE', () => {
+  it('has exactly 70 entries', () => {
+    assert.strictEqual(Object.keys(CADENCE_TABLE).length, 70);
+  });
+});
+
+describe('getCadence — Pull + Push workflows (35)', () => {
+  const pullPush = [
+    'execute-phase', 'plan-phase', 'discuss-phase', 'research-phase',
+    'run-job', 'create-milestone-job', 'cancel-job', 'rollback-job',
+    'new-milestone', 'complete-milestone', 'audit-milestone', 'plan-milestone-gaps',
+    'cleanup', 'discuss-idea', 'develop-idea', 'research-idea',
+    'consolidate-ideas', 'undo-consolidation', 'write-spec', 'refine-spec',
+    'approve-spec', 'quick', 'fast', 'add-todo', 'check-todos',
+    'new-project', 'init-product', 'add-phase', 'insert-phase', 'remove-phase',
+    'audit-phase', 'validate-phase', 'verify-work', 'add-tests', 'settings',
+  ];
+
+  assert.strictEqual(pullPush.length, 35, 'Expected 35 pull+push workflows');
+
+  for (const name of pullPush) {
+    it(`${name} -> pull:true, push:true`, () => {
+      const result = getCadence(name);
+      assert.deepStrictEqual(result, { pull: true, push: true });
+    });
+  }
+});
+
+describe('getCadence — Push only workflows (17)', () => {
+  const pushOnly = [
+    'pause-work', 'add-idea', 'import-spec', 'reject-idea', 'restore-idea',
+    'update-idea', 'add-doc', 'remove-doc', 'add-repo', 'remove-repo',
+    'capture-principle', 'complete-project', 'reactivate-project', 'switch-project',
+    'set-profile', 'map-codebase', 'reapply-patches',
+  ];
+
+  assert.strictEqual(pushOnly.length, 17, 'Expected 17 push-only workflows');
+
+  for (const name of pushOnly) {
+    it(`${name} -> pull:false, push:true`, () => {
+      const result = getCadence(name);
+      assert.deepStrictEqual(result, { pull: false, push: true });
+    });
+  }
+});
+
+describe('getCadence — Pull only workflows (4)', () => {
+  const pullOnly = [
+    'resume-work', 'progress', 'find-related-ideas', 'list-phase-assumptions',
+  ];
+
+  assert.strictEqual(pullOnly.length, 4, 'Expected 4 pull-only workflows');
+
+  for (const name of pullOnly) {
+    it(`${name} -> pull:true, push:false`, () => {
+      const result = getCadence(name);
+      assert.deepStrictEqual(result, { pull: true, push: false });
+    });
+  }
+});
+
+describe('getCadence — No sync workflows (14)', () => {
+  const noSync = [
+    'help', 'join-discord', 'list-ideas', 'list-specs', 'list-docs',
+    'list-jobs', 'list-projects', 'search', 'overlap-check', 'health',
+    'update', 'debug', 'node-repair', 'sync-upstream',
+  ];
+
+  assert.strictEqual(noSync.length, 14, 'Expected 14 no-sync workflows');
+
+  for (const name of noSync) {
+    it(`${name} -> pull:false, push:false`, () => {
+      const result = getCadence(name);
+      assert.deepStrictEqual(result, { pull: false, push: false });
+    });
+  }
+});
+
+describe('getCadence — unknown workflows', () => {
+  it('returns no-sync for unknown workflow names', () => {
+    assert.deepStrictEqual(getCadence('unknown-command'), { pull: false, push: false });
+  });
+
+  it('returns no-sync for empty string', () => {
+    assert.deepStrictEqual(getCadence(''), { pull: false, push: false });
+  });
+
+  it('returns no-sync for undefined', () => {
+    assert.deepStrictEqual(getCadence(undefined), { pull: false, push: false });
+  });
+});
+
+describe('getCadence — group totals', () => {
+  it('all entries sum to 70 (35 + 17 + 4 + 14)', () => {
+    const entries = Object.entries(CADENCE_TABLE);
+    const pullPush = entries.filter(([, v]) => v.pull && v.push).length;
+    const pushOnly = entries.filter(([, v]) => !v.pull && v.push).length;
+    const pullOnly = entries.filter(([, v]) => v.pull && !v.push).length;
+    const noSync = entries.filter(([, v]) => !v.pull && !v.push).length;
+
+    assert.strictEqual(pullPush, 35, '35 pull+push');
+    assert.strictEqual(pushOnly, 17, '17 push-only');
+    assert.strictEqual(pullOnly, 4, '4 pull-only');
+    assert.strictEqual(noSync, 14, '14 no-sync');
+    assert.strictEqual(pullPush + pushOnly + pullOnly + noSync, 70, 'total = 70');
+  });
+});
+
+// ─── Init Integration Tests ─────────────────────────────────────────────────
+
+describe('Init cadence output (integration)', () => {
+  // Only run integration tests if we are in a DGS product directory
+  const hasPlanningDir = fs.existsSync(path.join(process.cwd(), '.planning'));
+  const hasConfig = fs.existsSync(path.join(process.cwd(), '.planning', 'dgs.config.json'));
+
+  if (!hasPlanningDir && !hasConfig) {
+    it('skipped — not running in a DGS product directory', () => {
+      // Informational skip
+    });
+    return;
+  }
+
+  const { execSync } = require('child_process');
+  const toolsPath = path.join(__dirname, '..', 'bin', 'dgs-tools.cjs');
+
+  it('execute-phase init returns cadence_pull:true, cadence_push:true', () => {
+    const raw = execSync(`node ${toolsPath} init execute-phase 114 --raw`, {
+      cwd: process.cwd(),
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const data = JSON.parse(raw.trim());
+    assert.strictEqual(data.cadence_pull, true);
+    assert.strictEqual(data.cadence_push, true);
+  });
+
+  it('progress init returns cadence_pull:true, cadence_push:false', () => {
+    const raw = execSync(`node ${toolsPath} init progress --raw`, {
+      cwd: process.cwd(),
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const data = JSON.parse(raw.trim());
+    assert.strictEqual(data.cadence_pull, true);
+    assert.strictEqual(data.cadence_push, false);
+  });
+});