1 Robust, Re‑entrant Locking Layer

Below is a consolidated remediation plan that turns the weaknesses we identified in the sync_determine_operation prototype into a production‑grade design. The items are grouped in the same rough order of risk and impact as the earlier critique, so you can decide where to start if you cannot implement everything at once.

1  Robust, Re‑entrant Locking Layer

2  Authoritative “Last‑Generated” Fingerprint

Why

Without a frozen baseline of exactly what the generator produced, the decision engine cannot distinguish a legitimate manual edit from an uncommitted regeneration, leading to false “update” or “generate” cycles.

How

1. Commit adjunct – Every successful generate, fix, or update writes a side‑car file .pdd/meta/<basename>_<lang>.json:

   {
     "pdd_version": "0.0.40",
     "timestamp": "2025‑06‑11T15:04:00Z",
     "prompt_hash": "e6de…",
     "code_hash":   "87b1…",
     "example_hash":"90ce…",
     "test_hash":   "faba…",
     "command": "generate --incremental"
   }
   

2. Store in git – Add the meta file to the same commit as the generated artefacts. Now HEAD always contains the last machine output even if the user regenerated locally and forgot to commit.

3. Hash instead of mtime – The sync detector now computes current file hashes and does a direct set comparison with the meta file. This removes all reliance on timestamps, eliminating problems with rebases, check‑outs, and ZIP uploads.

3  Deterministic Conflict‑Resolution Strategy

4  Runtime & Test Signals Folded into Decision Engine

1. After each crash, verify, or pytest invocation, write a run report to .pdd/meta/<basename>_<lang>_run.json:

   {
     "timestamp": "2025‑06‑11T15:33:10Z",
     "exit_code": 0,
     "tests_passed": 57,
     "tests_failed": 0,
     "coverage": 91.3
   }
   

2. The next sync reads this file first. * If exit_code ≠ 0 → recommend crash. * If tests_failed > 0 → recommend fix. * If coverage < target → recommend test.

This closes the loop between observed executable health and the high‑level workflow.

5  Safety Nets for Destructive Operations

6  Cross‑Unit Dependency Awareness

1. Maintain a lightweight DAG in .pdd/meta/dependency_graph.json mapping prompt → prompts imported in its example (populated by auto‑deps).
2. When a prompt regenerates and its public interface (example) hash changes, enqueue downstream prompts for re‑sync.
3. Provide pdd sync --all-affected BASENAME to recursively walk the DAG and update dependants in topological order, re‑using the same file lock to avoid dead‑locks.

7  Fallback Manual‑Merge Wizard

If automatic analysis fails (confidence < 0.8, JSON invalid, or 3‑way merge conflict):

pdd sync BASENAME --interactive

1. Presents a TUI (Textual, rich) diff of prompt / code / test.
2. User can accept, reject, or edit each hunk.
3. On save, wizard writes the merged artefacts and updates the fingerprint (§ 2) so future syncs resume normally.

This avoids losing developer intent while still keeping “prompt as source‑of‑truth”.

8  Git Integration Hardening

• Use git status --porcelain=2 -z and rigorous parsing to separate staged, unstaged, untracked.
• Follow renames with git diff --name-status --find-renames.
• Detect sparse‑checkout by checking .git/info/sparse-checkout and fall back to work‑tree only if file not in index.
• In non‑git directories, deliberately degrade to “hash‑only” mode and emit a warning banner.

9  Observability & House‑Keeping

10  Platform‑Portability Fixes

• Use psutil.pid_exists(pid) instead of /proc.
• Lock‑file directory is %LOCALAPPDATA%\pdd\locks on Windows, $XDG_RUNTIME_DIR/pdd/locks on POSIX.
• File‑extension maps live in languages.yaml; add cpp,hpp,ts,tsx,rs,... so the detector handles multi‑file units.

Putting It All Together – Revised Decision Algorithm

Acquire FD lock  ─┐
                  │
Read meta file    │──┐  (baseline fingerprints)
Hash current files│  │
Compare           │  │
                  │  ├─► If fingerprints equal and last run OK → DONE
                  │  │
Analyse deltas    │  │
  ├─ Single file?─┘  │──► simple heuristic
  └─ ≥2 files?  ─────┘
          │
          ├─ change magnitude < T?  → heuristic
          └─ otherwise → LLM analysis (deterministic, cached)
Apply plan
            ├─ needs code write? → create safety branch + 3‑way merge
            ├─ needs execution? → run crash/pytest; write run-report
            └─ needs downstream? → push to dependency queue
Update meta fingerprints
Release lock

This pipeline never relies on timestamps, is safe against concurrent executions, preserves manual edits, and remains deterministic & auditable—while still falling back gracefully when an edge case escapes automation.

Incremental Adoption Path

Rolling out in this order gives you the highest risk‑reduction early while deferring the heavier graph & TUI work until the basics are rock solid.

Conclusion

The current heuristic‑only implementation will work on day‑one demos but is fragile in production. Anchoring sync decisions on persistent fingerprints, using atomic, re‑entrant locks, and folding real execution signals into the decision tree eliminates most mis‑classifications. Layering deterministic LLM assistance and strong safety nets on top completes a workflow that is both hands‑off for the happy path and recoverable when reality intervenes—delivering the promise of Prompt‑Driven Development without the foot‑guns.