cawdev-cli 1.0.4-beta → 1.0.6-beta

package/lib/agents.mjs

@@ -0,0 +1,65 @@
+/**
+ * The coding agents a machine can spawn, spelled once.
+ *
+ * <p>Three CLIs, each a command on the PATH: Claude Code, Antigravity and
+ * Codex. The setup walk, `cawdev config agent`, the config screen and the
+ * daemon all ask "which agent is this command" and "what is it called", and
+ * the answer was a `=== 'agy' ? … : 'Claude Code'` in five places — right for
+ * two agents and silently wrong for a third.
+ */
+
+/** Every agent, in the order they are offered. */
+export const KNOWN_AGENTS = ['claude', 'agy', 'codex'];
+
+const LABELS = { claude: 'Claude Code', agy: 'Antigravity CLI', codex: 'Codex CLI' };
+
+/** Which agent a configured command is — by its name, the rule `agentCommands` always used. */
+export function agentOfCommand(command) {
+  const name = String(command ?? '').split('/').pop();
+  if (name.endsWith('agy')) return 'agy';
+  if (name.endsWith('codex')) return 'codex';
+  return 'claude';
+}
+
+/** What a person calls the agent behind a command. */
+export function agentLabel(command) {
+  return LABELS[agentOfCommand(command)];
+}
+
+/**
+ * Why an agent that needs the whole machine was refused, and what to do about
+ * it — in steps, for THIS machine. Codex and Antigravity have no per-command
+ * allow-list, so a session that writes can only run with everything allowed;
+ * the refusal used to say "turn on allow everything" and nothing about where,
+ * or that the machine must first agree to take rules from the console.
+ *
+ * Pure, so the wording is read in a test rather than found in a failed run.
+ *
+ * @param agent `codex` or `agy`
+ * @param machine `{ name, acceptsConsoleRules, configPath, consoleUrl }`
+ * @param run `{ entryRef, profile }` — what to start again, and how
+ * @param readsWithout whether a read-only session of this agent needs nothing
+ */
+export function needsEverything(agent, machine = {}, run = {}, { readsWithout = true } = {}) {
+  const who = LABELS[agent] ?? agent;
+  const short = agent === 'agy' ? 'agy' : agent;
+  const again = run.entryRef ? `/new ${run.profile === 'PLAN' ? 'plan' : 'dev'} ${run.entryRef}` : '/new …';
+  const lines = [
+    `${who} cannot ${readsWithout ? 'write code' : 'run'} on this machine yet: it has no per-command `
+      + 'permissions, so a session that commits and pushes must be allowed to run anything — and '
+      + 'this machine has not allowed everything.',
+    '',
+    'To allow it:',
+    machine.acceptsConsoleRules
+      ? '  1. ✓ This machine already accepts permission rules from the console.'
+      : '  1. On this machine: in the cawdev terminal press c → "Accept permission rules from the '
+        + `console"${machine.configPath ? ` (or "acceptsRulesFromConsole": true in ${machine.configPath})` : ''}.`,
+    `  2. On cawdev: ${machine.consoleUrl ? `${machine.consoleUrl.replace(/\/+$/, '')}/settings/runners` : 'Settings → Runners'}`
+      + ` → ${machine.name ?? 'this machine'} → tick "Allow everything".`,
+    `  3. Start it again: ${again} --${short}`,
+    '',
+    'Allowing everything lets every unattended session on this machine run any command in its checkouts.',
+    `Or, without it: ${again} --claude${readsWithout && agent === 'codex' && run.entryRef ? ` — or keep ${who} for plans (/new plan ${run.entryRef} --codex)` : ''}.`,
+  ];
+  return lines.join('\n');
+}

package/lib/ansi.mjs

@@ -102,6 +102,8 @@ export function painter(depth = colourDepth()) {
     text: ink([0xd4, 0xd0, 0xcc], 37),
 
     bold: wrap('\x1b[1m'),
+    /** Bold AND underlined — a fact the eye should find first (advanced mode's agent · model). */
+    strong: wrap('\x1b[1;4m'),
     dim: wrap('\x1b[2m'),
     reverse: wrap('\x1b[7m'),
     /** Plain, for a value that should not compete with the label beside it. */

package/lib/background-shells.mjs

@@ -0,0 +1,108 @@
+/**
+ * The shell commands a Claude Code session started in the BACKGROUND and never
+ * saw the end of — read off its stream-json events.
+ *
+ * A lifecycle stage is one turn (R112): the daemon closes the session the
+ * moment the turn ends. A stage that ran `npm test` with `run_in_background`
+ * and ended its turn to wait for it loses the run — the result never comes
+ * back, nothing is recorded, and the walk marched on to MEMORY and FINISHED
+ * with the work unproven and uncommitted (R15, saasng). So the walk asks this,
+ * at the stage's end, whether anything it started is unfinished or unread;
+ * `walkLifecycle` then fails the stage instead of calling it done, which is
+ * what lets `/continue` pick the run back up at that stage.
+ *
+ * Pure: events in, a list out. Three tool shapes, by name:
+ * - `Bash` with `run_in_background: true` starts one; its result names the id
+ *   ("… running in background with ID: <id>");
+ * - `BashOutput` (or `TaskOutput`) reads one by `bash_id`/`shell_id`/`task_id`;
+ *   the command is over only when a read says a status other than running;
+ * - `KillShell`/`KillBash`/`TaskStop` ends one.
+ * A command whose id cannot be read off its result stays unfinished: failing
+ * loudly and re-running a stage costs a turn, calling unproven work proven
+ * costs somebody's afternoon.
+ *
+ * @author Claude Opus 5.5 (Claude Code)
+ * @author Moez Ben MBarka
+ */
+
+const READS = new Set(['BashOutput', 'TaskOutput']);
+const KILLS = new Set(['KillShell', 'KillBash', 'TaskStop']);
+
+/** The text of a tool_result's content, whichever of its two shapes it came in. */
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => (typeof part?.text === 'string' ? part.text : '')).join('\n');
+  }
+  return '';
+}
+
+function shellIdOf(input) {
+  const id = input?.bash_id ?? input?.shell_id ?? input?.task_id ?? input?.id;
+  return typeof id === 'string' && id ? id : null;
+}
+
+export class BackgroundShells {
+  constructor() {
+    /** tool_use id of each background `Bash` → { command, shellId, done }. */
+    this.started = new Map();
+    /** tool_use id of each read → the shell id it read. */
+    this.reads = new Map();
+  }
+
+  /** One stream-json event. Anything that is not about a shell is ignored. */
+  observe(event) {
+    const parts = event?.message?.content;
+    if (!Array.isArray(parts)) return;
+    if (event.type === 'assistant') {
+      for (const part of parts) {
+        if (part?.type !== 'tool_use') continue;
+        if (part.name === 'Bash' && part.input?.run_in_background === true) {
+          this.started.set(part.id, {
+            command: String(part.input.command ?? '').trim(),
+            shellId: null,
+            done: false,
+          });
+        } else if (READS.has(part.name)) {
+          const id = shellIdOf(part.input);
+          if (id) this.reads.set(part.id, id);
+        } else if (KILLS.has(part.name)) {
+          this.finish(shellIdOf(part.input));
+        }
+      }
+      return;
+    }
+    if (event.type === 'user') {
+      for (const part of parts) {
+        if (part?.type !== 'tool_result') continue;
+        const text = textOf(part.content);
+        const launched = this.started.get(part.tool_use_id);
+        if (launched && !launched.shellId) {
+          const id = /\bID:?\s*([A-Za-z0-9_-]+)/.exec(text);
+          if (id) launched.shellId = id[1];
+          continue;
+        }
+        const read = this.reads.get(part.tool_use_id);
+        if (read) {
+          // Over only when the read says so; a read of a command still going
+          // is the command still going.
+          if (!/<status>\s*running\s*<\/status>|\bstatus:\s*running\b/i.test(text)) {
+            this.finish(read);
+          }
+        }
+      }
+    }
+  }
+
+  finish(shellId) {
+    if (!shellId) return;
+    for (const each of this.started.values()) {
+      if (each.shellId === shellId) each.done = true;
+    }
+  }
+
+  /** The commands started in the background whose end this session never saw. */
+  unfinished() {
+    return [...this.started.values()].filter((each) => !each.done).map((each) => each.command);
+  }
+}

package/lib/codex.mjs

