windowmaker-wl/tools/wm-port/README.md

# wm-port: WindowMaker Wayland Port Dispatcher

Agent-assisted task execution for the Wayland port, driven by `ACTION_PLAN.md` and `ACTION_PLAN_PROMPTS.md`.

## Quick Start

```bash
export PATH="$PWD/tools/wm-port:$PATH"

# See what's available
wm-tasks

# Dispatch a task from the action plan
wm-dispatch B.1

# Generate an ad-hoc task from a template
wm-gen 3 "Replace XClearArea at wrlib/context.c:730 with wm_backend->window_clear_area"

# Monitor
wm-status --watch

# Collect results from background tasks
wm-collect

# Review diffs
wm-review B.1
```

## Scripts

| Script | Purpose | Default model |
|---|---|---|
| `wm-dispatch` | Execute action plan tasks | `qwen/qwen3-coder` |
| `wm-gen` | Generate ad-hoc tasks from templates | `anthropic/claude-sonnet-4` |
| `wm-tasks` | Show task board (status, waves, blockers) | — |
| `wm-status` | Monitor active agent sessions | — |
| `wm-collect` | Harvest results from background sessions | — |
| `wm-review` | Interactive diff review, approve/reject | — |
| `wm-done` | Manually mark tasks done/undone | — |
| `wm-kill` | Kill running agent sessions | — |

## Two ways to dispatch

### `wm-dispatch` — action plan tasks

Executes pre-defined tasks from `ACTION_PLAN.md`. Each task is mapped to a template, and the prompt is assembled automatically.

```bash
wm-dispatch B.1                       # single task, foreground
wm-dispatch --bg A5.1 B.1 B.3 C.1    # batch, background
wm-dispatch --wave 1 --bg             # entire wave in parallel
wm-dispatch --next 5 --bg             # next 5 unblocked tasks
wm-dispatch --dry-run A5.1            # preview prompt without dispatching
```

### `wm-gen` — ad-hoc tasks from templates

Generates a task from a template number + plain English description. Use this for follow-ups, fixes from verification findings, or anything not in the action plan.

```bash
# List templates
wm-gen --list

# Template + description
wm-gen 3 "Replace XClearArea at wrlib/context.c:730 with wm_backend->window_clear_area"
wm-gen 4 "Guard X11 init block at WINGs/widgets.c:637-739"
wm-gen 2 "Eliminate _x11_raw at src/framewin.c:1165" --name fix-framewin

# Pipe findings from a verification log
grep 'STOP\|issue' tools/wm-port/logs/F.2.log | wm-gen 3 --name fix-F2

# Preview
wm-gen --dry-run 4 "Guard the X11 block at wrlib/context.c:725-740"
```

## Workflow

### 1. Pick tasks

```bash
wm-tasks                  # full board
wm-tasks --ready          # what can be dispatched now?
wm-tasks --wave 1         # what's in wave 1?
wm-tasks B.1              # details on a specific task
```

### 2. Dispatch

```bash
# From the action plan
wm-dispatch B.1
wm-dispatch --wave 1 --bg

# Ad-hoc from template
wm-gen 3 "Replace XFoo at src/bar.c:42 with wm_backend->baz"
```

### 3. Monitor

```bash
wm-status --watch             # dashboard (refreshes every 2s)
wm-status --follow A5.1       # tail one agent's chat live
wm-kill A5.1                  # kill a stuck agent
wm-kill --all                 # kill all
```

### 4. Collect (background tasks)

```bash
wm-collect                    # harvest all finished sessions
wm-collect --dry-run          # preview without acting
```

Scans idle `wm-port-*` sessions, reads results, updates `done.txt`, saves logs, kills successful sessions. Failed/unclear sessions are kept for inspection.

### 5. Review (code change tasks)

```bash
wm-review --pending           # list branches ready for review
wm-review B.1                 # interactive review
```

The review flow:
1. Shows diff stat and colored diff
2. Shows agent's reported status (DONE/STOP/FAIL)
3. Prompts for action:
   - **approve** — merges the `port/<id>` branch, marks task done
   - **reject** — optionally deletes the branch
   - **diff** — full diff in pager
   - **log** — agent's full output in pager
   - **edit** — opens changed files in `$EDITOR`
   - **skip** — come back later

### 6. Track

```bash
wm-done G.1                   # manually mark done
wm-done --undo G.1            # re-open
wm-tasks                      # updated board
```

## What updates `done.txt`

| Path | When |
|---|---|
| `wm-dispatch` (foreground) | Agent reports DONE → auto-marked |
| `wm-collect` | Harvests background sessions → marks DONE ones |
| `wm-review --approve` | Human approves diff → marked |
| `wm-done` | Manual mark/unmark |

## Session lifecycle

Sessions are always created with `-keep`. Cleanup is handled by the scripts:

- **DONE** → session killed (unless `--keep`)
- **STOP / FAIL / unclear** → session kept for inspection, path printed
- `wm-collect` kills DONE sessions, keeps everything else
- `wm-kill` for manual cleanup

## How it works

1. `wm-dispatch` extracts the task block from `ACTION_PLAN.md` and the matching template from `ACTION_PLAN_PROMPTS.md`
2. `wm-gen` takes a template number + description directly
3. Both compose a prompt: task description + template procedure + reference tables
4. An ollie agent session is spawned via `$OLLIE/s/b`
5. The agent creates a `port/<id>` git branch, makes changes, verifies, reports status
6. You review with `wm-review` or results are harvested by `wm-collect`

## Files

```
tools/wm-port/
  task-map.sh     # Task database: ID→template, ID→wave, ID→blockers
  done.txt        # Completed task IDs (one per line)
  logs/           # Agent output logs (one per task/name)
  wm-dispatch     # Action plan task dispatcher
  wm-gen          # Ad-hoc task generator from templates
  wm-tasks        # Task board
  wm-status       # Session monitor
  wm-collect      # Background session harvester
  wm-review       # Diff reviewer
  wm-done         # Manual done/undo
  wm-kill         # Session killer
```

## Configuration

Defaults can be overridden per-call with flags:

| Flag | `wm-dispatch` default | `wm-gen` default |
|---|---|---|
| `--backend` | `openrouter` | `openrouter` |
| `--model` | `qwen/qwen3-coder` | `anthropic/claude-sonnet-4` |
| `--agent` | `coding` | `coding` |