duediligence 0.3.0 → 0.3.1

package/README.md

@@ -7,12 +7,13 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/duediligence"><img src="https://img.shields.io/npm/v/duediligence?style=flat-square&label=npm" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license"></a>
-  <a href="SKILL.md"><img src="https://img.shields.io/badge/Claude_Code-skill-D97757?style=flat-square" alt="Claude Code skill"></a>
+  <a href="skills/duediligence/SKILL.md"><img src="https://img.shields.io/badge/Claude_Code-skill-D97757?style=flat-square" alt="Claude Code skill"></a>
+  <a href="https://skills.sh/lunox-work/duediligence"><img src="https://img.shields.io/badge/skills.sh-npx_skills_add_lunox--work%2Fduediligence-111?style=flat-square" alt="skills.sh"></a>
   <a href="#install"><img src="https://img.shields.io/badge/judges-any_coding_agent-555?style=flat-square" alt="Judges any coding agent"></a>
 </p>
 
 <p align="center">
-  <img src="assets/hero.png" width="100%" alt="Coding agents that report a task complete are wrong 71% of the time (75 of 105). Independent tests cut that to 9% (9 of 105).">
+  <img src="assets/hero.png" width="100%" alt="Coding agents that report a task complete are wrong 71% of the time (75 of 105). duediligence cuts that to 9% (9 of 105).">
 </p>
 
 <table>
@@ -295,18 +296,29 @@ workdir (`bin/backends.mjs`). Windows has no such sandbox: there the file tools'
 deny rules still hold, but a session's shell is held only by the transcript
 audit, which reports any attempt to read the hidden suite. Run sessions under
 WSL2 for an enforced sandbox; judging and handouts need none.
-[SKILL.md](SKILL.md) has the steps as the skill runs them.
+[SKILL.md](skills/duediligence/SKILL.md) has the steps as the skill runs them.
 
 ## Install in full
 
 ```sh
-npx skills add lunox-work/duediligence -g   # the skill, for Claude Code and other agents
-git clone https://github.com/lunox-work/duediligence ~/.claude/skills/duediligence  # or the whole repo
-npx -y duediligence --help                  # the CLI; nothing to clone
+npx skills add lunox-work/duediligence -g   # the skill, for Claude Code, Codex, Cursor and 20+ agents
+npm i -g duediligence                       # the CLI the skill runs
 ```
 