@@ -0,0 +1,219 @@
+/**
+ * OpenAI's Codex CLI as a third agent — the arguments a spawn is given and the
+ * events it prints, and nothing that touches a process.
+ *
+ * In lib/ for `code-map.mjs`'s reason: the hard parts are a command line and a
+ * stream, both testable without a daemon, a platform or a model. The spawn
+ * itself is `spawnCodex` in runner.mjs, beside `spawnAntigravity`.
+ *
+ * <p>Every flag and field here was checked against the real CLI (0.155) by
+ * hand rather than read off documentation:
+ *
+ * <ul>
+ * <li>`codex exec --json` prints JSONL: `thread.started` (carries the id
+ *   `resume` takes), `item.started`/`item.completed` for `agent_message`,
+ *   `command_execution`, `mcp_tool_call`, `file_change`…, then
+ *   `turn.completed` with `usage` or `turn.failed` with `error`.
+ * <li>In `exec` the approval policy is NEVER, so an MCP call is refused
+ *   outright ("requires approval, but approval policy is never") unless its
+ *   server says `default_tools_approval_mode = "approve"`. With it, cawdev's
+ *   own server is reached even under `--sandbox read-only`, network included:
+ *   the sandbox is the SHELL's, not the MCP servers'.
+ * <li>`enabled_tools` really narrows a server — a tool left out is not offered
+ *   at all — and `disabled_tools` takes one away.
+ * <li>`env_vars` forwards named variables from Codex's own environment to a
+ *   server, which keeps the run's token off the command line, where `ps`
+ *   would show it to anybody on the machine.
+ * <li>`shell_environment_policy.set` blanks a variable for every command the
+ *   model runs — and `exclude` does NOT (tried: `echo $CAWDEV_TOKEN` still
+ *   printed it). The token reaches cawdev's server through `env_vars`, which
+ *   reads Codex's own environment and not the shell's, so blanking it for the
+ *   shell costs the server nothing.
+ * <li>`resume` takes the exec-level options BEFORE the subcommand:
+ *   `codex exec --json -s read-only resume <id> -`; after it, `-s` is refused.
+ * <li>`--strict-config` refuses a field it does not know, so a key misspelled
+ *   here fails the spawn out loud instead of being ignored.
+ * </ul>
+ */
+
+/** The `mcp__cawdev__` prefix off a Claude Code tool list, keeping cawdev's own names only. */
+export function cawdevToolNames(tools) {
+  const prefix = 'mcp__cawdev__';
+  return [...new Set((Array.isArray(tools) ? tools : [])
+    .filter((tool) => typeof tool === 'string' && tool.startsWith(prefix))
+    .map((tool) => tool.slice(prefix.length)))];
+}
+
+/**
+ * A value as TOML, which is what `-c key=value` parses.
+ *
+ * <p>A JSON string is a TOML basic string for everything JSON escapes; DEL is
+ * the one control character JSON leaves alone and TOML refuses.
+ */
+export function tomlValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(tomlValue).join(', ')}]`;
+  }
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(([key, each]) => `${tomlKey(key)} = ${tomlValue(each)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  return JSON.stringify(String(value ?? '')).replace(/\u007f/g, '\\u007f');
+}
+
+function tomlKey(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlValue(String(key));
+}
+
+/**
+ * The command line for one Codex turn. The prompt goes on stdin (`-`).
+ *
+ * @param options.sandbox `read-only` — the OS refuses every write the shell
+ *   attempts — or `bypass`, which is `--dangerously-bypass-approvals-and-sandbox`
+ *   and is only ever passed where the machine has allowed everything.
+ * @param options.servers `[{ name, command, args, env, envVars, enabledTools,
+ *   disabledTools }]`, each approved, since nobody is there to approve a call.
+ * @param options.hideFromShell variables blanked for the model's own commands.
+ */
+export function codexArgs({
+  model = null, effort = null, sandbox, resumeId = null, servers = [], hideFromShell = [],
+}) {
+  if (sandbox !== 'read-only' && sandbox !== 'bypass') {
+    throw new Error(`codexArgs: sandbox must be read-only or bypass, not ${sandbox}`);
+  }
+  // `--ignore-user-config` is `--setting-sources ''` for this CLI: the
+  // operator's own ~/.codex/config.toml can add MCP servers, hooks and an
+  // approval reviewer, and none of that may widen what a run was given. The
+  // sign-in is untouched — it is read from CODEX_HOME either way.
+  const args = ['exec', '--json', '--strict-config', '--ignore-user-config'];
+  args.push(...(sandbox === 'bypass'
+    ? ['--dangerously-bypass-approvals-and-sandbox']
+    : ['--sandbox', 'read-only']));
+  if (model) {
+    args.push('--model', model);
+  }
+  if (effort) {
+    args.push('-c', `model_reasoning_effort=${tomlValue(effort)}`);
+  }
+  if (hideFromShell.length) {
+    args.push('-c', `shell_environment_policy.set=${tomlValue(
+      Object.fromEntries(hideFromShell.map((name) => [name, ''])))}`);
+  }
+  for (const server of servers) {
+    const key = `mcp_servers.${tomlKey(server.name)}`;
+    args.push('-c', `${key}.command=${tomlValue(server.command)}`);
+    if (server.args?.length) {
+      args.push('-c', `${key}.args=${tomlValue(server.args)}`);
+    }
+    if (server.env && Object.keys(server.env).length) {
+      args.push('-c', `${key}.env=${tomlValue(server.env)}`);
+    }
+    if (server.envVars?.length) {
+      args.push('-c', `${key}.env_vars=${tomlValue(server.envVars)}`);
+    }
+    if (server.enabledTools) {
+      args.push('-c', `${key}.enabled_tools=${tomlValue(server.enabledTools)}`);
+    }
+    if (server.disabledTools?.length) {
+      args.push('-c', `${key}.disabled_tools=${tomlValue(server.disabledTools)}`);
+    }
+    // How long one call may take before Codex gives up on it — 60 s unless
+    // set, which is shorter than a person answering a question.
+    if (server.toolTimeoutSec) {
+      args.push('-c', `${key}.tool_timeout_sec=${tomlValue(server.toolTimeoutSec)}`);
+    }
+    args.push('-c', `${key}.default_tools_approval_mode="approve"`);
+  }
+  if (resumeId) {
+    args.push('resume', resumeId);
+  }
+  args.push('-');
+  return args;
+}
+
+/** A tool result's text, whatever shape the MCP server gave it. */
+function resultText(result) {
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    const text = content.map((each) => each?.text ?? '').filter(Boolean).join('\n');
+    if (text) return text;
+  }
+  return result == null ? '(no output)' : JSON.stringify(result);
+}
+
+/**
+ * One line of `codex exec --json`, as what the transcript and the run need.
+ *
+ * <p>Returns `{ sessionId?, lines: [{ kind, body }], usage?, failed?, error?, ended? }`.
+ * `ended` is true on `turn.completed` — the turn ending, which is the whole of
+ * what a stage is judged by. `failed` is `turn.failed`'s sentence; `error` a
+ * top-level error's, which may be passing. An event this version does not know
+ * yields nothing.
+ */
+export function translateCodexEvent(event) {
+  const out = { lines: [] };
+  const item = event?.item ?? {};
+  switch (event?.type) {
+    case 'thread.started':
+      out.sessionId = event.thread_id ?? null;
+      break;
+    case 'item.started':
+      if (item.type === 'command_execution') {
+        out.lines.push({ kind: 'TOOL', body: `Bash(${item.command ?? ''})` });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL',
+          body: `mcp__${item.server}__${item.tool}(${JSON.stringify(item.arguments ?? {})})`,
+        });
+      }
+      break;
+    case 'item.completed':
+      if (item.type === 'agent_message' && item.text) {
+        out.lines.push({ kind: 'ASSISTANT', body: item.text });
+      } else if (item.type === 'command_execution') {
+        const output = String(item.aggregated_output ?? '').slice(0, 4000);
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: output || `(exit ${item.exit_code ?? '?'})`,
+        });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: item.error
+            ? `failed: ${item.error.message ?? JSON.stringify(item.error)}`
+            : resultText(item.result).slice(0, 4000),
+        });
+      } else if (item.type === 'file_change') {
+        const changes = (item.changes ?? [])
+          .map((each) => `${each.kind ?? 'update'} ${each.path ?? ''}`.trim());
+        out.lines.push({ kind: 'TOOL', body: `Edit(${changes.join(', ') || 'files'})` });
+      } else if (item.type === 'error' && item.message) {
+        out.lines.push({ kind: 'SYSTEM', body: item.message });
+      }
+      break;
+    case 'turn.completed':
+      out.ended = true;
+      out.usage = {
+        input: Number(event.usage?.input_tokens) || 0,
+        output: Number(event.usage?.output_tokens) || 0,
+      };
+      break;
+    case 'turn.failed':
+      out.failed = event.error?.message ?? 'Codex reported the turn failed.';
+      out.lines.push({ kind: 'SYSTEM', body: out.failed });
+      break;
+    case 'error':
+      // NOT `failed`: a top-level error is also how a retried stream says
+      // "Reconnecting… 2/5". Only `turn.failed` ends a turn badly; this is
+      // kept as the last thing it said, for when nothing better arrives.
+      out.error = event.message ?? 'Codex reported an error.';
+      out.lines.push({ kind: 'SYSTEM', body: out.error });
+      break;
+    default:
+      break;
+  }
+  return out;
+}

