@popoverai/dotrequirements 0.33.0 → 0.34.0

package/dist/commands/solution/create.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `dotreq solution create [file]`: with no file, a solution from the
+ * project's default plan, titled with `--title`; with a plan file (YAML or
+ * JSON), its title, its description, its plan in the stored shape, and the
+ * inputs that already exist. `--description` says what the solution is
+ * beyond its title, in Markdown, and wins over the file's. The backend validates the plan and refuses an invalid one
+ * with the rules it broke.
+ */
+export declare function createCommand(file: string | undefined, options?: {
+    title?: string;
+    description?: string;
+    idea?: string[];
+}): Promise<void>;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/solution/create.js

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { planPayload, readPlanFile } from "./plan-file.js";
+import { parseThing } from "./things.js";
+/**
+ * `dotreq solution create [file]`: with no file, a solution from the
+ * project's default plan, titled with `--title`; with a plan file (YAML or
+ * JSON), its title, its description, its plan in the stored shape, and the
+ * inputs that already exist. `--description` says what the solution is
+ * beyond its title, in Markdown, and wins over the file's. The backend validates the plan and refuses an invalid one
+ * with the rules it broke.
+ */
+export async function createCommand(file, options = {}) {
+    const idea = options.idea?.map(parseThing);
+    const described = options.description?.trim() || undefined;
+    if (!file) {
+        const title = options.title?.trim();
+        if (!title) {
+            throw new Error("A solution from the project's default plan needs a title: --title <title>.");
+        }
+        const client = solutionClient();
+        const id = await client.mutation(api.solutions.mutations.create, {
+            project: client.project,
+            title,
+            description: described,
+            idea,
+        });
+        console.log(`Created "${title}" from the project's default plan: ${id}`);
+        return;
+    }
+    const spec = readPlanFile(readFileSync(resolve(process.cwd(), file), "utf8"), file);
+    const title = options.title?.trim() ||
+        (typeof spec?.title === "string" ? spec.title : undefined);
+    if (!spec?.plan || !title) {
+        throw new Error(`${file} needs a plan, and a title in the file or as --title (docs/working/plan-surfaces.md).`);
+    }
+    const client = solutionClient();
+    const id = await client.mutation(api.solutions.mutations.create, {
+        project: client.project,
+        title,
+        description: described ??
+            (typeof spec.description === "string" ? spec.description : undefined),
+        // PLAN-1: the plan as the file writes it; the backend reads it.
+        plan: planPayload(spec),
+        inputs: Array.isArray(spec.inputs) ? spec.inputs : [],
+        idea,
+    });
+    console.log(`Created "${title}": ${id}`);
+}
+//# sourceMappingURL=create.js.map

package/dist/commands/solution/demo-script.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a demo's script is saved in the checkout of the agent reviewing it
+ * (SIGHT-13.1), relative to the repository's root: the folder git ignores,
+ * under the script's file name. Kept in step with the backend's
+ * `demoScriptCopyPath` (convex/solutions/brief.ts), which is where the brief
+ * says the copy is.
+ */
+export declare function demoScriptCopyPath(name: string): string;
+/** An outcome as `dotreq solution next` returns it, as far as this reads it. */
+type BriefOutcome = {
+    things?: Array<{
+        kind: string;
+        name?: string;
+        script?: string;
+    }>;
+};
+/**
+ * Save a copy of each demo's script among the outcomes a reviewer reads in
+ * its checkout, where its brief says it is, so it records the video from
+ * that file and fixes anything small there first (SIGHT-13.1, 13.3). The
+ * drafter's latest script replaces any earlier copy, as when the drafter
+ * revised it. The folder ignores itself, so nothing saved there is ever
+ * committed (13.0). The review is already started, so a copy that can't be
+ * saved is said on stderr rather than failing the run.
+ */
+export declare function saveDemoScriptCopies(outcomes: readonly BriefOutcome[], cwd?: string): void;
+export {};
+//# sourceMappingURL=demo-script.d.ts.map

package/dist/commands/solution/demo-script.js

