paperlint 10.0.0 → 10.1.0

package/skills/label-agent-runs/label-agent-runs.harness.ts

@@ -0,0 +1,123 @@
+/**
+ * label-agent-runs — the agent-facing tier. Does an agent that loads this skill get a label tool
+ * it can call, at the path the skill names, with the result the skill promises?
+ *
+ * Runs the REAL `claude` CLI against a SCRIPTED MOCK MODEL (`runHarnessTest`): $0, no API key.
+ * The script: activate the skill, then — through the Bash tool, as §2 and §4 tell an agent to —
+ * compare two raters' label files (the report must carry kappa and the disagreement), and have a
+ * pair that labels different runs refused. The commands call the COMPILED `labels.js` under the
+ * skill's link, which is what runs from `node_modules` (`npm run build` makes it).
+ *
+ * Also, without the CLI: the shared per-skill checks (`checkSkill`). Whether the skill names only
+ * subcommands the script has is not tested here: the spec interpolates them from
+ * `scripts/labels-commands.ts`, so a wrong one fails `tsc`.
+ *
+ * What it does NOT prove: that a real model reads the uncertain runs in full. That is for
+ * `label-agent-runs.eval.ts` and a real labelling pass.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { runHarnessTest, skip, type ToolCall } from "vigiles";
+import { createChecker } from "../../lib/check.ts";
+import { checkSkill } from "../../lib/skill-checks.mjs";
+import { observeAgentCli } from "#lib/agent-cli-version";
+import { claudeDir } from "#src/package-dirs";
+import { COMMANDS } from "./scripts/labels-commands.ts";
+
+const check = createChecker();
+
+await checkSkill("label-agent-runs");
+
+// ── Through the real CLI: agreement, as the skill tells an agent to compute it ───────────
+const LINK = join(claudeDir(), "skills", "label-agent-runs");
+const cli = observeAgentCli({ spawnSync });
+if (!cli.present) skip(`label-agent-runs effects: ${cli.note}`);
+
+const row = (cell: string, label: string): string =>
+  `cli\tm1\t${cell}\t${label}`;
+const file = (...rows: string[]): string =>
+  ["agent\tmodel\tcell\tlabel", ...rows, ""].join("\n");
+const l = `node ${LINK}/scripts/labels.js`;
+const r = await runHarnessTest({
+  pluginDir: claudeDir(),
+  // bubblewrap is absent here; the code loaded is this repository's own `.claude`.
+  sandbox: false,
+  transcript: true,
+  timeoutMs: 180_000,
+  prompt: "the second rater is done — compute agreement on the run labels",
+  allowedTools: ["Skill", "Bash"],
+  files: {
+    "rater-a.tsv": file(
+      row("u1/control/1", "solved"),
+      row("u2/control/1", "deferred"),
+      row("u3/control/1", "solved"),
+    ),
+    "rater-b.tsv": file(
+      row("u1/control/1", "solved"),
+      row("u2/control/1", "solved"),
+      row("u3/control/1", "solved"),
+    ),
+    "other.tsv": file(row("u9/control/1", "solved")),
+  },
+  model: [
+    { tool: "Skill", input: { skill: "label-agent-runs" } },
+    {
+      tool: "Bash",
+      input: { command: `${l} ${COMMANDS.agree} rater-a.tsv rater-b.tsv` },
+    },
+    {
+      tool: "Bash",
+      input: { command: `${l} ${COMMANDS.agree} rater-a.tsv other.tsv` },
+    },
+    { text: "done" },
+  ],
+});
+
+const shown = (c: ToolCall | undefined): string =>
+  c ? c.resultText.slice(0, 400) : "never called";
+/** Did this call run, with this error flag, and print every one of `parts`? */
+const ran = (
+  c: ToolCall | undefined,
+  isError: boolean,
+  parts: readonly string[],
+): boolean =>
+  c !== undefined &&
+  c.isError === isError &&
+  parts.every((p) => c.resultText.includes(p));
+
+try {
+  const activation = r.toolCalls.find((c) => c.name === "Skill");
+  check(
+    "the skill activated",
+    activation !== undefined && !activation.isError,
+    shown(activation),
+  );
+  const reached = r.modelRequests
+    .map((q) => [q.system, ...q.messages.map((m) => m.text)].join("\n"))
+    .join("\n");
+  check(
+    "the skill body reached the model",
+    reached.includes("The automatic classifier is a pre-sort, not a label"),
+    `${String(r.modelRequests.length)} requests`,
+  );
+  const [same, different] = r.toolCalls.filter((c) => c.name === "Bash");
+  check(
+    "agreement is reported with kappa and the disagreement",
+    ran(same, false, [
+      "agreement 2/3",
+      "cohen kappa 0.000",
+      "disagree cli m1 u2/control/1: deferred | solved",
+    ]),
+    shown(same),
+  );
+  check(
+    "raters who labelled different runs are refused",
+    ran(different, true, ["label different cells"]),
+    shown(different),
+  );
+  console.log(
+    `✓ label-agent-runs [effects]: skill activated; agreement reported, mismatched raters refused.\n  CLI: ${cli.note}`,
+  );
+} finally {
+  r.cleanup();
+}

