# Ralph Progress Log

## Codebase Patterns
- **docs/commands.md placement convention**: per-command sections live under `### claw-forge X` headings;
  sub-sections (Pro tips, Failure modes, Parallel-safe agents, Related commands) use `####`; deeper
  nested headings inside a sub-section use `#####`. Match this depth when adding new content.
- **Cross-file source-of-truth**: CLAUDE.md is the architectural source-of-truth, docs/commands.md is
  user-facing. When user-facing docs lag behind ship code, the gap is usually documented in CLAUDE.md
  first (architecture section, "Key Conventions" bullets) and just needs translation into the
  docs/commands.md style (more example-driven, less architecture-driven).

---

Started: Sat May  2 20:36:20 AEST 2026

## 2026-05-02 - US-001
- Documented `touches_files` / file-claim locks in docs/commands.md.
- Files changed: docs/commands.md (added `#### Parallel-safe agents via file-claim locks` subsection
  between Pro tips and Failure modes under `### claw-forge run`).
- **Learnings:**
  - The new section covers: WHAT (atomic per-session file locks), HOW (opt-in via
    `touches_files: list[str]` on POST /sessions/{id}/tasks), AUTO-RELEASE (on
    completed/failed/paused), SPATIAL-vs-TEMPORAL (file claims complement merge-gating, not
    replace it), and the three REST endpoints (POST/DELETE/GET on /sessions/{id}/file-claims).
  - Lint untouched (no code changes); markdown fences balanced (166 → still even); table valid.
  - Surrounding sub-sections are `#### Pro tips` → `#### Failure modes — resume_conflict` →
    `#### Related commands`. The new section slotted between Pro tips and Failure modes —
    feature explanation before edge-case explanation.
---

## 2026-05-02 - US-002
- Documented `git.prefer_resumable` + `git.resume_stale_threshold` in docs/commands.md.
- Files changed: docs/commands.md (added `#### Resume preference` subsection between
  `##### When NOT to use smart` and `#### LLM conflict advisor`).
- **Learnings:**
  - Confirmed defaults from `claw_forge/cli.py:816-818`: `prefer_resumable=True`,
    `resume_stale_threshold=50`. PRD's line refs (781-783) had drifted; verify in code, not in
    PRD notes.
  - Cross-referenced the new `resume_conflict` failure-mode section (US-001 area):
    `prefer_resumable=false` does NOT disable the pre-dispatch sync. The sync runs
    unconditionally as a guardrail — important to surface so users don't think disabling
    the preference also disables the safety net.
  - Placement convention: three resume-flow knobs (`cleanup_orphan_worktrees`,
    `prefer_resumable`/`resume_stale_threshold`, `llm_conflict_proposals`) now sit as `####`
    peers in adjacency. Discoverability win for users tuning resume behaviour holistically.
---

## 2026-05-02 - US-003
- Added 3 rows to README.md "Workflow Features" table covering recent v0.5.x capabilities.
- Files changed: README.md (3 rows appended to existing table; no restructuring).
- **Learnings:**
  - PRD said "3 columns: Feature / Command / Flag" but the actual table is 2 columns
    ("| Feature | Command / Flag |"). Matched the actual table format — one of the
    acceptance criteria explicitly required preserving existing structure, which trumps
    the PRD's possibly-stale description.
  - New rows: Parallel-safe agents (touches_files), Reset failed/blocked in bulk
    (Kanban UI button), Resume-conflict surfacing (auto-detected, recovery path documented).
  - Cross-references all three to user-facing detail in docs/commands.md (added by US-001
    and US-002, plus the existing resume_conflict failure-modes section).
---
