PDD Sync Command: Architecture Analysis

PDD Sync Command: Architecture Analysis

Executive Summary

The pdd sync command is a state machine-based orchestrator that coordinates 8 operations (auto-deps, generate, example, crash, verify, test, fix, update) to keep code synchronized with prompts. After thorough analysis of ~3000 lines of code across 5 key files, we identified 27 distinct bugs that cause unpredictable behavior.

Root Cause: The system behaves like a finite state machine but states and transitions are not explicitly defined. Instead, they're encoded as 615 lines of nested if-else chains in sync_determine_operation.py.

1. Architecture Overview

1.1 Core Components

1.2 State Inputs (5 Categories)

+-------------------------------------------------------------------+
|                      DECISION INPUTS                              |
+-------------------------------------------------------------------+
| 1. File Hashes (4 files x 2 states = 16 combinations)             |
|    - prompt_hash, code_hash, example_hash, test_hash              |
+-------------------------------------------------------------------+
| 2. File Existence (4 files x 2 states = 16 combinations)          |
|    - prompt, code, example, test: exists/missing                  |
+-------------------------------------------------------------------+
| 3. RunReport (outcome log)                                        |
|    - exists/missing, exit_code, tests_passed/failed               |
|    - coverage, test_hash (staleness detection)                    |
+-------------------------------------------------------------------+
| 4. Fingerprint (last operation state)                             |
|    - command: auto-deps/generate/example/crash/verify/test/fix    |
|    - timestamp: relative to run_report                            |
+-------------------------------------------------------------------+
| 5. Operation History (in-memory during sync session)              |
|    - Arbitrary sequence of operations (for cycle detection)       |
+-------------------------------------------------------------------+

Theoretical State Space: 16 x 16 x 8 x 8 x 4 = 32,768 states

1.3 Available Operations

1.4 Decision Tree Structure (Priority Order)

TIER 1: Runtime Signals (if run_report exists) - Lines 872-1018
+-- fingerprint.command == 'crash' + exit_code != 0 -> CRASH (retry)
+-- fingerprint.command == 'crash' + exit_code == 0 -> VERIFY
+-- tests_failed > 0 -> FIX
+-- exit_code != 0 + example success history -> FIX
+-- exit_code != 0 + no history -> CRASH
+-- coverage < target -> TEST

TIER 2: No Fingerprint (new unit) - Lines 1025-1066
+-- prompt exists + has dependencies -> AUTO-DEPS
+-- prompt exists + no dependencies -> GENERATE
+-- no prompt -> NOTHING

TIER 3: Validate Expected Files - Lines 1068-1081
+-- Files missing that should exist -> _handle_missing_expected_files()

TIER 4: Hash Comparison - Lines 1083-1094
+-- Detect changes: prompt/code/example/test

TIER 5: No Changes - Workflow Progression - Lines 1096-1246
+-- _is_workflow_complete() -> NOTHING
+-- All files exist + no run_report -> CRASH
+-- All files exist + exit_code != 0 -> CRASH
+-- All files exist + verify not done -> VERIFY
+-- All files exist + stale run_report -> TEST
+-- Code exists + example missing -> EXAMPLE
+-- Code + example exist + test missing -> (crash/verify/test sequence)
+-- Code missing -> GENERATE

TIER 6: Single File Changed - Lines 1295-1365
+-- prompt changed -> AUTO-DEPS or GENERATE
+-- code changed -> UPDATE
+-- test changed -> TEST
+-- example changed -> VERIFY

TIER 7: Multiple Files Changed - Lines 1367-1430
+-- prompt in changes -> ANALYZE_CONFLICT (LLM)
+-- code in changes -> VERIFY
+-- example in changes -> VERIFY
+-- test in changes -> TEST

TIER 8: Fallback - Lines 1432-1444
+-- NOTHING (confidence=0.50)

2. Identified Bugs (27 Total)

2.1 CRITICAL Bugs (Prevent Core Functionality)

2.2 HIGH Severity Bugs (Cause Incorrect Behavior)

2.3 MEDIUM Severity Bugs (Reduce Reliability)

2.4 LOW Severity Bugs (Edge Cases)

3. Root Cause Analysis

3.1 Fundamental Flaw: Implicit State Machine

The system should be a finite state machine with:

• Explicit states (NEW, HAS_CODE, HAS_EXAMPLE, VERIFIED, HAS_TESTS, SYNCED)
• Explicit transitions (state + event -> new_state + operation)
• Validation before each transition

Instead, it's:

• 615 lines of if-else chains
• Multiple sources of truth (fingerprint, run_report, file system)
• Reactive cycle detection (detect after failure, not prevent)

3.2 Multiple Sources of Truth

3.3 Skip Flags Create Hidden Paths

When --skip-verify or --skip-tests is used:

1. Fingerprint is saved with command='verify' or command='test'
2. But the operation never actually ran
3. _is_workflow_complete() sees fingerprint and returns True
4. State machine believes workflow is complete when it isn't

4. Recommended Architecture: Explicit State Machine

4.1 State Definition

class SyncState(Enum):
    NEW_PROMPT = "new_prompt"
    DEPS_NEEDED = "deps_needed"
    CODE_MISSING = "code_missing"
    EXAMPLE_MISSING = "example_missing"
    EXAMPLE_CRASHES = "example_crashes"
    VERIFY_PENDING = "verify_pending"
    TESTS_MISSING = "tests_missing"
    TESTS_FAIL = "tests_fail"
    COVERAGE_LOW = "coverage_low"
    SYNCED = "synced"
    CONFLICT = "conflict"

4.2 Transition Table

TRANSITIONS = {
    SyncState.NEW_PROMPT: {
        'has_deps': (SyncState.DEPS_NEEDED, 'auto-deps'),
        'no_deps': (SyncState.CODE_MISSING, 'generate'),
    },
    SyncState.CODE_MISSING: {
        'generate_success': (SyncState.EXAMPLE_MISSING, 'example'),
    },
    SyncState.EXAMPLE_MISSING: {
        'example_success': (SyncState.VERIFY_PENDING, 'crash'),
    },
    SyncState.VERIFY_PENDING: {
        'verify_success': (SyncState.TESTS_MISSING, 'test'),
        'verify_fail': (SyncState.EXAMPLE_CRASHES, 'crash'),
    },
    # ... etc
}

4.3 Benefits

1. Deterministic: Same inputs always produce same outputs
2. Testable: Each transition can be unit tested
3. Complete: All valid states explicitly defined
4. Maintainable: Easy to add/modify transitions
5. Debuggable: Current state always known

5. Files Reference

6. Testing Recommendations

6.1 Unit Tests Needed

1. Skip flag handling doesn't create false fingerprints
2. Cycle detection with various patterns
3. Post-crash exception handling
4. Run report creation for all paths
5. Return value normalization

6.2 Integration Tests Needed

1. Full sync with skip_verify=True
2. Full sync with crash-verify cycle scenario
3. Full sync with test failures scenario
4. Full sync with budget exhaustion
5. Full sync after external file modification

7. Conclusion

The sync command has significant architectural debt that causes unpredictable behavior. The 27 identified bugs stem from three root causes:

1. Implicit state machine: States and transitions are scattered across 615 lines of if-else chains
2. Multiple sources of truth: Fingerprint, run_report, and file system can become inconsistent
3. Reactive cycle detection: Cycles are detected after failure, not prevented

The recommended long-term solution is to refactor to an explicit state machine with:

• States defined as Python enum
• Transitions defined as dictionary
• Validation before each transition
• Single source of truth

Generated: 2024-12-20