docs: update changelog, architecture, CLI tools, config, features, and user guide for parallel execution fixes

Documentation updates for #1116 fixes and code review findings:

- CHANGELOG.md: Add --no-verify commit flag, post-wave hook validation,
  STATE.md file locking, duplicate function removal, cross-platform init
- docs/ARCHITECTURE.md: Add 'Parallel Commit Safety' section explaining
  --no-verify strategy and STATE.md lockfile mechanism
- docs/CLI-TOOLS.md: Document --no-verify flag on commit command with
  usage guidance
- docs/CONFIGURATION.md: Add note about pre-commit hooks and parallel
  execution behavior under parallelization settings
- docs/FEATURES.md: Add --no-verify to executor capabilities, add
  'Parallel Safety' section
- docs/USER-GUIDE.md: Add troubleshooting entries for parallel execution
  build lock errors and Windows EPERM crashes, update recovery table
This commit is contained in:
Tom Boucher
2026-03-16 20:48:02 -04:00
parent 60f38cdb9e
commit 214a621cb2
5 changed files with 35 additions and 1 deletions

View File

@@ -247,6 +247,14 @@ Each executor gets:
- Project context (PROJECT.md, STATE.md)
- Phase context (CONTEXT.md, RESEARCH.md if available)
#### Parallel Commit Safety
When multiple executors run within the same wave, two mechanisms prevent conflicts:
1. **`--no-verify` commits** — Parallel agents skip pre-commit hooks (which can cause build lock contention, e.g., cargo lock fights in Rust projects). The orchestrator runs `git hook run pre-commit` once after each wave completes.
2. **STATE.md file locking** — All `writeStateMd()` calls use lockfile-based mutual exclusion (`STATE.md.lock` with `O_EXCL` atomic creation). This prevents the read-modify-write race condition where two agents read STATE.md, modify different fields, and the last writer overwrites the other's changes. Includes stale lock detection (10s timeout) and spin-wait with jitter.
---
## Data Flow