ravensight-playtest 0.6.0 → 0.7.0

package/README.md

@@ -623,6 +623,14 @@ ravensight-playtest fix fnd_7g3k --no-verify
 The target is either `<jobId>/<label>`, where the label is the one the report
 gives the finding, or a bare finding id.
 
+It can also be a punch list or blue tape item, `li_...`, when the item came
+from a finding or a fresh-eyes finding.
+The fix then runs exactly as it does for that finding, at the same price. After
+the job registers, the job id is recorded on the item. The item stays open
+until you close it. An item that did not come from a finding is refused before
+anything is charged; `feature` is the tool for that item. See
+[Punch list and blue tape](#punch-list-and-blue-tape-labs-beta).
+
 | Flag | Effect |
 |---|---|
 | `--game <gameId>` | The game, when this repo is not linked. |
@@ -1209,6 +1217,68 @@ During a feature job the model reads a list of those measurements, never the fil
 
 The report says what was wired in, what the project uses, what is unused and which placeholders are left for you to supply. The names are in `assets-report.md` in the run directory, which stays on your machine.
 
+## Punch list and blue tape (Labs beta)
+
+Adding, closing, promoting and drafting need Ravensight Labs on for the game.
+The list commands still read when Labs is off; they show an empty list then.
+The dashboard shows the same two lists.
+
+The punch list holds what has to be finished before handover. You close the
+items one at a time. Blue tape holds small annoyances a new player meets in the
+first minutes. Capture them fast, then promote the ones that matter to the
+punch list.
+
+```sh
+ravensight-playtest punch list                  # open items; --status open|done|dropped|all
+ravensight-playtest punch add "Make the jump button respond on the first press."
+ravensight-playtest punch done li_9f2c
+ravensight-playtest punch drop li_9f2c
+ravensight-playtest punch draft                 # one AI unit; prints proposals, saves nothing
+ravensight-playtest punch draft --accept        # one AI unit; adds every proposal
+
+ravensight-playtest tape "The title music is too loud."
+ravensight-playtest tape list
+ravensight-playtest tape promote li_4a1b        # moves it to the punch list
+ravensight-playtest tape drop li_4a1b
+
+ravensight-playtest fix li_9f2c                 # an item that came from a finding
+```
+
+Reading, adding, closing and promoting are free. `punch draft` proposes items
+from the game's findings and specifications. It costs one AI unit, and nothing
+when there is nothing to propose. Without `--accept` it saves nothing. It asks
+before it spends, so pass `--yes` in a script. A list holds at most 500 open
+items.
+
+Each added item gets a free plain-language check, printed as hints under it:
+long sentences, two instructions in one sentence, passive voice, and words with
+a simpler choice. The hints follow the rules of Simplified Technical English.
+They never block an item.
+
+No command here closes an item for you, including `fix li_...`.
+
+| Flag | Effect |
+|---|---|
+| `--game <gameId>` | The game, when this repo is not linked. |
+| `--status <status>` | `list` only: `open` (the default), `done`, `dropped` or `all`. |
+| `--accept` | `punch draft` only: add every proposal to the punch list. |
+| `--json` | Print the server's answer as JSON. |
+
+### Fresh eyes
+
+A fresh-eyes playtest is a persona run with the `fresh-eyes` persona: a player
+in their first session who reports only small friction. When the job finishes,
+each of its findings becomes an open blue tape item.
+
+```sh
+ravensight-playtest personas                    # check that fresh-eyes is listed for your game
+ravensight-playtest run --personas fresh-eyes
+```
+
+It is priced as any persona run is. Personas come from the content pack the
+server sends, so `fresh-eyes` works once the server lists it. No CLI upgrade is
+needed for it.
+
 ## 3D proof of concept (Labs, Alpha)
 
 Labs beta is Godot 2D. There is one 3D template, for trying Build a feature and Validate changes on a 3D project. That is the whole of the Alpha: `create` does not make a 3D game from a brief and refuses to try, and how well a real model builds 3D has not been measured. It has no switch of its own, needing the same Labs opt-in and capability switches, and no price of its own: the jobs cost what they cost on a 2D project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Local AI playtests and seeded game simulations with reports in Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",

package/src/api/client.js

@@ -14,6 +14,15 @@ function gameBase(gameId) {
   return `/api/v1/games/${encodeURIComponent(gameId)}/playtest`;
 }
 
+/** `/api/v1/games/:gameId/labs/lists/:list`, for the punch list and blue tape. */
+function labsListBase(gameId, list) {
+  if (typeof gameId !== 'string' || gameId.length === 0) {
+    throw new TypeError('gameId is required');
+  }
+  if (list !== 'punch' && list !== 'tape') throw new TypeError('list must be punch or tape');
+  return `/api/v1/games/${encodeURIComponent(gameId)}/labs/lists/${list}`;
+}
+
 /**
  * The Ravensight playtest API, as one object with one namespace per surface.
  *
@@ -407,6 +416,25 @@ export function createClient(options = {}) {
      * free. Editing and approving are the dashboard's, on purpose: this token
      * cannot do either.
      */
+    /**
+     * The punch list and blue tape. `list` is `punch` or `tape`. Reads and
+     * plain writes are free; `draft` is one AI unit and saves nothing.
+     */
+    lists: {
+      list: (gameId, list, { status } = {}) =>
+        get(labsListBase(gameId, list), { query: status ? { status } : undefined }),
+      get: (gameId, list, itemId) =>
+        get(`${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`),
+      add: (gameId, list, body) =>
+        request('POST', labsListBase(gameId, list), { body }).then(answer => answer.body),
+      update: (gameId, list, itemId, body) =>
+        request('PATCH', `${labsListBase(gameId, list)}/items/${encodeURIComponent(itemId)}`, { body }).then(answer => answer.body),
+      promote: (gameId, itemId) =>
+        request('POST', `${labsListBase(gameId, 'tape')}/items/${encodeURIComponent(itemId)}/promote`, { body: {} }).then(answer => answer.body),
+      draft: gameId =>
+        request('POST', `${labsListBase(gameId, 'punch')}/draft`, { body: {} }).then(answer => answer.body)
+    },
+
     featureSpecs: {
       create: (gameId, brief, extra = {}) =>
         request('POST', `/api/v1/games/${encodeURIComponent(gameId)}/labs/feature-specs`, { body: { brief, ...extra } }).then(answer => answer.body),

package/src/cli.js

@@ -537,6 +537,74 @@ export function buildProgram() {
       }));
     }));
 
