---
ontology: true
type: pattern
domain: hha-workspace
summary: Developer task board — how tasks for the developer are posted, picked up and completed through /admin/dev-tasks and the board API instead of email
tags: [developer, tasks, board, api, communication]
status: active
discovered: 2026-10-21
relatedTo: [INTEGRATION-THREAD, CTO-COMMUNICATION-RULES]
---

# Developer task board

Nash, Oct 21, 2026: "Communication with the developer, I would like to have it through the board." Tasks for the developer are no longer sent by email. They're posted on the board, ordered by urgency, and the developer moves each one from **Pending** to **Ongoing** to **Completed**. The CTO sees completions and questions on the board.

## Who does what

| Who | How | Can |
|---|---|---|
| Workspace CTO (this chat), other projects | Board API with a board key (`scripts/dev-task.mjs`) | Add, edit, reorder, move, remove/restore tasks; comment; read activity |
| Nash (platform admin) | The page `/admin/dev-tasks` | Everything the CTO can do on the page: move, drag to reorder, comment; grant access |
| Developer | The page `/admin/dev-tasks`, after Nash grants access | Open a task, Start (Pending → Ongoing), Back to Pending, Mark completed with a note (Ongoing → Completed), Reopen; ask questions on the task |

The developer never edits or deletes a brief. Removing a task archives it with its history, so it can be restored.

## Ordering

- A new task lands in **Pending** after every task at least as urgent and before the less urgent ones (urgent → high → normal → low).
- The CTO or Nash can then place it anywhere (`place --before / --after / --top / --bottom`, or drag on the page).
- **Completed** shows the most recently finished first.

## A task brief

Every task carries what the developer needs, the same structure the developer emails used:

| Field | Meaning |
|---|---|
| `title` | Short name (3–200 characters) |
| `project` | `HHA Workspace` (default), `HHA Brain`, `Synchron`… The page filters by project |
| `urgency` | `urgent`, `high`, `normal` (default), `low` |
| `summary` | One or two lines shown on the card |
| `why` | The reason and the vision |
| `steps` | The steps in order (array of strings) |
| `done_when` | How "done" is checked |
| `report_back` | What to write in the completion note |
| `do_not_touch` | What must stay unchanged |
| `details` | Anything longer (plain text) |
| `due_date` | Optional `YYYY-MM-DD`; overdue cards turn red |

Example `task.json`:

```json
{
  "title": "Production deploy and cron schedules",
  "urgency": "urgent",
  "summary": "Deploy main and confirm the permit-retry and permit-expiry schedules.",
  "why": "Several finished fixes are waiting on main. Until they're deployed, customers don't get them.",
  "steps": ["Deploy main to production.", "Confirm the permit-retry and permit-expiry cron schedules (times only)."],
  "done_when": "Production runs the latest main and both schedules ran once.",
  "report_back": "The commit in production, the deploy time, and the two schedule times.",
  "do_not_touch": "Real customer data."
}
```

## Using it from the command line (this chat or any project)

```bash
node scripts/dev-task.mjs add --file task.json
node scripts/dev-task.mjs add --title "Rotate the storage key" --urgency high --why "…" --step "Create" --step "Verify" --done-when "…"
node scripts/dev-task.mjs list
node scripts/dev-task.mjs show T-12
node scripts/dev-task.mjs place T-12 --top
node scripts/dev-task.mjs comment T-12 "Yes, keep the query string."
node scripts/dev-task.mjs activity --since 2026-10-21T00:00:00Z
node scripts/dev-task.mjs remove T-12        # archived, can be restored
```

## API (bearer board key)

All under `/api/dev-tasks`; header `Authorization: Bearer <board key>`; optional `X-Task-Source: <name shown in the history>`.

| Method and path | Does |
|---|---|
| `GET /api/dev-tasks?status=&project=&since=&include_archived=1` | List tasks |
| `POST /api/dev-tasks` | Create a task (lands in Pending, placed by urgency) |
| `GET /api/dev-tasks/{T-12 or id}` | One task with its history and comments |
| `PATCH /api/dev-tasks/{ref}` | Edit fields; `status`; `completion_note`; `place: {before|after: <T-3 or id>}` or `{edge: top|bottom}`; `archived: true/false` |
| `DELETE /api/dev-tasks/{ref}` | Remove (archive) |
| `POST /api/dev-tasks/{ref}/comments` | Comment `{ "text": "…" }` |
| `GET /api/dev-tasks/activity?since=` | Recent events, newest first |

The page uses `/api/admin/dev-tasks/{ref}` (signed-in session; developer rules apply).

## Keys and settings

- **Server (Workspace production):** `DEV_TASKS_API_KEY_HASHES` holds the SHA-256 of each caller's key, comma separated. The server never stores a usable key.
- **Caller (Nash's Mac, another project):** `HHA_DEV_TASKS_URL` (the Workspace address) and `HHA_DEV_TASKS_KEY`, in that project's `.env.local` (git-ignored). Optional `HHA_DEV_TASKS_SOURCE`.
- `node scripts/dev-task.mjs keygen` writes a new key straight into `.env.local` (refuses if that file isn't git-ignored), never prints it, and prints only the SHA-256 to add on the server. One key per caller; revoke one by removing its hash.
- `GET /api/internal/settings-check` reports whether `DEV_TASKS_API_KEY_HASHES` is set (yes/no only).

## Setup (once)

1. **Developer:** apply migration `supabase/migrations/0061_dev_tasks.sql` to production (additive: two new tables, nothing else touched) and deploy main.
2. **Nash's Mac, in the Workspace folder:** run `node scripts/dev-task.mjs keygen` and add `HHA_DEV_TASKS_URL=https://heavyhaulagent.com` to `.env.local` (the board runs there; heavyhaulgbt.com is the old server and answers 404). Send the printed SHA-256 to the developer; it's not a secret.
3. **Developer:** set `DEV_TASKS_API_KEY_HASHES=<that SHA-256>` in production settings and restart.
4. **Nash:** open `/admin/dev-tasks`, use the access card at the bottom to invite the developer's email. The developer signs in and opens the page.
5. **Check:** `node scripts/dev-task.mjs list` answers (empty board), and `GET /api/internal/settings-check` shows `DEV_TASKS_API_KEY_HASHES: true`.

**Another project:** copy `scripts/dev-task.mjs`, run `keygen` there, add `HHA_DEV_TASKS_URL` (and `HHA_DEV_TASKS_SOURCE`, e.g. `HHA Brain CTO`) to its `.env.local`, and have the developer append the new hash to `DEV_TASKS_API_KEY_HASHES`.

## Status

Live since Oct 22, 2026: migration 0061 applied, `DEV_TASKS_API_KEY_HASHES` set, checks passed (settings true, 401 without a key, page loads on heavyhaulagent.com). The open developer items were posted as T-1 to T-8.

## Design preview

`/dev-preview/dev-tasks` (development only, `?role=developer` for the developer's view) shows the board with sample tasks and saves nothing.
