@letterstory/cli 0.73.0 → 0.73.1

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.73.0";
+export const VERSION = "0.73.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -639,8 +639,9 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        candidate, compare, comparisons, picks, pick,
                                                        ledger, reading-list, finalists,
                                                        finalists-queue, pair, side-by-side,
-                                                       evals, eval-add, eval-set, proposals,
-                                                       propose-eval, capture-eval, reject-eval, promote,
+                                                       checklist, checklist-add, checklist-set,
+                                                       checklist-labels, feedback, feedback-add,
+                                                       feedback-file, feedback-reject, promote,
                                                        sessions, session-new, propose, trial-add,
                                                        trial-run, trial-save, the Write input bank
                                                        (inputs, input, inputs-harvest, input-save),

package/lib/commands/admin.mjs

@@ -8,8 +8,9 @@
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
 //   admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|criteria|promote …   (tuning:experiment)
-//   admin tuning evals|eval-add|eval-set|proposals|propose-eval|capture-eval|reject-eval …    (tuning:experiment)
-//     (propose-eval --fix "…" files the reader's rewrite; the diff is classified to a lever, or to a schema gap: kind lever)
+//   admin tuning checklist|checklist-add|checklist-set|checklist-labels|feedback|feedback-add|feedback-file|feedback-reject …    (tuning:experiment)
+//     (feedback-add --fix "…" files the reader's rewrite; the diff is classified and a disposition suggested.
+//      The old names — evals, eval-add, eval-set, proposals, propose-eval, capture-eval, reject-eval — still work.)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin crm import|capture|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
@@ -449,15 +450,19 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning criteria                                      the Eye Test's criteria: id, label and the question each asks of a pair
  *   admin tuning loop                                          where the loop stands: what waits at each station, and where to go next
  *   admin tuning ledger <comparison-id>                        the defect ledger: per arm, what the diagnosis read named, the floor and the ceiling, the candidate's next arm; then the reader edits per arm by lever, and the schema gaps
- *   admin tuning evals                                         the eval list: every defect category with its status and the picks' agreement (n, agreement, suggestion)
- *   admin tuning eval-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]   add a category (starts unvetted)
- *   admin tuning eval-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]   confirm / reject (a person's call), or add an example
- *   admin tuning proposals [--status proposed|captured|rejected]   the eval proposals: spans readers marked in a pair's text with their words, and what became of each
- *   admin tuning propose-eval --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]   mark a span as an eval (no --side from a blind read); --fix is the reader's rewrite, classified to a lever (or a schema gap: kind lever)
- *   admin tuning capture-eval <proposal-id> --as category --id … --label … --how … --layer … --lever … --locality local|structural --axis …   capture it into the eval list, the span (and its fix) as the category's example (appends when the id exists)
- *   admin tuning capture-eval <proposal-id> --as rule          file it as narrow; the rule itself is written in the kernels rule lab
- *   admin tuning capture-eval <proposal-id> --as lever [--note "…"]   file it as a schema gap: an edit no kernel-file lever can produce, for the kernels repo
- *   admin tuning reject-eval <proposal-id>                      a span that was not an eval after all
+ *   admin tuning checklist                                     the checklist: every defect category with its status, the picks' agreement (n, agreement, suggestion) and its labels (+/−)   (alias: evals)
+ *   admin tuning checklist-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]   add a category (starts unvetted)   (alias: eval-add)
+ *   admin tuning checklist-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]   confirm / reject (a person's call), or add an example   (alias: eval-set)
+ *   admin tuning checklist-labels <id>                         the labelled set of one category: positives (examples + feedback filed into it), negatives (rejected feedback suggested for it), grid overrules
+ *   admin tuning feedback [--status proposed|captured|rejected]   the feedback: spans readers marked in a pair's text with their words, each with its disposition   (alias: proposals)
+ *   admin tuning feedback-add --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]   add feedback (no --side from a blind read); --fix is the reader's rewrite, classified and a disposition suggested   (alias: propose-eval)
+ *   admin tuning feedback-file <id> --as checklist --id … --label … --how … --layer … --lever … --locality local|structural --axis …   file it on the checklist, the span (and its fix) as the category's example (appends when the id exists)   (alias: capture-eval; --as category)
+ *   admin tuning feedback-file <id> --as rule                   file it as a rule; the rule itself is written in the kernels rule lab
+ *   admin tuning feedback-file <id> --as config [--note "…"]    file it as a lever this candidate should pull
+ *   admin tuning feedback-file <id> --as implementation [--note "…"]   file it as a schema gap no setting can express, for the kernels repo (--as lever still works)
+ *   admin tuning feedback-file <id> --as material [--note "…"]  file it as the material's: the input never carried it
+ *   admin tuning feedback-file <id> --as note                   keep it; no action
+ *   admin tuning feedback-reject <id>                           feedback that was not worth keeping after all   (alias: reject-eval)
  *   admin tuning reading-list <comparison-id> [--n 10]          your next blind pairs as links, to read off the screen
  *   admin tuning finalists [--limit 10]                        the finalists feed: done, gates clean, no craft loss, not yet decided by the picks; ranked by the objective's order
  *   admin tuning finalists-queue [--n 10]                      your next blind pairs round-robin across the finalists (a key reads the queue of the person who owns it; recording a pick still needs a person)