+  // Labs lists. Each subcommand takes the shared flags itself, so `--json` and
+  // `--game` work after the subcommand name, where people type them.
+  const listFlags = command => common(command).option('--game <gameId>', 'the game, when this repo is not linked');
+  const statusOption = () => new Option('--status <status>', 'which items to show').choices(['open', 'done', 'dropped', 'all']).default('open');
+
+  const punch = common(program.command('punch')
+    .description('Labs beta: the punch list, what has to be finished before handover, closed one item at a time'));
+  listFlags(punch.command('list').description('show the punch list; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { punchList } = await import('./commands/punch.js');
+      return punchList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(punch.command('add').description('add one item; free, with plain-language hints'))
+    .argument('<text>', 'the item, in quotes')
+    .action(capture(slot, async (text, options) => {
+      const { punchAdd } = await import('./commands/punch.js');
+      return punchAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('done').description('close an item as done; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'done', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('drop').description('close an item as dropped; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { punchClose } = await import('./commands/punch.js');
+      return punchClose(itemId, 'dropped', flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(punch.command('draft').description('propose items from this game\'s findings and specs; one AI unit, saves nothing without --accept'))
+    .option('--accept', 'add every proposal to the punch list')
+    .action(capture(slot, async options => {
+      const { punchDraft } = await import('./commands/punch.js');
+      return punchDraft(flagsFrom(options, { game: options.game, accept: Boolean(options.accept) }));
+    }));
+
+  const tape = listFlags(program.command('tape')
+    .description('Labs beta: blue tape, small first-impression annoyances; tape "<text>" captures one'))
+    .argument('[text]', 'the annoyance, in quotes')
+    .action(capture(slot, async (text, options, command) => {
+      if (!text) {
+        command.outputHelp();
+        return ExitCode.FAILURE;
+      }
+      const { tapeAdd } = await import('./commands/tape.js');
+      return tapeAdd(text, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('list').description('show blue tape; free'))
+    .addOption(statusOption())
+    .action(capture(slot, async options => {
+      const { tapeList } = await import('./commands/tape.js');
+      return tapeList(flagsFrom(options, { game: options.game, status: options.status }));
+    }));
+  listFlags(tape.command('promote').description('move an item to the punch list; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapePromote } = await import('./commands/tape.js');
+      return tapePromote(itemId, flagsFrom(options, { game: options.game }));
+    }));
+  listFlags(tape.command('drop').description('drop an item; free'))
+    .argument('<itemId>', 'the item id, li_...')
+    .action(capture(slot, async (itemId, options) => {
+      const { tapeDrop } = await import('./commands/tape.js');
+      return tapeDrop(itemId, flagsFrom(options, { game: options.game }));
+    }));
+
   common(program.command('simulation-replay').description('verify a recorded simulation trace locally; creates no paid job'))
     .argument('<trace>', 'a selected trace.json written by simulate')
     .requiredOption('--driver-config <file>', 'local JSON-RPC executable configuration')

package/src/commands/fix.js

@@ -29,6 +29,8 @@ import * as stateFile from '../run/state.js';
 import { createUsageLedger, writeUsageFile } from '../run/usage.js';
 import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, godotRefusal, resolveSetup, resolveTarget, skillFor, usableLocalBrief, startBalanceLine, startBalanceShort } from './run.js';
 import { loadLocalBrief } from '../briefLocal.js';
+import { findListItem } from './lists.js';
+import { jobLink } from '../dashboard.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -212,9 +214,9 @@ async function fix(target, flags, injected, deps, log) {
     for (const line of unknownOptionNotes(unknown)) log(line);
     return EXIT.ENVIRONMENT;
   }
-  const parsed = parseTarget(target);
+  let parsed = parseTarget(target);
   if (!parsed) {
-    log('Name the finding to fix: either <jobId>/<label>, like pt_job_1/F002, or a finding id.');
+    log('Name the finding to fix: either <jobId>/<label>, like pt_job_1/F002, a finding id, or a punch list item, li_...');
     return EXIT.ENVIRONMENT;
   }
 
@@ -222,6 +224,20 @@ async function fix(target, flags, injected, deps, log) {
   if (setup.code !== undefined) return setup.code;
   const { context, api, gameId, apiUrl, repoRoot, cliVersion } = setup;
 
+  // A punch list item that came from a finding is fixed as that finding. The
+  // item only lends its finding's id, and later records the job; it is never closed here.
+  let listItem = null;
+  if (isListItemTarget(target)) {
+    const resolved = await resolveListItemTarget(api, gameId, String(target).trim());
+    if (resolved.refusal) {
+      log(resolved.refusal);
+      return EXIT.ENVIRONMENT;
+    }
+    listItem = resolved;
+    parsed = parseTarget(resolved.item.source.ref);
+    log(`${resolved.item.item_id} came from ${resolved.item.source.kind === 'fresh_eyes' ? 'fresh-eyes finding' : 'finding'} ${resolved.item.source.ref}, so this fixes that finding.`);
+  }
+
   const wantsVerify = options.verify !== false;
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
   const buildTarget = resolveTarget(options, context.config, driverName, repoRoot);
@@ -477,6 +493,7 @@ async function fix(target, flags, injected, deps, log) {
   // the runs, because the charge has already happened: a developer who cannot
   // name the job they paid for cannot ask anybody about it either.
   log(`job ${jobId}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${jobDir(repoRoot, jobId)}`);
+  if (listItem) await recordFixJob({ api, gameId, listItem, jobId, link: (registered.links && registered.links.dashboard) || jobLink(gameId, jobId, apiUrl), log });
 
   if (!fixRun) {
     log('The server registered the job without a fix run, so there is nothing to spend a model turn from.');
@@ -931,6 +948,56 @@ async function fix(target, flags, injected, deps, log) {
  * @param {{jobId: string|null, label: string|null, findingId: string|null}} target
  * @returns {Promise<Object|null>}
  */
+/** The list item sources whose ref is a finding a fix can replay. */
+export const FIXABLE_SOURCES = Object.freeze(['finding', 'fresh_eyes']);
+
+/** Whether a fix target names a Labs list item rather than a finding. */
+export function isListItemTarget(target) {
+  return String(target || '').trim().startsWith('li_');
+}
+
+/**
+ * Find a list item and check it came from a finding. Only a finding has the
+ * persona, the repro steps and the replay a fix needs; anything else is new
+ * work, which is what `feature` builds.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @param {string} itemId
+ * @returns {Promise<{item: Object, list: string}|{refusal: string}>}
+ */
+export async function resolveListItemTarget(api, gameId, itemId) {
+  if (!api.labs || !api.labs.lists) {
+    return { refusal: 'This server has no punch list. Fix the finding by its id instead.' };
+  }
+  const found = await findListItem(api, gameId, itemId);
+  if (!found) {
+    return { refusal: `No item ${itemId} is on this game's punch list or blue tape. Run "ravensight-playtest punch list --status all" to see the ids.` };
+  }
+  const source = found.item.source || {};
+  // A fresh-eyes item's ref is a finding's targetId too.
+  if (!FIXABLE_SOURCES.includes(source.kind) || !source.ref) {
+    return {
+      refusal: `${itemId} did not come from a finding, so fix has nothing to replay. Use "ravensight-playtest feature" for that item. Nothing was charged.`
+    };
+  }
+  return found;
+}
+
+/**
+ * Record the fix job on the list item. Best effort: the job is already paid
+ * for, and a list that cannot be written must not stop the fix.
+ */
+async function recordFixJob({ api, gameId, listItem, jobId, link, log }) {
+  const itemId = listItem.item.item_id;
+  try {
+    await api.labs.lists.update(gameId, listItem.list, itemId, { fix_job_id: jobId });
+    log(`Recorded job ${jobId} on ${itemId}: ${link}. The item stays open until you close it.`);
+  } catch (error) {
+    log(`warning: could not record job ${jobId} on ${itemId} (${error && error.message ? error.message : error}). The fix carries on.`);
+  }
+}
+
 export async function resolveFinding(api, gameId, target) {
   const answer = await api.jobs.findings(gameId, target.jobId ? { job: target.jobId } : {});
   const list = (answer && answer.findings) || [];

package/src/commands/lists.js

@@ -0,0 +1,206 @@
+import { createContext } from '../api/index.js';
+import { ApiError } from '../api/errors.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { CliError, ExitCode } from '../errors.js';
+import { ui } from '../ui/index.js';
+
+/**
+ * What `punch` and `tape` share: the game, the client, the refusals in plain
+ * words, and how an item is printed.
+ *
+ * The punch list holds what has to be finished before handover, closed one at
+ * a time. Blue tape holds small first-impression annoyances, captured fast and
+ * promoted to the punch list when they matter. Both live on the server under
+ * the game's Labs lists, so the dashboard and this CLI read the same items.
+ */
+
+export const LIST_NAMES = Object.freeze({ punch: 'punch list', tape: 'blue tape list' });
+export const STATUSES = Object.freeze(['open', 'done', 'dropped', 'all']);
+export const ITEM_ID = /^li_[A-Za-z0-9_-]+$/;
+export const LIMIT = 500;
+
+/**
+ * Run `fn` with the client and the game this repo is linked to (or `--game`).
+ * @param {Object} flags
+ * @param {Object} deps test seam: context
+ * @param {(setup: {api: Object, gameId: string}) => Promise<number>} fn
+ * @returns {Promise<number>}
+ */
+export async function withList(flags, deps, fn) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const gameId = resolveGameId(flags, context.config);
+    return fn({ api: context.api, gameId });
+  });
+}
+
+/**
+ * A refusal from the lists routes as a sentence a person can act on. Anything
+ * this does not recognise is handed back unchanged for `report` to print.
+ *
+ * @param {unknown} error
+ * @param {{list: string, itemId?: string|null}} where
+ * @returns {unknown}
+ */
+export function listError(error, { list, itemId = null }) {
+  if (!(error instanceof ApiError) && !(error && typeof error.status === 'number' && typeof error.code === 'string')) return error;
+  const name = LIST_NAMES[list] || 'list';
+  if (error.code === 'labs_not_enabled') {
+    return new CliError(
+      `The ${name} is part of Ravensight Labs (beta). Labs is not on for this game.`,
+      ExitCode.ENVIRONMENT,
+      { hint: 'Turn Labs on from the Labs page in the dashboard. Nothing was changed.' }
+    );
+  }
+  if (error.code === 'item_closed') {
+    return new CliError(`${itemId || 'That item'} is closed. Reopen it first, then promote it.`, ExitCode.FAILURE);
+  }
+  if (error.code === 'quota_exceeded') {
+    return new CliError('This account has no AI units left. Add funds, then try again. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'labs_list_attempts') {
+    return new CliError('Too many drafts came back empty this hour. Try again later. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'ai_unavailable') {
+    return new CliError('The AI service is not available right now. Try again later. Nothing was charged.', ExitCode.FAILURE);
+  }
+  if (error.code === 'list_full') {
+    return new CliError(
+      `The ${name} already has ${LIMIT} open items. Close or drop some, then add this one.`,
+      ExitCode.FAILURE
+    );
+  }
+  if (error.status === 404) {
+    if (itemId) {
+      return new CliError(
+        `No item ${itemId} is on this game's ${name}.`,
+        ExitCode.FAILURE,
+        { hint: `Run "ravensight-playtest ${list} list --status all" to see the item ids.` }
+      );
+    }
+    return new CliError(
+      `This game has no ${name} that this token can see.`,
+      ExitCode.FAILURE,
+      { hint: 'Run "ravensight-playtest check" to confirm the game is linked. An older server has no lists yet.' }
+    );
+  }
+  return error;
+}
+
+/**
+ * Call the server and turn its refusals into sentences.
+ * @template T
+ * @param {() => Promise<T>} call
+ * @param {{list: string, itemId?: string|null}} where
+ * @returns {Promise<T>}
+ */
+export async function guarded(call, where) {
+  try {
+    return await call();
+  } catch (error) {
+    throw listError(error, where);
+  }
+}
+
+/**
+ * Refuse an id that cannot be an item before asking the server about it.
+ * @param {string} itemId
+ */
+export function requireItemId(itemId) {
+  const value = String(itemId || '').trim();
+  if (!ITEM_ID.test(value)) {
+    throw new CliError(`"${value}" is not an item id. Item ids start with li_.`, ExitCode.FAILURE, {
+      hint: 'Run "ravensight-playtest punch list" or "ravensight-playtest tape list" to see them.'
+    });
+  }
+  return value;
+}
+
+/**
+ * Refuse empty text here rather than spend a round trip on it.
+ * @param {string} text
+ */
+export function requireText(text) {
+  const value = String(text || '').trim();
+  if (!value) throw new CliError('Say what the item is, in quotes.', ExitCode.FAILURE);
+  return value;
+}
+
+/** @param {string|undefined} status */
+export function requireStatus(status) {
+  if (status === undefined || status === null) return 'open';
+  if (!STATUSES.includes(status)) {
+    throw new CliError(`--status takes ${STATUSES.join(', ')}.`, ExitCode.FAILURE);
+  }
+  return status;
+}
+
+/** Where an item came from, in a few words. */
+export function sourceWords(source) {
+  if (!source || !source.kind || source.kind === 'manual') return 'manual';
+  const kind = String(source.kind).replace(/_/g, ' ');
+  return source.ref ? `${kind} ${source.ref}` : kind;
+}
+
+/** The plain-language hints under an item. A hint, never a block. */
+export function printHints(item) {
+  const issues = item && item.plain_check && Array.isArray(item.plain_check.issues) ? item.plain_check.issues : [];
+  for (const issue of issues) {
+    if (issue && issue.message) ui.info(`  hint: ${issue.message}`);
+  }
+  return issues.length;
+}
+
+/**
+ * Print a list answer as a table, or say it is empty.
+ * @param {Object} answer `{ items, counts }`
+ * @param {string} list
+ * @param {string} status
+ */
+export function printList(answer, list, status) {
+  const items = answer && Array.isArray(answer.items) ? answer.items : [];
+  const name = LIST_NAMES[list];
+  if (items.length === 0) {
+    ui.info(status === 'all' ? `The ${name} is empty.` : `The ${name} has no ${status} items.`);
+  } else {
+    ui.table(items.map(item => ({
+      item_id: item.item_id,
+      status: item.status,
+      text: item.text,
+      source: sourceWords(item.source) + (item.promoted_to ? `, now ${item.promoted_to}` : '') + (item.fix_job_id ? `, fix ${item.fix_job_id}` : '')
+    })), [
+      { key: 'item_id', label: 'ITEM' },
+      { key: 'status', label: 'STATUS' },
+      { key: 'text', label: 'TEXT' },
+      { key: 'source', label: 'SOURCE' }
+    ]);
+  }
+  const counts = answer && answer.counts;
+  if (counts) {
+    ui.blank();
+    ui.info(`${counts.open ?? 0} open, ${counts.done ?? 0} done, ${counts.dropped ?? 0} dropped.`);
+  }
+}
+
+/**
+ * Find one item by id, for `fix li_...`. The punch list first, because that is
+ * where a finding to fix usually sits, then blue tape on a 404.
+ *
+ * @param {Object} api
+ * @param {string} gameId
+ * @param {string} itemId
+ * @returns {Promise<{item: Object, list: string}|null>}
+ */
+export async function findListItem(api, gameId, itemId) {
+  for (const list of ['punch', 'tape']) {
+    try {
+      const answer = await api.labs.lists.get(gameId, list, itemId);
+      if (answer && answer.item) return { item: answer.item, list };
+    } catch (error) {
+      if (error && error.status === 404) continue;
+      throw listError(error, { list, itemId });
+    }
+  }
+  return null;
+}

package/src/commands/punch.js

@@ -0,0 +1,116 @@
+import { ui } from '../ui/index.js';
+import { ExitCode } from '../errors.js';
+import { guarded, printHints, printList, requireItemId, requireStatus, requireText, sourceWords, withList } from './lists.js';
+
+/**
+ * `ravensight-playtest punch`: the punch list (Labs beta).
+ *
+ * What has to be finished before handover, closed one item at a time. Reading,
+ * adding and closing are free. `draft` asks for proposals from the game's
+ * findings and specs, which is one AI unit, and saves nothing unless
+ * `--accept` is passed. Nothing here closes an item on its own: `fix li_...`
+ * records the fix job on the item and leaves closing it to a person.
+ */
+
+const LIST = 'punch';
+
+/** `punch list [--status open|done|dropped|all]` */
+export async function punchList(flags = {}, deps = {}) {
+  const status = requireStatus(flags.status);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.list(gameId, LIST, { status }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    printList(answer, LIST, status);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch add "<text>"` */
+export async function punchAdd(text, flags = {}, deps = {}) {
+  const value = requireText(text);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.add(gameId, LIST, { text: value }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    printAdded(answer);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch done <li_id>` and `punch drop <li_id>` */
+export async function punchClose(itemId, status, flags = {}, deps = {}) {
+  const id = requireItemId(itemId);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.update(gameId, LIST, id, { status }), { list: LIST, itemId: id });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    const text = answer && answer.item && answer.item.text ? `: ${answer.item.text}` : '';
+    ui.ok(`${status === 'done' ? 'Done' : 'Dropped'} ${id}${text}`);
+    return ExitCode.OK;
+  });
+}
+
+/** `punch draft [--accept]` */
+export async function punchDraft(flags = {}, deps = {}) {
+  return withList(flags, deps, async ({ api, gameId }) => {
+    if (!flags.json) {
+      ui.info('Drafting a punch list is one AI unit. It is not charged when there is nothing to propose.');
+      ui.info(flags.accept ? 'Every proposal will be added to the punch list.' : 'Nothing is saved. Pass --accept to add the proposals.');
+    }
+    const confirm = deps.confirm || ui.confirm;
+    if (!flags.yes && !(await confirm('Draft the punch list?', { yes: flags.yes }))) {
+      ui.info('Nothing was charged. Pass --yes to draft without a terminal.');
+      return ExitCode.CANCELED;
+    }
+    const answer = await guarded(() => api.labs.lists.draft(gameId), { list: LIST });
+    const proposals = answer && Array.isArray(answer.proposals) ? answer.proposals : [];
+    const added = [];
+    if (flags.accept) {
+      try {
+        for (const proposal of proposals) {
+          const body = proposal.source ? { text: proposal.text, source: proposal.source } : { text: proposal.text };
+          added.push(await guarded(() => api.labs.lists.add(gameId, LIST, body), { list: LIST }));
+        }
+      } catch (error) {
+        // Say what was saved before the refusal, so nobody adds it twice.
+        if (!flags.json) for (const saved of added) printAdded(saved);
+        throw error;
+      }
+    }
+    if (flags.json) {
+      ui.json({ ...answer, ...(flags.accept ? { added } : {}) });
+      return ExitCode.OK;
+    }
+    if (proposals.length === 0) {
+      ui.info('No proposals, so nothing was charged.');
+      return ExitCode.OK;
+    }
+    const units = Number(answer.units) || 0;
+    ui.info(`${proposals.length} proposal${proposals.length === 1 ? '' : 's'}, ${units} AI unit${units === 1 ? '' : 's'} charged:`);
+    if (flags.accept) {
+      for (const saved of added) printAdded(saved);
+      return ExitCode.OK;
+    }
+    proposals.forEach((proposal, index) => {
+      ui.info(`  ${index + 1}. ${proposal.text} (${sourceWords(proposal.source)})`);
+    });
+    ui.blank();
+    ui.info('Nothing was saved. Add the ones you want with "ravensight-playtest punch add".');
+    return ExitCode.OK;
+  });
+}
+
+/** One added item, with its plain-language hints under it. */
+export function printAdded(answer) {
+  const item = answer && answer.item ? answer.item : {};
+  if (answer && answer.existing) ui.info(`Already on the list: ${item.item_id}, ${item.text}`);
+  else ui.ok(`Added ${item.item_id}: ${item.text}`);
+  if (printHints(item) > 0) ui.info('  These hints follow the rules of Simplified Technical English. They never block an item.');
+}

package/src/commands/tape.js

@@ -0,0 +1,74 @@
+import { ui } from '../ui/index.js';
+import { ExitCode } from '../errors.js';
+import { guarded, printHints, printList, requireItemId, requireStatus, requireText, withList } from './lists.js';
+
+/**
+ * `ravensight-playtest tape`: blue tape (Labs beta).
+ *
+ * Small first-impression annoyances, captured in one line while they are
+ * fresh. Free. An item that turns out to matter is promoted to the punch list,
+ * which closes the tape item and keeps its source.
+ */
+
+const LIST = 'tape';
+
+/** `tape "<text>"` */
+export async function tapeAdd(text, flags = {}, deps = {}) {
+  const value = requireText(text);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.add(gameId, LIST, { text: value }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    const item = answer && answer.item ? answer.item : {};
+    if (answer && answer.existing) ui.info(`Already taped: ${item.item_id}, ${item.text}`);
+    else ui.ok(`Taped ${item.item_id}: ${item.text}`);
+    if (printHints(item) > 0) ui.info('  These hints follow the rules of Simplified Technical English. They never block an item.');
+    return ExitCode.OK;
+  });
+}
+
+/** `tape list [--status open|done|dropped|all]` */
+export async function tapeList(flags = {}, deps = {}) {
+  const status = requireStatus(flags.status);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.list(gameId, LIST, { status }), { list: LIST });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    printList(answer, LIST, status);
+    return ExitCode.OK;
+  });
+}
+
+/** `tape promote <li_id>` */
+export async function tapePromote(itemId, flags = {}, deps = {}) {
+  const id = requireItemId(itemId);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.promote(gameId, id), { list: LIST, itemId: id });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    const promoted = answer && answer.promoted ? answer.promoted : {};
+    ui.ok(`Promoted ${id} to the punch list as ${promoted.item_id}: ${promoted.text}`);
+    return ExitCode.OK;
+  });
+}
+
+/** `tape drop <li_id>` */
+export async function tapeDrop(itemId, flags = {}, deps = {}) {
+  const id = requireItemId(itemId);
+  return withList(flags, deps, async ({ api, gameId }) => {
+    const answer = await guarded(() => api.labs.lists.update(gameId, LIST, id, { status: 'dropped' }), { list: LIST, itemId: id });
+    if (flags.json) {
+      ui.json(answer);
+      return ExitCode.OK;
+    }
+    const text = answer && answer.item && answer.item.text ? `: ${answer.item.text}` : '';
+    ui.ok(`Dropped ${id}${text}`);
+    return ExitCode.OK;
+  });
+}