@letterstory/cli 0.98.0 → 0.98.1

package/lib/cli.mjs

@@ -58,7 +58,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.98.0";
+export const VERSION = "0.98.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. Every `type: "bool"` flag (and its
@@ -92,6 +92,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"stdin",
 	// `authors generate <id> --with-bios`.
 	"with-bios",
+	// `admin tuning climb-new … --no-run`; `rung-propose --accept --with-replay` / `rung-accept --with-replay`
+	// (not `--replay`: `evals` takes `--replay <stage>`).
+	"no-run",
+	"with-replay",
 	// `covers generate <id> --regenerate` and `arena run --gate --article <id>`
 	// both put a value-less flag next to a value: without these entries the parser
 	// hands the following token to the flag and the real argument disappears.

package/lib/commands/admin.mjs

@@ -599,6 +599,20 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning trial-run <trial-id> [--repeats 2]            queue runs (guardrails apply)
  *   admin tuning trial-save <trial-id> [--note "…"]            save a trial as a candidate version (never live)
  *
+ * The climb (docs/architecture/candidate-climb-2026-10-14.md): a candidate built from a kernel's FLOOR
+ * (the writer alone under the record's constraints) one rung of feedback at a time. Mark lines, rewrite
+ * them, pick sections, say what is wrong in a sentence; the proposer answers in your words and the dials';
+ * accept, and the next rung runs. Earlier feedback is watched on every later rung (gone / still there).
+ *   admin tuning climb-new --title "…" --kernel <id|name> (--bank <input-id> | --input-file f.md | --input "…") [--kind …] [--version N] [--no-run]
+ *                            a session whose Base is the kernel's floor; its first run is queued unless --no-run
+ *   admin tuning climb <session-id>                            the trail: each rung, what it changed, its run, how many earlier wishes it met; the ladder
+ *   admin tuning ladder                                        the floor, and the rungs a climb can add back by key (voice, rules-repair, house-style, …)
+ *   admin tuning feedback-add --run <run-id> --span "…" [--comment "…"] [--fix "…"] [--section <key>] [--locus span|section|piece] [--polarity issue|strength]
+ *                            feedback on a rung's run (a climb); --locus piece with --comment for the whole piece; --locus section --section <key> --polarity strength keeps a section
+ *   admin tuning rung-propose <session-id> [--trial <id>] [--feedback id,id] [--accept [--with-replay]]   the next rung from the feedback on the head's run; --accept takes the first rung proposed
+ *   admin tuning rung-accept <session-id> --parent <trial-id> (--preset <key> | --settings '[{dial,scope,value,plain,feedback_ids}]') [--name "…"] [--with-replay [--replay-n 4]]
+ *   admin tuning watches <run-id>                              read every earlier feedback item against this run's text (gone / still there), and list the readings
+ *
  * The Write input bank: real kernel requests (above all the arena outlines Auto-Pen sends), as sent.
  *   admin tuning inputs [--filter "origin=arena_outline;material=thin,typical"] [--q "…"]   list by tag, with coverage per bucket
  *   admin tuning input <input-id>                              one input in full: text, constraints, tags, run defaults, origin
@@ -1005,25 +1019,37 @@ async function cmdAdminTuning(ctx) {
 			const side = flagStr(flags.side);
 			const kind = flagStr(flags.kind);
 			if (
-				!span ||
+				(!span && flagStr(flags.locus) !== "piece") ||
 				(side && !["control", "candidate"].includes(side)) ||
 				(kind && !["narrow", "wide"].includes(kind))
 			)
 				throw new CliError(
-					'Usage: admin tuning feedback-add --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] | --run <run-id> [--locus span|section|piece] [--section <key>] [--polarity issue|strength]'
 				);
+			const locus = flagStr(flags.locus);
+			const polarity = flagStr(flags.polarity);
+			if (
+				(locus && !["span", "section", "piece"].includes(locus)) ||
+				(polarity && !["issue", "strength"].includes(polarity))
+			)
+				throw new CliError("--locus is span|section|piece; --polarity is issue|strength");
 			const r = await staffRequest(
 				ctx,
 				"POST",
 				`${T}/proposals`,
 				compact({
-					span,
+					span: locus === "piece" && !flagStr(flags.span) ? "(whole piece)" : span,
 					comment: flagStr(flags.comment),
 					fix: flagStr(flags.fix),
 					comparison_id: flagStr(flags.comparison),
 					cell_key: flagStr(flags.cell),
 					side,
 					kind,
+					// A climb: feedback on a rung's run, about a span, one section or the whole piece.
+					run_id: flagStr(flags.run),
+					locus,
+					section_key: flagStr(flags.section),
+					polarity,
 				})
 			);
 			if (json) return printResult(io, flags, r);
@@ -1603,6 +1629,171 @@ async function cmdAdminTuning(ctx) {
 				`${r.kernel}: saved as candidate v${r.version}${r.baseVersion ? ` (from v${r.baseVersion})` : ""}${r.leftBehind.length ? `; per-run, not saved: ${r.leftBehind.join(", ")}` : ""}`
 			);
 		}
+		// --- The climb: from the floor, one rung of feedback at a time (lib/tuning/climb.ts) ---
+		case "climb-new": {
+			const title = flagStr(flags.title);
+			const kernel = flagStr(flags.kernel);
+			const path = flagStr(flags["input-file"]);
+			let input = flagStr(flags.input);
+			if (path) {
+				try {
+					input = readFileSync(path, "utf8");
+				} catch (err) {
+					throw new CliError(`--input-file ${path}: ${err.message}`);
+				}
+			}
+			const bank = flagStr(flags.bank);
+			if (!title || !kernel || (!input && !bank))
+				throw new CliError(
+					'Usage: admin tuning climb-new --title "…" --kernel <id|name> (--bank <input-id> | --input-file f.md | --input "…") [--kind article|outline|brief] [--version N] [--no-run]'
+				);
+			let kernelId = kernel;
+			if (!/^[0-9a-f-]{36}$/i.test(kernel)) {
+				const { kernels } = await staffRequest(ctx, "GET", `${T}/kernels`);
+				const matches = kernels.filter((k) => k.name.toLowerCase() === kernel.toLowerCase());
+				const shared = matches.find((k) => !k.orgName) ?? matches[0];
+				if (!shared) throw new CliError(`No kernel named ${kernel} (admin tuning base-kernels lists them).`);
+				kernelId = shared.id;
+			}
+			const { session } = await staffRequest(
+				ctx,
+				"POST",
+				T,
+				compact({
+					title,
+					input_text: bank ? undefined : input,
+					input_kind: flagStr(flags.kind) ?? "unknown",
+					material: bank ? { source: "bank", input_id: bank } : undefined,
+					base_kernel_id: kernelId,
+					base_version: flagNum(flags.version),
+					started_from: "floor",
+				})
+			);
+			const floor = session.trials[0];
+			let runs = [];
+			if (!flagBool(flags["no-run"]) && floor && session.material?.ready !== false) {
+				const r = await staffRequest(ctx, "POST", `${T}/trials/${floor.id}/run`, { repeats: 1 });
+				runs = r.runs;
+			}
+			if (json) return printResult(io, flags, { session, runs });
+			return io.log(
+				`climb ${session.id} on ${session.baseKernelName}${session.baseVersion ? ` v${session.baseVersion}` : " (live)"}: floor trial ${floor?.id}${runs.length ? `, run ${runs[0].id} queued` : ""} → ${ctx.client.url}/superadmin/tuning/${session.id}`
+			);
+		}
+		case "climb": {
+			if (!id) throw new CliError("Usage: admin tuning climb <session-id>");
+			const r = await staffRequest(ctx, "GET", `${T}/sessions/${id}/climb`);
+			if (json) return printResult(io, flags, r);
+			const lines = [`climb ${r.session_id} (from the ${r.started_from}); head ${r.head_trial_id ?? "—"}`];
+			r.trail.forEach((rung, i) => {
+				const w = rung.watches;
+				const n = w.met + w.unmet + w.unread;
+				lines.push(
+					`${String(i).padStart(2)}  ${rung.name}  [${rung.trial_id}]${rung.run ? `  run ${rung.run.id} ${rung.run.status}${rung.run.words ? ` · ${rung.run.words} words` : ""}` : "  (no run)"}${n ? `  · ${w.met} of ${n} wishes met` : ""}${rung.replay_screen_id ? `  · replay ${rung.replay_screen_id}` : ""}`
+				);
+				for (const s of rung.settings ?? []) lines.push(`      ${s.plain}`);
+				if (rung.changes.length) lines.push(`      (${rung.changes.join("; ")})`);
+			});
+			const open = r.feedback.filter((f) => f.status === "proposed");
+			lines.push(`feedback: ${r.feedback.length} (${open.length} not yet answered)`);
+			for (const f of open.slice(0, 10))
+				lines.push(
+					`  ${f.id}  ${f.locus}${f.section_key ? ` ${f.section_key}` : ""}  ${f.polarity}: ${f.comment || f.span.slice(0, 80)}`
+				);
+			lines.push(`ladder: ${r.ladder.map((l) => `${l.key}${l.on ? " (on)" : ""}`).join(", ")}`);
+			return io.log(lines.join("\n"));
+		}
+		case "ladder": {
+			const r = await staffRequest(ctx, "GET", `${T}/ladder`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				[`floor: ${r.floor.what}`, ...r.ladder.map((l) => `${l.key.padEnd(16)} ${l.label} — ${l.help}`)].join(
+					"\n"
+				)
+			);
+		}
+		case "rung-propose": {
+			if (!id)
+				throw new CliError(
+					"Usage: admin tuning rung-propose <session-id> [--trial <id>] [--feedback id,id] [--accept [--with-replay]]"
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/sessions/${id}/climb/propose`,
+				compact({ trial_id: flagStr(flags.trial), feedback_ids: flagList(flags.feedback) ?? undefined })
+			);
+			let accepted = null;
+			if (flagBool(flags.accept) && r.rungs[0]) {
+				accepted = await staffRequest(
+					ctx,
+					"POST",
+					`${T}/sessions/${id}/climb/rungs`,
+					compact({
+						parent_trial_id: r.parent_trial_id,
+						name: r.rungs[0].name,
+						settings: r.rungs[0].settings,
+						replay: flagBool(flags["with-replay"]) || undefined,
+						replay_n: flagNum(flags["replay-n"]),
+					})
+				);
+			}
+			if (json) return printResult(io, flags, { ...r, accepted });
+			const lines = [];
+			r.rungs.forEach((rung, i) => {
+				lines.push(`rung ${i + 1}: ${rung.name}`);
+				for (const s of rung.settings)
+					lines.push(`  ${s.plain}  (${s.scope}:${s.dial}; answers ${s.feedback_ids.join(", ") || "—"})`);
+				lines.push(`  changes: ${rung.changes.join("; ")}`);
+			});
+			for (const u of r.unsupported)
+				lines.push(`no setting expresses${u.feedback_id ? ` ${u.feedback_id}` : ""}: ${u.what}`);
+			for (const x of r.rejected) lines.push(`dropped: ${x.dial} (${x.reason})`);
+			if (accepted)
+				lines.push(
+					`accepted as trial ${accepted.trial.id} (${accepted.trial.name}); run ${accepted.runs[0]?.id ?? "—"} queued${accepted.replay_screen_id ? `; replay ${accepted.replay_screen_id}` : ""}`
+				);
+			return io.log(lines.join("\n") || "(nothing proposed)");
+		}
+		case "rung-accept": {
+			const parent = flagStr(flags.parent);
+			const preset = flagStr(flags.preset);
+			const settings = flags.settings ? jsonFlag(flags.settings, "--settings") : undefined;
+			if (!id || !parent || (!preset && !settings))
+				throw new CliError(
+					"Usage: admin tuning rung-accept <session-id> --parent <trial-id> (--preset <key> | --settings '[…]') [--name \"…\"] [--with-replay [--replay-n 4]]"
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/sessions/${id}/climb/rungs`,
+				compact({
+					parent_trial_id: parent,
+					name: flagStr(flags.name),
+					preset,
+					settings,
+					replay: flagBool(flags["with-replay"]) || undefined,
+					replay_n: flagNum(flags["replay-n"]),
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				`rung ${r.trial.id} (${r.trial.name}); run ${r.runs[0]?.id ?? "—"} queued${r.replay_screen_id ? `; replay ${r.replay_screen_id}` : ""}${r.filed.length ? `; ${r.filed.length} feedback filed as config` : ""}`
+			);
+		}
+		case "watches": {
+			if (!id) throw new CliError("Usage: admin tuning watches <run-id>");
+			const r = await staffRequest(ctx, "POST", `${T}/runs/${id}/watches`, {});
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.readings
+					.map(
+						(w) =>
+							`${w.proposal_id}  ${w.verdict}${w.evidence ? `  “${w.evidence.slice(0, 100)}”` : ""}  (${w.method})`
+					)
+					.join("\n") || "(nothing to watch yet)"
+			);
+		}
 		// --- The Write input bank: real kernel requests a session can start from ---
 		case "inputs": {
 			const q = new URLSearchParams(
@@ -2319,7 +2510,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"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)"
+				"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|climb-new|climb|ladder|rung-propose|rung-accept|watches|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.98.0",
+	"version": "0.98.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",