@stage5/lumine 0.3.24 → 0.3.25

package/README.md

@@ -81,6 +81,17 @@ pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner
 can merge or replace main from Twinkle.
 
+For an exact source review of the live app, use `lumine pull <build-id>
+--published` in a persistent review folder. This checks out the requested
+build's published artifact read-only; `--main` explicitly selects its root
+project. It never substitutes the latest draft or creates a contribution
+branch. The CLI checks the publication pointer again before writing and
+refuses a concurrent publication; modified local files are stashed before a
+successful checkout. It requires the API's published-version selector to be
+deployed first. `--published` and `--version <n>` are mutually exclusive.
+`lumine admin builds review` already reviews the published app; unsupported
+selectors such as `--mode` or `--review-mode` fail instead of being ignored.
+
 Use `lumine branches <build-url-or-id>` to list the contribution branches you
 can review, including each contributor, branch number, status, and URL. Then use
 `lumine diff <branch-url>` to inspect one branch.

package/lib/admin.js

@@ -3264,6 +3264,16 @@ export function parseAdminOperation(options) {
         {
           status: parseTodoStatus(options.adminStatus),
           note,
+          ...(options.todoWorkflowFile
+            ? {
+                workflow: readAdminJsonFile(options.todoWorkflowFile),
+                expectedRevision: parseRequiredInteger(
+                  options.followupRevision,
+                  "--revision",
+                  1,
+                ),
+              }
+            : {}),
         },
       );
     }
@@ -7249,6 +7259,14 @@ function printTodoItems(items, heading) {
       `  #${todo.id} ${String(todo.status || "open").toUpperCase()} ${todo.kind || "task"} — ${todo.title || "(untitled)"}`,
     );
     if (todo.details) console.log(`    ${todo.details}`);
+    if (todo.workflow) {
+      const w = todo.workflow;
+      console.log(`    Implementation: ${w.implementation}; release: ${w.release}; verification: ${w.verification}`);
+      if (w.fixRef) console.log(`    Fix: ${w.fixRef}`);
+      if (w.releaseRef) console.log(`    Release: ${w.releaseRef}`);
+      if (w.evidence) console.log(`    Evidence: ${w.evidence}`);
+      if (w.nextAction) console.log(`    Next: ${w.nextAction}`);
+    }
     if (todo.lastProgressNote) {
       console.log(`    Latest progress: ${todo.lastProgressNote}`);
     }

package/lib/commands.js