package/lib/harness-prompt.mjs

@@ -48,10 +48,13 @@ export function harnessPrompt({
   //
   // R161. A REQUIRED one is named FIRST and in its own block. Two lists rather
   // than one annotated list, because a `(required)` suffix on a line in a list
-  // of twelve is a detail; a heading is an instruction. The AS_NEEDED wording
-  // below is byte-for-byte what it was — when a project requires nothing, and
-  // that is every project until somebody says otherwise, this function returns
-  // exactly what it returned before the entry.
+  // of twelve is a detail; a heading is an instruction. When a project
+  // requires nothing at all — every project until somebody says otherwise —
+  // this function still returns exactly what it returned before the entry:
+  // the AS_NEEDED wording below has since been extended once, by i257, but a
+  // project with no `mustExperts`/`mustSkills`/`mustServers` never reaches
+  // either block, so the claim is about that project, not about the wording
+  // itself staying fixed forever.
   const reach = [];
   const requiredOf = (list) => (list ?? []).filter((each) => each.required);
   const optionalOf = (list) => (list ?? []).filter((each) => !each.required);
@@ -63,12 +66,17 @@ export function harnessPrompt({
   if (mustExperts.length) {
     reach.push('**Experts you MUST use** — this project requires each of these. Delegate '
       + 'with the `Agent` tool, `subagent_type` exactly as written, before this stage is '
-      + `finished.\n${lines(mustExperts)}`);
+      + 'finished. This stage is one process and ends when your turn does: a backgrounded '
+      + '`Agent` call that has not reported back by then is lost, and so is anything gated on '
+      + 'it. Pass `run_in_background: false` and wait for each of these in the same turn — do '
+      + 'not say "I\'ll report back" and stop.\n'
+      + `${lines(mustExperts)}`);
   }
   if (mayExperts.length) {
     reach.push('**Experts** — delegate with the `Agent` tool, `subagent_type` exactly as '
       + 'written. Use one whenever its description fits the step you are on; they were '
-      + 'chosen for this project.\n'
+      + 'chosen for this project. The same rule applies: a call backgrounded past the end of '
+      + 'your turn never comes back.\n'
       + lines(mayExperts));
   } else if (!mustExperts.length && cannotDelegate?.length) {
     reach.push(`**Experts** — ${cannotDelegate.join(' ')}`);

package/lib/roadmap-format.mjs

@@ -255,6 +255,23 @@ export function parseRoadmap(text) {
         entry.afterRefs = tokens.map(({ ref }) => ref);
         continue;
       }
+      const tags = /^Tags:\s*(.+)$/.exec(line.trim());
+      if (tags) {
+        // R315. Already normalised by the server (lowercase, no `#`) by the
+        // time it reaches the file, so a plain split is the whole rule.
+        entry.tags = tags[1].split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
+        continue;
+      }
+      // R315. Computed, never stored, and never sent by import.mjs — the same
+      // arrangement as `Development:` above. Kept as the exact text so a file
+      // parsed and re-rendered without asking the API again is still a fixed
+      // point; `renderEntry` recomputes the same text from a live `origin`
+      // object when there is one.
+      const origin = /^Origin:\s*(.+)$/.exec(line.trim());
+      if (origin) {
+        entry.origin = origin[1].trim();
+        continue;
+      }
       const sprint = /^Sprint:\s*S(\d+)\s*(.*)$/.exec(line.trim());
       if (sprint) {
         // R257: `Sprint: S1 Notifications` — the sprint's number and its name
@@ -360,6 +377,33 @@ export function renderRoadmap(entries, { preamble, sectionOrder = [] }) {
   return parts.join('\n').replace(/\n+$/, '') + '\n';
 }
 
+/**
+ * The word `Origin:` writes — R315. `entry.origin` is a plain string once it
+ * has round-tripped through the file (see the parser above); freshly off the
+ * API it is `{kind, label, url}`, and this is the one place that turns the
+ * second into the first, so the two paths render identically.
+ */
+function originWord(origin) {
+  if (typeof origin === 'string') {
+    return origin;
+  }
+  if (!origin || origin.kind === 'NONE') {
+    return null;
+  }
+  switch (origin.kind) {
+    case 'SONARQUBE':
+      return 'SonarQube';
+    case 'FEEDBACK':
+      return 'Feedback';
+    case 'APPLICATION':
+      return origin.label ? `An application (${origin.label})` : 'An application';
+    case 'SESSION':
+      return origin.label ? `A session (${origin.label})` : 'A session';
+    default:
+      return null;
+  }
+}
+
 function renderEntry(entry) {
   const lines = [`### ${entryRef(entry)} — ${entry.title}`, ''];
 
@@ -425,6 +469,14 @@ function renderEntry(entry) {
       .map(({ ref }) => ref);
     lines.push(`After: ${written.join(', ')}`);
   }
+  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(', ')}`);
+  }
+  const origin = originWord(entry.origin);
+  if (origin) {
+    lines.push(`Origin: ${origin}`);
+  }
   if (entry.sprint) {
     // R257. A line on the card and never a heading: the section is where the
     // file groups, and a sprint is a set a person opened across sections. The

package/lib/runner-config.mjs

@@ -25,7 +25,8 @@
  * Adding a key that IS captured would make the daemon claim it applied
  * something it did not, which is worse than saying restart.
  */
-export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole']);
+export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole',
+  'autoWorkspaces']);
 
 /**
  * The legacy spelling of one key, read as the current one — so a config that
@@ -60,7 +61,7 @@ export function restartNeededFor(booted, file) {
   return [...keys]
     .filter((key) => !HOT_SWAPPABLE.includes(key))
     .filter((key) => canonical(before[key]) !== canonical(after[key]))
-    .sort();
+    .sort((a, b) => a.localeCompare(b));
 }
 
 /** Applied, or would be on a SIGHUP: the hot-swappable keys that differ. */

package/mcp/server.mjs

@@ -665,6 +665,13 @@ const TOOLS = [
             'Cards this one starts coding after — it waits in the queue until every one of ' +
             'them is MERGED or SHIPPED. Refs, as `related`. Same project, must exist, never itself.',
         },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Free words — lowercase, letters/digits/./_/-, up to 32 characters, at least one ' +
+            'letter, at most 12. The leading # is optional and stripped.',
+        },
       },
       required: ['title'],
     },
@@ -674,7 +681,7 @@ const TOOLS = [
         method: 'POST',
         body: pick(args, [
           'title', 'body', 'status', 'branch', 'merge', 'version', 'reason', 'section', 'related',
-          'after', 'sprint',
+          'after', 'sprint', 'tags',
         ]),
       });
       return `Created ${refOf(entry)} in ${slug}.\n\n${formatEntry(entry, {})}`;
@@ -734,6 +741,13 @@ const TOOLS = [
           items: { type: ['string', 'integer'] },
           description: 'Refs — R12, i15; a bare number is a roadmap card (R221).',
         },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Free words — lowercase, letters/digits/./_/-, up to 32 characters, at least one ' +
+            'letter, at most 12. The leading # is optional and stripped.',
+        },
       },
       required: ['title', 'severity'],
     },
@@ -741,7 +755,7 @@ const TOOLS = [
       const slug = await resolveProject(config, args.project);
       const issue = await api(config, `/api/projects/${slug}/issues`, {
         method: 'POST',
-        body: pick(args, ['title', 'body', 'severity', 'status', 'related']),
+        body: pick(args, ['title', 'body', 'severity', 'status', 'related', 'tags']),
       });
       return `Filed ${refOf(issue)} in ${slug}.\n\n${formatEntry(issue, {})}`;
     },
@@ -779,7 +793,7 @@ const TOOLS = [
   {
     name: 'roadmap_update',
     description:
-      'Edit an entry\'s title, body, section, sprint, related refs or the cards it starts ' +
+      'Edit an entry\'s title, body, section, sprint, tags, related refs or the cards it starts ' +
       'after. Use roadmap_set_status to move it.',
     inputSchema: {
       type: 'object',
@@ -813,6 +827,12 @@ const TOOLS = [
             'them is MERGED or SHIPPED. Refs, as `related`. Same project, must exist, never ' +
             'itself. [] clears it.',
         },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Free words — same rule as roadmap_create. Leave out to leave them alone; [] clears them.',
+        },
       },
       required: ['number'],
     },
@@ -821,7 +841,7 @@ 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']),
+        body: pick(args, ['title', 'body', 'section', 'related', 'after', 'sprint', 'tags']),
       });
       return `Updated ${refOf(entry)}.\n\n${formatEntry(entry, {})}`;
     },
@@ -2011,6 +2031,9 @@ function formatQualityReading(reading, branch) {
         `new coverage ${percent(row.newCoverage)}`,
       ];
       if (row.analysedAs === 'MAIN') parts.push('analysed as the main branch, not under its own name');
+      if (row.analysedAs === 'PROJECT') {
+        parts.push('analysed as its own SonarQube project; new = on lines this branch changed; no gate');
+      }
       if (row.headSha) parts.push(`at ${row.headSha.slice(0, 7)}`);
       if (row.dashboardUrl) parts.push(row.dashboardUrl);
       lines.push(`Branch ${asked.branch}: ${parts.join(' · ')}`);
@@ -2062,6 +2085,23 @@ function refOf(entry) {
   return entry.ref ?? ((entry.kind === 'ISSUE' ? 'i' : 'R') + entry.number);
 }
 
+/**
+ * The word `formatEntry` prints for a card's origin — R315. Never stored,
+ * always the object shape `{kind, label, url}` off the API — unlike
+ * `roadmap-format.mjs`'s own copy, which also has to read one back out of a
+ * file.
+ */
+function originWord(origin) {
+  if (!origin || origin.kind === 'NONE') return null;
+  switch (origin.kind) {
+    case 'SONARQUBE': return 'SonarQube';
+    case 'FEEDBACK': return 'Feedback';
+    case 'APPLICATION': return origin.label ? `an application (${origin.label})` : 'an application';
+    case 'SESSION': return origin.label ? `a session (${origin.label})` : 'a session';
+    default: return null;
+  }
+}
+
 function formatEntry(entry, { brief, comments, plan }) {
   const lines = [`${refOf(entry)} — ${entry.title}`, `  status: ${entry.statusDisplay}`];
   if (entry.branch) lines.push(`  branch: ${entry.branch}`);
@@ -2069,6 +2109,9 @@ function formatEntry(entry, { brief, comments, plan }) {
   if (entry.version) lines.push(`  version: ${entry.version}`);
   if (entry.declinedReason) lines.push(`  declined because: ${entry.declinedReason}`);
   if (entry.section) lines.push(`  section: ${entry.section}`);
+  // R315. Sorted for the same reason the export is: a reader's shape must not
+  // depend on the set's own insertion order.
+  if (entry.tags?.length) lines.push(`  tags: ${[...entry.tags].sort().map((t) => `#${t}`).join(' ')}`);
   // 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) {
@@ -2105,6 +2148,12 @@ function formatEntry(entry, { brief, comments, plan }) {
     lines.push(`  written by: a ${entry.createdBy.profile} session, `
       + `under ${entry.createdBy.startedByEmail}`);
   }
+  // R315. Never null on the wire — NONE is a person at the console — so only
+  // ever printed when it says something. Beside `written by` rather than
+  // instead of it: origin says the DOOR, and the session line above already
+  // says who and what kind, when the door was a session.
+  const origin = originWord(entry.origin);
+  if (origin) lines.push(`  origin: ${origin}`);
   if (!brief && entry.body) lines.push('', entry.body);
   // R124, between the body and the discussion — the order they are read in:
   // what we want, how we mean to get it, and the argument about both.

package/package.json

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