cortad 0.3.0-rc.2 → 0.3.0-rc.3

package/lib/cli.mjs

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homeOf, projectOf, readPending, readRunner, readToken, writePending, writeRunner } from "./home.mjs";
 import { serveMcp } from "./mcp.mjs";
+import { SHOW } from "./read-text.mjs";
 import { cliSpec, VERSION } from "./spec.mjs";
 import { hookOutput, stick, unstick } from "./stick.mjs";
 import { makeVerbs, READY_MS } from "./verbs.mjs";
@@ -62,13 +63,17 @@ export async function main(argv, { root = process.cwd(), env = process.env, stdo
   return out.isError ? 1 : 0;
 }
 
-// Positional arguments for the shell face: `verify f1`, `run_status <jobId>`, `findings 2`,
-// `dispute f1 "why"`. In findings a bare number is a page and anything else a run id.
+// Positional arguments for the shell face: `status rules 2`, `verify f1`, `run_status <jobId>`,
+// `findings 2`, `dispute f1 "why"`. A bare number is a page; in findings anything else is a run id.
 function argsOf(command, rest) {
+  const page = rest.find((w) => /^\d+$/.test(w));
   switch (command.replace(/-/g, "_")) {
+    case "status": {
+      const show = rest.find((w) => SHOW.includes(w));
+      return { ...(show ? { show } : {}), ...(page ? { page: Number(page) } : {}) };
+    }
     case "run_status": return rest[0] ? { jobId: rest[0] } : {};
     case "findings": {
-      const page = rest.find((w) => /^\d+$/.test(w));
       const jobId = rest.find((w) => w !== "--page" && !/^\d+$/.test(w));
       return { ...(jobId ? { jobId } : {}), ...(page ? { page: Number(page) } : {}) };
     }

package/lib/mcp.mjs

@@ -2,6 +2,8 @@
 // dependency. stdout carries protocol messages and nothing else; everything a person might read
 // goes to stderr. The tools are lib/verbs.mjs, one to one.
 
+import { SHOW } from "./read-text.mjs";
+
 export const PROTOCOL = "2025-06-18";
 
 // Codex keeps only the first 512 characters self-contained and Claude Code shares about 4 KB across
@@ -16,8 +18,9 @@ const none = { type: "object", properties: {}, additionalProperties: false };
 const readOnly = { readOnlyHint: true };
 
 export const TOOLS = [
-  { name: "status", title: "Cortad status", annotations: readOnly, inputSchema: none,
-    description: "What Cortad read in this repository, the plan with runs left, whether the app is up, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval." },
+  { name: "status", title: "Cortad status", annotations: readOnly,
+    description: "What Cortad read in this repository, the plan with runs left, whether the app is up, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval. With show, one section of the read in full, in pages.",
+    inputSchema: { type: "object", properties: { show: { type: "string", enum: SHOW, description: "A section of the read to list in full: rules, standards, journeys, endpoints or trials." }, page: { type: "integer", minimum: 1, description: "The page of that list. Default 1." } }, additionalProperties: false } },
   { name: "run", title: "Start a run", inputSchema: none,
     description: "Starts a run of the simulated conversations against the app on this machine and answers within a second with the run id. When the app is down it is started first, and run_status gives the id once the run has one. Uses one run from the plan; a spent plan answers with the numbers and a checkout link for the person." },
   { name: "run_status", title: "Run progress", annotations: readOnly,

package/lib/read-text.mjs

@@ -0,0 +1,91 @@
+import { at, clip, has, num, pack, pageOf, plural, SIDE } from "./words.mjs";
+
+// What Cortad read of the repository: the walkthrough `status` carries, and one section in full
+// for `status` with show. Both use the same lines, so the full list reads like the walkthrough.
+//
+// The full list comes back from GET /mcp/status?show=<name>: read.rules.all, read.machine.misses
+// complete with read.machine.mets, read.journeys.all, read.doors.all, read.trials.all. Where the API
+// has not sent it, what it did send is listed with "n of N listed".
+export const SHOW = ["rules", "standards", "journeys", "endpoints", "trials"];
+
+const rulesHead = (rules) => {
+  const files = Array.isArray(rules.files) ? rules.files.length : rules.files;
+  return `Rules in the code: ${num(rules.count)}${has(files) ? `, in ${plural(files, "file")}` : ""}.`;
+};
+const ruleLine = (e) => `  ${at(e.path, e.line)}  "${clip(e.text, 300)}"`;
+const headOf = (label, parts) => (parts.some(Boolean) ? `${label}: ${parts.filter(Boolean).join(", ")}.` : `${label}:`);
+const standardsHead = (m) => headOf("Engineering standards", [has(m.decided) && `${num(m.decided)} decided`, has(m.met) && `${num(m.met)} met`, has(m.missed) && `${num(m.missed)} missed`]);
+const standardLine = (x) => `  ${x.path ? `${at(x.path, x.line)}  ` : ""}${x.standard}${x.detail ? `: ${clip(x.detail, 240)}` : ""}${x.decidedBy ? ` (decided by ${x.decidedBy === "code" ? "code" : "a model"})` : ""}`;
+const trialsHead = (t) => headOf("Trials", [has(t.written) && `${num(t.written)} written`, has(t.playable) && `${num(t.playable)} playable`]);
+const heldWhy = (h) => `${SIDE[h.side] ? `, ${SIDE[h.side]}` : ""}${h.why ? `: ${clip(h.why, 300)}` : ""}`;
+const named = (label, group, max = 12) => {
+  if (!group) return null;
+  const names = group.names ?? [];
+  const more = (group.count ?? names.length) - Math.min(names.length, max);
+  const list = names.slice(0, max).join(", ");
+  return `${label} (${num(group.count ?? names.length)})${list ? `: ${list}${more > 0 ? `, and ${more} more` : ""}` : ""}.`;
+};
+// "Journeys (6):" when every one is here, "Journeys (6), 4 listed:" when not.
+const counted = (label, count, n) => `${label} (${num(count ?? n)})${has(count) && n < count ? `, ${num(n)} listed` : ""}:`;
+
+// The walkthrough, in the order the person is walked through it.
+export function readLines(r) {
+  const lines = ["What Cortad read:"];
+  if (r.rules) {
+    const examples = (r.rules.examples ?? []).slice(0, 3);
+    lines.push(`${rulesHead(r.rules)}${examples.length ? ` ${examples.length} of them:` : ""}`, ...examples.map(ruleLine));
+  }
+  for (const line of [named("Journeys", r.journeys), named("Simulated users", r.profiles), named("Endpoints", r.doors)]) if (line) lines.push(line);
+  const m = r.machine;
+  if (m) {
+    const misses = m.misses ?? [];
+    lines.push(standardsHead(m), ...misses.slice(0, 12).map(standardLine));
+    if (misses.length > 12) lines.push(`  and ${misses.length - 12} more.`);
+  }
+  const q = r.questions;
+  if (q) lines.push(`Questions: ${num(q.total)}${has(q.everywhere) ? `; ${num(q.everywhere)} asked in every conversation` : ""}${has(q.placed) ? `, ${num(q.placed)} placed in the situations they fit` : ""}.`);
+  const t = r.trials;
+  if (t) lines.push(trialsHead(t), ...(t.held ?? []).map((h) => `  ${h.surface}: ${plural(h.n, "trial")} held back${heldWhy(h)}`));
+  return lines;
+}
+
+export function showText(d, show, page = 1) {
+  if (!d.read) return "Cortad is still reading this repository.";
+  const { head, lines, continued } = sectionOf(d.read, show);
+  return pageOf(pack(head, lines, continued), page, (n) => `status with show ${show} and page ${n}`);
+}
+
+function sectionOf(r, show) {
+  switch (show) {
+    case "rules": {
+      const rules = r.rules ?? { count: 0 };
+      const all = rules.all ?? rules.examples ?? [];
+      return { head: `${rulesHead(rules)}${all.length < rules.count ? ` ${num(all.length)} of ${num(rules.count)} listed.` : ""}`, lines: all.map(ruleLine), continued: "Rules in the code, continued." };
+    }
+    case "standards": {
+      const m = r.machine ?? {};
+      const misses = m.misses ?? [];
+      const mets = m.mets ?? [];
+      return {
+        head: standardsHead(m),
+        lines: [misses.length && counted("Missed", m.missed, misses.length), ...misses.map(standardLine), mets.length && counted("Met", m.met, mets.length), ...mets.map(standardLine)].filter(Boolean),
+        continued: "Engineering standards, continued.",
+      };
+    }
+    case "journeys": {
+      const all = r.journeys?.all ?? (r.journeys?.names ?? []).map((name) => ({ name }));
+      return { head: counted("Journeys", r.journeys?.count, all.length), lines: all.map((j) => `  ${j.name}${j.steps?.length ? `: ${clip(j.steps.join("; "), 600)}` : ""}`), continued: "Journeys, continued." };
+    }
+    case "endpoints": {
+      const all = r.doors?.all ?? (r.doors?.names ?? []).map((name) => ({ name }));
+      return { head: counted("Endpoints", r.doors?.count, all.length), lines: all.map((e) => `  ${e.name}${e.path ? `: ${[e.method, e.path].filter(Boolean).join(" ")}` : ""}`), continued: "Endpoints, continued." };
+    }
+    case "trials":
+    default: {
+      const t = r.trials ?? {};
+      const all = t.all ?? (t.held ?? []).map((h) => ({ surface: h.surface, held: h.n, why: h.why, side: h.side }));
+      const line = (x) => `  ${x.surface}: ${[has(x.written) && `${num(x.written)} written`, has(x.playable) && `${num(x.playable)} playable`, x.held && `${num(x.held)} held back`].filter(Boolean).join(", ")}${x.held ? heldWhy(x) : ""}`;
+      return { head: trialsHead(t), lines: all.map(line), continued: "Trials, continued." };
+    }
+  }
+}

package/lib/text.mjs

@@ -1,31 +1,18 @@
+import { readLines } from "./read-text.mjs";
+import { at, clip, has, num, PAGE_CHARS, pageOf, plural, SIDE, upper } from "./words.mjs";
+
 // What each verb prints. A result is data for the coding agent: a line meant for the person starts
 // with "For the person:", and a run_status result ends with the next call. A field the API leaves
 // out prints nothing, so the text follows the API as it grows.
 
 const DONE = new Set(["succeeded", "failed", "canceled"]);
-const SIDE = { theirs: "on the app's side", ours: "on Cortad's side" };
 const UNIT = { sweeps: ["run", "runs"], runs: ["run", "runs"], trials: ["verify trial", "verify trials"] };
-// Copilot cuts a result past about 10 KB; a findings page stays under this.
-export const PAGE_CHARS = 9000;
 export const STARTING = "Starting your app for the run. Call run_status; it answers as soon as the run has an id.";
 
-const has = (v) => v !== undefined && v !== null;
-const num = (x) => (typeof x === "number" ? Math.round(x).toLocaleString("en-US") : String(x));
-export const plural = (n, one, many = `${one}s`) => `${num(n)} ${n === 1 ? one : many}`;
 const signed = (x) => (Math.round(x) > 0 ? `+${num(x)}` : num(x));
-const upper = (s) => `${s.charAt(0).toUpperCase()}${s.slice(1)}`;
-const at = (path, line) => `${path}${has(line) ? `:${line}` : ""}`;
-const clip = (s, max) => (String(s).length > max ? `${String(s).slice(0, max - 3)}...` : String(s));
 const units = (n, unit) => { const [one, many] = UNIT[unit] ?? [unit, unit]; return `${num(n)} ${n === 1 ? one : many}`; };
 const kn = (x) => (has(x?.k) ? `${num(x.k)} of ${num(x.n)}` : num(x));
 const interval = (ci) => (ci && has(ci.low) ? `, interval ${num(ci.low)} to ${num(ci.high)}` : "");
-const named = (label, group, max = 12) => {
-  if (!group) return null;
-  const names = group.names ?? [];
-  const more = (group.count ?? names.length) - Math.min(names.length, max);
-  const list = names.slice(0, max).join(", ");
-  return `${label} (${num(group.count ?? names.length)})${list ? `: ${list}${more > 0 ? `, and ${more} more` : ""}` : ""}.`;
-};
 
 export const finished = (run) => Boolean(run) && (run.finished ?? DONE.has(run.status));
 
@@ -52,33 +39,6 @@ function planLine(p) {
   return parts.length ? `${p.name}: ${parts.join(", ")}.` : `Plan: ${p.name}.`;
 }
 
-// What Cortad read, in the order the person is walked through it.
-function readLines(r) {
-  const lines = ["What Cortad read:"];
-  if (r.rules) {
-    const files = Array.isArray(r.rules.files) ? r.rules.files.length : r.rules.files;
-    const examples = (r.rules.examples ?? []).slice(0, 3);
-    lines.push(`Rules in the code: ${num(r.rules.count)}${has(files) ? `, in ${plural(files, "file")}` : ""}.${examples.length ? ` ${examples.length} of them:` : ""}`);
-    for (const e of examples) lines.push(`  ${at(e.path, e.line)}  "${clip(e.text, 200)}"`);
-  }
-  for (const line of [named("Journeys", r.journeys), named("Simulated users", r.profiles), named("Endpoints", r.doors)]) if (line) lines.push(line);
-  const m = r.machine;
-  if (m) {
-    lines.push(`Engineering standards: ${[has(m.decided) && `${num(m.decided)} decided`, has(m.met) && `${num(m.met)} met`, has(m.missed) && `${num(m.missed)} missed`].filter(Boolean).join(", ")}.`);
-    const misses = m.misses ?? [];
-    for (const x of misses.slice(0, 12)) lines.push(`  ${x.path ? `${at(x.path, x.line)}  ` : ""}${x.standard}${x.detail ? `: ${clip(x.detail, 240)}` : ""}${x.decidedBy ? ` (decided by ${x.decidedBy === "code" ? "code" : "a model"})` : ""}`);
-    if (misses.length > 12) lines.push(`  and ${misses.length - 12} more.`);
-  }
-  const q = r.questions;
-  if (q) lines.push(`Questions: ${num(q.total)}${has(q.everywhere) ? `; ${num(q.everywhere)} asked in every conversation` : ""}${has(q.placed) ? `, ${num(q.placed)} placed in the situations they fit` : ""}.`);
-  const t = r.trials;
-  if (t) {
-    lines.push(`Trials: ${[has(t.written) && `${num(t.written)} written`, has(t.playable) && `${num(t.playable)} playable`].filter(Boolean).join(", ")}.`);
-    for (const h of t.held ?? []) lines.push(`  ${h.surface}: ${plural(h.n, "trial")} held back${SIDE[h.side] ? `, ${SIDE[h.side]}` : ""}${h.why ? `: ${h.why}` : ""}`);
-  }
-  return lines;
-}
-
 function runLines(d, prefix = "") {
   const done = finished(d);
   const played = d.of ? `${num(d.played ?? 0)} of ${plural(d.of, "trial")} played` : "no trial played yet";
@@ -190,12 +150,7 @@ export function linesOf(d) {
   return [...merged.values()];
 }
 
-export function findingsText(d, page = 1) {
-  const pages = findingsPages(d);
-  const n = Math.min(Math.max(1, Math.floor(Number(page)) || 1), pages.length);
-  const tail = pages.length === 1 ? "" : n < pages.length ? `\npage ${n} of ${pages.length}, call findings with page ${n + 1}` : `\npage ${n} of ${pages.length}`;
-  return `${pages[n - 1]}${tail}`;
-}
+export const findingsText = (d, page = 1) => pageOf(findingsPages(d), page, (n) => `findings with page ${n}`);
 
 function findingsHead(d) {
   const lines = [`Run ${d.runId}: ${plural(d.findings?.length ?? 0, "finding")}.`];

package/lib/verbs.mjs

@@ -1,5 +1,6 @@
 import { realpathSync, statSync } from "node:fs";
 import { resolve as resolvePath, sep } from "node:path";
+import { SHOW, showText } from "./read-text.mjs";
 import { fieldConnectText, fieldText, findingsText, linesOf, refusedText, runText, STARTING, startedText, statusText, waitingText } from "./text.mjs";
 
 // The eight things a coding agent may ask of Cortad, each a call to the API with this machine's key
@@ -40,9 +41,12 @@ export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, ro
   const failed = (res) => ({ text: res.data?.why ?? res.data?.error ?? `Cortad answered ${res.status}.`, data: res.data, isError: true });
   const iso = () => new Date(now()).toISOString();
 
-  const status = async () => {
-    const res = await call("GET", "/mcp/status");
-    return res.ok ? { text: statusText(res.data), data: res.data } : failed(res);
+  // With show, one section of the read in full, paged; a name that is not a section is the plain status.
+  const status = async ({ show, page } = {}) => {
+    const section = SHOW.includes(show) ? show : null;
+    const res = await call("GET", `/mcp/status${section ? `?show=${section}` : ""}`);
+    if (!res.ok) return failed(res);
+    return { text: section ? showText(res.data, section, page) : statusText(res.data), data: res.data };
   };
 
   // Asks the server for the run and keeps its id here, so run_status finds it without one.

package/lib/words.mjs

@@ -0,0 +1,37 @@
+// The small pieces every rendering shares: numbers with their units, file and line, whose side a
+// stop is on, and the pages a long answer is cut into.
+
+// Copilot cuts a result past about 10 KB; a page stays under this.
+export const PAGE_CHARS = 9000;
+export const SIDE = { theirs: "on the app's side", ours: "on Cortad's side" };
+
+export const has = (v) => v !== undefined && v !== null;
+export const num = (x) => (typeof x === "number" ? Math.round(x).toLocaleString("en-US") : String(x));
+export const plural = (n, one, many = `${one}s`) => `${num(n)} ${n === 1 ? one : many}`;
+export const upper = (s) => `${s.charAt(0).toUpperCase()}${s.slice(1)}`;
+export const at = (path, line) => `${path}${has(line) ? `:${line}` : ""}`;
+export const clip = (s, max) => (String(s).length > max ? `${String(s).slice(0, max - 3)}...` : String(s));
+
+// One page of many, with the call that reads the next one: `next(2)` gives "findings with page 2".
+export function pageOf(pages, page, next) {
+  const n = Math.min(Math.max(1, Math.floor(Number(page)) || 1), pages.length);
+  const tail = pages.length === 1 ? "" : n < pages.length ? `\npage ${n} of ${pages.length}, call ${next(n + 1)}` : `\npage ${n} of ${pages.length}`;
+  return `${pages[n - 1]}${tail}`;
+}
+
+// Lines packed into pages under PAGE_CHARS; every page after the first opens with `continued`.
+export function pack(head, lines, continued, budget = PAGE_CHARS - 80) {
+  const pages = [];
+  let page = head;
+  let filled = false;
+  for (const line of lines) {
+    if (filled && page.length + line.length + 1 > budget) {
+      pages.push(page);
+      page = continued;
+      filled = false;
+    }
+    page += `\n${line}`;
+    filled = true;
+  }
+  return [...pages, page];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortad",
-  "version": "0.3.0-rc.2",
+  "version": "0.3.0-rc.3",
   "description": "Connects the AI app on your machine to Cortad for test conversations, and gives your coding agent the MCP and skill to run them. No dependencies.",
   "bin": {
     "cortad": "local.mjs"
@@ -17,6 +17,7 @@
     "lib/mcp.mjs",
     "lib/mint.mjs",
     "lib/pyhook/sitecustomize.py",
+    "lib/read-text.mjs",
     "lib/register.mjs",
     "lib/replay.mjs",
     "lib/sample.mjs",
@@ -28,6 +29,7 @@
     "lib/text.mjs",
     "lib/trace.cjs",
     "lib/verbs.mjs",
+    "lib/words.mjs",
     "local.mjs",
     "skill/SKILL.md",
     "skill/references/results.md"

package/skill/SKILL.md

@@ -29,6 +29,8 @@ The connect command ends with "Go back to the browser". From then on `status` ca
 4. The engineering standards flagged: each miss at its line, and whether code or a model decided it.
 5. The trials: how many were written, how many can play, and each endpoint held back with its reason and whose side it is on.
 
+Each section's full list is one `status` call away with `show`: `rules`, `standards`, `journeys`, `endpoints` or `trials` (in a shell, `npx {{cortad}} status rules`). A long list comes in pages, and the last line names the next page.
+
 Then the findings, then the fixes.
 
 ## Following a run

package/skill/references/results.md

@@ -44,6 +44,28 @@ For the person: https://cortad.com/lab shows this in the browser.
 next: run_status 8f2a1c4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b
 ```
 
+Each section in full, with `show` (`rules`, `standards`, `journeys`, `endpoints` or `trials`). A list longer than one page ends with `page 1 of 3, call status with show rules and page 2`.
+
+```
+Rules in the code: 16, in 5 files.
+  apps/api/src/agent/prompt.ts:41  "Never state a refund policy the product does not publish."
+  apps/api/src/agent/prompt.ts:44  "Point billing questions to the billing page."
+  apps/api/src/agent/system.ts:12  "Answer in the language the student writes in."
+  apps/api/src/agent/system.ts:15  "Keep an answer for a grade 9 student to grade 9 words."
+  apps/api/src/agent/system.ts:19  "Ask which lesson the question is about before answering it."
+  apps/api/src/agent/system.ts:22  "Give the method before the answer on homework."
+  apps/api/src/agent/system.ts:30  "Leave the student's name out of the reply."
+  apps/api/src/tools/search.ts:8  "Cite the lesson a fact comes from."
+  apps/api/src/tools/search.ts:14  "Say so when search finds nothing, rather than answering from memory."
+  apps/api/src/tools/search.ts:17  "Quote at most two sentences from a lesson."
+  apps/api/src/agent/handoff.ts:6  "Hand a refund request to a person."
+  apps/api/src/agent/handoff.ts:9  "Hand an account recovery to a person once the email is confirmed."
+  apps/api/src/agent/billing.ts:21  "Tell a parent what the plan costs only from the pricing page."
+  apps/api/src/agent/billing.ts:27  "Never promise a teacher a feature that is not released."
+  apps/web/src/chat/welcome.ts:3  "Greet a first lesson with what the student can ask."
+  apps/web/src/chat/welcome.ts:11  "End each homework answer with one practice question."
+```
+
 ## run
 
 The app is up: