cawdev-cli 1.1.0 → 1.1.1

package/lib/finish-check.mjs

@@ -18,6 +18,7 @@
 // finish that pushes a key is worse than one that leaves a file behind.
 
 import { execFile } from 'node:child_process';
+import { notAllowed, protectedChanges } from './protected.mjs';
 import { findSecret } from './secrets.mjs';
 
 /** The profiles whose run is a branch somebody will build on. */
@@ -109,8 +110,16 @@ export function notDoneYet(left) {
  * was), and `{ ok: false, reason }` otherwise, in words for the run's summary.
  * Never forces; a remote that has moved is a reason, not something to win.
  */
-export async function settleBranch(cwd, branch, { git = runGit, push, label = 'cawdev' } = {}) {
+export async function settleBranch(cwd, branch,
+  { git = runGit, push, label = 'cawdev', protected: policy = null } = {}) {
   const left = await leftOver(cwd, branch, { git });
+  // R562. Before the "nothing left" return: a protected change already
+  // committed and pushed (by a CLI that has no gate of its own) is exactly what
+  // this door exists to catch.
+  const held = left ? await heldProtected(cwd, policy) : [];
+  if (held.length) {
+    return { ok: false, reason: protectedHeld(held) };
+  }
   if (!left || !isUnfinished(left)) {
     return { ok: true, note: null };
   }
@@ -122,6 +131,10 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
     };
   }
 
+  // R562. The daemon has no session to ask, so a protected change nobody
+  // allowed fails the run (above, before anything is staged), held in the
+  // checkout. ASK fails too: Carry on, and the next `report done` asks.
+
   let committed = [];
   if (left.dirty.length) {
     await git(cwd, ['add', '-A']);
@@ -159,6 +172,10 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
         : null,
     };
   }