@@ -0,0 +1,43 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { repositoryRoot } from "./branch.js";
+/**
+ * Where a demo's script is saved in the checkout of the agent reviewing it
+ * (SIGHT-13.1), relative to the repository's root: the folder git ignores,
+ * under the script's file name. Kept in step with the backend's
+ * `demoScriptCopyPath` (convex/solutions/brief.ts), which is where the brief
+ * says the copy is.
+ */
+export function demoScriptCopyPath(name) {
+    return `.dotreq/demo-scripts/${name}`;
+}
+/**
+ * Save a copy of each demo's script among the outcomes a reviewer reads in
+ * its checkout, where its brief says it is, so it records the video from
+ * that file and fixes anything small there first (SIGHT-13.1, 13.3). The
+ * drafter's latest script replaces any earlier copy, as when the drafter
+ * revised it. The folder ignores itself, so nothing saved there is ever
+ * committed (13.0). The review is already started, so a copy that can't be
+ * saved is said on stderr rather than failing the run.
+ */
+export function saveDemoScriptCopies(outcomes, cwd = process.cwd()) {
+    const scripts = outcomes.flatMap((outcome) => (outcome.things ?? []).flatMap((thing) => thing.kind === "demo script" && thing.name && thing.script !== undefined
+        ? [{ name: basename(thing.name), script: thing.script }]
+        : []));
+    if (scripts.length === 0)
+        return;
+    const root = repositoryRoot(cwd) ?? cwd;
+    try {
+        mkdirSync(join(root, ".dotreq"), { recursive: true });
+        writeFileSync(join(root, ".dotreq", ".gitignore"), "*\n");
+        for (const { name, script } of scripts) {
+            const path = join(root, demoScriptCopyPath(name));
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, script);
+        }
+    }
+    catch (error) {
+        console.error(`Couldn't save a copy of the demo's script: ${error instanceof Error ? error.message : String(error)}. Its text is in your brief.`);
+    }
+}
+//# sourceMappingURL=demo-script.js.map

package/dist/commands/solution/image.d.ts

@@ -0,0 +1,60 @@
+import type { solutionClient } from "./client.js";
+/**
+ * Images on an outcome (SIGHT-9), such as a screenshot: the drafter submits an
+ * image file from its checkout or anywhere it can read, and the app keeps a
+ * copy; nothing is committed.
+ *
+ * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
+ * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
+ * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
+ * so they are refused. SVG is refused too: opened at full size in its own
+ * tab, an SVG runs whatever script it carries. The format is read from the
+ * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
+ * its `ftyp` box), since an extension says nothing about it. Kept in step
+ * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ */
+export declare const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
+export type ImageContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/avif";
+/** What the file is: a format a browser shows, or why it isn't one. */
+export type ImageFormat = {
+    contentType: ImageContentType;
+} | {
+    refused: string;
+};
+/** An image read from the checkout, ready to upload. */
+export type Image = {
+    name: string;
+    contentType: ImageContentType;
+    bytes: Uint8Array<ArrayBuffer>;
+};
+/** The image at a path, or a refusal naming the accepted formats (SIGHT-9.0.0). */
+export declare function readImage(path: string): Image;
+/** What image format the bytes hold, read from the file's signature. */
+export declare function imageFormat(bytes: Uint8Array): ImageFormat;
+/**
+ * Where an image's copy is saved in the checkout, relative to the
+ * repository's root (SIGHT-9.3): a folder git ignores, then one folder per
+ * stored copy, so two images of one name stay apart. Kept in step with the
+ * backend's `imageCopyPath` (convex/solutions/brief.ts), which is where
+ * the brief says the copy is.
+ */
+export declare function imageCopyPath(storageId: string, name: string): string;
+/** An outcome as `dotreq solution next` returns it, as far as this reads it. */
+type BriefOutcome = {
+    things?: Array<{
+        kind: string;
+        storageId?: string;
+    }>;
+};
+/**
+ * Save a copy of each image among the outcomes an agent works on in the
+ * checkout, where its brief says it is (SIGHT-9.3), in place of the copies
+ * an earlier session saved. The folder ignores itself, so nothing saved
+ * there is ever committed (9.0). The work is already started, so a copy
+ * that can't be saved is said on stderr rather than failing the run.
+ */
+export declare function saveImageCopies(client: ReturnType<typeof solutionClient>, solutionId: string, outcomes: readonly BriefOutcome[], cwd?: string): Promise<void>;
+/** Upload an image to the app (SIGHT-9.0), and the stored copy's id back. */
+export declare function uploadImage(client: ReturnType<typeof solutionClient>, solutionId: string, image: Image): Promise<string>;
+export {};
+//# sourceMappingURL=image.d.ts.map