-Either install puts the skill (SKILL.md) in place; it calls the same CLI,
-through `npx` when only SKILL.md was copied. Needs Node 20.19 or later on macOS,
+In Claude Code, the repository is also a plugin marketplace:
+
+```
+/plugin marketplace add lunox-work/duediligence
+/plugin install duediligence@duediligence
+```
+
+The plugin also bundles the `lunox` MCP server, Lunox's hosted platform
+([below](#sign-in-to-the-lunox-platform-optional)): Claude Code asks you to
+sign in on first use (`/mcp`), and signed out the skill runs locally as before.
+
+The skill is the folder [`skills/duediligence/`](skills/duediligence/), which
+also installs by copying it into an agent's skills folder. It runs the CLI at
+the version it names, and asks before installing it when it is missing. Needs Node 20.19 or later on macOS,
 Linux or Windows, and one of: Claude Code signed in, a Codex login, or
 `ANTHROPIC_API_KEY`. The first command that needs the toolchain installs
 `template/`'s dependencies with npm 10.9.2 under `~/.duediligence/`, once.
@@ -319,6 +331,29 @@ Specs, runs and results live in `~/.duediligence/`
 in the package. Every writer and agent session is denied that folder: it holds
 the hidden suites at rest.
 
+## Sign in to the Lunox platform (optional)
+
+Everything above runs on your machine and needs no account. The CLI can also
+sign in to Lunox's hosted platform, where a workspace keeps bounties,
+repositories, sandboxes and runs:
+
+```sh
+duediligence login     # prints a code; approve it in the browser (--open opens it)
+duediligence whoami    # the account, workspace and token expiry
+duediligence logout    # deletes the saved token
+```
+
+`login` uses the device flow: it prints a code, waits while you approve it at
+platform.lunox.work/device, and saves a 90-day workspace token in
+`~/.lunox/credentials` (mode 600; `LUNOX_CREDENTIALS` moves it), a file
+carveout shares. Only a workspace's owners and admins can sign a CLI in to it;
+`--org <handle>` picks the workspace when you have several, and
+`--platform <url>` or `LUNOX_PLATFORM_URL` another deployment. `logout`
+deletes the token here only: the platform has no route for a token to revoke
+itself, so revoke it in the platform's web app to stop it before it expires.
+No other command talks to the platform. In Claude Code, the plugin's `lunox`
+MCP server (`.mcp.json`) signs in on its own, through `/mcp`.
+
 ## Try it in five minutes
 
 `duration-parse` is a prepared example, copied into
@@ -458,11 +493,21 @@ reads the runner's disk and sends it over the network is not stopped.
 <summary>Every file and folder, in the repository and in <code>~/.duediligence/</code></summary>
 
 ```
-SKILL.md            the steps the skill runs
+skills/             the skill, duediligence/SKILL.md: the steps it runs
+.claude-plugin/     the Claude Code plugin and its one-plugin marketplace
+.mcp.json           the plugin's MCP server: lunox, the hosted platform (https://platform.lunox.work/mcp/duediligence)
+scripts/skill.mjs   check the skill, sync its version pins, pack it as a zip
 AGENTS.md           this README's section for coding agents, verbatim
 RESULTS.md          what the method was measured to do
-package.json        the npm package: `duediligence` → bin/cli.mjs
+package.json        the npm package: `duediligence` → bin/cli.mjs; `duediligence/api` → bin/api.mjs
+bin/api.mjs         the library entry: decisionItems, scenarios, diffDecisions, hiddenManifest, hiddenSha256,
+                    calibrate({ skeleton, reference }), verdict(outcomes), promptPath(name); no process, home or
+                    network on import or call (test/api.mjs)
+bin/rules.mjs       the judge's verdict and calibration's filter over suite results, pure
+bin/hash.mjs        the commitment hash of a spec folder or a file map, reading nothing else
 bin/cli.mjs         `duediligence <command>`: runs bin/<command>.mjs; `where`
+bin/platform-client.mjs  the hosted platform: its URL, ~/.lunox/credentials, one fetch-based request with the CLI version
+bin/account.mjs     login (device flow), whoami, logout; bin/login.mjs, whoami.mjs and logout.mjs run them
 evidence/           the experiment's write-ups behind RESULTS.md, vendored
 bin/fit.mjs         whether a repository's package can be a target
 bin/repo.mjs        point a spec at a package: seam, allowed paths, base tree, baseline
@@ -515,6 +560,8 @@ evidence/languages.mjs  Go and Rust modules end to end; commands and services in
   results.jsonl     one line per graded run
   template/<hash>/  template/ with its dependencies, installed on first use
   toolchains/       python-<hash>/ (with .venv), go-<hash>/, rust-<hash>/, built on first use
+
+~/.lunox/credentials  platform tokens after `login`, per platform URL and CLI (shared with carveout; LUNOX_CREDENTIALS)
 ```
 
 A development checkout keeps its own `specs/`, `runs/` and `results.jsonl` with
@@ -530,7 +577,7 @@ A development checkout keeps its own `specs/`, `runs/` and `results.jsonl` with
   <sub>
     <a href="RESULTS.md">RESULTS.md</a> ·
     <a href="AGENTS.md">AGENTS.md</a> ·
-    <a href="SKILL.md">SKILL.md</a> ·
+    <a href="skills/duediligence/SKILL.md">SKILL.md</a> ·
     <a href="https://github.com/lunox-work/duediligence/issues">Issues</a>
   </sub>
 </p>

package/bin/account.mjs

@@ -0,0 +1,262 @@
+// `login`, `whoami` and `logout` against the hosted platform
+// (platform-client.mjs). Each takes its argv and the outside world as
+// `deps`, so test/platform.mjs drives them against a fake platform with no
+// real waiting; bin/login.mjs, whoami.mjs and logout.mjs run them.
+//
+// login is RFC 8628's device flow on the platform's Better Auth:
+//   POST /api/auth/device/code  {client_id}                     → device_code, user_code, verification_uri(_complete), expires_in, interval
+//   POST /api/auth/device/token {grant_type, device_code, client_id} → access_token (a session that may only mint this client's token)
+//   GET  /api/v1/me, GET /api/v1/me/orgs                          (with that session)
+//   POST /api/v1/orgs/:orgId/tokens/cli {client, label}          → { token, secret }: a 90-day lnx_ token; the session ends
+// The token is saved, never printed.
+
+import { spawn } from "node:child_process";
+import { hostname as osHostname } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+
+import { credentialFor, credentialsPath, platformUrl, PlatformError, request, saveCredential } from "./platform-client.mjs";
+
+const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const ADMIN_ROLES = new Set(["owner", "admin"]);
+
+/** The process's own world; tests pass their own. */
+export function defaultDeps() {
+  return {
+    env: process.env,
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    ask: async (question) => {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        return await rl.question(question);
+      } finally {
+        rl.close();
+      }
+    },
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+    fetchImpl: fetch,
+    openUrl,
+    hostname: osHostname,
+  };
+}
+
+/** The OS's browser opener, detached; a failure is only a missed convenience. */
+function openUrl(url) {
+  const [command, args] =
+    process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url]] : ["xdg-open", [url]];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch {
+    // The URL is printed either way.
+  }
+}
+
+/** Whether a held role (Better Auth joins several with commas) may mint a token. */
+const isAdmin = (role) => String(role ?? "").split(",").some((one) => ADMIN_ROLES.has(one.trim()));
+const describe = (org) => `${org.slug} (${org.name}, ${org.role}) ${org.id}`;
+
+function options(argv, spec, usage) {
+  try {
+    return parseArgs({ args: argv, options: { ...spec, help: { type: "boolean", short: "h" } }, allowPositionals: false }).values;
+  } catch (error) {
+    throw new PlatformError(`${error.message}\n${usage}`);
+  }
+}
+
+/** Runs one of the three, printing a PlatformError as one line on stderr. Answers the exit code. */
+export async function run(command, argv, { client, version }, deps = defaultDeps()) {
+  const commands = { login, whoami, logout };
+  try {
+    return await commands[command](argv, { client, version }, deps);
+  } catch (error) {
+    if (!(error instanceof PlatformError)) throw error;
+    deps.err(`${client} ${command}: ${error.message}\n`);
+    return 1;
+  }
+}
+
+/** Picks the workspace to mint in: --org, the only one an owner or admin holds, or a choice on a TTY. */
+async function chooseOrg(orgs, wanted, { client, deps }) {
+  const eligible = orgs.filter((org) => isAdmin(org.role));
+  const listing = (list) => list.map((org) => `  ${describe(org)}`).join("\n");
+  if (wanted !== undefined) {
+    const key = wanted.replace(/^@/, "").toLowerCase();
+    const found = orgs.find((org) => org.id === wanted || org.slug.toLowerCase() === key);
+    if (found === undefined) throw new PlatformError(`No workspace ${wanted} for this account. It has:\n${listing(orgs)}`);
+    if (!isAdmin(found.role)) {
+      throw new PlatformError(`You are ${found.role} in ${found.slug}; only its owners and admins can give ${client} a token.`);
+    }
+    return found;
+  }
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) {
+    throw new PlatformError(
+      orgs.length === 0
+        ? "This account has no workspace yet. Create one in the platform's web app, then run login again."
+        : `You are not an owner or admin of any workspace, and only they can give ${client} a token. This account has:\n${listing(orgs)}`,
+    );
+  }
+  if (!deps.isTTY) {
+    throw new PlatformError(`This account can sign in to ${eligible.length} workspaces; name one with --org <handle|id>:\n${listing(eligible)}`);
+  }
+  deps.out(`\nWorkspaces you can sign ${client} in to:\n${eligible.map((org, i) => `  ${i + 1}. ${describe(org)}`).join("\n")}\n`);
+  for (let tries = 0; tries < 3; tries += 1) {
+    const answer = (await deps.ask(`Workspace [1-${eligible.length}]: `)).trim();
+    const index = Number(answer);
+    if (Number.isInteger(index) && index >= 1 && index <= eligible.length) return eligible[index - 1];
+    const named = eligible.find((org) => org.slug.toLowerCase() === answer.replace(/^@/, "").toLowerCase() || org.id === answer);
+    if (named) return named;
+  }
+  throw new PlatformError("No workspace chosen.");
+}
+
+/** Polls the token endpoint at the server's interval, five seconds slower after each `slow_down`, until approval, denial or expiry. */
+async function pollForSession(base, code, { client, version, deps }) {
+  let interval = Math.max(1, Number(code.interval) || 5) * 1000;
+  const deadline = deps.now() + Math.max(1, Number(code.expires_in) || 900) * 1000;
+  for (;;) {
+    await deps.sleep(interval);
+    if (deps.now() >= deadline) throw new PlatformError("The code expired before it was approved. Run login again.");
+    try {
+      const granted = await request({
+        base,
+        method: "POST",
+        path: "/api/auth/device/token",
+        body: { grant_type: GRANT, device_code: code.device_code, client_id: client },
+        client,
+        version,
+        fetchImpl: deps.fetchImpl,
+      });
+      if (typeof granted.access_token !== "string") throw new PlatformError("The platform approved the sign-in but sent no session.");
+      return granted.access_token;
+    } catch (error) {
+      if (!(error instanceof PlatformError)) throw error;
+      if (error.code === "authorization_pending") continue;
+      if (error.code === "slow_down") {
+        interval += 5000;
+        continue;
+      }
+      if (error.code === "expired_token") throw new PlatformError("The code expired before it was approved. Run login again.");
+      if (error.code === "access_denied") throw new PlatformError("The sign-in was denied in the browser. Nothing was saved.");
+      if (error.code === "invalid_grant") throw new PlatformError("The code is no longer valid (already used, or unknown). Run login again.");
+      throw error;
+    }
+  }
+}
+
+export async function login(argv, { client, version }, deps) {
+  const usage = `usage: ${client} login [--platform <url>] [--org <handle|id>] [--open]`;
+  const values = options(argv, { platform: { type: "string" }, org: { type: "string" }, open: { type: "boolean" } }, usage);
+  if (values.help) {
+    deps.out(
+      `${usage}\n\nSigns ${client} in to the Lunox platform (default ${platformUrl(undefined, {})}; LUNOX_PLATFORM_URL) with a code\n` +
+        `you approve in the browser, and saves a workspace token in ${credentialsPath(deps.env)} (LUNOX_CREDENTIALS).\n` +
+        `--org picks the workspace; --open opens the approval page.\n`,
+    );
+    return 0;
+  }
+  const base = platformUrl(values.platform, deps.env);
+  const call = (options) => request({ base, client, version, fetchImpl: deps.fetchImpl, ...options });
+  const code = await call({ method: "POST", path: "/api/auth/device/code", body: { client_id: client } });
+  if (typeof code.device_code !== "string" || typeof code.user_code !== "string") {
+    throw new PlatformError(`${base} answered the sign-in request without a code.`);
+  }
+  const page = code.verification_uri_complete ?? code.verification_uri ?? `${base}/device`;
+  const minutes = Math.round((Number(code.expires_in) || 900) / 60);
+  deps.out(
+    `To sign ${client} in to ${base}, open this page and approve the code:\n\n  ${page}\n\n` +
+      `  Code: ${code.user_code} (expires in ${minutes} minute${minutes === 1 ? "" : "s"})\n\n`,
+  );
+  if (values.open) deps.openUrl(page);
+  deps.out("Waiting for approval...\n");
+  const session = await pollForSession(base, code, { client, version, deps });
+  const asSession = (options) => call({ token: session, session: true, ...options });
+  let minted;
+  let me;
+  let org;
+  try {
+    me = (await asSession({ path: "/api/v1/me" })).user;
+    const orgs = (await asSession({ path: "/api/v1/me/orgs" })).organizations ?? [];
+    org = await chooseOrg(orgs, values.org, { client, deps });
+    const label = String(deps.hostname() ?? "").trim().slice(0, 60);
+    minted = await asSession({
+      method: "POST",
+      path: `/api/v1/orgs/${encodeURIComponent(org.id)}/tokens/cli`,
+      body: label === "" ? { client } : { client, label },
+    });
+  } catch (error) {
+    // Minting ends the session; a sign-in that stopped short ends it here, best effort.
+    await call({ token: session, session: true, method: "POST", path: "/api/auth/sign-out", body: {} }).catch(() => {});
+    throw error;
+  }
+  if (typeof minted?.secret !== "string" || !minted.secret.startsWith("lnx_")) {
+    throw new PlatformError(`${base} answered without a workspace token.`);
+  }
+  const path = credentialsPath(deps.env);
+  saveCredential(path, base, client, {
+    token: minted.secret,
+    organizationId: org.id,
+    organizationHandle: org.slug,
+    client,
+    createdAt: minted.token?.createdAt ?? new Date(deps.now()).toISOString(),
+    expiresAt: minted.token?.expiresAt ?? null,
+  });
+  const who = me ? `${me.name} <${me.email}>` : "you";
+  const expiry = minted.token?.expiresAt ? `; it expires ${minted.token.expiresAt.slice(0, 10)}` : "";
+  deps.out(`Signed in as ${who}, workspace ${org.name} (@${org.slug}) on ${base}.\nToken saved to ${path}${expiry}.\n`);
+  return 0;
+}
+
+export async function whoami(argv, { client, version }, deps) {
+  const usage = `usage: ${client} whoami [--platform <url>]`;
+  const values = options(argv, { platform: { type: "string" } }, usage);
+  if (values.help) {
+    deps.out(`${usage}\n\nThe account, workspace and token expiry ${client} is signed in with.\n`);
+    return 0;
+  }
+  const base = platformUrl(values.platform, deps.env);
+  const saved = credentialFor(credentialsPath(deps.env), base, client);
+  if (saved === undefined) throw new PlatformError(`Not signed in to ${base}. Run \`${client} login\`.`);
+  const call = (path) => request({ base, token: saved.token, path, client, version, fetchImpl: deps.fetchImpl });
+  const { user } = await call("/api/v1/me");
+  const { organization, role } = await call(`/api/v1/orgs/${encodeURIComponent(saved.organizationId)}`);
+  const expires = saved.expiresAt ? `expires ${saved.expiresAt.slice(0, 10)}` : "does not expire";
+  deps.out(
+    [
+      `user       ${user.name} <${user.email}>${user.username ? ` (@${user.username})` : ""}`,
+      `workspace  ${organization.name} (@${organization.slug}), ${role}`,
+      `platform   ${base}`,
+      `token      ${client}, ${expires}`,
+      "",
+    ].join("\n"),
+  );
+  return 0;
+}
+
+export async function logout(argv, { client }, deps) {
+  const usage = `usage: ${client} logout [--platform <url>]`;
+  const values = options(argv, { platform: { type: "string" } }, usage);
+  if (values.help) {
+    deps.out(`${usage}\n\nDeletes ${client}'s saved token for the platform.\n`);
+    return 0;
+  }
+  const base = platformUrl(values.platform, deps.env);
+  const path = credentialsPath(deps.env);
+  const saved = credentialFor(path, base, client);
+  if (saved === undefined) {
+    deps.out(`Not signed in to ${base}; nothing to do.\n`);
+    return 0;
+  }
+  saveCredential(path, base, client, undefined);
+  // The platform lets no API token revoke itself (token routes take a person's session), so this is local.
+  const until = saved.expiresAt ? `until ${saved.expiresAt.slice(0, 10)}` : "until it is revoked";
+  deps.out(
+    `Signed out of ${base}: the token is deleted from ${path}.\n` +
+      `The platform has no route for a token to revoke itself, so it stays valid ${until} unless an owner or\n` +
+      `admin of @${saved.organizationHandle} revokes it in the platform's web app (the workspace's API tokens).\n`,
+  );
+  return 0;
+}