+  const heldNow = await heldProtected(cwd, policy);
+  if (heldNow.length) {
+    return { ok: false, reason: protectedHeld(heldNow) };
+  }
   const pushed = await push(cwd, branch);
   if (!pushed.ok) {
     return {
@@ -176,3 +193,19 @@ export async function settleBranch(cwd, branch, { git = runGit, push, label = 'c
       : `The daemon pushed ${branch}, which the session had committed and not pushed.`,
   };
 }
+
+/** The protected paths this checkout changes that nobody has allowed. */
+export async function heldProtected(cwd, policy) {
+  if (!policy?.globs?.length || !policy.base) {
+    return [];
+  }
+  const changed = await protectedChanges(cwd, policy.base, policy.globs);
+  return notAllowed(changed, policy.allowed ?? []);
+}
+
+/** The sentence for a protected change at a door with nobody to ask. */
+export function protectedHeld(paths) {
+  return `${named(paths)} ${paths.length === 1 ? 'is' : 'are'} protected in this project and `
+    + "were changed without a person's leave, so nothing was committed or pushed. The work is "
+    + 'held in the checkout.';
+}

package/lib/harness-prompt.mjs

@@ -105,6 +105,12 @@ export function harnessPrompt({
       + 'least one tool under the prefix, before this stage is finished.\n'
       + mustServers.map((each) => `- \`${each.prefix}__…\` — ${each.name}`).join('\n'));
   }
+  // R319. A server that knows when it is worth reaching for says so, required
+  // or not; one that does not still gets nothing.
+  const adviceFor = (mcpServers ?? []).filter((each) => each.when);
+  if (adviceFor.length) {
+    reach.push(adviceFor.map((each) => `- \`${each.prefix}__…\` (${each.name}): ${each.when}`).join('\n'));
+  }
   if (reach.length) {
     parts.push(`## What this session may reach\n\n${reach.join('\n\n')}`);
   }

package/lib/order.mjs

@@ -0,0 +1,7 @@
+// Code-unit order: what Array#sort does to strings by default and what Java's
+// String.compareTo does, said out loud. Never localeCompare here: ICU weighs
+// `-`, `.` and `_` differently, and an export must not churn (R315) nor a
+// refusal reorder its paths.
+export function byCodeUnit(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/lib/protected.mjs

@@ -0,0 +1,225 @@
+// Protected files — R562.
+//
+// A project lists globs an agent may not change. Three layers enforce it and
+// this is the part that does not depend on the CLI: `protectedChanges` compares
+// the branch with the commit it was cut from, so it catches an Edit, a shell
+// `git checkout main -- pom.xml`, a `git mv`, a `sed -i` and a build step alike,
+// on every CLI and on a machine set to allow everything.
+//
+// Zero dependencies, like the rest of tools/.
+
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { matches, normalise } from './secrets.mjs';
+import { byCodeUnit } from './order.mjs';
+
+/** The modes a project can choose. REFUSE is what an unreadable policy means. */
+export const MODES = ['REFUSE', 'ASK'];
+
+/**
+ * The policy out of a shield, whatever shape it arrived in.
+ *
+ * Unreadable or missing is REFUSE with no globs — never a way of allowing.
+ */
+export function protectedPolicy(shield) {
+  const globs = Array.isArray(shield?.protectedPaths)
+    ? shield.protectedPaths.filter((glob) => typeof glob === 'string' && glob.trim())
+      .map((glob) => glob.trim())
+    : [];
+  const mode = String(shield?.protectedMode ?? '').toUpperCase() === 'ASK' ? 'ASK' : 'REFUSE';
+  const allowed = Array.isArray(shield?.protectedAllowed)
+    ? shield.protectedAllowed.filter((path) => typeof path === 'string')
+    : [];
+  return { globs, mode, allowed };
+}
+
+/**
+ * Whether a path, absolute or relative to the checkout, is a protected one.
+ *
+ * A path that leaves the checkout is not protected here — it is the scope
+ * rule's business — and a symlink is followed when it exists, so a link into a
+ * protected directory is the directory.
+ */
+export function isProtected(path, root, globs) {
+  if (typeof path !== 'string' || !path || !Array.isArray(globs) || globs.length === 0) {
+    return false;
+  }
+  const base = normalise(root);
+  const candidates = [normalise(path.startsWith('/') ? path : `${base}/${path}`)];
+  const real = resolveReal(candidates[0]);
+  if (real && real !== candidates[0]) {
+    candidates.push(real);
+  }
+  let realBase = base;
+  try {
+    realBase = realpathSync(base);
+  } catch {
+    // The checkout is not there; the lexical answer stands.
+  }
+  return candidates.some((resolved) => {
+    for (const root of [base, realBase]) {
+      if (resolved === root || resolved.startsWith(`${root}/`)) {
+        const relative = resolved === root ? '' : resolved.slice(root.length + 1);
+        return globs.some((glob) => matchesHere(relative, glob.replace(/^\.\//, '')));
+      }
+    }
+    return false;
+  });
+}
+
+/**
+ * Whether a relative path is under a glob. On macOS and Windows the default
+ * volume is case-insensitive, so `POM.XML` IS `pom.xml` there; comparing
+ * without case protects a little more than a case-sensitive volume needs, which
+ * is the safe direction to be wrong in.
+ */
+function matchesHere(path, glob) {
+  return process.platform === 'darwin' || process.platform === 'win32'
+    ? matches(path.toLowerCase(), glob.toLowerCase())
+    : matches(path, glob);
+}
+
+/** The real path of the longest part that exists, with the rest appended. */
+function resolveReal(path) {
+  const parts = path.split('/');
+  for (let keep = parts.length; keep > 1; keep -= 1) {
+    const head = parts.slice(0, keep).join('/') || '/';
+    try {
+      const real = realpathSync(head);
+      return normalise([real, ...parts.slice(keep)].join('/'));
+    } catch {
+      // Not there yet; try the parent.
+    }
+  }
+  return null;
+}
+
+function runGit(cwd, args) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(stderr?.trim() || error.message));
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
+/**
+ * The protected paths this branch changes, sorted and unique.
+ *
+ * The committed diff against `base` (a diff, not a log, so a change later
+ * reverted does not count; `--no-renames`, so moving a protected file away is
+ * caught on its old path) plus the working tree. Empty when there is nothing to
+ * judge: no globs, or no base.
+ */
+export async function protectedChanges(cwd, base, globs, { git = runGit } = {}) {
+  if (!base || !Array.isArray(globs) || globs.length === 0) {
+    return [];
+  }
+  const touched = new Set();
+  // A git failure THROWS. An unreadable base (garbage-collected, a shallow
+  // clone) is not a reason to say the branch is clean: the callers turn a throw
+  // into a refusal, which is the direction this fails in.
+  const diff = await git(cwd, ['diff', '--name-only', '--no-renames', '-z', base, 'HEAD']);
+  for (const path of diff.split('\0')) {
+    if (path) {
+      touched.add(path);
+    }
+  }
+  const status = await git(cwd, ['status', '--porcelain', '-z', '--untracked-files=all']);
+  const entries = status.split('\0');
+  for (let at = 0; at < entries.length; at += 1) {
+    const entry = entries[at];
+    if (entry.length < 4) {
+      continue;
+    }
+    touched.add(entry.slice(3));
+    // A rename or copy carries the old path as the next field.
+    if (entry[0] === 'R' || entry[0] === 'C' || entry[1] === 'R' || entry[1] === 'C') {
+      at += 1;
+      if (entries[at]) {
+        touched.add(entries[at]);
+      }
+    }
+  }
+  return [...touched]
+    .filter((path) => globs.some((glob) => matchesHere(path, glob.replace(/^\.\//, ''))))
+    .sort(byCodeUnit);
+}
+
+/** The base a branch was cut from: the merge-base with its upstream, else the claim's commit. */
+export async function protectedBase(cwd, baseBranch, fallback, { git = runGit } = {}) {
+  if (baseBranch) {
+    for (const ref of [`origin/${baseBranch}`, baseBranch]) {
+      try {
+        const sha = (await git(cwd, ['merge-base', ref, 'HEAD'])).trim();
+        if (sha) {
+          return sha;
+        }
+      } catch {
+        // Try the next ref.
+      }
+    }
+  }
+  return fallback || null;
+}
+
+/** What is changed and not allowed. */
+export function notAllowed(changed, allowed = []) {
+  const leave = new Set(allowed);
+  return changed.filter((path) => !leave.has(path));
+}
+
+/** The sentence a refusal gives, shared by every door. */
+export function protectedRefusal(paths, base) {
+  const list = paths.join(', ');
+  return `Not finished — this branch changes protected file(s) the project never lets an agent `
+    + `change: ${list}. Restore them (git checkout ${base ? base.slice(0, 12) : '<base>'} -- `
+    + `<path>, or delete what you added), commit, push, and report done again.`;
+}
+
+/** The paragraph every prompt carries. Null when nothing is protected. */
+export function protectedLine(policy, already = []) {
+  const globs = policy?.globs ?? [];
+  if (!globs.length) {
+    return null;
+  }
+  const how = policy.mode === 'ASK'
+    ? 'Changing one stops and asks a person first, and an allowed change is marked on the card in '
+      + 'red; prefer a design that leaves them alone.'
+    : 'An agent never changes them — not with an edit, not with the shell, not with git; the run '
+      + 'cannot finish while the branch changes one.';
+  const lines = [
+    `**Protected files.** This project protects: ${globs.map((glob) => `\`${glob}\``).join(', ')}. `
+      + `${how} Check your plan against this list before you start.`,
+  ];
+  if (already.length) {
+    lines.push(`This branch already changes ${already.map((path) => `\`${path}\``).join(', ')}, `
+      + 'which are protected; deal with that first.');
+  }
+  return lines.join('\n\n');
+}
+
+/**
+ * Rules for the CLI's permission list, one per glob.
+ *
+ * Only `Edit(path)` is matched — Claude Code rejects `Write(path)` as "not
+ * matched by file permission checks" and applies Edit rules to every
+ * file-editing tool, NotebookEdit included (measured on 2.1.307; see
+ * `protectFiles` in the runner).
+ */
+export function denyRules(globs) {
+  return (globs ?? []).map((glob) => `Edit(./${glob.replace(/^\.\//, '')})`);
+}
+
+/** A path relative to the checkout, or null when it is outside it. */
+export function relativeTo(path, root) {
+  const base = normalise(root);
+  const resolved = normalise(String(path).startsWith('/') ? String(path) : `${base}/${path}`);
+  if (resolved === base) {
+    return '';
+  }
+  return resolved.startsWith(`${base}/`) ? resolved.slice(base.length + 1) : null;
+}

package/lib/roadmap-format.mjs

@@ -4,6 +4,8 @@
 // is not a fixed point and the generated file churns on every release. Keeping
 // both halves in one file is how they stay agreed.
 
+import { byCodeUnit } from './order.mjs';
+
 /**
  * What to call a card — R127 — and, since R221, what identifies one.
  *
@@ -506,7 +508,7 @@ function originWord(origin) {
     case 'SONARQUBE':
       return 'SonarQube';
     case 'FEEDBACK':
-      return 'Feedback';
+      return origin.label ? `Feedback (from ${origin.label})` : 'Feedback';
     case 'APPLICATION':
       return origin.label ? `An application (${origin.label})` : 'An application';
     case 'SESSION':
@@ -613,7 +615,7 @@ function renderEntry(entry) {
   }
   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(', ')}`);
+    lines.push(`Tags: ${[...entry.tags].sort(byCodeUnit).join(', ')}`);
   }
   if (entry.assignee?.username) {
     // R331. Nothing for a card with nobody, so today's files stay byte-identical.

package/lib/runner-config.mjs

@@ -25,6 +25,15 @@
  * Adding a key that IS captured would make the daemon claim it applied
  * something it did not, which is worse than saying restart.
  */
+/**
+ * R577: the name this machine registers under — the environment first, then the
+ * file, then a default. The daemon and the CLI both ask it, so `cawdev config
+ * planning-limit` finds the same machine the daemon registered.
+ */
+export function runnerNameOf(file, env = process.env) {
+  return env.CAWDEV_RUNNER_NAME ?? file?.name ?? 'this-machine';
+}
+
 export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole',
   'autoWorkspaces']);
 

package/lib/secrets.mjs

@@ -217,7 +217,7 @@ export function withinScope(path, root, scope = null) {
  * daemon's cwd is not the checkout. A silent dependence on where the daemon
  * happens to be standing is exactly the bug this function exists to not have.
  */
-function normalise(path) {
+export function normalise(path) {
   const absolute = path.startsWith('/');
   const out = [];
   for (const part of path.split('/')) {
@@ -244,7 +244,7 @@ function normalise(path) {
  * zero-dep constraint is what makes `tools/` a directory somebody can read
  * before running it against their repositories.
  */
-function matches(path, glob) {
+export function matches(path, glob) {
   if (typeof glob !== 'string' || !glob) {
     return false;
   }

package/lib/sonar-analysis.mjs

@@ -0,0 +1,52 @@
+// The SonarQube server side of a scan, shared by the runner daemon
+// (tools/runner/runner.mjs, scanQuality) and `sonar.sh` (tools/quality/scan.mjs):
+// the scanner's report-task.txt, a GET with the scanner's own token, and the wait
+// for the server's analysis task. One place, so the two cannot drift (R584).
+// Zero dependencies, like all of tools/.
+
+/** A GET against the SonarQube server a scan just reported to, authorised with the scanner's own token. */
+export function sonarAsker(serverUrl, token) {
+  return async (path) => {
+    const response = await fetch(`${serverUrl}${path}`, { headers: { authorization: `Bearer ${token}` } });
+    if (!response.ok) {
+      throw new Error(`SonarQube answered ${response.status} to ${path.split('?')[0]}`);
+    }
+    return response.json();
+  };
+}
+
+/**
+ * Waits for a queued analysis to settle — shared by every scan path, BRANCH,
+ * MAIN and PROJECT alike. Throws rather than reports: every caller runs
+ * inside `scanQuality`'s own try/catch, which turns it into an error reading.
+ */
+export async function waitForAnalysis(ask, ceTaskId, deadline, timeoutSeconds) {
+  let settled = null;
+  while (Date.now() < deadline) {
+    const { task: current } = await ask(`/api/ce/task?id=${encodeURIComponent(ceTaskId)}`);
+    if (['SUCCESS', 'FAILED', 'CANCELED'].includes(current?.status)) {
+      settled = current;
+      break;
+    }
+    await new Promise((wake) => setTimeout(wake, 3000));
+  }
+  if (!settled) {
+    throw new Error(`SonarQube had not finished analysing after ${timeoutSeconds}s.`);
+  }
+  if (settled.status !== 'SUCCESS') {
+    throw new Error(settled.errorMessage ?? `SonarQube ${settled.status.toLowerCase()} the analysis.`);
+  }
+  return settled;
+}
+
+/** `key=value` lines — the shape of the scanner's `report-task.txt`. */
+export function parseProperties(text) {
+  const parsed = {};
+  for (const line of text.split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) {
+      parsed[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+    }
+  }
+  return parsed;
+}

package/lib/sonarqube-mcp.mjs

@@ -0,0 +1,50 @@
+// R319. What the daemon adds to SonarSource's MCP server before it is spawned.
+//
+// The registry row says WHAT to run (`java -jar <file name>`); this says where
+// the jar is on this machine and under which credentials, because those are
+// facts about the machine and the platform must not hold them. Pure, so the
+// three refusals can be tested without a daemon.
+
+import { isAbsolute, join } from 'node:path';
+
+/** The directory, on this machine, that holds the jar the row names. */
+export const JAR_DIR_ENV = 'CAWDEV_SONARQUBE_MCP_DIR';
+
+const trimSlash = (text) => String(text).replace(/\/+$/, '');
+
+/**
+ * The arguments and environment to spawn the server with, or the sentence
+ * saying why it is not attached. Never throws.
+ *
+ * - the token is `process.env[quality.tokenEnv]` — the credential R300 already
+ *   holds — and is put in the SERVER's environment only;
+ * - the URL is the machine's override, else the project's connection, so a
+ *   project on another server gets that server;
+ * - a machine with no `quality` block for the project, no token, no URL or no
+ *   jar directory does not get the server, and is told which.
+ */
+export function sonarqubeLaunch({ skill, quality, sonarUrl, env, storagePath }) {
+  const name = skill.name ?? skill.key;
+  const dir = env[JAR_DIR_ENV];
+  if (!dir || !isAbsolute(dir)) {
+    return { skip: `${name} was not attached: set ${JAR_DIR_ENV} to the absolute directory that `
+      + `holds ${skill.args.find((arg) => String(arg).endsWith('.jar')) ?? 'the server jar'}.` };
+  }
+  if (!quality) {
+    return { skip: `${name} was not attached: this machine has no "quality" block for this `
+      + 'project, so it holds no scanner token for the server to use.' };
+  }
+  const token = env[quality.tokenEnv];
+  if (!token) {
+    return { skip: `${name} was not attached: $${quality.tokenEnv} is not set on this machine.` };
+  }
+  const url = quality.url ?? sonarUrl;
+  if (!url) {
+    return { skip: `${name} was not attached: neither the project's connection nor this machine's `
+      + 'quality block names a SonarQube server.' };
+  }
+  return {
+    args: skill.args.map((arg) => (String(arg).endsWith('.jar') && !isAbsolute(arg) ? join(dir, arg) : arg)),
+    env: { SONARQUBE_TOKEN: token, SONARQUBE_URL: trimSlash(url), STORAGE_PATH: storagePath },
+  };
+}

package/lib/stage-tools.mjs

@@ -22,6 +22,15 @@
  * named string behind one named option — rather than an entry in `CAWDEV_READS`,
  * which would hand a write to every read-only stage of every profile and call it
  * a read.
+ *
+ * The second exception — R572 — is {@link SUGGEST}, `backlog_file`, and every
+ * read-only stage keeps it. It files FEEDBACK: a pending item a person accepts or
+ * refuses. It changes no file, no card, no status and no discussion, so "cannot
+ * change anything" survives it in every sense the claim was ever about. It is
+ * here because the read-only stages are where a session reads the most code and
+ * notices the most that is not this card's, and the only place that left them to
+ * say so was a report nobody files from. Named for `CARD_WRITE`'s reason: a
+ * writer let through on purpose, not a writer renamed a read.
  */
 
 /** Reading git without being able to change it. */
@@ -98,6 +107,26 @@ export const CAWDEV_READS = new Set([
  */
 const STAGE_READS = new Set([...CAWDEV_READS].filter((name) => name !== 'report'));
 
+/**
+ * R319. SonarSource's server, judged by a NAMED list for the reason
+ * {@link CAWDEV_READS} is: shape is the worst signal available, and here it is
+ * wrong — `change_sonar_issue_status`, `toggle_automatic_analysis` and
+ * `create_webhook` are writers the loose end-of-name test below reads as reads.
+ * What is not on this list is a writer, including a tool a later version adds.
+ * Pinned in stage-tools.test.mjs against the tool list read at 1.29.0.
+ */
+export const SONARQUBE_READS = new Set([
+  'show_rule', 'list_languages', 'search_sonar_issues_in_projects',
+  'search_security_hotspots', 'show_security_hotspot', 'get_project_quality_gate_status',
+  'list_quality_gates', 'get_component_measures', 'search_metrics',
+  'search_my_sonarqube_projects', 'list_branches', 'list_pull_requests',
+  'get_raw_source', 'search_files_by_coverage', 'get_file_coverage_details',
+  'search_duplicated_files', 'get_duplications',
+]);
+
+/** The `mcp__sonarqube__` prefix, once. */
+const SONARQUBE = 'mcp__sonarqube__';
+
 /** The `mcp__cawdev__` prefix, once. */
 const CAWDEV = 'mcp__cawdev__';
 
@@ -114,6 +143,15 @@ const REPORT = `${CAWDEV}report`;
  */
 export const CARD_WRITE = `${CAWDEV}roadmap_create`;
 
+/**
+ * The platform write every read-only stage may hold — R572. See the header.
+ *
+ * <p>A stage still only holds it when the PROFILE handed it over: this lets it
+ * through the read-only filter, it never adds it. `canChangeThings` goes on
+ * calling it a writer, which is what keeps it an exception.
+ */
+export const SUGGEST = `${CAWDEV}backlog_file`;
+
 /**
  * Reads that only mean something once the work exists — R302.
  *
@@ -221,6 +259,14 @@ export function canChangeThings(tool) {
   if (tool.startsWith(CAWDEV)) {
     return !STAGE_READS.has(tool.slice(CAWDEV.length));
   }
+  // The bare server (`mcp__sonarqube`) is Claude Code's whole-server grant and
+  // covers the writers too, so it is one.
+  if (tool === SONARQUBE.slice(0, -2)) {
+    return true;
+  }
+  if (tool.startsWith(SONARQUBE)) {
+    return !SONARQUBE_READS.has(tool.slice(SONARQUBE.length));
+  }
   // Everybody else's MCP tools, where shape is all there is: one that writes
   // usually says so in its name. A guess, and acceptable only because the
   // alternative — treating every third-party MCP tool as a writer — would strip
@@ -302,7 +348,8 @@ export function toolsForStage(stage, profileTools, testMode, options = {}) {
   const readOnly = (keepsCardWrite) => [
     ...allowed.filter((tool) => !canChangeThings(tool)
       || (delegates && DELEGATES.test(tool))
-      || (keepsCardWrite && tool === CARD_WRITE)),
+      || (keepsCardWrite && tool === CARD_WRITE)
+      || tool === SUGGEST),
     ...GIT_READS.filter((tool) => allowed.includes(tool) || allowed.includes('Bash(git *)')),
   ];
   switch (stage) {
@@ -412,6 +459,10 @@ export function driftedFrom(stage, toolLine, testMode, readOnlyExperts = [], opt
   if (stage === 'PLAN' && options.writesItsOwnCard && name === CARD_WRITE) {
     return null;
   }
+  // R572. Filing a suggestion is the other write a read-only stage was given.
+  if (name === SUGGEST) {
+    return null;
+  }
   return `cawdev: the ${stage} stage called ${name}, which it should not have been able to. `
     + notice;
 }

package/mcp/README.md

@@ -67,7 +67,8 @@ The sequence is fixed, and the second step is the one people skip:
    "what is being worked on right now" without asking anyone.
 3. Build to the card's "Done when" list.
 4. Finish with a PR. Never push to `main`. As your session ends the platform
-   moves the *branch* on the development board, not the card: to `REVIEW` where
+   moves the *branch* on the development board, not the card: to `TEST` (the board
+   column, not the TEST stage of a run) where
    the project runs `require_review` and somebody is going to read it, and to
    `DONE` where it does not — a finish nobody was asked about (R132), because
    there is no reviewer coming.
@@ -79,9 +80,7 @@ The sequence is fixed, and the second step is the one people skip:
 `roadmap_statuses` will tell you, and it is worth reading rather than guessing:
 `IN_DEVELOPMENT` needs a branch, `MERGED` needs the merge — a pull request, a merge
 commit, or a sha — `SHIPPED` needs a version that is a real git tag, and
-`DECLINED` needs a reason. `REVIEW` needs nothing, deliberately: the pull
-request it would otherwise carry belongs to the run, and a project that reviews
-without opening pull requests has none to give it.
+`DECLINED` needs a reason.
 
 **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
@@ -190,12 +189,12 @@ what you are allowed to do.
 | `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 a card, 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). Tagged `agent` as a source, plus any `tags` you pass — `customer` when you relay what a user said (R372). |
+| `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). Inside a run, what you find that is **not this card's** goes here, one item per suggestion: the platform stamps the item with the run, so the feedback page links the run and its card, and accepting it relates the new card to yours (R572). Every stage holds it, read-only ones included. |
 | `changelog_list` | The changelog, grouped by release, newest first. |
 | `changelog_get` | One entry. |
 | `changelog_add` | Add an entry; no version means `Unreleased`. |
 | `changelog_update` | Edit one, including moving it to a release when it ships. |
-| `quality_get` | The SonarQube reading — the default branch's gate, a named branch's gate and new problems (inside a run, this run's branch by default), and the open findings with links. Read-only: nothing here refreshes, scans or files (R302). |
+| `quality_get` | The SonarQube reading — the default branch's gate, a named branch's gate and new problems (inside a run, this run's branch by default), and the open findings with links (not those a person dismissed, R467). Read-only: nothing here refreshes, scans or files (R302). |
 
 ### Inside a run