cawdev-cli 1.0.8-beta → 1.0.10-beta

package/README.md

@@ -5,4 +5,9 @@ and spawning processes are Node's home turf, and a file with no dependencies is
 one you can read before running it against your repositories.
 visit https://cawdev.com to learn more
 
-https://github.com/4dali/cawdev-cli
+https://github.com/4dali/cawdev-cli
+## jira/
+
+`jira/import.mjs` brings a Jira Cloud project's issues, epics, sprints and
+comments into a cawdev project, once and again without duplicates (R337). Run from a checkout; see
+"Leaving Jira" in GUIDE.md. Its tests: `node --test "tools/jira/*.test.mjs"`.

package/lib/roadmap-format.mjs

@@ -56,11 +56,13 @@ export function statusToDisplay(status) {
  * The file has always grouped these two this way, and deriving them means a
  * declined entry cannot end up filed under a phase it is no longer part of.
  *
- * Two, and REVIEW is deliberately not a third: work waiting to be read is still
+ * Three since R371 — BACKLOG joined — and REVIEW is deliberately not a fourth: work waiting to be read is still
  * part of the phase it belongs to, and moving it to a section of its own would
  * take it out of its phase for a few days and put it back afterwards.
  */
 export const STATUS_SECTIONS = {
+  // R371: waiting to be brought in, before what is being considered.
+  BACKLOG: 'Backlog — waiting to be brought in',
   CONSIDERING: 'Considering — wanted, not settled',
   DECLINED: 'Declined — decided against, with the reason',
 };
@@ -77,6 +79,8 @@ export const STATUS_SECTIONS = {
 export const ISSUE_SECTIONS = {
   NEW: 'New — filed, not yet triaged',
   CONFIRMED: 'Confirmed — real, waiting for somebody',
+  // R371: an issue waiting to be brought in — after what needs somebody now.
+  BACKLOG: 'Backlog — waiting to be brought in',
   IN_DEVELOPMENT: 'In development — somebody is fixing it',
   MERGED: 'Resolved — the fix landed',
   SHIPPED: 'Released — the fix shipped',
@@ -232,6 +236,32 @@ export function parseRoadmap(text) {
         }
         continue;
       }
+      // R351. The date shape is checked here, where the line is read: a
+      // `Due:` that is not a date is a hand edit, and --live would otherwise
+      // report it as drift from a database that never held it.
+      const due = /^Due:\s*(.+)$/.exec(line.trim());
+      if (due) {
+        entry.due = due[1].trim();
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.due) || Number.isNaN(Date.parse(entry.due))) {
+          problems.push(`${block.heading}: Due "${due[1].trim()}" is not a date written 2026-11-01.`);
+        }
+        continue;
+      }
+      // R358. The version the card means to ship in; a free string, as `Version:` is.
+      const target = /^Target:\s*(.+)$/.exec(line.trim());
+      if (target) {
+        entry.targetVersion = target[1].trim();
+        continue;
+      }
+      const estimate = /^Estimate:\s*(.+)$/.exec(line.trim());
+      if (estimate) {
+        const n = Number(estimate[1].trim());
+        entry.estimate = n;
+        if (!Number.isInteger(n) || n <= 0) {
+          problems.push(`${block.heading}: Estimate "${estimate[1].trim()}" is not a positive whole number.`);
+        }
+        continue;
+      }
       const development = /^Development:\s*(.+)$/.exec(line.trim());
       if (development) {
         entry.development = statusFromDisplay(development[1].trim());
@@ -262,6 +292,16 @@ export function parseRoadmap(text) {
         entry.afterRefs = tokens.map(({ ref }) => ref);
         continue;
       }
+      const parent = /^Parent:\s*(\S+)\s*$/.exec(line.trim());
+      if (parent) {
+        // R336. One ref, always written in full (R300, i12). A token that is
+        // not a card is left as ordinary body text rather than eaten.
+        const token = parseRefToken(parent[1]);
+        if (token) {
+          entry.parentRef = token.ref;
+          continue;
+        }
+      }
       const tags = /^Tags:\s*(.+)$/.exec(line.trim());
       if (tags) {
         // R315. Already normalised by the server (lowercase, no `#`) by the
@@ -356,6 +396,45 @@ function* splitBlocks(text) {
   if (entry) yield entry;
 }
 
+/** The ref of the card this one sits under, from either shape — R336. */
+function parentRefOf(entry) {
+  const ref = entry.parent?.ref ?? entry.parentRef;
+  return ref ? (parseRefToken(ref)?.ref ?? null) : null;
+}
+
+/**
+ * Files each child directly after its parent, within one section — R336.
+ *
+ * Pure. A child keeps its place among its siblings (they stay in the order
+ * given), and a child whose parent is in some other section stays exactly
+ * where it was: the file groups by section first, and an epic spread over
+ * phases is still one epic by its `Parent:` lines.
+ */
+export function nestUnderParents(list) {
+  const refs = new Map(list.map((entry) => [entryRef(entry), entry]));
+  const nestedUnder = (entry) => {
+    const parent = parentRefOf(entry);
+    const card = parent && refs.get(parent);
+    // A parent that is itself a child is bad data; leave the child where it is
+    // rather than lose it behind a card that is not a root.
+    return card && !parentRefOf(card) ? parent : null;
+  };
+  const children = new Map();
+  for (const entry of list) {
+    const parent = nestedUnder(entry);
+    if (parent) {
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(entry);
+    }
+  }
+  const out = [];
+  for (const entry of list) {
+    if (nestedUnder(entry)) continue;
+    out.push(entry, ...(children.get(entryRef(entry)) ?? []));
+  }
+  return out;
+}
+
 /**
  * Writes entries as ROADMAP.md's entry sections.
  *
@@ -385,7 +464,7 @@ export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
   const parts = [preamble.trimEnd(), ''];
   for (const section of ordered) {
     parts.push('---', '', `## ${section}`, '');
-    for (const entry of bySection.get(section)) {
+    for (const entry of nestUnderParents(bySection.get(section))) {
       parts.push(renderEntry(entry), '');
     }
   }
@@ -443,6 +522,19 @@ function renderEntry(entry) {
     lines.push(`Priority: ${entry.priority}`);
   }
 
+  // R351. Two facts, written only when the card carries them, after the
+  // priority: when, then how big.
+  if (entry.due) {
+    lines.push(`Due: ${entry.due}`);
+  }
+  if (entry.estimate != null && entry.estimate > 0) {
+    lines.push(`Estimate: ${entry.estimate}`);
+  }
+  // R358. Where it means to ship; dropped once it has, because `Version:` then says.
+  if (entry.targetVersion && !entry.version) {
+    lines.push(`Target: ${entry.targetVersion}`);
+  }
+
   // Each status writes only what it currently claims. A MERGED entry keeps its
   // branch in the database as history, but the file must not print it: the
   // branch is expected to be deleted, and `--live` would then be reading a claim
@@ -492,6 +584,13 @@ function renderEntry(entry) {
       .map(({ ref }) => ref);
     lines.push(`After: ${written.join(', ')}`);
   }
+  {
+    // R336. The API gives `parent` as {number, ref, title}; the parser gives
+    // `parentRef`. Always the full ref, and no line at all without a parent, so
+    // no existing card's text changes.
+    const parent = parentRefOf(entry);
+    if (parent) lines.push(`Parent: ${parent}`);
+  }
   if (entry.tags?.length) {
     // R315. Sorted, so the export does not churn on the set's own order.
     lines.push(`Tags: ${[...entry.tags].sort().join(', ')}`);

package/lib/runner-config.mjs

@@ -76,7 +76,7 @@ function canonical(value) {
   if (value === undefined) return 'undefined';
   return JSON.stringify(value, (_, inner) => (
     inner && typeof inner === 'object' && !Array.isArray(inner)
-      ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+      ? Object.fromEntries(Object.keys(inner).sort((a, b) => a.localeCompare(b)).map((key) => [key, inner[key]]))
       : inner
   ));
 }

package/mcp/README.md

@@ -81,6 +81,14 @@ commit, or a sha — `SHIPPED` needs a version that is a real git tag, and
 request it would otherwise carry belongs to the run, and a project that reviews
 without opening pull requests has none to give it.
 
+**A card you file may land in the `BACKLOG`** (R371). Where a new card goes
+when you name no status is the project's rule, per door, and the default for a
+card or issue an agent files is the backlog: waiting until a person or a sprint
+brings it in, in no sprint and on no board column. Its origin names your
+session and the card your run was on. Name a status (`CONSIDERING`, `NEW`) when
+you mean the pipeline. Giving a backlog card a sprint moves it to the first
+status of its kind; moving a card to `BACKLOG` takes it out of its sprint.
+
 **Any status may move to any other.** There is no transition diagram — an entry
 really can go from `CONSIDERING` straight to `SHIPPED` if that is what happened.
 The rules are about what a status *carries*, not the path it took.
@@ -163,11 +171,12 @@ what you are allowed to do.
 | `roadmap_list` | Entries, optionally by status. `brief` omits bodies — use it to survey. |
 | `roadmap_get` | One entry in full: its body, **the plan agreed for it**, and the discussion on it. |
 | `roadmap_create` | Create an entry; the platform allocates its permanent number. |
-| `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
+| `roadmap_update` | Title, body, section, related ids, the cards it starts coding after (`after` — R181), when it is due and how big it is (`due` — R351: an ISO date, `""` clears; `estimate`: a positive number, `0` clears), the version it is meant for (`targetVersion` — R358, `""` clears; since R362 it must be one the project defined under Project settings → Versions, and any other name is refused), and who it is assigned to (`assignee` — R331: a username, `""` clears; `roadmap_list`/`issue_list` take `assignee` too, and `me` means the token's owner). |
 | `roadmap_comment` | Say something *beside* an entry rather than inside it. |
+| `done_when_tick` | Tick (or untick) one numbered item of the card's Done-when checklist as built, with one line of evidence (R368). `task_current` lists the items. Defaults to the run's own card and refuses another; the reviewer's column is a person's and no token can set it. |
 | `roadmap_set_status` | Move an entry, carrying whatever the status requires. |
 | `roadmap_decline` | Decline with a reason. The only exit. |
-| `backlog_file` | File **feedback**, not a card — something a person should decide about. A WRITER accepts it as a card or an issue, or refuses it (R199). |
+| `backlog_file` | File **feedback**, not a card — something a person should decide about. A WRITER accepts it as a card or an issue, or refuses it (R199). Tagged `agent` as a source, plus any `tags` you pass — `customer` when you relay what a user said (R372). |
 | `changelog_list` | The changelog, grouped by release, newest first. |
 | `changelog_get` | One entry. |
 | `changelog_add` | Add an entry; no version means `Unreleased`. |

package/mcp/server.mjs

@@ -412,6 +412,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'NEW',
@@ -621,13 +622,70 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'done_when_tick',
+    description:
+      "Tick (or untick) one item of the card's Done-when checklist as built. Items are " +
+      "numbered from 1 as task_current lists them. Call it when you have BUILT the item and " +
+      'CHECKED it, with one line of evidence — a test name, a command, a file:line. Do not ' +
+      'tick what you did not check: the reviewer ticks their own column separately and sees ' +
+      'yours. Defaults to the card this run is working on, and a run cannot tick another.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ...PROJECT_ARGUMENT,
+        number: {
+          type: ['string', 'integer'],
+          description:
+            'The card by ref — R91, i91. Optional inside a run: defaults to the run\'s own card.',
+        },
+        item: { type: 'integer', minimum: 1, description: "The item's number, from 1." },
+        done: { type: 'boolean', description: 'false takes the tick back. Default true.' },
+        note: {
+          type: 'string',
+          description: 'One line of evidence: a test name, a command, a file:line.',
+        },
+      },
+      required: ['item'],
+    },
+    handler: async (config, args) => {
+      let slug;
+      let ref = args.number;
+      if (ref === undefined || ref === null || ref === '') {
+        const { runId, project } = await requireRun(config);
+        const run = await api(config, `/api/projects/${project}/runs/${runId}`);
+        ref = run.entryRef ?? run.entryNumber;
+        slug = project;
+      } else {
+        slug = await resolveProject(config, args.project);
+      }
+      if (ref === undefined || ref === null || ref === '') {
+        throw new CawdevError('This run has no card, so there is no Done-when list to tick.');
+      }
+      if (!Number.isInteger(args.item) || args.item < 1) {
+        throw new CawdevError('item must be a whole number from 1, as task_current lists them.');
+      }
+      const done = args.done !== false;
+      const row = await api(config, `/api/projects/${slug}/roadmap/${encodeURIComponent(String(ref))}/done-when/${args.item}/built`, {
+        method: 'PUT',
+        body: { done, note: args.note },
+      });
+      return (
+        `${done ? 'Ticked' : 'Unticked'} item ${row.position} of ${ref} in ${slug} as built: ` +
+        row.text
+      );
+    },
+  },
+
   {
     name: 'roadmap_create',
     description:
       'Create a roadmap entry. The platform allocates its permanent number — written R91 on ' +
       'a roadmap card and i91 on an issue, one sequence across both — and the ' +
-      'platform decides where a card starts — CONSIDERING — unless you say otherwise; ' +
-      'a status that requires something must be given it.',
+      'project decides where a card you file starts — the BACKLOG by default for a card an ' +
+      'agent files, waiting until a person or a sprint brings it in — unless you say ' +
+      'otherwise; a status that requires something must be given it. A card in the BACKLOG ' +
+      'holds no sprint: giving it one moves it to CONSIDERING.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -640,6 +698,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'IN_DEVELOPMENT',
@@ -692,6 +751,26 @@ const TOOLS = [
           description:
             'How much it matters; it does not reorder the board. Leave out for MEDIUM.',
         },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. A fact on the card; it moves nothing. Leave out for none.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 1,
+          description: "How big it is, in the team's own unit (points, days — the platform does not say). Leave out for none.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project DEFINED under Project settings → Versions (R362); any other name is refused. The release corrects it if it lands elsewhere. Leave out for none.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". One level only: the parent ' +
+            'must be the same kind and have no parent itself, and this card must have no ' +
+            'children. An open card cannot be filed under a SHIPPED or DECLINED one.',
+        },
       },
       required: ['title'],
     },
@@ -701,7 +780,7 @@ const TOOLS = [
         method: 'POST',
         body: pick(args, [
           'title', 'body', 'status', 'branch', 'merge', 'version', 'reason', 'section', 'related',
-          'after', 'sprint', 'tags', 'assignee', 'priority',
+          'after', 'sprint', 'tags', 'assignee', 'priority', 'due', 'estimate', 'targetVersion', 'parent',
         ]),
       });
       return `Created ${refOf(entry)} in ${slug}.\n\n${formatEntry(entry, {})}`;
@@ -713,7 +792,7 @@ const TOOLS = [
     description:
       'What is broken in a project, and how badly — R85. The same numbering as the roadmap, ' +
       'written with an i: card 91 filed as an issue is i91, and there is no R91 as well. ' +
-      'Statuses are NEW, CONFIRMED, IN_DEVELOPMENT, MERGED (drawn as ' +
+      'Statuses are BACKLOG, NEW, CONFIRMED, IN_DEVELOPMENT, MERGED (drawn as ' +
       'Resolved) and DECLINED (Won\'t fix).',
     inputSchema: {
       type: 'object',
@@ -721,7 +800,7 @@ const TOOLS = [
         ...PROJECT_ARGUMENT,
         status: {
           type: 'string',
-          enum: ['NEW', 'CONFIRMED', 'IN_DEVELOPMENT', 'MERGED', 'SHIPPED', 'DECLINED'],
+          enum: ['BACKLOG', 'NEW', 'CONFIRMED', 'IN_DEVELOPMENT', 'MERGED', 'SHIPPED', 'DECLINED'],
         },
         assignee: {
           type: 'string',
@@ -748,8 +827,10 @@ const TOOLS = [
   {
     name: 'issue_file',
     description:
-      'File an issue: something that is broken, with how badly. Lands at NEW — filed and not ' +
-      'yet triaged — unless you say CONFIRMED, which claims you have already checked it. The ' +
+      'File an issue: something that is broken, with how badly. Lands where the project says ' +
+      'for an issue an agent files — the BACKLOG by default, waiting to be brought in, or NEW ' +
+      '(filed and not yet triaged) — unless you say NEW, or CONFIRMED, which claims you have ' +
+      'already checked it. The ' +
       'severity is required: it is how the board is ordered. Use `related` to name the card it ' +
       'was found on, by ref (R84). Issues count on their own sequence — R221 — and are ' +
       'written with an i: i91 is the ninety-first issue, and R91 is another card.',
@@ -760,7 +841,7 @@ const TOOLS = [
         title: { type: 'string' },
         body: { type: 'string', description: 'Markdown. What happens, and what should instead.' },
         severity: { type: 'string', enum: ['CRITICAL', 'MEDIUM', 'MINOR'] },
-        status: { type: 'string', enum: ['NEW', 'CONFIRMED'] },
+        status: { type: 'string', enum: ['BACKLOG', 'NEW', 'CONFIRMED'] },
         related: {
           type: 'array',
           items: { type: ['string', 'integer'] },
@@ -813,14 +894,25 @@ const TOOLS = [
         kind: { type: 'string', enum: ['ISSUE', 'FEATURE'] },
         title: { type: 'string' },
         body: { type: 'string', description: 'Markdown. What you noticed, and what should happen instead.' },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Who it came from, beyond you — e.g. "customer" when you are passing on what a user ' +
+            'said. "agent" is always added: you filed it. Same word rule as card tags.',
+        },
       },
       required: ['kind', 'title', 'body'],
     },
     handler: async (config, args) => {
       const slug = await resolveProject(config, args.project);
+      // R372: feedback says who it came from, and an agent filing it is one
+      // of the sources. Added here, at the agent's own door, not by the API:
+      // an application's token files through the same endpoint and is not an agent.
+      const tags = [...new Set([...(Array.isArray(args.tags) ? args.tags : []), 'agent'])];
       const item = await api(config, `/api/projects/${slug}/backlog`, {
         method: 'POST',
-        body: pick(args, ['kind', 'title', 'body']),
+        body: { ...pick(args, ['kind', 'title', 'body']), tags },
       });
       return `Filed in ${slug}'s backlog as pending: "${item.title}". Somebody will accept it ` +
         'as a card or an issue, or refuse it.';
@@ -830,8 +922,8 @@ const TOOLS = [
   {
     name: 'roadmap_update',
     description:
-      'Edit an entry\'s title, body, section, sprint, tags, related refs or the cards it starts ' +
-      'after. Use roadmap_set_status to move it.',
+      'Edit an entry\'s title, body, section, sprint, tags, parent, related refs or the cards it ' +
+      'starts after. Use roadmap_set_status to move it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -882,6 +974,25 @@ const TOOLS = [
           description:
             'How much it matters; it does not reorder the board. Leave out for MEDIUM (leave out to leave it alone).',
         },
+        due: {
+          type: 'string',
+          description: 'When it is due, written 2026-11-01. Leave out to leave it alone; "" clears it.',
+        },
+        estimate: {
+          type: 'integer',
+          minimum: 0,
+          description: "How big it is, in the team's own unit. Leave out to leave it alone; 0 clears it.",
+        },
+        targetVersion: {
+          type: 'string',
+          description: 'The version it is meant to ship in — one the project defined (R362); any other name is refused. Leave out to leave it alone; "" clears it.',
+        },
+        parent: {
+          type: 'string',
+          description:
+            'The card this one sits under (an epic), e.g. "R300". "" takes the card out of its ' +
+            'parent; leave out to leave it alone. Same rules as roadmap_create.',
+        },
       },
       required: ['number'],
     },
@@ -890,7 +1001,10 @@ const TOOLS = [
       const entry = await api(config, `/api/projects/${slug}/roadmap/${args.number}`, {
         method: 'PATCH',
         // pick keeps a present 0, which is how a card leaves its sprint.
-        body: pick(args, ['title', 'body', 'section', 'related', 'after', 'sprint', 'tags', 'assignee', 'priority']),
+        body: pick(args, [
+          'title', 'body', 'section', 'related', 'after', 'sprint', 'tags', 'assignee', 'priority',
+          'due', 'estimate', 'targetVersion', 'parent',
+        ]),
       });
       return `Updated ${refOf(entry)}.\n\n${formatEntry(entry, {})}`;
     },
@@ -917,6 +1031,7 @@ const TOOLS = [
         status: {
           type: 'string',
           enum: [
+            'BACKLOG',
             'CONSIDERING',
             'PLANNED',
             'NEW',
@@ -1128,6 +1243,12 @@ const TOOLS = [
         config,
         `/api/projects/${project}/roadmap/${cardRef}/plans`,
       ).catch(() => []);
+      // R368. The plan's Done-when list, numbered, with the ticks so far. Its
+      // own try, like the plan above: a platform without it answers 404.
+      const criteria = await api(
+        config,
+        `/api/projects/${project}/roadmap/${cardRef}/done-when`,
+      ).catch(() => []);
 
       const lines = [];
 
@@ -1154,8 +1275,25 @@ const TOOLS = [
         `run:     ${run.state}${run.runnerName ? ` on ${run.runnerName}` : ''}`,
         `started by ${run.startedByEmail}`,
         '',
-        formatEntry(entry, { comments, plan: plans?.[0] ?? null }),
       );
+      // R336. The epic this card was cut from, so a session sees the context.
+      // Its own try, like the history above: a parent that cannot be read (a
+      // 404, no grant) costs the paragraph and never the call.
+      if (entry.parent) {
+        const epic = await api(config, `/api/projects/${project}/roadmap/${entry.parent.ref}`)
+          .catch(() => null);
+        if (epic) {
+          lines.push(
+            `This card is part of ${entry.parent.ref} — ${epic.title}:`,
+            epicExcerpt(epic.body),
+            '',
+          );
+        }
+      }
+      lines.push(formatEntry(entry, { comments, plan: plans?.[0] ?? null }));
+      if (criteria?.length) {
+        lines.push('', formatDoneWhen(criteria));
+      }
 
       // What happened the other times. A session is told the entry and the
       // branch but not that two previous runs on this card failed, which is
@@ -2173,6 +2311,15 @@ function originWord(origin) {
   }
 }
 
+/** The first 600 characters of an epic's body, cut at a word — R336. */
+function epicExcerpt(body) {
+  const text = (body ?? '').trim();
+  if (text.length <= 600) return text;
+  const cut = text.slice(0, 600);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > 0 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 function formatEntry(entry, { brief, comments, plan }) {
   const lines = [`${refOf(entry)} — ${entry.title}`, `  status: ${entry.statusDisplay}`];
   if (entry.branch) lines.push(`  branch: ${entry.branch}`);
@@ -2189,6 +2336,11 @@ function formatEntry(entry, { brief, comments, plan }) {
   if (entry.priority && entry.priority !== 'MEDIUM') {
     lines.push(`  priority: ${entry.priority}`);
   }
+  // R351. Both printed only when the card carries them, as the export does.
+  if (entry.due) lines.push(`  due: ${entry.due}`);
+  if (entry.estimate) lines.push(`  estimate: ${entry.estimate}`);
+  // R358. Printed until the card ships; `version` says where it did.
+  if (entry.targetVersion && !entry.version) lines.push(`  target: ${entry.targetVersion}`);
   // R257. Always printed when the card has one, so a reader's shape does not
   // depend on which tool printed the card; a closed sprint says so.
   if (entry.sprint) {
@@ -2214,6 +2366,14 @@ function formatEntry(entry, { brief, comments, plan }) {
         .join(', ')}`,
     );
   }
+  // R336. The epic this card sits under, and the cards under this one.
+  if (entry.parent) lines.push(`  parent: ${entry.parent.ref} — ${entry.parent.title}`);
+  if (entry.children?.length) {
+    const progress = entry.progress ? `${entry.progress.done} of ${entry.progress.total} done — ` : '';
+    lines.push(
+      `  children: ${progress}${entry.children.map((c) => `${c.ref} (${c.status})`).join(', ')}`,
+    );
+  }
   // Said in a survey, where the comments themselves are not fetched: an entry
   // with an argument attached should be visibly different from one without,
   // even in a list. Omitted at zero rather than written as "comments: 0".
@@ -2262,6 +2422,22 @@ function formatPlan(plan) {
   return [`--- the plan (${written}) ---`, plan.body].join('\n');
 }
 
+/**
+ * R368. The Done-when list as an agent reads it: numbered as done_when_tick
+ * takes them, with each tick and its evidence. A reviewer's confirmation is
+ * shown too — it is the other column, and the agent should see it.
+ */
+export function formatDoneWhen(criteria) {
+  const lines = ['--- done when (tick each with done_when_tick once you have checked it) ---'];
+  for (const item of criteria) {
+    const mark = item.built ? '[built]' : '[ ]';
+    const note = item.built && item.builtNote ? ` — ${item.builtNote}` : '';
+    const confirmed = item.confirmed ? ' (confirmed by reviewer)' : '';
+    lines.push(`${String(item.position).padStart(2)}. ${mark} ${item.text}${note}${confirmed}`);
+  }
+  return lines.join('\n');
+}
+
 /**
  * One earlier attempt at this card — R38.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.8-beta",
+  "version": "1.0.10-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -510,6 +510,22 @@ then ↑.
 **`/view`** opens the focused session's page on cawdev — transcript, stages,
 card — in the browser, on the console this terminal signed in to.
 
+**On a session waiting for you** — a question, or a permission such as a stage
+gate whose summary is the whole plan — the prompt only has room for the start
+of it, and says so: `/view reads it all · /open answers it on cawdev`.
+**`/view`** then opens the READER: one window over the whole screen with the
+session's output and, under a rule, the request in full (the question and its
+options; the permission's summary, its input and its keys). It opens on the
+request; `↑`/`↓` (and the wheel), `PgUp`/`PgDn`, `g`/`G` scroll it, `esc`
+closes it, and any other key closes it and does what it always does — `a`
+answers, `y`/`s`/`n` decide. Outside advanced mode `/view` prints the request
+whole into the scrollback. When the question has options its list opens by
+itself and hides the banner; the list's own key line says `/view reads it all`,
+and `/` there leaves the list for the command line (`a` brings it back).
+**`/open`** opens the session's run page on cawdev,
+where the question panel and the decision are. `readerFrame` in split.mjs is
+the window, pure.
+
 **`/view R29`** prints a card here instead: its status, section, tags, branch,
 work item and pull request, who is coding or reviewing it, what it is related
 to, its page on the web, and the first thirty lines of its body (`cardLines`,
@@ -607,6 +623,21 @@ the whole of removing it. A clone and not a `git worktree`, on purpose: the
 daemon's reset checks the default branch out, which git refuses in a second
 worktree. Changed without a restart, like `agentCommands`.
 
+### Where a session with no branch reads: `<first>-read`
+
+A plan, a verify or an ask cuts no branch and takes no checkout, so it used to
+run in the project's first checkout **as that checkout happened to be** — on
+whatever branch the last run left there. A cancelled CTO Interview left
+`cto-interview` checked out, hundreds of commits behind, and every plan after
+it read that code. Such a session now reads `<first>-read`, beside the first
+checkout: a **detached `git worktree`** of it, brought to `origin/<default
+branch>` at the start of a session whenever no other session is reading there.
+The checkout itself is never moved, because a coding run may be working in it.
+One per project rather than one per run, because the CLI keeps a resumable
+conversation by its folder. Detached, so the default branch is never checked
+out twice. If it cannot be made — no remote, not a repository — the session
+reads the first checkout as before, and the log says why.
+
 ### `/reload`
 
 Quitting and starting again, in one word — for when the client's code changed