wherdr 1.3.2 → 1.3.3

package/bin/lib/install-skill.sh

@@ -0,0 +1,100 @@
+#!/bin/sh
+# Automatic startup is silent and best effort; explicit operations report errors.
+# Usage: sh bin/lib/install-skill.sh [auto|refresh|install|uninstall] [package root]
+install_skill() (
+  set -eu
+  [ -n "${HOME:-}" ] && [ -d "$HOME" ] || exit 0
+  root=${2:-$(CDPATH= cd -- "$(dirname "$0")/../.." && pwd -P)}
+  mode=${1:-auto}
+  base=${WHERDR_DIR:-$HOME/wherdr}
+  case "$base" in /*) ;; *) base="$PWD/$base" ;; esac
+  dest="$base/skills/wherdr"
+  state="$HOME/.local/state/wherdr"
+  disabled="$state/skill-disabled"
+  claude=${CLAUDE_CONFIG_DIR:-$HOME/.claude}
+  case "$claude" in /*) ;; *) claude="$HOME/$claude" ;; esac
+  dirs() {
+    [ ! -d "$claude" ] || printf '%s\n' "$claude/skills"
+    if [ -d "$HOME/.agents" ] || [ -d "$HOME/.codex" ] || [ -d "$HOME/.omp" ]; then
+      printf '%s\n' "$HOME/.agents/skills"
+    fi
+  }
+  # Opt-out applies even to an explicit install; uninstall is always available.
+  if [ "$mode" != uninstall ]; then
+    [ "${WHERDR_SKILL:-}" != off ] || { echo 'wherdr skill: disabled by WHERDR_SKILL=off'; exit 0; }
+    [ "$mode" = install ] || [ ! -e "$disabled" ] || exit 0
+    [ -n "$(dirs)" ] || { echo 'wherdr skill: no installed agent found'; exit 0; }
+  fi
+  if [ "$mode" = uninstall ]; then
+    mkdir -p "$state"
+    [ ! -L "$disabled" ] || { echo 'wherdr skill: opt-out marker is a symlink' >&2; exit 1; }
+    [ -f "$disabled" ] || : > "$disabled"
+  fi
+  # Never follow a foreign symlink at the managed copy or its metadata.
+  [ ! -L "$dest" ] && [ ! -L "$dest/SKILL.md" ] && [ ! -L "$dest/.wherdr-managed" ] || {
+    echo 'wherdr skill: foreign symlink left alone' >&2; exit 0;
+  }
+  owned=false
+  [ ! -f "$dest/.wherdr-managed" ] || owned=true
+  if [ -e "$dest" ] && [ "$owned" = false ]; then
+    # Adopt an older plugin copy only when an agent links to this exact path.
+    legacy=$(dirs | while IFS= read -r d; do
+      if [ -L "$d/wherdr" ] && [ "$(readlink "$d/wherdr")" = "$dest" ]; then echo 1; fi
+    done)
+    [ -z "$legacy" ] || owned=true
+    [ "$owned" = true ] || { echo 'wherdr skill: existing foreign copy left alone'; exit 0; }
+  fi
+  case "$mode" in
+    auto|refresh|install)
+      [ -f "$root/skills/wherdr/SKILL.md" ] || { echo 'wherdr skill: bundled SKILL.md is missing' >&2; exit 1; }
+      mkdir -p "$dest"
+      if ! cmp -s "$root/skills/wherdr/SKILL.md" "$dest/SKILL.md"; then
+        tmp=$(mktemp "$dest/.SKILL.XXXXXX")
+        trap 'rm -f "$tmp"' EXIT HUP INT TERM
+        cp "$root/skills/wherdr/SKILL.md" "$tmp"
+        chmod 644 "$tmp"
+        mv -f "$tmp" "$dest/SKILL.md"
+      fi
+      [ -f "$dest/.wherdr-managed" ] || : > "$dest/.wherdr-managed"
+      dirs | while IFS= read -r d; do
+        link="$d/wherdr"
+        record="$d/.wherdr-managed-target"
+        # The record survives removal of an old WHERDR_DIR. A path's shape
+        # alone never proves ownership of a dangling link.
+        if [ -L "$link" ] && [ ! -e "$link" ] && [ -f "$record" ] && [ ! -L "$record" ] \
+          && [ "$(cat "$record")" = "$(readlink "$link")" ]; then
+          rm "$link"
+        fi
+        if [ ! -e "$link" ] && [ ! -L "$link" ]; then
+          mkdir -p "$d"
+          ln -s "$dest" "$link"
+        fi
+        if [ -L "$link" ] && [ "$(readlink "$link")" = "$dest" ] && [ ! -L "$record" ]; then
+          if [ ! -f "$record" ] || [ "$(cat "$record")" != "$dest" ]; then printf '%s\n' "$dest" > "$record"; fi
+        fi
+      done
+      [ "$mode" != install ] || rm -f "$disabled"
+      echo 'wherdr skill: installed or already up to date'
+      ;;
+    uninstall)
+      dirs | while IFS= read -r d; do
+        if [ -L "$d/wherdr" ] && [ "$(readlink "$d/wherdr")" = "$dest" ]; then
+          rm "$d/wherdr"
+          [ -L "$d/.wherdr-managed-target" ] || rm -f "$d/.wherdr-managed-target"
+        fi
+      done
+      if [ "$owned" = true ]; then
+        rm -f "$dest/SKILL.md" "$dest/.wherdr-managed"
+        rmdir "$dest" "$(dirname "$dest")" 2>/dev/null || true
+      fi
+      echo 'wherdr skill: uninstalled; automatic installation disabled'
+      ;;
+    *) echo 'usage: install-skill.sh [auto|refresh|install|uninstall] [package root]' >&2; exit 1 ;;
+  esac
+)
+if [ "${1:-auto}" = auto ]; then
+  ( install_skill "$@" ) >/dev/null 2>&1
+  exit 0
+else
+  install_skill "$@"
+fi

package/bin/lib/skill.mjs

@@ -0,0 +1,16 @@
+// The shell helper is also used without Node by the Docker / Herdr installer.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+export function refreshSkill(env = process.env) {
+  // One-shot handoff from the detached updater; never pass it to the server.
+  const refreshed = env.WHERDR_SKILL_REFRESHED === '1'
+  delete env.WHERDR_SKILL_REFRESHED
+  delete process.env.WHERDR_SKILL_REFRESHED
+  if (refreshed || env.WHERDR_SKILL === 'off') return
+  try {
+    spawnSync('sh', [fileURLToPath(new URL('./install-skill.sh', import.meta.url))], {
+      env, stdio: 'ignore', timeout: 5000,
+    })
+  } catch {} // Optional: a read-only home or missing shell must not prevent startup.
+}

package/bin/lib/updater.mjs

@@ -9,6 +9,7 @@
 //
 // The server copies this file out of the package before running it (npm and
 // Homebrew replace the package folder): it imports Node built-ins only.
+import { createHash } from 'node:crypto'
 import { spawn } from 'node:child_process'
 import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
@@ -38,10 +39,16 @@ function pluginDriver(plan, io) {
   const staged = `${plan.root}.new`
   const previous = `${plan.root}.prev`
   return {
-    // The npm package of the target version, unpacked next to the running copy.
+    // The checksummed GitHub package, unpacked next to the running copy.
     async install() {
       const tgz = path.join(plan.dir, 'update', `wherdr-${plan.to}.tgz`)
-      await io.download(`${plan.registry.replace(/\/$/, '')}/wherdr/-/wherdr-${plan.to}.tgz`, tgz)
+      if (!plan.releaseBase) throw new Error('Release source is missing from the update plan')
+      if (!/^\d+\.\d+\.\d+$/.test(plan.to)) throw new Error('Invalid release version')
+      const url = `${plan.releaseBase}/v${plan.to}/wherdr-${plan.to}.tgz`
+      await io.download(url, tgz)
+      await io.download(`${url}.sha256`, `${tgz}.sha256`)
+      await io.verify(tgz, `${tgz}.sha256`)
+      io.rm(`${tgz}.sha256`)
       io.rm(staged)
       io.mkdir(staged)
       await io.run('tar', ['-xzf', tgz, '-C', staged, '--strip-components=1'])
@@ -107,13 +114,28 @@ function brewDriver(plan, io) {
       if (failed !== keg && path.dirname(failed) === path.dirname(keg)) io.rm(failed)
       await io.run(brew, ['link', '--overwrite', 'wherdr'], env)
     },
-    start: () => io.run(brew, ['services', 'restart', 'wherdr'], env),
+    async start() {
+      // The service's CLI refreshes its own package. No opt lookup or duplicate
+      // helper invocation can prevent the service restart.
+      return io.run(brew, ['services', 'restart', 'wherdr'], env)
+    },
   }
 }
 
 // `wherdr start` of the package now in place: the pid file, or the login service.
-function cliStart(plan, io) {
-  return io.run(plan.runtime, [path.join(plan.root, 'bin', 'wherdr.mjs'), 'start'])
+export async function refreshInstalledSkill(plan, io, root = plan.root) {
+  try {
+    const helper = path.join(root, 'bin', 'lib', 'install-skill.sh')
+    if (io.exists(helper)) {
+      await io.run('sh', [helper, 'refresh', root], { WHERDR_DIR: plan.dir }, { timeout: 5000 })
+      return true
+    }
+  } catch {} // A skill refresh never prevents an update or rollback.
+}
+
+async function cliStart(plan, io) {
+  const refreshed = await refreshInstalledSkill(plan, io)
+  return io.run(plan.runtime, [path.join(plan.root, 'bin', 'wherdr.mjs'), 'start'], refreshed ? { WHERDR_SKILL_REFRESHED: '1' } : {})
 }
 
 export function driverFor(plan, io) {
@@ -123,6 +145,26 @@ export function driverFor(plan, io) {
   throw new Error(`no one-tap update for ${plan.kind}`)
 }
 
+// ------------------------------------------------------- shown on the phone
+// The reason of a failed start as one short sentence: the line that says why,
+// without the command that reported it nor any absolute path (the whole
+// reason is in update.log).
+export function shortReason(reason) {
+  const why = String(reason || '')
+    .replace(/^.*? exited with \d+: /, '')
+    .replace(/^wherdr: /, '')
+    .replace(/\s*\((?:[A-Za-z]:)?[\\/][^()]*\)/g, '')
+    .replace(/(?:[A-Za-z]:)?[\\/](?:[^\s\\/:]+[\\/])+([^\s\\/:]+)/g, '$1')
+    .replace(/[\s.]+$/, '')
+  return why.length > 200 ? `${why.slice(0, 199)}…` : why
+}
+
+function didNotStart(plan, reason) {
+  const why = shortReason(reason)
+  if (why.startsWith(`wherdr ${plan.to} `)) return why
+  return `wherdr ${plan.to} did not start${why ? `: ${why}` : ''}`
+}
+
 // ---------------------------------------------------------- state machine
 // installing → restarting → checking → done; a failed install leaves the old
 // server running (failed); a new version that does not start or answer goes
@@ -152,20 +194,20 @@ export async function runUpdate(plan, io) {
     reason = `wherdr ${plan.to} did not answer within ${Math.round(healthMs / 1000)} s`
   } catch (e) { reason = e.message }
   io.log(`${reason}: going back to ${plan.from}`)
-  io.state('rolling-back', reason)
+  io.state('rolling-back', `${didNotStart(plan, reason)}.`)
   try {
     await io.stopServer()
     await d.rollback()
     await d.start()
     if (await io.healthy(plan.from, healthMs)) {
       io.log(`wherdr ${plan.from} answers again: rolled back`)
-      io.state('rolled-back', `wherdr ${plan.to} did not start (${reason}). Rolled back to ${plan.from}.`)
+      io.state('rolled-back', `${didNotStart(plan, reason)}. Rolled back to ${plan.from}.`)
       return 'rolled-back'
     }
     throw new Error(`wherdr ${plan.from} did not answer either`)
   } catch (e) {
     io.log(`rollback failed: ${e.message}`)
-    io.state('failed', `wherdr ${plan.to} did not start (${reason}), and going back to ${plan.from} failed: ${e.message}. See ${path.join(plan.dir, 'update.log')}.`)
+    io.state('failed', `${didNotStart(plan, reason)}. Going back to ${plan.from} failed too: ${shortReason(e.message)}. See update.log in the wherdr folder on the server.`)
     return 'failed'
   }
 }
@@ -191,22 +233,28 @@ export function realIo(plan, now = Date.now) {
       writeFileSync(`${stateFile}.tmp`, `${JSON.stringify(job)}\n`)
       renameSync(`${stateFile}.tmp`, stateFile)
     },
-    run(cmd, args, env = {}) {
+    run(cmd, args, env = {}, { timeout } = {}) {
       log(`$ ${[cmd, ...args].join(' ')}`)
       const { promise, resolve, reject } = Promise.withResolvers()
-      const child = spawn(cmd, args, { cwd: plan.dir, env: { ...process.env, PATH, ...env }, stdio: ['ignore', 'pipe', 'pipe'] })
+      const child = spawn(cmd, args, { cwd: plan.dir, env: { ...process.env, PATH, ...env }, detached: Boolean(timeout), stdio: ['ignore', 'pipe', 'pipe'] })
+      const timer = timeout ? setTimeout(() => {
+        // The shell's own children must not keep copying or hold log pipes open.
+        try { process.kill(-child.pid, 'SIGKILL') } catch { child.kill('SIGKILL') }
+        reject(new Error(`${path.basename(cmd)} timed out after ${timeout} ms`))
+      }, timeout) : undefined
       let out = ''
       const keep = (b) => { out = (out + b).slice(-4000); try { appendFileSync(logFile, b) } catch {} }
       child.stdout.on('data', keep)
       child.stderr.on('data', keep)
-      child.on('error', e => reject(new Error(`${path.basename(cmd)}: ${e.message}`)))
+      child.on('error', e => { clearTimeout(timer); reject(new Error(`${path.basename(cmd)}: ${e.message}`)) })
       child.on('close', (code) => {
+        clearTimeout(timer)
         if (code === 0) return resolve(out)
         // The lines that say what went wrong (`wherdr: …`, `Error: …`), not a stack trace.
         const lines = out.split('\n').map(l => l.trim()).filter(Boolean)
         const why = lines.filter(l => /^(wherdr: |error\b|\w*Error: )/i.test(l)).slice(0, 2)
         const tail = (why.length ? why : lines.slice(-1)).join(' / ')
-        reject(new Error(`${path.basename(cmd)} ${args[0]} exited with ${code}${tail ? `: ${tail}` : ''}`))
+        reject(new Error(`${path.basename(cmd)} ${path.basename(args[0] ?? '')} exited with ${code}${tail ? `: ${tail}` : ''}`))
       })
       return promise
     },
@@ -217,6 +265,11 @@ export function realIo(plan, now = Date.now) {
       mkdirSync(path.dirname(file), { recursive: true })
       writeFileSync(file, Buffer.from(await res.arrayBuffer()))
     },
+    verify(file, checksum) {
+      const expected = readFileSync(checksum, 'utf8').trim().split(/\s+/)[0]
+      const actual = createHash('sha256').update(readFileSync(file)).digest('hex')
+      if (!/^[a-f0-9]{64}$/.test(expected || '') || actual !== expected) throw new Error('Release SHA-256 mismatch')
+    },
     // The server being replaced, then whatever `wherdr start` left (pid file).
     async stopServer() {
       const pids = [plan.serverPid]

package/bin/lib/verify-release.mjs

@@ -0,0 +1,20 @@
+// Check transfer integrity before extraction. Metadata/checksum and archive
+// share an origin: this does not authenticate a publisher or prevent replacement.
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+const [file, checksum, source, version] = process.argv.slice(2)
+let matches = false
+if (source === 'npm') {
+  const metadata = JSON.parse(readFileSync(checksum, 'utf8'))
+  const integrity = metadata.dist?.integrity
+  const actual = createHash('sha512').update(readFileSync(file)).digest('base64')
+  matches = metadata.name === 'wherdr' && metadata.version === version && integrity === `sha512-${actual}`
+} else {
+  const expected = readFileSync(checksum, 'utf8').trim().split(/\s+/)[0]
+  const actual = createHash('sha256').update(readFileSync(file)).digest('hex')
+  matches = /^[a-f0-9]{64}$/.test(expected || '') && actual === expected
+}
+if (!matches) {
+  console.error('Release checksum mismatch')
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wherdr",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "license": "MIT",
   "type": "module",
   "description": "Unofficial mobile web client (PWA) to drive the coding agents running in Herdr",
@@ -25,7 +25,8 @@
   "files": [
     ".output",
     "!.output/**/*.map",
-    "bin"
+    "bin",
+    "skills/wherdr"
   ],
   "engines": {
     "node": ">=22"

package/skills/wherdr/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: wherdr
+description: Conventions for coordinating a herdr-projects project whose TASKS.md is shown and driven by wherdr's Project panel and Board. Use when you coordinate a herdr-projects project (you edit TASKS.md, launch and merge threads), and whenever a message starts with "✓ Tested:", "✓ Testé :", "↳ Problem:", "↳ Problème :", "↳ Question:", "↳ Question :", "✗ Problem:", "✗ Problème :", "? Question:", "? Question :", "↳ Decision:", "↳ Décision :", "↳ Launch", "↳ Lancer", "↳ Move up", "↳ Monter", "↳ Move down", "↳ Descendre", "↳ Queue:", "↳ Mettre en file", "↳ Remove from queue", "↳ Retirer de la file", "↳ Back to backlog", "↳ Remettre au backlog", "↳ Mark blocked", "↳ Marquer bloqué", "↳ Move to To do", "↳ Passer en À faire", "↳ Mark done", "↳ Marquer fait", "↳ Unblock", "↳ Débloquer", "↳ Detail on", "↳ Précision sur", "✓ Reviewed:", "✓ Relu :", "↳ Feedback on", "↳ Retour sur", "↳ Info for", "↳ Info pour" or "↳ Quote".
+---
+
+# wherdr Project panel conventions
+
+wherdr shows the project's `TASKS.md` as a board on the user's phone and computer, with
+buttons on each task. Each button sends a short message to you, the coordinator. You own
+`TASKS.md`: the panel never edits it, it only reads it and asks you to. wherdr's **Board**
+(every project, thread and agent in Blocked / To do / Ongoing / Finished columns) sends the
+same messages when the user moves a task card to another column, plus the three moves of
+its own listed below.
+
+Follow the project's own instructions (`PROJECT.md`) first; this skill fills in what the
+panel expects. Write task lines and badges in the user's language.
+
+## TASKS.md format
+
+```markdown
+## To test
+- [ ] Swipe between panes on the phone [b:green(ready to test)] [b:gray(t-0042)](t-0042)
+
+## In progress
+- [ ] Fix the quota shown for Codex [b:red(bug)] (agent → t-0043)
+
+## In queue
+- [ ] Dark mode for the settings
+
+## Backlog
+- [ ] Export a conversation as Markdown
+```
+
+- Each `## Title` is a list; each `- [ ] text` (or `- text`) line under it is a task.
+  `- [x]` marks it done. `#` headings, `###` subheadings, indented lines (task details) and
+  fenced code blocks are ignored.
+- The last `(…)` of a line is the owner (`me`, `agent`, a name, `agent → t-NNNN`): read,
+  never shown.
+- Lists are shown in a fixed order (the order below), whatever their order in the file.
+  Unknown titles are shown after Backlog, without buttons. Only lists present in the file
+  are shown (plus In progress when threads are open, and Done). Add or remove a list only
+  when the user asks.
+
+## Lists the panel recognizes
+
+Titles are matched case- and accent-insensitively; any of these names works.
+
+| List | Accepted titles | Meaning | Buttons |
+|---|---|---|---|
+| To test | À tester, To test, Testing, To verify, À vérifier, Test | Deployed, ready for the user to check. | Confirm, Problem, Question |
+| To decide | À décider, To decide, Decision(s), Decide, Question(s) | Questions only the user can settle. | Question, Answer |
+| To review | À relire, Relire, Relecture, To review, Review(s), Code review, PR(s), Pull request(s), À valider, To validate | Pull requests for the user to review; put the PR link in a badge or in the text. | Reviewed, Comment |
+| In progress | En cours, In progress, Doing, Ongoing, WIP, Active | Only what a thread is really doing now. Open threads are shown here live. | Add info (on a thread) |
+| In queue | En file, En file d'attente, File d'attente, File, In queue, Queue, Queued, Up next | Decided work: launch the first task as soon as a thread slot frees, in list order. | Up, Down, Launch now, Clarify, Remove from queue |
+| Blocked | Bloqué(e)(s), Blocked, On hold, En attente, Waiting, Stuck | Waiting for something external. Optional reason: `— blocked by: <reason>` (`— bloqué par : …`). | Unblock, Clarify |
+| To do | À faire, Todo, To do, To dos, Todos, Next, Prochainement, Soon | Soon, in the user's priority order. Never launched without a request. | Up, Down, Queue, Launch now, Clarify, Back to backlog |
+| Backlog | Backlog, Later, Plus tard, Idées, Ideas, Someday, Un jour | Everything else. Never launched without a request. | Launch, Clarify |
+| Done | Fait(s), Done, Terminé(e)(s), Finished, Complete(d) | Filled by the panel with resolved threads; you may leave it out. | — |
+
+Rules:
+
+- **To test** holds only what is deployed and ready. Work being fixed goes back to In
+  progress; waiting work goes to In queue.
+- **No duplicates across lists.** When the user asks for a change to a feature that is in
+  To test, remove its To test line; one line comes back to To test once the change is
+  deployed (feature and change tested together).
+- **In queue** contract: whenever a thread slot frees (a thread is resolved), launch the
+  first In queue task and move it to In progress, as long as the project and the machine
+  have a free slot. The In queue header shows the thread slots in use
+  (`max_parallel_threads` of `PROJECT.md`).
+
+## Global thread limit per machine
+
+The user can set a maximum of threads per machine, across all projects, in wherdr
+(Settings › Plugins › herdr-projects). wherdr then writes `.wherdr-limits.json` in the
+herdr-projects folder (the parent of the project folder):
+
+```json
+{ "updated": "…", "this": "Server", "machines": { "Server": { "max": 2, "open": 2, "free": 0, "threads": ["shop/t-0012"] } } }
+```
+
+Before starting a thread, read `machines[this].free` (or `machines["<machine>"]` for a
+thread on another machine; `max: null` means no global limit). When `free` is `0`, wait,
+even if the project still has slots. File missing or out of date: count the open threads of
+every project with `herdr-projects overview`. Go beyond a limit only when the user says so.
+
+## `(agent → t-NNNN)`
+
+Write an In progress task handled by an open thread with the owner `(agent → t-NNNN)`
+(the arrow may also be `->`). The panel hides that line while the thread's own live card is
+shown, so the task does not appear twice. Write the thread ID exactly (`t-` and at least
+four digits).
+
+## Badges
+
+The only decoration the panel draws. Anywhere on a task line:
+
+- `[b:color(text)]`: a badge. `[b:(text)]` is neutral.
+- `[b:color(text)](target)`: a clickable badge. Target: an `https://` (or `http://`) URL, or
+  a thread ID (`t-0042`, opens that thread's tab). Anything else is not clickable.
+- Colors: `red`, `orange`, `amber`, `green`, `teal`, `blue`, `violet`, `pink`, `gray`
+  (`grey`), a hex color (`#e5484d`, `#fff`), or nothing (neutral).
+- Text: short, at most 24 characters. It is removed from the task text (the text the
+  panel sends back to you).
+
+Use them sparingly, when they help the user: two or three per line at most. Defaults
+unless the user prefers otherwise:
+
+- `[b:gray(t-0042)](t-0042)`: the thread a line comes from.
+- `[b:green(ready to test)]`: every To test line.
+- `[b:amber(fixing)]` (with the thread badge) on In progress work being fixed;
+  `[b:gray(queued)]` on waiting work.
+- `[b:red(bug)]`: a fix. `[b:blue(iPhone)]`: to test on the phone.
+- A PR: `[b:violet(PR #12)](https://github.com/<owner>/<repo>/pull/12)`.
+
+A bare `http://` or `https://` URL in the task text also becomes a plain clickable
+link (for example `Review https://github.com/example/project/pull/12`). Use this
+when the URL should remain visible; use a linked badge for a compact label.
+
+## Messages from the panel
+
+`<task>` is the task text as the panel shows it: the line without its checkbox, badges and
+owner. Find the line in `TASKS.md` by that text. The English or French form depends on the
+app language; treat them the same.
+
+Messages marked *sent* arrive as is. Messages marked *draft* are put in the user's input
+field, completed by the user, then sent. A draft starts with `↳` and ends with ` —`: it is a
+**reference**, the task on one line, the user's text on the lines below it, up to the next
+reference. (Earlier versions wrote a problem and a question on one line, `✗ Problem: <task> —
+<details>` and `? Question: <task> — <question>`: treat them the same.)
+
+The user quotes your own messages with the same kind of line, by the time shown on the message:
+`↳ Quote message 11:37 : <start of the message> —` (the whole message),
+`↳ Quote point 11:37 : <question, point or passage> —`,
+`↳ Quote decision 11:37 #3 : <question of row 3> —` (a row of a table of numbered decisions) and
+`↳ Quote decisions 11:37 #1-4 : <questions> —` (the whole table, usually followed by `OK to all`;
+`#1,4` when the rows are not consecutive).
+Read the lines under each one as the answer to that message and that row, even when you have
+written other messages since. Long excerpts are cut with `…`. A short code may follow the time
+or the row, as in `11:37 #3 ~k3f`: wherdr uses it to tell apart two of your messages written in
+the same minute, or two tables of one message. You have nothing to do with it.
+`↳ Info for` names a thread (`t-NNNN`) instead of a task; its text may span several lines.
+
+| Message (EN / FR) | From | What to do |
+|---|---|---|
+| `✓ Tested: <task>` / `✓ Testé : <task>` (sent) | To test › Confirm | The user validated it: remove the line from To test. |
+| `↳ Problem: <task> —` / `↳ Problème : <task> —`, then the details below (draft) | To test › Problem | A bug report: remove the line from To test, fix it (or launch a thread) and track it in In progress; it comes back to To test once the fix is deployed. |
+| `↳ Question: <task> —` / `↳ Question : <task> —`, then the question below (draft) | To test, To decide › Question | Answer in detail: what to test and how (where to tap, expected result), from the thread's report. Do not change `TASKS.md`. |
+| `↳ Decision: <task> —` / `↳ Décision : <task> —`, then the answer below (draft) | To decide › Answer | Apply the decision, remove the line from To decide, and record it where the project keeps durable decisions. |
+| `✓ Reviewed: <task>` / `✓ Relu : <task>` (sent) | To review › Reviewed | The user reviewed the PR: carry on (merge, deploy as the project says) and remove the line from To review. |
+| `↳ Feedback on <task> —` / `↳ Retour sur <task> —`, then the comments below (draft) | To review › Comment | Review feedback on that PR: apply it or send it to the thread. |
+| `↳ Move up: <task>` / `↳ Monter : <task>` (sent) | To do, In queue | Move the line one place up in its list. May arrive several times in a row. |
+| `↳ Move down: <task>` / `↳ Descendre : <task>` (sent) | To do, In queue | Move the line one place down in its list. |
+| `↳ Queue: <task>` / `↳ Mettre en file : <task>` (sent) | To do › Queue | Move the line from To do to the end of In queue; launch it if a slot is free and it is first. |
+| `↳ Launch now: <task>` / `↳ Lancer maintenant : <task>` (sent) | To do, In queue › Launch now | Launch a thread now if the project and the machine have a free slot (beyond the limits only if the user says so); otherwise put the line first in In queue. |
+| `↳ Remove from queue: <task>` / `↳ Retirer de la file : <task>` (sent) | In queue | Move the line back to the top of To do. |
+| `↳ Back to backlog: <task>` / `↳ Remettre au backlog : <task>` (sent) | To do | Move the line to Backlog. |
+| `↳ Launch: <task>` / `↳ Lancer : <task>` (sent) | Backlog › Launch | Start the task: a thread if a slot is free, otherwise first in In queue. |
+| `↳ Unblock: <task>` / `↳ Débloquer : <task>` (sent) | Blocked › Unblock | Relaunch the task, or ask the user exactly what is still missing. |
+| `↳ Mark blocked: <task>` / `↳ Marquer bloqué : <task>` (sent) | Board: a task moved to Blocked | Move the line to Blocked (add that list if it is missing); ask the user what it waits for if you do not know. |
+| `↳ Move to To do: <task>` / `↳ Passer en À faire : <task>` (sent) | Board: a task moved to To do (from Blocked, In progress or Done) | Move the line to the end of To do (add that list if it is missing), unchecked. Do not launch it. |
+| `↳ Mark done: <task>` / `↳ Marquer fait : <task>` (sent) | Board: a task moved to Finished | The task is finished or no longer needed: move the line, checked, to Done when the project has that list, otherwise remove it. |
+| `↳ Detail on <task> —` / `↳ Précision sur <task> —`, then the details below (draft) | Clarify (Backlog, To do, In queue, Blocked) | Add the details to the task (indented lines under it, or the thread's brief) and confirm. Do not launch it. |
+| `↳ Info for t-NNNN: <text>` / `↳ Info pour t-NNNN : <text>` (sent) | In progress › Add info (a thread's card, or the task of a thread) | Pass `<text>` on to that thread as is, every line of it, without rewording (`herdr-projects thread prompt <project> t-NNNN --text-file <file>`, `-` reads standard input), then confirm to the user in one line. Do not change `TASKS.md`. If the thread is resolved or unknown, say so instead. |
+
+Never launch a task from To do or Backlog without one of these requests.
+
+## After a deployment
+
+For each change the user can now see, add one To test line written from the user's point
+of view: what to open and what should happen, not the technical cause ("Swipe between
+panes on the phone", not "Fix pointer events in PaneSwiper"). Add
+`[b:green(ready to test)]` and the thread badge. Remove the matching In progress line.
+
+Name threads and tasks the same way: what the user sees.
+
+## Questions left unanswered
+
+A question you asked the user that is still open goes to To decide, so the user can answer
+it from the panel. Remove the line as soon as it is answered.