package/bin/api.mjs

@@ -0,0 +1,73 @@
+// The library entry, `duediligence/api`: the rules and prompts without the
+// session runner, for a platform that runs its own agent loop and evaluator.
+// Every export is a pure function of its arguments, apart from the hash and
+// promptPath reading the files they are pointed at (a spec folder, the
+// package's prompts/). Importing it spawns no process, reads no home folder
+// (DUEDILIGENCE_HOME, HOME) and touches no network: it imports nothing that
+// does (bin/lib.mjs, whose top level seeds a home, least of all).
+// test/api.mjs holds it to that.
+//
+//   decisionItems(specText)                 the `Decided:` items with their Ticket/Instead/Scenarios fields
+//   scenarios(specText)                     the Gherkin scenarios keyed `kind-n`: { key, title, body }
+//   diffDecisions(before, after)            { kept, edited, added, removed } between two lists of decision texts
+//   hiddenManifest(dirOrFiles, kept?)       the commitment manifest of a spec folder or a file map
+//   hiddenSha256(dirOrFiles, kept?)         its sha256: what prepared.json, handouts and seals record
+//   calibrate({ skeleton, reference })      the hidden-test filter: { status, reason, hiddenWritten, kept, dropped }
+//   verdict(outcomes)                       passed | overfit | incomplete | regressed | refused, with counts and failing scenario keys
+//   promptPath(name)                        the absolute path of prompts/<name>.md; anything outside prompts/ refused
+//   renderPrompt(name, values)              prompts/<name>.md with each {{key}} filled from values, as the CLI fills repo/ briefs
+//
+// Suite results are what a runner prints (bin/runners/shared.mjs); the
+// rules' inputs and outputs are documented in bin/rules.mjs, the hash's in
+// bin/hash.mjs.
+
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export { decisionItems, diffDecisions, scenarios } from "./decisions.mjs";
+export { hiddenManifest, hiddenSha256 } from "./hash.mjs";
+export { calibration as calibrate, judgement as verdict } from "./rules.mjs";
+
+const PROMPTS = join(dirname(fileURLToPath(import.meta.url)), "..", "prompts");
+
+/**
+ * The absolute path of a brief under prompts/: `name` is relative with `/`,
+ * with or without `.md` ("spec-from-ticket", "skeleton.md", "repo/hidden-tests").
+ * Throws on an absolute path, `.` or `..` segments, a backslash, a path that
+ * resolves outside prompts/ (through a symlink too) or a file that is not there.
+ */
+export function promptPath(name) {
+  const refuse = (why) => {
+    throw new Error(`promptPath(${JSON.stringify(name)}): ${why}`);
+  };
+  if (typeof name !== "string" || name === "") refuse("a prompt name is a non-empty string");
+  if (name.includes("\0") || name.includes("\\") || isAbsolute(name) || /^[a-zA-Z]:/.test(name))
+    refuse("not a relative path under prompts/");
+  const parts = name.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) refuse("not a relative path under prompts/");
+  const path = join(PROMPTS, ...parts.slice(0, -1), parts.at(-1).endsWith(".md") ? parts.at(-1) : `${parts.at(-1)}.md`);
+  if (!existsSync(path) || !statSync(path).isFile()) refuse("no such prompt");
+  const within = relative(realpathSync(PROMPTS), realpathSync(path));
+  if (within === "" || within.startsWith(`..${sep}`) || within === ".." || isAbsolute(within)) refuse("outside prompts/");
+  return path;
+}
+
+/**
+ * The brief at prompts/`name` (as `promptPath` takes it) with each
+ * `{{key}}` replaced by `values[key]`, the way the CLI fills the repository
+ * briefs from a spec's toolchain.json (bin/lib.mjs `render`), for a
+ * platform that fills them from its own project. Throws when a placeholder
+ * has no value or a value is not a string, so a brief that gains a
+ * placeholder fails loudly at the version that adds it rather than reaching
+ * a model with `{{key}}` in it.
+ */
+export function renderPrompt(name, values) {
+  const path = promptPath(name);
+  if (values === null || typeof values !== "object") throw new Error(`renderPrompt(${JSON.stringify(name)}): values is an object`);
+  return readFileSync(path, "utf8").replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    if (!Object.hasOwn(values, key)) throw new Error(`renderPrompt(${JSON.stringify(name)}): no value for {{${key}}}`);
+    if (typeof values[key] !== "string") throw new Error(`renderPrompt(${JSON.stringify(name)}): {{${key}}} is not a string`);
+    return values[key];
+  });
+}