@@ -943,6 +943,8 @@ export async function selectProject(options) {
 }
 
 export async function pull(options) {
+  if (options.pullPublished && options.versionProvided)
+    throw new Error("Choose --published or --version, not both.");
   if (options.versionProvided && !(options.pullVersion > 0)) {
     throw new Error(
       "Pass a save number: `lumine pull --version <n>` (run `lumine versions` to see save numbers).",
@@ -962,7 +964,7 @@ export async function pull(options) {
     auth,
     buildId: requestedBuildId,
   });
-  if (options.pullVersion > 0) {
+  if (options.pullPublished || options.pullVersion > 0) {
     await pullVersionBuildFiles({ options, auth, build: selectedBuild });
     return;
   }
@@ -1830,10 +1832,10 @@ export async function pullMainBuildFiles({ options, auth, build }) {
 }
 
 // Read-only checkout of ONE previous save (`lumine pull --version <n>`).
-// Without --main it targets the build the workspace edits (your branch on team
-// projects); with --main it targets the team project's main history.
+// Numeric saves target the editable workspace branch unless --main is given.
+// --published reads the named Build directly; --main selects the project root.
 export async function pullVersionBuildFiles({ options, auth, build }) {
-  const versionNumber = options.pullVersion;
+  const versionNumber = options.pullPublished ? "published" : options.pullVersion;
   let targetBuild = build;
   if (options.pullMain) {
     const rootBuildId =
@@ -1842,7 +1844,7 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
       rootBuildId === Number(build?.id || 0)
         ? build
         : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
-  } else {
+  } else if (!options.pullPublished) {
     targetBuild = await resolveEditableWorkspaceBuild({
       options,
       auth,
@@ -1856,6 +1858,27 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
     buildId,
     versionNumber,
   });
+  if (options.pullPublished) {
+    const expected = Number(result.build?.publishedArtifactVersionId || 0);
+    if (
+      !expected ||
+      Number(result.version?.versionId) !== expected ||
+      !result.build?.isPublic
+    ) {
+      throw new Error(
+        "The API did not return the exact published artifact; update the API before using --published.",
+      );
+    }
+    const current = await loadBuildMetadata({ options, auth, buildId });
+    if (
+      !current.isPublic ||
+      Number(current.publishedArtifactVersionId) !== expected
+    ) {
+      throw new Error(
+        "The published version changed during checkout. Retry; no local files were changed.",
+      );
+    }
+  }
   const resolvedBuild = result.build || targetBuild;
   const version = result.version || { version: versionNumber };
   const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
@@ -1879,6 +1902,7 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
           ? path.join(path.dirname(enclosing.rootDir), dirName)
           : dirName),
   );
+  await stashLocalProjectFilesBeforePull({ dir, files });
   await writeProjectFiles({ dir, files });
   if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
     await removeLocalProjectFilesNotIn({ dir, files });
@@ -2422,6 +2446,7 @@ export function parseArgs(args) {
     "open",
     "noDescription",
     "publish",
+    "published",
     "save",
     "force",
     "noUpdateCheck",
@@ -2491,6 +2516,35 @@ export function parseArgs(args) {
     }
   }
 
+  if (
+    command === "admin" &&
+    positional[0] === "builds" &&
+    positional[1] === "review"
+  ) {
+    const allowed = new Set([
+      "help",
+      "output",
+      "outputDir",
+      "dir",
+      "waitMs",
+      "interact",
+      "browserPath",
+      "json",
+      "apiUrl",
+      "siteUrl",
+      "authFile",
+      "authToken",
+      "clientName",
+      "timeoutMs",
+      "noUpdateCheck",
+    ]);
+    for (const key of Object.keys(raw)) {
+      if (!allowed.has(key))
+        throw new Error(
+          `Unsupported Build review option --${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}. Runtime review already uses the published app; use pull --published for its source.`,
+        );
+    }
+  }
   const suggestionInboxActions = new Set([
     "list",
     "merge",
@@ -2593,6 +2647,7 @@ export function parseArgs(args) {
     adminSeverity: raw.severity ? String(raw.severity) : "",
     adminStatus: raw.status ? String(raw.status) : "",
     followupRevision: raw.revision ? String(raw.revision) : "",
+    todoWorkflowFile: raw.workflow ? String(raw.workflow) : "",
     adminDecision: raw.decision ? String(raw.decision) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
@@ -2808,6 +2863,7 @@ export function parseArgs(args) {
     clientName: String(raw.clientName || "Lumine CLI").slice(0, 120),
     dir: raw.dir ? String(raw.dir) : "",
     pullMain: parseBoolean(raw.main, false),
+    pullPublished: parseBoolean(raw.published, false),
     // Strict: only a plain positive integer counts. Anything else (missing
     // value, "foo", a swallowed flag like "--main", "2.5") stays 0 and the
     // consuming command must reject it via versionProvided instead of
@@ -3067,6 +3123,7 @@ export function printHelp() {
   lumine pull [twinkle-build-url]
   lumine pull [twinkle-build-url] --main
   lumine pull [twinkle-build-url] --version <n> [--main]
+  lumine pull [twinkle-build-url] --published [--main]
   lumine versions [twinkle-build-url] [--main] [--limit <n>]
   lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
@@ -3117,7 +3174,7 @@ export function printHelp() {
   lumine admin escalation set <audit-id> --status open|acknowledged|resolved --note <decision> [--json]
   lumine admin todo list [--status pending|open|in_progress|blocked|completed|cancelled|all] [--limit <number>] [--json]
   lumine admin todo add --title <title> --note <handoff-and-acceptance-criteria> [--kind task|experiment] [--status open|in_progress|blocked] [--json]
-  lumine admin todo update <todo-id> --status open|in_progress|blocked|completed|cancelled --note <progress-or-evidence> [--json]
+  lumine admin todo update <todo-id> --status open|in_progress|blocked|completed|cancelled --note <progress-or-evidence> [--workflow <file.json> --revision <n>] [--json]
   lumine admin sponsor applications list [--status pending|approved|rejected|withdrawn] [--json]
   lumine admin sponsor applications review <application-id> --decision approve|reject [--note <text>] [--json]
   lumine admin sponsor status set <user-id> --status probationary|trusted|suspended|revoked [--note <text>] [--json]
@@ -3280,6 +3337,7 @@ Options:
   --no-review-loop      Skip the evidence-based post-run loop retrospective
   --target <build>      Explicit Build URL or ID for rename/describe/upgrade
   --main                With pull/versions/restore: target the team project's main
+  --published           With pull: exact currently published artifact, read-only
   --version <n>         With pull: read-only checkout of previous save v<n>
   --title <text>        Build title for new/rename, or private todo title
   --description <text>  Build description for new/describe

package/lib/math-lab-build-sheet.js

@@ -0,0 +1,133 @@
+// Merges parts/<level>.json into the private question sheet the Math Lab
+// uploads with `lumine rewards sheet`, then validates the sheet against the
+// workspace's rewards.json exactly the way the server will (same code).
+// Usage: node --import tsx build-sheet.mjs --approved-review <live review id>
+// Reads that review afresh and preserves its questions before writing output.
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  LEVELS,
+  verifyApprovedPrefix,
+  verifyRewardEconomy,
+} from "./math-lab-preservation.js";
+
+export async function buildMathLabSheet({
+  contentDir,
+  args = process.argv.slice(2),
+}) {
+  const here = path.resolve(contentDir);
+  const parts = path.join(here, "parts");
+  if (
+    args.length !== 2 ||
+    args[0] !== "--approved-review" ||
+    !/^[1-9]\d*$/.test(args[1])
+  ) {
+    throw new Error(
+      "Usage: node --import tsx build-sheet.mjs --approved-review <current live review id>. No sheet was written.",
+    );
+  }
+  const cli = fileURLToPath(new URL("../bin/lumine.js", import.meta.url));
+  const approved = JSON.parse(
+    execFileSync(
+      process.execPath,
+      [
+        cli,
+        "admin",
+        "reward-review",
+        "show",
+        args[1],
+        "--json",
+        "--no-update-check",
+      ],
+      {
+        encoding: "utf8",
+        timeout: 60000,
+        maxBuffer: 16 * 1024 * 1024,
+      },
+    ),
+  );
+  const sheet = { rules: {} };
+  const missing = [];
+  for (const level of LEVELS) {
+    const file = path.join(parts, `${level}.json`);
+    if (!fs.existsSync(file)) {
+      missing.push(level);
+      continue;
+    }
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    sheet.rules[`${level}-daily`] = {
+      sets: data.sets.map((set) => ({
+        key: set.key,
+        questions: set.questions.map((q) => ({
+          prompt: q.prompt,
+          answer: q.answer,
+          ...(q.hint ? { hint: q.hint } : {}),
+          ...(q.guide ? { guide: q.guide } : {}),
+        })),
+      })),
+    };
+  }
+  const out = path.resolve(here, "..", "math-lab-sheet.json");
+  if (missing.length)
+    throw new Error(
+      `Missing grade parts: ${missing.join(", ")}. No sheet was written.`,
+    );
+  const preservation = verifyApprovedPrefix(sheet, approved);
+
+  // Server-identical validation: rewards.json + sheet → approved-shape config.
+  const policy = await import(
+    pathToFileURL(
+      path.resolve(
+        here,
+        "..",
+        "..",
+        "twinkle-api",
+        "helpers",
+        "build",
+        "rewardsPolicy.ts",
+      ),
+    ).href
+  );
+  const declared = JSON.parse(
+    fs.readFileSync(
+      path.resolve(here, "..", "math-lab", "rewards.json"),
+      "utf8",
+    ),
+  );
+  const composed = policy.composeRewardConfig({ declared, sheet });
+  if (composed.errors.length) {
+    for (const error of composed.errors) console.log(`- ${error}`);
+    process.exit(1);
+  }
+  verifyRewardEconomy(composed.config, approved);
+  const total = composed.config.rules.reduce(
+    (sum, rule) => sum + (rule.sets || []).length,
+    0,
+  );
+  // Nothing replaces the prior usable sheet until every check succeeds.
+  const output = JSON.stringify(sheet, null, 1) + "\n";
+  fs.writeFileSync(`${out}.next`, output, { mode: 0o600 });
+  fs.renameSync(`${out}.next`, out);
+  fs.writeFileSync(
+    `${out}.preservation.json`,
+    JSON.stringify(
+      {
+        ...preservation,
+        checkedAt: new Date().toISOString(),
+        sha256: createHash("sha256").update(output).digest("hex"),
+      },
+      null,
+      2,
+    ) + "\n",
+    { mode: 0o600 },
+  );
+  console.log(
+    `wrote ${out}; preserved ${preservation.rules.reduce((n, r) => n + r.preserved, 0)} published questions from review ${preservation.liveReview}`,
+  );
+  console.log(
+    `composed OK: ${composed.config.rules.length} rules, ${total} sets, ${Buffer.byteLength(JSON.stringify(sheet))} bytes`,
+  );
+}

package/lib/math-lab-preservation.js

@@ -0,0 +1,105 @@
+import { isDeepStrictEqual } from "node:util";
+
+export const LEVELS = [
+  "e1",
+  "e2",
+  "e3",
+  "e4",
+  "e5",
+  "e6",
+  "m1",
+  "m2",
+  "m3",
+  "h1",
+  "h2",
+  "h3",
+];
+
+export function verifyRewardEconomy(config, response) {
+  const withoutRefillSets = (value) => ({
+    ...value,
+    rules: value.rules.map((rule) => {
+      if (!LEVELS.some((level) => rule.id === `${level}-daily`)) return rule;
+      const { sets: _sets, ...economy } = rule;
+      return economy;
+    }),
+  });
+  if (
+    !isDeepStrictEqual(
+      withoutRefillSets(config),
+      withoutRefillSets(response.data.review.config),
+    )
+  ) {
+    throw new Error(
+      "A refill must preserve the approved reward rules and budgets. Review any economy change separately.",
+    );
+  }
+}
+
+// Refill-only: edits/removals to existing questions need a separate content review.
+export function verifyApprovedPrefix(sheet, response) {
+  const review = response?.data?.review;
+  const artifact = Number(review?.publishedArtifactVersionId);
+  if (
+    response?.ok !== true ||
+    Number(review?.buildId) !== 2460 ||
+    review?.status !== "approved" ||
+    review?.isLive !== true ||
+    !Number.isSafeInteger(artifact) ||
+    artifact <= 0 ||
+    Number(review?.publishedVersionId) !== artifact
+  ) {
+    throw new Error(
+      "A fresh, live, approved Math Lab review is required. Re-read the current reward review.",
+    );
+  }
+  const rules = review.config?.rules;
+  if (!Array.isArray(rules))
+    throw new Error("The approved review has no question rules.");
+  const result = [];
+  for (const level of LEVELS) {
+    const id = `${level}-daily`;
+    const matches = rules.filter((rule) => rule.id === id);
+    const before = matches[0]?.sets;
+    const after = sheet?.rules?.[id]?.sets;
+    if (
+      matches.length !== 1 ||
+      !Array.isArray(before) ||
+      !before.length ||
+      !Array.isArray(after)
+    ) {
+      throw new Error(
+        `${id}: missing or ambiguous approved questions or candidate grade.`,
+      );
+    }
+    if (after.length < before.length)
+      throw new Error(
+        `${id}: candidate loses ${before.length - after.length} approved questions.`,
+      );
+    for (let i = 0; i < before.length; i++) {
+      if (!isDeepStrictEqual(after[i], before[i])) {
+        throw new Error(
+          `${id}: approved question ${before[i].key || i + 1} changed or moved. Sync the canonical sheet before refilling.`,
+        );
+      }
+    }
+    const keys = after.map((set) => set.key);
+    if (
+      keys.some((key) => typeof key !== "string" || !key.trim()) ||
+      new Set(keys).size !== keys.length
+    ) {
+      throw new Error(`${id}: question keys must be present and unique.`);
+    }
+    result.push({
+      rule: id,
+      preserved: before.length,
+      added: after.length - before.length,
+    });
+  }
+  return {
+    liveReview: Number(review.id),
+    artifactVersionId: artifact,
+    preservedExact: true,
+    rules: result,
+  };
+}

package/lib/workspace.js

@@ -738,6 +738,8 @@ export async function writeVersionCheckoutMetadata({
         readOnly: true,
         versionCheckout: true,
         checkoutVersion: Number(version?.version || 0) || null,
+        checkoutArtifactVersionId: Number(version?.versionId || 0) || null,
+        publishedCheckout: options.pullPublished === true,
         checkoutVersionSummary: version?.summary || null,
         checkoutVersionCreatedAt: Number(version?.createdAt || 0) || null,
         build: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -1737,6 +1737,35 @@ audit path: canonical todo state and its private `todo.create` / `todo.update`
 audit response commit together, and no public bot, public mutation count, or
 rotation signal is involved.
 
+Track implementation, release and verification separately when a carryover
+involves a fix. After `add-admin-todo-workflow.sql` and the matching API are
+deployed, save a local JSON file such as:
+
+```json
+{
+  "implementation": "ready",
+  "release": "pending",
+  "verification": "pending",
+  "fixRef": "work/topic/release-review.md",
+  "releaseRef": "",
+  "evidence": "Focused regression passed; production is unchanged.",
+  "nextAction": "Deployer releases the reviewed fix, then check the live result."
+}
+```
+
+Use `lumine admin todo update 12 --revision <current-revision> --workflow
+work/topic/workflow.json --status in_progress --note "Ready for the deployer."
+--json`. The revision comes from the canonical list/update response; stale
+updates are rejected. Implementation values are `needed`, `in_progress`,
+`ready`, `not_needed`; release is `pending`, `live`, `not_needed`; verification
+is `pending` or `passed`. Any unfinished phase needs a concrete `nextAction`;
+passed verification needs `evidence`. Completion requires implementation ready
+(or unnecessary), release live (or unnecessary), and verification passed.
+Keep physical-device checks and observation windows pending until they happen.
+Legacy todos have `workflow: null`, which means unknown, never verified. An
+update without `--workflow` preserves an existing workflow and cannot bypass
+its completion requirements.
+
 Every successful full `daily-run start` response automatically includes all
 unfinished items under `data.carryoverTodos`. The same run ID increments an
 item's surfacing telemetry at most once, even when start is retried. This is the