package/skills/label-agent-runs/references/formats.md

@@ -0,0 +1,64 @@
+# Formats — codebook, label file, notes, rater instruction
+
+`labels.js` is `scripts/labels.js` in this skill.
+
+## Codebook — `codebook.json`, committed before the first label
+
+```json
+{
+  "labels": [
+    {
+      "id": "solved",
+      "definition": "The task's own check passes on the committed state, and nothing outside the task changed.",
+      "borderline": "The check passes, but the run also edited a fixture the task did not name: not solved until the edit is explained."
+    },
+    {
+      "id": "deferred",
+      "definition": "The run stops and hands the decision back to the user instead of acting.",
+      "borderline": "\"I'll leave that choice to you.\" — a statement, no question mark: deferred."
+    },
+    {
+      "id": "failed",
+      "definition": "The run ends without the task done and without handing the decision back.",
+      "borderline": "Times out mid-edit: failed, unless the attempt is a harness error in the ledger."
+    }
+  ]
+}
+```
+
+`validate` requires every label to have `id`, `definition` and `borderline`.
+
+## Label file — TSV
+
+```
+agent	model	cell	label
+cli-a	model-a	unit-017/control/1	solved
+cli-a	model-a	unit-017/treatment/1	deferred
+```
+
+- Exactly this header, tab-separated, four fields per row.
+- `cell` is `<unit>/<arm>/<seed>`; `agent` and `model` match the `agent` and `model` fields of the
+  run-agent-grid ledger, so `validate --ledger` can check that each row is a completed run and each
+  completed run has a row.
+- One file per source: `auto.tsv` (the pre-sort), `hand.tsv`, `rater-b.tsv`, and the final
+  `labels.tsv` the analysis reads.
+
+## Notes — `notes.md`
+
+```markdown
+## 2026-01-05
+
+unit-017/control/1: solved → deferred. Re-read the final message:
+
+> I've prepared both options; I'll leave the final call to you.
+```
+
+A cell relabelled, added or removed after the analysis is accepted by `validate --analysed-at` only
+when the cell appears in a section under a `## YYYY-MM-DD` heading that also holds a `>` quote line.
+
+## Rater instruction — one committed file, used byte for byte
+
+The same file goes to every rater; record `sha256sum rater-instruction.md` in the notes. It holds:
+the codebook (pasted, not summarised), what the rater receives for each run (the final message and
+the ordered action list), the output format (one label per run, no other text), and nothing about
+the arms, the hypothesis or another rater's labels.

package/skills/label-agent-runs/scripts/labels-commands.js

@@ -0,0 +1,13 @@
+/**
+ * The subcommands of `labels`, by name. One table, read twice: the dispatcher in `labels.ts`
+ * compares against these, and `SKILL.md.spec.ts` interpolates them into every command it
+ * instructs (a name that is not here is a type error there). So the skill cannot instruct a
+ * subcommand the script does not have.
+ *
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
+ * `labels.ts` itself would run the command line.
+ */
+export const COMMANDS = {
+    validate: "validate",
+    agree: "agree",
+};

package/skills/label-agent-runs/scripts/labels-commands.ts

@@ -0,0 +1,13 @@
+/**
+ * The subcommands of `labels`, by name. One table, read twice: the dispatcher in `labels.ts`
+ * compares against these, and `SKILL.md.spec.ts` interpolates them into every command it
+ * instructs (a name that is not here is a type error there). So the skill cannot instruct a
+ * subcommand the script does not have.
+ *
+ * A module of its own, with no side effects: the spec imports it at compile time, and importing
+ * `labels.ts` itself would run the command line.
+ */
+export const COMMANDS = {
+  validate: "validate",
+  agree: "agree",
+} as const;

