refactor: Extract completion-detector logic into testable modules

[EivMeyer]

Problem

Two duplicate implementations of completion detection:

1. Inline in orchestrator.js (lines 2158-2195) - completion-detector agent created dynamically
2. File src/agents/git-pusher-agent.json - Same logic as 500-char minified JS string

Issues

• DRY violation: Same "all validators approved" logic duplicated
• No constants: Topic names (VALIDATION_RESULT, IMPLEMENTATION_READY) are magic strings
• Untestable: Inline JS in JSON, no unit tests for injection logic
• String-boolean hack: approved === true || approved === 'true' scattered in both
• Two injection paths: startCluster() (line 736-757) AND _injectCompletionAgent() (line 2128-2200)

Affected Files

File	Lines	Issue
src/orchestrator.js	736-757, 2128-2200	Two injection paths with duplicated placeholder logic
src/agents/git-pusher-agent.json	10	500-char minified trigger script

Existing Test Coverage (DO NOT BREAK)

Test File	What It Tests
tests/config-validator.test.js	Completion handler validation
tests/integration/trigger-evaluation.test.js	helpers.allResponded(), helpers.hasConsensus()
tests/orchestrator-subscription-race.test.js	CLUSTER_COMPLETE not lost on fast completion
tests/integration/orchestrator-flow.test.js	Full message flow to cluster termination

Acceptance Criteria

• Single source of truth for "all validators approved" logic
• Constants module for topic names (TOPICS.VALIDATION_RESULT)
• Factory function to create completion agents
• Regression tests BEFORE refactoring
• Unit tests for extracted modules
• All existing tests pass

[EivMeyer]

Implementation Plan

Step 0: Regression Tests FIRST

Write tests for current behavior BEFORE touching any production code.

tests/unit/completion-injection.test.js

describe('_injectCompletionAgent', () => {
  describe('default mode', () => {
    it('should inject completion-detector when none exists')
    it('should NOT inject when completion-detector already exists')
    it('should NOT inject when git-pusher already exists')
  });
  describe('PR mode', () => {
    it('should inject git-pusher when autoPr=true')
    it('should inject git-pusher when ZEROSHOT_PR=1')
    it('should replace {{issue_number}} placeholder')
    it('should replace {{issue_title}} placeholder')
  });
});

tests/unit/completion-trigger-logic.test.js

describe('completion trigger logic', () => {
  it('should return false when no IMPLEMENTATION_READY')
  it('should return true when no validators exist')
  it('should return false when not all validators responded')
  it('should return false when any validator rejected')
  it('should return true when all approved (boolean)')
  it('should return true when all approved (string "true")')
  it('should use LATEST response per validator')
  it('should ignore responses from non-validators')
});

Gate: All Step 0 tests must pass before proceeding.

---

Step 1: Create Constants Module

File: src/constants/topics.js

const TOPICS = Object.freeze({
  ISSUE_OPENED: 'ISSUE_OPENED',
  IMPLEMENTATION_READY: 'IMPLEMENTATION_READY',
  VALIDATION_RESULT: 'VALIDATION_RESULT',
  CLUSTER_COMPLETE: 'CLUSTER_COMPLETE',
});

const ACTIONS = Object.freeze({
  EXECUTE_TASK: 'execute_task',
  STOP_CLUSTER: 'stop_cluster',
});

module.exports = { TOPICS, ACTIONS };

---

Step 2: Extract Trigger Logic

File: src/lib/completion-logic.js

• normalizeApproved(value) - Fix string-boolean hack at source
• allValidatorsApproved({ ledger, cluster }) - Core consensus check
• hasRealEvidence(results) - Evidence validation for git-pusher
• createCompletionTriggerScript({ requireEvidence }) - Generate script strings

---

Step 3: Create Agent Factory

File: src/agents/completion-agent-factory.js

function getCompletionAgent(options = {}) {
  if (options.autoPr) {
    return createGitPusherAgent(options);
  }
  return createCompletionAgent();
}

---

Step 4: Update Orchestrator

Consolidate two injection paths into one using factory.

---

Step 5: Simplify git-pusher-agent.json

Remove inline script, keep only prompt template.

---

Step 6: Add Unit Tests for New Modules

• tests/unit/completion-logic.test.js
• tests/unit/completion-agent-factory.test.js

---

Target Architecture

src/
├── constants/
│   └── topics.js              # Topic/action/role constants
├── lib/
│   └── completion-logic.js    # Extracted trigger logic
├── agents/
│   ├── completion-agent-factory.js  # Agent factory
│   └── git-pusher-agent.json        # Prompt only
└── orchestrator.js                   # Uses factory

Verification

1. Step 0 regression tests pass
2. npm test passes after each step
3. Manual E2E: zeroshot run <issue> --worktree and zeroshot run <issue> --pr