parallel-safe-implementation

Guidelines for implementing tasks in Ralph parallel mode without causing conflicts.

---

The Job

1. Implement assigned task completely
2. Stay within declared touches paths
3. Respect mutex boundaries
4. Avoid undeclared hotspots
5. Commit atomically with clear messages

Do NOT: modify DAG, schedule tasks, merge branches, or review other work.

---

Core Rules

1. Stay in Your Lane

Only modify files within your task's touches declaration:

touches: ["src/auth/**", "tests/auth/**"]

Allowed: src/auth/middleware.ts, tests/auth/login.test.ts Forbidden: src/api/routes.ts, package.json

2. Respect Mutex

If your task has mutex: ["db-migrations"], you have exclusive access to that resource. Other tasks with the same mutex will wait.

3. Avoid Hotspots

Never touch these without explicit mutex:

• package.json / package-lock.json → mutex: lockfile
• Database migrations → mutex: db-migrations
• Route configuration → mutex: router
• Global config files → mutex: global-config

---

Implementation Checklist

Before starting:

• [ ] Read task description and acceptance criteria
• [ ] Check touches for allowed paths
• [ ] Check mutex for exclusive resources
• [ ] Check dependsOn to understand available interfaces

While implementing:

• [ ] Make small, focused changes
• [ ] Avoid large refactors outside task scope
• [ ] Don't rename shared types/interfaces unless task requires it
• [ ] Test your changes in isolation

Before committing:

• [ ] Verify only allowed files changed
• [ ] Run relevant tests
• [ ] Write clear commit message referencing task ID

---

Commit Discipline

Good Commits

AUTH-002: Add auth middleware

- Implement JWT validation
- Add role-based access control
- Add unit tests for middleware

Bad Commits

WIP

various fixes

---

Conflict Prevention

Do

• Import existing modules, don't copy code
• Use existing patterns from codebase
• Add new files instead of heavily modifying shared ones
• Coordinate interface changes via contracts

Don't

• Refactor unrelated code
• Change file structure outside scope
• Modify global types without contract declaration
• Add dependencies without lockfile mutex

---

Touched Areas Summary

At task completion, report what you changed:

Task AUTH-002 completed
Files changed: 4
  + src/auth/middleware.ts (new)
  + src/auth/roles.ts (new)
  ~ src/auth/index.ts (export added)
  + tests/auth/middleware.test.ts (new)
  
Within declared touches: ✓
Mutex used: contract:auth-api

---

Safety Checklist Output

Pre-implementation safety check:
  ✓ touches: ["src/auth/**"] - clear scope
  ✓ mutex: ["contract:auth-api"] - exclusive access
  ✓ dependsOn: ["AUTH-001"] - user table available
  
  Hotspots to avoid:
    ✗ package.json (no lockfile mutex)
    ✗ db/migrations/** (no db-migrations mutex)
    
  Ready to implement safely