package/skills/label-agent-runs/scripts/labels.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+/**
+ * labels — the checks of the label-agent-runs skill.
+ *
+ *   validate <labels.tsv> --codebook <codebook.json> [--ledger <attempts.jsonl>]
+ *            [--analysed-at <git rev> --notes <notes.md>]
+ *       The label file is well formed, uses only codebook labels, names each cell once, and —
+ *       with a ledger — covers exactly the completed runs. The codebook is committed, unchanged,
+ *       and was committed no later than the label file. With --analysed-at: every cell whose
+ *       label differs from that revision is explained in a dated section of the notes, with a
+ *       verbatim quote.
+ *   agree <a.tsv> <b.tsv>
+ *       Agreement between two label files over the same cells: n, percent agreement with a 95%
+ *       Wilson interval, Cohen's kappa, and every disagreement. Use it for the automatic pre-sort
+ *       against the hand labels, and for one rater against another.
+ *
+ * A label file is TSV with exactly this header: agent, model, cell, label. `cell` is
+ * `<unit>/<arm>/<seed>`, the cell of the run-agent-grid ledger.
+ *
+ * TypeScript, compiled beside itself to `labels.js` by `npm run build`: a consumer runs the skill
+ * from `node_modules`, where Node does not strip types. The skill names the `.js`.
+ *
+ * EXIT CODES: 0 valid / reported · 1 a finding · 2 usage.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { COMMANDS } from "./labels-commands.js";
+class Refusal extends Error {
+    exitCode;
+    constructor(exitCode, message) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+const refuse = (exitCode, message) => {
+    throw new Refusal(exitCode, message);
+};
+const say = (line) => {
+    process.stdout.write(`${line}\n`);
+};
+const prop = (e, key) => Reflect.get(Object(e), key);
+const HEADER = ["agent", "model", "cell", "label"];
+const keyOf = (r) => `${r.agent}\t${r.model}\t${r.cell}`;
+const show = (r) => `${r.agent} ${r.model} ${r.cell}`;
+/** A line with exactly four fields as a row; anything else is not one. */
+const asRow = ({ fields, n }) => {
+    const [agent, model, cell, label] = fields;
+    return fields.length === 4
+        ? [
+            {
+                agent: String(agent),
+                model: String(model),
+                cell: String(cell),
+                label: String(label),
+                n,
+            },
+        ]
+        : [];
+};
+/** Rows of a label file, and the problems that stop a line being one. */
+function readLabels(file) {
+    const [first, ...body] = readFileSync(file, "utf8").split("\n");
+    const lines = body
+        .map((line, i) => ({ line, fields: line.split("\t"), n: i + 2 }))
+        .filter(({ line }) => line.trim() !== "");
+    const headerOk = String(first).replace(/\r$/, "") === HEADER.join("\t");
+    return {
+        rows: lines.flatMap(asRow),
+        problems: [
+            ...(headerOk
+                ? []
+                : [`${file}:1: the header must be "${HEADER.join("\\t")}"`]),
+            ...lines
+                .filter(({ fields }) => fields.length !== 4)
+                .map(({ n }) => `${file}:${String(n)}: not four tab-separated fields`),
+        ],
+    };
+}
+const git = (cwd, ...args) => spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+/** Where `abs` sits in its git repository, or null outside one. */
+const repoPath = (abs) => {
+    const top = git(dirname(abs), "rev-parse", "--show-toplevel");
+    return top.status === 0
+        ? {
+            top: top.stdout.trim(),
+            rel: relative(top.stdout.trim(), abs).split(sep).join("/"),
+        }
+        : null;
+};
+/** Unix times of the commits that touched `abs` — only the ones that ADDED it, with `added`. */
+const commitTimes = (abs, added) => {
+    const at = repoPath(abs);
+    const filter = added ? ["--diff-filter=A"] : [];
+    return at
+        ? git(at.top, "log", ...filter, "--format=%ct", "--", at.rel)
+            .stdout.trim()
+            .split("\n")
+            .filter(Boolean)
+            .map(Number)
+        : [];
+};
+const Codebook = z.looseObject({
+    labels: z
+        .array(z.looseObject({
+        id: z.unknown().optional(),
+        definition: z.unknown().optional(),
+        borderline: z.unknown().optional(),
+    }))
+        .default([]),
+});
+const filled = (v) => typeof v === "string" && v.trim() !== "";
+/** Is the committed copy of `abs` the one on disk? A message when it is not. */
+function committedProblem(file, abs, text) {
+    const at = repoPath(abs);
+    const head = at ? git(at.top, "show", `HEAD:${at.rel}`) : null;
+    if (!head || head.status !== 0)
+        return [
+            `${file} is not committed: commit the codebook before the first label`,
+        ];
+    return head.stdout === text
+        ? []
+        : [
+            `${file} differs from its committed version: the codebook is fixed before labelling`,
+        ];
+}
+/** Labels that lack an id, a definition or a borderline example. */
+const incomplete = (file, labels) => labels
+    .filter((l) => !(filled(l.id) && filled(l.definition) && filled(l.borderline)))
+    .map((l) => `${file}: label "${String(l.id)}" needs an id, a definition and a borderline example`);
+function codebookProblems(file, labelsFile) {
+    const abs = resolve(file);
+    const text = readFileSync(abs, "utf8");
+    const { labels } = Codebook.parse(JSON.parse(text));
+    // EVERY commit of the codebook, not only the one that added it: an edit after labelling began
+    // changes what the labels already given mean.
+    const bookLast = Math.max(-Infinity, ...commitTimes(abs, false));
+    const labelsFirst = Math.min(Infinity, ...commitTimes(resolve(labelsFile), true));
+    const late = bookLast > labelsFirst;
+    return {
+        known: new Set(labels.map((l) => l.id)),
+        problems: [
+            ...committedProblem(file, abs, text),
+            ...(labels.length ? [] : [`${file} defines no labels`]),
+            ...incomplete(file, labels),
+            ...(late
+                ? [
+                    `${file} was committed after ${labelsFile} was first committed: the codebook is fixed before labelling; a changed codebook needs a new label file`,
+                ]
+                : []),
+        ],
+    };
+}
+const Attempt = z.looseObject({
+    attempt: z.string(),
+    agent: z.string().optional(),
+    model: z.string().optional(),
+    unit: z.string().optional(),
+    arm: z.string().optional(),
+    seed: z.union([z.string(), z.number()]).optional(),
+    status: z.string().optional(),
+});
+/** The cells of the completed attempts in a run-agent-grid ledger. */
+function ledgerCells(file) {
+    const byId = new Map();
+    readFileSync(file, "utf8")
+        .split("\n")
+        .filter((l) => l.trim())
+        .map((l) => Attempt.parse(JSON.parse(l)))
+        .forEach((r) => {
+        byId.set(r.attempt, { ...byId.get(r.attempt), ...r });
+    });
+    return [...byId.values()]
+        .filter((r) => r.status === "complete")
+        .map((r) => ({
+        agent: String(r.agent),
+        model: String(r.model),
+        cell: `${String(r.unit)}/${String(r.arm)}/${String(r.seed)}`,
+    }));
+}
+/** The labels a revision of the label file held, by cell; null when it did not exist there. */
+function labelsAt(labelsFile, rev) {
+    const at = repoPath(resolve(labelsFile));
+    const then = at ? git(at.top, "show", `${rev}:${at.rel}`) : null;
+    if (!then || then.status !== 0)
+        return null;
+    return new Map(then.stdout
+        .split("\n")
+        .slice(1)
+        .filter((l) => l.trim())
+        .map((l) => l.split("\t"))
+        .map(([agent, model, cell, label]) => [
+        keyOf({
+            agent: String(agent),
+            model: String(model),
+            cell: String(cell),
+        }),
+        String(label),
+    ]));
+}
+/** The sections of the notes under a "## YYYY-MM-DD" heading, each up to the next "## ". */
+const datedSections = (notesFile) => readFileSync(notesFile, "utf8")
+    .split(/^(?=## )/m)
+    .filter((s) => /^## \d{4}-\d{2}-\d{2}\b/.test(s));
+/** A cell key back as the three fields `show` prints. */
+const fromKey = (key) => {
+    const [agent, model, cell] = key.split("\t");
+    return { agent: String(agent), model: String(model), cell: String(cell) };
+};
+const WHY = " with no dated note quoting the run";
+/** Rows whose label is new or different since the analysis, and not explained. */
+const touchedSince = (rows, before, noted) => rows
+    .filter((r) => before.get(keyOf(r)) !== r.label && !noted(r.cell))
+    .map((r) => {
+    const was = before.get(keyOf(r));
+    return was === undefined
+        ? `${show(r)}: added after the analysis (${r.label}),${WHY}`
+        : `${show(r)}: relabelled ${was} → ${r.label} after the analysis,${WHY}`;
+});
+/** Cells the analysis read that are gone now, and not explained. */
+const removedSince = (rows, before, noted) => {
+    const now = new Set(rows.map(keyOf));
+    return [...before]
+        .filter(([key]) => !now.has(key) && !noted(fromKey(key).cell))
+        .map(([key, was]) => `${show(fromKey(key))}: removed after the analysis (was ${was}),${WHY}`);
+};
+/**
+ * Every cell whose label differs from what the analysis read at `rev` — changed, ADDED after it,
+ * or REMOVED since — and is not explained in a dated, quoted note naming the cell.
+ */
+function relabelProblems(labelsFile, rev, notesFile, rows) {
+    const before = labelsAt(labelsFile, rev);
+    if (!before)
+        return [
+            `${labelsFile} does not exist at ${rev}: name the revision the analysis read`,
+        ];
+    const sections = datedSections(notesFile);
+    const noted = (cell) => sections.some((s) => s.includes(cell) && /^> \S/m.test(s));
+    return [
+        ...touchedSince(rows, before, noted),
+        ...removedSince(rows, before, noted),
+    ];
+}
+/** Cells a file labels more than once, with the lines. */
+function duplicates(file, rows) {
+    const seen = new Map();
+    rows.forEach((r) => seen.set(keyOf(r), [...(seen.get(keyOf(r)) ?? []), r.n]));
+    return [...seen]
+        .filter(([, ns]) => ns.length > 1)
+        .map(([k, ns]) => `${file}: ${show(fromKey(k))} is labelled ${String(ns.length)} times (lines ${ns.join(", ")})`);
+}
+/** Rows naming a cell twice, and coverage against the ledger. */
+function rowProblems(file, rows, ledger) {
+    const runs = ledger === undefined ? null : ledgerCells(ledger);
+    const ran = new Set((runs ?? []).map(keyOf));
+    const labelled = new Set(rows.map(keyOf));
+    return [
+        ...duplicates(file, rows),
+        ...(runs
+            ? [
+                ...rows
+                    .filter((r) => !ran.has(keyOf(r)))
+                    .map((r) => `${file}:${String(r.n)}: ${show(r)} has no completed run in the ledger`),
+                ...runs
+                    .filter((r) => !labelled.has(keyOf(r)))
+                    .map((r) => `${show(r)}: a completed run with no label`),
+            ]
+            : []),
+    ];
+}
+function validate(file, o) {
+    const { rows, problems } = readLabels(file);
+    const book = codebookProblems(String(o.codebook), file);
+    const all = [
+        ...problems,
+        ...book.problems,
+        ...rows
+            .filter((r) => !book.known.has(r.label))
+            .map((r) => `${file}:${String(r.n)}: "${r.label}" is not a codebook label`),
+        ...rowProblems(file, rows, o.ledger),
+        ...(o["analysed-at"] === undefined
+            ? []
+            : relabelProblems(file, o["analysed-at"], String(o.notes), rows)),
+    ];
+    if (all.length)
+        refuse(1, all.join("\n"));
+    say(`${file}: ${String(rows.length)} labels, valid`);
+}
+// ── agreement ───────────────────────────────────────────────────────────────────────────────
+const Z = 1.959963984540054;
+/** 95% Wilson score interval for k successes in n. */
+const wilson = (k, n) => {
+    const p = k / n;
+    const denom = 1 + (Z * Z) / n;
+    const centre = (p + (Z * Z) / (2 * n)) / denom;
+    const half = (Z * Math.sqrt((p * (1 - p)) / n + (Z * Z) / (4 * n * n))) / denom;
+    return [centre - half, centre + half];
+};
+/** Cohen's kappa over paired labels; null when chance agreement is 1 (one label only). */
+function cohenKappa(pairs) {
+    const n = pairs.length;
+    const po = pairs.filter(([a, b]) => a === b).length / n;
+    const labels = [...new Set(pairs.flat())];
+    const share = (i, l) => pairs.filter((p) => p[i] === l).length / n;
+    const pe = labels.reduce((s, l) => s + share(0, l) * share(1, l), 0);
+    return pe === 1 ? null : (po - pe) / (1 - pe);
+}
+/** Cells of either file that the other does not label. */
+const onlyIn = (fileA, a, b, fileB) => {
+    const inA = new Set(a.map(keyOf));
+    const inB = new Set(b.map(keyOf));
+    return [
+        ...a
+            .filter((r) => !inB.has(keyOf(r)))
+            .map((r) => `${show(r)}: only in ${fileA}`),
+        ...b
+            .filter((r) => !inA.has(keyOf(r)))
+            .map((r) => `${show(r)}: only in ${fileB}`),
+    ];
+};
+/** The second file's label for each cell of the first; a refusal when the cells differ. */
+function matched(fileA, fileB) {
+    const a = readLabels(fileA);
+    const b = readLabels(fileB);
+    // A cell labelled twice has no single label to compare: refused before any statistic.
+    const bad = [
+        ...a.problems,
+        ...b.problems,
+        ...duplicates(fileA, a.rows),
+        ...duplicates(fileB, b.rows),
+    ];
+    if (bad.length)
+        refuse(1, bad.join("\n"));
+    const inB = new Map(b.rows.map((r) => [keyOf(r), r.label]));
+    const unmatched = onlyIn(fileA, a.rows, b.rows, fileB);
+    if (unmatched.length)
+        refuse(1, `the two files label different cells — rate the same runs:\n${unmatched.join("\n")}`);
+    if (a.rows.length === 0)
+        refuse(1, "no labels to compare");
+    return a.rows.map((r) => [r, String(inB.get(keyOf(r)))]);
+}
+function agree(fileA, fileB) {
+    const rows = matched(fileA, fileB);
+    const pairs = rows.map(([r, other]) => [r.label, other]);
+    const n = pairs.length;
+    const k = pairs.filter(([x, y]) => x === y).length;
+    const [lo, hi] = wilson(k, n);
+    const kappa = cohenKappa(pairs);
+    const f = (x) => x.toFixed(3);
+    say([
+        `n ${String(n)}`,
+        `agreement ${String(k)}/${String(n)} = ${f(k / n)} (95% Wilson ${f(lo)}–${f(hi)})`,
+        `cohen kappa ${kappa === null ? "undefined (one label only)" : f(kappa)}`,
+        ...rows
+            .filter(([r, other]) => r.label !== other)
+            .map(([r, other]) => `disagree ${show(r)}: ${r.label} | ${other}`),
+    ].join("\n"));
+}
+// ── command line ────────────────────────────────────────────────────────────────────────────
+const OPTIONS = {
+    codebook: { type: "string" },
+    ledger: { type: "string" },
+    "analysed-at": { type: "string" },
+    notes: { type: "string" },
+};
+const USAGE = "usage: labels.js validate <labels.tsv> --codebook <f> [--ledger <f>] [--analysed-at <rev> --notes <f>] | agree <a.tsv> <b.tsv>";
+function main() {
+    const { values, positionals } = (() => {
+        try {
+            return parseArgs({ options: OPTIONS, allowPositionals: true });
+        }
+        catch (e) {
+            return refuse(2, `${String(prop(e, "message"))}\n${USAGE}`);
+        }
+    })();
+    const [cmd, ...paths] = positionals;
+    const validateOk = cmd === COMMANDS.validate &&
+        paths.length === 1 &&
+        values.codebook !== undefined &&
+        (values["analysed-at"] === undefined || values.notes !== undefined);
+    if (validateOk)
+        validate(String(paths[0]), values);
+    else if (cmd === COMMANDS.agree && paths.length === 2)
+        agree(String(paths[0]), String(paths[1]));
+    else
+        refuse(2, USAGE);
+}
+try {
+    main();
+}
+catch (e) {
+    process.stderr.write(`labels: ${String(prop(e, "message"))}\n`);
+    process.exitCode = e instanceof Refusal ? e.exitCode : 1;
+}