package/dist/commands/solution/image.js

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { api } from "../../convex.js";
+import { repositoryRoot } from "./branch.js";
+import { uploadToApp } from "./upload.js";
+/**
+ * Images on an outcome (SIGHT-9), such as a screenshot: the drafter submits an
+ * image file from its checkout or anywhere it can read, and the app keeps a
+ * copy; nothing is committed.
+ *
+ * Every browser we support (Chrome, Edge, Firefox, Safari on macOS and iOS)
+ * shows PNG, JPEG, GIF, WebP and AVIF (MDN's image type guide; AVIF from
+ * Safari 16.4). HEIC and TIFF show only in Safari, and JPEG XL not in Edge,
+ * so they are refused. SVG is refused too: opened at full size in its own
+ * tab, an SVG runs whatever script it carries. The format is read from the
+ * file's first bytes (the WHATWG MIME Sniffing signatures; AVIF's brand in
+ * its `ftyp` box), since an extension says nothing about it. Kept in step
+ * with the backend's `ACCEPTED_IMAGE_FORMATS` (convex/solutions/images.ts).
+ */
+export const ACCEPTED_IMAGE_FORMATS = "a PNG, JPEG, GIF, WebP or AVIF image";
+/** The image at a path, or a refusal naming the accepted formats (SIGHT-9.0.0). */
+export function readImage(path) {
+    const full = resolve(path);
+    if (!existsSync(full) || !statSync(full).isFile()) {
+        throw new Error(`There is no file at ${path}, so nothing was submitted.`);
+    }
+    const bytes = new Uint8Array(readFileSync(full));
+    const format = imageFormat(bytes);
+    if ("refused" in format) {
+        throw new Error(`${path} isn't an image a browser can show (${format.refused}), so nothing was submitted. Submit ${ACCEPTED_IMAGE_FORMATS}.`);
+    }
+    return { name: basename(full), contentType: format.contentType, bytes };
+}
+const AVIF_BRANDS = new Set(["avif", "avis"]);
+const HEIF_BRANDS = new Set(["heic", "heix", "heim", "heis", "hevc", "hevx"]);
+/** What image format the bytes hold, read from the file's signature. */
+export function imageFormat(bytes) {
+    const starts = (...signature) => signature.every((byte, at) => bytes[at] === byte);
+    if (starts(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)) {
+        return { contentType: "image/png" };
+    }
+    if (starts(0xff, 0xd8, 0xff))
+        return { contentType: "image/jpeg" };
+    if (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a") {
+        return { contentType: "image/gif" };
+    }
+    if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 6) === "WEBPVP") {
+        return { contentType: "image/webp" };
+    }
+    if (ascii(bytes, 4, 4) === "ftyp") {
+        // ISO-BMFF: the major brand, then compatible brands to the box's end.
+        // AVIF lists avif or avis; HEIC shares the box and lists its own.
+        const size = readUint32(bytes, 0);
+        const end = Math.min(bytes.length, size);
+        const brands = [ascii(bytes, 8, 4)];
+        for (let at = 16; at + 4 <= end; at += 4)
+            brands.push(ascii(bytes, at, 4));
+        if (brands.some((brand) => AVIF_BRANDS.has(brand))) {
+            return { contentType: "image/avif" };
+        }
+        if (brands.some((brand) => HEIF_BRANDS.has(brand))) {
+            return { refused: "it is a HEIC image, which only Safari shows" };
+        }
+        return { refused: "it isn't an image file" };
+    }
+    if (starts(0x49, 0x49, 0x2a, 0x00) || starts(0x4d, 0x4d, 0x00, 0x2a)) {
+        return { refused: "it is a TIFF image, which only Safari shows" };
+    }
+    if (/^\s*(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*)*<svg[\s>]/i.test(head(bytes))) {
+        return {
+            refused: "it is an SVG, which runs its scripts when opened at full size",
+        };
+    }
+    return { refused: "it isn't an image file" };
+}
+function ascii(bytes, at, length) {
+    return at + length <= bytes.length
+        ? String.fromCharCode(...bytes.subarray(at, at + length))
+        : "";
+}
+function readUint32(bytes, at) {
+    let value = 0;
+    for (let i = 0; i < 4; i++)
+        value = value * 256 + (bytes[at + i] ?? 0);
+    return value;
+}
+/** The file's start as text, for telling an SVG by its root element. */
+function head(bytes) {
+    return new TextDecoder("utf-8", { fatal: false })
+        .decode(bytes.subarray(0, 1024))
+        .replace(/^/, "");
+}
+/**
+ * Where an image's copy is saved in the checkout, relative to the
+ * repository's root (SIGHT-9.3): a folder git ignores, then one folder per
+ * stored copy, so two images of one name stay apart. Kept in step with the
+ * backend's `imageCopyPath` (convex/solutions/brief.ts), which is where
+ * the brief says the copy is.
+ */
+export function imageCopyPath(storageId, name) {
+    return `${COPIES_FOLDER}/images/${storageId}/${name}`;
+}
+const COPIES_FOLDER = ".dotreq";
+/**
+ * Save a copy of each image among the outcomes an agent works on in the
+ * checkout, where its brief says it is (SIGHT-9.3), in place of the copies
+ * an earlier session saved. The folder ignores itself, so nothing saved
+ * there is ever committed (9.0). The work is already started, so a copy
+ * that can't be saved is said on stderr rather than failing the run.
+ */
+export async function saveImageCopies(client, solutionId, outcomes, cwd = process.cwd()) {
+    const storageIds = [
+        ...new Set(outcomes.flatMap((outcome) => (outcome.things ?? []).flatMap((thing) => thing.kind === "image" && thing.storageId ? [thing.storageId] : []))),
+    ];
+    if (storageIds.length === 0)
+        return;
+    const root = repositoryRoot(cwd) ?? cwd;
+    const folder = join(root, COPIES_FOLDER);
+    try {
+        rmSync(join(folder, "images"), { recursive: true, force: true });
+        mkdirSync(folder, { recursive: true });
+        writeFileSync(join(folder, ".gitignore"), "*\n");
+        const copies = await client.query(api.solutions.images.copies, { solutionId, storageIds });
+        for (const storageId of storageIds) {
+            const copy = copies.find((found) => found.storageId === storageId);
+            if (!copy) {
+                console.error(`An image submitted (${storageId}) has no copy left.`);
+                continue;
+            }
+            const response = await fetch(copy.url);
+            if (!response.ok) {
+                console.error(`Couldn't save a copy of ${copy.name} (${response.status} ${response.statusText}).`);
+                continue;
+            }
+            const path = join(root, imageCopyPath(storageId, basename(copy.name)));
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, new Uint8Array(await response.arrayBuffer()));
+        }
+    }
+    catch (error) {
+        console.error(`Couldn't save copies of the images submitted: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Upload an image to the app (SIGHT-9.0), and the stored copy's id back. */
+export function uploadImage(client, solutionId, image) {
+    return uploadToApp(client, api.solutions.images.uploadUrl, { solutionId }, image);
+}
+//# sourceMappingURL=image.js.map

package/dist/commands/solution/index.d.ts

@@ -0,0 +1,12 @@
+import { type Command } from "commander";
+/**
+ * `dotreq solution`: work a solution through its plan of outcomes
+ * (docs/working/plan-surfaces.md). A person creates a solution and can
+ * start an agent's work by hand; an agent runs `next` when invoked, which
+ * gives it an outcome to draft or to review, and records what came of it
+ * with one verb per act — `author`, `review`, `ask`, `stall` — each naming
+ * its object and no ids (VERB-4), and reads the outcome's thread with
+ * `thread`.
+ */
+export declare function registerSolution(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/solution/index.js

@@ -0,0 +1,281 @@
+import { Option } from "commander";
+import { askCommand } from "./ask.js";
+import { authorCommand } from "./author.js";
+import { checkoutCommand, pushCommand } from "./checkout.js";
+import { REQUEST_CONTRACT } from "./contract.js";
+import { createCommand } from "./create.js";
+import { thingsCommand } from "./look-up.js";
+import { nextCommand } from "./next.js";
+import { pullRequestCommand } from "./pull-request.js";
+import { rehearseCommand } from "./rehearse.js";
+import { reviewCommand } from "./review.js";
+import { doneCommand } from "./share.js";
+import { stallCommand } from "./stall.js";
+import { startCommand } from "./start.js";
+import { statusCommand } from "./status.js";
+import { threadCommand } from "./thread.js";
+/**
+ * Verbs only an agent runs, kept out of `--help`: an agent gets them from
+ * `next`'s output, and a person has no reason to type them.
+ */
+const HIDDEN = { hidden: true };
+/**
+ * Where a verb's solution, agent and outcome come from when the run does
+ * not say (VERB-4.1). The same options on every verb an agent runs;
+ * `--step` is `--outcome` under its old name, kept out of `--help`.
+ */
+function whereOptions(command, outcome = "Which outcome, when you are at more than one; otherwise the one you are at") {
+    return command
+        .option("--solution <id>", "Which solution, when the run does not say (inside a runner it does)")
+        .option("--agent <name>", "Which agent you are, when the run does not say (inside a runner it does)")
+        .option("--outcome <name>", outcome)
+        .addOption(new Option("--step <name>").hideHelp());
+}
+/** The forms a reference takes: one source of truth, on `author --help` (VERB-5.5). */
+const REFERENCE_FORMS = `
+Where what you made is, one or more:
+  document:<id>            a document in dotrequirements
+  file:<path>[@<branch>]   a file in this repository
+  link:<url>               anything that lives elsewhere
+  board:<id>               a discovery board in dotrequirements
+  mockup:<id>              a mockup in dotrequirements
+  scores:<id>              scores in dotrequirements, made with dotreq scores create
+  pr:<number>              the solution's pull request, opened or found with
+                           dotreq solution pull-request. An outcome kept on a pull
+                           request is submitted with it, with the rest of its work
+  image:<path>             an image, such as a screenshot: a PNG, JPEG, GIF, WebP or
+                           AVIF. The app keeps a copy; don't commit it
+  "video:<path> <script>"  a video file here, such as a screen recording of a fix,
+                           and the steps file it was recorded from, as one argument,
+                           e.g. "video:final.mp4 steps.json". The video is an MP4
+                           with H.264, or a WebM with VP8 or VP9. The app keeps a copy of
+                           both; don't commit either. Where an agent reviews your
+                           outcome, it records the video: submit the demo-script
+                           instead
+  demo-script:<path>       a demo's steps file: the browser commands for each step
+                           and the sentence said over it. Don't record it: the agent
+                           reviewing it records the video once it would approve the
+                           script. The app keeps the script; don't commit it
+  "preview:<port>[/<page>] <cmd>"
+                           something running here — Storybook, a dev server — as one
+                           argument: the port it listens on (6006, 5173 or 8080;
+                           never 3000, the runner's), the page to open when it isn't
+                           the first one, and the command that starts it from the
+                           repository root. A screenshot of the page is taken as it
+                           is submitted
+
+Each reference can have a title, its name for the owner on the outcome's tab, and
+a preview's button names it: give one --title per reference, in the order the
+references are given. Without titles, each is named for what it is.
+
+A spec goes under .requirements/ as <name>.requirements.md, any other written
+outcome at .requirements/solutions/<solution>/<outcome>.md. With a repository
+connected, a file kept on the pull request is committed and submitted as
+file:<path>, unsynced, since it reaches the project's requirements when the
+pull request merges; one kept in the app is synced alone with
+\`dotreq sync --repo-contributes <path>\`, which writes the document id into its
+frontmatter, and submitted as document:<id>. With none, submit file:<path>: it
+is saved on the solution's branch, and the document id is written into its
+frontmatter.
+
+When your work moves on before anyone reviews it, the owner may read it next, so write
+an executive summary for them with --executive-summary (or --summary). If they haven't
+seen this work before, open with one sentence on what it is. If they sent it back, open
+with what changed since, and how their points were handled. Then list the assumptions
+worth their attention and what would benefit from their eyes. On an outcome no agent
+reviews, your work is refused without one.
+
+Examples:
+  dotreq solution author document:jd7abc --comment "Named the customer."
+  dotreq solution author file:src/checkout.ts@guest pr:12 image:checkout.png --comment "Guest path, behind the flag."
+  dotreq solution author "preview:8080/design/roll-count pnpm dev" file:src/RollCount.tsx --title "Roll count after three dice" --title "Roll count component" --comment "The roll count, as a dev-only page."
+`;
+/** What `pull-request` does, on its `--help`, where `author --help` sends the agent (PULL-2). */
+const PULL_REQUEST_HELP = `
+Pushes your commits to the solution's branch, then opens a pull request from it
+into the branch it was made from, ready for review, or finds the one already open.
+Prints its reference and its address:
+
+  The solution's pull request is pr:12: https://github.com/<owner>/<repository>/pull/12
+
+Submit it with the rest of your work, by its reference:
+
+  dotreq solution author pr:12 <reference>... --comment "..."
+
+Asking again gives the same pull request while it is open, with your new commits
+pushed to it; once it is merged or closed, a new one is opened.
+`;
+/**
+ * How to stall and what to say: on `stall --help`, where the brief sends the
+ * agent for it (VERB-5.4), in the form the Stop hook prints (VERB-5.6).
+ */
+const STALL_HELP = `
+Stall when something outside your reach has to change before your work can go
+on, such as a host you can't reach or access you don't have, and no decision
+would fix it. Say exactly what has to change:
+
+  dotreq solution stall "<what has to change>"
+
+The outcome waits until that is fixed and you are started again.
+`;
+/** The command as the Stop hook prints it, after the request contract on `ask --help`. */
+const ASK_EXAMPLES = `
+Examples:
+  dotreq solution ask question.json
+
+A reviewer doesn't ask: it escalates, with dotreq solution review escalate --comment "...".
+`;
+/**
+ * What each result does, on `review --help` (STEP-REVIEW-1, 2), and the
+ * executive summary an approval carries, in the words the shared reviewer
+ * block gives it (VERB-2.5, `defaultInstructions/everyStep.ts`).
+ */
+const REVIEW_RESULTS = `
+Results:
+  approved                 The work moves on.
+  approved-with-revisions  What remains is small: the drafter fixes it once, and it moves on without another review.
+  needs-revision           The drafter revises and you read it again. Not recorded from the twelfth round.
+  escalate                 The owner decides: approve it, or send it back. Your comment is the note they read.
+
+When you approve, write an executive summary for the owner with --executive-summary (or
+--summary), describing the work as it will stand once any fixes you asked for are made. If
+the owner hasn't seen this work before, open with one sentence on what it is. If they sent
+it back, open with what changed since, and how their points were handled. Then two short
+lists, one item per line:
+  Assumptions: the ones the work rests on that are worth the owner's attention, not all of them.
+  Look at: what would benefit from the owner's eyes.
+Don't recount the review; your comment carries that, for the drafter, who revises from it.
+Only an approval carries an executive summary.
+
+A demo's script is recorded by the agent reviewing it. Once you would approve the script,
+record the video from the copy in your checkout (.dotreq/demo-scripts/<file>) with
+agentic-demo record, fixing anything small first, such as a selector, a wait or a word.
+Then approve with the video and the script as you left it, as one argument after the
+result, and say in your comment what you changed. If the script needs more than that, give
+needs-revision, with no video. Only a plain approval carries a video.
+
+Examples:
+  dotreq solution review approved --comment "Checked the pitch against the board; the customer is named." --executive-summary "A pitch for guest checkout, for first-time buyers. Look at the appetite: two weeks."
+  dotreq solution review escalate --comment "Whether to name a segment is your call: the drafter and I disagree."
+  dotreq solution review needs-revision --comment "The risk score gives no reason."
+  dotreq solution review approved "video:demo/final.mp4 .dotreq/demo-scripts/steps.json" --comment "Recorded it; step 3 now waits for the receipt." --executive-summary "A two-minute demo of guest checkout. Look at step 4: the receipt."
+`;
+function wrap(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (error) {
+            console.error(`\nError: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    };
+}
+/**
+ * `dotreq solution`: work a solution through its plan of outcomes
+ * (docs/working/plan-surfaces.md). A person creates a solution and can
+ * start an agent's work by hand; an agent runs `next` when invoked, which
+ * gives it an outcome to draft or to review, and records what came of it
+ * with one verb per act — `author`, `review`, `ask`, `stall` — each naming
+ * its object and no ids (VERB-4), and reads the outcome's thread with
+ * `thread`.
+ */
+export function registerSolution(program) {
+    const solution = program
+        .command("solution", HIDDEN) // until solutions launch (SOLACCESS-2)
+        .description("Work a solution through its plan");
+    solution
+        .command("create [file]")
+        .description("Create a solution from the project's default plan, or from a plan file (YAML or JSON: title, plan, inputs)")
+        .option("--title <title>", "The solution's title: required without a file, else when the file has none")
+        .option("--description <text>", "What the solution is beyond its title, in Markdown: wins over the file's")
+        .option("--idea <reference...>", "Where the idea is written down, for the outcome that makes the solution exist: document:<id>, file:<path>[@<branch>], link:<url>")
+        .action(wrap(createCommand));
+    whereOptions(solution
+        .command("status")
+        .description("Where the outcome you are at stands, as recorded"))
+        .option("--json", "Print as JSON")
+        .action(wrap(statusCommand));
+    solution
+        .command("start <solution-id> <agent>")
+        .description("Start an agent's work by hand: a stalled agent again, on the part of an outcome it has due")
+        .option("--outcome <name>", "The outcome to start it on, when it has more than one due; otherwise its first")
+        .action(wrap(startCommand));
+    whereOptions(solution
+        .command("next", HIDDEN)
+        .description("Pick up your next outcome to draft or review: starts it and prints its instructions"))
+        .option("--json", "Print the kind, the outcome and the text as JSON")
+        .action(wrap(nextCommand));
+    whereOptions(solution
+        .command("author <reference...>", HIDDEN)
+        .description("Record what you made, and what changed and why"))
+        .option("--comment <text>", "What changed and why: the next reader sees it first (required)")
+        .option("--executive-summary <text>", "For the owner, when your work moves on before anyone reviews it (required there)")
+        .option("--summary <text>", "Short for --executive-summary")
+        .option("--title <text>", "A reference's name on the outcome's tab, for the owner: one per reference, in the order the references are given, or none", (value, previous = []) => [...previous, value])
+        .addHelpText("after", REFERENCE_FORMS)
+        .action(wrap(authorCommand));
+    whereOptions(solution
+        .command("pull-request", HIDDEN)
+        .description("Push the solution's branch and open its pull request, or find the one open; prints its reference, pr:<number>, to submit"))
+        .addHelpText("after", PULL_REQUEST_HELP)
+        .action(wrap(pullRequestCommand));
+    whereOptions(solution
+        .command("review <result> [video...]", HIDDEN)
+        .description("Record the review's result: approved, approved-with-revisions, needs-revision or escalate"))
+        .option("--comment <text>", "What should change, what you checked, or what the owner is to decide: required for every result")
+        .option("--executive-summary <text>", "For the owner, with every approval (required there)")
+        .option("--summary <text>", "Short for --executive-summary")
+        .addHelpText("after", REVIEW_RESULTS)
+        .action(wrap((result, videos, options) => reviewCommand(result, { ...options, videos })));
+    solution
+        .command("rehearse <scenario>")
+        .description("Run a scenario — a plan or some of its outcomes, its inputs, a real agent or a script for each agent — against the linked project, and report what happened. Its earlier runs are removed first, with what they made")
+        .option("--keep", "Leave the scenario's earlier runs in place, to review the new run beside them")
+        .action(wrap(rehearseCommand));
+    whereOptions(solution
+        .command("ask <request-file>", HIDDEN)
+        .description("Put a decision to the owner, as JSON in the named file; the drafter's, since a reviewer escalates"))
+        .addHelpText("after", `\n${REQUEST_CONTRACT}\n${ASK_EXAMPLES}`)
+        .action(wrap(askCommand));
+    whereOptions(solution
+        .command("thread", HIDDEN)
+        .description("The outcome's thread, oldest first: every submission, review, decision, stall and restart on it"))
+        .option("--latest [n]", "Only the newest n submission notes, review results, escalations and decisions, still oldest first; alone, the newest one. Stalls, restarts and redrafts are left out")
+        .action(wrap(threadCommand));
+    whereOptions(solution
+        .command("things <name>", HIDDEN)
+        .description("What an outcome or an input holds now, or the outcomes a checkpoint presents: one reference a line")).action(wrap(thingsCommand));
+    whereOptions(solution
+        .command("stall <reason>", HIDDEN)
+        .description("Your work cannot go on, and no decision would fix that: what has to change before it can be started again"))
+        // The runner's own stall, after its push: the reason already says why
+        // the work couldn't be pushed.
+        .addOption(new Option("--no-push").hideHelp())
+        .addHelpText("after", STALL_HELP)
+        .action(wrap(stallCommand));
+    // The runner's, around each session (SOLBRANCH-1, 2, 4): an agent never
+    // types them.
+    whereOptions(solution
+        .command("checkout", HIDDEN)
+        .description("Put the checkout on the solution's branch, made on its first session, with what other agents pushed to it"), "With --share: the outcome handed over, as the command you were given names it")
+        .option("--json", "Print the branch and what to tell the agent as JSON")
+        .option("--share <token>", "Check a solution's work out into this repository, from the share command you were given")
+        .option("--branch-wins", "With --share: where the branch has a newer version of a document you changed and didn't push, take the branch's")
+        .action(wrap(checkoutCommand));
+    whereOptions(solution
+        .command("push", HIDDEN)
+        .description("Send the documents you changed to the solution's branch, in a repository its share command checked out; in a runner, push the agent's commits to the run's branch"))
+        .option("--json", "Print whether it pushed, and why not, as JSON")
+        .option("--repo-wins", "Where the branch has a newer version of a document you changed, save yours over it; the branch keeps the one replaced")
+        .action(wrap(pushCommand));
+    // SOLSHARE-4: whoever an outcome waits on says it's done, from the
+    // repository the solution was checked out into.
+    solution
+        .command("done [where...]")
+        .description("Hand the outcome you checked out back: where what you made is, such as a pull request, and what you did")
+        .option("--comment <text>", "What you did")
+        .option("--solution <solution>", "Which solution, when more than one is checked out here")
+        .action(wrap(doneCommand));
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/solution/look-up.d.ts

@@ -0,0 +1,9 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution things <name>`: what an outcome, an input, or the
+ * outcomes a checkpoint presents hold now, one reference a line, under
+ * each outcome's name. Where a brief says what else the solution has made,
+ * to look up if it matters, it names this command.
+ */
+export declare function thingsCommand(name: string, options: WhereOptions): Promise<void>;
+//# sourceMappingURL=look-up.d.ts.map