@@ -507,8 +512,8 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning screens | screen <id>                         list / one screen: per candidate, each measure against the Base, with its noise
  *   admin tuning screen-advance <id>                           queue what the caps allow now (the cron does it every minute)
  *
- * The bake-off: a screen's versions graded item by item against the checklist (the eval list's
- * confirmed and unvetted categories, and the craft axes commitment / economy / movement), the winner
+ * The bake-off: a screen's versions graded item by item against the checklist's confirmed and
+ * unvetted categories and the craft axes commitment / economy / movement, the winner
  * per item tallied across the inputs, and a merge that composes the best of each into one candidate.
  * Deterministic; a person overrides a grade and confirms the merge, which is a hypothesis until the
  * eye test confirms it.
@@ -793,6 +798,7 @@ async function cmdAdminTuning(ctx) {
 				})
 			);
 		}
+		case "checklist":
 		case "evals": {
 			const r = await staffRequest(ctx, "GET", `${T}/evals`);
 			if (json) return printResult(io, flags, r);
@@ -800,16 +806,29 @@ async function cmdAdminTuning(ctx) {
 			if (!rows.length) return io.log("(no categories)");
 			const cell = (v, w) => String(v ?? "—").padEnd(w);
 			io.log(
-				`${cell("id", 24)} ${cell("status", 10)} ${cell("layer", 10)} ${cell("lever", 30)} ${"n".padStart(4)} ${"agree".padStart(6)} ${cell("suggest", 10)} ${"ex".padStart(3)}`
+				`${cell("id", 24)} ${cell("status", 10)} ${cell("layer", 10)} ${cell("lever", 30)} ${"n".padStart(4)} ${"agree".padStart(6)} ${cell("suggest", 10)} ${"+".padStart(3)} ${"−".padStart(3)}`
 			);
 			for (const c of rows) {
 				const v = c.vetting ?? {};
+				const l = c.labels ?? { positives: (c.examples ?? []).length, negatives: 0 };
 				io.log(
-					`${cell(c.id, 24)} ${cell(c.status, 10)} ${cell(c.layer, 10)} ${cell(c.lever || "—", 30)} ${String(v.n ?? 0).padStart(4)} ${String(v.agreement ?? "—").padStart(6)} ${cell(v.suggestion, 10)} ${String((c.examples ?? []).length).padStart(3)}`
+					`${cell(c.id, 24)} ${cell(c.status, 10)} ${cell(c.layer, 10)} ${cell(c.lever || "—", 30)} ${String(v.n ?? 0).padStart(4)} ${String(v.agreement ?? "—").padStart(6)} ${cell(v.suggestion, 10)} ${String(l.positives).padStart(3)} ${String(l.negatives).padStart(3)}`
 				);
 			}
 			return;
 		}
+		case "checklist-labels": {
+			if (!id) throw new CliError("Usage: admin tuning checklist-labels <category-id>");
+			const r = await staffRequest(ctx, "GET", `${T}/evals/${encodeURIComponent(id)}/labels`);
+			if (json) return printResult(io, flags, r);
+			io.log(
+				`${r.category_id}: ${r.counts.positives} positive, ${r.counts.negatives} negative (${r.grid_overrules} grid overrule${r.grid_overrules === 1 ? "" : "s"})`
+			);
+			for (const x of r.positives ?? []) io.log(`  + [${x.source}] "${x.span}"${x.fix ? ` → "${x.fix}"` : ""}`);
+			for (const x of r.negatives ?? []) io.log(`  − [${x.source}] "${x.span}"${x.fix ? ` → "${x.fix}"` : ""}`);
+			return;
+		}
+		case "checklist-add":
 		case "eval-add": {
 			const body = {
 				id: flagStr(flags.id),
@@ -830,25 +849,26 @@ async function cmdAdminTuning(ctx) {
 				!["local", "structural"].includes(body.locality ?? "")
 			)
 				throw new CliError(
-					'Usage: admin tuning eval-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]'
+					'Usage: admin tuning checklist-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]'
 				);
 			if (example) body.examples = [{ span: example, ...(flags.fix ? { fix: flagStr(flags.fix) } : {}) }];
 			const r = await staffRequest(ctx, "POST", `${T}/evals`, body);
 			return json ? printResult(io, flags, r) : io.log(`added ${r.category.id} (${r.category.status})`);
 		}
+		case "checklist-set":
 		case "eval-set": {
 			const status = flagStr(flags.status);
 			const example = flagStr(flags.example);
 			if (!id || (!status && !example) || (status && !["confirmed", "rejected", "unvetted"].includes(status)))
 				throw new CliError(
-					'Usage: admin tuning eval-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]'
+					'Usage: admin tuning checklist-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]'
 				);
 			const patch = {};
 			if (status) patch.status = status;
 			if (example) {
 				// The PATCH replaces the whole list: read what is stored and append.
 				const current = (await staffRequest(ctx, "GET", `${T}/evals`)).categories?.find((c) => c.id === id);
-				if (!current) throw new CliError(`No category ${id} in the eval list`);
+				if (!current) throw new CliError(`No category ${id} on the checklist`);
 				const fix = flagStr(flags.fix);
 				patch.examples = [...(current.examples ?? []), { span: example, ...(fix ? { fix } : {}) }];
 			}
@@ -857,27 +877,32 @@ async function cmdAdminTuning(ctx) {
 				? printResult(io, flags, r)
 				: io.log(`${r.category.id}: ${r.category.status}, ${(r.category.examples ?? []).length} examples`);
 		}
+		case "feedback":
 		case "proposals": {
 			const status = flagStr(flags.status);
 			if (status && !["proposed", "captured", "rejected"].includes(status))
-				throw new CliError("Usage: admin tuning proposals [--status proposed|captured|rejected]");
+				throw new CliError("Usage: admin tuning feedback [--status proposed|captured|rejected]");
 			const qs = status ? `?${new URLSearchParams({ status })}` : "";
 			const r = await staffRequest(ctx, "GET", `${T}/proposals${qs}`);
 			if (json) return printResult(io, flags, r);
 			const rows = r.proposals ?? [];
-			if (!rows.length) return io.log("(no proposals)");
+			if (!rows.length) return io.log("(no feedback)");
 			for (const p of rows) {
 				const where = [p.cell_key, p.side].filter(Boolean).join(" / ") || "—";
+				const suggested = p.suggested_disposition
+					? `; suggested ${p.suggested_disposition}${p.suggested_category ? ` (${p.suggested_category})` : ""}`
+					: "";
 				const edit =
 					p.fix != null
-						? `\n    → "${p.fix}"  [${p.edit_class ?? "?"} → ${p.lever ?? "no lever: schema gap"}]`
+						? `\n    → "${p.fix}"  [${p.edit_class ?? "?"} → ${p.lever ?? "no lever: schema gap"}${suggested}]`
 						: "";
 				io.log(
-					`${p.id}  ${p.status.padEnd(9)} ${p.kind.padEnd(6)} ${where}${p.category_id ? ` → ${p.category_id}` : ""}\n    "${p.span}"${edit}${p.comment ? `\n    ${p.comment}` : ""}`
+					`${p.id}  ${p.status.padEnd(9)} ${(p.disposition ?? p.kind).padEnd(14)} ${where}${p.category_id ? ` → ${p.category_id}` : ""}\n    "${p.span}"${edit}${p.comment ? `\n    ${p.comment}` : ""}`
 				);
 			}
 			return;
 		}
+		case "feedback-add":
 		case "propose-eval": {
 			const span = flagStr(flags.span);
 			const side = flagStr(flags.side);
@@ -888,7 +913,7 @@ async function cmdAdminTuning(ctx) {
 				(kind && !["narrow", "wide"].includes(kind))
 			)
 				throw new CliError(
-					'Usage: admin tuning propose-eval --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]'
+					'Usage: admin tuning feedback-add --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]'
 				);
 			const r = await staffRequest(
 				ctx,
@@ -906,17 +931,27 @@ async function cmdAdminTuning(ctx) {
 			);
 			if (json) return printResult(io, flags, r);
 			const p = r.proposal;
-			const edit = p.fix != null ? ` — ${p.edit_class}: ${p.lever ?? "no lever maps: a schema gap"}` : "";
-			return io.log(`proposed ${p.id} (${p.kind})${edit}`);
-		}
+			const suggested = p.suggested_disposition
+				? `; suggested ${p.suggested_disposition}${p.suggested_category ? ` (${p.suggested_category})` : ""}`
+				: "";
+			const edit =
+				p.fix != null ? ` — ${p.edit_class}: ${p.lever ?? "no lever maps: a schema gap"}${suggested}` : "";
+			return io.log(`added feedback ${p.id} (${p.disposition ?? p.kind})${edit}`);
+		}
+		case "feedback-file":
 		case "capture-eval": {
-			const as = flagStr(flags.as);
+			// The first names of checklist and implementation, still accepted.
+			const AS_ALIAS = { category: "checklist", lever: "implementation" };
+			const asGiven = flagStr(flags.as);
+			const as = AS_ALIAS[asGiven] ?? asGiven;
 			const usage =
-				'Usage: admin tuning capture-eval <proposal-id> --as category --id … --label … --how … --layer … --lever … --locality local|structural --axis … | --as rule | --as lever [--note "…"]';
-			if (!id || !["category", "rule", "lever"].includes(as ?? "")) throw new CliError(usage);
+				'Usage: admin tuning feedback-file <id> --as checklist --id … --label … --how … --layer … --lever … --locality local|structural --axis … | --as rule | --as config|implementation|material [--note "…"] | --as note';
+			if (!id || !["checklist", "rule", "config", "implementation", "material", "note"].includes(as ?? ""))
+				throw new CliError(usage);
 			let body = { as };
-			if (as === "lever") body = compact({ as, note: flagStr(flags.note) });
-			if (as === "category") {
+			if (as === "config" || as === "implementation" || as === "material")
+				body = compact({ as, note: flagStr(flags.note) });
+			if (as === "checklist") {
 				const category = {
 					id: flagStr(flags.id),
 					label: flagStr(flags.label),
@@ -938,14 +973,22 @@ async function cmdAdminTuning(ctx) {
 				body = { as, category };
 			}
 			const r = await staffRequest(ctx, "POST", `${T}/proposals/${id}/capture`, body);
-			return json
-				? printResult(io, flags, r)
-				: io.log(
-						`captured ${r.proposal.id} as ${r.proposal.kind}${r.category ? ` → ${r.category.id} (${(r.category.examples ?? []).length} examples)` : r.proposal.kind === "lever" ? "; a schema gap, filed for the kernels repo" : "; write the rule in the kernels rule lab"}`
-					);
+			if (json) return printResult(io, flags, r);
+			const FILED = {
+				rule: "; write the rule in the kernels rule lab",
+				implementation: "; a schema gap, filed for the kernels repo",
+				config: "; a lever for this candidate",
+				material: "; the input never carried it",
+				note: "; kept, no action",
+			};
+			const d = r.proposal.disposition ?? as;
+			return io.log(
+				`filed ${r.proposal.id} as ${d}${r.category ? ` → ${r.category.id} (${(r.category.examples ?? []).length} examples)` : (FILED[d] ?? "")}`
+			);
 		}
+		case "feedback-reject":
 		case "reject-eval": {
-			if (!id) throw new CliError("Usage: admin tuning reject-eval <proposal-id>");
+			if (!id) throw new CliError("Usage: admin tuning feedback-reject <id>");
 			const r = await staffRequest(ctx, "POST", `${T}/proposals/${id}/reject`, {});
 			return json ? printResult(io, flags, r) : io.log(`rejected ${r.proposal.id}`);
 		}
@@ -958,11 +1001,13 @@ async function cmdAdminTuning(ctx) {
 		case "loop": {
 			const r = await staffRequest(ctx, "GET", `${T}/loop`);
 			if (json) return printResult(io, flags, r);
-			io.log(`propose   ${r.propose.running} running`);
+			const week = r.propose.candidates_week ?? "?";
+			const progs = r.propose.programmes_running ?? "?";
+			io.log(`propose   ${r.propose.running} running, ${week} candidates this week, ${progs} programmes running`);
 			io.log(`read      ${r.read.settled_unread} settled, unread`);
 			io.log(`eye test  ${r.eye_test.finalists} finalists, ${r.eye_test.pairs_to_read} pairs to read`);
 			io.log(
-				`evals     ${r.evals.proposals_waiting} proposals waiting, ${r.evals.unvetted} unvetted, ${r.evals.suggested} with a suggestion${r.evals.reachable ? "" : " (the eval list could not be read)"}`
+				`checklist ${r.evals.proposals_waiting} feedback waiting, ${r.evals.unvetted} unvetted, ${r.evals.suggested} with a suggestion${r.evals.reachable ? "" : " (the checklist could not be read)"}`
 			);
 			io.log(`promote   ${r.promote.promotable} won their picks`);
 			io.log(`\nnext: ${r.next}`);
@@ -2188,7 +2233,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|loop|ledger|evals|eval-add|eval-set|proposals|propose-eval|capture-eval|reject-eval|reading-list|finalists|finalists-queue|pair|bank|bank-eval|bank-draft|bank-shape|bank-pool|bank-judge|bank-score|bank-try|people|invite|revoke|assignments|assign|unassign|tasks|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|arena-dials|comparison-extend|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|loop|ledger|checklist|checklist-add|checklist-set|checklist-labels|feedback|feedback-add|feedback-file|feedback-reject|reading-list|finalists|finalists-queue|pair|bank|bank-eval|bank-draft|bank-shape|bank-pool|bank-judge|bank-score|bank-try|people|invite|revoke|assignments|assign|unassign|tasks|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|arena-dials|comparison-extend|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
 			);
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.73.0",
+	"version": "0.73.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",