package/bin/calibrate.mjs

@@ -50,6 +50,7 @@ import {
   workdir,
   writeJson,
 } from "./lib.mjs";
+import { calibration } from "./rules.mjs";
 
 const failing = (result) => [
   ...result.files.filter((file) => file.crashed).map((file) => `${file.file} :: (file crashed)`),
@@ -72,9 +73,8 @@ async function calibrate(slug) {
     throw new Error(`${slug}: baseline.json is not the run on base plus stub; run generate first.`);
   for (const part of ["tests/public", "tests/private"])
     if (!existsSync(join(out, part))) throw new Error(`${slug}: no ${part}; run generate first.`);
-  const dropped = [];
 
-  // The skeleton: every hidden test fails, and fails inside its test.
+  // The skeleton: every hidden test fails, and fails inside its test (the rule: rules.mjs `calibration`).
   const skeletonDir = stage(workdir(`${slug}-calibrate`), slug, {
     skeleton: true,
     publicTests: true,
@@ -83,19 +83,10 @@ async function calibrate(slug) {
   const onSkeleton = runSuite(skeletonDir, "private", chain);
   const publicOnSkeleton = runSuite(skeletonDir, "public", chain);
   discard(skeletonDir);
-  if (!onSkeleton.compiled)
-    return {
-      slug,
-      status: "dropped",
-      reason: "The hidden suite does not compile against the skeleton.",
-      compileOutput: onSkeleton.compileOutput,
-    };
-  for (const file of onSkeleton.files)
-    if (file.crashed)
-      dropped.push({ id: `${file.file} :: *`, reason: "The file crashes on the skeleton instead of failing a test." });
-  for (const test of testsOf(onSkeleton))
-    if (test.ok || test.skipped)
-      dropped.push({ id: test.id, reason: test.skipped ? "Skipped." : "Passes on the skeleton." });
+  if (!onSkeleton.compiled) {
+    const { status, reason, compileOutput } = calibration({ skeleton: onSkeleton });
+    return { slug, status, reason, compileOutput };
+  }
 
   // The reference: a fourth session that sees both suites.
   const dir = stage(workdir(`${slug}-reference`), slug, {
@@ -160,37 +151,19 @@ async function calibrate(slug) {
   discard(snapshot);
   discard(dir);
 
-  const droppedIds = new Set(dropped.map((item) => item.id));
-  const droppedFiles = new Set(
-    dropped.filter((item) => item.id.endsWith(" :: *")).map((item) => item.id.slice(0, -5)),
-  );
-  const referenceTests = new Map(testsOf(judged.hidden).map((test) => [test.id, test]));
-  const hiddenIds = testsOf(onSkeleton).map((test) => test.id);
-  for (const id of hiddenIds) {
-    if (droppedIds.has(id)) continue;
-    const test = referenceTests.get(id);
-    if (test === undefined || !test.ok)
-      dropped.push({
-        id,
-        reason: `The reference cannot satisfy it: ${test?.error?.message.split("\n")[0] ?? "it did not run"}`,
-      });
-  }
-  const finalDropped = new Set(dropped.map((item) => item.id));
-  const kept = hiddenIds.filter(
-    (id) => !finalDropped.has(id) && !droppedFiles.has(id.split(" :: ")[0]),
-  );
+  const { status, reason, hiddenWritten, kept, dropped } = calibration({ skeleton: onSkeleton, reference: judged.hidden });
   const publicIds = testsOf(judged.public).map((test) => test.id);
   const publicFailing = failing(judged.public);
   const notes = sessions.at(-1).finalText.trim().split("\n").slice(-20).join("\n");
   const record = {
     slug,
-    status: kept.length > 0 ? "ok" : "dropped",
-    reason: kept.length > 0 ? null : "No hidden test survived calibration.",
+    status,
+    reason,
     publicIds,
     publicOnSkeleton: count(publicOnSkeleton, publicIds),
     publicFailingOnReference: publicFailing,
     ...(repo ? { referenceRegressions: regressions } : {}),
-    hiddenWritten: hiddenIds.length,
+    hiddenWritten,
     kept,
     dropped,
     reference: {
@@ -205,7 +178,7 @@ async function calibrate(slug) {
   };
   log(
     slug,
-    `kept ${kept.length}/${hiddenIds.length} hidden, dropped ${dropped.length}; reference public ${record.reference.public.passed}/${record.reference.public.total}`,
+    `kept ${kept.length}/${hiddenWritten} hidden, dropped ${dropped.length}; reference public ${record.reference.public.passed}/${record.reference.public.total}`,
     publicFailing.length > 0 ? `, ${publicFailing.length} PUBLIC FAILING ON REFERENCE` : "",
     regressions.length > 0 ? `, ${regressions.length} REFERENCE REGRESSION(S)` : "",
   );

package/bin/cli.mjs

@@ -30,6 +30,9 @@ const COMMANDS = {
   ci: "judge a commit from a seal and report it as a check (GitHub Actions or anywhere)",
   referee: "a blind referee of rejected runs' failing tests, on any backend (--backend)",
   "red-team-audit": "red-team passes (run --brief red-team) audited: literals, a second suite, a session",
+  login: "sign in to the Lunox platform (device code in the browser); --org, --platform, --open",
+  whoami: "the account, workspace and token expiry signed in with",
+  logout: "delete the saved platform token",
 };
 
 const [command, ...rest] = process.argv.slice(2);
@@ -53,6 +56,8 @@ if (!Object.hasOwn(COMMANDS, command ?? "")) {
       "",
       "Each command prints its own usage when called without arguments.",
       "Data: DUEDILIGENCE_HOME (default ~/.duediligence/).",
+      "Platform sign-in (optional; every other command is local): ~/.lunox/credentials (LUNOX_CREDENTIALS),",
+      "against https://platform.lunox.work (LUNOX_PLATFORM_URL).",
     ].join("\n"),
   );
   process.exit(command === undefined || command === "help" || command === "--help" ? 0 : 1);

package/bin/commitment.mjs

@@ -5,28 +5,9 @@
 // refuses on a mismatch, bin/promote.mjs prints it at reveal, and a seal
 // (bin/seal.mjs) carries it in seal.json.
 //
-// What is hashed, from a folder laid out as specs/<slug>/ (or an unpacked
-// seal): a manifest of lines in `sha256sum` format, `<hex>  <path>\n`,
-//   - one per file under tests/private/, every depth, `.DS_Store` skipped,
-//     sorted by the UTF-8 bytes of the path: the hex the sha256 of its
-//     bytes, the path `tests/private/<rel>` with `/` separators;
-//   - then one line for the kept test ids: the hex the sha256 of
-//     JSON.stringify(calibration.kept sorted) (UTF-8), the path
-//     `calibration.kept`;
-//   - only for a spec at a black-box seam, a last line for what the suites
-//     call (toolchain.json `boundary`: the command, or the service's start,
-//     healthcheck and build), since changing it changes what the hidden
-//     suite tests: the hex the sha256 of its JSON with keys sorted at every
-//     level, the path `toolchain.boundary`. A spec without one hashes as
-//     before.
-// hiddenSha256 is the sha256 of the manifest's UTF-8 bytes, lowercase hex.
-// By hand:
-//   (cd specs/<slug> && find tests/private -type f ! -name .DS_Store | LC_ALL=C sort | xargs shasum -a 256
-//    && printf '%s  calibration.kept\n' "$(jq -cj '.kept | sort' calibration.json | shasum -a 256 | cut -c1-64)"
-//    && printf '%s  toolchain.boundary\n' "$(jq -cjS '.boundary' toolchain.json | shasum -a 256 | cut -c1-64)") | shasum -a 256
-// (the last printf only when toolchain.json has a boundary)
-// (jq sorts by code point and JS by UTF-16 unit; the two agree unless an id
-// holds characters beyond the BMP.)
+// What is hashed, and how to compute it by hand: bin/hash.mjs, which
+// computes it from a folder or from files in memory and reads nothing else
+// (the library entry, bin/api.mjs, exports it).
 //
 // Specs prepared before the hash existed have no commitment in
 // prepared.json. Their first handout records one there (`hiddenRecordedBy:
@@ -35,35 +16,11 @@
 // without checking it. A repository handout's own handout.json is checked
 // too, so a change after the handout is refused even then.
 
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { join, sep } from "node:path";
-import { listFiles, readJson, specDir, writeJson } from "./lib.mjs";
+import { join } from "node:path";
+import { hiddenSha256 } from "./hash.mjs";
+import { readJson, specDir, writeJson } from "./lib.mjs";
 
-const sha = (data) => createHash("sha256").update(data).digest("hex");
-const byBytes = (a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path));
-/** A JSON value with every object's keys sorted, as `jq -S` writes it. */
-const sorted = (value) =>
-  Array.isArray(value)
-    ? value.map(sorted)
-    : value !== null && typeof value === "object"
-      ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]))
-      : value;
-
-/** The manifest hiddenSha256 is the hash of (see above). */
-export function hiddenManifest(dir, kept = readJson(join(dir, "calibration.json"), {}).kept ?? []) {
-  const hidden = join(dir, "tests", "private");
-  const lines = listFiles(hidden, [])
-    .filter((rel) => rel.split(sep).at(-1) !== ".DS_Store")
-    .map((rel) => ({ path: `tests/private/${rel.split(sep).join("/")}`, hex: sha(readFileSync(join(hidden, rel))) }));
-  lines.sort(byBytes).push({ path: "calibration.kept", hex: sha(JSON.stringify([...kept].sort())) });
-  const boundary = readJson(join(dir, "toolchain.json"), {}).boundary;
-  if (boundary !== undefined) lines.push({ path: "toolchain.boundary", hex: sha(JSON.stringify(sorted(boundary))) });
-  return lines.map((line) => `${line.hex}  ${line.path}\n`).join("");
-}
-
-/** The commitment hash of the hidden suite in `dir` (specs/<slug>/ or an unpacked seal). */
-export const hiddenSha256 = (dir, kept) => sha(hiddenManifest(dir, kept));
+export { hiddenManifest, hiddenSha256 } from "./hash.mjs";
 
 /**
  * The spec's recorded commitment against its hidden suite now: `ok` false