ai4kanban 0.4.1 → 0.5.0

package/bin/ai4kanban.mjs

@@ -167,8 +167,8 @@ function repairBoard(skillDir, root) {
   moveLegacyMemory(board)
   sayDid()
   // `init` on an existing board is the repair step: it adds what an older version never
-  // wrote (config.md, modules.md, the memory paths, the goal's `reviewed:` field) and never
-  // touches a file that's already filled in.
+  // wrote (config.md, modules.md, releases.md, the memory paths, the goal's `reviewed:`
+  // field) and never touches a file that's already filled in.
   runKanban(skillDir, root, ['init'])
   dropModuleGoals(board)
   checkConfig(board)
@@ -259,12 +259,20 @@ function cmdInstall(root, tracks) {
   runKanban(placed[0].dest, root, ['init', ...tracks])
   sayNotes()
   say('')
-  say('Next, and only an agent can do these:')
-  say('  1. fill in docs/kanban/config.md from what the repo tells you')
-  say('  2. write docs/kanban/modules.md (the skill\'s references/module-map.md says how)')
-  say('  3. propose the first 3 tasks')
+  // One instruction, not a list of steps. The steps are on the board now, in
+  // docs/kanban/setup-checklist.md — and two lists would drift. Setup picks up at the
+  // first unticked box, so this same line restarts it wherever it stops.
+  say('Next, paste this into your coding agent to finish setup:')
+  say('')
+  say(`    ${SETUP_INSTRUCTION}`)
 }
 
+// The line the user copies into their coding harness to run setup's agent steps. One
+// wording for every harness, and the same one the local board UI shows on its setup bar
+// (kanban-ui/lib/agent.ts) — the two are separate packages, so it is repeated here rather
+// than shared. Keep them in step.
+const SETUP_INSTRUCTION = '/kanban. Set up this board — follow docs/kanban/setup-checklist.md.'
+
 function cmdUpdate(root) {
   say(`ai4kanban ${VERSION} — updating ${root}`)
   const placed = placeSkill(root, 'update')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai4kanban",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Set up and update AI4Kanban in one command — copies the skill into your project and scaffolds the Markdown board under docs/kanban/.",
   "keywords": [
     "kanban",

package/skill/SKILL.md

@@ -1,17 +1,18 @@
 ---
 name: kanban
 description: Use to propose new tasks, add a task, mark one done, or push a task one step forward. Manages the file-based task board in docs/kanban/ — blockers, roadmap tracks, archive, and global task ids. Triggers on "propose new tasks", "what's on the backlog", "add a task", "this is done", "refine", "resolve", "dive deeper".
-argument-hint: "[propose | add <task> | refine <id> | resolve <id> | done <id> | reject <id>]"
+argument-hint: "[propose [count] | add <task> | refine <id> | resolve <id> | done <id> | reject <id>]"
 ---
 
 The task board lives in `docs/kanban/`. Read it before suggesting or adding work.
 
 ## Configuration
 
-**Read `docs/kanban/config.md` first** — it carries your project's settings: name, tracks,
-planning sources, reference docs, optional preset. `kanban init` seeds it; install fills it
-in; until then its defaults apply. It lives with your board, so an update leaves it
-untouched — the skill folder (`SKILL.md`, `kanban.mjs`, `references/`) is upstream-owned and
+**Read `docs/kanban/config.md` before proposing, adding, or refining** — it carries your
+project's settings: name, tracks, planning sources, reference docs, optional preset.
+`kanban init` seeds it; install fills it in; until then its defaults apply. It lives with
+your board, so an update leaves it
+untouched — the skill folder (`SKILL.md`, `kanban.mjs` with its `lib/` and `commands/`, `references/`) is upstream-owned and
 overwritten wholesale (see "Updating the skill"). "Your tracks / planning sources / reference
 docs" below mean this file.
 
@@ -59,7 +60,7 @@ docs/kanban/
 │   ├── README.md   the index — read it first
 │   ├── blockers/   hard blockers; they gate the next milestone — clear them first
 │   ├── <track>/    one folder per track (see Configuration), one card per file
-│   └── recurring/  jobs on a cadence (see "Recurring task") — never archived
+│   └── recurring/  jobs we repeat (see "Recurring task") — never archived
 ├── memory/         all memory — see "The memory set"
 │   ├── readme.md, decisions.md, rejected.md, redesign.md
 │   │               the four-file set for the project as a whole
@@ -69,6 +70,10 @@ docs/kanban/
 ├── modules.md      one line per module — install writes it, propose reads it (see "The
 │                   module map")
 ├── config.md       your project's settings (see Configuration) — seeded by init, yours to fill
+├── releases.md     the open releases, in the order they ship — one line each (see "Releases")
+├── setup-checklist.md
+│                   setup's own steps, while setup is unfinished (see "Setup") — the
+│                   last tick deletes it; no file means the board is set up
 ├── next-id         the next free task id — NEVER edit by hand; only the script writes it
 └── metrics.csv     one row per day: completed, created, rejected — script-kept; never touch
 ```
@@ -80,44 +85,64 @@ create, update, migrate, archive, or reject a task. It allocates ids, writes a c
 **frontmatter**, moves/removes task files, keeps the README index, and records the daily
 metric.
 
-Point `KB="node .claude/skills/kanban/kanban.mjs"`. Set it once and run every command from
-the repo root as `${KB} <command>`:
+Point `KB="node <this skill's folder>/kanban.mjs"` — the folder this SKILL.md sits in, which
+differs per agent (`.claude/skills/kanban/`, `.agents/skills/kanban/`, a plugin path). Set it
+once and run every command from the repo root as `${KB} <command>`:
 
 ```
 ${KB} init [track...]               # scaffold docs/kanban/ (tracks default to feature bug research)
-                                    # re-run to repair an older board: adds missing config.md, modules.md, memory paths
+                                    # re-run to repair an older board: adds missing config.md, modules.md, releases.md, .gitignore, memory paths
 ${KB} create [--count N]            # allocate N ids (default 1), prints them
 ${KB} create --title ".." --track <track> [--priority high|med|low] [--roi high|med|low] \
-             [--blocked-by 1,2] [--related 3] [--modules skill,site] [--question ".."] [--slug ..]
+             [--release v1] [--blocked-by 1,2] [--related 3] [--modules skill,site] [--question ".."] [--slug ..]
                                     # scaffold ONE card: frontmatter + body template + README entry; then fill only the body
-${KB} update <id> [--priority ..] [--roi ..] [--track ..] [--slug ..] \
-             [--blocked-by ..] [--related ..] [--modules ..] [--question ..] \
-             [--drop-question 1,3] [--clear-questions]
-                                    # rewrite a card's frontmatter; --track moves it, --slug renames
+${KB} update <id> [--priority ..] [--roi ..] [--status ..] [--release ..] [--track ..] [--slug ..] \
+             [--blocked-by ..] [--related ..] [--modules ..]
+                                    # rewrite a card's frontmatter fields; --track moves it, --slug renames
+${KB} update-questions <id> [--append ".."] [--update <n> ".."] [--drop 1,3] [--clear]
+                                    # patch open questions one op at a time — nothing rewrites the list whole;
+                                    # options for a pick-one question: references/resolve.md
+${KB} list [--module <m>]           # the open cards at a glance: id, title, meta, summary, file path;
+                                    # --module narrows it to the cards tagged with one module
 ${KB} archive <id>                  # finish task <id>
-${KB} reject  <id>                  # reject task <id>
-${KB} run     <id>                  # record one run of recurring task <id> (card kept)
 ${KB} peek                          # current next-id, no bump
 ${KB} help                          # full usage
 ```
 
-**Never hand-write a card's frontmatter.** Use `create`/`update` for the meta
-(title, track, priority, roi, blocked_by, related, modules, questions); use Write/Edit only
-for the card **body**.
+**Never hand-write a card's frontmatter.** Use `create`/`update`/`update-questions` for the
+meta (title, track, priority, roi, status, release, blocked_by, related, modules,
+questions); use Write/Edit only for the card **body**.
 
 Tag a card with `--modules` (see `docs/kanban/modules.md`);
 optional — a task can touch two modules or none. Add a new line to modules.md according to `module-map.md`
 if you find no match.
 
+## Releases
+
+A release is a version this project is planning; the open ones live in
+`docs/kanban/releases.md`, one line each, in ship order. A card names the release it ships
+in via `--release`; a card that names none is simply in no release. Releases are optional —
+a board that never plans a version works exactly as it does without one. Full guide in
+`references/releases.md` — read it before running any `release` command or setting
+`--release`.
+
 ## Task id
 
 Every task's id is the number at the front of its filename (`04-plan-cap-enforcement.md` →
 id 4). Ids are global and never reused; only the script's `create` allocates them.
 
+## Setup
+
+`docs/kanban/setup-checklist.md` being there says setup is unfinished — the last tick
+deletes it. While it's there, no flow creates cards; setup's own last step is the only
+exception. Full guide in `references/setup.md`.
+
 ## Propose new tasks
 
-When the user asks to propose work, pick **one module** and propose **3 new tasks
-inside it** — work nobody has planned yet. Full guide in `references/propose.md`.
+When the user asks to propose work, pick **one module** and propose new tasks inside it —
+work nobody has planned yet, each one short-term and its own single card (never a group
+task). **3** of them unless the user names a count; **10** is the cap. Full guide in
+`references/propose.md`.
 
 ## Add a task
 
@@ -172,11 +197,7 @@ Then run `${KB} archive <id>` to record the completion.
 
 ## Reject an idea
 
-Rejecting is rare. When you (or the user) turn down an idea, add a short line to
-`rejected.md` (see "The memory set") — under the topic that fits; start a new topic heading if none
-fits. Format: `- **<idea name>** — <why we said no, one line>.`
-
-Then run `${KB} reject <id>` to remove the card.
+Rejecting is rare, and it deletes the card. Full guide in `references/reject.md`.
 
 ## Record a redesign
 
@@ -192,8 +213,9 @@ A track is the bucket a task lives in — one folder per track under `todo/`. Yo
 
 ## Recurring task
 
-A recurring task is a job we repeat on a cadence (e.g. a weekly report), not a
-one-shot. Full guide in `references/recurring-task.md`.
+A recurring task is a job we repeat (e.g. a weekly report), not a one-shot. Adding one
+and running one are both in `references/recurring-task.md`; the job itself is the card's
+own `## Process`.
 
 ## Run the board locally
 
@@ -231,14 +253,18 @@ soon as the module is known — `init` does it for every module already on the m
 update flow does it for the rest, and any flow about to write a note runs it first.
 
 **`goal.md` sits outside the set, at the board root only** — the long-term goal, horizon,
-and roadmap in the user's words; the agent never writes the goal, except a frontmatter line
-`reviewed: strong | good | weak`.
-This field says whether the goal is clear enough to plan from — `weak` only when apparent (missing, still the template, too vague to judge a proposal against).
+and roadmap in the user's words. It starts empty; the agent never writes the goal, except
+the frontmatter line `reviewed: strong | good | pending | weak` — how clear the goal is to
+plan from. `weak` only when apparent (missing, empty, too vague to judge a proposal
+against). `pending` means written but not judged yet: the script and the local UI set it
+when a goal is saved, and you replace it the next time you read the goal. Judge it at the
+`goal` setup step and on every propose run — never stop to ask the user about it.
 
 ## Auto-pruning
 
 To compress the memory set — the project-wide copy and each module copy — down to
-planning-useful summaries, follow `references/prune-memory.md`.
+planning-useful summaries, follow `references/prune-memory.md`. The board ships with a
+recurring card that does this — never create one.
 
 ## Document a change
 

package/skill/commands/card.mjs

@@ -0,0 +1,335 @@
+// ---- create / update / update-questions / tag ------------------------------
+//
+// The commands that write a live card's frontmatter. The script owns the meta;
+// Write/Edit are for the body only.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { die, warn, rel, readNextId, writeNextId, TODO } from '../lib/paths.mjs'
+import { bumpMetric } from '../lib/metrics.mjs'
+import { parseFlags, slugify, validLevel, validStatus, validTrack, validModules, parseModuleList, parseIdList, normalizeRelease } from '../lib/validate.mjs'
+import { QUESTION_TAGS, parseQuestion, formatQuestion, warnBadQuestionTags, collectQuestions, parseQuestionOps, parseQuestionPositions } from '../lib/questions.mjs'
+import { serializeFrontmatter, parseFrontmatter } from '../lib/frontmatter.mjs'
+import { CADENCE_FORMS, formatCadence, parseCadence } from '../lib/cadence.mjs'
+import { locate, enclosingGroupRoot, isRecurringCard } from '../lib/cards.mjs'
+import { RECURRING } from '../lib/recurring.mjs'
+import { validRelease, setSubtreeRelease } from '../lib/releases.mjs'
+import { readmeHeadingFor, addReadmeRef, stripReadmeRefs, repointReadmeLink } from '../lib/readme.mjs'
+import { reconcileBoard } from '../lib/reconcile.mjs'
+
+// A todo item in any accepted form: `- [ ]`, `- []`, `- [x]`, `* [X]`, … — the shape
+// counts, not the literal string.
+const TODO_ITEM = /^[ \t]*[-*+][ \t]*\[[ xX]?\]/m
+
+function defaultBody() {
+  return [
+    '<one short line: what to do and why it matters.>',
+    '',
+    '## Scope',
+    '- <the concrete steps>',
+    '',
+    '## Todo',
+    '- [ ] every task must have todos — replace this line with the real steps.',
+    '',
+  ].join('\n')
+}
+
+// How often a recurring card repeats, as `--cadence` gives it: one of the forms in
+// lib/cadence.mjs, written back in that module's own spelling so every card reads the
+// same. An empty value is "no cadence" — the card goes back to running only when a
+// human clicks Run. Anything the grammar doesn't cover is refused with the accepted
+// forms, never written half-parsed.
+function cadenceFlag(raw) {
+  if (raw === true) die(`--cadence needs a value: ${CADENCE_FORMS}. Use --cadence "" to clear it.`)
+  const text = String(raw).trim()
+  if (!text) return ''
+  const parsed = parseCadence(text)
+  if (!parsed) die(`--cadence "${text}" isn't a cadence. Accepted: ${CADENCE_FORMS}`)
+  return formatCadence(parsed)
+}
+
+const CREATE_FLAGS = ['title', 'track', 'priority', 'roi', 'release', 'blocked-by', 'related', 'modules', 'question', 'option', 'mode', 'recommended-option', 'slug', 'count', 'no-body', 'cadence']
+
+// Two modes:
+//   bare      `create [--count N]`  → allocate ids and print them (group-task setup).
+//   card mode `create --title ... --track ...` → allocate ONE id, write the card's
+//             frontmatter + a body template, and index it. The script owns the meta;
+//             fill the body with your editor and leave the frontmatter alone.
+export function cmdCreate(args) {
+  const { flags, positional, order } = parseFlags(args, CREATE_FLAGS)
+  if (positional.length) die(`create takes options, not positional args (got "${positional.join(' ')}")`)
+
+  if (flags.title === undefined) {
+    for (const bad of ['track', 'priority', 'roi', 'release', 'blocked-by', 'related', 'modules', 'question', 'option', 'mode', 'recommended-option', 'slug', 'no-body', 'cadence']) {
+      if (flags[bad] !== undefined) die(`--${bad} needs --title (that's card mode). Without --title, create only allocates ids.`)
+    }
+    const count = flags.count !== undefined ? Number(flags.count) : 1
+    if (!Number.isInteger(count) || count < 1) die('--count must be a positive integer')
+    const start = readNextId()
+    const ids = Array.from({ length: count }, (_, k) => start + k)
+    writeNextId(start + count)
+    bumpMetric('created', count)
+    console.log(ids.join('\n'))
+    reconcileBoard()
+    return
+  }
+
+  // --- card mode ---
+  if (flags.count !== undefined) die("--count can't be combined with --title (card mode makes exactly one card)")
+  const title = String(flags.title).trim()
+  if (!title) die('--title must not be empty')
+  if (flags.track === undefined) die('--track is required in card mode (e.g. --track feature)')
+  const track = String(flags.track).trim()
+  validTrack(track)
+  const priority = flags.priority !== undefined ? String(flags.priority) : 'med'
+  validLevel(priority, 'priority')
+  const roi = flags.roi !== undefined ? String(flags.roi) : 'med'
+  validLevel(roi, 'roi')
+  // No --release means no release: the card is wanted, not promised to a version. Any
+  // other value has to name a release on the list — a typo must not invent a version.
+  const release = validRelease(normalizeRelease(flags.release))
+  const start = readNextId()
+  const blocked_by = flags['blocked-by'] !== undefined ? parseIdList(flags['blocked-by'], 'blocked-by', start) : []
+  const related = flags.related !== undefined ? parseIdList(flags.related, 'related', start) : []
+  const modules = flags.modules !== undefined ? validModules(parseModuleList(flags.modules)) : []
+  // Only a card that repeats can have a cadence — a one-shot task is built once.
+  let cadence = ''
+  if (flags.cadence !== undefined) {
+    if (track !== RECURRING) die(`--cadence is for recurring cards only (--track ${RECURRING}); a one-shot task is built once, not repeated.`)
+    cadence = cadenceFlag(flags.cadence)
+  }
+  const questions = collectQuestions(order)
+  warnBadQuestionTags(questions)
+  const slug = slugify(flags.slug !== undefined ? flags.slug : title)
+  const fileRel = path.join(track, `${start}-${slug}.md`)
+  const file = path.join(TODO, fileRel)
+  if (fs.existsSync(file)) die(`${rel(file)} already exists — pick a different --slug`)
+
+  // validation passed → allocate + write
+  writeNextId(start + 1)
+  bumpMetric('created')
+  const meta = { title, track, priority, roi, status: 'todo', release, blocked_by, related, modules, cadence, questions }
+  const body = flags['no-body'] ? '' : defaultBody()
+  fs.writeFileSync(file, serializeFrontmatter(meta) + '\n\n' + body)
+  const indexed = addReadmeRef(track, start, title, fileRel)
+  console.log(start)
+  console.log(`  wrote ${rel(file)} — frontmatter is set; fill the body with your editor, leave the frontmatter to the script`)
+  if (!TODO_ITEM.test(body)) warn(`#${start} has no todos — every task needs a \`- [ ]\` list under ## Todo`)
+  if (indexed) console.log(`  indexed under "## ${readmeHeadingFor(track)}"`)
+  reconcileBoard()
+}
+
+const UPDATE_FLAGS = ['title', 'track', 'priority', 'roi', 'status', 'release', 'blocked-by', 'related', 'modules', 'slug', 'cadence']
+
+// Rewrite a card's frontmatter fields. Also the sanctioned way to move a card between
+// tracks (--track moves the file + fixes the index) or rename it (--slug). Body is
+// untouched, and so is the question list — that's cmdUpdateQuestions' job.
+export function cmdUpdate(args) {
+  const { flags, positional } = parseFlags(args, UPDATE_FLAGS)
+  const id = Number(positional[0])
+  if (!Number.isInteger(id)) die('need a numeric task id: update <id> [--field value ...]')
+  const found = locate(id)
+  if (!found) die(`no task with id ${id} under ${rel(TODO)}`)
+  const file = found.kind === 'group' ? path.join(found.target, 'root.md') : found.target
+  const { meta, body } = parseFrontmatter(fs.readFileSync(file, 'utf8'))
+  if (!meta) die(`${rel(file)} has no frontmatter — run \`migrate\` first`)
+
+  const changes = []
+  if (flags.title !== undefined) {
+    const t = String(flags.title).trim()
+    if (!t) die('--title must not be empty')
+    meta.title = t
+    changes.push('title')
+  }
+  if (flags.priority !== undefined) {
+    validLevel(String(flags.priority), 'priority')
+    meta.priority = String(flags.priority)
+    changes.push('priority')
+  }
+  if (flags.roi !== undefined) {
+    validLevel(String(flags.roi), 'roi')
+    meta.roi = String(flags.roi)
+    changes.push('roi')
+  }
+  if (flags.status !== undefined) {
+    validStatus(String(flags.status))
+    meta.status = String(flags.status)
+    changes.push('status')
+  }
+  // `--release ""` — an empty value — takes the card back out of a version.
+  if (flags.release !== undefined) {
+    meta.release = validRelease(normalizeRelease(flags.release))
+    changes.push(`release→${meta.release || '(none)'}`)
+  }
+  const ceiling = readNextId()
+  if (flags['blocked-by'] !== undefined) {
+    meta.blocked_by = parseIdList(flags['blocked-by'], 'blocked-by', ceiling)
+    changes.push('blocked_by')
+  }
+  if (flags.related !== undefined) {
+    meta.related = parseIdList(flags.related, 'related', ceiling)
+    changes.push('related')
+  }
+  if (flags.modules !== undefined) {
+    meta.modules = validModules(parseModuleList(flags.modules))
+    changes.push('modules')
+  }
+  // How often the card repeats, and so whether the local UI runs it in the
+  // background at all. `--cadence ""` clears it and the card goes back to
+  // running only when someone clicks Run.
+  if (flags.cadence !== undefined) {
+    if (!isRecurringCard(found)) die(`#${id} is not recurring (${found.rel} is not under ${RECURRING}/) — only a card that repeats can have a cadence.`)
+    meta.cadence = cadenceFlag(flags.cadence)
+    changes.push(`cadence→${meta.cadence || '(none)'}`)
+  }
+  // A `ready` card has no open questions by definition (see STATUSES). Open questions
+  // mean the plan is not settled, so a `--status ready` with them pending lands as
+  // `todo`. This holds the invariant no matter who set the status.
+  if (meta.questions.length > 0 && meta.status === 'ready') {
+    meta.status = 'todo'
+    changes.push('status→todo (open questions)')
+  }
+
+  // A card's track is the folder its file sits in — right for a standalone card
+  // (skill/06 → skill), a group subtask (<group>/skill/21 → skill), a blocker,
+  // and a recurring card alike. A group root's own folder is the group, not a
+  // track, so its frontmatter value stands.
+  const curRel = path.relative(TODO, file)
+  const curTrack = found.kind === 'group' ? meta.track : path.basename(path.dirname(file))
+  const isSubtask = found.kind === 'file' && enclosingGroupRoot(file) !== null
+  let newTrack = curTrack
+  if (flags.track !== undefined) {
+    if (found.kind === 'group') die('moving a group task between tracks by script is not supported — move the folder by hand')
+    if (isSubtask) die('moving a group subtask between tracks by script is not supported — move the file by hand')
+    newTrack = String(flags.track).trim()
+    validTrack(newTrack)
+  }
+  let base = path.basename(file)
+  if (flags.slug !== undefined) {
+    if (found.kind === 'group') die('renaming a group root by script is not supported')
+    base = `${id}-${slugify(flags.slug)}.md`
+  }
+  meta.track = newTrack
+  // A card moved out of recurring/ leaves its cadence behind: nothing runs a
+  // one-shot task on a schedule, so the line would only mislead whoever reads it.
+  if (flags.track !== undefined && newTrack !== RECURRING && meta.cadence) {
+    meta.cadence = ''
+    changes.push('cadence cleared (no longer recurring)')
+  }
+  // Only a standalone card can change folders (--track). A subtask and a group
+  // root stay in their own folder; --slug at most renames the file there.
+  const standalone = found.kind === 'file' && !isSubtask
+  const destRel = standalone ? path.join(newTrack, base) : path.join(path.dirname(curRel), base)
+  const dest = path.join(TODO, destRel)
+  const moving = dest !== file
+  if (moving && fs.existsSync(dest)) die(`${rel(dest)} already exists`)
+
+  fs.writeFileSync(file, serializeFrontmatter(meta) + '\n' + body)
+  // Putting a group root in a release puts the whole group in it — every subtask, and
+  // the subtasks of a nested group too. Taking the root out takes them all out. Done
+  // after the root is written so the group ends up on one release either way.
+  if (flags.release !== undefined && found.kind === 'group') {
+    const ids = setSubtreeRelease(found.target, meta.release)
+    if (ids.length) changes.push(`release on ${ids.length} subtask${ids.length === 1 ? '' : 's'} (${ids.map((n) => `#${n}`).join(', ')})`)
+  }
+  if (moving) fs.renameSync(file, dest)
+  if (isSubtask) {
+    // A subtask never owns a top-level README entry — fix its nested bullet in place.
+    if (moving || changes.includes('title')) repointReadmeLink(id, curRel, destRel, meta.title)
+    if (moving) changes.push(`renamed → ${destRel.split(path.sep).join('/')}`)
+  } else if (moving) {
+    stripReadmeRefs({ kind: 'file', rel: curRel })
+    addReadmeRef(newTrack, id, meta.title, destRel)
+    changes.push(`moved → ${destRel.split(path.sep).join('/')}`)
+  } else if (changes.includes('title')) {
+    stripReadmeRefs({ kind: 'file', rel: curRel })
+    addReadmeRef(curTrack, id, meta.title, curRel)
+  }
+  console.log(`updated #${id}: ${changes.join(', ') || '(nothing changed)'}`)
+}
+
+// Patch a card's open-question list. Every op edits in place — append one, rewrite
+// one by position, drop answered ones, clear the list — so handing a single question
+// to the user never means re-passing its siblings (wholesale rewrites silently lost
+// options that weren't re-typed). Ops apply in the order they were typed, and a
+// position is read against the list as it stands when its op runs.
+export function cmdUpdateQuestions(args) {
+  const [idRaw, ...rest] = args
+  const id = Number(idRaw)
+  if (!Number.isInteger(id)) die('need a numeric task id: update-questions <id> [ops]')
+  const ops = parseQuestionOps(rest)
+  const found = locate(id)
+  if (!found) die(`no task with id ${id} under ${rel(TODO)}`)
+  const file = found.kind === 'group' ? path.join(found.target, 'root.md') : found.target
+  const { meta, body } = parseFrontmatter(fs.readFileSync(file, 'utf8'))
+  if (!meta) die(`${rel(file)} has no frontmatter — run \`migrate\` first`)
+
+  const changes = []
+  for (const op of ops) {
+    if (op.kind === 'clear') {
+      meta.questions = []
+      changes.push('cleared')
+    } else if (op.kind === 'drop') {
+      const ns = parseQuestionPositions(op.ns, meta.questions.length, 'drop')
+      meta.questions = meta.questions.filter((_, i) => !ns.includes(i + 1))
+      changes.push(`dropped ${ns.join(',')}`)
+    } else if (op.kind === 'append') {
+      meta.questions.push(op.question)
+      changes.push('appended')
+    } else {
+      const [n] = parseQuestionPositions(String(op.n), meta.questions.length, 'update')
+      meta.questions[n - 1] = op.question
+      changes.push(`rewrote ${n}`)
+    }
+  }
+  warnBadQuestionTags(meta.questions)
+  // The same invariant cmdUpdate holds: a `ready` card has no open questions.
+  if (meta.questions.length > 0 && meta.status === 'ready') {
+    meta.status = 'todo'
+    changes.push('status→todo (open questions)')
+  }
+  fs.writeFileSync(file, serializeFrontmatter(meta) + '\n' + body)
+  console.log(`updated #${id} questions: ${changes.join(', ')} (${meta.questions.length} open)`)
+}
+
+// Set (or clear) the tag on open questions, so the auto-refine loop can hand a
+// batch of questions to the human in one call without rewriting the whole list.
+// `nRaw` is one 1-based position or a comma-separated list (`1,2,3`); `tag` is
+// user | none (none strips any tag). Reads and rewrites the frontmatter
+// through the same path as `update`, so byte layout and group-root handling stay
+// identical.
+export function cmdTag(args) {
+  const [idRaw, nRaw, tagRaw] = args
+  const id = Number(idRaw)
+  if (!Number.isInteger(id)) die('need a numeric task id: tag <id> <n[,n...]> <user|none>')
+  const ns = String(nRaw || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map(Number)
+  if (ns.length === 0 || ns.some((n) => !Number.isInteger(n) || n < 1)) {
+    die('need one or more 1-based question numbers: tag <id> <n[,n...]> <user|none>')
+  }
+  const tag = String(tagRaw || '').toLowerCase()
+  if (tag !== 'none' && !QUESTION_TAGS.includes(tag)) {
+    die(`tag must be one of ${QUESTION_TAGS.join(' | ')} | none (got "${tagRaw}")`)
+  }
+  const found = locate(id)
+  if (!found) die(`no task with id ${id} under ${rel(TODO)}`)
+  const file = found.kind === 'group' ? path.join(found.target, 'root.md') : found.target
+  const { meta, body } = parseFrontmatter(fs.readFileSync(file, 'utf8'))
+  if (!meta) die(`${rel(file)} has no frontmatter — run \`migrate\` first`)
+  const over = ns.find((n) => n > meta.questions.length)
+  if (over !== undefined) {
+    die(`#${id} has ${meta.questions.length} open question(s) — there's no question ${over} to tag.`)
+  }
+  for (const n of ns) {
+    const q = meta.questions[n - 1]
+    const { text } = parseQuestion(q.text)
+    q.text = formatQuestion(tag === 'none' ? null : tag, text)
+  }
+  fs.writeFileSync(file, serializeFrontmatter(meta) + '\n' + body)
+  const label = tag === 'none' ? '(untagged)' : `[${tag}]`
+  console.log(`tagged #${id} question${ns.length > 1 ? 's' : ''} ${ns.join(', ')} as ${label}`)
+}